@solidrt/core 0.0.66 → 0.0.68

package/AGENTS.md

@@ -138,9 +138,9 @@ that reads exactly like Solid fallout.
   window (message, stack, a Reset button that retries the failed
   computations) and logs `Uncaught error`. `<Errored>` gives a subtree its
   own in-place fallback.
-  An `onFrame` callback is its own boundary, event-listener style: a throw
-  is caught and logged (`Error in onFrame callback`, repeating every
-  frame), the subscription stays, and THE REST OF THAT CALLBACK IS
+  An `onFrame` (or `onBeforeRender`) callback is its own boundary,
+  event-listener style: a throw is caught and logged (`Error in onFrame
+  callback`, repeating every frame), the subscription stays, and THE REST OF THAT CALLBACK IS
   ABANDONED - what it wrote before the throw lands, what came after never
   does, frame after frame while the app keeps presenting. A partial frame
   is therefore a live possibility: every sprite drawn after the throwing
@@ -613,7 +613,17 @@ that reads exactly like Solid fallout.
   `onFrame(fn, { demand: false })` is the same hook without the standing
   frame request: it runs on every frame the runtime delivers and the app
   presents only when the body writes, for a loop that follows time but
-  seldom changes the picture. `frameTime()` is the current frame's `tick`
+  seldom changes the picture. `onBeforeRender(fn)` is the frame's late
+  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, {
+  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
+  layer its style and count), so a write made anywhere in the frame's JS
+  is in that frame's picture, never the next. `frameTime()` is the current frame's `tick`
   read from anywhere (not reactive, requests nothing): the app's own
   clock for code with no tick in hand, where `performance.now()` would
   ignore the dev clock, `sol render` and tests. A JS

package/agents/performance.md

@@ -151,27 +151,29 @@ Rules, in order of leverage:
    snapshot instead of re-rasterizing. A window shader's output is invisible
    to get_snapshot and every other MCP tool; `bun run sol render` is the only
    way to see it (see @solidrt/cli AGENTS.md).
-8. `flux:wasm` runs a pure interpreter (wasmi, no JIT), so temper browser
-   expectations - but do not write it off for compute. A genuinely numeric
-   kernel (typed-array math, tight inner loops, no host calls inside the
-   loop) compiled from a systems language can come out a real multiple
-   faster than the same loop in interpreted JavaScript, and when profiling
-   shows such a kernel is what the app is spending its time on, that
-   multiple is worth having: measure the JS loop, port the kernel, measure
-   again, keep whichever wins. What wasm does not do is speed up
-   render-path work (rules 1-3 are that leverage), and every host call
-   costs marshalling, so batch at the boundary - one call over a byte
-   buffer, not a call per element. It is also the way to ship one compiled
-   module across every target with no native toolchain, and it pairs with
-   an isolate when a call runs long enough to block.
-9. `flux:ffi` (dlopen of a native library) is a binding tool, not a
-   performance tool. It needs a shared library compiled per platform and
-   architecture and shipped under each target's packing rules (Android
-   loads only what arrives inside the APK as a lib*.so), so reaching for
-   it "to make something fast" buys a build-and-packaging problem on every
-   platform the app targets. Use it when the app must call a native
-   library that already exists and already ships for those targets; for
-   speed, everything above comes first.
+8. `flux:wasm` compiles a module to machine code on devices that allow it
+   (`Flux.capabilities` lists `wasm-native`: desktop, 64-bit Android) and
+   interprets it elsewhere (iOS, 32-bit Android). Both lanes are the fast
+   lane for compute: measured on a desktop, an arm64 tablet and a 32-bit
+   TV, a numeric kernel (typed-array math, tight inner loops, no host calls
+   inside the loop) runs 18x to 960x faster than the same loop in
+   JavaScript when compiled and 4x to 88x when interpreted, float at the low
+   end, integer and SIMD-shaped loops at the high end. So when profiling
+   shows such a kernel is where the app spends its time, port it: measure
+   the JS loop, port the kernel, measure again, keep whichever wins. The
+   boundary is the cost, not the code: a host call out of the module costs
+   3x to 7x a plain JavaScript call, two to three hundred iterations of a
+   tight loop, so batch at the boundary - one call per frame over a byte
+   buffer, never a call per element. What wasm does not do is speed up
+   render-path work (rules 1-3 are that leverage). It is also the way to
+   ship one compiled module across every target with no native toolchain,
+   and it pairs with an isolate when a call runs long enough to block.
+9. There is no native-library route from app code. A shared library is
+   compiled per platform, so it cannot travel in a portable app payload,
+   and Android loads only what arrived inside the APK. Binding one is a
+   custom runtime build: the runtime crates with the library registered
+   beside the built-in modules. For speed, everything above comes first;
+   for a proven library that has a wasm build, rule 8.
 10. Text costs shaping, once per word per style, through a shared word cache;
    line breaking is arithmetic over the shaped words. So re-breaking text
    every frame with prepareText + layoutNextLine (a shape that breathes, an
@@ -188,7 +190,7 @@ Rules, in order of leverage:
 ## Isolates: heavy work off the JS thread
 
 A long synchronous computation (a big parse, a simulation step, a blocking
-`flux:ffi`/`flux:wasm` call) freezes rendering and input for its duration.
+`flux:wasm` call) freezes rendering and input for its duration.
 Move it into an isolate module: a file whose first statement is the
 `"use isolate"` directive runs in a second runtime on its own thread, and
 main calls its exports as async functions.

