@cueframe/kernel 0.0.1

package/dist/_members/composition/validators/font.d.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+export declare const FontStatus: z.ZodEnum<["pending", "uploading", "analyzing", "subsetting", "ready", "partial", "failed"]>;
+export type FontStatus = z.infer<typeof FontStatus>;
+export declare const FontVariant: z.ZodObject<{
+    weight: z.ZodNumber;
+    style: z.ZodEnum<["normal", "italic"]>;
+    storageKey: z.ZodString;
+    byteSize: z.ZodOptional<z.ZodNumber>;
+    subsetComplete: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    style: "normal" | "italic";
+    weight: number;
+    storageKey: string;
+    byteSize?: number | undefined;
+    subsetComplete?: boolean | undefined;
+}, {
+    style: "normal" | "italic";
+    weight: number;
+    storageKey: string;
+    byteSize?: number | undefined;
+    subsetComplete?: boolean | undefined;
+}>;
+export type FontVariant = z.infer<typeof FontVariant>;
+export declare const Font: z.ZodObject<{
+    id: z.ZodString;
+    family: z.ZodString;
+    status: z.ZodEnum<["pending", "uploading", "analyzing", "subsetting", "ready", "partial", "failed"]>;
+    variants: z.ZodArray<z.ZodObject<{
+        weight: z.ZodNumber;
+        style: z.ZodEnum<["normal", "italic"]>;
+        storageKey: z.ZodString;
+        byteSize: z.ZodOptional<z.ZodNumber>;
+        subsetComplete: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        style: "normal" | "italic";
+        weight: number;
+        storageKey: string;
+        byteSize?: number | undefined;
+        subsetComplete?: boolean | undefined;
+    }, {
+        style: "normal" | "italic";
+        weight: number;
+        storageKey: string;
+        byteSize?: number | undefined;
+        subsetComplete?: boolean | undefined;
+    }>, "atleastone">;
+    source: z.ZodOptional<z.ZodEnum<["uploaded", "system", "web"]>>;
+    license: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        source: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        source?: string | undefined;
+        notes?: string | undefined;
+    }, {
+        type: string;
+        source?: string | undefined;
+        notes?: string | undefined;
+    }>>;
+    createdAt: z.ZodOptional<z.ZodNumber>;
+    ownerOrgId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    status: "partial" | "pending" | "uploading" | "analyzing" | "subsetting" | "ready" | "failed";
+    family: string;
+    variants: [{
+        style: "normal" | "italic";
+        weight: number;
+        storageKey: string;
+        byteSize?: number | undefined;
+        subsetComplete?: boolean | undefined;
+    }, ...{
+        style: "normal" | "italic";
+        weight: number;
+        storageKey: string;
+        byteSize?: number | undefined;
+        subsetComplete?: boolean | undefined;
+    }[]];
+    source?: "system" | "web" | "uploaded" | undefined;
+    license?: {
+        type: string;
+        source?: string | undefined;
+        notes?: string | undefined;
+    } | undefined;
+    ownerOrgId?: string | undefined;
+    createdAt?: number | undefined;
+}, {
+    id: string;
+    status: "partial" | "pending" | "uploading" | "analyzing" | "subsetting" | "ready" | "failed";
+    family: string;
+    variants: [{
+        style: "normal" | "italic";
+        weight: number;
+        storageKey: string;
+        byteSize?: number | undefined;
+        subsetComplete?: boolean | undefined;
+    }, ...{
+        style: "normal" | "italic";
+        weight: number;
+        storageKey: string;
+        byteSize?: number | undefined;
+        subsetComplete?: boolean | undefined;
+    }[]];
+    source?: "system" | "web" | "uploaded" | undefined;
+    license?: {
+        type: string;
+        source?: string | undefined;
+        notes?: string | undefined;
+    } | undefined;
+    ownerOrgId?: string | undefined;
+    createdAt?: number | undefined;
+}>;
+export type Font = z.infer<typeof Font>;

