@sarmal/core 0.37.1 → 0.37.4

package/dist/{renderer-shared-Bcc_1IaT.d.cts → renderer-shared-9Xf6sIlx.d.cts}

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

package/dist/{renderer-shared-DWPVHjKZ.d.ts → renderer-shared-DElz98PT.d.ts}

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

package/dist/terminal.d.cts

@@ -1,5 +1,5 @@
-import { C as CurveDef } from './types-B1XeFpuq.cjs';
-import { R as Rgb } from './renderer-shared-Bcc_1IaT.cjs';
+import { C as CurveDef } from './types-D_ERoVvi.cjs';
+import { R as Rgb } from './renderer-shared-9Xf6sIlx.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-B1XeFpuq.js';
-import { R as Rgb } from './renderer-shared-DWPVHjKZ.js';
+import { C as CurveDef } from './types-D_ERoVvi.js';
+import { R as Rgb } from './renderer-shared-DElz98PT.js';
 
 type ColorCapability = "truecolor" | "256-color" | "monochrome";
 type DotCol = 0 | 1;

package/dist/{types-B1XeFpuq.d.cts → types-D_ERoVvi.d.cts}

@@ -347,5 +347,125 @@ interface SarmalOptions extends Omit<RendererOptions, "canvas" | "engine"> {
     /** @default 120 */
     trailLength?: number;
 }
+/**
+ * Shared init options for canvas and SVG renderer bindings.
+ * Changing any of these after mount destroys and recreates the instance.
+ */
+interface BaseInit {
+    trailLength?: number;
+    headRadius?: number;
+    autoStart?: boolean;
+    initialPhase?: number;
+    /** @default true */
+    pauseOnHidden?: boolean;
+}
+/**
+ * Canvas-specific init options. Extends {@link BaseInit} with buffer sizing.
+ * Changing any of these after mount destroys and recreates the instance.
+ */
+interface CanvasInit extends BaseInit {
+    width?: number;
+    height?: number;
+}
+/**
+ * Dot matrix renderer init options.
+ * Changing any of these after mount destroys and recreates the instance.
+ */
+interface DotMatrixInit {
+    /**
+     * Number of dot columns in the grid.
+     * @default 32
+     */
+    cols?: number;
+    /**
+     * Number of dot rows in the grid.
+     * @default 32
+     */
+    rows?: number;
+    /**
+     * Corner rounding of each dot: `0` = sharp square, `1` = full circle.
+     * @default 1
+     */
+    roundness?: number;
+    /**
+     * Number of trail points to keep.
+     * Larger values produce longer trails.
+     * If omitted, a value is chosen based on the grid density.
+     */
+    trailLength?: number;
+    autoStart?: boolean;
+    initialPhase?: number;
+    /** @default true */
+    pauseOnHidden?: boolean;
+    /** Canvas buffer width in pixels. Falls back to parent `clientWidth`, then 300. */
+    width?: number;
+    /** Canvas buffer height in pixels. Falls back to parent `clientHeight`, then 300. */
+    height?: number;
+}
+/**
+ * Options for `createSarmalDotMatrix`
+ *
+ * Init fields (`cols`, `rows`, `roundness`, `trailLength`, `autoStart`, `initialPhase`, `pauseOnHidden`)
+ *  require recreating the instance on change.
+ * Runtime fields (`trailColor`, `trailStyle`, `skeletonColor`)
+ *  can be updated live through {@link SarmalInstance.setRenderOptions}.
+ */
+interface DotMatrixSarmalOptions extends Omit<DotMatrixInit, "width" | "height"> {
+    /**
+     * Color of lit dots. Single color string for solid mode; array of two or more colors for gradient mode.
+     * Gradient mode samples a color per dot based on its position in the trail (tail to head).
+     * Background dots always use the first color at 5% opacity.
+     * @default '#ffffff'
+     */
+    trailColor?: TrailColor;
+    /**
+     * Trail rendering style.
+     * - `'default'`: solid color, alpha varies by intensity.
+     * - `'gradient-static'`: each dot's color is sampled from the `trailColor` gradient. Requires `trailColor` array.
+     * - `'gradient-animated'`: same as `gradient-static` but the gradient phase shifts over time.
+     * @default 'default'
+     */
+    trailStyle?: TrailStyle;
+    /**
+     * Color of the skeleton dots. Accepts `#rrggbb`, `#rgb`, `rgb()`, `rgba()`, or `oklch()`.
+     * Pass `"transparent"` to disable the skeleton entirely.
+     * @default '#ffffff'
+     */
+    skeletonColor?: string;
+}
+/**
+ * Framework-agnostic configuration shared by all canvas/SVG renderer bindings.
+ *
+ * Framework packages (React, Svelte, etc.) extend this with their specific
+ * surface: `class`/`className`, style type, event naming, bindable instance.
+ */
+interface BaseSarmalOptions {
+    curve: CurveDef;
+    trailColor?: TrailColor;
+    skeletonColor?: string;
+    headColor?: string;
+    trailStyle?: TrailStyle;
+    morphDuration?: number;
+    /** @default 'normalized' */
+    morphStrategy?: MorphStrategy;
+    trailLength?: number;
+    headRadius?: number;
+    trailWidth?: number;
+    autoStart?: boolean;
+    initialPhase?: number;
+    /** @default true */
+    pauseOnHidden?: boolean;
+}
+/**
+ * Framework-agnostic configuration shared by all dot matrix renderer bindings.
+ *
+ * Framework packages extend this with their specific surface: `class`/`className`, etc.
+ */
+interface BaseDotMatrixOptions extends DotMatrixSarmalOptions {
+    curve: CurveDef;
+    morphDuration?: number;
+    /** @default 'normalized' */
+    morphStrategy?: MorphStrategy;
+}
 
