lecodes-sdk 1.2.0 → 2.0.0

package/src/ui/presentable.ts

@@ -4,45 +4,61 @@
 // longer overlays a scene, it replaces it (with a transition); UI over a scene goes through
 // `UIWidget.attachTo(scene)`.
 //
+// A destination is addressed by (kind, id): a screen / video by its node id, a scene by its
+// scene id, a native view by its viewId (`_dest()`). The runtime reports the lifecycle back through
+// the tree emitter (TREE_EVENT_OPEN / CLOSE / BACK) — see ui/tree.ts resolveDest.
+//
 // This module is dependency-free on purpose: gl/ and g2/ import it, so it must not pull any UI
 // element code into engine-only bundles.
 
-/** Built-in transition catalog. `push`/`pop` are the stacked-navigation pair (slide + parallax +
- *  dim + edge shadow); the rest are simple two-view moves. */
+import type { EasingInput } from "../animate/tween/easing"
+
+/** The built-in transitions (ui/transitions.ts holds what each one is). `push` / `pop` are the
+ *  stacked-navigation pair — the incoming screen slides over the other one, which drifts and dims;
+ *  the rest are two-screen moves. */
 export type TransitionName =
   | "push" | "pop"
   | "slide-from-left" | "slide-from-right" | "slide-from-top" | "slide-from-bottom"
   | "zoom" | "zoom-in" | "zoom-out" | "fade" | "none"
 
-/** Start/end pose of one side of a custom transition. `x`/`y` are logical px, or a percentage of
- *  the destination's size (e.g. `"100%"` = one full width to the right). */
-export type TransitionTransform = {
-  x?: number | `${number}%`
-  y?: number | `${number}%`
-  scale?: number
-  opacity?: number
+/**
+ * One screen's pose in a transition — the keys of an `animateTo` bag a transition can move, with
+ * the side's own timing. An array is a list of keyframes, as there.
+ */
+export type TransitionPose = {
+  /** A transform list, as in a style — and here a `%` in `translate` is a percent of the screen's
+   *  own box: `"translateX(100%)"` is one width to the right. */
+  transform?: string | string[]
+  opacity?: number | number[]
+  /** Black over this screen, 0..1: how dark the screen UNDER the other one gets. */
+  dim?: number | number[]
+  /** ms (default 300). */
+  duration?: number
+  /** ms to wait; the screen holds its first pose through it. */
+  delay?: number
+  /** Any curve `animateTo` takes (default `ease-in-out`). */
+  easing?: EasingInput
 }
 
 /**
- * A custom transition: declarative poses for the incoming/outgoing destination, played natively.
- * Serializes onto each platform's existing transition machinery — there is no per-frame JS.
- * Fields omitted keep the identity pose. Interactive back-swipe stays system-native (push/pop
- * only); a spec applies to non-interactive transitions.
+ * A transition between two destinations, described by where each side is when it is NOT at rest:
+ * the incoming one comes FROM `enter`, the outgoing one goes TO `exit`. A side left out stays put.
+ *
+ * ```ts
+ * Router.push(page, { transition: { enter: { transform: "translateY(100%)", duration: 400 }, exit: { dim: 0.3 } } })
+ * ```
+ *
+ * A screen's own `transform` / `opacity` are not seen while a transition moves it (put a lasting
+ * effect on a child). A scene, a native view, a video never move: next to one of them only the
+ * screen's side plays, above it.
  */
 export interface TransitionSpec {
-  /** Duration in ms (default 300). */
-  duration?: number
-  /** cubic-bezier control points (default ease-out). */
-  easing?: [number, number, number, number]
-  /** The entering destination animates FROM this pose to identity. */
-  incoming?: { from?: TransitionTransform }
-  /** The leaving destination animates from identity TO this pose. */
-  outgoing?: { to?: TransitionTransform }
-  /** Scrim alpha (0..1) painted over whichever destination is underneath. */
-  dim?: number
-  /** Which side stacks on top during the animation (default "incoming"). On Android, transitions
-   *  involving a scene always animate the screen side on top — the scene view itself never moves. */
-  onTop?: "incoming" | "outgoing"
+  /** The incoming destination's start: it moves from this pose to rest. */
+  enter?: TransitionPose
+  /** The outgoing destination's end: it moves from rest to this pose. */
+  exit?: TransitionPose
+  /** Which side is above the other while they move (default `"enter"`). */
+  onTop?: "enter" | "exit"
 }
 
 export type Transition = TransitionName | TransitionSpec
@@ -54,6 +70,14 @@ export type PresentOptions = {
   transition?: Transition
 }
 
+/** `close()` / `Router.hide()`: the transition the destination leaves with (default "none"). */
+export type DismissOptions = {
+  transition?: Transition
+}
+
+/** @internal The (kind, id, viewName, paramsJson) tuple the tree bridge addresses a destination by. */
+export type DestTuple = [kind: number, id: number, viewName: string, paramsJson: string]
+
 /**
  * Anything that can be shown as the app's current destination: a `UIScreen`, a `Scene` /
  * `ARScene`, a `Scene2D`, a `NativeView`, or a `UIVideo`. One Presentable is visible at a time;
@@ -66,21 +90,26 @@ export type PresentOptions = {
 export interface Presentable {
   // Return type covers the implementers: UIScreen → void, Scene2D → this, ARScene → Promise.
   open(options?: PresentOptions): void | this | Promise<void>
-  close(): void
+  /** Close this destination if it is the one on screen (nothing takes its place). One that is not
+   *  on screen — already replaced by a `Router.init/push/replace` or another `open()` — is left as
+   *  it is, so `Router.init(home); scene.close()` keeps `home` visible. */
+  close(options?: DismissOptions): void
   onOpen(callback: () => void): this
   onClose(callback: () => void): this
-  onBackPressed(callback: () => void): this
+  onBack(callback: () => void): this
   /** @internal Async work that must finish BEFORE this destination replaces the current one
    *  (camera permission, warm render, session launch — ARScene). The previous destination —
    *  typically a loading screen — stays visible while it runs; `open()` and `Router.push/replace`
    *  await it and skip the swap entirely if it rejects (permission denied, or superseded by
    *  another navigation that happened while preparing). */
   _prepare?(): Promise<void>
+  /** @internal The destination tuple (see DestTuple). */
+  _dest(): DestTuple
 }
 
 // The destination visible right now. Set optimistically by every successful open()/router
