@sarmal/core 0.13.0 → 0.15.0

package/dist/{types-BW0bpL1Z.d.cts → types-BL9HhEmk.d.cts}

@@ -7,10 +7,8 @@ interface CurveDef {
   /**
    * The parametric function that defines the curve shape.
    * @param t Current position along the curve, in [0, period)
-   * @param time Elapsed wall-clock time in seconds — always increasing, never resets on period wrap
-   * @param params Named parameter overrides.
-   *   Always `{}` today — reserved for the upcoming parameterized-curves feature.
-   *   Do NOT remove this parameter; it is intentional forward-compatible plumbing.
+   * @param time Elapsed actual time in seconds. It is always increasing, and never resets on period wrap
+   * @param params Named parameter overrides. intentional forward-compatible parameter
    */
   fn: (t: number, time: number, params: Record<string, number>) => Point;
   /**
@@ -218,12 +216,39 @@ interface SarmalInstance extends AnimationControls {
    * @returns Promise that resolves when the morph is complete
    */
   morphTo(target: CurveDef, options?: MorphOptions): Promise<void>;
+  /**
+   * Changes render options on a live SarmalInstance without destroying and recreating it.
+   *
+   * ! Validation fails the operation completely if any of the fields fail the chceck.
+   */
+  setRenderOptions(partial: RuntimeRenderOptions): void;
 }
 /**
  * With 'gradient-animated' the colors cycle along the trail over time
  */
 type TrailStyle = "default" | "gradient-static" | "gradient-animated";
-type PalettePreset = "bard" | "sunset" | "ocean" | "ice" | "fire" | "forest";
+/**
+ * The value must be a single hex string or an array of hex strings.
+ *
+ * ! Named colors, shorthand hex, `rgb()`,  and `hsl()` notations are not yet supported.
+ */
+type TrailColor = string | string[];
+/**
+ * Runtime-renderable options that can be changed on a live instance without destroying and recreating it.
+ *
+ * Passing `null` for `headColor`makes the head color derive its color from the current `trailColor` and `trailStyle`
+ * Passing a hex string locks the head color until overridden.
+ *
+ * Passing `"transparent"` for `skeletonColor` hides the skeleton. Any other value must be a valid {@link TrailColor}.
+ */
+interface RuntimeRenderOptions {
+  trailColor?: TrailColor;
+  /** 6-digit hex string to override, or `null` to make it automatic */
+  headColor?: string | null;
+  /** 6-digit hex string, or `"transparent"` to hide the skeleton. */
+  skeletonColor?: string;
+  trailStyle?: TrailStyle;
+}
 /**
  * Common renderer options shared between canvas and SVG renderers.
  * Extracted to avoid duplication and ensure consistency.
@@ -244,31 +269,27 @@ interface BaseRendererOptions {
    */
   skeletonColor?: string;
   /**
+   * Single hex color for default trails, or an array of hex colors for gradient trails.
    * @default '#ffffff'
    */
-  trailColor?: string;
+  trailColor?: TrailColor;
   /**
-   * @default '#ffffff'
+   * Hex color for the head dot.
+   * If omitted, the color is derived from the trail
    */
   headColor?: string;
   /** @default 4 */
   headRadius?: number;
