manim-web 0.19.0 → 0.21.0

package/dist/mobjects/graphing/PieChart.d.ts

@@ -0,0 +1,180 @@
+import { VGroup } from '../../core/VGroup';
+import { VMobject } from '../../core/VMobject';
+/**
+ * Geometry of one slice, derived from the data.
+ * Non-positive values are skipped, so `index` is the position in the
+ * original `values` array and is not always contiguous.
+ */
+export interface SliceGeometry {
+    /** Index of this value in the original `values` array. */
+    index: number;
+    /** The (positive) data value for this slice. */
+    value: number;
+    /** Fraction of the total this slice occupies, in [0, 1]. */
+    fraction: number;
+    /** Start angle of the slice sweep, in radians. */
+    startAngle: number;
+    /** Sweep angle of the slice, in radians (proportional to the value). */
+    angle: number;
+}
+/**
+ * Compute the sweep angles for a set of values.
+ *
+ * Each positive value gets a sweep angle proportional to `value / total`.
+ * Non-positive values (zero and negative) are skipped and get no slice.
+ * The returned slices sweep counterclockwise from `startAngle`, in the order
+ * of the input array.
+ *
+ * @param values - The raw data values.
+ * @param startAngle - Angle of the first slice edge, in radians.
+ * @returns One SliceGeometry per positive value. Empty array if the total is 0.
+ */
+export declare function computeSliceGeometry(values: number[], startAngle: number): SliceGeometry[];
+/** How slice labels are placed relative to the slice. */
+export type LabelPosition = 'inside' | 'outside';
+/**
+ * Options shared by PieChart and DonutChart.
+ */
+export interface PieChartOptions {
+    /** Data values. One slice per positive value. Default: required. */
+    values: number[];
+    /** Text label for each value (by original index). Default: []. */
+    labels?: string[];
+    /** Slice colors. Single color applies to all, array cycles. Default: Manim palette. */
+    colors?: string | string[];
+    /** Angle of the first slice edge, in radians. Default: Math.PI / 2 (12 o'clock). */
+    startAngle?: number;
+    /** Outer radius of the chart. Default: 2. */
+    radius?: number;
+    /** Fill opacity of the slices. Default: 0.8. */
+    fillOpacity?: number;
+    /** Stroke color drawn between slices. Default: WHITE. */
+    strokeColor?: string;
+    /** Stroke width drawn between slices. Default: 2. */
+    strokeWidth?: number;
+    /** Whether to draw text labels on the slices. Default: true when labels are given. */
+    showLabels?: boolean;
+    /** Whether to append the percentage to each label. Default: false. */
+    showPercentages?: boolean;
+    /** Font size for slice labels. Default: 24. */
+    labelFontSize?: number;
+    /** Place labels 'inside' the slices or 'outside' the rim. Default: 'outside'. */
+    labelPosition?: LabelPosition;
+    /** Whether to draw a legend of label swatches. Default: false. */
+    showLegend?: boolean;
+    /** Font size for legend labels. Default: 18. */
+    legendFontSize?: number;
+}
+/**
+ * PieChart - a data-to-pie visualization mobject.
+ *
+ * Builds a VGroup of {@link Sector}s whose sweep angles are proportional to
+ * each value divided by the total. Non-positive values are skipped, a single
+ * value fills the whole circle, and empty data yields an empty group.
+ *
+ * @example
+ * ```typescript
+ * const pie = new PieChart({
+ *   values: [30, 20, 50],
+ *   labels: ['A', 'B', 'C'],
+ *   showPercentages: true,
+ * });
+ * pie.getSlice(0); // the first Sector
+ * ```
+ */
+export declare class PieChart extends VGroup {
+    /** The slice sectors. */
+    slices: VGroup;
+    /** The slice labels. */
+    labelGroup: VGroup;
+    /** The legend, when enabled. */
+    legend: VGroup | null;
+    protected _values: number[];
+    protected _labelTexts: string[];
+    protected _colors: string[];
+    protected _startAngle: number;
+    protected _radius: number;
+    protected _fillOpacity: number;
+    protected _strokeColor: string;
+    protected _strokeWidth: number;
+    protected _showLabels: boolean;
+    protected _showPercentages: boolean;
+    protected _labelFontSize: number;
+    protected _labelPosition: LabelPosition;
+    protected _showLegend: boolean;
+    protected _legendFontSize: number;
+    protected _geometry: SliceGeometry[];
+    constructor(options: PieChartOptions);
+    /**
+     * Create one slice mobject. Overridden by DonutChart to use AnnularSector.
+     * @param geom - The slice geometry.
+     * @param color - The slice fill color.
+     * @returns A Sector sweeping the slice.
+     */
+    protected _makeSlice(geom: SliceGeometry, color: string): VMobject;
+    /** Color for the slice at the given original value index. */
+    protected _colorForIndex(index: number): string;
+    /** Build all slice sectors into `this.slices`. */
+    protected _buildSlices(): void;
+    /** Radius at which to place a label for the given position mode. */
+    protected _labelRadius(): number;
+    /** Build the slice labels into `this.labelGroup`. */
+    protected _buildLabels(): void;
+    /** Compose the label text for a slice (name and/or percentage). */
+    protected _labelText(geom: SliceGeometry): string;
+    /** Build the legend into a new VGroup. */
+    protected _buildLegend(): VGroup;
+    /** Get all slice sectors. */
+    getSectors(): VMobject[];
+    /**
+     * Get a single slice sector by position.
+     * @param index - Position in the slice list (not the original value index).
+     * @returns The sector, or undefined when out of range.
+     */
+    getSlice(index: number): VMobject | undefined;
+    /** Get the slice geometry (angles and fractions) for all slices. */
+    getSliceGeometry(): SliceGeometry[];
+    /** Get the original data values. */
+    getValues(): number[];
+    /** Get the outer radius. */
+    getRadius(): number;
+    copy(): PieChart;
+    /** Options bundle used to reconstruct this chart in copy(). */
+    protected _optionsForCopy(): PieChartOptions;
+}
+/**
+ * Options for DonutChart. Adds the hole radius to {@link PieChartOptions}.
+ */
+export interface DonutChartOptions extends PieChartOptions {
+    /**
+     * Hole radius as a fraction of the outer radius, in [0, 1).
+     * Default: 0.5. A value of 0 makes a full pie.
+     */
+    innerRadius?: number;
+}
+/**
+ * DonutChart - a PieChart with a hole in the middle.
+ *
+ * Builds a VGroup of {@link AnnularSector}s. The slice-angle logic is shared
+ * with {@link PieChart}; only the slice shape differs. `innerRadius` is a
+ * fraction of the outer radius, in [0, 1).
+ *
+ * @example
+ * ```typescript
+ * const donut = new DonutChart({ values: [1, 2, 3], innerRadius: 0.5 });
+ * ```
+ */
+export declare class DonutChart extends PieChart {
+    protected _innerRadiusFraction: number;
+    constructor(options: DonutChartOptions);
+    private static _clampFraction;
+    /** Absolute inner (hole) radius in scene units. */
+    getInnerRadius(): number;
+    /** Inner radius as a fraction of the outer radius. */
+    getInnerRadiusFraction(): number;
+    /** Replace the pie sectors built by the base constructor with annular sectors. */
+    private _rebuildSlicesAsDonut;
+    protected _makeSlice(geom: SliceGeometry, color: string): VMobject;
+    copy(): DonutChart;
+}
+//# sourceMappingURL=PieChart.d.ts.map

