@sarmal/core 0.23.0 → 0.25.0

package/dist/index.d.cts

@@ -1,45 +1,31 @@
-import {
-  B as BaseRendererOptions,
-  E as Engine,
-  S as SarmalInstance,
-  C as CurveDef,
-  R as RendererOptions,
-  P as Point,
-  a as SarmalOptions,
-} from "./types-C0b4MPtI.cjs";
-export {
-  J as JumpOptions,
-  b as RuntimeRenderOptions,
-  c as SeekOptions,
-  T as TrailColor,
-  d as TrailStyle,
-} from "./types-C0b4MPtI.cjs";
-export { CurveName, curves } from "./curves/index.cjs";
-export { artemis2 } from "./curves/artemis2.cjs";
-export { astroid } from "./curves/astroid.cjs";
-export { deltoid } from "./curves/deltoid.cjs";
-export { epicycloid3 } from "./curves/epicycloid3.cjs";
-export { epitrochoid7 } from "./curves/epitrochoid7.cjs";
-export { lame } from "./curves/lame.cjs";
-export { lissajous32 } from "./curves/lissajous32.cjs";
-export { lissajous43 } from "./curves/lissajous43.cjs";
-export { rose3 } from "./curves/rose3.cjs";
-export { rose5 } from "./curves/rose5.cjs";
-import "./curves/rose52.cjs";
-import "./curves/star.cjs";
-import "./curves/star4.cjs";
-import "./curves/star7.cjs";
+import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, P as Point, R as RendererOptions, a as ControlPoint, b as SarmalOptions } from './types-BZpzgNau.cjs';
+export { J as JumpOptions, c as RuntimeRenderOptions, d as SeekOptions, T as TrailColor, e as TrailStyle } from './types-BZpzgNau.cjs';
+export { CurveName, curves } from './curves/index.cjs';
+export { artemis2 } from './curves/artemis2.cjs';
+export { astroid } from './curves/astroid.cjs';
+export { deltoid } from './curves/deltoid.cjs';
+export { epicycloid3 } from './curves/epicycloid3.cjs';
+export { epitrochoid7 } from './curves/epitrochoid7.cjs';
+export { lame } from './curves/lame.cjs';
+export { lissajous32 } from './curves/lissajous32.cjs';
+export { lissajous43 } from './curves/lissajous43.cjs';
+export { rose3 } from './curves/rose3.cjs';
+export { rose5 } from './curves/rose5.cjs';
+import './curves/rose52.cjs';
+import './curves/star.cjs';
+import './curves/star4.cjs';
+import './curves/star7.cjs';
 
 interface SVGRendererOptions extends BaseRendererOptions {
-  /** SVG element the renderer draws into directly */
-  container: SVGSVGElement;
-  engine: Engine;
-  /** @default 'Loading' */
-  ariaLabel?: string;
+    /** SVG element the renderer draws into directly */
+    container: SVGSVGElement;
+    engine: Engine;
+    /** @default 'Loading' */
+    ariaLabel?: string;
 }
 interface SVGSarmalOptions extends Omit<SVGRendererOptions, "container" | "engine"> {
-  /** @default 120 */
-  trailLength?: number;
+    /** @default 120 */
+    trailLength?: number;
 }
 /**
  * Creates a live SVG renderer for sarmal animations
@@ -64,23 +50,34 @@ declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
  * controlled.pause() // Pause later
  * ```
  */
-declare function createSarmalSVG(
-  container: SVGSVGElement,
-  curveDef: CurveDef,
-  options?: SVGSarmalOptions,
-): SarmalInstance;
+declare function createSarmalSVG(container: SVGSVGElement, curveDef: CurveDef, options?: SVGSarmalOptions): SarmalInstance;
 
