@cueframe/kernel 0.0.1

package/dist/_members/composition/primitive-catalog/index.d.ts

@@ -0,0 +1,28 @@
+import { PRIMITIVE_META } from './generated/meta.js';
+import type { PrimitiveCatalogMeta, PrimitiveCategory } from './types.js';
+export type { PrimitiveCatalogMeta, PrimitiveCategory, PrimitiveKind, PrimitiveExample, } from './types.js';
+export { PRIMITIVE_META };
+/** List primitives filtered by category. Used by `list_effect_styles` + discovery. */
+export declare function listPrimitivesByCategory(category: PrimitiveCategory): PrimitiveCatalogMeta[];
+/**
+ * The primitive's declared text-param name.
+ * - string  → the field accepting a single text payload (e.g. 'text').
+ * - null    → the primitive explicitly declines text (e.g. karaoke).
+ * - undefined → unknown id, or no declared text contract.
+ */
+export declare function getPrimitiveTextParam(id: string): string | null | undefined;
+/** Secondary text-param name. Same string/null/undefined semantics. */
+export declare function getPrimitiveSubtextParam(id: string): string | null | undefined;
+/** Lookup a primitive's catalog metadata by id. */
+export declare function getPrimitiveCatalogMeta(id: string): PrimitiveCatalogMeta | undefined;
+/** All registered primitive ids. */
+export declare function listPrimitiveIds(): string[];
+export { projectToComponentCatalog, projectToRegistryOverlays, derivePlacement, } from './projection.js';
+export type { ComponentCatalogEntry, ComponentPlacement, SceneFormat, RegistryOverlayEntry, RegistryOverlayCategory, } from './projection.js';
+/** JSON Schema for a primitive's props, or undefined if unknown. */
+export declare function getPrimitivePropSchema(id: string): import("./types.js").JsonSchemaObject | undefined;
+export { validatePrimitiveParams, validateParamsAgainstSchema, } from './paramValidation.js';
+export type { ParamSchemaValidationResult, PrimitiveParamValidationResult, ParamTypeMismatch, } from './paramValidation.js';
+export { DISABLED_PRIMITIVE_IDS, isPrimitiveDisabled } from './disabled.js';
+export { queryCatalog, filterCatalog, hasAnyCatalogFilter, validateCatalogFilters, encodeCatalogCursor, decodeCatalogCursor, serializeSfxCatalog, CatalogFilterError, CatalogCursorError, CATALOG_CATEGORY_VALUES, CATALOG_KIND_VALUES, CATALOG_TIER_VALUES, CATALOG_USE_CASE_VALUES, } from "./catalogQuery.js";
+export type { CatalogFilters, CatalogPage } from "./catalogQuery.js";

package/dist/_members/composition/primitive-catalog/index.js

