Master Tracker: Production-Ready Minimalist Zig Browser

[adybag14-cyber]

Full Browser Master Tracker

This tracker defines the path from the current experimental Lightpanda fork to
a production-ready minimalist Zig browser for real daily use. The target is not
full Chrome parity in every area. The target is a fast, installable,
user-facing browser that can browse the modern web reliably and ship most core
features users expect from Chrome-class browsing.

Product Target

The production bar for this fork is:

• open and use most common real-world sites without falling back to CDP only
• provide a stable headed browser UX with tabs, address bar, history, reload,
  stop, downloads, settings, and session persistence
• render modern HTML/CSS/JS content with acceptable fidelity for mainstream
  browsing
• support core Chrome-like daily-use features: multi-tab browsing, persistent
  profile, cookies/storage, TLS, uploads/downloads, autofill-adjacent form
  usability, screenshots, clipboard, find-in-page, and crash recovery
• preserve headless and CDP strengths as secondary product modes, not the main
  product definition

Non-Goals For First Production Cut

These are explicitly out of scope for the first production-ready release unless
they become necessary for site compatibility:

• Chrome extension ecosystem compatibility
• Google account sync or cloud profile sync
• full Chrome DevTools parity
• multi-process sandbox parity with Chrome

Current Baseline

The fork already has a real headed Windows foundation:

• Windows/MSVC build is stable
• browse runs in a native Win32 window
• address bar navigation works
• back, forward, reload, and stop browser chrome works
• stop restores the last committed live page/context
• wrapped-link click navigation works
• screenshots/export are wired through the headed presentation surface
• raster <img> rendering works for common sources used by the probes
• focus/autofocus/input bootstrap is working in headed mode
• label activation and Enter form submit basics work
• bounded localhost smoke probes exist for navigation, history, reload, stop,
  wrapped links, and form interactions

Achieved Gates

Gate A: Windows Headed Foundation

Status: Achieved

• native headed window lifecycle
• native input translation and text editing baseline
• browse command path
• Windows runtime stabilization and smoke probes

Gate B: Headed Browser Interaction MVP

Status: Achieved

• address bar navigation
• back/forward/reload/stop chrome
• wrapped-link hit testing and navigation
• live page restore after stop

Gate C: Shared Presentation Surface

Status: Achieved

• display-list based headed presentation path
• screenshot/export on the same presentation path
• basic text, box, link, and image presentation

Gate D: Basic Form/Input Reliability

Status: Achieved

• autofocus and initial typing
• label activation
• Enter submit path
• stable Windows SendInput-driven headed probes

Remaining Gates

Gate 1: Browser Shell MVP

Status: Active next milestone

Goal:

• turn the current single-page headed shell into a minimal real browser shell

Exit criteria:

• tab strip with open, close, switch, duplicate, and reopen closed tab
• new-window and basic popup/window handling policy
• visible loading/error states and disabled chrome state where applicable
• history UI, bookmarks UI, downloads UI, and basic settings UI
• find-in-page and zoom controls

Gate 2: Shared Subresource Loader And Profile

Status: Planned

Goal:

• move page assets and browser state onto a consistent browser-managed runtime

Exit criteria:

• images, CSS, scripts, fonts, and other subresources use the shared browser
  network/client path
• cookies, cache, auth, proxy, redirects, uploads, downloads, and persistent
  profile storage behave consistently
• file chooser and download manager flows exist
• same-origin, CORS, CSP, mixed-content, and certificate error behavior are
  coherent enough for mainstream browsing

Gate 3: Layout Engine Replacement

Status: Planned

Goal:

• replace the remaining dummy and heuristic layout paths with a real layout
  engine

Exit criteria:

• block and inline formatting contexts behave predictably
• flexbox support is usable on common sites
• positioning, overflow, fixed/sticky basics, margin/padding/border handling,
  and intrinsic sizing are implemented
• form controls and replaced elements layout correctly in normal documents

Gate 4: Paint, Text, And Compositing

Status: Planned

Goal:

• turn the current simple painter into a real browser rendering pipeline

Exit criteria:

• font loading and text shaping are good enough for mainstream sites
• CSS backgrounds, borders, opacity, transforms, clipping, and stacking are
  implemented at an MVP level
• image rendering uses the browser resource pipeline
• canvas, SVG, and screenshot fidelity materially improve
• dirty-region invalidation avoids full-frame redraws for common interactions