package/dist/_members/composition/validators/font.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+// Font lifecycle per data-model.md § FontRef (and the Font entity).
+// Font is immutable after `status: 'ready'` — variants don't get re-subsetted,
+// family doesn't change, files in R2 are content-addressed by subset hash.
+export const FontStatus = z.enum([
+    "pending",
+    "uploading",
+    "analyzing",
+    "subsetting",
+    "ready",
+    "partial", // common-glyphs buffer present, custom glyphs still subsetting
+    "failed",
+]);
+export const FontVariant = z.object({
+    weight: z.number().int().min(100).max(900),
+    style: z.enum(["normal", "italic"]),
+    storageKey: z.string().min(1),
+    byteSize: z.number().int().nonnegative().optional(),
+    subsetComplete: z.boolean().optional(),
+});
+export const Font = z.object({
+    id: z.string().min(1),
+    family: z.string().min(1),
+    status: FontStatus,
+    variants: z.array(FontVariant).nonempty(),
+    source: z.enum(["uploaded", "system", "web"]).optional(),
+    license: z.object({
+        type: z.string().min(1),
+        source: z.string().optional(),
+        notes: z.string().optional(),
+    }).optional(),
+    createdAt: z.number().optional(), // epoch ms
+    ownerOrgId: z.string().optional(),
+});

package/dist/_members/composition/validators/graphicKinds.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ClipSource kinds that constitute an AUTHORED GRAPHIC — pure data, ZERO
+ * imports, in its own module so the Temporal WORKFLOW bundle can value-import
+ * it: `validators/composition.ts` imports `zid` (convex-helpers) for the
+ * mediaId brand, so ANY value import of it — or of the validators barrel —
+ * drags convex-helpers into the workflow isolate and breaks the bundle
+ * (bundle.test.ts). Type imports stay on the barrel (erased at compile).
+ *
+ * ONE SSOT consumed by the compose no-discard gate
+ * (the API layer), the director's
+ * renderable-graphics lock (compileCssLayout.ts), the brief-exclusions gate
+ * (briefContract.ts), and the track-family invariants. A new graphic kind
+ * added to the ClipSource union MUST be added here too, or it silently misses
+ * those gates (review finding 2026-07-10).
+ */
+import type { GraphicRole } from "../graphics-plan/schemas.js";
+export declare const AUTHORED_GRAPHIC_KINDS: readonly ["overlay", "component", "card", "alpha-layer"];
+export type AuthoredGraphicKind = (typeof AUTHORED_GRAPHIC_KINDS)[number];
+/**
+ * The canonical authored KIND for each planner graphic ROLE — the clip kind the
+ * deterministic graphics compiler (graphics-plan/compile.ts) emits and the LLM
+ * designer authors by default. EVERY role currently compiles to an `overlay`
+ * clip: title-card/stat/lower-third/pull-quote are overlay primitives, `hero`'s
+ * behind-subject look is a zPlane ON an overlay (not a distinct kind), and
+ * `logo-tag` is a watermark overlay.
+ *
+ * The bridge the brief-EXCLUSIONS filter (briefContract.dropExcludedPlanGraphics)
+ * needs: plan graphics carry a ROLE, exclusions name a KIND. `Record<GraphicRole,
+ * …>` makes a NEW role a COMPILE error here — the same add-or-silently-miss
+ * discipline the kinds SSOT above enforces.
+ */
+export declare const GRAPHIC_ROLE_CANONICAL_KIND: Record<GraphicRole, AuthoredGraphicKind>;

package/dist/_members/composition/validators/graphicKinds.js

@@ -0,0 +1,30 @@
+export const AUTHORED_GRAPHIC_KINDS = ["overlay", "component", "card", "alpha-layer"];
+/**
+ * The canonical authored KIND for each planner graphic ROLE — the clip kind the
+ * deterministic graphics compiler (graphics-plan/compile.ts) emits and the LLM
+ * designer authors by default. EVERY role currently compiles to an `overlay`
+ * clip: title-card/stat/lower-third/pull-quote are overlay primitives, `hero`'s
+ * behind-subject look is a zPlane ON an overlay (not a distinct kind), and
+ * `logo-tag` is a watermark overlay.
+ *
+ * The bridge the brief-EXCLUSIONS filter (briefContract.dropExcludedPlanGraphics)
+ * needs: plan graphics carry a ROLE, exclusions name a KIND. `Record<GraphicRole,
+ * …>` makes a NEW role a COMPILE error here — the same add-or-silently-miss
+ * discipline the kinds SSOT above enforces.
+ */
+export const GRAPHIC_ROLE_CANONICAL_KIND = {
+    "title-card": "overlay",
+    stat: "overlay",
+    "lower-third": "overlay",
+    "pull-quote": "overlay",
+    hero: "overlay",
+    "logo-tag": "overlay",
+    // The ARGUMENT roles default to `overlay` too: the catalog's argument-carrying components
+    // (reasoning-trace, tool-call-stack, benchmark-bars, metric-gauge, eval-scorecard) are all
+    // overlay primitives placed by `primitiveId`. A designer that ESCALATES to a custom .tsx
+    // authors a `component` clip, and the exclusions check runs against the clip it actually
+    // wrote — this map only supplies the plan-time default.
+    enumeration: "overlay",
+    sequence: "overlay",
+    comparison: "overlay",
+};

