@hypit/hypit 0.1.12 → 0.1.14

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

@@ -1,4 +1,7 @@
 import { spawn } from "node:child_process";
+import { access, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { delimiter, isAbsolute, resolve } from "node:path";
 
 type ProcessResult = {
   readonly stdout: Uint8Array;
@@ -13,6 +16,25 @@ export function positiveInteger(value: number, subject: string): number {
   return value;
 }
 
+/** The engine's binary override requires a path; resolve our selected command without its fallback search. */
+export async function mediaExecutablePath(value: string): Promise<string> {
+  const pathLike = isAbsolute(value) || value.includes("/") || value.includes("\\");
+  const bases = pathLike ? [resolve(value)]
+    : (process.env.PATH ?? "").split(delimiter).filter(Boolean).map(directory => resolve(directory, value));
+  const extensions = process.platform === "win32" && !/\.[^\\/]+$/u.test(value) ? [".exe", ".com", ""] : [""];
+  for (const base of bases) for (const extension of extensions) {
+    const candidate = `${base}${extension}`;
+    try {
+      if (!(await stat(candidate)).isFile()) continue;
+      await access(candidate, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+      return candidate;
+    } catch (error) {
+      if (!["ENOENT", "ENOTDIR", "EACCES"].includes((error as NodeJS.ErrnoException).code ?? "")) throw error;
+    }
+  }
+  throw new Error(`HyperFrames media executable ${value} is unavailable; correct the Provider's ffmpegPath or ffprobePath.`);
+}
+
 function processEnvironment(): NodeJS.ProcessEnv {
   const names = ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL"] as const;
   return Object.fromEntries(names.flatMap((name) => process.env[name] === undefined

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

@@ -1,54 +1,46 @@
-import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 
 import { probeMediaToolchain } from "@hypit/media-execution";
 import type { ManagedProgram, ManagedProgramState } from "@hypit/runtime-kit";
-
-function run(executable: string, args: readonly string[]): Promise<{ ok: boolean; output: string }> {
-  return new Promise((resolve) => {
-    execFile(executable, [...args], { timeout: 15_000, shell: false, windowsHide: true }, (error, stdout, stderr) => {
-      resolve(error === null
-        ? { ok: true, output: stdout.trim() }
-        : { ok: false, output: (stderr.trim() || error.message).split("\n").at(-1) ?? "" });
-    });
-  });
-}
+import { browserCacheDirectory, browserDownloadBaseUrl, browserDownloadUrl, browserExecutablePath, configuredBrowserPath, requireBrowserExecutable, selectedBrowserVersion } from "./browser.js";
+import type { BrowserOptions } from "./browser.js";
 
 /**
- * HyperFrames owns the browser cache behind its CLI. It is deployment state,
- * not an author dependency, so the Endpoint lifecycle prepares it only
- * when this Provider is selected.
+ * This Provider owns browser selection and preparation. Probes never install;
+ * rendering receives the same selected executable instead of invoking engine discovery.
  */
 export function localHyperframesBrowserProgram(
-  input: {
+  input: BrowserOptions & {
     readonly id: string;
     readonly nodePath: string;
-    readonly hyperframesCliPath: string | (() => string);
     readonly ffprobePath: string;
     readonly ffmpegPath?: string;
   },
 ): ManagedProgram {
-  const cliPath = () => typeof input.hyperframesCliPath === "string" ? input.hyperframesCliPath : input.hyperframesCliPath();
+  const version = selectedBrowserVersion(input);
+  const selectedPath = browserExecutablePath(input);
+  const baseUrl = browserDownloadBaseUrl(input);
   const probeBrowser = async (): Promise<ManagedProgramState> => {
-    let executable: string;
-    try { executable = cliPath(); } catch (error) { return { state: "down", detail: error instanceof Error ? error.message : String(error) }; }
-    const located = await run(input.nodePath, [executable, "browser", "path"]);
-    if (!located.ok) return { state: "down", detail: `HyperFrames browser is unavailable: ${located.output}` };
-    const path = located.output.trim();
-    if (path.length === 0 || path.includes("\n") || path.includes("\r")) {
-      return { state: "mismatch", detail: "HyperFrames returned an invalid browser path" };
-    }
-    const version = await run(path, ["--version"]);
-    if (!version.ok || version.output.length === 0) {
-      return { state: "mismatch", detail: `HyperFrames browser cannot start: ${version.output}` };
-    }
+    try { await requireBrowserExecutable(selectedPath, version); }
+    catch (error) { return { state: "down", detail: error instanceof Error ? error.message : String(error) }; }
     return { state: "ready" };
   };
   return {
     id: input.id,
-    installation: {
-      probe: probeBrowser,
-      get commands() { return [{ command: input.nodePath, args: [cliPath(), "browser", "ensure"] }]; },
-    },
+    ...(configuredBrowserPath(input) === undefined ? {
+      // Projects sharing this installation also share the existing Program lifecycle lock/logs.
+      stateRoot: join(browserCacheDirectory(input), ".hypit-render-program"),
+      installation: {
+        probe: probeBrowser,
+        commands: [{ label: `Install Chrome Headless Shell ${version} at ${selectedPath} from ${browserDownloadUrl(input)}`, command: input.nodePath, args: [
+          "--import", import.meta.resolve("tsx"),
+          "--import", new URL("./capture-bootstrap.ts", import.meta.url).href,
+          fileURLToPath(new URL("./browser-install.ts", import.meta.url)), browserCacheDirectory(input), version!,
+          ...(baseUrl === undefined ? [] : [baseUrl]),
+        ] }],
+      },
+    } : {}),
     async probe(): Promise<ManagedProgramState> {
       const browser = await probeBrowser();
       if (browser.state !== "ready") return browser;

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

@@ -2,7 +2,6 @@ import { defineEndpointPackage } from "@hypit/endpoint-kit";
 import { mediaTypes } from "@hypit/media";
 import { renderHyperframesCapabilities, verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
 import { canonicalize } from "@hypit/protocol";
-import { resolveNodePackageExecutable } from "@hypit/package-loader-node";
 import { renderHyperframesVisual, resolveExecutionOptions, renderWorkerLimit } from "./render.js";
 import type { HyperframesExecutionOptions } from "./options.js";
 import { renderProgressReporter } from "./progress.js";
@@ -14,17 +13,12 @@ export type CreateLocalHyperframesProviderOptions = HyperframesExecutionOptions
   readonly pool?: string;
   /** Used by managed browser installation, not frame capture. */
   readonly nodePath?: string;
-  readonly hyperframesCliPath?: string;
   /** Whole render requests admitted concurrently; independent of frame workers. */
   readonly defaultConcurrency?: number;
   /** Shared Chrome slots across Need executions using this pool. */
   readonly browserCapacity?: number;
 };
 
-export function defaultHyperframesCliPath(): string {
-  return resolveNodePackageExecutable("hyperframes", "hyperframes", { from: import.meta.url });
-}
-
 export function createLocalHyperframesProvider(config: CreateLocalHyperframesProviderOptions) {
   const execution = resolveExecutionOptions(config);
   const pool = config.pool ?? config.instance ?? "hyperframes.local";
@@ -62,7 +56,10 @@ export function createLocalHyperframesProvider(config: CreateLocalHyperframesPro
           : request.range.endFrameExclusive - request.range.startFrame;
         const progress = renderProgressReporter(context.reportProgress, frameCount);
         try {
-          const visual = await renderHyperframesVisual(request, { ...config, workers: execution.workers, maxWorkers,
+          const visual = await renderHyperframesVisual(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(visual) } };

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

@@ -6,7 +6,7 @@ import type { EndpointInvocationContext } from "@hypit/endpoint-kit";
 import { stageHyperframesProject } from "@hypit/hyperframes/project";
 import { sealRenderedVisual } from "@hypit/media";
 import type { MediaFrameRange, RenderedVisual } from "@hypit/media";
-import { verifyCompositableSurfaceBytes } from "@hypit/media-execution";
+import { verifyCompositableSurfaceFile } from "@hypit/media-execution";
 import { verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
 import type { HyperframesVisualRequest } from "@hypit/render-hyperframes";
 import { isStreamingResourceStore } from "@hypit/runtime";
@@ -15,6 +15,7 @@ import { assert, positiveInteger } from "./process.js";
 import { runCaptureProcess } from "./capture-process.js";
 import { finished } from "node:stream/promises";
 import { autoWorkerLimit } from "./concurrency.js";
+import { browserCacheDirectory, browserExecutablePath, configuredBrowserPath, requireBrowserExecutable, selectedBrowserVersion } from "./browser.js";
 
 export type HyperframesRenderProgress =
   | { readonly phase: "staging" | "encoding" | "storing"; readonly elapsedMs: number }
@@ -43,6 +44,9 @@ export function resolveExecutionOptions(options: HyperframesExecutionOptions) {
   const browserGpu = options.browserGpu ?? "hardware";
   assert(["auto", "software", "hardware"].includes(browserGpu), "HyperFrames browserGpu is invalid");
   return {
+    chromePath: configuredBrowserPath(options),
+    browserVersion: selectedBrowserVersion(options),
+    browserCacheDirectory: browserCacheDirectory(options),
     workers,
     maxWorkers: workers === "auto" ? positiveInteger(options.maxWorkers ?? autoWorkerLimit(), "maxWorkers") : workers,
     quality, browserGpu,
@@ -71,7 +75,7 @@ export async function renderHyperframesVisual(
   options: RenderHyperframesVisualOptions,
 ): Promise<RenderedVisual> {
   verifyHyperframesVisualRequest(request);
-  const config = resolveExecutionOptions(options);
+  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;
@@ -97,8 +101,9 @@ export async function renderHyperframesVisual(
   };
   try {
     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}; encoder ${config.ffmpegPath}` });
+      `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}` });
     options.onProgress?.({ phase: "staging", elapsedMs: 0 });
     work = await mkdtemp(join(tmpdir(), "hypit-hyperframes-local-"));
     await stageHyperframesProject({ document, directory: work, signal,
@@ -109,7 +114,7 @@ export async function renderHyperframesVisual(
         assert(bytes !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
         return bytes;
       },
-      validateSurface: (surface, bytes, probeSignal) => verifyCompositableSurfaceBytes({ surface, bytes,
+      validateSurface: (surface, path, probeSignal) => verifyCompositableSurfaceFile({ surface, path,
         ffprobePath: config.ffprobePath, processTimeoutMs: config.processTimeoutMs,
         maxProbeOutputBytes: config.maxProcessOutputBytes, signal: probeSignal! }),
     });

package/packages/provider-hypihub/README.md

@@ -118,6 +118,9 @@ Resource identity with the same declared person-reference classification is uplo
 cross-Build cache. Seedance visual references can carry `personReference` in their media fields;
 the mapping declares it as a resource-transport field and the upload session receives
 `is_person_reference`, preserving true, false and omission. It stays out of the generation body.
+This covers reference images, reference videos, and first/last frames for every declared Seedance
+variant. Omission remains absent on the wire; HypiHub's upload API currently defaults it to false,
+so omission does not enable detection or person-reference preparation.
 HypiHub stores the authored classification and prepares the applicable upstream person reference;
 this Provider does not detect faces or select an upstream private-avatar group.
 

package/packages/runtime-host-node/README.md

@@ -53,3 +53,8 @@ to start execution, then `const runtime = await host.createRuntime(); await runt
 to submit work. `RuntimeHostExecution` does not run a second embedded Worker loop. A local carrier
 may stop accepting new Builds and drain; its assigned Builds stay in place and all carriers continue
 using the same resource accounting. Process policy belongs to the local Runtime, not this Host ABI.
+
+`prepareHostPackages` accepts exact specifier strings or `{ specifier, env }` installation inputs.
+The optional environment is applied only to that npm child process, merged over its inherited
+environment. It is neither persisted as installation status nor returned in package reports.
+The shared installer does not interpret SDK-specific variables; their owning packages supply them.

package/packages/runtime-host-node/src/index.ts

@@ -70,17 +70,20 @@ export type BuildView = {
   }[];
 };
 
-export type RuntimeHostCredentialStatus = {
+export type RuntimeHostCredentialDescription = {
   readonly endpoint: string;
   readonly slot: string;
   readonly label: string;
   readonly kind: "secret" | "json";
   readonly ref: CredentialRef;
   readonly acquisition?: CredentialAcquisition;
-  readonly configured: boolean;
   readonly writable: boolean;
 };
 
+export type RuntimeHostCredentialStatus = RuntimeHostCredentialDescription & {
+  readonly configured: boolean;
+};
+
 export type RuntimeHostControl = {
   /** Build evidence while active. Finished evidence is read through its Result Repository. */
   logs?(build: string, lines: number): Promise<import("@hypit/runtime").ExecutionLogView | undefined>;
@@ -105,6 +108,8 @@ export type RuntimeHostResultControl = {
 };
 
 export type RuntimeHostCredentialControl = {
+  /** Endpoint declarations and Store write capability; never reads an existing secret. */
+  describeCredentials(endpoint?: string): Promise<readonly RuntimeHostCredentialDescription[]>;
   credentials(endpoint?: string): Promise<readonly RuntimeHostCredentialStatus[]>;
   putCredential(endpoint: string, slot: string, secret: string): Promise<RuntimeHostCredentialStatus>;
   deleteCredential(endpoint: string, slot: string): Promise<{

package/packages/runtime-host-node/src/packages.ts

@@ -73,7 +73,7 @@ export async function inspectHostPackage(
     : undefined;
 }
 
-async function runNpm(root: string, specifiers: readonly string[], logPath: string): Promise<void> {
+async function runNpm(root: string, specifiers: readonly string[], logPath: string, env?: Readonly<Record<string, string>>): Promise<void> {
   // npm's prefix and cwd must denote the same physical project (not /tmp vs /private/tmp).
   const cwd = await realpath(root);
   const npmArgs = [
@@ -96,6 +96,7 @@ async function runNpm(root: string, specifiers: readonly string[], logPath: stri
         cwd,
         shell: false,
         windowsHide: true,
+        env: { ...process.env, ...env },
         stdio: ["ignore", log.fd, log.fd],
       });
       child.on("error", (error) => reject(new Error(`Cannot start npm: ${error.message}. Log: ${logPath}`, { cause: error })));
@@ -114,21 +115,26 @@ async function runNpm(root: string, specifiers: readonly string[], logPath: stri
  * package.json, lockfile and dependencies; Hypit keeps no parallel inventory.
  */
 export async function prepareHostPackages(
-  specifiers: readonly string[],
+  specifiers: readonly (string | { readonly specifier: string; readonly env?: Readonly<Record<string, string>> })[],
   options: {
     readonly root: string;
     readonly onProgress?: (event: HostPackageProgress) => void;
   },
 ): Promise<readonly HostPackageReport[]> {
   const root = resolve(options.root);
-  const bySpecifier = new Map<string, RegistryPackageSpec>();
+  const bySpecifier = new Map<string, RegistryPackageSpec & { readonly env?: Readonly<Record<string, string>> }>();
   for (const specifier of specifiers) {
-    const parsed = parseRegistryPackageSpec(specifier);
-    bySpecifier.set(parsed.specifier, parsed);
+    const parsed = parseRegistryPackageSpec(typeof specifier === "string" ? specifier : specifier.specifier);
+    const env = { ...bySpecifier.get(parsed.specifier)?.env };
+    for (const [key, value] of Object.entries(typeof specifier === "string" ? {} : specifier.env ?? {})) {
+      if (env[key] !== undefined && env[key] !== value) throw new Error(`Conflicting installation environment ${key} for ${parsed.specifier}`);
+      env[key] = value;
+    }
+    bySpecifier.set(parsed.specifier, { ...parsed, ...(Object.keys(env).length === 0 ? {} : { env }) });
   }
   const required = [...bySpecifier.values()].sort((left, right) => left.specifier.localeCompare(right.specifier));
   const reports: HostPackageReport[] = [];
-  for (const item of required) {
+  for (const { env, ...item } of required) {
     const installation = externalPackageInstallRoot(root, item.name, item.version);
     options.onProgress?.({ ...item, phase: "checking" });
     const missing = await installedVersion(installation, item.name) !== item.version;
@@ -142,7 +148,7 @@ export async function prepareHostPackages(
         dependencies: { [item.name]: item.version },
       }, null, 2)}\n`, "utf8");
       options.onProgress?.({ ...item, phase: "installing", logPath });
-      await runNpm(installation, [item.specifier], logPath);
+      await runNpm(installation, [item.specifier], logPath, env);
     }
     const version = await installedVersion(installation, item.name);
     if (version !== item.version) {

package/packages/runtime-local/README.md

@@ -258,3 +258,13 @@ capacity release and every completed Result. They use the production execution p
 This is a load experiment rather than part of every package regression. It reports fixture preparation,
 local progress, completion, executor RSS and cleanup separately; total test time also includes creating
 and removing the temporary Result repositories. Neither suite uses a completion-time performance target.
+
+
+### Credential management without reading the old value
+
+`openCredentials(endpoint)` opens only the selected Endpoint's credential control.
+`describeCredentials(endpoint)` returns its declared slots and each Store's write capability without
+resolving secrets. `credentials(endpoint)` also reads current values to report status and propagates
+read failures. Login and logout use the former: a damaged old credential cannot prevent replacement
+or deletion. Successful writes and deletions report their operation's result without rereading the
+secret. Execution still resolves credentials normally and reports Store errors.

package/packages/runtime-local/src/config.ts

@@ -462,7 +462,7 @@ export async function prepareRuntimeConfigPackages(
     ...document.endpoints.map((item) => item.use),
     ...credentials.credentials.map((item) => item.use),
   ], options.distributionPackageRoot);
-  return await prepareHostPackages(requirements.map((item) => item.specifier), {
+  return await prepareHostPackages(requirements, {
     root: hypitHostPackageRoot(options.hostStateRoot),
     ...(options.onProgress === undefined ? {} : { onProgress: options.onProgress }),
   });

package/packages/runtime-local/src/credentials.ts

@@ -28,16 +28,21 @@ export function createLocalCredentialControl(
       : `Endpoint ${endpoint} repeats credential slot ${slot}`);
     return matches[0]!;
   };
-  const status = async (item: typeof descriptions[number]) => ({
+  const describe = async (item: typeof descriptions[number]) => ({
     ...structuredClone(item),
-    configured: await options.credentialStore.resolve(item.ref) !== undefined,
     writable: await writableCredentialStore(options.credentialStore, item.ref) !== undefined,
   });
 
   return {
+    async describeCredentials(endpoint) {
+      return await Promise.all(descriptions.filter((item) => endpoint === undefined || item.endpoint === endpoint).map(describe));
+    },
     async credentials(endpoint) {
       const selected = descriptions.filter((item) => endpoint === undefined || item.endpoint === endpoint);
-      return await Promise.all(selected.map(status));
+      return await Promise.all(selected.map(async (item) => ({
+        ...await describe(item),
+        configured: await options.credentialStore.resolve(item.ref) !== undefined,
+      })));
     },
     async putCredential(endpoint, slot, secret) {
       assert(secret.length > 0, "credential secret is empty");
@@ -45,14 +50,14 @@ export function createLocalCredentialControl(
       const store = await writableCredentialStore(options.credentialStore, item.ref);
       assert(store !== undefined, `CredentialStore ${item.ref.store} is not writable`);
       await store.put(item.ref, { secret });
-      return await status(item);
+      return { ...structuredClone(item), writable: true, configured: true };
     },
     async deleteCredential(endpoint, slot) {
       const item = credential(endpoint, slot);
       const store = await writableCredentialStore(options.credentialStore, item.ref);
       assert(store !== undefined, `CredentialStore ${item.ref.store} is not writable`);
       const deleted = await store.delete(item.ref);
-      return { deleted, credential: await status(item) };
+      return { deleted, credential: { ...structuredClone(item), writable: true, configured: false } };
     },
     close() {
       return options.close?.();

package/packages/runtime-local/src/runtime.ts

@@ -41,7 +41,7 @@ function nonNegativeInteger(value: number, subject: string): number {
 function projectPath(root: string, path: string): string {
   const absolute = isAbsolute(path) ? resolve(path) : resolve(root, path);
   const relation = relative(resolve(root), absolute);
-  assert(relation === "" || (!relation.startsWith("..") && !isAbsolute(relation)),
+  assert(relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation)),
     `Build Result source ${path} is outside project ${resolve(root)}`);
   return (relation || ".").split(sep).join("/");
 }

package/packages/seedance/README.md

@@ -18,6 +18,20 @@ the author's literal, in whole seconds inside the model's declared range; measur
 with `hypit measure` and write the number here. Nothing in the graph computes it, so a Build plan is
 complete before it starts.
 
+## Reference audio
+
+The Seedance package rejects reference audio declared as `audio/mp4` or `audio/x-m4a`. Convert the
+audio to WAV or MP3 before using it; `media:ExtractAudio` produces WAV and can consume an upstream
+component's media output. Renaming a file or changing its declared media type is not conversion.
+
+Known imports are checked during Surface decoding. Future audio stays a graph input and is checked
+when its Blob arrives. The same rule applies to drafts, complete requests, planning and direct
+generation Producers. `sealSeedanceRequest` uses the endpoint's model-aware request builder;
+`seedanceComponent` and `seedanceDefinition.component` expose the same implementation.
+
+This checks the Blob's declared media type, not its bytes or codec. The selected Provider remains
+responsible for any additional service-specific input limits.
+
 ## Visual reference metadata
 
 Declare whether each image or video contains a person/avatar reference, including an AI-generated
@@ -37,10 +51,38 @@ Inspect the actual reference when deciding the value. For `FrameVideo`, use
 `first-frame-person-reference` and `last-frame-person-reference` beside their respective frame
 inputs. A last-frame classification requires a last-frame input.
 
+| Supplied visual input | Authored attribute | Request port |
+| --- | --- | --- |
+| Each `Reference image={...}` | `person-reference` | `referenceImage` |
+| Each `Reference video={...}` | `person-reference` | `referenceVideo` |
+| `FrameVideo` first frame | `first-frame-person-reference` | `firstFrame` |
+| `FrameVideo` last frame | `last-frame-person-reference` | `lastFrame` |
+
+These forms apply to `standard`, `fast`, `mini` and `2.5`. For example:
+
+```xml
+<seedance:FrameVideo id="turn" model="fast" prompt={direction} duration="5"
+  first-frame={presenter.image} first-frame-person-reference="true"
+  last-frame={empty-room.image} last-frame-person-reference="false"/>
+```
+
+Classify the material supplied to this request, not the intended result. A dance video with a person
+still needs `true` when used only for motion, even if the prompt asks for a different performer.
+An empty room stays `false` when the prompt asks to add a person. Inspect video across the selected
+excerpt, not only its opening frame. This flag neither detects faces nor locks or names an identity.
+Identity and action direction remain in the prompt and references.
+
+The SVML author declares this parameter on each reference input. Admitted files, generated
+images/videos and reused Results use the same attributes. For a future output, declare the intended
+reference classification explicitly; if its contents are uncertain, generate and inspect that
+material before using it downstream.
+
 The model's media ports carry this as `fields.personReference`. Providers interpret it through their
 service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
 `is_person_reference` when uploading the file, then uses the returned URL in the ordinary video
 request. A project Provider maps it according to its own API.
+Omission does not request automatic face detection. HypiHub currently treats omitted upload flags
+as unmarked (`false`); declare `true` explicitly for a person reference that needs its preparation.
 
 Video references can carry motion or camera behavior while image references carry the target
 appearance. Request duration and reference-clip duration are different limits. Check the selected

package/packages/seedance/src/index.ts

@@ -1,7 +1,4 @@
-import {
-  sealGenerationPortRequest,
-  sealGenerationPortTable,
-} from "@hypit/generation";
+import { sealGenerationPortTable } from "@hypit/generation";
 import type {
   GenerationPortTable,
   GenerationPortValue,
@@ -12,6 +9,7 @@ import type { SurfaceAttributeVocabulary, SurfacePortVocabulary } from "@hypit/m
 import { defineExactModelModule } from "@hypit/model-kit";
 import { textTypes } from "@hypit/text";
 import type { ResourceId } from "@hypit/protocol";
+import { validateSeedanceInputs } from "./validation.js";
 
 export const seedanceModuleRef = { name: "@hypit/seedance", version: "1" } as const;
 export const seedanceModels = ["seedance-2", "seedance-2-fast", "seedance-2-mini", "seedance-2.5"] as const;
@@ -93,7 +91,7 @@ export const seedancePorts: Readonly<Record<SeedanceModel, GenerationPortTable>>
 export type SeedancePortMap = Readonly<Record<string, readonly GenerationPortValue[]>>;
 
 export function sealSeedanceRequest(model: SeedanceModel, ports: SeedancePortMap): GenerationRequest {
-  return sealGenerationPortRequest(seedancePorts[model], ports);
+  return seedanceEndpointsByModel[model].sealRequest(ports);
 }
 
 const seedanceBaseDefinition = defineExactModelModule({
@@ -110,6 +108,7 @@ const seedanceBaseDefinition = defineExactModelModule({
       : `${model.split("-").map((part) => part[0]!.toUpperCase() + part.slice(1)).join("")}Request`,
     producerName: `request-${model}`,
     ports: seedancePorts[model],
+    validateInputs: validateSeedanceInputs,
   })),
 });
 
@@ -327,23 +326,7 @@ export const seedanceMarkupSurfaces = [
 /** The duration is an author literal on every Seedance Surface, so the manifest is the exact-model module's own. */
 export const seedanceManifest = seedanceBaseDefinition.manifest;
 
-const referenceAudioProducers = new Set(Object.values(seedanceEndpoints)
-  .map((endpoint) => endpoint.mediaBindings["referenceAudio"]!.producer.name));
-
-export const seedanceComponent = {
-  ...seedanceBaseDefinition.component,
-  producers: seedanceBaseDefinition.component.producers.map((facet) =>
-    referenceAudioProducers.has(facet.producer.name) ? {
-      ...facet,
-      handler: (context: Parameters<typeof facet.handler>[0]) => {
-        const artifact = context.inputs.artifact?.value;
-        if (artifact?.kind === "blob" && ["audio/mp4", "audio/x-m4a"].includes(artifact.mediaType)) {
-          throw new Error("Seedance reference audio does not accept m4a; convert to wav or mp3");
-        }
-        return facet.handler(context);
-      },
-    } : facet),
-};
+export const seedanceComponent = seedanceBaseDefinition.component;
 export const seedanceDefinition = seedanceBaseDefinition;
 
 export {

package/packages/seedance/src/surface.ts

@@ -23,6 +23,7 @@ import type {
 import { createSeedanceAssembledGenerationFragment } from "./fragment.js";
 import { seedanceEndpoints, seedancePorts } from "./index.js";
 import type { SeedanceModel, SeedancePortMap } from "./index.js";
+import { validateSeedanceAudio } from "./validation.js";
 
 type MediaInput = {
   readonly port: "referenceImage" | "referenceVideo" | "referenceAudio" | "firstFrame" | "lastFrame";
@@ -109,9 +110,7 @@ function mediaReference(
   if (value !== undefined && (value.kind !== "blob" || !value.mediaType.startsWith(`${role}/`))) {
     throw new Error(`${subject} must reference ${role} media`);
   }
-  if (value !== undefined && value.kind === "blob" && role === "audio" && ["audio/mp4", "audio/x-m4a"].includes(value.mediaType)) {
-    throw new Error(`${subject} references m4a audio, which Seedance does not accept; convert to wav or mp3 and admit that file`);
-  }
+  if (value?.kind === "blob" && role === "audio") validateSeedanceAudio(value, subject);
   return reference;
 }
 

package/packages/seedance/src/validation.ts

@@ -0,0 +1,16 @@
+import type { GenerationRequestDraft } from "@hypit/generation";
+import type { BlobRef } from "@hypit/protocol";
+
+/** Seedance's reference-audio rule, shared by known imports and request assembly. */
+export function validateSeedanceAudio(artifact: BlobRef, subject = "Seedance reference audio"): void {
+  if (artifact.mediaType === "audio/mp4" || artifact.mediaType === "audio/x-m4a") {
+    throw new Error(`${subject} does not accept m4a; convert the reference audio to WAV or MP3 before using it (media:ExtractAudio produces WAV)`);
+  }
+}
+
+/** Missing references in a draft remain graph inputs; only supplied audio is checked. */
+export function validateSeedanceInputs(request: GenerationRequestDraft): void {
+  for (const value of request.ports.referenceAudio ?? []) {
+    if (typeof value === "object" && value.role === "audio") validateSeedanceAudio(value.artifact);
+  }
+}

package/packages/studio/src/preview/runtime-shim.ts

@@ -47,7 +47,12 @@ function shim(): string {
       start: parseFloat(ownStart || (present && present.getAttribute('data-start')) || '0') || 0,
       duration: parseFloat(ownDuration || (present && present.getAttribute('data-duration')) || '0') || 0,
       mediaStart: parseFloat(element.getAttribute('data-media-start') || '0') || 0,
-      rate: parseFloat(element.getAttribute('data-playback-rate') || '1') || 1
+      rate: parseFloat(element.getAttribute('data-playback-rate') || '1') || 1,
+      startFrame: Number(element.getAttribute('data-hypit-start-frame')),
+      endFrame: Number(element.getAttribute('data-hypit-end-frame')),
+      sourceFrame: element.getAttribute('data-hypit-source-frame').split('/').map(BigInt),
+      sourceRate: element.getAttribute('data-hypit-source-rate').split('/').map(BigInt),
+      sourceFps: element.getAttribute('data-hypit-source-fps').split('/').map(Number)
     });
   }
   var audioContext;
@@ -149,7 +154,8 @@ function shim(): string {
     }
     for (var record of media) {
       var local = currentSeconds - record.start;
-      var inside = local >= 0 && local < record.duration;
+      var programFrame = Math.round(currentSeconds * fps);
+      var inside = programFrame >= record.startFrame && programFrame < record.endFrame;
       var element = record.element;
       element.style.visibility = inside ? 'visible' : 'hidden';
       // Normalized picture Artifacts are deliberately silent. Programme sound
@@ -157,10 +163,18 @@ function shim(): string {
       element.muted = true;
       if (!inside) { element.pause(); continue; }
       var target = record.mediaStart + (local + frameSeconds / 2) * record.rate;
+      var discrete = scrubbing || programFrame === record.endFrame - 1;
+      if (discrete) {
+        // The renderer floors exact source-frame coordinates. The midpoint of a
+        // programme frame can cross that source boundary at fractional speeds.
+        var a = record.sourceFrame, r = record.sourceRate;
+        var sourceFrame = Number((a[0] * r[1] + BigInt(programFrame - record.startFrame) * r[0] * a[1]) / (a[1] * r[1]));
+        target = (sourceFrame + 0.5) * record.sourceFps[1] / record.sourceFps[0];
+      }
       if (Number.isFinite(element.duration) && element.duration > 0) {
         target = Math.min(target, Math.max(0, element.duration - 0.001));
       }
-      if (scrubbing || local >= record.duration - frameSeconds - 0.000001) {
+      if (discrete) {
         element.pause();
         waits.push(seekDecoded(element, target));
       } else {

package/packages/studio/src/server.ts

@@ -2,7 +2,7 @@ import { watch } from "node:fs";
 import type { FSWatcher } from "node:fs";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 
@@ -207,7 +207,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
       if (isAbsolute(patch.path)) throw new Error("Studio patches must use workspace-relative paths.");
       const absolute = resolve(options.workspaceRoot, patch.path);
       const rel = relative(options.workspaceRoot, absolute);
-      if (rel.startsWith("..") || isAbsolute(rel) || !allowedSourceFiles.has(absolute)) {
+      if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel) || !allowedSourceFiles.has(absolute)) {
         throw new Error(`Studio cannot write source file ${patch.path}.`);
       }
       if (!Number.isInteger(patch.range.start) || !Number.isInteger(patch.range.end)

package/packages/video-cli/README.md

@@ -34,7 +34,11 @@ an editable starter; its Endpoint entries describe available routes, not choices
 Keep an existing chosen service, or configure the chosen local or hosted Provider and its capability
 bindings. HypiHub is the recommended integrated hosted route in the official Distribution; other
 services use project Provider packages. If the user chooses HypiHub,
-`hypit auth login hypihub.default` connects that account.
+`hypit auth login hypihub.default` connects that account after choosing its CredentialStore.
+The starter selects the OS store for macOS Keychain / Windows Credential Locker. On Linux, or when
+explicitly choosing file storage, edit the Profile's `credentials` and Endpoint reference as shown
+in [file CredentialStore](../credential-store-file/README.md#select-it-before-login) before `auth` or
+`runtime up`. This selection is configuration; execution never switches stores automatically.
 `hypit doctor --endpoint <name>` checks a selected Endpoint;
 `hypit runtime up --endpoint <name>` prepares that Endpoint and starts the Worker. Repeat the flag
 for several chosen Endpoints; omitting it prepares the whole Profile. `hypit programs up --endpoint