-export type { BaseRendererOptions as B, CurveDef as C, DotMatrixRuntimeRenderOptions as D, Engine as E, JumpOptions as J, MorphStrategy as M, Point as P, RendererOptions as R, SarmalInstance as S, TrailColor as T, TrailStyle as a, ControlPoint as b, SarmalOptions as c, BaseRuntimeRenderOptions as d, RuntimeRenderOptions as e, SeekOptions as f };
+export type { BaseRendererOptions as B, CurveDef as C, DotMatrixSarmalOptions as D, Engine as E, JumpOptions as J, MorphStrategy as M, Point as P, RendererOptions as R, SarmalInstance as S, TrailColor as T, DotMatrixRuntimeRenderOptions as a, ControlPoint as b, SarmalOptions as c, BaseDotMatrixOptions as d, BaseInit as e, BaseRuntimeRenderOptions as f, BaseSarmalOptions as g, CanvasInit as h, DotMatrixInit as i, RuntimeRenderOptions as j, SeekOptions as k, TrailStyle as l };

package/dist/{types-B1XeFpuq.d.ts → types-D_ERoVvi.d.ts}

@@ -347,5 +347,125 @@ interface SarmalOptions extends Omit<RendererOptions, "canvas" | "engine"> {
     /** @default 120 */
     trailLength?: number;
 }
+/**
+ * Shared init options for canvas and SVG renderer bindings.
+ * Changing any of these after mount destroys and recreates the instance.
+ */
+interface BaseInit {
+    trailLength?: number;
+    headRadius?: number;
+    autoStart?: boolean;
+    initialPhase?: number;
+    /** @default true */
+    pauseOnHidden?: boolean;
+}
+/**
+ * Canvas-specific init options. Extends {@link BaseInit} with buffer sizing.
+ * Changing any of these after mount destroys and recreates the instance.
+ */
+interface CanvasInit extends BaseInit {
+    width?: number;
+    height?: number;
+}
+/**
+ * Dot matrix renderer init options.
+ * Changing any of these after mount destroys and recreates the instance.
+ */
+interface DotMatrixInit {
+    /**
+     * Number of dot columns in the grid.
+     * @default 32
+     */
+    cols?: number;
+    /**
+     * Number of dot rows in the grid.
+     * @default 32
+     */
+    rows?: number;
+    /**
+     * Corner rounding of each dot: `0` = sharp square, `1` = full circle.
+     * @default 1
+     */
+    roundness?: number;
+    /**
+     * Number of trail points to keep.
+     * Larger values produce longer trails.
+     * If omitted, a value is chosen based on the grid density.
+     */
+    trailLength?: number;
+    autoStart?: boolean;
+    initialPhase?: number;
+    /** @default true */
+    pauseOnHidden?: boolean;
+    /** Canvas buffer width in pixels. Falls back to parent `clientWidth`, then 300. */
+    width?: number;
+    /** Canvas buffer height in pixels. Falls back to parent `clientHeight`, then 300. */
+    height?: number;
+}
+/**
+ * Options for `createSarmalDotMatrix`
+ *
+ * Init fields (`cols`, `rows`, `roundness`, `trailLength`, `autoStart`, `initialPhase`, `pauseOnHidden`)
+ *  require recreating the instance on change.
+ * Runtime fields (`trailColor`, `trailStyle`, `skeletonColor`)
+ *  can be updated live through {@link SarmalInstance.setRenderOptions}.
+ */
+interface DotMatrixSarmalOptions extends Omit<DotMatrixInit, "width" | "height"> {
+    /**
+     * Color of lit dots. Single color string for solid mode; array of two or more colors for gradient mode.
+     * Gradient mode samples a color per dot based on its position in the trail (tail to head).
+     * Background dots always use the first color at 5% opacity.
+     * @default '#ffffff'
+     */
+    trailColor?: TrailColor;
+    /**
+     * Trail rendering style.
+     * - `'default'`: solid color, alpha varies by intensity.
+     * - `'gradient-static'`: each dot's color is sampled from the `trailColor` gradient. Requires `trailColor` array.
+     * - `'gradient-animated'`: same as `gradient-static` but the gradient phase shifts over time.
+     * @default 'default'
+     */
+    trailStyle?: TrailStyle;
+    /**
+     * Color of the skeleton dots. Accepts `#rrggbb`, `#rgb`, `rgb()`, `rgba()`, or `oklch()`.
+     * Pass `"transparent"` to disable the skeleton entirely.
+     * @default '#ffffff'
+     */
+    skeletonColor?: string;
+}
+/**
+ * Framework-agnostic configuration shared by all canvas/SVG renderer bindings.
+ *
+ * Framework packages (React, Svelte, etc.) extend this with their specific
+ * surface: `class`/`className`, style type, event naming, bindable instance.
+ */
+interface BaseSarmalOptions {
+    curve: CurveDef;
+    trailColor?: TrailColor;
+    skeletonColor?: string;
+    headColor?: string;
+    trailStyle?: TrailStyle;
+    morphDuration?: number;
+    /** @default 'normalized' */
+    morphStrategy?: MorphStrategy;
+    trailLength?: number;
+    headRadius?: number;
+    trailWidth?: number;
+    autoStart?: boolean;
+    initialPhase?: number;
+    /** @default true */
+    pauseOnHidden?: boolean;
+}
+/**
+ * Framework-agnostic configuration shared by all dot matrix renderer bindings.
+ *
+ * Framework packages extend this with their specific surface: `class`/`className`, etc.
+ */
+interface BaseDotMatrixOptions extends DotMatrixSarmalOptions {
+    curve: CurveDef;
+    morphDuration?: number;
+    /** @default 'normalized' */
+    morphStrategy?: MorphStrategy;
+}
 
