@solidrt/core 0.0.50 → 0.0.52

package/src/types.d.ts

@@ -2,7 +2,7 @@
 /// <reference path="./runtime-modules.d.ts" />
 
 import type { Gradient } from "./color"
-import type { ProgramId, TextureId } from "flux:gpu"
+import type { ProgramId, TextureBindings, TextureId } from "flux:gpu"
 import type { TextInputHints } from "flux:rendertree"
 import type { Element } from "solid-js"
 
@@ -155,6 +155,7 @@ export interface PaintProps {
   // A solid color, or a gradient from createLinearGradient/createRadialGradient.
   color?: Color | Gradient
   blendMode?: "clear" | "source" | "destination" | "source-over" | "destination-over" | "source-in" | "destination-in" | "source-out" | "destination-out" | "source-atop" | "destination-atop" | "xor" | "plus" | "modulate" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "multiply" | "hue" | "saturation" | "color" | "luminosity"
+  /** Default "fill"; "stroke" on line, whose segment has no interior (see LineProps). */
   drawStyle?: "fill" | "stroke" | "stroke-and-fill"
   strokeCap?: "butt" | "round" | "square"
   strokeJoin?: "miter" | "round" | "bevel"
@@ -236,6 +237,14 @@ export interface PointerEvent {
    */
   parentX: number
   parentY: number
+  /**
+   * Pointer movement since the previous move event, in logical pixels. Mouse
+   * reports hardware deltas (summed, never lost, and the only motion signal
+   * while the pointer is locked); touch reports position diffs. 0 on
+   * non-move events.
+   */
+  movementX: number
+  movementY: number
   /** Node id whose handler is currently running (bubbling changes it per call). */
   currentTarget: number
   /** Deepest node id of the event's path (the hit leaf). */
@@ -357,7 +366,12 @@ export interface TextGeometryProps extends PositionProps {
   h?: number
 }
 
-/** See {@link PositionProps}: detached-only, never affects layout. */
+/**
+ * See {@link PositionProps}: detached-only, never affects layout. A line's
+ * reported bounds (getBoundingBox, the tree, a detached capture) are its
+ * painted box: the geometry's extent plus the stroke's reach, not the
+ * inherited box.
+ */
 export interface LineGeometryProps {
   /** Endpoints default to spanning the box: (0,0) to (box width, box height). */
   x1?: number
@@ -366,6 +380,167 @@ export interface LineGeometryProps {
   y2?: number
 }
 
+// Native transitions (okf/done/native-transitions.md): declared once on
+// the element, applied by the runtime to every later write of the covered
+// properties. JS hands over targets; Rust interpolates every frame, so a
+// running animation costs no JS per frame.
+
+/** A cubic-bezier timing curve: a CSS name or [x1, y1, x2, y2] control values. */
+export type TransitionCurve = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | [number, number, number, number]
+
+/**
+ * A perceptual spring - the default kind: a bare `{ duration }` is a
+ * critically damped spring. `duration` (ms) is the perceptual settling
+ * time, `bounce` in (-1, 1] the springiness - 0 (the default) settles
+ * without overshoot, positive values overshoot, negative values settle
+ * sluggishly. A new target while the spring runs keeps position and
+ * velocity, so the motion stays continuous - use springs for anything
+ * retargeted while moving.
+ */
+export interface TransitionSpring {
+  duration: number
+  bounce?: number
+  /** Hold each write for this long (ms) before it applies; a newer write during the hold replaces it and restarts the delay. */
+  delay?: number
+  /**
+   * Mount-time enter animation: at the element's first attach the property
+   * snaps to this value and animates to the value it mounted with. Numbers
+   * for the scalar properties; the color property takes a CSS color string
+   * or packed number. Per-property entries only (not under `all`); a later
+   * move or reorder re-runs nothing.
+   */
+  from?: number | string
+  /**
+   * Removal exit animation: an unmounted element stays visible, animates
+   * the property to this value (honoring `delay`), and is freed when its
+   * exit animations settle. Same value forms as `from`, per-property only.
+   * A move never plays it, the exiting element is hit-test invisible, its
+   * whole subtree stays painted with it, and no onTransitionEnd fires (the
+   * component is already disposed). An attached element keeps its layout
+   * slot until the exit finishes.
+   */
+  exit?: number | string
+}
+
+/**
+ * A duration/curve tween, opted into by naming the curve (a tween is
+ * always a specific curve; without one the spec reads as a spring).
+ * Duration in ms. A new target while the tween runs restarts it from the
+ * current value with the full duration (CSS semantics) - designer-timed,
+ * one-shot motion.
+ */
+export interface TransitionTween {
+  duration: number
+  curve: TransitionCurve
+  /** Hold each write for this long (ms) before it applies; a newer write during the hold replaces it and restarts the delay. */
+  delay?: number
+  /**
+   * Mount-time enter animation: at the element's first attach the property
+   * snaps to this value and animates to the value it mounted with. Numbers
+   * for the scalar properties; the color property takes a CSS color string
+   * or packed number. Per-property entries only (not under `all`); a later
+   * move or reorder re-runs nothing.
+   */
+  from?: number | string
+  /**
+   * Removal exit animation: an unmounted element stays visible, animates
+   * the property to this value (honoring `delay`), and is freed when its
+   * exit animations settle. Same value forms as `from`, per-property only.
+   * A move never plays it, the exiting element is hit-test invisible, its
+   * whole subtree stays painted with it, and no onTransitionEnd fires (the
+   * component is already disposed). An attached element keeps its layout
+   * slot until the exit finishes.
+   */
+  exit?: number | string
+}
+
+/**
+ * The shorthand string: `"<duration>ms [curve] [<delay>ms]"` - `"300ms"` is
+ * a bounce-0 spring, `"300ms ease-out"` a tween, `"300ms ease-out 100ms"`
+ * delayed (first time value the duration, second the delay; ms only).
+ * Bounce, bezier control values and `from` need the object form.
+ */
+export type TransitionShorthand = string
+
+export type Transition = TransitionSpring | TransitionTween | TransitionShorthand
+
+/** The property names a transition can cover (numeric scalars). */
+export type TransitionPropName =
+  | "x"
+  | "y"
+  | "w"
+  | "h"
+  | "x1"
+  | "y1"
+  | "x2"
+  | "y2"
+  | "scrollX"
+  | "scrollY"
+  | "opacity"
+  | "originX"
+  | "originY"
+  | "perspective"
+  | "clipRadius"
+  | "srcX"
+  | "srcY"
+  | "srcW"
+  | "srcH"
+  | "onLength"
+  | "offLength"
+  | "dashOffset"
+  | "rotate"
+  | "rotateX"
+  | "rotateY"
+  | "scale"
+  | "scaleX"
+  | "scaleY"
+  | "strokeWidth"
+  | "radius"
+  | "color"
+
+/** Payload of onTransitionEnd: which animated property finished. */
+export interface TransitionEndEvent {
+  property: TransitionPropName
+}
+
+export interface TransitionProps {
+  /**
+   * A runtime-side transition of one of this element's properties reached
+   * its target (natural settles only; a cancelled or retargeted animation
+   * does not fire until it finally settles). Delivered to this element
+   * only, no bubbling.
+   */
+  onTransitionEnd?: (event: TransitionEndEvent) => void
+  /**
+   * Animate later writes of the listed properties instead of snapping:
+   * `transition={{ x: { duration: 400, bounce: 0.2 }, opacity: "200ms ease-out" }}`.
+   * `all` covers every animatable property the element has, and a bare
+   * string is shorthand for it: `transition="300ms ease-out"`. Only
+   * properties the element carries animate (a d-rect has x, a view's x is
+   * its transform); the initial value never animates unless the entry sets
+   * `from` (an enter animation), and a non-numeric write (e.g. null)
+   * cancels the running animation and snaps. `null` clears the
+   * declaration; already-running animations finish.
+   */
+  transition?:
+    | ({
+        all?: Omit<TransitionSpring, "from" | "exit"> | Omit<TransitionTween, "from" | "exit"> | TransitionShorthand
+        /**
+         * Group stagger (ms): every descendant enter (`from`) or exit that
+         * begins in the same frame under this element gets `index * stagger`
+         * of extra delay, in occurrence order (enters and exits cascade
+         * separately). Nearest declaring ancestor wins; it orchestrates
+         * descendants only - ordinary writes and this element's own
+         * lifecycle are unaffected. Adds on top of a per-entry `delay`.
+         */
+        stagger?: number
+      } & {
+        [P in TransitionPropName]?: Transition
+      })
+    | TransitionShorthand
+    | null
+}
+
 // Primitives
 
 export interface WindowProps extends LayoutProps, PointerProps {
@@ -402,8 +577,8 @@ export interface WindowShaderProps {
    * type: 2/3/4 for `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`.
    */
   params?: Record<string, number | number[]>
-  /** Extra sampler2D inputs: uniform name to texture id. */
-  textures?: Record<string, TextureId>
+  /** Extra sampler2D inputs: uniform name to texture id, or `{ id, filter?, wrap? }` for a per-binding sampling override. */
+  textures?: TextureBindings
   /** Vertices drawn (attributeless triangles). Default 3, the covering triangle. */
   vertexCount?: number
   /**
@@ -424,18 +599,28 @@ export interface ViewOwnProps extends TransformProps, PointerProps {
   children?: Children
   trace?: boolean
   /**
-   * Design-space size `[w, h]` for the children: content drawn in that
-   * coordinate space is uniformly scaled to fit and centered in the element's
-   * box (SVG's default preserveAspectRatio, generalized). A pure fit
-   * transform - it never sizes the element, so give the box its size with
-   * layout props. Composed innermost: the transform props still operate in
-   * box space, and pointer events on children arrive in design coordinates.
-   * The overflow clip and scrollX/scrollY stay box properties too: the clip
-   * rect is the layout box and scroll offsets are box pixels, regardless of
-   * fit scale. The natural wrapper for parseSvg draws, or any d-* subtree
-   * authored in fixed design units.
+   * Design-space size `[w, h]` (both positive) for the children: everything
+   * under the view - layout, paint, input - happens in that coordinate space,
+   * which is uniformly scaled to fit and centered in the element's box (SVG's
+   * viewBox with its default preserveAspectRatio, generalized off the graphics
+   * format and onto a layout element; the fit is always "contain"). Laid-out
+   * children resolve flex, percentages and text wrapping against the design
+   * size, so a subtree scales into any box without reflowing. The view itself
+   * sizes like a replaced element: its intrinsic size is the design size, one
+   * sized axis derives the other from the design aspect, layout props
+   * override, and it always shrinks to fit (its min-content size is zero). As
+   * a flex item it still stretches like any other under the default alignment:
+   * a width-only design-size view in a row takes the line's height, not the
+   * design height, unless the row's alignItems or its own alignSelf is not
+   * "stretch" (CSS's rule for an <img> in a flex row). Composed innermost: the
+   * transform props still operate in box space, and pointer events on children
+   * arrive in design coordinates. The overflow clip and scrollX/scrollY stay
+   * box properties: the clip rect is the layout box and scroll offsets are box
+   * pixels, regardless of fit scale. The natural wrapper for parseSvg draws,
+   * any d-* subtree authored in fixed design units, or a whole panel that
+   * should scale rather than reflow.
    */
-  viewBox?: [number, number]
+  designSize?: [number, number]
   /**
    * Corner radii for the clip applied when overflow is non-visible (hidden,
    * clip, scroll on both axes). A single number rounds all four corners; an
@@ -458,13 +643,17 @@ export interface ViewOwnProps extends TransformProps, PointerProps {
    * (no multisampled scratch, one render pass), but vector content - svg
    * paths, rounded corners, rotated edges - comes out hard-edged. Text and
    * axis-aligned rects look identical, so prefer it for plain UI panels.
+   *
+   * A snapshot boundary's pixels are available to the GPU stack as a live
+   * texture id through `snapshotTexture(ref)`.
    */
   repaintBoundary?: boolean | "snapshot" | "snapshot-no-aa"
   /**
    * Run this view's rasterized subtree through a GPU program and composite
-   * the result in its place. Requires repaintBoundary="snapshot" (the cost
-   * is snapshot semantics, kept explicit; declared without it the shader is
-   * ignored with a warning). The pass is region-sized and split from content
+   * the result in its place. Requires a snapshot boundary
+   * (repaintBoundary="snapshot" or "snapshot-no-aa"; the cost is snapshot
+   * semantics, kept explicit; declared without one the shader is ignored
+   * with a warning). The pass is region-sized and split from content
    * invalidation: a params-only change re-runs just the pass against the
    * cached snapshot, so animating an effect over a static subtree never
    * re-rasterizes it.
@@ -496,8 +685,8 @@ export interface ViewShaderProps {
    * type: 2/3/4 for `vec2`/`vec3`/`vec4`, 16 (column-major) for `mat4`.
    */
   params?: Record<string, number | number[]>
-  /** Extra sampler2D inputs: uniform name to texture id. */
-  textures?: Record<string, TextureId>
+  /** Extra sampler2D inputs: uniform name to texture id, or `{ id, filter?, wrap? }` for a per-binding sampling override. */
+  textures?: TextureBindings
   /**
    * Transparent margin in logical px on every side of the layout box, for
    * the effect to write into - glow, drop shadow, blur that bleeds past the
@@ -541,21 +730,81 @@ export interface RectProps extends PaintProps, PointerProps {
 // Strokes paint inside the box, same as `RectProps`.
 export interface OvalProps extends PaintProps, PointerProps {}
 
-// A line's geometry is numbers, not a path string: the segment primitive to
-// reach for when endpoints move (each endpoint is one property write; a path
-// animates by rebuilding its `d` string). Endpoints (x1/y1/x2/y2) exist on
-// the detached `d-line` only. A laid-out `<line>` is practically a rule -
-// give it a thin box (length x strokeWidth); in general it draws its layout
-// box's top-left-to-bottom-right diagonal. For arbitrary angles and
-// connectors use `d-line`; for polylines and curves, a path.
-export interface LineProps extends PaintProps, PointerProps {
-  /** Dash pattern in local units: the drawn segment length. Both onLength and offLength must be set to dash; with either unset the line is solid. */
+/**
+ * A stroke's dash pattern, on `line` and `path`. Both lengths must be set
+ * to dash; with either unset, or a gap of 0, the stroke is solid.
+ */
+export interface DashProps {
+  /**
+   * The drawn length, in local units. The pattern runs continuously along
+   * the geometry - through a polyline's vertices and along a path's curves,
+   * restarting at each subpath of a path; 0 draws a dot per period (given
+   * round or square caps).
+   */
   onLength?: number
-  /** Dash pattern in local units: the gap length. Both onLength and offLength must be set to dash; with either unset the line is solid. */
+  /** The gap length, in local units. */
   offLength?: number
+  /**
+   * Distance into the dash pattern at which the stroke starts, in local
+   * units (SVG stroke-dashoffset). Wraps around the pattern's period;
+   * negative values allowed. Raising it marches the dashes toward the
+   * geometry's start: write it every frame for marching ants, or transition
+   * it for a one-shot slide. Default 0.
+   */
+  dashOffset?: number
+  /**
+   * What the geometry's length counts as, in the pattern's units (SVG
+   * pathLength): when set, `onLength`, `offLength` and `dashOffset` are
+   * scaled by the actual length over it. `pathLength={1}` makes them
+   * fractions: `onLength={0.77} offLength={1}` draws the first 77%, and
+   * transitioning `onLength` from 0 to 1 draws the geometry on. Must be
+   * positive; unset, the pattern is in local units.
+   */
+  pathLength?: number
 }
 
-export interface PathProps extends PaintProps, PointerProps {
+// A line's geometry is numbers, not a path string: the primitive to reach
+// for when the geometry moves (each endpoint is one property write, a
+// polyline is one array write; a path animates by rebuilding its `d` string).
+// Two forms: the segment, whose endpoints (x1/y1/x2/y2) exist on the
+// detached `d-line` only, and the polyline (`points`), which exists on both.
+// A laid-out `<line>` without points is practically a rule - give it a thin
+// box (length x strokeWidth); in general it draws its layout box's
+// top-left-to-bottom-right diagonal. For arbitrary angles and connectors use
+// `d-line`; for curves, a path. A line's stroke is centered on its geometry,
+// so it straddles the box (a rect's paints inside), and the bounds it
+// reports are the painted box: geometry plus stroke, on both forms.
+//
+// The paint defaults to `drawStyle="stroke"` (the box primitives default to
+// 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 {
+  /**
+   * 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
+   * set. Content, not box geometry: a laid-out <line points> measures its
+   * box from the points' extent, like a <path> from `d`, and draws them
+   * unscaled. Fewer than two points draws nothing; an odd count throws. Not
+   * covered by transitions: animate by writing a new array.
+   */
+  points?: number[] | Float32Array | Float64Array
+  /**
+   * Close the polyline's stroke: the segment back to the first point, joined
+   * there instead of capped. A fill always covers the polygon (closed
+   * implicitly), so this is a stroke distinction. Default false.
+   */
+  closed?: boolean
+}
+
+/**
+ * `d` is an SVG path string; the stroke is centered on the geometry. The
+ * bounds a path reports (getBoundingBox, the tree, a detached capture) are
+ * its painted box: the geometry's tight extent (curve extrema, not control
+ * 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 {
   d?: string
   fillRule?: "nonzero" | "evenodd"
 }
@@ -576,6 +825,17 @@ export interface TextRunProps {
   lineHeight?: number
   fontStyle?: "normal" | "italic"
   fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+  /**
+   * Underline in the run's own color, drawn straight through descenders
+   * (no skip-ink). Position and thickness come from the font's own metrics
+   * unless overridden; a font Impeller resolves through the system fallback
+   * gets the shipped Noto values.
+   */
+  textDecoration?: "none" | "underline"
+  /** Pixels from the baseline to the top of the underline. */
+  textUnderlineOffset?: number
+  /** Underline thickness in pixels. */
+  textDecorationThickness?: number
 }
 
 /**

package/src/window.ts

@@ -1,5 +1,5 @@
 import { createSignal, onCleanup, onSettled, flush } from "@solidjs/signals"
-import { requestFrame } from "flux:rendertree"
+import { requestFrame, setPointerLock } from "flux:rendertree"
 import { renderFrame } from "srt:render"
 import { on, once } from "srt:events"
 import { exit } from "srt:app"
@@ -38,9 +38,12 @@ let refreshRate = 60
  * the present count, and `rate` is the current refresh rate in Hz. `tick` is paced
  * by the runtime (one refresh period per present, slow-corrected toward the wall
  * clock) so animations driven off it stay smooth even when swap-return times
- * jitter. performance.now() and timers report/march on this same paced timeline
- * (so the whole time surface freezes together under the dev tools' clock
- * control); for real wall-clock time use Date.now().
+ * jitter, and it is continuous across hot reloads: every tick an instance
+ * sees is on one timebase, so dt is well-defined from the second call on.
+ * Timers freeze together with frame callbacks under the dev tools' clock
+ * control, but measure their delays against the wall clock, not this paced
+ * timeline. performance.now() is not on it either: it is real elapsed time
+ * for measuring work; Date.now() is calendar time.
  * Returns a cleanup function; also auto-cleans within a reactive scope.
  */
 export function onFrame(fn: (tick: number, frame: number, rate: number) => void) {
@@ -161,6 +164,33 @@ export function windowFocused(): boolean {
   return focusedAccessor()
 }
 
+/**
+ * Lock the pointer to the window (relative mouse mode) or release it. While
+ * locked the cursor is hidden and confined, clientX/clientY freeze at the
+ * lock point, and mouse motion keeps reporting through the pointer events'
+ * movementX/movementY - the mouse-look primitive. Window-level, no
+ * permission dance: one app, one window. Observe the applied state through
+ * pointerLocked(); the platform can refuse (no relative mode) and the OS
+ * may drop the lock, e.g. on focus loss.
+ */
+export function lockPointer(locked: boolean) {
+  if (typeof locked !== "boolean") throw new Error(`lockPointer: expected a boolean, got ${typeof locked}`)
+  setPointerLock(locked)
+}
+
+let pointerLockedAccessor: (() => boolean) | undefined
+
+/** Whether the pointer is currently locked (relative mouse mode), as a reactive accessor. */
+export function pointerLocked(): boolean {
+  if (!pointerLockedAccessor) {
+    let [locked, setLocked] = createSignal(false)
+    // Sticky event: a subscriber after the lock still observes the state.
+    on("pointerLock", ({ locked }: { locked: boolean }) => setLocked(locked))
+    pointerLockedAccessor = locked
+  }
+  return pointerLockedAccessor()
+}
+
 let keyboardHeightAccessor: (() => number) | undefined
 
 /**
@@ -178,14 +208,49 @@ export function keyboardHeight(): number {
   return keyboardHeightAccessor()
 }
 
+// Post-layout handlers run in registration order from one bus subscription,
+// then pending reactive writes are flushed once. The postLayout emit is a JS
+// entry inside the frame (layout has run, paint has not), and the runtime's
+// microtask checkpoint only comes after the whole frame closure, so a signal
+// write made by a handler would otherwise reach its node a frame late. The
+// drain lives here, the way runFrame drains before renderFrame, so that no
+// handler has to flush for itself. A throwing handler skips neither the
+// handlers after it nor the flush.
+let layoutHandlers: (() => void)[] = []
+let layoutSubscribed = false
+
+function runLayoutHandlers() {
+  for (let fn of [...layoutHandlers]) {
+    try {
+      fn()
+    } catch (err) {
+      console.error("Error in onLayout handler:", err)
+    }
+  }
+  try {
+    flush()
+  } catch (err) {
+    console.error("Error in reactive flush:", err)
+  }
+}
+
 /**
  * Fires after layout has been computed for the current frame but before paint.
- * Setting properties that affect layout from this callback will be picked up
- * by a re-layout pass before painting (one extra pass; cascades beyond that
- * paint stale).
+ * Property writes made from this callback, direct or through signals (pending
+ * reactive writes are flushed once every handler has run), are picked up by a
+ * re-layout pass before painting (one extra pass; cascades beyond that paint
+ * stale).
  */
 export function onLayout(fn: () => void) {
-  let unsubscribe = on("postLayout", fn)
+  if (!layoutSubscribed) {
+    layoutSubscribed = true
+    on("postLayout", runLayoutHandlers)
+  }
+  layoutHandlers.push(fn)
+  let unsubscribe = () => {
+    let i = layoutHandlers.indexOf(fn)
+    if (i >= 0) layoutHandlers.splice(i, 1)
+  }
   onCleanup(unsubscribe)
   return unsubscribe
 }
@@ -244,10 +309,20 @@ export function onBack(fn: (e: BackEvent) => void) {
 
 // ------ Window ----------------
 
-export function attachWindow(nodeId: number) {
+// The window root's id: the key-routing fallback target and the pointer
+// interest root. Set by attachWindow, moved by setWindowRoot when render()'s
+// error boundary swaps the app's window for the error window and back.
+let windowRootId = 0
+
+export function setWindowRoot(nodeId: number) {
+  windowRootId = nodeId
   // The root carries the ambient move-interest bit for global onPointerMove
   // subscribers (it is on every hit path); see core.setInterestRoot.
   setInterestRoot(nodeId)
+}
+
+export function attachWindow(nodeId: number) {
+  setWindowRoot(nodeId)
   let unsubscribe: () => void = null!
   let unsubDown: () => void = null!
   let unsubUp: () => void = null!
@@ -255,6 +330,7 @@ export function attachWindow(nodeId: number) {
   let unsubEnter: () => void = null!
   let unsubLeave: () => void = null!
   let unsubWheel: () => void = null!
+  let unsubTransitionEnd: () => void = null!
   let unsubKeyDown: () => void = null!
   let unsubKeyUp: () => void = null!
   let unsubBack: () => void = null!
@@ -263,8 +339,16 @@ export function attachWindow(nodeId: number) {
   let unsubRefreshRate: () => void = null!
   let unsubFirstResize: (() => void) | null = null
 
-  function runFrame(t: number, frame: number) {
-    if (animationFrames.size > 0) {
+  // `bootstrap` marks the synthetic first frame (see the first-resize
+  // subscription below): it flushes and paints the freshly initialized graph
+  // but does not invoke onFrame callbacks, because its timestamp is not a
+  // reading of the frame timeline - handing apps a zero tick gave every
+  // reloaded instance one enormous dt on the next real frame
+  // (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.
+  function runFrame(t: number, frame: number, bootstrap = false) {
+    if (!bootstrap && animationFrames.size > 0) {
       let frames = animationFrames
       animationFrames = new Map()
       for (let fn of frames.values()) fn(t, frame, refreshRate)
@@ -368,6 +452,17 @@ export function attachWindow(nodeId: number) {
       bubble(raw, "onWheel")
     })
 
+    // A native transition finished (runtime-side animation; see the
+    // `transition` prop). Target-only delivery, no bubbling: the element
+    // that declared the transition is the one interested in its end.
+    unsubTransitionEnd = on("transitionEnd", (raw: { target: number; property: string }) => {
+      try {
+        getEventHandler(raw.target, "onTransitionEnd")?.({ property: raw.property })
+      } catch (err) {
+        console.error("Error in onTransitionEnd handler:", err)
+      }
+    })
+
     // 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
@@ -376,13 +471,13 @@ export function attachWindow(nodeId: number) {
     // at dispatch time from current focus (nothing to freeze: keyup follows
     // focus, as in the DOM).
     let dispatchKey = (raw: any, handler: string) => {
-      let target = focusedNode() ?? nodeId
+      let target = focusedNode() ?? windowRootId
       let stopped = false
       let e = { ...raw, target, stopPropagation: () => (stopped = true) }
       let path = getNodePath(target)
       // A focused node detached this tick has no chain to the root; the
       // window root must still hear the key.
-      if (path[path.length - 1] !== nodeId) path.push(nodeId)
+      if (path[path.length - 1] !== windowRootId) path.push(windowRootId)
       for (let id of path) {
         e.currentTarget = id
         getEventHandler(id, handler)?.(e)
@@ -429,7 +524,7 @@ export function attachWindow(nodeId: number) {
     // where flush() is illegal (not reentrant). Defer runFrame to a microtask
     // so the first frame always runs after this callback returns.
     unsubFirstResize = once("resize", () => {
-      queueMicrotask(() => runFrame(0, 0))
+      queueMicrotask(() => runFrame(0, 0, true))
     })
   })
 
@@ -442,6 +537,7 @@ export function attachWindow(nodeId: number) {
     if (unsubEnter) unsubEnter()
     if (unsubLeave) unsubLeave()
     if (unsubWheel) unsubWheel()
+    if (unsubTransitionEnd) unsubTransitionEnd()
     if (unsubKeyDown) unsubKeyDown()
     if (unsubKeyUp) unsubKeyUp()
     if (unsubBack) unsubBack()