@nodetool-ai/execution 0.8.1

package/dist/supervisor.js

@@ -0,0 +1,97 @@
+/** The shield that marks a supervised line. */
+export const INTERVENTION_MARK = "⛨";
+const ZERO_ACTIONS = {
+    retry: 0,
+    substitute: 0,
+    skip: 0,
+    end_stream: 0,
+    fail: 0
+};
+const ZERO_DECIDERS = {
+    agent: 0,
+    sticky: 0,
+    bounds: 0,
+    default: 0,
+    kernel: 0
+};
+export function summarizeInterventions(interventions) {
+    const byAction = { ...ZERO_ACTIONS };
+    const byDecider = { ...ZERO_DECIDERS };
+    let costUsd = 0;
+    for (const item of interventions) {
+        byAction[item.verdict.action] += 1;
+        byDecider[item.decidedBy] += 1;
+        costUsd += item.costUsd ?? 0;
+    }
+    return {
+        decisions: interventions.length,
+        agentDecisions: byDecider.agent,
+        byAction,
+        byDecider,
+        costUsd
+    };
+}
+/** Human-readable phrase for a verdict, in the product's four verbs. */
+function describeVerdict(intervention) {
+    const { verdict } = intervention;
+    switch (verdict.action) {
+        case "retry":
+            return "retried";
+        case "substitute":
+            return "repaired output";
+        case "skip":
+            return verdict.applyTo === "signature"
+                ? "skipped (and every matching failure)"
+                : "skipped";
+        case "end_stream":
+            // Presented under skip per design §4: the kernel action stays distinct,
+            // the record keeps it, the reader sees one verb family.
+            return "skipped the rest, kept what was produced";
+        case "fail":
+            return verdict.reason ? `failed — ${verdict.reason}` : "failed";
+    }
+}
+/**
+ * One inline line per intervention, e.g.
+ * `⛨ fetch-item [3] skipped — HTTP 404 (agent, $0.0041)`.
+ */
+export function formatInterventionLine(intervention) {
+    const { escalation } = intervention;
+    const item = escalation.invocationKey ? ` [${escalation.invocationKey}]` : "";
+    const cost = intervention.costUsd && intervention.costUsd > 0
+        ? `, $${intervention.costUsd.toFixed(4)}`
+        : "";
+    return (`${INTERVENTION_MARK} ${escalation.nodeId}${item} ` +
+        `${describeVerdict(intervention)} — ${escalation.detail} ` +
+        `(${intervention.decidedBy}${cost})`);
+}
+/**
+ * The run's closing supervised line, e.g.
+ * `⛨ supervised: 3 decisions, 2 skipped, 1 retried, +$0.0200`.
+ *
+ * Item counts (`198/200 items`) are a fan-out property no run-level record
+ * carries — the kernel counts invocations, not the batch a user thinks in —
+ * so a caller that knows its item total passes it in; otherwise the line
+ * reports decisions.
+ */
+export function formatSupervisedSummary(summary, items) {
+    const parts = [];
+    if (items)
+        parts.push(`${items.produced}/${items.total} items`);
+    const verbs = [
+        ["skip", "skipped"],
+        ["end_stream", "stream(s) ended early"],
+        ["retry", "retried"],
+        ["substitute", "repaired"],
+        ["fail", "failed"]
+    ];
+    for (const [action, label] of verbs) {
+        const n = summary.byAction[action];
+        if (n > 0)
+            parts.push(`${n} ${label}`);
+    }
+    parts.push(`${summary.decisions} decision${summary.decisions === 1 ? "" : "s"}`);
+    parts.push(`+$${summary.costUsd.toFixed(4)}`);
+    return `${INTERVENTION_MARK} supervised: ${parts.join(", ")}`;
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"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"}

