@hypit/hypit 0.2.5 → 0.2.7

package/packages/video-cli/src/snapshot.ts

@@ -0,0 +1,186 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, mkdtemp, readFile, rename, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Readable } from "node:stream";
+import type { ReadableStream as NodeReadableStream } from "node:stream/web";
+import { pipeline } from "node:stream/promises";
+import type { CliIo } from "@hypit/cli";
+import { assertHyperframesDocument, hyperframesHtmlAssetUrls, hyperframesHtmlDomain } from "@hypit/hyperframes";
+import type { HyperframesDocument, HyperframesHtmlProject } from "@hypit/hyperframes";
+import { FileResourceStore } from "@hypit/resource-store-fs";
+import { hyperframesFramesRequest, renderHyperframesCapabilities, renderHyperframesTypes, verifyHyperframesFrames } from "@hypit/render-hyperframes";
+import type { Need } from "@hypit/protocol";
+import { creationEnvironment, selectedProvider, providerLine, providerView } from "./creation.js";
+import type { CreationEnvironment } from "./creation.js";
+import { snapshotFrameLabel, writeFrameGrid } from "./frame-grid.js";
+
+const MEDIA_TYPES: Readonly<Record<string, string>> = {
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp",
+  ".mp4": "video/mp4", ".webm": "video/webm", ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".otf": "font/otf",
+};
+
+async function readProject(source: string, html: string, resources: FileResourceStore): Promise<HyperframesHtmlProject> {
+  const assets = [];
+  const base = /^https?:/u.test(source) ? new URL(source) : pathToFileURL(source);
+  for (const url of hyperframesHtmlAssetUrls(html)) {
+    const address = new URL(url, base);
+    let mediaType: string | undefined;
+    let stream: Readable;
+    if (address.protocol === "file:") {
+      if (base.protocol !== "file:") throw new Error(`Network HTML cannot read local asset ${url}`);
+      const path = fileURLToPath(address);
+      mediaType = MEDIA_TYPES[extname(path).toLowerCase()];
+      if (mediaType === undefined) throw new Error(`Unsupported snapshot asset ${url}; use compiled HTML with inline scripts and styles`);
+      stream = createReadStream(path);
+    } else if (address.protocol === "http:" || address.protocol === "https:") {
+      const response = await fetch(address);
+      if (!response.ok || response.body === null) throw new Error(`Snapshot asset ${url}: HTTP ${response.status}`);
+      mediaType = response.headers.get("content-type")?.split(";")[0]?.trim();
+      if (mediaType === undefined || !Object.values(MEDIA_TYPES).includes(mediaType)) {
+        await response.body.cancel();
+        throw new Error(`Unsupported snapshot asset ${url} (${mediaType}); use compiled HTML with inline scripts and styles`);
+      }
+      stream = Readable.fromWeb(response.body as NodeReadableStream<Uint8Array>);
+    } else throw new Error(`Unsupported snapshot asset protocol ${address.protocol}`);
+    try { assets.push({ url, artifact: await resources.putStream(stream, mediaType) }); }
+    finally { stream.destroy(); }
+  }
+  return { html, assets };
+}
+
+const OPTIONS = ["--studio", "--to", "--at-frame", "--start-frame", "--end-frame-exclusive", "--step-frames", "--grid", "--cell", "--runtime", "--workspace"];
+
+export function writeSnapshotHelp(io: CliIo): void {
+  io.write(`hypit snapshot\nCapture exact frames from an existing compiled HyperFrames HTML programme through the selected Runtime Profile.\n\n`
+    + `  hypit snapshot --studio <studio-url> --at-frame <n[,n,…]> --to <directory>\n`
+    + `  hypit snapshot <index.html|HTML-URL> --at-frame <n[,n,…]> --to <directory>\n`
+    + `  hypit snapshot <index.html|HTML-URL> --start-frame <n> --end-frame-exclusive <n> [--step-frames <n>] --to <directory>\n`
+    + `      [--grid <columns>x<rows>] [--cell <pixels>] [--runtime <profile>] [--workspace <project>] [--json]\n\n`
+    + `Frame indices are zero-based on the original programme clock. Ranges exclude the end.\n`
+    + `Writes full-size PNGs and optional paginated grids. --cell controls grid image width (default 480).\n`
+    + `Uses render-frames, one immediate request. Browser preparation belongs to the selected Provider.\n`
+    + `HTML carries the compiled frame clock and media/font URLs; scripts and styles are inline.\nStudio exposes its current programme at http://<host>:<port>/__studio/visual.html.\n`);
+}
+
+export async function runSnapshotCli(argv: readonly string[], io: CliIo, environment: CreationEnvironment = creationEnvironment()): Promise<void> {
+  if (argv.includes("--help")) { writeSnapshotHelp(io); return; }
+  const options = new Map<string, string>();
+  const positionals = [];
+  const json = argv.includes("--json");
+  for (let index = 1; index < argv.length; index++) {
+    const arg = argv[index]!;
+    if (["--json", "--debug", "--verbose", "--no-color"].includes(arg)) continue;
+    if (arg === "--color") { index++; continue; }
+    if (!arg.startsWith("--")) { positionals.push(arg); continue; }
+    if (!OPTIONS.includes(arg)) throw new Error(`Unknown snapshot option ${arg}`);
+    if (options.has(arg)) throw new Error(`${arg} cannot be repeated`);
+    const value = argv[++index];
+    if (!value || value.startsWith("--")) throw new Error(`${arg} requires a value`);
+    options.set(arg, value);
+  }
+  const studio = options.get("--studio");
+  if (positionals.length !== (studio === undefined ? 1 : 0) || !options.has("--to")) throw new Error("snapshot takes one HTML input or --studio <url>, and --to <directory>");
+  const integer = (raw: string | undefined, label: string, minimum = 0): number => {
+    if (raw === undefined || !/^\d+$/u.test(raw) || !Number.isSafeInteger(Number(raw)) || Number(raw) < minimum) throw new Error(`${label} needs an integer >= ${minimum}`);
+    return Number(raw);
+  };
+  const source = studio === undefined
+    ? /^https?:\/\//u.test(positionals[0]!) ? positionals[0]! : resolve(environment.cwd, positionals[0]!)
+    : new URL("/__studio/document", studio).href;
+  let document: HyperframesDocument | undefined;
+  let html: string;
+  if (studio !== undefined) {
+    const response = await fetch(source);
+    if (!response.ok) throw new Error(`Studio programme: HTTP ${response.status} ${await response.text()}`);
+    document = await response.json() as HyperframesDocument;
+    assertHyperframesDocument(document);
+    html = document.html;
+  } else if (/^https?:/u.test(source)) {
+    const response = await fetch(source);
+    if (!response.ok) throw new Error(`Snapshot HTML: HTTP ${response.status} ${await response.text()}`);
+    html = await response.text();
+  } else html = await readFile(source, "utf8");
+  const domain = document ?? hyperframesHtmlDomain(html);
+  const explicit = options.get("--at-frame");
+  let frames: number[];
+  if (explicit !== undefined) {
+    if (["--start-frame", "--end-frame-exclusive", "--step-frames"].some(key => options.has(key))) throw new Error("Choose --at-frame or a frame range");
+    frames = explicit.split(",").map(value => integer(value, "--at-frame"));
+  } else {
+    const start = integer(options.get("--start-frame"), "--start-frame");
+    const end = integer(options.get("--end-frame-exclusive"), "--end-frame-exclusive");
+    const step = integer(options.get("--step-frames") ?? "1", "--step-frames", 1);
+    if (end <= start || end > domain.frameCount) throw new Error(`The frame range must satisfy 0 <= start < end <= ${domain.frameCount}`);
+    frames = Array.from({ length: Math.ceil((end - start) / step) }, (_, index) => start + index * step);
+  }
+  const grid = options.get("--grid")?.split("x");
+  if (grid !== undefined && grid.length !== 2) throw new Error("--grid needs columns x rows, for example 4x3");
+  const columns = grid === undefined ? undefined : integer(grid[0], "grid columns", 1);
+  const rows = grid === undefined ? undefined : integer(grid[1], "grid rows", 1);
+  if (options.has("--cell") && grid === undefined) throw new Error("--cell requires --grid");
+  const cell = integer(options.get("--cell") ?? "480", "--cell", 32);
+  const to = resolve(environment.cwd, options.get("--to")!);
+  if (await stat(to).then(() => true, () => false)) throw new Error(`Destination ${to} already exists`);
+  const temporary = await mkdtemp(join(tmpdir(), "hypit-snapshot-"));
+  let staging: string | undefined;
+  try {
+    const resources = new FileResourceStore(temporary);
+    let input: { document: HyperframesDocument } | { project: HyperframesHtmlProject };
+    if (document !== undefined) {
+      for (const artifact of document.artifacts) {
+        const response = await fetch(new URL(`/__studio/material/${artifact.resource}`, studio));
+        if (!response.ok || response.body === null) throw new Error(`Studio material ${artifact.resource}: HTTP ${response.status}`);
+        const stream = Readable.fromWeb(response.body as NodeReadableStream<Uint8Array>);
+        try { await resources.writeStream(artifact, stream); }
+        finally { stream.destroy(); }
+      }
+      input = { document };
+    } else input = { project: await readProject(source, html, resources) };
+    const need: Need = { id: "need:hypit-snapshot", capability: renderHyperframesCapabilities.renderFrames,
+      returns: renderHyperframesTypes.frames, result: "record:hypit-snapshot", constraints: hyperframesFramesRequest({ ...input, frames }) };
+    const { host, profile } = await environment.openHost(options.get("--runtime"), options.get("--workspace"));
+    const provider = await selectedProvider(host, need, profile);
+    if (!json) io.write(`Capturing ${frames.length} frames through ${providerLine(provider)}\n`);
+    const report = json ? io.writeProgress : io.writeProgress ?? io.write;
+    const fulfilled = await host.invoke(need, resources, {
+      reportProgress: async progress => { report?.(`  · ${progress.phase}\n`); },
+      reportDiagnostic: async diagnostic => { report?.(`  · ${diagnostic.message}\n`); },
+    });
+    if (fulfilled.value.kind !== "inline") throw new Error("The frame list came back by reference");
+    verifyHyperframesFrames(fulfilled.value.value);
+    const images = fulfilled.value.value;
+    if (images.length !== frames.length) throw new Error(`Requested ${frames.length} frames, received ${images.length}`);
+    await mkdir(dirname(to), { recursive: true });
+    staging = await mkdtemp(join(dirname(to), ".hypit-snapshot-"));
+    const files = [];
+    for (const [index, image] of images.entries()) {
+      const frame = frames[index]!;
+      const name = `frame-${String(frame).padStart(9, "0")}.png`;
+      const stream = await resources.open(image.resource);
+      if (stream === undefined) throw new Error(`Snapshot frame ${frame} is unavailable`);
+      await pipeline(stream, createWriteStream(join(staging, name), { flags: "wx" }));
+      files.push({ frame, seconds: frame * domain.frameRate.denominator / domain.frameRate.numerator, path: join(to, name) });
+    }
+    const grids: string[] = [];
+    if (columns !== undefined && rows !== undefined) {
+      const count = columns * rows;
+      for (let offset = 0; offset < files.length; offset += count) {
+        const page = [];
+        for (const file of files.slice(offset, offset + count)) page.push({ path: join(staging, `frame-${String(file.frame).padStart(9, "0")}.png`),
+          label: await snapshotFrameLabel(file.frame, file.seconds, cell) });
+        const name = `grid-${String(grids.length + 1).padStart(3, "0")}.jpg`;
+        await writeFrameGrid(page, join(staging, name), cell, columns);
+        grids.push(join(to, name));
+      }
+    }
+    await rename(staging, to);
+    staging = undefined;
+    if (json) io.write(`${JSON.stringify({ format: "hypit.video-cli-snapshot@1", source, ...providerView(provider), frames: files, grids }, null, 2)}\n`);
+    else io.write(`Captured ${files.length} PNGs${grids.length === 0 ? "" : ` and ${grids.length} grid${grids.length === 1 ? "" : "s"}`}\n  ${to}\n`);
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+    if (staging !== undefined) await rm(staging, { recursive: true, force: true });
+  }
+}

