@cueframe/kernel 0.0.1

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

@@ -0,0 +1,295 @@
+import { z } from "zod";
+import { zid } from "convex-helpers/server/zod3";
+import { GraphicRole } from "../graphics-plan/schemas.js";
+export const EasingValue = z.union([
+    z.enum(["linear", "ease", "ease-in", "ease-out", "ease-in-out"]),
+    z.object({
+        kind: z.literal("cubic-bezier"),
+        x1: z.number().min(0).max(1),
+        y1: z.number(),
+        x2: z.number().min(0).max(1),
+        y2: z.number(),
+    }),
+]);
+/** A palette reference (audio-substrate P2 AudioPaletteEntry.ref): a pack
+ *  soundId | music-pack bedId | org mediaId — an opaque string placement handle.
+ *  The brand SOUND kit fields (audio.sonicLogo / uiSoundSet / bedStyle /
+ *  ambiencePreference) reference sounds by this same handle. */
+export const AudioPaletteRef = z.string().min(1);
+export const FontRef = z.union([
+    z.object({
+        kind: z.literal("system"),
+        family: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal("web"),
+        family: z.string().min(1),
+        url: z.string().url().optional(),
+    }),
+    z.object({
+        kind: z.literal("uploaded"),
+        fontId: zid("fonts"),
+        family: z.string().optional(),
+    }),
+]);
+const Colors = z.object({
+    primary: z.string().min(1),
+    secondary: z.string().optional(),
+    accent: z.string().min(1),
+    background: z.string().min(1),
+    text: z.string().min(1),
+    textMuted: z.string().optional(),
+    border: z.string().optional(),
+    // Tier-2 core — author overrides for the derived fills + paired foregrounds.
+    surface: z.string().optional(),
+    card: z.string().optional(),
+    gridLine: z.string().optional(),
+    accentMuted: z.string().optional(),
+    textOnAccent: z.string().optional(),
+    textOnSurface: z.string().optional(),
+});
+const Fonts = z.object({
+    heading: FontRef,
+    body: FontRef.optional(),
+    caption: FontRef.optional(),
+});
+const Spacing = z.object({
+    base: z.number().positive().optional(),
+    lg: z.number().positive().optional(),
+    sm: z.number().positive().optional(),
+});
+const Sizing = z.object({
+    fontSizeHeading: z.number().positive().optional(),
+    fontSizeBody: z.number().positive().optional(),
+    fontSizeLabel: z.number().positive().optional(),
+    borderRadius: z.number().nonnegative().optional(),
+});
+const Motion = z.object({
+    duration: z.number().positive().optional(),
+    easing: EasingValue.optional(),
+    // Editorial motion identity — surfaces read these via `$brand:motion.*`
+    // (resolved at projection time). Mirrors the primitive `TextMotion` vocabulary.
+    entrance: z.enum(["none", "fade", "word-pop", "stagger-up"]).optional(),
+    staggerMs: z.number().nonnegative().optional(),
+    exitMs: z.number().nonnegative().optional(),
+});
+// Corner anchor shared by logo + watermark overlays.
+const Placement = z.enum(["tl", "tr", "bl", "br"]);
+const Logo = z.object({
+    src: z.string().min(1),
+    alt: z.string().optional(),
+    placement: Placement.optional(),
+    // Percentage of the composition width. Must be positive — a non-positive
+    // logo is a footgun, not an intent, so reject at the boundary.
+    sizePct: z.number().positive().optional(),
+});
+// Intro/outro bumper: either an authored card (title/subtitle on brand) or a
+// pre-rendered video clip. `src` is optional on disk — a card needs none, and
+// a video kit may carry the asset reference separately — so the wire shape
+// stays sparse and the resolver fails loud later if a video lacks its source.
+const IntroOutro = z.object({
+    kind: z.enum(["card", "video"]),
+    src: z.string().min(1).optional(),
+    title: z.string().optional(),
+    subtitle: z.string().optional(),
+    durationMs: z.number().positive().optional(),
+});
+const Watermark = z.object({
+    src: z.string().min(1),
+    // Alpha in [0,1]; anything outside is a malformed kit, not a clamp target.
+    opacity: z.number().min(0).max(1).optional(),
+    placement: Placement.optional(),
+});
+// ── Brand-kit language payload (built FROM INSPIRATION — spec 2026-07-14) ────
+// A motif is an observed on-screen graphic reproduced as an ordinary authored
+// skin (card html / overlay primitive / installed component). These mirror the
+// storage validators (composition.ts) and the HTTP schemas (schemas.ts Step 1.5)
+// verbatim — the wire validator has no `.openapi()` calls, so the shapes here
+// are the plain-zod twins carried onto the wire BrandKit for the projection.
+const MotifBody = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("card"),
+        html: z.string().min(1),
+        tokens: z.record(z.string(), z.string()).optional(),
+    }),
+    z.object({
+        kind: z.literal("overlay"),
+        primitiveId: z.string().min(1),
+        params: z.record(z.string(), z.unknown()).optional(),
+    }),
+    z.object({
+        kind: z.literal("component"),
+        componentId: z.string().min(1),
+        props: z.record(z.string(), z.unknown()).optional(),
+    }),
+]);
+// Closed vocabulary — SSOT is MOTION_PRESETS (packages/authoring/src/motion/shell.ts).
+const MotifMotionPreset = z.enum([
+    "fade-up",
+    "slide-in-left",
+    "slide-in-right",
+    "scale-pop",
+    "stagger-reveal",
+]);
+export const Motif = z.object({
+    id: z.string().min(1).max(40),
+    observed: z.string().min(1).max(500),
+    body: MotifBody,
+    motion: z.object({
+        preset: MotifMotionPreset,
+        enterMs: z.number().int().min(0).max(5000).optional(),
+        exitMs: z.number().int().min(0).max(5000).optional(),
+        staggerMs: z.number().int().min(0).max(2000).optional(),
+        confidence: z.enum(["high", "low"]).optional(),
+    }).optional(),
+    // Pinned to the closed graphics-plan GraphicRole vocabulary — the steering
+    // matcher (designBrief.ts) is exact-equality against a plan role, so an
+    // off-vocabulary role would synthesize a judge and then silently never steer
+    // (the half-applied-conditioning failure D1-R exists to kill). Storage stays
+    // an open string (matches the motion.preset pattern).
+    role: GraphicRole,
+    zone: z.object({ x: z.number(), y: z.number(), w: z.number(), h: z.number() }).optional(),
+    evidence: z.array(z.number().int().min(0)).max(24).optional(),
+    diffScore: z.number().min(0).max(1).optional(),
+    coverage: z.enum(["reproduced", "approximated", "skipped"]),
+    skipReason: z.string().max(300).optional(),
+});
+const AccessControl = z.object({
+    public: z.boolean().optional(),
+    readerOrgIds: z.array(z.string()).optional(),
+    writerOrgIds: z.array(z.string()).optional(),
+});
+const LicenseDeclaration = z.object({
+    type: z.string().min(1),
+    source: z.string().optional(),
+    notes: z.string().optional(),
+});
+export const BrandKit = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    colors: Colors,
+    fonts: Fonts,
+    spacing: Spacing.optional(),
+    sizing: Sizing.optional(),
+    motion: Motion.optional(),
+    // Per-creator caption IDENTITY collected by the dashboard / derived from a
+    // creator's references. Consumed by resolveBrandKit's caption derivation:
+    // emphasisColor → caption.fg, base/highlight color (clamped to the APCA body
+    // floor over the scrim), the backdrop `plate` treatment, per-word `entrance`
+    // motion + timing, and the emphasis treatment (base face + serif/scale/weight/
+    // italic/transform/letter-spacing + emphasis-run plate) → caption identity
+    // that the render binding applies onto the Captions primitive. The kit now
+    // owns the caption LOOK (including plate + entrance). Base GEOMETRY (caption
+    // size, screen position, safe-area, maxWidth) is NOT here — that is calibrated
+    // craft owned by the primitive's default. The kit selects the LOOK; the
+    // primitive owns the legible realization.
+    captionProfile: z
+        .object({
+        // Base caption text color + spoken-word highlight — clamped to the APCA
+        // body floor over the scrim at projection (same guard as emphasisColor→fg).
+        color: z.string().optional(),
+        highlightColor: z.string().optional(),
+        emphasisColor: z.string().optional(),
+        // Caption backdrop plate — the whole-block legibility treatment.
+        plate: z.enum(["glass", "solid", "none"]).optional(),
+        // Per-word entrance motion + timing (the shared TextMotion vocabulary).
+        entrance: z.enum(["none", "fade", "word-pop", "stagger-up"]).optional(),
+        entranceMs: z.number().optional(),
+        entranceStaggerMs: z.number().optional(),
+        exitMs: z.number().optional(),
+        // Base caption face (the carrier-word font). Defaults to fonts.caption.
+        fontFamily: z.string().optional(),
+        // Emphasis-word treatment — the qualitative identity signal.
+        emphasisFontFamily: z.string().optional(),
+        emphasisScale: z.number().positive().optional(),
+        emphasisFontWeight: z.number().optional(),
+        emphasisFontStyle: z.enum(["normal", "italic"]).optional(),
+        emphasisTextTransform: z.enum(["none", "uppercase"]).optional(),
+        emphasisLetterSpacing: z.number().optional(),
+        // Emphasis-run highlighter plate (editorial caption look).
+        emphasisPlate: z.boolean().optional(),
+        emphasisPlateColor: z.string().optional(),
+        emphasisPlateTextColor: z.string().optional(),
+    })
+        .optional(),
+    // ── Language payload (built FROM INSPIRATION) ─────────────────────────────
+    // Carried untransformed onto the wire kit so the projection (resolveBrandKit)
+    // can surface it as `ResolvedBrandKit.language`. Not a `$brand:` token root —
+    // these are exemplar/motif references the maker + judge condition on, not
+    // bindable design tokens.
+    exemplarKeys: z.array(z.string().min(1)).max(24).optional(),
+    contactSheetKey: z.string().min(1).optional(),
+    motifs: z.array(Motif).max(24).optional(),
+    styleRubric: z.string().max(4000).optional(),
+    density: z.object({
+        graphicsPerMin: z.number().min(0).max(60),
+        maxSimultaneous: z.number().int().min(1).max(6),
+    }).optional(),
+    inspiration: z.object({
+        sources: z.array(z.string()).min(1).max(24),
+        extractedAt: z.number(),
+        extractionVersion: z.string().min(1).max(60),
+    }).optional(),
+    logo: Logo.optional(),
+    intro: IntroOutro.optional(),
+    outro: IntroOutro.optional(),
+    watermark: Watermark.optional(),
+    /** Brand audio identity (audio design spec 2026-07-20): default SFX intensity
+     *  + music-bed defaults. Brief `audio` wins when present (caption-identity
+     *  precedence: brand default beats brief absence; brief beats brand).
+     *
+     *  Brand SOUND kit (audio-substrate Phase 5) — identity over TIME. All four
+     *  fields are OPTIONAL; a kit that sets none behaves byte-identically to a kit
+     *  with no audio block. Refs are palette references (P2 AudioPaletteEntry.ref:
+     *  a pack soundId | music-pack bedId | org mediaId — an opaque string handle). */
+    audio: z.object({
+        sfxIntensity: z.enum(["off", "light", "standard", "dense"]).optional(),
+        musicEnabled: z.boolean().optional(),
+        musicMood: z.string().max(300).optional(),
+        /** SONIC LOGO — a brand audio signature bound to the intro/outro bookend at
+         *  compose time (an sfx-role clip at the body edge adjacent to the render
+         *  bookend). `ref` = a palette reference; `placement` = which bookend(s);
+         *  `offsetMs` shifts within. Bound only when the corresponding bumper
+         *  (kit.intro / kit.outro) exists — else a non-blocking advisory. */
+        sonicLogo: z.object({
+            ref: AudioPaletteRef,
+            placement: z.enum(["intro", "outro", "both"]),
+            offsetMs: z.number().int().min(0).max(10000).optional(),
+        }).optional(),
+        /** UI SOUND SET — per-family palette overrides consumed by the sfxCompile
+         *  org-first draw as the HIGHEST-priority tier (brand > org palette > pack
+         *  default), mirroring how a brand FONT sits above org defaults. Keys are the
+         *  closed SfxFamily vocabulary; values are palette refs. */
+        uiSoundSet: z.object({
+            tick: AudioPaletteRef.optional(),
+            pop: AudioPaletteRef.optional(),
+            impact: AudioPaletteRef.optional(),
+            confirm: AudioPaletteRef.optional(),
+            error: AudioPaletteRef.optional(),
+            whoosh: AudioPaletteRef.optional(),
+            riser: AudioPaletteRef.optional(),
+        }).optional(),
+        /** BED STYLE — a preferred pack bed (`bedId`) or a style hint (`genre` /
+         *  `bpmRange`). SURFACED-ONLY today (compose does not auto-select a pack bed
+         *  — it uses a client-pinned bed or generates from mood); the field resolves
+         *  through the kit + surfaces via get_profile / brand-kit reads so driving
+         *  agents honor it when pinning / generating a bed. */
+        bedStyle: z.object({
+            bedId: AudioPaletteRef.optional(),
+            genre: z.string().max(120).optional(),
+            bpmRange: z.object({ min: z.number(), max: z.number() }).optional(),
+        }).optional(),
+        /** AMBIENCE PREFERENCE — a preferred ambience bed (`{ref}`) or explicit
+         *  `null` (opt-out). SURFACED-ONLY (compose has no ambience auto-placement);
+         *  resolves + surfaces for driving agents. */
+        ambiencePreference: z.object({ ref: AudioPaletteRef }).nullable().optional(),
+    }).optional(),
+    license: LicenseDeclaration.optional(),
+    licenseVerification: z.enum([
+        "attested",
+        "cueframe-verified",
+        "third-party-verified",
+    ]).optional(),
+    ownerOrgId: z.string().optional(),
+    acl: AccessControl.optional(),
+});