manim-web 0.20.0 → 0.22.0

package/dist/mobjects/particles/ParticleSystem.d.ts

@@ -0,0 +1,162 @@
+import { Vector3Tuple } from '../../core/Mobject';
+import { PMobject } from '../point/PMobject';
+/** External forces applied to every particle each step. */
+export interface ParticleForces {
+    /** Constant acceleration [x, y, z] in units/sec^2. Default: [0, 0, 0]. */
+    gravity?: Vector3Tuple;
+    /**
+     * Velocity damping per second, from 0 (none) to 1 (full stop in one second).
+     * Each step scales velocity by `1 - drag * dt`. Default: 0.
+     */
+    drag?: number;
+}
+/**
+ * A snapshot of one living particle, returned by {@link ParticleSystem.getParticles}.
+ * The arrays are copies, so a caller cannot mutate the internal state.
+ */
+export interface ParticleSnapshot {
+    /** Current position [x, y, z]. */
+    position: Vector3Tuple;
+    /** Current velocity [x, y, z] in units/sec. */
+    velocity: Vector3Tuple;
+    /** Age in seconds since the particle was spawned. */
+    age: number;
+    /** Total lifetime in seconds. The particle dies when `age > lifetime`. */
+    lifetime: number;
+    /** Current size, interpolated from `startSize` to `endSize` over the life. */
+    size: number;
+    /** Current color, interpolated from `startColor` to `endColor` over the life. */
+    color: string;
+}
+/** Options for creating a {@link ParticleSystem}. */
+export interface ParticleSystemOptions {
+    /** Particles emitted per second. Default: 20. */
+    spawnRate?: number;
+    /** Maximum living particles. Emission stops at the cap. Default: 500. */
+    maxParticles?: number;
+    /** Base lifetime in seconds. Default: 2. */
+    lifetime?: number;
+    /** Random +/- lifetime variation in seconds. Default: 0. */
+    lifetimeSpread?: number;
+    /** Emitter origin [x, y, z]. Default: [0, 0, 0]. */
+    position?: Vector3Tuple;
+    /** Random +/- spawn offset per axis from the origin. Default: [0, 0, 0]. */
+    positionSpread?: Vector3Tuple;
+    /** Initial velocity [x, y, z] in units/sec. Default: [0, 1, 0]. */
+    velocity?: Vector3Tuple;
+    /** Random +/- velocity variation per axis. Default: [0, 0, 0]. */
+    velocitySpread?: Vector3Tuple;
+    /** Forces applied each step. Default: none. */
+    forces?: ParticleForces;
+    /** Size at birth. Default: 8. */
+    startSize?: number;
+    /** Size at death. Default: 0. */
+    endSize?: number;
+    /** Color at birth. Default: white. */
+    startColor?: string;
+    /** Color at death. Default: white. */
+    endColor?: string;
+    /** Interpolate color in Oklab space for a smoother blend. Default: false. */
+    useOklab?: boolean;
+    /** Seed for the deterministic PRNG. Default: 0. */
+    seed?: number;
+}
+/**
+ * ParticleSystem - an emitter that spawns, integrates, ages and culls particles.
+ *
+ * Add it to a scene and the render loop calls {@link update} each frame, which
+ * advances the simulation by `dt`. Call {@link step} to advance it manually,
+ * for tests or offline renders.
+ *
+ * @example
+ * ```typescript
+ * const fountain = new ParticleSystem({
+ *   spawnRate: 60,
+ *   lifetime: 1.5,
+ *   velocity: [0, 4, 0],
+ *   velocitySpread: [1, 0.5, 1],
+ *   forces: { gravity: [0, -9.8, 0] },
+ *   startColor: '#ffcc00',
+ *   endColor: '#ff0033',
+ *   seed: 7,
+ * });
+ * scene.add(fountain);
+ * ```
+ */
+export declare class ParticleSystem extends PMobject {
+    private _spawnRate;
+    private readonly _maxParticles;
+    private readonly _lifetime;
+    private readonly _lifetimeSpread;
+    private readonly _origin;
+    private readonly _positionSpread;
+    private readonly _velocity;
+    private readonly _velocitySpread;
+    private readonly _gravity;
+    private readonly _drag;
+    private readonly _startSize;
+    private readonly _endSize;
+    private readonly _startColor;
+    private readonly _endColor;
+    private readonly _useOklab;
+    private _seed;
+    /** Living particles, oldest first. */
+    private _particles;
+    /** Fractional carry so a low `spawnRate * dt` still emits over several steps. */
+    private _spawnCarry;
+    /** The deterministic PRNG, re-created from the seed on {@link reset}. */
+    private _rng;
+    constructor(options?: ParticleSystemOptions);
+    /** The seed that drives the deterministic PRNG. */
+    get seed(): number;
+    /**
+     * Set the seed and restart the PRNG from it. Does not remove living particles;
+     * call {@link reset} for a full restart.
+     */
+    set seed(value: number);
+    /** Set the emission rate in particles per second. */
+    setSpawnRate(rate: number): this;
+    /** The current emission rate in particles per second. */
+    getSpawnRate(): number;
+    /** The number of living particles. */
+    getLivingCount(): number;
+    /**
+     * Snapshots of all living particles, oldest first. The returned records are
+     * copies, so mutating them does not change the simulation.
+     */
+    getParticles(): ParticleSnapshot[];
+    /**
+     * Remove every particle and restart the PRNG from the seed. After a reset, the
+     * same sequence of {@link step} calls reproduces the same evolution as a fresh
+     * system with the same seed.
+     */
+    reset(): this;
+    /**
+     * Advance the simulation by `dt` seconds. The step spawns new particles for the
+     * elapsed time, integrates position and velocity under the forces, ages every
+     * particle, and removes those whose age passes their lifetime.
+     *
+     * @param dt - Elapsed time in seconds. Values <= 0 are ignored.
+     */
+    step(dt: number): this;
+    /** Emit `floor(spawnRate * dt + carry)` particles, up to the cap. */
+    private _spawn;
+    /** Build one particle at the emitter, with seeded spread on spawn values. */
+    private _makeParticle;
+    /** A seeded random offset in the range [-amount, amount]. */
+    private _spread;
+    /**
+     * Semi-implicit Euler integration. For each particle, apply gravity and drag to
+     * the velocity, move by the new velocity, then age it and update its size and
+     * color from the age fraction.
+     */
+    private _integrate;
+    /** Remove particles whose age has passed their lifetime. Order is preserved. */
+    private _cull;
+    /** Mirror the living particles into the PMobject point buffer for rendering. */
+    private _syncParticlesToPoints;
+    /** An empty system has no living particles, so skip the bounding box. */
+    isEmpty(): boolean;
+    copy(): ParticleSystem;
+}
+//# sourceMappingURL=ParticleSystem.d.ts.map

