ITISYOU 0.1.0-dev · Phase 1 of 4 · foundation complete

STORY.md · rendered at build time

Development story

This page is a direct transform of the project's STORY.md — the running narrative the development process keeps as it goes. It records decisions, constraints, and problems as they happened, failures included. Sections that say "populated as they occur" are empty because nothing has occurred there yet — that's the point.

Origin

ITISYOU Browser exists because modern browsers increasingly treat the user as the product: attention-economy new-tab feeds, opaque telemetry, and AI features bolted on with sweeping access to browsing data. ITISYOU is being built as the opposite: a fast, calm, technically honest browser where the user owns their data, AI is off by default and structurally incapable of silent access, and every capability boundary is explicit.

Product Vision

  • A fully functional browser first — AI is optional, removable, and never required.
  • Tab Mode and persistent Workspace Mode as complementary models, not rivals.
  • Privacy as architecture, not as a settings page: history, bookmarks, workspace data, memory, credentials, permissions, AI memory, and sync data are separate datasets with separate boundaries.
  • Cross-platform (Windows, Linux, macOS) on a Chromium-derived foundation that keeps Chromium's sandbox and process isolation intact.

Locked Principles

1. Browser-first; AI optional and OFF by default (zero provider calls in Part 1). 2. Chromium-derived engine; Electron is not the permanent runtime. 3. Web pages are untrusted; no privileged APIs reach arbitrary web content. 4. Modular subsystems behind documented contracts. 5. No avoidable OS-specific assumptions outside platform adapters. 6. Evidence over claims: every milestone has implementation + test + verification.

Architecture Decisions

  • ADR-001 (2026-09-02): CEF binary distribution as the Part-1 Chromium integration. Full Chromium source fork rejected for now (hardware audit: 29.7 GB free vs 100+ GB required); Electron/WebView2/Qt WebEngine rejected on principle/platform/security-lag grounds. CEF 144 (Chromium 144.0.7559.261) with Chrome runtime style, Views framework, and the sandbox-preserving bootstrap pattern on Windows. Migration path to a source derivative is documented in the ADR.

Development Timeline

  • 2026-09-02 — Part 1 session begins. Repository was two files (plan + design ZIP). Environment audited (MSVC 14.44, CMake, Ninja, Node 22, Python 3.14; Chromium source build ruled out on disk constraints). Git repository initialized.
  • 2026-09-02 — Design system processed. Stitch ZIP safety-inspected and extracted: 53 screens (36 browser, 17 website) + DESIGN.md token spec ("Technical Precision": Inter + JetBrains Mono, Bone/Deep Slate palette, hard offset shadows, 4px grid). Inventory generated under design/inventory/.
  • 2026-09-02 — Engine selected. CEF 144.0.34 downloaded (144 MB), SHA1-verified, extracted, and pinned. ADR-001 accepted.

Milestones

  • Repository architecture: established (monorepo: apps/browser, apps/website, design, docs, progress, scripts).
  • Chromium integration decision: completed (ADR-001).
  • 2026-09-02 — the browser compiles and its core is verified. Full C++ implementation (engine-agnostic core + CEF shell) builds Release with the Windows sandbox ON (itisyou.dll + bootstrap pattern, LPAC ACLs applied). 30/30 unit tests pass covering JSON, omnibox classification, atomic persistence with backup recovery, session/history/workspace/settings stores, command permissions, AI-off invariants, network profiles, permission defaults, and log redaction (commit dfa794d).

Problems Encountered

  • Local machine cannot host a Chromium source checkout (29.7 GB free on repo drive vs 100+ GB required). Resolved by ADR-001's CEF strategy; heavy-build path documented for future infrastructure.
  • No git remote exists; source policy is private. Commits are local until the user provides a private remote. Recorded as a continuity note, not hidden.
  • Mid-session storage emergency: C: (system drive) neared capacity. The 5.9 GB npm cache on C: was deleted and npm's cache redirected to the external HDD; all builds, profiles and temp files now live on E:/G: by policy (see workflow doc).
  • First compile surfaced 6 error classes (ambiguous WindowOpenDisposition from dual CEF base classes, three missing CEF includes, MSVC translating \uXXXX even inside raw string literals, and try/catch under _HAS_EXCEPTIONS=0). All fixed in-session.
  • The first green build then failed 3 of 30 unit tests — the tests caught real bugs, not test bugs (see Fixes). This is the evidence-over-claims principle paying for itself within the first hour of the suite existing.

