@hypit/hypit 0.1.13 → 0.2.0

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

@@ -0,0 +1,60 @@
+# `@hypit/credential-store-file`
+
+A writable CredentialStore for a deployment that explicitly chooses local file storage, including
+Linux without an OS credential locker. It stores unencrypted credential values in an owner-private
+directory outside the video project. On Windows the selected directory must have a private user ACL;
+POSIX file modes do not set Windows ACLs. Choose `@hypit/credential-store-os` when using macOS Keychain
+or Windows Credential Locker, or `@hypit/credential-store-env` for externally supplied, read-only values.
+
+## Select it before login
+
+After `hypit runtime init`, edit the created Profile before running `auth` or starting its Runtime.
+Replace its credential-store selection and the chosen Endpoint's credential reference together:
+
+```json
+{
+  "credentials": {
+    "file": { "use": "@hypit/credential-store-file" }
+  },
+  "endpoints": {
+    "hypihub.default": {
+      "use": "@hypit/provider-hypihub",
+      "config": {
+        "baseUrl": "https://hypit.ai",
+        "apiKey": { "store": "file", "key": "hypihub.oauth" }
+      }
+    }
+  }
+}
+```
+
+This is a Profile fragment: preserve its format, dataRoot, other Endpoints and bindings. For an
+existing Profile, edit only the selected references and use `hypit runtime use <profile>` to select it.
+The Endpoint still owns its acquisition flow; the Store only persists its result:
+
+```bash
+hypit auth login hypihub.default
+hypit auth status hypihub.default
+hypit auth logout hypihub.default
+```
+
+No existing OS credential is migrated and no failed lookup tries another Store. A damaged document
+can be replaced by login or deleted by logout without decoding the old value. Status and execution
+report the read error rather than treating corruption as a missing credential.
+
+## Storage
+
+The default directory is `credentials` under the Host state root printed by `hypit paths`.
+`config.path` explicitly selects a directory, resolving relative paths against that Host root.
+Opening the adapter and reading an absent key do not create files. Keep this directory outside Git.
+
+Each key has its own JSON file containing only `secret` and optional `expiresAt`, as defined by
+CredentialValue. Filenames use reversible lower-case hex encoding of the key's UTF-16 bytes, with a
+`key-` prefix; they are not hashes or secret encryption. This preserves case-sensitive key identity on
+case-insensitive filesystems and keeps slashes and reserved names out of filesystem path syntax.
+Filesystem path-length limits still apply; an overlong key fails rather than selecting another name.
+
+Writes create an owner-only temporary file and replace the single destination with rename. Different
+keys do not overwrite each other's updates; concurrent writes to the same key keep the last completed
+replacement. The Store does not enumerate credentials, maintain an index, or record write history.
+Permission and I/O errors propagate. Existing directory permissions are not silently changed.

package/packages/credential-store-file/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@hypit/credential-store-file",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*"
+  }
+}

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

