@solidrt/core 0.0.67 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.67",
+  "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.67",
-    "@solidrt/test": "0.0.67"
+    "@solidrt/flux-types": "0.0.68",
+    "@solidrt/test": "0.0.68"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.13",

package/src/core.ts

@@ -390,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/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/runtime-modules.d.ts

@@ -306,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/types.d.ts

@@ -1053,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
@@ -1076,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)
@@ -589,6 +679,7 @@ export function attachWindow(nodeId: number) {
     } catch (err) {
       console.error("Error in reactive flush:", err)
     }
+    runBeforeRender(bootstrap)
     scanForOrphans(t)
     renderFrame()
   }