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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat: add author surfaces for generation models
kashorineb8fb8d6328a
diff --git a/packages/gemini-omni/README.md b/packages/gemini-omni/README.mdindex 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 Endpointimplementation; 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.jsonindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.mdindex 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-transformProgram, 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.jsonindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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 modelchoice; it does not route to another model or access a Provider. `@narratage/provider-kie` is oneoptional 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.jsonindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.mdindex 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 semanticsand validation only; Provider calls, credentials, retries and queueing belong to a Runtime Endpointsuch 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.jsonindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.mdindex 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.jsonindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.mdindex 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.jsonindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.yamlindex 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:../textpackages/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:../textpackages/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:../textpackages/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:../textpackages/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:../textpackages/semantic-map:dependencies:diff --git a/test/generation-model-surfaces.test.ts b/test/generation-model-surfaces.test.tsnew file mode 100644index 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);+});