@solidrt/core 0.0.61 → 0.0.62

package/agents/performance.md

@@ -172,8 +172,13 @@ Rules, in order of leverage:
    every frame with prepareText + layoutNextLine (a shape that breathes, an
    obstacle that moves, an editor on every keystroke) is cheap - the lines'
    d-texts hit the same cache - while changing a text's font, size or
-   weight re-shapes it. Animate text with transforms and paint (rule 5), or
-   by re-breaking; not by resizing it per frame.
+   weight re-shapes it. Painting costs one paragraph draw per line run of
+   same-styled words (the joined line goes through the same cache, so a
+   line composition seen before is a lookup): a paragraph draws as its
+   lines, not its words, and a re-breaking one shapes only the lines whose
+   breaks moved. A justified line or a per-word style change draws per
+   word. Animate text with transforms and paint (rule 5), or by
+   re-breaking; not by resizing it per frame.
 
 ## Isolates: heavy work off the JS thread
 
@@ -235,6 +240,34 @@ not infer it from the desktop number.
   content-independent floor: if a trivial scene and a heavy one present at
   nearly the same rate, you are compositor-bound and tuning the scene is
   wasted effort.
+- **Some paints cost a frame each on a tiled mobile GPU.** Measured on a
+  mid-range 2020 tablet (Adreno 610, Impeller GLES) with ten panes sliding
+  and resizing on a layout transition, each row by subtraction from the
+  compositor's own present record (`srt android --census`), against a
+  frame that ran at 60 fps with a 13 ms GPU span:
+  - a 3-stop linear-gradient fill per pane: +15 ms, 20 fps. A gradient is
+    shaded per pixel per frame; the same tint as a flat `d-rect` costs
+    nothing, and even a once-rendered 32x32 texture stretched over the pane
+    costs +5 ms over the flat fill.
+  - a rounded clip (`overflow="hidden"` with `clipRadius`) on a box whose
+    size is in flight: ~8 ms for one pane, ~13 ms for ten, most of it when
+    an image is under the clip. A static rounded clip is nearly free. Round
+    the paint instead (`radius` on `d-rect`, `d-texture` and `<texture>`)
+    and keep the clip rectangular.
+  - four 16 px draws per pane with `destination-out` and `destination-over`
+    blends: +16 ms. Any blend but source-over leaves the fast path,
+    whatever the size.
+  - seventy small source-over texture draws in place of ten pane-sized
+    ones: +10 ms. Draw count costs on its own.
+  - five 230-character paragraphs painted per word, 180 paragraph draws:
+    20 fps; painted per line run, 30 draws (rule 10, what the runtime does
+    now): 60 fps.
+  - a laid-out `TextInput` inside a resizing box re-checks its breaks and
+    scroll against the box per frame, ~0.2 ms per field on that tablet;
+    a fixed box, or a paragraph while not editing, costs nothing per frame.
+  `get_stats`' `paintOps` (draws, paragraphs, clips, roundedClips,
+  saveLayers, blends, gradients) says which of these a frame carries, per
+  rebuild and for the window's worst frame.
 - **Per-frame writes are gated on the raster thread, not on vsync**, so a pass
   that costs more than a refresh period does not silently pile up. If
   `rasterQueue` climbs across queries while fps drops the raster thread is

package/docs/index.md

@@ -164,6 +164,19 @@ launch the user started. Whether to load what `onSuspend` saved is the app's
 call. `env.visibility` is only whether anything is on screen, for pausing
 animation and audio, not the persistence moment.
 