package/docs/index.md

@@ -91,9 +91,13 @@ ancestor with `position="relative"`.
 ## Input
 
 Pointer, wheel, and key events are props on any element:
-`onPointerDown`, `onPointerMove`, `onPointerUp`, `onPointerEnter`,
-`onPointerLeave`, `onWheel`, `onKeyDown`, `onKeyUp`. Events travel from the
-hit leaf up to the root, and `stopPropagation()` ends the walk. Key events
+`onPointerDown`, `onPointerMove`, `onPointerUp`, `onPointerCancel`,
+`onPointerEnter`, `onPointerLeave`, `onWheel`, `onKeyDown`, `onKeyUp`.
+Events travel from the hit leaf up to the root, and `stopPropagation()`
+ends the walk. A pointer ends with an up or a cancel, never both: the
+cancel is the system taking the touch away (a back swipe, palm rejection),
+delivered along the pressed path with the pointer's last position, so a
+press ends without firing and a drag ends without a fling. Key events
 bubble the same way, starting at the focused node - or at the window root
 when nothing is focused, so `onKeyDown` on the window is where app-global
 shortcuts live.

package/package.json

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

package/src/core.ts

@@ -8,8 +8,9 @@ let handlers = new Map<number, Map<string, Function>>()
 // Pointer-handler presence mirrored into the render tree, so the runtime can
 // skip building deliveries that would reach nobody (moves over static content
 // are the flood case). Bits match alloy's EventInterest (rendertree/hit.rs);
-// keep the two in sync. Down/up are recorded but the runtime never gates
-// them: focus and gesture side effects hang off them regardless of handlers.
+// keep the two in sync. Down, up and cancel are recorded but the runtime
+// never gates them: focus and gesture side effects hang off them regardless
+// of handlers.
 const MOVE_BIT = 1
 const POINTER_INTEREST: Record<string, number> = {
   onPointerMove: MOVE_BIT,
@@ -18,6 +19,7 @@ const POINTER_INTEREST: Record<string, number> = {
   onPointerEnter: 8,
   onPointerLeave: 16,
   onWheel: 32,
+  onPointerCancel: 64,
 }
 
 let interests = new Map<number, number>()
@@ -388,6 +390,18 @@ export function prepareText(text: string, options?: tree.MeasureTextOptions): tr
   return tree.prepareText(text, options)
 }
 
+/**
+ * Makes the glyph cells of printable ASCII for these font styles ahead of
+ * their first use, off the frame: call it at startup with the type scale
+ * the app draws in (the components' Window does it for the theme's), so a
+ * screen's first paint in any of them never waits for cells. Glyphs outside
+ * ASCII are made at first use. Each entry names a font as a <text> would;
+ * line height and maxLines are ignored.
+ */
+export function warmText(styles: tree.MeasureTextOptions[]): void {
+  tree.warmText(styles)
+}
+
 /** One laid-out line from layoutNextLine. */
 export type TextLine = {
   /** Unit range [from, to) into prepared.units. */

package/src/double-tap.ts

@@ -48,8 +48,8 @@ export interface TapSequenceOptions {
 }
 
 /** The tap bookkeeping under a double-tap: one first tap at a time,
- * decided by the second down, by travel, by a long hold, by the window
- * timer or by cancel(). */
+ * decided by the second down, by travel, by a long hold, by a cancelled
+ * pointer, by the window timer or by cancel(). */
 export function createTapSequence(options: TapSequenceOptions) {
   let first: { id: number; at: PointerPoint; downAt: number; upAt: number | null } | null = null
   let timer: ReturnType<typeof setTimeout> | null = null
@@ -99,6 +99,9 @@ export function createTapSequence(options: TapSequenceOptions) {
         settle(false)
       }, DOUBLE_TAP_MS)
     },
+    cancelled(e: PointerEvent) {
+      if (first && first.id === e.pointerId) settle(false)
+    },
     cancel: () => settle(false),
   }
 }
@@ -145,6 +148,10 @@ export function createDoubleTap(options: DoubleTapOptions) {
       if (second === e.pointerId) release()
       taps.up(e)
     },
