manim-web 0.22.0 → 0.24.0

package/dist/serialization/urlState.d.ts

@@ -0,0 +1,127 @@
+/**
+ * URL-state permalinks for explorables.
+ *
+ * Turn the live state of an explorable (MovablePoint positions, Slider values,
+ * PanZoom camera) into a compact, shareable URL and restore it on load. This is
+ * the Desmos/Observable "share this view" behavior: one link reproduces the
+ * reader's interactive state.
+ *
+ * The state is any JSON-serializable value. It is `JSON.stringify`-ed, encoded
+ * as UTF-8 bytes, then written as an unpadded base64url string, so the result
+ * is URL-safe (only `A-Z a-z 0-9 - _`) and needs no percent-escaping in a hash.
+ *
+ * Every `window` / `location` / `history` access is guarded, so each function
+ * degrades to a no-op (or `null`) without throwing in a headless environment.
+ */
+/** Options for {@link bindStateToUrl}. */
+export interface BindUrlStateOptions {
+    /** Use `history.replaceState` (no new history entry) when saving. Default: true. */
+    replace?: boolean;
+    /** Apply the URL state to the controls immediately on bind. Default: true. */
+    restoreOnBind?: boolean;
+    /** Re-apply the URL state to the controls on every `hashchange`. Default: true. */
+    listen?: boolean;
+}
+/**
+ * One control's serializable state, keyed by a stable user-provided id.
+ *
+ * The controls (MovablePoint, Slider, PanZoomControls) have no registered scene
+ * serializer for their interactive state, so a permalink captures a small
+ * explicit `{ id: value }` map: `get` reads the live value, `set` restores it.
+ */
+export interface UrlStateBinding {
+    /** Stable id used as the key in the encoded `{ id: value }` map. */
+    id: string;
+    /** Read the current JSON-serializable value of this control. */
+    get: () => unknown;
+    /** Apply a decoded value back to this control. */
+    set: (value: unknown) => void;
+}
+/** Handle returned by {@link bindStateToUrl}. */
+export interface UrlStateController {
+    /** Read the current value of every binding into an `{ id: value }` map. */
+    capture: () => Record<string, unknown>;
+    /** Capture the current state and write it to the URL hash. */
+    save: () => void;
+    /**
+     * Read the URL hash and apply it to the bindings. Returns `true` when a valid
+     * state was found and applied, `false` otherwise.
+     */
+    restore: () => boolean;
+    /** Stop listening for `hashchange` (when `listen` was enabled). */
+    dispose: () => void;
+}
+/**
+ * Encode a JSON-serializable state to a compact, URL-safe string.
+ *
+ * The result contains only `A-Z a-z 0-9 - _`, so it is safe to drop into a URL
+ * hash without percent-escaping.
+ *
+ * @param state - Any JSON-serializable value.
+ * @returns The base64url-encoded JSON.
+ */
+export declare function encodeStateToHash(state: unknown): string;
+/**
+ * Decode a hash string produced by {@link encodeStateToHash} back to its state.
+ *
+ * A leading `#` is tolerated. A malformed or empty hash yields `null` and never
+ * throws.
+ *
+ * @param hash - The encoded string, with or without a leading `#`.
+ * @returns The decoded state, or `null` when the hash is empty or invalid.
+ */
+export declare function decodeStateFromHash(hash: string): unknown;
+/** Options for {@link writeStateToUrl}. */
+export interface WriteStateOptions {
+    /**
+     * Replace the current history entry instead of pushing a new one. A replace
+     * does not create a back-button step and does not fire `hashchange`.
+     * Default: false.
+     */
+    replace?: boolean;
+}
+/**
+ * Write a state to `location.hash`. No-op when there is no DOM.
+ *
+ * @param state - Any JSON-serializable value.
+ * @param options - `replace` to overwrite the current history entry.
+ */
+export declare function writeStateToUrl(state: unknown, options?: WriteStateOptions): void;
+/**
+ * Read and decode the state from the current `location.hash`.
+ *
+ * @returns The decoded state, or `null` when there is no DOM, no hash, or the
+ * hash is invalid.
+ */
+export declare function readStateFromUrl(): unknown;
+/**
+ * Listen for `hashchange` and call `cb` with the newly decoded state.
+ *
+ * @param cb - Called with the decoded state (or `null`) on every hash change.
+ * @returns An unsubscribe function. A no-op when there is no DOM.
+ */
+export declare function onUrlStateChange(cb: (state: unknown) => void): () => void;
+/**
+ * Bind a set of explorable controls to the URL hash.
+ *
+ * Each binding exposes a stable id, a getter and a setter. On bind the current
+ * URL state is applied to the controls (so a shared link restores the view),
+ * and `save()` captures the controls back into the URL. When `listen` is on,
+ * the controls also follow back/forward navigation through `hashchange`.
+ *
+ * @param bindings - One {@link UrlStateBinding} per control.
+ * @param options - Bind-time behavior (replace, restoreOnBind, listen).
+ * @returns A {@link UrlStateController} to capture, save, restore and dispose.
+ *
+ * @example
+ * ```ts
+ * const controller = bindStateToUrl([
+ *   { id: 'p', get: () => point.getPoint(), set: (v) => point.setPoint(v as Vector3Tuple) },
+ *   { id: 's', get: () => slider.getValue(), set: (v) => slider.setValue(v as number) },
+ * ]);
+ * // after a drag:
+ * controller.save();
+ * ```
+ */
+export declare function bindStateToUrl(bindings: readonly UrlStateBinding[], options?: BindUrlStateOptions): UrlStateController;
+//# sourceMappingURL=urlState.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"urlState.d.ts","sourceRoot":"","sources":["../../src/serialization/urlState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,GAAG,EAAE,MAAM,OAAO,CAAC;IACnB,kDAAkD;IAClD,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC/B;AAED,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB;;;OAGG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,mEAAmE;IACnE,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAoDD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAWzD;AAYD,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,iBAAsB,GAAG,IAAI,CAarF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAI1C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAOzE;AAuBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,SAAS,eAAe,EAAE,EACpC,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAmBpB"}