@proveanything/smartlinks 2.0.15 → 2.0.17

package/dist/theme-boot.js

@@ -0,0 +1,78 @@
+/* @proveanything/smartlinks/theme-boot.js — iframe theme + viewer-prefs bootstrap (theme tokens v1)
+ *
+ * ONLY for iframe / standalone app entries (admin.html, index.html). Container & widget apps do NOT
+ * need this — they inherit the host's :root tokens through the DOM. See docs/theme-tokens.md.
+ *
+ * What it does, and nothing more:
+ *   1. BOOT (synchronous, before first paint): reads the initial theme + viewer prefs from the URL
+ *      (`#slt=<base64url JSON>` plus convenience params ?theme=&contrast=&lang=&fontScale=) and applies
+ *      them to :root. Put this in <head>, inline, so it runs before the app's stylesheet — no flash.
+ *   2. LIVE: applies generic root-state updates the host posts (`smartlinks:root-state`) — viewer /
+ *      accessibility prefs (dark, contrast, font-scale, lang) and, if the host chooses, editor
+ *      brand-preview. The app AUTHORS CSS against these root hooks; it never writes a message handler.
+ *
+ * Root hooks the app styles against:
+ *   - theme:      the `.dark` class (Tailwind/shadcn convention) AND `[data-theme="dark|light"]`
+ *   - contrast:   `[data-contrast="high"]`  (also honour @media (prefers-contrast: more) natively)
+ *   - font size:  `--sl-font-scale` (e.g. 1.25) — scale your rem/base type off it
+ *   - language:   `lang` attribute (content/i18n is the app's own job; this just flags it)
+ *   - brand:      the --sl-* theme tokens (see theme.css)
+ *
+ * Brand THEME changes are expected via iframe reload (rare, operator-driven). Viewer / a11y prefs are
+ * applied LIVE here (a reload on an accessibility toggle is itself an accessibility failure).
+ */
+(function () {
+  if (typeof document === 'undefined') return;
+  var root = document.documentElement;
+
+  function setVar(k, val) {
+    root.style.setProperty(k.charAt(0) === '-' ? k : '--sl-' + k, String(val));
+  }
+  function applyTheme(mode) { // 'dark' | 'light'
+    if (!mode) return;
+    root.classList.toggle('dark', mode === 'dark');
+    root.setAttribute('data-theme', mode);
+  }
+  function applyState(s) {
+    if (!s || typeof s !== 'object') return;
+    var v = s.values || s.vars;
+    if (v) for (var k in v) if (Object.prototype.hasOwnProperty.call(v, k)) setVar(k, v[k]);
+    if (s.theme) applyTheme(s.theme);
+    if (s.contrast != null) {
+      if (s.contrast === 'normal' || s.contrast === false) root.removeAttribute('data-contrast');
+      else root.setAttribute('data-contrast', String(s.contrast));
+    }
+    if (s.fontScale != null) setVar('font-scale', s.fontScale);
+    if (s.lang) root.setAttribute('lang', String(s.lang));
+    var a = s.attrs;
+    if (a) for (var name in a) if (Object.prototype.hasOwnProperty.call(a, name)) {
+      if (a[name] == null || a[name] === false) root.removeAttribute(name);
+      else root.setAttribute(name, a[name] === true ? '' : String(a[name]));
+    }
+  }
+
+  // 1) BOOT from the URL — synchronous, before paint.
+  try {
+    var hash = location.hash || '';
+    var m = hash.match(/[#&]slt=([^&]+)/);
+    if (m) {
+      var b64 = m[1].replace(/-/g, '+').replace(/_/g, '/');
+      applyState(JSON.parse(decodeURIComponent(escape(atob(b64)))));
+    }
+    var q = new URLSearchParams(location.search);
+    var boot = {};
+    if (q.get('theme')) boot.theme = q.get('theme');
+    if (q.get('contrast')) boot.contrast = q.get('contrast');
+    if (q.get('lang')) boot.lang = q.get('lang');
+    if (q.get('fontScale')) boot.fontScale = q.get('fontScale');
+    applyState(boot);
+  } catch (e) { /* never block the app on a malformed theme payload */ }
+
+  // 2) LIVE updates — generic; the app never writes this.
+  try {
+    window.addEventListener('message', function (e) {
+      var d = e && e.data;
+      if (d && d.type === 'smartlinks:root-state') applyState(d);
+    });
+  } catch (e) {}
+})();

package/dist/theme.css

@@ -0,0 +1,55 @@
+/* @proveanything/smartlinks/theme.css — SmartLinks host theming preset (theme tokens v1)
+ *
+ * Maps Tailwind 4's design tokens onto the SmartLinks semantic theme tokens (--sl-color-*,
+ * --sl-radius-*, --sl-font-*) that the host sets on each app's mount root. After importing this,
+ * an app's `bg-primary` / `text-foreground` / `border-border` / `rounded-md` / `font-heading`
+ * resolve to whatever brand the host is running — no per-app mapping, no hardcoded palette.
+ *
+ *   app styles.css:
+ *     @import "tailwindcss";
+ *     @import "@proveanything/smartlinks/theme.css";
+ *
+ * Requires Tailwind 4 (@theme). Every value has a neutral fallback, so the app renders correctly
+ * even against a host that sets none of the --sl-* tokens. See docs/theme-tokens.md.
+ */
+
+@theme {
+  /* ── Colour (semantic roles) ─────────────────────────────────────────── */
+  --color-background:    var(--sl-color-bg, #ffffff);
+  --color-surface:       var(--sl-color-surface, #f7f7f8);
+  --color-surface-raised:var(--sl-color-surface-raised, var(--sl-color-surface, #ffffff));
+  --color-foreground:    var(--sl-color-fg, #18181b);
+  --color-muted:         var(--sl-color-muted, #71717a);
+  --color-border:        var(--sl-color-border, #e4e4e7);
+  --color-primary:       var(--sl-color-accent, #4f46e5);
+  --color-on-primary:    var(--sl-color-on-accent, #ffffff);
+  --color-primary-soft:  var(--sl-color-accent-soft, color-mix(in oklab, var(--sl-color-accent, #4f46e5) 12%, transparent));
+  --color-success:       var(--sl-color-success, #16a34a);
+  --color-danger:        var(--sl-color-danger, #dc2626);
+
+  /* ── Shape ───────────────────────────────────────────────────────────── */
+  --radius-sm: var(--sl-radius-sm, 4px);
+  --radius-md: var(--sl-radius-md, 8px);
+  --radius-lg: var(--sl-radius-lg, 16px);
+
+  /* ── Type ────────────────────────────────────────────────────────────── */
+  --font-heading: var(--sl-font-heading, var(--sl-font-body, ui-sans-serif, system-ui, sans-serif));
+  --font-body:    var(--sl-font-body, ui-sans-serif, system-ui, sans-serif);
+
+  /* ── Elevation (extended; no shadow unless the host sets one) ─────────── */
+  --shadow-sm: var(--sl-shadow-sm, 0 0 #0000);
+  --shadow-md: var(--sl-shadow-md, 0 0 #0000);
+}
+
+/* shadcn bridge (optional): if the app uses shadcn's --primary/--background/etc. HSL variables,
+ * uncomment to drive them from the SmartLinks tokens too. Left commented so it never overrides an
+ * app that has deliberately customised its shadcn palette — opt in per app (see migration step 17).
+ *
+ * :where([data-sl-app]) {
+ *   --primary:    var(--sl-color-accent);
+ *   --background: var(--sl-color-bg);
+ *   --foreground: var(--sl-color-fg);
+ *   --border:     var(--sl-color-border);
+ *   --radius:     var(--sl-radius-md);
+ * }
+ */

package/dist/types/appManifest.d.ts

@@ -429,6 +429,18 @@ export interface AppManifest {
          * `@proveanything/smartlinks/baseline.css`. Opt-in and additive. See docs/css-baseline.md.
          */
         cssBaseline?: string;
+        /**
+         * True if this app reads the host theme tokens (`--sl-color-*`, `--sl-radius-*`,
+         * `--sl-font-*`) rather than hardcoding a palette — i.e. it follows the host's brand.
+         * Lets a host's app browser show "follows your brand" vs "brings its own look", and turns
+         * on the doctor's hardcoded-colour warning. Opt-in. See docs/theme-tokens.md.
+         */
+        respectsHostTheme?: boolean;
+        /**
+         * Theme-token contract version this app targets, e.g. `"v1"`. Pairs with
+         * `@proveanything/smartlinks/theme.css`. See docs/theme-tokens.md.
+         */
+        themeTokens?: string;
         /**
          * Per-app namespaced UMD globals (R4.7+), e.g. `{ widgets: "MyAppWidgets" }`.
          * UMD-only: ESM bundles expose their exports through the module namespace and

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.15  |  Generated: 2026-09-22T15:00:20.418Z
+Version: 2.0.17  |  Generated: 2026-09-24T09:42:39.649Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2183,6 +2183,8 @@ interface AppManifest {
   moduleFormat?: 'umd' | 'esm' | 'dual';
   sharedDependencies?: string;
   cssBaseline?: string;
+  respectsHostTheme?: boolean;
+  themeTokens?: string;
   globals?: Record<string, string>;
   seo?: {
   strategy?: 'executor' | string;

package/docs/app-records-pattern.md

@@ -7,7 +7,7 @@
 > Status: **standard**. New apps MUST follow this contract; existing apps SHOULD migrate.
 >
 > SDK: `@proveanything/smartlinks` ≥ **2.0** (R5).
-> Admin shell (React only): `@proveanything/smartlinks-utils-ui` ≥ **0.7.6** — required for the admin side if using the React shell; not needed in public widgets.
+> Admin shell (React only): `@proveanything/smartlinks-utils-ui` ≥ **2.0** — required for the admin side if using the React shell; not needed in public widgets.
 
 ---
 

package/docs/deploying-apps.md

@@ -34,14 +34,24 @@ bundle. Two small additions to your build, both non-secret:
    // app.manifest.json
    "build": { "hash": "a1b2c3d4", "at": "2026-09-20T10:00:00Z" }
    ```
-2. **Ping us on publish** (a `postbuild` step — `SMARTLINKS_APP_ID` is an *identifier, not a
-   secret*, so it's fine in the repo):
+2. **Ping us on publish** (a `postbuild` step — the app id is an *identifier, not a secret*, so it's
+   fine in the repo). **Prefer the tiny node wrapper** the example app ships
+   (`scripts/smartlinks-deploy.mjs` in `smartlinks-app-example` — copy it): its
+   no-key path does exactly this ping and, crucially, **resolves the app id from
+   `SMARTLINKS_APP_ID` *or* the manifest's `meta.appId`**, so it works even when no env var is set:
+   ```js
+   // the id-resolution the wrapper uses — env var first, manifest fallback
+   const appId = process.env.SMARTLINKS_APP_ID
+     || JSON.parse(fs.readFileSync('public/app.manifest.json')).meta.appId
+   ```
+   ```jsonc
+   // package.json — wrapper (recommended)
+   "scripts": { "postbuild": "node scripts/smartlinks-deploy.mjs" }
+   ```
+   A bare `curl` works too, **but only if `$SMARTLINKS_APP_ID` is actually set in the build env** —
+   it has no manifest fallback, so an unset var makes the ping a silent no-op (a common miss):
    ```jsonc
-   // package.json
-   "scripts": {
-     "build":     "vite build && … && node scripts/hash-bundles.mjs",   // your existing hashing step
-     "postbuild": "curl -fsS -X POST \"$SMARTLINKS_API/api/v1/apps/$SMARTLINKS_APP_ID/refresh-dev\" -H 'content-type: application/json' -d \"{\\\"hash\\\":\\\"$BUILD_HASH\\\"}\""
-   }
+   "postbuild": "curl -fsS -X POST \"$SMARTLINKS_API/api/v1/apps/$SMARTLINKS_APP_ID/refresh-dev\" -H 'content-type: application/json' -d \"{\\\"hash\\\":\\\"$BUILD_HASH\\\"}\""
    ```
 
 That's it — no deploy key. When the ping arrives, SmartLinks looks up your app's published URL
@@ -51,6 +61,14 @@ and registers the dev release (the hash becomes the version). `POST /apps/{appId
 authorises nothing on its own — worst case it re-fetches your app's own public bundle — so it needs
 no secret; it's rate-limited and de-duped per app.
 
+**Where your app learns its own id:** either `SMARTLINKS_APP_ID` (a build-env var) or the manifest's
+`meta.appId`. **Whichever you use must equal your authoritative platform id** — the one in the
+catalog (the `appModules` handle the CDN + every collection's config bind to). On the keyed
+`/releases` path `meta.appId` is *ignored* in favour of the URL id, but for `refresh-dev` the id you
+ping with **is** the lookup key — so if `meta.appId` is blank or has drifted from your platform id,
+the ping resolves the wrong app (or `NO_DEV_URL`). **Stamp `meta.appId` with your real platform id**
+(don't invent one) and the manifest fallback is reliable.
+
 **One-time setup:** the app must exist in the catalog with its **id** and its **Lovable URL**
 recorded (that's how we know what to fetch, and the `id` you ping with must match). Ask the platform
 owner to register the app once; after that, every Publish auto-updates dev.

package/docs/theme-lookbook.v1.json

@@ -0,0 +1,120 @@
+{
+  "tokensVersion": "v1",
+  "note": "Reference starter themes for the theme-tokens v1 contract (see theme-tokens.md). These seed the Hub lookbook; the AI refines from one of these or generates new value-sets. Each is a plain value map the host expands to --sl-* on the app mount root. All pass WCAG AA for fg/bg and on-accent/accent.",
+  "themes": [
+    {
+      "id": "clean-slate",
+      "name": "Clean Slate",
+      "description": "Neutral default — safe, modern, brandable. The fallback identity.",
+      "values": {
+        "color-bg": "#ffffff",
+        "color-surface": "#f7f7f8",
+        "color-surface-raised": "#ffffff",
+        "color-fg": "#18181b",
+        "color-muted": "#71717a",
+        "color-border": "#e4e4e7",
+        "color-accent": "#4f46e5",
+        "color-on-accent": "#ffffff",
+        "color-accent-soft": "#eef2ff",
+        "radius-sm": "4px", "radius-md": "8px", "radius-lg": "16px",
+        "font-heading": "'Inter', ui-sans-serif, system-ui, sans-serif",
+        "font-body": "'Inter', ui-sans-serif, system-ui, sans-serif"
+      }
+    },
+    {
+      "id": "midnight",
+      "name": "Midnight",
+      "description": "Dark surface, cool accent. For premium / tech brands.",
+      "values": {
+        "color-bg": "#0b0d12",
+        "color-surface": "#151821",
+        "color-surface-raised": "#1d212c",
+        "color-fg": "#e7e9ee",
+        "color-muted": "#9aa1ad",
+        "color-border": "#2a2f3a",
+        "color-accent": "#6ea8fe",
+        "color-on-accent": "#0b0d12",
+        "color-accent-soft": "#18233a",
+        "radius-sm": "5px", "radius-md": "10px", "radius-lg": "18px",
+        "font-heading": "'Space Grotesk', ui-sans-serif, system-ui, sans-serif",
+        "font-body": "'Inter', ui-sans-serif, system-ui, sans-serif"
+      }
+    },
+    {
+      "id": "warm-editorial",
+      "name": "Warm Editorial",
+      "description": "Cream paper, serif headings, terracotta accent. Food, lifestyle, craft.",
+      "values": {
+        "color-bg": "#faf7f2",
+        "color-surface": "#ffffff",
+        "color-surface-raised": "#ffffff",
+        "color-fg": "#1a1a1a",
+        "color-muted": "#6b6b6b",
+        "color-border": "#e6e0d8",
+        "color-accent": "#b4531f",
+        "color-on-accent": "#ffffff",
+        "color-accent-soft": "#f6e9df",
+        "radius-sm": "3px", "radius-md": "6px", "radius-lg": "12px",
+        "font-heading": "'Fraunces', Georgia, serif",
+        "font-body": "'Inter', ui-sans-serif, system-ui, sans-serif"
+      }
+    },
+    {
+      "id": "fresh-mint",
+      "name": "Fresh Mint",
+      "description": "Airy light, green accent, soft corners. Wellness, sustainability, outdoors.",
+      "values": {
+        "color-bg": "#f6faf7",
+        "color-surface": "#ffffff",
+        "color-surface-raised": "#ffffff",
+        "color-fg": "#14261c",
+        "color-muted": "#5c7367",
+        "color-border": "#d9e7de",
+        "color-accent": "#0f8a5f",
+        "color-on-accent": "#ffffff",
+        "color-accent-soft": "#e2f3ea",
+        "radius-sm": "8px", "radius-md": "14px", "radius-lg": "24px",
+        "font-heading": "'Poppins', ui-sans-serif, system-ui, sans-serif",
+        "font-body": "'Inter', ui-sans-serif, system-ui, sans-serif"
+      }
+    },
+    {
+      "id": "bold-contrast",
+      "name": "Bold Contrast",
+      "description": "Mono, sharp corners, black accent. Streetwear, fashion, high-impact.",
+      "values": {
+        "color-bg": "#ffffff",
+        "color-surface": "#ffffff",
+        "color-surface-raised": "#ffffff",
+        "color-fg": "#0a0a0a",
+        "color-muted": "#5c5c5c",
+        "color-border": "#0a0a0a",
+        "color-accent": "#0a0a0a",
+        "color-on-accent": "#ffffff",
+        "color-accent-soft": "#f0f0f0",
+        "radius-sm": "0px", "radius-md": "0px", "radius-lg": "2px",
+        "font-heading": "'Archivo', ui-sans-serif, system-ui, sans-serif",
+        "font-body": "'Archivo', ui-sans-serif, system-ui, sans-serif"
+      }
+    },
+    {
+      "id": "soft-pastel",
+      "name": "Soft Pastel",
+      "description": "Gentle lilac, very rounded, friendly. Kids, beauty, playful DTC.",
+      "values": {
+        "color-bg": "#fbf7ff",
+        "color-surface": "#ffffff",
+        "color-surface-raised": "#ffffff",
+        "color-fg": "#241b33",
+        "color-muted": "#7a6f8c",
+        "color-border": "#ece2f7",
+        "color-accent": "#7c3aed",
+        "color-on-accent": "#ffffff",
+        "color-accent-soft": "#f1e9fe",
+        "radius-sm": "10px", "radius-md": "18px", "radius-lg": "28px",
+        "font-heading": "'Quicksand', ui-sans-serif, system-ui, sans-serif",
+        "font-body": "'Nunito', ui-sans-serif, system-ui, sans-serif"
+      }
+    }
+  ]
+}

package/docs/theme-tokens.md

@@ -0,0 +1,239 @@
+# SmartLinks Theme Tokens — host theming contract
+
+Status: **v1 (draft) — FORTHCOMING, not yet live host-side.**
+> ⚠️ **Do not build apps against this yet.** The host (Hub/Portal) does not yet set `--sl-*` tokens
+> or send `smartlinks:root-state`. Until it does, apps follow the **current** theming — see
+> [`theme.system.md`](./theme.system.md) (`useSmartLinksTheme()` + shadcn vars `--primary`/`--background`,
+> the `?theme=` base64 payload). This document is the target model that will supersede it once the host
+> serves it; it exists so the SDK preset (`theme.css`), the iframe bootstrap (`theme-boot.js`) and the
+> Hub theme engine can be built against a fixed contract.
+
+Applies to: `@proveanything/smartlinks` ^2.0 (R5), container + widget embeds
+Companion to: [`css-baseline.md`](./css-baseline.md) (mechanics, live) — this doc is **brand** (colour, shape, type)
+
+---
+
+## The one idea
+
+`sl-baseline` gives apps guaranteed **mechanics** (layout, spacing, type scale) with no colour or brand.
+Theme tokens give apps the host's **brand** — colour, corner shape, fonts — as a small set of
+**semantic CSS custom properties** the host sets and the app reads. An app that binds to these
+follows any host theme automatically, forever, with no code change.
+
+The durable thing here is the **token contract** (names + meanings), not any theme. A *theme* is just
+a set of token *values* — disposable data, hand-authored or AI-generated. The contract is small,
+semantic, and versioned; themes churn freely on top of it.
+
+```
+host sets  --sl-color-accent: #b4531f   (a theme value)
+    │
+    ▼
+SDK theme.css maps it onto Tailwind's token   →  bg-primary, text-primary, …
+    │
+    ▼
+app renders in the host's brand — no per-app work
+```
+
+---
+
+## 1. Design rules (why it lasts)
+
+1. **Semantic, never literal.** Tokens name a *role* (`--sl-color-accent`, `--sl-color-surface`),
+   never a colour (`--sl-blue-600`). Roles survive redesigns; literals rot.
+2. **Small guaranteed core.** The app-facing contract is ~12 tokens. Richer, Hub-specific styling
+   (button weight, elevation, density, imagery) lives in **host-internal** component tokens and is
+   NOT part of this contract — so it can evolve without breaking apps or binding other surfaces.
+3. **Additive, versioned, retained.** New tokens are added within a version with sane fallbacks; a
+   removal or rename is a new version, old retained. Same discipline as the shared-dependency
+   contract — never hard-remove.
+4. **Each surface declares the subset it honours.** The token set is a **superset**; Hub honours all
+   of it, Portal a subset. Apps read defensively (every token has a fallback), so one brand renders
+   consistently across surfaces and missing tokens degrade gracefully.
+5. **Tokens only — never templated CSS.** Themes are declarative values, always previewable and
+   validatable. (Liquid/templating belongs to content, not styling.)
+
+---
+
+## 2. The v1 token set
+
+All tokens are CSS custom properties read from the **nearest scoping element** (the app's mount
+root), so different embeds on one page can theme differently. Every token has a fallback, so an app
+renders correctly even against a host that sets none of them.
+
+### Core (v1 — guaranteed; every host honours these)
+
+| Token | Role | Example value |
+|---|---|---|
+| `--sl-color-bg` | app / page background | `#ffffff` |
+| `--sl-color-surface` | card / panel background | `#f7f7f8` |
+| `--sl-color-fg` | primary text (on bg/surface) | `#18181b` |
+| `--sl-color-muted` | secondary / muted text | `#71717a` |
+| `--sl-color-border` | borders, dividers, input outlines | `#e4e4e7` |
+| `--sl-color-accent` | brand / primary action | `#4f46e5` |
+| `--sl-color-on-accent` | text / icon on an accent fill | `#ffffff` |
+| `--sl-radius-sm` | small corner radius | `4px` |
+| `--sl-radius-md` | default corner radius | `8px` |
+| `--sl-radius-lg` | large corner radius | `16px` |
+| `--sl-font-heading` | heading font stack | `'Inter', sans-serif` |
+| `--sl-font-body` | body font stack | `'Inter', sans-serif` |
+
+### Extended (v1 — optional; Hub may set, Portal may not; read defensively)
+
+| Token | Role | Fallback |
+|---|---|---|
+| `--sl-color-surface-raised` | elevated surface (popover, modal) | `--sl-color-surface` |
+| `--sl-color-accent-soft` | soft accent fill (badges, hovers) | derived from `--sl-color-accent` |
+| `--sl-color-success` | positive status | `#16a34a` |
+| `--sl-color-danger` | negative / destructive status | `#dc2626` |
+| `--sl-shadow-sm` / `--sl-shadow-md` | elevation | none |
+
+> Everything richer than this — button weight (solid/soft/outline), density/compactness, image
+> treatment, elevation scale — is a **host-internal component token**, driven by Hub's theme engine.
+> It is deliberately NOT in this contract, so Hub can be as skinnable as it likes without it becoming
+> a forever-obligation on every app and surface.
+
+Dark mode is a *theme* (a different value-set), not a separate token set — the host swaps the values.
+
+---
+
+## 3. Theme value-sets (what the AI emits, what the lookbook stores)
+
+A theme is data: a token version + a flat map of values. The host expands each `values` key to
+`--sl-<key>` on the mount root.
+
+```jsonc
+{
+  "tokensVersion": "v1",
+  "name": "Warm Editorial",
+  "values": {
+    "color-bg": "#faf7f2",
+    "color-surface": "#ffffff",
+    "color-fg": "#1a1a1a",
+    "color-muted": "#6b6b6b",
+    "color-border": "#e6e0d8",
+    "color-accent": "#b4531f",
+    "color-on-accent": "#ffffff",
+    "radius-sm": "4px", "radius-md": "10px", "radius-lg": "18px",
+    "font-heading": "'Fraunces', serif",
+    "font-body": "'Inter', sans-serif"
+  }
+}
+```
+
+- **Lookbook** = a gallery of these value-sets shipped as starting points; AI can generate more.
+- **Refine** = AI edits `values` conversationally, previewed live in the real host, always inside the
+  contract → always safe, previewable, validatable.
+- **Brand on-ramp** = ingest a site/brand guide → AI emits a `values` set → refine.
+- **Validation** = a value-set must pass contrast (WCAG AA) for `fg`/`bg`, `muted`/`bg`,
+  `on-accent`/`accent` before it is offered or saved. AI output is checked, not trusted.
+
+Store per collection as `{ tokensVersion, name, values }` — portable, diffable, exportable.
+
+---
+
+## 4. Host obligations vs app obligations
+
+**Host (Hub / Portal):**
+- Applies the active theme's `--sl-*` tokens where the embed will read them — `:root`/`<body>` for the
+  simple one-brand page (container/widget apps inherit for free), or the app's mount root when embeds
+  must theme independently or you want leak isolation for untrusted apps.
+- For **iframe** apps, hands the initial state in via the URL fragment and posts live viewer-pref
+  updates as `smartlinks:root-state` (§6.2). Brand-theme changes = reload the embed.
+- Declares the token version it serves and which subset (Hub = full, Portal = core).
+
+**App:**
+- `@import "@proveanything/smartlinks/theme.css";` after Tailwind (see §5).
+- Uses semantic utilities (`bg-primary`, `text-foreground`, `border-border`, `rounded-md`,
+  `font-heading`) — never hardcoded palette utilities (`bg-blue-600`, `#rrggbb`).
+- Authors CSS against the viewer-pref hooks (§6.1): the `.dark` class, `[data-contrast="high"]`,
+  `--sl-font-scale`, and the native `@media (prefers-contrast|prefers-reduced-motion)` queries.
+  **Never writes a message handler** — the SDK bootstrap flips the hooks.
+- Iframe/standalone entries only: include `@proveanything/smartlinks/theme-boot.js` in `<head>`
+  (§6.2). Container/widget apps don't need it.
+- Declares intent in the manifest:
+
+```jsonc
+{ "meta": { "respectsHostTheme": true, "themeTokens": "v1" } }
+```
+
+`smartlinks-doctor` warns (not errors) on hardcoded colour utilities / hex in component source when
+`respectsHostTheme` is `true`.
+
+---
+
+## 5. The SDK preset (`theme.css`)
+
+Ships from the SDK. A Tailwind 4 `@theme` block that maps Tailwind's tokens onto the `--sl-*`
+contract, with fallbacks so it is safe even where the host sets nothing:
+
+```css
+@import "tailwindcss";
+@import "@proveanything/smartlinks/theme.css";
+```
+
+Requires Tailwind 4 (`@theme`). Apps still on Tailwind 3 stay as they are until they migrate
+(step 16); the preset is opt-in and additive.
+
+---
+
+## 6. Viewer preferences, accessibility & iframe delivery
+
+Two different kinds of "theme-ish" state, handled differently:
+
+| | Brand theme | Viewer / accessibility prefs |
+|---|---|---|
+| What | accent, fonts, radius (the `--sl-*` tokens) | light/dark, contrast, font size, reduced-motion, language |
+| Set by | the operator (rarely, in an editor) | the **viewer** (any time, mid-session) |
+| Change model | **reload** the embed with new values | **live**, no reload (a reload on an a11y toggle *is* an a11y failure) |
+
+**The app never writes a message handler.** It authors **CSS** against a small, fixed set of root
+hooks; a generic SDK bootstrap (§6.2) flips those hooks. That's the whole obligation.
+
+### 6.1 The viewer-pref hooks (fixed vocabulary)
+
+- **Dark mode** — the `.dark` class (Tailwind/shadcn convention) *and* `[data-theme="dark"|"light"]`.
+- **Contrast** — `[data-contrast="high"]`. Also honour `@media (prefers-contrast: more)` — the browser
+  propagates the OS setting into iframes natively, so you get that slice for free.
+- **Reduced motion** — honour `@media (prefers-reduced-motion: reduce)` (native, free).
+- **Font size** — `--sl-font-scale` (a number, e.g. `1.25`); scale your base/rem type off it.
+- **Language** — the `lang` attribute. (A language change is *content*, not just CSS — re-render/
+  re-fetch is the app's own i18n job; the hook just flags it. A heavy content swap may reload.)
+
+Most of accessibility is therefore **free**: the OS-level `prefers-contrast` / `prefers-reduced-motion`
+/ browser zoom reach the iframe with no passing at all — just respect the standard media queries.
+
+### 6.2 Iframe delivery (`theme-boot.js`)
+
+Container/widget apps inherit the host `:root` and need none of this. **Iframe/standalone** apps
+(their own document — the security boundary for untrusted apps) include the SDK bootstrap
+`@proveanything/smartlinks/theme-boot.js` in `<head>` (inline is best — zero flash):
+
+- **Boot (before first paint):** reads the initial state from the URL fragment
+  `#slt=<base64url(JSON)>` (`{ tokensVersion, values, theme, contrast, fontScale, lang }`), plus
+  convenience params `?theme=&contrast=&fontScale=&lang=`, and applies it to `:root` synchronously.
+  This *replaces* the legacy base64-17-keys scheme — same idea (correct on first paint), but a
+  structured, versioned payload.
+- **Live:** applies generic root-state updates the host posts as
+  `{ type: 'smartlinks:root-state', values?, theme?, contrast?, fontScale?, lang?, attrs? }`. This is
+  what makes accessibility toggles instant. The app carries none of this logic — the bootstrap is
+  generic and SDK-owned; the app only wrote CSS.
+
+Payload stays small (the reason the fixed vocabulary matters): the token set + a handful of mode keys
+fit comfortably in a URL fragment, no compression needed.
+
+---
+
+## 7. Versioning
+
+- `themeTokens: "vN"` — the version an app targets.
+- Within a version: additive only (new tokens get fallbacks). Never remove a token in-version.
+- A removal/rename → `v(N+1)`, `vN` retained; hosts may serve several; apps declare which they target.
+- Surfaces declare their honoured subset; the "mapping" between Hub and Portal is *which keys each
+  honours*, not a translation layer.
+
+## 8. Change log
+
+- **v1 (draft, 2026-09-23):** initial semantic core (12) + extended (optional) set; value-set schema;
+  host mount-root scoping; manifest declaration + doctor warn; viewer-pref/accessibility hooks
+  (`.dark`/`data-theme`, `data-contrast`, `--sl-font-scale`, `lang`, native `prefers-*`); iframe
+  `theme-boot.js` (URL-boot + generic live root-state); brand change = reload, prefs = live.