@solidrt/core 0.0.49 → 0.0.50

package/AGENTS.md

@@ -159,6 +159,17 @@ Peer deps @solidjs/signals and @solidjs/universal must match (currently
   expression container preserves it - `<d-text>{"one    two"}</d-text>` - and
   `\n` inside one produces a hard line break.
 
+- Rich text: `<span>` inside `<text>` restyles a run (`color`, `fontFamily`,
+  `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`); spans nest and
+  inherit inward from the `<text>`. Never lay a paragraph out word by word in
+  a wrapping row to mix styles - one `<text>` with spans wraps as a whole.
+  A span is content, not a box (no layout or `d-` form, no size, no
+  bounding box; it takes its parent's form). A `<span>` takes
+  pointer handlers (a link is a span, hit per line it spans), and any other
+  element child of `<text>` (`<view>`, `<texture>`, `<path>`, ...) is an
+  inline atom flowing with the words as one unbreakable box on the baseline;
+  give it margins for spacing, since JSX trims the whitespace around it.
+
 - Events: there is NO `onClick`/`onPress`. A "button" is a `<view>`/`<rect>`
   with `onPointerDown`. Handlers: onPointerDown/Up/Move/Enter/Leave, onWheel,
   onKeyDown/Up, onTextInput, onFocus/onBlur. Text entry: focus a node with an

package/examples/README.md

@@ -48,7 +48,7 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `window-shader-history.tsx` - the window shader's frame history: `previous` binds last frame as uPrevious, drawn as a one-frame motion echo behind an orbiting square; click toggles the echo term.
 
 ## Sound
-- `sound.tsx` - `createSound`: decode a clip once from bytes (here a binary import), replay cheaply; `overlap` stacking vs single-voice, `playing()` signal, release on unmount. Points to `createSoundStream` for long tracks streamed from a path.
+- `sound.tsx` - `createSound`: decode a clip once from bytes (here a binary import), replay cheaply; `overlap` stacking vs single-voice, `playing()` signal, release on unmount. `createPcmSound` for a synthesised clip from raw samples (a generated sine sweep). Points to `createSoundStream` for long tracks streamed from a path.
 
 ## Vector graphics
 - `parse-svg.tsx` - `parseSvg` turns a whole SVG *document string* (not HTML/JSX children) into plain draw data mapped to `<d-path>` inside a `viewBox`-fitted view; per-shape hover highlighting shows the payoff (exact-outline hit testing, recolor without re-parse), plus a `currentColor` icon recolored via the `color` option. This is how to use existing icon libraries (Lucide, Heroicons, etc.) - hand their SVG source to `parseSvg`.

package/examples/sound.tsx

@@ -14,14 +14,32 @@
 // selection tick. playing() is a signal: true from play() until stop() (it
 // does not flip back when a clip ends naturally).
 //
+// Sounds you can compute need no bytes at all: createPcmSound takes raw
+// samples (here a 60 ms sine sweep in an Int16Array) and gives the same handle
+// - generate it, do not ship it. Same reactive ownership as createSound.
+//
 // For a long track (music, ambience) do not load bytes at all: pass a file
 // path to createSoundStream from the same module, which decodes from disk on
 // demand and stays off the heap. Same play()/stop()/playing() surface,
 // always single-voice.
 import { render } from "@solidrt/core"
-import { createSound } from "@solidrt/core/sound"
+import { createPcmSound, createSound } from "@solidrt/core/sound"
 import blipBytes from "./blip.wav" with { type: "binary" }
 
+const RATE = 44100
+// A short sweep from 880 Hz down to 440 Hz with a linear fade-out.
+function sweep(): Int16Array {
+  let n = Math.round(RATE * 0.06)
+  let out = new Int16Array(n)
+  let phase = 0
+  for (let i = 0; i < n; i++) {
+    let t = i / n
+    phase += (2 * Math.PI * (880 - 440 * t)) / RATE
+    out[i] = Math.round(Math.sin(phase) * (1 - t) * 0.6 * 32767)
+  }
+  return out
+}
+
 function Button(props: { label: string; onTap: () => void }) {
   return (
     <view onPointerDown={props.onTap} padding={12} clipRadius={8}>
@@ -34,13 +52,15 @@ function Button(props: { label: string; onTap: () => void }) {
 function App() {
   let blip = createSound(blipBytes, { gain: 0.8 })
   let tick = createSound(blipBytes, { overlap: false })
+  let synth = createPcmSound(sweep(), RATE)
 
   return (
     <window padding={20} gap={8} alignItems="flex-start">
       <Button label="Blip (tap fast to stack voices)" onTap={() => blip.play()} />
       <Button label="Tick (overlap: false, restarts)" onTap={() => tick.play()} />
-      <Button label="Stop" onTap={() => { blip.stop(); tick.stop() }} />
-      <text color="#888">{blip.playing() || tick.playing() ? "playing" : "silent"}</text>
+      <Button label="Sweep (createPcmSound, generated)" onTap={() => synth.play()} />
+      <Button label="Stop" onTap={() => { blip.stop(); tick.stop(); synth.stop() }} />
+      <text color="#888">{blip.playing() || tick.playing() || synth.playing() ? "playing" : "silent"}</text>
     </window>
   )
 }

package/jsx-runtime.d.ts

@@ -7,6 +7,7 @@ import type {
   ViewProps,
   ViewOwnProps,
   TextProps,
+  SpanProps,
   TextureProps,
   LayoutProps,
   PositionProps,
@@ -54,5 +55,8 @@ export namespace JSX {
     "d-path": PathProps & PositionProps & ElementRef
     "d-texture": TextureProps & GeometryProps & ElementRef
     "d-text": TextProps & TextGeometryProps & ElementRef
+    // A styled run inside <text>/<d-text>; never has a layout box, so there is
+    // no d- form.
+    span: SpanProps & ElementRef
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -27,7 +27,7 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.49"
+    "@solidrt/flux-types": "0.0.50"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.0",

package/src/core.ts

@@ -331,4 +331,73 @@ export function getBoundingBoxViewport(node: { id: number }): BoundingBox | null
  */
 export function measureText(text: string, options?: tree.MeasureTextOptions): { width: number, height: number } {
   return tree.measureText(text, options)
+}
+
+/**
+ * Segments `text` into wrap units (words with their trailing whitespace) and
+ * shapes each in the given font, once, for laying lines out in app code with
+ * layoutNextLine or arithmetic of your own over `units`. For the non-standard
+ * case (text into a shape, around a moving obstacle, handed between columns,
+ * fitted by size); regular text of any length is a <text>.
+ */
+export function prepareText(text: string, options?: tree.MeasureTextOptions): tree.PreparedText {
+  return tree.prepareText(text, options)
+}
+
+/** One laid-out line from layoutNextLine. */
+export type TextLine = {
+  /** Unit range [from, to) into prepared.units. */
+  from: number
+  to: number
+  /** Character range into prepared.text: `text.slice(start, end)` is the line's text (break characters included). */
+  start: number
+  end: number
+  /** Ink width: the units' advances plus the last unit's width, without its trailing whitespace. */
+  width: number
+  /** Tallest ascent plus tallest descent on the line. */
+  height: number
+  ascent: number
+  /** The line ended at a hard break rather than by running out of width. */
+  hardBreak: boolean
+  /** Where the next line starts; equal to `to`. */
+  cursor: number
+}
+
+/**
+ * The next line of `prepared` from unit `cursor` that fits `width`, or null
+ * when the text is used up. Greedy: units go on the line while the pen plus
+ * the unit's ink stays within `width`; a hard break ends the line; a unit
+ * wider than `width` on its own goes on the line whole and overflows. Draw a
+ * line as `<d-text x y w={line.width + 1}>{prepared.text.slice(line.start, line.end)}</d-text>`
+ * with the same font options; its words are already shaped, so that is
+ * cheap. Floats, balancing and ellipsis are <text> features, not this.
+ */
+export function layoutNextLine(prepared: tree.PreparedText, cursor: number, width: number): TextLine | null {
+  let units = prepared.units
+  if (cursor >= units.length) return null
+  let pen = 0
+  let ascent = 0
+  let descent = 0
+  let i = cursor
+  while (i < units.length) {
+    let unit = units[i]!
+    if (i > cursor && pen + unit.width > width) break
+    pen += unit.advance
+    if (unit.ascent > ascent) ascent = unit.ascent
+    if (unit.descent > descent) descent = unit.descent
+    i++
+    if (unit.hardBreak) break
+  }
+  let last = units[i - 1]!
+  return {
+    from: cursor,
+    to: i,
+    start: units[cursor]!.start,
+    end: last.end,
+    width: pen - last.advance + last.width,
+    height: ascent + descent,
+    ascent,
+    hardBreak: last.hardBreak,
+    cursor: i,
+  }
 }

package/src/gpu.ts

@@ -21,8 +21,10 @@
 // `<texture>` elements and set their `blendMode` (e.g. `blendMode="plus"` for
 // an additive pass over a base pass) instead of writing a pass that samples
 // both. WITHIN one pipeline draw, `blend: "add"` accumulates overlapping
-// geometry additively (order-independent, no sorting); anything else draws
-// with GL blending disabled and overwrites.
+// geometry additively and `blend: "multiply"` scales it (both
+// order-independent, no sorting); `blend: "alpha"` composites over in
+// draw-list order (order-dependent: the app or a scene layer sorts); anything
+// else draws with GL blending disabled and overwrites.
 //
 // The pixel contract. Three facts hold for every texture and target:
 //
@@ -40,8 +42,8 @@
 //   default transparent black needs no thought.
 // - Values are non-linear RGBA8, with no color-space concept. Every texture
 //   and target holds 8-bit RGBA UNORM exactly as written; nothing converts to
-//   or from linear light. `filter: "linear"` averages and `blend: "add"`
-//   accumulates non-linear values - the usual approximation, stated so
+//   or from linear light. `filter: "linear"` averages and the `blend` modes
+//   accumulate non-linear values - the usual approximation, stated so
 //   shaders written today stay correct if a format vocabulary arrives.
 
 import { createEffect, createSignal, getOwner, onCleanup, untrack } from "@solidjs/signals"
@@ -512,10 +514,12 @@ function toUint8(data: ArrayBuffer | ArrayBufferView): Uint8Array {
  * `opts.depth` attaches a private depth buffer (cleared + tested per render);
  * `opts.depthWrite: false` (requires depth) keeps the test but stops the
  * draw from writing depth. `opts.blend: "add"` makes the draw accumulate
- * overlapping geometry additively (order-independent, no sorting) instead of
- * overwriting; a depth-tested additive pass is `{ depth: true, blend: "add",
- * depthWrite: false }` - each option only does what it says, neither implies
- * the other. The draw range (`firstVertex`, `vertexCount`, `instanceCount` -
+ * overlapping geometry additively and `"multiply"` makes it scale (darken)
+ * what is already there, both order-independent (no sorting) instead of
+ * overwriting; `"alpha"` composites over in draw-list order (premultiplied
+ * output, back-to-front is the caller's job). A depth-tested blended pass is
+ * `{ depth: true, blend: "add", depthWrite: false }` - each option only does
+ * what it says, neither implies the other. The draw range (`firstVertex`, `vertexCount`, `instanceCount` -
  * see DrawRange) defaults to the whole buffer drawn once and can be changed
  * later with `setDraw`; `instanceCount` is the standard answer to particles
  * and repeated meshes, N copies of the range told apart by `gl_InstanceID`

package/src/index.ts

@@ -1,6 +1,6 @@
 export * from "./renderer"
-export { setFocus, focusedNode, startTextInput, textInputActive, getFocusables, measureText, getBoundingBox, getBoundingBoxViewport, onPointerMove } from "./core"
-export type { BoundingBox, GlobalPointerEvent } from "./core"
+export { setFocus, focusedNode, startTextInput, textInputActive, getFocusables, measureText, prepareText, layoutNextLine, getBoundingBox, getBoundingBoxViewport, onPointerMove } from "./core"
+export type { BoundingBox, GlobalPointerEvent, TextLine } from "./core"
 export { parseColor, mixColors, brightness, createLinearGradient, createRadialGradient } from "./color"
 export type { Gradient, GradientStop } from "./color"
 export { onFrame, onLayout, onResize, onWindowFocus, onWindowBlur, onBack, exit } from "./window"
@@ -49,7 +49,7 @@ export type {
   Color,
   Pct,
 } from "./types"
-export type { MeasureTextOptions } from "flux:rendertree"
+export type { MeasureTextOptions, PreparedText, TextUnit } from "flux:rendertree"
 
 // A percentage value for dimensional props (e.g. transformOrigin): `pct(50)` is
 // half the element box. Keeps percentages a first-class branded value rather

package/src/renderer.ts

@@ -233,10 +233,12 @@ export let {
     return proxy
   },
 
+  // A string child of <text> or <span>: a run of its parent's content, with
+  // no element form of its own (the DOM's "#text" node name).
   createTextNode: (value: string): ProxyNode => {
-    let proxy = createProxyNode("d-span")
+    let proxy = createProxyNode("#text")
     // console.debug("[srt] createTextNode", proxy.id, value)
-    tree.createNode(proxy.id, "d-span")
+    tree.createNode(proxy.id, "#text")
     tree.setProperty(proxy.id, "text", "" + value)
     return proxy
   },
@@ -246,7 +248,7 @@ export let {
     tree.setProperty(node.id, "text", "" + value)
   },
 
-  isTextNode: (node: ProxyNode): boolean => node?.elementType === "d-span",
+  isTextNode: (node: ProxyNode): boolean => node?.elementType === "#text",
   setProperty: <T>(node: ProxyNode, name: string, value: T): void => {
     // console.debug("[srt] setProperty", node.id, name, value)
     applyProp(node, name, value)

package/src/sound.ts

@@ -1,14 +1,15 @@
 // Sound playback, reactive (SolidJS) layer. `createSound` decodes an encoded
 // clip (Ogg/Vorbis or WAV) once and owns its lifecycle: the decoded clip is
 // released, and any playing voices stopped, when the reactive owner is disposed.
-// Each play() is cheap (no re-decode). `createSoundStream` is the same but reads
-// a large track from a file path on demand instead of decoding it into memory.
+// Each play() is cheap (no re-decode). `createPcmSound` is the same over raw
+// samples the app generated itself; `createSoundStream` reads a large track
+// from a file path on demand instead of decoding it into memory.
 //
 // The imperative primitive lives in the `flux:audio` module; import
 // { play, load, loadPcm, stream } from "flux:audio" for non-reactive use.
 
 import { createSignal, onCleanup } from "@solidjs/signals"
-import { load, stream } from "flux:audio"
+import { load, loadPcm, stream } from "flux:audio"
 import { file } from "flux:fs"
 
 type FluxFile = ReturnType<typeof file>
@@ -34,6 +35,12 @@ export type SoundOptions = {
   overlap?: boolean
 }
 
+/** Options for a PCM sound: `SoundOptions` plus the channel count. */
+export type PcmSoundOptions = SoundOptions & {
+  /** Channel count, interleaved samples when 2. Defaults to 1 (mono). */
+  channels?: 1 | 2
+}
+
 /** Options for a streamed sound. Streams are always single-voice. */
 export type SoundStreamOptions = {
   /** Repeat the track until stopped. Defaults to false. */
@@ -140,6 +147,27 @@ export function createSound(source: Uint8Array, options: SoundOptions = {}): Sou
   })
 }
 
+/**
+ * A sound over raw PCM samples the app generated itself - no decoding, no
+ * container. The typed array is the sample format (Uint8Array = unsigned
+ * 8-bit, Int16Array = signed 16-bit, Float32Array = 32-bit float), interleaved
+ * when `channels` is 2. Same handle and lifecycle as createSound; on a box with
+ * no audio device the clip fails to load, so `error()` is set and play() is a
+ * no-op, exactly like createSound there. For imperative use, call loadPcm()
+ * from "flux:audio".
+ */
+export function createPcmSound(
+  samples: Uint8Array | Int16Array | Float32Array,
+  sampleRate: number,
+  options: PcmSoundOptions = {},
+): Sound {
+  return reactiveSound(() => loadPcm(samples, sampleRate, { channels: options.channels }), options.overlap ?? true, {
+    loop: options.loop,
+    gain: options.gain,
+    pan: options.pan,
+  })
+}
+
 /**
  * Streams a large track, decoding on demand instead of loading it into memory.
  * Single-voice: each play() restarts it. Pass a path (resolved like flux:fs,

package/src/types.d.ts

@@ -131,6 +131,21 @@ export interface LayoutProps extends FlexboxProps, GridProps {
   overflow?: "visible" | "clip" | "hidden" | "scroll"
   overflowX?: "visible" | "clip" | "hidden" | "scroll"
   overflowY?: "visible" | "clip" | "hidden" | "scroll"
+
+  /**
+   * As an inline atom (an element child of <text>): leave the flow and sit
+   * against that side of the text, at the top of the line where the atom
+   * occurs; the lines it overlaps wrap around its margin box. Same-side
+   * floats overlapping vertically sit beside each other. The text's height
+   * includes the float. Meaningless outside a <text>.
+   */
+  float?: "left" | "right"
+  /**
+   * As an inline atom: start a new line below the text's earlier floats on
+   * that side (a floated atom goes below them instead of beside). An empty
+   * `<view clear="both" />` is the section break after an image.
+   */
+  clear?: "left" | "right" | "both"
 }
 
 /** Colors are CSS color strings, parsed to a packed u32 by `parseColor`. */
@@ -545,8 +560,12 @@ export interface PathProps extends PaintProps, PointerProps {
   fillRule?: "nonzero" | "evenodd"
 }
 
-export interface TextProps extends PaintProps, PointerProps {
-  children?: Children
+/**
+ * Per-run text style: the paragraph default on <text>, an override on <span>.
+ * The cascade is intra-paragraph only: a span inherits from its enclosing
+ * span, then from the <text>; nothing inherits across the tree.
+ */
+export interface TextRunProps {
   fontFamily?: "sans" | "serif" | "mono" | (string & {})
   fontSize?: number
   /**
@@ -557,8 +576,49 @@ export interface TextProps extends PaintProps, PointerProps {
   lineHeight?: number
   fontStyle?: "normal" | "italic"
   fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+}
+
+/**
+ * A styled run inside <text>. Inline text only: children are text and other
+ * spans. `color` takes what a text's color takes (solid or gradient).
+ * Pointer handlers fire for the boxes of the run's own text on each line it
+ * spans and bubble to the enclosing spans and text.
+ */
+export interface SpanProps extends TextRunProps, PointerProps {
+  children?: Children
+  color?: Color | Gradient
+}
+
+export interface TextProps extends PaintProps, PointerProps, TextRunProps {
+  children?: Children
   textAlign?: "left" | "right" | "center" | "justify"
   maxLines?: number
+  /**
+   * What happens to text cut off by maxLines: "clip" (default), "ellipsis"
+   * (a U+2026 at the end of the last line), or any other string to use as
+   * the ellipsis. Drawn in the paragraph's default style.
+   */
+  textOverflow?: "clip" | "ellipsis" | (string & {})
+  /**
+   * A word (wrap unit) wider than the line: "anywhere" (default) splits it
+   * at grapheme boundaries so it stays inside the box, "normal" keeps it
+   * whole and lets it overflow (CSS's default).
+   */
+  overflowWrap?: "normal" | "anywhere"
+  /**
+   * First-line indent in pixels. Negative hangs: the first line starts at 0
+   * and every following line is indented by the magnitude. A hard break does
+   * not start a new first line.
+   */
+  textIndent?: number
+  /**
+   * How lines are chosen beyond greedy fitting (CSS text-wrap): "wrap"
+   * (default) is greedy; "balance" evens the line lengths while keeping the
+   * line count (headings, captions); "pretty" is greedy except that a lone
+   * word on the last line pulls one down from the line above. Neither
+   * applies once maxLines truncates.
+   */
+  textWrap?: "wrap" | "balance" | "pretty"
 }
 
 /**