@hypit/hypit 0.2.6 → 0.2.8

package/README.md

@@ -149,7 +149,7 @@ commands and the repository layout.
   </tr>
 </table>
 
-## Launch Partner
+## Launch Partners
 
 <table>
   <tr>

package/dist/public/hyperframes.d.ts

@@ -788,5 +788,22 @@ type BrowserProgram = {
 };
 declare function browserProgram(value: BrowserProgram, artifacts?: readonly BlobRef[]): VisualProgramElement["program"];
 
-export { BROWSER_PROGRAM_FORMAT, assertHyperframesDocument, assertHyperframesFrameIndex, assertHyperframesFrameSpan, browserProgram, compileHyperframesDocument, hyperframesComponent, hyperframesDocumentFragment, hyperframesDocumentSchema, hyperframesManifest, hyperframesModuleRef, hyperframesProducers, hyperframesResourceUri, hyperframesTime, hyperframesTypes, materializeHyperframesHtml };
-export type { BrowserProgram, HyperframesCanvas, HyperframesDocument, HyperframesFrameDomain, HyperframesFrameSpan, ResourceUrlResolver };
+/** An already materialized HTML programme and the local files its URLs address. */
+type HyperframesHtmlProject = {
+    readonly html: string;
+    readonly assets: readonly {
+        readonly url: string;
+        readonly artifact: BlobRef;
+    }[];
+};
+/** Read the exact clock emitted by this package. Seconds never reconstruct frame identity. */
+declare function hyperframesHtmlDomain(html: string): HyperframesFrameDomain & {
+    readonly canvas: HyperframesCanvas;
+};
+/** Resource URL positions in the compiler's self-contained HTML (inline JS and CSS). */
+declare function mapHyperframesHtmlUrls(html: string, map: (url: string) => string): string;
+declare function hyperframesHtmlAssetUrls(html: string): readonly string[];
+declare function assertHyperframesHtmlProject(value: unknown): asserts value is HyperframesHtmlProject;
+
+export { BROWSER_PROGRAM_FORMAT, assertHyperframesDocument, assertHyperframesFrameIndex, assertHyperframesFrameSpan, assertHyperframesHtmlProject, browserProgram, compileHyperframesDocument, hyperframesComponent, hyperframesDocumentFragment, hyperframesDocumentSchema, hyperframesHtmlAssetUrls, hyperframesHtmlDomain, hyperframesManifest, hyperframesModuleRef, hyperframesProducers, hyperframesResourceUri, hyperframesTime, hyperframesTypes, mapHyperframesHtmlUrls, materializeHyperframesHtml };
+export type { BrowserProgram, HyperframesCanvas, HyperframesDocument, HyperframesFrameDomain, HyperframesFrameSpan, HyperframesHtmlProject, ResourceUrlResolver };

package/examples/provider-package/README.md

@@ -68,7 +68,7 @@ differ from the image example, and each is the reason the video example exists.
 **The reference vocabulary is wider, and each role maps to its own field.** The Model declares
 `referenceImage`, `referenceVideo` and `referenceAudio` as separate ports precisely so each can map
 to one wire field — a service that mixes them into one array cannot tell the roles apart. An image
-reference also carries an optional `personReference` classification, which is why those ports use
+reference also requires a boolean `personReference` classification, which is why those ports use
 `itemObject` rather than `urlArray`: the item field travels with the URL it belongs to.
 
 ```json
@@ -76,7 +76,7 @@ reference also carries an optional `personReference` classification, which is wh
 ```
 
 `firstFrame` and `lastFrame` accept at most one item each, so their body fields are URLs.
-This illustrative service accepts their optional person classification on `POST /uploads` through
+This illustrative service accepts their required visual-reference person classification on `POST /uploads` through
 `x-person-reference: true` or `false`. Their mappings declare `resourceFields: ["personReference"]`,
 and the URL resolver sends that header when supplied. Replace this with the real service’s
 documented transport; a field that the service cannot carry must be refused, never discarded.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",
@@ -232,6 +232,7 @@
     "@hypit/narrative": "workspace:*",
     "@hypit/performance": "workspace:*",
     "@hypit/performance-studio": "workspace:*",
