@hypit/hypit 0.2.5 → 0.2.7

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

@@ -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-hyperframes-local/README.md

@@ -1,12 +1,22 @@
 # @hypit/provider-hyperframes-local
 
-Trusted local Provider for the `@hypit/render-hyperframes#render-visual` capability. It stages the
+Trusted local Provider for `@hypit/render-hyperframes@1#render-visual` and `#render-frames`. It stages the
 Resource dependencies declared by a `HyperframesDocument`, renders a silent MP4 with the
 HyperFrames engine, probes the bytes, and returns a verified `RenderedVisual`. Before capturing a typed
 Surface it decodes the exact bytes and checks declared dimensions, still/frame timing, SDR/sRGB and
 opaque/straight-alpha facts. These checks validate the typed rendering input; they do not create
 content identity or hidden output metadata.
 
+`render-frames` uses the same staging, source-frame mapping, readiness and opaque PNG capture as
+video export, returning the PNGs before encoding. It accepts a compiled document or a materialized
+HTML project. For selected frames it merges only their required source-frame windows; continuous
+windows decode sequentially. A complete batch shares one staged project and browser lifetime.
+The existing browser selection, explicit preparation, worker settings and cancellation apply.
+`maxRenderedBytes` bounds the total returned PNG bytes, or the encoded MP4 for a video request.
+`render-frames` has its own capability binding; it does not inherit a `render-visual` binding.
+For immediate CLI invocation, the host calls the handler directly: Build admission reservations do
+not coordinate separate CLI processes. Worker limits still bound browsers inside each invocation.
+
 Normalized transparent videos displayed by Media or project components use the ordinary video path.
 The engine decodes them to PNG frames with alpha, then Chrome blends them with lower layers and
 the authored Canvas background. Final frames use fast PNG encoding after Chrome has composited
@@ -73,8 +83,7 @@ an opaque session and chooses PNG separately at capture. It does not patch engin
 The Runtime Adapter declares one managed browser program. Prepare it explicitly:
 
 ```sh
-hypit programs up --runtime ./hypit.runtime.json --endpoint hyperframes.local
-hypit doctor --runtime ./hypit.runtime.json
+hypit programs prepare --runtime ./hypit.runtime.json --endpoint hyperframes.local
 ```
 
 Use the instance name from the Profile. `runtime up` also prepares it and starts the Runtime Worker.
