Tranche C — the close made honest · design true · the engine dogfooded

.changeset/tranche-c.md

@@ -0,0 +1,50 @@
+---
+"@mkbabb/keyframes.js": major
+---
+
+Tranche C — the close made honest, the design system made true, the engine dogfooded.
+
+This release ships alongside the Tranche B engine transposition (the
+`tranche-b-3-1-0` changeset, cut but never published — folded here so one
+provenance-signed publish ships both). C's published-library surface is the
+engine residuals; the design-system + dogfood + integrity work (W1–W3) lands in
+the demo + CI gates and does not change the published API.
+
+**The engine unification, completed to its edges (W4).**
+
+- **One generation-guarded loop core.** `play`/`drive`/`loop` fold into a single
+  `_run` frame-scheduler; `drive` inherits the `_gen` restart guard `loop` had,
+  so a `stop()`+restart mid-frame can no longer spawn a second rAF chain (the
+  unguarded double-schedule class is now structurally impossible).
+- **One canonical step: `tickDt(dt: ms): number` on every stepper.** The
+  frame-dependent no-arg `SmoothProgress.tick()` is removed and the
+  seconds-taking `SpringProgress.tick(seconds)` is demoted to a private
+  internal — no public stepper method takes seconds or means four different
+  things. `Tickable.tickDt` is typed `: number` (was `: void`). **Breaking:** if
+  you stepped `SmoothProgress`/`SpringProgress` manually, call `tickDt(ms)`.
+- **Fail-explicit option contract is now total.** `setColorSpace` /
+  `setHueMethod` join the `parseOption` seam — a malformed PRESENT value throws
+  `AnimationOptionError` (genuine omission still defaults), closing the last two
+  setters that silently accepted invalid input. **Breaking** for callers that
+  relied on an invalid value being silently accepted (e.g. `colorSpace: "srgb"`
+  — value.js's sRGB-family space is `"rgb"`).
+- **The default easing's compositor path: verified, then withheld.** A single
+  `cubic-bezier()` cannot faithfully reproduce the piecewise Penner
+  `easeInOutCubic` (proven: the best symmetric fit floors at ~0.0208 drift,
+  above the 1e-2 no-visible-drift tolerance), so the default carries no `.css`
+  twin and stays rAF-only — faithful by omission. A standing test reds if a
+  faithful twin is ever found or an unfaithful one shipped.
+- **`Timeline._advance` deduplicated** to one `setTarget` + one branch.
+
+**The boundary + release gates hardened.** `proof:boundary` closes its residual
+false-negative classes (a live bare side-effect import, a `@mkbabb/value.js/...`
+subpath specifier, a direct `export const` light export now each redden the
+gate); `rolldown` is declared as the gate's load-bearing dependency; the CI demo
+gate pins the glass-ui sibling to a tag (no moving-HEAD reproducibility hole).
+
+SemVer note: the tier is **major** because the combined B+C release changes
+behavior visible to a 3.0.0 consumer (fail-explicit setters throw where 3.0.0
+silently accepted; the canonical `tickDt` step). If the team treats the
+unpublished B 3.1.0 light-engine surface as the baseline (those steppers were
+never published), the change is additive — the publish owner finalizes the tier
+at `changeset version`.

.github/workflows/ci.yml

@@ -11,10 +11,18 @@
 #     proof:boundary — bundle EVERY light barrel entry and assert 0 value.js +
 #                0 static engine edge per entry, the heavy engine dynamic-only,
 #                no dormant static specifier (A inv α, widened in B.W2)
-#   `@mkbabb/glass-ui` is an OPTIONAL `file:../glass-ui` dependency; a clean
-#   runner has no sibling checkout, so `npm ci` cleanly SKIPS it
-#   (`optional: true`) — verified by the /tmp clean-runner archive run. The
-#   library gate therefore runs glass-ui-free.
+#   `@mkbabb/glass-ui` is an OPTIONAL `file:../glass-ui` dependency. On a clean
+#   runner the sibling is absent, so `npm ci` links `node_modules/@mkbabb/glass-ui
+#   -> ../../../glass-ui` whose target is MISSING: npm tolerates the dangling
+#   optional link non-fatally (exit 0), and the library graph never dereferences
+#   it (check:lib / build:lib / proof:boundary / test all green with the link
+#   dangling — verified by the /tmp clean-runner archive run). The library gate
+#   therefore runs glass-ui-free. NB: this is disposition (b) — the lockfile
+#   carries the optional `../glass-ui` node (`grep -c '"../glass-ui"\|@mkbabb/
+#   glass-ui' package-lock.json` = 5). A genuinely glass-ui-absent lockfile
+#   (disposition a) is unreachable without deleting the `optionalDependencies`
+#   declaration, which removes the `file:../glass-ui` link the demo dev install
+#   needs; (b) is the spec's reserved contingency, stated honestly here (C.W1 S5).
 #
 #   demo-smoke (DEMO) — the demo legitimately needs glass-ui, so this is a
 #   SEPARATE job that installs the published package + a browser and asserts
@@ -49,14 +57,37 @@ jobs:
               run: npm run check:lib
             - name: build (library)
               run: npm run build:lib
-            - name: dts artefact is real (not a 12-byte empty stub)
+            - name: dts artefact is real + the 15 public runtime symbols roll up
               run: |
                   test -f dist/keyframes.d.ts
                   bytes=$(wc -c < dist/keyframes.d.ts)
                   echo "dist/keyframes.d.ts = $bytes bytes"
                   test "$bytes" -gt 10000
-                  grep -q "class Animation" dist/keyframes.d.ts
-                  grep -q "loadAnimationEngine" dist/keyframes.d.ts
+                  # The 15 PUBLIC runtime symbols the library ships: the 14 light
+                  # barrel exports + the loadAnimationEngine dynamic accessor. Each
+                  # must roll up to the dts as a PRECISE `export declare …` anchor
+                  # — NOT a loose substring. The former `grep "class Animation"`
+                  # matched the `Animation_2` collision-rename / `AnimationGroup` /
+                  # `AnimationOptionError`, proving none of them; a dropped symbol
+                  # passed green. A symbol ships either directly
+                  # (`export declare class|function|const NAME…`) or, when
+                  # API-Extractor must collision-rename it (`ScrollTimeline_2`), as
+                  # an `export { <rename> as NAME }` aliased re-export — either proves it.
+                  SYMS="NumericAnimation SmoothProgress SpringProgress springLinearStops springTimingFunction ElementMorph Timeline ScrollTimeline ManualTimeline RAFPlayback resolveEasing toEasing AnimationOptionError UnknownEasingError loadAnimationEngine"
+                  missing=""
+                  for sym in $SYMS; do
+                    if grep -qE "^export declare (abstract class|class|function|const|enum) ${sym}[<(:; ]" dist/keyframes.d.ts \
+                       || grep -qE "^export \{ [A-Za-z0-9_]+ as ${sym} \}" dist/keyframes.d.ts; then
+                      :
+                    else
+                      missing="$missing $sym"
+                    fi
+                  done
+                  if [ -n "$missing" ]; then
+                    echo "dts MISSING public runtime symbol declaration(s):$missing"
+                    exit 1
+                  fi
+                  echo "dts public-symbol set complete: 15/15"
             - name: test
               run: npm test -- --run
             - name: proof:boundary (value.js static/dynamic boundary gate, all light entries)
@@ -81,16 +112,22 @@ jobs:
             # sibling (it consumes keyframes/value.js from the REGISTRY — no
             # circular sibling dep), so the demo build resolves it exactly as a
             # dev machine does.
-            - name: check out + build the glass-ui sibling (file:../glass-ui)
+            # PINNED to a known-good glass-ui tag (NOT the default branch): a
+            # foreign repo's moving HEAD is a reproducibility hole — a glass-ui
+            # main break (its own build, a peer/dep bump, a renamed build
+            # script) would red keyframes CI for a change with zero keyframes
+            # diff. The pin advances via an explicit chore(ci) bump — the same
+            # routed-through-a-PR discipline the value.js dep-order note keeps.
+            - name: check out + build the glass-ui sibling (file:../glass-ui, pinned)
               run: |
-                  git clone --depth 1 https://github.com/mkbabb/glass-ui.git "$GITHUB_WORKSPACE/../glass-ui"
+                  git clone --depth 1 --branch v3.2.0 https://github.com/mkbabb/glass-ui.git "$GITHUB_WORKSPACE/../glass-ui"
                   cd "$GITHUB_WORKSPACE/../glass-ui"
                   npm ci
                   npm run build
             - name: npm ci (picks up the built file:../glass-ui)
               run: npm ci
-            - name: install playwright (demo-gate only; --no-save keeps the lib posture)
-              run: npm i --no-save @playwright/test
+            - name: install playwright + lighthouse (demo-gate only; --no-save keeps the lib posture)
+              run: npm i --no-save @playwright/test lighthouse
             - name: install chromium
               run: npx playwright install --with-deps chromium
             - name: build the demo (gh-pages)
@@ -101,3 +138,47 @@ jobs:
               run: node scripts/occlusion-gate.mjs
               env:
                   KF_REQUIRE_BROWSER: "1"
+            # C.W1 S6 — the lighthouse A11y=100 (demo-owned) + SEO≥90 hard gate
+            # W5 deferred. Drives each scene into its OPEN-panel editing state
+            # (the product as USED, not the splash) and scores a11y+seo. HARD on
+            # any a11y audit OUTSIDE the two named allowance buckets
+            # (bucket-glassui → ASK-3 adoption; bucket-w2 → W2 close), on any
+            # regression of an already-passing audit, and on SEO<90. The buckets
+            # are an explicit manifest in the script — not a silent exemption —
+            # and the gate tightens by deletion as those closes land. lighthouse
+            # resolves from the repo root (the `npm i --no-save lighthouse` above).
+            - name: A11y (demo-owned) = 100 + SEO ≥ 90 — open-panel lighthouse gate
+              run: node scripts/lighthouse-gate.mjs
+              env:
+                  KF_REQUIRE_BROWSER: "1"
+            # C.W1 S4 — the LoAF >50ms-trace gate: the dev-only LoAF observer's
+            # REAL 2nd consumer (closing the LoAF + >50ms-trace chronics + the
+            # overfitting violation as ONE perf-evidence subsystem). The gate
+            # launches Chromium against a served bench page that mounts the
+            # observer EXPLICITLY (the prod demo stays observer-free), drives a
+            # large AnimationGroup composite, reads `window.__kfLoaf`, and FAILS
+            # on any >50ms main-thread block. It needs the LIBRARY build
+            # (`dist/keyframes.js`) the bench page imports — so build:lib runs
+            # here LAST (its `dist/` empty no longer disturbs the gh-pages gates
+            # above, which have all run). Chromium resolves from the repo
+            # (`npm i --no-save @playwright/test` above); KF_REQUIRE_BROWSER
+            # turns the playwright-absent skip into a hard CI failure.
+            - name: build the library (dist/keyframes.js for the bench page)
+              run: npm run build:lib
+            # KF_LOAF_COUNT runner-calibration: the strict 50ms LoAF threshold is
+            # a real-user-HARDWARE Web-Vitals standard. The shared GitHub VM runs
+            # ~6× slower than real hardware, so the full 200-cell composite's loop
+            # legitimately blocks ~130ms there (local: 20ms) with NO regression —
+            # a single absolute threshold cannot separate that from the bite-test's
+            # 120ms injected block. So CI runs a runner-calibrated 48-cell composite
+            # (still crosses the YIELD_BATCH=32 boundary → exercises the yield path;
+            # loop worst-frame ~30ms, comfortably under the UNCHANGED strict 50ms,
+            # and the 120ms inject still reddens). The full 200-cell yield-STRESS is
+            # the local/dedicated `npm run bench` authority (real hardware). The
+            # threshold itself is NOT relaxed — only the stress size is sized to the
+            # runner (cf. tranche-B 5fa76b4: CI perf SMOKE robust, real gate local).
+            - name: LoAF >50ms-trace gate (observer's 2nd consumer)
+              run: npm run bench -- --run bench/playwright.bench.ts
+              env:
+                  KF_REQUIRE_BROWSER: "1"
+                  KF_LOAF_COUNT: "48"