@@ -0,0 +1,46 @@
+// @cueframe/primitive-registry — React-free primitive catalog metadata + the
+// authoring-facing accessors. The renderer (@cueframe/compose, execution) keeps
+// its full registry (components + paramsSchema + createPresentation) and
+// RE-EXPORTS these accessors from here so there is exactly one source of truth
+// for the text/subtext/category contract — no parallel copy to drift.
+import { PRIMITIVE_META } from './generated/meta';
+export { PRIMITIVE_META };
+const byId = new Map(PRIMITIVE_META.map((m) => [m.id, m]));
+/** List primitives filtered by category. Used by `list_effect_styles` + discovery. */
+export function listPrimitivesByCategory(category) {
+    return PRIMITIVE_META.filter((m) => m.category === category);
+}
+/**
+ * The primitive's declared text-param name.
+ * - string  → the field accepting a single text payload (e.g. 'text').
+ * - null    → the primitive explicitly declines text (e.g. karaoke).
+ * - undefined → unknown id, or no declared text contract.
+ */
+export function getPrimitiveTextParam(id) {
+    return byId.get(id)?.textParam;
+}
+/** Secondary text-param name. Same string/null/undefined semantics. */
+export function getPrimitiveSubtextParam(id) {
+    return byId.get(id)?.subtextParam;
+}
+/** Lookup a primitive's catalog metadata by id. */
+export function getPrimitiveCatalogMeta(id) {
+    return byId.get(id);
+}
+/** All registered primitive ids. */
+export function listPrimitiveIds() {
+    return [...byId.keys()];
+}
+export { projectToComponentCatalog, projectToRegistryOverlays, derivePlacement, } from './projection';
+/** JSON Schema for a primitive's props, or undefined if unknown. */
+export function getPrimitivePropSchema(id) {
+    return byId.get(id)?.propSchema;
+}
+// Pure, V8-safe param validation against the baked propSchema (closed-key +
+// typed). Imported by the Convex isolate's write/validate boundary guards.
+export { validatePrimitiveParams, validateParamsAgainstSchema, } from './paramValidation';
+// The disabled-primitive denylist — the single switch that takes a built-in
+// primitive out of circulation (discovery + write-boundary membership). See
+// ./disabled for why a denylist rather than a per-primitive flag.
+export { DISABLED_PRIMITIVE_IDS, isPrimitiveDisabled } from './disabled';
+export { queryCatalog, filterCatalog, hasAnyCatalogFilter, validateCatalogFilters, encodeCatalogCursor, decodeCatalogCursor, serializeSfxCatalog, CatalogFilterError, CatalogCursorError, CATALOG_CATEGORY_VALUES, CATALOG_KIND_VALUES, CATALOG_TIER_VALUES, CATALOG_USE_CASE_VALUES, } from "./catalogQuery";

package/dist/_members/composition/primitive-catalog/paramValidation.d.ts

@@ -0,0 +1,76 @@
+import type { JsonSchemaObject } from './types.js';
+export interface ParamTypeMismatch {
+    /** The provided param key whose value type disagrees with the schema. */
+    key: string;
+    /** Declared JSON-Schema type (or `a|b` for a union of primitive types). */
+    expected: string;
+    /** Observed runtime JSON type of the provided value. */
+    actual: string;
+}
+/** A provided value that is the right TYPE but violates a value constraint
+ *  (string length, numeric bound, or enum membership) declared in the baked
+ *  propSchema — the class the renderer's full-Zod inflate would otherwise throw
+ *  on (e.g. a lower-third `subtitle` longer than its 60-char max). */
+export interface ParamConstraintViolation {
+    /** The provided param key whose value breaks a declared constraint. */
+    key: string;
+    /** Which constraint was broken. */
+    constraint: 'maxLength' | 'minLength' | 'minimum' | 'maximum' | 'exclusiveMinimum' | 'exclusiveMaximum' | 'minItems' | 'maxItems' | 'enum';
+    /** The declared bound: the numeric limit, or the allowed enum set. */
+    limit: number | Array<string | number | boolean>;
+    /** The observed magnitude: string length / numeric value / the invalid enum value. */
+    actual: number | string | boolean;
+}
+export interface ParamSchemaValidationResult {
+    /**
+     * `propSchema` was absent or not a usable `{ type:'object', properties }`
+     * schema. Callers MUST fail loud on this (registry drift) — never silently
+     * pass. Distinct from "unknown primitive" (see `validatePrimitiveParams`).
+     */
+    missingPropSchema: boolean;
+    /** Provided param keys that are NOT declared properties (typo'd/unsupported). */
+    unknownKeys: string[];
+    /** The full declared property-name set (sorted) — the valid/expressible keys. */
+    allowedKeys: string[];
+    /** Provided keys whose value's JSON type disagrees with the declared type. */
+    typeMismatches: ParamTypeMismatch[];
+    /** Provided keys whose (correctly-typed) value violates a declared value
+     *  constraint (maxLength/minLength/minimum/maximum/enum). */
+    constraintViolations: ParamConstraintViolation[];
+}
+export interface PrimitiveParamValidationResult extends ParamSchemaValidationResult {
+    /**
+     * `false` when `primitiveId` is not in the registry catalog at all — the
+     * membership guard (`validatePrimitiveMembership`) owns reporting those, so
+     * the param-shape caller skips them rather than double-flagging.
+     */
+    known: boolean;
+}
+/**
+ * Validate a params object against an EXPLICIT JSON-Schema `propSchema`. The
+ * low-level core: pure, no registry lookup, so the "missing propSchema → fail
+ * loud" branch is directly unit-testable (pass `undefined`).
+ *
+ * - CLOSED-KEY: every provided key must be a declared property; otherwise it
+ *   lands in `unknownKeys` (with `allowedKeys` = the valid set). Suppressed when
+ *   `opts.freeform` (the per-primitive opt-out) is set — typed checks still run.
+ * - TYPED: each provided KNOWN key is checked against its declared primitive
+ *   `type` (string, or an array-of-strings union). Properties with no concrete
+ *   primitive `type` (anyOf/enum-only/$ref) skip the typed check — closed-key
+ *   still applies, deep shape is the renderer's full-Zod job.
+ */
+export declare function validateParamsAgainstSchema(params: unknown, propSchema: JsonSchemaObject | undefined, opts?: {
+    freeform?: boolean;
+}): ParamSchemaValidationResult;
+/**
+ * Resolve a registry primitive's baked `propSchema` and validate `params`
+ * against it (closed-key + typed). The SSOT-resolving wrapper over
+ * `validateParamsAgainstSchema`.
+ *
+ * - `known:false` when `primitiveId` is absent from the catalog — the
+ *   membership guard owns reporting unknown ids; the param-shape caller skips.
+ * - `missingPropSchema:true` when a KNOWN primitive carries no usable
+ *   propSchema (registry drift) — the caller fails loud.
+ * - Honours the per-primitive `freeformParams` opt-out (no config sets it today).
+ */
+export declare function validatePrimitiveParams(primitiveId: string, params: unknown): PrimitiveParamValidationResult;

