@zanim/web 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0-beta.1 - 2026-09-20
+
+First public beta of `@zanim/web`.
+
+- Absolute-time, random-access Scene authoring and playback.
+- Canvas2D renderer with Zig/WASM kernels and shared WASM loading.
+- 2D/3D objects, vector documents, media, compositing, and Scene IR.
+- Build-time Typst/Math compilation through the Vite plugin.
+- Dynamic vector morphing and retained batch caches.
+- Correct multi-scene destruction and playback lifecycle for embedded presentations.
+
+The package is pre-1.0; API changes may occur in later 0.x releases.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zanim contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @zanim/web
+
+Browser runtime and TypeScript authoring API for Zanim.
+
+> **Release status:** `0.1.0-beta.1` is a pre-1.0 public beta. Random-access scene semantics are stable enough for real projects, but API names may still evolve in 0.x releases.
+
+## Install
+
+```bash
+npm install @zanim/web@0.1.0-beta.1
+```
+
+For build-time `Math` / `Typst` authoring, also install Vite 5+ and enable `@zanim/web/vite`. Vite is an optional peer dependency; runtime-only consumers do not need it.
+
+## Runtime
+
+- `src/core.js`: retained 2D objects, Canvas2D rendering and WASM bridge.
+- `src/scene.js`: authoring, timeline validation and scheduling.
+- `src/evaluator.js`: absolute-time evaluation.
+- `src/player.js`: playback.
+- `src/ir.js`: Scene IR import/export.
+- `src/media.js`: image/GIF/video/audio objects.
+- `src/three.js`: mesh/camera API and Web 3D layer.
+- `src/typst.js`: loads precompiled SVG/VectorDocument resources; it never embeds a Typst compiler.
+- `src/svg.js`: internal SVG-to-cubic-vector importer used by Typst.
+
+The repository no longer contains a Gallery or browser demo suite. User-facing examples are maintained in the separate tutorial repository.
+
+## State ownership
+
+Objects are ordinary declaration/layout values until `Scene.add()`. After registration, animation authoring updates `Scene.authored` and timeline clips; it does not rewrite the object's declaration state. `stateAt(object, t)` reconstructs historical state, while `authoredState(object)` exposes the current authoring head. Rendering temporarily applies sampled state and restores the raw object immediately afterward.
+
+## Math / Typst
+
+Use the Vite plugin once:
+
+```ts
+// vite.config.ts
+import { zanim } from '@zanim/web/vite';
+export default { plugins: [zanim()] };
+```
+
+Then author normally:
+
+```ts
+import { Math } from '@zanim/web';
+const formula = new Math('integral_0^1 x^2 dif x = 1/3', { fontSize: 34 });
+await formula.ready;
+```
+
+Build flow:
+
+```text
+new Math(static source)
+  → @zanim/web/vite
+  → local Typst CLI
+  → content-addressed SVG
+  → Vite production asset
+  → browser fetch
+  → VectorDocument
+```
+
+The npm runtime contains no Typst compiler/WASM and makes no font/CDN requests. Typst is required only on the developer/build machine. Resolution order is plugin `typst`, `ZANIM_TYPST`, project `.tools/typst/typst[.exe]`, then `PATH`.
+
+Formula source, `fontSize` and `color` are intentionally build-time static. Use `DynamicNumber` / `FormulaTemplate` for runtime-changing values. A dynamic formula source is a build error rather than a reason to ship a browser compiler.
+
+`configureTypstCompiler(...)` remains available for explicit development integrations. Python Preview uses it to point Web Preview at Python's `/api/typst`; production apps normally use the Vite-precompiled SVG path.
+
+## Dynamic vector morphs
+
+`prepareVectorMorph(source, target)` builds stable glyph/path correspondence between two `VectorDocument`s. `DynamicVectorObject2D` can then sample that plan from absolute time, so Typst text and other vector artwork can morph while remaining random-access rather than accumulating updater state. Matched groups interpolate cubic geometry directly; inserted/removed groups grow or shrink locally with opacity.
+
+## Multi-scene embedding
+
+`ZanimWasm.load(url)` is promise-cached per resolved URL. Pages that mount many independent `Scene` instances (for example a slide deck with several embedded Zanim views) therefore share one WebAssembly engine instead of refetching and reinstantiating the runtime for every canvas. Failed loads are evicted so a later mount can retry.
+
+## Build
+
+```bash
+cd web
+npm install
+./build.sh
+npm test
+```
+
+`build.sh` creates only `dist/zanim_web_core.wasm`. Typst SVGs belong to each consuming application and are emitted by `@zanim/web/vite` during that application's build.
+
+## Scene IR
+
+```ts
+import { Scene } from '@zanim/web';
+import { createSceneFromIR, sceneToIR } from '@zanim/web/ir';
+```
+
+Scene IR is semantic and random-access; it is not a frame dump. Runtime callbacks require explicit sampling when exported.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@zanim/web",
+  "version": "0.1.0-beta.1",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/zanim.js",
+  "types": "./src/zanim.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/zanim.d.ts",
+      "import": "./src/zanim.js"
+    },
+    "./zanim_web_core.wasm": "./dist/zanim_web_core.wasm",
+    "./ir": {
+      "types": "./src/ir.d.ts",
+      "import": "./src/ir.js"
+    },
+    "./vite": {
+      "types": "./vite.d.ts",
+      "import": "./vite.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "vite.js",
+    "vite.d.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "./build.sh",
+    "test": "node ./test.mjs && node ./rotation.test.mjs && node ./primitive-draw.test.mjs && node ./vite.test.mjs"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.29.9",
+    "magic-string": "^0.30.17"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "devDependencies": {
+    "vite": "^6.4.3"
+  },
+  "description": "Random-access browser animation runtime and TypeScript authoring API for Zanim",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zjwqsd/zanim.git",
+    "directory": "web"
+  },
+  "homepage": "https://github.com/zjwqsd/zanim#readme",
+  "bugs": {
+    "url": "https://github.com/zjwqsd/zanim/issues"
+  },
+  "keywords": [
+    "animation",
+    "graphics",
+    "canvas",
+    "wasm",
+    "typst",
+    "visualization"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  }
+}