Gate 5: Editing, Forms, And App Interactivity

Status: Planned

Goal:

• make normal website interaction feel dependable

Exit criteria:

• text selection, clipboard, caret movement, IME, drag/drop, and pointer
  capture are stable
• buttons, selects, checkboxes, radios, and file inputs behave correctly
• contenteditable and common rich-text editing flows work to a practical level
• keyboard shortcuts and accessibility-driven focus behavior are coherent

Gate 6: Modern Web Platform Coverage

Status: Planned

Goal:

• reach enough platform compatibility for mainstream browsing, not just simple
  pages

Exit criteria:

• robust fetch/XHR/WebSocket/navigation/history behavior
• storage APIs needed by common apps are implemented and persistent
• module/script loading and common JS integration paths are reliable
• workers and other core async primitives cover representative real sites

Gate 7: Tabs, Session Management, And Recovery

Status: Planned

Goal:

• make longer user sessions safe and practical

Exit criteria:

• persistent session restore
• crash recovery and restart restore
• per-tab loading/crash/error state
• memory cleanup on tab close and navigation churn

Gate 8: Performance, Stability, And Security

Status: Planned

Goal:

• raise the fork from experimental to something users can trust

Exit criteria:

• bounded memory/performance targets for long sessions
• crash logging and reproducible issue reports
• regression probes in CI for headed browsing on Windows
• clear security posture for cookies, storage, network policy, and unsafe
  content handling

Gate 9: Packaging And Production Readiness

Status: Planned

Goal:

• ship a browser, not just a buildable developer project

Exit criteria:

• Windows installer/package and portable build
• versioned releases and upgrade path
• default profile directory and migration behavior
• documentation for install, troubleshoot, and recover

Acceptance Bar For Production

Treat the browser as production-ready only when all of these are true:

• a normal user can install it and browse daily sites without needing CDP
• common login, search, reading, download, upload, and form flows work
• multi-tab browsing is stable for long sessions
• rendering quality is good enough that users do not need another browser to
  visually verify the page
• core crash, stop, reload, navigation, and recovery paths are predictable

Working Rule For Future Milestones

Prefer milestones that move the product from "experimental headed demo" toward
"installable minimalist browser." If a change only helps automation but does
not materially improve the browser product, it should usually rank below work
that advances the gates above.

[adybag14-cyber]

Goal: Add a reproducible offline Linux dependency restore path for headed-mode build validation on fork/headed-mode-foundation.
Started: 2026-05-10 01:08 UTC
Next: Add a restore script, update the headed production/build docs, and verify the workflow against the saved dependency archives.

[adybag14-cyber]

Goal: Add a reproducible offline Linux dependency restore path for headed-mode build validation on fork/headed-mode-foundation.
Started: 2026-05-10 09:16 UTC
Next: Add the restore script, wire the runbook to the saved Memory archives, and verify the flow reaches the known post-restore build stage.

[adybag14-cyber]