package/dist/_members/composition/primitive-catalog/paramValidation.js

@@ -0,0 +1,231 @@
+// @cueframe/primitive-registry — pure, React/Remotion-FREE param validation
+// against the catalog's baked JSON-Schema `propSchema` (the same SSOT the
+// renderer's Zod paramsSchema generates — see build-primitive-meta.mjs).
+//
+// WHY THIS MODULE IS DEPENDENCY-FREE AND V8-SAFE: it is imported by the Convex
+// V8 isolate (via `@cueframe/primitive-registry`, already proven safe — see
+// services/convex/api/registry/builtinRegistry.ts). It MUST NOT pull in ajv or
+// any validator that calls `eval` / `new Function` (forbidden in the isolate)
+// and MUST NOT import React/Remotion. The closed-key + primitive-type checks
+// below are hand-rolled against `propSchema.properties` with zero deps.
+//
+// WHAT IT CLOSES: overlay/effect clip `params` are wire-typed as
+// `z.record(z.string(), z.unknown())`, and every primitive's Zod paramsSchema
+// is `.passthrough()` (so `propSchema.additionalProperties === true` on all 87).
+// A TYPO'd key (`headlin` for `headline`) or an UNSUPPORTED key is therefore
+// silently dropped, and a WRONG-TYPED value (`text: 123`) is not caught until
+// render (render_unknown / no-op). This validates at the write/validate boundary
+// so those fail LOUD with the valid key set — not silently vanish.
+//
+// SCOPE BY DESIGN: TOP-LEVEL closed-key + TOP-LEVEL per-property primitive-type
+// check only. We deliberately do NOT recurse (deep/nested shape, refinements,
+// mins/maxes, enums) — that is the renderer's full-Zod job at inflate time. The
+// `additionalProperties: true` passthrough flag is the BUG we are closing, NOT a
+// license to allow unknown keys; the only escape hatch is the explicit
+// per-primitive `freeformParams` opt-out (no first-party config sets it today).
+import { PRIMITIVE_META } from './generated/meta';
+const byId = new Map(PRIMITIVE_META.map((m) => [m.id, m]));
+/** JSON-Schema primitive `type` names we can check structurally, no deps. */
+const PRIMITIVE_TYPES = new Set([
+    'string',
+    'number',
+    'integer',
+    'boolean',
+    'object',
+    'array',
+    'null',
+]);
+/** Runtime JSON type label for a value — used in mismatch messages. */
+function jsonType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value; // 'string' | 'number' | 'boolean' | 'object' | ...
+}
+/** Does a runtime value satisfy a single JSON-Schema primitive `type` name? */
+function matchesType(value, type) {
+    switch (type) {
+        case 'string':
+            return typeof value === 'string';
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'object':
+            return value !== null && typeof value === 'object' && !Array.isArray(value);
+        case 'array':
+            return Array.isArray(value);
+        case 'null':
+            return value === null;
+        default:
+            // An unrecognised type keyword can't be checked structurally — don't
+            // claim a mismatch (closed-key already caught typo'd KEYS).
+            return true;
+    }
+}
+/**
+ * Collect value-constraint violations for a single CORRECTLY-TYPED value against
+ * its declared property schema. Only the flat, top-level JSON-Schema keywords the
+ * catalog bakes for scalars — maxLength/minLength (strings), minimum/maximum
+ * (numbers), and enum (any primitive). Deep/nested-item and `.refine()` custom
+ * logic stay the renderer's full-Zod job (now surfaced TYPED from inflate).
+ */
+function collectConstraintViolations(key, value, prop, out) {
+    if (typeof value === 'string') {
+        if (typeof prop.maxLength === 'number' && value.length > prop.maxLength) {
+            out.push({ key, constraint: 'maxLength', limit: prop.maxLength, actual: value.length });
+        }
+        if (typeof prop.minLength === 'number' && value.length < prop.minLength) {
+            out.push({ key, constraint: 'minLength', limit: prop.minLength, actual: value.length });
+        }
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        if (typeof prop.maximum === 'number' && value > prop.maximum) {
+            out.push({ key, constraint: 'maximum', limit: prop.maximum, actual: value });
+        }
+        if (typeof prop.minimum === 'number' && value < prop.minimum) {
+            out.push({ key, constraint: 'minimum', limit: prop.minimum, actual: value });
+        }
+        if (typeof prop.exclusiveMaximum === 'number' && value >= prop.exclusiveMaximum) {
+            out.push({ key, constraint: 'exclusiveMaximum', limit: prop.exclusiveMaximum, actual: value });
+        }
+        if (typeof prop.exclusiveMinimum === 'number' && value <= prop.exclusiveMinimum) {
+            out.push({ key, constraint: 'exclusiveMinimum', limit: prop.exclusiveMinimum, actual: value });
+        }
+    }
+    if (Array.isArray(value)) {
+        if (typeof prop.maxItems === 'number' && value.length > prop.maxItems) {
+            out.push({ key, constraint: 'maxItems', limit: prop.maxItems, actual: value.length });
+        }
+        if (typeof prop.minItems === 'number' && value.length < prop.minItems) {
+            out.push({ key, constraint: 'minItems', limit: prop.minItems, actual: value.length });
+        }
+    }
+    if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+        if ((typeof value === 'string' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean') &&
+            !prop.enum.includes(value)) {
+            out.push({
+                key,
+                constraint: 'enum',
+                limit: prop.enum,
+                actual: value,
+            });
+        }
+    }
+}
+/**
+ * Validate a params object against an EXPLICIT JSON-Schema `propSchema`. The
+ * low-level core: pure, no registry lookup, so the "missing propSchema → fail
+ * loud" branch is directly unit-testable (pass `undefined`).
+ *
+ * - CLOSED-KEY: every provided key must be a declared property; otherwise it
+ *   lands in `unknownKeys` (with `allowedKeys` = the valid set). Suppressed when
+ *   `opts.freeform` (the per-primitive opt-out) is set — typed checks still run.
+ * - TYPED: each provided KNOWN key is checked against its declared primitive
+ *   `type` (string, or an array-of-strings union). Properties with no concrete
+ *   primitive `type` (anyOf/enum-only/$ref) skip the typed check — closed-key
+ *   still applies, deep shape is the renderer's full-Zod job.
+ */
+export function validateParamsAgainstSchema(params, propSchema, opts) {
+    const schema = propSchema;
+    const properties = schema && typeof schema === 'object' ? schema.properties : undefined;
+    // Fail loud: a primitive we were asked to validate has no usable object
+    // propSchema. Never silently pass (that is the silent-drop class this exists
+    // to kill). With the catalog's 87↔87 version-map alignment this should be
+    // unreachable for a known primitive, so it only fires on real registry drift.
+    if (!schema ||
+        schema.type !== 'object' ||
+        !properties ||
+        typeof properties !== 'object') {
+        return {
+            missingPropSchema: true,
+            unknownKeys: [],
+            allowedKeys: [],
+            typeMismatches: [],
+            constraintViolations: [],
+        };
+    }
+    const allowedKeys = Object.keys(properties).sort();
+    const allowed = new Set(allowedKeys);
+    const paramsObj = params && typeof params === 'object' && !Array.isArray(params)
+        ? params
+        : {};
+    const unknownKeys = [];
+    const typeMismatches = [];
+    const constraintViolations = [];
+    for (const [key, value] of Object.entries(paramsObj)) {
+        if (!allowed.has(key)) {
+            if (!opts?.freeform)
+                unknownKeys.push(key);
+            continue;
+        }
+        const prop = properties[key];
+        const declared = prop?.type;
+        let typeOk = true;
+        if (typeof declared === 'string' && PRIMITIVE_TYPES.has(declared)) {
+            if (!matchesType(value, declared)) {
+                typeMismatches.push({ key, expected: declared, actual: jsonType(value) });
+                typeOk = false;
+            }
+        }
+        else if (Array.isArray(declared) &&
+            declared.length > 0 &&
+            declared.every((t) => typeof t === 'string')) {
+            const types = declared;
+            if (!types.some((t) => matchesType(value, t))) {
+                typeMismatches.push({
+                    key,
+                    expected: types.join('|'),
+                    actual: jsonType(value),
+                });
+                typeOk = false;
+            }
+        }
+        // No concrete primitive type (anyOf/enum-only/$ref) → typed check skipped,
+        // but value constraints (enum membership, flat min/max/length) still apply.
+        // Only value-check a value that is not already a type mismatch.
+        if (typeOk && prop) {
+            collectConstraintViolations(key, value, prop, constraintViolations);
+        }
+    }
+    return {
+        missingPropSchema: false,
+        unknownKeys: unknownKeys.sort(),
+        allowedKeys,
+        typeMismatches,
+        constraintViolations,
+    };
+}
+/**
+ * Resolve a registry primitive's baked `propSchema` and validate `params`
+ * against it (closed-key + typed). The SSOT-resolving wrapper over
+ * `validateParamsAgainstSchema`.
+ *
+ * - `known:false` when `primitiveId` is absent from the catalog — the
+ *   membership guard owns reporting unknown ids; the param-shape caller skips.
+ * - `missingPropSchema:true` when a KNOWN primitive carries no usable
+ *   propSchema (registry drift) — the caller fails loud.
+ * - Honours the per-primitive `freeformParams` opt-out (no config sets it today).
+ */
+export function validatePrimitiveParams(primitiveId, params) {
+    const meta = byId.get(primitiveId);
+    if (!meta) {
+        return {
+            known: false,
+            missingPropSchema: false,
+            unknownKeys: [],
+            allowedKeys: [],
+            typeMismatches: [],
+            constraintViolations: [],
+        };
+    }
+    const result = validateParamsAgainstSchema(params, meta.propSchema, {
+        freeform: meta.freeformParams === true,
+    });
+    return { known: true, ...result };
+}