+A link from outside (a custom scheme link the OS routed to the app, or one
+a dev tool sent) arrives raw: `env.launchLink` is the one this run of the
+app was started with (null without; a hot reload starts at the location
+the app last reported, see `reportLocation` in `srt:dev`), `onLink` fires
+for one arriving while the app runs. What a link names is the app's to decide, and it is untrusted input:
+validate before acting on any part of it. A router turns links into screens
+for you; without one, parse it yourself. The scheme a packed app answers to
+is its appId (`com.example.app://settings`); `registerProtocolHandler()`
+makes the install the handler for it on Linux and Windows, where nothing
+installs a single executable, and does nothing on Android, whose package
+declares the scheme. A second desktop instance started with a link hands
+it to the running one and exits.
+
 ```tsx
 onSuspend(() => file("session.json").write(JSON.stringify(state)))
 if (env.launch === "restored") state = JSON.parse(await file("session.json").text())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.61",
+  "version": "0.0.62",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -32,7 +32,7 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.61"
+    "@solidrt/flux-types": "0.0.62"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.9",

package/src/environment.ts

@@ -83,6 +83,21 @@ function ensureLaunchState() {
   launchValue ??= "fresh"
 }
 
+// Fixed for the process like the launch fact (sticky `launchLink`, emitted
+// before any app code runs), so a plain value rather than a signal.
+let launchLinkValue: string | null | undefined
+
+function ensureLaunchLinkState() {
+  if (launchLinkValue !== undefined) return
+  runWithOwner(null, () => {
+    on("launchLink", (e: { link?: string | null }) => {
+      launchLinkValue = typeof e.link === "string" ? e.link : null
+    })
+  })
+  // A runtime that reports no launch link launched without one.
+  launchLinkValue ??= null
+}
+
 let visibilityAccessor: (() => Visibility) | undefined
 
 function ensureVisibilityState() {
@@ -257,6 +272,18 @@ export let env = {
     ensureLaunchState()
     return launchValue!
   },
+  /**
+   * The link this process was started with, or null: a custom scheme link
+   * the OS routed to the app (Android intent data; `srt render --link`),
+   * raw, exactly as it arrived. What it names is the app's to decide, and
+   * it is untrusted input: validate before acting on any part of it. A link
+   * arriving while the app runs is an event instead: `onLink`. Fixed for the
+   * process, so it needs no tracked scope.
+   */
+  get launchLink(): string | null {
+    ensureLaunchLinkState()
+    return launchLinkValue!
+  },
   /** Orientation of the display the window is on. */
   get orientation(): Orientation {
     ensureOrientationState()

package/src/index.ts

@@ -3,7 +3,7 @@ export { setFocus, focusedNode, startTextInput, textInputActive, getFocusables,
 export type { BoundingBox, GlobalPointerEvent, TextLine } from "./core"
 export { parseColor, mixColors, withAlpha, brightness, createLinearGradient, createRadialGradient } from "./color"
 export type { Gradient, GradientStop } from "./color"
-export { onFrame, onLayout, onResize, onWindowFocus, onWindowBlur, onBack, onSuspend, onQuit, exit, background } from "./window"
+export { onFrame, onLayout, onResize, onWindowFocus, onWindowBlur, onBack, onLink, onSuspend, onQuit, exit, background, registerProtocolHandler } from "./window"
 export type { BackEvent, LifecycleHandler } from "./window"
 export { windowSize, safeArea, displayScale, windowFocused, keyboardHeight, lockPointer, pointerLocked } from "./window"
 export { env } from "./environment"

package/src/runtime-modules.d.ts

@@ -83,6 +83,18 @@ declare module "srt:app" {
    * `back` on Android; exposed there as `background`.
    */
   export function background(): void
+  /**
+   * Make this install the handler for the app's own scheme (its appId, as
+   * in `com.example.app://settings`), so links of it open the app: on Linux
+   * a desktop entry plus the mimeapps.list default, on Windows the
+   * HKCU\Software\Classes protocol key, both for the current user. Throws
+   * when the registration cannot be written. Android and macOS packages
+   * declare the scheme themselves, so the call has nothing to do there; a
+   * dev client registers nothing and logs a warning. Prefer the
+   * @solidrt/core `registerProtocolHandler`, the same call documented with
+   * the rest of the link surface.
+   */
+  export function registerProtocolHandler(): void
 }
 
 // Dev-server control surface (lattice). Present only in dev/go builds; in other
