@hypit/hypit 0.2.5 → 0.2.7

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>
@@ -144,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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:*",
@@ -279,6 +280,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/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-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/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/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/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,
+};