From 045b3a4fd7df71b46f4432c114f70fb25d13b551 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Mon, 24 Aug 2026 19:56:06 -0400
Subject: [PATCH] feat(cli): report which catalog items a render actually used
 (#3470)

`registry_item_added` fires when a catalog block is installed and
`render_complete` fires when a video is produced, but nothing joined them, so
"did this video use the catalog?" had no answer.

`hyperframes add` now records each installed item in `hyperframes.json`
(installed files are plain composition HTML with no provenance marker, so this
manifest is the only record that a file came from the registry), and
`render_complete` reports both the items the project installed and the blocks
the rendered composition actually reaches. An item installed and then never
mounted was tried and dropped, which no add-time event can express.

The scan answering "which sub-compositions does this file mount" now has one
owner, `collectSubCompositionSrcs` in `@hyperframes/parsers`, shared with
lint's `lintMissingOrEmptySubComposition`. It holds two invariants that were
previously restated per call site and got re-derived wrongly: it is a text scan
rather than a DOM query, because `<template>` content is inert and every
sub-composition except the render entry is wrapped in one; and references
resolve root-relative at every nesting level, matching `parseSubCompositions`.
It walks tag by tag rather than running open-ended spans across the whole file,
so a malformed composition cannot stall the render plan.

Also: `registryItems` is declared in the config schema, which closes with
`additionalProperties: false`, with an ajv-backed test pinning every key the CLI
writes; counts are never truncated by the name cap, and the reported used blocks
stay a subset of the reported installed ones, with `registry_items_truncated`
marking a windowed list; and an unreadable manifest reports itself rather than
posing as a project that never used the catalog.
---
 bun.lock                                      |  27 +--
 docs/schema/hyperframes.json                  |  23 ++
 packages/cli/package.json                     |   1 +
 packages/cli/src/commands/add.ts              |  37 ++-
 packages/cli/src/commands/render.ts           |   9 +
 packages/cli/src/commands/render/execute.ts   |   2 +
 packages/cli/src/commands/render/plan.test.ts |  38 +++-
 packages/cli/src/commands/render/plan.ts      |   9 +-
 packages/cli/src/telemetry/events.test.ts     | 122 ++++++++++
 packages/cli/src/telemetry/events.ts          |  63 +++++
 packages/cli/src/utils/catalogUsage.test.ts   | 215 ++++++++++++++++++
 packages/cli/src/utils/catalogUsage.ts        | 153 +++++++++++++
 packages/cli/src/utils/projectConfig.test.ts  |  98 ++++++++
 packages/cli/src/utils/projectConfig.ts       | 155 ++++++++++++-
 .../cli/src/utils/projectConfigSchema.test.ts |  76 +++++++
 packages/lint/src/project.ts                  |  12 +-
 packages/parsers/src/assetResolution.test.ts  |  60 ++++-
 packages/parsers/src/assetResolution.ts       |  69 ++++++
 18 files changed, 1129 insertions(+), 40 deletions(-)
 create mode 100644 packages/cli/src/utils/catalogUsage.test.ts
 create mode 100644 packages/cli/src/utils/catalogUsage.ts
 create mode 100644 packages/cli/src/utils/projectConfigSchema.test.ts

diff --git a/bun.lock b/bun.lock
index 93cf6e2e5..e2875368d 100644
--- a/bun.lock
+++ b/bun.lock
@@ -24,7 +24,7 @@
     },
     "packages/aws-lambda": {
       "name": "@hyperframes/aws-lambda",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "@aws-sdk/client-s3": "^3.700.0",
         "@aws-sdk/client-sfn": "^3.700.0",
@@ -57,7 +57,7 @@
     },
     "packages/cli": {
       "name": "@hyperframes/cli",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "bin": {
         "hyperframes": "./bin/hyperframes.mjs",
       },
@@ -94,6 +94,7 @@
         "@types/fontkit": "^2.0.9",
         "@types/mime-types": "^3.0.1",
         "@types/node": "^25.0.10",
+        "ajv": "^8.20.0",
         "linkedom": "^0.18.12",
         "picocolors": "^1.1.1",
         "tsup": "^8.0.0",
@@ -107,7 +108,7 @@
     },
     "packages/core": {
       "name": "@hyperframes/core",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "@chenglou/pretext": "^0.0.5",
         "@hyperframes/lint": "workspace:*",
@@ -132,7 +133,7 @@
     },
     "packages/engine": {
       "name": "@hyperframes/engine",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "@hono/node-server": "^2.0.5",
         "@hyperframes/core": "workspace:^",
@@ -151,7 +152,7 @@
     },
     "packages/gcp-cloud-run": {
       "name": "@hyperframes/gcp-cloud-run",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "@google-cloud/storage": "^7.14.0",
         "@google-cloud/workflows": "^4.2.0",
@@ -172,7 +173,7 @@
     },
     "packages/lint": {
       "name": "@hyperframes/lint",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "@hyperframes/parsers": "workspace:*",
         "htmlparser2": "^10.1.0",
@@ -190,7 +191,7 @@
     },
     "packages/parsers": {
       "name": "@hyperframes/parsers",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "@babel/parser": "^7.27.0",
         "acorn": "^8.17.0",
@@ -210,7 +211,7 @@
     },
     "packages/player": {
       "name": "@hyperframes/player",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
       },
@@ -225,7 +226,7 @@
     },
     "packages/producer": {
       "name": "@hyperframes/producer",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "@fontsource/archivo-black": "^5.2.8",
         "@fontsource/eb-garamond": "^5.2.7",
@@ -270,7 +271,7 @@
     },
     "packages/sdk": {
       "name": "@hyperframes/sdk",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
         "@hyperframes/parsers": "workspace:*",
@@ -300,7 +301,7 @@
     },
     "packages/shader-transitions": {
       "name": "@hyperframes/shader-transitions",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "html2canvas": "^1.4.1",
       },
@@ -312,7 +313,7 @@
     },
     "packages/studio": {
       "name": "@hyperframes/studio",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "@codemirror/autocomplete": "^6.20.1",
         "@codemirror/commands": "^6.10.3",
@@ -363,7 +364,7 @@
     },
     "packages/studio-server": {
       "name": "@hyperframes/studio-server",
-      "version": "0.8.5",
+      "version": "0.8.13",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
         "@hyperframes/parsers": "workspace:*",
diff --git a/docs/schema/hyperframes.json b/docs/schema/hyperframes.json
index 8821e6631..d950bc6fe 100644
--- a/docs/schema/hyperframes.json
+++ b/docs/schema/hyperframes.json
@@ -56,6 +56,29 @@
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
       "description": "Owning authoring-workflow skill slug (e.g. product-launch-video). Set by `hyperframes init --skill` or seeded from the first `hyperframes render --skill`; every render of this project is then attributed to it on anonymous telemetry, without re-passing the flag."
+    },
+    "registryItems": {
+      "type": "array",
+      "description": "Catalog items installed by `hyperframes add`, in install order. Installed files are plain composition HTML with no provenance marker, so this is the only record that a file came from the registry; a render reads it back to report which catalog items the finished video actually used. Append-only, deduped by name.",
+      "items": {
+        "type": "object",
+        "required": ["name", "type", "target"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Registry item name, e.g. data-chart."
+          },
+          "type": {
+            "type": "string",
+            "description": "Registry item type, e.g. hyperframes:block."
+          },
+          "target": {
+            "type": "string",
+            "description": "Primary installed file, relative to the project root."
+          }
+        }
+      }
     }
   }
 }
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 3329b4053..ff56892fa 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -61,6 +61,7 @@
     "@types/fontkit": "^2.0.9",
     "@types/mime-types": "^3.0.1",
     "@types/node": "^25.0.10",
+    "ajv": "^8.20.0",
     "linkedom": "^0.18.12",
     "picocolors": "^1.1.1",
     "tsup": "^8.0.0",
diff --git a/packages/cli/src/commands/add.ts b/packages/cli/src/commands/add.ts
index fd6ed2aba..a0d857471 100644
--- a/packages/cli/src/commands/add.ts
+++ b/packages/cli/src/commands/add.ts
@@ -25,6 +25,7 @@ import {
   DEFAULT_PROJECT_CONFIG,
   loadProjectConfig,
   projectConfigPath,
+  recordProjectRegistryItems,
   writeProjectConfig,
 } from "../utils/projectConfig.js";
 import { copyToClipboard } from "../utils/clipboard.js";
