fix(cli): catalog --json carries each item's preview video and poster (#4443)

The catalog already loads every item's manifest, preview included, but the
--json rows dropped it, so an app listing the catalog had no way to show an
item before add downloads it. Rows now carry preview when the item has one.

docs/packages/cli.mdx

@@ -172,7 +172,9 @@ npx hyperframes catalog --human-friendly         # picker; installs on select
 
 Filter with `--type` (`block` or `component`) and `--tag` (`social`,
 `transition`, `text`, …). Default output is a table of name, type, description,
-and tags, shaped for agents to parse; `--json` is the structured form.
+and tags, shaped for agents to parse; `--json` is the structured form. Each
+`--json` row has the item's name, type, title, description and tags, plus its
+dimensions, duration and `preview` (`video` and `poster` URLs) when it has them.
 `--human-friendly` opens a picker that runs `add` on whatever you select.
 
 ## Bring in source material

packages/cli/src/commands/catalog.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-import { countUnindexed, pickByName, searchMissCommand } from "./catalog.js";
+import type { RegistryItem } from "@hyperframes/core";
+import { catalogRow, countUnindexed, pickByName, searchMissCommand } from "./catalog.js";
 
 /** The whole registry, which is what "in this registry" has to be measured against. */
 const registryNames = new Set(["fade-through", "whip-pan", "count-up"]);
@@ -667,3 +668,30 @@ describe("the on-device download offer", () => {
     expect(state.consentRecorded).toEqual([]);
   });
 });
+
+describe("catalogRow", () => {
+  const block = {
+    name: "app-showcase",
+    type: "hyperframes:block",
+    title: "App Showcase",
+    description: "Three phones",
+    tags: ["showcase"],
+    dimensions: { width: 1920, height: 1080 },
+    duration: 5,
+    files: [],
+  } as unknown as RegistryItem;
+
+  it("carries the preview so an app can show the item before add downloads it", () => {
+    const preview = { video: "https://example.test/a.mp4", poster: "https://example.test/a.png" };
+    expect(catalogRow({ ...block, preview } as RegistryItem)).toEqual({
+      name: "app-showcase",
+      type: "block",
+      title: "App Showcase",
+      description: "Three phones",
+      tags: ["showcase"],
+      dimensions: { width: 1920, height: 1080 },
+      duration: 5,
+      preview,
+    });
+  });
+});

packages/cli/src/commands/catalog.ts

@@ -10,7 +10,7 @@ export const examples: Example[] = [
 ];
 
 import * as clack from "@clack/prompts";
-import { type ItemType } from "@hyperframes/core";
+import { type ItemType, type RegistryItem } from "@hyperframes/core";
 import { c } from "../ui/colors.js";
 import { loadAllItems } from "../registry/resolver.js";
 import { fetchRegistryManifest } from "../registry/remote.js";
@@ -332,15 +332,7 @@ export default defineCommand({
     }
 
     if (json) {
-      const output = matching.map((item) => ({
-        name: item.name,
-        type: item.type.replace("hyperframes:", ""),
-        title: item.title,
-        description: item.description,
-        tags: item.tags ?? [],
-        ...("dimensions" in item && item.dimensions ? { dimensions: item.dimensions } : {}),
-        ...("duration" in item && item.duration ? { duration: item.duration } : {}),
-      }));
+      const output = matching.map(catalogRow);
       if (!query) {
         // A plain listing has no tier and no drop count, and this array shape
         // is already released. Leave it alone.
@@ -484,6 +476,20 @@ export default defineCommand({
   },
 });
 
+/** One `--json` row: what an agent or app needs to pick an item and show it before `add` downloads anything. */
+export function catalogRow(item: RegistryItem) {
+  return {
+    name: item.name,
+    type: item.type.replace("hyperframes:", ""),
+    title: item.title,
+    description: item.description,
+    tags: item.tags ?? [],
+    ...("dimensions" in item && item.dimensions ? { dimensions: item.dimensions } : {}),
+    ...("duration" in item && item.duration ? { duration: item.duration } : {}),
+    ...(item.preview ? { preview: item.preview } : {}),
+  };
+}
+
 /**
  * Resolve ranked names against the items this registry actually has.
  *