package/dist/mobjects/particles/ParticleSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleSystem.d.ts","sourceRoot":"","sources":["../../../src/mobjects/particles/ParticleSystem.ts"],"names":[],"mappings":"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"}

package/dist/mobjects/particles/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Particle-based mobjects: emitters that spawn, integrate and cull particles
+ * over time under forces, for motion graphics such as explosions and sparks.
+ */
+export { ParticleSystem, type ParticleSystemOptions, type ParticleForces, type ParticleSnapshot, } from './ParticleSystem';
+//# sourceMappingURL=index.d.ts.map

package/dist/mobjects/particles/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mobjects/particles/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/mobjects/text/TextOnPath.d.ts

@@ -0,0 +1,70 @@
+import { VGroup } from '../../core/VGroup';
+import { VMobject } from '../../core/VMobject';
+import { TextOnPathAlignment, TextOnPathOverflow } from './textOnPathLayout';
+/** A path the text can follow: a VMobject, a raw point chain, or a function. */
+export type TextOnPathSource = VMobject | number[][] | ((t: number) => number[]);
+/** A pre-built glyph plus its advance width, for synchronous layout. */
+export interface TextOnPathGlyph {
+    /** The glyph mobject to position. */
+    mobject: VMobject;
+    /** Advance width in world units. Defaults to `mobject.getWidth()`. */
+    width?: number;
+    /** Extra gap before this glyph (world units). Default 0. */
+    leadingGap?: number;
+}
+/** Options for {@link TextOnPath}. */
+export interface TextOnPathOptions {
+    /** The path to lay the glyphs on. */
+    path: TextOnPathSource;
+    /** Pre-built glyphs (synchronous mode). */
+    glyphs?: TextOnPathGlyph[];
+    /** Text to render (asynchronous font mode; needs `fontUrl`). */
+    text?: string;
+    /** URL of the font file (OTF/TTF) for font mode. */
+    fontUrl?: string;
+    /** Font size in pixels. Default 48. */
+    fontSize?: number;
+    /** Glyph color. Default '#ffffff'. */
+    color?: string;
+    /** Arc-length distance where the run starts. Default 0. */
+    startOffset?: number;
+    /** Extra spacing added after every glyph (world units). Default 0. */
+    tracking?: number;
+    /** Rotate each glyph to the path tangent. Default true. */
+    rotateWithTangent?: boolean;
+    /** Vertical placement relative to the curve. Default 'center'. */
+    alignment?: TextOnPathAlignment;
+    /** Clamp to the ends or wrap around the path. Default 'clamp'. */
+    overflow?: TextOnPathOverflow;
+}
+/**
+ * A VGroup of glyph mobjects laid out along a path.
+ *
+ * Synchronous usage:
+ *   const t = new TextOnPath({ glyphs, path: arc });
+ *
+ * Font usage:
+ *   const t = new TextOnPath({ text: 'Hello', fontUrl, path: arc });
+ *   await t.waitForReady();
+ */
+export declare class TextOnPath extends VGroup {
+    private readonly _options;
+    private readonly _path;
+    private readonly _fontSize;
+    private readonly _glyphColor;
+    private _readyPromise;
+    constructor(options: TextOnPathOptions);
+    /** Resolves once the font has loaded and glyphs are laid out (font mode). */
+    waitForReady(): Promise<void>;
+    /** Build a {@link SampledPath} from any accepted path source. */
+    private static _buildPath;
+    /**
+     * Position every glyph mobject along the path and add it to this group.
+     * Each glyph is transformed while unparented, so `rotate` and `moveTo`
+     * act in world space, then added to the group.
+     */
+    private _layoutGlyphs;
+    /** Load the font, build a GlyphVMobject per visible character, lay them out. */
+    private _loadAndBuild;
+}
+//# sourceMappingURL=TextOnPath.d.ts.map

