@shotstack/shotstack-studio 2.0.0-beta.9 → 2.0.0-rc.1

package/package.json

@@ -5,7 +5,7 @@
 		"cpuccino",
 		"dazzatron"
 	],
-	"version": "2.0.0-beta.9",
+	"version": "2.0.0-rc.1",
 	"description": "A video editing library for creating and editing videos with Shotstack",
 	"type": "module",
 	"main": "dist/shotstack-studio.umd.js",
@@ -18,17 +18,18 @@
 			"require": "./dist/shotstack-studio.umd.js",
 			"default": "./dist/shotstack-studio.es.js"
 		},
-		"./schema": {
-			"types": "./dist/schema/index.d.ts",
-			"import": "./dist/schema/index.mjs",
-			"require": "./dist/schema/index.cjs",
-			"default": "./dist/schema/index.mjs"
+		"./internal": {
+			"types": "./dist/internal.d.ts",
+			"import": "./dist/internal.es.js",
+			"require": "./dist/internal.umd.js",
+			"default": "./dist/internal.es.js"
 		}
 	},
 	"files": [
 		"dist/shotstack-studio.umd.js",
 		"dist/shotstack-studio.es.js",
-		"dist/schema/**",
+		"dist/internal.umd.js",
+		"dist/internal.es.js",
 		"dist/**/*.d.ts"
 	],
 	"keywords": [
@@ -38,16 +39,20 @@
 		"ffmpeg"
 	],
 	"license": "PolyForm Shield License 1.0.0",
+	"engines": {
+		"node": ">=22 <23"
+	},
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/shotstack/shotstack-studio-sdk"
 	},
 	"scripts": {
 		"dev": "vite",
+		"dev:shotstack": "vite --open /shotstack.html",
 		"start": "npm run build && vite preview",
-		"build": "npm run build:main && npm run build:schema",
+		"build": "npm run build:main && npm run build:internal",
 		"build:main": "vite build",
-		"build:schema": "vite build --config vite.config.schema.ts",
+		"build:internal": "node scripts/build-internal.mjs",
 		"test": "jest",
 		"test:watch": "jest --watch",
 		"test:package": "node test-package.js",
@@ -55,11 +60,12 @@
 		"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": {
-		"@jest/globals": "^30.2.0",
 		"@types/howler": "^2.2.12",
 		"@types/jest": "^30.0.0",
 		"@types/node": "^22.9.0",
@@ -80,16 +86,13 @@
 		"vite-plugin-dts": "^4.5.4"
 	},
 	"dependencies": {
-		"@huggingface/transformers": "^3.0.0",
-		"@shotstack/schemas": "^1.3.9",
-		"@shotstack/shotstack-canvas": "^1.8.0",
-		"fast-deep-equal": "^3.1.3",
+		"@shotstack/schemas": "1.7.0",
+		"@shotstack/shotstack-canvas": "^1.9.6",
 		"howler": "^2.2.4",
 		"mediabunny": "^1.11.2",
-		"opentype": "^0.1.2",
 		"opentype.js": "^1.3.4",
 		"pixi-filters": "^6.0.5",
-		"pixi.js": "^8.5.2",
+		"pixi.js": "^8.15.0",
 		"zod": "^4.0.0"
 	}
 }

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,159 @@ 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`
+- 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 +261,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
 

package/dist/schema/assets/images/typescript.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="32" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path fill="#007ACC" d="M0 128v128h256V0H0z"></path><path fill="#FFF" d="m56.612 128.85l-.081 10.483h33.32v94.68h23.568v-94.68h33.321v-10.28c0-5.69-.122-10.444-.284-10.566c-.122-.162-20.4-.244-44.983-.203l-44.74.122l-.121 10.443Zm149.955-10.742c6.501 1.625 11.459 4.51 16.01 9.224c2.357 2.52 5.851 7.111 6.136 8.208c.08.325-11.053 7.802-17.798 11.988c-.244.162-1.22-.894-2.317-2.52c-3.291-4.795-6.745-6.867-12.028-7.233c-7.76-.528-12.759 3.535-12.718 10.321c0 1.992.284 3.17 1.097 4.795c1.707 3.536 4.876 5.649 14.832 9.956c18.326 7.883 26.168 13.084 31.045 20.48c5.445 8.249 6.664 21.415 2.966 31.208c-4.063 10.646-14.14 17.879-28.323 20.276c-4.388.772-14.79.65-19.504-.203c-10.28-1.828-20.033-6.908-26.047-13.572c-2.357-2.6-6.949-9.387-6.664-9.874c.122-.163 1.178-.813 2.356-1.504c1.138-.65 5.446-3.129 9.509-5.485l7.355-4.267l1.544 2.276c2.154 3.29 6.867 7.801 9.712 9.305c8.167 4.307 19.383 3.698 24.909-1.26c2.357-2.153 3.332-4.388 3.332-7.68c0-2.966-.366-4.266-1.91-6.501c-1.99-2.845-6.054-5.242-17.595-10.24c-13.206-5.69-18.895-9.224-24.096-14.832c-3.007-3.25-5.852-8.452-7.03-12.8c-.975-3.617-1.22-12.678-.447-16.335c2.723-12.76 12.353-21.659 26.25-24.3c4.51-.853 14.994-.528 19.424.569Z"></path></svg>