Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat: add author surfaces for generation models

kashorineb8fb8d6328a
diff --git a/packages/gemini-omni/README.md b/packages/gemini-omni/README.md
index 04d45589..eeaa85fa 100644
--- a/packages/gemini-omni/README.md
+++ b/packages/gemini-omni/README.md
@@ -1,13 +1,21 @@
# `@narratage/gemini-omni`
-Exact author/compute contract for Gemini Omni video generation.
+Exact author/compute contract and package-owned author Surface for Gemini Omni video generation.
It defines one `video` endpoint with duration, aspect ratio, resolution and bounded image, opaque
-audio, video-range and character references. It validates and seals requests, then emits the
-provider-neutral `GeneratedVideoSet` contract from `@narratage/generation`.
+audio, video-range and character references. It validates and seals requests, then projects the
+primary result to an ordinary video Artifact.
The package does not call an API. `@narratage/provider-kie` is one separately selected Runtime Endpoint
implementation; another Provider can implement the same exact capability without changing Core.
-The package is directly activatable and currently offers exact compute Fragments rather than a bundled
-high-level author Surface.
+```xml
+<omni:Video id="scene" prompt={prompt} duration="8" aspect-ratio="9:16" resolution="1080p" seed="42">
+ <omni:Image image={person.image}/>
+ <omni:Excerpt video={reference.video} start-sec="1.5" end-sec="4"/>
+ <omni:AudioId value="voice-id"/>
+ <omni:CharacterId value="character-id"/>
+</omni:Video>
+```
+
+Opaque service IDs are authored scalar request values; actual media stay explicit Artifact edges.
diff --git a/packages/gemini-omni/package.json b/packages/gemini-omni/package.json
index 0b07294a..2227ba65 100644
--- a/packages/gemini-omni/package.json
+++ b/packages/gemini-omni/package.json
@@ -10,8 +10,11 @@
"activation": "./src/activation.ts"
},
"dependencies": {
+ "@narratage/artifact": "workspace:*",
"@narratage/generation": "workspace:*",
+ "@narratage/markup": "workspace:*",
"@narratage/model-kit": "workspace:*",
- "@narratage/protocol": "workspace:*"
+ "@narratage/protocol": "workspace:*",
+ "@narratage/text": "workspace:*"
}
}
diff --git a/packages/gemini-omni/src/activation.ts b/packages/gemini-omni/src/activation.ts
index 145ddb71..601ed2e1 100644
--- a/packages/gemini-omni/src/activation.ts
+++ b/packages/gemini-omni/src/activation.ts
@@ -1,3 +1,23 @@
-import { geminiOmniComponent, geminiOmniManifest } from "./index.js";
-export const svmlPackage = { format: "svml.node-package@1" as const, name: "@narratage/gemini-omni", modules: [{ manifest: geminiOmniManifest, specifiers: ["@narratage/gemini-omni", "@narratage/gemini-omni@1"] }], components: [geminiOmniComponent] };
+import { createMarkupSurfaceHostFacet } from "@narratage/markup";
+import {
+ geminiOmniComponent,
+ geminiOmniManifest,
+ geminiOmniModuleRef,
+ geminiOmniSurfaceImplementationDigest,
+} from "./index.js";
+import { decodeGeminiOmniVideoSurface } from "./surface.js";
+
+export const svmlPackage = {
+ format: "svml.node-package@1" as const,
+ name: "@narratage/gemini-omni",
+ modules: [{ manifest: geminiOmniManifest, specifiers: ["@narratage/gemini-omni", "@narratage/gemini-omni@1"] }],
+ components: [geminiOmniComponent],
+ hostFacets: [createMarkupSurfaceHostFacet({
+ module: geminiOmniModuleRef,
+ surface: "video",
+ mode: "structured",
+ implementationDigest: geminiOmniSurfaceImplementationDigest,
+ handler: decodeGeminiOmniVideoSurface,
+ })],
+};
export default svmlPackage;
diff --git a/packages/gemini-omni/src/index.ts b/packages/gemini-omni/src/index.ts
index cd7d84a0..76ce075b 100644
--- a/packages/gemini-omni/src/index.ts
+++ b/packages/gemini-omni/src/index.ts
@@ -1,6 +1,7 @@
import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";
import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
+import { digestOf } from "@narratage/protocol";
export const geminiOmniModuleRef = { name: "@narratage/gemini-omni", version: "1" } as const;
@@ -51,7 +52,7 @@ export function sealGeminiOmniRequest(
return sealGenerationPortRequest(geminiOmniVideoPorts, ports);
}
-export const geminiOmniDefinition = defineExactModelModule({
+const geminiOmniBaseDefinition = defineExactModelModule({
module: geminiOmniModuleRef,
endpoints: [{
key: "video",
@@ -61,7 +62,31 @@ export const geminiOmniDefinition = defineExactModelModule({
}],
});
-export const geminiOmniManifest = geminiOmniDefinition.manifest;
-export const geminiOmniManifestDigest = geminiOmniDefinition.manifestDigest;
-export const geminiOmniEndpoints = geminiOmniDefinition.endpoints;
-export const geminiOmniComponent = geminiOmniDefinition.component;
+export const geminiOmniEndpoints = geminiOmniBaseDefinition.endpoints;
+export const geminiOmniComponent = geminiOmniBaseDefinition.component;
+export const geminiOmniSurfaceImplementationDigest = digestOf("@narratage/gemini-omni/video-surface@1");
+const geminiOmniEndpoint = geminiOmniEndpoints.video!;
+export const geminiOmniManifest = {
+ ...geminiOmniBaseDefinition.manifest,
+ surfaces: [{
+ name: "video",
+ tag: "Video",
+ mode: "structured" as const,
+ outputs: [
+ geminiOmniEndpoint.draftType,
+ geminiOmniEndpoint.mediaBindings.images!.type,
+ geminiOmniEndpoint.mediaBindings.excerpts!.type,
+ ],
+ implementation: {
+ kind: "trusted-frontend-surface" as const,
+ locator: "@narratage/gemini-omni/video-surface",
+ digest: geminiOmniSurfaceImplementationDigest,
+ },
+ }],
+};
+export const geminiOmniManifestDigest = digestOf(geminiOmniManifest);
+export const geminiOmniDefinition = {
+ ...geminiOmniBaseDefinition,
+ manifest: geminiOmniManifest,
+ manifestDigest: geminiOmniManifestDigest,
+};
diff --git a/packages/gemini-omni/src/surface.ts b/packages/gemini-omni/src/surface.ts
new file mode 100644
index 00000000..47a8a8f1
--- /dev/null
+++ b/packages/gemini-omni/src/surface.ts
@@ -0,0 +1,218 @@
+import { artifactTypes } from "@narratage/artifact";
+import { generationPort, sealGenerationMediaBinding, sealGenerationRequestDraft } from "@narratage/generation";
+import type { GenerationMediaPort, GenerationPortValue } from "@narratage/generation";
+import {
+ createExactModelPrimaryGenerationFragment,
+ exactModelMediaInputNames,
+ exactModelTextInputName,
+} from "@narratage/model-kit";
+import type { ExactModelMediaInput } from "@narratage/model-kit";
+import type {
+ MarkupAttributeValue,
+ StructuredElement,
+ StructuredSurfaceHandler,
+ SurfaceResolvedReference,
+} from "@narratage/markup";
+import type { CanonicalValue, TypeRef } from "@narratage/protocol";
+import { textTypes, verifyText } from "@narratage/text";
+
+import { geminiOmniEndpoints } from "./index.js";
+
+type Media = {
+ readonly port: "images" | "excerpts";
+ readonly role: "image" | "video";
+ readonly source: SurfaceResolvedReference;
+ readonly fields?: Readonly<Record<string, number>>;
+};
+
+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 = allowed): 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();
+}
+
+function integer(element: StructuredElement, name: string): number {
+ const value = Number(text(element, name));
+ assert(Number.isSafeInteger(value), `${element.name}.${name} must be an integer`);
+ return value;
+}
+
+function number(element: StructuredElement, name: string): number {
+ const value = Number(text(element, name));
+ assert(Number.isFinite(value), `${element.name}.${name} must be a number`);
+ return 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;
+}
+
+function mediaRef(
+ element: StructuredElement,
+ name: string,
+ role: "image" | "video",
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ const result = ref(element, name, artifactTypes.blob, resolve);
+ if (result.record !== undefined) {
+ assert(result.record.value.kind === "blob" && result.record.value.mediaType.startsWith(`${role}/`),
+ `${element.name}.${name} must be ${role} media`);
+ }
+ return result;
+}
+
+function empty(element: StructuredElement): void {
+ assert(!element.children.some((item) => item.kind === "element" || item.value.trim()), `${element.name} must be empty`);
+}
+
+export const decodeGeminiOmniVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ exact(element, ["id", "prompt", "duration", "aspect-ratio", "resolution", "seed"],
+ ["id", "prompt", "duration", "aspect-ratio", "resolution"]);
+ const id = text(element, "id");
+ const endpoint = geminiOmniEndpoints.video!;
+ 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 ports: Record<string, readonly GenerationPortValue[]> = {
+ duration: [integer(element, "duration")],
+ aspectRatio: [text(element, "aspect-ratio")],
+ resolution: [text(element, "resolution")],
+ };
+ if (element.attributes.seed !== undefined) ports.seed = [integer(element, "seed")];
+ const media: Media[] = [];
+ const audioIds: string[] = [];
+ const characterIds: string[] = [];
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ assert(child.value.trim().length === 0, `${element.name} accepts only Image, Excerpt, AudioId or CharacterId children`);
+ continue;
+ }
+ switch (localName(child.name)) {
+ case "Image":
+ exact(child, ["image"]);
+ empty(child);
+ media.push({ port: "images", role: "image", source: mediaRef(child, "image", "image", resolveReference) });
+ break;
+ case "Excerpt": {
+ exact(child, ["video", "start-sec", "end-sec"]);
+ empty(child);
+ const startSec = number(child, "start-sec");
+ const endSec = number(child, "end-sec");
+ assert(startSec < endSec, `${child.name}.start-sec must be before end-sec`);
+ media.push({
+ port: "excerpts",
+ role: "video",
+ source: mediaRef(child, "video", "video", resolveReference),
+ fields: { startSec, endSec },
+ });
+ break;
+ }
+ case "AudioId":
+ exact(child, ["value"]);
+ empty(child);
+ audioIds.push(text(child, "value"));
+ break;
+ case "CharacterId":
+ exact(child, ["value"]);
+ empty(child);
+ characterIds.push(text(child, "value"));
+ break;
+ default:
+ throw new Error(`${element.name} does not accept ${child.name}`);
+ }
+ }
+ if (audioIds.length > 0) ports.audioIds = audioIds;
+ if (characterIds.length > 0) ports.characterIds = characterIds;
+ const imageCount = media.filter((item) => item.port === "images").length;
+ const excerptCount = media.filter((item) => item.port === "excerpts").length;
+ assert(imageCount <= generationPort(endpoint.ports, "images").maxItems,
+ `${element.name} accepts at most 7 Image children`);
+ assert(excerptCount <= generationPort(endpoint.ports, "excerpts").maxItems,
+ `${element.name} accepts at most one Excerpt child`);
+ assert(imageCount + excerptCount * 2 + characterIds.length <= 7,
+ `${element.name} exceeds Gemini Omni's shared reference budget`);
+
+ const draft = sealGenerationRequestDraft(endpoint.ports, ports);
+ 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 mediaInputs = media.map((item, index): ExactModelMediaInput => {
+ const name = `media-${String(index + 1).padStart(4, "0")}`;
+ const bindingId = `${id}.${name}.binding`;
+ const port = generationPort(endpoint.ports, item.port);
+ assert(port.value.kind === "media", `${item.port} is not a media port`);
+ records.push({
+ id: bindingId,
+ type: endpoint.mediaBindings[item.port]!.type,
+ value: {
+ kind: "inline",
+ value: sealGenerationMediaBinding(port as GenerationMediaPort, {
+ role: item.role,
+ ...(item.fields === undefined ? {} : { fields: item.fields }),
+ }) as unknown as CanonicalValue,
+ },
+ range: element.range,
+ });
+ const names = exactModelMediaInputNames(name);
+ inputs[names.binding] = { kind: "record", id: bindingId };
+ inputs[names.artifact] = item.source.ref;
+ return { name, port: item.port };
+ });
+ const fragment = createExactModelPrimaryGenerationFragment(endpoint, mediaInputs, [{ name: "prompt", port: "prompt" }]);
+ return {
+ records,
+ fragments: [fragment],
+ components: [{
+ id,
+ fragment: fragment.id,
+ inputs,
+ outputs: { video: `${id}.video` },
+ range: element.range,
+ }],
+ };
+};
diff --git a/packages/gpt-image/README.md b/packages/gpt-image/README.md
index 9f9c1066..f2da66a9 100644
--- a/packages/gpt-image/README.md
+++ b/packages/gpt-image/README.md
@@ -14,6 +14,32 @@ The one physical package exposes two independently importable logical modules:
- `@narratage/gpt-image/clean@1`: generation followed by the existing explicit image-transform
Program, exporting one cleaned image while retaining both operations in the graph.
-It currently exposes low-level Draft/Fragment factories rather than a high-level Prompt Surface.
-Prompt authoring and assembly are intentionally deferred to the separate Prompt redesign; that work
-will not change the media edges, exact request or Provider contract described here.
+Both modules own an `Image` Markup Surface. They use the same author shape, so choosing the clean
+module changes the visible graph expansion rather than the document structure:
+
+```svml
+<import as="text" from="@narratage/text@1"/>
+<import as="gpt" from="@narratage/gpt-image/clean@1"/>
+
+<text:Value id="prompt">
+ A woman holding the product, editorial photography.
+</text:Value>
+
+<gpt:Image
+ id="holding"
+ prompt={prompt}
+ aspect-ratio="9:16"
+ resolution="2K"
+>
+ <gpt:Reference image={person}/>
+ <gpt:Reference image={product}/>
+</gpt:Image>
+```
+
+`prompt` is an ordinary `Text` graph edge. Every `Reference` is an ordinary image Artifact edge;
+the Surface does not copy runtime media into request metadata. The raw module expands to request
+assembly, generation and primary-image selection. The clean module then adds the official
+`gptImageDenoiseV1` Program and the shared image-transform Need as one further visible operation.
+
+The Surface implementation belongs to this package. `model-kit` remains responsible only for the
+exact request and Fragment shell; it owns no author-Surface registry or model syntax.
diff --git a/packages/gpt-image/package.json b/packages/gpt-image/package.json
index 1b78ec0a..b65bc720 100644
--- a/packages/gpt-image/package.json
+++ b/packages/gpt-image/package.json
@@ -14,6 +14,7 @@
"@narratage/elaborator": "workspace:*",
"@narratage/generation": "workspace:*",
"@narratage/image-transform": "workspace:*",
+ "@narratage/markup": "workspace:*",
"@narratage/model-kit": "workspace:*",
"@narratage/protocol": "workspace:*",
"@narratage/text": "workspace:*"
diff --git a/packages/gpt-image/src/activation.ts b/packages/gpt-image/src/activation.ts
index 4282d930..0dea6089 100644
--- a/packages/gpt-image/src/activation.ts
+++ b/packages/gpt-image/src/activation.ts
@@ -1,4 +1,17 @@
-import { gptImageCleanManifest, gptImageComponent, gptImageManifest } from "./index.js";
+import { createMarkupSurfaceHostFacet } from "@narratage/markup";
+
+import {
+ gptImageCleanManifest,
+ gptImageCleanModuleRef,
+ gptImageComponent,
+ gptImageManifest,
+ gptImageModuleRef,
+ gptImageSurfaceImplementationDigests,
+} from "./index.js";
+import {
+ decodeCleanGptImageSurface,
+ decodeGptImageSurface,
+} from "./surface.js";
export const svmlPackage = {
format: "svml.node-package@1" as const,
name: "@narratage/gpt-image",
@@ -10,5 +23,21 @@ export const svmlPackage = {
specifiers: ["@narratage/gpt-image/clean", "@narratage/gpt-image/clean@1"],
}],
components: [gptImageComponent],
+ hostFacets: [
+ createMarkupSurfaceHostFacet({
+ module: gptImageModuleRef,
+ surface: "image",
+ mode: "structured",
+ implementationDigest: gptImageSurfaceImplementationDigests.image,
+ handler: decodeGptImageSurface,
+ }),
+ createMarkupSurfaceHostFacet({
+ module: gptImageCleanModuleRef,
+ surface: "image",
+ mode: "structured",
+ implementationDigest: gptImageSurfaceImplementationDigests.cleanImage,
+ handler: decodeCleanGptImageSurface,
+ }),
+ ],
};
export default svmlPackage;
diff --git a/packages/gpt-image/src/index.ts b/packages/gpt-image/src/index.ts
index dc092335..d8d805dd 100644
--- a/packages/gpt-image/src/index.ts
+++ b/packages/gpt-image/src/index.ts
@@ -9,6 +9,7 @@ import { digestOf } from "@narratage/protocol";
import {
imageTransformManifestDigest,
imageTransformModuleRef,
+ imageTransformTypes,
} from "@narratage/image-transform";
export const gptImageModuleRef = { name: "@narratage/gpt-image", version: "1" } as const;
@@ -48,7 +49,7 @@ export function sealGptImage2Draft(
return sealGenerationRequestDraft(gptImage2Ports, ports);
}
-export const gptImageDefinition = defineExactModelModule({
+const gptImageBaseDefinition = defineExactModelModule({
module: gptImageModuleRef,
endpoints: [{
key: "image",
@@ -58,10 +59,33 @@ export const gptImageDefinition = defineExactModelModule({
}],
});
-export const gptImageManifest = gptImageDefinition.manifest;
-export const gptImageManifestDigest = gptImageDefinition.manifestDigest;
-export const gptImageEndpoints = gptImageDefinition.endpoints;
-export const gptImageComponent = gptImageDefinition.component;
+export const gptImageEndpoints = gptImageBaseDefinition.endpoints;
+export const gptImageComponent = gptImageBaseDefinition.component;
+export const gptImageSurfaceImplementationDigests = {
+ image: digestOf("@narratage/gpt-image/image-surface@1"),
+ cleanImage: digestOf("@narratage/gpt-image/clean/image-surface@1"),
+} as const;
+const gptImageSurfaceDeclaration = {
+ name: "image",
+ tag: "Image",
+ mode: "structured" as const,
+ outputs: [gptImageEndpoints.image!.draftType, gptImageEndpoints.image!.mediaBindings.images!.type],
+ implementation: {
+ kind: "trusted-frontend-surface" as const,
+ locator: "@narratage/gpt-image/image-surface",
+ digest: gptImageSurfaceImplementationDigests.image,
+ },
+};
+export const gptImageManifest = {
+ ...gptImageBaseDefinition.manifest,
+ surfaces: [gptImageSurfaceDeclaration],
+};
+export const gptImageManifestDigest = digestOf(gptImageManifest);
+export const gptImageDefinition = {
+ ...gptImageBaseDefinition,
+ manifest: gptImageManifest,
+ manifestDigest: gptImageManifestDigest,
+};
/** Optional authoring submodule; the exact GPT model remains independent of post-processing. */
export const gptImageCleanModuleRef = { name: "@narratage/gpt-image/clean", version: "1" } as const;
@@ -75,7 +99,21 @@ export const gptImageCleanManifest = {
],
types: [],
capabilities: [],
- surfaces: [],
+ surfaces: [{
+ name: "image",
+ tag: "Image",
+ mode: "structured" as const,
+ outputs: [
+ gptImageEndpoints.image!.draftType,
+ gptImageEndpoints.image!.mediaBindings.images!.type,
+ imageTransformTypes.program,
+ ],
+ implementation: {
+ kind: "trusted-frontend-surface" as const,
+ locator: "@narratage/gpt-image/clean/image-surface",
+ digest: gptImageSurfaceImplementationDigests.cleanImage,
+ },
+ }],
producers: [],
};
export const gptImageCleanManifestDigest = digestOf(gptImageCleanManifest);
diff --git a/packages/gpt-image/src/surface.ts b/packages/gpt-image/src/surface.ts
new file mode 100644
index 00000000..b50a5191
--- /dev/null
+++ b/packages/gpt-image/src/surface.ts
@@ -0,0 +1,190 @@
+import { artifactTypes } from "@narratage/artifact";
+import {
+ generationPort,
+ sealGenerationMediaBinding,
+} from "@narratage/generation";
+import type { GenerationMediaPort } from "@narratage/generation";
+import {
+ gptImageDenoiseV1,
+ imageTransformTypes,
+} from "@narratage/image-transform";
+import {
+ exactModelMediaInputNames,
+ exactModelTextInputName,
+ createExactModelPrimaryGenerationFragment,
+} from "@narratage/model-kit";
+import type {
+ MarkupAttributeValue,
+ StructuredElement,
+ StructuredSurfaceHandler,
+ SurfaceResolvedReference,
+} from "@narratage/markup";
+import type { CanonicalValue, TypeRef } from "@narratage/protocol";
+import { textTypes, verifyText } from "@narratage/text";
+
+import { createGptImageCleanFragment } from "./fragment.js";
+import {
+ gptImage2Ports,
+ gptImageEndpoints,
+ sealGptImage2Draft,
+} from "./index.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function localName(value: string): string {
+ return value.includes(":") ? value.slice(value.lastIndexOf(":") + 1) : value;
+}
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+ return left.module.name === right.module.name
+ && left.module.version === right.module.version
+ && left.name === right.name;
+}
+
+function exactAttributes(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 textAttribute(element: StructuredElement, name: string): string {
+ const value = element.attributes[name];
+ assert(typeof value === "string" && value.trim().length > 0,
+ `${element.name}.${name} must be a non-empty string`);
+ return value.trim();
+}
+
+function referencePath(value: MarkupAttributeValue | undefined, subject: string): string {
+ assert(typeof value === "object" && value.kind === "reference" && value.path.length > 0,
+ `${subject} must be a whole-value reference`);
+ return value.path;
+}
+
+function resolve(
+ element: StructuredElement,
+ attribute: string,
+ expected: TypeRef,
+ resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ const path = referencePath(element.attributes[attribute], `${element.name}.${attribute}`);
+ const result = resolveReference(path);
+ assert(result !== undefined, `${element.name}.${attribute} cannot resolve ${path}`);
+ assert(sameType(result.type, expected), `${element.name}.${attribute} has the wrong type`);
+ return result;
+}
+
+function prompt(
+ element: StructuredElement,
+ resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ const result = resolve(element, "prompt", textTypes.text, resolveReference);
+ if (result.record !== undefined) {
+ assert(result.record.value.kind === "inline", `${element.name}.prompt must reference Text`);
+ verifyText(result.record.value.value);
+ }
+ return result;
+}
+
+function references(
+ element: StructuredElement,
+ resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): readonly SurfaceResolvedReference[] {
+ const result: 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`);
+ exactAttributes(child, ["image"], ["image"]);
+ assert(!child.children.some((item) => item.kind === "element" || item.value.trim().length > 0),
+ `${child.name} must be empty`);
+ const image = resolve(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`);
+ }
+ result.push(image);
+ }
+ assert(result.length <= 16, `${element.name} accepts at most 16 Reference children`);
+ return result;
+}
+
+function decode(clean: boolean): StructuredSurfaceHandler {
+ return ({ element, resolveReference }) => {
+ exactAttributes(element, ["id", "prompt", "aspect-ratio", "resolution"],
+ ["id", "prompt", "aspect-ratio", "resolution"]);
+ const id = textAttribute(element, "id");
+ const promptSource = prompt(element, resolveReference);
+ const images = references(element, resolveReference);
+ const endpoint = gptImageEndpoints.image!;
+ const imagePort = generationPort(gptImage2Ports, "images");
+ assert(imagePort.value.kind === "media", "GPT Image images port is not media");
+ const draft = sealGptImage2Draft({
+ aspectRatio: [textAttribute(element, "aspect-ratio")],
+ resolution: [textAttribute(element, "resolution")],
+ });
+ const records: Array<{
+ readonly id: string;
+ readonly type: TypeRef;
+ readonly value: { readonly kind: "inline"; readonly value: CanonicalValue };
+ readonly 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"] | { readonly kind: "record"; readonly id: string }> = {
+ draft: { kind: "record", id: `${id}.draft` },
+ [exactModelTextInputName("prompt")]: promptSource.ref,
+ };
+ const mediaInputs = 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;
+ });
+ if (clean) {
+ records.push({
+ id: `${id}.cleanup`,
+ type: imageTransformTypes.program,
+ value: { kind: "inline", value: gptImageDenoiseV1 as unknown as CanonicalValue },
+ range: element.range,
+ });
+ inputs.cleanup = { kind: "record", id: `${id}.cleanup` };
+ }
+ const textInputs = [{ name: "prompt", port: "prompt" }] as const;
+ const fragment = clean
+ ? createGptImageCleanFragment(mediaInputs, textInputs)
+ : createExactModelPrimaryGenerationFragment(endpoint, mediaInputs, textInputs);
+ return {
+ records,
+ components: [{
+ id,
+ fragment: fragment.id,
+ inputs,
+ outputs: { image: `${id}.image` },
+ range: element.range,
+ }],
+ fragments: [fragment],
+ };
+ };
+}
+
+export const decodeGptImageSurface = decode(false);
+export const decodeCleanGptImageSurface = decode(true);
diff --git a/packages/gpt-image/test/surface.test.ts b/packages/gpt-image/test/surface.test.ts
new file mode 100644
index 00000000..fdc46c7b
--- /dev/null
+++ b/packages/gpt-image/test/surface.test.ts
@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { artifactTypes } from "@narratage/artifact";
+import { parseStructuredElement } from "@narratage/markup";
+import type { StructuredSurfaceHandler, SurfaceResolvedReference } from "@narratage/markup";
+import { textTypes } from "@narratage/text";
+
+import gptImageNodePackage from "../src/activation.js";
+import {
+ decodeCleanGptImageSurface,
+ decodeGptImageSurface,
+} from "../src/surface.js";
+
+const refs = new Map<string, SurfaceResolvedReference>([
+ ["prompt", {
+ path: "prompt",
+ ref: { kind: "component-output", component: "assembled-prompt", output: "text" },
+ type: textTypes.text,
+ }],
+ ...["person.image", "product.image"].map((path) => [path, {
+ path,
+ ref: { kind: "component-output" as const, component: path.split(".")[0]!, output: "image" },
+ type: artifactTypes.blob,
+ }] as const),
+]);
+
+async function decode(source: string, handler: StructuredSurfaceHandler) {
+ const element = parseStructuredElement({ name: "gpt-image.svml", text: source }, 0).element;
+ return await handler({
+ sourceName: "gpt-image.svml",
+ element,
+ resolveReference: (path) => refs.get(path),
+ resolveAsset: () => { throw new Error("no asset"); },
+ });
+}
+
+const authored = `<gpt:Image id="holding" prompt={prompt} aspect-ratio="9:16" resolution="2K">
+ <gpt:Reference image={person.image}/>
+ <gpt:Reference image={product.image}/>
+</gpt:Image>`;
+
+test("raw GPT Image Surface keeps Text and every reference image on explicit graph edges", async () => {
+ const result = await decode(authored, decodeGptImageSurface);
+ const component = result.components[0]!;
+ assert.deepEqual(component.inputs["prompt:text"], {
+ kind: "component-output", component: "assembled-prompt", output: "text",
+ });
+ assert.deepEqual(component.inputs["image-0001:artifact"], {
+ kind: "component-output", component: "person", output: "image",
+ });
+ assert.deepEqual(component.inputs["image-0002:artifact"], {
+ kind: "component-output", component: "product", output: "image",
+ });
+ assert.deepEqual(component.outputs, { image: "holding.image" });
+ assert.equal(result.records.filter((record) => record.id.endsWith(".binding")).length, 2);
+ assert.equal(result.records.some((record) => record.id.endsWith(".cleanup")), false);
+ assert.deepEqual(result.fragments[0]?.operations.map((operation) => operation.id), [
+ "bind-text:0001:prompt",
+ "bind:0001:images",
+ "bind:0002:images",
+ "finalize-request",
+ "generate",
+ "select-primary-image",
+ ]);
+});
+
+test("clean GPT Image Surface adds the official denoise as one visible downstream operation", async () => {
+ const result = await decode(authored, decodeCleanGptImageSurface);
+ const component = result.components[0]!;
+ assert.deepEqual(component.inputs.cleanup, { kind: "record", id: "holding.cleanup" });
+ assert.ok(result.records.some((record) => record.id === "holding.cleanup"));
+ assert.deepEqual(result.fragments[0]?.operations.map((operation) => operation.id).toSorted(), [
+ "bind-text:0001:prompt",
+ "bind:0001:images",
+ "bind:0002:images",
+ "clean-image",
+ "finalize-request",
+ "generate",
+ "select-primary-image",
+ ].toSorted());
+ const clean = result.fragments[0]?.operations.find((operation) => operation.id === "clean-image");
+ assert.deepEqual(clean?.inputs.source, { kind: "fragment-operation", operation: "select-primary-image" });
+ assert.deepEqual(clean?.inputs.program, { kind: "fragment-input", name: "cleanup" });
+});
+
+test("the physical package carries both independently importable Surface implementations", () => {
+ assert.deepEqual(gptImageNodePackage.modules.map((item) => ({
+ name: item.manifest.name,
+ surfaces: item.manifest.surfaces.map((surface) => surface.tag),
+ })), [
+ { name: "@narratage/gpt-image", surfaces: ["Image"] },
+ { name: "@narratage/gpt-image/clean", surfaces: ["Image"] },
+ ]);
+ assert.equal(gptImageNodePackage.hostFacets.length, 2);
+});
+
+test("GPT Image Surface rejects hidden inline prompts and undeclared child shapes", async () => {
+ await assert.rejects(
+ decode('<gpt:Image id="bad" prompt="inline" aspect-ratio="9:16" resolution="2K"/>', decodeGptImageSurface),
+ /whole-value reference/u,
+ );
+ await assert.rejects(
+ decode('<gpt:Image id="bad" prompt={prompt} aspect-ratio="9:16" resolution="2K"><gpt:Audio audio={person.image}/></gpt:Image>', decodeGptImageSurface),
+ /only Reference children/u,
+ );
+});
diff --git a/packages/grok-imagine/README.md b/packages/grok-imagine/README.md
index 09459041..8ecf316b 100644
--- a/packages/grok-imagine/README.md
+++ b/packages/grok-imagine/README.md
@@ -1,11 +1,19 @@
# `@narratage/grok-imagine`
-Exact author/compute contracts for Grok Imagine video generation.
+Exact author/compute contracts and package-owned author Surfaces for Grok Imagine video generation.
-It exposes distinct text, image and 1.5-preview endpoints. Each request is nominally typed and
-validated before yielding a provider-neutral `GeneratedVideoSet`. The package declares the model
+It exposes the standard and 1.5-preview models as distinct Surfaces. Each request is nominally typed and
+validated before yielding an ordinary video Artifact. The package declares the model
choice; it does not route to another model or access a Provider. `@narratage/provider-kie` is one
optional Runtime implementation.
-The package is directly activatable and currently offers exact compute Fragments; higher-level author
-syntax belongs in an independently installable kit.
+```xml
+<grok:Video id="clip" prompt={prompt} duration="6" aspect-ratio="9:16" resolution="720p">
+ <grok:Reference image={person.image}/>
+</grok:Video>
+
+<grok:PreviewVideo id="preview" prompt={previewPrompt} duration="6"
+ aspect-ratio="9:16" resolution="720p"/>
+```
+
+Continuation via `source-task-id` belongs only to `Video` and requires an explicit reference image.
diff --git a/packages/grok-imagine/package.json b/packages/grok-imagine/package.json
index 4c8d869a..7b033edf 100644
--- a/packages/grok-imagine/package.json
+++ b/packages/grok-imagine/package.json
@@ -10,8 +10,11 @@
"activation": "./src/activation.ts"
},
"dependencies": {
+ "@narratage/artifact": "workspace:*",
"@narratage/generation": "workspace:*",
+ "@narratage/markup": "workspace:*",
"@narratage/model-kit": "workspace:*",
- "@narratage/protocol": "workspace:*"
+ "@narratage/protocol": "workspace:*",
+ "@narratage/text": "workspace:*"
}
}
diff --git a/packages/grok-imagine/src/activation.ts b/packages/grok-imagine/src/activation.ts
index df24fe04..3f7ddf1e 100644
--- a/packages/grok-imagine/src/activation.ts
+++ b/packages/grok-imagine/src/activation.ts
@@ -1,3 +1,32 @@
-import { grokImagineComponent, grokImagineManifest } from "./index.js";
-export const svmlPackage = { format: "svml.node-package@1" as const, name: "@narratage/grok-imagine", modules: [{ manifest: grokImagineManifest, specifiers: ["@narratage/grok-imagine", "@narratage/grok-imagine@1"] }], components: [grokImagineComponent] };
+import { createMarkupSurfaceHostFacet } from "@narratage/markup";
+import {
+ grokImagineComponent,
+ grokImagineManifest,
+ grokImagineModuleRef,
+ grokImagineSurfaceImplementationDigests,
+} from "./index.js";
+import { decodeGrokImaginePreviewVideoSurface, decodeGrokImagineVideoSurface } from "./surface.js";
+
+export const svmlPackage = {
+ format: "svml.node-package@1" as const,
+ name: "@narratage/grok-imagine",
+ modules: [{ manifest: grokImagineManifest, specifiers: ["@narratage/grok-imagine", "@narratage/grok-imagine@1"] }],
+ components: [grokImagineComponent],
+ hostFacets: [
+ createMarkupSurfaceHostFacet({
+ module: grokImagineModuleRef,
+ surface: "video",
+ mode: "structured",
+ implementationDigest: grokImagineSurfaceImplementationDigests.video,
+ handler: decodeGrokImagineVideoSurface,
+ }),
+ createMarkupSurfaceHostFacet({
+ module: grokImagineModuleRef,
+ surface: "preview-video",
+ mode: "structured",
+ implementationDigest: grokImagineSurfaceImplementationDigests.previewVideo,
+ handler: decodeGrokImaginePreviewVideoSurface,
+ }),
+ ],
+};
export default svmlPackage;
diff --git a/packages/grok-imagine/src/index.ts b/packages/grok-imagine/src/index.ts
index 215d01e3..6eed5257 100644
--- a/packages/grok-imagine/src/index.ts
+++ b/packages/grok-imagine/src/index.ts
@@ -1,6 +1,7 @@
import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";
import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
+import { digestOf } from "@narratage/protocol";
export const grokImagineModuleRef = { name: "@narratage/grok-imagine", version: "1" } as const;
export const grokImagineModels = ["grok-imagine-video", "grok-imagine-video-1.5-preview"] as const;
@@ -58,7 +59,7 @@ export function sealGrokImagineRequest(
return sealGenerationPortRequest(grokImaginePorts[model], ports);
}
-export const grokImagineDefinition = defineExactModelModule({
+const grokImagineBaseDefinition = defineExactModelModule({
module: grokImagineModuleRef,
endpoints: [
{
@@ -76,7 +77,38 @@ export const grokImagineDefinition = defineExactModelModule({
],
});
-export const grokImagineManifest = grokImagineDefinition.manifest;
-export const grokImagineManifestDigest = grokImagineDefinition.manifestDigest;
-export const grokImagineEndpoints = grokImagineDefinition.endpoints;
-export const grokImagineComponent = grokImagineDefinition.component;
+export const grokImagineEndpoints = grokImagineBaseDefinition.endpoints;
+export const grokImagineComponent = grokImagineBaseDefinition.component;
+export const grokImagineSurfaceImplementationDigests = {
+ video: digestOf("@narratage/grok-imagine/video-surface@1"),
+ previewVideo: digestOf("@narratage/grok-imagine/preview-video-surface@1"),
+} as const;
+const surface = (
+ name: "video" | "preview-video",
+ tag: "Video" | "PreviewVideo",
+ endpoint: NonNullable<(typeof grokImagineEndpoints)["video" | "preview-1.5"]>,
+ digest: (typeof grokImagineSurfaceImplementationDigests)["video" | "previewVideo"],
+) => ({
+ name,
+ tag,
+ mode: "structured" as const,
+ outputs: [endpoint.draftType, endpoint.mediaBindings.images!.type],
+ implementation: {
+ kind: "trusted-frontend-surface" as const,
+ locator: `@narratage/grok-imagine/${name}-surface`,
+ digest,
+ },
+});
+export const grokImagineManifest = {
+ ...grokImagineBaseDefinition.manifest,
+ surfaces: [
+ surface("video", "Video", grokImagineEndpoints.video!, grokImagineSurfaceImplementationDigests.video),
+ surface("preview-video", "PreviewVideo", grokImagineEndpoints["preview-1.5"]!, grokImagineSurfaceImplementationDigests.previewVideo),
+ ],
+};
+export const grokImagineManifestDigest = digestOf(grokImagineManifest);
+export const grokImagineDefinition = {
+ ...grokImagineBaseDefinition,
+ manifest: grokImagineManifest,
+ manifestDigest: grokImagineManifestDigest,
+};
diff --git a/packages/grok-imagine/src/surface.ts b/packages/grok-imagine/src/surface.ts
new file mode 100644
index 00000000..d9eff8cd
--- /dev/null
+++ b/packages/grok-imagine/src/surface.ts
@@ -0,0 +1,158 @@
+import { artifactTypes } from "@narratage/artifact";
+import { generationPort, sealGenerationMediaBinding, sealGenerationRequestDraft } from "@narratage/generation";
+import type { GenerationMediaPort, GenerationPortValue } from "@narratage/generation";
+import {
+ createExactModelPrimaryGenerationFragment,
+ exactModelMediaInputNames,
+ exactModelTextInputName,
+} from "@narratage/model-kit";
+import type { ExactModelEndpoint } from "@narratage/model-kit";
+import type {
+ MarkupAttributeValue,
+ StructuredElement,
+ StructuredSurfaceHandler,
+ SurfaceResolvedReference,
+} from "@narratage/markup";
+import type { CanonicalValue, TypeRef } from "@narratage/protocol";
+import { textTypes, verifyText } from "@narratage/text";
+
+import { grokImagineEndpoints } 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 = allowed): 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();
+}
+
+function integer(element: StructuredElement, name: string): number {
+ const value = Number(text(element, name));
+ assert(Number.isSafeInteger(value), `${element.name}.${name} must be an integer`);
+ return 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;
+}
+
+function decoder(endpoint: ExactModelEndpoint, continuation: boolean): StructuredSurfaceHandler {
+ return ({ element, resolveReference }) => {
+ exact(element,
+ continuation
+ ? ["id", "prompt", "duration", "aspect-ratio", "resolution", "source-task-id"]
+ : ["id", "prompt", "duration", "aspect-ratio", "resolution"],
+ ["id", "prompt", "duration", "aspect-ratio", "resolution"]);
+ 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", "Grok 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"]);
+ 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 be image media`);
+ }
+ images.push(image);
+ }
+ assert(images.length <= imagePort.maxItems, `${element.name} accepts at most ${imagePort.maxItems} references`);
+ const ports: Record<string, readonly GenerationPortValue[]> = {
+ duration: [integer(element, "duration")],
+ aspectRatio: [text(element, "aspect-ratio")],
+ resolution: [text(element, "resolution")],
+ };
+ if (element.attributes["source-task-id"] !== undefined) {
+ assert(continuation, `${element.name} does not support source-task-id`);
+ ports.sourceTaskId = [text(element, "source-task-id")];
+ assert(images.length > 0, `${element.name}.source-task-id requires at least one Reference`);
+ }
+ const draft = sealGenerationRequestDraft(endpoint.ports, ports);
+ 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: { video: `${id}.video` },
+ range: element.range,
+ }],
+ };
+ };
+}
+
+export const decodeGrokImagineVideoSurface = decoder(grokImagineEndpoints.video!, true);
+export const decodeGrokImaginePreviewVideoSurface = decoder(grokImagineEndpoints["preview-1.5"]!, false);
diff --git a/packages/minimax-h3/README.md b/packages/minimax-h3/README.md
index 5db8233e..49be1676 100644
--- a/packages/minimax-h3/README.md
+++ b/packages/minimax-h3/README.md
@@ -1,11 +1,20 @@
# `@narratage/minimax-h3`
-Exact author/compute contracts for MiniMax H3 video generation.
+Exact author/compute contracts and package-owned author Surfaces for MiniMax H3 video generation.
-Text, first/last-frame and subject-reference modes are separate endpoints rather than one dynamic
-port mode. Each returns a provider-neutral `GeneratedVideoSet`. This package owns request semantics
+Text, first/last-frame 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 `@narratage/provider-kie`.
-The package is directly activatable and intentionally exposes exact compute Fragments. A separate author
-kit may provide prettier domain syntax without moving model semantics into a Provider.
+```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.
diff --git a/packages/minimax-h3/package.json b/packages/minimax-h3/package.json
index fa832db0..12d35020 100644
--- a/packages/minimax-h3/package.json
+++ b/packages/minimax-h3/package.json
@@ -10,8 +10,11 @@
"activation": "./src/activation.ts"
},
"dependencies": {
+ "@narratage/artifact": "workspace:*",
"@narratage/generation": "workspace:*",
+ "@narratage/markup": "workspace:*",
"@narratage/model-kit": "workspace:*",
- "@narratage/protocol": "workspace:*"
+ "@narratage/protocol": "workspace:*",
+ "@narratage/text": "workspace:*"
}
}
diff --git a/packages/minimax-h3/src/activation.ts b/packages/minimax-h3/src/activation.ts
index bca80a31..cf0fa077 100644
--- a/packages/minimax-h3/src/activation.ts
+++ b/packages/minimax-h3/src/activation.ts
@@ -1,3 +1,9 @@
-import { minimaxH3Component, minimaxH3Manifest } from "./index.js";
-export const svmlPackage = { format: "svml.node-package@1" as const, name: "@narratage/minimax-h3", modules: [{ manifest: minimaxH3Manifest, specifiers: ["@narratage/minimax-h3", "@narratage/minimax-h3@1"] }], components: [minimaxH3Component] };
+import { createMarkupSurfaceHostFacet } from "@narratage/markup";
+import { minimaxH3Component, minimaxH3Manifest, minimaxH3ModuleRef, minimaxH3SurfaceImplementationDigests } from "./index.js";
+import { decodeMinimaxFrameVideoSurface, decodeMinimaxReferenceVideoSurface, decodeMinimaxTextVideoSurface } from "./surface.js";
+export const svmlPackage = { format: "svml.node-package@1" as const, name: "@narratage/minimax-h3", modules: [{ manifest: minimaxH3Manifest, specifiers: ["@narratage/minimax-h3", "@narratage/minimax-h3@1"] }], components: [minimaxH3Component], hostFacets: [
+ createMarkupSurfaceHostFacet({ module: minimaxH3ModuleRef, surface: "text-video", mode: "structured", implementationDigest: minimaxH3SurfaceImplementationDigests.textVideo, handler: decodeMinimaxTextVideoSurface }),
+ createMarkupSurfaceHostFacet({ module: minimaxH3ModuleRef, surface: "frame-video", mode: "structured", implementationDigest: minimaxH3SurfaceImplementationDigests.frameVideo, handler: decodeMinimaxFrameVideoSurface }),
+ createMarkupSurfaceHostFacet({ module: minimaxH3ModuleRef, surface: "reference-video", mode: "structured", implementationDigest: minimaxH3SurfaceImplementationDigests.referenceVideo, handler: decodeMinimaxReferenceVideoSurface }),
+] };
export default svmlPackage;
diff --git a/packages/minimax-h3/src/index.ts b/packages/minimax-h3/src/index.ts
index abe70580..e12b7bee 100644
--- a/packages/minimax-h3/src/index.ts
+++ b/packages/minimax-h3/src/index.ts
@@ -1,6 +1,7 @@
import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";
import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
+import { digestOf } from "@narratage/protocol";
export const minimaxH3ModuleRef = { name: "@narratage/minimax-h3", version: "1" } as const;
@@ -56,7 +57,7 @@ export function sealMinimaxH3Request(
return sealGenerationPortRequest(minimaxH3Ports, ports);
}
-export const minimaxH3Definition = defineExactModelModule({
+const minimaxH3BaseDefinition = defineExactModelModule({
module: minimaxH3ModuleRef,
endpoints: [{
key: "video",
@@ -66,7 +67,31 @@ export const minimaxH3Definition = defineExactModelModule({
}],
});
-export const minimaxH3Manifest = minimaxH3Definition.manifest;
-export const minimaxH3ManifestDigest = minimaxH3Definition.manifestDigest;
-export const minimaxH3Endpoints = minimaxH3Definition.endpoints;
-export const minimaxH3Component = minimaxH3Definition.component;
+export const minimaxH3Endpoints = minimaxH3BaseDefinition.endpoints;
+export const minimaxH3Component = minimaxH3BaseDefinition.component;
+export const minimaxH3SurfaceImplementationDigests = {
+ textVideo: digestOf("@narratage/minimax-h3/text-video-surface@1"),
+ frameVideo: digestOf("@narratage/minimax-h3/frame-video-surface@1"),
+ referenceVideo: digestOf("@narratage/minimax-h3/reference-video-surface@1"),
+} as const;
+const endpoint = minimaxH3Endpoints.video!;
+const declaration = (
+ name: string, tag: string, digest: (typeof minimaxH3SurfaceImplementationDigests)[keyof typeof minimaxH3SurfaceImplementationDigests],
+ bindings: readonly (keyof typeof endpoint.mediaBindings)[] = [],
+) => ({
+ name, tag, mode: "structured" as const,
+ outputs: [endpoint.draftType, ...bindings.map((port) => endpoint.mediaBindings[port]!.type)],
+ implementation: { kind: "trusted-frontend-surface" as const, locator: `@narratage/minimax-h3/${name}-surface`, digest },
+});
+export const minimaxH3Manifest = {
+ ...minimaxH3BaseDefinition.manifest,
+ surfaces: [
+ declaration("text-video", "TextVideo", minimaxH3SurfaceImplementationDigests.textVideo),
+ declaration("frame-video", "FrameVideo", minimaxH3SurfaceImplementationDigests.frameVideo, ["firstFrame", "lastFrame"]),
+ declaration("reference-video", "ReferenceVideo", minimaxH3SurfaceImplementationDigests.referenceVideo, ["referenceImage", "referenceVideo", "referenceAudio"]),
+ ],
+};
+export const minimaxH3ManifestDigest = digestOf(minimaxH3Manifest);
+export const minimaxH3Definition = {
+ ...minimaxH3BaseDefinition, manifest: minimaxH3Manifest, manifestDigest: minimaxH3ManifestDigest,
+};
diff --git a/packages/minimax-h3/src/surface.ts b/packages/minimax-h3/src/surface.ts
new file mode 100644
index 00000000..3de1adbd
--- /dev/null
+++ b/packages/minimax-h3/src/surface.ts
@@ -0,0 +1,84 @@
+import { artifactTypes } from "@narratage/artifact";
+import { generationPort, sealGenerationMediaBinding, sealGenerationRequestDraft } from "@narratage/generation";
+import type { GenerationMediaPort, GenerationMediaRole, GenerationPortValue } from "@narratage/generation";
+import { createExactModelPrimaryGenerationFragment, exactModelMediaInputNames, exactModelTextInputName } from "@narratage/model-kit";
+import type { ExactModelMediaInput } from "@narratage/model-kit";
+import type { MarkupAttributeValue, StructuredElement, StructuredSurfaceHandler, SurfaceResolvedReference } from "@narratage/markup";
+import type { CanonicalValue, TypeRef } from "@narratage/protocol";
+import { textTypes, verifyText } from "@narratage/text";
+import { minimaxH3Endpoints } from "./index.js";
+
+type Media = { readonly port: "referenceImage" | "referenceVideo" | "referenceAudio" | "firstFrame" | "lastFrame"; readonly role: GenerationMediaRole; readonly source: SurfaceResolvedReference };
+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(a: TypeRef, b: TypeRef): boolean { return a.name === b.name && a.module.name === b.module.name && a.module.version === b.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();
+}
+function optionalText(element: StructuredElement, name: string): string | undefined { return element.attributes[name] === undefined ? undefined : text(element, name); }
+function integer(element: StructuredElement, name: string): number { const value = Number(text(element, name)); assert(Number.isSafeInteger(value), `${element.name}.${name} must be an integer`); return 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;
+}
+function mediaRef(element: StructuredElement, name: string, role: GenerationMediaRole, resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
+ const result = ref(element, name, artifactTypes.blob, resolve);
+ if (result.record !== undefined) assert(result.record.value.kind === "blob" && result.record.value.mediaType.startsWith(`${role}/`), `${element.name}.${name} must be ${role} media`);
+ return result;
+}
+function empty(element: StructuredElement): void { assert(!element.children.some((item) => item.kind === "element" || item.value.trim()), `${element.name} must be empty`); }
+
+function output(element: StructuredElement, prompt: SurfaceResolvedReference, ports: Readonly<Record<string, readonly GenerationPortValue[]>>, media: readonly Media[]) {
+ const id = text(element, "id"); const endpoint = minimaxH3Endpoints.video!;
+ const draft = sealGenerationRequestDraft(endpoint.ports, ports);
+ 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 mediaInputs = media.map((item, index): ExactModelMediaInput => {
+ const name = `media-${String(index + 1).padStart(4, "0")}`; const binding = endpoint.mediaBindings[item.port]!; const port = generationPort(endpoint.ports, item.port);
+ assert(port.value.kind === "media", `${item.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: item.role }) as unknown as CanonicalValue }, range: element.range });
+ const names = exactModelMediaInputNames(name); inputs[names.binding] = { kind: "record", id: bindingId }; inputs[names.artifact] = item.source.ref;
+ return { name, port: item.port };
+ });
+ const fragment = createExactModelPrimaryGenerationFragment(endpoint, mediaInputs, [{ name: "prompt", port: "prompt" }]);
+ return { records, fragments: [fragment], components: [{ id, fragment: fragment.id, inputs, outputs: { video: `${id}.video` }, range: element.range }] };
+}
+function common(element: StructuredElement, resolveReference: (path: string) => SurfaceResolvedReference | undefined) {
+ 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 ports: Record<string, readonly GenerationPortValue[]> = { duration: [integer(element, "duration")] };
+ const resolution = optionalText(element, "resolution"); if (resolution !== undefined) ports.resolution = [resolution];
+ const aspect = optionalText(element, "aspect-ratio"); if (aspect !== undefined) ports.aspectRatio = [aspect];
+ return { prompt, ports };
+}
+
+export const decodeMinimaxTextVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ exact(element, ["id", "prompt", "duration", "resolution", "aspect-ratio"], ["id", "prompt", "duration"]); empty(element);
+ const { prompt, ports } = common(element, resolveReference); return output(element, prompt, ports, []);
+};
+export const decodeMinimaxFrameVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ exact(element, ["id", "prompt", "duration", "resolution", "first-frame", "last-frame"], ["id", "prompt", "duration", "first-frame"]); empty(element);
+ const { prompt, ports } = common(element, resolveReference); const media: Media[] = [{ port: "firstFrame", role: "image", source: mediaRef(element, "first-frame", "image", resolveReference) }];
+ if (element.attributes["last-frame"] !== undefined) media.push({ port: "lastFrame", role: "image", source: mediaRef(element, "last-frame", "image", resolveReference) });
+ return output(element, prompt, ports, media);
+};
+export const decodeMinimaxReferenceVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ exact(element, ["id", "prompt", "duration", "resolution", "aspect-ratio"], ["id", "prompt", "duration"]);
+ const { prompt, ports } = common(element, resolveReference); const media: Media[] = [];
+ const mapping = { image: ["referenceImage", "image"], video: ["referenceVideo", "video"], audio: ["referenceAudio", "audio"] } as const;
+ 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`); const used = Object.keys(mapping).filter((name) => child.attributes[name] !== undefined) as (keyof typeof mapping)[];
+ assert(used.length === 1, `${child.name} requires exactly one of image, video or audio`); exact(child, [used[0]!], [used[0]!]); empty(child);
+ const role = used[0]!; const [port] = mapping[role]; media.push({ port, role, source: mediaRef(child, role, role, resolveReference) });
+ }
+ assert(media.length > 0, `${element.name} requires at least one Reference`);
+ assert(!media.some((item) => item.role === "audio") || media.some((item) => item.role === "image" || item.role === "video"), `${element.name} reference audio requires an image or video companion`);
+ for (const port of ["referenceImage", "referenceVideo", "referenceAudio"] as const) assert(media.filter((item) => item.port === port).length <= generationPort(minimaxH3Endpoints.video!.ports, port).maxItems, `${element.name} has too many ${port} references`);
+ assert(media.length <= 12, `${element.name} accepts at most 12 total references`);
+ return output(element, prompt, ports, media);
+};
diff --git a/packages/nano-banana/README.md b/packages/nano-banana/README.md
index 15debc27..2a2c5f36 100644
--- a/packages/nano-banana/README.md
+++ b/packages/nano-banana/README.md
@@ -1,10 +1,19 @@
# `@narratage/nano-banana`
-Exact author/compute contracts for Nano Banana 2 and Nano Banana Pro image generation.
+Exact author/compute contracts and package-owned author Surfaces for Nano Banana 2 and Nano Banana Pro.
-The model variants are separate endpoints with exact request validation and a common
-provider-neutral `GeneratedImageSet` result. The package contains no Provider selection, API key or
-network execution. `@narratage/provider-kie` is one optional Runtime implementation.
+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; `@narratage/provider-kie` is one optional Runtime implementation.
-The package is directly activatable and currently offers exact compute Fragments rather than choosing one
-official authoring style.
+Import the model variant you mean and connect prompt and references as ordinary graph edges:
+
+```xml
+<nano:Image id="draft" prompt={prompt} aspect-ratio="9:16" resolution="2K" output-format="png">
+ <nano:Reference image={person.image}/>
+</nano:Image>
+
+<nano:ProImage id="final" prompt={finalPrompt} aspect-ratio="9:16" resolution="4K" output-format="png"/>
+```
+
+The Surface only lowers this syntax into the package's exact model request. It does not select a Provider.
diff --git a/packages/nano-banana/package.json b/packages/nano-banana/package.json
index 6a6d56f5..79b187e0 100644
--- a/packages/nano-banana/package.json
+++ b/packages/nano-banana/package.json
@@ -10,8 +10,11 @@
"activation": "./src/activation.ts"
},
"dependencies": {
+ "@narratage/artifact": "workspace:*",
"@narratage/generation": "workspace:*",
+ "@narratage/markup": "workspace:*",
"@narratage/model-kit": "workspace:*",
- "@narratage/protocol": "workspace:*"
+ "@narratage/protocol": "workspace:*",
+ "@narratage/text": "workspace:*"
}
}
diff --git a/packages/nano-banana/src/activation.ts b/packages/nano-banana/src/activation.ts
index f249314d..c4834f19 100644
--- a/packages/nano-banana/src/activation.ts
+++ b/packages/nano-banana/src/activation.ts
@@ -1,3 +1,10 @@
-import { nanoBananaComponent, nanoBananaManifest } from "./index.js";
-export const svmlPackage = { format: "svml.node-package@1" as const, name: "@narratage/nano-banana", modules: [{ manifest: nanoBananaManifest, specifiers: ["@narratage/nano-banana", "@narratage/nano-banana@1"] }], components: [nanoBananaComponent] };
+import { createMarkupSurfaceHostFacet } from "@narratage/markup";
+import {
+ nanoBananaComponent, nanoBananaManifest, nanoBananaModuleRef, nanoBananaSurfaceImplementationDigests,
+} from "./index.js";
+import { decodeNanoBananaImageSurface, decodeNanoBananaProImageSurface } from "./surface.js";
+export const svmlPackage = { format: "svml.node-package@1" as const, name: "@narratage/nano-banana", modules: [{ manifest: nanoBananaManifest, specifiers: ["@narratage/nano-banana", "@narratage/nano-banana@1"] }], components: [nanoBananaComponent], hostFacets: [
+ createMarkupSurfaceHostFacet({ module: nanoBananaModuleRef, surface: "image", mode: "structured", implementationDigest: nanoBananaSurfaceImplementationDigests.image, handler: decodeNanoBananaImageSurface }),
+ createMarkupSurfaceHostFacet({ module: nanoBananaModuleRef, surface: "pro-image", mode: "structured", implementationDigest: nanoBananaSurfaceImplementationDigests.proImage, handler: decodeNanoBananaProImageSurface }),
+] };
export default svmlPackage;
diff --git a/packages/nano-banana/src/index.ts b/packages/nano-banana/src/index.ts
index 1bf33ed9..ac73af38 100644
--- a/packages/nano-banana/src/index.ts
+++ b/packages/nano-banana/src/index.ts
@@ -1,6 +1,7 @@
import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";
import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
+import { digestOf } from "@narratage/protocol";
export const nanoBananaModuleRef = { name: "@narratage/nano-banana", version: "1" } as const;
export const nanoBananaModels = ["nano-banana-2", "nano-banana-pro"] as const;
@@ -43,7 +44,7 @@ export function sealNanoBananaRequest(
return sealGenerationPortRequest(nanoBananaPorts[model], ports);
}
-export const nanoBananaDefinition = defineExactModelModule({
+const nanoBananaBaseDefinition = defineExactModelModule({
module: nanoBananaModuleRef,
endpoints: nanoBananaModels.map((model) => ({
key: model === "nano-banana-2" ? "v2" : "pro",
@@ -53,7 +54,38 @@ export const nanoBananaDefinition = defineExactModelModule({
})),
});
-export const nanoBananaManifest = nanoBananaDefinition.manifest;
-export const nanoBananaManifestDigest = nanoBananaDefinition.manifestDigest;
-export const nanoBananaEndpoints = nanoBananaDefinition.endpoints;
-export const nanoBananaComponent = nanoBananaDefinition.component;
+export const nanoBananaEndpoints = nanoBananaBaseDefinition.endpoints;
+export const nanoBananaComponent = nanoBananaBaseDefinition.component;
+export const nanoBananaSurfaceImplementationDigests = {
+ image: digestOf("@narratage/nano-banana/image-surface@1"),
+ proImage: digestOf("@narratage/nano-banana/pro-image-surface@1"),
+} as const;
+const surface = (
+ name: "image" | "pro-image",
+ tag: "Image" | "ProImage",
+ endpoint: (typeof nanoBananaEndpoints)["v2" | "pro"],
+ digest: (typeof nanoBananaSurfaceImplementationDigests)["image" | "proImage"],
+) => ({
+ name,
+ tag,
+ mode: "structured" as const,
+ outputs: [endpoint!.draftType, endpoint!.mediaBindings.images!.type],
+ implementation: {
+ kind: "trusted-frontend-surface" as const,
+ locator: `@narratage/nano-banana/${name}-surface`,
+ digest,
+ },
+});
+export const nanoBananaManifest = {
+ ...nanoBananaBaseDefinition.manifest,
+ surfaces: [
+ surface("image", "Image", nanoBananaEndpoints.v2!, nanoBananaSurfaceImplementationDigests.image),
+ surface("pro-image", "ProImage", nanoBananaEndpoints.pro!, nanoBananaSurfaceImplementationDigests.proImage),
+ ],
+};
+export const nanoBananaManifestDigest = digestOf(nanoBananaManifest);
+export const nanoBananaDefinition = {
+ ...nanoBananaBaseDefinition,
+ manifest: nanoBananaManifest,
+ manifestDigest: nanoBananaManifestDigest,
+};
diff --git a/packages/nano-banana/src/surface.ts b/packages/nano-banana/src/surface.ts
new file mode 100644
index 00000000..2c2407db
--- /dev/null
+++ b/packages/nano-banana/src/surface.ts
@@ -0,0 +1,120 @@
+import { artifactTypes } from "@narratage/artifact";
+import { generationPort, sealGenerationMediaBinding, sealGenerationRequestDraft } from "@narratage/generation";
+import type { GenerationMediaPort } from "@narratage/generation";
+import {
+ createExactModelPrimaryGenerationFragment,
+ exactModelMediaInputNames,
+ exactModelTextInputName,
+} from "@narratage/model-kit";
+import type { ExactModelEndpoint } from "@narratage/model-kit";
+import type {
+ MarkupAttributeValue,
+ StructuredElement,
+ StructuredSurfaceHandler,
+ SurfaceResolvedReference,
+} from "@narratage/markup";
+import type { CanonicalValue, TypeRef } from "@narratage/protocol";
+import { textTypes, verifyText } from "@narratage/text";
+
+import { nanoBananaEndpoints } 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 = allowed): 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();
+}
+
+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;
+}
+
+function decoder(endpoint: ExactModelEndpoint): StructuredSurfaceHandler {
+ return ({ element, resolveReference }) => {
+ exact(element, ["id", "prompt", "aspect-ratio", "resolution", "output-format"]);
+ 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", "Nano Banana 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"]);
+ 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 draft = sealGenerationRequestDraft(endpoint.ports, {
+ aspectRatio: [text(element, "aspect-ratio")],
+ resolution: [text(element, "resolution")],
+ outputFormat: [text(element, "output-format")],
+ });
+ 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 decodeNanoBananaImageSurface = decoder(nanoBananaEndpoints.v2!);
+export const decodeNanoBananaProImageSurface = decoder(nanoBananaEndpoints.pro!);
diff --git a/packages/seedream/README.md b/packages/seedream/README.md
index bf910f1c..049c2862 100644
--- a/packages/seedream/README.md
+++ b/packages/seedream/README.md
@@ -1,10 +1,21 @@
# `@narratage/seedream`
-Exact author/compute contracts for Seedream 5 Lite text-to-image and image-to-image generation.
+Exact author/compute contracts and package-owned author Surfaces for Seedream image generation.
-The two modes are separate endpoints and return the provider-neutral `GeneratedImageSet` contract.
+The two modes are separate Surfaces and project the primary result to an ordinary image Artifact.
This package defines what the author requested, not where it runs: API translation, credentials,
retry and queue behavior belong to a selected Runtime Endpoint such as `@narratage/provider-kie`.
-The installed package is directly activatable and currently exposes exact compute Fragments. Domain kits
-may wrap them with author-facing syntax without changing this contract.
+The modes stay explicit in the source:
+
+```xml
+<seedream:TextImage id="scene" prompt={prompt} aspect-ratio="9:16"
+ quality="high" output-format="png" nsfw-check="true"/>
+
+<seedream:ReferenceImage id="variation" prompt={variationPrompt} aspect-ratio="9:16"
+ quality="high" output-format="png" nsfw-check="true">
+ <seedream:Reference image={scene.image}/>
+</seedream:ReferenceImage>
+```
+
+Prompt and every reference remain explicit graph inputs; the Runtime chooses no model on the author's behalf.
diff --git a/packages/seedream/package.json b/packages/seedream/package.json
index 53fb5f6a..9347d753 100644
--- a/packages/seedream/package.json
+++ b/packages/seedream/package.json
@@ -10,8 +10,11 @@
"activation": "./src/activation.ts"
},
"dependencies": {
+ "@narratage/artifact": "workspace:*",
"@narratage/generation": "workspace:*",
+ "@narratage/markup": "workspace:*",
"@narratage/model-kit": "workspace:*",
- "@narratage/protocol": "workspace:*"
+ "@narratage/protocol": "workspace:*",
+ "@narratage/text": "workspace:*"
}
}
diff --git a/packages/seedream/src/activation.ts b/packages/seedream/src/activation.ts
index c2d56ad4..ef5788d2 100644
--- a/packages/seedream/src/activation.ts
+++ b/packages/seedream/src/activation.ts
@@ -1,3 +1,8 @@
-import { seedreamComponent, seedreamManifest } from "./index.js";
-export const svmlPackage = { format: "svml.node-package@1" as const, name: "@narratage/seedream", modules: [{ manifest: seedreamManifest, specifiers: ["@narratage/seedream", "@narratage/seedream@1"] }], components: [seedreamComponent] };
+import { createMarkupSurfaceHostFacet } from "@narratage/markup";
+import { seedreamComponent, seedreamManifest, seedreamModuleRef, seedreamSurfaceImplementationDigests } from "./index.js";
+import { decodeSeedreamReferenceImageSurface, decodeSeedreamTextImageSurface } from "./surface.js";
+export const svmlPackage = { format: "svml.node-package@1" as const, name: "@narratage/seedream", modules: [{ manifest: seedreamManifest, specifiers: ["@narratage/seedream", "@narratage/seedream@1"] }], components: [seedreamComponent], hostFacets: [
+ createMarkupSurfaceHostFacet({ module: seedreamModuleRef, surface: "text-image", mode: "structured", implementationDigest: seedreamSurfaceImplementationDigests.textImage, handler: decodeSeedreamTextImageSurface }),
+ createMarkupSurfaceHostFacet({ module: seedreamModuleRef, surface: "reference-image", mode: "structured", implementationDigest: seedreamSurfaceImplementationDigests.referenceImage, handler: decodeSeedreamReferenceImageSurface }),
+] };
export default svmlPackage;
diff --git a/packages/seedream/src/index.ts b/packages/seedream/src/index.ts
index a12deab2..246da1ab 100644
--- a/packages/seedream/src/index.ts
+++ b/packages/seedream/src/index.ts
@@ -1,6 +1,7 @@
import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";
import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
+import { digestOf } from "@narratage/protocol";
export const seedreamModuleRef = { name: "@narratage/seedream", version: "1" } as const;
@@ -32,7 +33,7 @@ export function sealSeedreamRequest(
return sealGenerationPortRequest(seedream5LitePorts, ports);
}
-export const seedreamDefinition = defineExactModelModule({
+const seedreamBaseDefinition = defineExactModelModule({
module: seedreamModuleRef,
endpoints: [{
key: "image",
@@ -42,7 +43,26 @@ export const seedreamDefinition = defineExactModelModule({
}],
});
-export const seedreamManifest = seedreamDefinition.manifest;
-export const seedreamManifestDigest = seedreamDefinition.manifestDigest;
-export const seedreamEndpoints = seedreamDefinition.endpoints;
-export const seedreamComponent = seedreamDefinition.component;
+export const seedreamEndpoints = seedreamBaseDefinition.endpoints;
+export const seedreamComponent = seedreamBaseDefinition.component;
+export const seedreamSurfaceImplementationDigests = {
+ textImage: digestOf("@narratage/seedream/text-image-surface@1"),
+ referenceImage: digestOf("@narratage/seedream/reference-image-surface@1"),
+} as const;
+const endpoint = seedreamEndpoints.image!;
+export const seedreamManifest = {
+ ...seedreamBaseDefinition.manifest,
+ surfaces: [{
+ name: "text-image", tag: "TextImage", mode: "structured" as const,
+ outputs: [endpoint.draftType],
+ implementation: { kind: "trusted-frontend-surface" as const, locator: "@narratage/seedream/text-image-surface", digest: seedreamSurfaceImplementationDigests.textImage },
+ }, {
+ name: "reference-image", tag: "ReferenceImage", mode: "structured" as const,
+ outputs: [endpoint.draftType, endpoint.mediaBindings.images!.type],
+ implementation: { kind: "trusted-frontend-surface" as const, locator: "@narratage/seedream/reference-image-surface", digest: seedreamSurfaceImplementationDigests.referenceImage },
+ }],
+};
+export const seedreamManifestDigest = digestOf(seedreamManifest);
+export const seedreamDefinition = {
+ ...seedreamBaseDefinition, manifest: seedreamManifest, manifestDigest: seedreamManifestDigest,
+};
diff --git a/packages/seedream/src/surface.ts b/packages/seedream/src/surface.ts
new file mode 100644
index 00000000..c8fac1ce
--- /dev/null
+++ b/packages/seedream/src/surface.ts
@@ -0,0 +1,84 @@
+import { artifactTypes } from "@narratage/artifact";
+import { generationPort, sealGenerationMediaBinding, sealGenerationRequestDraft } from "@narratage/generation";
+import type { GenerationMediaPort } from "@narratage/generation";
+import { createExactModelPrimaryGenerationFragment, exactModelMediaInputNames, exactModelTextInputName } from "@narratage/model-kit";
+import type { MarkupAttributeValue, StructuredElement, StructuredSurfaceHandler, SurfaceResolvedReference } from "@narratage/markup";
+import type { CanonicalValue, TypeRef } from "@narratage/protocol";
+import { textTypes, verifyText } from "@narratage/text";
+import { seedreamEndpoints } 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(a: TypeRef, b: TypeRef): boolean { return a.name === b.name && a.module.name === b.module.name && a.module.version === b.module.version; }
+function exact(element: StructuredElement, allowed: readonly string[], required = allowed): 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();
+}
+function boolean(element: StructuredElement, name: string): boolean {
+ const value = text(element, name);
+ if (value === "true") return true;
+ if (value === "false") return false;
+ throw new Error(`${element.name}.${name} must be true or false`);
+}
+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;
+}
+
+function decoder(referenceMode: boolean): StructuredSurfaceHandler {
+ return ({ element, resolveReference }) => {
+ exact(element, ["id", "prompt", "aspect-ratio", "quality", "output-format", "nsfw-check"]);
+ 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 endpoint = seedreamEndpoints.image!;
+ const imagePort = generationPort(endpoint.ports, "images");
+ assert(imagePort.value.kind === "media", "Seedream 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(referenceMode && localName(child.name) === "Reference", `${element.name} accepts no such child`);
+ exact(child, ["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 be image media`);
+ images.push(image);
+ }
+ assert(referenceMode ? images.length >= 1 : images.length === 0,
+ referenceMode ? `${element.name} requires at least one Reference` : `${element.name} does not accept References`);
+ assert(images.length <= imagePort.maxItems, `${element.name} accepts at most ${imagePort.maxItems} References`);
+ const draft = sealGenerationRequestDraft(endpoint.ports, {
+ aspectRatio: [text(element, "aspect-ratio")], quality: [text(element, "quality")],
+ outputFormat: [text(element, "output-format")], nsfwCheck: [boolean(element, "nsfw-check")],
+ });
+ 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 decodeSeedreamTextImageSurface = decoder(false);
+export const decodeSeedreamReferenceImageSurface = decoder(true);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 23fce033..eb70c793 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1098,15 +1098,24 @@ importers:
packages/gemini-omni:
dependencies:
+ '@narratage/artifact':
+ specifier: workspace:*
+ version: link:../artifact
'@narratage/generation':
specifier: workspace:*
version: link:../generation
+ '@narratage/markup':
+ specifier: workspace:*
+ version: link:../markup
'@narratage/model-kit':
specifier: workspace:*
version: link:../model-kit
'@narratage/protocol':
specifier: workspace:*
version: link:../protocol
+ '@narratage/text':
+ specifier: workspace:*
+ version: link:../text
packages/generation:
dependencies:
@@ -1144,6 +1153,9 @@ importers:
'@narratage/image-transform':
specifier: workspace:*
version: link:../image-transform
+ '@narratage/markup':
+ specifier: workspace:*
+ version: link:../markup
'@narratage/model-kit':
specifier: workspace:*
version: link:../model-kit
@@ -1156,15 +1168,24 @@ importers:
packages/grok-imagine:
dependencies:
+ '@narratage/artifact':
+ specifier: workspace:*
+ version: link:../artifact
'@narratage/generation':
specifier: workspace:*
version: link:../generation
+ '@narratage/markup':
+ specifier: workspace:*
+ version: link:../markup
'@narratage/model-kit':
specifier: workspace:*
version: link:../model-kit
'@narratage/protocol':
specifier: workspace:*
version: link:../protocol
+ '@narratage/text':
+ specifier: workspace:*
+ version: link:../text
packages/host:
dependencies:
@@ -1447,15 +1468,24 @@ importers:
packages/minimax-h3:
dependencies:
+ '@narratage/artifact':
+ specifier: workspace:*
+ version: link:../artifact
'@narratage/generation':
specifier: workspace:*
version: link:../generation
+ '@narratage/markup':
+ specifier: workspace:*
+ version: link:../markup
'@narratage/model-kit':
specifier: workspace:*
version: link:../model-kit
'@narratage/protocol':
specifier: workspace:*
version: link:../protocol
+ '@narratage/text':
+ specifier: workspace:*
+ version: link:../text
packages/model-kit:
dependencies:
@@ -1477,15 +1507,24 @@ importers:
packages/nano-banana:
dependencies:
+ '@narratage/artifact':
+ specifier: workspace:*
+ version: link:../artifact
'@narratage/generation':
specifier: workspace:*
version: link:../generation
+ '@narratage/markup':
+ specifier: workspace:*
+ version: link:../markup
'@narratage/model-kit':
specifier: workspace:*
version: link:../model-kit
'@narratage/protocol':
specifier: workspace:*
version: link:../protocol
+ '@narratage/text':
+ specifier: workspace:*
+ version: link:../text
packages/narrative:
dependencies:
@@ -2162,15 +2201,24 @@ importers:
packages/seedream:
dependencies:
+ '@narratage/artifact':
+ specifier: workspace:*
+ version: link:../artifact
'@narratage/generation':
specifier: workspace:*
version: link:../generation
+ '@narratage/markup':
+ specifier: workspace:*
+ version: link:../markup
'@narratage/model-kit':
specifier: workspace:*
version: link:../model-kit
'@narratage/protocol':
specifier: workspace:*
version: link:../protocol
+ '@narratage/text':
+ specifier: workspace:*
+ version: link:../text
packages/semantic-map:
dependencies:
diff --git a/test/generation-model-surfaces.test.ts b/test/generation-model-surfaces.test.ts
new file mode 100644
index 00000000..dab5939c
--- /dev/null
+++ b/test/generation-model-surfaces.test.ts
@@ -0,0 +1,157 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { artifactTypes } from "@narratage/artifact";
+import { parseStructuredElement } from "@narratage/markup";
+import type { StructuredSurfaceHandler, SurfaceResolvedReference } from "@narratage/markup";
+import { textTypes } from "@narratage/text";
+
+import geminiPackage from "../packages/gemini-omni/src/activation.js";
+import { decodeGeminiOmniVideoSurface } from "../packages/gemini-omni/src/surface.js";
+import grokPackage from "../packages/grok-imagine/src/activation.js";
+import {
+ decodeGrokImaginePreviewVideoSurface,
+ decodeGrokImagineVideoSurface,
+} from "../packages/grok-imagine/src/surface.js";
+import minimaxPackage from "../packages/minimax-h3/src/activation.js";
+import {
+ decodeMinimaxFrameVideoSurface,
+ decodeMinimaxReferenceVideoSurface,
+ decodeMinimaxTextVideoSurface,
+} from "../packages/minimax-h3/src/surface.js";
+import nanoPackage from "../packages/nano-banana/src/activation.js";
+import {
+ decodeNanoBananaImageSurface,
+ decodeNanoBananaProImageSurface,
+} from "../packages/nano-banana/src/surface.js";
+import seedreamPackage from "../packages/seedream/src/activation.js";
+import {
+ decodeSeedreamReferenceImageSurface,
+ decodeSeedreamTextImageSurface,
+} from "../packages/seedream/src/surface.js";
+
+const references = new Map<string, SurfaceResolvedReference>([
+ ["prompt", {
+ path: "prompt",
+ ref: { kind: "component-output", component: "prompt", output: "text" },
+ type: textTypes.text,
+ }],
+ ...["person.image", "ending.image", "voice.audio", "gesture.video"].map((path) => [path, {
+ path,
+ ref: {
+ kind: "component-output" as const,
+ component: path.split(".")[0]!,
+ output: path.split(".")[1]!,
+ },
+ type: artifactTypes.blob,
+ }] as const),
+]);
+
+async function decode(source: string, handler: StructuredSurfaceHandler) {
+ const element = parseStructuredElement({ name: "model.svml", text: source }, 0).element;
+ return await handler({
+ sourceName: "model.svml",
+ element,
+ resolveReference: (path) => references.get(path),
+ resolveAsset: () => { throw new Error("no assets in this test"); },
+ });
+}
+
+function componentInput(result: Awaited<ReturnType<typeof decode>>, name: string) {
+ return result.components[0]!.inputs[name];
+}
+
+test("Nano Banana variants own explicit prompt/reference Surfaces", async () => {
+ for (const [handler, tag] of [
+ [decodeNanoBananaImageSurface, "Image"],
+ [decodeNanoBananaProImageSurface, "ProImage"],
+ ] as const) {
+ const result = await decode(`<nano:${tag} id="shot" prompt={prompt} aspect-ratio="9:16" resolution="2K" output-format="png">
+ <nano:Reference image={person.image}/>
+ </nano:${tag}>`, handler);
+ assert.deepEqual(componentInput(result, "prompt:text"), references.get("prompt")!.ref);
+ assert.deepEqual(componentInput(result, "image-0001:artifact"), references.get("person.image")!.ref);
+ assert.deepEqual(result.components[0]!.outputs, { image: "shot.image" });
+ }
+ assert.deepEqual(nanoPackage.modules[0]!.manifest.surfaces.map((surface) => surface.tag), ["Image", "ProImage"]);
+ assert.equal(nanoPackage.hostFacets.length, 2);
+});
+
+test("Seedream keeps text and reference image authoring as two visible modes", async () => {
+ const textOnly = await decode(
+ '<seedream:TextImage id="scene" prompt={prompt} aspect-ratio="9:16" quality="high" output-format="png" nsfw-check="true"/>',
+ decodeSeedreamTextImageSurface,
+ );
+ assert.equal(Object.keys(textOnly.components[0]!.inputs).some((name) => name.endsWith(":artifact")), false);
+
+ const reference = await decode(`<seedream:ReferenceImage id="scene" prompt={prompt} aspect-ratio="9:16" quality="high" output-format="png" nsfw-check="true">
+ <seedream:Reference image={person.image}/>
+ </seedream:ReferenceImage>`, decodeSeedreamReferenceImageSurface);
+ assert.deepEqual(componentInput(reference, "image-0001:artifact"), references.get("person.image")!.ref);
+ await assert.rejects(
+ decode('<seedream:ReferenceImage id="bad" prompt={prompt} aspect-ratio="9:16" quality="high" output-format="png" nsfw-check="true"/>', decodeSeedreamReferenceImageSurface),
+ /requires at least one Reference/u,
+ );
+ assert.equal(seedreamPackage.hostFacets.length, 2);
+});
+
+test("MiniMax exposes text, frame and multimodal reference graphs without dynamic mode guessing", async () => {
+ const plain = await decode(
+ '<h3:TextVideo id="plain" prompt={prompt} duration="6" resolution="768P" aspect-ratio="9:16"/>',
+ decodeMinimaxTextVideoSurface,
+ );
+ assert.deepEqual(plain.components[0]!.outputs, { video: "plain.video" });
+
+ const frame = await decode(
+ '<h3:FrameVideo id="frame" prompt={prompt} duration="6" resolution="2K" first-frame={person.image} last-frame={ending.image}/>',
+ decodeMinimaxFrameVideoSurface,
+ );
+ assert.deepEqual(componentInput(frame, "media-0001:artifact"), references.get("person.image")!.ref);
+ assert.deepEqual(componentInput(frame, "media-0002:artifact"), references.get("ending.image")!.ref);
+
+ const reference = await decode(`<h3:ReferenceVideo id="refs" prompt={prompt} duration="8" resolution="768P" aspect-ratio="9:16">
+ <h3:Reference image={person.image}/>
+ <h3:Reference audio={voice.audio}/>
+ </h3:ReferenceVideo>`, decodeMinimaxReferenceVideoSurface);
+ assert.equal(Object.keys(reference.components[0]!.inputs).filter((name) => name.endsWith(":artifact")).length, 2);
+ assert.deepEqual(minimaxPackage.modules[0]!.manifest.surfaces.map((surface) => surface.tag), [
+ "TextVideo", "FrameVideo", "ReferenceVideo",
+ ]);
+});
+
+test("Gemini Omni preserves media excerpts and opaque IDs in their proper request ports", async () => {
+ const result = await decode(`<omni:Video id="omni" prompt={prompt} duration="8" aspect-ratio="9:16" resolution="1080p" seed="42">
+ <omni:Image image={person.image}/>
+ <omni:Excerpt video={gesture.video} start-sec="1.5" end-sec="4"/>
+ <omni:AudioId value="voice-1"/>
+ <omni:CharacterId value="person-1"/>
+ </omni:Video>`, decodeGeminiOmniVideoSurface);
+ assert.deepEqual(componentInput(result, "media-0001:artifact"), references.get("person.image")!.ref);
+ assert.deepEqual(componentInput(result, "media-0002:artifact"), references.get("gesture.video")!.ref);
+ const draft = result.records.find((record) => record.id === "omni.draft")!;
+ assert.equal(draft.value.kind, "inline");
+ assert.deepEqual((draft.value.value as { ports: Record<string, unknown> }).ports.audioIds, ["voice-1"]);
+ assert.deepEqual((draft.value.value as { ports: Record<string, unknown> }).ports.characterIds, ["person-1"]);
+ const excerpt = result.records.find((record) => record.id === "omni.media-0002.binding")!;
+ assert.deepEqual((excerpt.value.value as { fields: unknown }).fields, { startSec: 1.5, endSec: 4 });
+ assert.equal(geminiPackage.hostFacets.length, 1);
+});
+
+test("Grok standard and preview variants stay separate and continuation is explicit", async () => {
+ const continuation = await decode(`<grok:Video id="continued" prompt={prompt} duration="6" aspect-ratio="9:16" resolution="720p" source-task-id="task-1">
+ <grok:Reference image={person.image}/>
+ </grok:Video>`, decodeGrokImagineVideoSurface);
+ assert.deepEqual(componentInput(continuation, "image-0001:artifact"), references.get("person.image")!.ref);
+
+ const preview = await decode(
+ '<grok:PreviewVideo id="preview" prompt={prompt} duration="6" aspect-ratio="9:16" resolution="720p"/>',
+ decodeGrokImaginePreviewVideoSurface,
+ );
+ assert.deepEqual(preview.components[0]!.outputs, { video: "preview.video" });
+ await assert.rejects(
+ decode('<grok:Video id="bad" prompt={prompt} duration="6" aspect-ratio="9:16" resolution="720p" source-task-id="task-1"/>', decodeGrokImagineVideoSurface),
+ /requires at least one Reference/u,
+ );
+ assert.deepEqual(grokPackage.modules[0]!.manifest.surfaces.map((surface) => surface.tag), ["Video", "PreviewVideo"]);
+ assert.equal(grokPackage.hostFacets.length, 2);
+});