package/dist/_members/composition/validators/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./composition.js";
+export * from "./composePlan.js";
+export * from "./brandKit.js";
+export * from "./font.js";
+export * from "./render.js";
+export * from "./registry.js";
+export * from "./project.js";
+export * from "./session.js";
+export * from "./webhook.js";

package/dist/_members/composition/validators/index.js

@@ -0,0 +1,9 @@
+export * from "./composition";
+export * from "./composePlan";
+export * from "./brandKit";
+export * from "./font";
+export * from "./render";
+export * from "./registry";
+export * from "./project";
+export * from "./session";
+export * from "./webhook";

package/dist/_members/composition/validators/project.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+export declare const Project: z.ZodObject<{
+    id: import("convex-helpers/server/zod3").Zid<"projects">;
+    name: z.ZodString;
+    defaultFormat: z.ZodOptional<z.ZodObject<{
+        aspectRatio: z.ZodEnum<["16:9", "9:16", "1:1", "4:5"]>;
+        fps: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<24>, z.ZodLiteral<30>, z.ZodLiteral<60>]>>;
+        resolution: z.ZodOptional<z.ZodEnum<["hd", "fhd", "4k"]>>;
+        platform: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        aspectRatio: "16:9" | "9:16" | "1:1" | "4:5";
+        fps?: 24 | 30 | 60 | undefined;
+        resolution?: "hd" | "fhd" | "4k" | undefined;
+        platform?: string | undefined;
+    }, {
+        aspectRatio: "16:9" | "9:16" | "1:1" | "4:5";
+        fps?: 24 | 30 | 60 | undefined;
+        resolution?: "hd" | "fhd" | "4k" | undefined;
+        platform?: string | undefined;
+    }>>;
+    palConformDefault: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<24>, z.ZodLiteral<30>]>>;
+    activeCompositionId: z.ZodOptional<z.ZodNullable<import("convex-helpers/server/zod3").Zid<"compositions">>>;
+    brandKitId: z.ZodOptional<z.ZodString>;
+    ownerOrgId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    id: string & {
+        __tableName: "projects";
+    };
+    name: string;
+    createdAt: number;
+    updatedAt: number;
+    ownerOrgId?: string | undefined;
+    defaultFormat?: {
+        aspectRatio: "16:9" | "9:16" | "1:1" | "4:5";
+        fps?: 24 | 30 | 60 | undefined;
+        resolution?: "hd" | "fhd" | "4k" | undefined;
+        platform?: string | undefined;
+    } | undefined;
+    palConformDefault?: 24 | 30 | undefined;
+    activeCompositionId?: import("convex/values").GenericId<"compositions"> | null | undefined;
+    brandKitId?: string | undefined;
+}, {
+    id: string & {
+        __tableName: "projects";
+    };
+    name: string;
+    createdAt: number;
+    updatedAt: number;
+    ownerOrgId?: string | undefined;
+    defaultFormat?: {
+        aspectRatio: "16:9" | "9:16" | "1:1" | "4:5";
+        fps?: 24 | 30 | 60 | undefined;
+        resolution?: "hd" | "fhd" | "4k" | undefined;
+        platform?: string | undefined;
+    } | undefined;
+    palConformDefault?: 24 | 30 | undefined;
+    activeCompositionId?: import("convex/values").GenericId<"compositions"> | null | undefined;
+    brandKitId?: string | undefined;
+}>;
+export type Project = z.infer<typeof Project>;