-}
-interface RendererOptions extends BaseRendererOptions {
-  /** Target canvas element that will contain the Sarmal */
-  canvas: HTMLCanvasElement;
-  engine: Engine;
   /**
    * Trail rendering style
    * @default 'default'
    */
   trailStyle?: TrailStyle;
-  /**
-   * Color palette for gradient trails
-   * Can be a preset name or custom array of hex colors.
-   * @default 'bard' for animated, 'ice' for static
-   */
-  palette?: PalettePreset | string[];
+}
+interface RendererOptions extends BaseRendererOptions {
+  /** Target canvas element that will contain the Sarmal */
+  canvas: HTMLCanvasElement;
+  engine: Engine;
 }
 interface SarmalOptions extends Omit<RendererOptions, "canvas" | "engine"> {
   /** @default 120 */
@@ -280,11 +301,12 @@ export type {
   CurveDef as C,
   Engine as E,
   JumpOptions as J,
-  PalettePreset as P,
+  Point as P,
   RendererOptions as R,
   SarmalInstance as S,
-  TrailStyle as T,
+  TrailColor as T,
   SarmalOptions as a,
-  Point as b,
+  RuntimeRenderOptions as b,
   SeekOptions as c,
+  TrailStyle as d,
 };

package/dist/{types-BW0bpL1Z.d.ts → types-BL9HhEmk.d.ts}

@@ -7,10 +7,8 @@ interface CurveDef {
   /**
    * The parametric function that defines the curve shape.
    * @param t Current position along the curve, in [0, period)
-   * @param time Elapsed wall-clock time in seconds — always increasing, never resets on period wrap
-   * @param params Named parameter overrides.
-   *   Always `{}` today — reserved for the upcoming parameterized-curves feature.
-   *   Do NOT remove this parameter; it is intentional forward-compatible plumbing.
+   * @param time Elapsed actual time in seconds. It is always increasing, and never resets on period wrap
+   * @param params Named parameter overrides. intentional forward-compatible parameter
    */
   fn: (t: number, time: number, params: Record<string, number>) => Point;
   /**
@@ -218,12 +216,39 @@ interface SarmalInstance extends AnimationControls {
    * @returns Promise that resolves when the morph is complete
    */
   morphTo(target: CurveDef, options?: MorphOptions): Promise<void>;
+  /**
+   * Changes render options on a live SarmalInstance without destroying and recreating it.
+   *
+   * ! Validation fails the operation completely if any of the fields fail the chceck.
+   */
+  setRenderOptions(partial: RuntimeRenderOptions): void;
 }
 /**
  * With 'gradient-animated' the colors cycle along the trail over time
  */
 type TrailStyle = "default" | "gradient-static" | "gradient-animated";
-type PalettePreset = "bard" | "sunset" | "ocean" | "ice" | "fire" | "forest";
+/**
+ * The value must be a single hex string or an array of hex strings.
+ *
+ * ! Named colors, shorthand hex, `rgb()`,  and `hsl()` notations are not yet supported.
+ */
+type TrailColor = string | string[];
+/**
+ * Runtime-renderable options that can be changed on a live instance without destroying and recreating it.
+ *
+ * Passing `null` for `headColor`makes the head color derive its color from the current `trailColor` and `trailStyle`
+ * Passing a hex string locks the head color until overridden.
+ *
+ * Passing `"transparent"` for `skeletonColor` hides the skeleton. Any other value must be a valid {@link TrailColor}.
+ */
+interface RuntimeRenderOptions {
+  trailColor?: TrailColor;
+  /** 6-digit hex string to override, or `null` to make it automatic */
+  headColor?: string | null;
+  /** 6-digit hex string, or `"transparent"` to hide the skeleton. */
+  skeletonColor?: string;
+  trailStyle?: TrailStyle;
+}
 /**
  * Common renderer options shared between canvas and SVG renderers.
  * Extracted to avoid duplication and ensure consistency.
@@ -244,31 +269,27 @@ interface BaseRendererOptions {
    */
   skeletonColor?: string;
   /**
+   * Single hex color for default trails, or an array of hex colors for gradient trails.
    * @default '#ffffff'
    */
-  trailColor?: string;
+  trailColor?: TrailColor;
   /**
-   * @default '#ffffff'
+   * Hex color for the head dot.
+   * If omitted, the color is derived from the trail
    */
   headColor?: string;
   /** @default 4 */
   headRadius?: number;
-}
-interface RendererOptions extends BaseRendererOptions {
-  /** Target canvas element that will contain the Sarmal */
-  canvas: HTMLCanvasElement;
-  engine: Engine;
   /**
    * Trail rendering style
    * @default 'default'
    */
   trailStyle?: TrailStyle;
-  /**
-   * Color palette for gradient trails
-   * Can be a preset name or custom array of hex colors.
-   * @default 'bard' for animated, 'ice' for static
-   */
-  palette?: PalettePreset | string[];
+}
+interface RendererOptions extends BaseRendererOptions {
+  /** Target canvas element that will contain the Sarmal */
+  canvas: HTMLCanvasElement;
+  engine: Engine;
 }
 interface SarmalOptions extends Omit<RendererOptions, "canvas" | "engine"> {
   /** @default 120 */
@@ -280,11 +301,12 @@ export type {
   CurveDef as C,
   Engine as E,
   JumpOptions as J,
-  PalettePreset as P,
+  Point as P,
   RendererOptions as R,
   SarmalInstance as S,
-  TrailStyle as T,
+  TrailColor as T,
   SarmalOptions as a,
-  Point as b,
+  RuntimeRenderOptions as b,
   SeekOptions as c,
+  TrailStyle as d,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarmal/core",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Curve path based loading indicators and their renderer",
   "keywords": [
     "animation",