@pneuma-craft/video 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.5.1
+
+### Patch Changes
+
+- eecee02: Republish to fix stale internal dependency refs. The previous publish (`@pneuma-craft/video@0.5.0`) declared `@pneuma-craft/timeline@0.3.0` instead of `@pneuma-craft/timeline@0.4.0`, because `bun pm pack` rewrote `workspace:*` against a lockfile that `bun install --no-frozen-lockfile` had not refreshed. The CI release script now nukes `bun.lock` before re-installing, so the lockfile mirrors the bumped versions and `bun pm pack` resolves to the correct ones.
+
+  `@pneuma-craft/react` is auto-patched by changesets because it depends on `@pneuma-craft/video`; the same fix flows through to its own published deps (`timeline@0.4.0`, `video@0.5.1`).
+
+## 0.5.0
+
+### Minor Changes
+
+- c7a09ae: Add **PreviewFrame**, a planning-layer visual attached to a track at a single time point that lets go (does not render) when a real clip on the same track covers that moment. Powers the AIGC progressive-fidelity workflow (cheap sketch → upgraded anchor → real clip) without diluting `Clip` semantics.
+
+  `@pneuma-craft/timeline` (additive)
+
+  - New types: `PreviewFrame`, `ResolvedPreviewFrame`, `ResolvedFrame.previewFrames[]`
+  - `Track` gains a sorted `previewFrames: PreviewFrame[]` array
+  - New commands (mirroring clip ops): `composition:add-preview-frame`, `remove-preview-frame`, `move-preview-frame`, `rebind-preview-frame`
+  - Matching events with undo compensations
+  - `resolveFrame()` applies a per-track let-go rule (clip wins over preview at the same time on the same track)
+  - `recomputeDuration()` extends to the last preview-frame time
+  - New utility `buildSetPreviewFrameCommand()` for agent upsert ergonomics
+  - `composition:add-track` now accepts `previewFrames` as optional in its input shape (defaults to `[]`)
+
+  `@pneuma-craft/video` (additive + small internal signature)
+
+  - `createFrameRenderer`'s 5th argument now accepts `{ subtitleRenderer?, includePreviewFrames? }`. The pre-existing positional `SubtitleRenderer` form is detected and normalized — existing call sites continue to compile.
+  - `PlaybackEngineOptions.includePreviewFrames` (defaults to `true`) — playback shows planning visuals
+  - `ExportEngineOptions.includePreviewFrames` (defaults to `false`) — export = finished cut by default; opt-in for review-grade exports of unfinished timelines
+
+  See `docs/specs/2026-05-09-preview-frame-design.md` for the full design and `docs/recipes/preview-frames.md` for an integration guide.
+
+### Patch Changes
+
+- Updated dependencies [c7a09ae]
+  - @pneuma-craft/timeline@0.4.0
+
 All notable changes to `@pneuma-craft/video` will be documented in this file.
 
 ## 0.4.0

package/dist/index.cjs

