hyperframes 0.8.81 → 0.8.83

package/dist/renderSetupWorker.js

@@ -24631,6 +24631,7 @@ function readClipTiming(attributes2, options = {}) {
 }
 
 // ../parsers/dist/compositionDuration.js
+var TIMING_TOLERANCE_SECONDS = 0.05;
 var isPositiveFinite = (value) => value !== null && Number.isFinite(value) && value > 0;
 function resolveCompositionDuration(input2) {
   const pendingClips = input2.clipEndsSeconds.filter((end) => end === null).length;
@@ -31090,6 +31091,27 @@ function captionFindings(rows, severity) {
   }
   return findings;
 }
+var hundredths = (seconds) => Math.round(seconds * 100) / 100;
+function clipsPastRootFindings(root, rows) {
+  if (root.attrs["data-composition-id"] === void 0) return [];
+  const rootDuration = readDataDurationSeconds((name) => root.attrs[name]);
+  if (rootDuration === null) return [];
+  const limit = hundredths(rootDuration);
+  return rows.flatMap((row) => {
+    const { start, end } = readClipTiming({ getAttribute: (name) => row.attrs[name] ?? null });
+    if (start === null || end === null || end <= rootDuration + TIMING_TOLERANCE_SECONDS) return [];
+    return [
+      {
+        code: "clip_ends_past_root_duration",
+        severity: "warning",
+        message: `${describe(row)} runs from ${hundredths(start)}s to ${hundredths(end)}s, past the root composition's data-duration of ${limit}s, so it is cut off in previews, posters and renders.`,
+        elementId: row.attrs.id,
+        fixHint: `Extend the root data-duration to ${hundredths(end)}, or make ${describe(row)} end at or before ${limit}s.`,
+        snippet: truncateSnippet(row.open.raw)
+      }
+    ];
+  });
+}
 var structureRules = [
   (ctx) => {
     if (ctx.options.isSubComposition) return [];
@@ -31100,7 +31122,8 @@ var structureRules = [
     return [
       ...nestedStructureFindings(rows, severity),
       ...missingDurationFindings(rows, severity),
-      ...captionFindings(rows, severity)
+      ...captionFindings(rows, severity),
+      ...clipsPastRootFindings(root, rows)
     ];
   }
 ];
@@ -31411,6 +31434,7 @@ async function lintHevcPreviewCodec(candidates) {
 function parseSubCompHtml(html) {
   return parseHTML(html).document;
 }
+var sourceFile = (projectDir, compSrcPath) => resolve4(projectDir, compSrcPath ?? "index.html");
 function querySelectorAllIncludingTemplates(root, selector) {
   const matches2 = [...root.querySelectorAll(selector)];
   for (const template of root.querySelectorAll("template")) {
@@ -31562,20 +31586,20 @@ async function lintProject(projectDir, entryFile, hostOptions = {}) {
     ...await lintVideoMediaStartPastEof(projectDir, allHtmlSources),
     ...await lintHevcPreviewCodec(collectLocalVideoCandidates(projectDir, allHtmlSources))
   ];
-  if (projectFindings.length > 0) {
-    for (const finding of projectFindings) {
-      rootResult.findings.push(finding);
-      if (finding.severity === "error") {
-        rootResult.errorCount++;
-        rootResult.ok = false;
-        totalErrors++;
-      } else if (finding.severity === "warning") {
-        rootResult.warningCount++;
-        totalWarnings++;
-      } else {
-        rootResult.infoCount++;
-        totalInfos++;
-      }
+  for (const finding of projectFindings) {
+    const ownFile = finding.file && resolve4(projectDir, finding.file);
+    const owner = results.find((entry) => resolve4(projectDir, entry.file) === ownFile)?.result ?? rootResult;
+    owner.findings.push(finding);
+    if (finding.severity === "error") {
+      owner.errorCount++;
+      owner.ok = false;
+      totalErrors++;
+    } else if (finding.severity === "warning") {
+      owner.warningCount++;
+      totalWarnings++;
+    } else {
+      owner.infoCount++;
+      totalInfos++;
     }
   }
   return { results, totalErrors, totalWarnings, totalInfos };
@@ -31635,7 +31659,7 @@ function lintProjectAudioFiles(projectDir, htmlSources) {
 function lintAudioSrcNotFound(projectDir, htmlSources) {
   const findings = [];
   const audioSrcRe = mediaSrcTagRe("audio");
-  const missingSrcs = [];
+  const missingByFile = /* @__PURE__ */ new Map();
   for (const { html, compSrcPath } of htmlSources) {
     let match;
     while ((match = audioSrcRe.exec(html)) !== null) {
@@ -31644,15 +31668,17 @@ function lintAudioSrcNotFound(projectDir, htmlSources) {
       if (isUnresolvedAssetPlaceholder(src)) continue;
       const rootRelative = compSrcPath ? rewriteAssetPath(compSrcPath, src, (path) => existsSync22(join22(projectDir, path))) : src;
       if (!existsSync22(resolveProjectRelativeSrc(rootRelative, projectDir))) {
-        missingSrcs.push(src);
+        const file = sourceFile(projectDir, compSrcPath);
+        missingByFile.set(file, (missingByFile.get(file) ?? /* @__PURE__ */ new Set()).add(src));
       }
     }
   }
-  if (missingSrcs.length > 0) {
-    const unique = [...new Set(missingSrcs)];
+  for (const [file, srcs] of missingByFile) {
+    const unique = [...srcs];
     findings.push({
       code: "audio_src_not_found",
       severity: "error",
+      file,
       message: `<audio> element references file(s) not found in the project: ${unique.join(", ")}. The rendered video will be silent.`,
       fixHint: unique.length === 1 ? `Add the file "${unique[0]}" to the project directory, or update the src attribute to point to an existing file.` : `Add the missing files to the project directory, or update the src attributes to point to existing files.`
     });
@@ -31678,19 +31704,22 @@ function lintMissingLocalAsset(projectDir, htmlSources) {
       const resolvedAsset = resolveExistingLocalAsset(projectDir, rootRelative);
       if (resolvedAsset) continue;
       const resolvedKey = resolve4(projectDir, rootRelative);
-      let bucket = missingByTag.get(tagName19);
+      const file = sourceFile(projectDir, compSrcPath);
+      const bucketKey = `${file}\0${tagName19}`;
+      let bucket = missingByTag.get(bucketKey);
       if (!bucket) {
-        bucket = /* @__PURE__ */ new Map();
-        missingByTag.set(tagName19, bucket);
+        bucket = { file, tagName: tagName19, byResolved: /* @__PURE__ */ new Map() };
+        missingByTag.set(bucketKey, bucket);
       }
-      if (!bucket.has(resolvedKey)) bucket.set(resolvedKey, src);
+      if (!bucket.byResolved.has(resolvedKey)) bucket.byResolved.set(resolvedKey, src);
     }
   }
-  for (const [tagName19, byResolved] of missingByTag) {
+  for (const { file, tagName: tagName19, byResolved } of missingByTag.values()) {
     const unique = [...byResolved.values()];
     findings.push({
       code: "missing_local_asset",
       severity: "error",
+      file,
       message: `<${tagName19}> element references local file(s) not found in the project: ${unique.join(", ")}. The renderer will silently skip these and produce a video with missing visuals.`,
       fixHint: unique.length === 1 ? `Add "${unique[0]}" to the project directory, or update the src attribute to point to an existing file. Common cause: captured asset filenames are unreliable (heygen-logo.svg often contains Google, nvidia-logo.svg may contain Autodesk, etc.). Open the contact sheets and verify the file actually exists at this path before referencing it.` : "Add the missing files to the project directory, or update the src attributes to point to existing files. Captured asset filenames are unreliable \u2014 verify against capture/contact-sheets/ and capture/extracted/asset-descriptions.md."
     });
@@ -31698,8 +31727,9 @@ function lintMissingLocalAsset(projectDir, htmlSources) {
   return findings;
 }
 function lintTextureMaskAssetNotFound(projectDir, htmlSources) {
-  const missing = /* @__PURE__ */ new Map();
+  const missingByFile = /* @__PURE__ */ new Map();
   for (const { html, compSrcPath } of htmlSources) {
+    const file = sourceFile(projectDir, compSrcPath);
     for (const cssSource of collectCssSources(projectDir, html, compSrcPath)) {
       let match;
       const pattern = new RegExp(MASK_IMAGE_URL_RE.source, MASK_IMAGE_URL_RE.flags);
@@ -31715,20 +31745,20 @@ function lintTextureMaskAssetNotFound(projectDir, htmlSources) {
           cssSource.rootRelativePath
         );
         if (candidates.some(existsSync22)) continue;
-        missing.set(url, candidates[0] ?? resolve4(projectDir, url));
+        missingByFile.set(file, (missingByFile.get(file) ?? /* @__PURE__ */ new Set()).add(url));
       }
     }
   }
-  if (missing.size === 0) return [];
-  const urls = [...missing.keys()];
-  return [
-    {
+  return [...missingByFile].map(([file, found]) => {
+    const urls = [...found];
+    return {
       code: "texture_mask_asset_not_found",
       severity: "error",
+      file,
       message: `CSS mask-image references file(s) not found in the project: ${urls.join(", ")}.`,
       fixHint: urls.length === 1 ? `Add "${urls[0]}" to the project, or update the mask-image URL to point to an existing texture mask.` : "Add the missing texture mask files to the project, or update the mask-image URLs to point to existing files."
-    }
-  ];
+    };
+  });
 }
 function lintMultipleRootCompositions(projectDir) {
   const findings = [];

package/dist/sherpaWorker.js

@@ -0,0 +1,179 @@
+import { createRequire as __hf_createRequire } from "node:module";
+import { fileURLToPath as __hf_fileURLToPath } from "node:url";
+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);
+
+// src/utils/optionalPackages.ts
+import { spawn } from "child_process";
+import { randomUUID } from "crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "fs";
+import { createRequire } from "module";
+import { homedir } from "os";
+import { basename, dirname, join, sep } from "path";
+var CACHE_DIR = join(homedir(), ".cache", "hyperframes", "optional");
+function manifestPath(dir, name) {
+  return join(dir, "node_modules", name, "package.json");
+}
+function isInstalled(dir, name) {
+  return existsSync(manifestPath(dir, name));
+}
+function loadInstalled(dir, name) {
+  if (!isInstalled(dir, name)) return null;
+  return createRequire(join(dir, "package.json"))(name);
+}
+var STAGING_PID_TRUSTED_FOR_MS = 6 * 60 * 60 * 1e3;
+
+// src/whisper/parakeet.ts
+import { execFileSync } from "child_process";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, mkdtempSync, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir2, tmpdir } from "os";
+import { basename as basename2, extname, join as join2 } from "path";
+var SHERPA_RESULT_PREFIX = "HYPERFRAMES_PARAKEET_RESULT:";
+var SHERPA_ERROR_PREFIX = "HYPERFRAMES_PARAKEET_ERROR:";
+function meanEnergy(samples, from, to) {
+  let energy = 0;
+  for (let i = from; i < to; i++) energy += samples[i] * samples[i];
+  return energy / Math.max(1, to - from);
+}
+function droppedSpeechGaps(samples, sampleRate, decoded) {
+  if (decoded.tokens.length === 0) return [];
+  const loud = 0.3 * meanEnergy(samples, 0, samples.length);
+  const { timestamps, durations } = decoded;
+  const gapStarts = [0, ...timestamps.map((t, i) => t + (durations?.[i] ?? 0))];
+  const gapEnds = [...timestamps, samples.length / sampleRate];
+  const at = (seconds) => Math.round(seconds * sampleRate);
+  return gapStarts.map((from, i) => [from, gapEnds[i]]).filter(([from, to]) => to - from >= 1 && meanEnergy(samples, at(from), at(to)) > loud);
+}
+function overlap(a, b) {
+  for (let n = Math.min(a.length, b.length); n > 0; n--) {
+    if (a.slice(-n).every((text, i) => text === b[i])) return n;
+  }
+  return 0;
+}
+function wordsOf(tokens) {
+  const words = [];
+  for (const t of tokens) {
+    if (t.text.startsWith(" ") || words.length === 0) words.push([t]);
+    else words.at(-1).push(t);
+  }
+  return words;
+}
+var letters = (word) => word.map((t) => t.text).join("").toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+var EDGE_SECONDS = 0.3;
+function spliceGap(decoded, patch, offset, [from, to]) {
+  const tokens = (w, shift) => w.tokens.map((text, i) => ({
+    text,
+    start: shift + w.timestamps[i],
+    duration: w.durations?.[i] ?? 0
+  }));
+  const kept = wordsOf(tokens(decoded, 0));
+  const added = wordsOf(tokens(patch, offset)).filter(
+    ([first]) => first.start >= from && first.start < to
+  );
+  const before = kept.filter(([first]) => first.start < from).map(letters);
+  const after = kept.filter(([first]) => first.start >= to).map(letters);
+  const head = added.filter(([first]) => first.start < from + EDGE_SECONDS).map(letters);
+  const tail = added.filter(([first]) => first.start >= to - EDGE_SECONDS).map(letters);
+  const fresh = added.slice(overlap(before, head), added.length - overlap(tail, after)).map(([first, ...rest]) => [{ ...first, text: ` ${first.text.trimStart()}` }, ...rest]);
+  const merged = [...kept, ...fresh].sort((a, b) => a[0].start - b[0].start).flat();
+  return {
+    tokens: merged.map((t) => t.text),
+    timestamps: merged.map((t) => t.start),
+    durations: merged.map((t) => t.duration)
+  };
+}
+function quietestBlockCenter(samples, lo, hi, block) {
+  let best = hi;
+  let bestEnergy = Infinity;
+  for (let s = lo; s + block <= hi; s += block) {
+    const energy = meanEnergy(samples, s, s + block);
+    if (energy < bestEnergy) {
+      bestEnergy = energy;
+      best = s + block / 2;
+    }
+  }
+  return best;
+}
+function silenceCuts(samples, sampleRate, windowSeconds = 60) {
+  const window = windowSeconds * sampleRate;
+  const slack = 5 * sampleRate;
+  const cuts = [0];
+  while (cuts.at(-1) + window < samples.length) {
+    const target = cuts.at(-1) + window;
+    const hi = Math.min(target + slack, samples.length);
+    cuts.push(quietestBlockCenter(samples, target - slack, hi, sampleRate / 10));
+  }
+  if (samples.length > 0) cuts.push(samples.length);
+  return cuts;
+}
+
+// src/whisper/sherpaWorker.ts
+var { wavPath, runtimeDir, config } = JSON.parse(process.env.HYPERFRAMES_PARAKEET_INPUT ?? "{}");
+var parentPid = process.ppid;
+var RETRY_PAD_SECONDS = 0.5;
+var GAP_MARGIN_SECONDS = 0.5;
+function decodeWindow(recognizer, wave, padSeconds = 0) {
+  const pad = Math.round(padSeconds * wave.sampleRate);
+  const samples = new Float32Array(pad + wave.samples.length);
+  samples.set(wave.samples, pad);
+  const stream = recognizer.createStream();
+  stream.acceptWaveform({ sampleRate: wave.sampleRate, samples });
+  recognizer.decode(stream);
+  const { tokens, timestamps, durations } = recognizer.getResult(stream);
+  return { tokens, timestamps: timestamps.map((t) => Math.max(0, t - padSeconds)), durations };
+}
+try {
+  const sherpa = loadInstalled(runtimeDir, "sherpa-onnx-node");
+  if (!sherpa) throw new Error(`sherpa-onnx-node is not installed in ${runtimeDir}`);
+  const recognizer = new sherpa.OfflineRecognizer(config);
+  const wave = sherpa.readWave(wavPath);
+  const cuts = silenceCuts(wave.samples, wave.sampleRate);
+  const windows = [];
+  for (let k = 0; k + 1 < cuts.length; k++) {
+    if (process.ppid !== parentPid) throw new Error("the CLI exited, so the decode stopped");
+    const slice = {
+      sampleRate: wave.sampleRate,
+      samples: wave.samples.subarray(cuts[k], cuts[k + 1])
+    };
+    let decoded = decodeWindow(recognizer, slice);
+    const gaps = droppedSpeechGaps(slice.samples, slice.sampleRate, decoded);
+    let spliced = decoded;
+    for (const [from, to] of gaps) {
+      const lo = Math.max(0, from - GAP_MARGIN_SECONDS);
+      const at = (seconds) => Math.round(seconds * slice.sampleRate);
+      const samples = slice.samples.subarray(at(lo), at(to + GAP_MARGIN_SECONDS));
+      const patch = decodeWindow(
+        recognizer,
+        { sampleRate: slice.sampleRate, samples },
+        RETRY_PAD_SECONDS
+      );
+      spliced = spliceGap(spliced, patch, lo, [from, to]);
+    }
+    if (spliced.tokens.length > decoded.tokens.length) decoded = spliced;
+    else if (gaps.length > 0) {
+      const retry = decodeWindow(recognizer, slice, RETRY_PAD_SECONDS);
+      if (retry.tokens.length > decoded.tokens.length) decoded = retry;
+    }
+    windows.push({ offset: cuts[k] / wave.sampleRate, ...decoded });
+  }
+  process.stdout.write(`${SHERPA_RESULT_PREFIX}${JSON.stringify(windows)}
+`);
+} catch (err) {
+  const message = (err instanceof Error ? err.message : String(err)).replace(/\s+/g, " ").trim();
+  process.stderr.write(`${SHERPA_ERROR_PREFIX}${message}
+`, () => {
+    throw err;
+  });
+}

package/dist/skills/hyperframes/SKILL.md

@@ -12,6 +12,8 @@ description: >
   browser session.
 ---
 
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+
 # HyperFrames entry point
 
 HyperFrames **renders video from HTML** — a composition is an HTML file whose DOM declares timing with `data-*` attributes, whose animation runtime is seekable, and whose media playback is owned by the framework. The full authoring contract lives in `/hyperframes-core`; read it before writing composition HTML. Brief, storyboard, review, production, dispatch, and frame-worker contracts live in this skill's `references/`.

package/dist/skills/hyperframes/references/plugin-installation.md

@@ -0,0 +1,43 @@
+# Running from an installed plugin
+
+Check the directory two levels above the loaded `SKILL.md` for `plugin.json`,
+`.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, or
+`.cursor-plugin/plugin.json` identifying `hyperframes`, or a Gemini extension manifest.
+That directory is `<PLUGIN_ROOT>`. If none exists, this is a standalone skill;
+follow the normal installation and freshness instructions.
+
+For a plugin installation, these rules replace the standalone update commands
+in every workflow and reference:
+
+- Do not run `hyperframes skills update`, `skills check`, or `npx skills add`.
+  The agent's plugin manager owns installation and updates. Read the workflow at
+  `<PLUGIN_ROOT>/skills/<name>/SKILL.md`; report a missing bundled skill instead
+  of downloading a different release. Resolve all skill references inside this
+  bundle, even if a standalone copy is also installed. Claude exposes the router
+  as `/hyperframes:hyperframes`; other clients may expose `/hyperframes`.
+- Replace `npx hyperframes` (or bare `hyperframes`) in command examples with:
+
+  ```bash
+  node "<PLUGIN_ROOT>/skills/hyperframes/scripts/plugin-cli.mjs" <command> <args...>
+  ```
+
+  Run in the user's project directory, never in the plugin directory. The launcher
+  selects the manifest's CLI version and disables automatic standalone skill
+  installation, including during `init`. The first call may download that exact
+  CLI version through npm. A download failure is an error, not permission to use
+  latest. Existing project dependency files and lockfiles must not be overwritten
+  to match the plugin; surface a runtime incompatibility before changing them.
+
+- For bundled Node helpers, use the same
+  launcher with `--script <absolute-script-path> <args...>`. This passes the
+  release version to their dependency loader. External providers, registry
+  downloads, and existing project dependencies have their own versions; a plugin
+  version alone does not freeze those inputs.
+- Treat the plugin directory as read-only. Put outputs and temporary work in the
+  project or a temporary directory. Pass this plugin root and launcher convention
+  to any delegated workflow so it does not fall back to global skills.
+
+To get newer skills, use the client's plugin update flow and reload the session.
+Do not silently update an installed plugin during a video task.
+
+The launcher suppresses CLI update notices as well as standalone skill refreshes, including when running an older CLI with a stale notice cache. It passes the release as `HYPERFRAMES_PLUGIN_VERSION` for plugin-aware helpers and as `HYPERFRAMES_SKILL_PKG_VERSION` for the existing helper-package bootstrap. Our release process versions those packages together.

package/dist/skills/hyperframes/references/skill-lifecycle.md

@@ -2,6 +2,8 @@
 
 Read this reference when installing or updating skills, diagnosing unexpected workflow behavior, or running HyperFrames setup in CI.
 
+For a plugin installation, follow [plugin execution rules](plugin-installation.md); the plugin manager owns updates and all workflows are bundled. The commands below apply only to standalone skills.
+
 HyperFrames installs the core set eagerly and workflow skills lazily.
 
 - **Core set:** `/hyperframes`, the `hyperframes-*` domain skills, and `/media-use`.

package/dist/skills/hyperframes/scripts/plugin-cli.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Run from the user's project; locate the release from this installed file.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, win32 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = fileURLToPath(new URL("../../../", import.meta.url));
+const manifests = [
+  "plugin.json",
+  ".claude-plugin/plugin.json",
+  ".codex-plugin/plugin.json",
+  ".cursor-plugin/plugin.json",
+  "gemini-extension.json",
+];
+
+export function pluginVersion(pluginRoot = root) {
+  for (const path of manifests) {
+    const file = join(pluginRoot, path);
+    if (!existsSync(file)) continue;
+    const manifest = JSON.parse(readFileSync(file, "utf8"));
+    if (
+      manifest.name !== "hyperframes" ||
+      !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(manifest.version ?? "")
+    ) {
+      throw new Error(`Invalid HyperFrames plugin release: ${file}`);
+    }
+    return manifest.version;
+  }
+  throw new Error(
+    "No HyperFrames plugin manifest found. Use the standalone skills installation instructions.",
+  );
+}
+
+export function invocation(
+  args,
+  {
+    version = pluginVersion(),
+    env = process.env,
+    platform = process.platform,
+    node = process.execPath,
+    pathExists = existsSync,
+  } = {},
+) {
+  if (args[0] === "skills")
+    throw new Error(
+      "Update HyperFrames through your agent's plugin manager; bundled skills are release-managed.",
+    );
+  const childEnv = {
+    ...env,
+    HYPERFRAMES_SKIP_SKILLS: "1",
+    HYPERFRAMES_SKILL_PKG_VERSION: version,
+    HYPERFRAMES_PLUGIN_VERSION: version,
+    HYPERFRAMES_NO_UPDATE_CHECK: "1",
+  };
+  if (args[0] === "--script") {
+    if (!args[1]) throw new Error("--script requires a Node script path.");
+    return { command: node, args: args.slice(1), env: childEnv };
+  }
+  const cliArgs = ["--yes", `hyperframes@${version}`, ...args];
+  if (platform !== "win32") return { command: "npx", args: cliArgs, env: childEnv };
+  const candidates = [
+    env.npm_execpath && win32.join(win32.dirname(env.npm_execpath), "npx-cli.js"),
+    win32.join(win32.dirname(node), "node_modules", "npm", "bin", "npx-cli.js"),
+  ].filter(Boolean);
+  const npx = candidates.find(pathExists);
+  if (!npx)
+    throw new Error(
+      "Cannot find npx-cli.js. Install Node.js with npm or run from an npm environment.",
+    );
+  return { command: node, args: [npx, ...cliArgs], env: childEnv };
+}
+
+if (process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) {
+  try {
+    const command = invocation(process.argv.slice(2));
+    const result = spawnSync(command.command, command.args, {
+      env: command.env,
+      stdio: "inherit",
+      windowsHide: true,
+    });
+    if (result.error) throw result.error;
+    process.exitCode = result.status ?? 1;
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/dist/skills/hyperframes/scripts/plugin-cli.test.mjs

@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  copyFileSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { test } from "node:test";
+import { invocation, pluginVersion } from "./plugin-cli.mjs";
+
+function fixture(t, manifest = "plugin.json", version = "1.2.3") {
+  const root = mkdtempSync(join(tmpdir(), "hf-plugin-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  mkdirSync(join(root, "skills/hyperframes/scripts"), { recursive: true });
+  mkdirSync(join(root, manifest, ".."), { recursive: true });
+  writeFileSync(join(root, manifest), JSON.stringify({ name: "hyperframes", version }));
+  const launcher = join(root, "skills/hyperframes/scripts/plugin-cli.mjs");
+  copyFileSync(new URL("./plugin-cli.mjs", import.meta.url), launcher);
+  return { root, launcher };
+}
+
+for (const manifest of [
+  "plugin.json",
+  ".claude-plugin/plugin.json",
+  ".codex-plugin/plugin.json",
+  ".cursor-plugin/plugin.json",
+  "gemini-extension.json",
+]) {
+  test(`locates ${manifest} without repository packages`, (t) => {
+    const { root } = fixture(t, manifest);
+    assert.equal(pluginVersion(root), "1.2.3");
+  });
+}
+
+test("rejects missing and floating plugin versions", (t) => {
+  const { root } = fixture(t, "plugin.json", "latest");
+  assert.throws(() => pluginVersion(root), /Invalid HyperFrames plugin release/);
+  rmSync(join(root, "plugin.json"));
+  assert.throws(() => pluginVersion(root), /No HyperFrames plugin manifest/);
+});
+
+test("pins CLI, suppresses standalone refresh, preserves unrelated environment", () => {
+  const result = invocation(["init", "project with spaces", "--non-interactive"], {
+    version: "1.2.3",
+    platform: "darwin",
+    env: { PATH: "/bin", HYPERFRAMES_SKIP_SKILLS: "0" },
+  });
+  assert.equal(result.command, "npx");
+  assert.deepEqual(result.args, [
+    "--yes",
+    "hyperframes@1.2.3",
+    "init",
+    "project with spaces",
+    "--non-interactive",
+  ]);
+  assert.deepEqual(result.env, {
+    PATH: "/bin",
+    HYPERFRAMES_SKIP_SKILLS: "1",
+    HYPERFRAMES_SKILL_PKG_VERSION: "1.2.3",
+    HYPERFRAMES_PLUGIN_VERSION: "1.2.3",
+    HYPERFRAMES_NO_UPDATE_CHECK: "1",
+  });
+  assert.throws(() => invocation(["skills", "update"], { version: "1.2.3" }), /plugin manager/);
+});
+
+test("Windows launches npx through Node without shell argument interpretation", () => {
+  const result = invocation(["render", "a & b"], {
+    version: "1.2.3",
+    platform: "win32",
+    node: String.raw`C:\Program Files\nodejs\node.exe`,
+    env: { npm_execpath: String.raw`C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js` },
+    pathExists: (p) => p === String.raw`C:\Program Files\nodejs\node_modules\npm\bin\npx-cli.js`,
+  });
+  assert.equal(result.command, String.raw`C:\Program Files\nodejs\node.exe`);
+  assert.deepEqual(result.args, [
+    String.raw`C:\Program Files\nodejs\node_modules\npm\bin\npx-cli.js`,
+    "--yes",
+    "hyperframes@1.2.3",
+    "render",
+    "a & b",
+  ]);
+  assert.throws(
+    () => invocation([], { version: "1.2.3", platform: "win32", env: {}, pathExists: () => false }),
+    /Cannot find npx/,
+  );
+});
+
+test("installed helper keeps cwd, arguments, release environment and exit code", (t) => {
+  const { root, launcher } = fixture(t);
+  const project = join(root, "user project");
+  mkdirSync(project);
+  const helper = join(root, "helper.mjs");
+  writeFileSync(
+    helper,
+    "console.log(JSON.stringify({ cwd: process.cwd(), args: process.argv.slice(2), skip: process.env.HYPERFRAMES_SKIP_SKILLS, version: process.env.HYPERFRAMES_SKILL_PKG_VERSION })); process.exit(7);",
+  );
+  const before = readFileSync(join(root, "plugin.json"), "utf8");
+  const result = spawnSync(
+    process.execPath,
+    [launcher, "--script", helper, "literal $value & spaces"],
+    { cwd: project, encoding: "utf8" },
+  );
+  assert.equal(result.status, 7, result.stderr);
+  assert.deepEqual(JSON.parse(result.stdout), {
+    cwd: realpathSync(project),
+    args: ["literal $value & spaces"],
+    skip: "1",
+    version: "1.2.3",
+  });
+  assert.equal(readFileSync(join(root, "plugin.json"), "utf8"), before);
+});

package/dist/skills/hyperframes-cli/SKILL.md

@@ -9,6 +9,8 @@ description: >
   HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.
 ---
 
+**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.
+
 # HyperFrames CLI
 
 Run commands as `npx hyperframes ...` unless project instructions provide a wrapper. Obey the wrapper when present. The CLI requires Node.js 22 or newer and FFmpeg.

package/dist/skills/hyperframes-cli/references/upgrade-info-misc.md

@@ -111,6 +111,7 @@ Events include two fingerprint properties used to distinguish managed-sandbox ru
 
 - **`sandbox_runtime`**: `gvisor` / `firecracker` / `docker` / `kvm` / `wsl` / `null`. gVisor via kernel string + `/proc/version`. Firecracker via `/dev/vsock` + DMI sys_vendor. Docker via `/.dockerenv` + cgroup.
 - **`agent_runtime`**: `claude_code` / `codex` / `cursor` / `copilot_agent` / `jules` / `replit` / `devin` / `aider` / `gemini_cli` / `hermes` / `openclaw` / `null`. Detected by the existence of well-known vendor env vars; the values themselves are never read.
+- **`client`**: set only when an app launched the CLI with a `HYPERFRAMES_CLIENT` tag (`<app>/<version>/<channel>`), sent as-is when it is a short slug.
 
 ## Asset Preprocessing
 

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

@@ -3,6 +3,8 @@ name: media-use
 description: Agent Media OS, the single skill for every media need in 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.
 ---
 
+**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.
+
 # media-use
 
 The media OS for HyperFrames: resolve · generate · operate · remember — every media type, one skill, zero context noise.