@shotstack/shotstack-studio 2.0.0-beta.34 → 2.0.0-beta.36

package/package.json

@@ -5,7 +5,7 @@
 		"cpuccino",
 		"dazzatron"
 	],
-	"version": "2.0.0-beta.34",
+	"version": "2.0.0-beta.36",
 	"description": "A video editing library for creating and editing videos with Shotstack",
 	"type": "module",
 	"main": "dist/shotstack-studio.umd.js",
@@ -46,6 +46,9 @@
 		"ffmpeg"
 	],
 	"license": "PolyForm Shield License 1.0.0",
+	"engines": {
+		"node": ">=22 <23"
+	},
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/shotstack/shotstack-studio-sdk"
@@ -56,7 +59,7 @@
 		"start": "npm run build && vite preview",
 		"build": "npm run build:main && npm run build:internal && npm run build:schema",
 		"build:main": "vite build",
-		"build:internal": "vite build --config vite.config.internal.ts",
+		"build:internal": "node scripts/build-internal.mjs",
 		"build:schema": "vite build --config vite.config.schema.ts",
 		"test": "jest",
 		"test:watch": "jest --watch",
@@ -65,7 +68,9 @@
 		"lint": "eslint --ignore-path .gitignore .",
 		"lint:fix": "eslint --ignore-path .gitignore --fix .",
 		"format": "prettier --ignore-path .gitignore --write .",
-		"prepublishOnly": "npm run build && npm run test && npm run test:package",
+		"verify:ci": "npm run lint && npm run typecheck && npm run test && npm run build && npm run test:package",
+		"release:check": "npm run verify:ci && npm pack --dry-run --json",
+		"prepublishOnly": "npm run release:check",
 		"generate:fonts": "npx tsx scripts/fetch-google-fonts.ts"
 	},
 	"devDependencies": {
@@ -91,7 +96,7 @@
 	},
 	"dependencies": {
 		"@huggingface/transformers": "^3.0.0",
-		"@shotstack/schemas": "1.5.6",
+		"@shotstack/schemas": "1.6.0",
 		"@shotstack/shotstack-canvas": "^1.9.6",
 		"fast-deep-equal": "^3.1.3",
 		"howler": "^2.2.4",

package/readme.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/badge/license-PolyForm_Shield-blue.svg)](https://polyformproject.org/licenses/shield/1.0.0/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
 
-A JavaScript library for creating and editing videos in the browser.
+A JavaScript SDK for browser-based video editing with timeline, canvas preview, and export.
 
 ## Interactive Examples
 
@@ -18,11 +18,11 @@ Try Shotstack Studio in your preferred framework:
 
 ## Features
 
-- Create video compositions with multiple tracks and clips
-- Visual timeline interface
-- Multi-track, drag-and-drop clip manipulation with snap-to-grid
-- Use in conjunction with the [Shotstack Edit API](https://shotstack.io/docs/guide/getting-started/hello-world-using-curl/) to render video
-- Export to video via the browser
+- Template-driven editing with undo/redo command model
+- Canvas preview rendering
+- Visual timeline with drag, resize, selection, and snapping
+- Extensible UI via `UIController` button API
+- Browser export pipeline via `VideoExporter`
 
 ## Installation
 
@@ -37,33 +37,57 @@ yarn add @shotstack/shotstack-studio
 ## Quick Start
 
 ```typescript
-import { Edit, Canvas, Controls, Timeline } from "@shotstack/shotstack-studio";
+import { Edit, Canvas, Controls, Timeline, UIController } from "@shotstack/shotstack-studio";
 
-// 1. Load a template
+// 1) Load a template
 const response = await fetch("https://shotstack-assets.s3.amazonaws.com/templates/hello-world/hello.json");
 const template = await response.json();
 
-// 2. Create Edit from template and load it
+// 2) Create core components
 const edit = new Edit(template);
+const canvas = new Canvas(edit);
+const ui = UIController.create(edit, canvas);
+
+// 3) Load runtime
+await canvas.load();
 await edit.load();
 
-// 3. Create a canvas to display the edit
-const canvas = new Canvas(edit);
-await canvas.load(); // Renders to [data-shotstack-studio] element
+// 4) Add one custom UI button
+ui.registerButton({
+  id: "text",
+  icon: `<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3 3H13"/><path d="M8 3V13"/><path d="M5 13H11"/></svg>`,
+  tooltip: "Add Text"
+});
 
