@odla-ai/brand 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1342 @@
+import { ToolHandler, Skill, ToolDef, Persona, Inference, AgentRunInput, ImageBlock, OracleContentBlock } from '@odla-ai/ai';
+
+/** 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;
+}
+
+/** Caller-fault error (bad hex, oversized payload, blocked transition…) — the
+ * route layer maps it to a 400. `fields` carries per-field messages when the
+ * failure came from input validation. */
+declare class BrandInputError extends Error {
+    readonly fields?: Record<string, string>;
+    constructor(message: string, fields?: Record<string, string>);
+}
+/** Missing entity — the route layer maps it to a 404. */
+declare class BrandNotFoundError extends Error {
+    constructor(what: string);
+}
+
+/** What `fetchBytes` resolves to: raw bytes plus the served content type. */
+interface BrandFetchedBytes {
+    bytes: Uint8Array;
+    contentType: string;
+}
+/** What every brand operation needs: the injected db, plus test overrides. */
+interface BrandDeps {
+    db: BrandDb;
+    /** Clock override (default `Date.now`). */
+    now?: () => number;
+    /** Id factory override (default `crypto.randomUUID`). */
+    newId?: () => string;
+    /** Asset-byte fetcher override (default: global `fetch`). */
+    fetchBytes?: (url: string) => Promise<BrandFetchedBytes>;
+}
+/** {@link BrandDeps} with the injectable defaults filled in. */
+interface ResolvedBrandDeps {
+    db: BrandDb;
+    now: () => number;
+    newId: () => string;
+    fetchBytes: (url: string) => Promise<BrandFetchedBytes>;
+}
+/** Fill the injectable defaults. */
+declare function resolveDeps(deps: BrandDeps): ResolvedBrandDeps;
+
+/** Wire-shape attribute value kinds odla-db stores. */
+type AttrType = "string" | "number" | "boolean" | "date" | "json";
+/** One serialized attribute: its type and index/uniqueness flags. */
+interface SerializedAttr {
+    type: AttrType;
+    unique: boolean;
+    indexed: boolean;
+    optional: boolean;
+}
+/** One serialized namespace: its attribute map. */
+interface SerializedEntity {
+    attrs: Record<string, SerializedAttr>;
+}
+/** One end of a serialized schema link. */
+interface SerializedLinkEnd {
+    on: string;
+    has: "one" | "many";
+    label: string;
+}
+/** A serialized schema link (unused by brand — audiences are denormalized). */
+interface SerializedLink {
+    forward: SerializedLinkEnd;
+    reverse: SerializedLinkEnd;
+}
+/** The wire-shape schema POSTed to `/app/:id/schema`. */
+interface SerializedSchema {
+    entities: Record<string, SerializedEntity>;
+    links: Record<string, SerializedLink>;
+}
+/**
+ * The pre-serialized (wire-shape) odla-db schema for the five brand
+ * namespaces; POST it to `/app/:id/schema` as `{ schema: BRAND_SCHEMA }`.
+ * Natural keys (`book.slug`, `section.key`) make provisioning and section
+ * upserts idempotent; mirrored `id` attrs make rows addressable by
+ * `where: { id }`.
+ */
+declare const BRAND_SCHEMA: SerializedSchema;
+
+/** Per-namespace CEL rule strings (missing action = deny). */
+interface BrandRule {
+    view?: string;
+    create?: string;
+    update?: string;
+    delete?: string;
+}
+/** Namespace → rule set, as installed at `/app/:id/admin/rules`. */
+type BrandRules = Record<string, BrandRule>;
+/**
+ * Default-deny CEL rules for the five brand namespaces; install at
+ * `/app/:id/admin/rules`. Books gate on the `memberIds` roster (owner-only
+ * writes); sections/palettes/proposals gate on their denormalized `audience`
+ * and are never client-deletable (archive via `status` instead); assets are
+ * fully worker-mediated. Use {@link brandRules} for a per-install copy.
+ */
+declare const BRAND_RULES: BrandRules;
+/**
+ * Rules factory, mirroring `chatRules()`/`crmRules()`. Today it returns a
+ * fresh copy of {@link BRAND_RULES}; it exists so a future option (e.g.
+ * locking views to an org email domain) can widen or tighten namespaces
+ * without apps changing their provisioning call shape.
+ */
+declare function brandRules(): BrandRules;
+
+/** Most swatches a single palette may carry. */
+declare const MAX_SWATCHES = 24;
+/** Upload content types the asset pipeline accepts. */
+declare const ASSET_CONTENT_TYPES: ReadonlySet<string>;
+/**
+ * Assert `value` is a `#rgb`/`#rrggbb` hex color and normalize it to
+ * lowercase `#rrggbb`. Alpha channels (`#rgba`/`#rrggbbaa`) and every other
+ * color syntax are rejected — tokens and contrast math are defined on opaque
+ * sRGB hex.
+ */
+declare function assertHex(value: unknown, label?: string): string;
+/** Assert a trimmed non-empty string of at most `max` characters. */
+declare function capString(value: unknown, label: string, max: number): string;
+/** Assert an array of capped strings (each trimmed and non-empty). */
+declare function capStringArray(value: unknown, label: string, opts: {
+    maxItems: number;
+    maxLen: number;
+    minItems?: number;
+}): string[];
+/**
+ * Assert a swatch list: 1–{@link MAX_SWATCHES} entries, each with a known
+ * role, a valid hex (normalized), and capped optional name/rationale.
+ * Returns the normalized copy — write THAT, never the raw input.
+ */
+declare function assertSwatches(value: unknown): Swatch[];
+/**
+ * Validate + normalize a section's `content` payload for its kind. Returns
+ * the normalized content to write; throws {@link BrandInputError} on an
+ * unknown kind or an invalid payload.
+ */
+declare function assertSectionContent(kind: string, content: unknown): Record<string, unknown>;
+/**
+ * Sanitize an upload's file name for use in an R2 key: strips path
+ * separators, control characters, and leading dots, then caps at 120
+ * characters. Throws when nothing survives sanitizing.
+ */
+declare function safeFileName(name: unknown): string;
+/**
+ * Assert an upload content type is on the {@link ASSET_CONTENT_TYPES}
+ * allowlist. Normalizes case and strips parameters (`; charset=…`) before
+ * checking; returns the normalized bare type.
+ */
+declare function assertAssetContentType(value: unknown): string;
+/**
+ * Validate + normalize an agent's asset analysis: description ≤ 2000 chars,
+ * ≤ 12 dominant colors (each normalized hex), ≤ 24 tags of ≤ 60 chars.
+ */
+declare function assertAnalysis(value: unknown): AssetAnalysis;
+
+/** Input to {@link createBookOps}. `memberIds` is the full auth roster —
+ * include the bot agent's id so it can pass the audience rules. */
+interface CreateBookInput {
+    id: string;
+    slug: string;
+    name: string;
+    ownerId: string;
+    memberIds: string[];
+    channelId?: string;
+    now: number;
+}
+/**
+ * Ops to create a brand book: one `brand_book` row in `draft` status with the
+ * id mirrored as an attr (odla-db ids aren't attrs), the owner always folded
+ * into the deduplicated `memberIds` roster (the create rule requires it), and
+ * both timestamps set to `now`.
+ */
+declare function createBookOps(input: CreateBookInput): BrandOp[];
+/**
+ * Ops to patch a brand book. `null` means CLEAR (a `retract` op — odla-db has
+ * no storable scalar null) and is only allowed on optional columns;
+ * `undefined` keys are dropped. Any write stamps `updatedAt`; an empty
+ * effective patch emits no ops at all.
+ */
+declare function updateBookOps(bookId: BrandEntityRef, patch: Record<string, unknown>, now: number): BrandOp[];
+/** The child rows whose `audience` snapshots a roster change must rewrite.
+ * Pass the rows you queried — the builder stays pure. */
+interface AudienceChildren {
+    sections?: Array<{
+        id: string;
+    }>;
+    palettes?: Array<{
+        id: string;
+    }>;
+    proposals?: Array<{
+        id: string;
+    }>;
+    assets?: Array<{
+        id: string;
+    }>;
+}
+/**
+ * Ops to change a book's roster: rewrite `memberIds` (owner always kept) and
+ * fan the new list out to every child row's denormalized `audience` snapshot.
+ * Query the children first and pass them in — this builder does no I/O, so
+ * tests can assert the exact fan-out.
+ */
+declare function audienceFanoutOps(book: Pick<BrandBook, "id" | "ownerId">, newMemberIds: string[], children: AudienceChildren, now: number): BrandOp[];
+
+/** The natural key a section row is upserted by: `${bookId}:${kind}`. */
+declare function sectionKey(bookId: string, kind: SectionKind): string;
+/** Input to {@link upsertSectionOps}. `audience` is the book's roster
+ * snapshot; `status` defaults to `draft` (a human approves later). */
+interface UpsertSectionInput {
+    bookId: string;
+    kind: SectionKind;
+    content: Record<string, unknown>;
+    status?: SectionStatus;
+    audience: string[];
+    updatedBy: string;
+    now: number;
+}
+/**
+ * Ops to create-or-replace a book's section of one kind: a single `update`
+ * addressed by the `{ ns, attr: "key", value }` Lookup ref, carrying the
+ * validated + normalized content (see `assertSectionContent`), the audience
+ * snapshot, and the author/timestamp.
+ */
+declare function upsertSectionOps(input: UpsertSectionInput): BrandOp[];
+
+/** Input to {@link proposePaletteOps}. `audience` is the book's roster
+ * snapshot; `contrastReport` is stored verbatim in the payload for the
+ * human reviewer. */
+interface ProposePaletteInput {
+    id: string;
+    bookId: string;
+    name: string;
+    rationale: string;
+    swatches: unknown;
+    seedHex?: string;
+    contrastReport?: unknown;
+    createdBy: string;
+    audience: string[];
+    sourceAssetId?: string;
+    messageId?: string;
+    now: number;
+}
+/**
+ * Ops to park a palette proposal for human review: one `brand_proposal` row,
+ * `kind: "palette"`, `status: "open"`, with the validated swatches (and
+ * optional seed/contrast report) in `payload`.
+ */
+declare function proposePaletteOps(input: ProposePaletteInput): BrandOp[];
+/** Input to {@link acceptProposalOps}: the proposal row as read back, the id
+ * to mint the palette under, and who resolved it. */
+interface AcceptProposalInput {
+    proposal: BrandProposal;
+    paletteId: string;
+    resolvedBy: string;
+    now: number;
+    resolutionNote?: string;
+}
+/**
+ * Ops to accept an OPEN palette proposal, all in one transact:
+ * 1. the `brand_palette` row (source: `extracted` when the proposal came from
+ *    an asset, `derived` when seeded, else `manual`),
+ * 2. the approved `palette` section upsert,
+ * 3. the book's `activePaletteId` pointer,
+ * 4. the proposal flipped to `accepted` with resolver + timestamp.
+ * Throws on a non-palette or already-resolved proposal, or a payload that no
+ * longer validates.
+ */
+declare function acceptProposalOps(input: AcceptProposalInput): BrandOp[];
+/** Input to {@link rejectProposalOps}. */
+interface RejectProposalInput {
+    proposal: BrandProposal;
+    resolvedBy: string;
+    now: number;
+    resolutionNote?: string;
+}
+/**
+ * Ops to reject an OPEN proposal (any kind): flip it to `rejected` with
+ * resolver, timestamp, and the optional note. Nothing else is touched — the
+ * proposal row itself is the audit trail.
+ */
+declare function rejectProposalOps(input: RejectProposalInput): BrandOp[];
+
+/** Input to {@link createAssetOps} — the storage upload's receipt fields
+ * (`path`/`url`/`size`) plus the declared kind and the book's audience. */
+interface CreateAssetInput {
+    id: string;
+    bookId: string;
+    kind: AssetKind;
+    path: string;
+    url: string;
+    contentType: string;
+    size: number;
+    uploadedBy: string;
+    audience: string[];
+    title?: string;
+    now: number;
+}
+/**
+ * Ops to record one uploaded asset: a single `brand_asset` row mirroring the
+ * storage object, with the content type re-checked against the allowlist and
+ * the size required to be a positive byte count.
+ */
+declare function createAssetOps(input: CreateAssetInput): BrandOp[];
+/**
+ * Ops to tombstone an asset after its storage object was deleted: stamp
+ * `deletedAt` in place. List reads exclude tombstoned rows; the row itself
+ * stays for provenance.
+ */
+declare function tombstoneAssetOps(assetId: BrandEntityRef, now: number): BrandOp[];
+/**
+ * Ops to record an agent's analysis of an asset: the validated + capped
+ * analysis json plus `analyzedAt`. Replaces any prior analysis whole.
+ */
+declare function recordAnalysisOps(assetId: BrandEntityRef, analysis: unknown, now: number): BrandOp[];
+
+/** An sRGB color with channels as fractions in [0, 1]. */
+interface Rgb {
+    /** Red channel, 0..1. */
+    r: number;
+    /** Green channel, 0..1. */
+    g: number;
+    /** Blue channel, 0..1. */
+    b: number;
+}
+/** Clamps a number into [0, 1]; NaN clamps to 0. */
+declare function clamp01(x: number): number;
+/**
+ * Parses `#rgb` or `#rrggbb` (case-insensitive) into channel fractions.
+ *
+ * @throws RangeError for anything else — named colors, missing `#`, wrong
+ * digit counts; alpha forms (`#rgba`/`#rrggbbaa`) get a dedicated message.
+ */
+declare function parseHex(hex: string): Rgb;
+/** Formats channel fractions as lowercase `#rrggbb`, clamping each into [0, 1]. */
+declare function toHex(rgb: Rgb): string;
+/** Normalizes any accepted hex form to lowercase `#rrggbb` (throws like parseHex). */
+declare function normalizeHex(hex: string): string;
+
+/** A color in HSL: hue in degrees [0, 360), saturation and lightness 0..1. */
+interface Hsl {
+    /** Hue angle in degrees, [0, 360); 0 when achromatic. */
+    h: number;
+    /** Saturation, 0..1. */
+    s: number;
+    /** Lightness, 0..1. */
+    l: number;
+}
+/** A color in OKLab: L 0..1, a/b roughly within ±0.4 for sRGB colors. */
+interface Oklab {
+    /** Perceived lightness, 0..1. */
+    L: number;
+    /** Green–red axis. */
+    a: number;
+    /** Blue–yellow axis. */
+    b: number;
+}
+/** A color in OKLCH — OKLab in polar form. */
+interface Oklch {
+    /** Perceived lightness, 0..1. */
+    L: number;
+    /** Chroma (radius in the a/b plane), ≥ 0. */
+    C: number;
+    /** Hue angle in degrees, [0, 360); 0 when achromatic. */
+    h: number;
+}
+/** IEC 61966-2-1 sRGB decoding: gamma-encoded channel → linear-light, both 0..1. */
+declare function srgbToLinear(c: number): number;
+/** IEC 61966-2-1 sRGB encoding: linear-light channel → gamma-encoded, both 0..1. */
+declare function linearToSrgb(c: number): number;
+/** Converts sRGB channel fractions to HSL (CSS Color 4 § 7). */
+declare function rgbToHsl({ r, g, b }: Rgb): Hsl;
+/** Converts HSL to sRGB channel fractions (CSS Color 4 § 7; any hue angle accepted). */
+declare function hslToRgb({ h, s, l }: Hsl): Rgb;
+/** Converts gamma-encoded sRGB to OKLab (Ottosson M1 → cbrt → M2). */
+declare function rgbToOklab({ r, g, b }: Rgb): Oklab;
+/**
+ * Converts OKLab to gamma-encoded sRGB (Ottosson's inverse matrices).
+ * Out-of-gamut inputs yield channels outside [0, 1] — feed the OKLCH form
+ * through {@link clampToGamut} first when hue fidelity matters (toHex would
+ * clip per channel, which distorts hue).
+ */
+declare function oklabToRgb({ L, a, b }: Oklab): Rgb;
+/** OKLab → OKLCH (polar form). Hue is 0 for achromatic colors (C ≈ 0). */
+declare function oklabToOklch({ L, a, b }: Oklab): Oklch;
+/** OKLCH → OKLab (rectangular form). */
+declare function oklchToOklab({ L, C, h }: Oklch): Oklab;
+/** Convenience: hex → OKLCH (throws like parseHex on bad input). */
+declare function hexToOklch(hex: string): Oklch;
+/**
+ * Convenience: OKLCH → lowercase `#rrggbb`. Out-of-gamut input is clipped
+ * per channel by toHex; call {@link clampToGamut} first to reduce chroma
+ * instead (preserving hue) when the input may be out of gamut.
+ */
+declare function oklchToHex(lch: Oklch): string;
+/** True when every sRGB channel is within [0, 1] (tiny epsilon for float noise). */
+declare function inSrgbGamut({ r, g, b }: Rgb): boolean;
+/**
+ * Brings an OKLCH color into the sRGB gamut by reducing chroma only —
+ * lightness and hue are preserved exactly (binary search, 24 iterations,
+ * chroma precision well under one 8-bit quantum). L is clamped into [0, 1]
+ * first; C = 0 (a pure gray) is always representable, so the search always
+ * lands in gamut.
+ */
+declare function clampToGamut(lch: Oklch): Oklch;
+
+/** Contrast contexts with distinct WCAG thresholds. */
+type ContrastKind = "text" | "large-text" | "ui";
+/** WCAG 2.1 relative luminance of a hex color: 0 = black, 1 = white. */
+declare function relativeLuminance(hex: string): number;
+/** WCAG 2.1 contrast ratio between two hex colors, in [1, 21]; order-independent. */
+declare function contrastRatio(hexA: string, hexB: string): number;
+/**
+ * WCAG 2.1 level-AA check for a contrast ratio: 4.5:1 for body text
+ * (SC 1.4.3), 3:1 for large text, 3:1 for UI components and graphical
+ * objects (SC 1.4.11).
+ */
+declare function meetsAA(ratio: number, kind?: ContrastKind): boolean;
+/**
+ * WCAG 2.1 level-AAA check for a contrast ratio (SC 1.4.6): 7:1 for body
+ * text, 4.5:1 for large text. WCAG defines no AAA bar for non-text UI, so
+ * "ui" is not an accepted kind here.
+ */
+declare function meetsAAA(ratio: number, kind?: Exclude<ContrastKind, "ui">): boolean;
+/**
+ * Default {@link pickTextOn} candidates: white and a near-black chosen so
+ * that the better of the two clears 4.5:1 against ANY background. The worst
+ * case is a mid-gray backdrop (luminance ≈ 0.18), where this pair still
+ * yields ≈ 4.51:1; a softer near-black (e.g. #111111) would drop that floor
+ * below 4.5.
+ */
+declare const PICK_TEXT_DEFAULT_CANDIDATES: readonly string[];
+/**
+ * Picks the candidate with the highest contrast ratio against `bgHex`
+ * (earliest candidate wins ties). With the default candidates the winner is
+ * always ≥ 4.5:1 — see {@link PICK_TEXT_DEFAULT_CANDIDATES}.
+ *
+ * @throws RangeError when `candidates` is empty.
+ */
+declare function pickTextOn(bgHex: string, candidates?: readonly string[]): string;
+
+/**
+ * Rotates a color's OKLCH hue by `degrees` (any sign/magnitude), keeping
+ * lightness and chroma constant, then chroma-clamps into sRGB. Rotating an
+ * achromatic color is a no-op up to 8-bit rounding (its chroma is ~0).
+ */
+declare function rotateHue(hex: string, degrees: number): string;
+/** The 180° opposite on the OKLCH hue wheel. */
+declare function complementary(hex: string): string;
+/** The two neighbors at ±`angle` (default 30°), as [minus, plus]. */
+declare function analogous(hex: string, angle?: number): [string, string];
+/** The two colors completing an equilateral triad (±120°), as [minus, plus]. */
+declare function triadic(hex: string): [string, string];
+/** The two colors flanking the complement (±150°), as [minus, plus]. */
+declare function splitComplementary(hex: string): [string, string];
+/** The three colors completing a square (+90°, +180°, +270°). */
+declare function tetradic(hex: string): [string, string, string];
+/**
+ * A monochrome chroma scale: `steps` colors at the seed's lightness and hue,
+ * fading chroma linearly from the seed's own chroma down to 0 (a pure gray).
+ * The first entry is the seed itself (normalized).
+ *
+ * @throws RangeError when `steps` is not an integer ≥ 2.
+ */
+declare function monochrome(hex: string, steps?: number): string[];
+
+/** Lightest OKLab L emitted by {@link tintShadeRamp} (first step). */
+declare const RAMP_L_MAX = 0.96;
+/** Darkest OKLab L emitted by {@link tintShadeRamp} (last step). */
+declare const RAMP_L_MIN = 0.27;
+/**
+ * A light-to-dark ramp of `steps` colors (default 9) built from the seed's
+ * hue and chroma: OKLab lightness runs linearly from {@link RAMP_L_MAX} down
+ * to {@link RAMP_L_MIN}, and chroma tapers from 100% of the seed's chroma at
+ * mid-ramp to 25% at both ends (then gamut-clamps, preserving hue).
+ *
+ * @throws RangeError when `steps` is not an integer ≥ 2.
+ */
+declare function tintShadeRamp(hex: string, steps?: number): string[];
+/** Direction {@link adjustLightnessUntil} may move lightness. */
+type LightnessDirection = "lighten" | "darken";
+/**
+ * Moves a color's OKLCH lightness toward white ("lighten") or black
+ * ("darken") until `predicate(hex)` holds, returning the passing color
+ * nearest the input (chroma and hue constant, gamut-clamped per step).
+ *
+ * Returns the input itself (normalized) when it already passes, and null
+ * when no lightness in that direction satisfies the predicate. Work is
+ * bounded: a 16-step coarse scan plus 22 bisection rounds. The predicate is
+ * always evaluated on exact 8-bit hex strings, including the returned one.
+ */
+declare function adjustLightnessUntil(hex: string, predicate: (hex: string) => boolean, direction: LightnessDirection): string | null;
+
+/** Euclidean distance between two OKLab coordinates (CSS Color 4 ΔEOK). */
+declare function deltaEOKLab(x: Oklab, y: Oklab): number;
+/**
+ * ΔEOK between two hex colors. 0 = identical; ~0.02 ≈ one just-noticeable
+ * difference; white ↔ black = 1. Symmetric in its arguments.
+ *
+ * @throws RangeError on malformed hex (see parseHex).
+ */
+declare function deltaEOK(hexA: string, hexB: string): number;
+
+/** One CSS named color: the keyword and its spec hex value. */
+interface NamedColor {
+    /** The CSS keyword, e.g. "rebeccapurple". */
+    name: string;
+    /** The spec's `#rrggbb` value, lowercase. */
+    hex: string;
+}
+/**
+ * All 148 CSS named colors in alphabetical order. Aliases (aqua/cyan,
+ * fuchsia/magenta, the gray/grey pairs) are separate entries sharing a hex.
+ */
+declare const CSS_NAMED_COLORS: readonly NamedColor[];
+/** A nearest-name match: the keyword, its spec hex, and the ΔEOK distance. */
+interface NearestNamedColor extends NamedColor {
+    /** ΔEOK from the query color to this named color (0 = exact hit). */
+    deltaEOK: number;
+}
+/**
+ * The CSS named color perceptually closest to `hex`, by ΔEOK in OKLab.
+ * Exact hits return distance 0. Ties — including shared-hex aliases like
+ * aqua/cyan — go to the alphabetically first keyword. As a rough guide,
+ * distances ≲ 0.02 are visually indistinguishable and ≳ 0.1 is only a loose
+ * "same family" match.
+ *
+ * @throws RangeError on malformed hex (see parseHex).
+ */
+declare function nearestNamedColor(hex: string): NearestNamedColor;
+
+/**
+ * Documented floor for pairwise ΔEOK between derived chart colors. The
+ * default chart constants guarantee it by construction (see file header);
+ * deriveChartColors also enforces it as a filter.
+ */
+declare const CHART_DELTA_MIN = 0.1;
+/** Options for {@link deriveChartColors}. */
+interface DeriveChartOptions {
+    /** How many colors to return, 1..12 (default 6). */
+    count?: number;
+    /** Pairwise ΔEOK floor (default {@link CHART_DELTA_MIN}). Best-effort above the default. */
+    deltaMin?: number;
+}
+/**
+ * Derives categorical chart colors from a seed: hue rotations (60° grid,
+ * then 30° offsets) around the seed's hue at a constant, gamut-safe
+ * lightness/chroma. Candidates are kept only if they stay at least
+ * `deltaMin` ΔEOK from every accepted color; if the requested floor is
+ * unattainable for `count` colors, remaining distinct candidates fill the
+ * set in hue order so callers always get `count` colors back.
+ *
+ * @throws RangeError when `count` is not an integer in 1..12, or on
+ * malformed hex.
+ */
+declare function deriveChartColors(seedHex: string, opts?: DeriveChartOptions): string[];
+/** Options for {@link derivePalette}. */
+interface DerivePaletteOptions {
+    /** Attach nearest-CSS-keyword `name`s to every swatch (default true). */
+    names?: boolean;
+}
+/**
+ * Derives a complete brand palette from one seed color: one swatch each for
+ * primary, secondary, highlight, good, warn, danger, bg, surface, text and
+ * neutral, plus six chart swatches (16 total) — see the file header for the
+ * derivation strategy and its WCAG guarantees.
+ *
+ * @throws RangeError on malformed seed hex (see parseHex).
+ */
+declare function derivePalette(seedHex: string, opts?: DerivePaletteOptions): Swatch[];
+
+/**
+ * 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;
+
+/** The bot identity the skill writes as (`selfId` = the agent id carried in
+ * the book's `memberIds` roster and every audience snapshot). */
+interface BrandSkillSelf {
+    selfId: string;
+    kind: "bot";
+    displayName?: string;
+}
+/** Options for {@link brandSkill}. */
+interface BrandSkillOpts {
+    /** The injected odla client (a real @odla-ai/db AdminDb satisfies it). */
+    db: BrandDb;
+    /** The one brand book this skill instance is scoped to. */
+    bookId: string;
+    /** The bot identity acting through these tools. */
+    self: BrandSkillSelf;
+    /** Origin prefixed onto relative asset urls (`url` starting with `/`). */
+    fileBaseUrl: string;
+    /** Asset-byte fetcher override (default: global fetch via resolveDeps). */
+    fetchBytes?: (url: string) => Promise<BrandFetchedBytes>;
+    /** False when the model cannot take image/document blocks inside a
+     * tool_result — view_asset then steers to the pre-turn attachment path. */
+    visionInToolResults?: boolean;
+    /** Clock override (tests). */
+    now?: () => number;
+    /** Id factory override (tests). */
+    newId?: () => string;
+}
+/** The resolved context every brand tool module builds its tools from. */
+interface BrandToolCtx {
+    db: BrandDb;
+    bookId: string;
+    self: BrandSkillSelf;
+    fileBaseUrl: string;
+    fetchBytes: (url: string) => Promise<BrandFetchedBytes>;
+    /** Whether image/document blocks may be returned inside tool results. */
+    visionInToolResults: boolean;
+    now: () => number;
+    newId: () => string;
+    /** Load the scoped book row; throws BrandNotFoundError when missing. */
+    loadBook(): Promise<BrandBook>;
+    /** Wrap a handler so Brand validation errors come back as actionable
+     * error text instead of the loop's sanitized generic failure. */
+    guard(handler: ToolHandler): ToolHandler;
+}
+/** Workflow guidance appended to the persona's system prompt as the skill's
+ * instruction section. */
+declare const BRAND_INSTRUCTIONS: string;
+/**
+ * Build the brand Skill: read/asset/palette/book tools scoped to one book,
+ * acting as one bot identity, plus {@link BRAND_INSTRUCTIONS}. Attach it to
+ * a Persona (or use `createBrandPersona`).
+ */
+declare function brandSkill(opts: BrandSkillOpts): Skill;
+
+/** Byte cap for in-conversation asset viewing (4.5 MiB — providers reject
+ * larger inline payloads well before context does). */
+declare const MAX_VIEW_BYTES = 4718592;
+/**
+ * Base64-encode bytes without assuming a platform: `btoa` over a chunked
+ * binary string where available (workerd, browsers, Node ≥ 16), `Buffer`
+ * otherwise. Chunking keeps `String.fromCharCode` off the argument-count
+ * cliff for multi-megabyte assets.
+ */
+declare function base64FromBytes(bytes: Uint8Array): string;
+/**
+ * The asset tools, scoped to the context's book: `view_asset` (fetch the
+ * stored bytes and return them as an image/PDF block, with size and type
+ * gates) and `record_asset_analysis` (persist the model's description,
+ * dominant colors, and tags onto the asset row).
+ */
+declare function assetTools(ctx: BrandToolCtx): ToolDef[];
+
+/**
+ * The book tools: `update_section` (validated per-kind content, upserted by
+ * natural key with the book's audience snapshot) and `compile_tokens`
+ * (palette + typography → light/dark token cache on the book row).
+ */
+declare function bookTools(ctx: BrandToolCtx): ToolDef[];
+
+/**
+ * The palette tools: `analyze_color`, `evaluate_contrast` (pure math),
+ * `propose_palette` (writes an OPEN proposal with an automatic contrast
+ * report), and `resolve_proposal` (applies the human's explicit verdict).
+ */
+declare function paletteTools(ctx: BrandToolCtx): ToolDef[];
+
+/** The default brand-director system prompt (override via `system`). */
+declare const DEFAULT_BRAND_SYSTEM: string;
+/** Options for {@link createBrandPersona}. */
+interface CreateBrandPersonaOpts {
+    /** Canonical model id the persona runs on. */
+    model: string;
+    /** System prompt override (default {@link DEFAULT_BRAND_SYSTEM}). */
+    system?: string;
+    /** Provider web-search server tool (default true — brand research). */
+    webSearch?: boolean;
+    /** Max model turns per run (default 10 — the workflow is multi-step). */
+    maxSteps?: number;
+    /** Extra skills appended after the brand skill (e.g. a chat skill). */
+    skills?: Skill[];
+    /** Options for the attached {@link brandSkill}. */
+    brand: BrandSkillOpts;
+}
+/** Build the brand-director Persona: {@link brandSkill} first, extra skills
+ * after, defaults per the option JSDoc above. */
+declare function createBrandPersona(opts: CreateBrandPersonaOpts): Persona;
+/** The capability flags {@link supportsBrandVision} inspects. */
+interface BrandVisionCapabilities {
+    toolResultBlocks?: boolean;
+    imageIn?: boolean;
+    documentIn?: boolean;
+}
+/** The (structural) slice of an @odla-ai/ai ModelSpec the probe reads. */
+interface BrandVisionSpec {
+    capabilities?: BrandVisionCapabilities;
+}
+/**
+ * Whether a model can view assets THROUGH view_asset — i.e. take image and
+ * document blocks inside tool results. Pure capabilities-metadata check
+ * (`toolResultBlocks && imageIn && documentIn`), never provider names; when
+ * false, hosts attach asset bytes as pre-turn input blocks instead and pass
+ * `visionInToolResults: false` to the skill.
+ */
+declare function supportsBrandVision(spec: BrandVisionSpec | null | undefined): boolean;
+
+/**
+ * The two read-only tools, scoped to the context's book:
+ * `read_brand_book` (book + sections + palettes + open proposals as compact
+ * text) and `list_assets` (live, non-tombstoned asset rows, optionally
+ * filtered by kind).
+ */
+declare function readTools(ctx: BrandToolCtx): ToolDef[];
+
+/** Everything {@link import("./index").createBrandRoutes} needs from the host worker. */
+interface BrandRouteOpts {
+    /** The injected odla client (a real @odla-ai/db AdminDb satisfies it). */
+    db: BrandDb;
+    /** Host-owned auth: resolve the request to an actor or null (→ 401). The
+     * tokens routes skip this only when `publicTokens` is true. */
+    authorize: (req: Request) => Promise<BrandActor | null> | BrandActor | null;
+    /** Mount point. Default "/api/brand". */
+    basePath?: string;
+    /** Upload size cap in bytes (checked against `File.size`). Default 8 MiB. */
+    maxUploadBytes?: number;
+    /** Serve `GET /books/:id/tokens.css` and `tokens.json` without authorize —
+     * compiled tokens only; every other route always authorizes. Default false. */
+    publicTokens?: boolean;
+    /** Injectable clock (tests). Default `Date.now`. */
+    now?: () => number;
+    /** Injectable id factory (tests). Default `crypto.randomUUID`. */
+    newId?: () => string;
+}
+/** Per-request context handed to the authorized route handlers. */
+interface BrandRouteCtx {
+    db: BrandDb;
+    actor: BrandActor;
+    now: () => number;
+    newId: () => string;
+    maxUploadBytes: number;
+}
+
+/**
+ * Build the brand fetch handler. Returns `null` for requests outside
+ * `basePath` (default `/api/brand`) so the host worker falls through to its
+ * own routes; inside it, every route requires `authorize` to resolve an
+ * actor (401 otherwise) EXCEPT the two tokens routes when `publicTokens` is
+ * true — compiled tokens are the one intentionally publishable surface.
+ * Domain errors map to 400/404 JSON; anything unexpected is an opaque 500.
+ */
+declare function createBrandRoutes(options: BrandRouteOpts): (req: Request) => Promise<Response | null>;
+
+/** The dispatch envelope odla-db's commit hook POSTs when a trigger fires —
+ * the same wire shape chat-agent consumes (see the header provenance note). */
+interface BrandDispatchBody {
+    v: number;
+    appId: string;
+    trigger: {
+        id: string;
+        skill: string;
+        runAs: {
+            agentId: string;
+            persona: string;
+        };
+        maxDepth?: number;
+    };
+    event: {
+        ns: string;
+        id: string;
+        row: Record<string, unknown>;
+    };
+}
+/**
+ * Validate an untrusted dispatch body; null if malformed. SHAPE-only,
+ * mirroring chat-agent's parseDispatch: it does NOT gate on `trigger.skill` —
+ * routing on skill is the HOST's job (a worker serving several skills checks
+ * `body.trigger.skill === "brand"` before calling {@link dispatchBrandTurn}),
+ * so an absent skill parses as `""`, never silently defaulted to "brand".
+ */
+declare function parseBrandDispatch(raw: unknown): BrandDispatchBody | null;
+/** The brand book bound to a chat channel (`brand_book.channelId`), or null
+ * when the channel id is empty or no book claims it. */
+declare function bookForChannel(db: BrandDb, channelId: string): Promise<BrandBook | null>;
+/**
+ * The agent-turn input for a dispatched message: a brand-flavored prompt
+ * (mirrors chat-agent's `inputFor` tone, steering into the brand workflow),
+ * and — when pre-turn `attachments` are supplied (the no-vision-in-tool-
+ * results path) — an explicit block array with the images BEFORE the text.
+ */
+declare function brandInputFor(body: BrandDispatchBody, attachments?: ImageBlock[]): string | OracleContentBlock[];
+/** Everything {@link dispatchBrandTurn} needs from the host worker. The
+ * @odla-ai/ai pieces (`inference`, `runAgent`) are injected so this module
+ * keeps the package's types-only relationship with the peer. */
+interface BrandDispatchDeps {
+    /** The injected odla client (a real @odla-ai/db AdminDb satisfies it). */
+    db: BrandDb;
+    /** The @odla-ai/ai inference facade the turn runs on. */
+    inference: Inference;
+    /** Canonical model id for the persona. */
+    model: string;
+    /** The agent loop — pass @odla-ai/ai's `runAgent`. */
+    runAgent: (inference: Inference, persona: Persona, input: AgentRunInput) => Promise<{
+        finalText: string;
+    }>;
+    /** Origin prefixed onto relative asset urls (skill + pre-turn attachments). */
+    fileBaseUrl: string;
+    /** Optional chat-skill factory (e.g. wrapping @odla-ai/chat's chatSkill) so
+     * the bot can reply in the triggering channel. */
+    chatSkillFor?: (channelId: string, self: BrandSkillSelf) => Skill;
+    /** Model catalog slice (model id → capability spec) for the vision probe;
+     * an absent catalog or unknown model fails safe to the pre-turn path. */
+    catalog?: Record<string, BrandVisionSpec>;
+}
+/**
+ * Run one brand-agent turn for a dispatched chat message: resolve the book
+ * via the row's `channelId` (throws {@link BrandNotFoundError} when no book
+ * claims the channel), probe `supportsBrandVision(catalog[model])`, build the
+ * persona (brand skill + optional chat skill, bot identity from
+ * `trigger.runAs`), and run the loop. When the model can NOT take blocks in
+ * tool results, assets are attached PRE-TURN as URL image blocks — v1 keeps
+ * detection simple: only when the message row carries an `assetIds` array
+ * (no body-text scraping), and only live image assets.
+ */
+declare function dispatchBrandTurn(deps: BrandDispatchDeps, body: BrandDispatchBody): Promise<{
+    finalText: string;
+}>;
+
+/** The odla-db namespace chat messages live in.
+ * PROVENANCE: @odla-ai/chat `CHAT_NS.message` (packages/chat/src/constants.ts)
+ * — duplicated as a local const because this package is zero-dep and the wire
+ * value is a stable contract, not an implementation detail. */
+declare const CHAT_MESSAGE_NS = "chat_message";
+/** Matches @odla/server's `Trigger` (the exact JSON POSTed to
+ * `/app/:id/admin/triggers`) — the same wire shape as chat's `ChatTrigger`. */
+interface BrandTrigger {
+    id: string;
+    watch: {
+        ns: string;
+        on: "create" | "update";
+    };
+    when?: string;
+    runAs: {
+        agentId: string;
+        persona: string;
+    };
+    skill: string;
+    maxDepth?: number;
+    channels?: string[];
+    validate?: string;
+}
+/** Options for {@link brandBotTrigger}. */
+interface BrandBotTriggerOpts {
+    /** Trigger id (unique per app). */
+    id: string;
+    /** The bot's agent id — must be in each target book's `memberIds` roster. */
+    agentId: string;
+    /** Persona name the dispatching worker runs. */
+    persona: string;
+    /** Fire only on messages mentioning this handle, e.g. "@brand". */
+    mention?: string;
+    /** Extra CEL over the new message row, ANDed with the built-in guards. */
+    when?: string;
+    /** Restrict to specific channel ids (the per-book mode). */
+    channels?: string[];
+    /** Watched write kind (default "create"). */
+    on?: "create" | "update";
+}
+/**
+ * Build a trigger that runs the brand agent on human chat messages
+ * (optionally @-mentions, optionally channel-scoped): chat's `botTrigger`
+ * shape with `skill: "brand"` and `maxDepth: 1` so a bot reply can never
+ * re-trigger a bot.
+ */
+declare function brandBotTrigger(opts: BrandBotTriggerOpts): BrandTrigger;
+
+/** One owner-facing setting the integration exposes (crm's shape). */
+interface IntegrationSetting {
+    key: string;
+    description: string;
+    public: boolean;
+    pattern?: string;
+    perEnv: boolean;
+    source: string;
+}
+/** One vault secret the integration needs (brand core needs none). */
+interface IntegrationSecret {
+    key: string;
+    description: string;
+    pattern?: string;
+    vault: boolean;
+}
+/** Human / CLI / doctor provisioning steps, documentation-as-data. */
+interface IntegrationProvision {
+    human: string[];
+    cli: string[];
+    doctor: string[];
+}
+/** Unauthenticated route check run by `odla-ai smoke`. */
+interface BrandIntegrationProbe {
+    path: string;
+    expectedStatus: number;
+}
+/** The brand descriptor shape: the shared base plus the schema + rules
+ * provisioning installs and the (app-supplied) bot triggers. */
+interface BrandIntegrationDescriptor {
+    id: string;
+    title: string;
+    npm: string;
+    settings: IntegrationSetting[];
+    secrets: IntegrationSecret[];
+    /** The schema to POST at /app/:id/schema. */
+    schema: SerializedSchema;
+    /** The default-deny rules to install at /app/:id/admin/rules (merged with existing). */
+    rules: BrandRules;
+    /** Commit triggers to register at /app/:id/admin/triggers (per-bot; app-supplied). */
+    triggers: BrandTrigger[];
+    probes?: BrandIntegrationProbe[];
+    provision: IntegrationProvision;
+}
+/**
+ * The static documentation descriptor for @odla-ai/brand. Data only: it
+ * describes what installing the brand capability means — push
+ * {@link BRAND_SCHEMA}, install the default-deny `brandRules()`, register
+ * `brandBotTrigger`s (app-supplied, in either the global mention-gated or the
+ * per-book channel-scoped mode), mount `createBrandRoutes` in the app worker
+ * — and performs none of it. Use {@link createBrandIntegration} in
+ * `odla.config.mjs` to add the live route probe the CLI can execute.
+ */
+declare const brandIntegration: BrandIntegrationDescriptor;
+/** Options for {@link createBrandIntegration}. */
+interface CreateBrandIntegrationOptions {
+    /** Worker mount path; defaults to `/api/brand`. */
+    basePath?: string;
+    /** Document (and probe-plan for) unauthenticated tokens routes. */
+    publicTokens?: boolean;
+    /** The global bot's mention handle — folded into the CLI trigger step. */
+    mention?: string;
+}
+/**
+ * Build the project-specific, CLI-consumable brand integration descriptor:
+ * {@link brandIntegration} plus a live smoke probe (an anonymous GET of
+ * `<basePath>/books` must answer 401 — routes mounted, authorize enforced,
+ * exactly crm's probe idiom) and, when `mention`/`publicTokens` are given,
+ * concrete CLI steps carrying the app's actual values. Mounting
+ * `createBrandRoutes` remains app-owned source work.
+ */
+declare function createBrandIntegration(options?: CreateBrandIntegrationOptions): BrandIntegrationDescriptor;
+
+export { ASSET_CONTENT_TYPES, ASSET_KINDS, type AcceptProposalInput, type AssetAnalysis, type AssetKind, type AttrType, type AudienceChildren, BOOK_STATUSES, BRAND_CHART_TOKENS, BRAND_CHAT_TOKENS, BRAND_DERIVED_TOKENS, BRAND_EMITTED_TOKENS, BRAND_INSTRUCTIONS, BRAND_NS, BRAND_REQUIRED_TOKENS, BRAND_RULES, BRAND_SCHEMA, type BookStatus, type BrandActor, type BrandAsset, type BrandAttrs, type BrandBook, type BrandBotTriggerOpts, type BrandDb, type BrandDeps, type BrandDispatchBody, type BrandDispatchDeps, type BrandEntityRef, type BrandFetchedBytes, type BrandFileRecord, BrandInputError, type BrandIntegrationDescriptor, type BrandIntegrationProbe, type BrandLookup, BrandNotFoundError, type BrandOp, type BrandPalette, type BrandProposal, type BrandResult, type BrandRouteCtx, type BrandRouteOpts, type BrandRow, type BrandRule, type BrandRules, type BrandScalar, type BrandSection, type BrandSkillOpts, type BrandSkillSelf, type BrandStorage, type BrandTokens, type BrandTokensSnapshot, type BrandToolCtx, type BrandTrigger, type BrandUploadBody, type BrandVisionCapabilities, type BrandVisionSpec, CHART_DELTA_MIN, CHAT_MESSAGE_NS, CSS_NAMED_COLORS, type CompileInput, type CompiledBrandTokens, type ContrastKind, type CreateAssetInput, type CreateBookInput, type CreateBrandIntegrationOptions, type CreateBrandPersonaOpts, DARK_FLIP_L_MAX, DARK_FLIP_L_MIN, DEFAULT_ACCENT_SEED, DEFAULT_BRAND_SYSTEM, type DeriveChartOptions, type DerivePaletteOptions, type Hsl, type ImagerySection, type IntegrationProvision, type IntegrationSecret, type IntegrationSetting, type LightnessDirection, type LogoSection, MAX_SWATCHES, MAX_VIEW_BYTES, type MapResult, type NamedColor, type NearestNamedColor, type Oklab, type Oklch, PALETTE_SOURCES, PALETTE_STATUSES, PICK_TEXT_DEFAULT_CANDIDATES, PROPOSAL_KINDS, PROPOSAL_STATUSES, type PaletteSection, type PaletteSource, type PaletteStatus, type ProposalKind, type ProposalStatus, type ProposePaletteInput, RAMP_L_MAX, RAMP_L_MIN, type RejectProposalInput, type RenderTokensCssOptions, type ResolvedBrandDeps, type Rgb, SECTION_KINDS, SECTION_STATUSES, SWATCH_ROLES, type SectionKind, type SectionStatus, type SerializedAttr, type SerializedEntity, type SerializedLink, type SerializedLinkEnd, type SerializedSchema, type Swatch, type SwatchRole, type TokenWarning, type TypographySection, type UpsertSectionInput, type VoiceSection, acceptProposalOps, adjustLightnessUntil, analogous, assertAnalysis, assertAssetContentType, assertHex, assertSectionContent, assertSwatches, assetTools, audienceFanoutOps, base64FromBytes, bookForChannel, bookTools, brandBotTrigger, brandInputFor, brandIntegration, brandRules, brandSkill, capString, capStringArray, clamp01, clampToGamut, compileBrandTokens, complementary, contrastRatio, createAssetOps, createBookOps, createBrandIntegration, createBrandPersona, createBrandRoutes, deltaEOK, deltaEOKLab, deriveChartColors, deriveDarkTokens, derivePalette, dispatchBrandTurn, hexToOklch, hslToRgb, inSrgbGamut, linearToSrgb, mapPaletteToTokens, meetsAA, meetsAAA, monochrome, nearestNamedColor, normalizeHex, oklabToOklch, oklabToRgb, oklchToHex, oklchToOklab, paletteTools, parseBrandDispatch, parseHex, pickTextOn, proposePaletteOps, readTools, recordAnalysisOps, rejectProposalOps, relativeLuminance, renderTokensCss, resolveDeps, rgbToHsl, rgbToOklab, rotateHue, safeFileName, sectionKey, splitComplementary, srgbToLinear, supportsBrandVision, tetradic, tintShadeRamp, toHex, tombstoneAssetOps, triadic, updateBookOps, upsertSectionOps };