@odla-ai/brand 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -47,7 +47,16 @@ __export(src_exports, {
   DARK_FLIP_L_MIN: () => DARK_FLIP_L_MIN,
   DEFAULT_ACCENT_SEED: () => DEFAULT_ACCENT_SEED,
   DEFAULT_BRAND_SYSTEM: () => DEFAULT_BRAND_SYSTEM,
+  DESIGN_ASSET_KIND: () => DESIGN_ASSET_KIND,
+  DESIGN_CONTENT_TYPES: () => DESIGN_CONTENT_TYPES,
+  MAX_COLORS: () => MAX_COLORS,
+  MAX_EXTERNALS: () => MAX_EXTERNALS,
+  MAX_FONTS: () => MAX_FONTS,
+  MAX_HEADING_CHARS: () => MAX_HEADING_CHARS,
+  MAX_OUTLINE_ENTRIES: () => MAX_OUTLINE_ENTRIES,
+  MAX_PROPS: () => MAX_PROPS,
   MAX_SWATCHES: () => MAX_SWATCHES,
+  MAX_THUMBNAIL_CHARS: () => MAX_THUMBNAIL_CHARS,
   MAX_VIEW_BYTES: () => MAX_VIEW_BYTES,
   PALETTE_SOURCES: () => PALETTE_SOURCES,
   PALETTE_STATUSES: () => PALETTE_STATUSES,
@@ -56,6 +65,7 @@ __export(src_exports, {
   PROPOSAL_STATUSES: () => PROPOSAL_STATUSES,
   RAMP_L_MAX: () => RAMP_L_MAX,
   RAMP_L_MIN: () => RAMP_L_MIN,
+  ROLE_TOKEN: () => ROLE_TOKEN,
   SECTION_KINDS: () => SECTION_KINDS,
   SECTION_STATUSES: () => SECTION_STATUSES,
   SWATCH_ROLES: () => SWATCH_ROLES,
@@ -70,6 +80,7 @@ __export(src_exports, {
   assetTools: () => assetTools,
   attachedBrandAssetIds: () => attachedBrandAssetIds,
   audienceFanoutOps: () => audienceFanoutOps,
+  base64ByteLength: () => base64ByteLength,
   base64FromBytes: () => base64FromBytes,
   beginAssetDeleteOps: () => beginAssetDeleteOps,
   bookForChannel: () => bookForChannel,
@@ -88,27 +99,43 @@ __export(src_exports, {
   capStringArray: () => capStringArray,
   clamp01: () => clamp01,
   clampToGamut: () => clampToGamut,
+  collapseWhitespace: () => collapseWhitespace,
   compileBrandTokens: () => compileBrandTokens,
   complementary: () => complementary,
   contrastRatio: () => contrastRatio,
+  contrastReport: () => contrastReport,
   createAssetOps: () => createAssetOps,
   createBookOps: () => createBookOps,
   createBrandIntegration: () => createBrandIntegration,
   createBrandPersona: () => createBrandPersona,
   createBrandRoutes: () => createBrandRoutes,
+  cssColorToHex: () => cssColorToHex,
+  decodeEntities: () => decodeEntities,
   deltaEOK: () => deltaEOK,
   deltaEOKLab: () => deltaEOKLab,
   deriveChartColors: () => deriveChartColors,
   deriveDarkTokens: () => deriveDarkTokens,
   derivePalette: () => derivePalette,
+  digestDesignBundle: () => digestDesignBundle,
+  digestDesignHtml: () => digestDesignHtml,
   dispatchBrandTurn: () => dispatchBrandTurn,
+  extractColors: () => extractColors,
+  extractDesignTokens: () => extractDesignTokens,
+  extractFonts: () => extractFonts,
+  extractOutline: () => extractOutline,
+  extractProps: () => extractProps,
+  extractThumbnailSvg: () => extractThumbnailSvg,
+  extractTitle: () => extractTitle,
   finishAssetDeleteOps: () => finishAssetDeleteOps,
   formatBrandDiscussionReference: () => formatBrandDiscussionReference,
+  groupAssets: () => groupAssets,
   hexToOklch: () => hexToOklch,
   hslToRgb: () => hslToRgb,
+  htmlToText: () => htmlToText,
   inSrgbGamut: () => inSrgbGamut,
   isBoundedBrandJson: () => isBoundedBrandJson,
   isBrandHumanAuthorityConsumption: () => isBrandHumanAuthorityConsumption,
+  isDesignBundle: () => isDesignBundle,
   linearToSrgb: () => linearToSrgb,
   mapPaletteToTokens: () => mapPaletteToTokens,
   meetsAA: () => meetsAA,
@@ -123,25 +150,32 @@ __export(src_exports, {
   paletteTools: () => paletteTools,
   parseBrandDiscussionReference: () => parseBrandDiscussionReference,
   parseBrandDispatch: () => parseBrandDispatch,
+  parseDesignBundle: () => parseDesignBundle,
   parseHex: () => parseHex,
   pickTextOn: () => pickTextOn,
   proposalReviewSnapshot: () => proposalReviewSnapshot,
   proposePaletteOps: () => proposePaletteOps,
   proposeSectionOps: () => proposeSectionOps,
+  readDesignManifest: () => readDesignManifest,
   readTools: () => readTools,
   recordAnalysisOps: () => recordAnalysisOps,
   rejectProposalOps: () => rejectProposalOps,
   relativeLuminance: () => relativeLuminance,
   renderTokensCss: () => renderTokensCss,
   resolveDeps: () => resolveDeps,
+  resolveVarRefs: () => resolveVarRefs,
   rgbToHsl: () => rgbToHsl,
   rgbToOklab: () => rgbToOklab,
   rotateHue: () => rotateHue,
   safeFileName: () => safeFileName,
+  scanCustomProperties: () => scanCustomProperties,
   sectionKey: () => sectionKey,
   splitComplementary: () => splitComplementary,
   srgbToLinear: () => srgbToLinear,
+  stripCssComments: () => stripCssComments,
+  styleSheetText: () => styleSheetText,
   supportsBrandVision: () => supportsBrandVision,
+  swatchesFromDesignTokens: () => swatchesFromDesignTokens,
   tetradic: () => tetradic,
   tintShadeRamp: () => tintShadeRamp,
   toHex: () => toHex,
@@ -168,7 +202,15 @@ var PALETTE_STATUSES = ["active", "archived"];
 var PALETTE_SOURCES = ["extracted", "derived", "manual"];
 var PROPOSAL_KINDS = SECTION_KINDS;
 var PROPOSAL_STATUSES = ["open", "accepted", "rejected", "superseded"];
-var ASSET_KINDS = ["logo", "wordmark", "inspiration", "document", "other"];
+var ASSET_KINDS = [
+  "logo",
+  "wordmark",
+  "inspiration",
+  "document",
+  "design",
+  "other"
+];
+var DESIGN_ASSET_KIND = "design";
 var SWATCH_ROLES = [
   "primary",
   "secondary",
@@ -392,7 +434,7 @@ var BRAND_SCHEMA = {
         id: uniq("string"),
         bookId: idx("string"),
         kind: idx("string"),
-        // logo | wordmark | inspiration | document | other
+        // logo | wordmark | inspiration | document | design | other
         path: idx("string"),
         storageObjectId: idx("string"),
         contentDigest: idx("string"),
@@ -404,6 +446,11 @@ var BRAND_SCHEMA = {
         analysis: opt("json"),
         // { description, dominantColors: hex[], tags }
         analyzedAt: opt("date"),
+        // `design` kind only: the DesignDigest computed from the uploaded
+        // bundle at upload time. Machine-derived and deterministic — unlike
+        // `analysis`, which is what a model reports seeing — so it needs no
+        // review gate and is rewritten only by re-uploading.
+        design: opt("json"),
         analysisRevision: a("number"),
         analysisDigest: opt("string"),
         analyzedBy: opt("string"),
@@ -498,6 +545,7 @@ var ASSET_CONTENT_TYPES = /* @__PURE__ */ new Set([
   "image/webp",
   "application/pdf"
 ]);
+var DESIGN_CONTENT_TYPES = /* @__PURE__ */ new Set(["text/html"]);
 var HEX_RGB = /^#[0-9a-f]{3}$/;
 var HEX_RRGGBB = /^#[0-9a-f]{6}$/;
 var HEX_ALPHA = /^#[0-9a-f]{4}$|^#[0-9a-f]{8}$/;
@@ -619,12 +667,13 @@ function safeFileName(name) {
     throw new BrandInputError("file name is empty or a dot segment after sanitizing");
   return cleaned.slice(0, 120);
 }
-function assertAssetContentType(value) {
+function assertAssetContentType(value, kind) {
   if (typeof value !== "string") throw new BrandInputError("contentType must be a string");
   const ct = value.split(";")[0].trim().toLowerCase();
-  if (!ASSET_CONTENT_TYPES.has(ct))
+  const allowed = kind === DESIGN_ASSET_KIND ? DESIGN_CONTENT_TYPES : ASSET_CONTENT_TYPES;
+  if (!allowed.has(ct))
     throw new BrandInputError(
-      `unsupported content type ${ct || "(empty)"}; allowed: ${[...ASSET_CONTENT_TYPES].join(", ")}`
+      `unsupported content type ${ct || "(empty)"} for kind ${kind ?? "other"}; allowed: ${[...allowed].join(", ")}`
     );
   return ct;
 }
@@ -1171,7 +1220,11 @@ function rejectProposalOps(input) {
 function createAssetOps(input) {
   if (!ASSET_KINDS.includes(input.kind))
     throw new BrandInputError(`kind must be one of: ${ASSET_KINDS.join(", ")}`);
-  const contentType = assertAssetContentType(input.contentType);
+  const contentType = assertAssetContentType(input.contentType, input.kind);
+  if (input.kind === DESIGN_ASSET_KIND && input.design === void 0)
+    throw new BrandInputError("a design asset must carry its parsed digest");
+  if (input.kind !== DESIGN_ASSET_KIND && input.design !== void 0)
+    throw new BrandInputError(`only ${DESIGN_ASSET_KIND} assets may carry a design digest`);
   if (typeof input.size !== "number" || !Number.isFinite(input.size) || input.size <= 0)
     throw new BrandInputError("size must be a positive byte count");
   if (!/^sha256:[0-9a-f]{64}$/.test(input.contentDigest))
@@ -1201,7 +1254,8 @@ function createAssetOps(input) {
           200
         ),
         createdAt: input.now,
-        ...title ? { title } : {}
+        ...title ? { title } : {},
+        ...input.design ? { design: input.design } : {}
       }
     },
     { t: "link", ns: BRAND_NS.asset, id: input.id, label: "book", target: input.bookId }
@@ -1253,6 +1307,180 @@ async function recordAnalysisOps(assetId, analysis, priorRevision, analyzedBy, a
   ];
 }
 
+// src/design/bundle.ts
+var MAX_THUMBNAIL_CHARS = 16384;
+function island(html, name) {
+  const open = `<script type="__bundler/${name}">`;
+  const start = html.indexOf(open);
+  if (start < 0) return null;
+  const from = start + open.length;
+  const end = html.indexOf("</script>", from);
+  return end < 0 ? null : html.slice(from, end);
+}
+function isDesignBundle(html) {
+  return html.includes('<script type="__bundler/manifest">') && html.includes('<script type="__bundler/template">');
+}
+function base64ByteLength(data) {
+  const len = data.length;
+  if (len === 0) return 0;
+  const pad = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+  return Math.max(0, Math.floor(len * 3 / 4) - pad);
+}
+function parseIslandJson(text, name) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new BrandInputError(`design bundle's ${name} island is not valid JSON`);
+  }
+}
+var isRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function readAssets(raw) {
+  if (!isRecord2(raw)) throw new BrandInputError("design bundle's manifest island must be an object");
+  const assets = [];
+  for (const [uuid, value] of Object.entries(raw)) {
+    if (!isRecord2(value)) continue;
+    const data = value.data;
+    const mime = value.mime;
+    if (typeof data !== "string" || typeof mime !== "string") continue;
+    assets.push({
+      uuid,
+      mime: mime.slice(0, 120),
+      bytes: base64ByteLength(data),
+      compressed: value.compressed === true
+    });
+  }
+  return assets;
+}
+function readExternals(raw) {
+  if (raw === null || raw === void 0) return [];
+  if (!Array.isArray(raw))
+    throw new BrandInputError("design bundle's ext_resources island must be an array");
+  const out = [];
+  for (const entry of raw) {
+    if (isRecord2(entry) && typeof entry.id === "string") out.push(entry.id.slice(0, 512));
+  }
+  return out;
+}
+function readPageOrder(raw) {
+  if (raw === null || raw === void 0) return [];
+  if (!Array.isArray(raw))
+    throw new BrandInputError("design bundle's page_order island must be an array");
+  return raw.filter((v) => typeof v === "string");
+}
+function extractThumbnailSvg(html) {
+  const anchor = html.indexOf("__bundler_thumbnail");
+  if (anchor < 0) return void 0;
+  const open = html.indexOf("<svg", anchor);
+  if (open < 0) return void 0;
+  const close = html.indexOf("</svg>", open);
+  if (close < 0) return void 0;
+  const svg = html.slice(open, close + "</svg>".length);
+  return svg.length > MAX_THUMBNAIL_CHARS ? void 0 : svg;
+}
+function readDesignManifest(html) {
+  const raw = island(html, "manifest");
+  if (raw === null) throw new BrandInputError("design bundle has no manifest island");
+  const parsed = parseIslandJson(raw, "manifest");
+  if (!isRecord2(parsed)) throw new BrandInputError("design bundle's manifest island must be an object");
+  const out = {};
+  for (const [uuid, value] of Object.entries(parsed)) {
+    if (!isRecord2(value)) continue;
+    const { data, mime } = value;
+    if (typeof data !== "string" || typeof mime !== "string") continue;
+    out[uuid] = { mime, compressed: value.compressed === true, data };
+  }
+  return out;
+}
+function parseDesignBundle(html) {
+  if (!isDesignBundle(html))
+    throw new BrandInputError(
+      "not a Claude Design bundle: no __bundler/manifest and __bundler/template script islands. Export the design as standalone HTML and upload that file."
+    );
+  const templateRaw = island(html, "template");
+  if (templateRaw === null)
+    throw new BrandInputError("design bundle's template island is unterminated");
+  const template = parseIslandJson(templateRaw, "template");
+  if (typeof template !== "string")
+    throw new BrandInputError("design bundle's template island must be a JSON string");
+  const manifestRaw = island(html, "manifest");
+  if (manifestRaw === null)
+    throw new BrandInputError("design bundle's manifest island is unterminated");
+  const extRaw = island(html, "ext_resources");
+  const pageRaw = island(html, "page_order");
+  const thumbnailSvg = extractThumbnailSvg(html);
+  return {
+    template,
+    assets: readAssets(parseIslandJson(manifestRaw, "manifest")),
+    externals: readExternals(extRaw === null ? null : parseIslandJson(extRaw, "ext_resources")),
+    pageOrder: readPageOrder(pageRaw === null ? null : parseIslandJson(pageRaw, "page_order")),
+    ...thumbnailSvg ? { thumbnailSvg } : {}
+  };
+}
+
+// src/design/css-scan.ts
+function stripCssComments(css) {
+  let out = "";
+  let i = 0;
+  for (; ; ) {
+    const start = css.indexOf("/*", i);
+    if (start < 0) return out + css.slice(i);
+    out += css.slice(i, start);
+    const end = css.indexOf("*/", start + 2);
+    if (end < 0) return out;
+    i = end + 2;
+  }
+}
+function styleSheetText(html) {
+  const parts = [];
+  let i = 0;
+  for (; ; ) {
+    const open = html.indexOf("<style", i);
+    if (open < 0) break;
+    const gt = html.indexOf(">", open);
+    if (gt < 0) break;
+    const close = html.indexOf("</style>", gt);
+    if (close < 0) break;
+    parts.push(html.slice(gt + 1, close));
+    i = close + "</style>".length;
+  }
+  return parts.join("\n");
+}
+function scanCustomProperties(css) {
+  const text = stripCssComments(css);
+  const found = [];
+  const stack = [];
+  let paren = 0;
+  let start = 0;
+  const flush = (end) => {
+    if (stack.length === 0) return;
+    const chunk = text.slice(start, end).trim();
+    if (!chunk.startsWith("--")) return;
+    const colon = chunk.indexOf(":");
+    if (colon < 0) return;
+    const name = chunk.slice(0, colon).trim();
+    if (name.length < 3) return;
+    found.push({ selectors: [...stack], name, value: chunk.slice(colon + 1).trim() });
+  };
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "(") paren++;
+    else if (ch === ")") paren = Math.max(0, paren - 1);
+    if (paren !== 0) continue;
+    if (ch === "{") {
+      stack.push(text.slice(start, i).trim());
+      start = i + 1;
+    } else if (ch === "}") {
+      flush(i);
+      stack.pop();
+      start = i + 1;
+    } else if (ch === ";") {
+      flush(i);
+      start = i + 1;
+    }
+  }
+  return found;
+}
+
 // src/color/hex.ts
 function clamp01(x) {
   return Number.isNaN(x) ? 0 : x < 0 ? 0 : x > 1 ? 1 : x;
@@ -1763,69 +1991,6 @@ function derivePalette(seedHex, opts = {}) {
   return withNames ? swatches.map((s) => ({ ...s, name: nearestNamedColor(s.hex).name })) : swatches;
 }
 
-// src/tokens/roles.ts
-var BRAND_REQUIRED_TOKENS = [
-  "--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"
-];
-var BRAND_DERIVED_TOKENS = [
-  "--ui-accent-glow",
-  "--ui-accent-2",
-  "--ui-accent-2-soft",
-  "--ui-highlight",
-  "--ui-focus",
-  "--ui-shadow-strong"
-];
-var BRAND_CHART_TOKENS = [
-  "--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"
-];
-var BRAND_CHAT_TOKENS = [
-  "--ui-chat-user-bg",
-  "--ui-chat-user-text",
-  "--ui-chat-assistant-bg",
-  "--ui-chat-thinking-bg",
-  "--ui-chat-thinking-text",
-  "--ui-chat-tool-accent"
-];
-var BRAND_EMITTED_TOKENS = [
-  ...BRAND_REQUIRED_TOKENS,
-  ...BRAND_DERIVED_TOKENS,
-  ...BRAND_CHART_TOKENS,
-  ...BRAND_CHAT_TOKENS
-];
-
 // src/tokens/map.ts
 var DEFAULT_ACCENT_SEED = "#3b5e8c";
 var CHROMATIC_C = 0.02;
@@ -2025,6 +2190,452 @@ function mapPaletteToTokens(input) {
   return { tokens, warnings };
 }
 
+// src/design/decompile.ts
+var CHART_TOKENS = [
+  "--ui-chart-1",
+  "--ui-chart-2",
+  "--ui-chart-3",
+  "--ui-chart-4",
+  "--ui-chart-5",
+  "--ui-chart-6"
+];
+function cssColorToHex(value) {
+  const text = value.trim();
+  if (text.startsWith("#")) {
+    try {
+      return assertHex(text);
+    } catch {
+      return null;
+    }
+  }
+  const fn = /^rgba?\(([^)]*)\)$/i.exec(text);
+  if (!fn) return null;
+  const parts = (fn[1] ?? "").split(/[,/\s]+/).filter((p) => p !== "");
+  if (parts.length < 3 || parts.length > 4) return null;
+  if (parts.length === 4) {
+    const alpha = parts[3].endsWith("%") ? Number.parseFloat(parts[3]) / 100 : Number.parseFloat(parts[3]);
+    if (!Number.isFinite(alpha) || alpha < 1) return null;
+  }
+  const channels = parts.slice(0, 3).map((part) => {
+    const n = Number.parseFloat(part);
+    if (!Number.isFinite(n)) return Number.NaN;
+    return Math.round(part.endsWith("%") ? n / 100 * 255 : n);
+  });
+  if (channels.some((c) => !Number.isFinite(c) || c < 0 || c > 255)) return null;
+  return `#${channels.map((c) => c.toString(16).padStart(2, "0")).join("")}`;
+}
+var skipReason = (value) => value.includes("var(") ? "unresolved var() reference" : value.includes("color-mix(") ? "composed with color-mix()" : /rgba?\(/i.test(value) ? "not fully opaque" : "not a literal color";
+function swatchesFromDesignTokens(tokens) {
+  const light = tokens.light;
+  const swatches = [];
+  const skipped = [];
+  const missing2 = [];
+  for (const [role, token] of Object.entries(ROLE_TOKEN)) {
+    if (role === "chart") continue;
+    const value = light[token];
+    if (value === void 0) {
+      missing2.push(role);
+      continue;
+    }
+    const hex = cssColorToHex(value);
+    if (hex === null) {
+      skipped.push({ token, value, reason: skipReason(value) });
+      continue;
+    }
+    swatches.push({ role, hex, rationale: `declared by the design as ${token}` });
+  }
+  let anyChart = false;
+  for (const token of CHART_TOKENS) {
+    const value = light[token];
+    if (value === void 0) continue;
+    const hex = cssColorToHex(value);
+    if (hex === null) {
+      skipped.push({ token, value, reason: skipReason(value) });
+      continue;
+    }
+    anyChart = true;
+    swatches.push({ role: "chart", hex, rationale: `declared by the design as ${token}` });
+  }
+  if (!anyChart) missing2.push("chart");
+  return { swatches, skipped, missing: missing2 };
+}
+
+// src/design/html-text.ts
+var NAMED_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: "\xA0",
+  mdash: "\u2014",
+  ndash: "\u2013",
+  hellip: "\u2026",
+  rsquo: "\u2019",
+  lsquo: "\u2018",
+  ldquo: "\u201C",
+  rdquo: "\u201D"
+};
+function decodeEntities(text) {
+  return text.replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z][a-zA-Z0-9]{1,31});/g, (whole, body) => {
+    if (body.startsWith("#x") || body.startsWith("#X")) {
+      const code = Number.parseInt(body.slice(2), 16);
+      return Number.isFinite(code) && code > 0 && code <= 1114111 ? String.fromCodePoint(code) : whole;
+    }
+    if (body.startsWith("#")) {
+      const code = Number.parseInt(body.slice(1), 10);
+      return Number.isFinite(code) && code > 0 && code <= 1114111 ? String.fromCodePoint(code) : whole;
+    }
+    return NAMED_ENTITIES[body.toLowerCase()] ?? whole;
+  });
+}
+var collapseWhitespace = (text) => text.replace(/\s+/g, " ").trim();
+function htmlToText(fragment) {
+  const withoutCode = fragment.replace(/<script\b[^>]*>[\s\S]*?<\/script\s*>/gi, " ").replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, " ");
+  return collapseWhitespace(decodeEntities(withoutCode.replace(/<[^>]*>/g, " ")));
+}
+
+// src/design/outline.ts
+var MAX_OUTLINE_ENTRIES = 120;
+var MAX_HEADING_CHARS = 200;
+function extractTitle(html) {
+  const match = /<title\b[^>]*>([\s\S]{0,2000}?)<\/title\s*>/i.exec(html);
+  if (!match) return void 0;
+  const text = htmlToText(match[1] ?? "");
+  return text === "" ? void 0 : text.slice(0, MAX_HEADING_CHARS);
+}
+function extractOutline(html) {
+  const pattern = /<h([1-6])\b[^>]*>([\s\S]{0,4000}?)<\/h\1\s*>/gi;
+  const entries = [];
+  for (; ; ) {
+    const match = pattern.exec(html);
+    if (match === null) break;
+    const text = htmlToText(match[2] ?? "");
+    if (text === "") continue;
+    if (entries.length >= MAX_OUTLINE_ENTRIES) return { entries, truncated: true };
+    entries.push({ level: Number(match[1]), text: text.slice(0, MAX_HEADING_CHARS) });
+  }
+  return { entries, truncated: false };
+}
+
+// src/design/props.ts
+var MAX_PROPS = 60;
+var isRecord3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function attributeValue(html, attr) {
+  const at = html.indexOf(`${attr}="`);
+  if (at >= 0) {
+    const from2 = at + attr.length + 2;
+    const end2 = html.indexOf('"', from2);
+    return end2 < 0 ? null : html.slice(from2, end2);
+  }
+  const single = html.indexOf(`${attr}='`);
+  if (single < 0) return null;
+  const from = single + attr.length + 2;
+  const end = html.indexOf("'", from);
+  return end < 0 ? null : html.slice(from, end);
+}
+function defaultText(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "string") return value.slice(0, 400);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  try {
+    return JSON.stringify(value).slice(0, 400);
+  } catch {
+    return void 0;
+  }
+}
+function toProp(name, spec) {
+  const options = Array.isArray(spec.options) ? spec.options.filter((v) => typeof v === "string").slice(0, 24) : void 0;
+  const declared = defaultText(spec.default);
+  return {
+    name: name.slice(0, 80),
+    editor: typeof spec.editor === "string" ? spec.editor.slice(0, 40) : "unknown",
+    ...options && options.length > 0 ? { options } : {},
+    ...declared !== void 0 ? { default: declared } : {},
+    ...typeof spec.section === "string" ? { section: spec.section.slice(0, 80) } : {},
+    ...typeof spec.tsType === "string" ? { tsType: spec.tsType.slice(0, 200) } : {}
+  };
+}
+function extractProps(html) {
+  const at = html.indexOf("data-props=");
+  if (at < 0) return { props: [], truncated: false };
+  const raw = attributeValue(html.slice(at), "data-props");
+  if (raw === null) return { props: [], truncated: false };
+  let parsed;
+  try {
+    parsed = JSON.parse(decodeEntities(raw));
+  } catch {
+    return { props: [], truncated: false };
+  }
+  if (!isRecord3(parsed)) return { props: [], truncated: false };
+  const entries = Object.entries(parsed).filter(
+    (entry) => isRecord3(entry[1])
+  );
+  return {
+    props: entries.slice(0, MAX_PROPS).map(([name, spec]) => toProp(name, spec)),
+    truncated: entries.length > MAX_PROPS
+  };
+}
+
+// src/design/styles.ts
+var MAX_FONTS = 16;
+var MAX_COLORS = 24;
+var GENERIC_FAMILIES = /* @__PURE__ */ new Set([
+  "serif",
+  "sans-serif",
+  "monospace",
+  "cursive",
+  "fantasy",
+  "system-ui",
+  "ui-serif",
+  "ui-sans-serif",
+  "ui-monospace",
+  "ui-rounded",
+  "math",
+  "emoji",
+  "inherit",
+  "initial",
+  "revert",
+  "unset",
+  "currentcolor"
+]);
+var familyName = (raw) => raw.trim().replace(/^["']|["']$/g, "").trim();
+function fontFaceFamilies(css) {
+  const seen = /* @__PURE__ */ new Set();
+  const blocks = /@font-face\s*\{([^}]{0,4000})\}/gi;
+  for (; ; ) {
+    const block = blocks.exec(css);
+    if (block === null) break;
+    const declared = /font-family\s*:\s*([^;]{1,200})/i.exec(block[1] ?? "");
+    if (!declared) continue;
+    const name = familyName(declared[1] ?? "");
+    if (name !== "" && !GENERIC_FAMILIES.has(name.toLowerCase())) seen.add(name);
+  }
+  return [...seen];
+}
+function stackFamilies(css) {
+  const counts = /* @__PURE__ */ new Map();
+  const stacks = /font-family\s*:\s*([^;{}]{1,400})/gi;
+  for (; ; ) {
+    const stack = stacks.exec(css);
+    if (stack === null) break;
+    for (const part of (stack[1] ?? "").split(",")) {
+      if (!/["']/.test(part)) continue;
+      const name = familyName(part);
+      if (name === "" || GENERIC_FAMILIES.has(name.toLowerCase()) || name.includes("var(")) continue;
+      counts.set(name, (counts.get(name) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()].sort((a2, b) => b[1] - a2[1] || (a2[0] < b[0] ? -1 : 1)).map(([name]) => name);
+}
+function extractFonts(templateHtml) {
+  const css = stripCssComments(styleSheetText(templateHtml));
+  const embedded = fontFaceFamilies(css);
+  return (embedded.length > 0 ? embedded : stackFamilies(css)).slice(0, MAX_FONTS);
+}
+function extractColors(templateHtml) {
+  const css = stripCssComments(styleSheetText(templateHtml));
+  const counts = /* @__PURE__ */ new Map();
+  const hexes = /#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b/g;
+  for (; ; ) {
+    const found = hexes.exec(css);
+    if (found === null) break;
+    const raw = (found[1] ?? "").toLowerCase();
+    const hex = raw.length === 3 ? `#${raw[0]}${raw[0]}${raw[1]}${raw[1]}${raw[2]}${raw[2]}` : `#${raw}`;
+    counts.set(hex, (counts.get(hex) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((a2, b) => b[1] - a2[1] || (a2[0] < b[0] ? -1 : 1)).slice(0, MAX_COLORS).map(([hex, count]) => ({ hex, count }));
+}
+
+// src/design/tokens.ts
+var MAX_VAR_DEPTH = 8;
+var DOC_SELECTOR = /(^|,)\s*(:root|html)\b|\[data-theme\s*=|\.ui-invert\b/;
+var DARK_SELECTOR = /data-theme\s*=\s*["']?dark|prefers-color-scheme\s*:\s*dark|\.ui-invert\b/;
+function splitVarArgs(inner) {
+  let paren = 0;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (ch === "(") paren++;
+    else if (ch === ")") paren--;
+    else if (ch === "," && paren === 0)
+      return { name: inner.slice(0, i).trim(), fallback: inner.slice(i + 1).trim() };
+  }
+  return { name: inner.trim() };
+}
+function resolveVarRefs(value, table, depth = 0) {
+  if (depth >= MAX_VAR_DEPTH || !value.includes("var(")) return value;
+  let out = "";
+  let i = 0;
+  for (; ; ) {
+    const at = value.indexOf("var(", i);
+    if (at < 0) return out + value.slice(i);
+    out += value.slice(i, at);
+    let paren = 1;
+    let j = at + "var(".length;
+    for (; j < value.length && paren > 0; j++) {
+      if (value[j] === "(") paren++;
+      else if (value[j] === ")") paren--;
+    }
+    if (paren > 0) return out + value.slice(at);
+    const { name, fallback } = splitVarArgs(value.slice(at + "var(".length, j - 1));
+    const referenced = table.get(name);
+    const replacement = referenced !== void 0 ? resolveVarRefs(referenced, table, depth + 1) : fallback !== void 0 ? resolveVarRefs(fallback, table, depth + 1) : `var(${name})`;
+    out += replacement;
+    i = j;
+  }
+}
+function foldDeclarations(html) {
+  const light = /* @__PURE__ */ new Map();
+  const darkOverrides = [];
+  for (const decl of scanCustomProperties(styleSheetText(html))) {
+    const innermost = decl.selectors[decl.selectors.length - 1] ?? "";
+    if (!DOC_SELECTOR.test(innermost)) continue;
+    if (decl.selectors.some((sel) => DARK_SELECTOR.test(sel))) darkOverrides.push([decl.name, decl.value]);
+    else light.set(decl.name, decl.value);
+  }
+  const dark = new Map(light);
+  for (const [name, value] of darkOverrides) dark.set(name, value);
+  return { light, dark };
+}
+function resolveUiTokens(table) {
+  const out = {};
+  for (const [name, value] of table) {
+    if (!name.startsWith("--ui-")) continue;
+    out[name] = resolveVarRefs(value, table);
+  }
+  return out;
+}
+function extractDesignTokens(templateHtml) {
+  const { light, dark } = foldDeclarations(templateHtml);
+  return { light: resolveUiTokens(light), dark: resolveUiTokens(dark) };
+}
+
+// src/design/digest.ts
+var MAX_EXTERNALS = 24;
+function groupAssets(bundle) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const asset of bundle.assets) {
+    const group = groups.get(asset.mime) ?? { mime: asset.mime, count: 0, bytes: 0 };
+    group.count += 1;
+    group.bytes += asset.bytes;
+    groups.set(asset.mime, group);
+  }
+  return [...groups.values()].sort((a2, b) => b.bytes - a2.bytes || (a2.mime < b.mime ? -1 : 1));
+}
+function digestDesignBundle(bundle) {
+  const template = bundle.template;
+  const outline = extractOutline(template);
+  const props = extractProps(template);
+  const assetGroups = groupAssets(bundle);
+  const title = extractTitle(template);
+  const truncated = [];
+  if (outline.truncated) truncated.push("outline");
+  if (props.truncated) truncated.push("props");
+  if (bundle.externals.length > MAX_EXTERNALS) truncated.push("externals");
+  return {
+    format: "claude-design-bundle/1",
+    ...title ? { title } : {},
+    templateBytes: new TextEncoder().encode(template).byteLength,
+    assetBytes: bundle.assets.reduce((total, asset) => total + asset.bytes, 0),
+    assetCount: bundle.assets.length,
+    assetGroups,
+    externals: bundle.externals.slice(0, MAX_EXTERNALS),
+    pageCount: bundle.pageOrder.length,
+    tokens: extractDesignTokens(template),
+    fonts: extractFonts(template),
+    colors: extractColors(template),
+    props: props.props,
+    outline: outline.entries,
+    ...bundle.thumbnailSvg ? { thumbnailSvg: bundle.thumbnailSvg } : {},
+    truncated
+  };
+}
+function digestDesignHtml(html) {
+  return digestDesignBundle(parseDesignBundle(html));
+}
+
+// src/palette-report.ts
+var round2 = (n) => Math.round(n * 100) / 100;
+function contrastReport(swatches) {
+  const byRole = (role) => swatches.find((s) => s.role === role)?.hex;
+  const bg = byRole("bg") ?? "#ffffff";
+  const report = {};
+  const put = (label, fg) => {
+    if (fg) report[label] = round2(contrastRatio(fg, bg));
+  };
+  put("text-on-bg", byRole("text"));
+  put("primary-on-bg", byRole("primary"));
+  put("good-on-bg", byRole("good"));
+  put("warn-on-bg", byRole("warn"));
+  put("danger-on-bg", byRole("danger"));
+  const primary = byRole("primary");
+  if (primary) report["text-on-primary"] = round2(contrastRatio(pickTextOn(primary), primary));
+  return report;
+}
+
+// src/tokens/roles.ts
+var BRAND_REQUIRED_TOKENS = [
+  "--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"
+];
+var BRAND_DERIVED_TOKENS = [
+  "--ui-accent-glow",
+  "--ui-accent-2",
+  "--ui-accent-2-soft",
+  "--ui-highlight",
+  "--ui-focus",
+  "--ui-shadow-strong"
+];
+var BRAND_CHART_TOKENS = [
+  "--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"
+];
+var BRAND_CHAT_TOKENS = [
+  "--ui-chat-user-bg",
+  "--ui-chat-user-text",
+  "--ui-chat-assistant-bg",
+  "--ui-chat-thinking-bg",
+  "--ui-chat-thinking-text",
+  "--ui-chat-tool-accent"
+];
+var BRAND_EMITTED_TOKENS = [
+  ...BRAND_REQUIRED_TOKENS,
+  ...BRAND_DERIVED_TOKENS,
+  ...BRAND_CHART_TOKENS,
+  ...BRAND_CHAT_TOKENS
+];
+
 // src/tokens/dark.ts
 var DARK_FLIP_L_MIN = 0.2;
 var DARK_FLIP_L_MAX = 0.95;
@@ -2182,10 +2793,10 @@ ${renderBlock(mediaSelector, dark, diffNames, "  ")}
 }
 
 // src/tokens/compile.ts
-var isRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isRecord4 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function applyOverrides(light, overrides, warnings) {
   if (overrides === void 0) return;
-  if (!isRecord2(overrides)) {
+  if (!isRecord4(overrides)) {
     warnings.push({ token: "--ui-accent", message: "overrides ignored: not an object" });
     return;
   }
@@ -2419,22 +3030,6 @@ function applyHarmony(swatches, seedHex, harmony) {
     return { ...s, hex, name: nearestNamedColor(hex).name, rationale: `${harmony} companion of the seed` };
   });
 }
-function contrastReport(swatches) {
-  const byRole = (role) => swatches.find((s) => s.role === role)?.hex;
-  const bg = byRole("bg") ?? "#ffffff";
-  const report = {};
-  const put = (label, fg) => {
-    if (fg) report[label] = Math.round(contrastRatio(fg, bg) * 100) / 100;
-  };
-  put("text-on-bg", byRole("text"));
-  put("primary-on-bg", byRole("primary"));
-  put("good-on-bg", byRole("good"));
-  put("warn-on-bg", byRole("warn"));
-  put("danger-on-bg", byRole("danger"));
-  const primary = byRole("primary");
-  if (primary) report["text-on-primary"] = Math.round(contrastRatio(pickTextOn(primary), primary) * 100) / 100;
-  return report;
-}
 var INCLUDE_SECTIONS = ["harmony", "ramp"];
 function analyzeLines(hex, include) {
   const lch = hexToOklch(hex);
@@ -2591,6 +3186,160 @@ function paletteTools(ctx) {
   return [analyzeColor, evaluateContrast, proposePalette];
 }
 
+// src/skill/design-tools.ts
+var MAX_SOURCE_WINDOW = 12e3;
+function describeDigest(asset, digest2) {
+  const lines = [
+    `Design ${asset.id}${digest2.title ? ` \u2014 "${digest2.title}"` : ""}${asset.title ? ` (uploaded as "${asset.title}")` : ""}`,
+    `Template ${digest2.templateBytes} bytes; ${digest2.assetCount} embedded assets (${digest2.assetBytes} bytes); ${digest2.pageCount} nested pages.`
+  ];
+  if (digest2.assetGroups.length > 0)
+    lines.push(
+      `Assets: ${digest2.assetGroups.map((g) => `${g.count}\xD7 ${g.mime} (${g.bytes} B)`).join(", ")}`
+    );
+  if (digest2.externals.length > 0) lines.push(`Built against: ${digest2.externals.join(", ")}`);
+  if (digest2.fonts.length > 0) lines.push(`Typefaces: ${digest2.fonts.join(", ")}`);
+  const tokenNames = Object.keys(digest2.tokens.light);
+  lines.push(
+    tokenNames.length > 0 ? `Declares ${tokenNames.length} --ui-* tokens (light) and ${Object.keys(digest2.tokens.dark).length} (dark). Key values: ${["--ui-bg", "--ui-text", "--ui-accent", "--ui-accent-strong", "--ui-surface"].filter((n) => digest2.tokens.light[n]).map((n) => `${n}=${digest2.tokens.light[n]}`).join(", ")}` : "Declares no --ui-* tokens; it was not authored on the @odla-ai/ui contract."
+  );
+  if (digest2.colors.length > 0)
+    lines.push(`Literal colors: ${digest2.colors.map((c) => `${c.hex}\xD7${c.count}`).join(", ")}`);
+  if (digest2.props.length > 0)
+    lines.push(
+      "Configurable props:\n" + digest2.props.map(
+        (p) => `  ${p.name} (${p.editor}${p.options ? `: ${p.options.join("|")}` : ""})${p.default === void 0 ? "" : ` default ${p.default}`}${p.section ? ` [${p.section}]` : ""}`
+      ).join("\n")
+    );
+  if (digest2.outline.length > 0)
+    lines.push(
+      "Outline:\n" + digest2.outline.map((h) => `${"  ".repeat(h.level - 1)}h${h.level} ${h.text}`).join("\n")
+    );
+  if (digest2.truncated.length > 0)
+    lines.push(`NOTE: truncated to fit digest caps: ${digest2.truncated.join(", ")}.`);
+  return lines.join("\n");
+}
+function sourceWindow(template, input) {
+  const length = Math.min(
+    MAX_SOURCE_WINDOW,
+    Math.max(1, typeof input.length === "number" ? input.length : MAX_SOURCE_WINDOW)
+  );
+  let start;
+  if (input.find !== void 0 && input.find !== "") {
+    const at = template.indexOf(input.find);
+    if (at < 0) throw new BrandNotFoundError(`"${input.find}" in the design source`);
+    start = Math.max(0, at - 400);
+  } else {
+    start = Math.max(0, Math.min(template.length, Math.trunc(input.offset ?? 0)));
+  }
+  const end = Math.min(template.length, start + length);
+  return { text: template.slice(start, end), start, end };
+}
+function designTools(ctx) {
+  const loadDesign = async (assetId) => {
+    await ctx.authority("brand.read");
+    const res = await ctx.db.query({
+      [BRAND_NS.asset]: { $: { where: { id: assetId, bookId: ctx.bookId, status: "live" } } }
+    });
+    const row = (res[BRAND_NS.asset] ?? [])[0];
+    if (!row || row.kind !== DESIGN_ASSET_KIND || !row.design)
+      throw new BrandNotFoundError(`design asset ${assetId}`);
+    return row;
+  };
+  const readDesign = {
+    name: "read_design",
+    description: "Read an uploaded Claude Design: its design tokens, typefaces, colors, configurable props, and heading outline. Start here before building anything from a design \u2014 it is the whole design at a size you can reason about.",
+    inputSchema: {
+      type: "object",
+      required: ["assetId"],
+      properties: {
+        assetId: { type: "string", description: "A design asset id from list_assets." }
+      }
+    },
+    handler: ctx.guard(async (input) => {
+      const asset = await loadDesign(capString(input.assetId, "assetId", 200));
+      return { content: describeDigest(asset, asset.design) };
+    })
+  };
+  const readDesignSource = {
+    name: "read_design_source",
+    description: "Read a window of a design's actual HTML source, to port exact markup or styles. Pass `find` to jump to the first occurrence of a string (a heading, a class name), or `offset` to page through. Returns at most 12000 characters.",
+    // The template is author-supplied content, not instructions.
+    outputTaint: ["tool_untrusted:read_design_source"],
+    inputSchema: {
+      type: "object",
+      required: ["assetId"],
+      properties: {
+        assetId: { type: "string" },
+        find: { type: "string", description: "Jump to the first occurrence of this string." },
+        offset: { type: "number", description: "Character offset to read from (ignored with find)." },
+        length: { type: "number", description: `Characters to return (max ${MAX_SOURCE_WINDOW}).` }
+      }
+    },
+    handler: ctx.guard(async (input) => {
+      const asset = await loadDesign(capString(input.assetId, "assetId", 200));
+      const template = await ctx.readDesignTemplate(asset.id);
+      const found = sourceWindow(template, {
+        ...typeof input.find === "string" ? { find: input.find } : {},
+        ...typeof input.offset === "number" ? { offset: input.offset } : {},
+        ...typeof input.length === "number" ? { length: input.length } : {}
+      });
+      return {
+        content: `Design ${asset.id} source, characters ${found.start}\u2013${found.end} of ${template.length}:
+` + found.text
+      };
+    })
+  };
+  const proposeFromDesign = {
+    name: "propose_palette_from_design",
+    description: "Read a design's own --ui-* token declarations back into a brand palette and park it as a proposal for human review. Use when a design already carries the brand's colors and they should become the brand book's palette. Does NOT change the brand.",
+    acceptsTaint: ["tool_untrusted:read_design_source"],
+    inputSchema: {
+      type: "object",
+      required: ["assetId", "rationale"],
+      properties: {
+        assetId: { type: "string" },
+        name: { type: "string", description: "Palette name; defaults to the design's title." },
+        rationale: { type: "string", description: "Why this design's palette should become the brand's." }
+      }
+    },
+    handler: ctx.guard(async (input) => {
+      const book = await ctx.loadBook();
+      await ctx.authority("brand.edit");
+      const asset = await loadDesign(capString(input.assetId, "assetId", 200));
+      const digest2 = asset.design;
+      const rationale = capString(input.rationale, "rationale", 2e3);
+      const name = capString(
+        input.name ?? digest2.title ?? asset.title ?? "Design palette",
+        "name",
+        120
+      );
+      const { swatches, skipped, missing: missing2 } = swatchesFromDesignTokens(digest2.tokens);
+      if (swatches.length === 0)
+        throw new BrandInputError(
+          `design ${asset.id} declares no --ui-* tokens that resolve to opaque colors; propose a palette explicitly instead.`
+        );
+      const report = contrastReport(swatches);
+      const proposal = await ctx.createProposal({
+        mutationId: ctx.newId(),
+        kind: "palette",
+        payload: { name, swatches, contrastReport: report, source: "design", designAssetId: asset.id },
+        rationale,
+        sourceAssetId: asset.id
+      });
+      if (proposal.bookId !== book.id || proposal.createdBy !== ctx.self.selfId || proposal.kind !== "palette" || proposal.status !== "open") throw new BrandInputError("brand proposal bridge returned an invalid proposal");
+      const notes = [
+        skipped.length > 0 ? `Not imported (not literal opaque colors): ${skipped.map((s) => `${s.token} \u2014 ${s.reason}`).join("; ")}.` : "",
+        missing2.length > 0 ? `Roles the design declares no token for: ${missing2.join(", ")}.` : ""
+      ].filter((n) => n !== "");
+      return {
+        content: `Parked palette proposal ${proposal.id} ("${name}") from design ${asset.id}: ${swatches.length} swatches read back from its --ui-* declarations. Contrast: ${Object.entries(report).map(([k, v]) => `${k} ${v.toFixed(2)}:1`).join(", ")}. ` + `${notes.join(" ")} Awaiting a human decision in the brand approval surface.`.trim()
+      };
+    })
+  };
+  return [readDesign, readDesignSource, proposeFromDesign];
+}
+
 // src/skill/read-tools.ts
 var iso = (ms) => new Date(ms).toISOString();
 var shortId = (id) => id.length <= 12 ? id : `${id.slice(0, 6)}\u2026${id.slice(-4)}`;
@@ -2706,10 +3455,11 @@ function readTools(ctx) {
 }
 
 // src/skill/skill.ts
-var BRAND_INSTRUCTIONS = "You help build and maintain ONE brand book. Workflow, in order:\n1. Understand the brand first: read_brand_book and list_assets before proposing anything.\n2. Look at the real material: view_asset on logos and inspiration, then record what you saw with record_asset_analysis (description, dominant colors as hex, tags).\n3. Explore with the math tools: analyze_color and evaluate_contrast. Never invent a hex without a rationale \u2014 ground every color in an asset's dominant color, a harmony companion, or a contrast fix, and say which.\n4. propose_palette parks a proposal for review. It does NOT change the brand.\n5. You cannot approve or resolve a proposal. Direct the human to the brand approval surface, which records a guarded receipt for their decision.\n6. update_section parks a proposal; it never overwrites an approved facet. Bind sourceAssetId when a real Brand asset grounds typography, voice, logo, or imagery. Human acceptance applies the exact reviewed change and automatically recompiles dependent tokens.\n7. Re-read the book after a decision and explain any compiler warnings conversationally.";
+var BRAND_INSTRUCTIONS = "You help build and maintain ONE brand book. Workflow, in order:\n1. Understand the brand first: read_brand_book and list_assets before proposing anything.\n2. Look at the real material: view_asset on logos and inspiration, then record what you saw with record_asset_analysis (description, dominant colors as hex, tags).\n3. Explore with the math tools: analyze_color and evaluate_contrast. Never invent a hex without a rationale \u2014 ground every color in an asset's dominant color, a harmony companion, or a contrast fix, and say which.\n4. When a Claude Design has been uploaded, read_design is the fastest way to learn the brand: it reports the design tokens, typefaces, props, and page outline. read_design_source reads exact markup when you need it. If the design already carries the brand colors, propose_palette_from_design reads its --ui-* declarations back into a palette proposal.\n5. propose_palette parks a proposal for review. It does NOT change the brand.\n6. You cannot approve or resolve a proposal. Direct the human to the brand approval surface, which records a guarded receipt for their decision.\n7. update_section parks a proposal; it never overwrites an approved facet. Bind sourceAssetId when a real Brand asset grounds typography, voice, logo, or imagery. Human acceptance applies the exact reviewed change and automatically recompiles dependent tokens.\n8. Re-read the book after a decision and explain any compiler warnings conversationally.";
 function brandSkill(opts) {
   if (opts.agentDbBinding.principalId !== opts.self.selfId || !opts.agentDbBinding.credentialRef) throw new BrandForbiddenError("brand db is not bound to the acting agent");
   const deps = resolveDeps({ db: opts.db, now: opts.now, newId: opts.newId });
+  const designTemplates = /* @__PURE__ */ new Map();
   const authority = (capability) => Promise.resolve(opts.authorizeCapability({
     agentId: opts.self.selfId,
     bookId: opts.bookId,
@@ -2742,6 +3492,16 @@ function brandSkill(opts) {
       bookId: opts.bookId,
       assetId
     }),
+    readDesignTemplate: (assetId) => {
+      const cached = designTemplates.get(assetId);
+      if (cached) return cached;
+      const pending = opts.agentBridge.readAssetContent({ jobId: opts.agentJobId, bookId: opts.bookId, assetId }).then(
+        (fetched) => parseDesignBundle(new TextDecoder().decode(fetched.bytes)).template
+      );
+      pending.catch(() => designTemplates.delete(assetId));
+      designTemplates.set(assetId, pending);
+      return pending;
+    },
     resolvePrincipals: (principalIds) => {
       const ids = [...new Set(principalIds)].slice(0, 100);
       return opts.resolvePrincipals({
@@ -2773,7 +3533,13 @@ function brandSkill(opts) {
   return {
     name: "brand",
     instructions: BRAND_INSTRUCTIONS,
-    tools: [...readTools(ctx), ...assetTools(ctx), ...paletteTools(ctx), ...bookTools(ctx)]
+    tools: [
+      ...readTools(ctx),
+      ...assetTools(ctx),
+      ...designTools(ctx),
+      ...paletteTools(ctx),
+      ...bookTools(ctx)
+    ]
   };
 }
 
@@ -2904,9 +3670,13 @@ async function uploadAsset(ctx, req, bookId) {
   const file = form.get("file");
   if (!(file instanceof File))
     throw new BrandInputError('"file" must be an uploaded file field');
+  const kindRaw = form.get("kind");
+  const kind = typeof kindRaw === "string" && kindRaw ? kindRaw : "other";
+  if (!ASSET_KINDS.includes(kind))
+    throw new BrandInputError(`kind must be one of: ${ASSET_KINDS.join(", ")}`);
   let contentType;
   try {
-    contentType = assertAssetContentType(file.type);
+    contentType = assertAssetContentType(file.type, kind);
   } catch (error) {
     if (error instanceof BrandInputError)
       return json({ error: error.message }, 415);
@@ -2914,10 +3684,7 @@ async function uploadAsset(ctx, req, bookId) {
   }
   if (file.size > ctx.maxUploadBytes)
     return json({ error: `file exceeds ${ctx.maxUploadBytes} bytes` }, 413);
-  const kindRaw = form.get("kind");
-  const kind = typeof kindRaw === "string" && kindRaw ? kindRaw : "other";
-  if (!ASSET_KINDS.includes(kind))
-    throw new BrandInputError(`kind must be one of: ${ASSET_KINDS.join(", ")}`);
+  const design = kind === DESIGN_ASSET_KIND ? digestDesignHtml(await file.text()) : void 0;
   const titleRaw = form.get("title");
   const title = typeof titleRaw === "string" && titleRaw ? capString(titleRaw, "title", 160) : void 0;
   const fileName = safeFileName(file.name);
@@ -2965,6 +3732,7 @@ async function uploadAsset(ctx, req, bookId) {
       uploadedAuthorityRef: authority.authorityRef,
       audience: book.memberIds,
       title,
+      ...design ? { design } : {},
       now: ctx.now()
     }), {
       mutationId: `brand:asset-upload:v1:${id}`,
@@ -3206,6 +3974,51 @@ async function handleBookItem(ctx, req, bookId) {
   return json(await loadMemberBook(ctx.db, bookId, ctx.actor.id));
 }
 
+// src/routes/design-preview.ts
+var SIGNED_READ_TTL_SECONDS = 60;
+function designPreviewHeaders(frameAncestors) {
+  return {
+    "content-type": "text/html; charset=utf-8",
+    "content-security-policy": [
+      "sandbox allow-scripts",
+      `frame-ancestors ${frameAncestors.join(" ")}`
+    ].join("; "),
+    "x-content-type-options": "nosniff",
+    "referrer-policy": "no-referrer",
+    "cache-control": "private, no-store"
+  };
+}
+async function handleDesignPreview(ctx, req, bookId, assetId) {
+  if (req.method !== "GET") return methodNotAllowed();
+  const book = await loadMemberBook(ctx.db, bookId, ctx.actor.id);
+  const asset = await linkedAsset(ctx, book, assetId);
+  if (asset.kind !== DESIGN_ASSET_KIND) throw new BrandNotFoundError(`design ${assetId}`);
+  const signed = await ctx.db.storage.sign(asset.path, SIGNED_READ_TTL_SECONDS);
+  const fetched = await ctx.fetchPrivateAsset(signed, {
+    headers: { accept: "text/html" },
+    redirect: "manual",
+    signal: req.signal
+  });
+  if (!fetched.ok || fetched.type === "opaqueredirect")
+    throw new BrandNotFoundError(`design ${assetId}`);
+  return new Response(new Uint8Array(await fetched.arrayBuffer()), {
+    status: 200,
+    headers: designPreviewHeaders(ctx.previewFrameAncestors)
+  });
+}
+async function handleDesignDigest(ctx, req, bookId, assetId) {
+  if (req.method !== "GET") return methodNotAllowed();
+  const book = await loadMemberBook(ctx.db, bookId, ctx.actor.id);
+  const asset = await linkedAsset(ctx, book, assetId);
+  if (asset.kind !== DESIGN_ASSET_KIND || !asset.design)
+    throw new BrandNotFoundError(`design ${assetId}`);
+  return json(
+    { assetId: asset.id, title: asset.title, digest: asset.design },
+    200,
+    { "cache-control": "private, no-store" }
+  );
+}
+
 // src/routes/proposal-input.ts
 var SNAPSHOT_KEYS = [
   "audience",
@@ -3426,13 +4239,13 @@ async function proposalDecisionOps(input) {
 
 // src/routes/proposal-resolution-receipts.ts
 async function proposalResolutionMutationKey(bookId, proposalId, mutationId) {
-  const digest = await brandJsonDigest({
+  const digest2 = await brandJsonDigest({
     version: 3,
     bookId,
     proposalId,
     mutationId
   });
-  return `brand:proposal-resolution:v3:${digest.slice("sha256:".length)}`;
+  return `brand:proposal-resolution:v3:${digest2.slice("sha256:".length)}`;
 }
 async function proposalReceiptByMutation(ctx, mutationKey) {
   const result = await ctx.db.query({
@@ -3982,6 +4795,130 @@ async function handleTokens(db, req, bookId, which, actor) {
   });
 }
 
+// src/routes/discussion-asset.ts
+var MAX_DISCUSSION_ASSET_BYTES = 4718592;
+var SIGN_TTL_SECONDS = 30;
+var TYPES = /* @__PURE__ */ new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "application/pdf"
+]);
+var bare = (value) => (value?.split(";", 1)[0] ?? "").trim().toLowerCase();
+var starts = (bytes, expected) => expected.every((value, index) => bytes[index] === value);
+function magicMatches(contentType, bytes) {
+  if (contentType === "image/png") {
+    return starts(bytes, [137, 80, 78, 71, 13, 10, 26, 10]);
+  }
+  if (contentType === "image/jpeg") {
+    return starts(bytes, [255, 216, 255]);
+  }
+  const prefix = new TextDecoder().decode(bytes.subarray(0, 16));
+  if (contentType === "image/gif") {
+    return prefix.startsWith("GIF87a") || prefix.startsWith("GIF89a");
+  }
+  if (contentType === "image/webp") {
+    return prefix.startsWith("RIFF") && prefix.slice(8, 12) === "WEBP";
+  }
+  return contentType === "application/pdf" && prefix.startsWith("%PDF-");
+}
+async function boundedBytes(response, max) {
+  const length = Number(response.headers.get("content-length"));
+  if (Number.isFinite(length) && length > max) return null;
+  if (!response.body) return new Uint8Array();
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const next = await reader.read();
+    if (next.done) break;
+    total += next.value.byteLength;
+    if (total > max) {
+      await reader.cancel();
+      return null;
+    }
+    chunks.push(next.value);
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+async function digest(bytes) {
+  const value = await crypto.subtle.digest("SHA-256", bytes.slice().buffer);
+  return `sha256:${[...new Uint8Array(value)].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+function exactAsset(beforeBook, before, afterBook, after) {
+  return afterBook.id === beforeBook.id && after.id === before.id && after.bookId === before.bookId && after.status === "live" && after.path === before.path && after.storageObjectId === before.storageObjectId && after.contentDigest === before.contentDigest && after.contentType === before.contentType && after.size === before.size;
+}
+function safeSignedUrl(value) {
+  try {
+    const url = new URL(value);
+    return value.length <= 4096 && url.protocol === "https:" && !url.username && !url.password ? url : null;
+  } catch {
+    return null;
+  }
+}
+async function handleBrandDiscussionAsset(ctx, req, target) {
+  const beforeBook = await loadMemberBook(ctx.db, target.bookId, ctx.actor.id);
+  const before = await linkedAsset(ctx, beforeBook, target.resourceId);
+  const contentType = bare(before.contentType);
+  if (!TYPES.has(contentType)) {
+    return json({ error: "asset content type is not viewable" }, 415);
+  }
+  if (before.size < 1 || before.size > MAX_DISCUSSION_ASSET_BYTES) {
+    return json({ error: "asset exceeds the discussion media limit" }, 413);
+  }
+  const signed = safeSignedUrl(
+    await ctx.db.storage.sign(before.path, SIGN_TTL_SECONDS)
+  );
+  if (!signed) throw new BrandInputError("private asset signing failed");
+  const response = await ctx.fetchPrivateAsset(signed, {
+    headers: { accept: contentType },
+    redirect: "manual",
+    signal: req.signal
+  });
+  if (!response.ok || response.type === "opaqueredirect") {
+    throw new BrandNotFoundError(`asset ${before.id}`);
+  }
+  const served = bare(response.headers.get("content-type"));
+  if (served === "image/svg+xml" || served && served !== "application/octet-stream" && served !== contentType) {
+    return json({ error: "asset content type is inconsistent" }, 415);
+  }
+  const bytes = await boundedBytes(response, MAX_DISCUSSION_ASSET_BYTES);
+  if (!bytes || bytes.byteLength !== before.size || !magicMatches(contentType, bytes) || await digest(bytes) !== before.contentDigest) {
+    return json({ error: "asset bytes failed validation" }, 422);
+  }
+  const afterBook = await loadMemberBook(ctx.db, target.bookId, ctx.actor.id);
+  const after = await linkedAsset(ctx, afterBook, target.resourceId);
+  if (!exactAsset(beforeBook, before, afterBook, after)) {
+    return json({ error: "asset changed during inspection" }, 409);
+  }
+  return json({
+    asset: {
+      reference: { kind: "brand:asset", id: `${before.bookId}/${before.id}` },
+      contentType,
+      byteLength: bytes.byteLength,
+      data: base64(bytes),
+      taint: "untrusted_project_material"
+    }
+  }, 200, {
+    "cache-control": "private, no-store",
+    "x-content-type-options": "nosniff"
+  });
+}
+function base64(bytes) {
+  let binary = "";
+  for (let index = 0; index < bytes.length; index += 8192) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + 8192));
+  }
+  return btoa(binary);
+}
+
 // src/routes/discussion-references.ts
 var capLimit = (raw) => {
   const parsed = Number(raw ?? 20);
@@ -4013,6 +4950,7 @@ var projection = (req, ctx, book, target, row) => {
   let summary = `${book.name} brand book`;
   let status = book.status;
   let destination = "Brand Studio \xB7 Brand book";
+  let swatches;
   if (target.kind === "brand:asset") {
     const asset = row;
     label = asset.title?.trim() || `${asset.kind} asset`;
@@ -4022,6 +4960,11 @@ var projection = (req, ctx, book, target, row) => {
     destination = "Brand Studio \xB7 Conversation";
   } else if (target.kind === "brand:palette") {
     const palette = row;
+    swatches = assertSwatches(palette.swatches).map((swatch) => ({
+      role: swatch.role,
+      hex: swatch.hex,
+      ...swatch.name ? { name: swatch.name } : {}
+    }));
     label = palette.name;
     hint = `${book.name} \xB7 ${palette.status} palette`;
     summary = `${palette.swatches.length}-color palette in ${book.name}`;
@@ -4054,7 +4997,8 @@ var projection = (req, ctx, book, target, row) => {
       new URL(req.url),
       target,
       ctx.discussionBasePath
-    )
+    ),
+    ...swatches ? { swatches } : {}
   };
 };
 async function exact(ctx, req, target) {
@@ -4108,11 +5052,23 @@ async function search(ctx, req, url) {
 }
 async function handleBrandDiscussionReferences(ctx, req, url) {
   if (req.method !== "GET") return methodNotAllowed();
+  const inspect = url.searchParams.get("inspect");
   const kind = url.searchParams.get("kind");
   const id = url.searchParams.get("id");
   if (kind && !id || !kind && id) return json({ error: "kind and id must be paired" }, 400);
   const target = targetFromQuery(url);
   if ((kind || id) && !target) return json({ items: [] });
+  if (inspect === "asset-content") {
+    const allowed = /* @__PURE__ */ new Set(["inspect", "kind", "id"]);
+    if ([...url.searchParams.keys()].some((key) => !allowed.has(key)) || target?.kind !== "brand:asset" || !target.resourceId) return json({ error: "exact brand asset kind and id required" }, 400);
+    return handleBrandDiscussionAsset(ctx, req, {
+      bookId: target.bookId,
+      resourceId: target.resourceId
+    });
+  }
+  if (inspect !== null && inspect !== "1") {
+    return json({ error: "invalid inspection mode" }, 400);
+  }
   return json({
     items: target ? await exact(ctx, req, target) : await search(ctx, req, url)
   });
@@ -4133,6 +5089,10 @@ async function route(ctx, req, url, seg) {
     if (seg.length === 4) return handleAssetItem(ctx, req, id, subId);
     if (seg.length === 5 && action === "content")
       return handleAssetContent(ctx, req, id, subId);
+    if (seg.length === 5 && action === "preview")
+      return handleDesignPreview(ctx, req, id, subId);
+    if (seg.length === 5 && action === "design")
+      return handleDesignDigest(ctx, req, id, subId);
     return null;
   }
   if (sub === "proposals" && seg.length === 5 && action === "resolve")
@@ -4153,7 +5113,9 @@ function createBrandRoutes(options) {
     now: options.now ?? Date.now,
     newId: options.newId ?? (() => crypto.randomUUID()),
     maxUploadBytes: options.maxUploadBytes ?? 8 * 1024 * 1024,
-    discussionBasePath: options.discussionBasePath ?? "/"
+    discussionBasePath: options.discussionBasePath ?? "/",
+    fetchPrivateAsset: options.fetchPrivateAsset ?? fetch,
+    previewFrameAncestors: options.previewFrameAncestors ?? ["'self'"]
   };
   return async (req) => {
     const url = new URL(req.url);