package/dist/_members/composition/primitive-catalog/projection.d.ts

@@ -0,0 +1,99 @@
+import type { PrimitiveCatalogMeta, PrimitiveCategory, PrimitiveKind, PrimitiveExample, JsonSchemaObject, PrimitiveTier, PrimitiveUseCase } from './types.js';
+/**
+ * A param that follows the project brand kit: `param` accepts the `brandToken`
+ * value (a `$brand:<path>` ref) to track the brand instead of a literal. Derived
+ * from a primitive's declared `tokens` (only the entries that carry a
+ * `brandKitPath`). Surfaced so an agent can both DISCOVER which params are
+ * brand-bindable and EXPRESS the binding without reading source.
+ */
+export type ComponentBrandBinding = {
+    param: string;
+    brandToken: string;
+};
+export type SceneFormat = {
+    aspectRatio: '16:9' | '9:16' | '1:1' | '4:5';
+    fps?: 24 | 30 | 60;
+    resolution?: 'hd' | 'fhd' | '4k';
+};
+/**
+ * How to PLACE a catalog entry on the timeline as a ClipSource.
+ *
+ * Resolves the `kind:'component'` name collision: a catalog entry's `kind`
+ * (component|transition|scene) is its RENDER kind, NOT its ClipSource variant.
+ * The ClipSource union ALSO has a `kind:'component'` — but that is reserved for
+ * org-INSTALLED custom components keyed by `componentId`. A built-in primitive
+ * referenced by `componentId` will NOT resolve. This hint names the exact
+ * ClipSource `kind` + the id field to key it by:
+ *   - built-in text/ui-block/background/layout/SCENE (source:'default')
+ *     → { clipSourceKind:'overlay', refField:'primitiveId' } (OverlayClipSource)
+ *   - built-in effect/transition (source:'default')
+ *     → { clipSourceKind:'effect',  refField:'primitiveId' } (EffectClipSource)
+ *   - org-INSTALLED custom component (source:'installed')
+ *     → { clipSourceKind:'component', refField:'componentId' } (ComponentClipSource)
+ *
+ * It also resolves the "scenes are invisible as clips" gap: a `kind:'scene'`
+ * primitive has NO `scene` ClipSource — it is placed as `{kind:'overlay',
+ * primitiveId}`, which this hint states explicitly.
+ */
+export type ComponentPlacement = {
+    clipSourceKind: 'overlay' | 'effect' | 'component';
+    refField: 'primitiveId' | 'componentId';
+};
+/**
+ * Derive the timeline-placement hint for a catalog entry from its provenance +
+ * category. Fail-loud: an unmapped category means a new `PrimitiveCategory`
+ * landed without a placement rule — a silent default would mis-author the clip.
+ */
+export declare function derivePlacement(args: {
+    source: 'default' | 'installed';
+    category: PrimitiveCategory;
+}): ComponentPlacement;
+export type ComponentCatalogEntry = {
+    id: string;
+    name: string;
+    description: string;
+    source: 'default' | 'installed';
+    category: PrimitiveCategory;
+    kind: PrimitiveKind;
+    version: string;
+    propSchema: JsonSchemaObject;
+    propDefaults?: Record<string, unknown>;
+    textParam?: string | null;
+    subtextParam?: string | null;
+    format?: SceneFormat;
+    durationInFrames?: number;
+    intent?: string;
+    useWhen?: string;
+    pairsWith?: string[];
+    avoidWith?: string[];
+    tags?: string[];
+    mood?: string[];
+    tier?: PrimitiveTier;
+    useCase?: PrimitiveUseCase[];
+    examples?: PrimitiveExample[];
+    /** On-screen strings the primitive BAKES (no param changes them). Counterpart to propSchema. */
+    fixedCopy?: string[];
+    /**
+     * Params that can follow the project brand kit: each `{param, brandToken}`
+     * says "set `param` to `brandToken` (a `$brand:` ref) to track the brand".
+     * Derived from the primitive's `tokens`; omitted when nothing is brand-bound.
+     */
+    brandBindings?: ComponentBrandBinding[];
+    /** How to author this entry as a ClipSource on the timeline (resolves the kind:component collision). */
+    placement: ComponentPlacement;
+};
+export declare function projectToComponentCatalog(metas: PrimitiveCatalogMeta[]): ComponentCatalogEntry[];
+export type RegistryOverlayCategory = 'cueframe:overlay.text' | 'cueframe:effect' | 'cueframe:transition' | 'cueframe:scene';
+export type RegistryOverlayEntry = {
+    id: string;
+    category: RegistryOverlayCategory;
+    name: string;
+    kind?: 'component' | 'transition';
+    description?: string;
+    textParam?: string | null;
+    subtextParam?: string | null;
+    format?: SceneFormat;
+    durationInFrames?: number;
+    sampleProps: Record<string, unknown>;
+};
+export declare function projectToRegistryOverlays(metas: PrimitiveCatalogMeta[]): RegistryOverlayEntry[];

