@hypit/hypit 0.2.5 → 0.2.6

package/README.md

@@ -15,6 +15,11 @@
   <a href="https://github.com/hypit-ai/hypit/blob/main/README.zh-CN.md"><strong>简体中文</strong></a>
 </p>
 
+<p align="center">
+  <a href="https://trendshift.io/repositories/229030"><img alt="Trendshift #1 Repository of the Day" src="https://trendshift.io/api/badge/trendshift/repositories/229030/daily"></a>
+  <a href="https://trendshift.io/repositories/229030"><img alt="Trendshift #1 TypeScript Repository of the Day" src="https://trendshift.io/api/badge/trendshift/repositories/229030/daily?language=TypeScript"></a>
+</p>
+
 <p align="center">
   <img alt="Stars" src="https://img.shields.io/github/stars/hypit-ai/hypit?style=flat-square&color=FFD700&logo=github&logoColor=white&label=Stars">
   <a href="https://github.com/hypit-ai/hypit/blob/main/package.json"><img alt="Node 22.15+" src="https://img.shields.io/badge/Node.js-22.15%2B-5FA04E?style=flat-square&logo=nodedotjs&logoColor=white"></a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",
@@ -279,6 +279,7 @@
     "@hypit/typography-track-studio": "workspace:*",
     "@hypit/visual-ir": "workspace:*",
     "@hypit/volcengine-matting": "workspace:*",
+    "@hypit/wan": "workspace:*",
     "@hypit/whisperx": "workspace:*",
     "@types/node": "24.10.1",
     "rollup": "4.62.4",

package/packages/caption/src/temporalize.ts

@@ -17,6 +17,7 @@ export function temporalizeCaptionDocument(
   }
   const breaks = new Set(document.cueBreaks.map((cueBreak) => cueBreak.afterUnitId));
   const timed: Array<{ unit: CaptionDocument["units"][number]; timing: TimedCaptionUnit }> = [];
+  const previousByRole = new Map<string | undefined, { timing: TimedCaptionUnit }>();
   for (const unit of document.units) {
     const window = tokenFrameSpan(semantic, unit.sourceTokenIds);
     if (window === undefined) continue;
@@ -25,7 +26,16 @@ export function temporalizeCaptionDocument(
     }
     const startFrame = window.startFrame;
     const endFrameExclusive = Math.max(startFrame + 1, window.endFrameExclusive);
-    timed.push({ unit, timing: { unitId: unit.id, startFrame, endFrameExclusive } });
+    // Acoustic Word windows may overlap. The Timeline keeps those measurements; an authored unit
+    // gets one owner: as soon as the next unit of the same Role starts, this one stops. A Cue
+    // envelope ends at its last unit, so Cue boundaries are exclusive by the same rule.
+    const previous = previousByRole.get(unit.role);
+    if (previous !== undefined && startFrame > previous.timing.startFrame && startFrame < previous.timing.endFrameExclusive) {
+      previous.timing = { ...previous.timing, endFrameExclusive: startFrame };
+    }
+    const entry = { unit, timing: { unitId: unit.id, startFrame, endFrameExclusive } };
+    previousByRole.set(unit.role, entry);
+    timed.push(entry);
   }
   const cues: TimedCaptionCue[] = [];
   let current: { units: TimedCaptionUnit[]; segmentId: string; turnId: string } | undefined;

package/packages/credential-store-os/runtime/windows-credential.ps1