@@ -0,0 +1,29 @@
+import { join, resolve } from "node:path";
+import {
+  createRuntimeCredentialStoreAdapterFacet,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+import { FileCredentialStore } from "./store.js";
+
+const fileCredentialStoreAdapter = createRuntimeCredentialStoreAdapterFacet({
+  use: "@hypit/credential-store-file",
+  validate(context) {
+    const config = runtimeConfigObject(context.config, "file CredentialStore");
+    runtimeConfigExact(config, ["path"], "file CredentialStore");
+    runtimeConfigString(config.path, "file credential path");
+  },
+  open(context) {
+    const config = runtimeConfigObject(context.config, "file CredentialStore");
+    const path = runtimeConfigString(config.path, "file credential path");
+    return { value: new FileCredentialStore(path === undefined
+      ? join(context.hostStateRoot, "credentials") : resolve(context.hostStateRoot, path)) };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [fileCredentialStoreAdapter],
+};
+export default hypitPackage;

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

@@ -0,0 +1 @@
+export { FileCredentialStore } from "./store.js";

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

@@ -0,0 +1,89 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, rename, rm, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { verifyCredentialRef } from "@hypit/runtime";
+import type { CredentialRef, CredentialValue, WritableCredentialStore } from "@hypit/runtime";
+
+function missing(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+function credentialValue(value: unknown): CredentialValue {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid credential value");
+  const record = value as Record<string, unknown>;
+  if (typeof record.secret !== "string" || record.secret.length === 0
+    || (record.expiresAt !== undefined && (typeof record.expiresAt !== "number" || !Number.isFinite(record.expiresAt)))) {
+    throw new Error("invalid credential value");
+  }
+  return { secret: record.secret, ...(record.expiresAt === undefined ? {} : { expiresAt: record.expiresAt as number }) };
+}
+
+/** One file per Store-local key; no enumeration, index or cross-key read/modify/write. */
+export class FileCredentialStore implements WritableCredentialStore {
+  constructor(readonly directory: string) {}
+
+  owns(ref: CredentialRef): boolean { return ref.store === "file"; }
+
+  #path(ref: CredentialRef): string {
+    verifyCredentialRef(ref);
+    if (!this.owns(ref)) throw new Error(`File CredentialStore does not own ${ref.store}`);
+    // Reversible UTF-16 encoding preserves the opaque JS key, even on case-insensitive filesystems.
+    // The prefix avoids reserved OS filenames; no key characters become path separators.
+    return join(this.directory, `key-${Buffer.from(ref.key, "utf16le").toString("hex")}.json`);
+  }
+
+  async #privateDirectory(create: boolean): Promise<void> {
+    if (create) await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const info = await stat(this.directory);
+    if (!info.isDirectory()) throw new Error(`Credential path is not a directory: ${this.directory}`);
+    if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
+      throw new Error(`Credential directory must be owner-private: ${this.directory}`);
+    }
+  }
+
+  async resolve(ref: CredentialRef): Promise<CredentialValue | undefined> {
+    if (!this.owns(ref)) return undefined;
+    const path = this.#path(ref);
+    try { await this.#privateDirectory(false); } catch (error) {
+      if (missing(error)) return undefined;
+      throw error;
+    }
+    let file;
+    try { file = await open(path, "r"); } catch (error) {
+      if (missing(error)) return undefined;
+      throw error;
+    }
+    try {
+      const info = await file.stat();
+      if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
+        throw new Error(`Credential file must be owner-private: ${path}`);
+      }
+      const text = await file.readFile("utf8");
+      // JSON parser messages may include secret bytes. Report the file, never its contents.
+      try { return credentialValue(JSON.parse(text)); } catch {
+        throw new Error(`Cannot decode credential file: ${path}; replace it with auth login or remove it with auth logout`);
+      }
+    } finally { await file.close(); }
+  }
+
+  async put(ref: CredentialRef, value: CredentialValue): Promise<void> {
+    const path = this.#path(ref);
+    const contents = JSON.stringify(credentialValue(value));
+    await this.#privateDirectory(true);
+    const temporary = join(this.directory, `.write-${randomUUID()}.tmp`);
+    const file = await open(temporary, "wx", 0o600);
+    try {
+      try { await file.writeFile(`${contents}\n`, "utf8"); } finally { await file.close(); }
+      await rename(temporary, path);
+    } finally { await rm(temporary, { force: true }); }
+  }
+
+  async delete(ref: CredentialRef): Promise<boolean> {
+    const path = this.#path(ref);
+    // Deletion never opens or decodes the old document.
+    try { await unlink(path); return true; } catch (error) {
+      if (missing(error)) return false;
+      throw error;
+    }
+  }
+}

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

@@ -141,7 +141,11 @@ function platformBackend(service: string) {
     return { read: macosReader(service), write: macosWriter(service), remove: macosDeleter(service) };
   }
   if (process.platform === "win32") return windowsBackend();