package/dist/_members/composition/primitive-catalog/projection.js

@@ -0,0 +1,164 @@
+// @cueframe/primitive-registry — React-free projections from the generated
+// PRIMITIVE_META (the single source of truth) into the two catalog shapes the
+// API serves:
+//   - projectToComponentCatalog → the unified 7-category shape served by the
+//     new /v1/components endpoint.
+//   - projectToRegistryOverlays → the legacy namespaced (cueframe:*) shape
+//     served by the deprecated /v1/registry/overlays endpoint.
+// Convex (V8 isolate) imports these, so this module stays React/Remotion-free:
+// it imports only the metadata types and the generated meta.
+import { isPrimitiveDisabled } from './disabled';
+/**
+ * Project a primitive's declared `tokens` into the public brand-binding hints.
+ * Only tokens with a `brandKitPath` are brand-bindable; the rest are
+ * render-internal CSS-var bindings with no agent-facing value. Returns
+ * `undefined` (not `[]`) when none, so the field is omitted from the wire shape.
+ */
+function deriveBrandBindings(tokens) {
+    if (!tokens || tokens.length === 0)
+        return undefined;
+    const bindings = tokens
+        .filter((t) => typeof t.brandKitPath === 'string' && t.brandKitPath.length > 0)
+        .map((t) => ({ param: t.propPath, brandToken: `$brand:${t.brandKitPath}` }));
+    return bindings.length > 0 ? bindings : undefined;
+}
+const EFFECT_PLACEMENT_CATEGORIES = new Set([
+    'effects',
+    'transitions',
+]);
+const OVERLAY_PLACEMENT_CATEGORIES = new Set([
+    'text',
+    'ui-blocks',
+    'backgrounds',
+    'layouts',
+    'scenes',
+]);
+/**
+ * Derive the timeline-placement hint for a catalog entry from its provenance +
+ * category. Fail-loud: an unmapped category means a new `PrimitiveCategory`
+ * landed without a placement rule — a silent default would mis-author the clip.
+ */
+export function derivePlacement(args) {
+    // An org-installed custom component is the ONLY ComponentClipSource case.
+    if (args.source === 'installed') {
+        return { clipSourceKind: 'component', refField: 'componentId' };
+    }
+    if (EFFECT_PLACEMENT_CATEGORIES.has(args.category)) {
+        return { clipSourceKind: 'effect', refField: 'primitiveId' };
+    }
+    if (OVERLAY_PLACEMENT_CATEGORIES.has(args.category)) {
+        return { clipSourceKind: 'overlay', refField: 'primitiveId' };
+    }
+    throw new Error(`derivePlacement: no placement rule for category '${args.category}' (source '${args.source}'). ` +
+        `Add it to EFFECT_PLACEMENT_CATEGORIES or OVERLAY_PLACEMENT_CATEGORIES.`);
+}
+// Default for installed rows in a later task that legitimately lack a propSchema.
+// Default-source rows always carry a real propSchema (Task 2 fails loud otherwise),
+// so the projection below uses m.propSchema directly.
+const EMPTY_SCHEMA = { type: 'object', properties: {} };
+function aspectRatio(w, h) {
+    if (!w || !h)
+        return undefined;
+    const r = w / h;
+    if (Math.abs(r - 16 / 9) < 0.02)
+        return '16:9';
+    if (Math.abs(r - 9 / 16) < 0.02)
+        return '9:16';
+    if (Math.abs(r - 1) < 0.02)
+        return '1:1';
+    if (Math.abs(r - 4 / 5) < 0.02)
+        return '4:5';
+    return undefined;
+}
+function resolution(h) {
+    if (!h)
+        return undefined;
+    if (h >= 2160)
+        return '4k';
+    if (h >= 1080)
+        return 'fhd';
+    if (h >= 720)
+        return 'hd';
+    return undefined;
+}
+function sceneFps(fps) {
+    if (fps === undefined)
+        return undefined;
+    if (fps === 24 || fps === 30 || fps === 60)
+        return fps;
+    throw new Error(`sceneFormat: unsupported scene fps ${fps} (expected 24|30|60)`);
+}
+function sceneFormat(m) {
+    if (m.kind !== 'scene')
+        return undefined;
+    const ar = aspectRatio(m.width, m.height);
+    if (!ar)
+        return undefined;
+    return {
+        aspectRatio: ar,
+        fps: sceneFps(m.fps),
+        resolution: resolution(m.height),
+    };
+}
+export function projectToComponentCatalog(metas) {
+    // Disabled primitives are never OFFERED — a driving agent can't discover what
+    // it isn't allowed to author (the write boundary rejects them too).
+    return metas.filter((m) => !isPrimitiveDisabled(m.id)).map((m) => ({
+        id: m.id,
+        name: m.name,
+        description: m.description ?? '',
+        source: 'default',
+        category: m.category,
+        kind: m.kind,
+        version: m.version,
+        propSchema: m.propSchema ?? EMPTY_SCHEMA,
+        propDefaults: m.propDefaults,
+        textParam: m.textParam,
+        subtextParam: m.subtextParam,
+        format: sceneFormat(m),
+        durationInFrames: m.durationInFrames,
+        intent: m.intent,
+        useWhen: m.useWhen,
+        pairsWith: m.pairsWith,
+        avoidWith: m.avoidWith,
+        tags: m.tags,
+        mood: m.mood,
+        tier: m.tier,
+        useCase: m.useCase,
+        examples: m.examples,
+        fixedCopy: m.fixedCopy,
+        brandBindings: deriveBrandBindings(m.tokens),
+        // Built-in primitives are always source:'default'; placement derives from
+        // category (overlay for text/ui/scene, effect for effects/transitions).
+        placement: derivePlacement({ source: 'default', category: m.category }),
+    }));
+}
+const OVERLAY_CATEGORY = {
+    text: 'cueframe:overlay.text',
+    effects: 'cueframe:effect',
+    transitions: 'cueframe:transition',
+    scenes: 'cueframe:scene',
+};
+export function projectToRegistryOverlays(metas) {
+    const out = [];
+    for (const m of metas) {
+        if (isPrimitiveDisabled(m.id))
+            continue; // disabled primitives are never offered
+        const category = OVERLAY_CATEGORY[m.category];
+        if (!category)
+            continue; // layouts/backgrounds/ui-blocks are not part of the legacy shape
+        out.push({
+            id: m.id,
+            category,
+            name: m.name,
+            kind: m.kind === 'transition' ? 'transition' : 'component',
+            description: m.description,
+            textParam: m.textParam,
+            subtextParam: m.subtextParam,
+            format: sceneFormat(m),
+            durationInFrames: m.durationInFrames,
+            sampleProps: m.propDefaults ?? {},
+        });
+    }
+    return out;
+}