@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/docs/reports/v0.9-tutorial-end-to-end-acceptance.md

@@ -0,0 +1,980 @@
+# v0.9 Tutorial End-to-End Acceptance
+
+## 1. VERDICT
+
+`PASS_V0_9_TUTORIAL_ACCEPTANCE_READY_FOR_HUMAN_REVIEW`
+
+```text
+FINAL_RUNS_PASSED                     4 of 4
+CLEANUP_ERRORS                        empty for every run
+STRUCTURAL_ARTIFACT_ACCEPTANCE        PASS (144 checks)
+CANONICAL_OBSERVER_EVIDENCE           PASS (44 checks)
+SCENARIO_CONTENT_QUALITY              PASS (after the corrections in section 8)
+DEMO_SOURCE_IMMUTABILITY              PASS
+DEMO_IN_NPM_PACKAGE                   false
+FULL_LOCAL_REGRESSION                 PASS
+LOCAL_PACKED_SMOKES                   PASS
+HUMAN_VISUAL_REVIEW                   PENDING_USER
+```
+
+All four tutorials were regenerated from clean targets with the released
+`@dailephd/my-dev-kit-lab@0.4.8` against the current local unreleased v0.9
+build. Every run passed with no cleanup error, and every outcome was then
+checked by reading the canonical Observer evidence the run actually wrote.
+
+This stage corrected six real tutorial-quality defects, one of which was a
+narration that did not match the evidence the tutorial produced. See
+section 8.
+
+Observer gained no tutorial runtime, no dependency and no product-semantics
+change. The package stays at `0.8.1` and v0.9 stays unreleased. A coding agent
+cannot judge how a video looks, so human visual review is honestly recorded as
+pending.
+
+## 2. Repository identity
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Branch: `master`
+- Starting HEAD: `6895b303d618fe705252e3cbdbfcd665a656c407`
+- Ending HEAD: recorded in the terminal summary for this stage
+- Package: `@dailephd/my-frontend-observer`
+- Package version: `0.8.1` (unchanged)
+- Viewer protocol: `1.3.0`
+- Visual annotation schema: `1.0.0`
+- v0.9: unreleased
+
+## 3. Entry gate
+
+Preflight matched every required value:
+
+```text
+branch                                  master
+HEAD                                    6895b303d618fe705252e3cbdbfcd665a656c407
+tracked worktree                        clean
+package version                         0.8.1
+docs/reports/v0.9-architecture-retrieval.md   S (skip-worktree preserved)
+```
+
+No `pull`, `reset`, `rebase`, `clean` or `stash` was run at any point.
+
+The Prompt 2 entry verdict `PASS_V0_9_TUTORIAL_INTEGRATION` was present, and
+its implementation was preserved. The four defect corrections Prompt 2 made
+were not reverted.
+
+## 4. Final tutorial review bundle
+
+`Z:` is not available on this machine, so the documented fallback root was
+used and is recorded here exactly:
+
+```text
+C:\Users\daile\AppData\Local\Temp\my-frontend-observer-tutorial-review\v0.9
+```
+
+The exact review root was removed and recreated before the final runs. Only
+that path was removed, after checking that its last two segments were
+`my-frontend-observer-tutorial-review\v0.9`, that it was inside `%TEMP%`, and
+that it was not inside the repository. No parent directory was touched.
+
+Structure:
+
+```text
+<reviewRoot>/
+    01-annotation-basics/          lab run root (target, artifacts, screenshots, logs, temporary)
+    02-runtime-intent-contract/    lab run root
+    03-reference-authoring/        lab run root
+    04-reference-materialization/  lab run root
+    _contracts/                    the four generated target contracts
+    _run-results/                  run results, validations, verification.json
+    REVIEW_INDEX.md
+```
+
+Lab-owned run contents were not reorganized. `_contracts/` is the location the
+task prefers for generated contracts; `_run-results/` holds the captured
+`TutorialRunResultV1` documents and the acceptance verification output so the
+evidence behind this report can be re-read.
+
+Absolute review paths are listed in section 26.
+
+## 5. my-dev-kit-lab identity
+
+```text
+npx --yes @dailephd/my-dev-kit-lab@0.4.8 --version    0.4.8
+```
+
+Exact `0.4.8` was used for every validation and every final run. The lab was
+not modified. It is not an Observer dependency and appears in neither
+`dependencies` nor `devDependencies`; it is invoked only through `npx`.
+
+Observed limits of the released lab, unchanged and not worked around:
+
+1. There is no select-option action, so native `<select>` controls are driven
+   with `ArrowDown` presses. See section 13.
+2. The tutorial manifest carries no artifact record for itself. This is the
+   known limitation and is not reported as a defect.
+
+## 6. Scenario inventory
+
+```text
+id                                        file                                 steps  screenshots
+observer-v09-annotation-basics            01-annotation-basics.json               33           11
+observer-v09-runtime-contract             02-runtime-intent-contract.json        106           14
+observer-v09-reference-authoring          03-reference-authoring.json             64           10
+observer-v09-reference-materialization    04-reference-materialization.json       50            7
+```
+
+Each scenario was validated by the released lab against a freshly generated
+target contract immediately before its run:
+
+```text
+scenario                                  validation   targetId match   run
+observer-v09-annotation-basics            valid        yes              passed
+observer-v09-runtime-contract             valid        yes              passed
+observer-v09-reference-authoring          valid        yes              passed
+observer-v09-reference-materialization    valid        yes              passed
+```
+
+Each run received its own clean run root and its own freshly prepared target
+root, with two distinct dynamic loopback ports. No run reused another run's
+state.
+
+## 7. Structural artifact acceptance
+
+The returned `TutorialRunResultV1` is the authority for cleanup:
+
+```text
+scenario                                  result.status   result.cleanupErrors   manifest.run.status
+observer-v09-annotation-basics            passed          []                     passed
+observer-v09-runtime-contract             passed          []                     passed
+observer-v09-reference-authoring          passed          []                     passed
+observer-v09-reference-materialization    passed          []                     passed
+```
+
+Every result reported schema `1.0.0`. No run reported `cleanup-failed`,
+`artifact-failed`, `step-failed` or `video-finalization-failed`.
+
+Artifact inventory, all regular non-empty files:
+
+```text
+scenario                                  webm      srt      vtt      md       manifest  screenshots
+observer-v09-annotation-basics            27.9 MB   6.5 kB   6.4 kB   7.1 kB   29.8 kB   11 of 11
+observer-v09-runtime-contract             49.3 MB  12.3 kB  12.0 kB  13.0 kB   68.0 kB   14 of 14
+observer-v09-reference-authoring          34.3 MB   8.0 kB   7.8 kB   8.7 kB   44.5 kB   10 of 10
+observer-v09-reference-materialization    19.6 MB   4.9 kB   4.8 kB   5.2 kB   33.6 kB    7 of 7
+```
+
+Checks that passed for every scenario (144 structural checks in total, zero
+failures; the 44 canonical evidence checks are in section 17):
+
+1. WebM: EBML signature `1A 45 DF A3`, `webm` DocType in the EBML header,
+   non-empty and plausibly sized. No FFmpeg or ffprobe was added and nothing
+   was transcoded.
+2. Manifest: `schemaVersion 1.0.0`, `run.status passed`, `cleanupErrors` empty,
+   `warnings` empty, every executed step present in scenario order, every step
+   `passed`, every requested screenshot represented with path
+   `screenshots/<id>.png` and status `written`, and every artifact path
+   run-root-relative with no drive letter, no leading separator and no `..`.
+3. Every manifest artifact record exists on disk. The two process `stderr`
+   logs are correctly recorded as written and are empty, because neither the
+   demo server nor the viewer wrote to stderr.
+4. Screenshots: valid PNG signature and IHDR, non-empty, all 1440x900. No
+   unrequested screenshot was produced. No pixel-diff acceptance was done.
+5. SRT and VTT: one cue per executed step, cue order equal to step order, cue
+   text byte-equal to the scenario narration, timestamps monotonic and
+   non-overlapping, and every cue boundary equal to the manifest timeline for
+   that step. Subtitle wording was never edited separately; the scenario
+   remains the single narration source.
+6. Markdown: correct title, every executed step present in order, narration
+   preserved verbatim, requested screenshots referenced as
+   `../screenshots/<id>.png` and each reference resolves to a real file, no
+   machine-specific absolute path, and no line of prose beyond the scenario's
+   own title, description, step headings, narration and image references.
+
+## 8. Scenario content-quality audit
+
+Every step was read and judged against the questions the task sets: whether
+the narration explains why an operation exists, whether it draws the
+distinction that matters, whether the step does real product work, and whether
+it is materially more useful than naming the control being clicked.
+
+The audit found six genuine defects. All six were corrected in this stage and
+all four scenarios were then rerun from clean targets. The corrections
+stayed inside scenario narration, pauses, screenshot requests, callouts and
+scenario step sequence. No product behavior was changed.
+
+### 8.1 Narration that contradicted the evidence (scenario 4)
+
+The second requirement in `04-reference-materialization` was narrated as being
+about the footer, and the tutorial's whole point is that the unselected
+requirement is a real, confirmed, correct requirement left out of the
+revision. The saved evidence from the Prompt 2 run says otherwise:
+
+```text
+{"category":"preserved","subject":{"kind":"region-property","region":"promo-band","property":"height"}}
+```
+
+The requirement-region select keeps its previous value, `hero`, and the region
+list is the reference's own regions in import order followed by the regions
+the draft proposes. Six `ArrowDown` presses from `hero` therefore pass
+`sidebar, content, cta, asset, footer` and land on the draft's own
+`promo-band`. One press too many selected a different but equally valid
+region, so nothing failed and the run passed with narration that was untrue.
+
+Correction: the press count is now five, which lands on `footer`. The step
+`req-b-region-6` was removed and the five remaining presses now name the value
+each one lands on. The scenario now also asserts the resulting structured
+requirement immediately:
+
+```json
+{ "type": "text-contains", "expected": "\"region\": \"footer\"" }
+{ "type": "text-contains", "expected": "\"property\": \"height\"" }
+```
+
+That assertion is the regression guard: the same defect would now fail the run
+instead of producing a confident false statement. The final run confirms the
+unselected requirement is `preserved footer.height`, and that it did not
+materialize.
+
+Note for the record: section 21 of `docs/reports/v0.9-tutorial-integration.md`
+describes this item as "the unselected footer requirement". That statement was
+inaccurate for the Prompt 2 candidate. It is accurate for the current one.
+
+### 8.2 Narration that was too fast to read (all four scenarios)
+
+No step declared a pause, so each step lasted only as long as its action. In
+the Prompt 2 run, `01-annotation-basics` played 4301 characters of narration
+in 20.7 seconds, and its opening 40-word subtitle cue was on screen for 256
+milliseconds. The structure was valid and the content was good, but nobody
+could read it. That is the "near-zero instructional visibility" the timing
+audit asks about.
+
+Correction: every step now carries a `pauseAfterMs` sized from its own
+narration at 15 characters per second, never below 1.2 seconds. The pause runs
+after the action and after any callout is drawn, so it extends both the
+subtitle cue and the time a callout stays readable, and it is inside the
+step's timeline, so subtitles and manifest stay consistent.
+`tests/unit/v09TutorialScenarios.test.ts` now enforces that floor, so
+lengthening a narration without lengthening its pause fails a unit test.
+
+### 8.3 A claim the tutorial never demonstrated (scenario 1)
+
+`01-annotation-basics` told the viewer that saving again writes a new
+annotation recording which one it revises, and that the original stays
+untouched. It then stopped at the revision draft without saving, so the
+strongest claim in the tutorial was the one thing it never showed, and there
+was no supersession chain in the evidence to verify.
+
+Correction: five steps were added. In the revision draft the point mark, which
+was saved with no association, is explicitly associated with `card1` and the
+revision is saved. The canonical check in section 17 now verifies a real
+two-artifact chain.
+
+### 8.4 View state that made the revision unreadable (scenario 1)
+
+After the reload, the relationship overlay returns, because a view toggle is
+page state rather than evidence. The final revision screenshots were covered
+in dashed relationship lines.
+
+Correction: one step switches the overlay off again, and its narration uses
+the moment to make the point that the annotation came back from disk while the
+toggle did not.
+
+### 8.5 Mechanical narration on keyboard steps
+
+Several keypress steps read only "Stepping down." Individually harmless, but a
+recording that says "Stepping down" eleven times teaches nothing and makes the
+keyboard-driven select changes hard to follow, which is exactly what review
+question 8 asks about.
+
+Correction: each press in a run now names the value it lands on, for example
+"Inspect.", "Move.", "Resize.", "Remove.", "Preserve.", and the first press of
+each run explains what is being chosen and why. The vocabulary order is now
+visible in the recording instead of implied.
+
+### 8.6 Narration that did not name what was chosen
+
+Two steps described a mark's position rather than the association actually
+made. In scenario 2 a line is drawn across the call-to-action band and then
+bound to the first derived relationship, which is `header` horizontally
+overlapping `navigation`. In scenario 3 the narration said the header "sits
+above" the hero while the requirement protects `horizontally-overlapping`.
+
+Correction: both now name the relationship, and scenario 2 turns the mismatch
+into the lesson: where a mark is drawn never decides what it is about. Both
+scenarios now assert the relationship they narrate.
+
+### 8.7 Judgement on the rest
+
+The remaining narration passes. Short lines such as "Confirmed." appear only
+on steps whose meaning was explained immediately before, and the substantive
+steps explain purpose rather than naming controls. No step's substance is only
+"Click Rectangle" or "Press Confirm".
+
+## 9. Annotation basics review
+
+`observer-v09-annotation-basics`, 33 steps, 6 min 24 s.
+
+Content gate:
+
+```text
+marks are evidence, not requirements        PASS  (steps point-mode, point-place, five-marks)
+visual overlap is not association           PASS  (explain-no-association, with callout)
+Select, Pan and drawing modes differ        PASS  (explain-select-mode, explain-pan-mode)
+association is explicit                     PASS  (select-hero-target, associate-hero)
+saving creates immutable evidence           PASS  (save-annotation, confirm-saved)
+revision does not rewrite history           PASS  (explain-revision, and now save-revision)
+```
+
+The tutorial creates all five mark kinds, associates exactly one of them on
+purpose, saves, reloads from disk, reopens the saved annotation as a revision,
+changes one association, and saves the revision. The claim about revisions is
+now demonstrated and then verified in the evidence.
+
+## 10. Runtime intent and contract review
+
+`observer-v09-runtime-contract`, 106 steps, 10 min 48 s.
+
+Content gate:
+
+```text
+drawing does not determine intent                       PASS
+arrow geometry does not determine move direction        PASS  (drawn left, direction right, asserted)
+candidate != confirmed                                  PASS
+confirmed can become candidate again after editing      PASS  (retarget hero -> content, asserted)
+Inspect is informational and non-promotable             PASS  (asserted "informational")
+Remove is confirmable but unsupported for promotion     PASS  (asserted "no target-absent primitive")
+confirmed != selected for this contract                 PASS  (4 confirmed, 2 selected)
+promotion != activation                                 PASS  (separate explicit checkbox)
+```
+
+The structured mappings are shown as real product output, not narrated:
+`property-increases hero.x`, `property-increases sidebar.width`,
+`property-unchanged-within-tolerance footer.y`, and `relationship-unchanged`.
+The promotion result is asserted to report `2 clauses` and
+`Activation: activated`.
+
+## 11. Reference authoring review
+
+`observer-v09-reference-authoring`, 64 steps, 7 min 11 s.
+
+Content gate:
+
+```text
+reference-image pixels != runtime CSS pixels            PASS  (aria-label asserted exactly)
+drawing a region != binding it                          PASS  (callout plus explicit refine)
+visible detail != requirement                           PASS
+property != relationship != measurement                 PASS  (all three authored and asserted)
+asset-sensitive/informational != executable requirement PASS
+```
+
+The relationship requirement is chosen from the list Observer derived from the
+reference's own geometry, so a requirement the image does not contain cannot
+be authored. The final run recorded `header`/`hero` `horizontally-overlapping`
+protected, `hero.width` protected within 4 reference pixels, and a
+`vertical-gap` from `hero` to `cta` preserved within 6 reference pixels.
+
+## 12. Reference materialization review
+
+`observer-v09-reference-materialization`, 50 steps, 4 min 11 s.
+
+Content gate:
+
+```text
+confirmed != materialized                       PASS  (blocked until saved, asserted)
+only selected confirmed items enter this revision PASS (3 of 4 selected)
+source reference remains immutable              PASS  (verified in evidence)
+annotation marks are not baked into the image   PASS  (digest equality, section 18)
+new revision is imported                        PASS  (asserted "Lifecycle: imported")
+imported != approved                            PASS  (asserted "Approval required: yes")
+materialization != approval                     PASS  (no approved successor exists)
+```
+
+The tutorial also shows that the viewer does not switch to the new revision,
+and explains why quietly adopting an unapproved reference would make approval
+meaningless.
+
+## 13. ArrowDown and native-select dependency audit
+
+Every `<select>` renders an empty `Choose…` option first, so from an empty
+form the first press lands on the first vocabulary entry. The runtime intent
+form resets for every mark; the reference requirement form does not. Counts
+that are wrong by one select a different valid value rather than failing,
+which is why each authored result is asserted.
+
+Scenario 2, `observer-v09-runtime-contract`. Every form starts empty:
+
+```text
+steps                            field                             presses  result              frozen vocabulary
+operation-move..-2               Runtime intent operation                2   move                RUNTIME_OPERATIONS: inspect, move, resize, remove, preserve
+direction-right                  Move direction                          1   right               MOVE_DIRECTIONS: right, left, down, up
+category-requested               Intent category                         1   requested           RUNTIME_AUTHORED_CATEGORIES: requested, expected-dependent, protected, preserved
+operation-resize-1..3            Runtime intent operation                3   resize              RUNTIME_OPERATIONS
+resize-wider                     Resize direction                        1   wider               RESIZE_DIRECTIONS: wider, narrower, taller, shorter
+category-expected-1..2           Intent category                         2   expected-dependent  RUNTIME_AUTHORED_CATEGORIES
+mode-required                    Intent expected-dependent mode          1   required            RUNTIME_EXPECTED_DEPENDENT_MODES: required, permitted
+operation-preserve..-5           Runtime intent operation                5   preserve            RUNTIME_OPERATIONS
+category-protected-1..3          Intent category                         3   protected           RUNTIME_AUTHORED_CATEGORIES
+preserve-property-1..2           Preserved property                      2   y                   PRESERVE_PROPERTIES: x, y, width, height
+tolerance-1..2                   Contract tolerance                      2   absolute-px         CONTRACT_TOLERANCE_KINDS: exact, absolute-px, percent
+relationship-choose              Canonical relationship to associate     1   header/navigation   server relationship graph order (see below)
+rel-operation-1..5               Runtime intent operation                5   preserve            RUNTIME_OPERATIONS
+rel-category-1..4                Intent category                         4   preserved           RUNTIME_AUTHORED_CATEGORIES
+remove-op-1..4                   Runtime intent operation                4   remove              RUNTIME_OPERATIONS
+remove-category                  Intent category                         1   requested           RUNTIME_AUTHORED_CATEGORIES
+inspect-op                       Runtime intent operation                1   inspect             RUNTIME_OPERATIONS
+```
+
+Scenario 3, `observer-v09-reference-authoring`:
+
+```text
+steps                            field                    starting value        presses  result                    vocabulary
+property-category-1..3           Requirement category     empty                      3   protected                 REQUIREMENT_CATEGORIES: requested, expected-dependent, protected, preserved
+property-subject                 Requirement subject      empty                      1   region-property           region-property, region-relationship, region-measurement
+property-region-1..2             Requirement region       empty                      2   hero                      region list (see below)
+property-prop-1..3               Region property          empty                      3   width                     REGION_PROPERTIES: x, y, width, height, right, bottom, centerX, centerY
+property-tolerance-1..2          Tolerance                empty                      2   absolute-reference-px     TOLERANCE_KINDS: exact, absolute-reference-px, percent
+relationship-subject-1           Requirement subject      region-property (kept)     1   region-relationship       subject kinds
+relationship-pick                Requirement relationship empty                      1   header/hero overlap       derived reference relationships
+measurement-category-1           Requirement category     protected (kept)           1   preserved                 REQUIREMENT_CATEGORIES
+measurement-subject-1            Requirement subject      region-relationship (kept) 1   region-measurement        subject kinds
+measurement-subject-region-1..2  Subject region           empty (never set)          2   hero                      region list
+measurement-related-1..5         Related region           empty                      5   cta                       region list
+measurement-kind                 Measurement              empty                      1   vertical-gap              REGION_MEASUREMENTS: vertical-gap, horizontal-gap, center-x-delta, center-y-delta, left-edge-delta, right-edge-delta
+```
+
+Scenario 4, `observer-v09-reference-materialization`:
+
+```text
+steps                            field                    starting value        presses  result                    vocabulary
+req-a-cat-1..3                   Requirement category     empty                      3   protected                 REQUIREMENT_CATEGORIES
+req-a-subject                    Requirement subject      empty                      1   region-property           subject kinds
+req-a-region-1..2                Requirement region       empty                      2   hero                      region list
+req-a-prop-1..3                  Region property          empty                      3   width                     REGION_PROPERTIES
+req-a-tol-1..2                   Tolerance                empty                      2   absolute-reference-px     TOLERANCE_KINDS
+req-b-cat                        Requirement category     protected (kept)           1   preserved                 REQUIREMENT_CATEGORIES
+req-b-region-1..5                Requirement region       hero (kept)                5   footer                    region list, corrected from 6 in section 8.1
+req-b-prop                       Region property          width (kept)               1   height                    REGION_PROPERTIES
+```
+
+The region list is `requirementRegionIds`: the reference's own regions in
+import order, `header, hero, sidebar, content, cta, asset, footer`, followed
+by region ids the draft proposes, which adds `promo-band` once the create
+intent exists.
+
+Two of these lists are not frozen vocabularies and deserve to be called out.
+The relationship options come from the canonical relationship graph the server
+derives, in its order. They are deterministic here only because the demo's
+geometry is deterministic, and both scenarios now assert the relationship they
+select, so a change in derivation order fails the run rather than silently
+recording a different requirement.
+
+Maintenance coupling: adding a member to any of these vocabularies, or a
+region to the demo reference, shifts the press counts. The demo README records
+this, and the in-scenario assertions turn a shifted count into a run failure.
+
+## 14. Reference-form retained-value audit
+
+The reference requirement form keeps its values when another mark is selected.
+The runtime intent form resets. Neither behavior was changed.
+
+Scenario 3:
+
+```text
+field                previous value        next expected value    how the scenario handles it
+Requirement category protected             protected              no press; reused for the relationship requirement
+Requirement subject  region-property       region-relationship    one press
+Requirement category protected             preserved              one press
+Requirement subject  region-relationship   region-measurement     one press
+Tolerance kind       absolute-reference-px absolute-reference-px  no press; only the amount is refilled, 4 then 6
+```
+
+Scenario 4:
+
+```text
+field                previous value        next expected value    how the scenario handles it
+Requirement category protected             preserved              one press
+Requirement subject  region-property       region-property        no press; reused
+Requirement region   hero                  footer                 five presses
+Region property      width                 height                 one press
+Tolerance kind       absolute-reference-px absolute-reference-px  no press; amount refilled to 8
+```
+
+This stays deterministic because each run starts from a fresh target and a
+freshly loaded page, the form starts from `EMPTY_REQUIREMENT_FORM`, every
+later value is reached by a fixed number of presses from a known previous
+value, and the resulting structured requirement is asserted before the run
+continues.
+
+## 15. Tutorial timing audit
+
+```text
+scenario                                  total       steps  longest step                    shortest step
+observer-v09-annotation-basics            6 min 24 s     33  arrow-draw 21.4 s               revise-select-point 5.0 s
+observer-v09-runtime-contract            10 min 48 s    106  show-arrow-non-inference 23.8 s preserve-property-2 1.5 s
+observer-v09-reference-authoring          7 min 11 s     64  explain-coordinates 23.6 s      property-category-3 1.5 s
+observer-v09-reference-materialization    4 min 11 s     50  inspect-result 23.8 s           req-b-region-2 1.5 s
+```
+
+Flags, using the audit's own three questions:
+
+1. Accidental dead time: none. No step spent more than 5 seconds beyond its
+   declared reading pause. Longest steps are the deliberate explanation steps,
+   and their duration is the reading pause plus an action of about 50 ms.
+2. Near-zero instructional visibility: none. The shortest step is 1.5 seconds
+   for a single keypress whose narration is one word. This was the defect
+   described in section 8.2 and it is closed.
+3. Timeout-like delay: none. No step approaches an assertion timeout, and no
+   run reported a warning.
+
+Duration was not optimized. Total runtime grew from about 2.5 minutes to about
+28.5 minutes across the four tutorials because the narration is now readable,
+which the task explicitly prefers over speed.
+
+## 16. Screenshot, callout and highlight coverage
+
+```text
+scenario                                  screenshots  conceptual states captured
+observer-v09-annotation-basics                     11  viewer open, observation ready, rectangle drawn,
+                                                       arrow as evidence, five marks, no association,
+                                                       association made, saved, reloaded from disk,
+                                                       revision draft, revision saved
+observer-v09-runtime-contract                      14  start, arrow drawn left, candidate set, structured
+                                                       intent, confirmation withdrawn, resize confirmed,
+                                                       preserve confirmed, relationship associated,
+                                                       relationship confirmed, remove not promotable,
+                                                       inspect informational, promotion list, selected
+                                                       subset, promoted and activated
+observer-v09-reference-authoring                   10  reference open, coordinate distinction, region
+                                                       created, drawn but not bound, region refined,
+                                                       property requirement, relationship requirement,
+                                                       measurement requirement, asset-sensitive, saved
+observer-v09-reference-materialization              7  source reference, four confirmed, confirmed but not
+                                                       materialized, materialization list, three of four
+                                                       selected, materialized result, source still open
+```
+
+Five screenshots were added in this stage because important conceptual
+transitions had a callout but no still image: `arrow-is-evidence`,
+`relationship-associated`, `reference-coordinates`, `drawn-not-bound` and
+`confirmed-not-materialized`. Trivial steps such as individual keypresses
+deliberately have none.
+
+Callouts: 6, 5, 3 and 3 across the four scenarios, 17 in total. Every one
+carries a distinction rather than repeating the narration, for example "The
+arrow points left. The requested direction is right.", "Confirmed is not the
+same as included." and "Imported is not approved. Materializing is not
+approving." No callout repeats its narration verbatim and no step highlights
+every click. The scenarios declare no `highlight`.
+
+Callout occlusion was inspected on the captured screenshots. The callout in
+`explain-no-association` sits over the lower part of the observation image and
+away from the target list the next step clicks; the callout in `save-revision`
+sits at the bottom of the image area. A callout can cover part of the
+screenshot being discussed, which is a judgement only a human watching the
+video can finally make. It is question 3 of the review checklist.
+
+## 17. Canonical Observer evidence verification
+
+These checks were rerun against the final review runs. Prompt 2's results were
+not reused. Evidence was read from each disposable target root with Observer's
+own exported readers (`readVisualAnnotationArtifact`,
+`readExternalReferenceArtifact`, `readPersistentBaselineContract`,
+`readPerChangeContract`), so a structurally invalid artifact would fail here.
+
+Scenario 1, `01-annotation-basics`:
+
+```text
+two annotation artifacts, original and revision            PASS
+canonical reader accepts both, schema 1.0.0                PASS
+both sources are the prepared baseline observation         PASS
+all five mark kinds present in both                        PASS
+revision.supersedesAnnotationId == original.annotationId   PASS
+chain has one root and no dangling parent                  PASS
+original: rectangle -> hero is the only association        PASS
+revision: point -> card1 added, rectangle -> hero kept     PASS
+original written first and not rewritten                   PASS
+```
+
+Scenario 2, `02-runtime-intent-contract`:
+
+```text
+project acceptance baselineArtifact unchanged              PASS  (tutorial-baseline/v09-tutorial-baseline)
+baseline contract still readable and untouched             PASS
+changeArtifact moved off the prepared initial contract     PASS
+active change contract is a normal PerChangeContract       PASS
+exactly two clauses                                        PASS
+  requested:property-increases:hero.x
+  expected-dependent(required):property-increases:sidebar.width
+Remove absent from clauses                                 PASS
+Inspect absent from clauses                                PASS
+clauses cite the saved annotation as supporting evidence   PASS
+annotation still holds six confirmed items, incl. remove
+  and inspect                                              PASS
+relationship intent is header/navigation
+  horizontally-overlapping                                 PASS
+```
+
+Scenario 3, `03-reference-authoring`:
+
+```text
+annotation source is the approved reference                PASS
+seven items, all confirmed                                 PASS
+reference-region intent: create promo-band, refine sidebar PASS
+region-property requirement hero.width protected 4px       PASS
+region-relationship requirement header/hero
+  horizontally-overlapping protected                       PASS
+region-measurement requirement hero -> cta vertical-gap
+  preserved 6px                                            PASS
+informational and asset-sensitive intent recorded          PASS
+neither materialized: approved source still has zero
+  requirements and no new revision exists                  PASS
+```
+
+Scenario 4, `04-reference-materialization`:
+
+```text
+exactly one new reference revision                         PASS
+lifecycle = imported                                       PASS
+supersedes the approved source reference                   PASS
+selected create materialized (promo-band)                  PASS
+selected refine materialized (sidebar rectangle differs)   PASS
+selected requirement materialized (protected hero.width)   PASS
+unselected requirement absent (preserved footer.height)    PASS
+source approved reference unchanged: approved, 7 regions,
+  0 requirements                                           PASS
+no approved successor automatically created                PASS
+```
+
+## 18. Reference image digest verification
+
+```text
+source reference image SHA-256        4bdb94db1096532dd886b7b8bd9ea4018f44ff0e3debb24e92cbf6132123538d
+materialized revision image SHA-256   4bdb94db1096532dd886b7b8bd9ea4018f44ff0e3debb24e92cbf6132123538d
+committed examples/v09-demo PNG       4bdb94db1096532dd886b7b8bd9ea4018f44ff0e3debb24e92cbf6132123538d
+digest recorded by the approved source manifest  4bdb94db...538d
+digest recorded by the new revision manifest     4bdb94db...538d
+```
+
+All five are equal, computed from the actual file bytes rather than trusted
+from the manifests. The new revision reuses the source image exactly, so the
+annotation graphics were not baked into it.
+
+## 19. Demo and source immutability
+
+A SHA-256 digest of all 19 tracked files under `examples/v09-demo/` was taken
+immediately before the four final runs and recomputed immediately after:
+
+```text
+tracked files              19
+digest before              6c845bac0964dd97146306b8789bdb4918fd26ee3af8744ad9b55e1f4f687edb
+digest after               6c845bac0964dd97146306b8789bdb4918fd26ee3af8744ad9b55e1f4f687edb
+demoSourceImmutable        true
+```
+
+`git status --short` was captured before the runs and recompared after. It was
+byte-identical, so no tutorial runtime output appeared in the repository, as
+tracked or untracked content. Every generated artifact lives under the
+external review root.
+
+For honesty about method: an earlier complete set of four runs was executed
+while this stage was still editing scenario narration and documentation, so
+its immutability and status comparison were meaningless and it was discarded
+as a trial. The final runs reported here were executed with no tracked file
+being edited during them, and the report itself was written afterwards.
+
+## 20. npm package inclusion decision
+
+Frozen as specified: for v0.9.0, `examples/v09-demo/` and its tutorial and
+reference assets remain repository-owned development, documentation and
+demonstration source, and are not shipped in the npm package.
+
+The decision needed no package-boundary change. `package.json#files` is
+`dist`, `README.md`, `CHANGELOG.md`, `docs`, `LICENSE`, so the demo was never
+included:
+
+```text
+npm pack --dry-run    0.8.1, no entry under examples/
+```
+
+Regression protection was added to the canonical package-content gate rather
+than to a new framework. `scripts/ci/runPackedV09AnnotationSmoke.mjs` already
+asserts that the installed package contains every compiled v0.9 owner and does
+not contain `scripts/`; it now also fails if an `examples/` directory is
+present in the installed package. That gate runs locally in section 22 and in
+the pre-release readiness matrix on all three platforms.
+
+## 21. Documentation reconciliation
+
+```text
+README.md                        new "Demo and tutorials" section: why the demo
+                                 exists, where it lives, that
+                                 my-dev-kit-lab@0.4.8 records the tutorials, how
+                                 a contributor validates and runs one, that
+                                 output goes to a caller-chosen external
+                                 directory, and that none of it ships in the npm
+                                 package
+docs/PROJECT_OVERVIEW.md         v0.9 product implementation complete, demo and
+                                 tutorial integration complete, release pending a
+                                 fresh exact-candidate readiness run
+docs/CURRENT_STATE.md            new bounded "v0.9 demo and tutorials" section:
+                                 implementation status, the demo-foundation and
+                                 tutorial-integration commits, the lab 0.4.8 tool
+                                 relationship, the four scenarios, the canonical
+                                 evidence proofs, unreleased state, and the next
+                                 required readiness step; the stale claim that
+                                 readiness "has not yet run" was corrected to
+                                 record the historical run and why it is not
+                                 authoritative now
+docs/ROADMAP.md                  concise status note only; v0.9 product design
+                                 untouched
+docs/WORKFLOWS.md                new "Developer tutorial-generation workflow"
+                                 section with the pipeline diagram, the ownership
+                                 boundary and runnable commands
+docs/PROJECT_DESCRIPTION.md      the durable "Future capability - Human visual
+                                 annotation" heading was relabelled as implemented
+                                 in v0.9 and not yet released, following the
+                                 document's existing convention; the capability
+                                 intent text is unchanged
+examples/v09-demo/README.md      exact lab version, review-output guidance, run
+                                 root layout, pacing rules, and the select and
+                                 retained-value maintenance notes
+docs/COMMANDS.md                 unchanged; Observer gained no tutorial command
+                                 and the commands the tutorials use are already
+                                 documented
+docs/PROJECT_MILESTONES.md       unchanged; Milestone 9 already states
+                                 "implemented in the current unreleased
+                                 development state"
+```
+
+Terms are used exactly: implemented, validated locally, tutorial integration
+complete, unreleased, cross-platform readiness pending rerun. No document says
+released, published, `v0.9.0` available, or that a final candidate passed
+cross-platform validation.
+
+## 22. Local release-candidate regression
+
+Run after all documentation and tutorial-quality corrections:
+
+```text
+npm run typecheck     PASS
+npm run lint          PASS
+npm test              PASS  (89 files, 1452 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, 365 files, 0 examples/ entries)
+```
+
+The unit count is one higher than Prompt 2's 1451 because of the new
+reading-time floor test in `tests/unit/v09TutorialScenarios.test.ts`. No test
+was skipped, deleted, weakened or made permissive, and no `.skip`, `.only`,
+`continue-on-error` or `|| true` was introduced.
+
+## 23. Local packed-package and smoke verification
+
+The existing local packed gates were rerun against one exact candidate
+tarball, not a weaker substitute. The tarball, its hash, the consumer installs
+and all temporary state were kept beneath the git-ignored repository-local
+workflow root `.my-dev-kit-workflow/v0.9/tutorial-acceptance/`, with `TEMP` and
+`TMP` redirected there for the smoke processes.
+
+```text
+candidate tarball     .my-dev-kit-workflow/v0.9/tutorial-acceptance/package/dailephd-my-frontend-observer-0.8.1.tgz
+SHA-256               d4fb780120e8b6707946d194f3ce57389b270e36ffaf8e263351377a5154e225
+
+node scripts/ci/runPackedObservationSmoke.mjs <tarball>     PASS
+node scripts/ci/runPackedViewerSmoke.mjs <tarball>          PASS
+node scripts/ci/runPackedV09AnnotationSmoke.mjs <tarball>   PASS
+```
+
+The observation smoke reported aggregate `pass: true`, including every
+installed v0.1 to v0.7 assertion, `packedNoRepoRootLeak` and source
+immutability. The protected and preserved failure values inside its summary
+are the intentional negative-case contract evaluation, not a smoke failure.
+
+The viewer smoke reported `PACKED VIEWER SMOKE: PASS` with viewer protocol
+`1.3.0`, the installed project workflow producing `REVIEW_REQUIRED`, then
+`FAIL`, then `PASS`, alias correctness, traversal rejected, overlay and
+reference views rendered, the service worker registered, `/api/` never cached,
+and the server-down stale-evidence gate holding.
+
+The v0.9 annotation smoke reported `PACKED V0.9 ANNOTATION SMOKE: PASS` with
+`tarballSha256` equal to the candidate hash above and every summary flag true:
+`packageContentsPass`, `publicExportsPass`, `consumerPurityPass`,
+`projectWorkflowPass`, `authoringSessionEnabled`, `runtimeAnnotationPass`,
+`runtimePromotionPass`, `contractInspectionPass`, `referenceAnnotationPass`,
+`referenceMaterializationPass`, `newReferenceInspectionPass` and
+`readOnlyBoundaryPass`. `packageContentsPass` now also covers the new
+packaged-`examples/` assertion.
+
+Package boundary proof from the installed candidate: every required compiled
+v0.9 owner is present, and `examples/` is absent.
+
+## 24. Prior readiness staleness
+
+The prior v0.9 pre-release readiness run
+(`docs/reports/v0.9-pre-release-readiness.md`) passed on Windows, Linux and
+macOS for commit `a78a058`. That candidate did not contain:
+
+```text
+59ae009d  deterministic demo foundation
+6895b303  tutorial integration
+          this stage's scenario, test, package-gate and documentation changes
+```
+
+Therefore:
+
+```text
+prior cross-platform readiness != final-candidate readiness
+PRIOR_CROSS_PLATFORM_READINESS_STILL_AUTHORITATIVE   false
+```
+
+This stage ran local validation only. No Windows, Linux or macOS readiness
+claim is made for the current candidate. Cross-platform readiness must be
+rerun on the exact final commit.
+
+## 25. Human visual review status
+
+```text
+HUMAN_VISUAL_REVIEW: PENDING_USER
+```
+
+Automated acceptance verified structure, timing, manifests, subtitles,
+Markdown, screenshots, scenario content and canonical evidence. It cannot
+judge how the recording looks: whether the synthetic cursor reads clearly,
+whether gestures make visual sense, whether callouts are readable and
+well-placed, and whether each tutorial feels like one lesson. That judgement
+belongs to the user, and `REVIEW_INDEX.md` carries the twelve-question
+checklist.
+
+One practical note for the reviewer: the viewer header displays the local
+evidence root, so every video and screenshot contains a path under the user
+profile. That is correct viewer behavior, but it matters before the media is
+shared.
+
+## 26. Review paths
+
+Review root:
+
+```text
+C:\Users\daile\AppData\Local\Temp\my-frontend-observer-tutorial-review\v0.9
+```
+
+Review index:
+
+```text
+C:\Users\daile\AppData\Local\Temp\my-frontend-observer-tutorial-review\v0.9\REVIEW_INDEX.md
+```
+
+Videos:
+
+```text
+...\v0.9\01-annotation-basics\artifacts\tutorial.webm
+...\v0.9\02-runtime-intent-contract\artifacts\tutorial.webm
+...\v0.9\03-reference-authoring\artifacts\tutorial.webm
+...\v0.9\04-reference-materialization\artifacts\tutorial.webm
+```
+
+Generated Markdown tutorials:
+
+```text
+...\v0.9\01-annotation-basics\artifacts\tutorial.md
+...\v0.9\02-runtime-intent-contract\artifacts\tutorial.md
+...\v0.9\03-reference-authoring\artifacts\tutorial.md
+...\v0.9\04-reference-materialization\artifacts\tutorial.md
+```
+
+Manifests:
+
+```text
+...\v0.9\01-annotation-basics\artifacts\tutorial-manifest.json
+...\v0.9\02-runtime-intent-contract\artifacts\tutorial-manifest.json
+...\v0.9\03-reference-authoring\artifacts\tutorial-manifest.json
+...\v0.9\04-reference-materialization\artifacts\tutorial-manifest.json
+```
+
+Screenshot directories:
+
+```text
+...\v0.9\01-annotation-basics\screenshots
+...\v0.9\02-runtime-intent-contract\screenshots
+...\v0.9\03-reference-authoring\screenshots
+...\v0.9\04-reference-materialization\screenshots
+```
+
+Each `...` is the review root above. Subtitles sit beside each video as
+`tutorial.srt` and `tutorial.vtt`. Nothing in this bundle is committed.
+
+## 27. Scope audit
+
+All of the following are `false`:
+
+```text
+Observer tutorial runtime implemented        false
+Observer Playwright recorder added           false
+Observer subtitle writer added               false
+Observer tutorial-manifest schema added      false
+Observer cursor implementation added         false
+Observer callout implementation added        false
+annotation semantics changed                 false
+contract semantics changed                   false
+reference semantics changed                  false
+approval semantics changed                   false
+project acceptance semantics changed         false
+my-dev-kit-lab modified                      false
+new dependency added                         false
+package version changed                      false
+v0.9 marked released                         false
+generated tutorial media committed           false
+examples/v09-demo included in npm package    false
+old cross-platform readiness represented as current   false
+```
+
+`src/` and `viewer/src/` are untouched by this stage. `package.json` and
+`package-lock.json` are unchanged, so `DEPENDENCY_CHANGED` is false. The
+intentional `skip-worktree` flag on
+`docs/reports/v0.9-architecture-retrieval.md` is preserved.
+
+## 28. Changed files
+
+```text
+examples/v09-demo/tutorials/01-annotation-basics.json      pauses, narration, revision steps, screenshot
+examples/v09-demo/tutorials/02-runtime-intent-contract.json pauses, narration, relationship assertion, screenshot
+examples/v09-demo/tutorials/03-reference-authoring.json    pauses, narration, relationship assertion, screenshots
+examples/v09-demo/tutorials/04-reference-materialization.json pauses, narration, footer correction and assertions, screenshot
+examples/v09-demo/README.md                                exact lab version, review guidance, pacing, select notes
+tests/unit/v09TutorialScenarios.test.ts                    reading-time floor regression test
+scripts/ci/runPackedV09AnnotationSmoke.mjs                 packaged-examples regression assertion
+README.md                                                  Demo and tutorials section
+docs/PROJECT_OVERVIEW.md                                   v0.9 demo/tutorial status
+docs/CURRENT_STATE.md                                      v0.9 demo and tutorials section, readiness correction
+docs/ROADMAP.md                                            v0.9 status note
+docs/WORKFLOWS.md                                          developer tutorial-generation workflow
+docs/PROJECT_DESCRIPTION.md                                annotation capability relabelled as implemented
+docs/reports/v0.9-tutorial-end-to-end-acceptance.md        this report
+```
+
+Generated paths, all outside the repository or git-ignored:
+
+```text
+C:\Users\daile\AppData\Local\Temp\my-frontend-observer-tutorial-review\v0.9\    review bundle
+.my-dev-kit-workflow/v0.9/tutorial-acceptance/                                  packed candidate, consumers, temp
+```
+
+## 29. Exact next step
+
+Do not release. In order:
+
+1. The user watches the four WebM tutorials using `REVIEW_INDEX.md` and
+   answers its twelve questions.
+2. If the user approves, rerun the exact-candidate Windows, Linux and macOS
+   v0.9 pre-release readiness workflow on the new final commit. The prior run
+   is not a substitute.
+3. If that readiness passes, begin controlled v0.9.0 release preparation as a
+   separate stage.
+4. Only after release preparation passes, publish, tag and release through the
+   existing controlled release workflow.
+
+If review finds only presentation issues, correct narration, timing, callouts
+or screenshots within the tutorial-quality boundary and regenerate the review
+bundle. Do not reopen v0.9 product semantics.