manim-web 0.29.0 → 0.30.0

package/dist/serialization/index.d.ts

@@ -14,4 +14,5 @@ export { registerSerializableMobject, unregisterSerializableMobject, getSerializ
 export type { SerializedScene, SerializedMobject, SerializedTransform, SerializedStyle, MobjectSerializer, SceneLike, ContainerLike, Vec3, } from './types';
 export { encodeStateToHash, decodeStateFromHash, writeStateToUrl, readStateFromUrl, onUrlStateChange, bindStateToUrl, } from './urlState';
 export type { WriteStateOptions, BindUrlStateOptions, UrlStateBinding, UrlStateController, } from './urlState';
+export { defineParametrizedScene, resolveProps, renderParametrized, propsFromUrl, type PropsRecord, type PropTypeTag, type PropsSchema, type DataFetcher, type SceneMetadata, type MetadataContext, type CalculateMetadataResult, type CalculateMetadata, type SceneBuilder, type ParametrizedSceneDefinition, type ResolvedMetadata, type ParametrizedRenderResult, type RenderParametrizedOptions, } from './parametrized';
 //# sourceMappingURL=index.d.ts.map

package/dist/serialization/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/serialization/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,2BAA2B,EAC3B,6BAA6B,EAC7B,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,aAAa,EACb,IAAI,GACL,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,GACnB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/serialization/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,2BAA2B,EAC3B,6BAA6B,EAC7B,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,aAAa,EACb,IAAI,GACL,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,2BAA2B,EAChC,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,gBAAgB,CAAC"}

package/dist/serialization/parametrized.d.ts

@@ -0,0 +1,152 @@
+import { Scene, SceneOptions } from '../core/Scene';
+/** A JSON-safe props bag. Each definition owns the shape of its own props. */
+export type PropsRecord = Record<string, unknown>;
+/** The runtime type tag a prop is validated and coerced against. */
+export type PropTypeTag = 'number' | 'string' | 'boolean' | 'vec3' | 'array' | 'object';
+/**
+ * Optional explicit schema: a type tag per prop key. When omitted, the tag of
+ * each prop is inferred from the type of its default value.
+ */
+export type PropsSchema<P extends object> = Partial<Record<keyof P, PropTypeTag>>;
+/**
+ * Fetches render-time data. The default implementation calls the global
+ * `fetch` and returns parsed JSON; tests inject a stub so they never touch the
+ * network. This is the dependency-injection seam for {@link renderParametrized}.
+ */
+export type DataFetcher = (url: string, init?: RequestInit) => Promise<unknown>;
+/** Scene config a {@link CalculateMetadata} hook may override before render. */
+export interface SceneMetadata {
+    /** Clip duration in seconds, for downstream export. Carried through as-is. */
+    duration?: number;
+    /** Render width in pixels. */
+    width?: number;
+    /** Render height in pixels. */
+    height?: number;
+    /** Target frame rate in fps. */
+    fps?: number;
+}
+/** Context passed to {@link CalculateMetadata}: resolved props and the fetcher. */
+export interface MetadataContext<P extends object> {
+    /** The props resolved from defaults + input (input wins). */
+    props: P;
+    /** The injected data fetcher (see {@link DataFetcher}). */
+    fetch: DataFetcher;
+}
+/**
+ * What {@link CalculateMetadata} returns: optional scene-config overrides, an
+ * optional patch of props (which wins over the input props), and the fetched
+ * `data` that reaches {@link SceneBuilder}.
+ */
+export interface CalculateMetadataResult<P extends object, D> extends SceneMetadata {
+    /** Props to override after the fetch (e.g. values computed from the data). */
+    props?: Partial<P>;
+    /** Data to pass to the build step. */
+    data?: D;
+}
+/** The async pre-render hook. Runs once, before the scene is built. */
+export type CalculateMetadata<P extends object, D> = (context: MetadataContext<P>) => CalculateMetadataResult<P, D> | Promise<CalculateMetadataResult<P, D>>;
+/** Builds the scene from the resolved props and the fetched data. */
+export type SceneBuilder<P extends object, D> = (scene: Scene, props: P, data: D | undefined) => void | Promise<void>;
+/** A parametrized scene definition. See {@link defineParametrizedScene}. */
+export interface ParametrizedSceneDefinition<P extends object, D = unknown> {
+    /** Optional stable id for logging or registry use. */
+    id?: string;
+    /** The default props. Also the source of the inferred prop schema. */
+    defaultProps: P;
+    /** Optional explicit per-prop type tags; inferred from defaults when absent. */
+    schema?: PropsSchema<P>;
+    /** Optional async hook that fetches data and overrides scene config. */
+    calculateMetadata?: CalculateMetadata<P, D>;
+    /** Builds the scene from resolved props + data. */
+    build: SceneBuilder<P, D>;
+}
+/** The resolved render metadata reported by {@link renderParametrized}. */
+export interface ResolvedMetadata {
+    /** Duration in seconds, as returned by the metadata hook (may be undefined). */
+    duration?: number;
+    /** The scene's actual render width in pixels. */
+    width: number;
+    /** The scene's actual render height in pixels. */
+    height: number;
+    /** The scene's actual target fps. */
+    fps: number;
+}
+/** The result of {@link renderParametrized}. */
+export interface ParametrizedRenderResult<P extends object, D> {
+    /** The built scene. */
+    scene: Scene;
+    /** The fully resolved props (defaults + input + metadata patch). */
+    props: P;
+    /** The data returned by the metadata hook, or undefined. */
+    data: D | undefined;
+    /** The resolved render metadata. */
+    metadata: ResolvedMetadata;
+    /** A shareable, URL-safe hash of the resolved props (reuses the URL codec). */
+    url: string;
+}
+/** Options for {@link renderParametrized}. */
+export interface RenderParametrizedOptions {
+    /** Build into this scene instead of a fresh headless one. */
+    scene?: Scene;
+    /** Scene options for the created scene when `scene` is not supplied. */
+    sceneOptions?: SceneOptions;
+    /** Injected data fetcher. Defaults to the global `fetch` + JSON parse. */
+    fetch?: DataFetcher;
+    /** Write the resolved props to the URL hash (no-op headless). Default false. */
+    writeUrl?: boolean;
+    /** Use `history.replaceState` when writing the URL. Default true. */
+    urlReplace?: boolean;
+}
+/**
+ * Define a parametrized scene. This is a typed identity helper: it infers the
+ * props and data generics from the definition and returns it unchanged.
+ *
+ * @param definition - The scene definition (defaults, optional schema, optional
+ *   metadata hook, build function).
+ * @returns The same definition, typed.
+ *
+ * @example
+ * ```ts
+ * const bar = defineParametrizedScene({
+ *   defaultProps: { label: 'A', value: 1, color: '#58C4DD' },
+ *   calculateMetadata: async ({ props, fetch }) => {
+ *     const data = await fetch(`/api/series/${props.label}`);
+ *     return { data, duration: 3, width: 1920, height: 1080, fps: 60 };
+ *   },
+ *   build: (scene, props, data) => {
+ *     // ...assemble the scene from props + data
+ *   },
+ * });
+ * ```
+ */
+export declare function defineParametrizedScene<P extends object, D = unknown>(definition: ParametrizedSceneDefinition<P, D>): ParametrizedSceneDefinition<P, D>;
+/**
+ * Resolve the effective props for a definition: a clone of the defaults with
+ * the input props merged over them (input wins). Each input value is coerced to
+ * the type of its default; an uncoercible or unknown key falls back to the
+ * default. Reused by {@link renderParametrized} and {@link propsFromUrl}.
+ *
+ * @param definition - The parametrized scene definition.
+ * @param inputProps - Partial input props (unknown keys are ignored).
+ * @returns The fully resolved props.
+ */
+export declare function resolveProps<P extends object, D>(definition: ParametrizedSceneDefinition<P, D>, inputProps?: PropsRecord): P;
+/** Read props from the current URL hash and resolve them against the defaults. */
+export declare function propsFromUrl<P extends object, D>(definition: ParametrizedSceneDefinition<P, D>): P;
+/**
+ * Render a parametrized scene: merge input props over defaults (input wins),
+ * run `calculateMetadata` (which may fetch data and override size/fps/duration),
+ * apply the metadata to the scene, build the scene, and expose the resolved
+ * props as a shareable URL hash.
+ *
+ * Headless-safe: with no `scene` and no DOM it builds a headless scene and the
+ * URL write is a no-op. The data fetch goes through the injectable
+ * {@link DataFetcher} seam, so tests never touch the network.
+ *
+ * @param definition - The parametrized scene definition.
+ * @param inputProps - Partial input props (merged over the defaults).
+ * @param options - Scene, fetcher and URL-write options.
+ * @returns The built scene, resolved props, data, metadata and shareable URL.
+ */
+export declare function renderParametrized<P extends object, D = unknown>(definition: ParametrizedSceneDefinition<P, D>, inputProps?: PropsRecord, options?: RenderParametrizedOptions): Promise<ParametrizedRenderResult<P, D>>;
+//# sourceMappingURL=parametrized.d.ts.map

package/dist/serialization/parametrized.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parametrized.d.ts","sourceRoot":"","sources":["../../src/serialization/parametrized.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAKzD,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,oEAAoE;AACpE,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAExF;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC;AAElF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhF,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,mFAAmF;AACnF,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM;IAC/C,6DAA6D;IAC7D,KAAK,EAAE,CAAC,CAAC;IACT,2DAA2D;IAC3D,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,CAAE,SAAQ,aAAa;IACjF,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACnB,sCAAsC;IACtC,IAAI,CAAC,EAAE,CAAC,CAAC;CACV;AAED,uEAAuE;AACvE,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,IAAI,CACnD,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,KACxB,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE5E,qEAAqE;AACrE,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,IAAI,CAC9C,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,CAAC,EACR,IAAI,EAAE,CAAC,GAAG,SAAS,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,4EAA4E;AAC5E,MAAM,WAAW,2BAA2B,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,OAAO;IACxE,sDAAsD;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,YAAY,EAAE,CAAC,CAAC;IAChB,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACxB,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5C,mDAAmD;IACnD,KAAK,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC3B;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,gDAAgD;AAChD,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC;IAC3D,uBAAuB;IACvB,KAAK,EAAE,KAAK,CAAC;IACb,oEAAoE;IACpE,KAAK,EAAE,CAAC,CAAC;IACT,4DAA4D;IAC5D,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IACpB,oCAAoC;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC,6DAA6D;IAC7D,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,wEAAwE;IACxE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAqFD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,OAAO,EACnE,UAAU,EAAE,2BAA2B,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5C,2BAA2B,CAAC,CAAC,EAAE,CAAC,CAAC,CAEnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAC9C,UAAU,EAAE,2BAA2B,CAAC,CAAC,EAAE,CAAC,CAAC,EAC7C,UAAU,CAAC,EAAE,WAAW,GACvB,CAAC,CAEH;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAC9C,UAAU,EAAE,2BAA2B,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5C,CAAC,CAIH;AA4BD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,OAAO,EACpE,UAAU,EAAE,2BAA2B,CAAC,CAAC,EAAE,CAAC,CAAC,EAC7C,UAAU,CAAC,EAAE,WAAW,EACxB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CA+CzC"}