@hypit/hypit 0.0.1 → 0.1.0

package/packages/mimo-speech/src/index.ts

@@ -0,0 +1,160 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationRequestDraft, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type { SurfaceAttributeVocabulary, SurfacePortVocabulary } from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const mimoSpeechModuleRef = { name: "@hypit/mimo-speech", version: "1" } as const;
+export const mimoSpeechModels = [
+  "mimo-v2.5-tts-voicedesign",
+  "mimo-v2.5-tts-voiceclone",
+] as const;
+export type MimoSpeechModel = typeof mimoSpeechModels[number];
+
+// Xiaomi documents no fixed character ceiling. Service-side limits stay service-side
+// instead of becoming an invented model constraint in Author Source.
+const spokenText = { kind: "text" } as const;
+const instruction = { kind: "text" } as const;
+
+function table(model: MimoSpeechModel): GenerationPortTable {
+  if (model === "mimo-v2.5-tts-voicedesign") {
+    return sealGenerationPortTable({
+      model,
+      result: "audio",
+      ports: [
+        { name: "text", value: spokenText, minItems: 1, maxItems: 1 },
+        { name: "voiceDescription", value: instruction, minItems: 1, maxItems: 1 },
+      ],
+      requires: [],
+    });
+  }
+  return sealGenerationPortTable({
+    model,
+    result: "audio",
+    ports: [
+      { name: "text", value: spokenText, minItems: 1, maxItems: 1 },
+      { name: "instruction", value: instruction, minItems: 0, maxItems: 1 },
+      { name: "voiceReference", value: { kind: "media", accepts: ["audio"] }, minItems: 1, maxItems: 1 },
+    ],
+    requires: [],
+  });
+}
+
+export const mimoSpeechPorts: Readonly<Record<MimoSpeechModel, GenerationPortTable>> = {
+  "mimo-v2.5-tts-voicedesign": table("mimo-v2.5-tts-voicedesign"),
+  "mimo-v2.5-tts-voiceclone": table("mimo-v2.5-tts-voiceclone"),
+};
+
+export function sealMimoSpeechRequest(
+  model: MimoSpeechModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+  return sealGenerationPortRequest(mimoSpeechPorts[model], ports);
+}
+
+export function sealMimoSpeechRequestDraft(
+  model: MimoSpeechModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+) {
+  return sealGenerationRequestDraft(mimoSpeechPorts[model], ports);
+}
+
+const base = defineExactModelModule({
+  module: mimoSpeechModuleRef,
+  endpoints: ([
+    ["voiceDesign", "mimo-v2.5-tts-voicedesign", "MimoVoiceDesignRequest"],
+    ["voiceClone", "mimo-v2.5-tts-voiceclone", "MimoVoiceCloneRequest"],
+  ] as const).map(([key, model, requestTypeName]) => ({
+    key,
+    requestTypeName,
+    producerName: `request-${model}`,
+    ports: mimoSpeechPorts[model],
+  })),
+});
+
+export const mimoSpeechEndpoints = base.endpoints;
+
+const spokenAttributes: readonly SurfaceAttributeVocabulary[] = [
+  {
+    name: "id",
+    kind: "identifier",
+    required: true,
+    summary: "Names this speech request and prefixes the binding it publishes.",
+  },
+  {
+    name: "speech",
+    kind: "reference",
+    required: true,
+    summary: "The Text edge whose exact words are spoken.",
+    accepts: [textTypes.text],
+  },
+];
+
+const referencePort: readonly SurfacePortVocabulary[] = [{
+  name: "reference",
+  type: artifactTypes.blob,
+  summary: "The designed voice reference, addressed as `<id>.reference`.",
+}];
+
+const audioPort: readonly SurfacePortVocabulary[] = [{
+  name: "audio",
+  type: artifactTypes.blob,
+  summary: "The independent speech, addressed as `<id>.audio`.",
+}];
+
+export const mimoSpeechMarkupSurfaces = [
+  {
+    name: "voiceDesign", tag: "VoiceDesign", mode: "structured",
+    outputs: [mimoSpeechEndpoints.voiceDesign.draftType],
+    vocabulary: {
+      summary: "Creates a reusable voice reference from a natural-language voice description.",
+      attributes: spokenAttributes,
+      ports: referencePort,
+      text: "The element's own text is the voice description and is required.",
+      example: `<mimo:VoiceDesign id="host" speech={story.segment.voiceSample.speech}>
+  A clear young woman with a grounded, confident conversational delivery.
+</mimo:VoiceDesign>`,
+      notes: [
+        "The element accepts no child elements; only its text is read.",
+        "The result is an ordinary audio Resource that can be supplied anywhere an audio reference is accepted.",
+      ],
+    },
+  },
+  {
+    name: "voiceClone", tag: "VoiceClone", mode: "structured",
+    outputs: [
+      mimoSpeechEndpoints.voiceClone.draftType,
+      ...Object.values(mimoSpeechEndpoints.voiceClone.mediaBindings).map((binding) => binding.type),
+    ],
+    vocabulary: {
+      summary: "Creates independent speech in the voice heard in one accepted audio reference.",
+      attributes: [
+        ...spokenAttributes,
+        {
+          name: "voice",
+          kind: "reference",
+          required: true,
+          summary: "The audio Resource carrying the voice identity to reproduce.",
+          accepts: [artifactTypes.blob],
+        },
+      ],
+      ports: audioPort,
+      text: "The element's own text is an optional delivery instruction.",
+      example: `<mimo:VoiceClone id="narration" speech={story.segment.reveal.speech} voice={host.reference}>
+  Quietly confident, with a short pause before the final word.
+</mimo:VoiceClone>`,
+      notes: [
+        "The element accepts no child elements; only its text is read.",
+        "The voice reference remains a normal audio Resource rather than a separate identity record.",
+      ],
+    },
+  },
+] as const;
+
+export const mimoSpeechManifest = { ...base.manifest } as const;
+export const mimoSpeechComponent = base.component;
+export const mimoSpeechDefinition = { ...base, manifest: mimoSpeechManifest };
+
+export { createMimoSpeechAudioFragment } from "./fragment.js";
+export { decodeMimoVoiceCloneSurface, decodeMimoVoiceDesignSurface } from "./surface.js";