@@ -471,31 +471,58 @@ async function createCompositor(width, height, type = "auto") {
 
 // src/frame-renderer.ts
 var import_timeline = require("@pneuma-craft/timeline");
-function createFrameRenderer(decoder, compositor, width, height, subtitleRenderer) {
+function normalizeOptions(arg) {
+  if (arg === void 0) return {};
+  if (typeof arg === "function") return { subtitleRenderer: arg };
+  return arg;
+}
+function createFrameRenderer(decoder, compositor, width, height, optionsOrLegacySubtitleRenderer) {
+  const options = normalizeOptions(optionsOrLegacySubtitleRenderer);
+  const { subtitleRenderer, includePreviewFrames = false } = options;
   return {
     async renderFrame(composition, time) {
       const resolved = (0, import_timeline.resolveFrame)(composition, time);
-      const videoClips = resolved.clips.filter((rc) => rc.track.type === "video");
-      const subtitleClips = subtitleRenderer ? resolved.clips.filter((rc) => rc.track.type === "subtitle") : [];
+      const clipsByTrack = /* @__PURE__ */ new Map();
+      for (const rc of resolved.clips) {
+        const arr = clipsByTrack.get(rc.track.id);
+        if (arr) arr.push(rc);
+        else clipsByTrack.set(rc.track.id, [rc]);
+      }
+      const previewByTrack = /* @__PURE__ */ new Map();
+      for (const rpf of resolved.previewFrames) previewByTrack.set(rpf.track.id, rpf);
       const layers = [];
-      for (let i = 0; i < videoClips.length; i++) {
-        const rc = videoClips[i];
-        const source = await decoder.decodeVideoFrame(
-          rc.clip.assetId,
-          rc.localTime,
-          width,
-          height
-        );
-        layers.push({
-          source,
-          opacity: 1,
-          zIndex: i
-        });
+      let zIndex = 0;
+      for (const track of composition.tracks) {
+        if (track.type !== "video") continue;
+        const trackClips = clipsByTrack.get(track.id);
+        if (trackClips && trackClips.length > 0) {
+          for (const rc of trackClips) {
+            const source = await decoder.decodeVideoFrame(
+              rc.clip.assetId,
+              rc.localTime,
+              width,
+              height
+            );
+            layers.push({ source, opacity: 1, zIndex: zIndex++ });
+          }
+          continue;
+        }
+        if (includePreviewFrames) {
+          const rpf = previewByTrack.get(track.id);
+          if (rpf) {
+            const source = await decoder.decodeVideoFrame(
+              rpf.previewFrame.assetId,
+              0,
+              width,
+              height
+            );
+            layers.push({ source, opacity: 1, zIndex: zIndex++ });
+          }
+        }
       }
-      if (subtitleRenderer && subtitleClips.length > 0) {
-        const baseZ = videoClips.length;
-        for (let i = 0; i < subtitleClips.length; i++) {
-          const rc = subtitleClips[i];
+      if (subtitleRenderer) {
+        const subtitleClips = resolved.clips.filter((rc) => rc.track.type === "subtitle");
+        for (const rc of subtitleClips) {
           const rendered = await subtitleRenderer({
             clip: rc.clip,
             localTime: rc.localTime,
@@ -503,11 +530,7 @@ function createFrameRenderer(decoder, compositor, width, height, subtitleRendere
             height
           });
           if (rendered) {
-            layers.push({
-              source: rendered,
-              opacity: 1,
-              zIndex: baseZ + i
-            });
+            layers.push({ source: rendered, opacity: 1, zIndex: zIndex++ });
           }
         }
       }
@@ -908,6 +931,7 @@ function createPlaybackEngine(options) {
   const compositorType = options?.compositorType ?? "canvas2d";
   const decodeTimeoutMs = options?.decodeTimeoutMs ?? DEFAULT_DECODE_TIMEOUT_MS;
   const subtitleRenderer = options?.subtitleRenderer;
+  const includePreviewFrames = options?.includePreviewFrames ?? true;
   let _state = "idle";
   let _playbackRate = 1;
   let _loop = null;
@@ -1076,7 +1100,7 @@ function createPlaybackEngine(options) {
           _compositor,
           composition.settings.width,
           composition.settings.height,
-          subtitleRenderer
+          { subtitleRenderer, includePreviewFrames }
         );
         _clock = createMasterClock({
           audioContext: _audioContext,
@@ -1235,6 +1259,7 @@ function createOfflineAudioRenderer() {
 var import_mediabunny2 = require("mediabunny");
 function createExportEngine(options) {
   const subtitleRenderer = options?.subtitleRenderer;
+  const includePreviewFrames = options?.includePreviewFrames ?? false;
   const progressListeners = /* @__PURE__ */ new Set();
   let abortController = null;
   function notifyProgress(progress) {
@@ -1257,7 +1282,10 @@ function createExportEngine(options) {
       const decoderAudioCtx = new OfflineAudioContext(1, 1, composition.settings.sampleRate || 48e3);
       const decoder = createMediaDecoder(resolver, decoderAudioCtx);
       const compositor = await createCompositor(width, height, "canvas2d");
-      const renderer = createFrameRenderer(decoder, compositor, width, height, subtitleRenderer);
+      const renderer = createFrameRenderer(decoder, compositor, width, height, {
+        subtitleRenderer,
+        includePreviewFrames
+      });
       try {
         const format = options2.format === "webm" ? new import_mediabunny2.WebMOutputFormat() : new import_mediabunny2.Mp4OutputFormat({ fastStart: "in-memory" });
         const target = new import_mediabunny2.BufferTarget();