@unrulysystems/native-motion-conformance 0.1.0-alpha.0

package/src/scenarios/layout-identity.ts

@@ -0,0 +1,264 @@
+// L2 (specs/L2-BUILD-PACKET.md) Altitude-2 conformance scenarios — the shared layout-identity
+// registry laws (REQ-LAYOUT-002/003/015 as inherited by the ratified registry seam). Authored ONCE,
+// engine-agnostic, ADDITIVE to the suite (the existing scenarios' semantics are untouched): each
+// drives the reference registry on a fake host (injectable clock + MotionGraph, scripted rects, no
+// driver/React/Fabric) and asserts a registry law — sole-static, lead-departs-from-predecessor,
+// both-holders coincidence on ONE shared flight, settle-at-lead-layout, crossfade conservation,
+// exit/resume + releasable, fail-loud holder discipline. `layout-identity.cross-engine-parity` is
+// external-evidence-only: recorded `unassertable` here, asserted at the named Altitude-5 Chromium gate
+// (LAYOUT_IDENTITY_PARITY_COUNTERPART → layout-identity-parity.e2e.ts) — never flipped to an in-suite pass.
+
+import {
+  EPSILON_POS,
+  ManualClock,
+  ManualScheduler,
+  createLayoutIdentityRegistry,
+  createMotionGraph,
+  toWindowSpaceRect,
+  type LayoutIdentityRegistry,
+  type Rect,
+  type Transform,
+} from '@unrulysystems/native-motion-core'
+import type { ScenarioResult, Verdict } from '../runner'
+
+const FAKE_ENGINE = 'fake-host'
+
+const CARD = toWindowSpaceRect({ x: 20, y: 400, width: 200, height: 150 })
+const HERO = toWindowSpaceRect({ x: 0, y: 0, width: 390, height: 500 })
+
+interface Outcome {
+  readonly verdict: Verdict
+  readonly detail: string
+}
+const pass = (detail: string): Outcome => ({ verdict: 'pass', detail })
+const fail = (detail: string): Outcome => ({ verdict: 'fail', detail })
+const unassertable = (detail: string): Outcome => ({ verdict: 'unassertable', detail })
+
+function harness(): { scheduler: ManualScheduler; registry: LayoutIdentityRegistry } {
+  const clock = new ManualClock(0)
+  const scheduler = new ManualScheduler(clock)
+  const graph = createMotionGraph({ clock, scheduler })
+  return { scheduler, registry: createLayoutIdentityRegistry({ graph }) }
+}
+
+// The rect a holder paints this frame: its layout rect under its read transform (top-left anchored).
+function painted(layout: Rect, t: Transform): Rect {
+  return {
+    x: layout.x + t.translateX,
+    y: layout.y + t.translateY,
+    width: layout.width * t.scaleX,
+    height: layout.height * t.scaleY,
+  }
+}
+
+function rectClose(a: Rect, b: Rect, eps = EPSILON_POS): boolean {
+  return (
+    Math.abs(a.x - b.x) < eps &&
+    Math.abs(a.y - b.y) < eps &&
+    Math.abs(a.width - b.width) < eps &&
+    Math.abs(a.height - b.height) < eps
+  )
+}
+
+function settleId(
+  scheduler: ManualScheduler,
+  registry: LayoutIdentityRegistry,
+  id: string,
+): number {
+  let frames = 0
+  while (!registry.isSettled(id) && frames < 2000) {
+    scheduler.frame(16.67)
+    frames += 1
+  }
+  return frames
+}
+
+export interface LayoutIdentityScenario {
+  readonly id: string
+  readonly requirements: readonly string[]
+  readonly assert: () => Outcome
+}
+
+export const LAYOUT_IDENTITY_SCENARIOS: readonly LayoutIdentityScenario[] = [
+  {
+    id: 'layout-identity.sole-static',
+    requirements: ['REQ-LAYOUT-003'],
+    assert() {
+      const { registry } = harness()
+      const { role } = registry.enter('card', 'a', CARD)
+      const read = registry.read('card', 'a')
+      if (role !== 'sole') return fail(`first enter role '${role}', want 'sole'`)
+      if (read.opacity !== 1) return fail(`sole opacity ${read.opacity}, want 1`)
+      if (!rectClose(painted(CARD, read.transform), CARD))
+        return fail('sole holder not static at its layout')
+      if (!registry.isSettled('card')) return fail('sole holder reports unsettled')
+      return pass('sole: static at own layout, opacity 1, settled')
+    },
+  },
+  {
+    id: 'layout-identity.lead-departs-from-predecessor',
+    requirements: ['REQ-LAYOUT-003', 'REQ-LAYOUT-015'],
+    assert() {
+      const { scheduler, registry } = harness()
+      registry.enter('card', 'a', CARD)
+      const { role } = registry.enter('card', 'b', HERO)
+      scheduler.frame(0)
+      const lead = registry.read('card', 'b')
+      if (role !== 'lead') return fail(`second enter role '${role}', want 'lead'`)
+      if (!rectClose(painted(HERO, lead.transform), CARD)) {
+        return fail('frame 0 of the flight does not paint at the predecessor rect (FLIP inversion)')
+      }
+      if (!registry.zLifted('card', 'b')) return fail('lead not z-lifted mid-flight')
+      return pass('lead departs from the predecessor rect, z-lifted')
+    },
+  },
+  {
+    id: 'layout-identity.coincidence-one-shared-flight',
+    requirements: ['REQ-LAYOUT-015'],
+    assert() {
+      const { scheduler, registry } = harness()
+      registry.enter('card', 'a', CARD)
+      registry.enter('card', 'b', HERO)
+      for (let i = 0; i < 12; i++) scheduler.frame(16.67)
+      const leadPainted = painted(HERO, registry.read('card', 'b').transform)
+      const trailingPainted = painted(CARD, registry.read('card', 'a').transform)
+      if (!rectClose(leadPainted, trailingPainted)) {
+        return fail('holders paint different rects mid-flight — not one shared flight')
+      }
+      if (rectClose(leadPainted, CARD) || rectClose(leadPainted, HERO)) {
+        return fail('shared rect sits at an endpoint mid-flight')
+      }
+      return pass('both holders coincide on one shared visual rect mid-flight')
+    },
+  },
+  {
+    id: 'layout-identity.settles-at-lead-layout',
+    requirements: ['REQ-LAYOUT-002'],
+    assert() {
+      const { scheduler, registry } = harness()
+      registry.enter('card', 'a', CARD)
+      registry.enter('card', 'b', HERO)
+      const frames = settleId(scheduler, registry, 'card')
+      if (frames >= 2000) return fail('flight never settled')
+      const lead = registry.read('card', 'b')
+      if (!rectClose(painted(HERO, lead.transform), HERO))
+        return fail('lead did not settle at its host layout')
+      if (lead.opacity !== 1) return fail(`settled lead opacity ${lead.opacity}, want exactly 1`)
+      if (registry.read('card', 'a').opacity !== 0)
+        return fail('settled trailing opacity not exactly 0')
+      if (registry.zLifted('card', 'b')) return fail('z-lift persists after settle')
+      return pass(`settled at host layout in ${frames} frames; exact opacity endpoints`)
+    },
+  },
+  {
+    id: 'layout-identity.crossfade-conservation',
+    requirements: ['REQ-LAYOUT-003'],
+    assert() {
+      const { scheduler, registry } = harness()
+      registry.enter('card', 'a', CARD)
+      registry.enter('card', 'b', HERO)
+      for (let i = 0; i < 10; i++) scheduler.frame(16.67)
+      const lead = registry.read('card', 'b').opacity
+      const trailing = registry.read('card', 'a').opacity
+      if (!(lead > 0 && lead < 1 && trailing > 0 && trailing < 1)) {
+        return fail(`mid-flight opacities at extremes (lead ${lead}, trailing ${trailing})`)
+      }
+      if (Math.abs(lead + trailing - 1) > 1e-9) {
+        return fail(`opacities not complementary (${lead} + ${trailing})`)
+      }
+      return pass('mid-flight crossfade is complementary and never both-extreme')
+    },
+  },
+  {
+    id: 'layout-identity.exit-reverses-and-releases',
+    requirements: ['REQ-LAYOUT-002', 'REQ-LAYOUT-003'],
+    assert() {
+      const { scheduler, registry } = harness()
+      registry.enter('card', 'a', CARD)
+      registry.enter('card', 'b', HERO)
+      settleId(scheduler, registry, 'card')
+      registry.leave('card', 'b')
+      if (registry.releasable('card', 'b'))
+        return fail('leaver releasable before the reverse flight settled')
+      scheduler.frame(0)
+      const resumed = registry.read('card', 'a')
+      if (!rectClose(painted(CARD, resumed.transform), HERO)) {
+        return fail('reverse flight does not depart from the rect being returned from')
+      }
+      settleId(scheduler, registry, 'card')
+      if (!registry.releasable('card', 'b')) return fail('leaver not releasable after settle')
+      const settled = registry.read('card', 'a')
+      if (!rectClose(painted(CARD, settled.transform), CARD) || settled.opacity !== 1) {
+        return fail('resumed holder did not settle at its own layout at opacity 1')
+      }
+      return pass(
+        'lead exit reverses the flight; leaver releasable at settle; resume lands at host layout',
+      )
+    },
+  },
+  {
+    id: 'layout-identity.fail-loud-holders',
+    requirements: ['REQ-LAYOUT-003'],
+    assert() {
+      const { registry } = harness()
+      registry.enter('card', 'a', CARD)
+      const probes: string[] = []
+      const expectThrow = (name: string, run: () => void): void => {
+        try {
+          run()
+          probes.push(`${name}: did not throw`)
+        } catch (e) {
+          if (!(e instanceof Error) || !e.message.includes('card')) {
+            probes.push(`${name}: error does not name the id`)
+          }
+        }
+      }
+      const expectWindowSpaceThrow = (name: string, run: () => void): void => {
+        try {
+          run()
+          probes.push(`${name}: did not throw`)
+        } catch (e) {
+          if (!(e instanceof Error) || !e.message.includes('window-space rect')) {
+            probes.push(`${name}: error does not name the branding boundary`)
+          }
+        }
+      }
+      expectThrow('double-enter', () => registry.enter('card', 'a', CARD))
+      expectThrow('ghost-read', () => registry.read('card', 'ghost'))
+      expectThrow('ghost-leave', () => registry.leave('card', 'ghost'))
+      expectWindowSpaceThrow('malformed-rect', () =>
+        toWindowSpaceRect({ x: Number.NaN, y: 0, width: 1, height: 1 }),
+      )
+      if (probes.length > 0) return fail(probes.join(' | '))
+      return pass(
+        'double-enter and ghost operations throw naming the id; malformed rects throw at the branding boundary',
+      )
+    },
+  },
+  {
+    id: 'layout-identity.cross-engine-parity',
+    requirements: ['REQ-LAYOUT-003', 'REQ-CONFORM-002'],
+    assert() {
+      // EXECUTING COUNTERPART registered (L4, REQ-CONFORM-011): the Altitude-5 Chromium gate
+      // asserts this registry's crossfade laws against real motion/react —
+      // `packages/native-motion-web/e2e/layout-identity-parity.e2e.ts`, declared as
+      // LAYOUT_IDENTITY_PARITY_COUNTERPART in parity.ts. Unassertable HERE only because the
+      // fake host has no second engine — a routing directive, never a skip.
+      return unassertable(
+        'asserted at alt5-playwright-chromium: layout-identity-parity.e2e.ts (registered ' +
+          'LAYOUT_IDENTITY_PARITY_COUNTERPART) runs the crossfade laws against real motion/react',
+      )
+    },
+  },
+]
+
+export function runLayoutIdentityScenario(scenario: LayoutIdentityScenario): ScenarioResult {
+  const outcome = scenario.assert()
+  return {
+    id: scenario.id,
+    engine: FAKE_ENGINE,
+    verdict: outcome.verdict,
+    readings: [],
+    detail: outcome.detail,
+  }
+}

