feat(registry): declared control surface — schema field, catalog controls table, contributor docs

Adds the control-surface convention for registry items:

- registry-item.json schema: optional controls field — name, type
  (toggle/variant/scalar), values/fields, min/max, default, drives; variant
  requires values, toggle forbids them, scalar requires both bounds.
- generate-catalog-pages.ts: renders the declaration as a Controls table on
  the item's generated catalog page; the section is generator-owned
  (GENERATED_HEADINGS) so it regenerates and disappears with the manifest.
- CONTROL_TYPES constant + updated enum drift-guard test in @hyperframes/core.
- hyperframes-registry skill docs: the Control surface build rule (budget,
  three control types, mapping laws, reserved controls, CONFIG comment
  grammar), a Clarify-step question, Quality Gate checkboxes + reviewer audit
  procedure, controls declaration in the templates and manifest-fields docs,
  and the component examples rewritten to the CONFIG-reading-helper pattern
  (raw tween args never migrate into host code).

The field is optional today and required at the Quality Gate for new items;
existing items are unaffected (regenerating the catalog with no declarations
is a byte-identical no-op).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: jbernard077

packages/core/schemas/registry-item.json

@@ -125,6 +125,76 @@
         "poster": { "type": "string" }
       }
     },
+    "controls": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The item's declared control surface — the single authoring source for control documentation. Each entry mirrors one control in the item's top-of-script CONFIG object and is rendered as a controls table on the item's generated catalog page.",
+      "items": {
+        "type": "object",
+        "required": ["name", "type", "drives"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-zA-Z][a-zA-Z0-9]*$",
+            "description": "Control name as it appears in CONFIG. Intent-named (e.g. \"energy\", \"layout\"), never implementation-named (e.g. \"staggerMs\")."
+          },
+          "type": {
+            "type": "string",
+            "enum": ["toggle", "variant", "scalar"],
+            "description": "toggle = boolean between two authored states; variant = enum over N authored poses; scalar = bounded number interpolating authored anchor states through a mapping."
+          },
+          "values": {
+            "type": "array",
+            "minItems": 2,
+            "items": { "type": "string", "minLength": 1 },
+            "description": "variant only: the authored poses. Toggles omit this (always true | false)."
+          },
+          "fields": {
+            "type": "array",
+            "minItems": 2,
+            "items": { "type": "string", "minLength": 1 },
+            "description": "Maps one declared control to N CONFIG keys (e.g. a paired animationIn/animationOut toggle counting as one control). default is then keyed per field."
+          },
+          "min": {
+            "type": "number",
+            "description": "scalar only: lower declared bound (out-of-bounds input clamps here, loudly)."
+          },
+          "max": {
+            "type": "number",
+            "description": "scalar only: upper declared bound (out-of-bounds input clamps here, loudly)."
+          },
+          "default": {
+            "description": "The shipped state: variant = one of values; toggle = boolean (or a per-field object when fields is set); scalar = a number within min..max."
+          },
+          "drives": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What the control drives — the designed state group or mapping behind it."
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "required": ["type"],
+              "properties": { "type": { "const": "variant" } }
+            },
+            "then": { "required": ["values"] },
+            "else": { "not": { "required": ["values"] } }
+          },
+          {
+            "if": {
+              "required": ["type"],
+              "properties": { "type": { "const": "scalar" } }
+            },
+            "then": { "required": ["min", "max"] },
+            "else": {
+              "not": { "anyOf": [{ "required": ["min"] }, { "required": ["max"] }] }
+            }
+          }
+        ]
+      }
+    },
     "relatedSkill": {
       "type": "string",
       "minLength": 1

packages/core/src/index.ts

@@ -352,6 +352,7 @@ export type {
 export {
   ITEM_TYPES,
   FILE_TYPES,
+  CONTROL_TYPES,
   ITEM_TYPE_DIRS,
   isExampleItem,
   isBlockItem,

packages/core/src/registry/index.ts

@@ -18,6 +18,7 @@ export type {
 export {
   ITEM_TYPES,
   FILE_TYPES,
+  CONTROL_TYPES,
   ITEM_TYPE_DIRS,
   BLOCK_CATEGORIES,
   resolveBlockCategory,

packages/core/src/registry/types.test.ts

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
 import {
+  CONTROL_TYPES,
   FILE_TYPES,
   ITEM_TYPES,
   isBlockItem,
@@ -120,13 +121,15 @@ describe("registry types", () => {
       expect(setEquals(enums[0]!, ITEM_TYPES)).toBe(true);
     });
 
-    it("registry-item.json has exactly two `type` enums: one ITEM_TYPES, one FILE_TYPES", () => {
+    it("registry-item.json has exactly three `type` enums: ITEM_TYPES, FILE_TYPES, CONTROL_TYPES", () => {
       const enums = collectEnums(registryItemSchema, "type");
       const distinct = new Set(enums.map(setKey));
-      // Two semantically distinct enums — the item's `type` and each file's `type`.
-      expect(distinct.size).toBe(2);
+      // Three semantically distinct enums — the item's `type`, each file's
+      // `type`, and each declared control's `type`.
+      expect(distinct.size).toBe(3);
       expect(enums.some((e) => setEquals(e, ITEM_TYPES))).toBe(true);
       expect(enums.some((e) => setEquals(e, FILE_TYPES))).toBe(true);
+      expect(enums.some((e) => setEquals(e, CONTROL_TYPES))).toBe(true);
     });
   });
 

packages/core/src/registry/types.ts

@@ -153,6 +153,14 @@ export const FILE_TYPES = [
   "hyperframes:timeline",
 ] as const satisfies readonly FileType[];
 
+/**
+ * The declared-control types in a registry item's `controls` field: toggle
+ * (boolean between two authored states), variant (enum over N authored poses),
+ * scalar (bounded number interpolating authored anchor states through a
+ * mapping). Kept in sync with the `controls` enum in registry-item.json.
+ */
+export const CONTROL_TYPES = ["toggle", "variant", "scalar"] as const;
+
 /**
  * Directory segment where each item type lives under a registry root — both
  * on disk (`registry/examples/…`) and in URL construction

scripts/generate-catalog-pages.ts

@@ -177,6 +177,7 @@ function discoverItems(): { kind: ItemKind; manifest: RegistryItem }[] {
 const GENERATED_HEADINGS = new Set([
   // current template
   "install",
+  "controls",
   "variables",
   "source",
   "add it to your video",
@@ -780,6 +781,77 @@ function generateVariables(manifest: RegistryItem): string[] {
  * not installed yet. Collapsed because these run to several hundred lines and an
  * expanded wall of markup would push everything else off the page.
  */
+interface ItemControl {
+  name: string;
+  type: "toggle" | "variant" | "scalar";
+  values?: string[];
+  fields?: string[];
+  min?: number;
+  max?: number;
+  default?: unknown;
+  drives: string;
+}
+
+/** Pipe characters break table cells; everything user-authored passes through here. */
+function tableCell(value: string): string {
+  return value.replace(/\|/g, "\\|");
+}
+
+/** The allowed inputs for one control, written the way a reader has to type them. */
+function controlRange(c: ItemControl): string {
+  if (c.type === "toggle") return "`true` / `false`";
+  if (c.type === "variant" && c.values?.length) {
+    return c.values.map((v) => `\`${v}\``).join(", ");
+  }
+  if (c.type === "scalar") {
+    if (typeof c.min === "number" && typeof c.max === "number") return `\`${c.min}\`..\`${c.max}\``;
+    return "bounded number";
+  }
+  return c.type;
+}
+
+/** The shipped state. Per-field defaults (paired toggles) list each field's value. */
+function controlDefault(c: ItemControl): string {
+  if (c.default === undefined) return "—";
+  if (typeof c.default === "object" && c.default !== null) {
+    const entries = Object.entries(c.default as Record<string, unknown>);
+    if (entries.length === 0) return "—";
+    return entries.map(([k, v]) => `\`${k}: ${String(v)}\``).join(", ");
+  }
+  return `\`${String(c.default)}\``;
+}
+
+/**
+ * The item's declared control surface, from `controls` in registry-item.json —
+ * the catalog-page render of the item's published-parameter list. Items without
+ * a declaration get no section (the field is optional until the gate requires it).
+ */
+function generateControls(manifest: RegistryItem): string[] {
+  const raw = (manifest as RegistryItem & { controls?: ItemControl[] }).controls;
+  if (!Array.isArray(raw) || raw.length === 0) return [];
+
+  const lines: string[] = [
+    "## Controls",
+    "",
+    "The designed levers this item publishes, set in its top-of-script `CONFIG`",
+    "object. Anything not listed here — and not a content field or a documented",
+    "CSS token — is locked: changing it means editing the item source.",
+    "",
+    "| Control | Type | Accepts | Default | Drives |",
+    "| --- | --- | --- | --- | --- |",
+  ];
+  for (const c of raw) {
+    const name = c.fields?.length
+      ? `\`${c.name}\` (${c.fields.map((f) => `\`${f}\``).join(" + ")})`
+      : `\`${c.name}\``;
+    lines.push(
+      `| ${tableCell(name)} | ${c.type} | ${tableCell(controlRange(c))} | ${tableCell(controlDefault(c))} | ${tableCell(c.drives)} |`,
+    );
+  }
+  lines.push("");
+  return lines;
+}
+
 function primarySource(
   kind: ItemKind,
   manifest: RegistryItem,
@@ -1061,6 +1133,7 @@ function generateItemMdx(
   //    their version is carried through below instead of being overwritten.
   lines.push(...usageSection(kind, manifest, primaryTarget, carried, textureGroups));
 
+  lines.push(...generateControls(manifest));
   lines.push(...generateParams(manifest));
   lines.push(...generateVariables(manifest));
   lines.push(...generateVariableUsage(manifest, primaryTarget));

skills-manifest.json

@@ -46,7 +46,7 @@
       "files": 3
     },
     "hyperframes-registry": {
-      "hash": "d6dfcc8ceb7c8178",
+      "hash": "050e3047190cb1ef",
       "files": 12
     },
     "media-use": {

skills/hyperframes-registry/examples/add-component.md

@@ -40,24 +40,16 @@ document.querySelectorAll(".shimmer-sweep-target").forEach((el) => {
 });
 ```
 
-**Timeline** — add the sweep:
+**Timeline** — add the sweep at a position; the snippet's CONFIG-reading helper owns
+the sweep's internal duration, ease, and stagger:
 
 ```js
-tl.fromTo(
-  ".shimmer-sweep-target",
-  {
-    "--shimmer-pos": "-20%",
-  },
-  {
-    "--shimmer-pos": "120%",
-    duration: 1.2,
-    ease: "power2.inOut",
-    stagger: 0.15,
-  },
-  1.5,
-);
+tl.add(shimmerSweepBuild(".shimmer-sweep-target"), 1.5);
 ```
 
+The parent composition owns _where_ the sweep sits on the timeline (the position arg);
+the component owns _how_ it moves. Raw tween args never migrate into host code.
+
 ### 4. Lint and preview
 
 ```bash
@@ -67,7 +59,8 @@ hyperframes preview
 
 ### 5. Customize
 
-- `--shimmer-color`: highlight color per element
-- `--shimmer-width`: light band width (default 20%)
-- `--shimmer-angle`: sweep direction (default 120deg)
-- Timeline `duration`, `ease`, `stagger`: control speed and feel
+- `sweep` in the snippet's `CONFIG`: `"subtle" | "standard" | "dramatic"` — drives band
+  width, angle, and the helper's internal duration/ease/stagger
+- `--shimmer-color`: host re-skin token — override per element or at host level
+- Everything else (raw durations, eases, staggers, band geometry) is locked — changing it
+  means editing the component source