@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/docs/reports/v0.9-demo-foundation.md

@@ -0,0 +1,589 @@
+# v0.9 Demo Foundation
+
+## 1. VERDICT
+
+`PASS_V0_9_DEMO_FOUNDATION`
+
+A deterministic, offline, version-controlled Observer demo now exists under
+`examples/v09-demo/`, together with a safe materialization script, a
+loopback-only demo server, a fixed external reference image, and automated
+unit, real-HTTP and real-Chromium coverage. The full Observer regression suite
+remains green. No product semantics, package version, dependency or release
+state changed.
+
+This is demonstration infrastructure only. It is not a v0.9 product feature and
+it does not release anything.
+
+## 2. Repository identity
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Branch: `master`
+- Starting HEAD: `9cedc2e79ed626b9bbced5583e2da605dc14a72c`
+- Package: `@dailephd/my-frontend-observer`
+- Package version: `0.8.1` (unchanged)
+
+The planner-known implementation-complete commit was
+`a78a058271564661e2f04a835db04071b135258a`. Local `master` was one commit
+ahead of it at `9cedc2e` (`docs: record v0.9 pre-release readiness`), which is
+exactly the later pre-release readiness work the task anticipates. That commit
+adds only `docs/reports/v0.9-pre-release-readiness.md`. The divergence is
+therefore legitimate continuation work, the tracked worktree was clean at
+entry, and `9cedc2e` was adopted as `STARTING_HEAD`. Nothing was reset,
+rebased, pulled or overwritten.
+
+`docs/reports/v0.9-architecture-retrieval.md` carried its intentional
+`skip-worktree` flag (`S`) at preflight and still carries it. It was not
+cleared, restored, overwritten or deleted. No `git clean` and no
+`git reset --hard` was run at any point.
+
+## 3. Purpose
+
+The Observer product now has a generic tutorial automation consumer,
+`@dailephd/my-dev-kit-lab@0.4.7`, which already owns Playwright loading,
+Chromium launch, managed processes, HTTP readiness, tutorial scenarios, target
+contracts, locators, assertions, cursor and overlay rendering, recording,
+subtitles, tutorial markdown, manifests and packed acceptance.
+
+Observer must not reimplement any of that. This stage therefore builds only the
+deterministic demo application that later Observer-specific tutorial scenarios
+will observe, annotate and compare, plus the small amount of infrastructure
+needed to materialize and serve it on loopback.
+
+This is Prompt 1 of three. No tutorial scenario was authored here, no tutorial
+video was generated, and no lab target contract was frozen.
+
+## 4. v0.9 entry state
+
+v0.9 product implementation was already complete and unreleased at entry. All
+frozen v0.9 semantics were treated as read-only:
+
+`VisualAnnotationArtifact`, annotation identity and persistence, runtime intent
+mappings, confirmation semantics, frontend-contract primitives, contract
+promotion, reference requirement semantics, reference materialization,
+reference approval, project acceptance and viewer authoring security are all
+unchanged by this stage.
+
+The demo was built around the completed product, not inside it.
+
+## 5. Demo architecture
+
+The demo is a small deterministic HTML, CSS and JavaScript application. No
+frontend framework, no second Vite application and no build system was added,
+and no dependency was added or upgraded.
+
+The architecture has three separable pieces:
+
+1. An immutable tracked template under `examples/v09-demo/`.
+2. A materialization script that copies that template into a caller-provided
+   disposable target root.
+3. A loopback-only static server that serves one materialized (or explicitly
+   pointed-at) demo application on a caller-selected port.
+
+Geometry lives entirely in CSS custom properties keyed on a single
+`data-demo-state` attribute. The server freezes the requested state into that
+attribute before serving the document. One small classic script owns the only
+two differences CSS cannot express honestly: removing an element from the DOM,
+and pointing an image at a different local file.
+
+## 6. Demo component inventory
+
+Tracked template:
+
+```text
+examples/v09-demo/README.md
+examples/v09-demo/app/index.html
+examples/v09-demo/app/styles.css
+examples/v09-demo/app/state.js
+examples/v09-demo/app/assets/brand-mark.svg
+examples/v09-demo/app/assets/asset-primary.svg
+examples/v09-demo/app/assets/asset-alternate.svg
+examples/v09-demo/references/v09-reference.png
+examples/v09-demo/references/v09-reference.provenance.json
+examples/v09-demo/scripts/prepare.mjs
+examples/v09-demo/scripts/server.mjs
+examples/v09-demo/scripts/generate-reference.mjs
+```
+
+The application contains a header, a navigation bar, a hero, a sidebar, a main
+content region, two cards, a call-to-action, a footer and a local illustration
+asset area.
+
+## 7. Stable target identity
+
+Every region carries a deliberate `data-demo-target` attribute. This vocabulary
+is the demo's identity contract and does not depend on any incidental CSS
+class:
+
+```text
+header
+navigation
+hero
+sidebar
+content
+card-1
+card-2
+cta
+footer
+asset
+```
+
+A bounded set of `data-testid` attributes exists only where automation needs to
+interact with the page rather than measure it:
+
+```text
+demo-state-badge
+demo-cta-button
+demo-asset-image
+demo-nav-<state>   (one per demo state)
+```
+
+`data-testid` was not added mechanically to every element. Observer Viewer
+selectors were deliberately not touched: `viewer/src/` is unchanged, and the
+minimum stable Viewer test ids belong to Prompt 2 after real scenario authoring
+shows what is needed.
+
+## 8. State model
+
+Nine frozen states, selected deterministically through the URL query parameter
+`?state=<state>`:
+
+```text
+baseline
+move-hero
+wider-sidebar
+changed-spacing
+move-footer
+removed-card
+changed-asset
+multi-change
+reference
+```
+
+Omitting `?state=` renders `baseline`. An unrecognized state fails closed: the
+server answers HTTP 400 with an explicit invalid-state document that names the
+rejected value (HTML-escaped) and lists the supported states. The application
+itself is never rendered for an invalid state, and no unrelated state is ever
+silently substituted.
+
+No state name needed to differ from the task's vocabulary.
+
+## 9. Baseline state
+
+Baseline geometry is frozen for the canonical tutorial viewport `1440x900`.
+Real Chromium measurements through the canonical observation path:
+
+```text
+header      x=0    y=0    w=1440 h=64
+navigation  x=0    y=64   w=1440 h=48
+sidebar     x=20   y=132  w=260  h=676
+content     x=304  y=132  w=1116 h=676
+hero        x=325  y=153  w=894  h=180
+card-1      x=325  y=353  w=300  h=170
+card-2      x=645  y=353  w=300  h=170
+cta         x=325  y=543  w=1074 h=72
+asset       x=325  y=635  w=1074 h=120
+footer      x=0    y=828  w=1440 h=72
+```
+
+Determinism measures actually taken: fixed band heights rather than
+font-dependent ones, a local system font stack, no network font, no remote
+asset, no animation, no transition, no timer, no random value, no current time,
+no network-loaded image, and `overflow: hidden` on the document so a scrollbar
+can never appear and change the usable layout width. In every state, real
+Chromium reports `innerWidth = 1440`, `scrollWidth = 1440` and
+`scrollHeight = 900`.
+
+## 10. Change-state semantics
+
+Measured against baseline with real Chromium:
+
+1. `move-hero` - hero `x` increases from 325 to 485, exactly +160px. Hero
+   width, `y` and height are unchanged, and every other demo target is
+   byte-identical to baseline. This is the clean `Move Right` ->
+   `property-increases x` example.
+2. `wider-sidebar` - sidebar `width` increases from 260 to 400, exactly
+   +140px. Sidebar `x`, `y` and height are unchanged, and the header and
+   footer do not move. This is the clean `Resize Wider` ->
+   `property-increases width` example.
+3. `changed-spacing` - the measured horizontal gap between the sidebar's right
+   edge and the content region's left edge grows from 24px to 96px. Neither
+   region's own width changes, and no demo target changes its `y`. This is a
+   relationship and measurement change, not a region change.
+4. `move-footer` - footer `y` decreases from 828 to 764, exactly -64px, while
+   footer `x`, width and height are unchanged and every other target is
+   identical to baseline. The footer lifts off the bottom edge, which is
+   deliberately the shape of a real layout regression.
+5. `removed-card` - `card-2` is genuinely absent from the document. The
+   canonical observation reports `selectionStatus = not-found` and no geometry
+   evidence, rather than fabricated geometry. `card-1` and every other target
+   are identical to baseline. This demonstrates human intent that v0.9 can
+   annotate as a `remove` operation but that the current `ContractPrimitive`
+   vocabulary cannot promote into a contract clause.
+6. `changed-asset` - the illustration image `src` changes from
+   `assets/asset-primary.svg` to `assets/asset-alternate.svg`. Every demo
+   target's geometry, including the asset container's, is identical to
+   baseline, so an asset-sensitive difference is never conflated with geometry.
+7. `multi-change` - five deterministic differences at once: hero `x` 625,
+   sidebar width 400, footer `y` 764, `card-2` absent, and the alternate asset.
+   This is the state for exercising selected-only contract promotion and
+   selected-only reference materialization. It is deliberately not the primary
+   simple tutorial state.
+
+## 11. Reference state
+
+`reference` represents a desired design rather than an observed change. It
+differs from baseline in four controlled ways, chosen so a reference workflow
+has one of each kind of difference to work with:
+
+- region geometry: sidebar width 320 (baseline 260), hero `x` 497 (baseline
+  325);
+- relationship and measurement: the sidebar-to-content gap is 56px (baseline
+  24px);
+- asset-sensitive area: the alternate local illustration;
+- visual treatment: a different accent colour.
+
+The page frame stays comparable: header and footer geometry are identical to
+baseline, and every demo region is still present. The reference is a design,
+not a removal.
+
+## 12. Local asset policy
+
+Every asset is a local file committed beneath `examples/v09-demo/`. There is no
+CDN, no Google Fonts, no external image URL, no external API and no
+network-dependent icon library. The demo renders correctly offline.
+
+This is enforced two ways. A unit test scans every demo application file and
+fails on any `http://` or `https://` reference (excluding the SVG XML
+namespace declaration, which is an identifier and never fetched). A real
+Chromium test records every network request origin while loading all nine
+states and asserts the only origin contacted is the demo's own loopback server.
+
+## 13. Materialization
+
+```powershell
+node examples/v09-demo/scripts/prepare.mjs <targetRoot>
+```
+
+The target root is required and never defaulted. It is resolved absolutely and
+validated before anything is removed. The script refuses:
+
+- a missing, empty or whitespace-only argument;
+- a target root containing a null byte;
+- a filesystem or drive root;
+- any path with fewer than two segments below its root;
+- the user's home directory;
+- the repository root;
+- the immutable demo template, or anything inside it;
+- any directory that contains the repository, which a reset would destroy.
+
+Reset semantics are "rematerialize the target root": a rerun destroys and
+recreates the target, so it always ends in the same clean state. There is no
+separate reset command, matching the task's contract.
+
+A materialized target contains exactly:
+
+```text
+<targetRoot>/app/index.html
+<targetRoot>/app/styles.css
+<targetRoot>/app/state.js
+<targetRoot>/app/assets/asset-alternate.svg
+<targetRoot>/app/assets/asset-primary.svg
+<targetRoot>/app/assets/brand-mark.svg
+<targetRoot>/server.mjs
+```
+
+That is everything needed to serve the demo without reaching back into the
+template or into any generated Observer evidence. The fixed reference PNG is
+deliberately not copied: it is not needed to serve the application, and Prompt
+2 imports it through canonical Observer commands from its tracked path.
+
+## 14. Source immutability
+
+The tracked template is read-only during materialization. A test takes a
+SHA-256 fingerprint of every file under `examples/v09-demo/` before the
+materialization suite runs and compares it after a destructive rematerialization
+has occurred; the fingerprints must match exactly. A further test asserts that
+nothing new appeared beside the template's own directories, and that every file
+written during the run lives under the selected target root.
+
+Materialization destroys and recreates only the explicitly selected disposable
+target root, and only after every containment and safety check has passed.
+
+No generated `.frontend-observer` evidence exists anywhere in the template, and
+a test enforces that.
+
+## 15. Demo server
+
+`examples/v09-demo/scripts/server.mjs` is a small Node HTTP server using only
+Node built-ins. No dependency was added.
+
+Behavior:
+
+- binds `127.0.0.1` only; the test reads the bound address back from the OS
+  rather than trusting the requested constant;
+- serves only the resolved demo application directory;
+- resolves every request path inside that directory and fails closed on `..`
+  segments, `.` segments, backslashes, null bytes and percent-encoded forms of
+  the same;
+- serves only a small allowlist of static types (`.html`, `.css`, `.js`,
+  `.svg`, `.png`, `.json`); anything else is 404 rather than a guessed type;
+- answers only `GET` and `HEAD`; any other method is 405;
+- sends `cache-control: no-store` and `x-content-type-options: nosniff`.
+
+Port selection is always the caller's. `4173` appears nowhere in the file, and
+a test asserts that. The command line requires `--port` and validates it as an
+integer in `1..65535`, rejecting a missing value, a non-integer, `0`, a
+negative value and `65536`. The exported `startDemoServer({ port })` additionally
+accepts `port: 0` for in-process automation, where the OS assigns an ephemeral
+port; this mirrors the repository's existing canonical viewer port contract in
+`src/viewerServer/port.ts`, which documents the same allowance for deterministic
+test use. A test proves the server listens on exactly the port the caller
+selected.
+
+An optional `--app-root <dir>` lets the tracked template be served directly
+while editing the demo. A materialized target needs no such flag: the server
+resolves `app/` beside itself.
+
+No lab `TutorialTargetContractV1` was frozen or committed. That belongs to
+Prompt 2, once the demo, the Observer project bootstrap and the project-aware
+viewer can be composed with dynamic loopback ports.
+
+## 16. Health and readiness
+
+```text
+GET /health
+```
+
+Answers HTTP 200 with a bounded deterministic JSON document:
+
+```json
+{
+  "ok": true,
+  "demoId": "my-frontend-observer-v09-demo",
+  "schemaVersion": "1.0.0",
+  "canonicalViewport": { "width": 1440, "height": 900 },
+  "defaultState": "baseline",
+  "states": ["baseline", "..."]
+}
+```
+
+There is no current time and no per-run identity in it. A test fetches it twice
+and asserts the two responses are byte-identical, and asserts the health
+response never contains application HTML. `schemaVersion` here describes this
+demo's own readiness document; it is not an Observer artifact schema version
+and no Observer schema was touched.
+
+## 17. Reference PNG
+
+`examples/v09-demo/references/v09-reference.png` is a fixed 1440x900 PNG
+(55,876 bytes) captured from the demo's `reference` state.
+
+It was produced by `examples/v09-demo/scripts/generate-reference.mjs`, which
+serves the `reference` state on loopback and captures it through the
+repository's own canonical Chromium observation path (`captureViewportInternal`
+from `src/browser/chromiumAdapter.ts`, via the compiled `dist/` module). No
+second screenshot engine was added. The script requires a prior `npm run build`
+and fails with an explicit message if the compiled modules are missing.
+
+`examples/v09-demo/references/v09-reference.provenance.json` records the source
+demo state, the canonical viewport, the image format, how the image was
+captured, the exact regeneration command and the intended tutorial use. It is a
+plain record beside the asset: it declares no artifact kind and no Observer
+schema version, and a test asserts both fields are absent.
+
+The committed PNG is a fixed demo asset. Nothing regenerates it during an
+ordinary test run; regeneration is an explicit manual command so an intentional
+visual change is reviewed deliberately.
+
+No generated `.frontend-observer/` reference artifacts were committed. Import
+and approval of this PNG through canonical Observer commands, inside a
+disposable target, belongs to Prompt 2.
+
+## 18. Unit and server tests
+
+`tests/unit/v09DemoTemplate.test.ts` (12 tests) - stable target vocabulary
+present exactly once each and closed to the frozen set, baseline state frozen
+into the tracked document, bounded and unique `data-testid` set, semantic
+elements for the major regions, no remote origin in any demo file, every
+referenced asset present locally, no animation/transition/timer/randomness/
+current time anywhere, no committed Observer evidence, and the reference PNG
+validated through `src/domain/externalReferenceImage.ts` (format detected from
+magic bytes, dimensions `1440x900`, size within the canonical bound) plus its
+provenance record.
+
+`tests/unit/v09DemoMaterialization.test.ts` (16 tests) - explicit target
+required; filesystem/drive root, root-like target, home directory, repository
+root, template and anything inside it, repository-containing directory and null
+byte all rejected; clean target produced with exactly the expected file list;
+every file copied byte-for-byte; rerun resets deterministically and discards a
+stale directory and a mutated file; template fingerprints unchanged across the
+destructive run; nothing written outside the selected target; no Observer
+evidence in the target; and the materialized `server.mjs` resolves its
+application root from the target root alone.
+
+`tests/unit/v09DemoServer.test.ts` (18 tests) - real HTTP throughout. Port
+argument validation, no hardcoded port, path containment unit coverage,
+single-attribute state rewriting, loopback binding read back from the OS,
+deterministic `/health`, health not confused with application HTML, baseline at
+`/`, every one of the nine states rendering with exactly that state frozen into
+the document, unknown state failing closed with 400 and no application markup,
+HTML escaping of a hostile state value, every local asset served with the right
+content type, wire-level traversal rejection including percent-encoded and
+backslash forms, the static allowlist, method rejection, and a server listening
+on exactly the caller-selected port.
+
+All demo unit suites passed.
+
+## 19. Real-browser validation
+
+`tests/browser/v09Demo.test.ts` (17 tests) runs against real Chromium at
+`1440x900`, using the repository's existing real-Chromium browser-test
+infrastructure.
+
+The geometry suite captures all nine states through the canonical observation
+path and asserts: every required demo target present in baseline; baseline
+rendered at exactly the canonical viewport with the footer flush to the bottom;
+the intended direction and magnitude of each state's primary difference; that
+every unrelated region is untouched in `move-hero`, `wider-sidebar`,
+`move-footer`, `removed-card` and `changed-asset`; that `changed-spacing`
+changes a measured gap and no region's `y`; that `card-2` resolves `not-found`
+with no fabricated geometry when removed; that `multi-change` shows several
+differences at once; that `reference` shows the intended controlled design
+differences while staying comparable; that every demo target stays present,
+unique (never `ambiguous`) and matched in every state except the intentionally
+absent card; and that the major regions expose real landmark roles (`banner`,
+`navigation`, `complementary`, `main`, `contentinfo`) in every state.
+
+The DOM suite uses a real page to assert what observation evidence deliberately
+does not carry: the asset `src` swap and its absence elsewhere, every
+tutorial-critical test id present and unique per state, the state badge text and
+`aria-current` navigation marking, the invalid-state page rendering without any
+application markup, that no remote origin is ever contacted, and that no state
+ever needs a scrollbar.
+
+All 17 real-browser demo tests passed.
+
+The accessibility check is a bounded structural and landmark-role check. It is
+not a full accessibility certification and is not claimed as one. No PWA,
+service-worker or OS-installation claim is made by this stage, because none was
+exercised.
+
+## 20. Scope audit
+
+All of the following are `false`:
+
+```text
+v0.9 annotation schema changed              false
+frontend contract schema changed            false
+external-reference schema changed           false
+runtime intent semantics changed            false
+contract promotion semantics changed        false
+reference materialization semantics changed false
+viewer security changed                     false
+tutorial runtime duplicated                 false
+Playwright tutorial engine added to Observer false
+WebM recorder added to Observer             false
+subtitle generator added to Observer        false
+package version changed                     false
+dependency added                            false
+v0.9 marked released                        false
+```
+
+`src/`, `viewer/src/`, `package.json`, `package-lock.json`, `scripts/` and
+`.github/workflows/` are all unchanged.
+
+One file outside `examples/` and `tests/` changed: `eslint.config.js` gained a
+scoped block giving `examples/v09-demo/app/**/*.js` the two DOM globals it
+uses. That file is lint configuration, not Observer production source or
+product semantics, and the addition is scoped to the demo application
+directory. ESLint 10 flat config has no per-file environment comment, so a
+config block is the only available mechanism.
+
+`examples/v09-demo` was deliberately not added to `package.json#files`. A
+`npm pack --dry-run` confirms zero `examples/` entries in the candidate
+tarball. Whether the demo ships inside `0.9.0` is a Prompt 3 decision, after
+tutorial acceptance.
+
+Documentation scope was respected. Only `examples/v09-demo/README.md` and this
+report were written. `README.md`, `docs/QUICKSTART.md`, `docs/WORKFLOWS.md`,
+`docs/CURRENT_STATE.md` and every other release-facing document are unchanged
+and remain owned by Prompt 3.
+
+## 21. Changed files
+
+Added:
+
+```text
+examples/v09-demo/README.md
+examples/v09-demo/app/index.html
+examples/v09-demo/app/styles.css
+examples/v09-demo/app/state.js
+examples/v09-demo/app/assets/brand-mark.svg
+examples/v09-demo/app/assets/asset-primary.svg
+examples/v09-demo/app/assets/asset-alternate.svg
+examples/v09-demo/references/v09-reference.png
+examples/v09-demo/references/v09-reference.provenance.json
+examples/v09-demo/scripts/prepare.mjs
+examples/v09-demo/scripts/server.mjs
+examples/v09-demo/scripts/generate-reference.mjs
+tests/unit/v09DemoTemplate.test.ts
+tests/unit/v09DemoMaterialization.test.ts
+tests/unit/v09DemoServer.test.ts
+tests/browser/v09Demo.test.ts
+docs/reports/v0.9-demo-foundation.md
+```
+
+Modified:
+
+```text
+eslint.config.js
+```
+
+Validation actually run, with exact results:
+
+```text
+npm run typecheck     PASS
+npm run lint          PASS
+npm test              PASS  (87 files, 1425 tests)
+npm run test:browser  PASS  (27 files, 252 tests)
+npm run test:security PASS  (16 files / 167 tests, then 3 files / 77 tests)
+npm run build         PASS
+npm run check:docs    PASS  (17 required files)
+npm pack --dry-run    PASS  (0.8.1, 0 examples/ entries; 362 files before this
+                             report was written, 363 with it)
+```
+
+No step was skipped. No test was weakened, skipped or deleted, and no
+`.skip`, `.only`, `continue-on-error` or `|| true` was introduced.
+
+Generated paths during this stage, all inside the repository-local approved
+workflow root and all git-ignored:
+
+```text
+.my-dev-kit-workflow/v0.9/demo-foundation/tests/materialization/   (created and removed by the materialization suite on each run)
+```
+
+Two transient exploratory paths were used during implementation and have been
+removed: `.my-dev-kit-workflow/v0.9/demo-foundation/scratch/` and
+`.my-dev-kit-workflow/v0.9/demo-foundation/smoke-target/`. Nothing substantial
+was generated on `C:\` outside the repository.
+
+`git diff --check` reports no whitespace problems. No `.frontend-observer`
+evidence, tutorial video, lab workspace, temporary target, server log,
+`node_modules` or `dist` content is tracked by this change.
+
+## 22. Remaining next step
+
+Prompt 2: Observer-specific `my-dev-kit-lab@0.4.7` tutorial integration.
+
+Prompt 2 owns dynamic `TutorialTargetContractV1` generation, demo and bootstrap
+process composition, Observer project initialization, baseline capture,
+external reference import and approval of `v09-reference.png`, project-aware
+Observer viewer startup, the minimum stable Viewer test ids, four
+`TutorialScenarioV1` files, scenario validation against
+`my-dev-kit-lab@0.4.7`, and Observer-specific runtime assertions.
+
+Known risks and blockers carried forward: none from this stage. The one open
+decision deliberately deferred is whether `examples/v09-demo` should be
+included in `package.json#files` for `0.9.0`, which Prompt 3 decides after
+tutorial acceptance.