+interface BoundaryResult {
+    scale: number;
+    offsetX: number;
+    offsetY: number;
+}
+/**
+ * Computes how to map engine coordinates into a viewport of the given logical size.
+ * ! Returns `null` if `pts` is empty
+ * ! Throws if all points are identical
+ *
+ * Padding per side is `max(FIT_PADDING * dim, minPaddingPx)`, so the stricter constraint wins.
+ * `minPaddingPx` defaults to `FIT_PADDING_MIN` (4px) for pixel-space callers.
+ * Pass `0` when the logical space is itself a normalized viewBox (e.g. SVG export).
+ */
+declare function computeBoundaries(pts: Point[], logicalWidth: number, logicalHeight: number, minPaddingPx?: number): BoundaryResult | null;
 /**
  * Can be passed directly to `trailColor`,
  *  or can be mixed/sliced before passing as a prop.
  */
 declare const palettes: {
-  readonly bard: ["#a855f7", "#3b82f6", "#14b8a6", "#ec4899"];
-  readonly sunset: ["#f97316", "#dc2626", "#9333ea", "#f472b6"];
-  readonly ocean: ["#1e3a8a", "#06b6d4", "#22d3ee", "#e0f2fe"];
-  readonly ice: ["#1e3a8a", "#67e8f9"];
-  readonly fire: ["#7f1d1d", "#fbbf24"];
-  readonly forest: ["#14532d", "#86efac"];
+    readonly bard: ["#a855f7", "#3b82f6", "#14b8a6", "#ec4899"];
+    readonly sunset: ["#f97316", "#dc2626", "#9333ea", "#f472b6"];
+    readonly ocean: ["#1e3a8a", "#06b6d4", "#22d3ee", "#e0f2fe"];
+    readonly ice: ["#1e3a8a", "#67e8f9"];
+    readonly fire: ["#7f1d1d", "#fbbf24"];
+    readonly forest: ["#14532d", "#86efac"];
 };
 type SarmalPalette = keyof typeof palettes;
 
@@ -104,7 +101,7 @@ declare function createRenderer(options: RendererOptions): SarmalInstance;
  * @param t       Parametric position along the closed loop.  Wraps into `[0, 2π)` automatically, so values outside that range are remapped rather than rejected
  * @returns       The `(x, y)` position on the spline at time `t`
  */
-declare function evaluateCatmullRom(points: Array<[number, number]>, t: number): Point;
+declare function evaluateCatmullRom(points: Array<ControlPoint>, t: number): Point;
 /**
  * The returned curve definition produces a closed Catmull-Rom spline that
  *  passes through every point in order, looping back from the last point to the first.
@@ -112,8 +109,9 @@ declare function evaluateCatmullRom(points: Array<[number, number]>, t: number):
  * @param points  Array of control points in **normalized `[−1, 1]` space**,
  *                  matching the playground's draw-mode coordinate system.
  *                ! Must contain at least 3 points.
- * @returns       A `CurveDef` with `period: 2π` and the spline evaluator as its `fn`.
- *                `name` is set to `"custom"`.
+ * @param opts    Optional overrides for the returned `CurveDef`.
+ * @param opts.name  Display name for the curve. Defaults to `"drawn"`.
+ * @returns       A `CurveDef` with `period: 2π`, `kind: "drawn"`, and the spline evaluator as its `fn`.
  * @throws        If `points` has fewer than 3 entries.
  *
  * @example
@@ -129,7 +127,9 @@ declare function evaluateCatmullRom(points: Array<[number, number]>, t: number):
  * createSarmal(canvas, curve)
  * ```
  */
-declare function drawCurve(points: Array<[number, number]>): CurveDef;
+declare function drawCurve(points: Array<ControlPoint>, opts?: {
+    name?: string;
+}): CurveDef;
 
 /**
  * Creates a sarmal animation on a canvas element
@@ -145,29 +145,6 @@ declare function drawCurve(points: Array<[number, number]>): CurveDef;
  * controlled.pause() // Pause later
  * ```
  */
-declare function createSarmal(
-  canvas: HTMLCanvasElement,
-  curveDef: CurveDef,
-  options?: SarmalOptions,
-): SarmalInstance;
+declare function createSarmal(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: SarmalOptions): SarmalInstance;
 
-export {
-  BaseRendererOptions,
-  CurveDef,
-  Engine,
-  Point,
-  RendererOptions,
-  type SVGRendererOptions,
-  type SVGSarmalOptions,
-  SarmalInstance,
-  SarmalOptions,
-  type SarmalPalette,
-  createEngine,
-  createRenderer,
-  createSVGRenderer,
-  createSarmal,
-  createSarmalSVG,
-  drawCurve,
-  evaluateCatmullRom,
-  palettes,
-};
+export { BaseRendererOptions, type BoundaryResult, CurveDef, Engine, Point, RendererOptions, type SVGRendererOptions, type SVGSarmalOptions, SarmalInstance, SarmalOptions, type SarmalPalette, computeBoundaries, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalSVG, drawCurve, evaluateCatmullRom, palettes };

