@prenta/admin 0.92.0 → 0.93.0

package/src/lib/reflow-baseline.ts

@@ -0,0 +1,70 @@
+import type { PageSection } from '@prenta/core/page-sections'
+
+/**
+ * The content a page's sections had when they were last live.
+ *
+ * ── What "baseline" means here, and why ───────────────────────────────────
+ *
+ * The guard answers "will this edit change how the live page wraps?" — so the
+ * baseline has to be what is actually on the site, not what was last saved.
+ *
+ * This CMS has no draft/published split: a document carries one `status` and
+ * saving a PUBLISHED page updates the live content in place. So for a published
+ * page the live content is whatever the editor loaded, refreshed on every save
+ * and publish. For a page that has never been published there is no baseline at
+ * all, and the guard reports line counts without deltas — correctly, because
+ * there is no live layout to break.
+ *
+ * Deliberately NOT sourced from the versions API. Versions do hold full
+ * snapshots, but they record every update, so finding "the published one" means
+ * scanning history and guessing which entry was live — an extra request and a
+ * heuristic, to reconstruct something the editor already has in hand.
+ */
+export interface ReflowBaseline {
+  byId: Map<string, Record<string, unknown>>
+}
+
+/**
+ * Snapshot section content, or `null` when the page is not live.
+ *
+ * `null` rather than an empty snapshot: an empty baseline would read as "every
+ * field was previously blank" and flag every line of existing copy as newly
+ * added.
+ */
+export function snapshotBaseline(
+  sections: readonly PageSection[],
+  status: string,
+): ReflowBaseline | null {
+  if (status !== 'PUBLISHED') return null
+  return {
+    byId: new Map(sections.map((s) => [s.id, { ...(s.content ?? {}) }])),
+  }
+}
+
+/**
+ * Resolve a `data-cms-field` path against a baseline.
+ *
+ * Paths are dotted and may index arrays (`stats.0.label`), matching the markers
+ * the renderers emit.
+ *
+ * Returns `undefined` for anything that is not baseline text — no snapshot, a
+ * section added since publish, a field that did not exist, or a non-string
+ * value. The guard reads `undefined` as "nothing to compare against" and
+ * reports no delta, which is the truthful answer in every one of those cases.
+ */
+export function baselineFieldText(
+  baseline: ReflowBaseline | null,
+  sectionId: string,
+  fieldPath: string,
+): string | undefined {
+  const content = baseline?.byId.get(sectionId)
+  if (!content) return undefined
+
+  let cursor: unknown = content
+  for (const key of fieldPath.split('.')) {
+    if (cursor === null || typeof cursor !== 'object') return undefined
+    cursor = (cursor as Record<string, unknown>)[key]
+  }
+
+  return typeof cursor === 'string' ? cursor : undefined
+}

package/src/lib/reflow-probe.ts

