wizards 0.2.20 → 0.2.21

package/apps/runtime/dist/authoring/guide.js

@@ -67,6 +67,8 @@ type Field = {
                                 //   every file costs something later (a video clip per photo)
   camera?: boolean              // file: also offer the camera, for papers the person has not scanned (image always offers it)
   video?: boolean               // file: the camera also records a short clip (up to 30 s); the clip is a file like any other
+  listen?: boolean              // file: a recording (video/audio) is listened to before the next step: {{field.speech}} gives what is
+                                //   said piece by piece between pauses, with exact times "[12.40–15.10] text" — to cut slips and pauses
   scan?: boolean                // text: a "scan" button fills it from a QR code or barcode (serial number, ticket, article number)
   connection?: connectionId     // kind "connection": the page shows "connect your account"; with required the person must connect
   list?: listId                 // kind "list": the page shows that stored list for the person to check, correct and extend
@@ -114,7 +116,7 @@ type GenerateStep = {
   prompt: string                // the brief, with {{templates}}; for "voice" the exact text that is read aloud
   options?: { aspectRatio?: "1:1"|"16:9"|"9:16"|"4:5"|"3:2"|"2:3", duration?: 4–10 (video seconds; 4, 6 or 8 are safe),
               resolution?: "720p"|"480p",   // video: 720p by default and at most; 480p for drafts and many clips
-              style?: string,   // image/video: the look · voice: how to speak ("ruhig, warm")
+              style?: string,   // image/video: the look · voice: how to speak ("ruhig, warm"; may name a field: "{{voiceStyle}}")
               template?: "invoice"|"offer"|"briefing"|"letter"|"report"|"free" }   // template for documents
   referenceImage?: fieldId | stepId   // the image the image/video starts from: an image field, or an earlier step that made images
   each?: fieldId | stepId | "steps.<id>.<key>"
@@ -136,17 +138,38 @@ type WidgetStep = {
   video?: boolean               // a FILM: the timeline is rendered to an MP4 WITH SOUND when the step runs; the person sees and
                                 //   downloads that video. data may then name generate steps: "steps.<id>" of an image / video / voice
                                 //   step arrives as a URL (a list of URLs for a step with "each").
+                                //   "steps.<agentStepId>.assets" gives the pictures an agent step kept (browser screenshots
+                                //   with save, export_file, generate_image) as { assetId: URL }; the step's JSON names them by id.
   working?: string
 }
 // an interactive HTML app written ONCE into the workspace; every run only brings new data (no model call, no cost)
 
+type FilmStep = {
+  type: "film"
+  brief: string                 // a template: what the film is — story, look, length, what to use. The kit carries the craft.
+  skills?: string[]             // skill packages the client reads; default ["hyperframes"]. A workspace package: "skills/<name>" (has SKILL.md)
+  kit?: string                  // workspace path of a STYLE KIT (.zip): a showreel made once with its rules (frame.md),
+                                //   techniques (SHOWCASE.md), helpers and stills — the bar every film of this wizard reaches
+  inputs?: { [name]: string }   // name (lowercase, -) → fieldId | steps.stepId: voice lines, pictures, uploads become files in
+                                //   input/<name>/, text in input/<name>.md, json in input/<name>.json
+  format?: "16:9" | "9:16" | "1:1"
+  seconds?: number              // about how long
+  model?: "standard" | "high"   // default standard
+  effort?: Effort
+  working?: string
+}
+// the AI client installed on the person's computer (Claude Code) writes the film as code in a folder of its own, with the
+// skills, the kit, the space's brand (colours, logo, facts) and the inputs; it looks at its frames and fixes them; the
+// runtime renders the MP4. It runs only where Claude Code is set up as the AI subscription — never on credits or in the
+// cloud — and takes 10–40 minutes. Sounds come from a fixed catalog (CC0); voice comes from a generate voice step before it.
+
 type ReviewStep = { type: "review", show: (stepId | "lists.<listId>")[], edit?: boolean, regenerate?: boolean }
 // shows earlier outputs; the person accepts, edits text outputs (edit), or asks for a new version with a note (regenerate)
 // a shown list is edited in place by the person
 
 type ResultStep = { type: "result", message?: string, deliverables: { from: stepId | "lists.<listId>", label?, formats: Format[] }[] }
 // formats per source: image→png · video→mp4 (several results: zip) · voice→mp3 · document→pdf docx html md png · dashboard→html pdf png
-//                     film widget (video: true)→mp4 png
+//                     film widget (video: true)→mp4 png · film→mp4
 //                     widget→html png pdf mp4 json (mp4 only when the widget registers a timeline)
 //                     agent text/markdown→md txt docx pdf html · agent json→json csv xlsx md (xlsx: one sheet per table)
 //                     agent, any format→zip: the FILES the step kept with mail_save / browser_download
@@ -182,6 +205,9 @@ ${sandboxGuideLine()}
 - Collecting documents (invoices from mail or portals): the step keeps each file with mail_save / browser_download under a dated path ("invoices/2026-09/2026-09-03_Notion_INV-123.pdf"); its deliverable offers "zip". Split a big job into steps (mail, then statements, then portals) — one step manages about 60 tool calls.
 - Going through documents one by one (receipts against payments): never one model step per document. One step reads them in batches (scan_documents takes 30 at once) and writes rows into a list with "check"; the review shows that list split-screen — the person answers each row beside its file, without any model call.
 - Video that convinces is built in stages, each with its own review: idea and script (agent, json with a table of shots) → one still per shot (generate image with "each", starting from the person's product photo) → one clip per still (generate video with "each" and referenceImage = the stills step) → a voice-over (generate voice) → a film widget (video: true) that cuts clips, captions, voice and a closing card with the call to action. The starters "facebook-video-ad" and "property-film" carry such a widget (film/film.js) to copy. Offer a cheaper path without clips: the film animates the stills.
+- Motion-graphics films (explainers, product spots, shorts) are a "film" step after the preparation, each with a review:
+  research and script (agent, high) → the voice-over (one generate voice step for the whole script; the film step finds the
+  word timings itself) → film (inputs: the voice, pictures, the script). The look comes from a style kit in the workspace (kit), so the film step stays on "standard".
 - Prices come from a file the admin keeps in the workspace (a CSV price list): the agent step looks them up with read_workspace_file and proposes positions as a table; the next page shows them in an "items" field with "prefill" for the person to correct; the runner computes the totals.
 - AI media is marked for you (EU AI Act, Art. 50): images, clips, voice-overs and films carry the marking in their file metadata, and the pages lay the EU's "AI" label over them. Never ask an image step to draw such a label into the picture. A film is different — it leaves the page as a video file, so its widget shows the EU label in the picture: wizard.ai tells a widget whether the run's media in its data is "generated" or "edited" (film/film.js draws the matching icon).
 - Every step a person sees later (review/result) must come from an earlier step id.
@@ -207,8 +233,10 @@ one-off pages stay "generate" steps. A widget is code in the wizard's WORKSPACE
   export steps through it frame by frame. In mode "export" hide all controls and do not autoplay.
 - A film (step.video): seek(t) may return a promise that resolves once the frame is drawn (set a clip's
   currentTime, wait for "seeked", draw it to a canvas). Name the sound in the timeline:
-  audio: [{ src, start, duration?, volume? }] with the URLs from wizard.data (the voice-over, the clips
-  themselves for their own sound). Clips and images of the run arrive as URLs, not inlined.
+  audio: [{ src, start, duration?, from?, volume? }] with the URLs from wizard.data (the voice-over, the
+  clips themselves for their own sound; up to 48 tracks). "from" is the second of the source a track
+  plays from — a recording cut into pieces names one track per piece. Clips and images of the run
+  arrive as URLs, not inlined.
 - Call wizard.ready() once the first frame is drawn. Lay out for the step's size and scale to fit
   the window on every "resize" event — the window can be 0×0 when your script first runs.
 - Plain HTML/CSS/JS, SVG or canvas. Calm design, one accent colour (brand.accent), legible labels.

package/apps/runtime/dist/engine/prepare.js

@@ -1,6 +1,6 @@
 import { allFields, isAudioValue } from "@engenty-wizards/shared/definition";
-import { loadAsset } from "../files/storage.js";
-import { transcribeAudio } from "../media/transcribe.js";
+import { extFor, loadAsset } from "../files/storage.js";
+import { listenPieces, transcribeAudio } from "../media/transcribe.js";
 /**
  * Gets the person's answers ready for a step that works on its own: a voice note is listened to
  * once and kept as text with the answer, and a recording or signature that is not this run's own
@@ -17,6 +17,10 @@ export async function prepareInputs(ctx) {
             }
             continue;
         }
+        if (field.kind === "file" && field.listen) {
+            await listenTo(ctx, field.id, field.label, value);
+            continue;
+        }
         if (field.kind !== "audio" || !isAudioValue(value)) {
             continue;
         }
@@ -52,3 +56,34 @@ export async function prepareInputs(ctx) {
         }
     }
 }
+/** A recording in a file field with `listen`: written down once, piece by piece with its times. */
+async function listenTo(ctx, id, label, value) {
+    if (ctx.state.heard?.[id]) {
+        return;
+    }
+    // Several recordings: the first is the one that is cut.
+    const first = Array.isArray(value) ? value[0] : value;
+    const found = typeof first === "string" && first ? await loadAsset(first) : null;
+    if (!found || found.row.runId !== ctx.runId || !/^(audio|video)\//.test(found.row.mime)) {
+        return;
+    }
+    await ctx.emit("info", `Hört „${label}“ an …`);
+    try {
+        const { pieces, costUsd } = await listenPieces({
+            bytes: new Uint8Array(found.data),
+            ext: extFor(found.row.mime),
+            abortSignal: ctx.signal,
+            call: ctx.call,
+        });
+        await ctx.chargeUsd(costUsd);
+        ctx.state.heard = { ...ctx.state.heard, [id]: pieces };
+    }
+    catch (err) {
+        if (ctx.signal.aborted) {
+            throw err;
+        }
+        // The step goes on without the words; the next one tries again.
+        console.error(`[run ${ctx.runId}] listen ${id}`, err);
+        await ctx.emit("info", `„${label}“ konnte nicht verschriftlicht werden.`);
+    }
+}

package/apps/runtime/dist/engine/requirements.js

@@ -1,5 +1,5 @@
 import { isDecisionStep, MODEL_CLASSES, ruleMatches, } from "@engenty-wizards/shared/definition";
-import { classProblem } from "../models.js";
+import { classProblem, filmClient } from "../models.js";
 /**
  * What a wizard needs of the models before a run starts: each class its steps call, and whether
  * this runtime can serve it. A step every run passes through blocks the start when its class is
@@ -32,6 +32,8 @@ export function stepClasses(step) {
                 default:
                     return [step.model ?? "high"];
             }
+        case "film":
+            return [step.model ?? "standard"];
         case "page":
             // A voice note the page asks for is listened to before the next step reads it.
             return step.fields.some((f) => f.kind === "audio" && f.required) ? ["audio"] : [];
@@ -221,6 +223,22 @@ export async function missingModels(def) {
         }
     }
     const missing = [];
+    // A film runs on an installed client only, whatever serves its class otherwise.
+    for (const step of def.steps) {
+        if (step.type !== "film") {
+            continue;
+        }
+        const cls = step.model ?? "standard";
+        const found = await filmClient(cls);
+        if ("problem" in found) {
+            missing.push({
+                cls,
+                problem: found.problem,
+                steps: [{ id: step.id, title: step.title }],
+                blocking: unavoidable.has(step.id),
+            });
+        }
+    }
     for (const [cls, uses] of needs) {
         const problem = await classProblem(cls);
         if (problem) {
@@ -261,6 +279,9 @@ export async function missingCapabilities() {
             missing.add(capability);
         }
     }
+    if ("problem" in (await filmClient("standard"))) {
+        missing.add("film");
+    }
     return missing;
 }
 /** The classes this runtime cannot serve. */

package/apps/runtime/dist/engine/steps.js

@@ -3,6 +3,7 @@ import { Agent } from "@mastra/core/agent";
 import { generateText, Output } from "ai";
 import { z } from "zod";
 import { extFor, loadAsset, loadAssetText } from "../files/storage.js";
+import { runFilmStep } from "../film/step.js";
 import { generateImageMedia, generateSpeechMedia, generateVideoMedia, } from "../media/generate.js";
 import { markMedia } from "../media/marking.js";
 import { attachTools, costOf, isHarnessVendor, textModel } from "../models.js";
@@ -558,7 +559,10 @@ export async function runGenerateStep(step, ctx) {
             const media = await generateSpeechMedia({
                 call: ctx.call,
                 text,
-                style: [step.options?.style, note].filter(Boolean).join(". ") || undefined,
+                // The style may name the person's answer: "{{voiceStyle}}, natural pace".
+                style: [step.options?.style && renderTemplate(step.options.style, ctx.scope).trim(), note]
+                    .filter(Boolean)
+                    .join(". ") || undefined,
                 abortSignal: ctx.signal,
             });
             await ctx.chargeUsd(media.costUsd);
@@ -597,5 +601,8 @@ export async function runAutomaticStep(step, ctx) {
     if (step.type === "widget") {
         return runWidgetStep(step, ctx);
     }
+    if (step.type === "film") {
+        return runFilmStep(step, ctx);
+    }
     throw new StepError(`Step ${step.id} is not automatic.`);
 }

package/apps/runtime/dist/engine/template.js

@@ -126,6 +126,14 @@ export function resolveRef(ref, scope) {
         const totals = itemsTotals(field, value, state.values);
         return totals[rest[0]];
     }
+    if (field?.kind === "file" && rest[0] === "speech") {
+        const pieces = state.heard?.[head];
+        // The lines an agent reads and cuts by: "[12.40–15.10] what is said".
+        return pieces
+            ? pieces.map((p) => `[${p.start.toFixed(2)}–${p.end.toFixed(2)}] ${p.text}`).join("\n") ||
+                "(no intelligible speech)"
+            : "";
+    }
     if (field?.kind === "image" || field?.kind === "file") {
         // The files themselves are read with read_document / scan_documents by these names.
         const ids = (Array.isArray(value) ? value : [value]).filter((v) => typeof v === "string" && v.length > 0);

package/apps/runtime/dist/files/storage.js

@@ -1,6 +1,9 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
 import { eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { db, schema } from "../db/client.js";
+import { env } from "../env.js";
 import { currentTenant } from "../tenants/tenant.js";
 import { objects } from "./objects.js";
 const assetKey = (file) => `assets/${file}`;
@@ -100,11 +103,15 @@ export async function removeAsset(id) {
         await db.delete(schema.asset).where(eq(schema.asset.id, id));
     }
 }
-/** Deletes every file a run made (uploads, results, renders) and their rows. */
+/** Deletes every file a run made (uploads, results, renders, film folders) and their rows. */
 export async function removeAssetFiles(runId) {
     const rows = await db.query.asset.findMany({ where: eq(schema.asset.runId, runId) });
     for (const row of rows) {
         await objects.remove(assetKey(row.path));
     }
     await db.delete(schema.asset).where(eq(schema.asset.runId, runId));
+    // The folders its films were made in (../film/project.ts).
+    if (/^[A-Za-z0-9_-]+$/.test(runId)) {
+        await rm(join(env.dataDir, "films", runId), { recursive: true, force: true });
+    }
 }

package/apps/runtime/dist/film/project.js

@@ -0,0 +1,195 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, normalize } from "node:path";
+import { dataRef, FILM_SIZES } from "@engenty-wizards/shared/definition";
+import { unzipSync } from "fflate";
+import { renderTemplate, resolveRef } from "../engine/template.js";
+import { env } from "../env.js";
+import { getBlob } from "../files/blobs.js";
+import { extFor, loadAsset } from "../files/storage.js";
+import { projectFileContent } from "../services/project-files.js";
+import { placeSkills } from "./skills.js";
+import { soundCatalog } from "./sounds.js";
+import { runHyperframes } from "./tools.js";
+/**
+ * The folder a film is made in: one per run and step, kept after the run so a later change edits
+ * the code instead of starting over. Laid out for the client:
+ *
+ *   BRIEF.md            what to make (the step's brief, the format, the length)
+ *   CLAUDE.md, AGENTS.md the rules of the folder
+ *   .claude/skills/     the skill packages
+ *   showcase/           the wizard's style kit, the bar to reach
+ *   brand/              the space's brand: brand.json, logos
+ *   input/              what this run made before: voice lines, pictures, texts, uploads
+ *   audio-catalog/      the only sounds the film may use
+ *   film/               the HyperFrames project; renders/film.mp4 is the result
+ */
+export function filmRoot(runId, stepId) {
+    return join(env.dataDir, "films", runId, stepId);
+}
+const SESSION = join(".engenty", "session");
+export async function savedSession(root) {
+    try {
+        return (await readFile(join(root, SESSION), "utf8")).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveSession(root, id) {
+    await mkdir(join(root, ".engenty"), { recursive: true });
+    await writeFile(join(root, SESSION), id);
+}
+/** Writes bytes to a path inside `root`; a name that would leave it is refused. */
+async function put(root, rel, data) {
+    const path = normalize(join(root, rel));
+    if (!path.startsWith(`${root}/`)) {
+        return;
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, data);
+}
+const safeName = (name) => name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "file";
+function rules(step, skills) {
+    const size = FILM_SIZES[step.format];
+    return `# The film folder
+
+You make one film here, autonomously, to the end. Nobody answers questions: where a skill asks the
+person, decide yourself and note it in PROGRESS.md.
+
+- **What to make:** BRIEF.md. **The bar:** showcase/ (read showcase/SHOWCASE.md and showcase/frame.md
+  first when it exists, look at its stills, reuse its helpers from showcase/assets/). **The brand:**
+  brand/brand.json and brand/logos/ — colours, logo and fonts come from there only.
+- **Material:** input/ (see input/README.md). Use nothing from the web; you have no network.
+- **Skills:** ${skills.join(", ")} in .claude/skills/<name>/SKILL.md. Start with \`hyperframes\` and
+  read the skill files directly; do not update or install skills.
+- **The HyperFrames project is film/** (${size.width}×${size.height}, already set up). Keep every file
+  of the film inside film/.
+- **Running HyperFrames:** only through the \`hyperframes\` tool (MCP server \`film\`), e.g.
+  \`["lint","film"]\`, \`["check","film"]\`, \`["snapshot","film","--at","1,4,8"]\`,
+  \`["render","film","-q","draft"]\`, \`["transcribe","input/voice/l01.wav","--json","-d","input/voice"]\`.
+  \`npx\`, \`npm\` and network do not work in the shell.
+- **Look at your work:** snapshot the frames and read the PNGs, fix what is wrong. Before you finish,
+  render a draft and look at a frame every second of the whole film: empty areas, cut-off text,
+  overlaps, jumps.
+- **Finish** only when \`["check","film"]\` passes and \`["render","film","-q","draft"]\` succeeds, with \`film/index.html\` complete. The runtime renders the final MP4 itself.
+  End with a short summary: what the film shows, what you decided.
+
+## Sound (hard rules)
+
+- Sounds come only from audio-catalog/ (catalog.json lists each file with tags, keywords, licence).
+  Copy the picked files into film/assets/ and list them in film/AUDIO.md (file, source, licence, use).
+- Never generate, synthesize or download audio: no ffmpeg tone or noise, no TTS, no music models. Voice
+  lines come only from input/. Mixing is HyperFrames' job (\`<audio>\` with start, duration, volume).
+- Install nothing (no pip, brew, npm).
+`;
+}
+/** Sets up the folder for a first attempt; a later attempt finds it as it was left. */
+export async function prepareFilmFolder(step, ctx) {
+    const root = filmRoot(ctx.runId, step.id);
+    const brief = renderTemplate(step.brief, ctx.scope).trim();
+    // The same brief and material as last time: the film is there to go on with or to change.
+    const stamp = createHash("sha256")
+        .update(JSON.stringify([
+        brief,
+        Object.values(step.inputs).map((raw) => {
+            const ref = dataRef(raw);
+            const [head, id] = ref.split(".");
+            return head === "steps" ? ctx.state.outputs[id]?.at : ctx.state.values[ref];
+        }),
+    ]))
+        .digest("hex");
+    const stampFile = join(root, ".engenty", "inputs");
+    const same = existsSync(stampFile) && (await readFile(stampFile, "utf8")) === stamp;
+    if (same && existsSync(join(root, "film", "index.html")) && (await savedSession(root))) {
+        return { root, brief };
+    }
+    await rm(root, { recursive: true, force: true });
+    await mkdir(root, { recursive: true });
+    const skills = await placeSkills(step.skills, ctx.files, join(root, ".claude", "skills"));
+    const size = FILM_SIZES[step.format];
+    await put(root, "BRIEF.md", `# Brief\n\nFormat ${step.format}, ${size.width}×${size.height}${step.seconds ? `, about ${step.seconds} s` : ""}. Language of all text on screen: the brief's language.\n\n${brief}\n`);
+    const text = rules(step, skills);
+    await put(root, "CLAUDE.md", text);
+    await put(root, "AGENTS.md", text);
+    // The style kit.
+    if (step.kit) {
+        const file = ctx.files.find((f) => f.path === step.kit);
+        if (file) {
+            const entries = unzipSync(new Uint8Array(await getBlob(file.hash)));
+            for (const [name, data] of Object.entries(entries)) {
+                if (!name.endsWith("/")) {
+                    await put(join(root, "showcase"), name.replace(/^showcase\//, ""), data);
+                }
+            }
+        }
+    }
+    // The space's brand.
+    const b = ctx.scope.brand;
+    const logos = [];
+    for (const f of ctx.projectFiles.filter((p) => p.kind === "logo")) {
+        try {
+            const { data } = await projectFileContent(f.projectId, f.id);
+            const name = `logos/${safeName(f.name.replace(/\.[^.]+$/, ""))}.${extFor(f.mime) === "bin" ? (f.name.split(".").pop() ?? "bin") : extFor(f.mime)}`;
+            await put(join(root, "brand"), name, data);
+            logos.push(name);
+        }
+        catch {
+            // a logo less
+        }
+    }
+    await put(join(root, "brand"), "brand.json", JSON.stringify({
+        note: "The space's brand. Colours are named by what they are for; the first is the accent.",
+        name: b.name ?? "",
+        about: b.about ?? "",
+        colors: (b.colors ?? []).map((c) => ({ name: c.name, value: c.value })),
+        logos,
+        facts: (b.facts ?? []).map((f) => `${f.label}: ${f.value}`),
+    }, null, 1));
+    // What the run made before.
+    const listed = [];
+    for (const [name, raw] of Object.entries(step.inputs)) {
+        const ref = dataRef(raw);
+        const [head, id] = ref.split(".");
+        const output = head === "steps" ? ctx.state.outputs[id] : undefined;
+        const assetIds = head === "steps"
+            ? (output?.assets ?? []).map((a) => a.id)
+            : [ctx.state.values[ref]].flat().filter((v) => typeof v === "string");
+        let n = 0;
+        for (const assetId of assetIds) {
+            const found = await loadAsset(assetId);
+            if (found && found.row.runId === ctx.runId) {
+                const file = `${name}/${safeName(found.row.name)}`;
+                await put(join(root, "input"), file, found.data);
+                listed.push(`- \`input/${file}\` (${found.row.mime})`);
+                n++;
+            }
+        }
+        if (head === "steps" && output?.json !== undefined) {
+            await put(join(root, "input"), `${name}.json`, JSON.stringify(output.json, null, 1));
+            listed.push(`- \`input/${name}.json\``);
+        }
+        else if (head === "steps" && output?.text) {
+            await put(join(root, "input"), `${name}.md`, output.text);
+            listed.push(`- \`input/${name}.md\``);
+        }
+        else if (!n) {
+            const value = resolveRef(ref, ctx.scope);
+            if (value !== undefined && value !== null && value !== "") {
+                await put(join(root, "input"), `${name}.md`, typeof value === "string" ? value : JSON.stringify(value, null, 1));
+                listed.push(`- \`input/${name}.md\``);
+            }
+        }
+    }
+    await put(join(root, "input"), "README.md", `# Material for this film\n\n${listed.join("\n") || "(none)"}\n\nVoice lines play one after another in their order; their lengths decide the timing.\n`);
+    await cp(await soundCatalog(), join(root, "audio-catalog"), { recursive: true });
+    // The HyperFrames project, set up for the format.
+    const preset = { "16:9": "landscape", "9:16": "portrait", "1:1": "square" }[step.format];
+    const init = await runHyperframes(["init", "film", "--non-interactive", "--skip-transcribe", `--resolution=${preset}`], { cwd: root, signal: ctx.signal, timeoutMs: 5 * 60_000 });
+    if (init.code !== 0 || !existsSync(join(root, "film"))) {
+        throw new Error(`Das Filmprojekt konnte nicht angelegt werden: ${init.out.slice(-300)}`);
+    }
+    await put(root, ".engenty/inputs", stamp);
+    return { root, brief };
+}

package/apps/runtime/dist/film/skills.js

@@ -0,0 +1,91 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { cp, mkdir, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { env } from "../env.js";
+import { getBlob } from "../files/blobs.js";
+const exec = promisify(execFile);
+export const PLATFORM_SKILLS = {
+    hyperframes: {
+        name: "hyperframes",
+        source: "https://github.com/heygen-com/hyperframes",
+        version: "6308727b85726433e6a1e148b608d8cb11085114",
+        licence: "Apache-2.0",
+        tarball: "https://codeload.github.com/heygen-com/hyperframes/tar.gz/6308727b85726433e6a1e148b608d8cb11085114",
+        folder: "skills",
+    },
+};
+const fetching = new Map();
+/** The folder holding a platform package's skills; fetched on first use. */
+export function platformSkills(name) {
+    const pkg = PLATFORM_SKILLS[name];
+    if (!pkg) {
+        return Promise.reject(new Error(`Das Skill-Paket „${name}“ gibt es nicht.`));
+    }
+    const dir = join(env.dataDir, "skills", `${pkg.name}@${pkg.version.slice(0, 12)}`);
+    if (existsSync(join(dir, ".complete"))) {
+        return Promise.resolve(dir);
+    }
+    let pending = fetching.get(name);
+    if (!pending) {
+        pending = fetchPackage(pkg, dir).finally(() => fetching.delete(name));
+        fetching.set(name, pending);
+    }
+    return pending;
+}
+async function fetchPackage(pkg, dir) {
+    const res = await fetch(pkg.tarball);
+    if (!res.ok) {
+        throw new Error(`Das Skill-Paket „${pkg.name}“ konnte nicht geladen werden (${res.status}).`);
+    }
+    const tmp = `${dir}.part`;
+    await rm(tmp, { recursive: true, force: true });
+    await mkdir(tmp, { recursive: true });
+    const archive = join(tmp, "package.tar.gz");
+    await writeFile(archive, Buffer.from(await res.arrayBuffer()));
+    // GitHub's tarball has one top folder (<repo>-<sha>); only its skills folder is kept.
+    await exec("tar", ["-xzf", archive, "-C", tmp, "--strip-components=1", `*/${pkg.folder}/*`]);
+    const skills = join(tmp, pkg.folder);
+    for (const entry of await readdir(skills, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !existsSync(join(skills, entry.name, "SKILL.md"))) {
+            await rm(join(skills, entry.name), { recursive: true, force: true });
+        }
+    }
+    await writeFile(join(skills, "PACKAGE.json"), JSON.stringify({ name: pkg.name, source: pkg.source, version: pkg.version, licence: pkg.licence }, null, 1));
+    await writeFile(join(skills, ".complete"), new Date().toISOString());
+    await rm(dir, { recursive: true, force: true });
+    await rename(skills, dir);
+    await rm(tmp, { recursive: true, force: true });
+    return dir;
+}
+/**
+ * Puts the step's skill packages into `target` (one folder per skill): platform packages by
+ * name, workspace packages (`skills/<name>`) from the wizard's files. Returns the skill names.
+ */
+export async function placeSkills(names, files, target) {
+    await mkdir(target, { recursive: true });
+    const placed = [];
+    for (const name of names) {
+        if (name.startsWith("skills/")) {
+            const prefix = `${name.replace(/\/+$/, "")}/`;
+            const own = files.filter((f) => f.path.startsWith(prefix));
+            const skill = prefix.split("/")[1];
+            for (const f of own) {
+                const dest = join(target, skill, f.path.slice(prefix.length));
+                await mkdir(join(dest, ".."), { recursive: true });
+                await writeFile(dest, await getBlob(f.hash));
+            }
+            placed.push(skill);
+            continue;
+        }
+        const dir = await platformSkills(name);
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                await cp(join(dir, entry.name), join(target, entry.name), { recursive: true });
+                placed.push(entry.name);
+            }
+        }
+    }
+    return placed;
+}