-  throw new Error("OS CredentialStore supports macOS and Windows only");
+  // A Profile that selects this Store cannot be repaired by anything the user does here, and the
+  // other two Stores are the answer, so name them where the failure is read.
+  throw new Error("OS CredentialStore supports macOS and Windows only; select "
+    + "@hypit/credential-store-file (owner-private local file) or @hypit/credential-store-env "
+    + "(externally supplied value) in this Profile's credentials instead");
 }
 
 /** One logical writable store backed by the current user's OS credential locker. */

package/packages/fonts-open/src/surface.ts

@@ -9,7 +9,7 @@ import {
 } from "@hypit/media";
 import type { FontArtifactRef, FontStackRef } from "@hypit/media";
 import type { StructuredElement, StructuredSurfaceHandler } from "@hypit/markup";
-import { resolveNodePackageResource } from "@hypit/package-loader-node";
+import { NodePackageNotFoundError, resolveNodePackageResource } from "@hypit/package-loader-node";
 
 import {
   openFontFamilies,
@@ -21,11 +21,17 @@ import type {
   OpenFontStyle,
 } from "./catalog.js";
 
+const fontDependencies = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+  readonly optionalDependencies: Readonly<Record<string, string>>;
+};
+
 function resolveFontPackageFile(packageName: string, path: string): string {
   try {
     return resolveNodePackageResource(packageName, path, { from: import.meta.url });
   } catch (error) {
-    const version = packageName === "@infolektuell/noto-color-emoji" ? "0.2.0" : "5.3.0";
+    if (!(error instanceof NodePackageNotFoundError)) throw error;
+    const version = fontDependencies.optionalDependencies[packageName];
+    if (version === undefined) throw error;
     throw new Error(
       `${packageName} is needed by this authored font. Install it once with: hypit packages install ${packageName}@${version}`,
       { cause: error },

package/packages/hyperframes/README.md

@@ -12,6 +12,8 @@ This package understands only `VisualTrack`, `ProgramSpace` and canvas geometry.
 does not know Caption, Speech, B-roll, Seedance or any other author-domain component. It flattens
 every Track's Presents, orders them by their own absolute stacking keys and emits frame-bound local
 keyframes. An authoring Track never becomes an isolated render stacking surface.
+Terminal text and SVG mask sources retain the same Present-relative frame animations as other
+elements, including direct seeks into the middle of a Present.
 
 It deliberately ignores `AudioTrack`. HyperFrames produces a silent visual fact; the media pipeline
 compiles and renders program audio separately, then an explicit mux Provider joins the two. Changing
@@ -23,6 +25,12 @@ a Provider can verify and name staged bytes without guessing from the hash. A lo
 render Runtime calls `materializeHyperframesHtml()` with its own Artifact URL resolver before
 handing the HTML to HyperFrames. That environment-specific materialization is not a new compiled
 Record and does not change the compiled document.
+Staging assigns short local filenames; opaque Resource IDs are never interpreted as filesystem
+paths or filenames, so their length and punctuation do not restrict the host filesystem.
+`stageHyperframesProject` streams each asset into its staged file. Its `validateSurface(surface, path,
+signal)` callback borrows that completed file during inspection; it receives neither a whole-file
+byte copy nor ownership of the file. The staging caller keeps the directory alive until all work
+has settled, including cancellation.
 
 The document exposes its render domain directly rather than asking an Endpoint to scrape HTML:
 exact rational `frameRate`, integer `frameCount`, and canvas dimensions are explicit document
@@ -53,8 +61,12 @@ places a direct typed child. Every child is placed once, including sampled video
 This keeps actual video available to the renderer's exact source-frame preparation.
 
 CSS is scoped to the generated program root with `@scope`; `:scope` styles that root. The HTML can
-contain arbitrary local structure, SVG, internal stacking, masks and backdrop filters. The optional
-`setup` string is a JavaScript function body with `root` and `data` arguments. It returns a synchronous
+contain arbitrary local structure, SVG, internal stacking, masks and backdrop filters.
+CSS scope does not isolate HTML/SVG IDs. Use classes or data attributes for local queries; when an
+SVG needs an ID for `url(#...)` or `href`, derive it from the unique `root.id` in `setup` and set both
+the definition and its references there. Reusable instances must not repeat hard-coded SVG IDs.
+
+The optional `setup` string is a JavaScript function body with `root` and `data` arguments. It returns a synchronous
 `render(localFrame)` function, evaluated on initial load and active `hf-seek` events. Outside the
 Present's lifetime, the dispatcher settles the boundary pose once instead of repeatedly updating
 an invisible program. Active seeks always redraw, including the same frame after resources become
@@ -63,6 +75,8 @@ objects in `setup`; express animation state as a function of frame and inputs so
 begin at any frame. Async work belongs to
 material preparation before rendering; browser resources belong in the program's declared artifacts.
 Use `hyperframesResourceUri(artifact.resource)` in resource-bearing markup or CSS.
+Returning a Promise from `render` reports an authoring error; frame capture never waits for an
+unbounded asynchronous drawing task or races it.
 
 Ordinary child sampling follows the Present clock. Reframing the parent leaves source playback
 unchanged. `projectTimelineMedia` from `@hypit/hypit/timeline` gives a component selected prepared

package/packages/hyperframes/src/browser-program.ts

@@ -76,7 +76,12 @@ export function browserProgramScript(entries: readonly {
         // including repeated frame 0 after images/fonts finish loading.
         if (region !== 'active' && entry.region === region) continue;
         try {
-          entry.render(Math.max(0, Math.min(entry.durationFrames, local)));
+          const result = entry.render(Math.max(0, Math.min(entry.durationFrames, local)));
+          if (result != null && typeof result.then === 'function') {
+            // Observe a later rejection, but never let asynchronous drawing race frame capture.
+            Promise.resolve(result).catch(fail);
+            throw new Error('Browser program render(localFrame) must be synchronous; prepare asynchronous resources before rendering.');
+          }
           entry.region = region;
         }
         catch (error) { fail(error); }

package/packages/hyperframes/src/document.ts

@@ -229,23 +229,22 @@ function exactFontStyle(element: VisualElement, stableId: StableDomId): string[]
   ];
 }
 
-function renderElement(
-  element: VisualElement,
-  children: ReadonlyMap<string, readonly VisualElement[]>,
-  context: {
-    readonly trackId: string;
-    readonly presentId: string;
-    readonly presentStart: string;
-    readonly presentDuration: string;
-    readonly presentDurationFrames: number;
-    readonly presentStartFrame: number;
-    readonly programNumerator: number;
-    readonly programDenominator: number;
-    readonly stackIndex: number;
-    readonly emittedFilterIds: Set<string>;
-    readonly stableId: StableDomId;
-  },
-): string {
+type ElementContext = {
+  readonly trackId: string;
+  readonly presentId: string;
+  readonly presentStart: string;
+  readonly presentDuration: string;
+  readonly presentDurationFrames: number;
+  readonly presentStartFrame: number;
+  readonly programNumerator: number;
+  readonly programDenominator: number;
+  readonly stackIndex: number;
+  readonly emittedFilterIds: Set<string>;
+  readonly stableId: StableDomId;
+};
+
+/** Every emitted element, including SVG mask sources, keeps the same authored frame clock. */
+function elementPresentation(element: VisualElement, context: ElementContext) {
   const id = context.stableId([context.trackId, context.presentId, element.id]);
   const animationName = element.animation === undefined
     ? undefined
@@ -277,6 +276,16 @@ function renderElement(
     ? ""
     : ` data-hypit-frame-animation data-hypit-animation-start-frame="${context.presentStartFrame}" data-hypit-animation-duration-frames="${animationDurationFrames}" data-hypit-animation-sample-frames="${context.presentDurationFrames}" data-hypit-animation-properties="${animationProperties.join(",")}"`;
   const common = `${commonAttributes}${animationAttributes} style="${escapeHtml(inlineStyle)}"`;
+  return { inlineStyle, commonAttributes: `${commonAttributes}${animationAttributes}`, common };
+}
+
+function renderElement(
+  element: VisualElement,
+  children: ReadonlyMap<string, readonly VisualElement[]>,
+  context: ElementContext,
+): string {
+  const { inlineStyle, commonAttributes, common } = elementPresentation(element, context);
+  const id = context.stableId([context.trackId, context.presentId, element.id]);
   if (element.kind === "mask") {
     const direct = children.get(element.id) ?? [];
     const maskRoot = direct.find((child) => child.id === element.maskElement);
@@ -295,6 +304,7 @@ function renderElement(
       throw new Error(`Local mask ${element.id} mask source must be one terminal owned element.`);
     }
     const maskSource = (() => {
+      const sourcePresentation = elementPresentation(maskRoot, context);
       if (maskRoot.kind === "text") {
         const alignment = maskRoot.style.find((declaration) => declaration.name === "text-align")?.value;
         const anchor = alignment === "right" || alignment === "end" ? "end" : alignment === "left" || alignment === "start" ? "start" : "middle";
@@ -310,17 +320,17 @@ function renderElement(
           ? blockAlignment === "flex-start" ? "0" : blockAlignment === "flex-end" ? "100%" : "50%"
           : String(blockAlignment === "flex-start" ? paddingTop : blockAlignment === "flex-end" ? maskHeight - paddingBottom : (paddingTop + maskHeight - paddingBottom) / 2);
         const baseline = blockAlignment === "flex-start" ? "text-before-edge" : blockAlignment === "flex-end" ? "text-after-edge" : "central";
-        const textStyle = [css(maskRoot.style), ...exactFontStyle(maskRoot, context.stableId), "fill:currentColor"].filter(Boolean).join(";");
-        return `<text${attributes(maskRoot.attributes)} x="${x}" y="${y}" text-anchor="${anchor}" dominant-baseline="${baseline}" style="${escapeHtml(textStyle)}">${escapeHtml(maskRoot.text)}</text>`;
+        const textStyle = `${sourcePresentation.inlineStyle};fill:currentColor`;
+        return `<text ${sourcePresentation.commonAttributes} x="${x}" y="${y}" text-anchor="${anchor}" dominant-baseline="${baseline}" style="${escapeHtml(textStyle)}">${escapeHtml(maskRoot.text)}</text>`;
       }
       if (maskRoot.kind === "text-flow" || maskRoot.kind === "path-text") {
         return `<foreignObject x="0" y="0" width="100%" height="100%"><div xmlns="http://www.w3.org/1999/xhtml" style="position:relative;width:100%;height:100%">${renderOwned(maskRoot)}</div></foreignObject>`;
       }
       if (maskRoot.kind === "image") {
-        return `<image x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" href="${escapeHtml(hyperframesResourceUri(maskRoot.artifact.resource))}" style="${escapeHtml(css(maskRoot.style))}"/>`;
+        return `<image ${sourcePresentation.common} x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" href="${escapeHtml(hyperframesResourceUri(maskRoot.artifact.resource))}"/>`;
       }
       if (maskRoot.kind === "surface" && maskRoot.surface.timing.kind === "still") {
-        return `<image data-hypit-surface-resource="${maskRoot.surface.artifact.resource}" x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" href="${escapeHtml(hyperframesResourceUri(maskRoot.surface.artifact.resource))}" style="${escapeHtml(css(maskRoot.style))}"/>`;
+        return `<image ${sourcePresentation.common} data-hypit-surface-resource="${maskRoot.surface.artifact.resource}" x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" href="${escapeHtml(hyperframesResourceUri(maskRoot.surface.artifact.resource))}"/>`;
       }
       throw new Error(`Local mask ${element.id} requires a terminal owned text, image or still Surface mask source.`);
     })();

package/packages/hyperframes/src/project.ts

@@ -12,9 +12,10 @@ export type HyperframesArtifactReader = (
   artifact: BlobRef,
   signal?: AbortSignal,
 ) => Promise<Uint8Array | AsyncIterable<Uint8Array>>;
+/** Inspect the completed staged file; its lifetime belongs to the staging caller. */
 export type HyperframesSurfaceValidator = (
   surface: CompositableSurfaceRef,
-  bytes: Uint8Array,
+  path: string,
   signal?: AbortSignal,
 ) => Promise<void>;
 
@@ -39,9 +40,7 @@ function extension(mediaType: string): string {
 /**
  * Lay one document out as a directory HyperFrames can render.
  *
- * The same layout serves a local render and a distributed one: the local
- * Provider serves it to the capture engine, and the AWS Provider tars it into a site. If
- * the two laid it out differently, one Need would name two different projects.
+ * A local or hosted Provider can serve the same staged document to its capture engine.
  * Resource names are local to this staged project and carry no content claim.
  */
 export async function stageHyperframesProject(options: {
@@ -63,25 +62,25 @@ export async function stageHyperframesProject(options: {
   await mkdir(artifactDirectory, { recursive: true });
   const paths = new Map<string, string>();
   const surfaces = new Map(document.surfaces.map((surface) => [surface.artifact.resource, surface]));
-  await Promise.allSettled(document.artifacts.map(async (artifact) => {
+  await Promise.allSettled(document.artifacts.map(async (artifact, index) => {
     try {
       signal.throwIfAborted();
-      const name = `${artifact.resource}${extension(artifact.mediaType)}`;
+      // Resource identities are portable protocol values, not filesystem names.
+      const name = `asset-${index}${extension(artifact.mediaType)}`;
       const opened = await read(artifact, signal);
       signal.throwIfAborted();
       const chunks = opened instanceof Uint8Array
         ? (async function* () { yield opened; })()
         : opened;
       const surface = surfaces.get(artifact.resource);
-      const retained: Uint8Array[] = [];
       let size = 0;
-      const target = await open(join(artifactDirectory, name), "w");
+      const path = join(artifactDirectory, name);
+      const target = await open(path, "w");
       try {
         for await (const chunk of chunks) {
           signal.throwIfAborted();
-          await target.write(chunk);
+          await target.writeFile(chunk);
           size += chunk.byteLength;
-          if (surface !== undefined) retained.push(Uint8Array.from(chunk));
         }
       } finally {
         await target.close();
@@ -89,17 +88,9 @@ export async function stageHyperframesProject(options: {
       if (size !== artifact.size) {
         throw new Error(`HyperFrames Artifact ${artifact.resource} size differs`);
       }
-      const bytes = surface === undefined ? undefined : (() => {
-        const value = new Uint8Array(size);
-        let offset = 0;
-        for (const chunk of retained) {
-          value.set(chunk, offset);
-          offset += chunk.byteLength;
-        }
-        return value;
-      })();
       if (surface !== undefined) {
-        await options.validateSurface!(structuredClone(surface), bytes!.slice(), signal);
+        // The validator borrows the completed staged file for this call only.
+        await options.validateSurface!(structuredClone(surface), path, signal);
       }
       paths.set(artifact.resource, `./artifacts/${name}`);
     } catch (error) {

package/packages/media-execution/README.md

@@ -26,6 +26,13 @@ deployments can reuse the same functions to preserve stream selection, timing, c
 This is not an author package, Provider, queue or Core extension. It performs no endpoint selection,
 credential lookup or SVML parsing.
 
+`verifyCompositableSurfaceFile({ surface, path, ... })` inspects a file already staged by an execution
+owner. That owner must keep it unchanged until the call settles, including cancellation; inspection
+neither copies nor removes it. `verifyCompositableSurfaceBytes({ surface, bytes, ... })` remains a
+convenience wrapper for callers that have bytes, creates its own temporary file, and removes that
+file only after probing has settled. Both use the same decoded Surface checks and return no extra
+result facts. Filesystem paths belong to this Node execution boundary, not to Surface or Blob refs.
+
 Audio gain envelopes and audible subranges are evaluated per sample after tempo/looping and Clip
 fades, before the requested range is cropped. Original source and envelope progress therefore survive
 local silence and range rendering. This is generic AudioProgramPlan execution, independent of author

package/packages/media-execution/src/execute.ts

@@ -33,6 +33,7 @@ import {
   } from "@hypit/protocol";
 import type { BlobRef, CanonicalValue, StoredValue } from "@hypit/protocol";
 
+import { mediaProcessEnv } from "./process-env.js";
 import { parseMediaInspection } from "./probe.js";
 import {
   compositeAnimatedWebpFrame,
@@ -98,10 +99,7 @@ async function runProcess(args: {
       shell: false,
       windowsHide: true,
       stdio: ["ignore", "pipe", "pipe"],
-      env: {
-        PATH: process.env.PATH ?? "",
-        ...(args.sharedLibraryPath === undefined ? {} : { LD_LIBRARY_PATH: args.sharedLibraryPath }),
-      },
+      env: mediaProcessEnv(args.sharedLibraryPath === undefined ? undefined : { LD_LIBRARY_PATH: args.sharedLibraryPath }),
     });
     const stdout: Buffer[] = [];
     let stdoutBytes = 0;
@@ -678,8 +676,10 @@ export async function executeNormalizeMedia(
         "scale=trunc(iw*max(sar\\,1)/2)*2:trunc(ih*max(1/sar\\,1)/2)*2",
         "setsar=1",
       ].join(",");
+      // FFmpeg enables autorotation by default. Its positive boolean option changed
+      // syntax across releases; no override is needed to materialize source rotation.
       const visualInput = animation === undefined
-        ? [...encoding.inputArgs, "-autorotate", "-i", input, "-map", `0:${plan.video.index}`]
+        ? [...encoding.inputArgs, "-i", input, "-map", `0:${plan.video.index}`]
         : ["-f", "concat", "-safe", "0", "-i", await animatedWebpConcat(env, animation, work), "-map", "0:v:0"];
       // The execution format must retain the source's alpha while materializing
       // the program clock. Both encodings publish the same SynchronizedMedia type.

package/packages/media-execution/src/index.ts

@@ -10,7 +10,7 @@ export {
   executeTransformMedia,
 } from "./execute.js";
 export { parseMediaInspection } from "./probe.js";
-export { verifyCompositableSurfaceBytes } from "./surface.js";
+export { verifyCompositableSurfaceBytes, verifyCompositableSurfaceFile } from "./surface.js";
 export { probeMediaToolchain } from "./toolchain.js";
 export type { MediaToolchainState } from "./toolchain.js";
 export type * from "./execute.js";

package/packages/media-execution/src/process-env.ts

@@ -0,0 +1,20 @@
+const windowsProcessCreation = ["PATHEXT", "SYSTEMROOT", "WINDIR", "ComSpec"] as const;
+
+/**
+ * ffmpeg and ffprobe are started as PATH executables. The Host environment is
+ * not forwarded, so credential values stay out of those processes. Windows still
+ * needs the process-creation variables CreateProcess uses to resolve `.exe`.
+ */
+export function mediaProcessEnv(
+  extra?: Readonly<Record<string, string>>,
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { PATH: process.env.PATH ?? "" };
+  if (process.platform === "win32") {
+    for (const name of windowsProcessCreation) {
+      const value = process.env[name];
+      if (value !== undefined && value.length > 0) env[name] = value;
+    }
+  }
+  if (extra !== undefined) Object.assign(env, extra);
+  return env;
+}