@@ -0,0 +1,299 @@
+import { BREAKPOINTS, type BreakpointId } from './breakpoints.js'
+
+/**
+ * Measures how a field's copy wraps at every breakpoint, by laying it out for
+ * real rather than estimating.
+ *
+ * ── Why not a class chain ─────────────────────────────────────────────────
+ *
+ * The design handoff specifies rebuilding each probe from a hardcoded list of
+ * wrapper classes per guarded field, and warns twice that a width cap outside
+ * that list makes the guard lie — at wide breakpoints only, so it looks correct
+ * on mobile. By the handoff's own account that list drifted twice.
+ *
+ * A chain is a second source of truth that has to track the renderers' markup
+ * by hand. Worse here: the prototype had semantic classes (`.pv-hero-h`), while
+ * these components are styled with Tailwind utility strings that Prettier's
+ * plugin reorders on save. And a chain written in the admin cannot describe a
+ * consumer's own registered renderer at all.
+ *
+ * So the probe measures the REAL element: the caller renders the actual section
+ * into a hidden host, and this module finds the field by its `data-cms-field`
+ * marker — the same attribute the click-to-edit bridge uses. There is nothing
+ * to keep in sync, and a renderer refactor cannot silently invalidate it.
+ *
+ * ── Why one host, resized ─────────────────────────────────────────────────
+ *
+ * Six widths are measured by resizing a single rendered copy, not by rendering
+ * six. Layout is recomputed either way; React reconciliation is not.
+ */
+
+/** A field's wrap count at one breakpoint. */
+export interface FieldLineCount {
+  id: BreakpointId
+  lines: number
+}
+
+/**
+ * Line count from an element's laid-out height.
+ *
+ * Falls back to `fontSize * 1.25` when `line-height` computes to `normal`,
+ * which it does for any element that never set one. Rounding rather than
+ * flooring: sub-pixel line heights accumulate, and 2.97 lines is three.
+ */
+export function linesFromMetrics(height: number, lineHeight: number, fontSize: number): number {
+  const effective = Number.isFinite(lineHeight) && lineHeight > 0 ? lineHeight : fontSize * 1.25
+  if (!Number.isFinite(effective) || effective <= 0) return 1
+  // An empty field still occupies one line's worth of intent.
+  return Math.max(1, Math.round(height / effective))
+}
+
+/**
+ * How many lines an element's text actually occupies.
+ *
+ * Counts LINE BOXES via a Range over the element's contents, deduplicated by
+ * their top edge. Dividing the element's height by its line-height — the
+ * obvious approach, and what the prototype does — counts padding as text: a
+ * button reading "Get Started" measured 2 lines, because its vertical padding
+ * came to roughly another line's worth of height. Every padded element was
+ * over-reported, which is most CTAs and every boxed heading.
+ *
+ * Rects are deduplicated by rounded top edge because a range spanning nested
+ * inline elements (a `<strong>` mid-sentence, an icon in a button) yields one
+ * rect per fragment, not per line.
+ *
+ * Falls back to the height ratio when the range produces nothing — an element
+ * whose content is a single replaced node, or a layout engine that gives no
+ * rects for empty text.
+ */
+export function countLines(el: HTMLElement): number {
+  const doc = el.ownerDocument
+  try {
+    const range = doc.createRange()
+    range.selectNodeContents(el)
+    const rects = Array.from(range.getClientRects()).filter((r) => r.height > 0)
+    range.detach?.()
+    if (rects.length > 0) {
+      const tops = new Set(rects.map((r) => Math.round(r.top)))
+      return Math.max(1, tops.size)
+    }
+  } catch {
+    // No Range support (or a detached document) — fall through to metrics.
+  }
+
+  const cs = getComputedStyle(el)
+  return linesFromMetrics(
+    el.getBoundingClientRect().height,
+    Number.parseFloat(cs.lineHeight),
+    Number.parseFloat(cs.fontSize),
+  )
+}
+
+/**
+ * The off-screen host.
+ *
+ * `left: -99999px`, never `display: none` — a hidden element has no layout, so
+ * every measurement would be zero. `visibility: hidden` would keep layout but
+ * also keep the element in the accessibility tree; moving it off-screen and
+ * marking it `aria-hidden` keeps it out of both the viewport and the a11y tree
+ * while still being laid out.
+ *
+ * MOUNT IT INSIDE `.prenta-admin`, never on `document.body`. Type tokens and
+ * the font stack are scoped to that root, so a host outside it lays text out in
+ * the document's default font and every measurement is taken at the wrong
+ * metrics. Caught by `e2e/reflow-probe.spec.ts` on its first run: a button
+ * measured 127px on the canvas and 139px in a body-mounted probe.
+ *
+ * Use `mountProbeHost` rather than appending by hand.
+ */
+export function createProbeHost(doc: Document = document): HTMLElement {
+  const host = doc.createElement('div')
+  host.setAttribute('aria-hidden', 'true')
+  host.dataset.reflowProbe = 'true'
+  Object.assign(host.style, {
+    position: 'fixed',
+    left: '-99999px',
+    top: '0',
+    // Never inherit the rail's width — the probe sets its own per breakpoint.
+    width: 'auto',
+    pointerEvents: 'none',
+  })
+  return host
+}
+
+/**
+ * Attach a probe host in the only place it measures correctly.
+ *
+ * Returns a detach function. Falls back to `document.body` only when no admin
+ * root exists (it always does in the app) — and callers should treat a
+ * fallback mount as untrustworthy rather than silently measuring.
+ */
+export function mountProbeHost(
+  host: HTMLElement,
+  doc: Document = document,
+): { detach: () => void; scoped: boolean } {
+  const root = doc.querySelector('.prenta-admin')
+  const parent = root ?? doc.body
+  parent.appendChild(host)
+  return { detach: () => host.remove(), scoped: Boolean(root) }
+}
+
+/**
+ * Measure one field across every breakpoint.
+ *
+ * `container` must carry the same class chain the canvas uses
+ * (`prenta-canvas`, which supplies the query container). Its width is set per
+ * breakpoint, so it must not be width-constrained by a parent.
+ *
+ * `scope` narrows to one section and is REQUIRED whenever the container holds
+ * more than one, because `data-cms-field` paths are unique only within a
+ * section — every section has a `heading` and a `body`. Without it a whole page
+ * silently measures the first section's field and reports it for all of them.
+ * (That mistake is what `e2e/reflow-probe.spec.ts` caught on its second run.)
+ *
+ * Returns `null` when the field cannot be found — the canvas is rendering a
+ * component without `data-cms-field` markers, so there is nothing to measure.
+ * Reporting a line count from the wrong element would be worse than reporting
+ * none: an editor reads a number as a fact.
+ */
+export function measureFieldAcrossBreakpoints(
+  container: HTMLElement,
+  fieldPath: string,
+  scope?: string,
+): FieldLineCount[] | null {
+  const field = `[data-cms-field="${CSS.escape(fieldPath)}"]`
+  const selector = scope ? `${scope} ${field}` : field
+  if (!container.querySelector(selector)) return null
+
+  const previousWidth = container.style.width
+  const out: FieldLineCount[] = []
+
+  for (const bp of BREAKPOINTS) {
+    container.style.width = `${bp.width}px`
+    // Re-query inside the loop: a renderer may swap elements between layouts
+    // (a grid that becomes a stack can remount its children).
+    const el = container.querySelector(selector)
+    out.push({ id: bp.id, lines: el ? countLines(el as HTMLElement) : 1 })
+  }
+
+  container.style.width = previousWidth
+  return out
+}
+
+/** What a probe pass produces for one field. */
+export interface FieldReflow {
+  current: FieldLineCount[]
+  baseline: FieldLineCount[]
+}
+
+/**
+ * Measure a field's wrapping now and as published, from the live canvas.
+ *
+ * The whole `.prenta-canvas` is cloned, not just the target section. Cloning
+ * the section alone would require rebuilding whatever sits between the canvas
+ * root and the section — which is the class-chain problem again, in a smaller
+ * disguise. `e2e/reflow-probe.spec.ts` asserts the whole-canvas clone
+ * reproduces every field's rendered width exactly; nothing asserts that for a
+ * hand-rebuilt wrapper.
+ *
+ * The baseline is measured by writing the published string into the SAME cloned
+ * element and re-measuring, rather than by rendering the published section. The
+ * two differ in exactly one field, so everything else — width caps, siblings,
+ * grid tracks — is held identical by construction rather than by hoping a second
+ * render matches.
+ *
+ * `baselineText` of `undefined` means the field has no published version (a new
+ * section), so there is no change to report and current is echoed as baseline.
+ *
+ * Returns `null` when the section or field is absent from the canvas — a
+ * consumer's renderer may carry no `data-cms-field` markers, and a line count
+ * read off the wrong element is worse than none.
+ */
+export function probeFieldReflow(options: {
+  canvas: HTMLElement
+  sectionId: string
+  fieldPath: string
+  baselineText: string | undefined
+  doc?: Document
+}): FieldReflow | null {
+  const { canvas, sectionId, fieldPath, baselineText, doc = document } = options
+
+  const sectionSel = `[data-section-id="${CSS.escape(sectionId)}"]`
+  const fieldSel = `${sectionSel} [data-cms-field="${CSS.escape(fieldPath)}"]`
+  if (!canvas.querySelector(fieldSel)) return null
+
+  const host = createProbeHost(doc)
+  const clone = canvas.cloneNode(true) as HTMLElement
+  // The canvas is scaled to fit its column. A transform does not change layout
+  // width, but it does scale the measured rects — and line height is read from
+  // a rect. Left on, every count would be off by the scale factor.
+  clone.style.transform = 'none'
+  clone.style.maxWidth = 'none'
+  host.appendChild(clone)
+
+  const { detach, scoped } = mountProbeHost(host, doc)
+  // Outside `.prenta-admin` the type tokens don't apply and every measurement
+  // is taken in the document's default font. Report nothing rather than that.
+  if (!scoped) {
+    detach()
+    return null
+  }
+
+  try {
+    const current = measureFieldAcrossBreakpoints(clone, fieldPath, sectionSel)
+    if (!current) return null
+    if (baselineText === undefined) return { current, baseline: current }
+
+    const el = clone.querySelector(fieldSel)
+    if (!el) return { current, baseline: current }
+    el.textContent = baselineText
+    const baseline = measureFieldAcrossBreakpoints(clone, fieldPath, sectionSel)
+    return { current, baseline: baseline ?? current }
+  } finally {
+    detach()
+  }
+}
+
+export type ReflowSeverity = 'same' | 'grew' | 'grew-badly'
+
+/**
+ * Compare a field's current wrapping against its published baseline.
+ *
+ * Only growth is flagged. Copy that got shorter cannot break a layout that
+ * already held the longer version, so reporting it would be noise on exactly
+ * the edit an editor was asked to make.
+ */
+export function reflowSeverity(current: number, baseline: number): ReflowSeverity {
+  const delta = current - baseline
+  if (delta <= 0) return 'same'
+  return delta === 1 ? 'grew' : 'grew-badly'
+}
+
+/**
+ * The breakpoint worth proofing on: the biggest jump, and on a tie the
+ * narrowest width. A tie means the same damage happens at several sizes, and
+ * the narrowest is where it is most likely to look broken.
+ */
+export function worstBreakpoint(
+  current: FieldLineCount[],
+  baseline: FieldLineCount[],
+): BreakpointId | null {
+  const widthOf = (id: BreakpointId) => BREAKPOINTS.find((b) => b.id === id)?.width ?? 0
+  let worst: { id: BreakpointId; delta: number } | null = null
+
+  for (const c of current) {
+    const b = baseline.find((x) => x.id === c.id)
+    if (!b) continue
+    const delta = c.lines - b.lines
+    if (delta <= 0) continue
+    if (
+      !worst ||
+      delta > worst.delta ||
+      (delta === worst.delta && widthOf(c.id) < widthOf(worst.id))
+    ) {
+      worst = { id: c.id, delta }
+    }
+  }
+
+  return worst?.id ?? null
+}