@@ -78,6 +79,23 @@ function variableValuesAttribute(values: Record<string, unknown> | null): string
   return ` data-variable-values='${json}'`;
 }
 
+/**
+ * The file a consumer points at for this item: the snippet if it has one, else
+ * its composition, else whatever landed first. Project-relative, empty when the
+ * item installed no files.
+ *
+ * One owner for this choice. The paste snippet's `data-composition-src` and the
+ * recorded manifest target must name the same file, or a render would look for
+ * a block at a path the composition never mounts and report it as dropped.
+ */
+function primaryInstalledTarget(item: RegistryItem): string {
+  const primary =
+    item.files.find((f) => f.type === "hyperframes:snippet") ??
+    item.files.find((f) => f.type === "hyperframes:composition") ??
+    item.files[0];
+  return primary?.target ?? "";
+}
+
 export function buildSnippet(
   item: RegistryItem,
   relativeTarget: string,
@@ -321,13 +339,22 @@ export async function runAdd(opts: RunAddArgs): Promise<RunAddResult> {
     });
   }
 
+  // Persist what came from the registry. Installed files are plain composition
+  // HTML with no provenance marker, so without this a later render cannot tell
+  // a catalog block from one the user wrote — and "did the catalog item survive
+  // into the video?" stays unanswerable.
+  recordProjectRegistryItems(
+    projectDir,
+    installPlan.map((planItem) => ({
+      name: planItem.name,
+      type: planItem.type,
+      target: primaryInstalledTarget(planItem),
+    })),
+  );
+
   // 6. Build include snippet + clipboard copy for the requested item.
   const itemForInstall = installPlan[installPlan.length - 1]!;
-  const primaryFile =
-    itemForInstall.files.find((f) => f.type === "hyperframes:snippet") ??
-    itemForInstall.files.find((f) => f.type === "hyperframes:composition") ??
-    itemForInstall.files[0];
-  const snippetTargetRel = primaryFile?.target ?? "";
+  const snippetTargetRel = primaryInstalledTarget(itemForInstall);
   const snippet = buildSnippet(item, snippetTargetRel, variableValues);
   const clipboardCopied = !opts.skipClipboard && snippet ? copyToClipboard(snippet) : false;
 
diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts
index 8170fc75a..102a45bcc 100644
--- a/packages/cli/src/commands/render.ts
+++ b/packages/cli/src/commands/render.ts
@@ -4,6 +4,7 @@ import type { Example } from "./_examples.js";
 import { mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync, rmSync } from "node:fs";
 import { createRenderPlan, resolveBrowserGpuForCli, type RenderFormat } from "./render/plan.js";
 import { seedProjectAuthoringSkill } from "../utils/projectConfig.js";
+import type { CatalogUsage } from "../utils/catalogUsage.js";
 import { presentRenderPlan } from "./render/present.js";
 import { executeRenderPlan, renderLintContinuationHint, runRenderLint } from "./render/execute.js";
 // Test-only seams retained at the command boundary for render behavior tests.
@@ -377,6 +378,12 @@ export interface RenderOptions {
   quality: "draft" | "standard" | "high";
   /** Authoring workflow skill that drove this render (telemetry attribution). */
   authoringSkill?: string;
+  /**
+   * Catalog items installed in this project and those the rendered composition
+   * reaches. Resolved once in the render plan; absent on programmatic callers
+   * that build options by hand, which simply omit the catalog properties.
+   */
+  catalogUsage?: CatalogUsage;
   format: RenderFormat;
   gifLoop?: number;
   workers?: number;
@@ -763,6 +770,7 @@ async function renderDocker(
       docker: true,
       gpu: options.gpu,
       authoringSkill: options.authoringSkill,
+      catalogUsage: options.catalogUsage,
       ...getMemorySnapshot(),
     }),
   );