package/packages/wan/README.md

@@ -0,0 +1,31 @@
+# `@hypit/wan`
+
+Exact author/compute contracts and package-owned author Surfaces for Wan 2.7 Image and Wan 2.7 Image
+Pro.
+
+The model variants are separate endpoints with exact request validation. Their Surfaces project the
+primary result to an ordinary image Artifact. The package contains no Provider selection, API key or
+network execution. The selected Provider implements its exact capability.
+
+Import the model variant you mean and connect prompt and references as ordinary graph edges:
+
+```xml
+<wan:Image id="draft" prompt={prompt} resolution="2K">
+  <wan:Reference image={product.image}/>
+</wan:Image>
+
+<wan:ProImage id="hero" prompt={heroPrompt} resolution="4K"/>
+```
+
+The Surface only lowers this syntax into the package's exact model request. It does not select a
+Provider.
+
+Both variants accept prompts up to 5,000 characters and up to nine references, and render at `1K` or
+`2K`; the Pro variant adds `4K`. The model takes no aspect ratio: with references present the output
+takes the shape of the last one, and a prompt-only element renders at the band's own framing. There
+is no negative prompt either, so write exclusions into the prompt.
+
+`count` renders up to four pictures. Setting `image-set` renders one storyline across several
+pictures instead, where `count` names a ceiling of up to twelve and the model chooses how many it
+returns. An image set shapes a storyline the way `extended-reasoning` shapes a single picture, so the
+two are not stated together.

