@hypit/hypit 0.1.12 → 0.1.14

package/README.md

@@ -140,13 +140,47 @@ commands and the repository layout.
   </tr>
   <tr>
     <td>Questions</td>
-    <td><a href="https://discord.gg/85hnyQnxpn">Discord</a> or <a href="https://t.me/hypit">Telegram</a></td>
+    <td><a href="https://discord.gg/85hnyQnxpn">Discord</a> or <a href="https://t.me/hypitai">Telegram</a></td>
+  </tr>
+</table>
+
+## Launch Partner
+
+<table>
+  <tr>
+    <td width="220" align="center">
+      <a href="https://openagents.org/blog/posts/2026-09-08-pilot-user-program-zh-hypit"><img alt="OpenAgents" src="./docs/public/openagents.png" width="180"></a>
+    </td>
+    <td>OpenAgents Workspace is a product that helps you manage AI agents, allowing you to invoke agents running on any device (whether on a mobile phone or computer) anytime, anywhere. Agents can collaborate within the platform to help you complete tasks and boost efficiency. It currently supports integration with over 20 types of agents, including Claude, Codex, OpenClaw, and Hermes (Details on supported models: <a href="https://api-gateway.openagents.org/static/index.html">https://api-gateway.openagents.org/static/index.html</a>)</td>
+  </tr>
+  <tr>
+    <td width="220" align="center">
+      <a href="https://monid.ai?fpr=alvin-45480b">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="./docs/public/monid-logo-white.svg">
+          <img alt="Monid" src="./docs/public/monid-logo-blue.svg" width="150">
+        </picture>
+      </a>
+    </td>
+    <td>Monid is the OpenRouter for agent tools: one key, one wallet, hundreds of tools, billed per call. Hypit can route Seedance video, images, speech and word-level transcription to Monid.</td>
+  </tr>
+  <tr>
+    <td width="220" align="center">
+      <a href="https://www.hiapi.ai"><img alt="HiAPI" src="./docs/public/hiapi.png" width="165"></a>
+    </td>
+    <td>HiAPI is a unified API platform for AI image, video, audio, and language models. Connect GPT Image 2.5, Seedance 2.0, Veo 3.1, Kling, Wan, and other popular models through one platform. Pay as you go with no monthly fee, with free trial credits available for new users.</td>
   </tr>
 </table>
 
 ## ⭐ Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=hypit-ai/hypit&type=Date)](https://www.star-history.com/#hypit-ai/hypit&Date)
+<a href="https://www.star-history.com/?repos=hypit-ai%2Fhypit&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=hypit-ai/hypit&type=date&theme=dark&logscale&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=hypit-ai/hypit&type=date&logscale&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=hypit-ai/hypit&type=date&logscale&legend=top-left" />
+ </picture>
+</a>
 
 ## Contributors
 

package/bin/hypit.mjs

@@ -19,8 +19,6 @@ process.emitWarning = function hypitWarning(warning, ...args) {
 };
 
 const distributionRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-process.env.HYPIT_CLI_LAUNCHER ??= import.meta.filename;
-process.env.HYPIT_DISTRIBUTION_ROOT ??= distributionRoot;
 register();
 const {
   installDistributionPackageResolution,

package/dist/public/model-kit.d.ts

@@ -380,6 +380,15 @@ type GenerationMediaValue = {
 };
 type GenerationPortValue = string | number | boolean | GenerationMediaValue;
 
+/**
+ * The one request envelope every exact model uses. A Provider reads ports by
+ * name and never learns a model-specific field layout, so the same wire mapping
+ * mechanism serves every model and every service reselling it.
+ */
+type GenerationRequest = {
+    /** An absent port is an omitted key. A present port always carries at least one value. */
+    readonly ports: Readonly<Record<string, readonly GenerationPortValue[]>>;
+};
 /**
  * A request while graph inputs are still being attached. It is deliberately a
  * Providers can only receive the finalized request after the exact model
@@ -423,6 +432,10 @@ type ExactModelEndpointSpec = {
     readonly requestTypeName: string;
     readonly producerName: string;
     readonly ports: GenerationPortTable;
+    /** Additional complete-request rules, after port and supplied-input validation. */
+    readonly validateRequest?: (request: GenerationRequest) => void;
+    /** Pure, synchronous checks of supplied values, in drafts and complete requests; throw to reject. */
+    readonly validateInputs?: (inputs: GenerationRequestDraft) => void;
 };
 type ExactModelEndpoint = {
     readonly key: string;
@@ -435,6 +448,9 @@ type ExactModelEndpoint = {
     readonly mediaBindings: Readonly<Record<string, ExactModelMediaBindingEndpoint>>;
     readonly textBindings: Readonly<Record<string, ExactModelTextBindingEndpoint>>;
     readonly ports: GenerationPortTable;
+    readonly validateRequest: (request: unknown) => void;
+    readonly validateDraft: (draft: unknown) => void;
+    readonly sealRequest: (ports: GenerationRequest["ports"]) => GenerationRequest;
     readonly fragment: ReturnType<typeof sealGraphFragment>;
 };
 type ExactModelMediaBindingEndpoint = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",
@@ -168,6 +168,7 @@
   ],
   "scripts": {
     "pack:distribution": "node scripts/pack-distribution.mjs",
+    "check:distribution": "node scripts/check-distribution.mjs",
     "build:public-types": "node scripts/build-public-types.mjs",
     "check": "tsc -p tsconfig.json --noEmit",
     "docs:dev": "vitepress dev docs",
@@ -202,6 +203,7 @@
     "@hypit/comment-sticker-studio": "workspace:*",
     "@hypit/composition": "workspace:*",
     "@hypit/credential-store-env": "workspace:*",
+    "@hypit/credential-store-file": "workspace:*",
     "@hypit/credential-store-os": "workspace:*",
     "@hypit/deck-track": "workspace:*",
     "@hypit/deck-track-studio": "workspace:*",

package/packages/cli/README.md

@@ -148,6 +148,9 @@ from a lookup that still needs the Build's Runtime or correct project selection.
 Worker process log instead, for Runtime startup or process-level failures.
 
 Project context resolution is owned by [`@hypit/project-context-node`](../project-context-node/README.md).
+History Source filters resolve existing filesystem links before comparing project-relative Result
+paths. A deleted Source or directory remains queryable: only its existing ancestor is resolved and
+the missing path suffix is retained. This is local argument handling, with no saved alias inventory.
 CLI, Studio and creation tools call that same package; the CLI is not another environment owner.
 
 `doctor`, `programs up|status|down`, and `runtime up` accept repeated `--endpoint <instance>` values.

package/packages/cli/package.json

@@ -27,6 +27,7 @@
     "typescript": "5.9.3"
   },
   "devDependencies": {
+    "@hypit/runtime-local": "workspace:*",
     "@hypit/markup": "workspace:*",
     "@hypit/run-markup": "workspace:*",
     "@hypit/workspace-fs-node": "workspace:*"

package/packages/cli/src/commands/environment.ts

@@ -364,13 +364,10 @@ export async function runEnvironmentCommand(input: {
     }
     const credentialsControl = await (await runtimeHost(runtimeProfile)).openCredentials(args.endpoint);
     try {
-      let credentials = await credentialsControl.credentials(args.endpoint);
-      if (args.slot !== undefined) credentials = credentials.filter((item) => item.slot === args.slot);
-      if (credentials.length === 0) throw new Error(`Endpoint ${args.endpoint} has no matching credential`);
-      if (args.slot === undefined && credentials.length > 1 && args.action !== "status") {
-        throw new Error(`Endpoint ${args.endpoint} has several credentials; select one with --slot`);
-      }
       if (args.action === "status") {
+        let credentials = await credentialsControl.credentials(args.endpoint);
+        if (args.slot !== undefined) credentials = credentials.filter((item) => item.slot === args.slot);
+        if (credentials.length === 0) throw new Error(`Endpoint ${args.endpoint} has no matching credential`);
         const view = credentials.slice(0, args.limit).map((item) => ({
           endpoint: item.endpoint,
           slot: item.slot,
@@ -397,7 +394,15 @@ export async function runEnvironmentCommand(input: {
             : `login opens OAuth: ${item.acquisition.authorizationEndpoint}`;
           return `${item.slot}: ${item.configured ? "configured" : "missing"} · ${item.writable ? "writable" : "read-only"} · ${entry}`;
         }));
-      } else if (args.action === "login") {
+        return;
+      }
+      let credentials = await credentialsControl.describeCredentials(args.endpoint);
+      if (args.slot !== undefined) credentials = credentials.filter((item) => item.slot === args.slot);
+      if (credentials.length === 0) throw new Error(`Endpoint ${args.endpoint} has no matching credential`);
+      if (args.slot === undefined && credentials.length > 1) {
+        throw new Error(`Endpoint ${args.endpoint} has several credentials; select one with --slot`);
+      }
+      if (args.action === "login") {
         const [item] = credentials;
         if (item === undefined) throw new Error(`Endpoint ${args.endpoint} has no matching credential`);
         if (!item.writable) {

package/packages/cli/src/commands/results.ts

@@ -1,4 +1,5 @@
-import { resolve } from "node:path";
+import { realpath } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
 
 import type { BuildResultRepository } from "@hypit/build-result";
 
@@ -20,6 +21,21 @@ export function isProjectResultCommand(args: CliCommand): args is ProjectResultC
     || args.command === "get" || (args.command === "result" && args.action === "edit");
 }
 
+/** History can name a deleted Source. Resolve existing directory links, keeping the absent suffix. */
+async function historySourcePath(path: string): Promise<string> {
+  let existing = resolve(path);
+  const suffix: string[] = [];
+  while (true) {
+    try { return resolve(await realpath(existing), ...suffix); }
+    catch (error) {
+      const parent = dirname(existing);
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT" || parent === existing) throw error;
+      suffix.unshift(basename(existing));
+      existing = parent;
+    }
+  }
+}
+
 /** Execute commands that need only project-owned Result history, never a Runtime. */
 export async function runProjectResultCommand(input: {
   readonly args: ProjectResultCommand;
@@ -62,7 +78,7 @@ export async function runProjectResultCommand(input: {
   }
 
   if (args.command === "history") {
-    const source = args.source === undefined ? undefined : resolve(args.source);
+    const source = args.source === undefined ? undefined : await historySourcePath(args.source);
     const page = await browseBuildOutputHistory(repository, {
       projectRoot,
       output: args.outputName,
@@ -177,7 +193,7 @@ export async function runProjectResultCommand(input: {
     kind: exported.kind,
     path: exported.path,
   };
-  const path = projectPath(exported.path, projectRoot);
+  const path = projectPath(await realpath(exported.path), projectRoot);
   write(machine, `Exported ${exported.output} → ${path}`, "success",
     args.presentation.verbose ? [
       ["Build", exported.build],

package/packages/cli/src/main.ts

@@ -148,7 +148,8 @@ export async function runCli(
     }, "Runtime Profile created", "success", [
       ["Profile", selected.profile],
       ["Project", selected.projectRoot],
-    ], ["No package was installed, no service was contacted and no Worker was started."]);
+    ], ["Review the Profile’s credential stores and Endpoint settings before login or runtime up.",
+      "No package was installed, no service was contacted and no Worker was started."]);
     return;
   }
   if (args.command === "runtime" && args.action === "use") {

package/packages/cli/src/oauth.ts

@@ -28,6 +28,54 @@ function tokenExpiry(value: { readonly expires_at?: unknown; readonly expires_in
   return seconds === undefined ? undefined : Date.now() + seconds * 1_000;
 }
 
+export type AuthorizeBrowserLaunch = {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly windowsVerbatimArguments: boolean;
+  readonly env?: Readonly<Record<string, string>>;
+};
+
+/**
+ * Open the authorize URL in a browser. Windows `cmd /c start` treats `&` as a command
+ * separator unless the URL is a later quoted token after an explicit window title.
+ */
+export function authorizeBrowserLaunch(
+  url: string,
+  options: { readonly platform?: NodeJS.Platform; readonly comSpec?: string } = {},
+): AuthorizeBrowserLaunch {
+  const platform = options.platform ?? process.platform;
+  if (platform === "win32") {
+    // Expand one environment value after cmd parses the command. Interpolating the
+    // URL into command text would also expand percent sequences inside the URL.
+    const serialized = new URL(url).href;
+    return {
+      command: options.comSpec ?? process.env.ComSpec ?? "cmd.exe",
+      args: ["/d", "/s", "/v:off", "/c", 'start "" "%HYPIT_OAUTH_AUTHORIZE_URL%"'],
+      windowsVerbatimArguments: true,
+      env: { HYPIT_OAUTH_AUTHORIZE_URL: serialized },
+    };
+  }
+  return {
+    command: platform === "darwin" ? "open" : "xdg-open",
+    args: [url],
+    windowsVerbatimArguments: false,
+  };
+}
+
+function openAuthorizeUrl(url: string): void {
+  const launch = authorizeBrowserLaunch(url);
+  const child = spawn(launch.command, [...launch.args], {
+    stdio: "ignore",
+    detached: true,
+    windowsHide: true,
+    windowsVerbatimArguments: launch.windowsVerbatimArguments,
+    ...(launch.env === undefined ? {} : { env: { ...process.env, ...launch.env } }),
+  });
+  // A missing opener must not crash the CLI; the URL is already on the progress line.
+  child.once("error", () => undefined);
+  child.unref();
+}
+
 /** Acquire one OAuth credential from the exact data declared by its Endpoint package. */
 export async function acquireOAuthCredential(
   acquisition: CredentialAcquisition,
@@ -102,13 +150,8 @@ export async function acquireOAuthCredential(
   authorize.searchParams.set("code_challenge", challenge);
   authorize.searchParams.set("code_challenge_method", "S256");
   options.onProgress?.(`Opening sign-in: ${authorize}`);
-  if (options.open === undefined) {
-    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
-    const openerArgs = process.platform === "win32" ? ["/c", "start", "", authorize.toString()] : [authorize.toString()];
-    spawn(opener, openerArgs, { stdio: "ignore", detached: true, windowsHide: true }).unref();
-  } else {
-    options.open(authorize.toString());
-  }
+  if (options.open === undefined) openAuthorizeUrl(authorize.toString());
+  else options.open(authorize.toString());
   const code = await callback;
   options.onProgress?.("Authorization returned. Exchanging token…");
   const deadline = AbortSignal.timeout(acquisition.requestTimeoutMs);

package/packages/cli/src/output.ts

@@ -1,4 +1,4 @@
-import { relative, resolve } from "node:path";
+import { relative, resolve, sep } from "node:path";
 
 import type { CanonicalValue } from "@hypit/protocol";
 
@@ -279,7 +279,7 @@ function glyph(io: CliIo, unicode: string, ascii: string): string {
 function shortPath(path: string): string {
   const absolute = resolve(path);
   const local = relative(process.cwd(), absolute);
-  return local.length > 0 && !local.startsWith("..") ? local : absolute;
+  return local.length > 0 && local !== ".." && !local.startsWith(`..${sep}`) ? local : absolute;
 }
 
 function facts(rows: readonly (readonly [string, string])[], colors: Palette): string[] {

package/packages/cli/src/source-discovery.ts

@@ -1,5 +1,5 @@
 import { readFile, realpath } from "node:fs/promises";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 
 import { authorFrontendsFromHostFacets, prepareAuthorSource } from "@hypit/elaborator";
 import type { AuthorFrontend } from "@hypit/elaborator";
@@ -12,7 +12,7 @@ import { parseSourceHeader, sourceFrontendPackageAbi } from "@hypit/source";
 
 function isWithin(root: string, path: string): boolean {
   const relation = relative(root, path);
-  return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
+  return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
 }
 
 function selectedPackage(request: string): string {

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/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); }