@solidrt/core 0.0.51 → 0.0.53

package/src/renderer.ts

@@ -1,8 +1,9 @@
-import { createRoot, onCleanup } from "@solidjs/signals"
+import { createRoot, onCleanup, NotReadyError } from "@solidjs/signals"
 import { createRenderer } from "@solidjs/universal"
+import { createErrorBoundary } from "solid-js"
 import type { Element } from "solid-js"
 import * as tree from "flux:rendertree"
-import { attachWindow } from "./window"
+import { attachWindow, setWindowRoot } from "./window"
 import { setEventHandler, setFocusable, setTextInputHints, cleanupNode, focusedNode, setFocus } from "./core"
 
 export { getEventHandler } from "./core"
@@ -213,20 +214,7 @@ function applyProp<T>(node: ProxyNode, name: string, value: T): void {
   setTreeProperty(node, name, value)
 }
 
-export let {
-  effect,
-  memo,
-  createComponent,
-  createElement,
-  createTextNode,
-  insertNode,
-  insert,
-  spread,
-  setProp,
-  mergeProps,
-  applyRef,
-  ref,
-} = createRenderer<ProxyNode>({
+let renderer = createRenderer<ProxyNode>({
   createElement: (elementType: string, props?: Record<string, any>): ProxyNode => {
     let proxy = createProxyNode(elementType)
 
@@ -235,11 +223,13 @@ export let {
     if (elementType === "window") tree.createRoot(proxy.id)
     else tree.createNode(proxy.id, elementType)
 
-    // The universal JSX template hands static props here as an object; children
-    // and ref arrive through their own hooks, so skip them.
+    // The universal JSX template hands static props here as an object. The
+    // compiler routes children/ref expressions through their own hooks, so
+    // those names only appear here in degenerate literal forms (children="hi",
+    // a bare ref) - let them flow to the tree so the unknown-property warning
+    // reports them instead of dropping them silently.
     if (props) {
       for (let name in props) {
-        if (name === "children" || name === "ref") continue
         applyProp(proxy, name, props[name])
       }
     }
@@ -276,6 +266,14 @@ export let {
     pendingDestroy.delete(node.id)
 
     if (parent) {
+      // console.debug("[srt] insertNode", parent.id, node.id, anchor?.id ?? "")
+
+      // Native first: the tree refuses a laid-out element under a d-* parent
+      // (it throws, naming both tags), and the mirror must not record a child
+      // the tree does not have.
+      if (anchor) tree.insertNode(parent.id, node.id, anchor.id)
+      else tree.insertNode(parent.id, node.id)
+
       node.parent = parent
 
       if (!anchor) {
@@ -288,11 +286,6 @@ export let {
           parent.children.splice(index, 0, node)
         }
       }
-
-      // console.debug("[srt] insertNode", parent.id, node.id, anchor?.id ?? "")
-
-      if (anchor) tree.insertNode(parent.id, node.id, anchor.id)
-      else tree.insertNode(parent.id, node.id)
     }
   },
 
@@ -309,28 +302,185 @@ export let {
   },
 })
 
-// The app's single <window> node, set by render(). Serves as the default mount
-// target for createPortal (single window by design, so one ambient ref).
+export let { memo, createComponent, createElement, createTextNode, insertNode, spread, setProp, mergeProps, applyRef, ref } =
+  renderer
+let { effect: rawEffect, insert: rawInsert } = renderer
+
+// ------ Per-node error containment --------
+//
+// Every reactive write into the tree goes through two exports the compiled
+// JSX calls: `effect` (an element's dynamic props) and `insert` (a child
+// expression). An error thrown while computing either is contained right
+// there: the props or children keep their last good value, the effect stays
+// subscribed (the throwing read is tracked, so fixing it recomputes and the
+// node recovers on its own), and the rest of the app keeps running. Without
+// this one unclaimed error halts the whole reactive system. A NotReadyError
+// is not an error but a pending async read on its way to the nearest
+// <Loading>, so it passes through. Reported once per site until it recovers,
+// not once per run. What escapes these two (a user createEffect that throws)
+// still reaches render()'s root boundary.
+const SKIP = Symbol("skip")
+
+function guard<T>(fn: (prev?: T) => T, describe: () => string, nested: boolean, empty: T): (prev?: T) => T {
+  let last = empty
+  let failing = false
+  return (prev?: T) => {
+    try {
+      let value = fn(prev === SKIP ? undefined : prev)
+      if (failing) {
+        failing = false
+        console.warn(`Recovered: ${describe()} computes again`)
+      }
+      // A child expression resolving to a function is read by an inner
+      // effect (universal's insert); that read gets the same containment.
+      // Solid's flatten only unwraps zero-arity functions and inserts any
+      // other function as a node, so only accessors are wrapped, and the
+      // wrapper keeps arity 0.
+      if (nested && typeof value === "function" && value.length === 0) {
+        let inner = guard(value as any, describe, true, empty)
+        value = (() => inner()) as any
+      }
+      last = value
+      return value
+    } catch (e) {
+      if (e instanceof NotReadyError) throw e
+      if (!failing) {
+        failing = true
+        console.error(`Contained error: ${describe()} threw and keeps its last value until it computes again.`, e)
+      }
+      return last
+    }
+  }
+}
+
+// Universal's declarations trail its runtime (effect takes options, insert
+// takes initial and options), so the wrappers carry the runtime signatures.
+type EffectFn = <T>(fn: (prev?: T) => T, effectFn?: (value: T, prev?: T) => void, options?: unknown) => void
+type InsertFn = (parent: ProxyNode, accessor: unknown, marker?: unknown, initial?: unknown, options?: unknown) => ProxyNode
+let effectRaw = rawEffect as unknown as EffectFn
+let insertRaw = rawInsert as unknown as InsertFn
+
+export let effect: EffectFn = (fn, effectFn, options) =>
+  effectRaw<any>(
+    guard<any>(fn, () => "an element's prop expression", false, SKIP),
+    effectFn && ((value, prev) => (value === SKIP ? undefined : effectFn(value, prev === SKIP ? undefined : prev))),
+    options,
+  )
+
+export let insert: InsertFn = (parent, accessor, marker, initial, options) =>
+  insertRaw(
+    parent,
+    typeof accessor === "function"
+      ? guard(accessor as any, () => `a child expression of <${parent.elementType}> ${getNodePath(parent.id).join("/")}`, true, undefined)
+      : accessor,
+    marker,
+    initial,
+    options,
+  )
+
+// The current <window> node: the app's, or the error window standing in for
+// it. Serves as the default mount target for createPortal (single window by
+// design, so one ambient ref).
 let windowRoot: ProxyNode | undefined
+let rendered = false
+// Ids of error windows built by the root boundary, alive only while shown.
+let errorWindows = new Set<number>()
 
 /**
  * Mounts a SolidRT app. Call once at the top level: `render(() => <App />)`.
  * The element returned by `code` MUST be a `<window>` (it becomes the native
  * window and root of the render tree); anything else throws. Runs inside a
  * reactive root, so the whole tree is disposed together on engine reload.
+ *
+ * The whole app, window included, sits inside an error boundary: an error no
+ * <Errored> claims replaces the app's window with an error window (message,
+ * stack, a reset button) instead of halting the reactive system for good.
+ * The app's subtree stays alive behind it - the boundary keeps it and marks
+ * only the failed computations - so reset recomputes those in place and the
+ * same window node comes back.
  */
 export function render(code: () => any) {
+  // Once per app: there is no unmount; teardown is engine teardown.
+  if (rendered) {
+    throw new Error("render() already called; an app has exactly one render()")
+  }
+  rendered = true
   createRoot(() => {
-    let root = code()
-    if (!root || root.elementType !== "window") {
-      throw new Error("render() root must be a <window> element")
-    }
-    windowRoot = root
-    attachWindow(root.id)
-    insert(null, root)
+    let root = createErrorBoundary(
+      () => {
+        let win = code()
+        if (!win || win.elementType !== "window") {
+          throw new Error("render() root must be a <window> element")
+        }
+        return win
+      },
+      (error, reset) => {
+        // The boundary hands the error as an accessor.
+        let err = error()
+        console.error("Uncaught error: the app is replaced by the error window until reset or reload.", err)
+        let win = errorWindow(err, reset)
+        errorWindows.add(win.id)
+        return win
+      },
+    )
+    rawEffect(
+      () => root() as ProxyNode,
+      (win, prev) => swapRoot(win, prev),
+    )
   })
 }
 
+// The boundary's value changed: the app's window on mount and after a
+// successful reset, an error window after an error. Creating a window already
+// made it the native root; setRoot is the way back to an existing one.
+function swapRoot(win: ProxyNode, prev?: ProxyNode) {
+  windowRoot = win
+  if (prev === undefined) {
+    attachWindow(win.id)
+    return
+  }
+  // Creating the error window made it the native root; the app's window
+  // coming back is the case that needs the explicit way back.
+  if (!errorWindows.has(win.id)) tree.setRoot(win.id)
+  setWindowRoot(win.id)
+  // Keys route to the focused node; one inside the hidden window must not
+  // keep hearing them.
+  setFocus(null)
+  // The app's window survives behind an error window (the boundary keeps its
+  // subtree for reset); an error window replaced by anything is dead.
+  if (errorWindows.has(prev.id) || !errorWindows.has(win.id)) {
+    errorWindows.delete(prev.id)
+    destroyNode(prev)
+  }
+}
+
+// The error window: the in-app sibling of the runtime's startup BSOD, built
+// from the primitives directly (no JSX in core). Static content; the reset
+// button recomputes the failed sources, and a reload replaces everything.
+function errorWindow(err: unknown, reset: () => void): ProxyNode {
+  let message = err instanceof Error ? err.message : String(err)
+  let stack = err instanceof Error && err.stack ? err.stack : ""
+  let text = (content: string, props: Record<string, any>) => {
+    let node = createElement("text", props)
+    insertNode(node, createTextNode(content))
+    return node
+  }
+  let win = createElement("window", { title: "Application error" })
+  insertNode(win, createElement("d-rect", { color: "#1144bb" }))
+  let column = createElement("view", { flexGrow: 1, flexDirection: "column", padding: 40, gap: 12 })
+  insertNode(column, text(":(", { color: "white", fontSize: 64, fontWeight: 700 }))
+  insertNode(column, text("Something went wrong", { color: "white", fontSize: 22 }))
+  insertNode(column, text(message, { color: "white", fontSize: 16 }))
+  if (stack) insertNode(column, text(stack, { color: "#aac2ff", fontSize: 12, fontFamily: "mono" }))
+  insertNode(column, text("Fix the error and save to reload, or reset to retry the failed computations.", { color: "#aac2ff", fontSize: 14 }))
+  let button = createElement("view", { alignSelf: "flex-start", padding: 12, onPointerDown: () => reset() })
+  insertNode(button, createElement("d-rect", { color: "white", radius: 6 }))
+  insertNode(button, text("Reset", { color: "#1144bb", fontSize: 16, fontWeight: 600 }))
+  insertNode(column, button)
+  insertNode(win, column)
+  return win
+}
+
 /**
  * Relocates an already-built node out of its lexical position to `mount` (the
  * window root by default), then removes it again when the surrounding reactive
@@ -362,6 +512,11 @@ export function createPortal(node: Element, mount?: ProxyNode): null {
     throw new Error("createPortal: node must be a single built element")
   }
   insertNode(target, node as ProxyNode)
-  onCleanup(() => removeNode(target, node as ProxyNode))
+  // A destroyed mount target has already swept the portaled node with it
+  // (destroy walks the mount tree), so detaching then would hand freed ids to
+  // the native side, which panics. Gone from the proxy map = already freed.
+  onCleanup(() => {
+    if (nodes.has((node as ProxyNode).id)) removeNode(target, node as ProxyNode)
+  })
   return null
 }

package/src/runtime-modules.d.ts

@@ -47,6 +47,10 @@ declare module "*.ogg" {
   const bytes: Uint8Array
   export default bytes
 }
+declare module "*.glb" {
+  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

package/src/scroll.ts

@@ -4,7 +4,7 @@
 // momentum, scrollbars and styling are policy and belong to the component (the
 // "skin") that composes this, the same way createTextEditorLayout backs TextInput.
 
-import { createSignal, flush } from "@solidjs/signals"
+import { createSignal } from "@solidjs/signals"
 import { getBoundingBox } from "./core"
 import { onLayout } from "./window"
 
@@ -12,6 +12,15 @@ export type ScrollAxis = "vertical" | "horizontal" | "both"
 
 export type ScrollOffset = { x: number; y: number }
 
+/** The web's scroll behavior word, simplified: "instant" asks the skin for no
+ * motion; "auto" (the default) and "smooth" both mean its usual motion, since
+ * the default already animates. */
+export type ScrollBehavior = "auto" | "instant" | "smooth"
+
+/** Target of scrollTo/scrollBy. An omitted axis keeps its offset (scrollTo)
+ * or moves by 0 (scrollBy). */
+export type ScrollToOptions = { x?: number; y?: number; behavior?: ScrollBehavior }
+
 export type ScrollOptions = {
   /** Which axes can scroll. Locked axes are pinned to 0. Default "vertical". */
   axis?: ScrollAxis
@@ -20,10 +29,18 @@ export type ScrollOptions = {
 export type Scroll = {
   /** Current clamped offset, as a reactive accessor. */
   offset(): ScrollOffset
-  /** Scroll by a delta (positive moves content up/left), clamped to range. */
-  scrollBy(dx: number, dy: number): void
+  /** Largest reachable offset per axis (content overflow, 0 on a locked axis),
+   * as a reactive accessor refreshed each layout. Watching it is how a scroll
+   * policy learns that the content or the viewport changed size. */
+  range(): ScrollOffset
+  /** Behavior of the latest scrollTo/scrollBy, as a reactive accessor: the
+   * skin reads it to withhold its motion for an instant write. Layout
+   * re-clamps leave it alone. */
+  behavior(): ScrollBehavior
   /** Scroll to an absolute offset, clamped to range. */
-  scrollTo(x: number, y: number): void
+  scrollTo(options: ScrollToOptions): void
+  /** Scroll by a delta (positive moves content up/left), clamped to range. */
+  scrollBy(options: ScrollToOptions): void
 }
 
 /**
@@ -32,7 +49,9 @@ export type Scroll = {
  * current content-vs-viewport overflow, so the view stays valid when content
  * grows or shrinks (e.g. an offset that scrolled to the bottom snaps up when the
  * list gets shorter). scrollBy/scrollTo clamp against the most recently measured
- * range. Pure geometry: no input handling and no visual policy.
+ * range. Pure geometry: no input handling and no visual policy. Anything beyond
+ * clamping (following a growing log, keeping an item in view) is a policy the
+ * caller writes against `range()` and `offset()`.
  *
  * The viewport node is the clipping box (overflow hidden); the content node is
  * the inner wrapper that holds the children and takes their natural size. Apply
@@ -48,6 +67,11 @@ export function createScroll(
   let canY = axis === "vertical" || axis === "both"
 
   let [offset, setOffset] = createSignal<ScrollOffset>({ x: 0, y: 0 })
+  let [range, setRange] = createSignal<ScrollOffset>({ x: 0, y: 0 })
+  let [behavior, setBehavior] = createSignal<ScrollBehavior>("auto")
+  // Mirrors the signal: a setter's value is not readable until the flush, and
+  // two writes in one batch must still compare against the latest.
+  let lastBehavior: ScrollBehavior = "auto"
 
   // A scroll viewport with no explicit main-axis size resolves to 0 in flex
   // layout and its content silently vanishes - a classic trap (maxHeight alone
@@ -59,6 +83,8 @@ export function createScroll(
 
   // Last measured overflow, refreshed each layout. scrollBy/scrollTo clamp
   // against these between layouts; onLayout re-clamps once new sizes are known.
+  // Kept as plain values beside the `range` signal because a signal write is
+  // not readable until the flush, and clamping needs the number now.
   let maxX = 0
   let maxY = 0
 
@@ -67,10 +93,14 @@ export function createScroll(
     y: canY ? Math.max(0, Math.min(y, maxY)) : 0,
   })
 
-  let set = (x: number, y: number) => {
+  let set = (x: number, y: number, b: ScrollBehavior = "auto") => {
     let cur = offset()
     let next = clamp(x, y)
     if (next.x !== cur.x || next.y !== cur.y) setOffset(next)
+    if (b !== lastBehavior) {
+      lastBehavior = b
+      setBehavior(b)
+    }
   }
 
   onLayout(() => {
@@ -94,20 +124,26 @@ export function createScroll(
     }
     maxX = Math.max(0, cb.width - vb.width)
     maxY = Math.max(0, cb.height - vb.height)
+    let r = range()
+    let rx = canX ? maxX : 0
+    let ry = canY ? maxY : 0
+    if (r.x !== rx || r.y !== ry) setRange({ x: rx, y: ry })
     let cur = offset()
     let next = clamp(cur.x, cur.y)
-    if (next.x !== cur.x || next.y !== cur.y) {
-      setOffset(next)
-      flush()
-    }
+    if (next.x !== cur.x || next.y !== cur.y) setOffset(next)
   })
 
   return {
     offset,
-    scrollBy: (dx, dy) => {
+    range,
+    behavior,
+    scrollTo: (o) => {
       let cur = offset()
-      set(cur.x + dx, cur.y + dy)
+      set(o.x ?? cur.x, o.y ?? cur.y, o.behavior)
+    },
+    scrollBy: (o) => {
+      let cur = offset()
+      set(cur.x + (o.x ?? 0), cur.y + (o.y ?? 0), o.behavior)
     },
-    scrollTo: (x, y) => set(x, y),
   }
-}
+}

package/src/svg.ts

@@ -46,7 +46,7 @@ export type SvgDocument = {
  * that fits the document's coordinate space into its box:
  *
  *     let doc = createMemo(() => parseSvg(src))
- *     <view repaintBoundary viewBox={[doc().width, doc().height]} width={48} height={48}>
+ *     <view repaintBoundary designSize={[doc().width, doc().height]} width={48} height={48}>
  *       {doc().draws.map((draw) => <d-path {...draw} />)}
  *     </view>
  *

package/src/text-input.ts

@@ -397,7 +397,6 @@ export function createTextEditorLayout(
 
     setScrollX(wrap ? 0 : follow(scrollX(), c.x, caretWidth, vw, contentWidth + caretWidth))
     setScrollY(follow(scrollY(), c.y, c.height, vh, contentHeight))
-    flush()
   })
 
   return { lines, caret, caretLine, offsetAtX, lineAtY, step, scrollX, scrollY }

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"
@@ -365,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
@@ -468,7 +474,20 @@ export type TransitionPropName =
   | "y1"
   | "x2"
   | "y2"
+  | "scrollX"
+  | "scrollY"
   | "opacity"
+  | "originX"
+  | "originY"
+  | "perspective"
+  | "clipRadius"
+  | "srcX"
+  | "srcY"
+  | "srcW"
+  | "srcH"
+  | "onLength"
+  | "offLength"
+  | "dashOffset"
   | "rotate"
   | "rotateX"
   | "rotateY"
@@ -558,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
   /**
@@ -580,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.
-   */
-  viewBox?: [number, number]
+   * 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.
+   */
+  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
@@ -614,6 +643,9 @@ 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"
   /**
@@ -653,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
@@ -698,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
+}
+
+// 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
 }
 
-export interface PathProps extends PaintProps, PointerProps {
+/**
+ * `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"
 }