@odla-ai/brand 0.1.0 → 0.2.0

package/dist/index-bj73h3qo.d.ts

@@ -0,0 +1,409 @@
+/** The odla-db namespaces @odla-ai/brand installs and writes. */
+declare const BRAND_NS: {
+    readonly book: "brand_book";
+    readonly section: "brand_section";
+    readonly palette: "brand_palette";
+    readonly proposal: "brand_proposal";
+    readonly asset: "brand_asset";
+};
+/** Brand-book lifecycle: authored → adopted → retired (delete is owner-only). */
+declare const BOOK_STATUSES: readonly ["draft", "active", "archived"];
+/** Where a brand book stands in its lifecycle. */
+type BookStatus = (typeof BOOK_STATUSES)[number];
+/** The section kinds a book carries — one row per kind, upserted by natural key. */
+declare const SECTION_KINDS: readonly ["palette", "typography", "voice", "logo", "imagery"];
+/** Which facet of the brand a section documents. */
+type SectionKind = (typeof SECTION_KINDS)[number];
+/** Section review state: agent drafts, a human approves. */
+declare const SECTION_STATUSES: readonly ["draft", "approved"];
+/** Whether a section's content has human sign-off. */
+type SectionStatus = (typeof SECTION_STATUSES)[number];
+/** Palette lifecycle — palettes are never row-deleted, only archived. */
+declare const PALETTE_STATUSES: readonly ["active", "archived"];
+/** Whether a palette is the live one or a retired predecessor. */
+type PaletteStatus = (typeof PALETTE_STATUSES)[number];
+/** How a palette came to be: pulled from an asset, derived from a seed color,
+ * or entered by hand. */
+declare const PALETTE_SOURCES: readonly ["extracted", "derived", "manual"];
+/** Provenance of a palette's swatches. */
+type PaletteSource = (typeof PALETTE_SOURCES)[number];
+/** What a proposal proposes (palettes are the first-class case). */
+declare const PROPOSAL_KINDS: readonly ["palette", "typography", "voice", "logo"];
+/** Which brand facet a proposal targets. */
+type ProposalKind = (typeof PROPOSAL_KINDS)[number];
+/** Proposal lifecycle: open until a HUMAN accepts/rejects it (or a newer
+ * proposal supersedes it) — agents never resolve their own proposals. */
+declare const PROPOSAL_STATUSES: readonly ["open", "accepted", "rejected", "superseded"];
+/** Where a proposal stands in the human-gated review flow. */
+type ProposalStatus = (typeof PROPOSAL_STATUSES)[number];
+/** What kind of upload an asset row records. */
+declare const ASSET_KINDS: readonly ["logo", "wordmark", "inspiration", "document", "font", "other"];
+/** The declared purpose of an uploaded asset. */
+type AssetKind = (typeof ASSET_KINDS)[number];
+/** Every swatch role a palette may assign. `chart` may repeat (a series);
+ * `custom` is the escape hatch for roles the token compiler doesn't map. */
+declare const SWATCH_ROLES: readonly ["primary", "secondary", "highlight", "bg", "surface", "text", "neutral", "good", "warn", "danger", "chart", "custom"];
+
+/** Scalar values odla-db attrs and where-clauses accept. */
+type BrandScalar = string | number | boolean | null;
+/** Natural-key lookup ref for idempotent upserts (odla-db `Lookup` shape). */
+interface BrandLookup {
+    ns: string;
+    attr: string;
+    value: BrandScalar;
+}
+/** How an op names its row: a raw entity id, or a natural-key lookup. */
+type BrandEntityRef = string | BrandLookup;
+/** Attr payload of one op. Typed `any` on purpose: the real odla-db
+ * `transact` constrains attrs to its own `Value` type, and `any` is the one
+ * shape assignable in both directions with no cast. */
+type BrandAttrs = Record<string, any>;
+/** One transact operation (update = attr-merge upsert; merge = deep-merge
+ * into a json attribute; retract = clear the named attributes, since a typed
+ * scalar can't store null). */
+type BrandOp = {
+    t: "update";
+    ns: string;
+    id: BrandEntityRef;
+    attrs: BrandAttrs;
+} | {
+    t: "merge";
+    ns: string;
+    id: BrandEntityRef;
+    attrs: BrandAttrs;
+} | {
+    t: "retract";
+    ns: string;
+    id: BrandEntityRef;
+    attrs: string[];
+} | {
+    t: "delete";
+    ns: string;
+    id: BrandEntityRef;
+};
+/** A row as odla-db returns it: hydrated id plus attrs. */
+type BrandRow = {
+    id: string;
+} & Record<string, unknown>;
+/** Query result: namespace → rows. */
+type BrandResult = Record<string, BrandRow[]>;
+/** The role a swatch plays in the palette (what the token compiler maps). */
+type SwatchRole = (typeof SWATCH_ROLES)[number];
+/** One palette color: a role, a `#rrggbb` hex, and optional naming/why. */
+interface Swatch {
+    role: SwatchRole;
+    hex: string;
+    name?: string;
+    rationale?: string;
+}
+/** `palette`-kind section content: the accepted palette, denormalized. */
+interface PaletteSection {
+    paletteId: string;
+    name: string;
+    swatches: Swatch[];
+}
+/** `typography`-kind section content. `scale` is a modular type-scale ratio. */
+interface TypographySection {
+    fontDisplay?: string;
+    fontBody?: string;
+    fontMono?: string;
+    scale?: number;
+    notes?: string;
+}
+/** `voice`-kind section content: tone plus writing principles/examples. */
+interface VoiceSection {
+    tone: string;
+    principles: string[];
+    examples?: string[];
+}
+/** `logo`-kind section content: usage rules and don'ts. */
+interface LogoSection {
+    clearspace?: string;
+    minSize?: string;
+    usage: string[];
+    donts: string[];
+}
+/** `imagery`-kind section content: photographic/illustration direction. */
+interface ImagerySection {
+    style: string;
+    guidance: string[];
+}
+/** Agent-produced description of an uploaded asset (validated + capped). */
+interface AssetAnalysis {
+    description: string;
+    dominantColors: string[];
+    tags: string[];
+}
+/** The compiled-token cache stored on `brand_book.tokens`. `warnings` carries
+ * the compiler's `TokenWarning[]` (typed loosely here so the row types don't
+ * depend on the token compiler's module). */
+interface BrandTokensSnapshot {
+    light: Record<string, string>;
+    dark: Record<string, string>;
+    warnings: unknown[];
+    compiledAt: number;
+}
+/** A brand book row: the auth roster (`memberIds`, including the bot agent
+ * id) plus the active palette and compiled-token cache. */
+interface BrandBook {
+    id: string;
+    slug: string;
+    name: string;
+    status: BookStatus;
+    ownerId: string;
+    memberIds: string[];
+    channelId?: string;
+    activePaletteId?: string;
+    tokens?: BrandTokensSnapshot;
+    summary?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/** A section row — one per (book, kind), upserted by its natural `key`. */
+interface BrandSection {
+    id: string;
+    key: string;
+    bookId: string;
+    kind: SectionKind;
+    status: SectionStatus;
+    content: Record<string, unknown>;
+    audience: string[];
+    updatedBy: string;
+    updatedAt: number;
+}
+/** A palette row. Swatches are json ON the palette, not a namespace: the
+ * palette is the atomic proposal/approval unit and swatches are never
+ * queried across palettes. */
+interface BrandPalette {
+    id: string;
+    bookId: string;
+    name: string;
+    status: PaletteStatus;
+    swatches: Swatch[];
+    seedHex?: string;
+    source: PaletteSource;
+    rationale?: string;
+    proposalId?: string;
+    audience: string[];
+    createdAt: number;
+    updatedAt: number;
+}
+/** A proposal row: agent output parked for explicit human resolution. */
+interface BrandProposal {
+    id: string;
+    bookId: string;
+    kind: ProposalKind;
+    status: ProposalStatus;
+    payload: Record<string, unknown>;
+    rationale: string;
+    sourceAssetId?: string;
+    messageId?: string;
+    audience: string[];
+    createdBy: string;
+    createdAt: number;
+    resolvedBy?: string;
+    resolvedAt?: number;
+    resolutionNote?: string;
+}
+/** An asset row mirroring one real uploaded file (worker-mediated; rules
+ * close the namespace). Delete is a tombstone (`deletedAt`), never a row
+ * delete, so analyses/proposals referencing it stay coherent. */
+interface BrandAsset {
+    id: string;
+    bookId: string;
+    kind: AssetKind;
+    path: string;
+    url: string;
+    contentType: string;
+    size: number;
+    title?: string;
+    analysis?: AssetAnalysis;
+    analyzedAt?: number;
+    audience: string[];
+    uploadedBy: string;
+    createdAt: number;
+    deletedAt?: number;
+}
+/** What `db.storage.upload` resolves to (odla-db's file record shape). */
+interface BrandFileRecord {
+    id: string;
+    path: string;
+    url: string;
+    size: number;
+    contentType: string;
+}
+/** Bodies `storage.upload` accepts — a practical subset of the platform's
+ * `BodyInit` (which has no ambient type under a DOM-less lib). The real
+ * @odla-ai/db client accepts a superset, so it still structurally satisfies
+ * {@link BrandStorage}. */
+type BrandUploadBody = string | Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>;
+/** The injected file store — @odla-ai/db's `storage` API satisfies this. */
+interface BrandStorage {
+    upload(path: string, data: BrandUploadBody, contentType?: string): Promise<BrandFileRecord>;
+    delete(path: string): Promise<void>;
+}
+/** The injected odla client (structural — a real @odla-ai/db `AdminDb`
+ * satisfies it). `transact` accepts flat op arrays and `mutationId` gives
+ * exactly-once application (`duplicate: true` on replay). */
+interface BrandDb {
+    query(q: Record<string, unknown>): Promise<Record<string, unknown[]>>;
+    transact(ops: unknown[], opts?: {
+        mutationId?: string;
+    }): Promise<{
+        txId: number;
+        duplicate?: boolean;
+    }>;
+    storage: BrandStorage;
+}
+/** Who is acting: a human member or the book's bot agent. */
+interface BrandActor {
+    id: string;
+    kind: "human" | "agent";
+    email?: string;
+}
+
+/**
+ * The @odla-ai/ui required tier (js/tokens.js REQUIRED_TOKENS), in the ui
+ * contract's order. The compiler always emits a concrete value for every
+ * one of these.
+ */
+declare const BRAND_REQUIRED_TOKENS: readonly ["--ui-bg", "--ui-surface", "--ui-surface-2", "--ui-text", "--ui-text-muted", "--ui-text-faint", "--ui-border", "--ui-border-strong", "--ui-accent", "--ui-accent-strong", "--ui-accent-soft", "--ui-on-accent", "--ui-good", "--ui-good-soft", "--ui-warn", "--ui-warn-soft", "--ui-danger", "--ui-danger-soft", "--ui-code-bg", "--ui-code-text", "--ui-shadow", "--ui-font-sans", "--ui-font-serif", "--ui-font-mono", "--ui-font-display"];
+/**
+ * Accent-composing derived roles from the ui defaulted tier. All five
+ * accent-family members of the :where([data-ui-accent]) re-declaration set
+ * (--ui-accent-glow, --ui-accent-2, --ui-accent-2-soft, --ui-highlight,
+ * --ui-focus) plus --ui-shadow-strong, which composes var(--ui-shadow) —
+ * a token this compiler re-declares, so the island rule applies to it too.
+ */
+declare const BRAND_DERIVED_TOKENS: readonly ["--ui-accent-glow", "--ui-accent-2", "--ui-accent-2-soft", "--ui-highlight", "--ui-focus", "--ui-shadow-strong"];
+/**
+ * Chart roles the compiler emits: the six series slots (real palette
+ * swatches when the palette carries them, ui var() compositions otherwise)
+ * and the four accent-composing chart roles the :where([data-ui-accent])
+ * block re-declares (band, band-strong, flow, glow).
+ */
+declare const BRAND_CHART_TOKENS: readonly ["--ui-chart-1", "--ui-chart-2", "--ui-chart-3", "--ui-chart-4", "--ui-chart-5", "--ui-chart-6", "--ui-chart-band", "--ui-chart-band-strong", "--ui-chart-flow", "--ui-chart-glow"];
+/**
+ * Chat surface roles (js/tokens.js CHAT_TOKENS, complete). Two are in the
+ * accent-swap set (user-bg, tool-accent); the other four compose surface /
+ * text tokens the compiler also re-declares, so an island stays coherent.
+ */
+declare const BRAND_CHAT_TOKENS: readonly ["--ui-chat-user-bg", "--ui-chat-user-text", "--ui-chat-assistant-bg", "--ui-chat-thinking-bg", "--ui-chat-thinking-text", "--ui-chat-tool-accent"];
+/**
+ * Every token the compiler emits, in emission order — also the deterministic
+ * declaration order renderTokensCss uses, so golden CSS fixtures are stable.
+ */
+declare const BRAND_EMITTED_TOKENS: readonly string[];
+
+/**
+ * A compiled token map: `--ui-*` custom-property name → CSS value. Values
+ * are either concrete (hex, font stack, shadow) or composition strings
+ * (`var(--ui-accent)`, `color-mix(in srgb, var(--ui-accent) 10%, transparent)`)
+ * that recompute wherever the map is declared — which is what lets one
+ * object serve as both a :root theme and a scoped override-island payload.
+ */
+type BrandTokens = Record<string, string>;
+/**
+ * A non-fatal compiler note: a missing swatch role that fell back to a
+ * derived value, a dropped invalid input, or a color the compiler had to
+ * move to clear a WCAG contrast bar (then `adjustedFrom` carries the
+ * original hex).
+ */
+interface TokenWarning {
+    /** The `--ui-*` token the note is about. */
+    token: string;
+    /** Human-readable explanation, actionable for the brand author. */
+    message: string;
+    /** The original hex, when the compiler adjusted a color for contrast. */
+    adjustedFrom?: string;
+}
+/** Input to {@link import("./compile").compileBrandTokens}. */
+interface CompileInput {
+    /** The palette to compile — typically a brand_palette row's swatches. */
+    swatches: Swatch[];
+    /** Optional typography section; fonts get system-stack fallbacks appended. */
+    typography?: TypographySection;
+    /** Author escape hatch: applied verbatim onto the light map, last. */
+    overrides?: BrandTokens;
+}
+/** The compiler's result: light + derived dark token maps, plus notes. */
+interface CompiledBrandTokens {
+    /** Light-mode tokens (every name in BRAND_EMITTED_TOKENS, plus overrides). */
+    light: BrandTokens;
+    /** Dark-mode tokens derived from `light` — same key set. */
+    dark: BrandTokens;
+    /** Fallbacks taken and contrast adjustments made; empty on a clean palette. */
+    warnings: TokenWarning[];
+}
+
+/**
+ * Seed used when the palette has no usable chromatic swatch at all — the
+ * @odla-ai/ui neutral default accent (css/tokens.css restrained blue).
+ */
+declare const DEFAULT_ACCENT_SEED = "#3b5e8c";
+/** What {@link mapPaletteToTokens} returns. */
+interface MapResult {
+    /** The light-mode token map — every name in BRAND_EMITTED_TOKENS. */
+    tokens: BrandTokens;
+    /** Fallbacks taken and contrast adjustments made. */
+    warnings: TokenWarning[];
+}
+/**
+ * Maps a palette (+ optional typography) onto the full light-mode
+ * @odla-ai/ui token set. Never throws on bad palettes: invalid swatches are
+ * dropped, missing roles derive from the accent via derivePalette, and every
+ * degradation is recorded as a {@link TokenWarning}.
+ */
+declare function mapPaletteToTokens(input: CompileInput): MapResult;
+
+/** Darkest OKLab L a flipped neutral may take — the dark bg floor (never black). */
+declare const DARK_FLIP_L_MIN = 0.2;
+/** Lightest OKLab L a flipped neutral may take — keeps flipped text off pure white. */
+declare const DARK_FLIP_L_MAX = 0.95;
+/**
+ * Derives the dark-mode token map from a light one (see the file header for
+ * the flip / re-lighten / passthrough rules). Pure and total: tokens the
+ * rules don't recognize — including non-hex values in recognized slots —
+ * pass through unchanged, and the result always has exactly the input's
+ * key set. Deterministic, never throws.
+ */
+declare function deriveDarkTokens(light: BrandTokens): BrandTokens;
+
+/** Options for {@link renderTokensCss}. */
+interface RenderTokensCssOptions {
+    /** Dark-mode tokens (deriveDarkTokens output). Omit for a light-only sheet. */
+    dark?: BrandTokens;
+    /**
+     * Selector the light block declares on (default ":root"). A scoped
+     * selector (e.g. `[data-brand="acme"]`) gets its dark blocks nested under
+     * the document-level theme guards instead of replacing them.
+     */
+    selector?: string;
+    /**
+     * Also emit a `.ui-invert` block carrying the full dark payload, so the
+     * subtree renders dark regardless of the global mode. Requires `dark`.
+     */
+    includeInvert?: boolean;
+}
+/**
+ * Renders a compiled token map (plus optional dark map) as CSS text shaped
+ * like an @odla-ai/ui theme tokens file — see the file header for the block
+ * structure and ordering guarantees. Deterministic for a given input.
+ */
+declare function renderTokensCss(light: BrandTokens, opts?: RenderTokensCssOptions): string;
+
+/**
+ * Compiles a brand palette into @odla-ai/ui design tokens: a light map
+ * covering every name in BRAND_EMITTED_TOKENS (plus overrides), a dark map
+ * derived from it (same key set), and the warnings accumulated along the
+ * way — missing-role fallbacks and contrast adjustments (`adjustedFrom`).
+ *
+ * Both maps double as runtime override-island payloads: every derived
+ * default that composes the accent family is re-declared, so applying the
+ * map on any element recomputes charts, softs, focus and chat roles against
+ * the brand palette (see roles.ts). Deterministic; never throws on bad
+ * palettes.
+ */
+declare function compileBrandTokens(input: CompileInput): CompiledBrandTokens;
+
+export { SWATCH_ROLES as $, type AssetAnalysis as A, type BrandDb as B, type BrandStorage as C, type BrandTokens as D, type BrandTokensSnapshot as E, type BrandUploadBody as F, type CompileInput as G, type CompiledBrandTokens as H, DARK_FLIP_L_MAX as I, DARK_FLIP_L_MIN as J, DEFAULT_ACCENT_SEED as K, type ImagerySection as L, type LogoSection as M, type MapResult as N, PALETTE_STATUSES as O, PALETTE_SOURCES as P, PROPOSAL_KINDS as Q, PROPOSAL_STATUSES as R, type Swatch as S, type PaletteSection as T, type PaletteSource as U, type PaletteStatus as V, type ProposalKind as W, type ProposalStatus as X, type RenderTokensCssOptions as Y, SECTION_KINDS as Z, SECTION_STATUSES as _, type BrandBook as a, type SwatchRole as a0, type TokenWarning as a1, type TypographySection as a2, type VoiceSection as a3, compileBrandTokens as a4, deriveDarkTokens as a5, mapPaletteToTokens as a6, renderTokensCss as a7, type BrandOp as b, type BrandEntityRef as c, type SectionKind as d, type SectionStatus as e, type BrandProposal as f, type AssetKind as g, type BrandActor as h, ASSET_KINDS as i, BOOK_STATUSES as j, BRAND_CHART_TOKENS as k, BRAND_CHAT_TOKENS as l, BRAND_DERIVED_TOKENS as m, BRAND_EMITTED_TOKENS as n, BRAND_NS as o, BRAND_REQUIRED_TOKENS as p, type BookStatus as q, type BrandAsset as r, type BrandAttrs as s, type BrandFileRecord as t, type BrandLookup as u, type BrandPalette as v, type BrandResult as w, type BrandRow as x, type BrandScalar as y, type BrandSection as z };

package/dist/index.cjs

@@ -18,8 +18,8 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var index_exports = {};
-__export(index_exports, {
+var src_exports = {};
+__export(src_exports, {
   ASSET_CONTENT_TYPES: () => ASSET_CONTENT_TYPES,
   ASSET_KINDS: () => ASSET_KINDS,
   BOOK_STATUSES: () => BOOK_STATUSES,
@@ -130,7 +130,7 @@ __export(index_exports, {
   updateBookOps: () => updateBookOps,
   upsertSectionOps: () => upsertSectionOps
 });
-module.exports = __toCommonJS(index_exports);
+module.exports = __toCommonJS(src_exports);
 
 // src/constants.ts
 var BRAND_NS = {