package/dist/index.d.ts

@@ -1,45 +1,31 @@
-import {
-  B as BaseRendererOptions,
-  E as Engine,
-  S as SarmalInstance,
-  C as CurveDef,
-  R as RendererOptions,
-  P as Point,
-  a as SarmalOptions,
-} from "./types-C0b4MPtI.js";
-export {
-  J as JumpOptions,
-  b as RuntimeRenderOptions,
-  c as SeekOptions,
-  T as TrailColor,
-  d as TrailStyle,
-} from "./types-C0b4MPtI.js";
-export { CurveName, curves } from "./curves/index.js";
-export { artemis2 } from "./curves/artemis2.js";
-export { astroid } from "./curves/astroid.js";
-export { deltoid } from "./curves/deltoid.js";
-export { epicycloid3 } from "./curves/epicycloid3.js";
-export { epitrochoid7 } from "./curves/epitrochoid7.js";
-export { lame } from "./curves/lame.js";
-export { lissajous32 } from "./curves/lissajous32.js";
-export { lissajous43 } from "./curves/lissajous43.js";
-export { rose3 } from "./curves/rose3.js";
-export { rose5 } from "./curves/rose5.js";
-import "./curves/rose52.js";
-import "./curves/star.js";
-import "./curves/star4.js";
-import "./curves/star7.js";
+import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, P as Point, R as RendererOptions, a as ControlPoint, b as SarmalOptions } from './types-BZpzgNau.js';
+export { J as JumpOptions, c as RuntimeRenderOptions, d as SeekOptions, T as TrailColor, e as TrailStyle } from './types-BZpzgNau.js';
+export { CurveName, curves } from './curves/index.js';
+export { artemis2 } from './curves/artemis2.js';
+export { astroid } from './curves/astroid.js';
+export { deltoid } from './curves/deltoid.js';
+export { epicycloid3 } from './curves/epicycloid3.js';
+export { epitrochoid7 } from './curves/epitrochoid7.js';
+export { lame } from './curves/lame.js';
+export { lissajous32 } from './curves/lissajous32.js';
+export { lissajous43 } from './curves/lissajous43.js';
+export { rose3 } from './curves/rose3.js';
+export { rose5 } from './curves/rose5.js';
+import './curves/rose52.js';
+import './curves/star.js';
+import './curves/star4.js';
+import './curves/star7.js';
 
 interface SVGRendererOptions extends BaseRendererOptions {
-  /** SVG element the renderer draws into directly */
-  container: SVGSVGElement;
-  engine: Engine;
-  /** @default 'Loading' */
-  ariaLabel?: string;
+    /** SVG element the renderer draws into directly */
+    container: SVGSVGElement;
+    engine: Engine;
+    /** @default 'Loading' */
+    ariaLabel?: string;
 }
 interface SVGSarmalOptions extends Omit<SVGRendererOptions, "container" | "engine"> {
-  /** @default 120 */
-  trailLength?: number;
+    /** @default 120 */
+    trailLength?: number;
 }
 /**
  * Creates a live SVG renderer for sarmal animations
@@ -64,23 +50,34 @@ declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
  * controlled.pause() // Pause later
  * ```
  */
-declare function createSarmalSVG(
-  container: SVGSVGElement,
-  curveDef: CurveDef,
-  options?: SVGSarmalOptions,
-): SarmalInstance;
+declare function createSarmalSVG(container: SVGSVGElement, curveDef: CurveDef, options?: SVGSarmalOptions): SarmalInstance;
 
