retiam 1.0.1 → 1.0.3

package/readme.md

@@ -12,20 +12,60 @@ Retiam is a TypeScript animation engine built on WebGPU. Write scenes for mathem
 - **Rendering:** combine 2D paths, 3D meshes, lighting, shadows, compute effects, and post-processing.
 - **Specialized libraries:** add charts, graphs, physics, procedural shapes, sketch styling, and emphasis animations through separate imports.
 - **Audio and output:** work with audio, narration, and subtitles; inspect snapshots, render video, or share scenes as web components.
+- **Retiam Studio:** edit scenes alongside a live preview, tune supported values with inspectors, and control playback from your generated project.
 
 ## Getting started
 
-The project generator creates a TypeScript application, installs its dependencies,
-and opens Retiam Studio with a **Write** animation of “Retiam”:
+| Method | Use it for | Result |
+| --- | --- | --- |
+| [npm project and Studio](#create-a-project-with-studio) | Author and preview TypeScript scenes, then render video | Source project, MP4 and snapshots |
+| [CDN modules](#use-retiam-from-a-cdn) | Add a live scene directly to a browser page | Interactive WebGPU canvas |
+| [Embedded export](#export-an-independent-web-embed) | Share a finished animation on another website | Hosted web component and bundled assets |
+
+### Create a project with Studio
+
+Use Node.js 20.19 or newer and a WebGPU-capable browser. The project generator
+creates a TypeScript application, installs its dependencies, and opens Retiam
+Studio with a **Write** animation of “Retiam”:
 
 ```bash
-npx create-retiam my-animation
+npx create-retiam@latest my-animation
+```
+
+The generated project declares
+`"retiam": "latest"`. Its initial install uses npm's `latest` engine release;
+the package manager's lockfile records the resolved version for later installs.
+
+The editor opens below the preview. Drag the divider to resize it, or use the
+layout control to dock it on the left or right. Studio remembers your choice.
+Single-scene projects show the preview and editor; scene navigation and search
+appear when more scenes are added and the page reloads.
+
+Press Ctrl+C to stop the server. To reopen Studio:
+
+```bash
+cd my-animation
+npm run dev
 ```
 
-Run `npm run dev` inside the generated project to reopen Studio. Use `--no-start`
-to install without launching or `--no-install` to generate files only. The
-[`create-retiam` package](packages/create-retiam/README.md) is released separately
-from the engine; see its maintainer instructions for packaging and publication.
+Edit `src/scenes/Retiam.ts` in your editor or Studio. The generated project also
+includes `config.js` for CLI rendering, `studio/` for the local editor, and the
+Vite and TypeScript configuration. In Studio, **Run** or **Ctrl/Command+Enter**
+applies and saves edits. Add default-exported Scene classes under `src/scenes/`
+to make them available in the scene browser after reloading.
+
+| Generator option | Behavior |
+| --- | --- |
+| `--no-start` | Install dependencies without starting Studio |
+| `--no-install` | Generate files without installing or starting |
+| `--no-open` | Start the server without opening a browser |
+| `--title "Hello"` | Change the starter animation text |
+| `--pm npm\|pnpm\|yarn\|bun` | Choose the package manager |
+
+The [`create-retiam` package](packages/create-retiam/README.md)
+is released separately from the engine. Publish the engine version required by
+its starter before publishing the generator. Generator updates apply to new
+projects; existing projects keep their own Studio and configuration files.
 
 ### Manual setup
 
@@ -33,7 +73,7 @@ Install Retiam in your own TypeScript application:
 
 ```bash
 npm install retiam
-npm install --save-dev typescript vite @webgpu/types
+npm install --save-dev typescript "vite@^6.1.1" @webgpu/types
 ```
 
 Follow the [installation guide](https://abhilasbiswas.github.io/retiam-docs/installation/) for the complete project structure, TypeScript configuration, and browser entry point. To use an unpublished checkout, run `npm pack` in this repository and install the generated `.tgz` file in your application.
@@ -93,21 +133,259 @@ window.addEventListener("pagehide", () => scene.destroy(), { once: true });
 
 The host page needs a `<canvas id="canvas"></canvas>` with an explicit CSS display size. Continue with [your first scene](https://abhilasbiswas.github.io/retiam-docs/first-scene/) for animation, camera, and lifecycle guidance.
 
+## Use Retiam from a CDN
+
+Import Retiam directly in a browser page. The published module is available at
+**[jsDelivr](https://cdn.jsdelivr.net/npm/retiam@latest/dist/retiam.es.min.js)**.
+This example loads the core and charts entries through the latest release tag:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Retiam CDN animation</title>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      canvas { display: block; width: 100%; height: 100%; }
+    </style>
+    <script type="importmap">
+      {
+        "imports": {
+          "retiam": "https://cdn.jsdelivr.net/npm/retiam@latest/dist/retiam.es.min.js",
+          "retiam/charts": "https://cdn.jsdelivr.net/npm/retiam@latest/dist/libs/charts/index.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <canvas id="canvas"></canvas>
+    <script type="module">
+      import { Scene, Circle, Create, CameraModel, hex } from 'retiam';
+
+      class BrowserScene extends Scene {
+        async run() {
+          this.clearColor(hex('#080C14'));
+          this.camera.model = CameraModel.ORTHOGRAPHIC;
+          this.camera.orthoScale = 12;
+          this.camera.position.set([0, 0, 20]);
+          this.camera.lookAt([0, 0, 0]);
+          const circle = new Circle(1, { fill: hex('#38BDF8') });
+          this.add(circle);
+          await this.play(new Create(circle, { duration: 1200 }));
+          await this.wait(1000);
+        }
+      }
+
+      const scene = new BrowserScene();
+      scene.start(document.querySelector('#canvas')).catch(console.error);
+      window.addEventListener('pagehide', () => scene.destroy(), { once: true });
+    </script>
+  </body>
+</html>
+```
+
+Serve the page over HTTPS or localhost, with a WebGPU-capable browser. No Retiam
+npm installation is needed for this page. Add import-map entries for any other
+sublibraries you use, such as `retiam/shapes`, with the same release tag. jsDelivr
+serves the module's related chunks, fonts, workers and WASM assets. A CDN page
+runs the animation live; the [npm CLI workflow](#cli-and-video-rendering) produces
+video and snapshots.
+
+## Export an independent web embed
+
+Bundle a finished scene into a custom element for a blog, documentation page or
+another application. The exported files include the engine code and emitted
+assets needed by that scene. The receiving site needs WebGPU and those files.
+
+This recipe uses Vite 6, matching the generated project's toolchain. For a
+generated npm project, save the following as `src/embed.ts`. Each element
+owns its canvas and Scene, handles resizing, and cleans up when removed.
+
+<details>
+<summary>src/embed.ts</summary>
+
+```typescript
+import MyScene from './scenes/Retiam';
+
+// A separate name lets this bundle coexist with other scene components.
+class MyRetiamSceneElement extends HTMLElement {
+  private cleanup?: () => void;
+
+  connectedCallback() {
+    this.cleanup?.();
+    const canvas = document.createElement('canvas');
+    canvas.style.cssText = 'display:block;width:100%;height:100%';
+    this.replaceChildren(canvas);
+    const scene = new MyScene();
+    let cancelled = false, started = false, resizeFrame = 0;
+    let observer: ResizeObserver | undefined;
+
+    this.cleanup = () => {
+      cancelled = true;
+      observer?.disconnect();
+      cancelAnimationFrame(resizeFrame);
+      if (started) scene.destroy();
+      // A pending initialization cleans up in its continuation below.
+    };
+    void scene.start(canvas).then(() => {
+      started = true;
+      if (cancelled) { scene.destroy(); return; }
+      observer = new ResizeObserver(() => {
+        cancelAnimationFrame(resizeFrame);
+        resizeFrame = requestAnimationFrame(() => {
+          // Current composer resizing listens to the window resize event.
+          window.dispatchEvent(new Event('resize'));
+        });
+      });
+      observer.observe(this);
+      this.dispatchEvent(new CustomEvent('scene-ready', { bubbles: true }));
+    }).catch(error => {
+      scene.destroy();
+      if (!cancelled) {
+        const message = document.createElement('p');
+        message.setAttribute('role', 'alert');
+        message.textContent = String(error);
+        this.replaceChildren(message);
+      }
+    });
+  }
+
+  disconnectedCallback() {
+    this.cleanup?.();
+    this.cleanup = undefined;
+  }
+}
+
+if (!customElements.get('my-retiam-scene')) {
+  customElements.define('my-retiam-scene', MyRetiamSceneElement);
+}
+```
+
+</details>
+
+For a manual project, change the scene import to your scene module. The
+[npm embed recipe](https://abhilasbiswas.github.io/retiam-docs/export/#embed-from-npm)
+explains lifecycle handling, multiple instances and hosting.
+
+Save this as `vite.embed.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  base: './',
+  build: {
+    target: 'es2022',
+    outDir: 'outputs/embed',
+    lib: {
+      entry: 'src/embed.ts',
+      formats: ['es'],
+      fileName: 'my-scene',
+    },
+  },
+});
+```
+
+Build the component:
+
+```bash
+npx vite build --config vite.embed.config.ts
+```
+
+Copy the **whole** `outputs/embed` folder to your website, for example under
+`/embeds/my-scene/`, then mount the custom element:
+
+```html
+<script type="module" src="/embeds/my-scene/my-scene.js"></script>
+<my-retiam-scene style="display:block;width:100%;height:540px"></my-retiam-scene>
+```
+
+The receiving site needs no npm installation or separate Retiam CDN import.
+Preserve emitted files and their relative paths. Assets or services explicitly
+referenced by remote URLs still need hosting. Use a distinct custom-element name
+for each different scene bundle. An MP4 is the alternative when the receiving
+page only needs video playback.
+
+The engine repository also provides an export CLI:
+
+```bash
+npx retiam export scenes/MyScene.ts outputs/embed
+```
+
+Its current implementation expects the engine repository's `src/engine` layout.
+Use the package-based Vite recipe above for generated and other external npm
+projects. See [repository export](https://abhilasbiswas.github.io/retiam-docs/export/#standalone-embeds)
+for the CLI's script and `<retiam-scene>` usage.
+
 ## CLI and video rendering
 
-Use the CLI to analyze scenes, capture PNG snapshots, and render video:
+Run these commands from the generated project folder containing `package.json`
+and `config.js`:
 
 ```bash
-npx retiam lint scenes/FirstScene.ts --json
-npx retiam snapshot scenes/FirstScene.ts --times 1.0,2.5,4.0 --json
-npx retiam render scenes/FirstScene.ts -w 1920 -h 1080 -f 60 -d 4000 -o outputs/video
+npx retiam lint src/scenes/Retiam.ts --json
+npx retiam snapshot src/scenes/Retiam.ts --times 1.0,2.5,4.0 --json
+npx retiam render src/scenes/Retiam.ts
 ```
 
-Puppeteer is a required production dependency of Retiam starting with version 1.0.1 and is installed automatically with the package. Render and snapshot commands need a working Chrome/WebGPU setup. Video rendering also requires FFmpeg on your `PATH`.
+Puppeteer is a required production dependency of Retiam and is installed automatically with the package. Render and snapshot commands need a working Chrome/WebGPU setup. Video rendering also requires FFmpeg on your `PATH`.
 
-Projects made with `create-retiam` include a commented `config.js` containing all CLI and engine render defaults. `npx retiam render` reads it from the calling project; `retiam.config.js` takes priority when present, and CLI flags override file settings. Settings include video output, anti-aliasing, transparency, shadows, shading, raytracing, and denoising.
+### Render configuration
 
-For rendering and snapshots, your project must include an `index.html` host that loads the scene selected by the CLI's `file` query parameter. Use the host from the [installation guide](https://abhilasbiswas.github.io/retiam-docs/installation/#create-a-consumer-application). Render duration (`-d`) is in milliseconds; output (`-o`) is a directory.
+The generated [config.js](packages/create-retiam/starter/config.js) contains CLI
+output and renderer quality settings with their defaults and comments. The default output
+is 1920×1080 at 60 fps, MP4 at `20M`, in `outputs/video`. `maxDuration: 0` renders
+until the scene finishes; set a limit for scenes that loop indefinitely.
+
+For a smaller draft, edit the output fields in `config.js`:
+
+```javascript
+export default {
+  width: 1280,
+  height: 720,
+  fps: 30,
+  videoBitrate: '8M',
+  outputFormat: 'mp4',
+  outputDir: './outputs/video',
+  maxDuration: 4000, // milliseconds
+};
+```
+
+The renderer starts with built-in defaults, loads `config.js` from the calling
+project, then applies CLI flags. If `retiam.config.js` exists, it is used instead
+of `config.js`. For example, this renders at 60 fps while retaining the other
+file settings:
+
+```bash
+npx retiam render src/scenes/Retiam.ts -f 60
+```
+
+The complete file also covers anti-aliasing, transparency layers, shadows,
+culling, raytracing, denoising, local server ports, and input replay.
+See the [configuration reference](https://abhilasbiswas.github.io/retiam-docs/export/#render-configuration).
+
+Choose surface appearance in scene code and materials:
+
+```typescript
+import { CelShading, GoochShading } from 'retiam';
+
+this.shading = new CelShading({ bands: 3 }); // Scene default
+sphere.material.shading = new GoochShading({ warm: 0.6, cool: 0.4 });
+```
+
+Each shading model supplies its own WGSL. Numeric parameters update through the
+material buffer without recompiling shaders. These styles apply to rasterized
+3D models; raytracing uses its own physically based lighting.
+
+For the manual setup above, use `scenes/FirstScene.ts` as the scene path. Rendering
+and snapshots serve the project's `index.html`; a host that supports selecting
+different scenes must load the CLI's `file` query parameter. The
+[manual installation guide](https://abhilasbiswas.github.io/retiam-docs/installation/#create-a-consumer-application)
+includes that bootstrap. Render duration (`-d`) is in milliseconds, snapshot
+times are in seconds, and output (`-o`) is a directory. Render filenames include
+a timestamp.
 
 See [rendering and export](https://abhilasbiswas.github.io/retiam-docs/export/) for project setup and encoding options, or follow [package-based embeds](https://abhilasbiswas.github.io/retiam-docs/export/#embed-from-npm) to bundle a scene for another website. Run `npx retiam help` for the command reference.
 
@@ -126,10 +404,14 @@ Import shared scene primitives from `retiam` and specialized functionality from
 | `retiam/rough` | RoughJS styling integration |
 | `retiam/tts` | Microsoft Edge speech synthesis, narration, and subtitles |
 
-See the [library guide](https://abhilasbiswas.github.io/retiam-docs/libraries/) for import boundaries and examples. Starting with Retiam 1.0.1, `roughjs` is a required production dependency and is installed automatically.
+See the [library guide](https://abhilasbiswas.github.io/retiam-docs/libraries/) for import boundaries and examples. `roughjs` is a required production dependency and is installed automatically.
 
 Built-in fonts and imported engine assets are included in the library package. Application media is managed separately. Edge speech synthesis in the browser requires a compatible service. See [asset workflows](https://abhilasbiswas.github.io/retiam-docs/asset-workflows/) and [speech and subtitles](https://abhilasbiswas.github.io/retiam-docs/speech-subtitles/) for setup.
 
+MSDF font generation runs in a browser worker using the WASM supplied by
+`@zappar/msdf-generator`, a production dependency. The repository's font-baking
+tools, including `msdf-bmfont-xml` and `msdf-atlas-gen`, remain development tools.
+
 ## Repository development
 
 Use Node.js 24, matching the documentation CI configuration.