@hypit/hypit 0.0.1 → 0.1.1

package/packages/seedance/src/index.ts

@@ -0,0 +1,329 @@
+import {
+  sealGenerationPortRequest,
+  sealGenerationPortTable,
+} from "@hypit/generation";
+import type {
+  GenerationPortTable,
+  GenerationPortValue,
+  GenerationRequest,
+} from "@hypit/generation";
+import { artifactTypes } from "@hypit/artifact";
+import type { SurfaceAttributeVocabulary, SurfacePortVocabulary } from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+import type { ResourceId } from "@hypit/protocol";
+
+export const seedanceModuleRef = { name: "@hypit/seedance", version: "1" } as const;
+export const seedanceModels = ["seedance-2", "seedance-2-fast", "seedance-2-mini", "seedance-2.5"] as const;
+export type SeedanceModel = typeof seedanceModels[number];
+
+const ASPECT_RATIOS = ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"] as const;
+
+const SEEDANCE_25_DURATIONS = [-1, ...Array.from({ length: 27 }, (_item, index) => index + 4)] as const;
+
+/**
+ * Exact Seedance model inputs. Provider wire names are deliberately absent:
+ * KIE, Volcengine or another service maps these ports independently.
+ *
+ * Seedance 2.5 is not treated as an alias for a Seedance 2 variant. Its public
+ * KIE contract widens prompt/reference capacities and duration independently,
+ * so it receives its own exact Capability while reusing the same three author
+ * Surfaces.
+ */
+function seedancePortTable(model: SeedanceModel): GenerationPortTable {
+  const is25 = model === "seedance-2.5";
+  return sealGenerationPortTable({
+    model,
+    result: "video",
+    ports: [
+      { name: "prompt", value: { kind: "text", maxChars: is25 ? 30_000 : 20_000 }, minItems: 1, maxItems: 1 },
+      { name: "referenceImage", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: is25 ? 30 : 9 },
+      { name: "referenceVideo", value: { kind: "media", accepts: ["video"] }, minItems: 0, maxItems: is25 ? 10 : 3 },
+      { name: "referenceAudio", value: { kind: "media", accepts: ["audio"] }, minItems: 0, maxItems: is25 ? 10 : 3 },
+      { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+      { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+      {
+        name: "resolution",
+        value: {
+          kind: "enum",
+          values: model === "seedance-2"
+            ? ["480p", "720p", "1080p", "4k"]
+            : is25 ? ["480p", "720p", "1080p"] : ["480p", "720p"],
+        },
+        minItems: 1,
+        maxItems: 1,
+      },
+      { name: "aspectRatio", value: { kind: "enum", values: [...ASPECT_RATIOS] }, minItems: 1, maxItems: 1 },
+      {
+        name: "duration",
+        value: is25
+          ? { kind: "enum", values: [...SEEDANCE_25_DURATIONS] }
+          : { kind: "number", integer: true, minimum: 4, maximum: 15 },
+        minItems: 1,
+        maxItems: 1,
+      },
+      { name: "generateAudio", value: { kind: "boolean" }, minItems: 1, maxItems: 1 },
+      { name: "webSearch", value: { kind: "boolean" }, minItems: 1, maxItems: 1 },
+    ],
+    requires: [
+      // First-frame, first-and-last-frame and multimodal reference are three
+      // scenarios the model cannot combine.
+      { kind: "atMostOneOf", ports: ["referenceImage", "firstFrame"] },
+      { kind: "atMostOneOf", ports: ["referenceVideo", "firstFrame"] },
+      { kind: "atMostOneOf", ports: ["referenceAudio", "firstFrame"] },
+      { kind: "requiresPresent", port: "lastFrame", needs: ["firstFrame"] },
+      ...(is25 ? [] : [
+        // Seedance 2 reference audio cannot travel alone; it needs a visual reference.
+        { kind: "requiresAnyOf" as const, port: "referenceAudio", anyOf: ["referenceImage", "referenceVideo"] },
+        { kind: "weightedTotal" as const, weights: { referenceImage: 1, referenceVideo: 1, referenceAudio: 1 }, maximum: 12 },
+      ]),
+    ],
+  });
+}
+
+export const seedancePorts: Readonly<Record<SeedanceModel, GenerationPortTable>> = {
+  "seedance-2": seedancePortTable("seedance-2"),
+  "seedance-2-fast": seedancePortTable("seedance-2-fast"),
+  "seedance-2-mini": seedancePortTable("seedance-2-mini"),
+  "seedance-2.5": seedancePortTable("seedance-2.5"),
+};
+
+export type SeedancePortMap = Readonly<Record<string, readonly GenerationPortValue[]>>;
+
+export function sealSeedanceRequest(model: SeedanceModel, ports: SeedancePortMap): GenerationRequest {
+  return sealGenerationPortRequest(seedancePorts[model], ports);
+}
+
+const seedanceBaseDefinition = defineExactModelModule({
+  module: seedanceModuleRef,
+  endpoints: ([
+    ["standard", "seedance-2"],
+    ["fast", "seedance-2-fast"],
+    ["mini", "seedance-2-mini"],
+    ["v25", "seedance-2.5"],
+  ] as const).map(([key, model]) => ({
+    key,
+    requestTypeName: model === "seedance-2.5"
+      ? "Seedance25Request"
+      : `${model.split("-").map((part) => part[0]!.toUpperCase() + part.slice(1)).join("")}Request`,
+    producerName: `request-${model}`,
+    ports: seedancePorts[model],
+  })),
+});
+
+export const seedanceEndpoints = seedanceBaseDefinition.endpoints;
+export const seedanceEndpointsByModel = {
+  "seedance-2": seedanceEndpoints.standard!,
+  "seedance-2-fast": seedanceEndpoints.fast!,
+  "seedance-2-mini": seedanceEndpoints.mini!,
+  "seedance-2.5": seedanceEndpoints.v25!,
+} as const;
+
+const seedanceCommonAttributes: readonly SurfaceAttributeVocabulary[] = [
+  {
+    name: "id",
+    kind: "identifier",
+    required: true,
+    summary: "Names this generation and prefixes the binding it publishes.",
+  },
+  {
+    name: "model",
+    kind: "literal",
+    required: true,
+    summary: "Chooses the exact Seedance variant that renders the video.",
+    values: [
+      "standard", "seedance-2",
+      "fast", "seedance-2-fast",
+      "mini", "seedance-2-mini",
+      "2.5", "seedance-2.5",
+    ],
+  },
+  {
+    name: "prompt",
+    kind: "reference",
+    required: true,
+    summary: "The Text edge describing the video the model renders.",
+    accepts: [textTypes.text],
+  },
+  {
+    name: "duration",
+    kind: "literal",
+    required: true,
+    summary: "Sets the length of the video in whole seconds within the model's range; the author's decision, measured beforehand with hypit measure.",
+  },
+  {
+    name: "resolution",
+    kind: "literal",
+    required: false,
+    summary: "Chooses the size band the model renders at.",
+    values: ["480p", "720p", "1080p", "4k"],
+  },
+  {
+    name: "aspect-ratio",
+    kind: "literal",
+    required: false,
+    summary: "Chooses the shape of the generated video.",
+    values: [...ASPECT_RATIOS],
+  },
+  {
+    name: "generate-audio",
+    kind: "literal",
+    required: false,
+    summary: "Decides whether the model generates audio alongside the picture.",
+    values: ["true", "false"],
+  },
+];
+
+const seedanceVideoPort: readonly SurfacePortVocabulary[] = [{
+  name: "video",
+  type: artifactTypes.blob,
+  summary: "The first ordered member of the generated set, addressed as `<id>.video`.",
+}];
+
+const seedanceSettingNotes: readonly string[] = [
+  "`resolution` defaults to `720p`, `aspect-ratio` to `9:16` and `generate-audio` to `false`.",
+  "`standard` offers `1080p` and `4k`; `2.5` offers `1080p`; `fast` and `mini` render at `480p` or `720p`.",
+  "`duration` is 4 to 15 seconds for `standard`, `fast` and `mini`, and `-1` for automatic or 4 to 30 seconds for `2.5`.",
+];
+
+export const seedanceMarkupSurfaces = [
+  {
+    name: "text-video",
+    tag: "TextVideo",
+    mode: "structured",
+    outputs: [
+      ...Object.values(seedanceEndpoints).flatMap((endpoint) => [
+        endpoint.draftType,
+        ...Object.values(endpoint.mediaBindings).map((binding) => binding.type),
+      ]),
+    ],
+    vocabulary: {
+      summary: "Generates one video with an exact Seedance model from a Text prompt alone.",
+      attributes: [
+        ...seedanceCommonAttributes,
+        {
+          name: "web-search",
+          kind: "literal",
+          required: false,
+          summary: "Decides whether the model consults Web Search while generating.",
+          values: ["true", "false"],
+        },
+      ],
+      ports: seedanceVideoPort,
+      example: '<seedance:TextVideo id="take-hook" model="mini" prompt={direction} duration="5" generate-audio="true"/>',
+      notes: [
+        ...seedanceSettingNotes,
+        "This is the only invocation shape that exposes Web Search.",
+        "The element accepts no children and no text content.",
+      ],
+    },
+  },
+  {
+    name: "frame-video",
+    tag: "FrameVideo",
+    mode: "structured",
+    outputs: [...Object.values(seedanceEndpoints).flatMap((endpoint) => [
+      endpoint.draftType, ...Object.values(endpoint.mediaBindings).map((binding) => binding.type),
+    ])],
+    vocabulary: {
+      summary: "Generates one video with an exact Seedance model from a Text prompt and the images the video opens and closes on.",
+      attributes: [
+        ...seedanceCommonAttributes,
+        {
+          name: "first-frame",
+          kind: "reference",
+          required: true,
+          summary: "The image Artifact the generated video opens on.",
+          accepts: [artifactTypes.blob],
+        },
+        {
+          name: "last-frame",
+          kind: "reference",
+          required: false,
+          summary: "The image Artifact the generated video closes on.",
+          accepts: [artifactTypes.blob],
+        },
+      ],
+      ports: seedanceVideoPort,
+      example: '<seedance:FrameVideo id="bridge" model="fast" prompt={direction} duration="5" first-frame={first.image} last-frame={last.image}/>',
+      notes: [
+        ...seedanceSettingNotes,
+        "Both frames are ordinary image Artifact edges; the Surface copies no runtime media into request metadata.",
+        "The element accepts no children and no text content.",
+      ],
+    },
+  },
+  {
+    name: "reference-video",
+    tag: "ReferenceVideo",
+    mode: "structured",
+    outputs: [...Object.values(seedanceEndpoints).flatMap((endpoint) => [
+      endpoint.draftType, ...Object.values(endpoint.mediaBindings).map((binding) => binding.type),
+    ])],
+    vocabulary: {
+      summary: "Generates one video with an exact Seedance model from a Text prompt and one or more image, video or audio references.",
+      attributes: seedanceCommonAttributes,
+      children: [{
+        tag: "Reference",
+        cardinality: "many",
+        summary: "Attaches one Artifact as a reference through exactly one of its `image`, `video` or `audio` references.",
+        attributes: [
+          {
+            name: "image",
+            kind: "reference",
+            required: false,
+            summary: "The image Artifact this reference contributes to the generation.",
+            accepts: [artifactTypes.blob],
+          },
+          {
+            name: "video",
+            kind: "reference",
+            required: false,
+            summary: "The video Artifact this reference contributes to the generation.",
+            accepts: [artifactTypes.blob],
+          },
+          {
+            name: "audio",
+            kind: "reference",
+            required: false,
+            summary: "The audio Artifact this reference contributes to the generation.",
+            accepts: [artifactTypes.blob],
+          },
+        ],
+      }],
+      ports: seedanceVideoPort,
+      example: `<seedance:ReferenceVideo
+  id="hook-take"
+  model="mini"
+  prompt={hook-prompt}
+  duration="8"
+  resolution="720p"
+  aspect-ratio="9:16"
+  generate-audio="true"
+>
+  <seedance:Reference image={presenter-clean}/>
+  <seedance:Reference audio={presenter-voice}/>
+</seedance:ReferenceVideo>`,
+      notes: [
+        ...seedanceSettingNotes,
+        "The element requires at least one `Reference` child, and the model's port limits cap how many of each role it accepts.",
+        "A `Reference` carries exactly one of `image`, `video` or `audio`, and is empty.",
+      ],
+    },
+  },
+] as const;
+
+/** The duration is an author literal on every Seedance Surface, so the manifest is the exact-model module's own. */
+export const seedanceManifest = seedanceBaseDefinition.manifest;
+export const seedanceComponent = seedanceBaseDefinition.component;
+export const seedanceDefinition = seedanceBaseDefinition;
+
+export {
+  createSeedanceAssembledGenerationFragment,
+  createSeedanceGenerationFragment,
+} from "./fragment.js";
+export {
+  decodeSeedanceFrameVideoSurface,
+  decodeSeedanceReferenceVideoSurface,
+  decodeSeedanceTextVideoSurface,
+} from "./surface.js";

package/packages/seedance/src/surface.ts

@@ -0,0 +1,355 @@
+import { artifactTypes } from "@hypit/artifact";
+import {
+  generationPort,
+  sealGenerationMediaBinding,
+  sealGenerationRequestDraft,
+} from "@hypit/generation";
+import type {
+  GenerationMediaPort,
+  GenerationMediaRole,
+  GenerationPortTable,
+} from "@hypit/generation";
+import { exactModelMediaInputNames, exactModelTextInputName } from "@hypit/model-kit";
+import type { ExactModelEndpoint, ExactModelMediaInput } from "@hypit/model-kit";
+import type { CanonicalValue } from "@hypit/protocol";
+import { textTypes, verifyText } from "@hypit/text";
+import type {
+  MarkupAttributeValue,
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+} from "@hypit/markup";
+
+import { createSeedanceAssembledGenerationFragment } from "./fragment.js";
+import { seedanceEndpoints, seedancePorts } from "./index.js";
+import type { SeedanceModel, SeedancePortMap } from "./index.js";
+
+type MediaInput = {
+  readonly port: "referenceImage" | "referenceVideo" | "referenceAudio" | "firstFrame" | "lastFrame";
+  readonly role: GenerationMediaRole;
+  readonly source: SurfaceResolvedReference;
+};
+
+function localName(value: string): string {
+  return value.includes(":") ? value.slice(value.lastIndexOf(":") + 1) : value;
+}
+
+function attributes(element: StructuredElement, required: readonly string[], optional: readonly string[] = []): void {
+  const allowed = new Set([...required, ...optional]);
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.has(name));
+  if (unknown.length > 0 || required.some((name) => element.attributes[name] === undefined)) {
+    throw new Error(`${element.name} requires ${required.join(", ")}`
+      + (optional.length === 0 ? "" : `; optional: ${optional.join(", ")}`));
+  }
+}
+
+function empty(element: StructuredElement): void {
+  if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
+    throw new Error(`${element.name} must be empty`);
+  }
+}
+
+function stringAttribute(element: StructuredElement, name: string): string {
+  const value = element.attributes[name];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${element.name}.${name} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function optionalStringAttribute(element: StructuredElement, name: string): string | undefined {
+  const value = element.attributes[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${element.name}.${name} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function referencePath(element: StructuredElement, name: string): string {
+  const value: MarkupAttributeValue | undefined = element.attributes[name];
+  if (typeof value !== "object" || value.kind !== "reference" || value.path.length === 0) {
+    throw new Error(`${element.name}.${name} must be a whole-value reference`);
+  }
+  return value.path;
+}
+
+function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
+  return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
+}
+
+function resolved(
+  element: StructuredElement,
+  name: string,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const path = referencePath(element, name);
+  const value = resolveReference(path);
+  if (value === undefined) throw new Error(`${element.name}.${name} cannot resolve ${path}`);
+  return value;
+}
+
+function prompt(reference: SurfaceResolvedReference, subject: string): void {
+  if (!sameType(reference.type, textTypes.text)) throw new Error(`${subject} must reference Text`);
+  const value = reference.record?.value;
+  if (value !== undefined) {
+    if (value.kind !== "inline") throw new Error(`${subject} has an invalid authored Text value`);
+    verifyText(value.value);
+  }
+}
+
+function mediaReference(
+  reference: SurfaceResolvedReference,
+  role: GenerationMediaRole,
+  subject: string,
+): SurfaceResolvedReference {
+  if (!sameType(reference.type, artifactTypes.blob)) throw new Error(`${subject} must reference a BlobArtifact`);
+  const value = reference.record?.value;
+  if (value !== undefined && (value.kind !== "blob" || !value.mediaType.startsWith(`${role}/`))) {
+    throw new Error(`${subject} must reference ${role} media`);
+  }
+  return reference;
+}
+
+function modelSelection(element: StructuredElement) {
+  const requested = stringAttribute(element, "model");
+  if (requested === "standard" || requested === "seedance-2") {
+    return { endpoint: seedanceEndpoints.standard!, model: "seedance-2" as const };
+  }
+  if (requested === "fast" || requested === "seedance-2-fast") {
+    return { endpoint: seedanceEndpoints.fast!, model: "seedance-2-fast" as const };
+  }
+  if (requested === "mini" || requested === "seedance-2-mini") {
+    return { endpoint: seedanceEndpoints.mini!, model: "seedance-2-mini" as const };
+  }
+  if (requested === "2.5" || requested === "seedance-2.5") {
+    return { endpoint: seedanceEndpoints.v25!, model: "seedance-2.5" as const };
+  }
+  throw new Error(`${element.name}.model must be standard, fast, mini or 2.5`);
+}
+
+function integerAttribute(element: StructuredElement, name: string): number {
+  const value = Number(stringAttribute(element, name));
+  if (!Number.isSafeInteger(value)) throw new Error(`${element.name}.${name} must be an integer`);
+  return value;
+}
+
+function booleanAttribute(element: StructuredElement, name: string, fallback: boolean): boolean {
+  const value = optionalStringAttribute(element, name);
+  if (value === undefined) return fallback;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new Error(`${element.name}.${name} must be true or false`);
+}
+
+function enumeratedPort(table: GenerationPortTable, name: string): readonly (string | number)[] {
+  const port = generationPort(table, name);
+  if (port.value.kind !== "enum") throw new Error(`${table.model} port ${name} is not enumerated`);
+  return port.value.values;
+}
+
+function generationSettings(
+  element: StructuredElement,
+  model: SeedanceModel,
+): SeedancePortMap {
+  const table = seedancePorts[model];
+  const duration = generationPort(table, "duration");
+  // The author's literal, measured beforehand; the model's declared range is the only check.
+  const durationSec = integerAttribute(element, "duration");
+  if (duration.value.kind === "number") {
+    const { minimum = 0, maximum = Number.MAX_SAFE_INTEGER } = duration.value;
+    if (durationSec < minimum || durationSec > maximum) {
+      throw new Error(`${element.name}.duration must be between ${minimum} and ${maximum} seconds`);
+    }
+  } else if (duration.value.kind === "enum") {
+    if (!duration.value.values.includes(durationSec)) {
+      throw new Error(`${element.name}.duration must be -1 (auto) or between 4 and 30 seconds for ${model}`);
+    }
+  } else {
+    throw new Error("Seedance duration port is not numeric");
+  }
+  const resolutions = enumeratedPort(table, "resolution");
+  const resolution = optionalStringAttribute(element, "resolution") ?? "720p";
+  if (!resolutions.includes(resolution)) {
+    throw new Error(`${element.name}.resolution must be ${resolutions.join(", ")} for ${model}`);
+  }
+  const aspectRatios = enumeratedPort(table, "aspectRatio");
+  const aspectRatio = optionalStringAttribute(element, "aspect-ratio") ?? "9:16";
+  if (!aspectRatios.includes(aspectRatio)) throw new Error(`${element.name}.aspect-ratio is not supported by Seedance`);
+  return {
+    duration: [durationSec],
+    resolution: [resolution],
+    aspectRatio: [aspectRatio],
+    generateAudio: [booleanAttribute(element, "generate-audio", false)],
+    webSearch: [booleanAttribute(element, "web-search", false)],
+  };
+}
+
+const REFERENCE_PORTS = {
+  image: "referenceImage",
+  video: "referenceVideo",
+  audio: "referenceAudio",
+} as const;
+
+function referenceInputs(
+  element: StructuredElement,
+  model: SeedanceModel,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): MediaInput[] {
+  const accepted = Object.keys(REFERENCE_PORTS) as readonly GenerationMediaRole[];
+  const result: MediaInput[] = [];
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Reference children`);
+      continue;
+    }
+    if (localName(child.name) !== "Reference") throw new Error(`${element.name} accepts only Reference children`);
+    attributes(child, [], accepted);
+    empty(child);
+    const kinds = accepted.filter((kind) => child.attributes[kind] !== undefined);
+    if (kinds.length !== 1) throw new Error(`${child.name} requires exactly one of ${accepted.join(", ")}`);
+    const role = kinds[0]!;
+    result.push({
+      role,
+      port: REFERENCE_PORTS[role],
+      source: mediaReference(resolved(child, role, resolveReference), role, `${child.name}.${role}`),
+    });
+  }
+  if (result.length === 0) throw new Error(`${element.name} requires at least one Reference child`);
+  const table = seedancePorts[model];
+  for (const role of accepted) {
+    const port = generationPort(table, REFERENCE_PORTS[role]);
+    const used = result.filter((item) => item.role === role).length;
+    if (used > port.maxItems) throw new Error(`${element.name} accepts at most ${port.maxItems} ${role} references`);
+  }
+  return result;
+}
+
+function frameInputs(
+  element: StructuredElement,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): MediaInput[] {
+  const first = mediaReference(resolved(element, "first-frame", resolveReference), "image", `${element.name}.first-frame`);
+  const result: MediaInput[] = [{ port: "firstFrame", role: "image", source: first }];
+  if (element.attributes["last-frame"] !== undefined) {
+    result.push({
+      port: "lastFrame",
+      role: "image",
+      source: mediaReference(resolved(element, "last-frame", resolveReference), "image", `${element.name}.last-frame`),
+    });
+  }
+  return result;
+}
+
+function assembleMedia(
+  id: string,
+  endpoint: ExactModelEndpoint,
+  values: readonly MediaInput[],
+  range: StructuredElement["range"],
+) {
+  const records: Array<{
+    readonly id: string;
+    readonly type: SurfaceResolvedReference["type"];
+    readonly value: { readonly kind: "inline"; readonly value: CanonicalValue };
+    readonly range: StructuredElement["range"];
+  }> = [];
+  const inputs: Record<string, SurfaceResolvedReference["ref"] | { readonly kind: "record"; readonly id: string }> = {};
+  const mediaInputs = values.map((value, index): ExactModelMediaInput => {
+    const name = `media-${String(index + 1).padStart(4, "0")}`;
+    const binding = endpoint.mediaBindings[value.port];
+    if (binding === undefined) throw new Error(`${endpoint.ports.model} has no media port ${value.port}`);
+    const port = generationPort(endpoint.ports, value.port);
+    if (port.value.kind !== "media") throw new Error(`${endpoint.ports.model} port ${value.port} is not media`);
+    const bindingId = `${id}.${name}.binding`;
+    records.push({
+      id: bindingId,
+      type: binding.type,
+      value: {
+        kind: "inline",
+        value: sealGenerationMediaBinding(port as GenerationMediaPort, { role: value.role }) as unknown as CanonicalValue,
+      },
+      range,
+    });
+    const names = exactModelMediaInputNames(name);
+    inputs[names.binding] = { kind: "record", id: bindingId };
+    inputs[names.artifact] = value.source.ref;
+    return { name, port: value.port };
+  });
+  return { mediaInputs, records, inputs };
+}
+
+function generationOutput(args: {
+  readonly element: StructuredElement;
+  readonly endpoint: ExactModelEndpoint;
+  readonly model: SeedanceModel;
+  readonly promptSource: SurfaceResolvedReference;
+  readonly media: readonly MediaInput[];
+  readonly resolveReference: (path: string) => SurfaceResolvedReference | undefined;
+}) {
+  const { element, endpoint, model, promptSource } = args;
+  const id = stringAttribute(element, "id");
+  const assembled = assembleMedia(id, endpoint, args.media, element.range);
+  const draft = sealGenerationRequestDraft(seedancePorts[model], generationSettings(element, model));
+  const fragment = createSeedanceAssembledGenerationFragment(
+    endpoint,
+    assembled.mediaInputs,
+    [{ name: "prompt", port: "prompt" }],
+  );
+  const draftId = `${id}.draft`;
+  return {
+    records: [{
+      id: draftId,
+      type: endpoint.draftType,
+      value: { kind: "inline" as const, value: draft as unknown as CanonicalValue },
+      range: element.range,
+    }, ...assembled.records],
+    components: [{
+      id,
+      fragment: fragment.id,
+      inputs: {
+        draft: { kind: "record" as const, id: draftId },
+        [exactModelTextInputName("prompt")]: promptSource.ref,
+        ...assembled.inputs,
+      },
+      outputs: { video: `${id}.video` },
+      range: element.range,
+    }],
+    fragments: [fragment],
+  };
+}
+
+const COMMON_OPTIONAL = ["resolution", "aspect-ratio", "generate-audio"] as const;
+
+export const decodeSeedanceTextVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  attributes(element, ["id", "model", "prompt", "duration"], [...COMMON_OPTIONAL, "web-search"]);
+  empty(element);
+  const selected = modelSelection(element);
+  const promptSource = resolved(element, "prompt", resolveReference);
+  prompt(promptSource, `${element.name}.prompt`);
+  return generationOutput({ element, ...selected, promptSource, media: [], resolveReference });
+};
+
+export const decodeSeedanceFrameVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  attributes(element, ["id", "model", "prompt", "duration", "first-frame"], [...COMMON_OPTIONAL, "last-frame"]);
+  empty(element);
+  const selected = modelSelection(element);
+  const promptSource = resolved(element, "prompt", resolveReference);
+  prompt(promptSource, `${element.name}.prompt`);
+  return generationOutput({
+    element, ...selected, promptSource, media: frameInputs(element, resolveReference), resolveReference,
+  });
+};
+
+export const decodeSeedanceReferenceVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  attributes(element, ["id", "model", "prompt", "duration"], COMMON_OPTIONAL);
+  const selected = modelSelection(element);
+  const promptSource = resolved(element, "prompt", resolveReference);
+  prompt(promptSource, `${element.name}.prompt`);
+  return generationOutput({
+    element,
+    ...selected,
+    promptSource,
+    media: referenceInputs(element, selected.model, resolveReference),
+    resolveReference,
+  });
+};