Achieved: Added an in-repo offline Linux dependency restore script and a focused recovery note for headed-mode build validation.
Completed: 2026-05-10 01:08 UTC
Commit: 32bcdf7 and a107473
Validation: Ran the restore script against the saved dependency archives in a scratch copy and confirmed it created ../zig-v8-fork, ../boringssl-zig, ../offline-deps/*, refreshed .cargo/config.toml and vendor/, and rewrote build.zig.zon to local path dependencies.

[adybag14-cyber]

Achieved: Ported the browser repo's build.zig C-source/config-header wiring onto the newer Zig module APIs and switched manifest parsing to fromSliceAlloc so the offline Linux restore path advances past the browser-owned build-script failures.
Completed: 2026-05-10 09:28 UTC
Commit: c32ef73
Validation: In a scratch restore using the saved offline dependency archives plus Zig 0.17.0-dev, zig build --summary all -Dprebuilt_v8_path='../offline-deps/libc_v8_14.0.365.4_linux_x86_64 (1).a' no longer fails in browser/build.zig; the remaining blockers are now external dependency API mismatches in boringssl-zig and zig-v8-fork.

[adybag14-cyber]

Goal: Make the core headed Win32 form-control smoke probes portable across local checkouts instead of depending on one hardcoded Windows repo path.
Started: 2026-05-10 01:44 UTC
Next: Add shared repo/browser path resolution for smoke scripts, update the form-controls probes, and commit the validation fix.

[adybag14-cyber]

Goal: Standardize the headed Windows validation gate suites and connect the Windows runbook to the existing probe families.
Started: 2026-05-10 01:50 UTC
Next: Add a small probe matrix document under tmp-browser-smoke/, update docs/WINDOWS_FULL_USE.md to reference the suite map and recommended validation order, then commit the docs change on fork/headed-mode-foundation.

[adybag14-cyber]

Achieved: Made the two foundational headed Win32 form-control smoke probes resolve the repo root and browser binary from the current checkout instead of a hardcoded C:\Users\adyba\src\lightpanda-browser path.
Completed: 2026-05-10 02:01 UTC
Commit: d59305d, 7a1dc76
Validation: tmp-browser-smoke/form-controls/enter-submit-probe.ps1 and tmp-browser-smoke/form-controls/label-click-probe.ps1 can now run from any repo checkout, with optional LIGHTPANDA_REPO_ROOT and LIGHTPANDA_BROWSER_EXE overrides for local headed verification.

[adybag14-cyber]

Achieved: Added a headed probe-suite matrix at tmp-browser-smoke/README.md and updated docs/WINDOWS_FULL_USE.md so the Windows runbook now routes changes to the right headed validation families before reduced-Google or broader manual checks.
Completed: 2026-05-10 01:56 UTC
Commit: 34963a0, 1682339
Validation: Verified both files on fork/headed-mode-foundation through GitHub after the branch updates landed. This slice was documentation-only, so no runtime probe execution was performed in the scheduled container.

[adybag14-cyber]

Goal: Add a named headed-validation suite helper and runbook updates so future headed-mode work can use repeatable probe families instead of ad hoc smoke folders.
Started: 2026-05-10 01:52 UTC
Next: Inspect the current Windows validation docs/scripts, add the suite helper on the branch, and commit the update.

[adybag14-cyber]

Achieved: Added a Windows helper to list named headed validation suites and recommend the default bounded probe sets by change area, then documented it in the headed probe README and Windows runbook.
Completed: 2026-05-10 02:02 UTC
Commit: 1703bd2 (helper landed in 864196f)
Validation: Confirmed the new helper and both doc updates are present on fork/headed-mode-foundation; runtime execution was not exercised in this Linux scheduled container.

[adybag14-cyber]

Goal: Restore the missing in-repo Linux offline dependency recovery helper on fork/headed-mode-foundation and document the workflow so scheduled headed-mode build validation stops rediscovering it.
Started: 2026-05-10 02:06 UTC
Next: Add the helper script and runbook update, verify it against the saved dependency archives, and commit the branch fix.

[adybag14-cyber]

Achieved: Restored a missing in-repo Linux offline dependency recovery path by adding scripts/linux/prepare_offline_build_inputs.sh, refreshing docs/LINUX_OFFLINE_BUILD_RECOVERY.md, and wiring the headed production guide to the new helper.
Completed: 2026-05-10 02:13 UTC
Commit: cb3bdfa, 46d2cb7, ab9f320
Validation: Ran the helper against the saved dependency archives in a scratch checkout and confirmed it rebuilds ../zig-v8-fork, ../boringssl-zig, ../offline-deps/*, .cargo/config.toml, vendor/, and rewrites build.zig.zon to local path dependencies.

[adybag14-cyber]

Goal: Add a repo-local helper that restores the saved offline Linux build inputs for headed-mode work.
Started: 2026-05-10 02:13 UTC
Next: Inspect the current build/dependency layout, add the restore script on fork/headed-mode-foundation, and validate it against the saved Memory archives.

[adybag14-cyber]

Achieved: Added scripts/linux/restore_offline_build_inputs.sh on fork/headed-mode-foundation to restore the saved offline Linux dependency layout, copy the vendored html5ever Cargo inputs, rewrite build.zig.zon to local paths, and neutralize zig-v8-fork's remote depot_tools fetch for prebuilt-V8 offline use.
Completed: 2026-05-10 02:13 UTC
Commit: 8e85921
Validation: Ran the helper against the saved Memory archives and confirmed the next zig build -Dprebuilt_v8_path=... --summary all failure moved off remote fetches and back to the known Zig 0.17 build API mismatches in build.zig and boringssl-zig.

[adybag14-cyber]

Goal: Add a reusable Windows localhost HTML validation helper for headed-mode checks against saved local pages.
Started: 2026-05-10 02:15 UTC
Next: Add the helper script and wire the runbook so local attached-page validation is repeatable instead of ad hoc.