-// 4. Initialize the Timeline
-const container = document.querySelector("[data-shotstack-timeline]");
-const timeline = new Timeline(edit, container, {
-  features: { toolbar: true, ruler: true, playhead: true, snap: true }
+ui.on("button:text", ({ position }) => {
+  edit.addTrack(0, {
+    clips: [
+      {
+        asset: {
+          type: "rich-text",
+          text: "Title",
+          font: { family: "Work Sans", size: 72, weight: 600, color: "#ffffff", opacity: 1 },
+          align: { horizontal: "center", vertical: "middle" }
+        },
+        start: position,
+        length: 5,
+        width: 500,
+        height: 200
+      }
+    ]
+  });
 });
+
+// 5) Timeline + controls
+const timelineContainer = document.querySelector("[data-shotstack-timeline]") as HTMLElement;
+const timeline = new Timeline(edit, timelineContainer);
 await timeline.load();
 
-// 5. Add keyboard controls
 const controls = new Controls(edit);
 await controls.load();
 ```
 
-Your HTML should include containers for both the canvas and timeline:
+Your HTML must include both containers:
 
 ```html
 <div data-shotstack-studio></div>
@@ -74,185 +98,160 @@ Your HTML should include containers for both the canvas and timeline:
 
 ### Edit
 
-The Edit class represents a video project with its timeline, clips, and properties.
+`Edit` is the runtime editing session and source of truth for document mutations.
 
 ```typescript
 import { Edit } from "@shotstack/shotstack-studio";
 
-// Create an edit from a template
 const edit = new Edit(templateJson);
 await edit.load();
 
-// Or reload a different template later
-await edit.loadEdit(newTemplate);
+await edit.loadEdit(nextTemplateJson);
 
-// Playback controls
+// Playback (seconds)
 edit.play();
 edit.pause();
-edit.seek(2000); // Seek to 2 seconds (in milliseconds)
-edit.stop(); // Stop and return to beginning
-
-// Editing functions
-edit.addClip(0, {
-  asset: {
-    type: "image",
-    src: "https://example.com/image.jpg"
-  },
+edit.seek(2);
+edit.stop();
+
+// Mutations
+await edit.addTrack(0, { clips: [] });
+await edit.addClip(0, {
+  asset: { type: "image", src: "https://example.com/image.jpg" },
   start: 0,
   length: 5
 });
+await edit.updateClip(0, 0, { length: 6 });
+await edit.deleteClip(0, 0);
 
-edit.addTrack(1, { clips: [] });
-edit.deleteClip(0, 0);
-edit.deleteTrack(1);
-
-// Undo/Redo
-edit.undo();
-edit.redo();
-edit.canUndo(); // Check if undo is available (useful for UI)
-edit.canRedo(); // Check if redo is available
+// History
+await edit.undo();
+await edit.redo();
 
-// Get edit information
+// Read state
 const clip = edit.getClip(0, 0);
 const track = edit.getTrack(0);
-const editJson = edit.getEdit();
-const duration = edit.totalDuration; // in milliseconds
+const snapshot = edit.getEdit();
+const durationSeconds = edit.totalDuration;
 ```
 
 #### Events
 
-The Edit class provides a typed event system to listen for specific actions:
+Listen using string event names:
 
 ```typescript
-import { Edit, EditEvent } from "@shotstack/shotstack-studio";
+const unsubscribeClipSelected = edit.events.on("clip:selected", data => {
+  console.log("Selected clip", data.trackIndex, data.clipIndex);
+});
 
-// Listen for clip selection events
-edit.events.on(EditEvent.ClipSelected, data => {
-  console.log("Clip selected:", data.clip);
-  console.log("Track index:", data.trackIndex);
-  console.log("Clip index:", data.clipIndex);
+edit.events.on("clip:updated", data => {
+  console.log("Updated from", data.previous, "to", data.current);
 });
 
-// Listen for clip update events
-edit.events.on(EditEvent.ClipUpdated, data => {
-  console.log("Previous state:", data.previous);
-  console.log("Current state:", data.current);
+edit.events.on("playback:play", () => {
+  console.log("Playback started");
 });
 
-// Listen for playback events
-edit.events.on(EditEvent.PlaybackPlay, () => console.log("Playing"));
-edit.events.on(EditEvent.PlaybackPause, () => console.log("Paused"));
+// Unsubscribe when no longer needed
+unsubscribeClipSelected();
 ```
 
-Available events:
-
-**Playback:** `PlaybackPlay`, `PlaybackPause`
-
-**Clips:** `ClipAdded`, `ClipDeleted`, `ClipSelected`, `ClipUpdated`, `ClipCopied`, `ClipSplit`, `ClipRestored`
-
-**Selection:** `SelectionCleared`
-
-**Edit State:** `EditChanged`, `EditUndo`, `EditRedo`
+Available event names:
 
-**Tracks:** `TrackAdded`, `TrackRemoved`
-
-**Duration:** `DurationChanged`
-
-**Output:** `OutputResized`, `OutputFpsChanged`, `OutputFormatChanged`
-
-**Merge Fields:** `MergeFieldRegistered`, `MergeFieldUpdated`, `MergeFieldRemoved`, `MergeFieldChanged`
-
-**Transcription:** `TranscriptionProgress`, `TranscriptionCompleted`, `TranscriptionFailed`
+- Playback: `playback:play`, `playback:pause`
+- Timeline: `timeline:updated`, `timeline:backgroundChanged`
+- Clip lifecycle: `clip:added`, `clip:split`, `clip:selected`, `clip:updated`, `clip:deleted`, `clip:restored`, `clip:copied`, `clip:loadFailed`, `clip:unresolved`
+- Selection: `selection:cleared`
+- Edit state: `edit:changed`, `edit:undo`, `edit:redo`
+- Track: `track:added`, `track:removed`
+- Duration: `duration:changed`
+- Output: `output:resized`, `output:resolutionChanged`, `output:aspectRatioChanged`, `output:fpsChanged`, `output:formatChanged`, `output:destinationsChanged`
+- Merge fields: `mergefield:changed`
+- Transcription: `transcription:progress`, `transcription:completed`, `transcription:failed`
+- Luma masking: `luma:attached`, `luma:detached`
 
 ### Canvas
 
-The Canvas class provides the visual rendering of the edit.
+`Canvas` renders the current edit.
 
 ```typescript
-// Create and load the canvas
+import { Canvas } from "@shotstack/shotstack-studio";
+
 const canvas = new Canvas(edit);
 await canvas.load();
 
-// Zoom and positioning
 canvas.centerEdit();
 canvas.zoomToFit();
-canvas.setZoom(1.5); // 1.0 is 100%, 0.5 is 50%, etc.
-canvas.dispose(); // Clean up resources when done
+canvas.setZoom(1.25);
+canvas.resize();
+canvas.dispose();
 ```
 
-### Controls
+### UIController
 
-The Controls class adds keyboard controls for playback.
+`UIController` manages built-in UI wiring and extensible button events.
 
 ```typescript
-const controls = new Controls(edit);
-await controls.load();
+import { UIController } from "@shotstack/shotstack-studio";
+
+const ui = UIController.create(edit, canvas, { mergeFields: true });
+
+ui.registerButton({
+  id: "add-title",
+  icon: `<svg viewBox="0 0 16 16">...</svg>`,
+  tooltip: "Add Title"
+});
+
+const unsubscribe = ui.on("button:add-title", ({ position }) => {
+  console.log("Button clicked at", position, "seconds");
+});
 
-// Available keyboard controls:
-// Space - Play/Pause
-// J - Stop
-// K - Pause
-// L - Play
-// Left Arrow - Seek backward
-// Right Arrow - Seek forward
-// Shift + Arrow - Seek larger amount
-// Comma - Step backward one frame
-// Period - Step forward one frame
-// Cmd/Ctrl + Z - Undo
-// Cmd/Ctrl + Shift + Z - Redo
-// Cmd/Ctrl + E - Export/download video
+ui.unregisterButton("add-title");
+unsubscribe();
+ui.dispose();
 ```
 
 ### Timeline
 
-The Timeline class provides a visual timeline interface for editing.
+`Timeline` provides visual clip editing.
 
 ```typescript
 import { Timeline } from "@shotstack/shotstack-studio";
 
-const container = document.querySelector("[data-shotstack-timeline]");
-const timeline = new Timeline(edit, container, {
-  features: {
-    toolbar: true, // Playback controls and editing buttons
-    ruler: true, // Time ruler with markers
-    playhead: true, // Draggable playhead
-    snap: true, // Snap clips to grid and other clips
-    badges: true // Asset type badges on clips
-  }
-});
+const container = document.querySelector("[data-shotstack-timeline]") as HTMLElement;
+const timeline = new Timeline(edit, container);
+
 await timeline.load();
+timeline.zoomIn();
+timeline.zoomOut();
+timeline.dispose();
 ```
 
-### VideoExporter
+### Controls
 
-The VideoExporter class exports the Edit to a MP4 video file encoded in h264 and AAC.
+`Controls` enables keyboard playback/edit shortcuts.
 
 ```typescript
-const exporter = new VideoExporter(edit, canvas);
-await exporter.export("my-video.mp4", 25); // filename, fps
+import { Controls } from "@shotstack/shotstack-studio";
+
+const controls = new Controls(edit);
+await controls.load();
 ```
 
-## Merge Fields
+### VideoExporter
 
-Merge fields allow dynamic content substitution using `{{ FIELD_NAME }}` syntax in your templates.
+`VideoExporter` exports a timeline render from the browser runtime.
 
 ```typescript
-import { Edit, EditEvent } from "@shotstack/shotstack-studio";
+import { VideoExporter } from "@shotstack/shotstack-studio";
 
-// Set a merge field value
-edit.setMergeField("TITLE", "My Video Title");
-edit.setMergeField("SUBTITLE", "A great subtitle");
-
-// Get all registered merge fields
-const fields = edit.getMergeFields();
-
-// Listen for merge field changes
-edit.events.on(EditEvent.MergeFieldUpdated, ({ field }) => {
-  console.log(`Field ${field.name} updated to:`, field.value);
-});
+const exporter = new VideoExporter(edit, canvas);
+await exporter.export("my-video.mp4", 25);
 ```
 
-In templates, use placeholders that will be replaced with merge field values:
+## Merge Fields
+
+Merge fields are template placeholders, typically in the form `{{ FIELD_NAME }}`.
 
 ```json
 {
@@ -263,34 +262,43 @@ In templates, use placeholders that will be replaced with merge field values:
 }
 ```
 
-## Custom Toolbar Buttons
+When merge-field-aware UI is required, enable it via `UIController` options:
+
+```typescript
+const ui = UIController.create(edit, canvas, { mergeFields: true });
+```
+
+You can also subscribe to merge field events when integrations update merge data:
 
-Register custom toolbar buttons to extend the canvas toolbar with your own actions:
+```typescript
+edit.events.on("mergefield:changed", ({ fields }) => {
+  console.log("Merge fields updated:", fields.length);
+});
+```
+
+## Custom UI Buttons
+
+Use `UIController` to register and handle custom button actions.
 
 ```typescript
-// Register a custom button
-edit.registerToolbarButton({
-  id: "add-text",
+ui.registerButton({
+  id: "text",
   icon: `<svg viewBox="0 0 16 16">...</svg>`,
   tooltip: "Add Text",
-  event: "text:requested",
-  dividerBefore: true // Optional: add a divider before this button
+  dividerBefore: true
 });
 
-// Handle the custom event
-edit.events.on("text:requested", ({ position }) => {
-  // position is the current playhead position in milliseconds
-  edit.addClip(0, {
-    asset: { type: "text", text: "New Text" },
-    start: position / 1000,
-    length: 5
-  });
+ui.on("button:text", ({ position, selectedClip }) => {
+  console.log("Current time (seconds):", position);
+  console.log("Current selection:", selectedClip);
 });
+
+ui.unregisterButton("text");
 ```
 
 ## API Reference
 
-For complete schema and type definitions, see the [Shotstack API Reference](https://shotstack.io/docs/api/#tocs_edit).
+For schema-level details and type definitions, see the [Shotstack API Reference](https://shotstack.io/docs/api/#tocs_edit).
 
 ## License