+    onPointerCancel: (e: PointerEvent) => {
+      if (second === e.pointerId) release()
+      taps.cancelled(e)
+    },
   }
   return { handlers, cancel }
 }

package/src/gpu.ts

@@ -97,7 +97,7 @@ export type { TextureFormat } from "flux:gpu"
 // runtime, distinct types to the checker, so a cross-space slip like
 // destroyBuffer(textureId) fails to compile. Exported so apps can annotate
 // storage (`let ids: TextureId[]`).
-export type { BufferId, DrawId, ProgramId, RenderPipelineId, ShaderStageId, TextureId } from "flux:gpu"
+export type { BufferId, DrawId, ProgramId, RenderPipelineId, ShaderStageId, TextureId, TextureRect } from "flux:gpu"
 
 // Re-exported so callers that depend on @solidrt/core -- like @solidrt/components
 // -- need not import flux directly: destroyTexture for the manual-cleanup path
@@ -196,22 +196,11 @@ export {
   programAttributes,
 } from "flux:gpu"
 
-/**
- * Tags an inline GLSL source, returning it unchanged. Shaders small enough to
- * belong beside the code that uses them stay in the file; the tag is what makes
- * them legible there, because editors highlight GLSL inside a template literal
- * only when a known tag marks it (the name matters - `glsl` is the one the
- * grammars look for).
- *
- * Interpolated values are stringified verbatim, with no GLSL-aware formatting:
- * `${2}` splices in the int literal `2`, which will not assign to a float. Pass
- * anything that varies as a uniform instead of building it into the source.
- *
- * Raw semantics, so backslashes reach the compiler as written: the GLSL
- * preprocessor continues a line with a trailing `\`, which a cooked template
- * would reject as an invalid escape and silently pass through as `undefined`.
- */
-export let glsl = String.raw
+// The tag, and the screen-size clamp both sprite renderers share: the
+// GLSL function a vertex stage pastes in, its JS twin for the picker, and
+// the validation of a [minScreenPx, maxScreenPx] pair. Both live in the
+// pure shaders.ts so headless tests and pure modules can reach them.
+export { checkScreenSize, glsl, SCREEN_SIZE_GLSL, screenSizeScale } from "./shaders.ts"
 
 // captureSnapshot renders a node to pixels and readTexture reads any
 // texture's bytes back; both resolve the same { width, height, data } shape.