package/packages/mimo-speech/src/surface.ts

@@ -0,0 +1,193 @@
+import { artifactTypes } from "@hypit/artifact";
+import { generationPort, sealGenerationMediaBinding } from "@hypit/generation";
+import type { GenerationMediaPort, GenerationPortValue } from "@hypit/generation";
+import { exactModelMediaInputNames, exactModelTextInputName } from "@hypit/model-kit";
+import type { ExactModelEndpoint, ExactModelMediaInput, ExactModelTextInput } 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 { createMimoSpeechAudioFragment } from "./fragment.js";
+import { mimoSpeechEndpoints, sealMimoSpeechRequestDraft } from "./index.js";
+
+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 attributes(element: StructuredElement, required: readonly string[]): void {
+  const allowed = new Set(required);
+  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(", ")}`);
+  }
+}
+
+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 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 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 speechText(reference: SurfaceResolvedReference, subject: string): SurfaceResolvedReference {
+  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);
+  }
+  return reference;
+}
+
+function voiceReference(reference: SurfaceResolvedReference, subject: string): SurfaceResolvedReference {
+  if (!sameType(reference.type, artifactTypes.blob)) throw new Error(`${subject} must reference an audio Resource`);
+  const value = reference.record?.value;
+  if (value !== undefined && (value.kind !== "blob" || !value.mediaType.startsWith("audio/"))) {
+    throw new Error(`${subject} must reference audio media`);
+  }
+  return reference;
+}
+
+function body(element: StructuredElement, required: boolean): string | undefined {
+  if (element.children.some((child) => child.kind === "element")) {
+    throw new Error(`${element.name} accepts instruction text only`);
+  }
+  const lines = element.children.map((child) => child.kind === "text" ? child.value : "").join("")
+    .replaceAll("\r\n", "\n").split("\n");
+  while (lines[0]?.trim() === "") lines.shift();
+  while (lines.at(-1)?.trim() === "") lines.pop();
+  const indents = lines.filter((line) => line.trim()).map((line) => /^\s*/u.exec(line)?.[0].length ?? 0);
+  const indent = indents.length === 0 ? 0 : Math.min(...indents);
+  const value = lines.map((line) => line.slice(indent).trimEnd()).join("\n").trim();
+  if (value.length === 0) {
+    if (required) throw new Error(`${element.name} requires a voice description in its body`);
+    return undefined;
+  }
+  return value;
+}
+
+function output(
+  element: StructuredElement,
+  endpoint: ExactModelEndpoint,
+  draft: ReturnType<typeof sealMimoSpeechRequestDraft>,
+  outputName: "reference" | "audio",
+  text: readonly { readonly input: ExactModelTextInput; readonly source: SurfaceResolvedReference }[],
+  media: readonly { readonly input: ExactModelMediaInput; readonly source: SurfaceResolvedReference }[] = [],
+) {
+  const id = stringAttribute(element, "id");
+  const draftId = `${id}.draft`;
+  const records: Array<{
+    readonly id: string;
+    readonly type: SurfaceResolvedReference["type"];
+    readonly value: { readonly kind: "inline"; readonly value: CanonicalValue };
+    readonly range: StructuredElement["range"];
+  }> = [{
+    id: draftId,
+    type: endpoint.draftType,
+    value: { kind: "inline", value: draft as unknown as CanonicalValue },
+    range: element.range,
+  }];
+  const inputs: Record<string, SurfaceResolvedReference["ref"] | { readonly kind: "record"; readonly id: string }> = {
+    draft: { kind: "record", id: draftId },
+  };
+  for (const item of text) inputs[exactModelTextInputName(item.input.name)] = item.source.ref;
+  for (const item of media) {
+    const binding = endpoint.mediaBindings[item.input.port];
+    if (binding === undefined) throw new Error(`${endpoint.ports.model} has no media port ${item.input.port}`);
+    const port = generationPort(endpoint.ports, item.input.port);
+    if (port.value.kind !== "media") throw new Error(`${endpoint.ports.model} port ${item.input.port} is not media`);
+    const names = exactModelMediaInputNames(item.input.name);
+    const bindingId = `${id}.${item.input.name}.binding`;
+    records.push({
+      id: bindingId,
+      type: binding.type,
+      value: {
+        kind: "inline",
+        value: sealGenerationMediaBinding(port as GenerationMediaPort, { role: "audio" }) as unknown as CanonicalValue,
+      },
+      range: element.range,
+    });
+    inputs[names.binding] = { kind: "record", id: bindingId };
+    inputs[names.artifact] = item.source.ref;
+  }
+  const fragment = createMimoSpeechAudioFragment(
+    endpoint,
+    media.map((item) => item.input),
+    text.map((item) => item.input),
+  );
+  return {
+    records,
+    components: [{
+      id,
+      fragment: fragment.id,
+      inputs,
+      outputs: { audio: `${id}.${outputName}` },
+      range: element.range,
+    }],
+    fragments: [fragment],
+  };
+}
+
+function speechInput(
+  element: StructuredElement,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+) {
+  return {
+    input: { name: "speech", port: "text" },
+    source: speechText(resolved(element, "speech", resolveReference), `${element.name}.speech`),
+  } as const;
+}
+
+export const decodeMimoVoiceDesignSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  attributes(element, ["id", "speech"]);
+  return output(
+    element,
+    mimoSpeechEndpoints.voiceDesign,
+    sealMimoSpeechRequestDraft("mimo-v2.5-tts-voicedesign", { voiceDescription: [body(element, true)!] }),
+    "reference",
+    [speechInput(element, resolveReference)],
+  );
+};
+
+export const decodeMimoVoiceCloneSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  attributes(element, ["id", "speech", "voice"]);
+  const instruction = body(element, false);
+  const ports: Record<string, readonly GenerationPortValue[]> = {};
+  if (instruction !== undefined) ports.instruction = [instruction];
+  return output(
+    element,
+    mimoSpeechEndpoints.voiceClone,
+    sealMimoSpeechRequestDraft("mimo-v2.5-tts-voiceclone", ports),
+    "audio",
+    [speechInput(element, resolveReference)],
+    [{
+      input: { name: "voice", port: "voiceReference" },
+      source: voiceReference(resolved(element, "voice", resolveReference), `${element.name}.voice`),
+    }],
+  );
+};

package/packages/minimax-h3/README.md

@@ -0,0 +1,21 @@
+# `@hypit/minimax-h3`
+
+Exact author/compute contracts and package-owned author Surfaces for MiniMax H3 video generation.
+
+Text, frame-guided and subject-reference modes are separate Surfaces rather than one dynamic
+port mode. Each produces an ordinary video Artifact. This package owns request semantics
+and validation only; Provider calls, credentials, retries and queueing belong to a Runtime Endpoint
+such as `@hypit/provider-kie`.
+
+```xml
+<h3:TextVideo id="idea" prompt={prompt} duration="6" resolution="768P" aspect-ratio="9:16"/>
+<h3:FrameVideo id="motion" prompt={motionPrompt} duration="6" resolution="2K"
+  first-frame={cover.image} last-frame={ending.image}/>
+<h3:ReferenceVideo id="montage" prompt={montagePrompt} duration="8" resolution="768P" aspect-ratio="9:16">
+  <h3:Reference image={person.image}/>
+  <h3:Reference video={gesture.video}/>
+</h3:ReferenceVideo>
+```
+
+The Surface makes every prompt/media dependency an explicit graph edge and leaves execution to a Provider.
+`FrameVideo` accepts a first frame, a last frame, or both; either frame is an ordinary image Artifact edge.

package/packages/minimax-h3/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@hypit/minimax-h3",
+  "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/minimax-h3/src/activation.ts

@@ -0,0 +1,14 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import { minimaxH3Component, minimaxH3Definition, minimaxH3Manifest, minimaxH3ModuleRef,
+  minimaxH3MarkupSurfaces } from "./index.js";
+import { decodeMinimaxFrameVideoSurface, decodeMinimaxReferenceVideoSurface, decodeMinimaxTextVideoSurface } from "./surface.js";
+export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest: minimaxH3Manifest }], components: [minimaxH3Component], hostFacets: [
+  minimaxH3Definition.hostFacet,
+  createMarkupSurfaceHostFacet({ module: minimaxH3ModuleRef,
+    declaration: minimaxH3MarkupSurfaces.find((item) => item.name === "text-video")!, handler: decodeMinimaxTextVideoSurface }),
+  createMarkupSurfaceHostFacet({ module: minimaxH3ModuleRef,
+    declaration: minimaxH3MarkupSurfaces.find((item) => item.name === "frame-video")!, handler: decodeMinimaxFrameVideoSurface }),
+  createMarkupSurfaceHostFacet({ module: minimaxH3ModuleRef,
+    declaration: minimaxH3MarkupSurfaces.find((item) => item.name === "reference-video")!, handler: decodeMinimaxReferenceVideoSurface }),
+] };
+export default hypitPackage;

package/packages/minimax-h3/src/index.ts

@@ -0,0 +1,188 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type {
+  SurfaceAttributeVocabulary,
+  SurfacePortVocabulary,
+  SurfaceVocabulary,
+} from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const minimaxH3ModuleRef = { name: "@hypit/minimax-h3", version: "1" } as const;
+
+/**
+ * What MiniMax H3 accepts is a property of the trained model, not of whichever
+ * service resells it. A service that splits these ports across several of its
+ * own endpoints expresses that in its wire mapping.
+ *
+ * `768P` and `2K` are the model's own two output tiers — H3-Base renders at
+ * 768p and H3-Regenerate-2K re-renders from the original context — so the
+ * spelling is MiniMax's, not any gateway's.
+ */
+export const minimaxH3Ports: GenerationPortTable = sealGenerationPortTable({
+  model: "minimax-h3",
+  result: "video",
+  ports: [
+    { name: "prompt", value: { kind: "text", maxChars: 7_000 }, minItems: 1, maxItems: 1 },
+    {
+      name: "duration",
+      value: { kind: "number", integer: true, minimum: 4, maximum: 15 },
+      minItems: 1,
+      maxItems: 1,
+    },
+    { name: "resolution", value: { kind: "enum", values: ["768P", "2K"] }, minItems: 0, maxItems: 1 },
+    {
+      name: "aspectRatio",
+      value: { kind: "enum", values: ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"] },
+      minItems: 0,
+      maxItems: 1,
+    },
+    { name: "referenceImage", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 9 },
+    { name: "referenceVideo", value: { kind: "media", accepts: ["video"] }, minItems: 0, maxItems: 3 },
+    { name: "referenceAudio", value: { kind: "media", accepts: ["audio"] }, minItems: 0, maxItems: 3 },
+    { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+    { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+  ],
+  requires: [
+    { kind: "atMostOneOf", ports: ["referenceImage", "firstFrame"] },
+    { kind: "atMostOneOf", ports: ["referenceImage", "lastFrame"] },
+    { kind: "atMostOneOf", ports: ["referenceVideo", "firstFrame"] },
+    { kind: "atMostOneOf", ports: ["referenceVideo", "lastFrame"] },
+    { kind: "atMostOneOf", ports: ["referenceAudio", "firstFrame"] },
+    { kind: "atMostOneOf", ports: ["referenceAudio", "lastFrame"] },
+    { kind: "requiresAnyOf", port: "referenceAudio", anyOf: ["referenceImage", "referenceVideo"] },
+    // A first/last frame run inherits its framing from the uploaded image, so the
+    // model takes no aspect ratio in that mode.
+    { kind: "atMostOneOf", ports: ["aspectRatio", "firstFrame"] },
+    { kind: "atMostOneOf", ports: ["aspectRatio", "lastFrame"] },
+    { kind: "weightedTotal", weights: { referenceImage: 1, referenceVideo: 1, referenceAudio: 1 }, maximum: 12 },
+  ],
+});
+
+export function sealMinimaxH3Request(
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+  return sealGenerationPortRequest(minimaxH3Ports, ports);
+}
+
+const minimaxH3BaseDefinition = defineExactModelModule({
+  module: minimaxH3ModuleRef,
+  endpoints: [{
+    key: "video",
+    requestTypeName: "MinimaxH3Request",
+    producerName: "request-minimax-h3",
+    ports: minimaxH3Ports,
+  }],
+});
+
+export const minimaxH3Endpoints = minimaxH3BaseDefinition.endpoints;
+export const minimaxH3Component = minimaxH3BaseDefinition.component;
+const endpoint = minimaxH3Endpoints.video!;
+const declaration = (
+  name: string, tag: string,
+  bindings: readonly (keyof typeof endpoint.mediaBindings)[],
+  vocabulary: SurfaceVocabulary,
+) => ({
+  name, tag, mode: "structured" as const,
+  outputs: [endpoint.draftType, ...bindings.map((port) => endpoint.mediaBindings[port]!.type)],
+  vocabulary,
+});
+
+const minimaxH3Common: readonly SurfaceAttributeVocabulary[] = [
+  { name: "id", kind: "identifier", required: true,
+    summary: "Names this generation so its video Artifact can be referenced elsewhere in the Source." },
+  { name: "prompt", kind: "reference", required: true, accepts: [textTypes.text],
+    summary: "Selects the Text the model generates from." },
+  { name: "duration", kind: "literal", required: true,
+    summary: "Sets the length of the generated video in whole seconds." },
+  { name: "resolution", kind: "literal", required: false, values: ["768P", "2K"],
+    summary: "Chooses which of the model's two output tiers renders the video." },
+];
+
+const minimaxH3AspectRatio: SurfaceAttributeVocabulary = {
+  name: "aspect-ratio", kind: "literal", required: false,
+  values: ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"],
+  summary: "Sets the Frame shape of the generated video.",
+};
+
+const minimaxH3VideoPorts: readonly SurfacePortVocabulary[] = [
+  { name: "video", type: artifactTypes.blob, summary: "The generated video Artifact." },
+];
+
+const minimaxH3DurationNote = "`duration` is a whole number of seconds between 4 and 15.";
+const minimaxH3ResolutionNote = "`768P` and `2K` are the model's own tiers: H3-Base renders at 768p and H3-Regenerate-2K re-renders from the original context.";
+
+export const minimaxH3MarkupSurfaces = [
+    declaration("text-video", "TextVideo", [], {
+      summary: "Generates one video Artifact from a Text prompt with the MiniMax H3 model.",
+      attributes: [...minimaxH3Common, minimaxH3AspectRatio],
+      ports: minimaxH3VideoPorts,
+      example: '<h3:TextVideo id="idea" prompt={prompt} duration="6" resolution="768P" aspect-ratio="9:16"/>',
+      notes: [
+        minimaxH3DurationNote,
+        minimaxH3ResolutionNote,
+        "The element takes no children and no text content.",
+      ],
+    }),
+    declaration("frame-video", "FrameVideo", ["firstFrame", "lastFrame"], {
+      summary: "Generates one video Artifact from a first frame, a last frame, or both with the MiniMax H3 model.",
+      attributes: [
+        ...minimaxH3Common,
+        { name: "first-frame", kind: "reference", required: false, accepts: [artifactTypes.blob],
+          summary: "Selects the image Artifact the generated video opens on." },
+        { name: "last-frame", kind: "reference", required: false, accepts: [artifactTypes.blob],
+          summary: "Selects the image Artifact the generated video closes on." },
+      ],
+      ports: minimaxH3VideoPorts,
+      example: [
+        '<h3:FrameVideo id="motion" prompt={motionPrompt} duration="6" resolution="2K"',
+        "  first-frame={cover.image} last-frame={ending.image}/>",
+      ].join("\n"),
+      notes: [
+        minimaxH3DurationNote,
+        minimaxH3ResolutionNote,
+        "A first/last frame run inherits its framing from the given image, so this element takes no `aspect-ratio`.",
+        "At least one of `first-frame` or `last-frame` is required; both reference image Blobs.",
+        "The element takes no children and no text content.",
+      ],
+    }),
+    declaration("reference-video", "ReferenceVideo", ["referenceImage", "referenceVideo", "referenceAudio"], {
+      summary: "Generates one video Artifact from a Text prompt and the image, video and audio subjects it carries with the MiniMax H3 model.",
+      attributes: [...minimaxH3Common, minimaxH3AspectRatio],
+      children: [
+        { tag: "Reference", cardinality: "many",
+          summary: "Attaches one subject Artifact the model generates from, chosen by an `image`, `video` or `audio` reference.",
+          attributes: [
+            { name: "image", kind: "reference", required: false, accepts: [artifactTypes.blob],
+              summary: "Selects the image Artifact whose subject the generated video carries." },
+            { name: "video", kind: "reference", required: false, accepts: [artifactTypes.blob],
+              summary: "Selects the video Artifact whose subject the generated video carries." },
+            { name: "audio", kind: "reference", required: false, accepts: [artifactTypes.blob],
+              summary: "Selects the audio Artifact the generated video carries." },
+          ] },
+      ],
+      ports: minimaxH3VideoPorts,
+      example: [
+        '<h3:ReferenceVideo id="montage" prompt={montagePrompt} duration="8" resolution="768P" aspect-ratio="9:16">',
+        "  <h3:Reference image={person.image}/>",
+        "  <h3:Reference video={gesture.video}/>",
+        "</h3:ReferenceVideo>",
+      ].join("\n"),
+      notes: [
+        minimaxH3DurationNote,
+        minimaxH3ResolutionNote,
+        "`Reference` carries exactly one of `image`, `video` or `audio`, and is empty.",
+        "The element requires at least one `Reference`, and accepts at most 9 image, 3 video and 3 audio references and 12 in total.",
+        "An audio `Reference` requires an image or video `Reference` beside it.",
+        "The element carries no text content.",
+      ],
+    }),
+  ] as const;
+
+export const minimaxH3Manifest = {
+  ...minimaxH3BaseDefinition.manifest,
+};
+export const minimaxH3Definition = {
+  ...minimaxH3BaseDefinition, manifest: minimaxH3Manifest,
+};