package/src/compositing.js

@@ -0,0 +1,136 @@
+import {
+  Bounds2D,
+  Transform2D,
+  ZObject,
+  sampleValue,
+  setWorldCanvasTransform,
+} from './core.js';
+
+function finitePositive(value, name) {
+  const number = Number(value);
+  if (!(number > 0) || !Number.isFinite(number)) {
+    throw new RangeError(`${name} must be a positive finite number`);
+  }
+  return number;
+}
+
+function sceneCanvas(scene) {
+  const canvas = scene?.renderer?.canvas;
+  if (!canvas || typeof canvas.width !== 'number' || typeof canvas.height !== 'number') {
+    throw new TypeError('SceneRasterObject2D requires a renderable child Scene');
+  }
+  return canvas;
+}
+
+function transformedBounds(width, height, transform) {
+  const hx = width / 2;
+  const hy = height / 2;
+  const points = [
+    transform.apply(-hx, -hy),
+    transform.apply(hx, -hy),
+    transform.apply(hx, hy),
+    transform.apply(-hx, hy),
+  ];
+  return new Bounds2D(
+    Math.min(...points.map(point => point[0])),
+    Math.min(...points.map(point => point[1])),
+    Math.max(...points.map(point => point[0])),
+    Math.max(...points.map(point => point[1])),
+  );
+}
+
+/**
+ * Draw another Zanim Scene as one transformable object.
+ *
+ * The child Scene keeps its own renderer/canvas and timeline. The parent only
+ * samples that surface, so embedding never flattens the child into a low-res
+ * screenshot and the child can later be promoted/reused without recompiling.
+ */
+export class SceneRasterObject2D extends ZObject {
+  constructor(
+    scene,
+    {
+      width = null,
+      height = null,
+      sourceTime = 0,
+      ownsScene = false,
+      ...rest
+    } = {},
+  ) {
+    super(rest);
+    const canvas = sceneCanvas(scene);
+    const sourceWidth = Math.max(1, Number(canvas.width) || 1);
+    const sourceHeight = Math.max(1, Number(canvas.height) || 1);
+    const aspect = sourceWidth / sourceHeight;
+
+    if (width == null && height == null) {
+      width = sourceWidth / 100;
+      height = sourceHeight / 100;
+    } else if (width == null) {
+      height = finitePositive(height, 'height');
+      width = height * aspect;
+    } else if (height == null) {
+      width = finitePositive(width, 'width');
+      height = width / aspect;
+    } else {
+      width = finitePositive(width, 'width');
+      height = finitePositive(height, 'height');
+    }
+
+    this.scene = scene;
+    this.width = width;
+    this.height = height;
+    this.sourceTime = sourceTime;
+    this.ownsScene = Boolean(ownsScene);
+    this._lastSample = null;
+    this._webRuntimeOnly = 'scene-raster';
+  }
+
+  _boundsWithTransform(transform) {
+    return transformedBounds(this.width, this.height, transform);
+  }
+
+  bounds() {
+    return this._boundsWithTransform(this.transform);
+  }
+
+  sample(time) {
+    const target = Math.max(0, sampleValue(this.sourceTime, time));
+    const duration = Number(this.scene.duration) || 0;
+    const resolved = duration > 0 ? Math.min(target, duration) : target;
+    if (this._lastSample == null || Math.abs(this._lastSample - resolved) > 1e-12) {
+      this.scene.seek(resolved);
+      this._lastSample = resolved;
+    } else if (!this.scene.stats?.frames) {
+      this.scene.render();
+    }
+    return this;
+  }
+
+  draw(renderer, parent = Transform2D.identity()) {
+    const childCanvas = sceneCanvas(this.scene);
+    if (childCanvas === renderer.canvas) {
+      throw new Error('SceneRasterObject2D cannot sample from its parent render target');
+    }
+    this.sample(renderer.time ?? 0);
+
+    const ctx = renderer.ctx;
+    const transform = this.world(parent);
+    ctx.save();
+    ctx.globalAlpha *= Math.max(0, Math.min(1, this.opacity));
+    setWorldCanvasTransform(renderer, ctx, transform);
+    ctx.scale(1, -1);
+    ctx.drawImage(
+      childCanvas,
+      -this.width / 2,
+      -this.height / 2,
+      this.width,
+      this.height,
+    );
+    ctx.restore();
+  }
+
+  destroy() {
+    if (this.ownsScene) this.scene.destroy?.();
+  }
+}