package/dist/_members/composition/validators/project.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { zid } from "convex-helpers/server/zod3";
+import { Format } from "./composition";
+// Project per data-model.md § Project — top-level container that holds an
+// active editable Composition pointer, default format for new compositions,
+// and references to brand kit + render history. Compositions stay queryable
+// independently; the Project just points at the current "active" version.
+export const Project = z.object({
+    id: zid("projects"),
+    name: z.string().min(1),
+    // Default format applied to new Compositions created under this Project.
+    // Each Composition still carries its own Format — this is just the seed.
+    defaultFormat: Format.optional(),
+    // PAL-region fps conform default. See data-model.md § MediaItem for the table.
+    // 'palConformDefault: 24' makes 25fps PAL footage conform to 24 instead of 30.
+    palConformDefault: z.union([z.literal(24), z.literal(30)]).optional(),
+    // Pointer to the currently-active Composition for this Project. Edits land
+    // on a new CompositionVersion each PUT; this pointer advances to the new
+    // version's id. Nullable when the Project has no active Composition (e.g.,
+    // immediately after creation, or after the active composition was hard-deleted).
+    activeCompositionId: zid("compositions").nullable().optional(),
+    // Stable external `kitId` STRING (the v1 brand-kits API id), not a strict
+    // `zid("brandKits")`. Resolved org-scoped at render by either kitId or the
+    // legacy convex `_id`. Keeps the brand reference consistent end-to-end (#33).
+    brandKitId: z.string().optional(),
+    ownerOrgId: z.string().optional(),
+    createdAt: z.number(),
+    updatedAt: z.number(),
+});

package/dist/_members/composition/validators/registry.d.ts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+export declare const PrimitiveOriginClass: z.ZodEnum<["first-party", "community-verified", "community-unverified", "user-private", "sandbox", "deprecated"]>;
+export type PrimitiveOriginClass = z.infer<typeof PrimitiveOriginClass>;
+export declare const PrimitiveMode: z.ZodEnum<["2d", "immersive", "interactive"]>;
+export type PrimitiveMode = z.infer<typeof PrimitiveMode>;
+export declare const PrimitiveToken: z.ZodObject<{
+    path: z.ZodString;
+    fallback: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    fallback?: unknown;
+}, {
+    path: string;
+    fallback?: unknown;
+}>;
+export declare const PrimitiveOtioMapping: z.ZodObject<{
+    effectName: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    effectName: string;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    effectName: string;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+export declare const PrimitiveMeta: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    use_when: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    avoid_when: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    vibe: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    formats: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    pairs_well_with: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    exemplars: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    description?: string | undefined;
+    use_when?: string[] | undefined;
+    avoid_when?: string[] | undefined;
+    vibe?: string[] | undefined;
+    formats?: string[] | undefined;
+    pairs_well_with?: string[] | undefined;
+    exemplars?: string[] | undefined;
+}, {
+    description?: string | undefined;
+    use_when?: string[] | undefined;
+    avoid_when?: string[] | undefined;
+    vibe?: string[] | undefined;
+    formats?: string[] | undefined;
+    pairs_well_with?: string[] | undefined;
+    exemplars?: string[] | undefined;
+}>;
+export declare const PrimitiveRegistryEntry: z.ZodObject<{
+    name: z.ZodString;
+    package: z.ZodString;
+    category: z.ZodEnum<["overlay", "text", "effect", "transition", "layout"]>;
+    version: z.ZodString;
+    origin: z.ZodEnum<["first-party", "community-verified", "community-unverified", "user-private", "sandbox", "deprecated"]>;
+    modes: z.ZodOptional<z.ZodArray<z.ZodEnum<["2d", "immersive", "interactive"]>, "many">>;
+    paramsSchema: z.ZodUnknown;
+    varyingParams: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    extends: z.ZodOptional<z.ZodString>;
+    tokens: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        fallback: z.ZodUnknown;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        fallback?: unknown;
+    }, {
+        path: string;
+        fallback?: unknown;
+    }>, "many">>;
+    otio: z.ZodOptional<z.ZodObject<{
+        effectName: z.ZodString;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        effectName: string;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        effectName: string;
+        metadata?: Record<string, unknown> | undefined;
+    }>>;
+    meta: z.ZodOptional<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        use_when: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        avoid_when: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        vibe: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        formats: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        pairs_well_with: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        exemplars: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+        use_when?: string[] | undefined;
+        avoid_when?: string[] | undefined;
+        vibe?: string[] | undefined;
+        formats?: string[] | undefined;
+        pairs_well_with?: string[] | undefined;
+        exemplars?: string[] | undefined;
+    }, {
+        description?: string | undefined;
+        use_when?: string[] | undefined;
+        avoid_when?: string[] | undefined;
+        vibe?: string[] | undefined;
+        formats?: string[] | undefined;
+        pairs_well_with?: string[] | undefined;
+        exemplars?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    version: string;
+    package: string;
+    category: "overlay" | "effect" | "text" | "transition" | "layout";
+    origin: "first-party" | "community-verified" | "community-unverified" | "user-private" | "sandbox" | "deprecated";
+    tokens?: {
+        path: string;
+        fallback?: unknown;
+    }[] | undefined;
+    modes?: ("interactive" | "2d" | "immersive")[] | undefined;
+    paramsSchema?: unknown;
+    varyingParams?: string[] | undefined;
+    extends?: string | undefined;
+    otio?: {
+        effectName: string;
+        metadata?: Record<string, unknown> | undefined;
+    } | undefined;
+    meta?: {
+        description?: string | undefined;
+        use_when?: string[] | undefined;
+        avoid_when?: string[] | undefined;
+        vibe?: string[] | undefined;
+        formats?: string[] | undefined;
+        pairs_well_with?: string[] | undefined;
+        exemplars?: string[] | undefined;
+    } | undefined;
+}, {
+    name: string;
+    version: string;
+    package: string;
+    category: "overlay" | "effect" | "text" | "transition" | "layout";
+    origin: "first-party" | "community-verified" | "community-unverified" | "user-private" | "sandbox" | "deprecated";
+    tokens?: {
+        path: string;
+        fallback?: unknown;
+    }[] | undefined;
+    modes?: ("interactive" | "2d" | "immersive")[] | undefined;
+    paramsSchema?: unknown;
+    varyingParams?: string[] | undefined;
+    extends?: string | undefined;
+    otio?: {
+        effectName: string;
+        metadata?: Record<string, unknown> | undefined;
+    } | undefined;
+    meta?: {
+        description?: string | undefined;
+        use_when?: string[] | undefined;
+        avoid_when?: string[] | undefined;
+        vibe?: string[] | undefined;
+        formats?: string[] | undefined;
+        pairs_well_with?: string[] | undefined;
+        exemplars?: string[] | undefined;
+    } | undefined;
+}>;
+export type PrimitiveRegistryEntry = z.infer<typeof PrimitiveRegistryEntry>;

