@hypit/hypit 0.1.13 → 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/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/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/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

package/packages/video-cli/package.json

@@ -13,6 +13,7 @@
     "@hypit/cli": "workspace:*",
     "@hypit/compiler-markup-node": "workspace:*",
     "@hypit/composition": "workspace:*",
+    "@hypit/credential-store-file": "workspace:*",
     "@hypit/credential-store-os": "workspace:*",
     "@hypit/driver-node": "workspace:*",
     "@hypit/estimate": "workspace:*",

package/packages/video-cli/src/distribution.ts

@@ -12,8 +12,7 @@ import {
 
 // The Distribution root is the replaceable Hypit tool checkout, not this
 // package's source directory and never the author's project.
-const packageRoot = resolve(process.env.HYPIT_DISTRIBUTION_ROOT ?? resolve(import.meta.dirname, "../../.."));
-const installedLauncher = process.env.HYPIT_CLI_LAUNCHER;
+const packageRoot = resolve(import.meta.dirname, "../../..");
 const defaultBuildResultRepository = {
   use: "@hypit/build-result-fs",
   config: { path: ".hypit/results" },
@@ -57,14 +56,8 @@ export const videoCliDistribution: CliDistribution = {
       : { distributionPackageRoot: options.distributionPackageRoot }),
     workerLaunch: {
       command: process.execPath,
-      // The repository launcher registers TypeScript support before entering the CLI.
-      // Tests that import this Distribution directly keep the current Node arguments.
-      args: installedLauncher === undefined
-        ? [
-            ...process.execArgv.filter((item) => !item.startsWith("--test")),
-            fileURLToPath(new URL("./cli.ts", import.meta.url)),
-          ]
-        : [installedLauncher],
+      // The loaded Distribution owns its Worker entry and TypeScript/package resolution.
+      args: [fileURLToPath(new URL("../../../bin/hypit.mjs", import.meta.url))],
     },
   }),
   openProjectResults: async (projectRoot, options) => {

package/packages/video-cli/src/version.ts

@@ -20,7 +20,7 @@ export function writeVersionHelp(io: CliIo): void {
 /** Installation discovery belongs to the executable, independent of video execution and Skill installers. */
 export async function runVersionCli(argv: readonly string[], io: CliIo, environment: VersionEnvironment = {
   packageRoot: resolve(import.meta.dirname, "../../.."),
-  ...(process.env.HYPIT_CLI_LAUNCHER === undefined ? {} : { launcher: process.env.HYPIT_CLI_LAUNCHER }),
+  launcher: resolve(import.meta.dirname, "../../../bin/hypit.mjs"),
   fetch: globalThis.fetch,
 }): Promise<void> {
   let check = false;

package/packages/yt-dlp/README.md

@@ -17,8 +17,9 @@ Runtime Profile and creates no Build.
 - `downloadVideo(url, target)` downloads one video to the given path. Its caller owns destination
   preparation and overwrite policy. The target extension must be `.mp4`, `.mkv`, `.webm` or `.mov`.
 
-The downloader invokes the locked Python project in `services/yt-dlp` through `uv`, located relative
-to the installed Distribution. Ship its `pyproject.toml` and `uv.lock` with this package's source.
+The downloader locates its declared `@hypit/yt-dlp-service-runtime` package through the active
+Distribution/package resolver and invokes that package's locked Python project through `uv`.
+Ship its `pyproject.toml` and `uv.lock`; the caller's location and a `services/` ancestor are irrelevant.
 `uv` and `ffmpeg` must be available on PATH; the CLI also uses `ffprobe` to report the saved media.
 
 The request selects `bv*+ba/b`, with `res:1080,vcodec:h264` format preferences and `--no-playlist`.

package/packages/yt-dlp/package.json

@@ -6,5 +6,9 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/package-loader-node": "workspace:*",
+    "@hypit/yt-dlp-service-runtime": "workspace:*"
   }
 }

package/packages/yt-dlp/src/download.ts

@@ -11,11 +11,11 @@
  * the same shape WhisperX and OpenCV already use for their Python programs.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
 import { copyFile, mkdtemp, readdir, rename, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, extname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+
+import { resolveNodePackageResource } from "@hypit/package-loader-node";
 
 /**
  * Whether this is a link to fetch rather than a path to open.
@@ -34,20 +34,16 @@ export function isVideoUrl(value: string): boolean {
 }
 
 /**
- * The uv project holding the pinned `yt-dlp`, found by walking up from this module rather than from
- * the working directory, which is wherever the author happened to run the command from.
+ * The locked uv project is a Distribution package asset, the same way WhisperX and
+ * OpenCV locate their Python programs. Walking parents of this file only works
+ * while the module still sits above `services/` in a contributor checkout.
  */
 function serviceProject(): string {
-  let directory = dirname(fileURLToPath(import.meta.url));
-  while (true) {
-    const candidate = join(directory, "services", "yt-dlp", "pyproject.toml");
-    if (existsSync(candidate)) return dirname(candidate);
-    const parent = dirname(directory);
-    if (parent === directory) {
-      throw new Error("no services/yt-dlp project above this module; the Distribution is incomplete");
-    }
-    directory = parent;
-  }
+  return dirname(resolveNodePackageResource(
+    "@hypit/yt-dlp-service-runtime",
+    "pyproject.toml",
+    { from: import.meta.url },
+  ));
 }
 
 /**