package/dist/mobjects/text/TextOnPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextOnPath.d.ts","sourceRoot":"","sources":["../../../src/mobjects/text/TextOnPath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,OAAO,EAQL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAK5B,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;AAEjF,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,OAAO,EAAE,QAAQ,CAAC;IAClB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,IAAI,EAAE,gBAAgB,CAAC;IACvB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kEAAkE;IAClE,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,qBAAa,UAAW,SAAQ,MAAM;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,aAAa,CAAgB;gBAEzB,OAAO,EAAE,iBAAiB;IA8BtC,6EAA6E;IACvE,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC,iEAAiE;IACjE,OAAO,CAAC,MAAM,CAAC,UAAU;IAUzB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAkCrB,gFAAgF;YAClE,aAAa;CAmD5B"}

package/dist/mobjects/text/index.d.ts

@@ -8,6 +8,8 @@ export { Text, type TextOptions } from './Text';
 export { type TextStyleMaps, type TextStyleRun, buildStyledTextLines } from './textStyleRuns';
 export { GlyphVMobject, type GlyphVMobjectOptions } from './GlyphVMobject';
 export { TextGlyphGroup, type TextGlyphGroupOptions } from './TextGlyphGroup';
+export { TextOnPath, type TextOnPathOptions, type TextOnPathGlyph, type TextOnPathSource, } from './TextOnPath';
+export { computeGlyphPlacements, sampledPathFromPoints, sampledPathFromFunction, visibleGlyphChars, alignmentToOffset, type SampledPath, type GlyphLayoutEntry, type GlyphLayoutOptions, type GlyphPlacement, type TextOnPathAlignment, type TextOnPathOverflow, type PathPoint, } from './textOnPathLayout';
 export { Paragraph, type ParagraphOptions } from './Paragraph';
 export { MarkupText, type MarkupTextOptions, type StyledTextSegment } from './MarkupText';
 export { ensureKatexStyles, areKatexStylesLoaded, setKatexStylesheetUrl } from './katexStyles';