package/dist/mobjects/graphing/PieChart.d.ts.map

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

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

@@ -21,5 +21,6 @@ export { VectorFieldVector, type VectorFieldVectorOptions } from './Vector';
 export { ComplexPlane, type ComplexPlaneOptions, type Complex } from './ComplexPlane';
 export { PolarPlane, type PolarPlaneOptions } from './ComplexPlane';
 export { BarChart, type BarChartOptions } from './BarChart';
+export { PieChart, type PieChartOptions, DonutChart, type DonutChartOptions, computeSliceGeometry, type SliceGeometry, type LabelPosition, } from './PieChart';
 export { VectorField, ArrowVectorField, StreamLines, stepVectorField, type Integrator, type VectorFunction, type ColorFunction, type VectorFieldBaseOptions, type ArrowVectorFieldOptions, type StreamLinesOptions, type ContinuousMotionOptions, } from './VectorField';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mobjects/graphing/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,YAAY,EACZ,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAGhD,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAGtF,OAAO,EAAE,KAAK,2BAA2B,EAAE,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAGjG,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAG/F,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG3E,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAGpF,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtF,OAAO,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGzE,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAG7E,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAGxF,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAG1F,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAG5E,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGtF,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGpE,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAG5D,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mobjects/graphing/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,YAAY,EACZ,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAGhD,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAGtF,OAAO,EAAE,KAAK,2BAA2B,EAAE,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAGjG,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAG/F,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG3E,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAGpF,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtF,OAAO,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGzE,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAG7E,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAGxF,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAG1F,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAG5E,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGtF,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGpE,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAG5D,OAAO,EACL,QAAQ,EACR,KAAK,eAAe,EACpB,UAAU,EACV,KAAK,iBAAiB,EACtB,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,eAAe,CAAC"}

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"}