@@ -1498,6 +1506,7 @@ function trackRenderMetrics(
     docker,
     gpu: options.gpu,
     authoringSkill: options.authoringSkill,
+    catalogUsage: options.catalogUsage,
     staticDedupEnabled: perf?.staticDedup?.enabled,
     staticDedupArmed: perf?.staticDedup?.armed,
     staticDedupSkipReason: perf?.staticDedup?.skipReason,
diff --git a/packages/cli/src/commands/render/execute.ts b/packages/cli/src/commands/render/execute.ts
index 163c849f2..301a9894f 100644
--- a/packages/cli/src/commands/render/execute.ts
+++ b/packages/cli/src/commands/render/execute.ts
@@ -101,6 +101,7 @@ export async function executeRenderPlan(
     fps: plan.fps,
     quality: plan.quality,
     authoringSkill: plan.authoringSkill,
+    catalogUsage: plan.catalogUsage,
     format: plan.format,
     gifLoop: plan.gifLoop,
     workers: plan.workers,
@@ -254,6 +255,7 @@ async function executeBatchRender(
     fps: plan.fps,
     quality: plan.quality,
     authoringSkill: plan.authoringSkill,
+    catalogUsage: plan.catalogUsage,
     format: plan.format,
     workers: plan.workers,
     gpu: plan.useGpu,
diff --git a/packages/cli/src/commands/render/plan.test.ts b/packages/cli/src/commands/render/plan.test.ts
index 03482cb0a..7aed45f5e 100644
--- a/packages/cli/src/commands/render/plan.test.ts
+++ b/packages/cli/src/commands/render/plan.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { CliUsageError } from "../../utils/commandResult.js";
@@ -37,6 +37,42 @@ describe("createRenderPlan", () => {
     expect(Object.isFrozen(plan.environment)).toBe(true);
   });
 
+  // The catalog join reaches the render event through the plan, so a plan that
+  // silently drops it would leave every render reporting no catalog items.
+  it("resolves catalog usage from the project manifest and the render entry", () => {
+    writeFileSync(
+      join(projectDir, "index.html"),
+      '<main data-composition-id="main" data-width="1920" data-height="1080" data-fps="24">' +
+        '<div data-composition-src="compositions/kept.html" data-duration="2"></div></main>',
+    );
+    mkdirSync(join(projectDir, "compositions"), { recursive: true });
+    // `<template>`-wrapped, as sub-compositions are actually authored: template
+    // content is inert, so a DOM scan of these files would find nothing.
+    for (const name of ["kept", "dropped"]) {
+      writeFileSync(
+        join(projectDir, "compositions", `${name}.html`),
+        `<template id="${name}-template"><div data-composition-id="${name}" data-width="1920" data-height="1080"></div></template>`,
+      );
+    }
+    writeFileSync(
+      join(projectDir, "hyperframes.json"),
+      JSON.stringify({
+        registry: "https://example.test",
+        registryItems: [
+          { name: "kept", type: "hyperframes:block", target: "compositions/kept.html" },
+          { name: "dropped", type: "hyperframes:block", target: "compositions/dropped.html" },
+        ],
+      }),
+    );
+
+    const plan = createRenderPlan({ dir: projectDir, output: "result.mp4" });
+    expect(plan.catalogUsage).toEqual({
+      installed: ["dropped", "kept"],
+      usedBlocks: ["kept"],
+      manifestUnreadable: false,
+    });
+  });
+
   it("preserves an explicit strict-readiness opt-in", () => {
     const plan = createRenderPlan({ dir: projectDir, "best-effort": false });
     expect(plan.bestEffort).toBe(false);
diff --git a/packages/cli/src/commands/render/plan.ts b/packages/cli/src/commands/render/plan.ts
index 043b08db9..600a26776 100644
--- a/packages/cli/src/commands/render/plan.ts
+++ b/packages/cli/src/commands/render/plan.ts
@@ -29,6 +29,7 @@ import {
 } from "../../utils/renderArgs.js";
 import { normalizeSkillSlug } from "../../telemetry/skill.js";
 import { loadProjectConfig } from "../../utils/projectConfig.js";
+import { type CatalogUsage, summarizeCatalogUsage } from "../../utils/catalogUsage.js";
 
 const VALID_QUALITY = new Set(["draft", "standard", "high"]);
 const RENDER_FORMATS = ["mp4", "webm", "mov", "png-sequence", "gif"] as const;
@@ -99,6 +100,8 @@ export interface RenderPlan {
   quality: RenderQuality;
   authoringSkill?: string;
   invalidAuthoringSkill?: string;
+  /** Catalog items installed in this project, and those the entry reaches. */
+  catalogUsage: CatalogUsage;
   format: RenderFormat;
   gifLoop?: number;
   gifFpsCapped: boolean;
@@ -204,6 +207,10 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
       ? args.skill
       : undefined;
 
+  // Resolved here, once, from the same entry the render will use: batch rows
+  // vary only their variables, so every row shares this composition tree.
+  const catalogUsage = summarizeCatalogUsage(project.dir, renderTarget);
+
   const formatRaw = args.format ?? "mp4";
   const format = parseRenderFormat(formatRaw);
   if (!format) {
@@ -412,6 +419,7 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
     quality,
     authoringSkill,
     invalidAuthoringSkill,
+    catalogUsage,
     format,
     gifLoop,
     gifFpsCapped,
@@ -461,7 +469,6 @@ export function renderOutputDirectory(plan: RenderPlan): string {
 
 /** Resolve browser GPU mode from Docker, CLI, env, then the auto default. */
 // Re-exported by render.ts to preserve its tested public seam.
-// fallow-ignore-next-line unused-export
 export function resolveBrowserGpuForCli(
   useDocker: boolean,
   browserGpuArg: boolean | undefined,
diff --git a/packages/cli/src/telemetry/events.test.ts b/packages/cli/src/telemetry/events.test.ts
index 393e643d6..f7aa33ae3 100644
--- a/packages/cli/src/telemetry/events.test.ts
+++ b/packages/cli/src/telemetry/events.test.ts
@@ -190,6 +190,128 @@ describe("render telemetry events", () => {
     flush.mockClear();
   });
 
+  // The catalog join. Counts must be present at zero: the no-catalog cohort is
+  // what the with-catalog cohort is compared against, and an absent property is
+  // indistinguishable from an older CLI that never sent one.
+  it("reports zero catalog counts for a project with no registry items", () => {
+    trackRenderComplete({
+      durationMs: 1000,
+      fps: 30,
+      quality: "draft",
+      docker: false,
+      gpu: false,
+      catalogUsage: { installed: [], usedBlocks: [], manifestUnreadable: false },
+    });
+    const props = trackEvent.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(props.registry_item_count).toBe(0);
+    expect(props.registry_blocks_used_count).toBe(0);
+    expect(props.registry_items).toBeUndefined();
+  });
+
+  it("names the installed items and the subset the render reached", () => {
+    trackRenderComplete({
+      durationMs: 1000,
+      fps: 30,
+      quality: "draft",
+      docker: false,
+      gpu: false,
+      catalogUsage: {
+        installed: ["bar-chart-race", "data-chart"],
+        usedBlocks: ["data-chart"],
+        manifestUnreadable: false,
+      },
+    });
+    const props = trackEvent.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(props.registry_items).toBe("bar-chart-race,data-chart");
+    expect(props.registry_item_count).toBe(2);
+    expect(props.registry_blocks_used).toBe("data-chart");
+    expect(props.registry_blocks_used_count).toBe(1);
+  });
+
+  // A count is one integer with no cardinality risk. Capping it would lose the
+  // real number with no way downstream to tell 40 installs from 400.
+  it("caps the item names but reports the true counts past the cap", () => {
+    const installed = Array.from({ length: 45 }, (_, i) => `b${String(i + 1).padStart(2, "0")}`);
+    trackRenderComplete({
+      durationMs: 1000,
+      fps: 30,
+      quality: "draft",
+      docker: false,
+      gpu: false,
+      catalogUsage: { installed, usedBlocks: installed.slice(-5), manifestUnreadable: false },
+    });
+    const props = trackEvent.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(props.registry_item_count).toBe(45);
+    expect(props.registry_blocks_used_count).toBe(5);
+    expect(String(props.registry_items).split(",")).toHaveLength(40);
+    // The names are a window, and a query joining on them would otherwise read
+    // this project as 45 abandoned items: every used block sits past the cap,
+    // so `registry_blocks_used` is absent against a count of 5.
+    expect(props.registry_items_truncated).toBe(true);
+    expect(props.registry_blocks_used).toBeUndefined();
+  });
+
+  it("does not claim truncation when every name fits", () => {
+    trackRenderComplete({
+      durationMs: 1000,
+      fps: 30,
+      quality: "draft",
+      docker: false,
+      gpu: false,
+      catalogUsage: {
+        installed: ["bar-chart-race", "data-chart"],
+        usedBlocks: ["data-chart"],
+        manifestUnreadable: false,
+      },
+    });
+    const props = trackEvent.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(props.registry_items_truncated).toBeUndefined();
+  });
+
+  // Sliced independently the two lists come out disjoint, which breaks the one
+  // relationship any drop-off query relies on.
+  it("keeps the used names a subset of the reported installed names", () => {
+    const installed = Array.from({ length: 45 }, (_, i) => `b${String(i + 1).padStart(2, "0")}`);
+    trackRenderComplete({
+      durationMs: 1000,
+      fps: 30,
+      quality: "draft",
+      docker: false,
+      gpu: false,
+      catalogUsage: { installed, usedBlocks: installed.slice(-5), manifestUnreadable: false },
+    });
+    const props = trackEvent.mock.calls[0]?.[1] as Record<string, unknown>;
+    const reported = new Set(String(props.registry_items).split(","));
+    const used =
+      props.registry_blocks_used === undefined ? [] : String(props.registry_blocks_used).split(",");
+    expect(used.every((name) => reported.has(name))).toBe(true);
+  });
+
+  // The control cohort is the one that must not silently absorb failures: a
+  // project whose manifest cannot be read is not a project without a catalog.
+  it("flags an unreadable manifest instead of reporting it as zero catalog items", () => {
+    trackRenderComplete({
+      durationMs: 1000,
+      fps: 30,
+      quality: "draft",
+      docker: false,
+      gpu: false,
+      catalogUsage: { installed: [], usedBlocks: [], manifestUnreadable: true },
+    });
+    const props = trackEvent.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(props.registry_manifest_unreadable).toBe(true);
+    expect(props.registry_item_count).toBeUndefined();
+  });
+
+  // A caller that built render options by hand makes no catalog claim, rather
+  // than claiming zero items.
+  it("omits the catalog props entirely when usage was never resolved", () => {
+    trackRenderComplete({ durationMs: 1, fps: 30, quality: "draft", docker: false, gpu: false });
+    const props = trackEvent.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(props.registry_item_count).toBeUndefined();
+    expect(props.registry_blocks_used_count).toBeUndefined();
+  });
+
   it("flushes immediately after render_complete and render_error (exit races the lazy flush)", () => {
     trackRenderComplete({ durationMs: 1000, fps: 30, quality: "draft", docker: false, gpu: false });
     expect(flush).toHaveBeenCalledTimes(1);
diff --git a/packages/cli/src/telemetry/events.ts b/packages/cli/src/telemetry/events.ts
index 02b01701f..fb8737c53 100644
--- a/packages/cli/src/telemetry/events.ts
+++ b/packages/cli/src/telemetry/events.ts
@@ -1,6 +1,7 @@
 import { redactTelemetryString, type OutputResolutionIssueKind } from "@hyperframes/core";
 import type { SubTimelineWaitOutcome } from "@hyperframes/engine";
 import { FEEDBACK_RATING_SCALE } from "../utils/feedbackRating.js";
+import type { CatalogUsage } from "../utils/catalogUsage.js";
 import { flush, shouldTrack, trackEvent } from "./client.js";
 import { readConfig } from "./config.js";
 import { getPowerState } from "./system.js";
@@ -173,6 +174,60 @@ export function trackCommand(command: string, runId?: string): void {
   });
 }
 
+/**
+ * Cap on item names in one event. Registry names are low-cardinality slugs, but
+ * a project with a hundred blocks should not push a hundred-name string into
+ * every render. The cap belongs at the boundary that builds the string, and
+ * deliberately NOT on the counts: a count is one integer with no cardinality
+ * risk, and a saturated one loses the real number with no way downstream to
+ * tell 40 installs from 400.
+ */
+const MAX_REPORTED_ITEM_NAMES = 40;
+
+/**
+ * Catalog half of `render_complete`.
+ *
+ * Counts are emitted even when zero: the no-catalog cohort is exactly what the
+ * with-catalog cohort gets compared against, and a property that is simply
+ * absent is indistinguishable from an older CLI that never sent one. Names ride
+ * as a comma-joined string because event property values are scalars only (same
+ * shape as `recent_render_ids` on `cli_render_feedback`).
+ *
+ * The used names are narrowed to the reported installed names, so
+ * `registry_blocks_used` stays a subset of `registry_items` even when the cap
+ * bites. Sliced independently, the two lists can come out disjoint, breaking
+ * the one relationship a drop-off query relies on. When the cap does bite,
+ * `registry_items_truncated` says so: the counts still carry the truth, but the
+ * names are a window, and a query that joins on names must not read the
+ * difference as abandonment.
+ *
+ * An unreadable manifest reports itself and omits the counts rather than
+ * sending zeros, so a failed read cannot pose as a project that never used the
+ * catalog. Undefined usage means the caller built render options by hand rather
+ * than through the render plan, so it makes no catalog claim at all.
+ */
+function catalogEventProperties(
+  usage: CatalogUsage | undefined,
+): Record<string, string | number | boolean> {
+  if (!usage) return {};
+  if (usage.manifestUnreadable) return { registry_manifest_unreadable: true };
+  const names = usage.installed.slice(0, MAX_REPORTED_ITEM_NAMES);
+  const reportedNames = new Set(names);
+  const used = usage.usedBlocks.filter((name) => reportedNames.has(name));
+  const truncated = names.length < usage.installed.length;
+  return {
+    registry_item_count: usage.installed.length,
+    registry_blocks_used_count: usage.usedBlocks.length,
+    // Say when the name lists are a window rather than the whole set. Without
+    // it a name-joining drop-off query silently reads a truncated project as
+    // all-abandoned: the used blocks can all sit past the cap, leaving an empty
+    // `registry_blocks_used` against a non-zero count.
+    ...(truncated ? { registry_items_truncated: true } : {}),
+    ...(names.length > 0 ? { registry_items: names.join(",") } : {}),
+    ...(used.length > 0 ? { registry_blocks_used: used.join(",") } : {}),
+  };
+}
+
 export function trackRenderComplete(
   props: {
     durationMs: number;
@@ -180,6 +235,13 @@ export function trackRenderComplete(
     quality: string;
     /** Authoring workflow skill that drove this render (e.g. "product-launch-video"). */
     authoringSkill?: string;
+    /**
+     * Catalog items installed in this project, and those the rendered
+     * composition reaches. The pair is what joins `registry_item_added` to a
+     * finished video: an installed item missing from the used set was tried
+     * and dropped, which no add-time event can express.
+     */
+    catalogUsage?: CatalogUsage;
     workers?: number;
     // Worker auto-sizing provenance (RenderPerfSummary.workerSizing). Answers
     // "why N workers?" fleet-wide, and validates the advisory per-worker heap
@@ -292,6 +354,7 @@ export function trackRenderComplete(
       fps: props.fps,
       quality: props.quality,
       authoring_skill: props.authoringSkill,
+      ...catalogEventProperties(props.catalogUsage),
       workers: props.workers,
       workers_bound_by: props.workersBoundBy,
       workers_cpu_based: props.workersCpuBased,
diff --git a/packages/cli/src/utils/catalogUsage.test.ts b/packages/cli/src/utils/catalogUsage.test.ts
new file mode 100644
index 000000000..52808f83d
--- /dev/null
+++ b/packages/cli/src/utils/catalogUsage.test.ts
@@ -0,0 +1,215 @@
+import { describe, expect, it } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { summarizeCatalogUsage, type CatalogUsage } from "./catalogUsage.js";
+import type { RegistryItemRecord } from "./projectConfig.js";
+
+/**
+ * Materialize a throwaway project, summarize it, and clean up. Every case here
+ * needs the same fixture, so the shape lives once.
+ */
+function usageOf(
+  files: Record<string, string>,
+  registryItems?: RegistryItemRecord[],
+  entry = "index.html",
+): CatalogUsage {
+  const dir = mkdtempSync(join(tmpdir(), "hf-catalog-test-"));
+  try {
+    writeFileSync(
+      join(dir, "hyperframes.json"),
+      JSON.stringify({
+        registry: "https://example.test",
+        ...(registryItems ? { registryItems } : {}),
+      }),
+    );
+    for (const [rel, html] of Object.entries(files)) {
+      const path = join(dir, rel);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, html);
+    }
+    return summarizeCatalogUsage(dir, join(dir, entry));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Same as {@link usageOf}, but writes `hyperframes.json` verbatim. */
+function usageOfRawConfig(configText: string | null): CatalogUsage {
+  const dir = mkdtempSync(join(tmpdir(), "hf-catalog-test-"));
+  try {
+    if (configText !== null) writeFileSync(join(dir, "hyperframes.json"), configText);
+    writeFileSync(join(dir, "index.html"), entryDoc());
+    return summarizeCatalogUsage(dir, join(dir, "index.html"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function mountTag(src: string): string {
+  return `<div data-composition-src="${src}" data-duration="3" data-width="1920" data-height="1080"></div>`;
+}
+
+/** Render entry: a plain document, never `<template>`-wrapped (lint forbids it). */
+function entryDoc(...srcs: string[]): string {
+  return `<!doctype html><html><body><div id="root" data-composition-id="main" data-width="1920" data-height="1080">${srcs
+    .map(mountTag)
+    .join("")}</div></body></html>`;
+}
+
+/**
+ * A sub-composition as they are actually authored everywhere in this repo:
+ * wrapped in `<template>`. Template content is inert, so a DOM scan of this
+ * file finds nothing — the fixture exists to keep that failure from returning.
+ */
+function subCompDoc(id: string, ...srcs: string[]): string {
+  return `<template id="${id}-template"><div data-composition-id="${id}" data-width="1920" data-height="1080">${srcs
+    .map(mountTag)
+    .join("")}</div></template>`;
+}
+
+const BLOCK = (name: string): RegistryItemRecord => ({
+  name,
+  type: "hyperframes:block",
+  target: `compositions/${name}.html`,
+});
+
+describe("summarizeCatalogUsage", () => {
+  it("reports nothing for a project that never added a catalog item", () => {
+    expect(usageOf({ "index.html": entryDoc() })).toEqual({
+      installed: [],
+      usedBlocks: [],
+      manifestUnreadable: false,
+    });
+  });
+
+  // The whole point of the manifest: an item that was installed and then not
+  // mounted is a rejection, and no add-time event can say so.
+  it("separates an installed block that the entry mounts from one it dropped", () => {
+    expect(
+      usageOf(
+        {
+          "index.html": entryDoc("compositions/kept.html"),
+          "compositions/kept.html": subCompDoc("kept"),
+          "compositions/dropped.html": subCompDoc("dropped"),
+        },
+        [BLOCK("kept"), BLOCK("dropped")],
+      ),
+    ).toEqual({
+      installed: ["dropped", "kept"],
+      usedBlocks: ["kept"],
+      manifestUnreadable: false,
+    });
+  });
+
+  // Regression for two invariants that a DOM scan of raw files gets wrong, each
+  // of which reports a block that renders in every video as abandoned:
+  // `<template>` content is invisible to `querySelectorAll`, and nested
+  // `data-composition-src` is root-relative, not relative to its own file.
+  it("follows a root-relative mount from inside a template-wrapped sub-composition", () => {
+    expect(
+      usageOf(
+        {
+          "index.html": entryDoc("compositions/outer.html"),
+          "compositions/outer.html": subCompDoc("outer", "compositions/inner.html"),
+          "compositions/inner.html": subCompDoc("inner"),
+        },
+        [BLOCK("outer"), BLOCK("inner")],
+      ).usedBlocks,
+    ).toEqual(["inner", "outer"]);
+  });
+
+  // A cyclic project must not wedge a render that already produced a video.
+  it("terminates on a mount cycle", () => {
+    expect(
+      usageOf(
+        {
+          "index.html": entryDoc("compositions/a.html"),
+          "compositions/a.html": subCompDoc("a", "compositions/b.html"),
+          "compositions/b.html": subCompDoc("b", "compositions/a.html"),
+        },
+        [BLOCK("a"), BLOCK("b")],
+      ).usedBlocks,
+    ).toEqual(["a", "b"]);
+  });
+
+  // A mount the author commented out does not render, so it is not "used".
+  it("ignores a commented-out mount", () => {
+    expect(
+      usageOf(
+        {
+          "index.html": `<!doctype html><html><body><!-- ${mountTag("compositions/kept.html")} --></body></html>`,
+          "compositions/kept.html": subCompDoc("kept"),
+        },
+        [BLOCK("kept")],
+      ),
+    ).toEqual({ installed: ["kept"], usedBlocks: [], manifestUnreadable: false });
+  });
+
+  // Components are pasted inline, so there is no src to match. Reporting one as
+  // "used" would be a guess; reporting it as installed is a fact.
+  it("counts a component as installed but never as used", () => {
+    expect(
+      usageOf({ "index.html": entryDoc() }, [
+        {
+          name: "film-grain",
+          type: "hyperframes:component",
+          target: "compositions/components/film-grain.html",
+        },
+      ]),
+    ).toEqual({ installed: ["film-grain"], usedBlocks: [], manifestUnreadable: false });
+  });
+
+  it("drops a manifest name that is not a safe slug rather than sending it", () => {
+    expect(
+      usageOf({ "index.html": entryDoc() }, [
+        { name: "/Users/someone/secret", type: "hyperframes:block", target: "compositions/x.html" },
+        BLOCK("fine"),
+      ]).installed,
+    ).toEqual(["fine"]);
+  });
+
+  it("never matches a manifest target that escapes the project directory", () => {
+    expect(
+      usageOf({ "index.html": entryDoc("compositions/kept.html") }, [
+        { name: "escaping", type: "hyperframes:block", target: "../outside.html" },
+      ]).usedBlocks,
+    ).toEqual([]);
+  });
+
+  it("survives an entry file that does not exist", () => {
+    expect(usageOf({}, [BLOCK("kept")], "missing.html")).toEqual({
+      installed: ["kept"],
+      usedBlocks: [],
+      manifestUnreadable: false,
+    });
+  });
+
+  it("contributes nothing for a remote mount, which has no local file to match", () => {
+    expect(
+      usageOf({ "index.html": entryDoc("https://example.test/compositions/kept.html") }, [
+        BLOCK("kept"),
+      ]).usedBlocks,
+    ).toEqual([]);
+  });
+
+  // A degraded read must not enrol a catalog user into the no-catalog control
+  // group, which would bias the comparison toward "the catalog changes nothing".
+  it("distinguishes a corrupt manifest from a project that never used the catalog", () => {
+    expect(usageOfRawConfig("{ not valid json")).toEqual({
+      installed: [],
+      usedBlocks: [],
+      manifestUnreadable: true,
+    });
+    expect(usageOfRawConfig('{ "registry": "https://example.test" }')).toEqual({
+      installed: [],
+      usedBlocks: [],
+      manifestUnreadable: false,
+    });
+    expect(usageOfRawConfig(null)).toEqual({
+      installed: [],
+      usedBlocks: [],
+      manifestUnreadable: false,
+    });
+  });
+});
diff --git a/packages/cli/src/utils/catalogUsage.ts b/packages/cli/src/utils/catalogUsage.ts
new file mode 100644
index 000000000..715b9cd6e
--- /dev/null
+++ b/packages/cli/src/utils/catalogUsage.ts
@@ -0,0 +1,153 @@
+/**
+ * Which catalog (registry) items a project installed, and which of them the
+ * composition being rendered actually reaches.
+ *
+ * `hyperframes add` is the only place that knows a file came from the registry
+ * — installed files are plain composition HTML and carry no provenance marker —
+ * so it records each item in `hyperframes.json`. Render reads that manifest
+ * back and walks the composition's `data-composition-src` tree, letting the
+ * render event report both halves: what the project pulled in, and what
+ * survived into the video.
+ *
+ * The delta is the part no add-time event can produce. `registry_item_added`
+ * says a block was installed; only this says it was then thrown away.
+ */
+
+import { readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { collectSubCompositionSrcs } from "@hyperframes/parsers/asset-resolution";
+import { type RegistryItemRecord, readProjectConfigWithStatus } from "./projectConfig.js";
+
+/** Installed catalog items, and the subset the rendered composition reaches. */
+export interface CatalogUsage {
+  /**
+   * Every item name recorded by `hyperframes add`, sorted, deduped, slug-gated.
+   * Not truncated: the reporting cap belongs to whoever builds the event
+   * string, so a count taken from this array is the real number.
+   */
+  installed: string[];
+  /**
+   * Installed `hyperframes:block` items whose file is reachable from the render
+   * entry. Always a subset of {@link installed}. Components are excluded: they
+   * are pasted inline into the user's own markup rather than mounted by src, so
+   * a component leaves no trace to match.
+   */
+  usedBlocks: string[];
+  /**
+   * True when `hyperframes.json` exists but could not be read or parsed.
+   *
+   * A degraded read must not look like a project that never touched the
+   * catalog: the no-catalog cohort is the control this whole feature is
+   * measured against, and quietly enrolling failures into it biases the
+   * comparison toward "the catalog makes no difference".
+   */
+  manifestUnreadable: boolean;
+}
+
+const EMPTY: CatalogUsage = Object.freeze({
+  installed: [],
+  usedBlocks: [],
+  manifestUnreadable: false,
+});
+
+const UNREADABLE: CatalogUsage = Object.freeze({
+  installed: [],
+  usedBlocks: [],
+  manifestUnreadable: true,
+});
+
+/**
+ * Cap on files visited while walking the sub-composition tree. A composition
+ * nests a handful of blocks; anything past this is a pathological or cyclic
+ * project, and telemetry must not turn into an unbounded filesystem crawl.
+ */
+const MAX_VISITED_FILES = 250;
+
+/** Cap on a single file fed to the scanner, mirroring the composition census. */
+const MAX_HTML_BYTES = 20 * 1024 * 1024;
+
+/**
+ * Item names are slug-gated before they reach the anonymous event stream, the
+ * same guard `normalizeSkillSlug` applies to authoring skills: a custom or
+ * hand-edited registry must not be able to push paths, PII, or unbounded
+ * cardinality into telemetry. The two rules share a shape but not an owner —
+ * a registry name and a skill slug are free to diverge.
+ */
+const REGISTRY_ITEM_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/**
+ * Absolute paths of every composition file reachable from `entryPath` through
+ * `data-composition-src`, entry included.
+ *
+ * Two invariants are borrowed rather than re-derived, because getting either
+ * wrong silently reports a block that renders in every video as abandoned:
+ * references are collected by text scan (`collectSubCompositionSrcs`, so
+ * `<template>`-wrapped sub-compositions are visible), and each one resolves
+ * against the PROJECT ROOT at every nesting level, never the referencing
+ * file's directory. Both mirror the renderer's `parseSubCompositions`.
+ *
+ * Unreadable files are skipped rather than thrown: this feeds a telemetry
+ * property, and a render that produced a video must never fail on the way to
+ * reporting it.
+ */
+function reachableCompositions(projectDir: string, entryPath: string): Set<string> {
+  const seen = new Set<string>();
+  const queue = [resolve(entryPath)];
+  while (queue.length > 0 && seen.size < MAX_VISITED_FILES) {
+    const current = queue.shift()!;
+    if (seen.has(current)) continue;
+    seen.add(current);
+    let html: string;
+    try {
+      html = readFileSync(current, "utf-8");
+    } catch {
+      continue;
+    }
+    if (html.length > MAX_HTML_BYTES) continue;
+    for (const src of collectSubCompositionSrcs(html)) {
+      queue.push(resolve(projectDir, src));
+    }
+  }
+  return seen;
+}
+
+/** True when `target` (project-relative, per the manifest) is in `reachable`. */
+function isReached(projectDir: string, target: string, reachable: Set<string>): boolean {
+  // A manifest target is written project-relative. Guard against an absolute
+  // or escaping one rather than resolving it against the wrong root.
+  if (isAbsolute(target)) return false;
+  const abs = resolve(projectDir, target);
+  if (relative(projectDir, abs).startsWith("..")) return false;
+  return reachable.has(abs);
+}
+
+function reportableNames(names: string[]): string[] {
+  return [...new Set(names.filter((name) => REGISTRY_ITEM_NAME.test(name)))].sort();
+}
+
+/**
+ * Read the project's catalog manifest and resolve it against the composition
+ * being rendered. Returns empty sets for a project that never ran
+ * `hyperframes add`, which is the honest answer: no catalog items, not unknown.
+ */
+export function summarizeCatalogUsage(projectDir: string, entryPath: string): CatalogUsage {
+  const { status, config } = readProjectConfigWithStatus(projectDir);
+  if (status === "unreadable") return UNREADABLE;
+
+  const items: RegistryItemRecord[] = config?.registryItems ?? [];
+  if (items.length === 0) return EMPTY;
+
+  const installed = reportableNames(items.map((item) => item.name));
+  if (installed.length === 0) return EMPTY;
+
+  const reachable = reachableCompositions(projectDir, entryPath);
+  const usedBlocks = reportableNames(
+    items
+      .filter(
+        (item) =>
+          item.type === "hyperframes:block" && isReached(projectDir, item.target, reachable),
+      )
+      .map((item) => item.name),
+  );
+  return { installed, usedBlocks, manifestUnreadable: false };
+}
diff --git a/packages/cli/src/utils/projectConfig.test.ts b/packages/cli/src/utils/projectConfig.test.ts
index f783a9540..5a3ebd93b 100644
--- a/packages/cli/src/utils/projectConfig.test.ts
+++ b/packages/cli/src/utils/projectConfig.test.ts
@@ -9,6 +9,7 @@ import {
   projectConfigPath,
   readProjectConfig,
   resolveAutoProxy,
+  recordProjectRegistryItems,
   seedProjectAuthoringSkill,
   writeProjectConfig,
   PROJECT_CONFIG_FILENAME,
@@ -364,4 +365,101 @@ describe("projectConfig", () => {
       }
     });
   });
+  describe("recordProjectRegistryItems", () => {
+    const BLOCK = {
+      name: "data-chart",
+      type: "hyperframes:block",
+      target: "compositions/data-chart.html",
+    };
+
+    it("appends installed items to an existing config", () => {
+      const dir = tmp();
+      try {
+        writeProjectConfig(dir);
+        recordProjectRegistryItems(dir, [BLOCK]);
+        expect(loadProjectConfig(dir).registryItems).toEqual([BLOCK]);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    it("dedupes by name, so re-adding an item does not grow the manifest", () => {
+      const dir = tmp();
+      try {
+        writeProjectConfig(dir);
+        recordProjectRegistryItems(dir, [BLOCK]);
+        recordProjectRegistryItems(dir, [BLOCK, { ...BLOCK, name: "bar-chart-race" }]);
+        expect(loadProjectConfig(dir).registryItems?.map((i) => i.name)).toEqual([
+          "data-chart",
+          "bar-chart-race",
+        ]);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    // The old guard compared object identity, and `add` always builds fresh
+    // records, so a redundant re-add always rewrote the file. Pinned through
+    // the file's own byte-level formatting: a rewrite would re-serialize it.
+    it("does not rewrite the file when every item is already recorded", () => {
+      const dir = tmp();
+      try {
+        const text = `{\n\t"registry": "https://example.com/r",\n\t"registryItems": [\n\t\t{ "name": "data-chart", "type": "hyperframes:block", "target": "compositions/data-chart.html" }\n\t]\n}\n`;
+        writeFileSync(projectConfigPath(dir), text, "utf-8");
+        recordProjectRegistryItems(dir, [{ ...BLOCK }]);
+        expect(readFileSync(projectConfigPath(dir), "utf-8")).toBe(text);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    // The config is normally committed, so an install must not rewrite keys it
+    // does not own or reflow the file.
+    it("preserves unknown keys and the file's own indentation", () => {
+      const dir = tmp();
+      try {
+        writeFileSync(
+          projectConfigPath(dir),
+          JSON.stringify({ registry: "https://example.com/r", customKey: 42 }, null, 4),
+          "utf-8",
+        );
+        recordProjectRegistryItems(dir, [BLOCK]);
+        const text = readFileSync(projectConfigPath(dir), "utf-8");
+        expect(text).toContain('"customKey": 42');
+        expect(text).toContain('\n    "registry"');
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    it("does not create a config for a project that has none", () => {
+      const dir = tmp();
+      try {
+        recordProjectRegistryItems(dir, [BLOCK]);
+        expect(readProjectConfig(dir)).toBeUndefined();
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    it("leaves a corrupt config untouched", () => {
+      const dir = tmp();
+      try {
+        writeFileSync(projectConfigPath(dir), "{ not valid json", "utf-8");
+        recordProjectRegistryItems(dir, [BLOCK]);
+        expect(readFileSync(projectConfigPath(dir), "utf-8")).toBe("{ not valid json");
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    // normalizeConfig rebuilds from a whitelist; an omission there would read
+    // as "this project never installed a catalog item".
+    it("survives a normalizeConfig round-trip", () => {
+      expect(normalizeConfig({ registryItems: [BLOCK] }).registryItems).toEqual([BLOCK]);
+      expect(
+        normalizeConfig({ registryItems: [{ name: "x" }] as never }).registryItems,
+      ).toBeUndefined();
+    });
+  });
 });
diff --git a/packages/cli/src/utils/projectConfig.ts b/packages/cli/src/utils/projectConfig.ts
index c3afc7709..a1ec4d52f 100644
--- a/packages/cli/src/utils/projectConfig.ts
+++ b/packages/cli/src/utils/projectConfig.ts
@@ -33,6 +33,23 @@ export interface ProjectConfigMedia {
   autoProxy?: boolean;
 }
 
+/**
+ * One catalog item installed into this project by `hyperframes add`.
+ *
+ * Installed files are plain composition HTML with no provenance marker, so
+ * this manifest is the only record that a file came from the registry. It is
+ * what lets a render report which catalog items a finished video actually
+ * used, instead of only which ones were once downloaded.
+ */
+export interface RegistryItemRecord {
+  /** Registry item name, e.g. "data-chart". */
+  name: string;
+  /** Registry item type, e.g. "hyperframes:block". */
+  type: string;
+  /** Primary installed file, relative to the project root. */
+  target: string;
+}
+
 export interface ProjectConfig {
   $schema?: string;
   /** Base URL of the registry to pull items from. */
@@ -49,6 +66,13 @@ export interface ProjectConfig {
    * telemetry without the caller re-passing the flag.
    */
   authoringSkill?: string;
+  /**
+   * Catalog items installed by `hyperframes add`, in install order. Append-only
+   * and deduped by name; removing an item from the project does not prune it,
+   * so a later render still reports it as installed-but-unused rather than
+   * silently forgetting it was ever tried.
+   */
+  registryItems?: RegistryItemRecord[];
 }
 
 export const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
@@ -69,16 +93,41 @@ export function projectConfigPath(projectDir: string): string {
   return join(resolve(projectDir), PROJECT_CONFIG_FILENAME);
 }
 
+/**
+ * Why a project-config read produced no config.
+ *
+ * Most callers only need "did I get one", but a caller reporting on the config
+ * must not treat a broken file as an absent one: a project whose config cannot
+ * be read is not a project without a config, and collapsing the two enrolls a
+ * failure into whatever the empty case means.
+ */
+export type ProjectConfigReadStatus = "ok" | "missing" | "unreadable";
+
+/** Read `hyperframes.json`, distinguishing an absent file from a broken one. */
+export function readProjectConfigWithStatus(projectDir: string): {
+  status: ProjectConfigReadStatus;
+  config?: ProjectConfig;
+} {
+  const path = projectConfigPath(projectDir);
+  let text: string;
+  try {
+    text = readFileSync(path, "utf-8");
+  } catch (error) {
+    // Anything other than "not there" (permissions, I/O) is a real failure to
+    // read a config that may well exist.
+    return { status: isFileNotFound(error) ? "missing" : "unreadable" };
+  }
+  try {
+    return { status: "ok", config: normalizeConfig(JSON.parse(text) as Partial<ProjectConfig>) };
+  } catch {
+    return { status: "unreadable" };
+  }
+}
+
 /** Read `hyperframes.json` from a project directory. */
 export function readProjectConfig(projectDir: string): ProjectConfig | undefined {
-  const path = projectConfigPath(projectDir);
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf-8")) as Partial<ProjectConfig>;
-    return normalizeConfig(parsed);
-  } catch {
-    // Missing file or corrupt JSON → no config.
-    return undefined;
-  }
+  // Missing file or corrupt JSON → no config.
+  return readProjectConfigWithStatus(projectDir).config;
 }
 
 /**
@@ -104,9 +153,31 @@ export function normalizeConfig(partial: Partial<ProjectConfig>): ProjectConfig
     // Slug-gate on read so a hand-edited or corrupt value never reaches the
     // telemetry stream; an invalid slug simply drops the attribution.
     authoringSkill: normalizeSkillSlug(partial.authoringSkill),
+    // Whitelist rebuild - an omission here silently drops the manifest on
+    // every config round-trip, which would read as "this project never
+    // installed a catalog item".
+    registryItems: normalizeRegistryItems(partial.registryItems),
   };
 }
 
+/**
+ * Keep only well-formed records. A hand-edited or partially-written manifest
+ * degrades to the entries that still parse rather than failing a command that
+ * merely wanted to read the registry URL.
+ */
+function normalizeRegistryItems(raw: unknown): RegistryItemRecord[] | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  const items = raw.filter(
+    (entry): entry is RegistryItemRecord =>
+      isJsonObject(entry) &&
+      typeof entry.name === "string" &&
+      entry.name !== "" &&
+      typeof entry.type === "string" &&
+      typeof entry.target === "string",
+  );
+  return items.length > 0 ? items : undefined;
+}
+
 /** Write `hyperframes.json` to a project directory. Overwrites if present. */
 export function writeProjectConfig(
   projectDir: string,
@@ -162,9 +233,10 @@ function isFileNotFound(error: unknown): boolean {
  * empty slug is ignored. Best effort: a read-only or missing project directory
  * never fails the render it rode in on.
  *
- * This is the only writer that touches an ALREADY EXISTING `hyperframes.json`
- * (every other `writeProjectConfig` call site is guarded to write only when the
- * file is absent), so it must not round-trip through {@link normalizeConfig}:
+ * One of two writers that touch an ALREADY EXISTING `hyperframes.json` (the
+ * other is {@link recordProjectRegistryItems}; every plain `writeProjectConfig`
+ * call site is guarded to write only when the file is absent), so it must not
+ * round-trip through {@link normalizeConfig}:
  * that rebuilds the object from a field whitelist, which would drop keys it
  * does not know about and materialize defaults the user never wrote. The file
  * is normally committed, so a render must not introduce a diff beyond the one
@@ -210,3 +282,64 @@ export function seedProjectAuthoringSkill(projectDir: string, rawSkill: unknown)
     // never a render blocker.
   }
 }
+
+/**
+ * Append installed catalog items to `hyperframes.json` so a later render can
+ * report which of them the finished video actually used.
+ *
+ * Same in-place patch discipline as {@link seedProjectAuthoringSkill}, and for
+ * the same reason: this writes an ALREADY EXISTING, normally committed config,
+ * so it must not round-trip through {@link normalizeConfig} (a whitelist
+ * rebuild would drop unknown keys and materialize defaults the user never
+ * wrote). Existing entries are kept and deduped by name, so re-adding an item
+ * does not grow the file and a manually pruned entry is not resurrected twice.
+ *
+ * Best effort throughout: a read-only project, a missing config, or corrupt
+ * JSON must never fail the `add` it rode in on.
+ */
+export function recordProjectRegistryItems(
+  projectDir: string,
+  items: readonly RegistryItemRecord[],
+): void {
+  if (items.length === 0) return;
+  const path = projectConfigPath(projectDir);
+
+  let text: string;
+  try {
+    text = readFileSync(path, "utf-8");
+  } catch {
+    // No config to patch. `add` outside an initialized project is a valid
+    // flow; it simply leaves no manifest behind.
+    return;
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (!isJsonObject(parsed)) return;
+    const existing = normalizeRegistryItems(parsed.registryItems) ?? [];
+    const byName = new Map(existing.map((item) => [item.name, item]));
+    for (const item of items) byName.set(item.name, item);
+    // Compare by value, not identity: `add` always constructs fresh record
+    // objects, so an identity check would never match and re-adding an
+    // unchanged item would rewrite the file on every install.
+    const merged = [...byName.values()];
+    const unchanged =
+      merged.length === existing.length &&
+      merged.every((item, index) => {
+        const prior = existing[index];
+        return (
+          prior !== undefined &&
+          prior.name === item.name &&
+          prior.type === item.type &&
+          prior.target === item.target
+        );
+      });
+    if (unchanged) return;
+    parsed.registryItems = merged;
+    const indent = /\n([ \t]+)"/.exec(text)?.[1] ?? "  ";
+    writeFileSync(path, JSON.stringify(parsed, null, indent) + "\n", "utf-8");
+  } catch {
+    // Corrupt JSON or a read-only file: the manifest is telemetry provenance,
+    // never an install blocker.
+  }
+}
diff --git a/packages/cli/src/utils/projectConfigSchema.test.ts b/packages/cli/src/utils/projectConfigSchema.test.ts
new file mode 100644
index 000000000..36adaa320
--- /dev/null
+++ b/packages/cli/src/utils/projectConfigSchema.test.ts
@@ -0,0 +1,76 @@
+/**
+ * `docs/schema/hyperframes.json` is authored by hand (sync-schemas.ts mirrors
+ * only the registry schemas and skips this one), sets `additionalProperties:
+ * false` at both levels, and is the schema every generated `hyperframes.json`
+ * points at. So a new config key that lands in code but not in the schema turns
+ * a valid, committed config into one that fails validation in any schema-aware
+ * editor, with nothing in CI to notice.
+ *
+ * This pins the two together by validating a config that exercises every key
+ * the CLI can write, nested objects included. A key-name check alone is not
+ * enough: `registryItems` is an array of objects with their own
+ * `additionalProperties: false`, so a fourth field on `RegistryItemRecord`
+ * would recreate the same break one level down.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import {
+  DEFAULT_PROJECT_CONFIG,
+  type ProjectConfig,
+  type RegistryItemRecord,
+} from "./projectConfig.js";
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
+const SCHEMA_PATH = resolve(REPO_ROOT, "docs/schema/hyperframes.json");
+
+/**
+ * One record carrying every field the CLI writes. Typed, so a new field on
+ * `RegistryItemRecord` is a compile error here until it is listed, and then a
+ * validation failure until it is declared in the schema.
+ */
+const EVERY_RECORD_FIELD: Required<RegistryItemRecord> = {
+  name: "data-chart",
+  type: "hyperframes:block",
+  target: "compositions/data-chart.html",
+};
+
+/** A config exercising every key the CLI can write, at every level. */
+const EVERY_WRITTEN_KEY: Required<ProjectConfig> = {
+  $schema: "https://hyperframes.heygen.com/schema/hyperframes.json",
+  registry: "https://example.test/registry",
+  paths: DEFAULT_PROJECT_CONFIG.paths,
+  media: { autoProxy: true },
+  authoringSkill: "product-launch-video",
+  registryItems: [EVERY_RECORD_FIELD],
+};
+
+describe("hyperframes.json schema", () => {
+  const schema = JSON.parse(readFileSync(SCHEMA_PATH, "utf-8")) as Record<string, unknown>;
+  const validate = new Ajv2020({ strict: false, validateFormats: false }).compile(schema);
+
+  it("accepts a config using every key the CLI can write", () => {
+    // Guard the guard: without a closed schema at both levels the assertion
+    // below would pass for an undeclared key rather than failing.
+    expect(schema.additionalProperties).toBe(false);
+    const items = (schema.properties as Record<string, { items?: Record<string, unknown> }>)
+      .registryItems?.items;
+    expect(items?.additionalProperties).toBe(false);
+
+    expect(validate(EVERY_WRITTEN_KEY), JSON.stringify(validate.errors)).toBe(true);
+  });
+
+  // Proves the check above can fail, rather than passing because ajv was
+  // handed something it never rejects.
+  it("rejects a key the schema does not declare, at either level", () => {
+    expect(validate({ ...EVERY_WRITTEN_KEY, unknownTopLevelKey: 1 })).toBe(false);
+    expect(
+      validate({
+        ...EVERY_WRITTEN_KEY,
+        registryItems: [{ ...EVERY_RECORD_FIELD, unknownItemKey: 1 }],
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/packages/lint/src/project.ts b/packages/lint/src/project.ts
index 1330b467d..a64456601 100644
--- a/packages/lint/src/project.ts
+++ b/packages/lint/src/project.ts
@@ -7,6 +7,7 @@ import { checkSubCompositionUsability } from "@hyperframes/parsers/sub-compositi
 import { parseHTML } from "linkedom";
 import {
   cleanAssetUrl,
+  collectSubCompositionSrcs,
   isRemoteOrInlineUrl,
   isUnresolvedAssetPlaceholder,
   isWithinProjectRoot,
@@ -588,14 +589,9 @@ function lintMissingOrEmptySubComposition(
 
   // fallow-ignore-next-line complexity
   const walk = (html: string): void => {
-    const compositionSrcRe = /<[^>]*\bdata-composition-src\s*=\s*["']([^"']+)["'][^>]*>/gi;
-    const scannable = maskNonScannableRanges(html);
-    let match: RegExpExecArray | null;
-    while ((match = compositionSrcRe.exec(scannable)) !== null) {
-      const srcPath = (match[1] ?? "").trim();
-      if (!srcPath) continue;
-      if (isUnresolvedAssetPlaceholder(srcPath)) continue; // __UPPER__ placeholder or late-bound templating token
-
+    // Shared scanner — see collectSubCompositionSrcs for why this must be a
+    // text scan rather than a DOM query (template content is inert).
+    for (const srcPath of collectSubCompositionSrcs(html)) {
       // data-composition-src is always written root-relative (even from a
       // nested sub-composition) — matches the resolution the renderer uses
       // in packages/producer/src/services/htmlCompiler.ts (parseSubCompositions
diff --git a/packages/parsers/src/assetResolution.test.ts b/packages/parsers/src/assetResolution.test.ts
index 95381264c..3f99b9074 100644
--- a/packages/parsers/src/assetResolution.test.ts
+++ b/packages/parsers/src/assetResolution.test.ts
@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
-import { isUnresolvedAssetPlaceholder, maskNonScannableRanges } from "./assetResolution.js";
+import {
+  collectSubCompositionSrcs,
+  isUnresolvedAssetPlaceholder,
+  maskNonScannableRanges,
+} from "./assetResolution.js";
 
 describe("maskNonScannableRanges", () => {
   it("masks complete comments without changing offsets", () => {
@@ -55,3 +59,57 @@ describe("isUnresolvedAssetPlaceholder", () => {
     }
   });
 });
+
+describe("collectSubCompositionSrcs", () => {
+  it("finds mounts inside a template, which a DOM query cannot see", () => {
+    const html =
+      '<!doctype html><html><body><div data-composition-src="compositions/a.html"></div>' +
+      '<template id="t"><div data-composition-src="compositions/b.html"></div></template></body></html>';
+    expect(collectSubCompositionSrcs(html)).toEqual(["compositions/a.html", "compositions/b.html"]);
+  });
+
+  it("skips commented-out, scripted, and styled mounts", () => {
+    const html =
+      '<!-- <div data-composition-src="commented.html"></div> -->' +
+      "<script>const s = '<div data-composition-src=\"scripted.html\"></div>';</script>" +
+      '<style>/* <div data-composition-src="styled.html"></div> */</style>' +
+      '<div data-composition-src="real.html"></div>';
+    expect(collectSubCompositionSrcs(html)).toEqual(["real.html"]);
+  });
+
+  it("skips build-time placeholders and dedupes repeats", () => {
+    const html =
+      '<div data-composition-src="__SCENE__"></div>' +
+      '<div data-composition-src="{{scene}}"></div>' +
+      '<div data-composition-src="a.html"></div><div data-composition-src="a.html"></div>';
+    expect(collectSubCompositionSrcs(html)).toEqual(["a.html"]);
+  });
+
+  // A remote mount names no file on disk, and every caller resolves what comes
+  // back against the project root. Letting one through yields a nonsense path
+  // (`<projectDir>/https:/host/a.html`): a false "does not exist" for lint, and
+  // a wasted slot against the telemetry walk's file budget.
+  it("drops remote and inline mounts, keeping local ones", () => {
+    const html =
+      '<div data-composition-src="https://host/remote.html"></div>' +
+      '<div data-composition-src="//host/protocol-relative.html"></div>' +
+      '<div data-composition-src="data:text/html,inline"></div>' +
+      '<div data-composition-src="compositions/local.html"></div>';
+    expect(collectSubCompositionSrcs(html)).toEqual(["compositions/local.html"]);
+  });
+
+  it("ignores an unterminated final tag and an attribute outside any tag", () => {
+    expect(collectSubCompositionSrcs('<div data-composition-src="a.html"')).toEqual([]);
+    expect(collectSubCompositionSrcs('data-composition-src="a.html"')).toEqual([]);
+  });
+
+  // Regression guard, and it needs no timing assertion to bite: the previous
+  // whole-file regex had two open-ended `[^>]*` spans, which is quadratic on
+  // input full of `<` with no `>`. At 1MB that ran for minutes, so this case
+  // failed on the suite timeout. This scan walks tag by tag and is linear.
+  // The function is on the render-plan path, so a truncated download or a blob
+  // of stray `<` must not be able to hang a render before it starts.
+  it("stays fast on a megabyte of unterminated tag openings", () => {
+    expect(collectSubCompositionSrcs("<".repeat(1024 * 1024))).toEqual([]);
+  });
+});
diff --git a/packages/parsers/src/assetResolution.ts b/packages/parsers/src/assetResolution.ts
index 933be9cb3..aca5fbeb1 100644
--- a/packages/parsers/src/assetResolution.ts
+++ b/packages/parsers/src/assetResolution.ts
@@ -42,6 +42,75 @@ export function isUnresolvedAssetPlaceholder(rawSrc: string): boolean {
   return /^__[A-Z_]+__$/.test(rawSrc.trim()) || hasUnresolvedTemplatingToken(rawSrc);
 }
 
+/** `data-composition-src="..."`, matched within a single already-delimited tag. */
+const COMPOSITION_SRC_ATTR = /\bdata-composition-src\s*=\s*["']([^"']+)["']/i;
+
+/**
+ * Every `data-composition-src` reference in one composition file's raw text, in
+ * document order, deduped. The single owner of "which sub-compositions does
+ * this file mount", so lint, telemetry, and any future scanner cannot drift
+ * apart on the answer.
+ *
+ * Text-scanning rather than DOM-walking, and that is the load-bearing choice.
+ * Every sub-composition except the render entry is authored inside a
+ * `<template>` (the root index.html is forbidden from using that wrapper;
+ * everything else prefers it). Template content is inert: it lives under
+ * `template.content`, not the live document, so `document.querySelectorAll`
+ * on a raw sub-composition file finds nothing and every nested reference
+ * disappears. The renderer only gets away with a DOM scan because it recurses
+ * on COMPILED html, where the wrapper is already gone.
+ *
+ * Callers must resolve each value against the PROJECT ROOT, never the
+ * referencing file's directory: `data-composition-src` is root-relative at
+ * every nesting level (see `parseSubCompositions` in htmlCompiler.ts).
+ *
+ * Comments, `<style>`, and `<script>` bodies are masked first so a
+ * commented-out mount is not counted as a real one. Build-time placeholders and
+ * remote or inline URLs are dropped: neither names a file on disk, and every
+ * caller resolves what comes back against the project root.
+ *
+ * The scan walks tag by tag with `indexOf` rather than running one regex with
+ * two open-ended `[^>]*` spans across the whole file. That shape is quadratic:
+ * on input full of `<` with no `>`, every `<` starts a scan to end-of-string
+ * that then backtracks, measured at 41ms / 165ms / 660ms / 2640ms for 10k /
+ * 20k / 40k / 80k characters. This function runs on every render (via the
+ * render plan), so a truncated download or a blob full of stray `<` would hang
+ * the plan step before any video is produced. Bounding each regex to one
+ * already-delimited tag makes the whole scan linear.
+ */
+export function collectSubCompositionSrcs(html: string): string[] {
+  const scannable = maskNonScannableRanges(html);
+  const srcs: string[] = [];
+  const seen = new Set<string>();
+
+  let cursor = 0;
+  while (cursor < scannable.length) {
+    const open = scannable.indexOf("<", cursor);
+    if (open === -1) break;
+    const close = scannable.indexOf(">", open + 1);
+    // An unterminated final tag is not a tag. The previous whole-file regex
+    // also required a closing `>`, so this drops nothing it used to find.
+    if (close === -1) break;
+    cursor = close + 1;
+
+    const match = COMPOSITION_SRC_ATTR.exec(scannable.slice(open, cursor));
+    if (!match) continue;
+    const src = (match[1] ?? "").trim();
+    if (!src || seen.has(src)) continue;
+    // __UPPER__ placeholder or late-bound templating token — not a real reference.
+    if (isUnresolvedAssetPlaceholder(src)) continue;
+    // A remote or inline mount names no file on disk. Every caller resolves
+    // these against the project root, so letting one through produces a
+    // nonsense path (`<projectDir>/https:/host/a.html`) that then reads as a
+    // missing local file: a false "does not exist" for lint, and a wasted
+    // visit against the telemetry walk's file budget.
+    if (isRemoteOrInlineUrl(src)) continue;
+    seen.add(src);
+    srcs.push(src);
+  }
+  return srcs;
+}
+
 export function cleanAssetUrl(url: string): string {
   return url.trim().split(/[?#]/, 1)[0] ?? "";
 }