@@ -110,6 +122,17 @@ declare module "srt:dev" {
    * clients ever invoke commands.
    */
   export function registerDebug(name: string, fn: (args?: any) => unknown): void
+  /**
+   * Report where the app is, for tooling: a string naming the current
+   * location (a router's path; an app routing by hand may report its own),
+   * called again on every change. The runtime stores the value and never
+   * interprets it. The dev server reads it (`GET /__control__/link`, the
+   * get_location MCP tool), and a hot reload of the same app starts with the
+   * last reported location as its `env.launchLink`, so a rebuild comes back
+   * to the screen it left. null withdraws it. Callable in every build, but
+   * only dev clients ever read it.
+   */
+  export function reportLocation(location: string | null): void
 }
 
 // Installed-app management (lattice), the player's surface over the client's

package/src/text-input.ts

@@ -256,9 +256,11 @@ export type TextEditorLayout = {
  * frame. A size change that re-breaks nothing (an empty field, lines that
  * still fit, a height-only change) stops at the line placement: the lines,
  * the caret and everything the caller derives from them keep their values
- * and re-run nothing, so a field inside a resizing box costs one placement
- * per frame, not a flush of its whole graph. Pure geometry: no caret
- * rendering and no placeholder/visual policy.
+ * and re-run nothing, and the placement reads the break inputs through a
+ * memo of its own rather than `input()` (which a caller builds per read),
+ * so a field inside a resizing box costs one placement of its units per
+ * frame, not a flush of its whole graph. Pure geometry: no caret rendering
+ * and no placeholder/visual policy.
  */
 export function createTextEditorLayout(
   viewport: () => { id: number } | undefined,
@@ -283,6 +285,19 @@ export function createTextEditorLayout(
     return prepareText(text, { ...font(), runs, carets: true })
   })
 
+  // What the breaks depend on, apart from the rest of the input: the caller
+  // builds input() per read (a field's value, font, caret and runs - some
+  // twenty reactive reads), and a placement re-run for a viewport width
+  // change must not pay for that. Equal by field, so only a real change
+  // reaches the placement.
+  let breaking = createMemo(
+    (): BreakInput => {
+      let { text, wrap, caretWidth = 0 } = input()
+      return { text, wrap, caretWidth }
+    },
+    { equals: sameBreakInput },
+  )
+
   // Lines carry their unit range so the caret math walks only their units.
   // Equal placements (same units, same breaks and metrics) keep the previous
   // value, so nothing downstream re-runs for a width change that changed
@@ -290,11 +305,13 @@ export function createTextEditorLayout(
   // keeps the previous object: a row bound to it (a non-keyed <For> item)
   // sees no change and writes nothing, so a moved break costs the lines it
   // touched, not every line of the field.
-  type PlacedLine = EditorLine & { from: number; to: number }
-  type Placement = { units: TextUnit[]; lines: PlacedLine[] }
+  type PlacedLine = EditorLine & { from: number; to: number; hardBreak: boolean }
+  // `holds` is the range of wrap widths [min, max) the breaker yields these
+  // same lines at (see holdRange); the layout handler skips a width inside it.
+  type Placement = { units: TextUnit[]; lines: PlacedLine[]; holds: [number, number] }
   let placed = createMemo(
     (prev): Placement => {
-      let { text, wrap, caretWidth = 0 } = input()
+      let { text, wrap, caretWidth } = breaking()
       // Wrapped lines leave room for the caret at the end of a full line, so a
       // wrapping editor never scrolls horizontally.
       let width = wrap ? Math.max(0, viewportWidth() - caretWidth) : Infinity
@@ -305,21 +322,33 @@ export function createTextEditorLayout(
       let line = layoutNextLine(units, cursor, width)
       let hardBreak = false
       while (line) {
-        out.push({ start: line.start, end: line.end, y, height: line.height, width: line.width, from: line.from, to: line.to })
+        out.push({
+          start: line.start,
+          end: line.end,
+          y,
+          height: line.height,
+          width: line.width,
+          from: line.from,
+          to: line.to,
+          hardBreak: line.hardBreak,
+        })
         y += line.height
         hardBreak = line.hardBreak
         line = layoutNextLine(units, line.cursor, width)
       }
       if (out.length === 0 || hardBreak) {
         let n = units.units.length
-        out.push({ start: text.length, end: text.length, y, height: space().height, width: 0, from: n, to: n })
+        out.push({ start: text.length, end: text.length, y, height: space().height, width: 0, from: n, to: n, hardBreak: false })
       }
       if (prev && prev.units === units.units) {
         for (let i = 0; i < out.length && i < prev.lines.length; i++) {
           if (sameLine(prev.lines[i]!, out[i]!)) out[i] = prev.lines[i]!
         }
       }
-      return { units: units.units, lines: out }
+      // Split units are the width's own (a unit wider than it), so those
+      // lines hold for no other width.
+      let holds: [number, number] = units.units === prepared().units ? holdRange(units.units, out) : [Infinity, Infinity]
+      return { units: units.units, lines: out, holds }
     },
     { equals: samePlacement },
   )
@@ -452,7 +481,7 @@ export function createTextEditorLayout(
   // when the caret has left the visible range, so the memo carries the
   // retained position across recomputes.
   let scrollX = createMemo((prev: number | undefined): number => {
-    let { caretWidth = 0, wrap } = input()
+    let { caretWidth, wrap } = breaking()
     if (wrap) return 0
     let contentWidth = lines().reduce((w, l) => Math.max(w, l.width), 0)
     let c = caret()
@@ -465,12 +494,43 @@ export function createTextEditorLayout(
     return follow(prev ?? 0, c.y, c.height, viewportHeight(), last.y + last.height)
   })
 
+  // Whether the lines placed at the last written width are what the breaker
+  // yields at `width` too. Such a width is not written: the write would mark
+  // the whole graph below the placement for a re-check that finds nothing,
+  // which is what a field inside a resizing box paid per frame. So
+  // viewportWidth lags the box by less than a break while wrapping, and a
+  // placement re-run for a text change at the lagging width is checked here
+  // again on that frame and corrected before paint (writes from onLayout
+  // land in the same frame's re-layout; the same holds for the height
+  // below). Unwrapped, the width is the horizontal scroll's extent and is
+  // always written.
+  let keepsBreaks = (width: number): boolean => {
+    let { wrap, caretWidth } = breaking()
+    if (!wrap) return false
+    let [min, max] = placed().holds
+    let w = Math.max(0, width - caretWidth)
+    return w >= min && w < max
+  }
+
+  // The same for the height: a height at which the retained scroll offset
+  // still keeps the caret in view is not written, so the scroll graph stays
+  // untouched while a short field's box grows and shrinks.
+  let keepsScroll = (height: number): boolean => {
+    let ls = lines()
+    let last = ls[ls.length - 1]!
+    let c = caret()
+    let current = scrollY()
+    return follow(current, c.y, c.height, height, last.y + last.height) === current
+  }
+
   onLayout(() => {
     let node = viewport()
     if (!node) return
     let box = getLayoutBox(node)
-    setViewportWidth(box?.width ?? 0)
-    setViewportHeight(box?.height ?? 0)
+    let width = box?.width ?? 0
+    let height = box?.height ?? 0
+    if (!keepsBreaks(width)) setViewportWidth(width)
+    if (!keepsScroll(height)) setViewportHeight(height)
   })
 
   return { lines, caret, caretLine, offsetAtX, selectionRects, lineAtY, step, scrollX, scrollY }
@@ -519,6 +579,33 @@ function splitWide(prepared: PreparedText, width: number): PreparedText {
   return { text: prepared.text, units }
 }
 
+// The wrap widths [min, max) at which the greedy breaker yields exactly
+// `lines` over `units`: every line's ink fits (min), and no line's first
+// unit fits at the end of the line before it (max), except across a hard
+// break, where it never joins. Greedy breaking is decided line by line on
+// just those two tests, so inside the range the placement is unchanged.
+function holdRange(units: TextUnit[], lines: { from: number; to: number; width: number; hardBreak: boolean }[]): [number, number] {
+  let min = 0
+  let max = Infinity
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i]!
+    if (line.width > min) min = line.width
+    let next = lines[i + 1]
+    if (!next || line.hardBreak || next.from >= units.length) continue
+    let pen = 0
+    for (let u = line.from; u < line.to; u++) pen += units[u]!.advance
+    let join = pen + unitInk(units, next.from)
+    if (join < max) max = join
+  }
+  return [min, max]
+}
+
+type BreakInput = { text: string; wrap: boolean; caretWidth: number }
+
+function sameBreakInput(a: BreakInput, b: BreakInput): boolean {
+  return a.text === b.text && a.wrap === b.wrap && a.caretWidth === b.caretWidth
+}
+
 // Font options compared field by field: the same keys with the same values.
 function sameOptions(a: MeasureTextOptions, b: MeasureTextOptions): boolean {
   let ka = Object.keys(a) as (keyof MeasureTextOptions)[]

package/src/window.ts

@@ -2,7 +2,7 @@ import { createSignal, getOwner, onCleanup, onSettled, runWithOwner, flush } fro
 import { requestFrame, setPointerLock } from "flux:rendertree"
 import { renderFrame } from "srt:render"
 import { on, once } from "srt:events"
-import { exit as nativeExit, background as nativeBackground } from "srt:app"
+import { exit as nativeExit, background as nativeBackground, registerProtocolHandler as nativeRegisterProtocolHandler } from "srt:app"
 import { platform } from "flux:process"
 import { getEventHandler, focusedNode, setFocus, activateTextInput, setInterestRoot } from "./core"
 import { scanForOrphans, getNodePath } from "./renderer"
@@ -141,6 +141,20 @@ export function background() {
   nativeBackground()
 }
 
+/**
+ * Makes this install the handler for the app's own scheme, so links like
+ * `com.example.app://settings` (the scheme is the appId) open the app from a
+ * browser, another app or the shell: `env.launchLink` when it starts the
+ * app, `onLink` when the app already runs. The web's name, simplified: no
+ * arguments, the scheme is fixed. A packed desktop app has to call it,
+ * since nothing installs a single executable (call it again after moving
+ * the executable); Android and macOS packages declare the scheme, so the
+ * call does nothing there. Throws when the registration cannot be written.
+ */
+export function registerProtocolHandler() {
+  nativeRegisterProtocolHandler()
+}
+
 // The default action of an unprevented back event: what the platform itself
 // does at the root of an app. Android backgrounds (since Android 12);
 // everywhere else back at the root ends the app.
@@ -417,6 +431,23 @@ export function onWindowFocus(fn: () => void) {
   return unsubscribe
 }
 
+/**
+ * Calls `fn` with a link handed to the running app from outside: a custom
+ * scheme link the OS routed here (another app, a QR code, a notification),
+ * or one a dev tool sent (`open_link` over MCP, `POST /__control__/link`).
+ * The raw string, exactly as it arrived; the app decides what it means, and
+ * it is untrusted input: validate before acting on any part of it. The link
+ * the app was *started* with is not an event (nothing was listening yet) but
+ * a fact: `env.launchLink`.
+ *
+ * Returns a cleanup function; also auto-cleans within an owned scope.
+ */
+export function onLink(fn: (link: string) => void) {
+  let unsubscribe = on("link", (e: { link: string }) => fn(e.link))
+  if (getOwner()) onCleanup(unsubscribe)
+  return unsubscribe
+}
+
 export function onWindowBlur(fn: () => void) {
   let unsubscribe = on("windowBlur", fn)
   if (getOwner()) onCleanup(unsubscribe)