@@ -293,7 +282,9 @@ export function createCubeTexture(
 
 /**
  * Creates a GPU texture you intend to update over time: seed it with `data`,
- * then call `uploadTexture(id, data)` (from flux:gpu) to push new pixels.
+ * then call `uploadTexture(id, data)` (from flux:gpu) to push new pixels, or
+ * `uploadTexture(id, cell, { x, y, width, height })` to write one rect of it
+ * (a runtime atlas placing a cell without re-sending the sheet).
  * `data` must hold at least `width * height` pixels at the declared format's
  * size, in the view type matching the format (Uint8Array for "rgba8"/
  * "rgba8-srgb"/"r8", Float32Array for "r32f"/"rgba32f"/"rgba16f"); it may

package/src/index.ts

@@ -1,10 +1,10 @@
 export * from "./renderer"
-export { setFocus, focusedNode, startTextInput, textInputActive, getFocusables, measureText, prepareText, layoutNextLine, unitInk, getBoundingBox, getBoundingBoxViewport, getLayoutBox, snapshotTexture, onPointerMove } from "./core"
+export { setFocus, focusedNode, startTextInput, textInputActive, getFocusables, measureText, prepareText, warmText, layoutNextLine, unitInk, getBoundingBox, getBoundingBoxViewport, getLayoutBox, snapshotTexture, onPointerMove } from "./core"
 export type { BoundingBox, GlobalPointerEvent, TextLine } from "./core"
 export { parseColor, mixColors, withAlpha, brightness, createLinearGradient, createRadialGradient } from "./color"
 export type { Gradient, GradientStop } from "./color"
-export { onFrame, frameTime, onLayout, onResize, onWindowFocus, onWindowBlur, onBack, onLink, onSuspend, onQuit, exit, background, registerProtocolHandler } from "./window"
-export type { BackEvent, FrameOptions, LifecycleHandler } from "./window"
+export { onFrame, frameTime, onBeforeRender, onLayout, onResize, onWindowFocus, onWindowBlur, onBack, onLink, onSuspend, onQuit, exit, background, registerProtocolHandler } from "./window"
+export type { BackEvent, BeforeRenderOptions, FrameOptions, LifecycleHandler } from "./window"
 export { windowSize, safeArea, displayScale, windowFocused, keyboardHeight, lockPointer, pointerLocked } from "./window"
 export { env } from "./environment"
 export type { InputDevices, SystemTheme, Orientation, Visibility, Launch } from "./environment"

package/src/input-pointer.ts

@@ -133,6 +133,7 @@ export interface PointerFeed extends InputDevice {
     onPointerDown(event: PointerEvent): void
     onPointerMove(event: PointerEvent): void
     onPointerUp(event: PointerEvent): void
+    onPointerCancel(event: PointerEvent): void
     onPointerLeave(event: PointerEvent): void
     onWheel(event: WheelEvent): void
   }
@@ -481,6 +482,17 @@ export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed
           opening = null
         }
       },
+      onPointerCancel(e) {
+        if (!downs.has(e.pointerId)) return
+        // The brackets close with no velocity and no swipe: the pointer
+        // ended without its lift.
+        transform.handlers.onPointerCancel(e)
+        released = null
+        lifted(e)
+        hold.cancelled(e)
+        taps.cancelled(e)
+        if (opening && opening.id === e.pointerId) opening = null
+      },
       onPointerLeave() {},
       onWheel(e) {
         if (e.deltaY === 0) return

package/src/long-press.ts

@@ -36,7 +36,8 @@ export interface HoldTimerOptions {
 }
 
 /** The arm / slop / timer machine under a long-press: one pointer at a
- * time, disarmed by travel, by a lift, by a second pointer or by cancel(). */
+ * time, disarmed by travel, by a lift, by a cancelled pointer, by a second
+ * pointer or by cancel(). */
 export function createHoldTimer(options: HoldTimerOptions) {
   let armed: { id: number; at: PointerPoint; mods: { shiftKey: boolean; ctrlKey: boolean; altKey: boolean; metaKey: boolean; button?: number } } | null = null
   let timer: ReturnType<typeof setTimeout> | null = null
@@ -69,6 +70,9 @@ export function createHoldTimer(options: HoldTimerOptions) {
     up(e: PointerEvent) {
       if (armed && armed.id === e.pointerId) disarm()
     },
+    cancelled(e: PointerEvent) {
+      if (armed && armed.id === e.pointerId) disarm()
+    },
     cancel: disarm,
   }
 }
@@ -84,6 +88,10 @@ export interface LongPressOptions {
   onLongPressMove?: (dx: number, dy: number) => void
   /** The lift after a fire. */
   onLongPressEnd?: () => void
+  /** A fired long press ended without its lift: the system cancelled the
+   * pointer (onPointerCancel), or another recognizer took it in the
+   * arena. Fired instead of onLongPressEnd. */
+  onLongPressCancel?: () => void
 }
 
 export function createLongPress(options: LongPressOptions) {
@@ -99,16 +107,26 @@ export function createLongPress(options: LongPressOptions) {
       options.onLongPress?.(at)
     },
   })
-  let cancel = () => {
-    hold.cancel()
+  let release = () => {
     if (fired !== null) {
       arena.release(fired, owner)
       fired = null
       last = null
     }
   }
+  // The press ends without its lift, whatever took the pointer: the arena
+  // (cancel) or the system (onPointerCancel). An unmount releases alone.
+  let cancel = () => {
+    hold.cancel()
+    let won = fired !== null
+    release()
+    if (won) options.onLongPressCancel?.()
+  }
   let owner: ArenaOwner = { cancel }
-  onSettled(() => cancel)
+  onSettled(() => () => {
+    hold.cancel()
+    release()
+  })
 
   let handlers = {
     onPointerDown: (e: PointerEvent) => {
@@ -126,12 +144,16 @@ export function createLongPress(options: LongPressOptions) {
     },
     onPointerUp: (e: PointerEvent) => {
       if (fired === e.pointerId) {
-        cancel()
+        release()
         options.onLongPressEnd?.()
         return
       }
       hold.up(e)
     },
+    onPointerCancel: (e: PointerEvent) => {
+      if (fired === e.pointerId) cancel()
+      else hold.cancelled(e)
+    },
   }
   return { handlers, cancel }
 }

package/src/pan.ts

@@ -35,6 +35,13 @@ export interface PanOptions {
    * finger rested before lifting or moved under FLING_MIN_VELOCITY.
    */
   onPanEnd?: (velocity: Velocity) => void
+  /**
+   * The pan ended without its result: the system cancelled the pointer
+   * (onPointerCancel), or another recognizer took it in the arena. Fired
+   * instead of onPanEnd, only after onPanStart; whoever animates on
+   * settles here, nothing flings.
+   */
+  onPanCancel?: () => void
 }
 
 // The pan recognizer: turns a drag into a movement-delta stream. On a down it
@@ -49,8 +56,9 @@ export interface PanOptions {
 // fling minimum) for momentum. Moves and the up arrive on the frozen down
 // path, so an active pan keeps streaming when the pointer leaves the node
 // or the window.
-// cancel() is the external-cancel hook; it ends an active pan without
-// onPanEnd. Options are read at event time. Single-pointer by design; for
+// cancel() is the external-cancel hook, the arena's; it and a pointer cancel
+// end an active pan with onPanCancel instead of onPanEnd. Options are read
+// at event time. Single-pointer by design; for
 // multi-pointer pinch/rotate compose createTransform instead.
 //
 // Frames: the slop is finger travel, so it is measured in window pixels
@@ -87,7 +95,13 @@ export function createPan(options: PanOptions) {
     armed = null
     origin = null
   }
-  let cancel = reset
+  // The pan ends without its result, whatever took the pointer: the arena
+  // (cancel) or the system (onPointerCancel). An unmount resets alone.
+  let cancel = () => {
+    let started = active != null
+    reset()
+    if (started) options.onPanCancel?.()
+  }
   let owner = { cancel }
 
   // An unmount mid-drag must not leave a resolved claim behind.
@@ -134,6 +148,10 @@ export function createPan(options: PanOptions) {
         reset()
       }
     },
+    onPointerCancel: (e: PointerEvent) => {
+      if (active === e.pointerId) cancel()
+      else if (armed === e.pointerId) reset()
+    },
   }
 
   return { handlers, cancel }

