@@ -0,0 +1,40 @@
+name: Comments
+
+permissions:
+  contents: read
+
+# No secrets and a read-only token, so fork PRs run it too. Rules: CONTRIBUTING.md, "Comments".
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+concurrency:
+  group: comments-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  comments:
+    name: Comments
+    # A release PR carries commits that each passed this gate on their own PR.
+    if: ${{ !startsWith(github.head_ref, 'release/') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          # The PR's own head, graded against its merge-base: not the merge preview, which would
+          # charge the branch for every comment main changed since it forked.
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+      # The commented-out-code rule asks the TypeScript parser, a root dependency.
+      - run: bash scripts/ci/install-workspace-dependencies.sh --ignore-scripts
+      - name: Test the checker
+        run: node --test scripts/check-comment-citations.test.mjs
+      - name: Check the comments this diff touched
+        env:
+          COMMENT_CHECK_BASE: ${{ github.event.pull_request.base.sha }}
+        run: node scripts/check-comment-citations.mjs
@@ -55,13 +55,15 @@ jobs:
         id: filter
         with:
           token: ""
+          # A file counts only if it matches every pattern. Player and Studio `src/` run in a browser
+          # and no code reads a package README, so a diff confined to them skips Windows.
+          predicate-quantifier: every
           filters: |
             code:
-              - "packages/**"
-              - "scripts/**"
-              - "package.json"
-              - "bun.lock"
-              - ".github/workflows/windows-render.yml"
+              - "{packages/**,scripts/**,package.json,bun.lock,.github/workflows/windows-render.yml}"
+              - "!packages/player/src/**"
+              - "!packages/studio/src/**"
+              - "!packages/*/README.md"
 
   preflight:
     name: Preflight (lint + format)
 
@@ -69,6 +69,19 @@ If you must add a cast, add a comment:
 const event = data as unknown as RuntimeEvent;
 ```
 
+#### Comments
+
+A comment says what the code cannot: the reason, the invariant, the non-obvious constraint. Names, types and tests carry the rest, and reasoning or history goes in the PR description, where it stays attached to the change.
+
+The `Comments` check (`scripts/check-comment-citations.mjs`) grades the comments a PR adds or edits:
+
+- **Citations must resolve.** A backticked path, a `path:line`, a backticked camelCase symbol, or "pinned by" / "covered by" / "see" plus a test file must point at something in the repo. A comment that names its source reads as evidence, so a stale one sends the next reader to a dead end.
+- **No history.** "used to", "previously", "was removed", "before this change", "PR #123" describe the past, which git already records. State what is true now.
+- **No commented-out code.** Delete it; git keeps it.
+- **No block over 40 lines.** Cut it to the why and the invariant. A block that must stay whole (a licence, a diagram, a protocol table) starts with `comment-length: <reason>`.
+
+Only comment blocks holding a line your PR added can fail. Findings elsewhere in a file you touched are printed as warnings, and fixing one while you are there is welcome. To grade files by hand, pass their paths: `node scripts/check-comment-citations.mjs path/to/file.ts`.
+
 ## Adding Registry Items (Blocks & Components)
 
 The registry at `registry/` contains reusable items installable via `hyperframes add <name>`. Each item lives in its own directory under `registry/blocks/` or `registry/components/`.
 
@@ -242,6 +242,35 @@ script, CLI overrides, and which value wins. If you are building tooling on
 `@hyperframes/core`, `extractCompositionMetadata()` reads the same
 `data-composition-variables` array — that is how Studio builds its editing UI.
 
+## Load a composition's own files from its script
+
+When a composition is mounted, a `src` or `href` attribute that points at a
+file next to it is rewritten to where that file lives, so
+`<img src="assets/logo.png">` keeps working. A path your script builds is a
+plain string and is never rewritten, so resolve it with
+`window.__hyperframes.assetUrl()`. It takes a path written relative to the
+composition's own file and returns a URL the page can load, whether the file is
+mounted, previewed or opened on its own.
+
+A path meant from the project root, such as `assets/logo.png` in a composition
+at `compositions/intro.html` whose image sits in the project's own `assets/`
+folder, already resolves from the page. Leave it as a plain string:
+`assetUrl()` would look for it beside the composition and miss.
+
+```html compositions/globe/globe.html
+<div data-composition-id="globe" data-width="1920" data-height="1080">
+  <script>
+    const texture = new THREE.TextureLoader().load(
+      __hyperframes.assetUrl("assets/earth.jpg"),
+    );
+  </script>
+</div>
+```
+
+A separate script file (`<script src="...">`) has no composition of its own to
+resolve against. Resolve the URLs in the composition's inline script and hand
+them over, for example on a global the file reads.
+
 ## See every composition in a project
 
 ```bash
 
@@ -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
 
@@ -52,7 +52,7 @@
     "player:perf": "bun run --filter @hyperframes/player perf",
     "format:check": "oxfmt --check .",
     "knip": "knip",
-    "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-registry-set-delta.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-media-use-copy-parity.test.mjs scripts/check-svg-sanitize-parity.test.mjs scripts/check-media-use-svg-sanitize-generated.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-large-files.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/publish-workflow.test.mjs scripts/pr-edit-concurrency.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/lint-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts scripts/catalog-publication.test.mjs scripts/ci/resolve-workflow-pr.test.mjs scripts/check-catalog-source-pr.test.mjs scripts/generate-registry-items.test.ts scripts/catalog-drift.test.ts scripts/catalog-fetch-mirror.test.ts scripts/catalog-script-inlining.test.ts scripts/catalog-detail.test.ts scripts/generate-catalog-pages.test.ts scripts/verify-catalog-payloads.test.ts scripts/registry-skill-files.test.ts scripts/creator-editing-capabilities.test.mjs scripts/generate-catalog-previews.test.ts scripts/registry-primitive-payloads.test.ts registry/components/pan-stations/pan-stations.test.mjs && vitest run scripts/catalog/ scripts/contrastRatchet.test.ts scripts/generate-catalog-payloads.test.ts",
+    "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-registry-set-delta.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-comment-citations.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-media-use-copy-parity.test.mjs scripts/check-svg-sanitize-parity.test.mjs scripts/check-media-use-svg-sanitize-generated.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-large-files.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/publish-workflow.test.mjs scripts/pr-edit-concurrency.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/lint-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts scripts/catalog-publication.test.mjs scripts/ci/resolve-workflow-pr.test.mjs scripts/check-catalog-source-pr.test.mjs scripts/generate-registry-items.test.ts scripts/catalog-drift.test.ts scripts/catalog-fetch-mirror.test.ts scripts/catalog-script-inlining.test.ts scripts/catalog-detail.test.ts scripts/generate-catalog-pages.test.ts scripts/verify-catalog-payloads.test.ts scripts/registry-skill-files.test.ts scripts/creator-editing-capabilities.test.mjs scripts/generate-catalog-previews.test.ts scripts/registry-primitive-payloads.test.ts registry/components/pan-stations/pan-stations.test.mjs && vitest run scripts/catalog/ scripts/contrastRatchet.test.ts scripts/generate-catalog-payloads.test.ts",
     "typecheck:scripts": "tsc --noEmit -p scripts/tsconfig.json",
     "test:skills": "node --test 'skills/**/*.test.mjs' 'packages/cli/src/media-use/**/*.test.mjs'",
     "generate:previews": "tsx scripts/generate-template-previews.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,
+    });
+  });
+});
@@ -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.
  *
 
