@proveanything/smartlinks 2.0.14 → 2.0.16

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.14  |  Generated: 2026-09-22T11:19:25.044Z
+Version: 2.0.16  |  Generated: 2026-09-23T19:24:45.314Z
 
 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/dist/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.
@@ -236,14 +254,24 @@ today.)
 
 ---
 
-## Wiring it into your build
+## Wiring it into your build (the KEYED path — CI / controlled env / beta·stable)
+
+> ⚠️ **This is the deploy-key path — not the default for a Lovable dev publish.** If you build in
+> Lovable (no deploy key in the build), your dev publishes register via the **key-free `refresh-dev`
+> ping** in **[Section A](#a-from-lovable--hit-publish-no-key-anywhere-recommended-for-lovable-apps)** — put *that* in `postbuild`, not the
+> binary below. Reach for `smartlinks-register-release` only where you (a) hold a deploy key and
+> (b) set `SMARTLINKS_CHANNEL` — i.e. a controlled dev/CI environment, or a formal **beta/stable**
+> deploy. In a keyless Lovable postbuild this binary **skips silently** (no channel ⇒ no-op), so a
+> dev publish would register *nothing* — that's the trap. One rule: **dev publish → `refresh-dev`;
+> keyed/formal deploy → `register-release`.**
 
-Registration is the **last step of your build** — after bundles are built and hashed. Run a
+Registration is the **last step of a keyed build** — after bundles are built and hashed. Run a
 small script that reads your built manifest and POSTs it, and **exits non-zero on failure**
 so a bad install fails the publish.
 
-The SDK ships the script, so you don't copy-paste it — run it as your postbuild step. It reads
-your built manifest, POSTs it, prints any warnings, and exits non-zero on failure.
+The SDK ships the script, so you don't copy-paste it — run it as your postbuild step **in a keyed
+environment**. It reads your built manifest, POSTs it, prints any warnings, and exits non-zero on
+failure.
 
 ```jsonc
 // package.json
@@ -266,13 +294,16 @@ It is driven entirely by env vars, so the same command works for dev (Lovable) a
 
 > The full source is at `scripts/register-release.mjs` in the SDK package if you'd rather vendor it.
 
-Registration is gated by **`SMARTLINKS_CHANNEL`**, so the three Lovable build types behave correctly:
+Registration is gated by **`SMARTLINKS_CHANNEL`**, so a keyed build behaves correctly by intent:
 
 | Build | `SMARTLINKS_CHANNEL` | Result |
 |---|---|---|
-| **Preview / live-edit** | unset | **skips quietly** — never registers, never fails |
-| **Dev (Publish)** | `dev` | registers to `dev` with the workspace Build-Secret key + your Lovable `SMARTLINKS_BUNDLE_BASE_URL` |
-| **Prod (CI)** | `stable` | registers to `stable` with the prod/master key; a missing key **hard-fails** |
+| **Preview / live-edit / plain Lovable dev publish** | unset | **skips quietly** — never registers, never fails. (A Lovable dev publish is meant to register via the key-free `refresh-dev` ping in [Section A](#a-from-lovable--hit-publish-no-key-anywhere-recommended-for-lovable-apps), not this binary.) |
+| **Controlled dev env (you hold a dev key)** | `dev` | registers to `dev` with the dev key + your `SMARTLINKS_BUNDLE_BASE_URL` |
+| **Prod (CI / formal deploy)** | `stable` | registers to `stable` with the prod/master key; a missing key **hard-fails** |
+
+> The middle row is a *controlled* dev environment where you deliberately hold a dev key and set the
+> channel — **not** a stock Lovable publish, which carries neither and so should use `refresh-dev`.
 
 **Two secrets, two scopes:** the **deploy key** is channel-scoped and can be a *workspace-level*
 Lovable Build Secret shared by every app (a dev key only writes `dev`, so sharing it is safe). The

package/dist/docs/host-dependency-contract.md

@@ -178,3 +178,24 @@ if (host && host.version !== SHARED_DEPENDENCY_CONTRACT_VERSION) {
 The host publishes its live contract on `window.__SMARTLINKS_SHARED__` (`{ version, specifiers }`),
 which `getHostSharedDependencies()` reads. Import-map shim paths follow `importMapPathFor(specifier)`
 (`/sl-shared/<version>/<slug>.js`), so both the portal and the SDK generate identical paths.
+
+## Version retention — hosts MUST keep every published version (load-bearing)
+
+The version in the shim path (`/sl-shared/vN/`) exists **so multiple contract versions coexist**. A
+deployed app pins the version it was built against (`meta.sharedDependencies`) and resolves its shims
+from that path forever. Therefore:
+
+> **A contract bump is ADDITIVE. Generating `/sl-shared/v7/` MUST NOT delete `/sl-shared/v5/` or
+> `/sl-shared/v6/`.** The shims are tiny re-export files — keep them.
+
+If the host's shim generator *replaces* the previous version instead of *appending*, the versioning
+buys nothing: every bump silently breaks every already-deployed app not yet rebuilt (bare-specifier
+resolution failure → blank container — the exact failure this whole contract prevents). "The host
+serves all versions while apps migrate" is not aspirational; it's a hard requirement of the host.
+
+**Retiring a version:** only remove `/sl-shared/vN/` once no installed app still declares that
+`meta.sharedDependencies` version. You can determine that from the app registry (each app's declared
+version × where it's installed); until it's provably unreferenced, keep it. Prefer a long deprecation
+window over reclaiming a few KB.
+
+(The same rule applies to any versioned CSS-baseline paths — additive, never delete a live version.)

package/dist/docs/theme-tokens.md

@@ -0,0 +1,232 @@
+# SmartLinks Theme Tokens — host theming contract
+
+Status: **v1 (draft)**
+Applies to: `@proveanything/smartlinks` ^2.0 (R5), container + widget embeds
+Companion to: [`css-baseline.md`](./css-baseline.md) (mechanics) — 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.

package/dist/openapi.yaml

@@ -17959,6 +17959,10 @@ components:
           type: string
         cssBaseline:
           type: string
+        respectsHostTheme:
+          type: boolean
+        themeTokens:
+          type: string
         globals:
           type: object
           additionalProperties:

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.14  |  Generated: 2026-09-22T11:19:25.044Z
+Version: 2.0.16  |  Generated: 2026-09-23T19:24:45.314Z
 
 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/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.
@@ -236,14 +254,24 @@ today.)
 
 ---
 
-## Wiring it into your build
+## Wiring it into your build (the KEYED path — CI / controlled env / beta·stable)
+
+> ⚠️ **This is the deploy-key path — not the default for a Lovable dev publish.** If you build in
+> Lovable (no deploy key in the build), your dev publishes register via the **key-free `refresh-dev`
+> ping** in **[Section A](#a-from-lovable--hit-publish-no-key-anywhere-recommended-for-lovable-apps)** — put *that* in `postbuild`, not the
+> binary below. Reach for `smartlinks-register-release` only where you (a) hold a deploy key and
+> (b) set `SMARTLINKS_CHANNEL` — i.e. a controlled dev/CI environment, or a formal **beta/stable**
+> deploy. In a keyless Lovable postbuild this binary **skips silently** (no channel ⇒ no-op), so a
+> dev publish would register *nothing* — that's the trap. One rule: **dev publish → `refresh-dev`;
+> keyed/formal deploy → `register-release`.**
 
-Registration is the **last step of your build** — after bundles are built and hashed. Run a
+Registration is the **last step of a keyed build** — after bundles are built and hashed. Run a
 small script that reads your built manifest and POSTs it, and **exits non-zero on failure**
 so a bad install fails the publish.
 
-The SDK ships the script, so you don't copy-paste it — run it as your postbuild step. It reads
-your built manifest, POSTs it, prints any warnings, and exits non-zero on failure.
+The SDK ships the script, so you don't copy-paste it — run it as your postbuild step **in a keyed
+environment**. It reads your built manifest, POSTs it, prints any warnings, and exits non-zero on
+failure.
 
 ```jsonc
 // package.json
@@ -266,13 +294,16 @@ It is driven entirely by env vars, so the same command works for dev (Lovable) a
 
 > The full source is at `scripts/register-release.mjs` in the SDK package if you'd rather vendor it.
 
-Registration is gated by **`SMARTLINKS_CHANNEL`**, so the three Lovable build types behave correctly:
+Registration is gated by **`SMARTLINKS_CHANNEL`**, so a keyed build behaves correctly by intent:
 
 | Build | `SMARTLINKS_CHANNEL` | Result |
 |---|---|---|
-| **Preview / live-edit** | unset | **skips quietly** — never registers, never fails |
-| **Dev (Publish)** | `dev` | registers to `dev` with the workspace Build-Secret key + your Lovable `SMARTLINKS_BUNDLE_BASE_URL` |
-| **Prod (CI)** | `stable` | registers to `stable` with the prod/master key; a missing key **hard-fails** |
+| **Preview / live-edit / plain Lovable dev publish** | unset | **skips quietly** — never registers, never fails. (A Lovable dev publish is meant to register via the key-free `refresh-dev` ping in [Section A](#a-from-lovable--hit-publish-no-key-anywhere-recommended-for-lovable-apps), not this binary.) |
+| **Controlled dev env (you hold a dev key)** | `dev` | registers to `dev` with the dev key + your `SMARTLINKS_BUNDLE_BASE_URL` |
+| **Prod (CI / formal deploy)** | `stable` | registers to `stable` with the prod/master key; a missing key **hard-fails** |
+
+> The middle row is a *controlled* dev environment where you deliberately hold a dev key and set the
+> channel — **not** a stock Lovable publish, which carries neither and so should use `refresh-dev`.
 
 **Two secrets, two scopes:** the **deploy key** is channel-scoped and can be a *workspace-level*
 Lovable Build Secret shared by every app (a dev key only writes `dev`, so sharing it is safe). The

package/docs/host-dependency-contract.md

@@ -178,3 +178,24 @@ if (host && host.version !== SHARED_DEPENDENCY_CONTRACT_VERSION) {
 The host publishes its live contract on `window.__SMARTLINKS_SHARED__` (`{ version, specifiers }`),
 which `getHostSharedDependencies()` reads. Import-map shim paths follow `importMapPathFor(specifier)`
 (`/sl-shared/<version>/<slug>.js`), so both the portal and the SDK generate identical paths.
+
+## Version retention — hosts MUST keep every published version (load-bearing)
+
+The version in the shim path (`/sl-shared/vN/`) exists **so multiple contract versions coexist**. A
+deployed app pins the version it was built against (`meta.sharedDependencies`) and resolves its shims
+from that path forever. Therefore:
+
+> **A contract bump is ADDITIVE. Generating `/sl-shared/v7/` MUST NOT delete `/sl-shared/v5/` or
+> `/sl-shared/v6/`.** The shims are tiny re-export files — keep them.
+
+If the host's shim generator *replaces* the previous version instead of *appending*, the versioning
+buys nothing: every bump silently breaks every already-deployed app not yet rebuilt (bare-specifier
+resolution failure → blank container — the exact failure this whole contract prevents). "The host
+serves all versions while apps migrate" is not aspirational; it's a hard requirement of the host.
+
+**Retiring a version:** only remove `/sl-shared/vN/` once no installed app still declares that
+`meta.sharedDependencies` version. You can determine that from the app registry (each app's declared
+version × where it's installed); until it's provably unreferenced, keep it. Prefer a long deprecation
+window over reclaiming a few KB.
+
+(The same rule applies to any versioned CSS-baseline paths — additive, never delete a live version.)

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,232 @@
+# SmartLinks Theme Tokens — host theming contract
+
+Status: **v1 (draft)**
+Applies to: `@proveanything/smartlinks` ^2.0 (R5), container + widget embeds
+Companion to: [`css-baseline.md`](./css-baseline.md) (mechanics) — 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.

package/openapi.yaml

@@ -17959,6 +17959,10 @@ components:
           type: string
         cssBaseline:
           type: string
+        respectsHostTheme:
+          type: boolean
+        themeTokens:
+          type: string
         globals:
           type: object
           additionalProperties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.14",
+  "version": "2.0.16",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",
@@ -23,6 +23,8 @@
     },
     "./baseline.css": "./dist/baseline.css",
     "./baseline.classes.json": "./dist/baseline.classes.json",
+    "./theme.css": "./dist/theme.css",
+    "./theme-boot.js": "./dist/theme-boot.js",
     "./package.json": "./package.json"
   },
   "bin": {

package/scripts/doctor.mjs

@@ -16,7 +16,7 @@
 // Exit code: 0 = clean, 1 = violations (CI-friendly).
 // =============================================================================
 
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { bareImportsOf } from './lib/bare-imports.mjs';
@@ -184,6 +184,54 @@ if (meta.cssBaseline) {
   }
 }
 
+// ---- Host theming (theme tokens) -------------------------------------------
+// If the app declares meta.respectsHostTheme, warn on hardcoded Tailwind PALETTE utilities in
+// component SOURCE (e.g. bg-blue-600, text-zinc-900) — those pin a colour instead of following the
+// host brand via the semantic tokens (bg-primary, text-foreground, border-border). Scans source,
+// not compiled bundles (bundles are full of legitimate hex). Heuristic + WARN-only. See
+// docs/theme-tokens.md.
+if (meta.respectsHostTheme) {
+  const THEME_TOKENS_VERSION = 'v1';
+  if (!meta.themeTokens) {
+    warnings.push(`meta.respectsHostTheme is true but meta.themeTokens is not declared — set it to "${THEME_TOKENS_VERSION}".`);
+  } else if (meta.themeTokens !== THEME_TOKENS_VERSION) {
+    warnings.push(`meta.themeTokens is "${meta.themeTokens}" but this SDK ships theme tokens "${THEME_TOKENS_VERSION}".`);
+  }
+
+  const PALETTE = 'slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose';
+  const UTIL = 'bg|text|border|ring|divide|from|via|to|fill|stroke|outline|decoration|shadow|accent|caret';
+  const paletteRe = new RegExp(`\\b(?:${UTIL})-(?:${PALETTE})-(?:50|100|200|300|400|500|600|700|800|900|950)\\b`, 'g');
+
+  const SRC_EXT = /\.(tsx|ts|jsx|js|vue|html|svelte)$/;
+  const SKIP_DIR = new Set(['node_modules', 'dist', '.nuxt', '.output', '.git', 'public']);
+  function walk(dir, out = []) {
+    let entries = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+    for (const e of entries) {
+      if (e.isDirectory()) { if (!SKIP_DIR.has(e.name)) walk(join(dir, e.name), out); }
+      else if (SRC_EXT.test(e.name)) out.push(join(dir, e.name));
+    }
+    return out;
+  }
+
+  const srcRoot = existsSync(join(appDir, 'src')) ? join(appDir, 'src') : appDir;
+  const offenders = [];
+  let totalHits = 0;
+  for (const f of walk(srcRoot)) {
+    const hits = [...new Set((readFileSync(f, 'utf8').match(paletteRe) || []))];
+    if (hits.length) { offenders.push({ file: f.replace(appDir + '/', '').replace(appDir + '\\', ''), hits }); totalHits += hits.length; }
+  }
+
+  if (offenders.length === 0) {
+    console.log(`${GREEN}✓${RESET} theme ${DIM}(respectsHostTheme)${RESET} — no hardcoded palette utilities in source`);
+  } else {
+    console.log(`${YELLOW}⚠${RESET} theme ${DIM}(respectsHostTheme)${RESET} — hardcoded palette utilities in ${offenders.length} file${offenders.length === 1 ? '' : 's'} (use bg-primary / text-foreground / border-border instead):`);
+    for (const o of offenders.slice(0, 15)) console.log(`    ${DIM}${o.file}${RESET}  ${YELLOW}${o.hits.slice(0, 6).join(' ')}${o.hits.length > 6 ? ' …' : ''}${RESET}`);
+    if (offenders.length > 15) console.log(`    ${DIM}…and ${offenders.length - 15} more file(s)${RESET}`);
+    warnings.push(`respectsHostTheme is true but ${totalHits} hardcoded palette utilit${totalHits === 1 ? 'y' : 'ies'} found in source — replace with semantic tokens, or drop respectsHostTheme if the app intentionally brings its own look.`);
+  }
+}
+
 console.log('');
 for (const w of warnings) console.log(`${YELLOW}⚠ ${w}${RESET}`);