package/src/runtime-modules.d.ts

@@ -26,7 +26,8 @@ declare module "*.frag" {
 
 // Binary asset imports: `import data from "./pic.png" with { type: "binary" }`.
 // The bundler inlines the file's bytes as a Uint8Array (see packages/cli
-// bundler `inlineImport`); feed it straight into createImage/decodeImage.
+// bundler `inlineImport`); feed it straight into createImage/decodeImage, or a
+// `.wasm` into `new Module` from flux:wasm.
 declare module "*.png" {
   const bytes: Uint8Array
   export default bytes
@@ -55,6 +56,10 @@ declare module "*.sol3m" {
   const bytes: Uint8Array
   export default bytes
 }
+declare module "*.wasm" {
+  const bytes: Uint8Array
+  export default bytes
+}
 
 // UI event bus (lattice), provided by the runtime as a builtin module.
 // on/once return an unsubscribe function. Notable events: the routed pointer
@@ -301,4 +306,12 @@ declare module "sol:test" {
    * frame runs and no app time passes.
    */
   export function capture(node: number): { width: number; height: number; data: Uint8Array }
+  /**
+   * Run one frame with a capture of `node` queued ahead of it, so the
+   * frame's own paint services it: fulfills, once the frame has run, with
+   * what that frame drew of the node (the shape of `capture`). Written
+   * and painted in one frame, where `capture` paints the tree afresh
+   * after the fact. One frame at a time, as `frame`.
+   */
+  export function painted(node: number): Promise<{ width: number; height: number; data: Uint8Array }>
 }

package/src/shaders.ts

@@ -0,0 +1,82 @@
+// The GPU-free shader helpers: the `glsl` tag every shader source in the
+// repo is written with, and the GLSL shared between renderers with its JS
+// twins. Pure - no GPU or GUI imports - so the tests run headless on flux
+// and the extensions' pure modules can import from here; gpu.ts re-exports
+// all of it for apps.
+//
+// The screen-size clamp, shared by every renderer that draws a world-sized
+// quad and lets it hold a size on screen: @solidrt/2d's sprites (the
+// camera zoom is the pixels per world unit) and @solidrt/3d's sprite
+// material (the projection at the quad's depth is). A quad `w x h` world
+// units draws at its world size times the pixels per unit, clamped to
+// [minPx, maxPx] on its smaller axis as ONE uniform scale, so its aspect
+// holds. No bounds is world size; a floor alone is the marker that stays
+// findable at the overview; a ceiling alone is the label that must not
+// balloon; equal bounds is a constant screen size (Three's
+// `sizeAttenuation: false`), where w and h carry the aspect alone. A zero
+// bound is off. The GLSL and the JS below are the same function twice,
+// and every picker applies the JS one to the rect it tests, so a hit is
+// where the pixel is (tests/shaders.test.ts pins the pair).
+
+/**
+ * Tags an inline GLSL source, returning it unchanged. Shaders small enough to
+ * belong beside the code that uses them stay in the file; the tag is what makes
+ * them legible there, because editors highlight GLSL inside a template literal
+ * only when a known tag marks it (the name matters - `glsl` is the one the
+ * grammars look for).
+ *
+ * Interpolated values are stringified verbatim, with no GLSL-aware formatting:
+ * `${2}` splices in the int literal `2`, which will not assign to a float. Pass
+ * anything that varies as a uniform instead of building it into the source.
+ *
+ * Raw semantics, so backslashes reach the compiler as written: the GLSL
+ * preprocessor continues a line with a trailing `\`, which a cooked template
+ * would reject as an invalid escape and silently pass through as `undefined`.
+ */
+export let glsl = String.raw
+
+/**
+ * The GLSL half: `screenSizeScale(size, pxPerUnit, screenPx)` returns the
+ * uniform scale a `size` (world units) quad takes so its smaller axis
+ * covers at least `screenPx.x` and at most `screenPx.y` pixels when one
+ * world unit is `pxPerUnit` pixels; a zero bound is off, a collapsed quad
+ * (zero axis) stays collapsed. Paste it before `main`, multiply the quad's
+ * size by it.
+ */
+export const SCREEN_SIZE_GLSL = glsl`
+  float screenSizeScale(vec2 size, float pxPerUnit, vec2 screenPx) {
+    float smallest = min(abs(size.x), abs(size.y)) * pxPerUnit;
+    if (smallest <= 0.0) return 1.0;
+    float target = smallest;
+    if (screenPx.x > 0.0) target = max(target, screenPx.x);
+    if (screenPx.y > 0.0) target = min(target, screenPx.y);
+    return target / smallest;
+  }
+`
+
+/**
+ * The JS half of SCREEN_SIZE_GLSL, for the picker: the uniform scale a
+ * `w x h` quad draws at when one world unit is `pxPerUnit` pixels and
+ * its smaller axis is clamped to [minPx, maxPx] on screen. 1 with both
+ * bounds off, when the quad already lies within them, or when it is
+ * collapsed.
+ */
+export function screenSizeScale(w: number, h: number, pxPerUnit: number, minPx: number, maxPx: number): number {
+  let smallest = Math.min(Math.abs(w), Math.abs(h)) * pxPerUnit
+  if (!(smallest > 0)) return 1
+  let target = smallest
+  if (minPx > 0) target = Math.max(target, minPx)
+  if (maxPx > 0) target = Math.min(target, maxPx)
+  return target / smallest
+}
+
+/**
+ * Validate a screen-size pair (throws - the dev validation policy): each
+ * bound finite and >= 0 (0 = off), and a ceiling never below a floor that
+ * is on. `site` names the caller in the message.
+ */
+export function checkScreenSize(site: string, minPx: number, maxPx: number): void {
+  if (!(Number.isFinite(minPx) && minPx >= 0)) throw new Error(`${site}: minScreenPx must be a finite number >= 0, got ${minPx}`)
+  if (!(Number.isFinite(maxPx) && maxPx >= 0)) throw new Error(`${site}: maxScreenPx must be a finite number >= 0, got ${maxPx}`)
+  if (minPx > 0 && maxPx > 0 && maxPx < minPx) throw new Error(`${site}: maxScreenPx ${maxPx} is below minScreenPx ${minPx}`)
+}

package/src/swipe.ts

@@ -67,6 +67,10 @@ export interface SwipeOptions {
   onSwipe?: (direction: SwipeDirection, velocity: Velocity) => void
   /** Every lift of an active swipe, qualified or not. */
   onSwipeEnd?: (velocity: Velocity) => void
+  /** An active swipe ended without its lift: the system cancelled the
+   * pointer (onPointerCancel), or another recognizer took it in the
+   * arena. Fired instead of onSwipe and onSwipeEnd. */
+  onSwipeCancel?: () => void
 }
 
 export function createSwipe(options: SwipeOptions) {
@@ -97,6 +101,11 @@ export function createSwipe(options: SwipeOptions) {
       if (direction) options.onSwipe?.(direction, velocity)
       options.onSwipeEnd?.(velocity)
     },
+    onPanCancel: () => {
+      down = null
+      lift = null
+      options.onSwipeCancel?.()
+    },
   })
 
   let handlers = {
@@ -120,6 +129,13 @@ export function createSwipe(options: SwipeOptions) {
         lift = null
       }
     },
+    onPointerCancel: (e: PointerEvent) => {
+      pan.handlers.onPointerCancel(e)
+      if (down && down.id === e.pointerId) {
+        down = null
+        lift = null
+      }
+    },
   }
   let cancel = () => {
     pan.cancel()

package/src/transform.ts

@@ -59,6 +59,10 @@ export interface TransformOptions {
    * parent-frame pixels per second (velocity.ts; zero after a rest or
    * under the fling minimum). */
   onTransformEnd?: (velocity: Velocity) => void
+  /** The gesture ended without its result: the system cancelled a finger
+   * (onPointerCancel), or another recognizer took the pointers in the
+   * arena. Fired instead of onTransformEnd, only after onTransformStart. */
+  onTransformCancel?: () => void
 }
 
 // The merged transform recognizer: pan + pinch + rotate as ONE gesture over
@@ -116,7 +120,8 @@ export interface TransformOptions {
 // configuration, so the change itself never emits a jump delta. The gesture
 // ends when the last finger lifts. Moves and ups arrive on the frozen down
 // path, so an active transform survives leaving the node or the window.
-// cancel() is the external-cancel hook; it ends an active gesture without
+// cancel() is the external-cancel hook, the arena's; it and a cancelled
+// finger end an active gesture with onTransformCancel instead of
 // onTransformEnd. Options are read at event time.
 //
 // Frames: the slop, the span filter and its rate gates are finger-travel
@@ -206,7 +211,11 @@ export function createTransform(options: TransformOptions) {
     rebase = false
     tracker.reset()
   }
-  let cancel = reset
+  let cancel = () => {
+    let started = active
+    reset()
+    if (started) options.onTransformCancel?.()
+  }
   let owner: ArenaOwner = { cancel }
 
   // The per-frame measure point: runs at the pointerFrame terminator, when
@@ -355,6 +364,17 @@ export function createTransform(options: TransformOptions) {
       pointers.delete(e.pointerId)
       ref = pointers.size > 0 ? measure() : null
     },
+    onPointerCancel: (e: PointerEvent) => {
+      if (!pointers.has(e.pointerId)) return
+      // The system cancels the gesture, not a finger: every platform
+      // cancels all of them together, so the whole gesture ends.
+      if (active) {
+        cancel()
+        return
+      }
+      pointers.delete(e.pointerId)
+      ref = pointers.size > 0 ? measure() : null
+    },
   }
 
   return { handlers, cancel }

package/src/types.d.ts

@@ -278,7 +278,8 @@ export interface TransformProps {
 
 // Window-relative pointer coordinates are reported as clientX/clientY (matching
 // the DOM MouseEvent). pointerType distinguishes mouse from touch; button is the
-// pressed button on down/up (0 = primary); the modifier flags mirror the DOM.
+// pressed button on down/up (0 = primary) and absent on a cancel; the modifier
+// flags mirror the DOM.
 export interface PointerEvent {
   /**
    * When the event happened, in milliseconds. Every input event carries one,
@@ -408,6 +409,15 @@ export interface NodeProps {
 export interface PointerProps extends NodeProps {
   onPointerDown?: (event: PointerEvent) => void
   onPointerUp?: (event: PointerEvent) => void
+  /**
+   * The system took the pointer away: a system gesture (the back swipe,
+   * the notification shade), palm rejection, the window losing the touch.
+   * The last event for that pointer, and no up follows it, so a press
+   * ends without firing and a drag ends without a fling. Routed along the
+   * pressed path like an up, with the pointer's last known position and
+   * no `button`.
+   */
+  onPointerCancel?: (event: PointerEvent) => void
   onPointerMove?: (event: PointerEvent) => void
   onPointerEnter?: (event: PointerEvent) => void
   onPointerLeave?: (event: PointerEvent) => void
@@ -1043,6 +1053,14 @@ export interface PathProps extends PaintProps, PointerProps, DashProps {
   shadow?: ShadowProps
 }
 
+/**
+ * A font role ("sans", "serif", "mono": the font the app packages for it,
+ * or the runtime's own Noto) or a registered family name; an unknown
+ * family falls back to sans. A character the family's font lacks is drawn
+ * from the next registered font that has it, roles first; one no
+ * registered font has draws as the font's missing-glyph box. Whitespace
+ * and control characters never draw a box: a tab advances like a space.
+ */
 export type FontFamily = "sans" | "serif" | "mono" | (string & {})
 export type FontStyle = "normal" | "italic"
 export type FontWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
@@ -1066,11 +1084,21 @@ export interface TextRunProps {
   lineHeight?: number
   fontStyle?: FontStyle
   fontWeight?: FontWeight
+  /**
+   * Width as a percentage of normal (CSS font-stretch: 100 normal, 75
+   * condensed, 125 expanded), set on the font's width axis and clamped to
+   * its range; a font without one draws at its one width. Default 100.
+   */
+  fontStretch?: number
+  /**
+   * Extra advance after every character (grapheme cluster) in pixels, the
+   * last one included, as CSS letter-spacing; negative tightens. Default 0.
+   */
+  letterSpacing?: number
   /**
    * 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.
+   * unless overridden.
    */
   textDecoration?: TextDecoration
   /** Pixels from the baseline to the top of the underline. */

package/src/window.ts

@@ -422,7 +422,9 @@ export function keyboardHeight(): number {
 // 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.
+// handlers after it nor the flush. The publish pass (onBeforeRender) runs
+// once more after the flush, for the same reason: what a handler hands an
+// extension lands in this frame's paint too.
 let layoutHandlers: (() => void)[] = []
 let layoutSubscribed = false
 
@@ -439,6 +441,7 @@ function runLayoutHandlers() {
   } catch (err) {
     console.error("Error in reactive flush:", err)
   }
+  runPublish()
 }
 
 /**
@@ -462,6 +465,93 @@ export function onLayout(fn: () => void) {
   return unsubscribe
 }
 
+// ------ Before render ----------------
+
+// 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
+// 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
+// publish - so they are in the frame they were made in, the way the
+// engine's own transform flush ahead of the paint is. Without this pass
+// those writes land at the microtask after the whole frame closure, one
+// frame after the paint that should have shown them. Each handler is its
+// own boundary, listener style: a throw is logged and the rest still run.
+let lateHandlers: (() => void)[] = []
+let publishHandlers: (() => void)[] = []
+
+function runHandlers(handlers: (() => void)[]) {
+  for (let fn of [...handlers]) {
+    try {
+      fn()
+    } catch (err) {
+      console.error("Error in onBeforeRender callback:", err)
+    }
+  }
+}
+
+// Before renderFrame(): the late pass (skipped on the bootstrap frame, which
+// runs no frame callbacks either), its signal writes flushed, then the
+// publish pass - the same handlers-then-flush shape as the post-layout
+// entry, so a late handler's reactive write reaches its node in this frame
+// and the publish pass sees it. An empty flush is a flag check.
+function runBeforeRender(bootstrap: boolean) {
+  if (!bootstrap) {
+    runHandlers(lateHandlers)
+    try {
+      flush()
+    } catch (err) {
+      console.error("Error in reactive flush:", err)
+    }
+  }
+  runHandlers(publishHandlers)
+}
+
+// After the post-layout handlers' flush: the publish pass alone.
+function runPublish() {
+  runHandlers(publishHandlers)
+}
+
+export interface BeforeRenderOptions {
+  /**
+   * Run in the publish pass: after every plain handler, and again after
+   * the `onLayout` handlers of a frame that has any. For handing pending
+   * state to the engine, never for deciding it.
+   */
+  publish?: boolean
+}
+
+/**
+ * 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.
+ * Writes made here, to the engine or through signals, are in this frame:
+ * the pending reactive writes are flushed once every handler has run.
+ *
+ * `{ publish: true }` registers for the publish pass instead: after every
+ * plain handler, and once more after the `onLayout` handlers of a frame
+ * that has any. It is where an extension hands the engine what the frame
+ * wrote into its mirrors (a scene syncs its record buffers and lights, a
+ * sprite layer its style and pose publish), so a write made anywhere in
+ * the frame's JS is in that frame's paint. A publish handler must be
+ * idempotent (it may run twice per frame) and must not write app state.
+ *
+ * Returns a cleanup function; also auto-cleans within an owned scope.
+ */
+export function onBeforeRender(fn: () => void, options?: BeforeRenderOptions) {
+  let handlers = options?.publish ? publishHandlers : lateHandlers
+  handlers.push(fn)
+  let unsubscribe = () => {
+    let i = handlers.indexOf(fn)
+    if (i >= 0) handlers.splice(i, 1)
+  }
+  if (getOwner()) onCleanup(unsubscribe)
+  return unsubscribe
+}
+
 export function onWindowFocus(fn: () => void) {
   let unsubscribe = on("windowFocus", fn)
   if (getOwner()) onCleanup(unsubscribe)
@@ -553,6 +643,7 @@ export function attachWindow(nodeId: number) {
   let unsubscribe: () => void = null!
   let unsubDown: () => void = null!
   let unsubUp: () => void = null!
+  let unsubCancel: () => void = null!
   let unsubMove: () => void = null!
   let unsubEnter: () => void = null!
   let unsubLeave: () => void = null!
@@ -588,6 +679,7 @@ export function attachWindow(nodeId: number) {
     } catch (err) {
       console.error("Error in reactive flush:", err)
     }
+    runBeforeRender(bootstrap)
     scanForOrphans(t)
     renderFrame()
   }
@@ -664,6 +756,10 @@ export function attachWindow(nodeId: number) {
       bubble(raw, "onPointerUp")
     })
 
+    unsubCancel = on("pointerCancel", (raw: RawPointer) => {
+      bubble(raw, "onPointerCancel")
+    })
+
     unsubMove = on("pointerMove", (raw: RawPointer) => {
       bubble(raw, "onPointerMove")
     })
@@ -761,6 +857,7 @@ export function attachWindow(nodeId: number) {
     if (unsubscribe) unsubscribe()
     if (unsubDown) unsubDown()
     if (unsubUp) unsubUp()
+    if (unsubCancel) unsubCancel()
     if (unsubMove) unsubMove()
     if (unsubEnter) unsubEnter()
     if (unsubLeave) unsubLeave()