package/dist/mobjects/text/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mobjects/text/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAGhD,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG9F,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAG9E,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/D,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAG1F,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG/F,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAG7F,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG1F,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG9F,OAAO,EAAE,GAAG,EAAE,KAAK,UAAU,EAAE,MAAM,OAAO,CAAC;AAI7C,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACrF,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAGpF,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAG5D,OAAO,EACL,IAAI,EACJ,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,KAAK,EACV,KAAK,SAAS,EACd,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG/E,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,WAAW,EACX,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,YAAY,EACZ,KAAK,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mobjects/text/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAGhD,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG9F,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAG9E,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,SAAS,GACf,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/D,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAG1F,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG/F,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAG7F,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG1F,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG9F,OAAO,EAAE,GAAG,EAAE,KAAK,UAAU,EAAE,MAAM,OAAO,CAAC;AAI7C,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACrF,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAGpF,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAG5D,OAAO,EACL,IAAI,EACJ,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,KAAK,EACV,KAAK,SAAS,EACd,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG/E,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,WAAW,EACX,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,YAAY,EACZ,KAAK,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC"}

package/dist/mobjects/text/textOnPathLayout.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Pure layout math for laying glyphs along an arbitrary curve (text-on-a-path).
+ *
+ * This module has no dependency on fonts or Three.js. It turns a list of glyph
+ * advance widths and a sampled path into per-glyph placements (a center point
+ * and a rotation angle). `TextOnPath` consumes these placements to position its
+ * glyph mobjects, which keeps the geometry independently testable.
+ *
+ * All distances are arc length in world units. Angles are radians (atan2).
+ */
+/** A 3D point `[x, y, z]`. */
+export type PathPoint = [number, number, number];
+/** Vertical placement of each glyph relative to the curve. */
+export type TextOnPathAlignment = 'center' | 'baseline' | 'top';
+/** Behavior when a glyph runs past the end of the path. */
+export type TextOnPathOverflow = 'clamp' | 'wrap';
+/**
+ * A path that reports its total arc length and can be sampled by arc-length
+ * distance. Built from a cubic Bezier point chain or from a function.
+ */
+export interface SampledPath {
+    /** Total arc length of the path in world units. */
+    readonly totalLength: number;
+    /** Point at absolute arc-length distance `d` (clamped to `[0, totalLength]`). */
+    pointAtDistance(d: number): PathPoint;
+    /** Tangent angle (radians) at absolute arc-length distance `d`. */
+    angleAtDistance(d: number): number;
+}
+/** One glyph to place, described only by its advance width and leading gap. */
+export interface GlyphLayoutEntry {
+    /** Advance width of the glyph in world units. */
+    width: number;
+    /** Extra gap before this glyph (spaces, kerning). Default 0. */
+    leadingGap?: number;
+}
+/** Options that drive {@link computeGlyphPlacements}. */
+export interface GlyphLayoutOptions {
+    /** Arc-length distance where the run starts. Default 0. */
+    startOffset?: number;
+    /** Extra spacing added after every glyph. Default 0. */
+    tracking?: number;
+    /** Rotate each glyph to the path tangent. Default true. */
+    rotateWithTangent?: boolean;
+    /** Perpendicular offset from the curve (world units). Default 0. */
+    alignmentOffset?: number;
+    /** Clamp to the ends or wrap around the path. Default 'clamp'. */
+    overflow?: TextOnPathOverflow;
+}
+/** The computed placement of one glyph along the path. */
+export interface GlyphPlacement {
+    /** World point where the glyph center sits. */
+    center: PathPoint;
+    /** Rotation angle in radians (0 when `rotateWithTangent` is false). */
+    angle: number;
+    /** Arc-length distance of the glyph center before clamp or wrap. */
+    distance: number;
+    /** True when the glyph center ran past an end of the path. */
+    overflow: boolean;
+}
+/**
+ * Build a {@link SampledPath} from a shared-anchor cubic Bezier point chain
+ * (the point layout every VMobject uses).
+ *
+ * @param points - Point chain `[A0, H1, H2, A1, H3, H4, A2, ...]`
+ * @param samplesPerSegment - Samples per cubic for the arc-length table
+ */
+export declare function sampledPathFromPoints(points: number[][], samplesPerSegment?: number): SampledPath;
+/**
+ * Build a {@link SampledPath} from a parametric function `t -> [x, y, z]`,
+ * `t` in `[0, 1]`.
+ *
+ * @param fn - Parametric curve function
+ * @param samples - Number of sample segments (default 200)
+ */
+export declare function sampledPathFromFunction(fn: (t: number) => number[], samples?: number): SampledPath;
+/**
+ * Place glyphs along a path by advancing a pen along the arc length.
+ *
+ * Each glyph center is set at `pen + leadingGap + width / 2`, where `pen`
+ * advances by `width + tracking` after every glyph. A glyph whose center runs
+ * past an end is marked `overflow` and is either clamped to the nearest end or
+ * wrapped around the path, per `options.overflow`.
+ *
+ * @param glyphs - Glyph advance widths and leading gaps, in order
+ * @param path - The path to lay the glyphs on
+ * @param options - Layout options (see {@link GlyphLayoutOptions})
+ * @returns One placement per input glyph
+ */
+export declare function computeGlyphPlacements(glyphs: GlyphLayoutEntry[], path: SampledPath, options?: GlyphLayoutOptions): GlyphPlacement[];
+/**
+ * The visible (non-whitespace) characters of a string, in order.
+ * Whitespace advances the pen but draws no glyph, so it is excluded here.
+ *
+ * @param text - Input string
+ * @returns Array of visible characters
+ */
+export declare function visibleGlyphChars(text: string): string[];
+/**
+ * Map an {@link TextOnPathAlignment} to a perpendicular offset from the curve.
+ *
+ * `center` keeps the glyph center on the curve. `baseline` lifts it to the
+ * positive-perpendicular side (baseline near the curve) and `top` lowers it,
+ * each by `height / 2`.
+ *
+ * @param alignment - Alignment mode
+ * @param height - Representative glyph height in world units
+ * @returns Perpendicular offset in world units
+ */
+export declare function alignmentToOffset(alignment: TextOnPathAlignment, height: number): number;
+//# sourceMappingURL=textOnPathLayout.d.ts.map

package/dist/mobjects/text/textOnPathLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textOnPathLayout.d.ts","sourceRoot":"","sources":["../../../src/mobjects/text/textOnPathLayout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,8BAA8B;AAC9B,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD,8DAA8D;AAC9D,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAC;AAEhE,2DAA2D;AAC3D,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,mEAAmE;IACnE,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACpC;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,yDAAyD;AACzD,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,MAAM,EAAE,SAAS,CAAC;IAClB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;CACnB;AA2BD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,iBAAiB,SAAK,GAAG,WAAW,CA+D7F;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAAE,EAAE,OAAO,SAAM,GAAG,WAAW,CA0C/F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,gBAAgB,EAAE,EAC1B,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE,kBAAuB,GAC/B,cAAc,EAAE,CA6ClB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAExD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIxF"}