+interface BoundaryResult {
+    scale: number;
+    offsetX: number;
+    offsetY: number;
+}
+/**
+ * Computes how to map engine coordinates into a viewport of the given logical size.
+ * ! Returns `null` if `pts` is empty
+ * ! Throws if all points are identical
+ *
+ * Padding per side is `max(FIT_PADDING * dim, minPaddingPx)`, so the stricter constraint wins.
+ * `minPaddingPx` defaults to `FIT_PADDING_MIN` (4px) for pixel-space callers.
+ * Pass `0` when the logical space is itself a normalized viewBox (e.g. SVG export).
+ */
+declare function computeBoundaries(pts: Point[], logicalWidth: number, logicalHeight: number, minPaddingPx?: number): BoundaryResult | null;
 /**
  * Can be passed directly to `trailColor`,
  *  or can be mixed/sliced before passing as a prop.
  */
 declare const palettes: {
-  readonly bard: ["#a855f7", "#3b82f6", "#14b8a6", "#ec4899"];
-  readonly sunset: ["#f97316", "#dc2626", "#9333ea", "#f472b6"];
-  readonly ocean: ["#1e3a8a", "#06b6d4", "#22d3ee", "#e0f2fe"];
-  readonly ice: ["#1e3a8a", "#67e8f9"];
-  readonly fire: ["#7f1d1d", "#fbbf24"];
-  readonly forest: ["#14532d", "#86efac"];
+    readonly bard: ["#a855f7", "#3b82f6", "#14b8a6", "#ec4899"];
+    readonly sunset: ["#f97316", "#dc2626", "#9333ea", "#f472b6"];
+    readonly ocean: ["#1e3a8a", "#06b6d4", "#22d3ee", "#e0f2fe"];
+    readonly ice: ["#1e3a8a", "#67e8f9"];
+    readonly fire: ["#7f1d1d", "#fbbf24"];
+    readonly forest: ["#14532d", "#86efac"];
 };
 type SarmalPalette = keyof typeof palettes;
 
@@ -104,7 +101,7 @@ declare function createRenderer(options: RendererOptions): SarmalInstance;
  * @param t       Parametric position along the closed loop.  Wraps into `[0, 2π)` automatically, so values outside that range are remapped rather than rejected
  * @returns       The `(x, y)` position on the spline at time `t`
  */
-declare function evaluateCatmullRom(points: Array<[number, number]>, t: number): Point;
+declare function evaluateCatmullRom(points: Array<ControlPoint>, t: number): Point;
 /**
  * The returned curve definition produces a closed Catmull-Rom spline that
  *  passes through every point in order, looping back from the last point to the first.
@@ -112,8 +109,9 @@ declare function evaluateCatmullRom(points: Array<[number, number]>, t: number):
  * @param points  Array of control points in **normalized `[−1, 1]` space**,
  *                  matching the playground's draw-mode coordinate system.
  *                ! Must contain at least 3 points.
- * @returns       A `CurveDef` with `period: 2π` and the spline evaluator as its `fn`.
- *                `name` is set to `"custom"`.
+ * @param opts    Optional overrides for the returned `CurveDef`.
+ * @param opts.name  Display name for the curve. Defaults to `"drawn"`.
+ * @returns       A `CurveDef` with `period: 2π`, `kind: "drawn"`, and the spline evaluator as its `fn`.
  * @throws        If `points` has fewer than 3 entries.
  *
  * @example
@@ -129,7 +127,9 @@ declare function evaluateCatmullRom(points: Array<[number, number]>, t: number):
  * createSarmal(canvas, curve)
  * ```
  */
-declare function drawCurve(points: Array<[number, number]>): CurveDef;
+declare function drawCurve(points: Array<ControlPoint>, opts?: {
+    name?: string;
+}): CurveDef;
 
 /**
  * Creates a sarmal animation on a canvas element
@@ -145,29 +145,6 @@ declare function drawCurve(points: Array<[number, number]>): CurveDef;
  * controlled.pause() // Pause later
  * ```
  */
-declare function createSarmal(
-  canvas: HTMLCanvasElement,
-  curveDef: CurveDef,
-  options?: SarmalOptions,
-): SarmalInstance;
+declare function createSarmal(canvas: HTMLCanvasElement, curveDef: CurveDef, options?: SarmalOptions): SarmalInstance;
 
-export {
-  BaseRendererOptions,
-  CurveDef,
-  Engine,
-  Point,
-  RendererOptions,
-  type SVGRendererOptions,
-  type SVGSarmalOptions,
-  SarmalInstance,
-  SarmalOptions,
-  type SarmalPalette,
-  createEngine,
-  createRenderer,
-  createSVGRenderer,
-  createSarmal,
-  createSarmalSVG,
-  drawCurve,
-  evaluateCatmullRom,
-  palettes,
-};
+export { BaseRendererOptions, type BoundaryResult, CurveDef, Engine, Point, RendererOptions, type SVGRendererOptions, type SVGSarmalOptions, SarmalInstance, SarmalOptions, type SarmalPalette, computeBoundaries, createEngine, createRenderer, createSVGRenderer, createSarmal, createSarmalSVG, drawCurve, evaluateCatmullRom, palettes };