@cueframe/kernel 0.1.0 → 0.1.1

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

@@ -1,46 +0,0 @@
-// @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.js

@@ -1,231 +0,0 @@
-// @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.js

@@ -1,164 +0,0 @@
-// @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;
-}

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

@@ -1,14 +0,0 @@
-// @cueframe/primitive-registry — the React-free catalog-metadata contract.
-//
-// This is the AUTHORING-facing view of "what primitives exist and their param
-// contract" — distinct from:
-//   - @cueframe/primitives PrimitiveMeta (the RUNTIME catalog entry: React
-//     component + zod paramsSchema + createPresentation), which is execution-side.
-//   - @cueframe/composition PrimitiveRegistryEntry (the MARKETPLACE/distribution
-//     registry: origin class, modes, OTIO mapping), which is a different layer.
-//
-// The metadata here is generated from each primitive's config.ts (see
-// scripts/build-primitive-meta.mjs) so authoring can read the catalog without
-// importing the renderer (which would be an authoring -> execution boundary
-// violation). Mirror of the JSON-serializable subset of PrimitiveMeta.
-export {};

package/dist/_members/composition/projection/behind-placement.js

@@ -1,62 +0,0 @@
-/**
- * Launch-grade behind-text placement (spec §6). Derives a SCENE-space anchor from
- * the matte geometry sidecar: lateral center of the clip-union silhouette; vertical
- * in the shoulder band (head-top + a fraction) so the bite is rounded and partial,
- * never the flat torso wall; minTextWidth guarantees the line reads past the
- * silhouette on both sides. Pure; all values source-normalized [0,1].
- *
- * The sidecar is the person-matte bake's `.geometry.json` artifact (one record
- * per frame: subject bbox + 16-bucket column/row coverage marginals, computed
- * from the smoothed alpha — see person_matting.py `_frame_geometry`). The
- * orchestration activity downloads + camelCases it into `MatteGeometryLike`;
- * this module never does I/O.
- */
-/** Minimum fraction of bake-window frames with a detected subject before the
- *  behind treatment is even considered (relocated `captionsBehindEligible`
- *  principle — composition-floor's MIN_ACTIVE_SPEAKER_PRESENCE sibling). Below
- *  this the clip reads as b-roll / no-speaker → no anchor, degrade to front. */
-export const MIN_PRESENCE_FOR_BEHIND = 0.6;
-/** Shoulder-band shape. `headLambda` drops the anchor a frame-height fraction
- *  below the union head-top so the silhouette bites the line from below-the-chin
- *  (rounded head + shoulders), not the flat torso wall. `widthPad` widens the
- *  minimum text width past the union silhouette so the line reads on BOTH sides
- *  of the body. Calibration constants — Phase-7 fixtures tune them. */
-export const BEHIND_BAND = { headLambda: 0.18, widthPad: 1.25 };
-/** Anchors never sink below this — past mid-frame the "behind" read collapses
- *  into a lower-third (the silhouette no longer frames the line from above). */
-const MAX_ANCHOR_Y = 0.55;
-/** Hard ceiling on any text width estimate (frame fraction). */
-const MAX_TEXT_WIDTH = 0.95;
-/**
- * Derive the behind-text anchor from a clip's matte geometry. Returns null when
- * the clip has no stable subject to be behind (presence below the floor, or no
- * frame ever produced a bbox) — the caller degrades the overlay to front.
- *
- * Placement: lateral center of the UNION bbox across all present frames (stable
- * against per-frame jitter); vertical at union head-top + the shoulder-band
- * lambda, capped at MAX_ANCHOR_Y; minTextWidth = union silhouette width padded
- * by `widthPad` so the line extends past the body on both sides.
- */
-export function deriveBehindAnchor(g) {
-    if (g.presenceFraction < MIN_PRESENCE_FOR_BEHIND)
-        return null;
-    let x0 = Infinity;
-    let y0 = Infinity;
-    let x1 = -Infinity;
-    let hasBbox = false;
-    for (const frame of g.frames) {
-        if (!frame.bbox)
-            continue;
-        hasBbox = true;
-        x0 = Math.min(x0, frame.bbox[0]);
-        y0 = Math.min(y0, frame.bbox[1]);
-        x1 = Math.max(x1, frame.bbox[2]);
-    }
-    if (!hasBbox)
-        return null;
-    return {
-        x: (x0 + x1) / 2,
-        y: Math.min(MAX_ANCHOR_Y, y0 + BEHIND_BAND.headLambda),
-        minTextWidth: Math.min(MAX_TEXT_WIDTH, (x1 - x0) * BEHIND_BAND.widthPad),
-    };
-}