@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/docs/reports/v0.9-tutorial-integration.md

@@ -0,0 +1,731 @@
+# v0.9 Tutorial Integration
+
+## 1. VERDICT
+
+`PASS_V0_9_TUTORIAL_INTEGRATION`
+
+```text
+LAB_V0_4_8_POINTER_DEFECT_CLOSED    true
+POSITIONAL_CLICK_SUPPORTED          true
+POSITIONAL_DRAG_SUPPORTED           true
+POINT_TUTORIAL_GESTURE              PASS
+RECTANGLE_TUTORIAL_GESTURE          PASS
+LINE_TUTORIAL_GESTURE               PASS
+ARROW_TUTORIAL_GESTURE              PASS
+NOTE_TUTORIAL_GESTURE               PASS
+```
+
+The defect that blocked the previous attempt is closed. All four Observer
+tutorials validate against the released `@dailephd/my-dev-kit-lab@0.4.8`, run
+end to end in real Chromium, and produce the full artifact set. Every outcome
+was then verified by reading the canonical Observer evidence the runs actually
+wrote, not by watching the video.
+
+Observer implements no tutorial runtime, gained no dependency, and its product
+semantics are unchanged. The package stays at `0.8.1` and v0.9 stays
+unreleased.
+
+## 2. Repository identity
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Branch: `master`
+- Starting HEAD: `59ae009d4bfdd38b91aa7a4e8ce4e1ca69970948`
+- Package: `@dailephd/my-frontend-observer`
+- Package version: `0.8.1` (unchanged)
+- v0.9: unreleased
+
+## 3. Prompt 1 entry gate
+
+Preflight matched every required value: branch `master`, HEAD
+`59ae009d4bfdd38b91aa7a4e8ce4e1ca69970948`, clean tracked worktree, package
+`0.8.1`, and `docs/reports/v0.9-architecture-retrieval.md` still carrying its
+intentional `skip-worktree` flag (`S`). No pull, rebase, reset, stash or clean
+was run.
+
+The only worktree entry at preflight was the untracked blocker report from the
+previous attempt, which this report replaces.
+
+The Prompt 1 demo is unchanged in design. The canonical viewport is still
+1440x900, the nine states are intact, and the `move-footer` correction still
+uses relative positioning so real Chromium observes a genuine 64px footer
+shift. A digest of every tracked file under `examples/v09-demo/` was taken
+before the final tutorial runs and compared afterwards; see section 23.
+
+## 4. my-dev-kit-lab v0.4.8 released contract
+
+Read from the released package rather than assumed:
+
+```text
+TutorialScenarioV1 schemaVersion          1.0.0
+TutorialTargetContractV1 schemaVersion    1.0.0
+TutorialRunResultV1 schemaVersion         1.0.0
+TutorialManifestV1 schemaVersion          1.0.0
+```
+
+All four remain `1.0.0`. The v0.4.8 changelog states this explicitly, and the
+committed scenarios and the generated target contracts use those exact values.
+
+Locator kinds, assertions, the `{{targetRoot}}` placeholder and the
+`contract-root`/`target-root` process working directories are unchanged from
+v0.4.7. The action vocabulary gained two members and lost none:
+
+```text
+goto, click, fill, press, hover, drag, wait-for, pointer-click, pointer-drag
+```
+
+Existing element-to-element `drag` is preserved unchanged, so v0.4.7 scenarios
+remain valid.
+
+`LAB_CLI_SOURCE: npm`. `npx --yes @dailephd/my-dev-kit-lab@0.4.8 --version`
+reported `0.4.8`. The sibling checkout at `C:\Users\daile\Projects\my-dev-kit-lab`
+was inspected read-only for corroboration and reports version `0.4.8`; it was
+not modified, built or written to.
+
+## 5. v0.4.8 positional pointer-action contract
+
+The released shapes, taken from the validator and the executor:
+
+```json
+{
+  "type": "pointer-click",
+  "locator": { "kind": "test-id", "testId": "runtime-annotation-surface" },
+  "position": { "x": 0.33, "y": 0.48 },
+  "coordinateSpace": "fraction",
+  "timeoutMs": 5000
+}
+```
+
+```json
+{
+  "type": "pointer-drag",
+  "locator": { "kind": "test-id", "testId": "runtime-annotation-surface" },
+  "from": { "x": 0.24, "y": 0.18 },
+  "to": { "x": 0.83, "y": 0.36 },
+  "coordinateSpace": "fraction",
+  "timeoutMs": 5000
+}
+```
+
+Contract facts that matter for authoring:
+
+- `coordinateSpace` is required and its only accepted value is `"fraction"`.
+- Coordinates are fractions of the located element's own bounding box, with
+  inclusive bounds `[0, 1]`. Anything outside that fails validation.
+- A zero-length `pointer-drag` is rejected by the validator, so a drag always
+  expresses a real gesture.
+- Execution is real Playwright mouse input: `mouse.move`, `mouse.down`, for a
+  drag a `mouse.move` to the end point in a fixed 8 steps
+  (`POINTER_DRAG_MOVE_STEPS = 8`), then `mouse.up`. The `mouse.up` runs even
+  when the movement throws, so a failed step cannot leave a button held down.
+- Both actions wait for the located element to be visible and then read its
+  bounding box. They anchor to one element rather than to the page, so a
+  scenario still cannot address arbitrary screen coordinates.
+- The cursor, click feedback, highlight and callout overlays are the lab's own
+  and are unchanged; Observer contributes none of them.
+
+Both names match what the defect diagnosis suggested, but they were taken from
+the released package, not assumed.
+
+## 6. Pointer defect reproduction closure
+
+The v0.4.7 blocker was that `drag` resolved two locators and dragged between
+their element centres, while Observer drawing needs two freely chosen points
+inside one surface. In every drawing mode the viewer deliberately makes target
+rectangles pointer-inert, so the only pointer-receiving element covering the
+drawing surface was the single screenshot `<image>`, and two locators could not
+yield two distinct points of one element.
+
+Before writing any scenario, that exact interaction was reproduced against the
+real demo, the real project-aware viewer and the real released v0.4.8 CLI. A
+disposable gate scenario drove all five drawing primitives and asserted the
+draft item count after each one:
+
+```text
+step              action           result   draft item count
+rectangle-draw    pointer-drag     passed   0 -> 1
+line-draw         pointer-drag     passed   1 -> 2
+arrow-draw        pointer-drag     passed   2 -> 3
+point-place       pointer-click    passed   3 -> 4
+note-place        pointer-click    passed   4 -> 5
+```
+
+The run finished `status: passed` with `cleanupErrors: []`, and the captured
+screenshot shows five real marks on the observation with the panel reporting
+"5 draft items". The marks were created through the viewer's ordinary pointer
+event path: `useAnnotationPointerInteraction`'s pointerdown, pointermove and
+pointerup handlers on the source-frame SVG.
+
+No Observer workaround was involved. No hidden control, no tutorial-only
+endpoint, no direct annotation POST, no `page.evaluate`, no React state
+mutation and no synthetic fixture. The gate passed with zero Observer source
+changes: the two viewer selectors described in section 14 were added
+afterwards, for authoring quality, not to make the gate pass.
+
+One measured detail that shaped every scenario: the drawing SVG's bounding box
+maps one-to-one onto the source frame, so a fraction of the element is a
+fraction of the captured viewport. That is why the committed coordinates read
+as sensible positions on the page.
+
+## 7. Point / Rectangle / Line / Arrow / Note gesture proof
+
+```text
+primitive   lab action      surface locator                                 position specification        real Observer draft
+point       pointer-click   test-id runtime-annotation-surface              position (0.33, 0.48)         point mark added
+rectangle   pointer-drag    test-id runtime-annotation-surface              (0.24,0.18) -> (0.83,0.36)    rectangle mark added
+line        pointer-drag    test-id runtime-annotation-surface              (0.24,0.64) -> (0.80,0.64)    line mark added
+arrow       pointer-drag    test-id runtime-annotation-surface              (0.30,0.55) -> (0.62,0.55)    arrow mark added
+note        pointer-click   test-id runtime-annotation-surface              position (0.35, 0.77)         note mark added with its text
+```
+
+The same two actions drive the reference surface in scenarios 3 and 4, anchored
+to `test-id reference-annotation-surface`.
+
+Every one of the five is exercised again in the committed scenarios, so the
+gate is not a one-off: scenario 1 alone creates all five mark kinds and its
+saved artifact contains `point, rectangle, line, arrow, note`.
+
+## 8. Disposable tutorial target architecture
+
+Each run gets a lab-owned run root. The lab passes `<runRoot>/target` to the
+prepare command as `{{targetRoot}}`, and prepare builds a complete throwaway
+Observer project inside it:
+
+```text
+<targetRoot>/demo/                    materialized deterministic demo
+<targetRoot>/demo/server.mjs          the demo server the lab then manages
+<targetRoot>/frontend-observer.json   canonical project configuration
+<targetRoot>/.frontend-observer/      canonical managed evidence state
+```
+
+These are the current canonical Observer paths (`PROJECT_CONFIG_FILENAME` and
+`PROJECT_STATE_DIRECTORY`), not a parallel layout. No second project
+configuration was invented.
+
+Nothing is ever written under `examples/v09-demo/`. The demo the lab serves is
+the materialized copy inside the target root, not the tracked template.
+
+## 9. Dynamic target-contract generation
+
+`examples/v09-demo/scripts/generate-tutorial-target.mjs` writes one contract to
+an explicit `--out` path for an explicit `--scenario`.
+
+Ports are discovered with Node built-ins only: a temporary
+`net.Server` bound to `127.0.0.1:0`, the assigned port read back, the listener
+closed. Two ports are taken and checked to be distinct. No dependency was
+added.
+
+Closing the probe is unavoidable, and it means a port is only known-free at the
+instant it is chosen; nothing can reserve a TCP port without holding it open.
+The contract is therefore generated immediately before each run, and that
+constraint is documented in the demo README.
+
+`--demo-port` and `--viewer-port` pin the ports for deterministic debugging and
+for the generator's own tests. Generated contracts carry absolute paths and
+live ports, so none are committed; only the generator is.
+
+The contract declares a `demo-server` process with an HTTP readiness probe on
+`/health`, an `observer-viewer` process with a readiness probe on
+`/api/status`, and an `applicationUrl` pointing at the viewer, which is the
+application the tutorials drive. Both processes use `cwd: "target-root"`, and
+the viewer is started without `--root` so the project-aware session discovers
+the prepared project itself.
+
+## 10. Prepare/bootstrap lifecycle
+
+`examples/v09-demo/scripts/prepare-tutorial-target.mjs` is the contract's
+trusted prepare executable. It runs once and terminates; it never becomes a
+server.
+
+In order:
+
+1. validate `--target-root`, `--scenario` and `--demo-port`;
+2. materialize the demo by calling Prompt 1's own `prepareDemoTarget`, so no
+   second demo-copy implementation exists;
+3. start Prompt 1's `startDemoServer` in process on the same `demoPort` the lab
+   will later use;
+4. `node dist/cli.js init` with the demo URL, the 1440x900 viewport and a
+   targets file;
+5. `node dist/cli.js capture baseline`;
+6. scenario-specific evidence;
+7. stop the temporary server in a `finally`.
+
+The temporary server exists because Observer's canonical `init` and `capture`
+need a live loopback target. Stopping it in a `finally` means a failing prepare
+still releases the port, which a test verifies by rebinding that exact port
+after prepare returns.
+
+Every artifact comes from a canonical owner. Prepare authors contract JSON only
+as *input* to `approve-baseline` and `save-change-contract`, which are what
+validate and persist the artifacts; it never writes an artifact manifest
+itself.
+
+## 11. Baseline observation setup
+
+`capture baseline` is run through the built CLI, and the result is verified
+rather than assumed: the alias `baseline` resolves in the project catalog, the
+observation manifest's `observationId` matches the catalog entry, the
+`screenshot.png` is non-empty, and all ten configured runtime targets report
+`selectionStatus: matched`.
+
+The configured targets bind to Prompt 1's stable vocabulary:
+
+```text
+header, navigation, hero, sidebar, content, card1, card2, cta, footer, asset
+```
+
+Observer target names must match `^[A-Za-z0-9_-]{1,64}$`, which has no place
+for a hyphenated `card-1`, so the two card targets are named `card1` and
+`card2` while their selectors remain `[data-demo-target="card-1"]` and
+`[data-demo-target="card-2"]`. That is the only naming adjustment, and it is
+deterministic.
+
+## 12. Contract activation setup
+
+For `observer-v09-runtime-contract`, prepare additionally approves a baseline
+contract and saves an initial change contract through the canonical commands,
+then writes project acceptance.
+
+The acceptance block is written through the canonical
+`validateProjectConfig` owner: the configuration is read, extended,
+revalidated and only then written back, so an invalid acceptance block can
+never reach disk.
+
+One correction was needed during implementation. `--output` names a *parent*
+directory and the writer creates the artifact directory beneath it, so
+acceptance must point at the artifact directory, not the output argument.
+Pointing at the parent produced a genuine runtime refusal from the promotion
+service ("the configured baseline contract is missing or invalid"). The real
+persisted paths are now read back from the CLI's own `Artifact:` output and
+converted to portable project-relative paths.
+
+After the tutorial promotes and activates, the canonical check in section 21
+confirms the baseline entry is untouched and only the change entry moved.
+
+## 13. External-reference setup
+
+For both reference scenarios, prepare imports the fixed Prompt 1 asset
+`examples/v09-demo/references/v09-reference.png` through `import-reference`
+with a `--label` of `v09-tutorial-reference`, then approves it through
+`approve-reference`. No external-reference manifest is handwritten.
+
+Regions come from a new tracked fixture,
+`examples/v09-demo/references/v09-reference-regions.json`, holding seven
+regions: `header, hero, sidebar, content, cta, asset, footer`.
+
+The geometry was not guessed. The committed PNG's dimensions were read from its
+own IHDR chunk and confirmed to be 1440x900, and the rectangles were then
+measured from the demo's `reference` state in real Chromium at that exact
+viewport. Because the PNG is a 1:1 viewport capture, reference-image pixels
+equal that state's rendered geometry. Every rectangle is integral and inside
+the image bounds. A test re-derives the digest of the committed PNG and
+asserts the imported artifact carries exactly those bytes and those region ids.
+
+Applicability was left undeclared. The importer does not require it here, and
+inventing a theme or application state merely for completeness would have been
+fabricated metadata.
+
+## 14. Viewer selector stabilization
+
+Two selectors were added, one per annotation drawing surface:
+
+```text
+data-testid="runtime-annotation-surface"     the observation drawing surface
+data-testid="reference-annotation-surface"   the reference drawing surface
+```
+
+The entire production diff under `viewer/src/` is 18 added lines across four
+files and zero deleted lines: an optional `surfaceTestId` prop on
+`TargetOverlaySvg` and `ReferenceRegionOverlaySvg`, rendered as `data-testid`
+only when supplied, plus the two call sites that supply it.
+
+The prop is optional on purpose. `TargetOverlaySvg` is also rendered twice
+side by side in the comparison workspace, where one shared test id would be
+ambiguous, so only the annotation-capable workspace supplies one. A test
+asserts exactly one of each id is ever present.
+
+Everything else in the scenarios uses existing accessibility, in the priority
+order the task sets: `role` plus accessible name wherever possible
+(`Rectangle mode`, `Associate target hero`, `Select reference region sidebar`,
+`observation baseline`), existing stable data attributes for status
+(`data-draft-item-count`, `data-interpretation-state`, `data-activation-state`,
+`data-materialized-lifecycle`), and deliberate stable classes for a few status
+paragraphs. No selector binds to a generated identifier, and a test enforces
+that by rejecting any 32-character hex run, any `annotation-item-` prefix and
+any `:nth-child` anywhere in the four scenarios.
+
+No behavior branch, no tutorial-only control, no hidden button and no alternate
+code path was added. A test drives a real drawing gesture through the newly
+identified surface to prove the attribute changed nothing.
+
+## 15. Annotation basics scenario
+
+`observer-v09-annotation-basics`, 27 steps.
+
+Covers the project-aware viewer, selecting the baseline observation by its
+human alias, Select and Pan modes, all five mark kinds, explicit target
+association, save, reload, and reopening the saved annotation as a revision.
+
+The narration teaches that a mark is evidence rather than a requirement; that
+drawing over a target does not associate it, because overlap genuinely is
+ambiguous; that Select and Pan are separate so one drag is never ambiguous;
+that saving produces immutable evidence; and that editing produces a revision
+rather than a rewrite.
+
+The arrow step already plants the idea the next tutorial proves: a drawn
+direction is a fact about the drawing, not an instruction about the layout.
+
+One real authoring defect was found and fixed here rather than worked around.
+The arrow originally crossed the rectangle's clickable centre, so selecting the
+rectangle failed with a genuine pointer interception. The arrow was moved to
+the card row.
+
+## 16. Runtime intent and contract scenario
+
+`observer-v09-runtime-contract`, 106 steps.
+
+Demonstrates all five operations, `inspect`, `move`, `resize`, `preserve` and
+`remove`, and all four authorable categories, `requested`,
+`expected-dependent` with mode `required`, `protected` and `preserved`. The
+narration states plainly that `unexpected` is not authorable, because it is
+something Observer concludes when comparing runs, never something a person
+declares in advance.
+
+The required mappings are all shown as real structured output:
+
+```text
+Move Right            -> property-increases hero.x
+Resize Wider          -> property-increases sidebar.width
+Preserve property     -> property-unchanged-within-tolerance footer.y
+Preserve relationship -> relationship-unchanged
+```
+
+Arrow non-inference is demonstrated, not merely narrated: the arrow is drawn
+pointing left, the move direction `right` is chosen explicitly, and the
+scenario asserts the resulting primitive is `property-increases` on
+`"property": "x"` for `"target": "hero"`.
+
+Confirmation invalidation is shown by retargeting a confirmed intent from
+`hero` to `content`: the primitive follows the new association and the
+interpretation drops back to `candidate`, which the scenario asserts. The
+subject is then restored and reconfirmed.
+
+`Remove` is confirmed and then shown to be unpromotable, with the product's own
+words asserted: the vocabulary has "no target-absent primitive". `Inspect` is
+confirmed and shown to be informational for good.
+
+Selective promotion picks two of four confirmed intents by their deterministic
+human-readable labels, and activation is a separate explicit checkbox. The
+promotion result is asserted to report `2 clauses` and
+`Activation: activated`.
+
+Two real defects were found and fixed while making this run: the evidence-list
+locator `baseline` became ambiguous once a contract path also contained the
+word, and a perfectly horizontal line has a zero-height bounding box that
+Playwright treats as invisible. The locator is now `observation baseline` and
+the line is drawn diagonally.
+
+## 17. Reference authoring scenario
+
+`observer-v09-reference-authoring`, 64 steps.
+
+Covers reference-image coordinates, explicit region association, candidate
+region create and refine, all three requirement subject kinds, informational
+intent, asset-sensitive intent, confirmation and save.
+
+The coordinate distinction is asserted, not just narrated: the surface's
+accessible name is checked to be exactly `Reference image, 1440 by 900 pixels`,
+and the narration explains these are image pixels and not the runtime CSS
+pixels of a rendered page.
+
+The three requirements use real current vocabulary:
+
+```text
+region-property      hero.width, protected, absolute-reference-px 4
+region-relationship  chosen from relationships Observer derived from this
+                     reference's own geometry, protected
+region-measurement   vertical-gap hero to cta, preserved,
+                     absolute-reference-px 6
+```
+
+The relationship is picked from the canonical derived list rather than typed,
+so the scenario cannot require a relationship the image does not contain.
+
+Asset-sensitive intent is shown as informational, with the narration
+explaining that an image mattering to a human eye is not the same as a
+checkable geometric claim.
+
+The requirement form keeps its previous values when another mark is selected,
+unlike the runtime form which resets. That is existing product behavior and was
+not changed; the scenario steps from the retained value instead, and the demo
+README documents it for anyone editing these files.
+
+## 18. Reference materialization scenario
+
+`observer-v09-reference-materialization`, 51 steps.
+
+From a clean run: open the approved source reference, create a candidate
+region, refine an existing region, author two requirements, confirm all four,
+save, select three of the four, and materialize.
+
+Leaving the fourth unselected is the point. It is confirmed and correct and
+simply not part of this revision, which is what makes selection meaningful and
+is verified afterwards by the new revision carrying exactly one requirement.
+
+The scenario asserts the product's own bounded evidence before acting, that
+materialization is blocked until the annotation is saved and that the warning
+states the current reference remains unchanged and the result is "not approved
+automatically"; and afterwards that the result reports `Lifecycle: imported`,
+`Approval required: yes`, a `Supersedes:` line and `Requirements: 1`.
+
+The final step notes that the viewer did not switch to the new revision, and
+explains why quietly adopting an unapproved reference would make approval
+meaningless. No behavior was changed to make navigation easier.
+
+## 19. Lab scenario validation
+
+Every scenario was validated by the real released CLI against a freshly
+generated target contract:
+
+```text
+observer-v09-annotation-basics            valid   targetIdMatches true   27 steps
+observer-v09-runtime-contract             valid   targetIdMatches true  106 steps
+observer-v09-reference-authoring          valid   targetIdMatches true   64 steps
+observer-v09-reference-materialization    valid   targetIdMatches true   51 steps
+```
+
+## 20. Real tutorial execution
+
+All four executed through `my-dev-kit-lab tutorial run` with real Chromium,
+each into its own run root outside the repository, under
+`%TEMP%\my-frontend-observer-v09-tutorial-smoke\final\`. `Z:` was not available
+on this machine, so the documented fallback was used.
+
+```text
+scenario                                  status   cleanupErrors   failed steps
+observer-v09-annotation-basics            passed   []              none
+observer-v09-runtime-contract             passed   []              none
+observer-v09-reference-authoring          passed   []              none
+observer-v09-reference-materialization    passed   []              none
+```
+
+Every run reported `TutorialRunResultV1` schema `1.0.0`. Each scenario received
+a fresh target root and built its own starting state; no run consumed another
+run's output.
+
+## 21. Canonical Observer post-run verification
+
+The video is not correctness authority. Each run's disposable target root was
+read directly. All 35 checks passed.
+
+Scenario 1: one saved `my-frontend-observer/visual-annotation` artifact,
+schema `1.0.0`, source `runtime-observation` whose `observationId` equals the
+prepared baseline; all five mark kinds present; exactly one explicit
+`runtime-target` association, to `hero`; the other four marks still
+unassociated.
+
+Scenario 2: project acceptance still names
+`tutorial-baseline/v09-tutorial-baseline` as `baselineArtifact`, unchanged;
+`changeArtifact` now points at a promoted change contract that is not the
+initial one; that contract has exactly two clauses:
+
+```text
+requested:property-increases:hero.x
+expected-dependent:property-increases:sidebar.width
+```
+
+Remove did not become a clause, Inspect did not become a clause, and the saved
+annotation still records all six items with all six confirmed, including the
+unpromotable remove and inspect intents.
+
+Scenario 3: annotation source is `external-reference`; seven items, all
+confirmed; region `create` and `refine` both present; all three requirement
+subject kinds present; informational and asset-sensitive intents confirmed and
+not materialized; and no new reference revision was created by authoring
+alone, which is the distinction the next tutorial builds on.
+
+Scenario 4: exactly one approved reference still exists and no approved
+successor was created; a new imported revision exists whose
+`supersedesReferenceId` equals the approved source's `referenceId`; it carries
+8 regions including `promo-band`, and the refined `sidebar` rectangle really
+differs from the source's; it carries exactly one requirement, the selected
+`hero.width` one, and the unselected footer requirement is absent; the source
+approved reference is unchanged at 7 regions and 0 requirements; and the image
+digest is byte-identical to the committed PNG
+(`4bdb94db1096532d...`), proving the source image is reused and annotation
+marks are not baked into it.
+
+## 22. Tutorial artifact inventory
+
+Every required artifact was written as a non-empty regular file, and every
+requested screenshot was produced.
+
+```text
+scenario                                video     srt     vtt     markdown  manifest  screenshots
+observer-v09-annotation-basics          1.8 MB    3.0 kB  2.9 kB  3.2 kB    24.6 kB   9 of 9
+observer-v09-runtime-contract           5.5 MB   11.3 kB 11.0 kB 12.0 kB    66.3 kB  13 of 13
+observer-v09-reference-authoring        3.8 MB    7.5 kB  7.3 kB  8.0 kB    42.9 kB   8 of 8
+observer-v09-reference-materialization  2.8 MB    4.5 kB  4.4 kB  4.7 kB    32.8 kB   6 of 6
+```
+
+All four manifests declare `TutorialManifestV1` schema `1.0.0`.
+
+No generated artifact is tracked. Videos, screenshots, subtitles, Markdown,
+manifests, generated target contracts, target roots and logs all live outside
+the repository or under the git-ignored workflow root. Prompt 3 owns the human
+review of these artifacts and any decision to retain some of them.
+
+## 23. Source/demo immutability
+
+A SHA-256 digest of all 19 tracked files under `examples/v09-demo/` was taken
+after implementation was complete and immediately before the four final runs,
+and recomputed after all four finished.
+
+```text
+demoSourceImmutable: true
+```
+
+Tutorial execution mutated nothing in the tracked template. The bootstrap test
+independently fingerprints the template around a real prepare and asserts the
+same thing, and the Prompt 1 materialization test continues to prove the
+template survives a destructive rematerialization.
+
+## 24. Full Observer regression
+
+```text
+npm run typecheck     PASS
+npm run lint          PASS
+npm test              PASS  (89 files, 1451 tests)
+npm run test:browser  PASS  (29 files, 275 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, 364 files, 0 examples/ entries)
+```
+
+New tests added by this stage:
+
+- `tests/unit/v09TutorialTargetContract.test.ts` (16 tests): released schema
+  version, exact target id shared by all four scenarios, only keys the
+  released validator accepts, no shell-like field, `{{targetRoot}}` as the only
+  placeholder, demo readiness on `/health`, viewer readiness on `/api/status`,
+  `applicationUrl` pointing at the viewer, loopback-only urls, rejection of an
+  unknown scenario and of invalid or identical ports, determinism for explicit
+  ports, and two distinct free ports when none are given.
+- `tests/unit/v09TutorialScenarios.test.ts` (10 tests): exactly four files,
+  released schema version, unique ids in order, one shared target id,
+  1440x900 viewport, non-empty narration on every step, only released
+  actions/locators/assertions, in-bounds non-degenerate pointer fractions,
+  never using element-to-element `drag` for drawing, no Observer-only field, no
+  absolute path, and no selector bound to a generated identifier. It
+  deliberately does not reimplement the lab validator, which is run separately.
+- `tests/browser/v09TutorialBootstrap.test.ts` (17 tests): real prepare runs
+  with real Chromium capture, proving materialization, canonical project
+  initialization, target binding to the demo vocabulary, baseline capture with
+  all ten targets matched, the temporary server releasing its port, contract
+  acceptance with valid baseline and change contracts tied to the captured
+  observation, canonical reference import and approval with a digest match
+  against the committed PNG, and template immutability.
+- `tests/browser/v09ViewerTutorialSelectors.test.ts` (6 tests): each new test
+  id present exactly once in the state a tutorial uses it in, on the real SVG
+  surface, with its pre-existing role, accessible name and class untouched,
+  present across every interaction mode, still drawing correctly, and never
+  duplicated.
+
+One existing test was updated rather than weakened:
+`tests/unit/v09DemoMaterialization.test.ts` pinned the demo template's
+top-level entries, which legitimately gained `tutorials/`. No test was skipped,
+deleted or made permissive, and no `.skip`, `.only`, `continue-on-error` or
+`|| true` was introduced.
+
+## 25. Scope audit
+
+All of the following are `false`:
+
+```text
+Observer tutorial runtime implemented          false
+Observer Playwright loader added               false
+Observer browser recorder added                false
+Observer subtitle writer added                 false
+Observer tutorial-manifest schema added        false
+Observer cursor implementation added           false
+Observer callout renderer added                false
+Observer arbitrary tutorial JavaScript added   false
+Observer product semantics changed             false
+annotation schema changed                      false
+contract schema changed                        false
+reference schema changed                       false
+package version changed                        false
+dependency added                               false
+my-dev-kit-lab modified                        false
+v0.9 released                                  false
+```
+
+`package.json` and `package-lock.json` are untouched. The dependency set is
+still exactly `playwright`; `@dailephd/my-dev-kit-lab` appears in neither
+`dependencies` nor `devDependencies`, and is invoked only as an external tool
+through `npx`.
+
+`src/` is unchanged. The only production change is the 18-line additive viewer
+selector diff in section 14.
+
+`examples/v09-demo` was deliberately not added to `package.json#files`; a pack
+dry run confirms zero `examples/` entries. Prompt 3 owns that decision.
+
+Documentation scope was respected: only `examples/v09-demo/README.md` and this
+report were written.
+
+## 26. Changed files
+
+Added:
+
+```text
+examples/v09-demo/scripts/generate-tutorial-target.mjs
+examples/v09-demo/scripts/prepare-tutorial-target.mjs
+examples/v09-demo/references/v09-reference-regions.json
+examples/v09-demo/tutorials/01-annotation-basics.json
+examples/v09-demo/tutorials/02-runtime-intent-contract.json
+examples/v09-demo/tutorials/03-reference-authoring.json
+examples/v09-demo/tutorials/04-reference-materialization.json
+tests/unit/v09TutorialTargetContract.test.ts
+tests/unit/v09TutorialScenarios.test.ts
+tests/browser/v09TutorialBootstrap.test.ts
+tests/browser/v09ViewerTutorialSelectors.test.ts
+docs/reports/v0.9-tutorial-integration.md
+```
+
+Modified:
+
+```text
+examples/v09-demo/README.md                        developer tutorial section
+viewer/src/components/TargetOverlaySvg.tsx         optional surfaceTestId prop
+viewer/src/components/ReferenceRegionOverlaySvg.tsx optional surfaceTestId prop
+viewer/src/components/ObservationWorkspace.tsx     supplies the runtime id
+viewer/src/components/ReferenceWorkspace.tsx       supplies the reference id
+tests/unit/v09DemoMaterialization.test.ts          template inventory now includes tutorials/
+```
+
+Generated paths, all git-ignored or outside the repository:
+
+```text
+.my-dev-kit-workflow/v0.9/tutorial-integration/     generated contracts, probes, smoke results
+%TEMP%/my-frontend-observer-v09-tutorial-smoke/     tutorial run roots and artifacts
+```
+
+`git diff --check` reports no whitespace problems, and `git status --short`
+shows no generated tutorial artifact in tracked source.
+
+## 27. Remaining Prompt 3 work
+
+Prompt 3 owns end-to-end tutorial acceptance, human review of the four videos,
+subtitles and Markdown, documentation reconciliation across the release-facing
+documents, the decision on whether `examples/v09-demo` ships inside `0.9.0`,
+and the final release regression.
+
+Two things are worth carrying forward. The scenarios drive native `<select>`
+controls with `ArrowDown` presses because the lab has no select action, so the
+press counts follow the order of Observer's frozen intent vocabularies and will
+need updating if one of those lists gains a member; this is documented in the
+demo README. And free-port discovery cannot hold a port, so a target contract
+should always be generated immediately before its run.
+
+No blocker remains.