@@ -110,17 +119,20 @@ receipt is stored. To install into an empty location, explicitly choose `browser
 
 `config.chromePath` selects a user-managed Chrome/Chromium executable. It cannot be combined with
 `browserVersion` or `browserDownloadBaseUrl`; invalid combinations fail instead of assigning precedence. Relative paths resolve
-from the Runtime Profile root. This mode never downloads or repairs a browser. Its version remains
+from the Runtime data root, as does `browserCacheDirectory`. The Profile's `dataRoot` itself resolves
+relative to the Profile file. This mode never downloads or repairs a browser. Its version remains
 under the user's control, including system-browser auto-updates. `HYPERFRAMES_BROWSER_PATH` and
 `PRODUCER_HEADLESS_SHELL_PATH` do not select browsers in this Provider; configure `chromePath`.
 On platforms without a supported managed download, explicitly select an installed browser.
 
 `doctor` displays the selected path and its source, and only inspects it. Build preflight, rendering
-and previews never install a browser. `programs up` / `runtime up` display the selected managed
+and previews never install a browser. `programs prepare`, `programs up` and `runtime up` display the selected managed
 version, installation location and download URL before running preparation. The probe runs `--version` and checks
 FFmpeg/FFprobe; it does not promise GPU or page compatibility. Capture receives that same selected
-path as the engine's `chromePath`, including its GPU probe. Active Workers keep their loaded package
-recommendation; restart them explicitly after changing Profile or package dependencies.
+path as the engine's `chromePath`, including its GPU probe. New Builds read current Endpoint
+configuration and project implementation; active Builds keep their selected configuration. A
+Distribution update or change to the Worker's inherited environment requires an explicit Worker
+restart when active work permits. Ordinary Profile edits do not require restarting every process.
 
 The Provider's `hypit.dependencyInstallEnv` disables Puppeteer's browser download while preparing its
 engine/producer npm dependencies. The repository `.puppeteerrc.cjs` does the same for checkout installs.

package/packages/provider-hyperframes-local/src/capture.ts

@@ -11,7 +11,8 @@ import { CaptureConcurrency } from "./concurrency.js";
 import { createOpaqueFrameCapture } from "./opaque-capture.js";
 
 export type CaptureInput = {
-  readonly document: HyperframesDocument;
+  readonly document: Pick<HyperframesDocument, "frameRate" | "frameCount" | "canvas">;
+  readonly frames?: readonly number[];
   readonly range: MediaFrameRange;
   readonly config: ReturnType<typeof resolveExecutionOptions> & { readonly chromePath: string };
   readonly directory: string;
@@ -24,14 +25,16 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
   onProgress: (event: HyperframesRenderProgress) => void): Promise<string> {
   const { document, range, config, directory: work } = input;
   const signal = controller.signal;
-  const frameCount = range.endFrameExclusive - range.startFrame;
+  const frameCount = input.frames?.length ?? range.endFrameExclusive - range.startFrame;
+  const selected = input.frames === undefined ? undefined : new Set(input.frames);
+  const at = (index: number) => input.frames?.[index] ?? range.startFrame + index;
   const fps = { num: document.frameRate.numerator, den: document.frameRate.denominator };
   const limit = renderWorkerLimit(config, frameCount, fps.num / fps.den);
   const concurrency = new CaptureConcurrency(limit, config.workers === "auto");
   // Short contiguous batches retain sequential capture while allowing free browsers
   // to help with expensive passages. This queue exists only inside this render.
   const batchCount = Math.max(limit, Math.ceil(frameCount / Math.max(1, Math.round(fps.num / fps.den))));
-  const batches = distributeFrameRange(range, batchCount);
+  const batches = distributeFrameRange({ startFrame: 0, endFrameExclusive: frameCount }, batchCount);
   let nextBatch = 0;
   const started = performance.now();
   const elapsedMs = () => Math.round(performance.now() - started);
@@ -81,7 +84,8 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
     const sources = new Map<string, { frames: Map<number, string>; width: number; height: number }>();
     let sourceFrames = 0;
     // One source at a time bounds decoder pressure independently of browser concurrency.
-    const windows = sourceWindows(slots, range);
+    const windows = sourceWindows(slots, input.frames === undefined ? [range]
+      : input.frames.map(frame => ({ startFrame: frame, endFrameExclusive: frame + 1 })));
     const sourceTotal = windows.reduce((sum, source) => sum + source.windows.reduce((count, window) =>
       count + window.endFrameExclusive - window.startFrame, 0), 0);
     if (sourceTotal > 0) onProgress({ phase: "decoding", completed: 0, total: sourceTotal, elapsedMs: elapsedMs() });
@@ -119,7 +123,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
           const frameIndex = sourceFrameAt(slot, frame);
           const framePath = sources.get(slot.src)?.frames.get(frameIndex);
           // Browser initialization may seek outside the requested interval.
-          if (frame < range.startFrame || frame >= range.endFrameExclusive) continue;
+          if (selected === undefined ? frame < range.startFrame || frame >= range.endFrameExclusive : !selected.has(frame)) continue;
           assert(framePath !== undefined, `HyperFrames has no decoded frame ${frameIndex} for ${slot.id}`);
           payloads.set(slot.id, { framePath, frameIndex });
         }
@@ -132,7 +136,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
     await mkdir(outputFrames);
     onProgress?.({ phase: "prepared", workers: concurrency.target, sourceFrames, elapsedMs: elapsedMs() });
     const jobs: Promise<void>[] = [];
-    let active = 0, open = 0, initializing = 0, capturedFrames = 0;
+    let active = 0, open = 0, initializing = 0, capturedFrames = 0, capturedBytes = 0;
     let startupMs = 0;
     const launch = (): void => {
       const worker = jobs.length;
@@ -187,13 +191,18 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
           if (active > concurrency.target) break;
           const batch = batches[nextBatch++];
           if (batch === undefined) break;
-          for (let frame = batch.startFrame; frame < batch.endFrameExclusive; frame++) {
+          for (let index = batch.startFrame; index < batch.endFrameExclusive; index++) {
+            const frame = at(index);
             signal.throwIfAborted();
             const captured = await stage(`worker ${worker} frame ${frame}`, config.frameTimeoutMs, () => captureFrame(frame));
+            if (input.frames !== undefined) {
+              capturedBytes += captured.buffer.byteLength;
+              assert(capturedBytes <= config.maxRenderedBytes, "HyperFrames PNG output exceeds its byte limit");
+            }
             timing.seekMs += captured.seekMs;
             timing.prepareMs += captured.prepareMs;
             timing.screenshotMs += captured.screenshotMs;
-            await writeFile(join(outputFrames, `${String(frame - range.startFrame).padStart(9, "0")}.png`), captured.buffer);
+            await writeFile(join(outputFrames, `${String(index).padStart(9, "0")}.png`), captured.buffer);
             completed++;
             capturedFrames++;
             if (performance.now() - lastProgressAt >= 1_000) {
@@ -239,6 +248,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
     if (failure !== undefined) throw failure;
     signal.throwIfAborted();
     await Promise.all(closing.values());
+    if (input.frames !== undefined) return outputFrames;
     const output = join(work, "visual.mp4");
     onProgress({ phase: "encoding", elapsedMs: elapsedMs() });
     const crf = { draft: 28, standard: 23, high: 18 }[config.quality];

package/packages/provider-hyperframes-local/src/index.ts

@@ -6,5 +6,5 @@ export type {
   HyperframesWorkers,
 } from "./provider.js";
 
-export { renderHyperframesVisual } from "./render.js";
+export { renderHyperframesVisual, renderHyperframesFrames } from "./render.js";
 export type { RenderHyperframesVisualOptions, HyperframesRenderProgress } from "./render.js";

package/packages/provider-hyperframes-local/src/output.ts

@@ -38,7 +38,7 @@ function outputFrameCount(stream: ProbeStream): number {
 
 export async function verifyOutput(args: {
   readonly path: string;
-  readonly document: HyperframesDocument;
+  readonly document: Pick<HyperframesDocument, "frameRate" | "frameCount" | "canvas">;
   readonly ffprobePath: string;
   readonly timeoutMs: number;
   readonly maxOutputBytes: number;

package/packages/provider-hyperframes-local/src/process-tree.ts

@@ -33,7 +33,10 @@ export async function killRenderTree(pid: number): Promise<void> {
   for (const child of descendants.reverse()) {
     for (const target of [-child, child]) {
       try { process.kill(target, "SIGKILL"); }
-      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+      catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== "ESRCH" && !(target < 0 && code === "EPERM")) throw error;
+      }
     }
   }
   const deadline = Date.now() + cleanupMs;
@@ -76,7 +79,10 @@ export function killRenderDescendantsSync(pid: number): void {
   for (const child of descendants.slice(1).reverse()) {
     for (const target of [-child, child]) {
       try { process.kill(target, "SIGKILL"); }
-      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+      catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== "ESRCH" && !(target < 0 && code === "EPERM")) throw error;
+      }
     }
   }
 }

package/packages/provider-hyperframes-local/src/provider.ts

@@ -1,8 +1,8 @@
 import { defineEndpointPackage } from "@hypit/endpoint-kit";
 import { mediaTypes } from "@hypit/media";
-import { renderHyperframesCapabilities, verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
+import { renderHyperframesCapabilities, renderHyperframesTypes, verifyHyperframesFramesRequest, hyperframesFramesDomain, verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
 import { canonicalize } from "@hypit/protocol";
-import { renderHyperframesVisual, resolveExecutionOptions, renderWorkerLimit } from "./render.js";
+import { renderHyperframesVisual, renderHyperframesFrames, resolveExecutionOptions, renderWorkerLimit } from "./render.js";
 import type { HyperframesExecutionOptions } from "./options.js";
 import { renderProgressReporter } from "./progress.js";
 
@@ -67,6 +67,33 @@ export function createLocalHyperframesProvider(config: CreateLocalHyperframesPro
           await progress.flush();
         }
       },
+    }, {
+      lifecycle: "immediate" as const,
+      capability: renderHyperframesCapabilities.renderFrames,
+      returns: renderHyperframesTypes.frames,
+      ...(config.browserCapacity === undefined ? {} : {
+        resources: [{ id: browsers, limit: config.browserCapacity }],
+        unitsForRequest: (request: import("@hypit/endpoint-kit").EndpointRequest) => {
+          verifyHyperframesFramesRequest(request.constraints);
+          const document = hyperframesFramesDomain(request.constraints);
+          return { [browsers]: renderWorkerLimit(reserved, request.constraints.frames.length,
+            document.frameRate.numerator / document.frameRate.denominator) };
+        },
+      }),
+      handler: async context => {
+        const request = context.need.constraints;
+        verifyHyperframesFramesRequest(request);
+        const progress = renderProgressReporter(context.reportProgress, request.frames.length);
+        try {
+          const frames = await renderHyperframesFrames(request, { ...config,
+            ...(execution.chromePath === undefined ? { browserVersion: execution.browserVersion! } : { chromePath: execution.chromePath }),
+            browserCacheDirectory: execution.browserCacheDirectory,
+            workers: execution.workers, maxWorkers,
+            resources: context.resources, onProgress: progress.onProgress,
+            ...(context.reportDiagnostic === undefined ? {} : { onDiagnostic: context.reportDiagnostic }) });
+          return { value: { kind: "inline", value: canonicalize(frames) } };
+        } finally { await progress.flush(); }
+      },
     }],
   });
 }

package/packages/provider-hyperframes-local/src/render.ts

@@ -3,12 +3,12 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { EndpointInvocationContext } from "@hypit/endpoint-kit";
-import { stageHyperframesProject } from "@hypit/hyperframes/project";
+import { stageHyperframesProject, stageHyperframesHtmlProject } from "@hypit/hyperframes/project";
 import { sealRenderedVisual } from "@hypit/media";
 import type { MediaFrameRange, RenderedVisual } from "@hypit/media";
 import { verifyCompositableSurfaceFile } from "@hypit/media-execution";
-import { verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
-import type { HyperframesVisualRequest } from "@hypit/render-hyperframes";
+import { verifyHyperframesVisualRequest, verifyHyperframesFramesRequest, hyperframesFramesDomain } from "@hypit/render-hyperframes";
+import type { HyperframesVisualRequest, HyperframesFramesRequest, HyperframesFrames } from "@hypit/render-hyperframes";
 import { isStreamingResourceStore } from "@hypit/runtime";
 import type { HyperframesExecutionOptions } from "./options.js";
 import { assert, positiveInteger } from "./process.js";
@@ -75,10 +75,22 @@ export async function renderHyperframesVisual(
   options: RenderHyperframesVisualOptions,
 ): Promise<RenderedVisual> {
   verifyHyperframesVisualRequest(request);
+  return capture(request, options) as Promise<RenderedVisual>;
+}
+
+export async function renderHyperframesFrames(request: HyperframesFramesRequest, options: RenderHyperframesVisualOptions): Promise<HyperframesFrames> {
+  verifyHyperframesFramesRequest(request);
+  return capture(request, options) as Promise<HyperframesFrames>;
+}
+
+async function capture(request: HyperframesVisualRequest | HyperframesFramesRequest, options: RenderHyperframesVisualOptions): Promise<RenderedVisual | HyperframesFrames> {
   const config = { ...resolveExecutionOptions(options), chromePath: browserExecutablePath(options) };
-  const { document } = request;
-  const range = request.range ?? { startFrame: 0, endFrameExclusive: document.frameCount };
-  const frameCount = range.endFrameExclusive - range.startFrame;
+  const frames = "frames" in request ? request.frames : undefined;
+  const document = "frames" in request ? hyperframesFramesDomain(request) : request.document;
+  const range = frames === undefined
+    ? (request as HyperframesVisualRequest).range ?? { startFrame: 0, endFrameExclusive: document.frameCount }
+    : { startFrame: frames[0]!, endFrameExclusive: frames.at(-1)! + 1 };
+  const frameCount = frames?.length ?? range.endFrameExclusive - range.startFrame;
   const controller = new AbortController();
   const signal = options.signal === undefined ? controller.signal : AbortSignal.any([controller.signal, options.signal]);
   const started = performance.now();
@@ -103,23 +115,25 @@ export async function renderHyperframesVisual(
     signal.throwIfAborted();
     await requireBrowserExecutable(config.chromePath, config.browserVersion);
     await options.onDiagnostic?.({ level: "info", message:
-      `Render ${frameCount} frames; workers ${config.workers} (limit ${renderWorkerLimit(config, frameCount, document.frameRate.numerator / document.frameRate.denominator)}); opaque fast PNG; quality ${config.quality}; GPU ${config.browserGpu}; browser ${config.chromePath}; encoder ${config.ffmpegPath}` });
+      `Capture ${frameCount} frames; workers ${config.workers} (limit ${renderWorkerLimit(config, frameCount, document.frameRate.numerator / document.frameRate.denominator)}); opaque fast PNG; GPU ${config.browserGpu}; browser ${config.chromePath}`
+      + (frames === undefined ? `; quality ${config.quality}; encoder ${config.ffmpegPath}` : "; PNG output") });
     options.onProgress?.({ phase: "staging", elapsedMs: 0 });
     work = await mkdtemp(join(tmpdir(), "hypit-hyperframes-local-"));
-    await stageHyperframesProject({ document, directory: work, signal,
-      read: async (artifact, readSignal) => {
+    const read: import("@hypit/hyperframes/project").HyperframesArtifactReader = async (artifact, readSignal) => {
         const io = { signal: readSignal! };
         const bytes = isStreamingResourceStore(options.resources)
           ? await options.resources.open(artifact.resource, io) : await options.resources.get(artifact.resource, io);
         assert(bytes !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
         return bytes;
-      },
+      };
+    if ("project" in request) await stageHyperframesHtmlProject({ project: request.project, directory: work, signal, read });
+    else await stageHyperframesProject({ document: request.document, directory: work, signal, read,
       validateSurface: (surface, path, probeSignal) => verifyCompositableSurfaceFile({ surface, path,
         ffprobePath: config.ffprobePath, processTimeoutMs: config.processTimeoutMs,
         maxProbeOutputBytes: config.maxProcessOutputBytes, signal: probeSignal! }),
     });
     changePhase("decoding source frames");
-    await runCaptureProcess({ document, range, config, directory: work,
+    await runCaptureProcess({ document, range, ...(frames === undefined ? {} : { frames }), config, directory: work,
       engineModule: import.meta.resolve("@hyperframes/engine"),
       producerModule: import.meta.resolve("@hyperframes/producer"),
     }, signal, (event) => {
@@ -132,22 +146,33 @@ export async function renderHyperframesVisual(
     signal.throwIfAborted();
     changePhase("storing output");
     options.onProgress?.({ phase: "storing", elapsedMs: Math.round(performance.now() - started) });
-    const output = join(work, "visual.mp4");
-    let artifact;
-    if (isStreamingResourceStore(options.resources)) {
-      const stream = createReadStream(output, { signal });
-      const closed = finished(stream).catch(() => {});
-      try { artifact = await options.resources.putStream(stream, "video/mp4", { signal }); }
-      finally { stream.destroy(); await closed; }
+    const store = async (output: string, mediaType: string) => {
+      if (isStreamingResourceStore(options.resources)) {
+        const stream = createReadStream(output, { signal });
+        const closed = finished(stream).catch(() => {});
+        try { return await options.resources.putStream(stream, mediaType, { signal }); }
+        finally { stream.destroy(); await closed; }
+      }
+      return options.resources.put(await readFile(output, { signal }), mediaType, { signal });
+    };
+    let result: RenderedVisual | HyperframesFrames;
+    if (frames === undefined) {
+      result = sealRenderedVisual({ frameRate: document.frameRate, frameCount, canvas: document.canvas,
+        artifact: await store(join(work, "visual.mp4"), "video/mp4") });
     } else {
-      artifact = await options.resources.put(await readFile(output, { signal }), "video/mp4", { signal });
+      const artifacts = [];
+      for (let index = 0; index < frames.length; index++) {
+        signal.throwIfAborted();
+        artifacts.push(await store(join(work, "frames", `${String(index).padStart(9, "0")}.png`), "image/png"));
+      }
+      result = artifacts;
     }
     signal.throwIfAborted();
 
     changePhase("complete");
     await Promise.all(diagnostics);
     options.onProgress?.({ phase: "complete", frames: frameCount, elapsedMs: Math.round(performance.now() - started) });
-    return sealRenderedVisual({ frameRate: document.frameRate, frameCount, canvas: document.canvas, artifact });
+    return result;
   } catch (error) {
     if (signal.aborted) throw signal.reason;
     controller.abort(error);

package/packages/provider-hyperframes-local/src/sampling.ts

@@ -51,9 +51,10 @@ export function sourceFrameAt(slot: VideoSlot, frame: number): number {
   return value;
 }
 
-export function sourceWindows(slots: readonly VideoSlot[], range: MediaFrameRange) {
+export function sourceWindows(slots: readonly VideoSlot[], selection: MediaFrameRange | readonly MediaFrameRange[]) {
+  const ranges: readonly MediaFrameRange[] = Array.isArray(selection) ? selection : [selection as MediaFrameRange];
   const sources = new Map<string, { fps: VideoSlot["sourceFps"]; windows: MediaFrameRange[] }>();
-  for (const slot of slots) {
+  for (const range of ranges) for (const slot of slots) {
     const first = Math.max(range.startFrame, slot.startFrame);
     const last = Math.min(range.endFrameExclusive, slot.endFrameExclusive) - 1;
     if (last < first) continue;

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": {}
 }
 ```