@pixerate/flair 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @pixerate/flair
+
+## 0.1.0
+
+### Minor Changes
+
+- f4849b5: First public release: WebGL2 shader effects with image controls, animated vector effects, a catalog of 59 ready-made effects, and a UI-agnostic, agent-ready effect editor built on `@pixerate/editor`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack James
+
+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

@@ -1,3 +1,255 @@
-# Temporary Holding Version
+# @pixerate/flair
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <strong>Visual effects and motion graphics for the web: WebGL2 shader effects, animated vector effects, a catalog of ready-made looks, and a UI-agnostic, agent-ready effect editor.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@pixerate/flair"><img src="https://img.shields.io/npm/v/@pixerate/flair.svg?style=flat-square&color=violet" alt="npm version" /></a>
+  <a href="https://github.com/Pixerate/flair/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Pixerate/flair/ci.yml?branch=main&style=flat-square" alt="CI build status" /></a>
+  <a href="https://pixerate.github.io/flair/"><img src="https://img.shields.io/badge/demo-live-a855f7.svg?style=flat-square" alt="Live demo" /></a>
+  <a href="https://github.com/Pixerate/flair/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="MIT License" /></a>
+</p>
+
+---
+
+## 🌟 Overview
+
+Flair gives products a library of good-looking, configurable visual effects (hero backgrounds, textures, light, image treatments, transitions, loaders, animated icons and charts) and the tools to make more of them, by hand or with an agent.
+
+### Core Capabilities
+
+- 🎨 **Effect catalog (`@pixerate/flair/catalog`)**: 59 effects, each with controls and presets. There are 44 WebGL2 shaders (gradients, organic textures, patterns, light, space, retro, image effects, transitions) and 15 animated SVG effects (loaders, status icons, charts, counters). [Browse them live](https://pixerate.github.io/flair/).
+- ⚡ **Shader engine**:
+  - Shadertoy-style GLSL ES 3.00 fragment shaders, with controls declared in the source (`// @control`), including image inputs.
+  - Compile errors come back with line numbers that match the source.
+  - Live previews (`ShaderRenderer`) and many animated thumbnails on one context (`ThumbnailPool`).
+  - Frames at exact times (`ShaderFrames`), looping GIFs, and standalone HTML pages.
+- ✒️ **Vector motion (`@pixerate/flair/vector`)**: animated SVG described as data. It covers attribute tweens, draw-on strokes, motion along paths, counters and view zooms. Every frame is a pure function of time (`svgFrame`), and `SvgPlayer` plays it.
+- 🎛️ **Effect editor (`@pixerate/flair/editor`)**:
+  - A headless editor for an effect's source, values, keyframes, presets and timeline.
+  - Built on [`@pixerate/editor`](https://github.com/Pixerate/editor)'s undo history and command registry, with no UI framework assumed.
+- 🤖 **Agent-native, bring your own model**:
+  - Every editing action is a command, and the commands are exposed as MCP-shaped tools.
+  - Ships instructions for the model. The host supplies the model, keys and agent loop.
+- 🎬 **Directing and interchange**: multi-shot scenes with camera moves, procedural effects, validation and fast headless simulation. Also blend modes, Oklab colour and grading, retiming, timecode, and export to Lottie, Apple Motion, FCP7 XML and CMX 3600 EDL.
+
+---
+
+## 📦 Entry points
+
+| Import | What it provides | Runtime dependencies |
+| :--- | :--- | :--- |
+| `@pixerate/flair` | Shader engine, vector motion, time and easing, colour, blending, transitions, scenes, interchange exporters | None (browser-safe) |
+| `@pixerate/flair/catalog` | `EFFECTS`, `getEffect`, `findEffects`, `effectDefaults`, `renderVectorEffect`, GLSL helpers, sample images | None |
+| `@pixerate/flair/vector` | `SvgMotion`, `svgFrame`, `svgView`, `SvgPlayer`, `svgMotionIssues` | None |
+| `@pixerate/flair/editor` | `EffectEditor`, effect documents, keyframe tracks, renderer bindings, agent tools and instructions | `@pixerate/editor` (optional peer) |
+| `@pixerate/flair/node` | `exportMotionGraphic`: renders a shader to GIF/MP4 through headless Chrome and ffmpeg | Node.js |
+
+The `flair` CLI inspects shaders, writes standalone pages and directs scenes (see [CLI](#-cli)).
+
+---
+
+## 🏗️ Architecture
+
+```mermaid
+graph TD
+  subgraph Effects["Effects (no dependencies)"]
+    Catalog["catalog: 59 effects + presets"]
+    Shader["shader engine: controls, compile, render, GIF, HTML"]
+    Vector["vector motion: SvgMotion, SvgPlayer"]
+    Time["time: clocks, easing, keyframes, noise"]
+  end
+  subgraph Editing["Editing (@pixerate/flair/editor)"]
+    Doc["EffectDocument: source, values, tracks, presets"]
+    Editor["EffectEditor: state, playhead"]
+    Cmds["commands → MCP tools"]
+  end
+  PE["@pixerate/editor: history, commands"]
+  Host["Your app: UI (any framework) + your model"]
+
+  Catalog --> Shader
+  Catalog --> Vector
+  Doc --> Editor
+  Editor --> Cmds
+  PE --> Editor
+  PE --> Cmds
+  Editor -- bindShaderRenderer / bindSvgView --> Shader
+  Editor --> Vector
+  Host --> Editor
+  Host -- tool calls --> Cmds
+```
+
+Flair stays free of LLM SDKs and UI frameworks. Your app owns the interface and the model. Flair owns the rendering, the effect model and the tool surface.
+
+---
+
+## 🚀 Quickstart
+
+```bash
+npm install @pixerate/flair
+# For the editor:
+npm install @pixerate/flair @pixerate/editor
+```
+
+### 1. Drop in a catalog effect
+
+```ts
+import { ShaderRenderer, SvgPlayer } from "@pixerate/flair";
+import { getEffect, effectDefaults, renderVectorEffect } from "@pixerate/flair/catalog";
+
+// A shader background
+const aurora = getEffect("aurora")!;
+if (aurora.kind === "shader") {
+  const preview = new ShaderRenderer(document.querySelector("#hero")!);
+  preview.setSource(aurora.source);
+  preview.setValues(effectDefaults(aurora, { preset: "Ember", values: { uSpeed: 0.5 } }));
+}
+
+// An animated SVG loader, recoloured
+const spinner = getEffect("spinner")!;
+if (spinner.kind === "vector") {
+  new SvgPlayer(document.querySelector("#loading")!, renderVectorEffect(spinner, { accent: "#0ea5e9" }), {
+    hold: spinner.hold,
+  });
+}
+```
+
+Find effects with `findEffects({ text: "glow", category: "light", kind: "shader" })`. Each effect has an `id`, `name`, `description`, `category`, `tags` and optional `presets`. Image effects default to built-in sample pictures, so they look right before you set `uImage` to your own URL.
+
+### 2. Write your own shader
+
+```glsl
+// Controls are uniforms annotated on the same line.
+uniform vec3 uTint;    // @control color default=#77C16A label="Tint"
+uniform float uSpeed;  // @control min=0 max=4 default=1 label="Speed"
+uniform sampler2D uPhoto; // @control filter=linear wrap=clamp label="Photo"
+
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+  vec2 uv = fragCoord / iResolution.xy;
+  vec3 photo = texture(uPhoto, uv + 0.01 * sin(uv.yx * 20.0 + iTime * uSpeed)).rgb;
+  fragColor = vec4(photo * uTint, 1.0);
+}
+```
+
+```ts
+import { ShaderRenderer, ShaderFrames, recordGif, standaloneHtml, parseControls } from "@pixerate/flair";
+
+const status = renderer.setSource(source); // { ok, errors: [{ line, message }] }
+parseControls(source); // [{ name: "uTint", type: "vec3", color: true, default: [...] }, ...]
+const gif = await recordGif({ source, width: 480, height: 270, fps: 30, duration: 3 });
+const page = standaloneHtml("My effect", source, { uSpeed: 2 });
+```
+
+### 3. Build an editor (any UI)
+
+```ts
+import { createEffectEditor, bindShaderRenderer, bindSvgView } from "@pixerate/flair/editor";
+import { ShaderRenderer } from "@pixerate/flair";
+
+const editor = createEffectEditor({ from: "nebula" });
+const renderer = new ShaderRenderer(previewElement);
+bindShaderRenderer(editor, renderer); // source, values at the playhead, time; compile errors flow back
+
+editor.subscribe((state) => render(state)); // state: document, controls, values, issues, compile, time, history
+editor.setValue("uDensity", 1.4); // checked and undoable; slider drags merge into one step
+editor.setKeyframe("uSpeed", 2000, 0.2, "ease-in-out");
+editor.applyPreset("Ember");
+editor.play();
+editor.undo();
+
+// Menus, shortcuts and command palettes run the same commands by id:
+editor.commands.execute("values.randomize");
+window.addEventListener("keydown", (e) => editor.commands.handleKeyDown(e)); // Space plays/pauses
+```
+
+`getState()` returns the same object until something changes, so React's `useSyncExternalStore` works as is. Documents are plain JSON (`EffectDocument`), and keyframe tracks use `@pixerate/editor`'s keyframe shape and easing names.
+
+### 4. Let an agent drive it
+
+```ts
+import { createEffectToolProvider, toolDefinitions, callTool, EFFECT_AGENT_INSTRUCTIONS } from "@pixerate/flair/editor";
+
+const tools = createEffectToolProvider(editor, {
+  capture: () => renderer.capture({ type: "image/png" }), // adds a `view_effect` tool so the model can look
+});
+
+// Give your model EFFECT_AGENT_INSTRUCTIONS and toolDefinitions(tools), then for each tool call:
+const result = await callTool(tools, call.name, call.input); // MCP tools/call result
+
+// Or register the provider with @pixerate/editor's ToolRegistry, or bridge it to an MCP server.
+```
+
+The tools are `list_commands`, `run_command` and `run_commands`, plus `view_effect` when you can capture the preview. The commands they run:
+
+- **Inspect and start:** `effect.describe`, `catalog.search`, `effect.load`.
+- **Edit the effect:** `effect.setSource`.
+- **Values and presets:** `values.set`, `values.reset`, `values.randomize`, `preset.apply` and `preset.save`.
+- **Keyframes:** `keyframe.set`, `keyframe.remove`, `keyframe.setEasing` and `keyframe.clear`.
+- **Timeline:** `timeline.setTiming`, `timeline.play` and `timeline.seek`.
+- **History:** `history.undo` and `history.redo`.
+
+Every change is one undo step, and refusals come back as messages the model can act on.
+
+---
+
+## 🎨 The catalog
+
+| Category | Effects |
+| :--- | :--- |
+| gradient | mesh gradient, aurora, gradient flow, conic sweep, silk |
+| organic | liquid marble, smoke, lava lamp, plasma, caustics, flames, blob morph |
+| pattern | dot wave, Truchet flow, hex pulse, living cells, moiré rings, kaleidoscope, stripes |
+| light / space | bokeh, god rays, sparkles, neon ripple, warp starfield, nebula, event horizon |
+| retro | synthwave, digital rain, dithered gradient, TV static |
+| image | ripple, glitch, duotone, halftone, pixel reveal, CRT screen, film look |
+| transition | wipe, iris, block dissolve, grid wipe, glass wipe, twister, light leak, cross zoom |
+| loader / icon / data | spinner, bouncing dots, pulse ping, equalizer, progress ring, bar chart, line chart, stat counter, route, success check, error cross, heartbeat, signature, confetti |
+
+Every shader is self-contained and compiles on WebGL2. Open [`#check`](https://pixerate.github.io/flair/#check) on the demo to compile the catalog on your own GPU.
+
+---
+
+## 💻 CLI
+
+```bash
+npx flair controls ./effect.frag            # list @control uniforms (--json for JSON)
+npx flair html ./effect.frag --out page.html --open
+npx flair scene validate ./scene.json        # layout, framing and timing checks
+npx flair scene review ./scene.json          # fast headless simulation + review
+npx flair scene lottie ./scene.json out.json # also: fcp7, edl, motn
+```
+
+---
+
+## 🧪 Interactive Browser Demo
+
+The [live demo](https://pixerate.github.io/flair/) has three parts:
+
+- **Gallery:** the whole catalog, live.
+- **Editor:** controls, presets, keyframes, source and export, built with React on the headless editor.
+- **Agent tools:** the tool surface, plus a sample agent plan you can run.
+
+To run it locally:
+
+```bash
+pnpm install
+pnpm dev   # http://localhost:3100
+```
+
+---
+
+## 🛠️ Development
+
+```bash
+pnpm typecheck && pnpm build && pnpm test
+pnpm changeset   # describe consumer-facing changes; merging to main publishes them
+```
+
+See [AGENTS.md](./AGENTS.md) for the conventions contributors and coding agents follow.
+
+---
+
+## 📄 License
+
+MIT © Pixerate

package/dist/catalog/index.d.ts

@@ -0,0 +1,74 @@
+import { a as ControlDef, C as ControlValue } from '../controls-DdXMbovi.js';
+import { E as EffectDefinition, a as EffectCategory, S as ShaderEffect } from '../types-CkKkavvB.js';
+export { b as EFFECT_CATEGORIES, c as EffectPreset, V as VectorControl, d as VectorEffect, e as colorControl, n as numberControl, r as renderVectorEffect, v as vectorControlDef } from '../types-CkKkavvB.js';
+import '../motion-D0TVv2CF.js';
+
+/**
+ * Sample pictures for the catalog's image effects: small SVGs as `data:` URLs,
+ * so image controls have something to show with nothing to download.
+ */
+/** An ASCII SVG as a base64 `data:image/svg+xml` URL. */
+declare function svgDataUrl(svg: string): string;
+/** Built-in sample pictures, as image control values. */
+declare const SAMPLE_IMAGES: {
+    readonly landscape: string;
+    readonly city: string;
+    readonly portrait: string;
+};
+
+/**
+ * GLSL helpers the catalog's shaders are built from. Each effect's source
+ * inlines the helpers it uses, so a source stays self-contained: copy it into
+ * any Shadertoy-style host and it compiles.
+ */
+/** Hashes: `hash12` (vec2 → float), `hash22` (vec2 → vec2), both 0–1. */
+declare const HASH: string;
+/** Smooth value noise, 0–1 (needs {@link HASH}). */
+declare const NOISE: string;
+/** Fractal noise: `fbm(p, octaves)`, about 0–1 (needs {@link NOISE}). */
+declare const FBM: string;
+/** Inigo Quilez's cosine palette: `palette(t, a, b, c, d)`. */
+declare const PALETTE: string;
+/** Mixes colours in Oklab, so blends stay bright: `oklabMix(a, b, t)` on sRGB colours. */
+declare const OKLAB_MIX: string;
+/** 2D rotation matrix: `rot(angle)`. */
+declare const ROTATE: string;
+/** Joins helpers and a body into one source, a blank line apart. */
+declare function glsl(...parts: string[]): string;
+
+/**
+ * The effect catalog: ready-made shader and vector effects, each with
+ * controls and presets, to drop into a product or start an edit from.
+ *
+ * - Browsing: `EFFECTS`, `getEffect`, `findEffects`, `EFFECT_CATEGORIES`.
+ * - Controls: `effectControls`, `effectDefaults`.
+ * - Vector effects: `renderVectorEffect` fills in their controls.
+ *
+ * @packageDocumentation
+ */
+
+/** The catalog's shader effects. */
+declare const SHADER_EFFECTS: readonly ShaderEffect[];
+/** Every effect in the catalog, shaders first, grouped by category. */
+declare const EFFECTS: readonly EffectDefinition[];
+/** The effect with this id, or undefined. */
+declare function getEffect(id: string): EffectDefinition | undefined;
+interface EffectQuery {
+    /** Words to look for in the name, description, tags and id (all must match). */
+    text?: string;
+    category?: EffectCategory;
+    kind?: EffectDefinition["kind"];
+    /** Effects with every one of these tags. */
+    tags?: readonly string[];
+}
+/** Effects matching a query, in catalog order. */
+declare function findEffects(query?: EffectQuery): EffectDefinition[];
+/** An effect's controls: a shader's `@control` uniforms, or a vector effect's declared controls. */
+declare function effectControls(effect: EffectDefinition): ControlDef[];
+/** An effect's values: each control's default, overridden by `values` (and a preset by name, when given). */
+declare function effectDefaults(effect: EffectDefinition, options?: {
+    preset?: string;
+    values?: Record<string, ControlValue>;
+}): Record<string, ControlValue>;
+
+export { EFFECTS, EffectCategory, EffectDefinition, type EffectQuery, FBM, HASH, NOISE, OKLAB_MIX, PALETTE, ROTATE, SAMPLE_IMAGES, SHADER_EFFECTS, ShaderEffect, effectControls, effectDefaults, findEffects, getEffect, glsl, svgDataUrl };

package/dist/catalog/index.js

@@ -0,0 +1,47 @@
+import {
+  EFFECTS,
+  EFFECT_CATEGORIES,
+  FBM,
+  HASH,
+  NOISE,
+  OKLAB_MIX,
+  PALETTE,
+  ROTATE,
+  SAMPLE_IMAGES,
+  SHADER_EFFECTS,
+  colorControl,
+  effectControls,
+  effectDefaults,
+  findEffects,
+  getEffect,
+  glsl,
+  numberControl,
+  renderVectorEffect,
+  svgDataUrl,
+  vectorControlDef
+} from "../chunk-MWVTQFV5.js";
+import "../chunk-EHDJ3CPJ.js";
+import "../chunk-J55UBNAT.js";
+export {
+  EFFECTS,
+  EFFECT_CATEGORIES,
+  FBM,
+  HASH,
+  NOISE,
+  OKLAB_MIX,
+  PALETTE,
+  ROTATE,
+  SAMPLE_IMAGES,
+  SHADER_EFFECTS,
+  colorControl,
+  effectControls,
+  effectDefaults,
+  findEffects,
+  getEffect,
+  glsl,
+  numberControl,
+  renderVectorEffect,
+  svgDataUrl,
+  vectorControlDef
+};
+//# sourceMappingURL=index.js.map

package/dist/catalog/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-36DTNSHU.js

@@ -0,0 +1,160 @@
+// src/scene/types.ts
+function isElementCommand(cmd) {
+  return cmd.type === "element" && "element" in cmd && !!cmd.element;
+}
+function isUpdateCommand(cmd) {
+  return cmd.type === "update" && "id" in cmd && typeof cmd.id === "string";
+}
+function isDeleteCommand(cmd) {
+  return cmd.type === "delete" && "id" in cmd && typeof cmd.id === "string";
+}
+
+// src/scene/geometry.ts
+function boundsOf(e) {
+  if (e.points?.length) {
+    const xs = e.points.map((p) => e.x + p[0]);
+    const ys = e.points.map((p) => e.y + p[1]);
+    const x = Math.min(...xs);
+    const y = Math.min(...ys);
+    return {
+      x,
+      y,
+      width: Math.max(1, Math.max(...xs) - x),
+      height: Math.max(1, Math.max(...ys) - y)
+    };
+  }
+  return { x: e.x, y: e.y, width: Math.max(1, e.width), height: Math.max(1, e.height) };
+}
+function overlapArea(a, b) {
+  const w = Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x);
+  const h = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y);
+  return w > 0 && h > 0 ? w * h : 0;
+}
+var areaOf = (r) => r.width * r.height;
+
+// src/scene/camera.ts
+var DEFAULT_STAGE = {
+  width: 1920,
+  height: 1080,
+  caption: 0
+};
+var CAMERA_MS = 600;
+var boardHeight = (stage) => stage.height - (stage.caption ?? 0);
+function viewAt(cx, cy, zoom, stage) {
+  return {
+    zoom,
+    scrollX: stage.width / (2 * zoom) - cx,
+    scrollY: boardHeight(stage) / (2 * zoom) - cy
+  };
+}
+function centreOf(view, stage) {
+  return [
+    stage.width / (2 * view.zoom) - view.scrollX,
+    boardHeight(stage) / (2 * view.zoom) - view.scrollY
+  ];
+}
+function frame(rect, stage) {
+  if (!(rect.width > 0 && rect.height > 0)) {
+    throw new Error("A camera rectangle needs a positive width and height");
+  }
+  const zoom = Math.min(stage.width / rect.width, boardHeight(stage) / rect.height);
+  return viewAt(rect.x + rect.width / 2, rect.y + rect.height / 2, zoom, stage);
+}
+function calculateFramingRect(elements, stage, options = {}) {
+  const activeElements = elements.filter((e) => !e.isDeleted);
+  const targetH = boardHeight(stage);
+  const stageAspect = stage.width / Math.max(1, targetH);
+  if (activeElements.length === 0) {
+    return {
+      x: 0,
+      y: 0,
+      width: stage.width,
+      height: targetH
+    };
+  }
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const el of activeElements) {
+    const b = boundsOf(el);
+    if (b.x < minX) minX = b.x;
+    if (b.y < minY) minY = b.y;
+    if (b.x + b.width > maxX) maxX = b.x + b.width;
+    if (b.y + b.height > maxY) maxY = b.y + b.height;
+  }
+  let width = maxX - minX;
+  let height = maxY - minY;
+  const padding = options.padding ?? 0.15;
+  if (padding > 0) {
+    const padX = width * padding;
+    const padY = height * padding;
+    minX -= padX;
+    minY -= padY;
+    width += padX * 2;
+    height += padY * 2;
+  }
+  if (options.minWidth && width < options.minWidth) {
+    const diff = options.minWidth - width;
+    minX -= diff / 2;
+    width = options.minWidth;
+  }
+  if (options.minHeight && height < options.minHeight) {
+    const diff = options.minHeight - height;
+    minY -= diff / 2;
+    height = options.minHeight;
+  }
+  const currentAspect = width / Math.max(1, height);
+  if (currentAspect < stageAspect) {
+    const targetWidth = height * stageAspect;
+    const diff = targetWidth - width;
+    minX -= diff / 2;
+    width = targetWidth;
+  } else if (currentAspect > stageAspect) {
+    const targetHeight = width / stageAspect;
+    const diff = targetHeight - height;
+    minY -= diff / 2;
+    height = targetHeight;
+  }
+  return {
+    x: minX,
+    y: minY,
+    width,
+    height
+  };
+}
+function between(from, to, t, stage) {
+  const [x0, y0] = centreOf(from, stage);
+  const [x1, y1] = centreOf(to, stage);
+  const zoom = from.zoom * Math.pow(to.zoom / from.zoom, t);
+  return viewAt(x0 + (x1 - x0) * t, y0 + (y1 - y0) * t, zoom, stage);
+}
+function visibleRect(view, stage) {
+  return {
+    x: -view.scrollX,
+    y: -view.scrollY,
+    width: stage.width / view.zoom,
+    height: boardHeight(stage) / view.zoom
+  };
+}
+var easeInOutCubic = (t) => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+
+export {
+  isElementCommand,
+  isUpdateCommand,
+  isDeleteCommand,
+  boundsOf,
+  overlapArea,
+  areaOf,
+  DEFAULT_STAGE,
+  CAMERA_MS,
+  boardHeight,
+  viewAt,
+  centreOf,
+  frame,
+  calculateFramingRect,
+  between,
+  visibleRect,
+  easeInOutCubic
+};
+//# sourceMappingURL=chunk-36DTNSHU.js.map

package/dist/chunk-36DTNSHU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/scene/types.ts","../src/scene/geometry.ts","../src/scene/camera.ts"],"sourcesContent":["import type { Rect, SceneElement } from './geometry.js';\nimport type { Stage } from './camera.js';\nimport type { Effect } from './effects.js';\nimport type { Behavior } from './behavior.js';\nimport type { SceneRig } from './rig.js';\n\n/** Shader or external visual stream in the scene. */\nexport interface SceneMedia {\n  type: 'shader' | string;\n  source?: string;\n  values?: Record<string, unknown>;\n  [field: string]: unknown;\n}\n\nexport interface ElementCommand {\n  type: 'element';\n  element: SceneElement;\n}\n\nexport interface UpdateCommand {\n  type: 'update';\n  id: string;\n  props: Partial<SceneElement>;\n}\n\nexport interface DeleteCommand {\n  type: 'delete';\n  id: string;\n}\n\nexport interface ClearCommand {\n  type: 'clear';\n}\n\nexport interface CustomCommand {\n  type: string;\n  [key: string]: unknown;\n}\n\n/** A command to add, move, or style elements in a shot. */\nexport type SceneCommand =\n  | ElementCommand\n  | UpdateCommand\n  | DeleteCommand\n  | ClearCommand\n  | CustomCommand;\n\nexport function isElementCommand(cmd: SceneCommand): cmd is ElementCommand {\n  return cmd.type === 'element' && 'element' in cmd && !!cmd.element;\n}\n\nexport function isUpdateCommand(cmd: SceneCommand): cmd is UpdateCommand {\n  return cmd.type === 'update' && 'id' in cmd && typeof cmd.id === 'string';\n}\n\nexport function isDeleteCommand(cmd: SceneCommand): cmd is DeleteCommand {\n  return cmd.type === 'delete' && 'id' in cmd && typeof cmd.id === 'string';\n}\n\nexport interface DynamicFraming {\n  /** Element IDs to frame. */\n  frame: string[];\n  /** Proportional padding (default 0.15 for 15%). */\n  padding?: number;\n  /** Minimum width in scene units. */\n  minWidth?: number;\n  /** Minimum height in scene units. */\n  minHeight?: number;\n}\n\nexport type ShotCamera = Rect | DynamicFraming;\n\n/** One beat of a scene: camera framing, title, narration/caption, commands, and procedural effects. */\nexport interface Shot {\n  /** Narration / caption spoken or displayed during this beat. */\n  caption?: string;\n  /** High-level title or callout displayed on screen. */\n  title?: string;\n  /** Camera framing box in scene units, or dynamic auto-framing target. */\n  camera?: ShotCamera;\n  /** Pause/dwell duration after this shot's actions run (in milliseconds). Default: 800ms. */\n  hold?: number;\n  /** Drawing or state change commands played during this shot. */\n  run?: SceneCommand[];\n  /** Procedural visual effects started in this shot. */\n  effects?: Effect[];\n  /** IDs of active effects to stop/fade at the start of this shot. */\n  stopEffects?: string[];\n  /** Continuous procedural parameter and physics behaviors played during this shot. */\n  behaviors?: Behavior[];\n}\n\n/** Complete animated scene specification. */\nexport interface Scene {\n  name: string;\n  title?: string;\n  description?: string;\n  stage?: Partial<Stage>;\n  /** Embedded media (e.g. bespoke WebGL fragment shaders). */\n  media?: Record<string, SceneMedia>;\n  /** Target duration [minSeconds, maxSeconds]. */\n  target?: [number, number];\n  /** Interactive macro rigs binding high-level controls to uniforms or element properties. */\n  rig?: SceneRig;\n  shots: Shot[];\n}\n","export type Point = [number, number];\n\nexport interface Rect {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\n/** An element placed or animated in a scene. */\nexport interface SceneElement {\n  id: string;\n  type: string;\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n  points?: readonly (readonly [number, number])[];\n  fontSize?: number;\n  text?: string;\n  containerId?: string | null;\n  isDeleted?: boolean;\n  opacity?: number;\n}\n\n/** Bounds in scene units, ignoring rotation. */\nexport function boundsOf(e: SceneElement): Rect {\n  if (e.points?.length) {\n    const xs = e.points.map((p) => e.x + p[0]);\n    const ys = e.points.map((p) => e.y + p[1]);\n    const x = Math.min(...xs);\n    const y = Math.min(...ys);\n    return {\n      x,\n      y,\n      width: Math.max(1, Math.max(...xs) - x),\n      height: Math.max(1, Math.max(...ys) - y),\n    };\n  }\n  return { x: e.x, y: e.y, width: Math.max(1, e.width), height: Math.max(1, e.height) };\n}\n\n/** Area of the overlap of two rectangles (0 when they do not meet). */\nexport function overlapArea(a: Rect, b: Rect): number {\n  const w = Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x);\n  const h = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y);\n  return w > 0 && h > 0 ? w * h : 0;\n}\n\nexport const areaOf = (r: Rect): number => r.width * r.height;\n","import { type Rect, type SceneElement, boundsOf } from './geometry.js';\n\nexport interface Stage {\n  width: number;\n  height: number;\n  caption?: number;\n}\n\nexport const DEFAULT_STAGE: Stage = {\n  width: 1920,\n  height: 1080,\n  caption: 0,\n};\n\nexport const CAMERA_MS = 600;\n\n/** Camera view into the scene: drawn at (point + scroll) × zoom. */\nexport interface View {\n  zoom: number;\n  scrollX: number;\n  scrollY: number;\n}\n\nexport const boardHeight = (stage: Stage): number => stage.height - (stage.caption ?? 0);\n\n/** View with `(cx, cy)` in the middle of the board at `zoom`. */\nexport function viewAt(cx: number, cy: number, zoom: number, stage: Stage): View {\n  return {\n    zoom,\n    scrollX: stage.width / (2 * zoom) - cx,\n    scrollY: boardHeight(stage) / (2 * zoom) - cy,\n  };\n}\n\n/** Scene point in the middle of the board. */\nexport function centreOf(view: View, stage: Stage): [number, number] {\n  return [\n    stage.width / (2 * view.zoom) - view.scrollX,\n    boardHeight(stage) / (2 * view.zoom) - view.scrollY,\n  ];\n}\n\n/** The view that fits `rect` on the board, centred and with its aspect kept. */\nexport function frame(rect: Rect, stage: Stage): View {\n  if (!(rect.width > 0 && rect.height > 0)) {\n    throw new Error('A camera rectangle needs a positive width and height');\n  }\n  const zoom = Math.min(stage.width / rect.width, boardHeight(stage) / rect.height);\n  return viewAt(rect.x + rect.width / 2, rect.y + rect.height / 2, zoom, stage);\n}\n\nexport interface FramingOptions {\n  /** Proportional padding added to all sides (e.g., 0.15 for 15%). Default: 0.15 */\n  padding?: number;\n  /** Minimum width in scene units. */\n  minWidth?: number;\n  /** Minimum height in scene units. */\n  minHeight?: number;\n}\n\n/**\n * Calculates a camera framing rectangle that encloses target elements\n * while preserving the stage aspect ratio and applying optional margin padding.\n */\nexport function calculateFramingRect(\n  elements: readonly SceneElement[],\n  stage: Stage,\n  options: FramingOptions = {},\n): Rect {\n  const activeElements = elements.filter((e) => !e.isDeleted);\n  const targetH = boardHeight(stage);\n  const stageAspect = stage.width / Math.max(1, targetH);\n\n  if (activeElements.length === 0) {\n    return {\n      x: 0,\n      y: 0,\n      width: stage.width,\n      height: targetH,\n    };\n  }\n\n  let minX = Infinity;\n  let minY = Infinity;\n  let maxX = -Infinity;\n  let maxY = -Infinity;\n\n  for (const el of activeElements) {\n    const b = boundsOf(el);\n    if (b.x < minX) minX = b.x;\n    if (b.y < minY) minY = b.y;\n    if (b.x + b.width > maxX) maxX = b.x + b.width;\n    if (b.y + b.height > maxY) maxY = b.y + b.height;\n  }\n\n  let width = maxX - minX;\n  let height = maxY - minY;\n\n  // Apply padding (default 15%)\n  const padding = options.padding ?? 0.15;\n  if (padding > 0) {\n    const padX = width * padding;\n    const padY = height * padding;\n    minX -= padX;\n    minY -= padY;\n    width += padX * 2;\n    height += padY * 2;\n  }\n\n  // Apply min dimensions\n  if (options.minWidth && width < options.minWidth) {\n    const diff = options.minWidth - width;\n    minX -= diff / 2;\n    width = options.minWidth;\n  }\n  if (options.minHeight && height < options.minHeight) {\n    const diff = options.minHeight - height;\n    minY -= diff / 2;\n    height = options.minHeight;\n  }\n\n  // Preserve stage aspect ratio centered around midpoint\n  const currentAspect = width / Math.max(1, height);\n  if (currentAspect < stageAspect) {\n    // Taller than stage: expand width\n    const targetWidth = height * stageAspect;\n    const diff = targetWidth - width;\n    minX -= diff / 2;\n    width = targetWidth;\n  } else if (currentAspect > stageAspect) {\n    // Wider than stage: expand height\n    const targetHeight = width / stageAspect;\n    const diff = targetHeight - height;\n    minY -= diff / 2;\n    height = targetHeight;\n  }\n\n  return {\n    x: minX,\n    y: minY,\n    width,\n    height,\n  };\n}\n\n/**\n * The view part-way (`t` from 0 to 1) from one view to another.\n * Centre moves linearly and zoom scales exponentially for smooth motion.\n */\nexport function between(from: View, to: View, t: number, stage: Stage): View {\n  const [x0, y0] = centreOf(from, stage);\n  const [x1, y1] = centreOf(to, stage);\n  const zoom = from.zoom * Math.pow(to.zoom / from.zoom, t);\n  return viewAt(x0 + (x1 - x0) * t, y0 + (y1 - y0) * t, zoom, stage);\n}\n\n/** The part of the scene the camera currently shows. */\nexport function visibleRect(view: View, stage: Stage): Rect {\n  return {\n    x: -view.scrollX,\n    y: -view.scrollY,\n    width: stage.width / view.zoom,\n    height: boardHeight(stage) / view.zoom,\n  };\n}\n\n/** Smooth cubic ease in / ease out. */\nexport const easeInOutCubic = (t: number): number =>\n  t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;\n"],"mappings":"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","names":[]}