@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/timeline-preview/frames.js

@@ -0,0 +1,731 @@
+/**
+ * Composite a timeline at chosen timecodes, headlessly.
+ *
+ * The question this answers is the one an agent editing a timeline could not
+ * ask before: *what does the cut actually look like at 2.4s?* Structural
+ * validation says the clips are wired correctly and `get_clip_frames` shows one
+ * clip's source media, but neither shows the frame — the picture under the
+ * title, the title's animation mid-flight, the transition halfway through, the
+ * track order that decides what covers what.
+ *
+ * It resolves the scene the same way every other render surface does
+ * (`computeActiveLayers` → `resolveAnimatedLayerProps`), rasterizes the
+ * text/shape/caption layers through the shared drawing rules, decodes the media
+ * layers with Mediabunny, and composites on `@napi-rs/canvas` through the
+ * shared Canvas 2D rules. So it needs no GPU, no ffmpeg and no browser, and it
+ * runs anywhere the agent runs.
+ *
+ * Effects run through CPU pixel passes matching the GPU chain. Unknown effect
+ * types are reported in `effects_not_applied`, and missing render resources
+ * are reported on each frame.
+ */
+import { createCanvas, loadImage } from "@napi-rs/canvas";
+import { computeModel3DBakeHash, resolveModel3DCamera } from "@nodetool-ai/timeline";
+import { ensureGoogleFonts } from "@nodetool-ai/timeline/fonts/google-node";
+import { accumulateBlurSample, clipSourceTimeSec, computeActiveLayersWithHorizon, createAnimationCompileCache, drawTimelineFrame, hasActiveAnimation, measureTextWith, motionBlurSampleTimes, layerShutterTime, resolveFrameMotionBlur, resolveAnimatedLayerProps, resolveTextStaggerContext, seedBlurAccumulation, shutterWindowIsStatic, trackZ, unsupportedEffectTypes } from "@nodetool-ai/timeline/scene";
+import { forEachVideoFrame } from "../analysis/media-decode.js";
+import { DEFAULT_PREVIEW_WIDTH, MAX_PREVIEW_WIDTH } from "../capabilities/timelines.specs.js";
+import { collectModel3DLayers, Model3DPrerenderer, sessionOptionsFor } from "./model3d.js";
+import { PreviewRasterizer } from "./rasterize.js";
+/**
+ * Reads of one asset allowed per render pass. See `bytesFor` for why a failed
+ * read is retried at all, and why the retries are bounded.
+ */
+const MAX_ASSET_READ_ATTEMPTS = 3;
+/** The message behind a thrown value, for a layer's `skipped` reason. */
+function describeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.trim() || "it failed with no message";
+}
+async function loadPreviewImage(bytes) {
+    const buffer = Buffer.from(bytes);
+    try {
+        return await loadImage(buffer);
+    }
+    catch (error) {
+        if (buffer.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a") {
+            throw error;
+        }
+        // Canvas can mistake SVG text in PNG metadata for the image format.
+        // Re-encode only the decoding copy through the shared image codec.
+        const { extractImageRegion } = await import("@nodetool-ai/runtime");
+        const normalized = await extractImageRegion(bytes, { sourceMime: "image/png" });
+        return loadImage(Buffer.from(normalized.data));
+    }
+}
+/** Frame geometry: the output size, and the sequence size the layout is in. */
+function frameSize(sequence, requested) {
+    const seqW = Math.max(1, sequence.width || 1920);
+    const seqH = Math.max(1, sequence.height || 1080);
+    const width = Math.min(MAX_PREVIEW_WIDTH, Math.max(16, Math.round(requested ?? DEFAULT_PREVIEW_WIDTH)));
+    return { width, height: Math.max(1, Math.round((width * seqH) / seqW)) };
+}
+/**
+ * Decode one video frame at an already-resolved source time.
+ *
+ * The caller resolves it, because which mapping applies is the layer's to
+ * decide: an ordinary video clip seeks by `clipSourceTimeSec`, and a baked 3D
+ * clip by `bakeSourceTimeSec`, whose origin is the clip's own first frame
+ * however the clip is trimmed (design §D6, time origin).
+ */
+async function decodeVideoFrameAt(bytes, sourceTimeSec) {
+    const sourceSec = Math.max(0, sourceTimeSec);
+    let out = null;
+    await forEachVideoFrame(bytes, [sourceSec], (frame) => {
+        const canvas = createCanvas(frame.width, frame.height);
+        const ctx = canvas.getContext("2d");
+        const image = ctx.createImageData(frame.width, frame.height);
+        image.data.set(frame.rgba);
+        ctx.putImageData(image, 0, 0);
+        out = { canvas, width: frame.width, height: frame.height };
+    });
+    return out;
+}
+/** The text a layer draws, for the report. */
+function layerText(layer) {
+    if (layer.kind === "text")
+        return layer.textStyle?.text;
+    if (layer.kind === "caption" && layer.caption) {
+        return layer.caption.words.map((w) => w.text).join(" ");
+    }
+    return undefined;
+}
+/** The camera a 3D layer drew with, in the report's vocabulary. */
+function cameraReport(camera) {
+    const report = {
+        mode: camera.mode,
+        azimuth_deg: Number(camera.azimuthDeg.toFixed(3)),
+        elevation_deg: Number(camera.elevationDeg.toFixed(3)),
+        fov_deg: Number(camera.fovDeg.toFixed(3)),
+        zoom: Number(camera.zoom.toFixed(3))
+    };
+    if (camera.sceneCameraName)
+        report.scene_camera_name = camera.sceneCameraName;
+    if (camera.targetOffset)
+        report.target_offset = camera.targetOffset;
+    return report;
+}
+/** A clip's authored name, for a report that only holds its id. */
+function clipName(sequence, clipId) {
+    return sequence.clips.find((clip) => clip.id === clipId)?.name ?? clipId;
+}
+/**
+ * Composite `timesMs` and return the PNG of each, plus what each layer
+ * contributed. Asset bytes are loaded once per asset across all timecodes.
+ */
+export async function renderTimelineFrames(options) {
+    const { sequence, loadAsset } = options;
+    const onlyClipIds = options.onlyClipIds ? new Set(options.onlyClipIds) : undefined;
+    const { width, height } = frameSize(sequence, options.width);
+    // Animation offsets and text sizes are authored against the sequence's own
+    // resolution, so that is the space they are sampled in; the frame is drawn
+    // smaller and the transform math is told the reference size.
+    const animationCanvas = {
+        width: Math.max(1, sequence.width || 1920),
+        height: Math.max(1, sequence.height || 1080),
+        // A `"line"` stagger is counted against the wrapped line count, so the
+        // count measures through the same kind of context the rasterizer draws on.
+        measureText: measureTextWith(
+        // SAFETY: `RasterContext2D` is the subset of the 2D canvas API the
+        // measurement uses, and a skia context provides all of it.
+        createCanvas(1, 1).getContext("2d"))
+    };
+    const geometry = {
+        canvasWidth: width,
+        canvasHeight: height,
+        refWidth: animationCanvas.width,
+        refHeight: animationCanvas.height
+    };
+    const { unavailable: fontsUnavailable } = await ensureGoogleFonts(sequence);
+    const rasterizer = new PreviewRasterizer(width, height);
+    // Text size, tracking, and wrapping are authored in sequence pixels.
+    const referenceRasterizer = new PreviewRasterizer(animationCanvas.width, animationCanvas.height);
+    const animCache = createAnimationCompileCache();
+    /**
+     * The scene options every resolve in this pass shares. `model3dBakeHash` is
+     * what lets a `model3d` clip play its Blender bake as a video layer: without
+     * a resolver the scene model has no live hash to compare against and always
+     * draws the live 3D layer (design §D6).
+     */
+    const sceneOptions = {
+        canvas: animationCanvas,
+        animationCache: animCache,
+        mediaTracks: sequence.mediaTracks,
+        camera2d: sequence.camera2d,
+        tempo: sequence.tempo,
+        model3dBakeHash: (clip) => computeModel3DBakeHash(clip, {
+            fps: Math.max(1, sequence.fps || 30),
+            width: animationCanvas.width,
+            height: animationCanvas.height
+        })
+    };
+    const canvas = createCanvas(width, height);
+    const ctx = canvas.getContext("2d");
+    const asSurface = (canvasFor) => ({
+        // SAFETY: `CompositeContext2D` is the subset of the 2D canvas API the
+        // compositing rules use, and a skia context provides all of it.
+        ctx: canvasFor.getContext("2d"),
+        surface: canvasFor
+    });
+    let scratch = null;
+    const scratchFor = (w, h) => {
+        const surface = scratch && scratch.width === w && scratch.height === h
+            ? scratch
+            : createCanvas(w, h);
+        scratch = surface;
+        return asSurface(surface);
+    };
+    /**
+     * Precomposite surfaces, pooled across frames and handed out one at a time
+     * within a frame: a nested group holds its surface until the group above has
+     * drawn it, so they cannot share the way the wipe scratch does.
+     */
+    const precompositePool = [];
+    let precompositesTaken = 0;
+    const precompositeSurfaceFor = (w, h) => {
+        const index = precompositesTaken++;
+        let surface = precompositePool[index];
+        if (!surface || surface.width !== w || surface.height !== h) {
+            surface = createCanvas(w, h);
+            precompositePool[index] = surface;
+        }
+        return asSurface(surface);
+    };
+    /**
+     * Coverage scratch for a feathered shape mask, and the pair a matted layer
+     * composes on. Both come from the precomposite pool because it is the one
+     * that hands out a *distinct* surface per call within a frame — a feathered
+     * mask and the layer it cuts are live at the same moment, so they cannot
+     * share the single reused wipe scratch.
+     */
+    const maskSurfaceFor = precompositeSurfaceFor;
+    const matteSurfaceFor = precompositeSurfaceFor;
+    /**
+     * Where a cropped layer's picture lands. Also from the precomposite pool: the
+     * crop stays live for the whole of one layer's draw, and the mask surfaces
+     * read from it while it does.
+     */
+    const cropSurfaceFor = precompositeSurfaceFor;
+    /**
+     * Encoded asset bytes, shared by every frame in the pass — but only a
+     * *successful* read is kept. A failed one is dropped so a later frame reads
+     * the asset again: one transient failure used to decide the whole pass, and
+     * every frame after it came out missing that layer while the asset itself
+     * was healthy.
+     *
+     * Retries are bounded rather than unbounded because a pass draws
+     * `timesMs.length` frames (times the motion-blur samples), and every frame
+     * reads every media layer. Three attempts gives a blip two more chances
+     * while costing an asset that is really gone a handful of reads instead of
+     * one per sampled instant.
+     */
+    const assetBytes = new Map();
+    const assetReadAttempts = new Map();
+    /** Why the last read of an asset failed, for the layer's `skipped` reason. */
+    const assetReadErrors = new Map();
+    const bytesFor = (assetId) => {
+        const cached = assetBytes.get(assetId);
+        if (cached)
+            return cached;
+        if ((assetReadAttempts.get(assetId) ?? 0) >= MAX_ASSET_READ_ATTEMPTS) {
+            return Promise.resolve(null);
+        }
+        assetReadAttempts.set(assetId, (assetReadAttempts.get(assetId) ?? 0) + 1);
+        const pending = loadAsset(assetId).then((bytes) => {
+            if (bytes && bytes.byteLength > 0) {
+                assetReadErrors.delete(assetId);
+                return bytes;
+            }
+            assetBytes.delete(assetId);
+            assetReadErrors.set(assetId, bytes ? "the read returned no bytes" : "no bytes were available");
+            return null;
+        }, (error) => {
+            assetBytes.delete(assetId);
+            assetReadErrors.set(assetId, describeError(error));
+            return null;
+        });
+        assetBytes.set(assetId, pending);
+        return pending;
+    };
+    /**
+     * The 3D layers of the whole pass, drawn in headless Chromium before the
+     * first frame is composited (D5, host 2). It shares `bytesFor`, so a GLB is
+     * read once for the pass whether or not a layer of it also draws elsewhere.
+     */
+    const model3d = new Model3DPrerenderer({
+        width,
+        height,
+        loadAsset: bytesFor
+    });
+    const decodedImages = new Map();
+    /** Why an asset's bytes would not decode, for the layer's `skipped` reason. */
+    const decodeErrors = new Map();
+    const frames = [];
+    const effectsNotApplied = new Set();
+    const frameMs = 1000 / Math.max(1, sequence.fps || 30);
+    const frameBlurs = options.timesMs.map((timeMs) => resolveFrameMotionBlur(sequence.clips, options.motionBlur, timeMs, frameMs, sequence.tracks));
+    /**
+     * Where the shutter window is summed. Allocated only for a blurred render:
+     * with blur off the main canvas is the frame, exactly as it was before.
+     */
+    const blurAccumulator = frameBlurs.some((blur) => blur.samplesPerFrame > 1) ? createCanvas(width, height) : null;
+    const blurCtx = blurAccumulator
+        ? // SAFETY: `CompositeContext2D` is the subset of the 2D canvas API the
+            // accumulation uses, and a skia context provides all of it.
+            blurAccumulator.getContext("2d")
+        : null;
+    /** The same resolved scene and per-layer clock drive collection and drawing. */
+    const resolveSample = (timeMs, frameTimeMs, sampleIndex, sampleCount) => {
+        const layerTime = (clip) => layerShutterTime(clip, frameTimeMs, sampleIndex, sampleCount, frameMs, options.motionBlur);
+        const scene = computeActiveLayersWithHorizon(sequence.tracks, sequence.clips, timeMs, { ...sceneOptions, layerTimeMs: layerTime });
+        const layers = onlyClipIds
+            ? scene.layers.filter((layer) => onlyClipIds.has(layer.clipId))
+            : scene.layers;
+        const sampledLayers = new Map();
+        const sampleLayer = (layer) => {
+            const previous = sampledLayers.get(layer);
+            if (previous)
+                return previous;
+            const timeMs = layerTime(layer.clip);
+            const anim = resolveAnimatedLayerProps(layer, timeMs, animationCanvas, animCache, { mediaTracks: sequence.mediaTracks ?? [], clips: sequence.clips, tempo: sequence.tempo });
+            const sampled = { timeMs, anim };
+            if (layer.kind === "model3d" && layer.model3dStyle) {
+                sampled.camera = resolveModel3DCamera(layer.model3dStyle, anim);
+                // The scene's sourceTimeSec uses its global clock. Its layerTimeMs
+                // callback only gates activity, so seek this clip on its own shutter clock.
+                sampled.sourceTimeSec = clipSourceTimeSec(layer.clip, timeMs) * layer.model3dStyle.animation.speed;
+            }
+            sampledLayers.set(layer, sampled);
+            return sampled;
+        };
+        return { ...scene, layers, sampleLayer };
+    };
+    /**
+     * Draw one instant onto the main canvas and say what each layer contributed.
+     *
+     * One call is a whole frame with blur off, and one sample of the shutter
+     * window with it on — the picture is the same work either way, which is what
+     * keeps a blurred preview from drifting from an unblurred one.
+     */
+    const composeAt = async (sample) => {
+        const { layers: active, adjustments, precomposites, droppedLayers } = sample;
+        const ancestorGroups = new Set(active.flatMap((layer) => layer.precomposeGroupId ? [layer.precomposeGroupId] : []));
+        const precomposeById = new Map(precomposites.map((group) => [group.clipId, group]));
+        for (const groupId of ancestorGroups) {
+            const parentId = precomposeById.get(groupId)?.precomposeGroupId;
+            if (parentId) {
+                ancestorGroups.add(parentId);
+            }
+        }
+        const drawPrecomposites = precomposites.filter((group) => !onlyClipIds || ancestorGroups.has(group.clipId)).map((group) => ({
+            id: group.clipId,
+            zIndex: trackZ(group.trackIndex),
+            stackOrder: group.stackOrder,
+            opacity: group.opacity,
+            blendMode: group.blendMode,
+            effects: group.effects,
+            transition: group.transition,
+            precomposeGroupId: group.precomposeGroupId
+        }));
+        const drawAdjustments = adjustments.filter((adjustment) => !onlyClipIds || onlyClipIds.has(adjustment.clipId)).map((adjustment) => ({
+            clipId: adjustment.clipId,
+            zIndex: trackZ(adjustment.trackIndex),
+            opacity: adjustment.opacity,
+            effects: adjustment.effects,
+            mask: adjustment.mask,
+            wipe: adjustment.wipe,
+            precomposeGroupId: adjustment.precomposeGroupId
+        }));
+        // A group's effects run on its composed surface, so they are named here
+        // beside the layers' own — otherwise a group effect this path cannot draw
+        // would go unreported (I7).
+        for (const type of unsupportedEffectTypes([
+            ...active,
+            ...drawPrecomposites,
+            ...drawAdjustments
+        ])) {
+            effectsNotApplied.add(type);
+        }
+        precompositesTaken = 0;
+        const drawLayers = [];
+        const reports = [];
+        /**
+         * Degradations this pass finds before the draw — today only a 3D layer
+         * whose renderer would not run, which the compositor never sees because
+         * the layer never reaches it.
+         */
+        const degradedBeforeDraw = [];
+        /** Which report each drawn layer belongs to, matched by identity. */
+        const reportFor = new Map();
+        const sourceForLayer = async (layer, sampled) => {
+            const { anim, timeMs: layerTimeMs } = sampled;
+            if (layer.kind === "caption" && layer.caption) {
+                const raster = rasterizer.caption(layer.caption);
+                if (!raster)
+                    return { skipped: "nothing to draw" };
+                return {
+                    source: raster,
+                    width: raster.width,
+                    height: raster.height,
+                    untransformed: true
+                };
+            }
+            if (layer.kind === "text" && anim.textStyle) {
+                const stagger = resolveTextStaggerContext(layer.clip, layerTimeMs, animationCanvas, animCache, sequence.tempo);
+                const raster = referenceRasterizer.text(anim.textStyle, stagger);
+                if (!raster)
+                    return { skipped: "nothing to draw" };
+                return { source: raster, width: raster.width, height: raster.height };
+            }
+            if (layer.kind === "shape") {
+                // The animated style carries a driven trim range; without it a trim
+                // animation would rasterize its first frame and hold.
+                const shapeStyle = anim.shapeStyle ?? layer.shapeStyle;
+                if (!shapeStyle)
+                    return { skipped: "nothing to draw" };
+                const raster = rasterizer.shape(shapeStyle);
+                if (!raster)
+                    return { skipped: "nothing to draw" };
+                return { source: raster, width: raster.width, height: raster.height };
+            }
+            if (!layer.assetId) {
+                return {
+                    skipped: layer.clip.status === "draft"
+                        ? "clip has no rendered media yet (status: draft)"
+                        : `clip has no asset to draw (status: ${layer.clip.status})`
+                };
+            }
+            // Bound once: the decode's failure callback closes over it, which would
+            // otherwise lose the narrowing the guard above established.
+            const assetId = layer.assetId;
+            const bytes = await bytesFor(assetId);
+            if (!bytes || bytes.byteLength === 0) {
+                const reason = assetReadErrors.get(assetId) ?? "no bytes were available";
+                return { skipped: `asset ${assetId} could not be read: ${reason}` };
+            }
+            if (layer.kind === "model3d") {
+                const style = layer.model3dStyle;
+                if (!style)
+                    return { skipped: "clip has no 3D style to draw with" };
+                // The pixels were drawn before the pass started compositing: this only
+                // looks them up, by the same group, pose and instant they were asked
+                // for with.
+                const pixels = model3d.get(assetId, sessionOptionsFor(style), sampled.camera ?? resolveModel3DCamera(style, anim), sampled.sourceTimeSec ?? 0);
+                if (!pixels) {
+                    return { skipped: "the 3D layer was not rendered at this instant" };
+                }
+                if ("unavailable" in pixels) {
+                    degradedBeforeDraw.push({
+                        clip_id: layer.clipId,
+                        clip_name: layer.clip.name,
+                        reason: "model3d_unavailable"
+                    });
+                    return {
+                        skipped: `the 3D renderer could not draw this clip: ${pixels.unavailable}`
+                    };
+                }
+                return {
+                    source: pixels.image,
+                    width: pixels.image.width,
+                    height: pixels.image.height
+                };
+            }
+            if (layer.kind === "video") {
+                const sourceTimeSec = layer.bakeSourceTimeSec ?? clipSourceTimeSec(layer.clip, layerTimeMs);
+                const frame = await decodeVideoFrameAt(bytes, sourceTimeSec);
+                if (!frame) {
+                    return {
+                        skipped: `no decodable frame at ${Math.round(sourceTimeSec * 1000)}ms into the source`
+                    };
+                }
+                return {
+                    source: frame.canvas,
+                    width: frame.width,
+                    height: frame.height
+                };
+            }
+            // Unlike a read, a decode is a pure function of bytes this pass already
+            // holds, so a failure here is cached: retrying it would fail the same
+            // way on every frame. Its reason is kept for the same report.
+            let image = decodedImages.get(assetId);
+            if (image === undefined) {
+                image = await loadPreviewImage(bytes).catch((error) => {
+                    decodeErrors.set(assetId, describeError(error));
+                    return null;
+                });
+                decodedImages.set(assetId, image);
+            }
+            if (!image) {
+                const reason = decodeErrors.get(assetId);
+                return {
+                    skipped: reason
+                        ? `asset ${assetId} is not a decodable image: ${reason}`
+                        : `asset ${assetId} is not a decodable image`
+                };
+            }
+            return { source: image, width: image.width, height: image.height };
+        };
+        /**
+         * An active layer as something the Canvas 2D rules can draw, or the reason
+         * it draws nothing. Visible layers and matte dependencies share the same
+         * cached animation samples the 3D pre-pass and layer report read.
+         */
+        const toDrawLayer = async (layer) => {
+            const sampled = sample.sampleLayer(layer);
+            const { anim } = sampled;
+            const resolved = await sourceForLayer(layer, sampled);
+            if ("skipped" in resolved)
+                return resolved.skipped;
+            const drawn = {
+                clipId: layer.clipId,
+                source: resolved.source,
+                sourceWidth: resolved.width,
+                sourceHeight: resolved.height,
+                opacity: anim.opacity,
+                blendMode: layer.blendMode,
+                zIndex: trackZ(layer.trackIndex),
+                stackOrder: layer.stackOrder,
+                precomposeGroupId: layer.precomposeGroupId,
+                mask: anim.mask
+            };
+            if (resolved.untransformed) {
+                // Captions are drawn at frame resolution and composite untransformed —
+                // by the clip's transform, by its group's, and by its effects. The
+                // cut's opacity is already in `opacity`; leaving the record off keeps
+                // its geometry — and a dip's one solid — off a layer that composites
+                // untransformed anyway.
+                return drawn;
+            }
+            drawn.transform = anim.transform;
+            drawn.parentMatrix = layer.parentMatrix;
+            drawn.borderRadius = anim.borderRadius ?? layer.borderRadius;
+            drawn.crop = layer.crop;
+            drawn.shapeMask = anim.clipMask;
+            drawn.effects = anim.effects ?? layer.effects;
+            drawn.trackEffects = layer.trackEffects;
+            drawn.transition = layer.transition;
+            if (layer.matte) {
+                // A matte source is not in `active` — the scene model held it back —
+                // so it is decoded and placed here and nowhere else.
+                const matteLayer = await toDrawLayer(layer.matte.layer);
+                if (typeof matteLayer === "string") {
+                    const source = layer.matte.layer;
+                    return `matte source clip ${source.clipId}${source.assetId ? ` (asset ${source.assetId})` : ""} failed: ${matteLayer}`;
+                }
+                drawn.matte = {
+                    mode: layer.matte.mode,
+                    invert: layer.matte.invert,
+                    layer: matteLayer,
+                    strength: layer.matte.strength,
+                    featherPx: layer.matte.featherPx
+                };
+            }
+            return drawn;
+        };
+        for (const layer of active) {
+            const sampled = sample.sampleLayer(layer);
+            const { anim } = sampled;
+            const zIndex = trackZ(layer.trackIndex);
+            const report = {
+                clip_id: layer.clipId,
+                clip_name: layer.clip.name,
+                kind: layer.kind,
+                track_index: layer.trackIndex,
+                z_index: zIndex,
+                opacity: Number(anim.opacity.toFixed(3)),
+                blend_mode: String(layer.blendMode),
+                text: anim.textStyle?.text ?? layerText(layer)
+            };
+            const wipeMask = anim.mask ?? layer.transition?.mask;
+            if (wipeMask) {
+                report.wipe = {
+                    direction: wipeMask.direction,
+                    progress: Number(wipeMask.progress.toFixed(3))
+                };
+            }
+            if (layer.transition) {
+                report.transition = {
+                    type: layer.transition.type,
+                    role: layer.transition.role,
+                    progress: Number(layer.transition.progress.toFixed(3))
+                };
+            }
+            if (layer.kind === "model3d" && layer.model3dStyle) {
+                report.camera = cameraReport(sampled.camera ?? resolveModel3DCamera(layer.model3dStyle, anim));
+                report.animation_time_sec = Number((sampled.sourceTimeSec ?? 0).toFixed(3));
+            }
+            if (layer.shapeMask)
+                report.mask = { kind: layer.shapeMask.kind };
+            reports.push(report);
+            const drawn = await toDrawLayer(layer);
+            if (typeof drawn === "string") {
+                report.skipped = drawn;
+                continue;
+            }
+            if (layer.matte) {
+                report.matte = {
+                    source_clip_id: layer.matte.layer.clipId,
+                    mode: layer.matte.mode,
+                    invert: layer.matte.invert
+                };
+            }
+            drawLayers.push(drawn);
+            reportFor.set(drawn, report);
+        }
+        const drawReport = drawTimelineFrame(ctx, drawLayers, geometry, {
+            maskScratch: scratchFor,
+            projectiveSurface: precompositeSurfaceFor,
+            effectSurface: precompositeSurfaceFor,
+            adjustments: drawAdjustments,
+            adjustmentSurface: scratchFor,
+            precomposites: drawPrecomposites,
+            precompositeSurface: precompositeSurfaceFor,
+            maskSurface: maskSurfaceFor,
+            matteSurface: matteSurfaceFor,
+            cropSurface: cropSurfaceFor
+        });
+        for (const layer of drawReport.skipped) {
+            const report = reportFor.get(layer);
+            if (report)
+                report.skipped = "source could not be drawn";
+        }
+        return {
+            // Top of the stack first: the reader's question is what is on top.
+            reports: reports.sort((a, b) => b.z_index - a.z_index),
+            dropped: droppedLayers.filter((dropped) => !onlyClipIds || onlyClipIds.has(dropped.clipId)).map((dropped) => ({
+                clip_id: dropped.clipId,
+                clip_name: clipName(sequence, dropped.clipId),
+                reason: dropped.reason
+            })),
+            degraded: [
+                ...degradedBeforeDraw,
+                ...drawReport.degraded.map((entry) => ({
+                    clip_id: entry.clipId,
+                    clip_name: entry.clipId
+                        ? clipName(sequence, entry.clipId)
+                        : undefined,
+                    reason: entry.reason
+                }))
+            ]
+        };
+    };
+    /**
+     * Ask the 3D pre-pass for every `model3d` layer at one instant, matte
+     * sources included.
+     *
+     * The scene, camera and source clock are the same samples composition uses.
+     */
+    const requestModel3DAt = (sample) => {
+        for (const layer of collectModel3DLayers(sample.layers)) {
+            const style = layer.model3dStyle;
+            if (!layer.assetId || !style)
+                continue;
+            const sampled = sample.sampleLayer(layer);
+            model3d.request(layer.assetId, sessionOptionsFor(style), sampled.camera ?? resolveModel3DCamera(style, sampled.anim), sampled.sourceTimeSec ?? 0);
+        }
+    };
+    /**
+     * True when the shutter window holds one picture. Resolving the layer set
+     * decodes nothing, so the check costs a fraction of the N decodes and N
+     * composites it saves on a still frame.
+     */
+    const shutterIsStatic = (timeMs, blur) => {
+        if (blur.samplesPerFrame <= 1)
+            return false;
+        const { layers } = computeActiveLayersWithHorizon(sequence.tracks, sequence.clips, timeMs, sceneOptions);
+        return shutterWindowIsStatic(layers, hasActiveAnimation(layers, timeMs, animationCanvas, animCache, sequence.clips, sequence.tempo));
+    };
+    /**
+     * Every instant this pass will compose: one per frame with blur off, and the
+     * shutter window's samples with it on. Resolved up front because the 3D
+     * pre-pass below has to know every instant before it renders any of them.
+     */
+    const frameInstants = options.timesMs.map((timeMs, index) => {
+        const sampleTimes = shutterIsStatic(timeMs, frameBlurs[index])
+            ? [timeMs]
+            : motionBlurSampleTimes(timeMs, frameMs, frameBlurs[index]);
+        return {
+            timeMs, blur: frameBlurs[index], sampleTimes,
+            samples: sampleTimes.map((sampleMs, sampleIndex) => resolveSample(sampleMs, timeMs, sampleIndex, sampleTimes.length))
+        };
+    });
+    // A document without 3D clips never loads the headless renderer.
+    if (sequence.clips.some((clip) => clip.mediaType === "model3d")) {
+        for (const { samples } of frameInstants) {
+            for (const sample of samples)
+                requestModel3DAt(sample);
+        }
+        await model3d.run();
+    }
+    for (const { timeMs, sampleTimes, samples, blur } of frameInstants) {
+        let composed;
+        const failures = new Map();
+        const dropped = new Map();
+        const degraded = new Map();
+        const recordSample = (sample, index, sampleMs) => {
+            const record = (kind, entry) => {
+                const key = JSON.stringify([kind, entry.clip_id, entry.clip_name, entry.reason]);
+                const existing = failures.get(key);
+                const affected = { index, time_ms: sampleMs };
+                if (existing) {
+                    if (existing.samples.at(-1)?.index !== index) {
+                        existing.samples.push(affected);
+                    }
+                }
+                else {
+                    failures.set(key, { kind, ...entry, samples: [affected] });
+                }
+            };
+            for (const layer of sample.reports) {
+                if (layer.skipped)
+                    record("skipped", {
+                        clip_id: layer.clip_id, clip_name: layer.clip_name, reason: layer.skipped
+                    });
+            }
+            for (const entry of sample.dropped) {
+                record("dropped", entry);
+                dropped.set(JSON.stringify(entry), entry);
+            }
+            for (const entry of sample.degraded) {
+                record("degraded", entry);
+                degraded.set(JSON.stringify(entry), entry);
+            }
+        };
+        if (!blurCtx || !blurAccumulator || sampleTimes.length === 1) {
+            composed = await composeAt(samples[0]);
+            recordSample(composed, 0, timeMs);
+        }
+        else {
+            seedBlurAccumulation(blurCtx, geometry);
+            // The report describes the first instant of the shutter window, since no
+            // single set of numbers describes a picture that is N instants averaged.
+            composed = await composeAt(samples[0]);
+            recordSample(composed, 0, sampleTimes[0]);
+            accumulateBlurSample(blurCtx, canvas, blur.weight, geometry);
+            for (const [index, sampleMs] of sampleTimes.slice(1).entries()) {
+                const sample = await composeAt(samples[index + 1]);
+                recordSample(sample, index + 1, sampleMs);
+                accumulateBlurSample(blurCtx, canvas, blur.weight, geometry);
+            }
+        }
+        frames.push({
+            complete: failures.size === 0 &&
+                effectsNotApplied.size === 0 && fontsUnavailable.length === 0,
+            time_ms: timeMs,
+            png: new Uint8Array((sampleTimes.length > 1 && blurAccumulator ? blurAccumulator : canvas).toBuffer("image/png")),
+            width,
+            height,
+            layers: composed.reports,
+            dropped: [...dropped.values()],
+            degraded: [...degraded.values()],
+            failures: [...failures.values()]
+        });
+    }
+    return {
+        complete: frames.every((frame) => frame.complete),
+        frames,
+        effectsNotApplied: [...effectsNotApplied].sort(),
+        fontsUnavailable
+    };
+}
+//# sourceMappingURL=frames.js.map