{"id":50495361,"url":"https://github.com/anhtnt90dev/web-browser","last_synced_at":"2026-06-02T06:30:33.622Z","repository":{"id":361655186,"uuid":"1254609954","full_name":"anhtnt90dev/web-browser","owner":"anhtnt90dev","description":"TypeScript Electron web browser built from scratch with bilingual guides and diagrams","archived":false,"fork":false,"pushed_at":"2026-05-31T16:33:49.000Z","size":64,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T18:22:04.022Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anhtnt90dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T19:36:13.000Z","updated_at":"2026-05-31T16:33:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/anhtnt90dev/web-browser","commit_stats":null,"previous_names":["anhtnt90dev/web-browser"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/anhtnt90dev/web-browser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anhtnt90dev%2Fweb-browser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anhtnt90dev%2Fweb-browser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anhtnt90dev%2Fweb-browser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anhtnt90dev%2Fweb-browser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anhtnt90dev","download_url":"https://codeload.github.com/anhtnt90dev/web-browser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anhtnt90dev%2Fweb-browser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33810341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T06:30:32.811Z","updated_at":"2026-06-02T06:30:33.609Z","avatar_url":"https://github.com/anhtnt90dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.md\"\u003e\u003cimg alt=\"Tiếng Việt\" src=\"https://img.shields.io/badge/VI-Ti%E1%BA%BFng_Vi%E1%BB%87t-cc6699?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"docs/en/build-from-scratch.md\"\u003e\u003cimg alt=\"English\" src=\"https://img.shields.io/badge/EN-English-blue?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"docs/vi/xay-dung-tu-dau.md\"\u003e\u003cimg alt=\"Vietnamese build guide\" src=\"https://img.shields.io/badge/Guide-Build_from_Scratch-0f766e?style=flat-square\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eLearn Web Browser Engineering\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eMột khóa học nhỏ theo dự án: xây dựng browser shell desktop bằng TypeScript, Electron, webview isolation, state management, verification và tài liệu song ngữ.\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Modules-6-blue?style=flat-square\" alt=\"6 Modules\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Projects-1-green?style=flat-square\" alt=\"1 Project\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Languages-2-yellow?style=flat-square\" alt=\"2 Languages\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square\" alt=\"MIT License\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://anhtnt90dev.github.io/web-browser/\"\u003e\u003cstrong\u003eOpen the GitHub Pages guide\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e Guide này lấy cảm hứng về cách trình bày từ [`walkinglabs/learn-harness-engineering`](https://github.com/walkinglabs/learn-harness-engineering): có visual preview, quick start, learning path, project breakdown, sơ đồ ASCII/Mermaid và kiểm chứng rõ ràng. Nội dung bên dưới được viết riêng cho dự án browser này.\n\n---\n\n## Table of Contents\n\n- [Visual Preview](#visual-preview)\n- [Browser Shell Pattern](#browser-shell-pattern)\n- [Quick Start](#quick-start)\n- [Capstone Project](#capstone-project)\n- [Learning Path](#learning-path)\n- [Browser Engineering Roadmap](#browser-engineering-roadmap)\n- [Syllabus](#syllabus)\n- [Verification](#verification)\n- [Repository Structure](#repository-structure)\n\n---\n\n## Visual Preview\n\n### Browser Chrome\n\n\u003e UI đầu tiên tập trung vào thao tác thật: tab strip, address bar, navigation controls, bookmark bar, webview stage và status bar.\n\n![Browser UI wireframe](./docs/assets/browser-ui-wireframe.svg)\n\n### Runtime Architecture\n\n\u003e Renderer điều khiển browser chrome, Electron main process khóa chính sách an toàn, còn web content chạy trong vùng webview tách biệt.\n\n```mermaid\nflowchart LR\n  User[User] --\u003e Chrome[Renderer browser chrome]\n  Chrome --\u003e State[Tab and bookmark state]\n  Chrome --\u003e Webview[Electron webview]\n  Webview --\u003e Web[Web page process]\n  Chrome --\u003e Preload[Preload bridge]\n  Preload --\u003e Main[Electron main process]\n  Main --\u003e Session[(Electron session)]\n  Main --\u003e Policy[Webview security policy]\n  Policy --\u003e Webview\n```\n\n### Navigation Flow\n\n\u003e Address bar không chỉ nhận URL. Nó phân loại input thành URL thật hoặc search query, rồi cập nhật state khi webview phát event.\n\n```mermaid\nsequenceDiagram\n  participant U as User\n  participant R as Renderer UI\n  participant N as normalizeAddressInput\n  participant W as Webview\n  participant S as Browser state\n\n  U-\u003e\u003eR: Type URL or search text\n  R-\u003e\u003eN: Normalize input\n  alt URL\n    N--\u003e\u003eR: https://example.com\n  else Search query\n    N--\u003e\u003eR: https://duckduckgo.com/?q=...\n  end\n  R-\u003e\u003eS: Mark active tab loading\n  R-\u003e\u003eW: loadURL(target)\n  W--\u003e\u003eR: did-navigate / title / loading events\n  R-\u003e\u003eS: Update URL, title, history flags\n  R--\u003e\u003eU: Refresh toolbar, tab strip, status\n```\n\n---\n\n## Browser Shell Pattern\n\nĐiểm quan trọng của dự án này: **ta không viết rendering engine từ đầu; ta xây browser shell từ đầu.** Chromium render trang web, còn code của dự án quyết định cách người dùng điều hướng, quản lý tab, lưu bookmark và kiểm soát an toàn.\n\n```text\n                    THE BROWSER SHELL PATTERN\n                    =========================\n\n    User --\u003e Browser Chrome --\u003e Pure State + Webview Controller --\u003e Webview\n                 |                         |                         |\n                 |                         |                         v\n                 |                         |                  Web page process\n                 |                         |\n                 v                         v\n          Toolbar / tabs             tests can verify\n          bookmarks / status         URL and tab behavior\n\n    Electron main process governs:\n    +--\u003e Window creation\n    +--\u003e Webview attachment policy\n    +--\u003e Permission denial by default\n    +--\u003e Context isolation and Node isolation\n```\n\nBrowser shell có năm phần chính:\n\n- **Chrome UI**: tab strip, toolbar, address bar, bookmark bar, status bar.\n- **Navigation**: biến input thành URL hoặc DuckDuckGo search URL.\n- **State**: tab, active tab, loading state, history flags, bookmarks.\n- **Isolation**: renderer không có Node trực tiếp; webview bị ép `nodeIntegration: false`.\n- **Verification**: pure logic có unit test; app có build/typecheck/audit.\n\n---\n\n## Quick Start\n\nBạn chỉ cần Node.js và npm.\n\n```bash\nnpm install\nnpm test\nnpm run typecheck\nnpm run build\nnpm run dev\n```\n\n`npm run dev` sẽ build Electron main process, chạy Vite renderer tại `http://127.0.0.1:5173/`, rồi mở Electron window `From Scratch Browser`.\n\n---\n\n## Capstone Project\n\nToàn bộ guide xoay quanh một sản phẩm duy nhất: **desktop web browser tối giản nhưng chạy thật**.\n\n```text\n    ┌──────────────────────────────────────────────────────────────┐\n    │                  From Scratch Browser                        │\n    │                                                              │\n    │  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐  │\n    │  │ Active Tab   │ │ Other Tab    │ │ + New Tab            │  │\n    │  └──────────────┘ └──────────────┘ └──────────────────────┘  │\n    │                                                              │\n    │  [\u003c] [\u003e] [R] [H]  https://example.com                 [*][+] │\n    │                                                              │\n    │  Bookmarks:  Docs  Search  Localhost                         │\n    │                                                              │\n    │  ┌────────────────────────────────────────────────────────┐  │\n    │  │                                                        │  │\n    │  │                 Electron webview                       │  │\n    │  │             isolated web page content                   │  │\n    │  │                                                        │  │\n    │  └────────────────────────────────────────────────────────┘  │\n    │                                                              │\n    │  Status: hovered link or current URL                         │\n    └──────────────────────────────────────────────────────────────┘\n\n    Core features:\n    ├── Navigate by URL or search query\n    ├── Back / forward / reload / stop / home\n    ├── Multiple tabs\n    ├── Local bookmarks\n    ├── Webview isolation\n    └── Verification pipeline\n```\n\n---\n\n## Learning Path\n\nNên đọc và thực hành theo thứ tự này.\n\n```text\n    Phase 1: FOUNDATION                    Phase 2: BROWSER LOGIC\n    ====================                   ======================\n\n    M01  Project scaffold                  M03  Address normalization\n         TypeScript + Vite + Electron           URL vs search query\n\n    M02  Electron process model            M04  Tab and bookmark state\n         main / preload / renderer              pure functions + tests\n\n             |                                      |\n             v                                      v\n\n    Phase 3: RUNTIME UI                    Phase 4: SAFETY \u0026 DOCS\n    ===================                    ======================\n\n    M05  Browser chrome                    M06  Verification and docs\n         toolbar + tabs + webviews              test + typecheck + build\n\n             |                                      |\n             v                                      v\n\n         Working desktop browser            Bilingual learning guide\n```\n\n---\n\n## Syllabus\n\n### Modules\n\n| Module | Question | Output |\n|--------|----------|--------|\n| M01 | Làm sao scaffold desktop browser bằng TypeScript? | `package.json`, `tsconfig`, Vite configs |\n| M02 | Electron chia main/preload/renderer như thế nào? | `src/main/main.ts`, `src/main/preload.ts` |\n| M03 | Address bar nên hiểu input ra sao? | `src/shared/navigation.ts` + tests |\n| M04 | Tab và bookmark nên được quản lý ở đâu? | `src/renderer/browserState.ts` + tests |\n| M05 | UI điều khiển webview như thế nào? | `src/renderer/renderer.ts`, HTML, CSS |\n| M06 | Khi nào được coi là xong? | test, typecheck, build, audit, launch |\n\n### Project Milestones\n\n| Milestone | What You Build | Evidence |\n|-----------|----------------|----------|\n| P01 | Core URL/search parser | `tests/navigation.test.ts` |\n| P02 | Browser state reducer | `tests/browserState.test.ts` |\n| P03 | Electron shell | `npm run build:main` |\n| P04 | Renderer UI | `npm run build:renderer` |\n| P05 | Documentation pack | `docs/en`, `docs/vi`, `docs/diagrams`, `docs/assets` |\n| P06 | Full verification run | `npm test`, `npm run typecheck`, `npm run build`, `npm audit --omit=dev` |\n\n---\n\n## Browser Engineering Roadmap\n\nSau khi đối chiếu với [`browser.engineering`](https://browser.engineering/) và repo [`browserengineering/book`](https://github.com/browserengineering/book), dự án có thể phát triển theo hai nhánh rõ ràng:\n\n```text\n    TRACK A: PRODUCT BROWSER SHELL        TRACK B: MINI ENGINE LAB\n    ==============================        ========================\n\n    Session restore                       URL + HTTP lifecycle\n    History page                          Canvas drawing model\n    Bookmark manager                      Text layout\n    Find in page                          HTML tokenizer/tree\n    Zoom controls                         CSS cascade\n    Download shelf                        Layout tree\n    Security indicator                    Paint commands\n    Error pages                           Accessibility concepts\n\n    Goal: app dùng tốt hơn                Goal: hiểu engine bên trong\n```\n\nBa milestone nên làm tiếp:\n\n1. **Session và History**: persistent tabs, history reducer, history page.\n2. **Find, Zoom và Error Pages**: workflow browser giá trị cao trên Electron shell.\n3. **Mini Engine Lab**: package riêng `labs/mini-engine` để học URL fetching, HTML parsing, CSS, layout và painting.\n\nRoadmap chi tiết:\n\n- [Vietnamese roadmap](./docs/vi/browser-engineering-roadmap.md)\n- [English roadmap](./docs/en/browser-engineering-roadmap.md)\n\n---\n\n## Verification\n\nKhông coi thay đổi là hoàn tất nếu chưa có bằng chứng chạy được.\n\n```text\n    VERIFICATION PIPELINE\n    =====================\n\n    npm test\n      └── navigation + browser state behavior\n\n    npm run typecheck\n      └── TypeScript correctness\n\n    npm run build\n      ├── Electron main/preload bundle\n      └── Renderer production bundle\n\n    npm audit --omit=dev\n      └── Runtime dependency vulnerability check\n\n    npm run dev\n      └── Smoke test: Electron window opens\n```\n\nCác tài liệu chi tiết:\n\n- [English build guide](./docs/en/build-from-scratch.md)\n- [Hướng dẫn tiếng Việt](./docs/vi/xay-dung-tu-dau.md)\n- [Architecture diagram source](./docs/diagrams/architecture.mmd)\n- [Navigation flow source](./docs/diagrams/navigation-flow.mmd)\n- [Build process source](./docs/diagrams/build-process.mmd)\n\n---\n\n## Repository Structure\n\n```text\nweb-browser/\n├── src/\n│   ├── main/                 # Electron main process and preload bridge\n│   ├── renderer/             # Browser chrome UI, state, styles\n│   └── shared/               # Reusable pure logic\n├── tests/                    # Vitest unit tests\n├── docs/\n│   ├── en/                   # English guide\n│   ├── vi/                   # Vietnamese guide\n│   ├── diagrams/             # Mermaid source files\n│   ├── assets/               # SVG illustrations\n│   └── superpowers/          # Design and implementation records\n├── package.json\n├── tsconfig.json\n├── vite.main.config.ts\n├── vite.renderer.config.ts\n└── vitest.config.ts\n```\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanhtnt90dev%2Fweb-browser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanhtnt90dev%2Fweb-browser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanhtnt90dev%2Fweb-browser/lists"}