@@ -57,6 +57,19 @@ vi.mock("../browser/manager.js", () => ({
   ensureBrowser: async () => ({ executablePath: undefined, source: "system" }),
 }));
 
+// Lets one test hold the project history in its opening; every other test opens the real one.
+const historyState = vi.hoisted(() => ({
+  open: null as null | ((...args: unknown[]) => Promise<unknown>),
+}));
+vi.mock("@hyperframes/studio-server", async (importOriginal) => {
+  const original = await importOriginal<typeof import("@hyperframes/studio-server")>();
+  return {
+    ...original,
+    openProjectHistory: (...args: Parameters<typeof original.openProjectHistory>) =>
+      historyState.open ? historyState.open(...args) : original.openProjectHistory(...args),
+  };
+});
+
 // Only `fs.watch` is replaced, so the SSE describe below can fire a file-change
 // on demand; every other server test keeps reading and writing real files.
 const mockWatcher = new EventEmitter() as EventEmitter & { close: () => void };
@@ -113,6 +126,47 @@ describe("Studio thumbnail GPU capture plumbing", () => {
   });
 });
 
+describe("createStudioServer project history (D-491)", () => {
+  it("serves the project's history, and a change the watcher sees becomes an entry", async () => {
+    const projectDir = tmpProject();
+    writeFileSync(join(projectDir, "index.html"), "<html>before</html>");
+    server = createStudioServer({ projectDir, historyRoot: tmpProject() });
+    const historyUrl = `/api/projects/${encodeURIComponent(basename(projectDir))}/history`;
+    const list = async () =>
+      (await (await server!.app.request(historyUrl)).json()) as {
+        entries: Array<{ who: { kind: string } }>;
+        back: { label: string } | null;
+      };
+    expect(await list()).toMatchObject({ entries: [], back: null });
+
+    writeFileSync(join(projectDir, "index.html"), "<html>agent</html>");
+    mockWatcher.emit("change", "change", "index.html");
+
+    // Writes with no window open group until 2 s of quiet.
+    await vi.waitFor(async () => expect((await list()).entries).toHaveLength(1), {
+      timeout: 5_000,
+      interval: 200,
+    });
+    expect((await list()).entries[0]!.who.kind).toBe("outside");
+    await server.shutdown();
+  });
+
+  it("shutdown returns within preview's exit watchdog while the history is still opening", async () => {
+    historyState.open = () => new Promise(() => {});
+    try {
+      const projectDir = tmpProject();
+      server = createStudioServer({ projectDir, historyRoot: tmpProject() });
+      void server.app.request(`/api/projects/${encodeURIComponent(basename(projectDir))}/history`);
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      const started = Date.now();
+      await server.shutdown();
+      expect(Date.now() - started).toBeLessThan(2_900);
+    } finally {
+      historyState.open = null;
+    }
+  });
+});
+
 describe("createStudioServer autoProxy plumbing", () => {
   it("hyperframes.json media.autoProxy=false flows through to the adapter", () => {
     const projectDir = tmpProject();