Failed Approaches

  • None yet in implementation. (Chromium source checkout was rejected *before* attempting it, by environment qualification — deliberately not a failure, a constraint.)

Fixes

  • JSON parser accepted numbers with leading zeros ("01") — now rejected per spec.
  • Omnibox classifier read localhost:8080 as URL *scheme* "localhost" and sent it to search — host:port shapes are now recognized before scheme extraction.
  • CommandRegistry::Register read command.id in the same call expression that moved command (unspecified evaluation order; MSVC moved first, registering every command under an empty id). The key is now copied out before the move.
  • CEF permits only one Chrome-style browser view per window; every tab was silently blank until the window and all views moved to the Alloy runtime style (a view-hosting distinction — sandbox and Site Isolation untouched).
  • The post-completion adversarial gate audit (5-agent workflow) found that hostile sites could iframe non-privileged internal pages and reach the internal API tier. Fixed the same day at four independent layers (display-isolated scheme, frame-ancestors 'none', subframe navigation blocking, main-frame-only binding/tier checks) plus exact-host privileged matching, with a new security.embed.blocked smoke regression step. Threat-model invariant 8 records it.

Testing Evidence

  • 2026-09-02: C++ core unit suite 30/30; browser smoke suite 20/20 steps (real HTTPS: example.com, wikipedia.org; back/forward/reload; tab lifecycle incl. reopen; workspace create/switch; history recording; AI-off enforcement; session save) + restore verification 2/2 across a process restart; website suite 1298/1298 checks; production smoke on https://browse.itisyou.app (HTTPS, CSP headers, live /api/status). Full detail: docs/reports/PHASE-1-COMPLETION.md.

Security Decisions

  • Windows sandbox preserved by adopting CEF's bootstrap.exe + application-DLL pattern rather than the legacy unsandboxed exe pattern.
  • Browser chrome implemented as trusted HTML served over the internal itisyou:// scheme in a dedicated privileged view; the JS↔native bridge is origin-gated and denied to web content at three separate layers (renderer bindings, browser-side origin check, navigation block on the privileged host).
  • Permission requests centralized in a default-deny PermissionService.

Deployment History

  • 2026-09-02 — browse.itisyou.app goes live. Cloudflare Workers + Static Assets; 16 pages built from the Stitch design system with zero runtime dependencies; strict CSP and security headers; /api/status serves the real machine-readable project status; custom domain attached and HTTPS verified the same day the browser's smoke suite first went green.

Lessons Learned

  • Qualify the environment before adopting an engine strategy: an hour of auditing (disk/RAM/toolchain) prevented days of doomed Chromium checkout.
  • Stitch exports are excellent visual specs and unacceptable production code; splitting "visual truth" from implementation early kept both honest.
  • Write the unit tests before the first launch: they caught three real core bugs (including an argument-evaluation-order bug that silently broke every command) while they were still cheap to find.
  • Poll-based integration tests race against real browsers; wait on committed navigation events, not on state snapshots.
  • Parallel agents work when ownership boundaries are files, not intentions: browser C++, browser UI, website, and docs proceeded concurrently with zero merge conflicts because each stream owned a directory.

Current Verified State

Phase 1 is complete (2026-09-02). ITISYOU Browser 0.1.0-dev is a real, sandboxed, Chromium-derived (CEF 144 / Chromium 144.0.7559.261) browser on Windows: it renders real HTTPS pages in per-tab isolated browser views under a design-faithful Tab Mode shell, with working navigation, session recovery, workspaces (foundation), local history, a command palette, internal itisyou:// pages, a deny-by-default permission boundary, structured redacted logging — and an AI runtime that is present but structurally OFF (zero provider calls, verified). The knowledge hub is live at https://browse.itisyou.app, reporting real progress from the repository ledger. Linux/macOS are architecture-ready but unverified. Phases 2–4 are planned, not started. Evidence: docs/reports/PHASE-1-COMPLETION.md.

Two additional milestones from the same day:

  • The browser survived its own first bug hunt: the CEF one-Chrome-style-view limit initially left every tab blank; diagnosis via the structured logs (cef.log line → Alloy runtime style fix) took minutes, which is exactly why the logging architecture was built first.
  • The repository gained a private remote (github.com/leelaravind/itisyou-browser) and all verified milestones are pushed.

For structured, machine-readable state see the progress page or the status API.