package/src/lib/seo-service.ts

@@ -11,6 +11,7 @@
 import type { BrandAlignmentScoreResult } from '@prenta/core/brand-voice'
 import type { SEOAnalysisResult } from '@prenta/core/seo/analysis'
 import { cmsApi } from './api.js'
+import type { MaxImagePreview } from '@prenta/core/seo/robots-directives'
 
 /**
  * `cmsApi` never throws — it returns `{ error, status }` on a network/HTTP
@@ -182,6 +183,12 @@ export interface SeoContentRecord {
   twitterImageId: string | null
   noindex: boolean
   nofollow: boolean
+  /** Blocks text snippets, and with them AI Overview and chat citations. */
+  nosnippet: boolean
+  /** Blocks cached copies. */
+  noarchive: boolean
+  /** Largest image preview a result may show. */
+  maxImagePreview: MaxImagePreview
   structuredDataType: string | null
   structuredData: Record<string, unknown> | null
   /** llms.txt curation: AUTO (heuristic), ALWAYS (pin), NEVER (exclude). */
@@ -232,6 +239,9 @@ export interface SeoFieldPayload {
   twitterImage?: string
   noindex?: boolean
   nofollow?: boolean
+  nosnippet?: boolean
+  noarchive?: boolean
+  maxImagePreview?: MaxImagePreview
   structuredDataType?: string
   structuredData?: Record<string, unknown>
   llmsInclude?: LlmsInclude

package/src/styles/prenta-tokens.css

@@ -1,29 +1,39 @@
 /*
  * PrentaCMS design tokens — scoped to the admin root.
- * Source: design-system/tokens.json (v1.0).
- * Appearance accent overrides set --acc / --primary at runtime.
+ * GENERATED FILE — DO NOT EDIT. Source: design-system/tokens.json.
+ * Regenerate: pnpm --filter @prenta/admin generate
+ *
+ * Scoped to .prenta-admin rather than :root on purpose: the admin renders
+ * inside consumer applications, and custom properties resolve by INHERITANCE,
+ * not by specificity — a host site's :root would otherwise win against every
+ * admin rule reading these names. Appearance settings mutate --acc / --primary
+ * at runtime on this same element.
  */
 
 .prenta-admin {
   /* Surfaces */
-  --bg: #f5f4fa;
-  --sb: #ffffff;
-  --card: #ffffff;
-  --bdr: #e8e6f2;
+  --bg: #f5f4fa; /* App background */
+  --sb: #ffffff; /* Sidebar / topbar surface */
+  --card: #ffffff; /* Card / panel surface */
+  --bdr: #e8e6f2; /* Hairline border */
 
   /* Text */
-  --txt: #1a1827;
-  --sub: #6b6878;
-  /* Deviates from tokens.json's #B0ADBE (2.2:1 on white — illegible). The
-     admin uses --muted as real text (section labels, hints, icons), so it
-     must meet WCAG AA (>=4.5:1) on --card and --bg while staying one step
-     lighter than --sub to preserve the text hierarchy. */
+  --txt: #1a1827; /* Primary text */
+  --sub: #6b6878; /* Secondary text */
+  /*
+   * Tertiary text. The handoff value #B0ADBE is 2.2:1 on --card — below WCAG
+   * AA. The admin uses --muted as real text (section labels, check hints,
+   * canvas meta line, character counters), so it is darkened to 4.6:1 while
+   * staying one step lighter than --sub to preserve the hierarchy. Do not
+   * revert without also changing every --muted consumer to decorative use.
+   * Handoff value: #b0adbe — deliberately overridden.
+   */
   --muted: #716e83;
 
   /* Accent */
-  --acc: #7c3aed;
-  --acc-l: #ede9fe;
-  --acc-m: #c4b5fd;
+  --acc: #7c3aed; /* Accent / interactive */
+  --acc-l: #ede9fe; /* Accent tint (hover/active bg) */
+  --acc-m: #c4b5fd; /* Accent mid (focus ring) */
 
   /* Semantic */
   --suc: #059669;
@@ -35,11 +45,7 @@
   --info: #0891b2;
   --info-l: #e0f7fa;
 
-  /*
-   * Page / post-type tag palette — distinct editorial hues.
-   * Kept separate from status tokens so "pink" is not warning orange and
-   * "blue" is not info cyan. Soft companions tint pill backgrounds.
-   */
+  /* Tag palette */
   --tag-purple: #7c3aed;
   --tag-purple-soft: #f3e8ff;
   --tag-green: #0f766e;
@@ -60,56 +66,123 @@
   --ai2: #c026d3;
   --ai-soft: linear-gradient(135deg, rgba(124, 58, 237, 0.09), rgba(192, 38, 211, 0.07));
 
+  /* Controls */
+  /*
+   * Switch knob stays white in both themes per the design system; tokenized so
+   * a consumer theme can move it.
+   */
+  --toggle-thumb: #ffffff;
+
+  /* Type */
+  /*
+   * UI text. Self-hosted woff2 under design-system/fonts — never a third-party
+   * request, because the admin renders inside consumer applications.
+   */
+  --font-sans: 'DM Sans', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  /* Code, robots directives, token names */
+  --font-mono: 'DM Mono', ui-monospace, 'SFMono-Regular', monospace;
+  --fw-reg: 450;
+  --fw-med: 500;
+  --fw-semi: 600;
+  --fw-bold: 700;
+  --fs-page: 21px; /* Page title */
+  --fs-card: 14px; /* Card / section title */
+  --fs-body: 13px; /* Body, controls, table cells */
+  --fs-sub: 12px; /* Secondary / captions */
+  --fs-hint: 11.5px; /* Hints, metadata */
+  --fs-label: 10px; /* Section labels */
+
   /* Layout */
   --sbw: 224px;
   --sbw-col: 60px;
   --tbh: 56px;
-  --r: 10px;
-  --r-control: 8px;
-  --r-sm: 6px;
-  --r-pill: 99px;
 
-  /* Elevation */
-  --shd: 0 1px 2px rgba(0, 0, 0, 0.05), 0 1px 4px rgba(0, 0, 0, 0.04);
-  --shd2: 0 4px 16px rgba(0, 0, 0, 0.1);
+  /* Radius */
+  --r-sm: 6px; /* Small buttons, badges, tags, chips-in-rows */
+  --r-field: 7px; /* Text inputs, textareas, selects */
+  /*
+   * Primary / secondary buttons, dropdowns. --r-control is the pre-2.0 name,
+   * kept resolving for existing rules.
+   */
+  --r-ctl: 8px;
+  --r-control: var(--r-ctl); /* deprecated alias */
+  --r: 10px; /* Cards and panels */
+  --r-fig: 12px; /* Canvas figures and media frames */
+  --r-pill: 99px; /* Toggles, meters, notice pills */
+
+  /* Spacing */
+  --sp-2: 2px;
+  --sp-4: 4px;
+  --sp-6: 6px;
+  --sp-8: 8px;
+  --sp-10: 10px;
+  --sp-12: 12px; /* Row padding-y */
+  --sp-14: 14px; /* Panel padding */
+  --sp-16: 16px; /* Editor header padding-x */
+  --sp-18: 18px; /* Canvas gutter top */
+  --sp-20: 20px;
+  --sp-24: 24px; /* Canvas gutter sides */
+  --sp-28: 28px;
+  --sp-32: 32px;
+  --sp-40: 40px; /* Canvas gutter bottom */
+
+  /* Control sizing */
+  --h-chip: 26px; /* Rail buttons, theme toggle */
+  --h-field: 33px; /* Text inputs and small buttons */
+  --h-ctl: 34px; /* Header controls: icon buttons, breakpoint trigger, zoom chip, SEO chip */
+
+  /* Border */
+  --bw: 1px;
+  --bw-ctl: 1.5px; /* Input and card border */
+  --bw-focus: 2px; /* Focus and active outline */
+  --ring: 0 0 0 3px var(--acc-m); /* Focus ring shadow */
 
-  /* Typography */
-  --font-sans: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-  --font-mono: 'DM Mono', ui-monospace, 'SFMono-Regular', monospace;
-  --fs-page: 21px;
-  --fs-card: 14px;
-  --fs-body: 13px;
-  --fs-sub: 12px;
-  --fs-hint: 11.5px;
-  --fs-label: 10px;
+  /* Elevation */
+  --shd: 0 1px 2px rgba(0, 0, 0, 0.05), 0 1px 4px rgba(0, 0, 0, 0.04); /* Card resting */
+  --shd2: 0 4px 16px rgba(0, 0, 0, 0.1); /* Popovers, modals, hover */
 
   /* Motion */
-  --motion-fast: 0.12s;
-  --motion-base: 0.18s;
+  --mo-fast: 0.12s; /* Hover, color */
+  --motion-fast: var(--mo-fast); /* deprecated alias */
+  --mo-base: 0.18s; /* Toggles, reveals */
+  --motion-base: var(--mo-base); /* deprecated alias */
+  --mo-slow: 0.22s; /* Panels, canvas scale */
+  --ease: cubic-bezier(0.4, 0, 0.2, 1);
+  /* Pre-2.0 composite. Use --mo-slow var(--ease) instead. */
   --motion-layout: 0.22s cubic-bezier(0.4, 0, 0.2, 1);
 
-  /* Controls — the toggle thumb stays white in both modes per the design
-     system (.tog-thumb { background: #fff }), tokenized for themeability. */
-  --toggle-thumb: #ffffff;
+  /* Layering */
+  --z-raise: 2; /* Canvas section labels, sticky group headers */
+  --z-resizer: 30; /* Panel drag handle */
+  --z-overlay: 45; /* In-panel overlays (version history) */
+  --z-menu: 120; /* Dropdowns, flyouts */
+  --z-toast: 200;
 }
 
 .dark .prenta-admin,
 .prenta-admin.dark,
 .prenta-admin[data-theme='dark'] {
+  /* Surfaces */
   --bg: #0d0c18;
   --sb: #141222;
   --card: #1c1a2e;
   --bdr: #2c2a42;
 
+  /* Text */
   --txt: #eae8f5;
   --sub: #8e8ba8;
-  /* Same AA deviation as light mode (tokens.json #504E68 is 2.1:1 on card). */
+  /*
+   * Same AA correction as light mode — the handoff value #504E68 is 2.1:1 on
+   * --card. Handoff value: #504e68 — deliberately overridden.
+   */
   --muted: #8784a2;
 
+  /* Accent */
   --acc: #9d71f0;
   --acc-l: #231950;
   --acc-m: #5e3eaa;
 
+  /* Semantic */
   --suc: #10b981;
   --suc-l: #022c22;
   --warn: #fbbf24;
@@ -119,6 +192,7 @@
   --info: #38bdf8;
   --info-l: #0a2838;
 
+  /* Tag palette */
   --tag-purple: #a78bfa;
   --tag-purple-soft: #2e1065;
   --tag-green: #2dd4bf;
@@ -134,8 +208,12 @@
   --tag-gray: #94a3b8;
   --tag-gray-soft: #1e293b;
 
+  /* AI */
+  --ai1: #7c3aed;
+  --ai2: #c026d3;
   --ai-soft: linear-gradient(135deg, rgba(157, 113, 240, 0.16), rgba(192, 38, 211, 0.12));
 
+  /* Elevation */
   --shd: 0 1px 2px rgba(0, 0, 0, 0.3), 0 1px 4px rgba(0, 0, 0, 0.2);
   --shd2: 0 4px 20px rgba(0, 0, 0, 0.45);
 }