package/packages/wan/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@hypit/wan",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/artifact": "workspace:*",
+    "@hypit/generation": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/model-kit": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/text": "workspace:*"
+  }
+}

package/packages/wan/src/activation.ts

@@ -0,0 +1,11 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import { wanComponent, wanDefinition, wanManifest, wanModuleRef, wanMarkupSurfaces } from "./index.js";
+import { decodeWanImageSurface, decodeWanProImageSurface } from "./surface.js";
+export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest: wanManifest }], components: [wanComponent], hostFacets: [
+  wanDefinition.hostFacet,
+  createMarkupSurfaceHostFacet({ module: wanModuleRef,
+    declaration: wanMarkupSurfaces.find((item) => item.name === "image")!, handler: decodeWanImageSurface }),
+  createMarkupSurfaceHostFacet({ module: wanModuleRef,
+    declaration: wanMarkupSurfaces.find((item) => item.name === "pro-image")!, handler: decodeWanProImageSurface }),
+] };
+export default hypitPackage;

package/packages/wan/src/index.ts

@@ -0,0 +1,160 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type { SurfaceAttributeVocabulary, SurfaceChildVocabulary } from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const wanModuleRef = { name: "@hypit/wan", version: "1" } as const;
+export const wanModels = ["wan-2.7-image", "wan-2.7-image-pro"] as const;
+export type WanModel = typeof wanModels[number];
+
+/**
+ * The model renders at one of these bands. It takes no aspect ratio: with input images the output
+ * follows the last one, and a prompt-only request renders at the band's own framing.
+ */
+const WAN_RESOLUTIONS = ["1K", "2K"] as const;
+const WAN_PRO_RESOLUTIONS = ["1K", "2K", "4K"] as const;
+
+function wanPortTable(model: WanModel): GenerationPortTable {
+  const pro = model === "wan-2.7-image-pro";
+  return sealGenerationPortTable({
+    model,
+    result: "image",
+    ports: [
+      { name: "prompt", value: { kind: "text", maxChars: 5_000 }, minItems: 1, maxItems: 1 },
+      { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 9 },
+      {
+        name: "resolution",
+        value: { kind: "enum", values: pro ? [...WAN_PRO_RESOLUTIONS] : [...WAN_RESOLUTIONS] },
+        minItems: 0,
+        maxItems: 1,
+      },
+      // One request renders up to four pictures, or up to twelve as a story-coherent set. The
+      // model chooses how many of an image set it returns, so this names a ceiling.
+      { name: "count", value: { kind: "number", integer: true, minimum: 1, maximum: 12 }, minItems: 0, maxItems: 1 },
+      { name: "imageSet", value: { kind: "boolean" }, minItems: 0, maxItems: 1 },
+      { name: "extendedReasoning", value: { kind: "boolean" }, minItems: 0, maxItems: 1 },
+      { name: "watermark", value: { kind: "boolean" }, minItems: 0, maxItems: 1 },
+      { name: "seed", value: { kind: "number", integer: true, minimum: 0, maximum: 2_147_483_647 }, minItems: 0, maxItems: 1 },
+    ],
+    // An image set renders one storyline in several pictures, which is what extended reasoning
+    // would otherwise shape for a single picture.
+    requires: [{ kind: "atMostOneOf", ports: ["imageSet", "extendedReasoning"] }],
+  });
+}
+
+export const wanPorts: Readonly<Record<WanModel, GenerationPortTable>> = {
+  "wan-2.7-image": wanPortTable("wan-2.7-image"),
+  "wan-2.7-image-pro": wanPortTable("wan-2.7-image-pro"),
+};
+
+export function sealWanRequest(
+  model: WanModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+  return sealGenerationPortRequest(wanPorts[model], ports);
+}
+
+const wanBaseDefinition = defineExactModelModule({
+  module: wanModuleRef,
+  endpoints: wanModels.map((model) => ({
+    key: model === "wan-2.7-image" ? "image" : "pro",
+    requestTypeName: model === "wan-2.7-image" ? "WanImageRequest" : "WanProImageRequest",
+    producerName: `request-${model}`,
+    ports: wanPorts[model],
+  })),
+});
+
+export const wanEndpoints = wanBaseDefinition.endpoints;
+export const wanComponent = wanBaseDefinition.component;
+
+function wanAttributes(pro: boolean): readonly SurfaceAttributeVocabulary[] {
+  return [
+    { name: "id", kind: "identifier", required: true,
+      summary: "Names this generation and prefixes the bindings it publishes." },
+    { name: "prompt", kind: "reference", required: true, accepts: [textTypes.text],
+      summary: "The Text edge describing the picture, the edit to make, or the storyline of an image set." },
+    { name: "resolution", kind: "literal", required: false,
+      values: pro ? [...WAN_PRO_RESOLUTIONS] : [...WAN_RESOLUTIONS],
+      summary: "The size band the model renders at." },
+    { name: "count", kind: "literal", required: false,
+      summary: "How many pictures to render, up to four, or the ceiling of an image set." },
+    { name: "image-set", kind: "literal", required: false, values: ["true", "false"],
+      summary: "Renders one storyline as several pictures instead of one picture." },
+    { name: "extended-reasoning", kind: "literal", required: false, values: ["true", "false"],
+      summary: "Spends longer shaping a single picture before rendering it." },
+    { name: "watermark", kind: "literal", required: false, values: ["true", "false"],
+      summary: "Marks the returned pictures as AI generated." },
+    { name: "seed", kind: "literal", required: false,
+      summary: "Seeds the model's sampling so a rerun stays close to this one." },
+  ];
+}
+
+const wanChildren: readonly SurfaceChildVocabulary[] = [
+  { tag: "Reference", cardinality: "many",
+    summary: "Attaches one image Artifact the model edits or draws on.",
+    attributes: [
+      { name: "image", kind: "reference", required: true, accepts: [artifactTypes.blob],
+        summary: "Selects the image Artifact this reference contributes." },
+    ] },
+];
+
+const surface = (
+  name: "image" | "pro-image",
+  tag: "Image" | "ProImage",
+  endpoint: (typeof wanEndpoints)["image" | "pro"],
+  pro: boolean,
+  summary: string,
+  example: string,
+) => ({
+  name,
+  tag,
+  mode: "structured" as const,
+  outputs: [endpoint!.draftType, endpoint!.mediaBindings.images!.type],
+  vocabulary: {
+    summary,
+    attributes: wanAttributes(pro),
+    children: wanChildren,
+    ports: [{
+      name: "image",
+      type: artifactTypes.blob,
+      summary: "The primary generated image, addressed as `<id>.image`.",
+    }],
+    example,
+    notes: [
+      "The element accepts at most 9 `Reference` children and no text content.",
+      "With references present the output takes the shape of the last one; a prompt-only element renders at the band's own framing.",
+      "The model reads exclusions from the prompt itself, so write them there.",
+      "Every `Reference` is an ordinary image Artifact edge; the Surface copies no runtime media into request metadata.",
+      "The Surface lowers the element into the package's exact model request and selects no Provider.",
+    ],
+  },
+});
+
+export const wanMarkupSurfaces = [
+  surface("image", "Image", wanEndpoints.image!, false,
+    "Generates pictures with the exact Wan 2.7 Image model from a Text prompt and optional reference images.",
+    `<wan:Image
+  id="draft"
+  prompt={prompt}
+  resolution="2K"
+>
+  <wan:Reference image={product.image}/>
+</wan:Image>`),
+  surface("pro-image", "ProImage", wanEndpoints.pro!, true,
+    "Generates pictures with the exact Wan 2.7 Image Pro model from a Text prompt and optional reference images.",
+    `<wan:ProImage
+  id="hero"
+  prompt={heroPrompt}
+  resolution="4K"
+/>`),
+] as const;
+
+export const wanManifest = {
+  ...wanBaseDefinition.manifest,
+};
+export const wanDefinition = {
+  ...wanBaseDefinition,
+  manifest: wanManifest,
+};

