@sarmal/core 0.36.4 → 0.37.0

package/dist/{renderer-shared-CFimm7VD.d.cts → renderer-shared-BDDSZhB6.d.cts}

@@ -1,4 +1,4 @@
-import { P as Point } from './types-CCgSK31t.cjs';
+import { P as Point } from './types-DS2VYCEa.cjs';
 
 interface BoundaryResult {
     scale: number;

package/dist/{renderer-shared-BZV9ELOa.d.ts → renderer-shared-D7ZDFZqK.d.ts}

@@ -1,4 +1,4 @@
-import { P as Point } from './types-CCgSK31t.js';
+import { P as Point } from './types-DS2VYCEa.js';
 
 interface BoundaryResult {
     scale: number;

package/dist/terminal.d.cts

@@ -1,5 +1,5 @@
-import { C as CurveDef } from './types-CCgSK31t.cjs';
-import { R as Rgb } from './renderer-shared-CFimm7VD.cjs';
+import { C as CurveDef } from './types-DS2VYCEa.cjs';
+import { R as Rgb } from './renderer-shared-BDDSZhB6.cjs';
 
 type ColorCapability = "truecolor" | "256-color" | "monochrome";
 type DotCol = 0 | 1;

package/dist/terminal.d.ts

@@ -1,5 +1,5 @@
-import { C as CurveDef } from './types-CCgSK31t.js';
-import { R as Rgb } from './renderer-shared-BZV9ELOa.js';
+import { C as CurveDef } from './types-DS2VYCEa.js';
+import { R as Rgb } from './renderer-shared-D7ZDFZqK.js';
 
 type ColorCapability = "truecolor" | "256-color" | "monochrome";
 type DotCol = 0 | 1;

package/dist/{types-CCgSK31t.d.cts → types-DS2VYCEa.d.cts}

@@ -244,9 +244,10 @@ interface SarmalInstance<T extends BaseRuntimeRenderOptions = RuntimeRenderOptio
  */
 type TrailStyle = "default" | "gradient-static" | "gradient-animated";
 /**
- * The value must be a single hex string or an array of hex strings.
+ * A single color string or an array of color strings for gradient trails.
  *
- * ! Named colors, shorthand hex, `rgb()`,  and `hsl()` notations are not yet supported.
+ * Accepted formats: `#rrggbb`, `#rgb`, `rgb()`, `rgba()`, `oklch()`.
+ * ! `hsl()` and named colors (e.g. `"red"`) are not supported.
  */
 type TrailColor = string | string[];
 /**

package/dist/{types-CCgSK31t.d.ts → types-DS2VYCEa.d.ts}

@@ -244,9 +244,10 @@ interface SarmalInstance<T extends BaseRuntimeRenderOptions = RuntimeRenderOptio
  */
 type TrailStyle = "default" | "gradient-static" | "gradient-animated";
 /**
- * The value must be a single hex string or an array of hex strings.
+ * A single color string or an array of color strings for gradient trails.
  *
- * ! Named colors, shorthand hex, `rgb()`,  and `hsl()` notations are not yet supported.
+ * Accepted formats: `#rrggbb`, `#rgb`, `rgb()`, `rgba()`, `oklch()`.
+ * ! `hsl()` and named colors (e.g. `"red"`) are not supported.
  */
 type TrailColor = string | string[];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarmal/core",
-  "version": "0.36.4",
+  "version": "0.37.0",
   "description": "Curve path based loading indicators and their renderer",
   "keywords": [
     "animation",
@@ -85,6 +85,7 @@
     "bench": "vitest bench"
   },
   "devDependencies": {
+    "@tanstack/intent": "0.0.41",
     "@types/node": "^25.5.2",
     "jsdom": "^29.0.2",
     "oxfmt": "^0.44.0",

package/skills/core/SKILL.md

@@ -2,7 +2,8 @@
 name: core
 description: Parametric curve loading indicators for the web. Use when adding animated
   spinners or loading indicators with @sarmal/core — covers createSarmal (canvas),
-  createSarmalSVG, built-in curves, lifecycle, and animation controls.
+  createSarmalSVG, createSarmalDotMatrix, terminal renderer, built-in curves,
+  lifecycle, animation controls, and auto-init.
 license: MIT
 ---
 
@@ -14,8 +15,9 @@ sarmal renders parametric math curves as animated loading/thinking indicators. I
 
 The package ships TypeScript definitions that are the authoritative, always-current API reference. Read them before writing any code:
 
-- `node_modules/@sarmal/core/dist/index.d.ts` — `SarmalInstance`, `SarmalOptions`, `createSarmal`, `createSarmalSVG`, `RuntimeRenderOptions`, `TrailStyle`, `TrailColor`, and all other types
+- `node_modules/@sarmal/core/dist/index.d.ts` — `SarmalInstance`, `SarmalOptions`, `SVGSarmalOptions`, `DotMatrixSarmalOptions`, `RuntimeRenderOptions`, `DotMatrixRuntimeRenderOptions`, `BaseRendererOptions`, `TrailStyle`, `TrailColor`, `Engine`, and all other types
 - `node_modules/@sarmal/core/dist/curves/index.d.ts` — `CurveName` union type listing every available built-in curve name; individual curve exports
+- `node_modules/@sarmal/core/dist/terminal.d.ts` — `terminalSarmal`, `TerminalSarmalOptions`
 
 Do not rely on training data for option names, defaults, or curve names — read the `.d.ts` files.
 
@@ -28,13 +30,28 @@ npm install @sarmal/core
 ## Entry points
 
 ```ts
-import { createSarmal, createSarmalSVG, curves } from "@sarmal/core";
+// Main package — canvas, SVG, dot matrix, utilities
+import { createSarmal, createSarmalSVG, createSarmalDotMatrix, curves } from "@sarmal/core";
+
+// Auto-init (no-JS CDN usage)
+import "@sarmal/core/auto";
+
+// Terminal renderer (Node.js only)
+import { terminalSarmal } from "@sarmal/core/terminal";
 ```
 
-**`createSarmal(canvas, curveDef, options?): SarmalInstance`** — canvas renderer  
-**`createSarmalSVG(svg, curveDef, options?): SarmalInstance`** — SVG renderer
+### Exported functions
 
-Both accept the same options and return the same `SarmalInstance` interface.
+| Function                                            | Purpose                                            |
+| --------------------------------------------------- | -------------------------------------------------- |
+| `createSarmal(canvas, curveDef, options?)`          | Canvas ribbon renderer                             |
+| `createSarmalSVG(svg, curveDef, options?)`          | SVG ribbon renderer                                |
+| `createSarmalDotMatrix(canvas, curveDef, options?)` | Dot matrix canvas renderer                         |
+| `createEngine(curveDef, trailLength?)`              | Math-only engine, no rendering                     |
+| `createRenderer(options)`                           | Low-level canvas renderer (advanced)               |
+| `createSVGRenderer(options)`                        | Low-level SVG renderer (advanced)                  |
+| `drawCurve(points, options?)`                       | Build a `CurveDef` from Catmull-Rom control points |
+| `terminalSarmal(stream, curveDef, options?)`        | Braille/ANSI terminal renderer                     |
 
 ## Using built-in curves
 
@@ -52,7 +69,7 @@ For all available curve names, read the `CurveName` type in `dist/curves/index.d
 
 ## Coordinate space — most important gotcha
 
-The two renderers use **different coordinate spaces** for all size values:
+The two ribbon renderers use **different coordinate spaces** for all size values:
 
 | Renderer                | Space               | `headRadius` default |
 | ----------------------- | ------------------- | -------------------- |
@@ -63,6 +80,8 @@ When configuring `headRadius` or any size option for the SVG renderer, use viewB
 
 The same applies to `setRenderOptions` calls on SVG instances.
 
+The dot matrix renderer does not use either coordinate space — it maps the curve onto a grid of dots specified by `cols` and `rows`.
+
 ## Lifecycle
 
 ```ts
@@ -75,6 +94,16 @@ sarmal.destroy(); // REQUIRED: stops the loop and frees resources
 
 **Always call `destroy()`** when removing the element or unmounting a component. Omitting it leaks a `requestAnimationFrame` loop.
 
+**`autoStart`** defaults to `true` — the animation begins immediately on creation. Pass `{ autoStart: false }` to start paused.
+
+**`pauseOnHidden`** defaults to `true` — the animation automatically pauses when the browser tab is hidden and resumes when visible. Pass `{ pauseOnHidden: false }` to keep running in background tabs.
+
+**`initialPhase`** — seeks to the given phase before the first frame, so the animation starts mid-curve with a full trail already rendered.
+
+```ts
+const sarmal = createSarmal(canvas, curveDef, { initialPhase: Math.PI });
+```
+
 ## Animation controls
 
 ```ts
@@ -99,29 +128,162 @@ await sarmal.morphTo(rose5, { duration: 600 });
 
 ## Runtime style changes
 
-A subset of options can be changed on a live instance via `setRenderOptions`. For the exact list, read `RuntimeRenderOptions` in `dist/index.d.ts`. Validation is strict — if any field fails, the entire call is rejected.
+`setRenderOptions` changes visual options on a live instance without recreating it. Validation is fail-atomic — if any field fails, the entire call is rejected and nothing changes.
 
 ```ts
 sarmal.setRenderOptions({
   trailColor: ["#ff0000", "#0000ff"],
   trailStyle: "gradient-animated",
+  trailWidth: 1.5, // multiplier: 1 = default, 2 = double width
   skeletonColor: "transparent", // hides the skeleton
   headColor: null, // null = derive from trail automatically
 });
 ```
 
+For the exact list of accepted fields, read `RuntimeRenderOptions` in `dist/index.d.ts`.
+
+**Dot matrix instances** use `DotMatrixRuntimeRenderOptions` which only supports `trailColor`, `trailStyle`, and `skeletonColor`. Passing `headColor`, `headRadius`, or `trailWidth` to `setRenderOptions` on a dot matrix instance throws.
+
+## Dot matrix renderer
+
+`createSarmalDotMatrix` renders the curve as a grid of rounded dots on a canvas. The head and trail are expressed as brightness on the grid rather than a ribbon path.
+
+```ts
+import { createSarmalDotMatrix, rose3 } from "@sarmal/core";
+
+const instance = createSarmalDotMatrix(canvas, rose3, {
+  cols: 32, // dot columns (default: 32)
+  rows: 32, // dot rows (default: 32)
+  roundness: 1, // 0 = square, 1 = full circle (default: 1)
+  trailColor: "#2dd4bf",
+  trailStyle: "gradient-animated",
+});
+```
+
+The canvas `width` and `height` HTML attributes (not CSS) determine the rendering area. The dot matrix renderer reads pixel dimensions directly; CSS sizing alone has no effect on the grid.
+
+`trailLength` defaults to `cols * 3`. `DotMatrixSarmalOptions` supports the same lifecycle options as the ribbon renderers (`autoStart`, `pauseOnHidden`, `initialPhase`) but not `headColor`, `headRadius`, or `trailWidth`.
+
+## Built-in palettes
+
+`palettes` is a named collection of multi-stop color arrays ready to pass as `trailColor`:
+
+```ts
+import { palettes } from "@sarmal/core";
+
+sarmal.setRenderOptions({
+  trailColor: palettes.bard, // ["#a855f7", "#3b82f6", "#14b8a6", "#ec4899"]
+  trailStyle: "gradient-animated",
+});
+```
+
+Available names: `bard`, `carnival`, `ocean`, `sunset`, `ice`, `rocketpop`, `neon`, `vaporwave`, `pastel`, `sakura`. Read `SarmalPalette` in `dist/index.d.ts` for the full union.
+
+## Drawing curves from control points
+
+`drawCurve` builds a `CurveDef` from Catmull-Rom spline control points — no math required:
+
+```ts
+import { createSarmal, drawCurve } from "@sarmal/core";
+
+const curve = drawCurve([
+  [0, -0.8],
+  [0.8, 0],
+  [0, 0.8],
+  [-0.8, 0],
+]);
+
+const sarmal = createSarmal(canvas, curve);
+```
+
+Control points are `[x, y]` tuples in `[-1, 1]` space. The spline is closed automatically.
+
+## Terminal renderer
+
+`@sarmal/core/terminal` renders curves in the terminal using braille characters and ANSI colors. Node.js only.
+
+```ts
+import { terminalSarmal } from "@sarmal/core/terminal";
+import { artemis2 } from "@sarmal/core";
+
+const stop = terminalSarmal(process.stdout, artemis2, {
+  size: 16, // braille cell width (default: 16)
+  fps: 30,
+  speed: 1,
+  color: "rgb", // "rgb" | "256" | "mono"
+});
+
+// stop() to clean up and restore cursor
+```
+
+Or run directly: `npx @sarmal/core` — accepts `--name`, `--fps`, `--speed`, `--size`, `--color`.
+
 ## Auto-init (no JS required)
 
+Import the side-effect module or drop in the CDN script:
+
 ```ts
 import "@sarmal/core/auto";
 ```
 
 ```html
+<script src="https://cdn.jsdelivr.net/npm/@sarmal/core/dist/auto-init.js"></script>
+```
+
+Then annotate elements with `data-sarmal`:
+
+```html
+<!-- canvas ribbon renderer -->
 <canvas data-sarmal="lissajous32" width="200" height="200"></canvas>
-<svg data-sarmal="rose5" width="200" height="200"></svg>
+
+<!-- SVG ribbon renderer -->
+<svg data-sarmal="rose5" style="width:200px; height:200px;"></svg>
+
+<!-- dot matrix renderer — requires data-renderer="dot-matrix" -->
+<canvas
+  data-sarmal="rose3"
+  data-renderer="dot-matrix"
+  data-cols="32"
+  data-rows="32"
+  width="200"
+  height="200"
+></canvas>
 ```
 
-Data attributes mirror the option names in kebab-case: `data-trail-color`, `data-trail-length`, `data-trail-style`, `data-skeleton-color`, `data-head-color`, `data-head-radius`.
+`data-renderer` accepts `"dot-matrix"` or `"canvas"` (explicit but redundant). Any other value is an error — the element is skipped and a `console.error` is emitted. Omitting the attribute defaults to the canvas ribbon renderer.
+
+### Supported data attributes
+
+Shared by all three renderers:
+
+| Attribute              | Mirrors option  | Notes                                                   |
+| ---------------------- | --------------- | ------------------------------------------------------- |
+| `data-sarmal`          | —               | **Required.** Curve name.                               |
+| `data-trail-color`     | `trailColor`    | Single color string or JSON array: `'["#f00","#00f"]'`  |
+| `data-skeleton-color`  | `skeletonColor` | Pass `"transparent"` to hide.                           |
+| `data-trail-style`     | `trailStyle`    | `"default"`, `"gradient-static"`, `"gradient-animated"` |
+| `data-trail-length`    | `trailLength`   | Integer.                                                |
+| `data-speed`           | —               | Applied via `setSpeed()` after creation.                |
+| `data-auto-start`      | `autoStart`     | Set to `"false"` to start paused. Omit to auto-play.    |
+| `data-pause-on-hidden` | `pauseOnHidden` | Set to `"false"` to keep running when tab is hidden.    |
+| `data-initial-phase`   | `initialPhase`  | Number. `"0"` is valid and seeks to phase 0.            |
+
+Canvas and SVG ribbon renderers only:
+
+| Attribute          | Mirrors option |
+| ------------------ | -------------- |
+| `data-head-color`  | `headColor`    |
+| `data-head-radius` | `headRadius`   |
+| `data-trail-width` | `trailWidth`   |
+
+Dot matrix renderer only:
+
+| Attribute        | Mirrors option |
+| ---------------- | -------------- |
+| `data-renderer`  | —              | `"dot-matrix"` selects this renderer. `"canvas"` is accepted but redundant. Any other value logs an error and skips the element. |
+| `data-cols`      | `cols`         |
+| `data-rows`      | `rows`         |
+| `data-roundness` | `roundness`    |
 
 ## CDN usage
 
@@ -143,9 +305,12 @@ Auto-init script (no JS needed):
 
 ## Common mistakes
 
-- **`trailColor` with named colors or `hsl()`** — accepted formats are `#rrggbb`, `#rgb`, `#rrggbbaa` (alpha stripped), `rgb()`, `rgba()` (alpha stripped); named colors (`'red'`) and `hsl()` throw
-- **SVG `headRadius` with pixel values** — SVG space is 0–100 viewBox units; a canvas value of `4` renders as a large dot in SVG
+- **Named colors or `hsl()` in `trailColor`** — not supported; accepted formats are `#rrggbb`, `#rgb`, `rgb()`, `rgba()`, and `oklch()`. Named colors (`'red'`) and `hsl()` throw.
+- **SVG `headRadius` with pixel values** — SVG space is 0–100 viewBox units; a canvas value of `4` renders as a large dot in SVG. Use `0.5`–`2` for SVG.
+- **Dot matrix `setRenderOptions` with canvas-only fields** — `headColor`, `headRadius`, and `trailWidth` throw on dot matrix instances; use `DotMatrixRuntimeRenderOptions` fields only.
+- **Dot matrix canvas sizing** — set `width` and `height` HTML attributes, not just CSS. The renderer reads `canvas.width` / `canvas.height` directly; CSS-only sizing produces a mismatched grid.
 - **Forgetting `destroy()`** — always clean up in React `useEffect` return, Vue `onUnmounted`, etc.
-- **Changing `trailLength` after construction** — not possible; `trailLength` is fixed at creation; create a new instance
-- **Gradient colors without a gradient `trailStyle`** — `string[]` for `trailColor` has no visual effect unless `trailStyle` is `'gradient-static'` or `'gradient-animated'`
-- **Reading trail length from `trail.length`** — when using the engine directly, use `engine.trailCount`; the buffer is pre-allocated and always full-length
+- **Changing `trailLength` after construction** — not possible; `trailLength` is fixed at creation; create a new instance.
+- **Gradient colors without a gradient `trailStyle`** — `string[]` for `trailColor` has no visual effect unless `trailStyle` is `'gradient-static'` or `'gradient-animated'`.
+- **Reading trail size from `trail.length`** — when using `createEngine` directly, use `engine.trailCount`; the buffer is pre-allocated and always full-length.
+- **`data-initial-phase="0"` ignored** — auto-init uses a `!== undefined` check for this attribute specifically, so `"0"` correctly seeks to phase 0. All other numeric attributes use truthy checks and would ignore `"0"`.