hyperframes 0.8.140 → 0.8.142

package/dist/{screenshotCapture-ECBTLCU6.js → screenshotCapture-TEUIWXWN.js}

@@ -4,13 +4,20 @@ import { dirname as __hf_dirname } from "node:path";
 var require = __hf_createRequire(import.meta.url);
 var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
+import {
+  DEFAULT_MAX_SCREENSHOTS
+} from "./chunk-P36MALQF.js";
 import {
   isDegradableEvaluateTimeoutError
 } from "./chunk-AWNBM3MZ.js";
 import {
+  CaptureDirRefusedError,
   ensureCaptureDirSync,
   writeCaptureFileSync
 } from "./chunk-MRF4AMKD.js";
+import {
+  normalizeErrorMessage
+} from "./chunk-KNU5COPB.js";
 import "./chunk-M2WBOQ2Q.js";
 
 // src/capture/screenshotCapture.ts
@@ -35,13 +42,15 @@ async function captureFullPagePlate(page, screenshotsDir, budget = {}) {
     const docHeight = await page.evaluate(
       `Math.max(document.body.scrollHeight, document.documentElement.scrollHeight)`
     );
-    if (docHeight > MAX_PLATE_HEIGHT_PX) return null;
-    if ((budget.remainingMs?.() ?? 1) <= 0) return null;
+    if (docHeight > MAX_PLATE_HEIGHT_PX) return { kind: "omitted", reason: "height-limit" };
+    if ((budget.remainingMs?.() ?? 1) <= 0) return { kind: "omitted", reason: "budget-exhausted" };
     const buffer = await page.screenshot({ type: "png", fullPage: true });
     const produced = pngHeight(buffer);
-    if (produced != null && produced > MAX_PLATE_HEIGHT_PX) return null;
+    if (produced != null && produced > MAX_PLATE_HEIGHT_PX)
+      return { kind: "omitted", reason: "height-limit" };
     writeCaptureFileSync(join(screenshotsDir, "full-page.png"), buffer);
-    return "screenshots/full-page.png";
+    budget.files?.push("screenshots/full-page.png");
+    return { kind: "captured", file: "screenshots/full-page.png" };
   } finally {
     try {
       await page.evaluate(
@@ -57,9 +66,21 @@ async function captureFullPagePlate(page, screenshotsDir, budget = {}) {
 async function captureScrollScreenshots(page, outputDir, budget = {}) {
   const screenshotsDir = join(outputDir, "screenshots");
   ensureCaptureDirSync(outputDir, screenshotsDir);
-  const MAX_SCREENSHOTS = 20;
-  const filePaths = [];
-  if ((budget.remainingMs?.() ?? 1) <= 0) return filePaths;
+  const maxScreenshots = budget.maxScreenshots ?? DEFAULT_MAX_SCREENSHOTS;
+  const viewportLimit = Math.max(1, maxScreenshots - 1);
+  const filePaths = budget.files ?? [];
+  filePaths.length = 0;
+  const filenames = /* @__PURE__ */ new Set();
+  const result = { files: filePaths, interruption: null };
+  const budgetSpent = () => {
+    if ((budget.remainingMs?.() ?? 1) > 0) return false;
+    result.interruption = {
+      reason: "budget-exhausted",
+      message: "post-navigation budget exhausted during screenshots"
+    };
+    return true;
+  };
+  if (budgetSpent()) return result;
   try {
     await page.evaluate(() => {
       const selectors = [
@@ -126,50 +147,49 @@ async function captureScrollScreenshots(page, outputDir, budget = {}) {
       `Math.max(document.body.scrollHeight, document.documentElement.scrollHeight)`
     );
     const viewportHeight = await page.evaluate(`window.innerHeight`);
-    const step = Math.floor(viewportHeight * 0.7);
-    const positions = [0];
-    for (let y = step; y < scrollHeight - viewportHeight; y += step) {
-      positions.push(y);
-    }
+    const step = Math.max(1, Math.floor(viewportHeight * 0.7));
     const lastPos = Math.max(0, scrollHeight - viewportHeight);
-    if (positions[positions.length - 1] !== lastPos) {
-      positions.push(lastPos);
-    }
-    let finalPositions = positions;
-    if (positions.length > MAX_SCREENSHOTS) {
-      finalPositions = [positions[0]];
-      const stride = (positions.length - 1) / (MAX_SCREENSHOTS - 1);
-      for (let i = 1; i < MAX_SCREENSHOTS - 1; i++) {
-        finalPositions.push(positions[Math.round(i * stride)]);
-      }
-      finalPositions.push(positions[positions.length - 1]);
+    const positionCount = Math.ceil(lastPos / step) + 1;
+    const count = Math.min(viewportLimit, positionCount);
+    const finalPositions = [];
+    for (let i = 0; i < count; i++) {
+      const positionIndex = count === 1 ? 0 : Math.round(i * (positionCount - 1) / (count - 1));
+      finalPositions.push(Math.min(positionIndex * step, lastPos));
     }
     for (let i = 0; i < finalPositions.length; i++) {
-      if ((budget.remainingMs?.() ?? 1) <= 0) break;
+      if (budgetSpent()) break;
       await page.evaluate(`window.scrollTo(0, ${finalPositions[i]})`);
       await new Promise((r) => setTimeout(r, 400));
       const pct = Math.round(
         finalPositions[i] / Math.max(1, scrollHeight - viewportHeight) * 100
       );
-      const filename = `scroll-${String(Math.min(pct, 100)).padStart(3, "0")}.png`;
+      const stem = `scroll-${String(Math.min(pct, 100)).padStart(3, "0")}`;
+      let filename = `${stem}.png`;
+      if (filenames.has(filename)) filename = `${stem}-${i}.png`;
+      filenames.add(filename);
       const filePath = join(screenshotsDir, filename);
-      if ((budget.remainingMs?.() ?? 1) <= 0) break;
+      if (budgetSpent()) break;
       const buffer = await page.screenshot({ type: "png" });
       writeCaptureFileSync(filePath, buffer);
       filePaths.push(`screenshots/${filename}`);
     }
     await page.evaluate(`window.scrollTo(0, 0)`);
     await new Promise((r) => setTimeout(r, 200));
-    if ((budget.remainingMs?.() ?? 1) > 0) {
-      const plate = await captureFullPagePlate(page, screenshotsDir, budget);
-      if (plate) filePaths.push(plate);
+    if (filePaths.length < maxScreenshots && !budgetSpent()) {
+      const plate = await captureFullPagePlate(page, screenshotsDir, {
+        ...budget,
+        files: filePaths
+      });
+      if (plate.kind === "omitted" && plate.reason === "budget-exhausted") budgetSpent();
     }
   } catch (err) {
-    if (isDegradableEvaluateTimeoutError(err)) {
-      throw err;
-    }
+    if (err instanceof CaptureDirRefusedError) throw err;
+    result.interruption = {
+      reason: isDegradableEvaluateTimeoutError(err) ? "request-timeout" : "internal-error",
+      message: normalizeErrorMessage(err)
+    };
   }
-  return filePaths;
+  return result;
 }
 export {
   MAX_PLATE_HEIGHT_PX,

package/dist/{sherpa-ZW6PWJS4.js → sherpa-ZYTNFHD5.js}

@@ -21,26 +21,26 @@ import "./chunk-EOVYQ3IG.js";
 import {
   getPreparedWavDurationSeconds,
   prepareWav
-} from "./chunk-F3SPK6SO.js";
+} from "./chunk-7FCDA4RH.js";
 import {
   emitWords
 } from "./chunk-6IHWCZ3W.js";
 import {
   stoppedByCancelSignal
-} from "./chunk-LQG6GPVK.js";
+} from "./chunk-FWRNQOLT.js";
 import "./chunk-6BEFEWFB.js";
 import "./chunk-PXSM4HPB.js";
 import "./chunk-WCJGTLPF.js";
 import "./chunk-TVCRUG2S.js";
 import "./chunk-AMKC3AXA.js";
-import "./chunk-TPECLKPA.js";
-import "./chunk-6U3MN4HW.js";
+import "./chunk-IDX52YJN.js";
+import "./chunk-DPHJKWP5.js";
 import "./chunk-A4KQZXZI.js";
 import "./chunk-USDEMXXL.js";
-import "./chunk-QP3BRKGF.js";
+import "./chunk-YFT3BL7N.js";
 import "./chunk-OZUQF4NB.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-B3I3XJ47.js";
+import "./chunk-J4UX3RS3.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-YA62XGXS.js";
 import "./chunk-OFQWTKPW.js";
@@ -50,8 +50,7 @@ import "./chunk-RQVDTPGD.js";
 import "./chunk-LAOCA3MQ.js";
 import "./chunk-LCSMOLGX.js";
 import "./chunk-TWWSYAKJ.js";
-import "./chunk-WY5OODN5.js";
-import "./chunk-24OWOBQH.js";
+import "./chunk-IW2CKH6A.js";
 import "./chunk-JFKL3WAE.js";
 import "./chunk-HBBJFK6I.js";
 import "./chunk-PJ3HDUCY.js";

package/dist/skills/hyperframes-cli/references/cloud.md

@@ -30,7 +30,7 @@ npx hyperframes auth refresh            # force-refresh an OAuth token before a
 npx hyperframes auth logout             # clear the stored credential
 ```
 
-Credential resolution order (first match wins): `HEYGEN_API_KEY`, then `HYPERFRAMES_API_KEY`, then `~/.heygen/credentials`. Point at a different backend with `HEYGEN_API_URL` (default `https://api.heygen.com`).
+Credential resolution order (first match wins): `HEYGEN_API_KEY`, then `HYPERFRAMES_API_KEY`, then `HEYGEN_ACCESS_TOKEN` (an OAuth token a host app injects; never refreshed or saved), then `~/.heygen/credentials`. Point at a different backend with `HEYGEN_API_URL` (default `https://api.heygen.com`).
 
 ## The render pipeline
 

package/dist/skills/media-use/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: media-use
-description: Agent Media OS for a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal. When the host app provides its own music or sound-effect tools, use those for music and sound effects; `resolve --type bgm|sfx` needs the heygen CLI.
+description: Agent Media OS for a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal. When the host app provides its own music or sound-effect tools, use those for music and sound effects; `resolve --type bgm|sfx` needs the heygen CLI. When `HEYGEN_API_BASE` is set, HeyGen calls go through that host with no CLI sign-in.
 ---
 
 **Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
@@ -9,11 +9,13 @@ description: Agent Media OS for a HyperFrames project. Resolve BGM, SFX, image,
 
 The media OS for HyperFrames: resolve · generate · operate · remember — every media type, one skill, zero context noise.
 
-First run, when you will use HeyGen media (catalog search, TTS, avatar video): install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.
+Only when `HEYGEN_API_BASE` is set in your environment (a host app set it and pays for HeyGen with its own key): HeyGen media is already paid for. Do not ask the person to install or sign in to the `heygen` CLI and do not offer its OAuth allowance; catalog search, TTS and avatar calls here go through the host. When that same host also gives you its own HeyGen tools, use those first. When a call through the host is refused, tell the person the host's message as written (it names the fix, such as adding or replacing the key in the app's Settings) and stop; do not switch to another provider unless they ask.
 
-Music and sound effects inside a host app: when the app you run in gives you its own music or sound-effect tools, use those. `resolve --type bgm` and `--type sfx` search the HeyGen catalog through the `heygen` CLI; without it they fail and say so (`sfx` still answers from its bundled library).
+First run otherwise (no `HEYGEN_API_BASE`), when you will use HeyGen media (catalog search, TTS, avatar video): install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.
 
-Before generating a voiceover or an avatar video, tell the person: signing in to the heygen CLI with OAuth (`heygen auth login --oauth`) gives a free allowance for TTS voiceover and avatar videos, while an API key bills API credits.
+Music and sound effects inside a host app: when the app you run in gives you its own music or sound-effect tools, use those. Without `HEYGEN_API_BASE`, `resolve --type bgm` and `--type sfx` search the HeyGen catalog through the `heygen` CLI; without it they fail and say so (`sfx` still answers from its bundled library).
+
+Without `HEYGEN_API_BASE`, before generating a voiceover or an avatar video, tell the person: signing in to the heygen CLI with OAuth (`heygen auth login --oauth`) gives a free allowance for TTS voiceover and avatar videos, while an API key bills API credits.
 
 ## Resolve — the one verb
 

package/dist/skills/media-use/audio/scripts/lib/heygen.mjs

@@ -1,16 +1,51 @@
 import { fetchMedia } from "../../../scripts/lib/media-fetch.mjs";
 // heygen.mjs — vendored HeyGen REST helpers (auth + transport) for the audio
 // pipeline. The credential resolver matches the hyperframes CLI auth: first
-// usable source wins — a host-injected OAuth $HEYGEN_ACCESS_TOKEN (Bearer) →
+// usable source wins — a host gateway ($HEYGEN_API_BASE with its own
+// $HEYGEN_API_KEY) → a host-injected OAuth $HEYGEN_ACCESS_TOKEN (Bearer) →
 // $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY → a nearby .env → ~/.heygen/
 // credentials (oauth → Bearer, else api_key → X-Api-Key; $HEYGEN_CONFIG_DIR
-// overrides the dir). Vendored so the skill ships standalone. Pure node.
+// overrides the dir). $HEYGEN_API_BASE moves every request to that host, as it
+// does for the heygen CLI; plain HTTP needs $HEYGEN_ALLOW_HTTP=1, as there.
+// Vendored so the skill ships standalone. Pure node.
 
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
 export const HEYGEN_BASE = "https://api.heygen.com/v3";
+
+// The v3 base every request goes to: $HEYGEN_API_BASE when a host app names its own gateway (HyperFrames Desktop
+// forwards it to HeyGen with the API key saved in its Settings), else HeyGen's public API. Plain HTTP carries the key
+// in the clear, so it needs $HEYGEN_ALLOW_HTTP=1, the heygen CLI's own rule.
+export function heygenBase() {
+  const host = process.env.HEYGEN_API_BASE?.trim().replace(/\/+$/, "");
+  if (!host) return HEYGEN_BASE;
+  if (host.startsWith("http://") && process.env.HEYGEN_ALLOW_HTTP !== "1")
+    throw new Error(
+      `HEYGEN_API_BASE (${host}) uses HTTP, which sends the key in plaintext. Set HEYGEN_ALLOW_HTTP=1 to allow it.`,
+    );
+  return `${host}/v3`;
+}
+
+// No base override, or one on HeyGen's own hosts (a canary or dev API).
+function heygenOwnBase() {
+  const host = process.env.HEYGEN_API_BASE?.trim();
+  if (!host) return true;
+  try {
+    const name = new URL(host).hostname;
+    return name === "heygen.com" || name.endsWith(".heygen.com");
+  } catch {
+    return false;
+  }
+}
+
+// A host gateway: the host named its own API base and the key that base accepts. It pays for every call, so it wins
+// over any other credential the environment carries.
+const hostGatewayKey = () =>
+  process.env.HEYGEN_API_BASE?.trim() && process.env.HEYGEN_API_KEY
+    ? process.env.HEYGEN_API_KEY
+    : null;
 export const HEYGEN_CLI_SOURCE_HEADERS = { "X-HeyGen-Source": "cli" };
 // Tool-attribution sent on EVERY media-use HeyGen call regardless of auth type, so
 // the backend can isolate media-use consumption from other free TTS / avatar video.
@@ -29,6 +64,10 @@ function envFileText(path) {
   }
 }
 
+// A host app sets these in the environment it spawns, never in a project file: a project's .env naming its own base
+// would send the person's shell HEYGEN_API_KEY to that host.
+const HOST_ONLY = new Set(["HEYGEN_API_BASE", "HEYGEN_ALLOW_HTTP"]);
+
 // Walk up ≤5 dirs from startDir; load the first .env (shell env always wins).
 export function loadEnvFromDir(startDir) {
   let dir = resolve(startDir);
@@ -48,7 +87,7 @@ export function loadEnvFromDir(startDir) {
           const end = val.indexOf(q, 1);
           val = end > 0 ? val.slice(1, end) : val.slice(1);
         }
-        if (!(key in process.env)) process.env[key] = val;
+        if (!HOST_ONLY.has(key) && !(key in process.env)) process.env[key] = val;
       }
       return;
     }
@@ -68,6 +107,10 @@ export function heygenCredential() {
 // (a folder, a locked ~/.heygen), so heygenAuthHeaders can say to fix that path: logging in again would fail there too.
 // Read without checking first, so the file cannot change between a check and the read.
 function resolveCredential() {
+  const gatewayKey = hostGatewayKey();
+  if (gatewayKey) return { headers: { "X-Api-Key": gatewayKey } };
+  // Every other credential belongs to HeyGen: a base on any other host gets none of them.
+  if (!heygenOwnBase()) return null;
   const accessToken = process.env.HEYGEN_ACCESS_TOKEN;
   if (accessToken) return { headers: { Authorization: `Bearer ${accessToken}` } };
   const envKey = process.env.HEYGEN_API_KEY || process.env.HYPERFRAMES_API_KEY;
@@ -144,7 +187,7 @@ export async function heygenJSON(path, { method = "GET", headers = {}, body } =
     opts.headers["Content-Type"] = "application/json";
     opts.body = JSON.stringify(body);
   }
-  const res = await fetch(`${HEYGEN_BASE}${path}`, opts);
+  const res = await fetch(`${heygenBase()}${path}`, opts);
   if (!res.ok) {
     const detail = await res.text().catch(() => "");
     const message = `HeyGen ${method} ${path} → HTTP ${res.status}${detail ? `\n${detail.slice(0, 300)}` : ""}`;

package/dist/skills/media-use/audio/scripts/lib/heygen.test.mjs

@@ -1,36 +1,47 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   heygenAuthHeaders,
   heygenAuthMethod,
+  heygenBase,
   heygenCredential,
+  heygenJSON,
   loadEnvFromDir,
 } from "./heygen.mjs";
 
+const HEYGEN_ENV = [
+  "HEYGEN_ACCESS_TOKEN",
+  "HEYGEN_API_KEY",
+  "HYPERFRAMES_API_KEY",
+  "HEYGEN_CONFIG_DIR",
+  "HEYGEN_API_BASE",
+  "HEYGEN_ALLOW_HTTP",
+];
+
+// Runs fn with every HeyGen variable unset, then puts them back; an async fn restores once it settles.
 function withCleanHeygenEnv(fn) {
-  const previousAccessToken = process.env.HEYGEN_ACCESS_TOKEN;
-  const previousApiKey = process.env.HEYGEN_API_KEY;
-  const previousHyperframesApiKey = process.env.HYPERFRAMES_API_KEY;
-  const previousConfigDir = process.env.HEYGEN_CONFIG_DIR;
+  const previous = Object.fromEntries(HEYGEN_ENV.map((name) => [name, process.env[name]]));
+  const restore = () => {
+    for (const [name, value] of Object.entries(previous)) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  };
+  for (const name of HEYGEN_ENV) delete process.env[name];
+  let result;
   try {
-    delete process.env.HEYGEN_ACCESS_TOKEN;
-    delete process.env.HEYGEN_API_KEY;
-    delete process.env.HYPERFRAMES_API_KEY;
-    delete process.env.HEYGEN_CONFIG_DIR;
-    return fn();
-  } finally {
-    if (previousAccessToken === undefined) delete process.env.HEYGEN_ACCESS_TOKEN;
-    else process.env.HEYGEN_ACCESS_TOKEN = previousAccessToken;
-    if (previousApiKey === undefined) delete process.env.HEYGEN_API_KEY;
-    else process.env.HEYGEN_API_KEY = previousApiKey;
-    if (previousHyperframesApiKey === undefined) delete process.env.HYPERFRAMES_API_KEY;
-    else process.env.HYPERFRAMES_API_KEY = previousHyperframesApiKey;
-    if (previousConfigDir === undefined) delete process.env.HEYGEN_CONFIG_DIR;
-    else process.env.HEYGEN_CONFIG_DIR = previousConfigDir;
+    result = fn();
+  } catch (error) {
+    restore();
+    throw error;
   }
+  if (result && typeof result.then === "function") return result.finally(restore);
+  restore();
+  return result;
 }
 
 test("heygenAuthHeaders does not tag API-key requests as CLI traffic, but still carries the media-use tool tag", () => {
@@ -138,6 +149,27 @@ test("loadEnvFromDir skips a .env folder and loads the .env file above it", () =
   }
 });
 
+test("a project's .env cannot name the HeyGen base, so a shell key never leaves for its host", () => {
+  withCleanHeygenEnv(() => {
+    const project = mkdtempSync(join(tmpdir(), "heygen-env-"));
+    writeFileSync(
+      join(project, ".env"),
+      "HEYGEN_API_BASE=https://proxy.example.com\nHEYGEN_ALLOW_HTTP=1\nMEDIA_USE_ENV_BASE_TEST=loaded\n",
+    );
+    try {
+      process.env.HEYGEN_API_KEY = "hg_shell_real";
+      loadEnvFromDir(project);
+      assert.equal(process.env.MEDIA_USE_ENV_BASE_TEST, "loaded");
+      assert.equal(process.env.HEYGEN_API_BASE, undefined);
+      assert.equal(process.env.HEYGEN_ALLOW_HTTP, undefined);
+      assert.equal(heygenBase(), "https://api.heygen.com/v3");
+    } finally {
+      delete process.env.MEDIA_USE_ENV_BASE_TEST;
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+});
+
 test("heygenAuthMethod returns null when the credentials path is a folder", () => {
   withCleanHeygenEnv(() => {
     const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
@@ -183,3 +215,78 @@ test("heygenAuthHeaders says to fix an unreadable credentials path, and to log i
     }
   });
 });
+
+test("heygenBase is HeyGen's public API unless a host names another", () => {
+  withCleanHeygenEnv(() => {
+    assert.equal(heygenBase(), "https://api.heygen.com/v3");
+    process.env.HEYGEN_API_BASE = "https://api-canary.heygen.com/";
+    assert.equal(heygenBase(), "https://api-canary.heygen.com/v3");
+  });
+});
+
+test("heygenBase refuses a plain-HTTP host unless HEYGEN_ALLOW_HTTP is set, as the heygen CLI does", () => {
+  withCleanHeygenEnv(() => {
+    process.env.HEYGEN_API_BASE = "http://127.0.0.1:4100";
+    assert.throws(() => heygenBase(), /HEYGEN_ALLOW_HTTP=1/);
+    process.env.HEYGEN_ALLOW_HTTP = "1";
+    assert.equal(heygenBase(), "http://127.0.0.1:4100/v3");
+  });
+});
+
+test("a host gateway (HEYGEN_API_BASE with its own HEYGEN_API_KEY) wins over a host OAuth token", () => {
+  withCleanHeygenEnv(() => {
+    process.env.HEYGEN_API_BASE = "http://127.0.0.1:4100";
+    process.env.HEYGEN_ALLOW_HTTP = "1";
+    process.env.HEYGEN_API_KEY = "gateway-token";
+    process.env.HEYGEN_ACCESS_TOKEN = "at_host";
+    assert.deepEqual(heygenAuthHeaders(), {
+      "X-Api-Key": "gateway-token",
+      "X-HeyGen-Client-Source": "media-use",
+    });
+    assert.equal(heygenAuthMethod(), "api_key");
+  });
+});
+
+test("heygenJSON sends its request to the host's HEYGEN_API_BASE with the host's key", async () => {
+  /** @type {{ url?: string, key?: string | string[] }} */
+  const seen = {};
+  const server = createServer((req, res) => {
+    seen.url = req.url;
+    seen.key = req.headers["x-api-key"];
+    res.writeHead(200, { "content-type": "application/json" }).end('{"data":[]}');
+  });
+  await new Promise((done) => server.listen(0, "127.0.0.1", done));
+  const { port } = /** @type {import("node:net").AddressInfo} */ (server.address());
+  try {
+    await withCleanHeygenEnv(async () => {
+      process.env.HEYGEN_API_BASE = `http://127.0.0.1:${port}`;
+      process.env.HEYGEN_ALLOW_HTTP = "1";
+      process.env.HEYGEN_API_KEY = "gateway-token";
+      const reply = await heygenJSON("/voices?limit=1", { headers: heygenAuthHeaders() });
+      assert.deepEqual(reply, { data: [] });
+    });
+    assert.equal(seen.url, "/v3/voices?limit=1");
+    assert.equal(seen.key, "gateway-token");
+  } finally {
+    server.close();
+  }
+});
+
+test("a base that isn't HeyGen's gets no stored or host OAuth credential, only a key named for it", () => {
+  withCleanHeygenEnv(() => {
+    const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
+    try {
+      process.env.HEYGEN_CONFIG_DIR = dir;
+      writeFileSync(join(dir, "credentials"), JSON.stringify({ api_key: "hg_stored" }));
+      process.env.HEYGEN_ACCESS_TOKEN = "at_host";
+      process.env.HEYGEN_API_BASE = "https://proxy.example.com";
+      assert.equal(heygenCredential(), null);
+      assert.throws(() => heygenAuthHeaders(), /no HeyGen credentials/);
+      // HeyGen's own hosts keep every credential source.
+      process.env.HEYGEN_API_BASE = "https://api-canary.heygen.com";
+      assert.equal(heygenAuthMethod(), "oauth");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/dist/skills/media-use/references/grading.md

@@ -83,8 +83,10 @@ on that same real media element with its registered paused GSAP timeline:
 | `--hf-color-grading-ascii`         | 0 to 1  |
 | `--hf-color-grading-dither`        | 0 to 1  |
 
-Author the initial value directly in the media element's inline `style`, then
-use finite `tl.to()` keyframes. Do not use a frame-zero `tl.set()`, CSS
+Once set (inline, in a stylesheet or on a parent), a property overrides the
+payload's value for that control, so set it only on media you animate: put the
+tween's first value in the element's inline `style`, then use finite `tl.to()`
+keyframes. Leave it unset for a static grade. Do not use a frame-zero `tl.set()`, CSS
 animation clocks, timers, random values, or `onUpdate` callbacks. The static
 `data-color-grading` payload remains the fallback and source of the other
 controls.

package/dist/skills/media-use/references/setup-providers.md

@@ -15,6 +15,19 @@ This unlocks the FREE path for bgm/sfx/image/icon catalog search, TTS (voice), a
 npx hyperframes media-use resolve --doctor
 ```
 
+## Host HeyGen access (no CLI sign-in)
+
+A host app can give media-use HeyGen access of its own by setting
+`HEYGEN_API_BASE` (its gateway), `HEYGEN_API_KEY` (the token that gateway
+accepts) and, for a loopback gateway, `HEYGEN_ALLOW_HTTP=1`. The gateway adds
+the host's key, so it never enters the agent's environment, and every
+call is charged to that key's API credits. The `heygen` CLI honours the same
+variables, so `resolve` (bgm/sfx/image/icon/voice/avatar-video) and the audio
+engine's TTS all go through the host. With host access, skip CLI install and
+sign-in, prefer the host's own HeyGen tools where it has them, never fall back
+to a local or third-party generator on your own, and relay a refused call's
+message (for example "add a key in Settings > Account") as written.
+
 ## Providers
 
 media-use holds no keys; every external tool owns its auth. Generation is

package/dist/{skills-VKZAX5AS.js → skills-CZHVAD3J.js}

@@ -9,8 +9,8 @@ import {
 } from "./chunk-6BEFEWFB.js";
 import {
   trackSkillsInstallSkipped
-} from "./chunk-JSGANFFH.js";
-import "./chunk-C2JUHIG5.js";
+} from "./chunk-XGMNQQTJ.js";
+import "./chunk-LBKDQKWV.js";
 import {
   diag
 } from "./chunk-VWG7OQKU.js";
@@ -39,15 +39,15 @@ import {
   isCoreSkill,
   presentSkills,
   pruneOrphanedLockEntries
-} from "./chunk-IFY57LUW.js";
+} from "./chunk-FZK35GT4.js";
 import {
   withMeta
-} from "./chunk-DDQ4LOML.js";
+} from "./chunk-JLKMWY2T.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-MUINFURL.js";
+import "./chunk-DZEVA7DI.js";
 import "./chunk-KNU5COPB.js";
 import {
   c

package/dist/{skillsUpdateCheck-PAY2OPDE.js → skillsUpdateCheck-6WLLX53A.js}

@@ -9,13 +9,13 @@ import {
   printSkillsUpdateNotice,
   refreshSkillsCache,
   skillsCheckDue
-} from "./chunk-IFY57LUW.js";
-import "./chunk-DDQ4LOML.js";
+} from "./chunk-FZK35GT4.js";
+import "./chunk-JLKMWY2T.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-MUINFURL.js";
+import "./chunk-DZEVA7DI.js";
 import "./chunk-KNU5COPB.js";
 import "./chunk-M2WBOQ2Q.js";
 export {