package/dist/timeline-debug/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@nodetool-ai/execution/timeline-debug` — timeline validation + debug report.
+ *
+ * Pure, dependency-injected core: no DB, no ffmpeg, no browser. Hosts (the
+ * CLI `timeline` command today) resolve the target and write the bundle.
+ */
+export type { TimelineDebugIssue, TimelineValidation, TimelineInteractionRecord, TimelineDebugTarget, TimelineSequenceMeta, TimelineDebugReport } from "./types.js";
+export { validateTimelineSequence, collectStrippedPaths } from "./validate.js";
+export { buildTimelineDebugReport } from "./report.js";
+export { renderTimelineReportMarkdown } from "./markdown.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/timeline-debug/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/timeline-debug/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC"}

package/dist/timeline-debug/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@nodetool-ai/execution/timeline-debug` — timeline validation + debug report.
+ *
+ * Pure, dependency-injected core: no DB, no ffmpeg, no browser. Hosts (the
+ * CLI `timeline` command today) resolve the target and write the bundle.
+ */
+export { validateTimelineSequence, collectStrippedPaths } from "./validate.js";
+export { buildTimelineDebugReport } from "./report.js";
+export { renderTimelineReportMarkdown } from "./markdown.js";
+//# sourceMappingURL=index.js.map

package/dist/timeline-debug/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/timeline-debug/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC"}

package/dist/timeline-debug/legibility.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Text legibility: the two failures a document decides on its own.
+ *
+ * A title too small to read at delivery size, and a title whose colour is too
+ * close to what sits behind it, are the motion mistakes a frame preview catches
+ * and a structural check used to leave to the agent (F24). Both are warnings
+ * (R5): the heuristic is a floor, not a judgement, and the picture still
+ * renders.
+ *
+ * The check refuses to guess. A colour it cannot parse, a gradient fill, a
+ * translucent plate, a backdrop it cannot prove is behind the text — each ends
+ * the contrast check rather than producing a finding, because a legibility
+ * warning nobody can act on is worse than none.
+ */
+import type { TimelineDocument } from "@nodetool-ai/protocol/api-schemas/timeline.js";
+import type { TimelineDebugIssue } from "./types.js";
+/**
+ * Legibility findings for every text clip in the document. `frameHeight` is the
+ * sequence's pixel height — a font size is authored in sequence pixels, so the
+ * floor is a fraction of that and not of anything on the author's screen.
+ */
+export declare function checkLegibility(doc: TimelineDocument, frameHeight: number): TimelineDebugIssue[];
+//# sourceMappingURL=legibility.d.ts.map

package/dist/timeline-debug/legibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legibility.d.ts","sourceRoot":"","sources":["../../src/timeline-debug/legibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,+CAA+C,CAAC;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAoMrD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,gBAAgB,EACrB,WAAW,EAAE,MAAM,GAClB,kBAAkB,EAAE,CAuDtB"}

package/dist/timeline-debug/legibility.js