+    "@hypit/pixverse": "workspace:*",
     "@hypit/program-space": "workspace:*",
     "@hypit/project-context-node": "workspace:*",
     "@hypit/protocol": "workspace:*",

package/packages/caption-fine/README.md

@@ -14,10 +14,10 @@ does not carry a private visual role.
   </caption-fine:Track>
 ```
 
-An optional Spatial Region Timeline replaces only the moving placement point. The timeline is authored
-numeric input, measured from the actual footage before the composition pass that consumes it;
-it is not a face-tracking request. A prior Build may produce that footage with ordinary fixed Caption,
-and a later Run can reuse the same media and alignment while changing placement:
+An optional Spatial Region Timeline supplies a moving placement point when the user's reference
+visibly uses head-following Caption or the user asks for that treatment. Ordinary Caption uses the
+Style's placement without regions. The Region Timeline is authored numeric input mapped from available picture
+evidence to the composition that consumes it; it is not a face-tracking request:
 
 ```xml
 <space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>

package/packages/credential-store-file/README.md

@@ -50,6 +50,10 @@ The default directory is `credentials` under the Host state root printed by `hyp
 `config.path` explicitly selects a directory, including an absolute directory outside that root;
 relative paths resolve against the Host root.
 Opening the adapter and reading an absent key do not create files. Keep this directory outside Git.
+On WSL, the default under the Linux home uses normal Linux permissions. If the Host state root is
+on a Windows-mounted drive, set this Store's `config.path` to a private directory in the WSL Linux
+filesystem before login. A Windows mount's reported mode does not establish that its Windows ACL
+protects the secret, so the Store does not waive its owner-private check for that path.
 
 Each key has its own JSON file containing only `secret` and optional `expiresAt`, as defined by
 CredentialValue. Filenames use reversible lower-case hex encoding of the key's UTF-16 bytes, with a

package/packages/credential-store-file/src/store.ts

@@ -38,7 +38,7 @@ export class FileCredentialStore implements WritableCredentialStore {
     const info = await stat(this.directory);
     if (!info.isDirectory()) throw new Error(`Credential path is not a directory: ${this.directory}`);
     if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
-      throw new Error(`Credential directory must be owner-private: ${this.directory}`);
+      throw new Error(`Credential directory must be owner-private: ${this.directory}. On WSL, keep credentials in the Linux filesystem rather than a Windows-mounted drive.`);
     }
   }
 
@@ -57,7 +57,7 @@ export class FileCredentialStore implements WritableCredentialStore {
     try {
       const info = await file.stat();
       if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
-        throw new Error(`Credential file must be owner-private: ${path}`);
+        throw new Error(`Credential file must be owner-private: ${path}. On WSL, keep credentials in the Linux filesystem rather than a Windows-mounted drive.`);
       }
       const text = await file.readFile("utf8");
       // JSON parser messages may include secret bytes. Report the file, never its contents.

package/packages/credential-store-platform/README.md

@@ -47,6 +47,8 @@ credential stored in a locker stays in that locker; a credential stored in a fil
 - `path` selects the directory for Linux file storage, resolved against the Host state root printed by
   `hypit paths`. The default is the same `credentials` directory `@hypit/credential-store-file` uses,
   so on Linux, switching between the two Stores finds the credential already stored.
+- WSL uses the Linux file Store. If the Host state root is on a Windows-mounted drive, select a
+  private directory in the WSL Linux filesystem with `path`; the Store keeps its permission check.
 - `service` selects the locker service name. The OS Store's own default applies when it is absent.
 
 ## Storage on each platform

package/packages/hyperframes/README.md

@@ -25,6 +25,13 @@ a Provider can verify and name staged bytes without guessing from the hash. A lo
 render Runtime calls `materializeHyperframesHtml()` with its own Artifact URL resolver before
 handing the HTML to HyperFrames. That environment-specific materialization is not a new compiled
 Record and does not change the compiled document.
+
+For observation of already materialized HTML, `HyperframesHtmlProject` carries the HTML and the
+BlobRefs addressed by its media/font URLs. `hyperframesHtmlDomain` reads the compiler's exact root
+frame clock and canvas; `stageHyperframesHtmlProject` stages those resources. This input does not
+reconstruct a Composition or invent typed Surface facts from HTML. A caller with the original
+`HyperframesDocument`, such as Studio, should pass that document to preserve all declared dependencies,
+including resources embedded in browser-program data. The document remains the complete typed input.
 Staging assigns short local filenames; opaque Resource IDs are never interpreted as filesystem
 paths or filenames, so their length and punctuation do not restrict the host filesystem.
 `stageHyperframesProject` streams each asset into its staged file. Its `validateSurface(surface, path,

package/packages/hyperframes/src/html-project.ts

@@ -0,0 +1,99 @@
+import type { BlobRef } from "@hypit/protocol";
+import { isResourceId } from "@hypit/protocol";
+import type { HyperframesCanvas, HyperframesFrameDomain } from "./types.js";
+
+/** An already materialized HTML programme and the local files its URLs address. */
+export type HyperframesHtmlProject = {
+  readonly html: string;
+  readonly assets: readonly { readonly url: string; readonly artifact: BlobRef }[];
+};
+
+/** Read the exact clock emitted by this package. Seconds never reconstruct frame identity. */
+export function hyperframesHtmlDomain(html: string): HyperframesFrameDomain & { readonly canvas: HyperframesCanvas } {
+  const attributeValue = (tag: string, name: string): string | undefined => {
+    const marker = `${name}="`;
+    for (let at = tag.indexOf(marker); at !== -1; at = tag.indexOf(marker, at + marker.length)) {
+      const previous = tag[at - 1];
+      if (previous === undefined || !" \t\r\n\f".includes(previous)) continue;
+      const start = at + marker.length;
+      const end = tag.indexOf('"', start);
+      return end === -1 ? undefined : tag.slice(start, end);
+    }
+    return undefined;
+  };
+  let root: string | undefined;
+  for (let at = html.indexOf("<div"); at !== -1; at = html.indexOf("<div", at)) {
+    const end = html.indexOf(">", at + 4);
+    if (end === -1) break;
+    const tag = html.slice(at, end + 1);
+    at = end + 1;
+    if (attributeValue(tag, "data-composition-id") === undefined) continue;
+    if (root !== undefined) throw new Error("Snapshot HTML needs exactly one compiled HyperFrames composition root");
+    root = tag;
+  }
+  if (root === undefined) throw new Error("Snapshot HTML needs exactly one compiled HyperFrames composition root");
+  const attribute = (name: string) => {
+    const value = attributeValue(root, name);
+    if (value === undefined) throw new Error(`Snapshot HTML lacks ${name}; use the compiled HyperFrames HTML`);
+    return value;
+  };
+  const positive = (value: string, name: string) => {
+    const number = Number(value);
+    if (!/^\d+$/u.test(value) || !Number.isSafeInteger(number) || number <= 0) throw new Error(`Invalid HyperFrames ${name}`);
+    return number;
+  };
+  const fps = attribute("data-fps").split("/");
+  if (fps.length > 2) throw new Error("HyperFrames data-fps must be an exact rational");
+  return {
+    frameRate: { numerator: positive(fps[0]!, "frame rate"), denominator: positive(fps[1] ?? "1", "frame rate denominator") },
+    frameCount: positive(attribute("data-hypit-frame-count"), "frame count"),
+    canvas: { width: positive(attribute("data-width"), "width"), height: positive(attribute("data-height"), "height") },
+  };
+}
+
+function unescape(value: string): string {
+  return value.replaceAll("&quot;", '"').replaceAll("&#39;", "'").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
+}
+
+/** Resource URL positions in the compiler's self-contained HTML (inline JS and CSS). */
+export function mapHyperframesHtmlUrls(html: string, map: (url: string) => string): string {
+  const escape = (value: string) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;");
+  const cssUrls = (css: string) => css.replace(/url\(\s*(["']?)([^)"']+)\1\s*\)/gu,
+    (_all, _quote: string, url: string) => `url("${map(url.trim()).replaceAll("\\", "\\\\").replaceAll('"', '\\"')}")`);
+  return html.replace(/<style\b([^>]*)>([\s\S]*?)<\/style>/gu,
+    (_all, attributes: string, css: string) => `<style${attributes}>${cssUrls(css)}</style>`)
+    .replace(/<[a-z][^>]*>/gu, tag => {
+      const attributes = /^(?:<(?:img|video|source|image|use|script|link)\b)/u.test(tag)
+        ? tag.replace(/\s(src|poster|href)="([^"]*)"/gu,
+          (_all, key: string, url: string) => ` ${key}="${escape(map(unescape(url)))}"`) : tag;
+      return attributes.replace(/\sstyle="([^"]*)"/gu,
+        (_all, css: string) => ` style="${escape(cssUrls(unescape(css)))}"`);
+    });
+}
+
+export function hyperframesHtmlAssetUrls(html: string): readonly string[] {
+  const urls = new Set<string>();
+  mapHyperframesHtmlUrls(html, url => {
+    if (url !== "" && !url.startsWith("#") && !url.startsWith("data:")) urls.add(url);
+    return url;
+  });
+  return [...urls];
+}
+
+export function assertHyperframesHtmlProject(value: unknown): asserts value is HyperframesHtmlProject {
+  const project = value as HyperframesHtmlProject;
+  if (!project || typeof project.html !== "string" || !Array.isArray(project.assets)) throw new Error("HyperFrames HTML project needs html and assets");
+  hyperframesHtmlDomain(project.html);
+  if (/hypit-resource:\/\//u.test(project.html)) throw new Error("HTML still has unresolved resources; materialize its HyperframesDocument first");
+  const urls = new Set<string>();
+  for (const asset of project.assets) {
+    const blob = asset?.artifact;
+    if (typeof asset?.url !== "string" || urls.has(asset.url) || blob?.kind !== "blob" || !isResourceId(blob.resource)
+      || !Number.isSafeInteger(blob.size) || blob.size < 0 || typeof blob.mediaType !== "string" || !blob.mediaType) {
+      throw new Error("Invalid or repeated HyperFrames HTML asset");
+    }
+    urls.add(asset.url);
+  }
+  const referenced = hyperframesHtmlAssetUrls(project.html);
+  if (referenced.length !== urls.size || referenced.some(url => !urls.has(url))) throw new Error("HyperFrames HTML assets must address its referenced URLs");
+}

package/packages/hyperframes/src/index.ts

@@ -11,3 +11,5 @@ export {
 export type * from "./types.js";
 export { browserProgram, BROWSER_PROGRAM_FORMAT } from "./browser-program.js";
 export type { BrowserProgram } from "./browser-program.js";
+export { assertHyperframesHtmlProject, hyperframesHtmlDomain, hyperframesHtmlAssetUrls, mapHyperframesHtmlUrls } from "./html-project.js";
+export type { HyperframesHtmlProject } from "./html-project.js";

package/packages/hyperframes/src/project.ts

@@ -6,6 +6,8 @@ import type { BlobRef } from "@hypit/protocol";
 
 import { assertHyperframesDocument, materializeHyperframesHtml } from "./document.js";
 import type { HyperframesDocument } from "./types.js";
+import { assertHyperframesHtmlProject, mapHyperframesHtmlUrls } from "./html-project.js";
+import type { HyperframesHtmlProject } from "./html-project.js";
 
 /** Reads one execution resource. Whose store it comes from is the caller's business. */
 export type HyperframesArtifactReader = (
@@ -37,6 +39,32 @@ function extension(mediaType: string): string {
   return found;
 }
 
+/** Stage an existing HTML programme; no reverse compilation or inferred Surface declarations. */
+export async function stageHyperframesHtmlProject(options: {
+  readonly project: HyperframesHtmlProject;
+  readonly directory: string;
+  readonly read: HyperframesArtifactReader;
+  readonly signal?: AbortSignal;
+}): Promise<void> {
+  assertHyperframesHtmlProject(options.project);
+  await mkdir(join(options.directory, "artifacts"), { recursive: true });
+  const paths = new Map<string, string>();
+  for (const [index, asset] of options.project.assets.entries()) {
+    options.signal?.throwIfAborted();
+    const path = `artifacts/asset-${index}${extension(asset.artifact.mediaType)}`;
+    const bytes = await options.read(asset.artifact, options.signal);
+    const file = await open(join(options.directory, path), "w");
+    try {
+      if (bytes instanceof Uint8Array) await file.writeFile(bytes);
+      else for await (const chunk of bytes) { options.signal?.throwIfAborted(); await file.writeFile(chunk); }
+    } finally { await file.close(); }
+    paths.set(asset.url, `./${path}`);
+  }
+  await writeFile(join(options.directory, "index.html"), mapHyperframesHtmlUrls(options.project.html, url => paths.get(url) ?? url), {
+    encoding: "utf8", ...(options.signal === undefined ? {} : { signal: options.signal }),
+  });
+}
+
 /**
  * Lay one document out as a directory HyperFrames can render.
  *

package/packages/pixverse/README.md

@@ -0,0 +1,35 @@
+# `@hypit/pixverse`
+
+Exact author/compute contracts and a package-owned author Surface for PixVerse V6.
+
+The Surface projects the primary result to an ordinary video Artifact. The package contains no
+Provider selection, API key or network execution. The selected Provider implements its exact
+capability.
+
+Connect prompt and frames as ordinary graph edges:
+
+```xml
+<pix:Video
+  id="opening"
+  prompt={line}
+  duration="5"
+  quality="720p"
+  aspect-ratio="9:16"
+  generate-audio="true"
+/>
+
+<pix:Video id="bridge" prompt={motion} duration="5" quality="720p"
+  first-frame={hero.image} last-frame={product.image}/>
+```
+
+The Surface only lowers this syntax into the package's exact model request. It does not select a
+Provider.
+
+The model renders 1 to 15 seconds at `360p`, `540p`, `720p` or `1080p`. A prompt-only run states its
+`aspect-ratio`; a run that starts from a `first-frame` takes that frame's shape instead. A
+`last-frame` bridges from the first frame into one continuous shot, so it is not combined with
+`multi-clip`, which renders the prompt as several cuts.
+
+`generate-audio` renders an audio track alongside the picture, including speech the prompt asks a
+character to say. The model exposes no separate voice, language or dialogue field, so a spoken line
+belongs in the prompt itself.

package/packages/pixverse/package.json

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

@@ -0,0 +1,11 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import {
+  pixverseComponent, pixverseDefinition, pixverseManifest, pixverseModuleRef, pixverseMarkupSurfaces,
+} from "./index.js";
+import { decodePixverseVideoSurface } from "./surface.js";
+export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest: pixverseManifest }], components: [pixverseComponent], hostFacets: [
+  pixverseDefinition.hostFacet,
+  createMarkupSurfaceHostFacet({ module: pixverseModuleRef,
+    declaration: pixverseMarkupSurfaces.find((item) => item.name === "video")!, handler: decodePixverseVideoSurface }),
+] };
+export default hypitPackage;

package/packages/pixverse/src/index.ts

@@ -0,0 +1,122 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type { SurfaceAttributeVocabulary } from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const pixverseModuleRef = { name: "@hypit/pixverse", version: "1" } as const;
+export const pixverseModels = ["pixverse-v6"] as const;
+export type PixverseModel = typeof pixverseModels[number];
+
+const PIXVERSE_QUALITIES = ["360p", "540p", "720p", "1080p"] as const;
+const PIXVERSE_ASPECT_RATIOS = ["16:9", "4:3", "1:1", "3:4", "9:16", "2:3", "3:2", "21:9"] as const;
+
+export const pixverseV6Ports: GenerationPortTable = sealGenerationPortTable({
+  model: "pixverse-v6",
+  result: "video",
+  ports: [
+    { name: "prompt", value: { kind: "text", maxChars: 5_000 }, minItems: 1, maxItems: 1 },
+    { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+    { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+    { name: "duration", value: { kind: "number", integer: true, minimum: 1, maximum: 15 }, minItems: 1, maxItems: 1 },
+    { name: "quality", value: { kind: "enum", values: [...PIXVERSE_QUALITIES] }, minItems: 1, maxItems: 1 },
+    { name: "aspectRatio", value: { kind: "enum", values: [...PIXVERSE_ASPECT_RATIOS] }, minItems: 0, maxItems: 1 },
+    { name: "generateAudio", value: { kind: "boolean" }, minItems: 0, maxItems: 1 },
+    { name: "multiClip", 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 },
+  ],
+  requires: [
+    // A last frame states where a run that already has a first frame ends.
+    { kind: "requiresPresent", port: "lastFrame", needs: ["firstFrame"] },
+    // A run that starts from a frame inherits that frame's shape, and one that
+    // bridges two frames renders a single continuous shot.
+    { kind: "atMostOneOf", ports: ["aspectRatio", "firstFrame"] },
+    { kind: "atMostOneOf", ports: ["multiClip", "lastFrame"] },
+  ],
+});
+
+export const pixversePorts: Readonly<Record<PixverseModel, GenerationPortTable>> = {
+  "pixverse-v6": pixverseV6Ports,
+};
+
+export function sealPixverseRequest(
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+  return sealGenerationPortRequest(pixverseV6Ports, ports);
+}
+
+const pixverseBaseDefinition = defineExactModelModule({
+  module: pixverseModuleRef,
+  endpoints: [{
+    key: "video",
+    requestTypeName: "PixverseV6Request",
+    producerName: "request-pixverse-v6",
+    ports: pixverseV6Ports,
+  }],
+});
+
+export const pixverseEndpoints = pixverseBaseDefinition.endpoints;
+export const pixverseComponent = pixverseBaseDefinition.component;
+const endpoint = pixverseEndpoints.video!;
+
+const pixverseAttributes: readonly SurfaceAttributeVocabulary[] = [
+  { name: "id", kind: "identifier", required: true,
+    summary: "Names this generation so its video Artifact can be referenced elsewhere in the Source." },
+  { name: "prompt", kind: "reference", required: true, accepts: [textTypes.text],
+    summary: "The Text edge describing the shot, including any spoken line the model should voice." },
+  { name: "first-frame", kind: "reference", required: false, accepts: [artifactTypes.blob],
+    summary: "Starts the video from one image Artifact." },
+  { name: "last-frame", kind: "reference", required: false, accepts: [artifactTypes.blob],
+    summary: "Ends the video on one image Artifact, bridging from the first frame." },
+  { name: "duration", kind: "literal", required: true,
+    summary: "How many seconds of video to render, from 1 to 15." },
+  { name: "quality", kind: "literal", required: true, values: [...PIXVERSE_QUALITIES],
+    summary: "The size band the model renders at." },
+  { name: "aspect-ratio", kind: "literal", required: false, values: [...PIXVERSE_ASPECT_RATIOS],
+    summary: "The Frame shape of the generated video." },
+  { name: "generate-audio", kind: "literal", required: false, values: ["true", "false"],
+    summary: "Renders an audio track alongside the picture." },
+  { name: "multi-clip", kind: "literal", required: false, values: ["true", "false"],
+    summary: "Renders the prompt as several cuts instead of one continuous shot." },
+  { name: "seed", kind: "literal", required: false,
+    summary: "Seeds the model's sampling so a rerun stays close to this one." },
+];
+
+export const pixverseMarkupSurfaces = [{
+  name: "video",
+  tag: "Video",
+  mode: "structured" as const,
+  outputs: [endpoint.draftType, endpoint.mediaBindings.firstFrame!.type, endpoint.mediaBindings.lastFrame!.type],
+  vocabulary: {
+      summary: "Generates one video with the exact PixVerse V6 model from a Text prompt, optionally starting from a frame or bridging two.",
+    attributes: pixverseAttributes,
+    ports: [{
+      name: "video",
+      type: artifactTypes.blob,
+      summary: "The generated video, addressed as `<id>.video`.",
+    }],
+    example: `<pix:Video
+  id="opening"
+  prompt={line}
+  duration="5"
+  quality="720p"
+  aspect-ratio="9:16"
+  generate-audio="true"
+/>`,
+    notes: [
+      "A run that starts from a frame takes its shape from that frame, so `aspect-ratio` states the shape only for a prompt-only run.",
+      "A `last-frame` bridges from the `first-frame` into one continuous shot, so it is not combined with `multi-clip`.",
+      "A spoken line belongs in the prompt; the model exposes no separate voice, language or dialogue field.",
+      "The Surface lowers the element into the package's exact model request and selects no Provider.",
+    ],
+  },
+}] as const;
+
+export const pixverseManifest = {
+  ...pixverseBaseDefinition.manifest,
+};
+export const pixverseDefinition = {
+  ...pixverseBaseDefinition,
+  manifest: pixverseManifest,
+};

package/packages/pixverse/src/surface.ts

@@ -0,0 +1,146 @@
+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 { pixverseEndpoints } from "./index.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+  return left.name === right.name && left.module.name === right.module.name && left.module.version === right.module.version;
+}
+
+const attributes = ["id", "prompt", "first-frame", "last-frame", "duration", "quality",
+  "aspect-ratio", "generate-audio", "multi-clip", "seed"] as const;
+
+function exact(element: StructuredElement): void {
+  const unknown = Object.keys(element.attributes).filter((name) => !attributes.includes(name as typeof attributes[number]));
+  assert(unknown.length === 0, `${element.name} does not accept ${unknown[0]}`);
+  const missing = ["id", "prompt", "duration", "quality"].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 integer(element: StructuredElement, name: string): readonly GenerationPortValue[] {
+  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;
+}
+
+function frame(
+  element: StructuredElement,
+  name: string,
+  resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference | undefined {
+  if (element.attributes[name] === undefined) return undefined;
+  const image = ref(element, name, artifactTypes.blob, resolve);
+  if (image.record !== undefined) {
+    assert(image.record.value.kind === "blob" && image.record.value.mediaType.startsWith("image/"),
+      `${element.name}.${name} must reference image media`);
+  }
+  return image;
+}
+
+function decoder(endpoint: ExactModelEndpoint): StructuredSurfaceHandler {
+  return ({ element, resolveReference }) => {
+    exact(element);
+    assert(!element.children.some((item) => item.kind === "element" || item.value.trim()),
+      `${element.name} accepts no children`);
+    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 frames = ([["firstFrame", "first-frame"], ["lastFrame", "last-frame"]] as const)
+      .flatMap(([port, attribute]) => {
+        const image = frame(element, attribute, resolveReference);
+        return image === undefined ? [] : [{ port, image }];
+      });
+    const stated: Record<string, readonly GenerationPortValue[] | undefined> = {
+      duration: integer(element, "duration"),
+      quality: [text(element, "quality")],
+      aspectRatio: optionalText(element, "aspect-ratio"),
+      generateAudio: optionalFlag(element, "generate-audio"),
+      multiClip: optionalFlag(element, "multi-clip"),
+      seed: element.attributes["seed"] === undefined ? undefined : integer(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 = frames.map(({ port, image }, index) => {
+      const name = `media-${String(index + 1).padStart(4, "0")}`;
+      const bindingId = `${id}.${name}.binding`;
+      const mediaPort = generationPort(endpoint.ports, port);
+      assert(mediaPort.value.kind === "media", `PixVerse port ${port} is not media`);
+      records.push({
+        id: bindingId, type: endpoint.mediaBindings[port]!.type,
+        value: { kind: "inline", value: sealGenerationMediaBinding(mediaPort 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 } 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 decodePixverseVideoSurface = decoder(pixverseEndpoints.video!);

package/packages/provider-hiapi/README.md

@@ -37,7 +37,7 @@ Service limits this Provider reports as unsupported before submitting:
   `1:3`, `9:21`; 4K excludes `1:1`, `3:1`, `1:3`, `9:21`; image-to-image takes up to six references.
 - Grok Imagine renders 480p or 720p; `grok-imagine-1.5/image-to-video` animates exactly one image.
 
-Seedance visual references may carry `person-reference`; the Provider accepts the declaration and
+Seedance visual references require `person-reference`; the Provider accepts the declaration and
 transmits nothing for it, since HiAPI has no field for it. Seedance rejects reference images and
 videos that contain a real human face; HiAPI offers no way to register authorized portrait material,
 so such a request fails with the service's moderation error.