frameyard 0.0.0-stage → 0.2.0

package/dist/runtime/index.js

@@ -0,0 +1,289 @@
+import { normalizeComposition, resolveAudioClips, resolveProps, resolveTranscriptClips, } from "../contracts.js";
+import { FrameyardError, isFrameyardError } from "../errors.js";
+import { frameToMilliseconds } from "./clock.js";
+export { frameToMilliseconds, frameToSeconds } from "./clock.js";
+export { random } from "./random.js";
+function isThenable(value) {
+    return ((typeof value === "object" || typeof value === "function") &&
+        value !== null &&
+        typeof value.then === "function");
+}
+function wrapCompositionError(phase, frame, error) {
+    if (isFrameyardError(error)) {
+        return error;
+    }
+    const location = frame === null ? "" : ` at frame ${frame}`;
+    return new FrameyardError("COMPOSITION_ERROR", `Composition ${phase}() failed${location}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+}
+function seekAnimations(container, frame, fps, onTransition) {
+    if (typeof container.getAnimations !== "function") {
+        return;
+    }
+    const time = frameToMilliseconds(frame, fps);
+    let sawTransition = false;
+    for (const animation of container.getAnimations({ subtree: true })) {
+        if (typeof CSSTransition !== "undefined" && animation instanceof CSSTransition) {
+            sawTransition = true;
+        }
+        try {
+            animation.pause();
+            animation.currentTime = time;
+        }
+        catch (error) {
+            throw new FrameyardError("COMPOSITION_ERROR", `A CSS or Web Animation could not be seeked to frame ${frame}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    if (sawTransition) {
+        onTransition?.();
+    }
+}
+function installDiagnosticsClock() {
+    const warnings = new Set();
+    const originalRandom = Math.random;
+    const originalDateNow = Date.now;
+    const originalSetTimeout = window.setTimeout;
+    const originalSetInterval = window.setInterval;
+    const originalRaf = window.requestAnimationFrame;
+    const perf = performance;
+    const originalPerfNow = perf.now;
+    let perfPatched = false;
+    Math.random = () => {
+        warnings.add("Math.random()");
+        return originalRandom();
+    };
+    Date.now = () => {
+        warnings.add("Date.now()");
+        return originalDateNow();
+    };
+    window.setTimeout = ((handler, timeout, ...args) => {
+        warnings.add("setTimeout()");
+        return originalSetTimeout(handler, timeout, ...args);
+    });
+    window.setInterval = ((handler, timeout, ...args) => {
+        warnings.add("setInterval()");
+        return originalSetInterval(handler, timeout, ...args);
+    });
+    window.requestAnimationFrame = ((callback) => {
+        warnings.add("requestAnimationFrame()");
+        return originalRaf(callback);
+    });
+    try {
+        perf.now = () => {
+            warnings.add("performance.now()");
+            return originalPerfNow();
+        };
+        perfPatched = true;
+    }
+    catch {
+        // Some engines make performance.now non-writable; skip that signal.
+    }
+    return {
+        warnings,
+        restore() {
+            Math.random = originalRandom;
+            Date.now = originalDateNow;
+            window.setTimeout = originalSetTimeout;
+            window.setInterval = originalSetInterval;
+            window.requestAnimationFrame = originalRaf;
+            if (perfPatched) {
+                perf.now = originalPerfNow;
+            }
+        },
+    };
+}
+function diagnosticsMessage(scope, frame, warning) {
+    const location = frame === null ? "" : ` at frame ${frame}`;
+    switch (warning) {
+        case "Math.random()":
+            return `${scope}${location} used Math.random(); use random("stable:key") for deterministic values.`;
+        case "Date.now()":
+        case "performance.now()":
+            return `${scope}${location} read ${warning}; derive time from the frame and frame rate.`;
+        default:
+            return `${scope}${location} used ${warning}; drive animation from update({ frame }).`;
+    }
+}
+function withDiagnosticsSync(scope, frame, diagnostics, callback) {
+    if (!diagnostics) {
+        return callback();
+    }
+    const clock = installDiagnosticsClock();
+    try {
+        return callback();
+    }
+    finally {
+        clock.restore();
+        for (const warning of clock.warnings) {
+            try {
+                diagnostics(diagnosticsMessage(scope, frame, warning));
+            }
+            catch {
+                // Diagnostics must never affect composition execution.
+            }
+        }
+    }
+}
+async function withDiagnosticsAsync(scope, diagnostics, callback) {
+    if (!diagnostics) {
+        return callback();
+    }
+    const clock = installDiagnosticsClock();
+    try {
+        return await callback();
+    }
+    finally {
+        clock.restore();
+        for (const warning of clock.warnings) {
+            try {
+                diagnostics(diagnosticsMessage(scope, null, warning));
+            }
+            catch {
+                // Diagnostics must never affect composition execution.
+            }
+        }
+    }
+}
+async function disposeAfterFailure(composition) {
+    try {
+        const result = composition.dispose?.();
+        if (isThenable(result)) {
+            await result;
+        }
+    }
+    catch {
+        // Cleanup after a failed mount or first update must not mask the failure.
+    }
+}
+async function waitForMountedAssets(container) {
+    await document.fonts.ready;
+    const images = Array.from(container.querySelectorAll("img"));
+    await Promise.all(images.map(async (image) => {
+        if (!image.currentSrc && !image.src) {
+            return;
+        }
+        try {
+            await image.decode();
+        }
+        catch (error) {
+            throw new FrameyardError("ASSET_NOT_FOUND", `Could not load image asset "${image.currentSrc || image.src}".`, {
+                cause: error,
+            });
+        }
+    }));
+}
+/** Imports a composition module through the preview server and normalizes its default export. */
+export async function loadCompositionModule(url) {
+    let module;
+    try {
+        module = (await import(/* @vite-ignore */ url));
+    }
+    catch (error) {
+        throw new FrameyardError("COMPOSITION_INVALID", `Could not load composition module ${url}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (module.default === undefined) {
+        throw new FrameyardError("COMPOSITION_INVALID", `Composition module ${url} has no default export.`);
+    }
+    return normalizeComposition(module.default);
+}
+/**
+ * Mounts a composition and returns a seekable runtime. Mounting and asset
+ * loading complete before this promise resolves; every subsequent seek is
+ * synchronous and independent of previously visited frames.
+ */
+export async function createCompositionRuntime(options) {
+    const composition = normalizeComposition(options.composition);
+    const props = resolveProps(composition, options.props);
+    const audioClips = resolveAudioClips(composition, props);
+    const transcriptClips = resolveTranscriptClips(composition, props);
+    const { container } = options;
+    const diagnostics = options.diagnostics;
+    let warnedTransition = false;
+    const warnTransition = () => {
+        if (!diagnostics || warnedTransition) {
+            return;
+        }
+        warnedTransition = true;
+        try {
+            diagnostics("Composition uses CSS transitions; derive visual styles from frame and props in update() instead.");
+        }
+        catch {
+            // Diagnostics must never affect composition execution.
+        }
+    };
+    container.replaceChildren();
+    try {
+        await withDiagnosticsAsync("Composition mount()", diagnostics, () => composition.mount({ container, props }));
+    }
+    catch (error) {
+        await disposeAfterFailure(composition);
+        container.replaceChildren();
+        throw wrapCompositionError("mount", null, error);
+    }
+    try {
+        await waitForMountedAssets(container);
+    }
+    catch (error) {
+        await disposeAfterFailure(composition);
+        container.replaceChildren();
+        throw error;
+    }
+    let frame = 0;
+    let disposed = false;
+    function seek(targetFrame) {
+        if (disposed) {
+            throw new FrameyardError("COMPOSITION_ERROR", "Cannot seek a disposed composition runtime.");
+        }
+        if (!Number.isInteger(targetFrame) || targetFrame < 0 || targetFrame >= composition.durationInFrames) {
+            throw new FrameyardError("FRAME_OUT_OF_RANGE", `Frame ${targetFrame} is outside the valid range 0..${composition.durationInFrames - 1}.`);
+        }
+        try {
+            const result = withDiagnosticsSync("Composition update()", targetFrame, diagnostics, () => composition.update({ frame: targetFrame, props }));
+            if (isThenable(result)) {
+                throw new FrameyardError("COMPOSITION_UPDATE_ASYNC", `Composition update() must be synchronous, but it returned a promise at frame ${targetFrame}.`);
+            }
+            seekAnimations(container, targetFrame, composition.fps, warnTransition);
+        }
+        catch (error) {
+            throw wrapCompositionError("update", targetFrame, error);
+        }
+        frame = targetFrame;
+    }
+    try {
+        seek(0);
+    }
+    catch (error) {
+        await disposeAfterFailure(composition);
+        container.replaceChildren();
+        throw error;
+    }
+    return Object.freeze({
+        composition,
+        props,
+        audioClips,
+        transcriptClips,
+        get frame() {
+            return frame;
+        },
+        seek,
+        async dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            try {
+                if (composition.dispose) {
+                    const result = composition.dispose();
+                    if (isThenable(result)) {
+                        await result;
+                    }
+                }
+            }
+            catch (error) {
+                container.replaceChildren();
+                throw wrapCompositionError("dispose", null, error);
+            }
+            container.replaceChildren();
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

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

package/dist/runtime/random.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns a deterministic value in [0, 1) derived only from the supplied key.
+ *
+ * The calculation is stateless: call order and previous frames cannot affect
+ * the result. Use stable, descriptive keys such as `random("star:17:y")`.
+ */
+export declare function random(key: string): number;
+//# sourceMappingURL=random.d.ts.map

package/dist/runtime/random.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../../src/runtime/random.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAgB1C"}

package/dist/runtime/random.js

@@ -0,0 +1,21 @@
+/**
+ * Returns a deterministic value in [0, 1) derived only from the supplied key.
+ *
+ * The calculation is stateless: call order and previous frames cannot affect
+ * the result. Use stable, descriptive keys such as `random("star:17:y")`.
+ */
+export function random(key) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < key.length; index += 1) {
+        hash ^= key.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    // MurmurHash3's 32-bit finalizer spreads adjacent keys across the range.
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 0x7feb352d);
+    hash ^= hash >>> 15;
+    hash = Math.imul(hash, 0x846ca68b);
+    hash ^= hash >>> 16;
+    return (hash >>> 0) / 0x1_0000_0000;
+}
+//# sourceMappingURL=random.js.map

package/dist/runtime/random.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.js","sourceRoot":"","sources":["../../src/runtime/random.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,GAAW;IAChC,IAAI,IAAI,GAAG,UAAU,CAAC;IAEtB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACnD,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;IAED,yEAAyE;IACzE,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;IACpB,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACnC,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;IACpB,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACnC,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;IAEpB,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,aAAa,CAAC;AACtC,CAAC"}

package/dist/scaffold.d.ts

@@ -0,0 +1,3 @@
+export declare function scaffoldFiles(projectName: string): Record<string, string>;
+export declare const SCAFFOLD_NEXT: string[];
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AA8JA,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBzE;AAED,eAAO,MAAM,aAAa,UAKzB,CAAC"}

package/dist/scaffold.js

@@ -0,0 +1,176 @@
+import { VERSION } from "./version.js";
+const AGENTS_GUIDE = `# AGENTS.md
+
+This project produces deterministic, parameterized video with Frameyard. Follow this guide when editing or rendering it.
+
+## Project layout
+
+- \`video.config.js\` explicitly maps composition IDs to entry modules. There is no directory scanning; a new composition is invisible until it is listed.
+- \`package.json\` pins the CLI version in \`dev\`, \`check\`, \`render\`, and \`still\` scripts. Run \`dev\` with \`npm run dev\` or \`pnpm dev\`; for the others, pass the composition id: \`npm run check -- hello\` (npm) or \`pnpm check hello\` (pnpm).
+- \`compositions/\` contains native JavaScript ES modules. Import bare \`frameyard\` and \`frameyard/runtime\`; the preview server supplies the import map.
+- \`props/\` contains JSON props, merged shallowly over \`defaultProps\` and deep-frozen.
+- \`assets/\` (create it when needed) contains audio, images, fonts, and generated assets.
+
+\`width\`, \`height\`, \`fps\`, and \`durationInFrames\` are fixed composition metadata. Do not derive them from props.
+
+## Agent workflow
+
+1. Read \`video.config.js\`, the composition source, and the props file before changing behavior.
+2. Author the composition or props with native HTML, CSS, SVG, Canvas 2D, and JavaScript. Do not add a bundling step.
+3. Validate every frame: \`npx frameyard check <id> --json\`. Use \`--props <file>\` to validate a specific props file.
+4. Inspect a representative frame: \`npx frameyard still <id> --frame <n> --out <file.png> --json\`, then view the PNG when the host supports images. State explicitly when visual inspection is not possible.
+5. Render: \`npx frameyard render <id> --props <file> --out <file.mp4> --json\`.
+6. Report the composition, props, validation result, still path and inspection status, video path, and any failure. Never claim success when \`check\` fails, a still is missing, or a render exits nonzero.
+
+## Commands
+
+\`\`\`sh
+npx frameyard dev
+npx frameyard doctor --json
+npx frameyard check hello --json
+npx frameyard still hello --frame 42 --out hello-42.png --json
+npx frameyard render hello --props props/hello.json --out hello.mp4 --json
+\`\`\`
+
+- Use \`--json\` for non-interactive commands. Parse stdout as the structured result; treat stderr as progress and diagnostics.
+- Use \`--project <dir>\` when running outside the project root.
+- \`still\` and \`render\` replace existing outputs only with \`--overwrite\`. Generated assets are replaced only with \`--force\`, and only with user approval.
+
+## Determinism rules
+
+- A frame may depend only on its integer \`frame\`, immutable \`props\`, and assets loaded before frame production.
+- \`mount()\` may await loading work. \`update({ frame, props })\` is synchronous and seek-safe. \`dispose()\` releases resources.
+- Keep mutable state in module-scope variables, not on \`this\`.
+- Use \`random("stable:key")\` from \`frameyard/runtime\` for randomness.
+- Never use \`Math.random()\`, \`Date.now()\`, \`performance.now()\`, timers, independent \`requestAnimationFrame()\` loops, CSS transitions, or state left from a previously visited frame as animation inputs.
+- CSS \`@keyframes\` and the Web Animations API are valid; the runtime seeks them.
+- Load remote data, fonts, and images during \`mount()\` or before the first frame. Network requests are blocked during capture; a \`fetch()\` from \`update()\` is a bug.
+- Redraw Canvas 2D from the current frame.
+
+## Audio and transcripts
+
+- Audio clips are placed by composition frames and trimmed by seconds. Frameyard does not time-stretch audio or change composition duration to fit it.
+- Produce speech with \`npx frameyard tts\` and transcripts with \`npx frameyard transcribe\`; never call \`qwen-tts\` or \`whisper-cli\` directly, and never run inference inside \`mount()\` or \`update()\`.
+- Do not overwrite or regenerate generated assets without explicit approval.
+- \`words: true\` requires measured word timings; never interpolate segment timings.
+- Commit \`frameyard.assets.json\` when present; do not edit hashes or manifest entries by hand.
+
+The official \`frameyard\` agent skill contains the full host-neutral contract. Install it with \`npx skills add vladiantio/frameyard\` or see the \`skills/frameyard/\` directory in the \`frameyard\` npm package. This file is the project-local summary.
+
+This project was scaffolded with frameyard ${VERSION}. \`npx frameyard\` resolves the latest published version; run \`npx frameyard@${VERSION}\` when you need the CLI version that scaffolded the project.
+`;
+const PROJECT_README = `# My Frameyard project
+
+Coding agents should read \`AGENTS.md\` for the project rules and the check, still, and render workflow.
+
+Start the preview:
+
+\`\`\`sh
+npx frameyard dev
+\`\`\`
+
+Validate and render:
+
+\`\`\`sh
+npx frameyard doctor
+npx frameyard check hello
+npx frameyard render hello --props props/hello.json --out hello.mp4
+\`\`\`
+
+Or run the pinned scripts from \`package.json\`:
+
+\`\`\`sh
+npm run dev
+npm run check -- hello
+npm run render -- hello --props props/hello.json --out hello.mp4
+npm run still -- hello --frame 42 --out hello-42.png
+\`\`\`
+`;
+const SCAFFOLD_TEMPLATES = {
+    "video.config.js": `export default {\n  compositions: {\n    hello: "./compositions/hello.js",\n  },\n};\n`,
+    "props/hello.json": `${JSON.stringify({ title: "Hello, Frameyard", accent: "#b8f36b" }, null, 2)}\n`,
+    "AGENTS.md": AGENTS_GUIDE,
+    "README.md": PROJECT_README,
+    "compositions/hello.js": `import { defineComposition } from "frameyard";
+
+let title;
+let sweep;
+let glow;
+
+export default defineComposition({
+  width: 1280,
+  height: 720,
+  fps: 30,
+  durationInFrames: 150,
+  defaultProps: { title: "Hello, Frameyard", accent: "#b8f36b" },
+  validateProps(props) {
+    const errors = [];
+    if (typeof props.title !== "string") errors.push("title must be a string");
+    if (typeof props.accent !== "string") errors.push("accent must be a string");
+    return errors;
+  },
+  mount({ container, props }) {
+    container.style.setProperty("--accent", props.accent);
+    container.innerHTML =
+      '<style>' +
+      '#hello { position: relative; width: 100%; height: 100%; display: grid; place-items: center; overflow: hidden; background: #0b0d10; color: #e8edf3; font-family: Inter, system-ui, sans-serif; }' +
+      '#hello h1 { position: relative; margin: 0; font-size: 96px; letter-spacing: -0.04em; }' +
+      '#hello p { position: relative; margin: 18px 0 0; color: #8a97a6; font-size: 26px; }' +
+      '#glow { position: absolute; width: 520px; height: 520px; border-radius: 50%; background: var(--accent); filter: blur(120px); opacity: 0.16; }' +
+      '#sweep { position: absolute; left: 0; bottom: 0; width: 0%; height: 4px; background: var(--accent); }' +
+      '</style>' +
+      '<div id="hello"><div id="glow"></div><div style="position: relative; text-align: center"><h1 id="title"></h1><p>Deterministic video, authored on the web.</p></div><div id="sweep"></div></div>';
+    title = container.querySelector("#title");
+    sweep = container.querySelector("#sweep");
+    glow = container.querySelector("#glow");
+  },
+  update({ frame, props }) {
+    title.textContent = props.title;
+    const intro = Math.min(1, frame / 24);
+    title.style.opacity = String(intro);
+    title.style.transform = "translateY(" + (1 - intro) * 28 + "px)";
+    glow.style.transform =
+      "translate(" + Math.sin(frame / 26) * 120 + "px," + Math.cos(frame / 34) * 80 + "px)";
+    sweep.style.width = (frame / 149) * 100 + "%";
+  },
+  dispose() {
+    title = undefined;
+    sweep = undefined;
+    glow = undefined;
+  },
+});
+`,
+};
+// Keep the generated package name valid for npm and pnpm.
+function packageName(projectName) {
+    const normalized = projectName
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[._-]+|[._-]+$/g, "")
+        .slice(0, 214)
+        .replace(/[._-]+$/g, "");
+    return normalized === "" ? "frameyard-project" : normalized;
+}
+export function scaffoldFiles(projectName) {
+    return {
+        "package.json": `${JSON.stringify({
+            name: packageName(projectName),
+            private: true,
+            type: "module",
+            scripts: {
+                dev: `npx --yes frameyard@${VERSION} dev`,
+                check: `npx --yes frameyard@${VERSION} check`,
+                render: `npx --yes frameyard@${VERSION} render`,
+                still: `npx --yes frameyard@${VERSION} still`,
+            },
+        }, null, 2)}\n`,
+        ...SCAFFOLD_TEMPLATES,
+    };
+}
+export const SCAFFOLD_NEXT = [
+    "npx frameyard doctor",
+    "npx frameyard dev",
+    "npx frameyard check hello",
+    "npx frameyard render hello --out hello.mp4",
+];
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6CA0DwB,OAAO,kFAAkF,OAAO;CAC5I,CAAC;AAEF,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BtB,CAAC;AAEF,MAAM,kBAAkB,GAA2B;IACjD,iBAAiB,EAAE,wFAAwF;IAC3G,kBAAkB,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI;IACpG,WAAW,EAAE,YAAY;IACzB,WAAW,EAAE,cAAc;IAC3B,uBAAuB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgD1B;CACA,CAAC;AAEF,0DAA0D;AAC1D,SAAS,WAAW,CAAC,WAAmB;IACtC,MAAM,UAAU,GAAG,WAAW;SAC3B,WAAW,EAAE;SACb,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC;SAC9B,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;SACb,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC3B,OAAO,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,UAAU,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,OAAO;QACL,cAAc,EAAE,GAAG,IAAI,CAAC,SAAS,CAC/B;YACE,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC;YAC9B,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE;gBACP,GAAG,EAAE,uBAAuB,OAAO,MAAM;gBACzC,KAAK,EAAE,uBAAuB,OAAO,QAAQ;gBAC7C,MAAM,EAAE,uBAAuB,OAAO,SAAS;gBAC/C,KAAK,EAAE,uBAAuB,OAAO,QAAQ;aAC9C;SACF,EACD,IAAI,EACJ,CAAC,CACF,IAAI;QACL,GAAG,kBAAkB;KACtB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,sBAAsB;IACtB,mBAAmB;IACnB,2BAA2B;IAC3B,4CAA4C;CAC7C,CAAC"}

package/dist/server/preview-html.d.ts

@@ -0,0 +1,2 @@
+export declare function renderPreviewHtml(): string;
+//# sourceMappingURL=preview-html.d.ts.map

package/dist/server/preview-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-html.d.ts","sourceRoot":"","sources":["../../src/server/preview-html.ts"],"names":[],"mappings":"AAWA,wBAAgB,iBAAiB,IAAI,MAAM,CA6N1C"}