@solidrt/core 0.0.71 → 0.0.72

package/AGENTS.md

@@ -16,6 +16,11 @@ matches the work before starting it:
   before writing any per-frame code, any animation, or anything that writes
   properties in a loop.
 
+When SolidRT itself gets in the way (a bug, a missing export, a doc that
+misled you, a trap nothing warned about), append it to SOLIDRT-FEEDBACK.md
+in the project root, creating the file if needed: what you hit, and what
+you expected instead.
+
 ## The window is device-sized - design fluid
 
 A SolidRT window is host-sized and resizable, and the SAME app runs on phones,
@@ -304,7 +309,10 @@ that reads exactly like Solid fallout.
 
 - Events: there is NO `onClick`/`onPress`. A "button" is a `<view>`/`<rect>`
   with `onPointerDown`. Handlers: onPointerDown/Up/Move/Enter/Leave, onWheel,
-  onKeyDown/Up, onTextInput, onFocus/onBlur. Text entry: focus a node with an
+  onKeyDown/Up, onTextInput, onFocus/onBlur. `pointerEvents` gates hit
+  testing and cascades like CSS: "none" on a container also disables its
+  subtree until a descendant sets "auto" (or "all", which makes the element
+  one target and skips its children). Text entry: focus a node with an
   `onTextInput` handler. Focus alone never raises the on-screen keyboard: a
   tap on the focused node (or explicit startTextInput()) does, and never
   while a physical keyboard is attached; on keyboard-equipped platforms the
@@ -617,8 +625,11 @@ that reads exactly like Solid fallout.
   update: it runs after every onFrame callback and the reactive flush,
   when the frame's state is final, for what must see everything the frame
   wrote and write once more (a camera follow, a fit to a measured box;
-  Unity's LateUpdate); its signal writes are flushed before the paint
-  too, the way onLayout's are. `onBeforeRender(fn, {
+  Unity's LateUpdate) - native motion (a clip player, a node transition)
+  steps before the frame's callbacks and starts what they declared after
+  them, so a follow of an animated node reads the pose this frame draws;
+  its signal writes are flushed before the paint too, the way onLayout's
+  are. `onBeforeRender(fn, {
   publish: true })` runs after those, and again after a frame's onLayout
   handlers: the pass where an extension hands the engine what the frame
   wrote into its mirrors (a scene its record buffers and lights, a sprite

package/agents/performance.md

@@ -24,7 +24,13 @@ Rules, in order of leverage:
    use them for anything interactive), `{ duration, curve }` is a tween
    (`linear | ease | ease-in | ease-out | ease-in-out` or a cubic-bezier
    array; tweens restart from the current value on retarget, CSS
-   semantics). Keys are property names plus `all` as catch-all; a string
+   semantics). Keys are the animatable property names (the
+   TransitionPropName set: opacity, transform components, color, shadow,
+   and x/y/w/h on the detached primitives), `all` as catch-all, and
+   `layout`: a layout property (width, height, padding, flex, order)
+   never takes an entry of its own; whatever layout does to the
+   element's box animates through `layout`, which slides it from its
+   painted box to its new one. A string
    is shorthand (`transition="300ms ease-out"`); `delay` holds each
    write, `from` animates the first attach in (enter), `exit` animates
    removal out before the node frees, `stagger` on a parent cascades its

package/docs/reference/input.md

@@ -8,7 +8,7 @@ the walk.
 
 ## Handlers
 
-{{ decl packages/core/src/types.d.ts PointerProps }}
+{{ decl packages/core/src/types.d.ts InputProps }}
 
 `pointerEvents="none"` takes an element out of hit testing, and the walk skips
 it as an ancestor too, so the `parentX`/`parentY` of an event stay in the frame

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.71",
+  "version": "0.0.72",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -33,8 +33,8 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.71",
-    "@solidrt/test": "0.0.71"
+    "@solidrt/flux-types": "0.0.72",
+    "@solidrt/test": "0.0.72"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.13",

package/src/gpu.ts