@@ -0,0 +1,240 @@
+/**
+ * Cap height a viewer can read on a phone. 2.5% of frame height is 27px at
+ * 1080p — the floor broadcast lower-third practice lands on, and the one the
+ * task list names.
+ */
+const MIN_TEXT_HEIGHT_FRAC = 0.025;
+/** WCAG 2.2 AA for large text. Titles are large text; body copy is not here. */
+const MIN_CONTRAST_RATIO = 3;
+/** The basic CSS colour names and their aliases, which authored styles use. */
+const NAMED_COLORS = new Map(Object.entries({
+    black: "#000000",
+    silver: "#c0c0c0",
+    gray: "#808080",
+    grey: "#808080",
+    white: "#ffffff",
+    maroon: "#800000",
+    red: "#ff0000",
+    purple: "#800080",
+    fuchsia: "#ff00ff",
+    magenta: "#ff00ff",
+    green: "#008000",
+    lime: "#00ff00",
+    olive: "#808000",
+    yellow: "#ffff00",
+    navy: "#000080",
+    blue: "#0000ff",
+    teal: "#008080",
+    aqua: "#00ffff",
+    cyan: "#00ffff"
+}));
+/**
+ * An opaque sRGB colour, or `null` for anything this check will not reason
+ * about — an unknown notation, and any colour carrying alpha, since what shows
+ * through a translucent fill is a compositing question and not a document one.
+ */
+function parseOpaqueColor(input) {
+    if (input === undefined)
+        return null;
+    const trimmed = input.trim();
+    const value = NAMED_COLORS.get(trimmed.toLowerCase()) ?? trimmed;
+    const hex = /^#([0-9a-f]{3,8})$/i.exec(value);
+    if (hex) {
+        const digits = hex[1];
+        if (digits.length === 3 || digits.length === 4) {
+            if (digits.length === 4 && digits[3] !== "f" && digits[3] !== "F") {
+                return null;
+            }
+            const [r, g, b] = [digits[0], digits[1], digits[2]].map((d) => parseInt(`${d}${d}`, 16));
+            return { r: r, g: g, b: b };
+        }
+        if (digits.length === 6 || digits.length === 8) {
+            if (digits.length === 8 && parseInt(digits.slice(6), 16) !== 255) {
+                return null;
+            }
+            return {
+                r: parseInt(digits.slice(0, 2), 16),
+                g: parseInt(digits.slice(2, 4), 16),
+                b: parseInt(digits.slice(4, 6), 16)
+            };
+        }
+        return null;
+    }
+    const rgb = /^rgba?\(\s*([0-9.]+)\s*[, ]\s*([0-9.]+)\s*[, ]\s*([0-9.]+)\s*(?:[,/]\s*([0-9.]+)\s*)?\)$/i.exec(value);
+    if (!rgb)
+        return null;
+    if (rgb[4] !== undefined && Number(rgb[4]) < 1)
+        return null;
+    const channels = [rgb[1], rgb[2], rgb[3]].map(Number);
+    if (channels.some((c) => !Number.isFinite(c) || c < 0 || c > 255))
+        return null;
+    return { r: channels[0], g: channels[1], b: channels[2] };
+}
+/** WCAG relative luminance of an sRGB triple. */
+function relativeLuminance({ r, g, b }) {
+    const linear = [r, g, b].map((channel) => {
+        const c = channel / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * linear[0] + 0.7152 * linear[1] + 0.0722 * linear[2];
+}
+/** WCAG contrast ratio, 1 (identical) to 21 (black on white). */
+function contrastRatio(a, b) {
+    const [light, dark] = [relativeLuminance(a), relativeLuminance(b)].sort((x, y) => y - x);
+    return (light + 0.05) / (dark + 0.05);
+}
+/** The colour a text clip's glyphs are filled with, or `null` for a gradient. */
+function textColor(clip) {
+    const style = clip.textStyle;
+    if (!style)
+        return undefined;
+    const fill = style.fill;
+    if (fill)
+        return fill.type === "solid" ? fill.color : undefined;
+    return style.color;
+}
+/**
+ * A shape clip that is provably behind the text at every instant the text is
+ * on screen, and provably covers it.
+ *
+ * "Provably" is doing the work. Track z is `1000 - index` (I9), so a higher
+ * index draws underneath; the shape must cover the whole frame, because the
+ * text's own block box needs a font measurement this check does not have; it
+ * must be opaque and solid-filled; and its window must contain the text's. A
+ * shape that only mostly qualifies is not reported — the check would then be
+ * naming a plate the title may not actually sit on.
+ */
+function backdropShapeColor(doc, text) {
+    const trackIndex = new Map(doc.tracks
+        .filter((track) => track.type !== "audio" && track.visible)
+        .map((track) => [track.id, track.index]));
+    const textIndex = trackIndex.get(text.trackId);
+    if (textIndex === undefined)
+        return undefined;
+    const textEndMs = text.startMs + text.durationMs;
+    let bestIndex = Number.POSITIVE_INFINITY;
+    let bestColor;
+    for (const clip of doc.clips) {
+        if (clip.mediaType !== "shape" || clip.hidden === true)
+            continue;
+        const index = trackIndex.get(clip.trackId);
+        if (index === undefined || index <= textIndex || index >= bestIndex) {
+            continue;
+        }
+        if ((clip.opacity ?? 1) < 1 || clip.mask || clip.matte)
+            continue;
+        if (clip.startMs > text.startMs)
+            continue;
+        if (clip.startMs + clip.durationMs < textEndMs)
+            continue;
+        const style = clip.shapeStyle;
+        if (!style || style.kind !== "rect")
+            continue;
+        // `shapeBox` defaults: a rect with no geometry covers the middle half of
+        // the frame, so an absent field is not "full frame".
+        if ((style.x ?? 0.25) > 0 || (style.y ?? 0.25) > 0)
+            continue;
+        if ((style.width ?? 0.5) < 1 || (style.height ?? 0.5) < 1)
+            continue;
+        const authoredFill = style.fillStyle ?? style.fill;
+        const fill = typeof authoredFill === "string"
+            ? authoredFill
+            : authoredFill?.type === "solid"
+                ? authoredFill.color
+                : undefined;
+        if (fill === undefined)
+            continue;
+        bestIndex = index;
+        bestColor = fill;
+    }
+    return bestColor;
+}
+/**
+ * Whether a picture clip is drawn under this text for any of its window.
+ *
+ * "Under" is the same z rule the backdrop check uses — a higher track index
+ * composites below — and any video or image clip counts, since a frame of it
+ * can be any colour. What it is *not* is a judgement about contrast: nothing
+ * in the document says what the picture looks like at that instant.
+ */
+function pictureUnder(doc, text) {
+    const trackIndex = new Map(doc.tracks
+        .filter((track) => track.type !== "audio" && track.visible)
+        .map((track) => [track.id, track.index]));
+    const textIndex = trackIndex.get(text.trackId);
+    if (textIndex === undefined)
+        return false;
+    const textEndMs = text.startMs + text.durationMs;
+    return doc.clips.some((clip) => {
+        if (clip.mediaType !== "video" && clip.mediaType !== "image")
+            return false;
+        if (clip.hidden === true)
+            return false;
+        const index = trackIndex.get(clip.trackId);
+        if (index === undefined || index <= textIndex)
+            return false;
+        return clip.startMs < textEndMs && clip.startMs + clip.durationMs > text.startMs;
+    });
+}
+/**
+ * Legibility findings for every text clip in the document. `frameHeight` is the
+ * sequence's pixel height — a font size is authored in sequence pixels, so the
+ * floor is a fraction of that and not of anything on the author's screen.
+ */
+export function checkLegibility(doc, frameHeight) {
+    const issues = [];
+    for (const clip of doc.clips) {
+        const style = clip.textStyle;
+        if (clip.mediaType !== "text" || !style || clip.hidden === true)
+            continue;
+        const label = clip.name || clip.id;
+        const at = { clipId: clip.id, trackId: clip.trackId };
+        const minPx = frameHeight * MIN_TEXT_HEIGHT_FRAC;
+        if (style.fontSizePx < minPx) {
+            issues.push({
+                severity: "warning",
+                code: "text_illegible",
+                message: `Clip "${label}" sets ${Math.round(style.fontSizePx)}px type in a ${frameHeight}px frame — under ${(MIN_TEXT_HEIGHT_FRAC * 100).toFixed(1)}% of frame height (${Math.round(minPx)}px), which is unreadable on a phone.`,
+                path: "textStyle.fontSizePx",
+                ...at
+            });
+        }
+        // Type drawn straight onto moving picture with nothing behind it is the
+        // case the contrast check gives up on — the frame decides it, not the
+        // document. Saying nothing made a clean validation read as approval, so
+        // the check reports that it could not judge and names the two fixes and
+        // the tool that answers it.
+        const backed = style.background !== undefined ||
+            style.stroke !== undefined ||
+            backdropShapeColor(doc, clip) !== undefined;
+        if (!backed && pictureUnder(doc, clip)) {
+            issues.push({
+                severity: "warning",
+                code: "text_backing_unproven",
+                message: `Clip "${label}" draws over picture with no scrim, plate or outline, so nothing here decides whether it is readable — render the frame with preview_timeline_frame and look, or give it textStyle.background or textStyle.stroke.`,
+                path: "textStyle",
+                ...at
+            });
+        }
+        const foreground = parseOpaqueColor(textColor(clip));
+        if (!foreground)
+            continue;
+        const plate = style.background?.color;
+        const behind = plate ?? backdropShapeColor(doc, clip);
+        const background = parseOpaqueColor(behind);
+        if (!background)
+            continue;
+        const ratio = contrastRatio(foreground, background);
+        if (ratio >= MIN_CONTRAST_RATIO)
+            continue;
+        issues.push({
+            severity: "warning",
+            code: "text_illegible",
+            message: `Clip "${label}" draws ${textColor(clip)} on ${behind}${plate ? " (its own background plate)" : " (the shape clip behind it)"} — a contrast ratio of ${ratio.toFixed(2)}:1, under the ${MIN_CONTRAST_RATIO}:1 large-text floor.`,
+            path: plate ? "textStyle.background.color" : "textStyle.color",
+            ...at
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=legibility.js.map

package/dist/timeline-debug/legibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legibility.js","sourceRoot":"","sources":["../../src/timeline-debug/legibility.ts"],"names":[],"mappings":"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"}

package/dist/timeline-debug/markdown.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Renders a `TimelineDebugReport` as human-readable Markdown for the bundle.
+ */
+import type { TimelineDebugReport } from "./types.js";
+export declare function renderTimelineReportMarkdown(report: TimelineDebugReport): string;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/timeline-debug/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/timeline-debug/markdown.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAsB,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAiG1E,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAsDhF"}

package/dist/timeline-debug/markdown.js

@@ -0,0 +1,103 @@
+import { isString } from "../predicates.js";
+import { isObjectLike } from "../predicates.js";
+const short = (value, max = 120) => {
+    if (value === undefined)
+        return "—";
+    let s;
+    try {
+        s = isString(value) ? value : JSON.stringify(value);
+    }
+    catch {
+        s = String(value);
+    }
+    s = (s ?? "null").replace(/\s+/g, " ");
+    return s.length > max ? `${s.slice(0, max)}…` : s;
+};
+const where = (issue) => {
+    const parts = [
+        issue.clipId ? `clip \`${issue.clipId}\`` : null,
+        issue.trackId ? `track \`${issue.trackId}\`` : null,
+        issue.path ? `\`${issue.path}\`` : null
+    ].filter((part) => part !== null);
+    return parts.length > 0 ? parts.join(" · ") : "—";
+};
+function issueTable(title, issues, lines) {
+    if (issues.length === 0)
+        return;
+    lines.push("", `## ${title}`, "");
+    lines.push("| Severity | Code | Where | Message |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const issue of issues) {
+        lines.push(`| ${issue.severity} | \`${issue.code}\` | ${where(issue)} | ${short(issue.message, 300)} |`);
+    }
+}
+const asRecord = (value) => isObjectLike(value) ? value : null;
+/**
+ * The bridge snapshot carries full `documentTracks`/`documentClips` for the
+ * report's `finalDocument`; the markdown only needs the reduced view, so
+ * render per-track/per-clip lines instead of one giant JSON dump.
+ */
+function finalStateLines(state) {
+    const record = asRecord(state);
+    const tracks = Array.isArray(record?.tracks) ? record.tracks : null;
+    const clips = Array.isArray(record?.clips) ? record.clips : null;
+    if (!tracks || !clips)
+        return [`- ${short(state, 600)}`];
+    const lines = [];
+    for (const track of tracks) {
+        const onTrack = clips.filter((clip) => clip.trackId === track.id);
+        lines.push(`- track \`${track.id ?? "?"}\` (${track.type ?? "?"}, index ${track.index ?? "?"})` +
+            `${track.name ? ` "${track.name}"` : ""} — ${onTrack.length} clip(s)`);
+        for (const clip of onTrack) {
+            const end = (clip.startMs ?? 0) + (clip.durationMs ?? 0);
+            lines.push(`  - \`${clip.id ?? "?"}\`${clip.name ? ` "${clip.name}"` : ""} ` +
+                `${clip.mediaType ?? "?"} ${clip.startMs ?? 0}–${end}ms`);
+        }
+    }
+    const orphaned = clips.filter((clip) => !tracks.some((track) => track.id === clip.trackId));
+    for (const clip of orphaned) {
+        lines.push(`- orphaned clip \`${clip.id ?? "?"}\` on missing track \`${clip.trackId ?? "?"}\``);
+    }
+    return lines;
+}
+export function renderTimelineReportMarkdown(report) {
+    const lines = [];
+    const title = report.target.name ?? report.target.ref;
+    lines.push(`# Timeline debug: ${title}`);
+    lines.push("");
+    lines.push(`${report.verdict.ok ? "✅" : "❌"} ${report.verdict.headline}`);
+    lines.push("");
+    lines.push(`Target: \`${report.target.ref}\` (${report.target.kind})`);
+    lines.push(`Sequence: ${report.meta.width}×${report.meta.height} @ ${report.meta.fps}fps · ` +
+        `${report.meta.durationMs}ms · ${report.meta.trackCount} track(s), ` +
+        `${report.meta.clipCount} clip(s)`);
+    if (report.verdict.issues.length > 0) {
+        lines.push("", "## Issues", "");
+        for (const issue of report.verdict.issues)
+            lines.push(`- ${issue}`);
+    }
+    issueTable("Validation", [...report.validation.errors, ...report.validation.warnings], lines);
+    if (report.interactions.length > 0) {
+        lines.push("", "## Interactions", "");
+        lines.push("| Tool | OK | Input | Error |");
+        lines.push("| --- | --- | --- | --- |");
+        for (const step of report.interactions) {
+            lines.push(`| \`${step.tool}\` | ${step.ok ? "✅" : "❌"} | ${short(step.input)} | ${step.error ? short(step.error, 200) : "—"} |`);
+        }
+    }
+    if (report.finalValidation) {
+        issueTable("Validation after edits", [...report.finalValidation.errors, ...report.finalValidation.warnings], lines);
+    }
+    if (report.finalState !== undefined) {
+        lines.push("", "## Final state", "");
+        lines.push(...finalStateLines(report.finalState));
+    }
+    if (report.notSimulated.length > 0) {
+        lines.push("", "## Not simulated", "");
+        for (const entry of report.notSimulated)
+            lines.push(`- ${entry}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=markdown.js.map

package/dist/timeline-debug/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/timeline-debug/markdown.ts"],"names":[],"mappings":"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"}

package/dist/timeline-debug/motion.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Motion checks: what the animation compiler quietly does to a clip whose
+ * authored motion does not fit it, and what the sampler quietly discards when
+ * two animations drive the same absolute channel.
+ *
+ * Everything here reads the compiler's own output (`compileClipAnimations`)
+ * rather than restating its window math, so a rule change in
+ * `packages/timeline/src/animation/compile.ts` moves these findings with it. A
+ * document whose animations all fit produces nothing.
+ */
+import type { TimelineClip } from "@nodetool-ai/protocol/api-schemas/timeline.js";
+import { type Canvas } from "@nodetool-ai/timeline";
+import type { TimelineDebugIssue } from "./types.js";
+/**
+ * Every motion finding for one clip. `canvas` is the sequence's pixel size,
+ * which the compiler needs to resolve a preset's normalized distances and to
+ * count the wrapped lines of a `"line"` stagger.
+ */
+export declare function checkClipMotion(clip: TimelineClip, canvas: Canvas): TimelineDebugIssue[];
+//# sourceMappingURL=motion.d.ts.map

package/dist/timeline-debug/motion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../../src/timeline-debug/motion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+CAA+C,CAAC;AAClF,OAAO,EAQL,KAAK,MAAM,EAIZ,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAwYrD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,MAAM,GACb,kBAAkB,EAAE,CAyBtB"}