@@ -38,6 +38,9 @@ switch ($Operation) {
     # Add replaces the same resource/account; do not destroy the old value before it succeeds.
     $bytes = [Convert]::FromBase64String([string]$request.secret)
     $secret = [System.Text.Encoding]::UTF8.GetString($bytes)
+    if ($secret.Length -gt 512) {
+      throw "PasswordVault cannot store a $($secret.Length)-character secret (limit 512). Select @hypit/credential-store-file for OAuth tokens."
+    }
     $credential = New-Object Windows.Security.Credentials.PasswordCredential(
       [string]$request.service,
       [string]$request.account,

package/packages/credential-store-os/src/windows.ts

@@ -9,6 +9,19 @@ type WindowsCredentialResult = {
 
 const windowsScript = fileURLToPath(new URL("../runtime/windows-credential.ps1", import.meta.url));
 
+/** PasswordVault password field; OAuth JSON routinely exceeds this. */
+export const windowsLockerPasswordLimit = 512;
+
+export function assertWindowsLockerSecret(secret: string, account: string): void {
+  if (secret.length > windowsLockerPasswordLimit) {
+    throw new Error(
+      `Windows Credential Locker cannot store the ${secret.length}-character secret for ${account}`
+      + ` (PasswordVault limit is ${windowsLockerPasswordLimit} characters).`
+      + " Select @hypit/credential-store-file for OAuth tokens.",
+    );
+  }
+}
+
 /** The OS adapter owns this one child; Node owns its timeout, bounded output and termination. */
 export function windowsCredential(
   operation: "read" | "write" | "delete",
@@ -16,6 +29,7 @@ export function windowsCredential(
   account: string,
   secret?: string,
 ): Promise<WindowsCredentialResult> {
+  if (secret !== undefined) assertWindowsLockerSecret(secret, account);
   return new Promise((resolve, reject) => {
     const child = execFile("powershell.exe", [
       "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",

package/packages/media-execution/src/execute.ts

@@ -1307,9 +1307,27 @@ export async function executeMuxProgramMedia(
       && compareTimestamp(finalVideo[0]!.startPts, finalAudio[0]!.startPts) === 0,
     "Final mux audio and video do not share one presentation origin");
     const finalAudioSpan = duration(finalAudio[0]!);
-    assert(roundPositive(finalAudioSpan.numerator * 48_000n, finalAudioSpan.denominator)
-      === need.audio.sampleFrames,
-    "Final mux audio presentation span differs from TimelineAudio");
+    /*
+     * The staged WAV is asserted sample-exact above; this checks what survived AAC.
+     *
+     * AAC cannot carry an arbitrary sample count: the encoder emits 1024-sample frames and
+     * reports a priming delay that the MP4 muxer compensates with an edit list, so the
+     * presented span lands a few samples away from the input. Measured here with ffmpeg 6.1
+     * on synthetic tone (i.e. independent of any project's material): a 4 249 600-sample input
+     * presents as 4 249 584 (-16), and 4 236 800 presents as 4 236 768 (-32). Padding the
+     * timeline to a whole number of AAC frames does not remove it — the delay is not a
+     * frame-alignment artifact.
+     *
+     * Demanding exact equality therefore rejects every correct mux whose length is not a
+     * fixed point of that round trip. The real invariant AAC can hold is that no whole frame
+     * of audio went missing, so the tolerance is one AAC frame rather than an arbitrary epsilon;
+     * anything larger still means genuine desync and still fails.
+     */
+    const AAC_FRAME_SAMPLES = 1_024;
+    const finalAudioSamples = roundPositive(finalAudioSpan.numerator * 48_000n, finalAudioSpan.denominator);
+    assert(Math.abs(finalAudioSamples - need.audio.sampleFrames) < AAC_FRAME_SAMPLES,
+      `Final mux audio presentation span differs from TimelineAudio by ${
+        String(finalAudioSamples - need.audio.sampleFrames)} samples`);
     const artifact = await env.artifacts.putFile(output, "video/mp4");
     const value: MuxedMedia = sealMuxedMedia({
       frameRate: need.visual.frameRate,

package/packages/provider-hiapi/README.md

@@ -54,6 +54,13 @@ Runtime Profile example:
 
 ```json
 {
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtimes/local",
+  "credentials": {
+    "platform": {
+      "use": "@hypit/credential-store-platform"
+    }
+  },
   "endpoints": {
     "hiapi.default": {
       "use": "@hypit/provider-hiapi",
@@ -64,7 +71,8 @@ Runtime Profile example:
         "pollIntervalMs": 10000
       }
     }
-  }
+  },
+  "bindings": {}
 }
 ```
 

package/packages/provider-hypihub/README.md

@@ -84,18 +84,26 @@ Runtime Profile example:
 
 ```json
 {
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtimes/local",
+  "credentials": {
+    "platform": {
+      "use": "@hypit/credential-store-platform"
+    }
+  },
   "endpoints": {
     "hypihub.default": {
       "use": "@hypit/provider-hypihub",
       "pool": "hypihub.default",
       "config": {
         "baseUrl": "https://hypit.ai",
-        "apiKey": { "store": "os", "key": "hypihub.oauth" },
+        "apiKey": { "store": "platform", "key": "hypihub.oauth" },
         "defaultConcurrency": 3,
         "pollIntervalMs": 10000
       }
     }
-  }
+  },
+  "bindings": {}
 }
 ```
 

package/packages/provider-monid/README.md

@@ -2,7 +2,7 @@
 
 Hypit Runtime Provider for a [Monid](https://monid.ai) workspace. It runs Monid's generation
 endpoints through `POST /v1/run`, polls `GET /v1/runs/{runId}` until the run is terminal, downloads
-the returned video and stores it in the current Build.
+every returned file and stores it in the current Build.
 
 | Capability | Monid endpoint |
 | --- | --- |
@@ -11,16 +11,17 @@ the returned video and stores it in the current Build.
 | `@hypit/seedance@1#seedance-2-mini` | `bytedance` `/v1/video/seedance-2.0-mini` |
 | `@hypit/seedance@1#seedance-2.5` | `bytedance` `/v1/video/seedance-2.5` |
 | `@hypit/minimax-h3@1#minimax-h3` | `minimax` `/v1/video/minimax-h3` |
+| `@hypit/wan@1#wan-2.7-image` | `alibaba` `/v1/image/wan2.7-image` |
+| `@hypit/wan@1#wan-2.7-image-pro` | `alibaba` `/v1/image/wan2.7-image-pro` |
 
 Monid's catalogue lists further generation endpoints, including the H3 Fast, Max and Max Turbo
-variants and Hailuo 2.3; their models are not the ones the Distribution describes. Input schemas
-are published through the authenticated `inspect` operation, which is where the request bodies
-above come from.
+variants, Hailuo 2.3 and the Kling, Gemini and Qwen families; their models are not the ones the
+Distribution describes. Input schemas are published through the authenticated `inspect` operation,
+which is where the request bodies below come from.
 
-Every mapped endpoint relays a BytePlus ModelArk request: one `content` array holding the prompt
-and each media input as a typed item with its `role` (`first_frame`, `last_frame`,
-`reference_image`, `reference_video`, `reference_audio`), then `resolution`, `ratio` and
-`duration`.
+The video endpoints relay a BytePlus ModelArk request: one `content` array holding the prompt and
+each media input as a typed item with its `role` (`first_frame`, `last_frame`, `reference_image`,
+`reference_video`, `reference_audio`), then `resolution`, `ratio` and `duration`.
 
 The Seedance endpoints add `generate_audio`. Monid documents no web search field for them, so
 `web-search="true"` is unsupported, and Seedance 2.5 frame mode (`first-frame` present) requires
@@ -37,6 +38,17 @@ text-to-video request carrying no `aspect-ratio` is reported unsupported before
 resolved, and the other two modes are sent as `adaptive`. H3 returns its video at `content.url`
 rather than the ModelArk `video_url`.
 
+The Wan image endpoints take their fields directly: `prompt`, `images` as plain URLs, `size` for the
+band, `n`, `enable_sequential`, `thinking_mode`, `watermark` and `seed`. Both variants accept the
+same fields, and the Pro variant adds the `4K` band. Two service limits are reported before any
+reference is resolved: `4K` renders from a prompt alone, without reference images or an image set,
+and a request renders at most four pictures outside an image set. An image set returns several
+files, so collection downloads each one.
+
+The endpoints also document a custom colour palette and per-image bounding boxes. Neither has a
+representation in the model port vocabulary, which carries scalars and media rather than object
+arrays, so the Provider transmits neither.
+
 Reference media are uploaded through the workspace file system Monid provides for this purpose
 (`sfs`): `/put` signs an upload for `hypit/<resource>.<ext>`, the bytes are `PUT` to that URL, and
 `/cat` mints a one-day download URL that the generation endpoint fetches. Uploaded files stay in the
@@ -52,6 +64,13 @@ Runtime Profile example:
 
 ```json
 {
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtimes/local",
+  "credentials": {
+    "platform": {
+      "use": "@hypit/credential-store-platform"
+    }
+  },
   "endpoints": {
     "monid.default": {
       "use": "@hypit/provider-monid",
@@ -62,7 +81,8 @@ Runtime Profile example:
         "pollIntervalMs": 10000
       }
     }
-  }
+  },
+  "bindings": {}
 }
 ```
 

package/packages/provider-monid/package.json

@@ -12,7 +12,8 @@
     "@hypit/minimax-h3": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/runtime": "workspace:*",
-    "@hypit/runtime-kit": "workspace:*"
+    "@hypit/runtime-kit": "workspace:*",
+    "@hypit/wan": "workspace:*"
   },
   "devDependencies": {
     "@hypit/seedance": "workspace:*"

package/packages/provider-monid/src/mapping.ts

@@ -3,6 +3,7 @@ import type { GenerationWireMapping } from "@hypit/generation";
 
 const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };
 const MINIMAX_H3: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
+const WAN: ModuleRef = { name: "@hypit/wan", version: "1" };
 
 /**
  * One mapping plus the Monid provider that relays the endpoint. Monid addresses an endpoint by
@@ -57,10 +58,33 @@ const minimaxH3: MonidMapping = {
   },
 };
 
+/**
+ * Monid's `alibaba` Wan 2.7 image endpoints. Both variants take the same fields; the Pro variant
+ * adds a 4K band. Input images are plain public URLs rather than role-tagged items, and the model
+ * reads exclusions from the prompt, so it has no negative-prompt field.
+ */
+const wan = (name: string, endpoint: string): MonidMapping => ({
+  service: "alibaba",
+  capability: { module: WAN, name }, result: "image",
+  routes: [{ model: endpoint }],
+  fields: {
+    prompt: { as: "value", field: "prompt" },
+    images: { as: "urlArray", field: "images" },
+    resolution: { as: "value", field: "size" },
+    count: { as: "value", field: "n" },
+    imageSet: { as: "value", field: "enable_sequential" },
+    extendedReasoning: { as: "value", field: "thinking_mode" },
+    watermark: { as: "value", field: "watermark" },
+    seed: { as: "value", field: "seed" },
+  },
+});
+
 export const monidMappings: readonly MonidMapping[] = [
   seedance("seedance-2", "/v1/video/seedance-2.0"),
   seedance("seedance-2-fast", "/v1/video/seedance-2.0-fast"),
   seedance("seedance-2-mini", "/v1/video/seedance-2.0-mini"),
   seedance("seedance-2.5", "/v1/video/seedance-2.5"),
   minimaxH3,
+  wan("wan-2.7-image", "/v1/image/wan2.7-image"),
+  wan("wan-2.7-image-pro", "/v1/image/wan2.7-image-pro"),
 ];

package/packages/provider-monid/src/provider.ts

@@ -31,7 +31,7 @@ type Handle = {
   readonly runId: string;
   readonly route: string;
   readonly startedAt: number;
-  readonly url?: string;
+  readonly urls?: readonly string[];
 };
 
 function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
@@ -66,13 +66,21 @@ function httpsUrl(value: unknown, subject: string): string {
   return value;
 }
 /**
- * The relayed result. The ModelArk endpoints return the task's `video_url`; MiniMax-H3 returns the
- * video at `content.url`. The link expires, so collection downloads it rather than storing it.
+ * The relayed result. The ModelArk endpoints return the task's `video_url` and MiniMax-H3 its
+ * `content.url`; an image endpoint returns one entry per rendered picture. Every link expires, so
+ * collection downloads them rather than storing the addresses.
  */
-function outputVideoUrl(run: Record<string, unknown>): string {
+function outputUrls(run: Record<string, unknown>): readonly string[] {
   const output = object(run.output, "Monid run output");
   const content = output.content === undefined ? undefined : object(output.content, "Monid run output content");
-  return httpsUrl(output.video_url ?? content?.video_url ?? content?.url, "Monid run output");
+  const listed = [output.results, output.images, output.urls, content?.results, content?.images]
+    .find((value): value is readonly unknown[] => Array.isArray(value) && value.length > 0);
+  if (listed !== undefined) {
+    return listed.map((item, index) => httpsUrl(
+      typeof item === "string" ? item : object(item, `Monid run output ${index}`).url,
+      `Monid run output ${index}`));
+  }
+  return [httpsUrl(output.video_url ?? output.url ?? content?.video_url ?? content?.url, "Monid run output")];
 }
 const extensions: Readonly<Record<string, string>> = {
   "image/jpeg": "jpg", "image/png": "png", "image/webp": "webp", "video/mp4": "mp4", "video/quicktime": "mov",
@@ -180,7 +188,7 @@ function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: n
         if (!ended) return { ...wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: String(run.status) }), receipt };
         const rejected = monidRunFailure(run, handle.runId);
         if (rejected !== undefined) return { ...failure(rejected), receipt };
-        return { status: "ready", handle: canonicalize({ ...handle, url: outputVideoUrl(run) }), receipt };
+        return { status: "ready", handle: canonicalize({ ...handle, urls: outputUrls(run) }), receipt };
       } catch (error) {
         return failure(error);
       }
@@ -201,7 +209,7 @@ function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: n
         }
         const rejected = monidRunFailure(run, handle.runId);
         if (rejected !== undefined) return { ...failure(rejected), receipt };
-        return { status: "ready", handle: canonicalize({ ...handle, url: outputVideoUrl(run) }), receipt };
+        return { status: "ready", handle: canonicalize({ ...handle, urls: outputUrls(run) }), receipt };
       } catch (error) {
         return failure(error);
       }
@@ -211,10 +219,15 @@ function endpoint(client: MonidClient, pollIntervalMs: number, maxOperationMs: n
         const handle = object(context.handle, "Monid handle") as unknown as Handle;
         const route = monidRouteForCapability(context.need.capability);
         assert(route !== undefined && handle.route === route.key, "Monid collection route differs");
-        await context.reportProgress?.({ phase: "Receiving generated video" });
-        const downloaded = await client.download(httpsUrl(handle.url, "Monid handle"));
-        const blob = await context.resources.put(downloaded.bytes, downloaded.mediaType);
-        return { status: "completed", result: { value: route.packageResult([blob]) }, receipt: { id: handle.runId } };
+        const urls = handle.urls ?? [];
+        assert(urls.length > 0, "Monid handle carries no result");
+        await context.reportProgress?.({ phase: `Receiving ${urls.length} generated ${route.media}${urls.length === 1 ? "" : "s"}` });
+        const blobs: BlobRef[] = [];
+        for (const url of urls) {
+          const downloaded = await client.download(httpsUrl(url, "Monid handle"));
+          blobs.push(await context.resources.put(downloaded.bytes, downloaded.mediaType));
+        }
+        return { status: "completed", result: { value: route.packageResult(blobs) }, receipt: { id: handle.runId } };
       } catch (error) {
         return failure(error);
       }

package/packages/provider-monid/src/routes.ts

@@ -2,6 +2,7 @@ import {
   compileWireRequest,
   selectWireModelForRequest,
   generationTypes,
+  sealGeneratedImageSet,
   sealGeneratedVideoSet,
 } from "@hypit/generation";
 import type { GenerationArtifactUrlResolver, GenerationRequest } from "@hypit/generation";
@@ -22,6 +23,8 @@ export type MonidPreparedRequest = {
 export type MonidRoute = MonidMapping & {
   readonly key: string;
   readonly returns: TypeRef;
+  /** What the run produces, which decides how many results collection expects. */
+  readonly media: "image" | "video";
   readonly supports: (request: EndpointRequest) => EndpointSupport;
   readonly prepare: (constraints: CanonicalValue) => MonidPreparedRequest;
   readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
@@ -42,7 +45,20 @@ function referenceToVideo(request: GenerationRequest): boolean {
   return present(request, "referenceImage") || present(request, "referenceVideo") || present(request, "referenceAudio");
 }
 
+function wanRejection(mapping: MonidMapping, request: GenerationRequest): string | undefined {
+  const set = scalar(request, "imageSet") === true;
+  if (scalar(request, "resolution") === "4K" && (present(request, "images") || set)) {
+    return "Wan renders 4K from a prompt alone, without reference images or an image set";
+  }
+  const count = scalar(request, "count");
+  if (typeof count === "number" && count > 4 && !set) {
+    return `Wan renders at most 4 pictures outside an image set, not ${count}`;
+  }
+  return undefined;
+}
+
 function rejection(mapping: MonidMapping, request: GenerationRequest): string | undefined {
+  if (mapping.capability.module.name === "@hypit/wan") return wanRejection(mapping, request);
   if (mapping.capability.name === "minimax-h3") {
     // MiniMax-H3 resolves the framing from the uploaded image in frame mode and defaults
     // reference-to-video to adaptive. Text-to-video carries no such source, and the endpoint
@@ -103,7 +119,8 @@ function capabilityKey(capability: CapabilityRef): string {
 export const monidRoutes: readonly MonidRoute[] = monidMappings.map((mapping) => ({
   ...mapping,
   key: capabilityKey(mapping.capability),
-  returns: generationTypes.videoSet,
+  returns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,
+  media: mapping.result === "image" ? "image" as const : "video" as const,
   supports: (request) => {
     const reason = rejection(mapping, request.constraints as unknown as GenerationRequest);
     return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
@@ -112,7 +129,10 @@ export const monidRoutes: readonly MonidRoute[] = monidMappings.map((mapping) =>
     const request = constraints as unknown as GenerationRequest;
     const reason = rejection(mapping, request);
     if (reason !== undefined) throw new Error(reason);
-    const body = mapping.capability.name === "minimax-h3" ? minimaxH3Input : arkInput;
+    // The Wan endpoints take the compiled fields as their body; the ModelArk endpoints fold their
+    // media into one role-tagged `content` array first.
+    const body = mapping.capability.module.name === "@hypit/wan" ? (input: Record<string, unknown>) => input
+      : mapping.capability.name === "minimax-h3" ? minimaxH3Input : arkInput;
     return {
       service: mapping.service,
       endpoint: selectWireModelForRequest(mapping, request),
@@ -121,7 +141,9 @@ export const monidRoutes: readonly MonidRoute[] = monidMappings.map((mapping) =>
   },
   packageResult: (artifacts) => ({
     kind: "inline",
-    value: canonicalize(sealGeneratedVideoSet({ videos: artifacts })),
+    value: canonicalize(mapping.result === "image"
+      ? sealGeneratedImageSet({ images: artifacts })
+      : sealGeneratedVideoSet({ videos: artifacts })),
   }),
 }));
 

package/packages/provider-pollo/README.md

@@ -37,6 +37,13 @@ Runtime Profile example:
 
 ```json
 {
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtimes/local",
+  "credentials": {
+    "platform": {
+      "use": "@hypit/credential-store-platform"
+    }
+  },
   "endpoints": {
     "pollo.default": {
       "use": "@hypit/provider-pollo",
@@ -47,7 +54,8 @@ Runtime Profile example:
         "pollIntervalMs": 10000
       }
     }
-  }
+  },
+  "bindings": {}
 }
 ```
 

package/packages/provider-tokendance/README.md

@@ -46,6 +46,13 @@ Runtime Profile example:
 
 ```json
 {
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtimes/local",
+  "credentials": {
+    "platform": {
+      "use": "@hypit/credential-store-platform"
+    }
+  },
   "endpoints": {
     "tokendance.default": {
       "use": "@hypit/provider-tokendance",
@@ -56,7 +63,8 @@ Runtime Profile example:
         "pollIntervalMs": 10000
       }
     }
-  }
+  },
+  "bindings": {}
 }
 ```
 

package/packages/wan/README.md

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

package/packages/wan/package.json

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

package/packages/wan/src/activation.ts

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

package/packages/wan/src/index.ts

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

package/packages/wan/src/surface.ts

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