@@ -152,6 +152,13 @@ export {
 export { copyTexture, destroyBuffer, renderTarget, setDraw } from "flux:gpu"
 export type { BlendMode, BufferUpdate, CullMode, DrawRange, IndexBinding, IndexFormat, IndexRange, InstanceOrder, OrderUpdate, ShaderParams, Topology, VertexAttribute, VertexBufferLayout, VertexFormat } from "flux:gpu"
 
+// The vertex vocabulary as data (vertex.ts): the format codecs, the
+// arithmetic over an attribute list and the record accessors that the 3d
+// geometry layouts, the 3d instance streams and the 2d material style
+// streams all run on.
+export { attributeAccess, checkLayout, encodeRecord, formatFeeds, isFloatFormat, isFloatLayout, layoutBytes, layoutComponents, layoutFields, layoutKey, layoutSlot, layoutStride, layoutView, writeRecord, VERTEX_FORMATS } from "./vertex.ts"
+export type { AttributeAccess, FormatCodec, FormatKind } from "./vertex.ts"
+
 // The draw-list verbs, re-exported raw: entries live and die with their draw
 // target (see createDrawTarget below), so there is no per-entry lifetime to
 // wrap. addDraw adds an entry (appended, or inserted via opts.before) and

package/src/index.ts

@@ -58,7 +58,7 @@ export type {
   Element,
   LayoutProps,
   TransformProps,
-  PointerProps,
+  InputProps,
   TransitionProps,
   Transition,
   TransitionCurve,
@@ -119,6 +119,8 @@ export {
   createRenderEffect,
   createRoot,
   createStore,
+  createProjection,
+  snapshot,
   reconcile,
   merge,
   omit,
@@ -131,6 +133,22 @@ export {
 } from "@solidjs/signals"
 export type { Accessor, Setter, Signal, Store, StoreSetter } from "@solidjs/signals"
 
+// Async and optimistic state (from @solidjs/signals). `isPending` and
+// `latest` read an async value's in-flight change, `refresh` re-asks it
+// and `affects` marks it as changing; `action` runs a mutation as a
+// transition, and the optimistic primitives show the expected value until
+// it completes. See CHEATSHEET.md "Async" and "Actions & optimistic".
+export {
+  action,
+  createOptimistic,
+  createOptimisticStore,
+  isPending,
+  latest,
+  refresh,
+  affects,
+} from "@solidjs/signals"
+export type { Refreshable } from "@solidjs/signals"
+
 // Owner and lifecycle (from @solidjs/signals). `createRoot` above is the fourth
 // member of this group - it creates an owned scope, these reach the owner it
 // established. Capture an owner to restore it across an async boundary

package/src/renderer.ts

@@ -1,7 +1,7 @@
 // createErrorBoundary comes from signals, not solid-js: solid-js marks it
 // @internal (an app writes <Errored>, a renderer reaches for the primitive)
 // and leaves it out of its public types.
-import { createErrorBoundary, createRoot, onCleanup, NotReadyError, untrack } from "@solidjs/signals"
+import { createErrorBoundary, createRoot, onCleanup, NotReadyError, runWithOwner, untrack } from "@solidjs/signals"
 import { createRenderer } from "@solidjs/universal"
 import type { Element } from "solid-js"
 import * as tree from "flux:rendertree"
@@ -122,6 +122,13 @@ let warnedLeakTypes = new Set<string>()
 // warning: a leak that keeps growing at a stable set of types warns again
 // each time the total crosses the next power of ten.
 let warnedMagnitude = -1
+// The other cause of orphans: a subtree whose build a throw cut short (a
+// child expression or component body that threw an error, or a pending
+// read on its way to <Loading>, which retries and abandons again). The
+// elements created before the throw are never inserted. Counted where
+// such throws pass (insert's guard, the root boundary) so the warning can
+// point at it (okf/backlog/suspend-retry-orphan-elements.md).
+let abandonedBuilds = 0
 
 export function scanForOrphans(now: number): void {
   if (!import.meta.env.DEV) return
@@ -144,11 +151,17 @@ export function scanForOrphans(now: number): void {
   for (let [type] of fresh) warnedLeakTypes.add(type)
   warnedMagnitude = magnitude
   let list = [...counts].map(([type, n]) => `<${type}> x${n}`).join(", ")
+  let abandoned =
+    abandonedBuilds === 0
+      ? ""
+      : `A build cut short by a throw leaves what it had created unreachable too: ${abandonedBuilds} ` +
+        `such throws so far (an error in a child expression or component body, or a pending read ` +
+        `on its way to <Loading>, which retries and abandons again). `
   console.warn(
     `Leak sentinel: ${total} nodes are unreachable and will never be freed: ${list}. ` +
       `The usual cause is reading an element-valued prop more than once (every read ` +
       `builds a new subtree); read it once where it mounts, or resolve it with ` +
-      `children(). If these nodes are intentionally kept for later mounting, ignore ` +
+      `children(). ${abandoned}If these nodes are intentionally kept for later mounting, ignore ` +
       `this. The next warning comes when a new element type joins the list or the ` +
       `total passes ${10 ** (magnitude + 1)}.`,
   )
@@ -345,6 +358,28 @@ export let { memo, createComponent, createElement, createTextNode, insertNode, s
   renderer
 let { effect: rawEffect, insert: rawInsert } = renderer
 
+/** A ref callback as a component prop: a function, or an array of them. */
+export type RefCallback<T> = ((handle: T) => void) | RefCallback<T>[]
+
+/**
+ * Hands `handle` to a component's `ref` callback prop the way Solid hands
+ * an element to an element's `ref`: read untracked, called outside any
+ * owner, so a signal setter passed straight in (`ref={setLayer}`) writes
+ * without tripping the owned-scope guard. A component body is an owned
+ * scope, so calling the prop directly there throws
+ * REACTIVE_WRITE_IN_OWNED_SCOPE in dev; `untrack` does not lift that.
+ * Accepts an array of callbacks like Solid's applyRef does.
+ */
+export function callRef<T>(read: () => RefCallback<T> | undefined, handle: T): void {
+  let callback = untrack(read)
+  if (callback === undefined) return
+  runWithOwner(null, () => {
+    if (Array.isArray(callback)) {
+      for (let f of (callback as unknown[]).flat(Infinity) as ((handle: T) => void)[]) f(handle)
+    } else callback(handle)
+  })
+}
+
 // ------ Per-node error containment --------
 //
 // Every reactive write into the tree goes through two exports the compiled
@@ -382,6 +417,9 @@ function guard<T>(fn: (prev?: T) => T, describe: () => string, nested: boolean,
       last = value
       return value
     } catch (e) {
+      // Only a child expression builds a subtree a throw can abandon; a
+      // prop expression creates no elements.
+      if (nested) abandonedBuilds += 1
       if (e instanceof NotReadyError) throw e
       if (!failing) {
         failing = true
@@ -456,6 +494,7 @@ export function render(code: () => any) {
       (error, reset) => {
         // The boundary hands the error as an accessor.
         let err = error()
+        abandonedBuilds += 1
         console.error("Uncaught error: the app is replaced by the error window until reset or reload.", err)
         let win = errorWindow(err, reset)
         errorWindows.add(win.id)

package/src/types.d.ts

@@ -381,7 +381,9 @@ export interface WheelEvent extends PointerEvent {
 // Routing: keydown/keyup dispatch along the focused node's ancestor chain,
 // leaf->root, always ending at the window root; with nothing focused they go
 // to the window root alone. <window onKeyDown> is therefore the app-global
-// shortcut point.
+// shortcut point. An Escape keydown nobody consumed then runs the back
+// handler stack (onBack) without its platform default, so a control that
+// takes Escape itself calls stopPropagation.
 export interface KeyEvent {
   /** When the key event happened, in milliseconds, on the clock of
    * `PointerEvent.timeStamp`. */
@@ -421,7 +423,7 @@ export interface NodeProps {
   label?: string
 }
 
-export interface PointerProps extends NodeProps {
+export interface InputProps extends NodeProps {
   onPointerDown?: (event: PointerEvent) => void
   onPointerUp?: (event: PointerEvent) => void
   /**
@@ -456,6 +458,15 @@ export interface PointerProps extends NodeProps {
    * still moves through setFocus.
    */
   focusable?: boolean
+  /**
+   * Hit testing, with CSS pointer-events inheritance: unset inherits the
+   * nearest ancestor's value (root: "auto"). "none" makes the element and
+   * its subtree transparent and drops it from the bubble path; a descendant
+   * that sets "auto" or "all" opts back in. "auto" hits the element's box
+   * with children deepest-first. "all" (not CSS's) hits the box as one
+   * target and never descends: the whole element is the target whatever its
+   * children's shapes, nothing outside the box is captured.
+   */
   pointerEvents?: "auto" | "none" | "all"
   /**
    * The mouse cursor while this element is hovered: a platform shape by its
@@ -762,7 +773,7 @@ export interface TransitionProps {
 
 // Primitives
 
-export interface WindowProps extends LayoutProps, PointerProps, TransitionProps {
+export interface WindowProps extends LayoutProps, InputProps, TransitionProps {
   children?: Children
   title?: string
   fullscreen?: boolean
@@ -817,7 +828,7 @@ export interface WindowShaderProps {
 // Everything a view offers besides layout: d-view uses this directly (a
 // detached view has no taffy presence, so layout props would be rejected at
 // runtime); the layout `view` adds LayoutProps below.
-export interface ViewOwnProps extends TransformProps, PointerProps {
+export interface ViewOwnProps extends TransformProps, InputProps {
   children?: Children
   trace?: boolean
   /**
@@ -970,7 +981,7 @@ export interface ViewProps extends ViewOwnProps, LayoutProps {}
 // the box for a clip to cut. `path` and `line` strokes stay centered on their
 // geometry - there the geometry is the stroke, not a box. A dashed stroke
 // dashes that same inset outline (see DashProps).
-export interface RectProps extends PaintProps, PointerProps, DashProps {
+export interface RectProps extends PaintProps, InputProps, DashProps {
   // Corner radius, measured on the box (the stroke's outer edge). A single
   // number applies to all four corners; an array is [top-left, top-right,
   // bottom-right, bottom-left] (CSS border-radius order).
@@ -979,7 +990,7 @@ export interface RectProps extends PaintProps, PointerProps, DashProps {
 }
 
 // Strokes paint inside the box, same as `RectProps`.
-export interface OvalProps extends PaintProps, PointerProps, DashProps {
+export interface OvalProps extends PaintProps, InputProps, DashProps {
   shadow?: ShadowProps
 }
 
@@ -1036,7 +1047,7 @@ export interface DashProps {
 // fill). On a polyline "fill" and "stroke-and-fill" fill the polygon
 // (nonzero, implicitly closed) and hit-test its interior; on the two-point
 // form fill has no effect, a segment has no interior.
-export interface LineProps extends PaintProps, PointerProps, DashProps {
+export interface LineProps extends PaintProps, InputProps, DashProps {
   /**
    * Polyline vertices as a flat [x0, y0, x1, y1, ...] in the element's local
    * space (the space x1..y2 use). Takes precedence over the endpoints while
@@ -1061,7 +1072,7 @@ export interface LineProps extends PaintProps, PointerProps, DashProps {
  * points) plus the stroke's reach, at a `d-path`'s x/y - not its layout box
  * or the inherited one.
  */
-export interface PathProps extends PaintProps, PointerProps, DashProps {
+export interface PathProps extends PaintProps, InputProps, DashProps {
   d?: string
   fillRule?: "nonzero" | "evenodd"
   /** Shadows the drawn silhouette (fill and/or stroke); `spread` is rejected here. */
@@ -1128,12 +1139,12 @@ export interface TextRunProps {
  * Pointer handlers fire for the boxes of the run's own text on each line it
  * spans and bubble to the enclosing spans and text.
  */
-export interface SpanProps extends TextRunProps, PointerProps {
+export interface SpanProps extends TextRunProps, InputProps {
   children?: Children
   color?: Color | Gradient
 }
 
-export interface TextProps extends PaintProps, PointerProps, TextRunProps {
+export interface TextProps extends PaintProps, InputProps, TextRunProps {
   children?: Children
   textAlign?: TextAlign
   maxLines?: number
@@ -1174,7 +1185,7 @@ export interface TextProps extends PaintProps, PointerProps, TextRunProps {
  * Texture alpha is premultiplied, so additive modes need no manual
  * premultiplication.
  */
-export interface TextureProps extends PaintProps, PointerProps {
+export interface TextureProps extends PaintProps, InputProps {
   src?: TextureId
   /**
    * Corner radius, as on a rect: the image is drawn as a rounded rect filled

package/src/vertex.ts

@@ -0,0 +1,294 @@
+// The vertex vocabulary as data: one codec per vertex format (the engine's
+// table in the same spelling, so it is also the list a declared format
+// must be one of), and the arithmetic over an attribute LIST - the stride
+// it interleaves to, its identity key, where a name sits, whether a
+// Float32Array can hold it - plus the accessors that read and write one
+// attribute of a record through its codec, so no caller ever knows an
+// offset, a stride or a format. @solidrt/3d's geometry layouts and
+// instance streams and @solidrt/2d's material style streams run on this;
+// the named presets (a 3d geometry's "base" layout) stay in the packages.
+//
+// Every format is a multiple of 4 bytes (WebGPU's alignment rule), which
+// is what keeps every offset and stride 4-aligned with no padding
+// arithmetic anywhere, and a Float32Array view over any record buffer
+// always valid.
+
+import type { VertexAttribute, VertexFormat } from "flux:gpu"
+
+/** The shader `in` family a vertex format feeds (WebGPU's rule: the
+ * format decides): "float" for the float and normalized formats (`in
+ * vec*`), "uint" for uint* (`in uvec*`), "sint" for sint* (`in ivec*`). */
+export type FormatKind = "float" | "uint" | "sint"
+
+/** One vertex format's codec: its size, its component count, its kind,
+ * and the read and write of component `k` of an attribute at byte `at`
+ * of a DataView, in the value the shader sees (a normalized integer
+ * decodes to 0..1 / -1..1, an unnormalized one to its exact value). */
+export type FormatCodec = {
+  bytes: number
+  components: number
+  kind: FormatKind
+  get(dv: DataView, at: number, k: number): number
+  set(dv: DataView, at: number, k: number, v: number): void
+}
+
+// The integer component kinds behind the packed formats: width, the
+// value that maps to 1 (GL ES 3.0's normalization rule, -max mapping to
+// -1 and the one value below it clamped there), and the raw accessors.
+type IntKind = { bytes: number; max: number; get(dv: DataView, at: number): number; set(dv: DataView, at: number, v: number): void }
+const U8: IntKind = { bytes: 1, max: 255, get: (dv, at) => dv.getUint8(at), set: (dv, at, v) => dv.setUint8(at, v) }
+const S8: IntKind = { bytes: 1, max: 127, get: (dv, at) => dv.getInt8(at), set: (dv, at, v) => dv.setInt8(at, v) }
+const U16: IntKind = { bytes: 2, max: 65535, get: (dv, at) => dv.getUint16(at, true), set: (dv, at, v) => dv.setUint16(at, v, true) }
+const S16: IntKind = { bytes: 2, max: 32767, get: (dv, at) => dv.getInt16(at, true), set: (dv, at, v) => dv.setInt16(at, v, true) }
+const U32: IntKind = { bytes: 4, max: 4294967295, get: (dv, at) => dv.getUint32(at, true), set: (dv, at, v) => dv.setUint32(at, v, true) }
+const S32: IntKind = { bytes: 4, max: 2147483647, get: (dv, at) => dv.getInt32(at, true), set: (dv, at, v) => dv.setInt32(at, v, true) }
+
+function clamp(v: number, lo: number, hi: number): number {
+  return v < lo ? lo : v > hi ? hi : v
+}
+
+function floatCodec(components: number, bytes: number, get: (dv: DataView, at: number) => number, set: (dv: DataView, at: number, v: number) => void): FormatCodec {
+  return {
+    bytes: components * bytes,
+    components,
+    kind: "float",
+    get: (dv, at, k) => get(dv, at + k * bytes),
+    set: (dv, at, k, v) => set(dv, at + k * bytes, v),
+  }
+}
+
+function unormCodec(components: number, int: IntKind): FormatCodec {
+  return {
+    bytes: components * int.bytes,
+    components,
+    kind: "float",
+    get: (dv, at, k) => int.get(dv, at + k * int.bytes) / int.max,
+    set: (dv, at, k, v) => int.set(dv, at + k * int.bytes, Math.round(clamp(v, 0, 1) * int.max)),
+  }
+}
+
+function snormCodec(components: number, int: IntKind): FormatCodec {
+  return {
+    bytes: components * int.bytes,
+    components,
+    kind: "float",
+    get: (dv, at, k) => Math.max(int.get(dv, at + k * int.bytes) / int.max, -1),
+    set: (dv, at, k, v) => int.set(dv, at + k * int.bytes, Math.round(clamp(v, -1, 1) * int.max)),
+  }
+}
+
+function uintCodec(components: number, int: IntKind): FormatCodec {
+  return {
+    bytes: components * int.bytes,
+    components,
+    kind: "uint",
+    get: (dv, at, k) => int.get(dv, at + k * int.bytes),
+    set: (dv, at, k, v) => int.set(dv, at + k * int.bytes, Math.round(clamp(v, 0, int.max))),
+  }
+}
+
+function sintCodec(components: number, int: IntKind): FormatCodec {
+  return {
+    bytes: components * int.bytes,
+    components,
+    kind: "sint",
+    get: (dv, at, k) => int.get(dv, at + k * int.bytes),
+    set: (dv, at, k, v) => int.set(dv, at + k * int.bytes, Math.round(clamp(v, -int.max - 1, int.max))),
+  }
+}
+
+let getF32 = (dv: DataView, at: number) => dv.getFloat32(at, true)
+let setF32 = (dv: DataView, at: number, v: number) => dv.setFloat32(at, v, true)
+let getF16 = (dv: DataView, at: number) => dv.getFloat16(at, true)
+let setF16 = (dv: DataView, at: number, v: number) => dv.setFloat16(at, v, true)
+
+/** The vertex vocabulary: one codec per format (the engine's table in
+ * the same spelling), so it is also the list a declared format must be
+ * one of. A format feeds the shader `in` of its kind and component
+ * count (`formatFeeds`). */
+export const VERTEX_FORMATS: Record<VertexFormat, FormatCodec> = {
+  float32: floatCodec(1, Float32Array.BYTES_PER_ELEMENT, getF32, setF32),
+  float32x2: floatCodec(2, Float32Array.BYTES_PER_ELEMENT, getF32, setF32),
+  float32x3: floatCodec(3, Float32Array.BYTES_PER_ELEMENT, getF32, setF32),
+  float32x4: floatCodec(4, Float32Array.BYTES_PER_ELEMENT, getF32, setF32),
+  float16x2: floatCodec(2, Float16Array.BYTES_PER_ELEMENT, getF16, setF16),
+  float16x4: floatCodec(4, Float16Array.BYTES_PER_ELEMENT, getF16, setF16),
+  unorm8x4: unormCodec(4, U8),
+  snorm8x4: snormCodec(4, S8),
+  unorm16x2: unormCodec(2, U16),
+  unorm16x4: unormCodec(4, U16),
+  snorm16x2: snormCodec(2, S16),
+  snorm16x4: snormCodec(4, S16),
+  uint8x4: uintCodec(4, U8),
+  uint16x2: uintCodec(2, U16),
+  uint16x4: uintCodec(4, U16),
+  uint32: uintCodec(1, U32),
+  uint32x2: uintCodec(2, U32),
+  uint32x3: uintCodec(3, U32),
+  uint32x4: uintCodec(4, U32),
+  sint8x4: sintCodec(4, S8),
+  sint16x2: sintCodec(2, S16),
+  sint16x4: sintCodec(4, S16),
+  sint32: sintCodec(1, S32),
+  sint32x2: sintCodec(2, S32),
+  sint32x3: sintCodec(3, S32),
+  sint32x4: sintCodec(4, S32),
+}
+
+/** Whether a layout declaring `declared` may feed a program input the
+ * engine reflects as `reflected` (float32xN for `vec*`, uint32xN for
+ * `uvec*`, sint32xN for `ivec*`): same component count and same kind,
+ * the engine's own pipeline rule. */
+export function formatFeeds(declared: VertexFormat, reflected: VertexFormat): boolean {
+  let d = VERTEX_FORMATS[declared]
+  let r = VERTEX_FORMATS[reflected]
+  return d.components === r.components && d.kind === r.kind
+}
+
+/** Whether a format is one of the float32 family: what a Float32Array
+ * holds directly. */
+export function isFloatFormat(format: VertexFormat): boolean {
+  return format.startsWith("float32")
+}
+
+/** Bytes per record of an attribute list - its interleave stride. */
+export function layoutStride(layout: readonly VertexAttribute[]): number {
+  let stride = 0
+  for (let attr of layout) stride += VERTEX_FORMATS[attr.format].bytes
+  return stride
+}
+
+/** Values per record of an attribute list: its attributes' components
+ * summed - what a record written as a flat value list counts in. */
+export function layoutComponents(layout: readonly VertexAttribute[]): number {
+  let n = 0
+  for (let attr of layout) n += VERTEX_FORMATS[attr.format].components
+  return n
+}
+
+/** An attribute list's identity as a string (name:format per attribute,
+ * in order): two lists with equal keys interleave identically. */
+export function layoutKey(layout: readonly VertexAttribute[]): string {
+  return layout.map(a => a.name + ":" + a.format).join(",")
+}
+
+/** Where an attribute sits in the interleave: its byte offset, format
+ * and component count. Null when the list does not carry that name. */
+export function layoutSlot(layout: readonly VertexAttribute[], name: string): { offset: number; format: VertexFormat; components: number } | null {
+  let offset = 0
+  for (let attr of layout) {
+    let codec = VERTEX_FORMATS[attr.format]
+    if (attr.name === name) return { offset, format: attr.format, components: codec.components }
+    offset += codec.bytes
+  }
+  return null
+}
+
+/** Whether every attribute of a list is float32-family: such a buffer
+ * is a Float32Array of `layoutStride / 4` floats per record. */
+export function isFloatLayout(layout: readonly VertexAttribute[]): boolean {
+  return layout.every(a => isFloatFormat(a.format))
+}
+
+/** The check an attribute list must pass before it names a buffer: a
+ * known format on every attribute and no name twice. Throws naming
+ * `where` (the dev validation policy). */
+export function checkLayout(layout: readonly VertexAttribute[], where: string): void {
+  let seen = new Set<string>()
+  for (let attr of layout) {
+    if (!(attr.format in VERTEX_FORMATS)) {
+      throw new Error(where + ": unknown vertex format '" + String(attr.format) + "' for " + attr.name + " (expected " + Object.keys(VERTEX_FORMATS).join(", ") + ")")
+    }
+    if (seen.has(attr.name)) throw new Error(where + ": duplicate attribute '" + attr.name + "'")
+    seen.add(attr.name)
+  }
+}
+
+/** The bytes of a record buffer, whatever view holds them. */
+export function layoutBytes(records: ArrayBufferView): Uint8Array {
+  return new Uint8Array(records.buffer, records.byteOffset, records.byteLength)
+}
+
+/** The view a record buffer of `layout` is handed out as: a Float32Array
+ * over an all-float layout (indexable as floats), a Uint8Array over a
+ * layout with a packed channel. */
+export function layoutView(layout: readonly VertexAttribute[], buffer: ArrayBuffer, byteOffset = 0, byteLength = buffer.byteLength - byteOffset): ArrayBufferView {
+  return isFloatLayout(layout)
+    ? new Float32Array(buffer, byteOffset, byteLength / Float32Array.BYTES_PER_ELEMENT)
+    : new Uint8Array(buffer, byteOffset, byteLength)
+}
+
+/** A view on one attribute of a record buffer: component `k` of record
+ * `i`, read and written as the value the shader sees, through the
+ * format's codec. The one way anything touches record data, so no
+ * caller knows an offset, a stride or a format. */
+export type AttributeAccess = {
+  format: VertexFormat
+  components: number
+  get(i: number, k: number): number
+  set(i: number, k: number, v: number): void
+}
+
+/** The accessor for `name` over a bare record buffer of `layout`, bound
+ * to that buffer; null when the layout lacks the name. */
+export function attributeAccess(records: ArrayBufferView, layout: readonly VertexAttribute[], name: string): AttributeAccess | null {
+  let slot = layoutSlot(layout, name)
+  if (slot === null) return null
+  let stride = layoutStride(layout)
+  let codec = VERTEX_FORMATS[slot.format]
+  let offset = slot.offset
+  let dv = new DataView(records.buffer, records.byteOffset, records.byteLength)
+  return {
+    format: slot.format,
+    components: codec.components,
+    get: (i, k) => codec.get(dv, i * stride + offset, k),
+    set: (i, k, v) => codec.set(dv, i * stride + offset, k, v),
+  }
+}
+
+/** One accessor per attribute of `layout`, in order, reading through
+ * `view()` at every call - the form for a buffer that growth replaces:
+ * the accessors stay valid, the DataView behind them moves. */
+export function layoutFields(layout: readonly VertexAttribute[], view: () => DataView): AttributeAccess[] {
+  let stride = layoutStride(layout)
+  let offset = 0
+  return layout.map(attr => {
+    let codec = VERTEX_FORMATS[attr.format]
+    let at = offset
+    offset += codec.bytes
+    return {
+      format: attr.format,
+      components: codec.components,
+      get: (i, k) => codec.get(view(), i * stride + at, k),
+      set: (i, k, v) => codec.set(view(), i * stride + at, k, v),
+    }
+  })
+}
+
+/** Encode `values` (one per component, in layout order, as the shader
+ * sees them) into record `i` of a buffer: indexed float stores over an
+ * all-float layout given as `floats` (the values ARE the bytes; indexed
+ * stores beat TypedArray.set over a plain array under QuickJS, which
+ * walks the array-like generically), the accessors' codecs otherwise.
+ * Throws naming `site` on a value count that is not the layout's. */
+export function writeRecord(layout: readonly VertexAttribute[], fields: readonly AttributeAccess[], floats: Float32Array | null, i: number, values: ArrayLike<number>, site: string): void {
+  let n = layoutComponents(layout)
+  if (values.length !== n) throw new Error(site + ": a " + layoutKey(layout) + " record is " + n + " values, got " + values.length)
+  if (floats !== null) {
+    let at = i * n
+    for (let k = 0; k < n; k++) floats[at + k] = values[k]!
+    return
+  }
+  let j = 0
+  for (let f of fields) for (let k = 0; k < f.components; k++) f.set(i, k, values[j++]!)
+}
+
+/** One record of `layout` encoded from `values`: the bytes a blank slot
+ * copies (a material's fresh style record). */
+export function encodeRecord(layout: readonly VertexAttribute[], values: ArrayLike<number>, site: string): Uint8Array {
+  let buffer = new ArrayBuffer(layoutStride(layout))
+  let dv = new DataView(buffer)
+  let fields = layoutFields(layout, () => dv)
+  writeRecord(layout, fields, isFloatLayout(layout) ? new Float32Array(buffer) : null, 0, values, site)
+  return new Uint8Array(buffer)
+}

package/src/window.ts

@@ -1,5 +1,6 @@
 import { createSignal, getOwner, onCleanup, onSettled, runWithOwner, flush } from "@solidjs/signals"
 import { requestFrame, setPointerLock } from "flux:rendertree"
+import { startTransitions } from "flux:spatial"
 import { renderFrame } from "sol:render"
 import { on, once } from "sol:events"
 import { exit as nativeExit, background as nativeBackground, registerProtocolHandler as nativeRegisterProtocolHandler } from "sol:app"
@@ -470,7 +471,9 @@ export function onLayout(fn: () => void) {
 // The last JS of a frame, in two passes. The plain handlers are the app's
 // late update: they run once per frame after every onFrame callback and
 // the reactive flush, so a follow or a fit reads the finished state of the
-// frame (Unity's LateUpdate). The publish handlers run after them, and
+// frame (Unity's LateUpdate) - native motion stepped before the frame's
+// callbacks and started after them (runFrame), so a pose read here is the
+// one this frame draws. The publish handlers run after them, and
 // once more after the post-layout handlers' flush (the one other JS entry
 // ahead of the paint): an extension hands its pending writes to the engine
 // there - a scene's record bytes and lights, a layer's style and pose
@@ -527,7 +530,11 @@ export interface BeforeRenderOptions {
  * Calls `fn` right before every frame renders: after the frame's `onFrame`
  * callbacks and the reactive flush, when the frame's state is final. The
  * frame's late update: a camera follow, a fit to a measured box, anything
- * that must see what every frame callback wrote and write once more.
+ * that must see what every frame callback wrote and write once more. The
+ * engine's own motion (a clip player, a node transition) has stepped to
+ * this frame's pose before the frame's callbacks and started what they
+ * declared (an enter from its `from`) after them, so a follow of an
+ * animated node reads where it is drawn, not where it was.
  * Writes made here, to the engine or through signals, are in this frame:
  * the pending reactive writes are flushed once every handler has run.
  *
@@ -597,13 +604,15 @@ let backHandlers: ((e: BackEvent) => void)[] = []
 
 /**
  * Calls `fn` on the user's back intent (Android back button/gesture, the
- * desktop dev chord). Call `e.preventDefault()` when back means in-app
- * navigation right now (close a modal, previous screen); unprevented, the
- * event passes to the handler registered before this one, and if none of them
- * prevents it either, to the default action: what the platform does at the
- * root of an app - `background()` on Android, `exit()` elsewhere. Apps
- * without a handler get the platform's behavior, which is the correct
- * zero-effort default.
+ * pad's back button, the desktop dev chord). Call `e.preventDefault()` when
+ * back means in-app navigation right now (close a modal, previous screen);
+ * unprevented, the event passes to the handler registered before this one,
+ * and if none of them prevents it either, to the default action: what the
+ * platform does at the root of an app - `background()` on Android, `exit()`
+ * elsewhere. Apps without a handler get the platform's behavior, which is
+ * the correct zero-effort default. An Escape keydown that no key handler
+ * consumed (`stopPropagation`) runs the same stack without the default
+ * action: Escape closes the topmost overlay and never leaves the app.
  *
  * Handlers form a stack: the most recently registered runs first and the first
  * to prevent ends the dispatch, so each screen or overlay owns one step of the
@@ -641,6 +650,7 @@ export function setWindowRoot(nodeId: number) {
 export function attachWindow(nodeId: number) {
   setWindowRoot(nodeId)
   let unsubscribe: () => void = null!
+  let unsubFrameStart: () => void = null!
   let unsubDown: () => void = null!
   let unsubUp: () => void = null!
   let unsubCancel: () => void = null!
@@ -665,8 +675,10 @@ export function attachWindow(nodeId: number) {
   // (okf/done/onframe-tick-reset-on-reload.md). The callbacks stay
   // registered and run on the first real render event, before the first
   // paint with their writes applied.
+  // The frame's tick is stamped by "frameStart", ahead of this handler
+  // and of the engine's motion events (a clip's end, a settle), so a
+  // handler of those reads the frame's clock, not the last frame's.
   function runFrame(t: number, frame: number, bootstrap = false) {
-    if (!bootstrap) latestTick = t
     if (!bootstrap && animationFrames.size > 0) {
       let frames = animationFrames
       animationFrames = new Map()
@@ -679,6 +691,12 @@ export function attachWindow(nodeId: number) {
     } catch (err) {
       console.error("Error in reactive flush:", err)
     }
+    // The frame's start pass: the native motion the callbacks and the
+    // flush declared (a node created with an enter, one let go of with an
+    // exit) starts here, where Unity runs its animation update - after
+    // Update, before LateUpdate - so the late pass reads the pose the
+    // frame draws. The engine steps running motion before the callbacks.
+    startTransitions()
     runBeforeRender(bootstrap)
     scanForOrphans(t)
     renderFrame()
@@ -690,6 +708,9 @@ export function attachWindow(nodeId: number) {
       if (hz > 0) refreshRate = hz
     })
 
+    unsubFrameStart = on("frameStart", ({ time }: { time: number; frame: number }) => {
+      latestTick = time * 1000
+    })
     unsubscribe = on("render", ({ time, frame }: { time: number; frame: number }) => {
       runFrame(time * 1000, frame)
     })
@@ -787,13 +808,33 @@ export function attachWindow(nodeId: number) {
       }
     })
 
+    // The back stack: top down, stopping at the first handler that prevents.
+    // The native triggers (the Android button, the pad's back, the dev chord)
+    // carry the platform default when none does; an unconsumed Escape runs
+    // the same stack without it, since Escape closes what is open and never
+    // leaves the app.
+    let dispatchBack = (platformDefault: boolean) => {
+      let prevented = false
+      let e: BackEvent = {
+        preventDefault: () => {
+          prevented = true
+        },
+      }
+      // Copy first: a handler may unregister (itself or others) mid-dispatch.
+      let stack = [...backHandlers]
+      for (let i = stack.length - 1; i >= 0 && !prevented; i--) stack[i]!(e)
+      if (!prevented && platformDefault) backDefault()
+    }
+
     // Key events dispatch along the focused node's ancestor chain, leaf->root
     // (the pointer bubbling contract), so a container hears keys from focused
     // descendants and the window root hears everything: <window onKeyDown> is
     // the app-global shortcut point. With nothing focused the path is the
     // window root alone - key events are never dropped. The path is resolved
     // at dispatch time from current focus (nothing to freeze: keyup follows
-    // focus, as in the DOM).
+    // focus, as in the DOM). An Escape keydown that reaches the end of the
+    // chain unconsumed is a back: the web's own default action for the key
+    // (closing a dialog), which a handler suppresses with stopPropagation.
     let dispatchKey = (raw: any, handler: string) => {
       let target = focusedNode() ?? windowRootId
       let stopped = false
@@ -807,25 +848,14 @@ export function attachWindow(nodeId: number) {
         getEventHandler(id, handler)?.(e)
         if (stopped) break
       }
+      if (!stopped && handler === "onKeyDown" && e.key === "Escape") dispatchBack(false)
     }
 
     unsubKeyDown = on("keydown", (raw: any) => dispatchKey(raw, "onKeyDown"))
 
     unsubKeyUp = on("keyup", (raw: any) => dispatchKey(raw, "onKeyUp"))
 
-    unsubBack = on("back", () => {
-      let prevented = false
-      let e: BackEvent = {
-        preventDefault: () => {
-          prevented = true
-        },
-      }
-      // Copy first: a handler may unregister (itself or others) mid-dispatch.
-      // Top of the stack down, stopping as soon as one takes the event.
-      let stack = [...backHandlers]
-      for (let i = stack.length - 1; i >= 0 && !prevented; i--) stack[i]!(e)
-      if (!prevented) backDefault()
-    })
+    unsubBack = on("back", () => dispatchBack(true))
 
     unsubTextInput = on("textInput", (e: any) => {
       let id = focusedNode()
@@ -855,6 +885,7 @@ export function attachWindow(nodeId: number) {
   onCleanup(() => {
     setInterestRoot(null)
     if (unsubscribe) unsubscribe()
+    if (unsubFrameStart) unsubFrameStart()
     if (unsubDown) unsubDown()
     if (unsubUp) unsubUp()
     if (unsubCancel) unsubCancel()