@sarmal/core 0.24.0 → 0.25.1

package/dist/index.d.cts

@@ -1,31 +1,46 @@
-import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, R as RendererOptions, P as Point, a as SarmalOptions } from './types-CknrlCAf.cjs';
-export { J as JumpOptions, b as RuntimeRenderOptions, c as SeekOptions, T as TrailColor, d as TrailStyle } from './types-CknrlCAf.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-Z9i1_AQZ.cjs";
+export {
+  J as JumpOptions,
+  c as RuntimeRenderOptions,
+  d as SeekOptions,
+  T as TrailColor,
+  e as TrailStyle,
+} from "./types-Z9i1_AQZ.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
@@ -50,19 +65,43 @@ 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;
 
@@ -86,7 +125,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.
@@ -94,8 +133,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.
+ * @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π` and the spline evaluator as its `fn`.
- *                `name` is set to `"custom"`.
  * @throws        If `points` has fewer than 3 entries.
  *
  * @example
@@ -111,7 +151,12 @@ 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
@@ -127,6 +172,31 @@ 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,31 +1,46 @@
-import { B as BaseRendererOptions, E as Engine, S as SarmalInstance, C as CurveDef, R as RendererOptions, P as Point, a as SarmalOptions } from './types-CknrlCAf.js';
-export { J as JumpOptions, b as RuntimeRenderOptions, c as SeekOptions, T as TrailColor, d as TrailStyle } from './types-CknrlCAf.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-Z9i1_AQZ.js";
+export {
+  J as JumpOptions,
+  c as RuntimeRenderOptions,
+  d as SeekOptions,
+  T as TrailColor,
+  e as TrailStyle,
+} from "./types-Z9i1_AQZ.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
@@ -50,19 +65,43 @@ 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;
 
@@ -86,7 +125,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.
@@ -94,8 +133,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.
+ * @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π` and the spline evaluator as its `fn`.
- *                `name` is set to `"custom"`.
  * @throws        If `points` has fewer than 3 entries.
  *
  * @example
@@ -111,7 +151,12 @@ 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
@@ -127,6 +172,31 @@ 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,
+};