-// navigation, cleared by close(), and corrected by router onChange (hosts hand the wire desc
-// back on every stack change, including back gestures — `_p` resolves it to the SDK instance).
+// navigation, cleared by close(), and corrected by router onChange (the runtime reports the new
+// top on every stack change, including back gestures).
 let current: Presentable | null = null
 /** @internal Call whenever the visible destination changes. */
 export const _setCurrent = (p: Presentable | null): void => { current = p }
@@ -103,15 +132,3 @@ let navEpoch = 0
 export const _navEpoch = (): number => navEpoch
 /** @internal Call on every action that changes the visible destination. */
 export const _bumpNavEpoch = (): void => { navEpoch++ }
-
-/** @internal Does this host implement the Presentable navigation surface? The SDK falls back to
- *  the legacy openScreen/openScene bridges when it doesn't (screens keep working; scene/native
- *  destinations in the Router then throw). */
-export const _navSupported = (): boolean =>
-  typeof _creatorUI !== "undefined" && typeof _creatorUI.openView === "function"
-
-/** @internal The wire descriptor for a Presentable. Screens (and anything without `_viewDesc`)
- *  travel as themselves; scenes/native views/video provide a stable descriptor object carrying
- *  `_p` (the SDK instance) so hosts can hand it back through router onChange / lifecycle. */
-export const _descOf = (p: Presentable): object =>
-  typeof (p as any)._viewDesc === "function" ? (p as any)._viewDesc() : (p as object)

package/src/ui/router.ts

@@ -1,13 +1,27 @@
-import { _bumpNavEpoch, _descOf, _navSupported, _setCurrent, Presentable, type Transition } from "./presentable"
+import { _bumpNavEpoch, _setCurrent, Presentable, type DismissOptions, type PresentOptions, type Transition } from "./presentable"
+import { _transitionBack, _transitionId, TRANSITION_NONE, TRANSITION_UNSET } from "./transitions"
 import { _navDefaults } from "./theme"
+import { ensureEmitter, pin, resolveDest, setRouterChangeHandler, tree } from "./tree"
 
 type RouterOptions = {
   showDefaultBackButton?: boolean
 }
 