package/src/scenarios/layout.ts

@@ -0,0 +1,258 @@
+// SPEC-LAYOUT §4a/§4b Altitude-2 conformance scenarios (REQ-LAYOUT-002/011/012/013/016/018/019 + REQ-
+// LAYOUT-003). Authored ONCE, engine-agnostic: each drives the reference projection engine on a fake host
+// (scripted before/after rects + injectable null, injectable clock + MotionGraph, no driver/React/Fabric/
+// simulator) and asserts a projection law — ends-at-host-layout, parent-relative coherence, child-undistorted
+// under scale, null-fails-closed, retarget C0/C1, stale-identity fail-closed, settle-gating, and the layoutId
+// two-position geometry. At Milestone 1 the fake host is the only engine; the IDENTICAL scenarios re-run
+// against motion/react (web) + the native runtime at Milestone 2. `layout.cross-engine-parity` is
+// external-evidence-only: recorded `unassertable` here (no in-process layout engine), asserted at the named
+// Playwright Chromium gate (LAYOUT_PARITY_COUNTERPART → layout.e2e.ts) — never flipped to an in-suite pass.
+
+import {
+  EPSILON_POS,
+  EPSILON_SCALE,
+  EPSILON_VEL,
+  ManualClock,
+  ManualScheduler,
+  type MotionGraph,
+  type Rect,
+  applyTransformToRect,
+  composeParentRelative,
+  counterScale,
+  createMeasureTracker,
+  createMotionGraph,
+  createProjectionSession,
+  isIdentity,
+  projectAtProgress,
+} from '@unrulysystems/native-motion-core'
+import type { ScenarioResult, Verdict } from '../runner'
+
+const FAKE_ENGINE = 'fake-host'
+
+const BEFORE: Rect = { x: 0, y: 0, width: 100, height: 100 }
+const AFTER: Rect = { x: 200, y: 300, width: 200, height: 50 }
+const AFTER2: Rect = { x: 400, y: 100, width: 80, height: 80 }
+
+interface Outcome {
+  readonly verdict: Verdict
+  readonly detail: string
+}
+const pass = (detail: string): Outcome => ({ verdict: 'pass', detail })
+const fail = (detail: string): Outcome => ({ verdict: 'fail', detail })
+const unassertable = (detail: string): Outcome => ({ verdict: 'unassertable', detail })
+
+function harness(): {
+  scheduler: ManualScheduler
+  graph: MotionGraph
+  session: ReturnType<typeof createProjectionSession>
+} {
+  const clock = new ManualClock(0)
+  const scheduler = new ManualScheduler(clock)
+  const graph = createMotionGraph({ clock, scheduler })
+  const session = createProjectionSession({ graph })
+  return { scheduler, graph, session }
+}
+
+function rectClose(a: Rect, b: Rect, eps = EPSILON_POS): boolean {
+  return (
+    Math.abs(a.x - b.x) < eps &&
+    Math.abs(a.y - b.y) < eps &&
+    Math.abs(a.width - b.width) < eps &&
+    Math.abs(a.height - b.height) < eps
+  )
+}
+
+export interface LayoutScenario {
+  readonly id: string
+  readonly requirements: readonly string[]
+  readonly assert: () => Outcome
+}
+
+export const LAYOUT_SCENARIOS: readonly LayoutScenario[] = [
+  {
+    id: 'layout.ends-at-host-layout',
+    requirements: ['REQ-LAYOUT-002'],
+    assert() {
+      const { scheduler, session } = harness()
+      session.begin('el', BEFORE, AFTER)
+      scheduler.frames(400, 16.67)
+      const v = session.visualRect()
+      if (v === null) return fail('visualRect null after settle')
+      if (!rectClose(v, AFTER)) return fail(`landed at ${JSON.stringify(v)}, expected AFTER`)
+      if (!isIdentity(session.transform())) return fail('transform not identity at settle')
+      if (!session.isSettled()) return fail('not settled')
+      return pass('projection lands the element on its host-computed layout (identity at settle)')
+    },
+  },
+  {
+    id: 'layout.parent-relative',
+    requirements: ['REQ-LAYOUT-012'],
+    assert() {
+      const pBefore: Rect = { x: 0, y: 0, width: 100, height: 100 }
+      const pAfter: Rect = { x: 300, y: 400, width: 200, height: 50 }
+      const childLocal: Rect = { x: 40, y: 10, width: 20, height: 20 }
+      const fracX = childLocal.x / pAfter.width
+      for (const p of [0, 0.25, 0.5, 0.75, 1]) {
+        const parentVisual = applyTransformToRect(projectAtProgress(pBefore, pAfter, p), pAfter)
+        const child = composeParentRelative(pBefore, pAfter, childLocal, p)
+        if (Math.abs((child.x - parentVisual.x) / parentVisual.width - fracX) > 1e-6) {
+          return fail(`child fractional position drifted at p=${p}`)
+        }
+      }
+      const childAbsX = pAfter.x + childLocal.x
+      if (
+        Math.abs(composeParentRelative(pBefore, pAfter, childLocal, 0).x - childAbsX) < EPSILON_POS
+      ) {
+        return fail('child stranded at its after origin at p=0')
+      }
+      return pass(
+        'a nested child tracks the parent projection frame, never stranded at the after origin',
+      )
+    },
+  },
+  {
+    id: 'layout.child-undistorted',
+    requirements: ['REQ-LAYOUT-013'],
+    assert() {
+      const gBefore: Rect = { x: 0, y: 0, width: 100, height: 100 }
+      const gAfter: Rect = { x: 0, y: 0, width: 200, height: 200 } // 2.0 parent scale
+      const intrinsic = 20
+      for (const p of [0, 0.25, 0.5, 0.75, 1]) {
+        const tp = projectAtProgress(gBefore, gAfter, p)
+        const rendered = intrinsic * (tp.scaleX * counterScale(tp).scaleX)
+        if (Math.abs(rendered - intrinsic) / intrinsic > EPSILON_SCALE) {
+          return fail(`counter-scaled child distorted at p=${p}: rendered ${rendered}`)
+        }
+      }
+      return pass(
+        'a counter-scaled child stays within 1% of intrinsic size under a 2x parent scale',
+      )
+    },
+  },
+  {
+    id: 'layout.null-fails-closed',
+    requirements: ['REQ-LAYOUT-011', 'REQ-LAYOUT-019'],
+    assert() {
+      const { scheduler, session } = harness()
+      session.begin('el', null, AFTER)
+      if (session.measured()) return fail('measured despite a null read')
+      if (!isIdentity(session.transform())) return fail('transform not identity when unmeasured')
+      if (session.isSettled()) return fail('settled while unmeasured')
+      scheduler.frames(10, 16.67)
+      if (!isIdentity(session.transform())) return fail('unmeasured element moved on clock advance')
+      session.begin('el', BEFORE, AFTER) // next epoch, valid read
+      scheduler.frames(400, 16.67)
+      if (!session.isSettled()) return fail('did not resume + settle after a valid read')
+      return pass('a null read fails closed to identity + unsettled; a later valid read resumes')
+    },
+  },
+  {
+    id: 'layout.retarget-continuity',
+    requirements: ['REQ-LAYOUT-018'],
+    assert() {
+      const { scheduler, session } = harness()
+      session.begin('el', BEFORE, AFTER)
+      scheduler.frames(5, 16.67)
+      const before = session.visualRect()
+      if (before === null) return fail('null mid-flight')
+      const vxMinus = session.velocity().x
+      if (Math.abs(vxMinus) <= EPSILON_VEL) return fail('not moving mid-flight (vacuous)')
+      session.retarget(AFTER2)
+      const after = session.visualRect()
+      if (after === null) return fail('null after retarget')
+      if (Math.abs(after.x - before.x) >= EPSILON_POS) return fail('C0 broken — position snapped')
+      if (Math.abs(session.velocity().x - vxMinus) >= EPSILON_VEL)
+        return fail('C1 broken — velocity zeroed')
+      scheduler.frames(400, 16.67)
+      const v = session.visualRect()
+      if (v === null || !rectClose(v, AFTER2)) return fail('did not end at the new host layout')
+      return pass(
+        'retarget continues from the live position + velocity, ends at the new layout (C0/C1)',
+      )
+    },
+  },
+  {
+    id: 'layout.stale-identity',
+    requirements: ['REQ-LAYOUT-016'],
+    assert() {
+      const t = createMeasureTracker('el-1')
+      t.attach()
+      t.beginEpoch(1)
+      if (!t.measure({ measure: () => AFTER }).measured) return fail('did not measure a valid read')
+      if (!t.validate('el-1')) return fail('a matching live token was rejected')
+      if (t.validate('el-2')) return fail('a stale token was accepted')
+      if (t.current().measured) return fail('a stale token did not re-enter the measure loop')
+      return pass(
+        'a stale identity token fails closed and re-enters the measure loop (no stale delta)',
+      )
+    },
+  },
+  {
+    id: 'layout.settle-gating',
+    requirements: ['REQ-LAYOUT-019'],
+    assert() {
+      const { scheduler, session } = harness()
+      session.begin('el', BEFORE, AFTER)
+      if (session.isSettled()) return fail('settled while a projection is in flight')
+      let transitions = 0
+      let prev = false
+      for (let i = 0; i < 400; i++) {
+        scheduler.frame(16.67)
+        const now = session.isSettled()
+        if (now && !prev) transitions++
+        prev = now
+      }
+      if (!session.isSettled()) return fail('stuck unsettled')
+      if (transitions !== 1) return fail(`settled ${transitions} times, expected exactly 1`)
+      return pass('unsettled while projecting; settles exactly once (measurement-availability)')
+    },
+  },
+  {
+    id: 'layout.layoutid-two-positions',
+    requirements: ['REQ-LAYOUT-003'],
+    assert() {
+      const { scheduler, session } = harness()
+      const posA: Rect = { x: 0, y: 0, width: 100, height: 40 }
+      const posB: Rect = { x: 250, y: 120, width: 100, height: 40 }
+      const posC: Rect = { x: 60, y: 300, width: 100, height: 40 }
+      session.begin('shared', posA, posB) // one mounted element animating between two positions
+      scheduler.frames(400, 16.67)
+      let v = session.visualRect()
+      if (v === null || !rectClose(v, posB)) return fail('did not animate to the second position')
+      session.begin('shared', posB, posC) // the same element re-laid-out to a third position
+      scheduler.frames(400, 16.67)
+      v = session.visualRect()
+      if (v === null || !rectClose(v, posC)) return fail('did not animate to the next position')
+      return pass(
+        'a single mounted element animates between successive layout positions (layoutId geometry)',
+      )
+    },
+  },
+  {
+    id: 'layout.cross-engine-parity',
+    requirements: ['REQ-CONFORM-002'],
+    assert() {
+      // External-evidence-only: layout geometry needs a real DOM engine (onLayout rects would be
+      // fiction under jsdom/native), so this row stays `unassertable` and is discharged by the named
+      // Playwright Chromium gate. Owner front-loaded for the banner's 3-line routed clamp.
+      return unassertable(
+        'Owner: the Playwright Chromium gate layout.e2e.ts (LAYOUT_PARITY_COUNTERPART). Layout ' +
+          'geometry needs a real DOM engine — external-evidence-only (SPEC-CONFORMANCE §3), ' +
+          'unassertable under jsdom/native, discharged by that named Chromium altitude.',
+      )
+    },
+  },
+]
+
+// Run one layout scenario against the reference projection engine, producing a ScenarioResult under the
+// fake-host engine (M1). The session carries its own deterministic clock/graph — no adapter needed.
+export function runLayoutScenario(scenario: LayoutScenario): ScenarioResult {
+  const outcome = scenario.assert()
+  return {
+    id: scenario.id,
+    engine: FAKE_ENGINE,
+    verdict: outcome.verdict,
+    readings: [],
+    detail: outcome.detail,
+  }
+}