-export type { BaseRendererOptions as B, CurveDef as C, DotMatrixRuntimeRenderOptions as D, Engine as E, JumpOptions as J, MorphStrategy as M, Point as P, RendererOptions as R, SarmalInstance as S, TrailColor as T, TrailStyle as a, ControlPoint as b, SarmalOptions as c, BaseRuntimeRenderOptions as d, RuntimeRenderOptions as e, SeekOptions as f };
+export type { BaseRendererOptions as B, CurveDef as C, DotMatrixSarmalOptions as D, Engine as E, JumpOptions as J, MorphStrategy as M, Point as P, RendererOptions as R, SarmalInstance as S, TrailColor as T, DotMatrixRuntimeRenderOptions as a, ControlPoint as b, SarmalOptions as c, BaseDotMatrixOptions as d, BaseInit as e, BaseRuntimeRenderOptions as f, BaseSarmalOptions as g, CanvasInit as h, DotMatrixInit as i, RuntimeRenderOptions as j, SeekOptions as k, TrailStyle as l };

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@sarmal/core",
-  "version": "0.37.1",
-  "description": "Curve path based loading indicators and their renderer",
+  "version": "0.37.4",
+  "description": "Animated curve library for loading states and ambient motion",
   "keywords": [
     "animation",
     "canvas",
     "curve",
     "loading",
-    "parametric",
-    "spinner",
+    "loading-indicator",
     "svg",
-    "tanstack-intent"
+    "tanstack-intent",
+    "trail"
   ],
   "homepage": "https://sarmal.art",
   "bugs": {

package/skills/core/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: core
-description: Parametric curve loading indicators for the web. Use when adding animated
-  spinners or loading indicators with @sarmal/core — covers createSarmal (canvas),
+description: Animated curve library for the web. Use when adding animated curves,
+  loading indicators, or ambient motion with @sarmal/core — covers createSarmal (canvas),
   createSarmalSVG, createSarmalDotMatrix, terminal renderer, built-in curves,
   lifecycle, animation controls, and auto-init.
 license: MIT
@@ -9,7 +9,7 @@ license: MIT
 
 # @sarmal/core
 
-sarmal renders parametric math curves as animated loading/thinking indicators. It is not a CSS spinner — it is a canvas or SVG renderer that animates a moving "head" dot leaving a fading trail along a curve path.
+sarmal renders animated curves as loading indicators, thinking states, or ambient motion. It is a canvas or SVG renderer that animates a moving "head" dot leaving a fading trail along a curve path.
 
 ## Type definitions (read these first)