package/packages/wan/src/surface.ts

@@ -0,0 +1,147 @@
+import { artifactTypes } from "@hypit/artifact";
+import { generationPort, sealGenerationMediaBinding, sealGenerationRequestDraft } from "@hypit/generation";
+import type { GenerationMediaPort, GenerationPortValue } from "@hypit/generation";
+import {
+  createExactModelPrimaryGenerationFragment,
+  exactModelMediaInputNames,
+  exactModelTextInputName,
+} from "@hypit/model-kit";
+import type { ExactModelEndpoint } from "@hypit/model-kit";
+import type {
+  MarkupAttributeValue,
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+} from "@hypit/markup";
+import type { CanonicalValue, TypeRef } from "@hypit/protocol";
+import { textTypes, verifyText } from "@hypit/text";
+
+import { wanEndpoints } from "./index.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function localName(name: string): string {
+  return name.includes(":") ? name.slice(name.lastIndexOf(":") + 1) : name;
+}
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+  return left.name === right.name && left.module.name === right.module.name && left.module.version === right.module.version;
+}
+
+function exact(element: StructuredElement, allowed: readonly string[], required: readonly string[]): void {
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.includes(name));
+  assert(unknown.length === 0, `${element.name} does not accept ${unknown[0]}`);
+  const missing = required.filter((name) => element.attributes[name] === undefined);
+  assert(missing.length === 0, `${element.name} requires ${missing.join(", ")}`);
+}
+
+function text(element: StructuredElement, name: string): string {
+  const value = element.attributes[name];
+  assert(typeof value === "string" && value.trim().length > 0, `${element.name}.${name} must be text`);
+  return value.trim();
+}
+
+/** An absent optional attribute leaves its port unstated, which the model reads as its own default. */
+function optionalText(element: StructuredElement, name: string): readonly GenerationPortValue[] | undefined {
+  return element.attributes[name] === undefined ? undefined : [text(element, name)];
+}
+
+function optionalFlag(element: StructuredElement, name: string): readonly GenerationPortValue[] | undefined {
+  if (element.attributes[name] === undefined) return undefined;
+  const value = text(element, name);
+  assert(value === "true" || value === "false", `${element.name}.${name} must be true or false`);
+  return [value === "true"];
+}
+
+function optionalInteger(element: StructuredElement, name: string): readonly GenerationPortValue[] | undefined {
+  if (element.attributes[name] === undefined) return undefined;
+  const value = text(element, name);
+  assert(/^\d+$/u.test(value), `${element.name}.${name} must be a whole number`);
+  return [Number(value)];
+}
+
+function ref(
+  element: StructuredElement,
+  name: string,
+  type: TypeRef,
+  resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const value: MarkupAttributeValue | undefined = element.attributes[name];
+  assert(typeof value === "object" && value.kind === "reference", `${element.name}.${name} must be a reference`);
+  const result = resolve(value.path);
+  assert(result !== undefined && sameType(result.type, type), `${element.name}.${name} has the wrong type`);
+  return result;
+}
+
+const attributes = ["id", "prompt", "resolution", "count", "image-set", "extended-reasoning", "watermark", "seed"] as const;
+
+function decoder(endpoint: ExactModelEndpoint): StructuredSurfaceHandler {
+  return ({ element, resolveReference }) => {
+    exact(element, [...attributes], ["id", "prompt"]);
+    const id = text(element, "id");
+    const prompt = ref(element, "prompt", textTypes.text, resolveReference);
+    if (prompt.record !== undefined) {
+      assert(prompt.record.value.kind === "inline", `${element.name}.prompt must reference Text`);
+      verifyText(prompt.record.value.value);
+    }
+    const imagePort = generationPort(endpoint.ports, "images");
+    assert(imagePort.value.kind === "media", "Wan images port is not media");
+    const images: SurfaceResolvedReference[] = [];
+    for (const child of element.children) {
+      if (child.kind === "text") {
+        assert(child.value.trim().length === 0, `${element.name} accepts only Reference children`);
+        continue;
+      }
+      assert(localName(child.name) === "Reference", `${element.name} accepts only Reference children`);
+      exact(child, ["image"], ["image"]);
+      assert(!child.children.some((item) => item.kind === "element" || item.value.trim()), `${child.name} must be empty`);
+      const image = ref(child, "image", artifactTypes.blob, resolveReference);
+      if (image.record !== undefined) {
+        assert(image.record.value.kind === "blob" && image.record.value.mediaType.startsWith("image/"),
+          `${child.name}.image must reference image media`);
+      }
+      images.push(image);
+    }
+    assert(images.length <= imagePort.maxItems, `${element.name} accepts at most ${imagePort.maxItems} references`);
+    const stated: Record<string, readonly GenerationPortValue[] | undefined> = {
+      resolution: optionalText(element, "resolution"),
+      count: optionalInteger(element, "count"),
+      imageSet: optionalFlag(element, "image-set"),
+      extendedReasoning: optionalFlag(element, "extended-reasoning"),
+      watermark: optionalFlag(element, "watermark"),
+      seed: optionalInteger(element, "seed"),
+    };
+    const draft = sealGenerationRequestDraft(endpoint.ports, Object.fromEntries(
+      Object.entries(stated).filter((entry): entry is [string, readonly GenerationPortValue[]] => entry[1] !== undefined),
+    ));
+    const records: Array<{ id: string; type: TypeRef; value: { kind: "inline"; value: CanonicalValue }; range: StructuredElement["range"] }> = [{
+      id: `${id}.draft`, type: endpoint.draftType,
+      value: { kind: "inline", value: draft as unknown as CanonicalValue }, range: element.range,
+    }];
+    const inputs: Record<string, SurfaceResolvedReference["ref"] | { kind: "record"; id: string }> = {
+      draft: { kind: "record", id: `${id}.draft` }, [exactModelTextInputName("prompt")]: prompt.ref,
+    };
+    const media = images.map((image, index) => {
+      const name = `image-${String(index + 1).padStart(4, "0")}`;
+      const bindingId = `${id}.${name}.binding`;
+      records.push({
+        id: bindingId, type: endpoint.mediaBindings.images!.type,
+        value: { kind: "inline", value: sealGenerationMediaBinding(imagePort as GenerationMediaPort, { role: "image" }) as unknown as CanonicalValue },
+        range: element.range,
+      });
+      const names = exactModelMediaInputNames(name);
+      inputs[names.binding] = { kind: "record", id: bindingId };
+      inputs[names.artifact] = image.ref;
+      return { name, port: "images" } as const;
+    });
+    const fragment = createExactModelPrimaryGenerationFragment(endpoint, media, [{ name: "prompt", port: "prompt" }]);
+    return { records, fragments: [fragment], components: [{
+      id, fragment: fragment.id, inputs, outputs: { image: `${id}.image` }, range: element.range,
+    }] };
+  };
+}
+
+export const decodeWanImageSurface = decoder(wanEndpoints.image!);
+export const decodeWanProImageSurface = decoder(wanEndpoints.pro!);

