@proveanything/smartlinks 2.0.15 → 2.0.17

package/dist/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/dist/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/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.

package/dist/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.

package/dist/docs/ui-utils.md

@@ -1,104 +1,121 @@
-# UI Utils — `@proveanything/smartlinks-utils-ui`
-
-> **This page is a pointer.** Detailed, up-to-date docs for every component
-> live in the UI Utils package itself. This SDK doc only summarises *what's
-> in the box* and *when to reach for it* — so we don't have to update the
-> SDK every time a UI Utils prop changes.
-
-- **NPM:** [`@proveanything/smartlinks-utils-ui`](https://www.npmjs.com/package/@proveanything/smartlinks-utils-ui)
-- **Source & docs:** [`smartlinks-ui` repo](https://github.com/proveanything/smartlinks-ui)
-- **Per-component reference:** [`packages/smartlinks-ui/docs/`](https://github.com/proveanything/smartlinks-ui/tree/main/packages/smartlinks-ui/docs)
-- **Tracks:** `@proveanything/smartlinks ≥ 1.13` (peer dep)
-
-## Install
-
-```bash
-npm install @proveanything/smartlinks-utils-ui
-# Peer deps you probably already have:
-npm install react react-dom @proveanything/smartlinks @tanstack/react-query
-```
-
-Import the styles **once** in your app entry (typically `src/admin-main.tsx`):
-
-```ts
-import '@proveanything/smartlinks-utils-ui/styles.css';
-```
-
-Components inherit your shadcn-compatible CSS variables (`--primary`,
-`--background`, `--border`, …) — no extra theming required.
-
-> **Admin-only.** Every component in this package calls the SDK with
-> `admin: true` somewhere (save, upload, etc.). Never import it from a
-> public widget or from `MobileAdminContainer`.
-
-## What's in the box
-
-| Module | Subpath import | Use it for |
-|---|---|---|
-| **RecordsAdminShell** | `/records-admin` | Full admin UI for the `app.records` pattern. Top-level scopes: **Global** (`'collection'`), **Rule** (`'rule'`, AND-of-OR over facets), and **Product** — with automatic variant & batch drill-down where the collection enables them. Browser pane, editor pane with sticky save/discard/delete, optimistic save, deep-linking, lifecycle hooks, conflict handling. Decide [cardinality](https://github.com/proveanything/smartlinks-ui/blob/main/packages/smartlinks-ui/docs/records-admin-shell.md#-choosing-cardinality-read-this-first) up front: `'singleton'` (one winning record per scope — warranty, nutrition) vs `'list'` (many records per scope — auction items, FAQs, gallery). |
-| **Records hooks** | `/records-admin` | `useResolvedRecord`, `useMergedRecord`, `useCollectedRecords`, `useResolveAllRecords`, `useRulePreview`, … for the **public widget** side. |
-| **AdminPageHeader** | (root) | Standardised title / subtitle / icon / help / actions header. **Required** for any admin app that doesn't mount `RecordsAdminShell` (which embeds it). No bespoke admin chrome. |
-| **AssetPicker** | `/asset-picker` | Pick / upload / paste / URL-import / AI-generate / stock-search / crop media assets. MIME filtering, scope-aware, tag editor. |
-| **IconPicker** | `/icon-picker` | Searchable Font Awesome 7 Pro picker (requires the FA kit script on the host page). |
-| **FontPicker** | `/font-picker` | Google Fonts catalogue + custom uploaded font families with live previews. |
-| **ConditionsEditor** | `/conditions-editor` | Recursive AND/OR rule builder (12 condition types, facet-aware). |
-| **FacetRuleEditor** | `/facet-rule-editor` | Author server-side facet rules (AND-of-OR) for record targeting. |
-| **LinkPicker** | `/link-picker` | Universal navigation picker: external URL, an installed app, or a deep link inside an app. Stores a `LinkTarget` discriminated union — never a resolved URL. Ships with `resolveLink` and `useLinkTargets`. |
-| **Hints** | (root) | `useHintsPreference`, `useIntroState`, `HintsPreferenceToggle` — global "show/hide intro hints" preference shared across admin apps. |
-
-Each module has a per-subpath export so bundlers tree-shake the rest:
-
-```ts
-import { RecordsAdminShell } from '@proveanything/smartlinks-utils-ui/records-admin';
-import { AssetPicker }       from '@proveanything/smartlinks-utils-ui/asset-picker';
-```
-
-## Minimal examples
-
-### Records admin (most apps need this)
-
-```tsx
-import { RecordsAdminShell } from '@proveanything/smartlinks-utils-ui/records-admin';
-import * as SL from '@proveanything/smartlinks';
-
-<RecordsAdminShell
-  SL={SL}
-  collectionId={collectionId}
-  appId={appId}
-  recordType="nutrition"
-  label="Nutrition info"
-  scopes={['collection', 'rule', 'product']}   // canonical top-level tabs
-  // items={{ cardinality: 'list' }}           // ← opt in for multi-item apps
-  defaultData={() => ({})}
-  renderEditor={(ctx) => <NutritionForm ctx={ctx} />}
-/>
-```
-
-### Public widget — read the resolved value
-
-```tsx
-import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
-
-const { data, source } = useResolvedRecord({
-  SL, appId, recordType: 'nutrition',
-  collectionId, productId, variantId, batchId,
-});
-// source: 'proof' | 'batch' | 'variant' | 'product' | 'rule' | 'collection' | null
-```
-
-For multi-item (`cardinality: 'list'`) apps, use `useResolveAllRecords` /
-`app.records.resolveAll()` instead — it returns every applicable record, not
-just the winner.
-
-For everything else (props, slots, cardinality decisions, deep-link adapters,
-lifecycle hooks, conflict handling, design tokens) → **read the package docs**.
-
-## Prerequisites
-
-All components assume `SL.initializeApi()` has already run.
-
-## Where to go next
-
-- Component reference: <https://github.com/proveanything/smartlinks-ui/tree/main/packages/smartlinks-ui/docs>
-- Records pattern (concepts, scope inheritance, resolution order): [`records-admin-pattern.md`](./records-admin-pattern.md)
-- Public consumption (how widgets/executors fetch the right records at runtime): the package's [`public-consumption.md`](https://github.com/proveanything/smartlinks-ui/blob/main/packages/smartlinks-ui/docs/public-consumption.md)
+# UI Utils — `@proveanything/smartlinks-utils-ui`
+
+The standardised, **admin-only** React toolkit for SmartLinks microapps. This page
+is self-contained: the table and examples below are enough to build with. The
+exhaustive per-component reference (props, slots, hooks, design tokens) ships
+**inside the package** — read it from `node_modules/@proveanything/smartlinks-utils-ui/docs/`
+after install. Nothing here depends on an external site.
+
+- **NPM:** [`@proveanything/smartlinks-utils-ui`](https://www.npmjs.com/package/@proveanything/smartlinks-utils-ui)
+- **Per-component reference:** `node_modules/@proveanything/smartlinks-utils-ui/docs/*.md`
+  (`records-admin-shell.md`, `admin-page-header.md`, `asset-picker.md`, `conditions-editor.md`,
+  `facet-rule-editor.md`, `link-picker.md`, `records-admin-hooks.md`, `public-consumption.md`, …)
+- **Tracks:** `@proveanything/smartlinks ≥ 2.0` (peer dep)
+
+## Admin is standardised; the consumer surface is bespoke
+
+Two different design mandates, and the split is deliberate:
+
+- **Admin surfaces** (the desktop `admin.html` a brand operator uses) are a
+  **product family** — like Salesforce: consistent, predictable chrome across every
+  app an operator opens. Do **not** hand-roll admin tables, editors or page headers.
+  Mount `RecordsAdminShell` for anything record-shaped; otherwise wrap the page in
+  `AdminPageHeader` and use the pickers. That consistency *is* the product.
+- **Consumer / public surfaces** (the container, widgets, public pages the
+  end-customer sees) are **bespoke and brand-led** — entirely your design. utils-ui
+  belongs here only as read-side hooks (`useResolvedRecord`, `useResolveAllRecords`),
+  never as UI.
+
+## Install
+
+```bash
+npm install @proveanything/smartlinks-utils-ui
+# Peer deps you probably already have:
+npm install react react-dom @proveanything/smartlinks @tanstack/react-query
+```
+
+Import the styles **once** in your admin entry (typically `src/admin-main.tsx`):
+
+```ts
+import '@proveanything/smartlinks-utils-ui/styles.css';
+```
+
+Components inherit your shadcn-compatible CSS variables (`--primary`,
+`--background`, `--border`, …) — no extra theming required.
+
+> **Admin-only.** Every component in this package calls the SDK with
+> `admin: true` somewhere (save, upload, etc.). Never import it from a
+> public widget or from `MobileAdminContainer`.
+
+## What's in the box
+
+| Module | Subpath import | Use it for |
+|---|---|---|
+| **RecordsAdminShell** | `/records-admin` | Full admin UI for the `app.records` pattern. Top-level scopes: **Global** (`'collection'`), **Rule** (`'rule'`, AND-of-OR over facets), and **Product** — with automatic variant & batch drill-down where the collection enables them. Browser pane, editor pane with sticky save/discard/delete, optimistic save, deep-linking, lifecycle hooks, conflict handling. Decide **cardinality** up front: `'singleton'` (one winning record per scope — warranty, nutrition) vs `'list'` (many records per scope — auction items, FAQs, gallery). See `docs/records-admin-shell.md`. |
+| **Records hooks** | `/records-admin` | `useResolvedRecord`, `useMergedRecord`, `useCollectedRecords`, `useResolveAllRecords`, `useRulePreview`, … for the **public widget** side. See `docs/records-admin-hooks.md`. |
+| **AdminPageHeader** | (root) | Standardised title / subtitle / icon / help / actions header. **Required** for any admin app that doesn't mount `RecordsAdminShell` (which embeds it). No bespoke admin chrome. |
+| **AssetPicker** | `/asset-picker` | Pick / upload / paste / URL-import / AI-generate / stock-search / crop media assets. MIME filtering, scope-aware, tag editor. |
+| **IconPicker** | `/icon-picker` | Searchable Font Awesome 7 Pro picker (requires the FA kit script on the host page). |
+| **FontPicker** | `/font-picker` | Google Fonts catalogue + custom uploaded font families with live previews. |
+| **ConditionsEditor** | `/conditions-editor` | Recursive AND/OR rule builder (12 condition types, facet-aware). |
+| **FacetRuleEditor** | `/facet-rule-editor` | Author server-side facet rules (AND-of-OR) for record targeting. |
+| **LinkPicker** | `/link-picker` | Universal navigation picker: external URL, an installed app, or a deep link inside an app. Stores a `LinkTarget` discriminated union — never a resolved URL. Ships with `resolveLink` and `useLinkTargets`. |
+| **Liquid editors** | `/liquid-editor` | Author Liquid templates with a code or rich (TipTap) editor, variable autocomplete. |
+| **Hints** | (root) | `useHintsPreference`, `useIntroState`, `HintsPreferenceToggle` — global "show/hide intro hints" preference shared across admin apps. |
+
+Each module has a per-subpath export so bundlers tree-shake the rest:
+
+```ts
+import { RecordsAdminShell } from '@proveanything/smartlinks-utils-ui/records-admin';
+import { AssetPicker }       from '@proveanything/smartlinks-utils-ui/asset-picker';
+```
+
+## Minimal examples
+
+### Records admin (most apps need this)
+
+```tsx
+import { RecordsAdminShell } from '@proveanything/smartlinks-utils-ui/records-admin';
+import * as SL from '@proveanything/smartlinks';
+
+<RecordsAdminShell
+  SL={SL}
+  collectionId={collectionId}
+  appId={appId}
+  recordType="nutrition"
+  label="Nutrition info"
+  scopes={['collection', 'rule', 'product']}   // canonical top-level tabs
+  // items={{ cardinality: 'list' }}           // ← opt in for multi-item apps
+  defaultData={() => ({})}
+  renderEditor={(ctx) => <NutritionForm ctx={ctx} />}
+/>
+```
+
+### Public widget — read the resolved value
+
+```tsx
+import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const { data, source } = useResolvedRecord({
+  SL, appId, recordType: 'nutrition',
+  collectionId, productId, variantId, batchId,
+});
+// source: 'proof' | 'batch' | 'variant' | 'product' | 'rule' | 'collection' | null
+```
+
+For multi-item (`cardinality: 'list'`) apps, use `useResolveAllRecords` /
+`app.records.resolveAll()` instead — it returns every applicable record, not
+just the winner.
+
+For everything else (props, slots, cardinality decisions, deep-link adapters,
+lifecycle hooks, conflict handling, design tokens) → **read the matching file in
+`node_modules/@proveanything/smartlinks-utils-ui/docs/`**.
+
+## Prerequisites
+
+All components assume `SL.initializeApi()` has already run.
+
+## Where to go next
+
+- Per-component reference (shipped with the package): `node_modules/@proveanything/smartlinks-utils-ui/docs/`
+- Records pattern (concepts, scope inheritance, resolution order): [`app-records-pattern.md`](./app-records-pattern.md)