-type NavigateOptions = {
-  /** Transition to play. Defaults: `"push"` for push, `"pop"` for pop; replace follows the
-   *  theme's `replaceTransition` (`"none"` out of the box). */
+export type NavigateOptions = {
+  /** Transition to play. Defaults: `"push"` for push; replace follows the theme's
+   *  `replaceTransition` (`"none"` out of the box); a pop plays the way back the destination it
+   *  pops remembers. */
+  transition?: Transition
+  /** The way BACK from the destination — what `Router.pop()` without a transition, the edge swipe
+   *  and the system's back play when they take it off the stack. Default: the transition it came
+   *  with, the other way round (a push goes back with a pop, a slide from the bottom leaves
+   *  downwards; a zoom goes back with a fade). A `replace` that names none keeps the way back of
+   *  the destination it replaces: it belongs to the place in the stack. */
+  popTransition?: Transition
+}
+
+export type PopOptions = {
+  /** Transition to play instead of the way back the popped destination remembers. */
   transition?: Transition
 }
 
@@ -29,12 +43,12 @@ type Router = {
   replace(page: Presentable, opts?: NavigateOptions): void | Promise<void>
   /** Pop the top destination (the programmatic twin of the back gesture); `to` unwinds to a
    *  stack index in one step. */
-  pop(to?: number, opts?: NavigateOptions): void
+  pop(to?: number, opts?: PopOptions): void
   /** Blank the router's page, keeping the stack — `restore()` brings it back. A destination
    *  opened directly stays visible. */
-  hide(): void
+  hide(opts?: DismissOptions): void
   /** Re-present the stack top after `hide()` or a direct `open()` suspended the router. */
-  restore(): void
+  restore(opts?: PresentOptions): void
 
   /** `"change"` fires on every stack change — pushes, pops, and native back gestures — with the
    *  new top destination. */
@@ -43,42 +57,44 @@ type Router = {
 }
 
 let currentPage: Presentable | null = null
-let onChange = (page: any) => {
-  // Hosts hand back the wire object: the screen itself, or a descriptor carrying `_p`.
-  currentPage = page && page._p ? page._p : page
-  // The router's page is the visible destination (hosts fire this on every stack change,
-  // including back gestures) — keep Presentable.current in sync.
+let hooked = false
+const onChange = (kind: number, id: number) => {
+  // The runtime reports the new top on every stack change (pushes, pops, back gestures): resolve
+  // it to the SDK instance and keep Presentable.current in sync.
+  const page = resolveDest(kind, id) as unknown as Presentable | undefined
+  if (!page) return
+  currentPage = page
   _setCurrent(currentPage)
   for (let callback of (Router as any)._changeListeners) {
     callback(currentPage)
   }
 }
 
-// Non-screen destinations have no legacy bridge to fall back to — surface that clearly instead
-// of letting an old host try to build a screen out of a scene descriptor.
-const wireDesc = (page: Presentable): object => {
-  const desc = _descOf(page)
-  if (desc !== page && !_navSupported()) {
-    throw new Error("This host does not support scene/native-view navigation (requires _creatorUI.openView)")
-  }
-  return desc
-}
+// A screen the router holds is attached (pinned) until the runtime retires it (TREE_EVENT_DETACHED).
+// Scenes / native views are not tree elements: their destination registry holds them (`_dest()`).
+const hold = (page: Presentable): void => { if ((page as any)._h) pin(page as any) }
 
 export const Router: Router = /*#__PURE__*/ Object.freeze({
 
   init(homePage: Presentable, opts: RouterOptions = {}): void {
+    ensureEmitter()
+    if (!hooked) { hooked = true; setRouterChangeHandler(onChange) }
     _bumpNavEpoch()
-    _creatorUI.routerOpen(wireDesc(homePage), onChange, opts.showDefaultBackButton ?? false)
+    const [kind, id, name, params] = homePage._dest()
+    hold(homePage)
+    tree().routerOpen(kind, id, name, params, opts.showDefaultBackButton ?? false)
     currentPage = homePage
     _setCurrent(homePage)
   },
   push(page: Presentable, opts?: NavigateOptions): void | Promise<void> {
-    const desc = wireDesc(page)   // throws early on unsupported hosts, before any async work
     const go = () => {
       _bumpNavEpoch()
-      // Legacy hosts ignore the extra transition argument.
-      _creatorUI.routerPush(desc, opts?.transition ?? "push")
-      _setCurrent(page)   // optimistic — host onChange confirms (async on native hosts)
+      const [kind, id, name, params] = page._dest()
+      hold(page)
+      const transition = opts?.transition ?? "push"
+      const back = opts?.popTransition !== undefined ? _transitionId(opts.popTransition) : _transitionBack(transition)
+      tree().routerPush(kind, id, name, params, _transitionId(transition), back)
+      _setCurrent(page)   // optimistic — the runtime's change event confirms
     }
     // A preparing destination (ARScene) keeps the current page visible until it's ready; a
     // rejection (camera denied / superseded) propagates to the caller and nothing is pushed.
@@ -86,28 +102,29 @@ export const Router: Router = /*#__PURE__*/ Object.freeze({
     return prep ? prep.then(go) : go()
   },
   replace(page: Presentable, opts?: NavigateOptions): void | Promise<void> {
-    const desc = wireDesc(page)
     const go = () => {
       _bumpNavEpoch()
-      _creatorUI.routerReplace(desc, opts?.transition ?? _navDefaults.replace)
-      _setCurrent(page)   // optimistic — host onChange confirms (async on native hosts)
+      const [kind, id, name, params] = page._dest()
+      hold(page)
+      tree().routerReplace(kind, id, name, params, _transitionId(opts?.transition ?? _navDefaults.replace), _transitionId(opts?.popTransition))
+      _setCurrent(page)   // optimistic — the runtime's change event confirms
     }
     const prep = page._prepare?.()
     return prep ? prep.then(go) : go()
   },
-  pop(to?: number, opts?: NavigateOptions): void {
+  pop(to?: number, opts?: PopOptions): void {
     _bumpNavEpoch()
-    _creatorUI.routerPop(to ?? -1, opts?.transition ?? "pop")
+    tree().routerPop(to ?? -1, _transitionId(opts?.transition, TRANSITION_UNSET))
   },
-  hide() {
+  hide(opts?: DismissOptions) {
     _bumpNavEpoch()
-    _creatorUI.routerHide()
+    tree().routerHide(_transitionId(opts?.transition, TRANSITION_NONE))
     // hide() only blanks the router's own page — a directly-opened destination stays visible.
     if (Presentable.current === currentPage) _setCurrent(null)
   },
-  restore() {
+  restore(opts?: PresentOptions) {
     _bumpNavEpoch()
-    _creatorUI.routerRestore()
+    tree().routerRestore(_transitionId(opts?.transition, TRANSITION_NONE))
     _setCurrent(currentPage)   // the stack top is visible again
   },
 

package/src/ui/styleColor.ts

@@ -0,0 +1,56 @@
+// The UI color wire. The UI core parses CSS colors itself (engines/ui color.h over AnyCanvas's
+// css_color.h — the parser the SDK's `Color` is a twin of), so a color STRING goes over as written:
+// the same grammar, and CSS semantics for junk (an unparseable color is transparent, never an
+// error). The SDK converts only what the core cannot read — a packed `0xRRGGBB` number and
+// `[r, g, b(, a)]` components — to '#rrggbbaa', and a non-color there throws naming the key.
+// The element keeps the app's own value in `_style` (reads answer what the app set); only the wire
+// is converted. Kept out of UINode.ts: its `type Color` would clash with the `Color` value.
+// Bundle rule: this module must reach no CSS parser (numericColorToHex, never `Color`) — the name
+// table would otherwise ride along in every app with a styled color.
+
+import { numericColorToHex } from "../core/color"
+import { COLOR_KEYS, COLOR_SHORTHAND_KEYS } from "./colorKeys.gen"
+
+/** @internal One color value → its wire form. Pass-throughs: null / undefined (a reset) and every
+ *  string (CSS colors, `"default"`, `var(…)` — the core reads them all). A number or an array goes
+ *  through {@link numericColorToHex} and throws, naming the key and the value, when it is not a
+ *  color. */
+export const wireColor = (key: string, v: unknown): unknown => {
+  if (v == null || typeof v === "string") return v
+  try {
+    return numericColorToHex(v)
+  } catch (e) {
+    if (e instanceof Error) e.message = `${key}: ${e.message}`
+    throw e
+  }
+}
+
+/** @internal One style write → its wire value: a color key through {@link wireColor}. A shorthand
+ *  (`background`, `border*`) is a color in one of its forms only: a number or an array under
+ *  `background` is one; a string stays (the core's shorthand tells a color from a width, an image,
+ *  a gradient — same grammar) and a number under `border*` is a width. Every other key as is. */
+export const wireValue = (key: string, v: unknown): unknown => {
+  if (COLOR_SHORTHAND_KEYS.has(key)) {
+    return key === "background" && (typeof v === "number" || Array.isArray(v)) ? wireColor(key, v) : v
+  }
+  return COLOR_KEYS.has(key) ? wireColor(key, v) : v
+}
+
+// A nested state block (a `$class`: `$pressed`, `$landscape`, `$checked`, …): a plain object that is
+// not a host handle — a backgroundImage FetchResponse / File carries `_h` (the runtime's
+// own rule, presentation/tree.cpp mergeStyleLayer).
+const isBlock = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v) && !("_h" in v)
+
+/** @internal A style bag → its wire form: {@link wireValue} per key, nested state blocks
+ *  recursively. Copy on write: the SAME object comes back when nothing changed. */
+export const wireStyle = <T extends object>(bag: T): T => {
+  const src = bag as Record<string, unknown>
+  let out: Record<string, unknown> | null = null
+  for (const key of Object.keys(src)) {
+    const v = src[key]
+    const w = isBlock(v) ? wireStyle(v) : wireValue(key, v)
+    if (w !== v) (out ??= { ...src })[key] = w
+  }
+  return (out ?? bag) as T
+}

package/src/ui/theme.ts

@@ -27,9 +27,10 @@ const RESERVED = ["safe-top", "safe-bottom", "safe-left", "safe-right", "vw", "v
  * card.style({ bgColor: T.cardBg })   // T.cardBg === "var(--cardBg)"
  * ```
  *
- * Strings pass through (colors, fonts, expressions like `"max(safe-top, 24px)"`); numbers are
- * lengths (px); `null` removes a key (comfort knobs reset to their defaults). Env names
- * (`safe-*`, `vw`/`vh`/…) are host-owned — skipped with a warning. One special key:
+ * Strings pass through as written (colors — the core parses CSS —, fonts, expressions like
+ * `"max(safe-top, 24px)"`); numbers are lengths (px), so a theme COLOR is always a
+ * string (`"#0A84FF"`, `"red"`, never `0x0a84ff`); `null` removes a key (comfort knobs reset to
+ * their defaults). Env names (`safe-*`, `vw`/`vh`/…) are host-owned — skipped with a warning. One special key:
  * `replaceTransition` — the app-wide default transition for `Router.replace` (consumed SDK-side,
  * never sent to the host table).
  */
@@ -39,8 +40,9 @@ const setTheme = <T extends Record<string, string | number | Transition | null>>
 ): ThemeAccessors<Omit<T, "replaceTransition">> => {
   const accessors: Record<string, string> = {}
   let send = values as ThemeValues
+  const own = () => { if (send === values) send = { ...values } as ThemeValues }
   const strip = (key: string) => {
-    if (send === values) send = { ...values } as ThemeValues
+    own()
     delete send[key]
   }
   for (const key of Object.keys(values)) {
@@ -56,8 +58,7 @@ const setTheme = <T extends Record<string, string | number | Transition | null>>
     }
     accessors[key] = `var(--${key})`
   }
-  // Optional during rollout: hosts without the method simply don't theme (values still type).
-  if (Object.keys(send).length > 0) _creatorUI.setTheme?.(send)
+  if (Object.keys(send).length > 0) _creatorTree.setTheme(send)
   return accessors as ThemeAccessors<Omit<T, "replaceTransition">>
 }
 

package/src/ui/transitions.ts

@@ -0,0 +1,249 @@
+// Screen transitions (docs/plans/transitions-plan.md). Every transition — the built-in ones too —
+// is DATA in the format of presentable.ts and is written HERE: the runtime holds no catalog and
+// knows no name, a host animates nothing of its own. A transition becomes a tween blob whose
+// targets are ROLES, registered once per world (`_creatorTree.defineTransition`); a navigation call
+// carries the id, and the runtime binds the roles to the two screen roots when it plays it — as
+// ordinary tracks on their `transform` / `opacity` / `dim`, which never commit.
+//
+// Depends on the tween builder alone: gl/ and g2/ reach this through their open().
+
+import type { Easing } from "../animate/easings"
+import { DEFAULT_EASING, parseEasing, type EasingSpec } from "../animate/tween/easing"
+import { CLOCK_UI, DOM_UI, KIND_FLOAT, KIND_TRANSFORM, buildBlob, parseTransformList, transformLanes, warnOnce, type Keyframe, type Track, type TweenTarget } from "../animate/tween/spec"
+import type { Transition, TransitionName, TransitionPose, TransitionSpec } from "./presentable"
+
+/** Wire ids: a registered transition is > 0. */
+export const TRANSITION_NONE = 0
+/** "The caller names none": the runtime plays what the stack entry remembers (a pop), or keeps
+ *  what the replaced entry remembered (a replace's way back). */
+export const TRANSITION_UNSET = -1
+
+/** Who a track moves. The ALONE roles play next to a destination that cannot move (a scene, a
+ *  native view, a video) or next to nothing (close(), the first open): only the screen plays, above. */
+export const ROLE_ENTER = 0
+export const ROLE_EXIT = 1
+export const ROLE_ENTER_ALONE = 2
+export const ROLE_EXIT_ALONE = 3
+
+/** `defineTransition` flags. */
+export const TRANSITION_ENTER_ON_TOP = 1
+
+const DEFAULT_DURATION_MS = 300
+
+// ---- the catalog ---------------------------------------------------------------------------------
+
+// A spring as a curve over 0..1 (the response of a unit step, `omega` = how soon it settles inside
+// the span): what UIKit's `dampingRatio` animators and the old Android SpringInterpolator eased with.
+const spring = (damping: number, omega: number): Easing => (t) => {
+  if (t >= 1) return 1
+  if (damping < 1) {
+    const wd = omega * Math.sqrt(1 - damping * damping)
+    return 1 - Math.exp(-damping * omega * t) * (Math.cos(wd * t) + ((damping * omega) / wd) * Math.sin(wd * t))
+  }
+  const w = omega * damping
+  return 1 - Math.exp(-w * t) * (1 + w * t)
+}
+
+// A soft ease-out that settles with a slight overshoot: the slides and the base zoom.
+const SETTLE = [0.3, 1.1, 0.5, 1] as const
+
+const slide = (enter: string, exit: string): TransitionSpec => ({
+  enter: { transform: enter, duration: 400, easing: SETTLE },
+  exit: { transform: exit, duration: 400, easing: SETTLE },
+})
+
+// The stacked pair: the top screen travels its whole width while the one under it drifts a part
+// of it and dims. The two phone platforms keep their own feel — the numbers of one table.
+const push = (): TransitionSpec => {
+  if (_creatorDevice.platform === "android") {
+    const t = { duration: 350, easing: [0.2, 0, 0, 1] as const }
+    return { enter: { transform: "translateX(100%)", ...t }, exit: { transform: "translateX(-25%)", dim: 0.3, ...t } }
+  }
+  const t = { duration: 380, easing: spring(1, 9) }
+  return { enter: { transform: "translateX(100%)", ...t }, exit: { transform: "translateX(-30%)", dim: 0.12, ...t } }
+}
+
+/** What a name is. `none` has no spec. */
+const named = (name: TransitionName): TransitionSpec | null => {
+  switch (name) {
+    case "push": return push()
+    case "pop": return mirrored(push())
+    case "slide-from-left": return slide("translateX(-100%)", "translateX(100%)")
+    case "slide-from-right": return slide("translateX(100%)", "translateX(-100%)")
+    case "slide-from-top": return slide("translateY(-100%)", "translateY(100%)")
+    case "slide-from-bottom": return slide("translateY(100%)", "translateY(-100%)")
+    // the incoming grows into place above the other one, which only fills the thin edge
+    case "zoom":
+    case "zoom-in": return { enter: { transform: "scale(0.985)", duration: 400, easing: SETTLE } }
+    // the outgoing recedes and dissolves above; the incoming settles from slightly enlarged, never
+    // below 1, so no edge is exposed
+    case "zoom-out": {
+      const t = { duration: 420, easing: spring(0.82, 10) }
+      return { onTop: "exit", enter: { transform: "scale(1.06)", ...t }, exit: { transform: "scale(0.92)", opacity: 0, ...t } }
+    }
+    // a fade-THROUGH: out, then in — two half-transparent screens never show through each other
+    case "fade": return {
+      onTop: "exit",
+      exit: { opacity: 0, duration: 120, easing: [0.42, 0, 1, 1] },
+      enter: { opacity: 0, delay: 120, duration: 200, easing: [0, 0, 0.58, 1] },
+    }
+    default: return null
+  }
+}
+
+/** The way back of a name. A slide and the stacked pair go back the way they came; a zoom's mirror
+ *  would end with the top screen vanishing at its start scale, so a zoom goes back with a fade. */
+const BACK: Record<TransitionName, TransitionName> = {
+  "push": "pop", "pop": "push",
+  "slide-from-left": "slide-from-right", "slide-from-right": "slide-from-left",
+  "slide-from-top": "slide-from-bottom", "slide-from-bottom": "slide-from-top",
+  "zoom": "fade", "zoom-in": "fade", "zoom-out": "fade", "fade": "fade", "none": "none",
+}
+
+// ---- the mirror ----------------------------------------------------------------------------------
+
+const backwards = <T>(v: T | T[] | undefined): T | T[] | undefined => (Array.isArray(v) ? v.slice().reverse() : v)
+
+const reversedPose = (p: TransitionPose | undefined): TransitionPose | undefined =>
+  p && { ...p, transform: backwards(p.transform), opacity: backwards(p.opacity), dim: backwards(p.dim) }
+
+/** The way back of a spec: the ROLES swap — the screen that came leaves into its `enter` pose, the
+ *  one that left comes back from its `exit` pose, the same screen stays on top — and the timing and
+ *  the curves stay as written. Not a rewind: that would turn an ease-out into a slow start. */
+export const mirrored = (s: TransitionSpec): TransitionSpec => ({
+  enter: reversedPose(s.exit),
+  exit: reversedPose(s.enter),
+  onTop: (s.onTop ?? "enter") === "enter" ? "exit" : "enter",
+})
+
+// ---- a spec → tracks ---------------------------------------------------------------------------
+
+/** One prop of a side: its keys in the order the side plays them (an incoming side ends at rest
+ *  after them, an outgoing one starts at rest before them), and what rest is. */
+type Lane = { prop: string, kind: number, sig?: string, keys: number[][], rest: number[] }
+type Side = { lanes: Lane[], atMs: number, durMs: number, easing: EasingSpec }
+
+const list = <T>(v: T | T[]): T[] => (Array.isArray(v) ? v : [v])
+
+const transformLane = (value: string | string[]): Lane | null => {
+  const parsed = list(value).map((v) => parseTransformList(v, true))
+  const first = parsed[0]
+  if (!first || parsed.some((p) => p === null || p.sig !== first.sig)) {
+    warnOnce("transition:transform", "a transition's transform must be a list of translate / scale / rotate, the same functions in every keyframe — ignored")
+    return null
+  }
+  if (first.sig === "") return null
+  const rest: number[] = []
+  for (const fn of first.sig.split(",")) for (let i = transformLanes(fn); i > 0; i--) rest.push(fn.startsWith("scale") ? 1 : 0)
+  return { prop: "transform", kind: KIND_TRANSFORM, sig: first.sig, keys: parsed.map((p) => p!.lanes), rest }
+}
+
+const floatLane = (prop: string, value: number | number[], rest: number): Lane =>
+  ({ prop, kind: KIND_FLOAT, keys: list(value).map((v) => [v]), rest: [rest] })
+
+const sideOf = (pose: TransitionPose | undefined): Side | null => {
+  if (!pose) return null
+  const lanes: Lane[] = []
+  if (pose.transform !== undefined) { const l = transformLane(pose.transform); if (l) lanes.push(l) }
+  if (pose.opacity !== undefined) lanes.push(floatLane("opacity", pose.opacity, 1))
+  if (pose.dim !== undefined) lanes.push(floatLane("dim", pose.dim, 0))
+  if (lanes.length === 0) return null
+  return {
+    lanes,
+    atMs: Math.max(0, pose.delay ?? 0),
+    durMs: Math.max(0, pose.duration ?? DEFAULT_DURATION_MS),
+    easing: pose.easing === undefined ? DEFAULT_EASING : parseEasing(pose.easing),
+  }
+}
+
+/** The OTHER side's pose as this screen's own, for a screen that plays alone: it takes the pose of
+ *  the side that is on top (the one made to cover and to uncover — the side under it only drifts),
+ *  travelling the other way, so a push still moves everything to the left; its keys run backwards,
+ *  the direction being the opposite one. No dim: nothing is over it. */
+const borrowed = (side: Side | null): Side | null => {
+  if (!side) return null
+  const lanes = side.lanes.filter((l) => l.prop !== "dim").map((l) => {
+    if (l.kind !== KIND_TRANSFORM) return { ...l, keys: l.keys.slice().reverse() }
+    const sign: number[] = []
+    for (const fn of l.sig!.split(",")) for (let i = transformLanes(fn); i > 0; i--) sign.push(fn.startsWith("translate") ? -1 : 1)
+    return { ...l, keys: l.keys.map((k) => k.map((v, i) => v * sign[i]!)).reverse() }
+  })
+  return lanes.length > 0 ? { ...side, lanes } : null
+}
+
+const roleTarget = {} as TweenTarget   // a track's target is its role: nothing of a Track reads this
+
+/** `incoming` = the screen moves from its pose to rest; otherwise from rest to its pose. */
+const tracksOf = (side: Side | null, role: number, incoming: boolean): Track[] => {
+  if (!side) return []
+  const channel = { domain: DOM_UI, id: () => role + 1, value: () => null }
+  return side.lanes.map((l) => {
+    // explicit keys at both ends: a captured one that fails to read would leave a screen in its pose
+    const values = incoming ? [...l.keys, l.rest] : [l.rest, ...l.keys]
+    const keys: Keyframe[] = values.map((lanes, i) => ({ t: i / (values.length - 1), easing: side.easing, value: { lanes } }))
+    return { target: roleTarget, prop: l.prop, channel, kind: l.kind, lanes: l.rest.length, sig: l.sig, atMs: side.atMs, durMs: side.durMs, commit: false, keys }
+  })
+}
+
+/** @internal The blob of a spec: `roles[i]` is the role of the blob's target `i`. Null = the spec
+ *  moves nothing. */
+export const _transitionBlob = (spec: TransitionSpec): { data: Float32Array, strings: string[], roles: number[], flags: number } | null => {
+  const enter = sideOf(spec.enter), exit = sideOf(spec.exit)
+  const enterOnTop = (spec.onTop ?? "enter") === "enter"
+  const tracks = [
+    ...tracksOf(enter, ROLE_ENTER, true),
+    ...tracksOf(exit, ROLE_EXIT, false),
+    ...tracksOf(enterOnTop ? enter : borrowed(exit), ROLE_ENTER_ALONE, true),
+    ...tracksOf(enterOnTop ? borrowed(enter) : exit, ROLE_EXIT_ALONE, false),
+  ]
+  if (tracks.length === 0) return null
+  let durationMs = 0
+  for (const t of tracks) durationMs = Math.max(durationMs, t.atMs + t.durMs)
+  const blob = buildBlob({ clock: CLOCK_UI, durationMs, delayMs: 0, iterations: 1, pingPong: false, rate: 1, tracks, calls: [] })
+  return { data: blob.data, strings: blob.strings, roles: blob.targets.map((t) => (t as number) - 1), flags: enterOnTop ? TRANSITION_ENTER_ON_TOP : 0 }
+}
+
+// ---- the registry (one per world, like the runtime's) -------------------------------------------
+
+type Entry = { id: number, back?: number, spec: TransitionSpec | null }
+let byName = new Map<string, Entry>()
+let bySpec = new WeakMap<TransitionSpec, Entry>()
+
+const define = (spec: TransitionSpec | null): Entry => {
+  const blob = spec && _transitionBlob(spec)
+  return { id: blob ? _creatorTree.defineTransition(blob.data, blob.strings, blob.roles, blob.flags) : TRANSITION_NONE, spec }
+}
+
+const entryOf = (t: Transition): Entry => {
+  if (typeof t === "string") {
+    let e = byName.get(t)
+    if (!e) {
+      if (!(t in BACK)) warnOnce(`transition:${t}`, `"${t}" is not a transition — none plays`)
+      byName.set(t, e = define(named(t)))
+    }
+    return e
+  }
+  let e = bySpec.get(t)
+  if (!e) bySpec.set(t, e = define(t))
+  return e
+}
+
+/** @internal The wire id of a transition (registered on its first use); nothing named = `unset`. */
+export const _transitionId = (t: Transition | undefined, unset: number = TRANSITION_UNSET): number =>
+  t === undefined ? unset : entryOf(t).id
+
+/** @internal The wire id of the way back of `t`: the catalog's for a name, the mirror of a spec. */
+export const _transitionBack = (t: Transition): number => {
+  const e = entryOf(t)
+  if (e.back === undefined) {
+    e.back = typeof t === "string" ? entryOf(BACK[t as TransitionName] ?? "none").id
+      : e.spec ? define(mirrored(e.spec)).id : TRANSITION_NONE
+  }
+  return e.back
+}
+
+/** @internal Tests: a new fake runtime has no transition of the previous one. */
+export const _resetTransitions = (): void => {
+  byName = new Map()
+  bySpec = new WeakMap()
+}