package/packages/yt-dlp/src/download.ts

@@ -10,13 +10,22 @@
  * keep changing, so an unpinned copy makes the same link fetch differently on two machines. This is
  * the same shape WhisperX and OpenCV already use for their Python programs.
  */
-import { spawnSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import { copyFile, mkdtemp, readdir, rename, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { extname, join } from "node:path";
 
 import { requireVideoDownload } from "./environment.js";
 
+function runExec(file: string, args: readonly string[], options: { readonly timeout?: number; readonly maxBuffer?: number; readonly signal?: AbortSignal | undefined } = {}): Promise<{ readonly stdout: string; readonly stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(file, [...args], { encoding: "utf8", windowsHide: true, ...options }, (error, stdout, stderr) => {
+      if (error !== null) reject(Object.assign(error, { stdout, stderr }));
+      else resolve({ stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+
 /**
  * Whether this is a link to fetch rather than a path to open.
  *
@@ -42,30 +51,35 @@ export function isVideoUrl(value: string): boolean {
  * nothing under the bound. `--no-playlist` keeps a link inside a playlist from fetching the playlist.
  * The container follows the target's extension.
  */
-export async function downloadVideo(url: string, target: string): Promise<void> {
+export async function downloadVideo(url: string, target: string, options: { readonly signal?: AbortSignal } = {}): Promise<void> {
   const container = extname(target).slice(1).toLowerCase();
   if (!["mp4", "mkv", "webm", "mov"].includes(container)) {
     throw new Error(`${target} must end in .mp4, .mkv, .webm or .mov`);
   }
   const executable = requireVideoDownload();
-  const media = spawnSync("ffmpeg", ["-version"], { encoding: "utf8", windowsHide: true, timeout: 15_000 });
-  if (media.status !== 0) throw new Error("FFmpeg is unavailable on PATH; install your selected media toolchain before fetching video");
+  try {
+    await runExec("ffmpeg", ["-version"], { timeout: 15_000, signal: options.signal });
+  } catch (error) {
+    if (options.signal?.aborted) throw error;
+    throw new Error("FFmpeg is unavailable on PATH; install your selected media toolchain before fetching video");
+  }
   const work = await mkdtemp(join(tmpdir(), "hypit-fetch-"));
   try {
-    const result = spawnSync(executable, [
-      "--ignore-config", "--no-update", "--no-remote-components", "--no-plugin-dirs",
-      "--no-js-runtimes", "--js-runtimes", `node:${process.execPath}`,
-      "--no-playlist", "--no-progress", "--quiet",
-      "--format", "bv*+ba/b",
-      "--merge-output-format", container,
-      "--format-sort", "res:1080,vcodec:h264",
-      "--output", join(work, "video.%(ext)s"),
-      url,
-    ], { encoding: "utf8", windowsHide: true, timeout: 900_000 });
-
-    if (result.error !== undefined) throw result.error;
-    if (result.status !== 0) {
-      throw new Error(`yt-dlp could not fetch ${url}: ${(result.stderr ?? "").trim().slice(-2000)}`);
+    try {
+      await runExec(executable, [
+        "--ignore-config", "--no-update", "--no-remote-components", "--no-plugin-dirs",
+        "--no-js-runtimes", "--js-runtimes", `node:${process.execPath}`,
+        "--no-playlist", "--no-progress", "--quiet",
+        "--format", "bv*+ba/b",
+        "--merge-output-format", container,
+        "--format-sort", "res:1080,vcodec:h264",
+        "--output", join(work, "video.%(ext)s"),
+        url,
+      ], { timeout: 900_000, maxBuffer: 10 * 1024 * 1024, signal: options.signal });
+    } catch (cause) {
+      if (options.signal?.aborted) throw cause;
+      const error = cause as { stderr?: string; message?: string };
+      throw new Error(`yt-dlp could not fetch ${url}: ${(error.stderr ?? error.message ?? "").trim().slice(-2000)}`);
     }
     const finished = (await readdir(work)).filter((name) => !name.endsWith(".part"));
     const [file] = finished.sort();