package/dist/_members/composition/validators/registry.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+export const PrimitiveOriginClass = z.enum([
+    "first-party",
+    "community-verified",
+    "community-unverified",
+    "user-private",
+    "sandbox",
+    "deprecated",
+]);
+export const PrimitiveMode = z.enum(["2d", "immersive", "interactive"]);
+export const PrimitiveToken = z.object({
+    path: z.string().min(1),
+    fallback: z.unknown(),
+});
+export const PrimitiveOtioMapping = z.object({
+    effectName: z.string().min(1),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const PrimitiveMeta = z.object({
+    description: z.string().optional(),
+    use_when: z.array(z.string()).optional(),
+    avoid_when: z.array(z.string()).optional(),
+    vibe: z.array(z.string()).optional(),
+    formats: z.array(z.string()).optional(),
+    pairs_well_with: z.array(z.string()).optional(),
+    exemplars: z.array(z.string()).optional(),
+});
+export const PrimitiveRegistryEntry = z.object({
+    name: z.string().min(1),
+    package: z.string().min(1),
+    category: z.enum(["overlay", "text", "effect", "transition", "layout"]),
+    version: z.string().min(1),
+    origin: PrimitiveOriginClass,
+    modes: z.array(PrimitiveMode).optional(),
+    paramsSchema: z.unknown(),
+    varyingParams: z.array(z.string()).optional(),
+    extends: z.string().optional(),
+    tokens: z.array(PrimitiveToken).optional(),
+    otio: PrimitiveOtioMapping.optional(),
+    meta: PrimitiveMeta.optional(),
+});