@proveanything/smartlinks 1.9.21 → 1.9.22

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.21  |  Generated: 2026-04-25T10:48:10.932Z
+Version: 1.9.22  |  Generated: 2026-04-25T11:11:00.344Z
 
 This is a concise summary of all available API functions and types.
 

package/dist/docs/overview.md

@@ -67,7 +67,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Forms** | `docs/forms.md` | Form definitions, schema-driven rendering, submission patterns |
 | **Auth Kit** | `docs/auth-kit.md` | End-user sign-in: email/password, magic links, phone OTP, Google OAuth |
 | **Records Admin Pattern** | `docs/records-admin-pattern.md` | Standard pattern for per-product/facet/variant/batch admin UIs |
-| **UI Utils** | `docs/ui-utils.md` | `@proveanything/ui-utils` — React shells, hooks, and primitives for records-based apps |
+| **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 
 ---
 

package/dist/docs/records-admin-pattern.md

@@ -79,7 +79,7 @@ Notes:
 - Variants and batches are **always nested under a product** in the SDK, so their refs include `productId`.
 - `facet:` refs are **collection-wide** — facets cross products by design.
 - `default` is a single record per (app, recordType) used as the global fallback.
-- Refs are opaque to the SDK. Apps parse them. A helper module (`@proveanything/ui-utils/records`) exports `parseRef`/`buildRef` so all apps agree on syntax. See Appendix A for the full implementation.
+- Refs are opaque to the SDK. Apps parse them. A helper module (`@proveanything/smartlinks-utils-ui/records-admin`) exports `parseRef`/`buildRef` so all apps agree on syntax. See Appendix A for the full implementation.
 
 ### Adding scopes later
 
@@ -99,10 +99,10 @@ proof → batch → variant → product → facet(*) → default
 
 > **Rule:** Resolution is **first-match-wins, not merge**. If you need field-level merging, build it on top with explicit `inheritsFrom` markers in the payload — but the default for shared infra is whole-record replacement, because it is far easier to reason about.
 
-The canonical resolver lives in `@proveanything/ui-utils/records` so every app behaves identically:
+The canonical resolver lives in `@proveanything/smartlinks-utils-ui/records-admin` so every app behaves identically:
 
 ```ts
-import { resolveRecord } from '@proveanything/ui-utils/records';
+import { resolveRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
 
 const resolved = await resolveRecord({
   appId,
@@ -147,29 +147,24 @@ See [app-manifest.md](app-manifest.md) for the full schema reference.
 
 ## 6. Discovering whether variants / batches are in use
 
-The SDK does **not** expose a `collection.variantsEnabled` flag, by design. Whether a product has variants/batches is an **emergent** property: it has them iff someone created some.
-
-The standard probe pattern:
+The `Collection` object exposes top-level `variants: boolean` and `batches: boolean` flags that indicate whether the collection has these features enabled. Read them directly rather than probing by listing:
 
 ```ts
-import { variant, batch } from '@proveanything/smartlinks';
+import { appConfiguration } from '@proveanything/smartlinks';
 
-const [variants, batches] = await Promise.all([
-  variant.list(collectionId, productId).catch(() => []),
-  batch.list(collectionId, productId).catch(() => []),
-]);
+const collection = await appConfiguration.getCollection(collectionId);
 
-// scopeConfig is the parsed manifest records entry for this recordType
-// e.g. manifest.records?.nutrition → { scopes: ['product', 'facet', 'batch'], ... }
-const showVariantTab = variants.length > 0 || scopeConfig?.scopes.includes('variant') === true;
-const showBatchTab   = batches.length  > 0 || scopeConfig?.scopes.includes('batch') === true;
+const showVariantTab = collection.variants && scopeConfig?.scopes.includes('variant') === true;
+const showBatchTab   = collection.batches  && scopeConfig?.scopes.includes('batch') === true;
 ```
 
+`scopeConfig` is the parsed manifest `records` entry for this `recordType` — e.g. `manifest.records?.nutrition`.
+
 Rules:
 
-1. If the app **declares** support for the scope, always offer "Add variant" / "Add batch" affordances even when the list is empty.
-2. If the app does **not** declare support, hide the tab entirely even if some exist (another app created them).
-3. Cache list results per `(collectionId, productId)` with a short TTL — the shell will hit them often.
+1. If the collection has the feature **and** the app **declares** support for the scope, show the tab and offer "Add variant" / "Add batch" affordances.
+2. If the app does **not** declare support, hide the tab entirely even if `collection.variants` is true (another app created them).
+3. If the collection does not have the feature enabled, hide the tab even if the app declares support.
 
 ---
 
@@ -181,7 +176,7 @@ Because resolution is first-match-wins, the admin UI must make inheritance **vis
 - Each field in the editor displays a small **↩ "Inherited"** marker when its value matches the parent and **● "Override"** when it differs.
 - A row-level "Reset to inherited" action removes the override (deletes the record at the current scope if all overrides are reset).
 
-Apps don't have to implement this themselves — the `<RecordEditor>` primitive in `@proveanything/ui-utils` does it given the resolved parent payload.
+Apps don't have to implement this themselves — the `<RecordEditor>` primitive in `@proveanything/smartlinks-utils-ui` does it given the resolved parent payload.
 
 ---
 
@@ -195,23 +190,19 @@ Standard verbs every shell should expose:
 | **Copy from**     | Pick a source scope, copy its payload to the current scope.          |
 | **Clear**         | Delete records at the current scope (children unaffected).           |
 
-The SDK does not currently expose a bulk write endpoint for records. Implement these by fanning out individual `app.records.create` / `app.records.update` calls with bounded concurrency (e.g. 10 in-flight at a time):
+Use the `bulkUpsert` / `bulkDelete` helpers from `@proveanything/smartlinks-utils-ui/records-admin`, which handle batching and error collection for you:
 
 ```ts
-import { app } from '@proveanything/smartlinks';
+import { bulkUpsert, bulkDelete } from '@proveanything/smartlinks-utils-ui/records-admin';
 
-// fan-out with concurrency cap
-const chunks = chunkArray(targetRefs, 10);
-for (const chunk of chunks) {
-  await Promise.all(
-    chunk.map((ref) =>
-      app.records.update(collectionId, appId, refToRecordId(ref), { data: payload }, true)
-    )
-  );
-}
+// Apply current payload to many refs
+await bulkUpsert({ SL, collectionId, appId, recordType, refs: targetRefs, data: payload });
+
+// Clear records at selected refs
+await bulkDelete({ SL, collectionId, appId, recordType, refs: targetRefs });
 ```
 
-If you are writing to **hundreds** of records at once, **flag it** to the platform team — a batch endpoint should be added rather than saturating the API from the browser.
+If you are using `<RecordsAdminShell>`, the bulk actions menu is included and wired automatically via the `onTelemetry` hook — you don't call these directly unless you're building a custom shell.
 
 ---
 
@@ -238,7 +229,7 @@ facet,bread_type/sourdough,240,11.0,...
 To keep widgets consistent across apps, expose one hook per record type (implemented in `@proveanything/ui-utils`):
 
 ```ts
-import { useResolvedRecord } from '@proveanything/ui-utils/records';
+import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
 
 const { data, source, isLoading } = useResolvedRecord({
   appId,
@@ -269,7 +260,7 @@ All admin shells emit these events. The `<RecordsAdminShell>` from `@proveanythi
 ## 12. Required reading for app authors
 
 1. This document.
-2. The companion **[UI utils guide](ui-utils.md)** — explains the React primitives that implement this pattern.
+2. The companion **[UI utils guide](ui-utils.md)** — explains the React primitives (`<RecordsAdminShell>`, `useResolvedRecord`, etc.) that implement this pattern.
 3. [PRODUCT_FACETS_SDK.md](PRODUCT_FACETS_SDK.md) — facet model.
 4. [app-data-storage.md](app-data-storage.md) — `app.records` surface.
 
@@ -279,9 +270,9 @@ All admin shells emit these events. The `<RecordsAdminShell>` from `@proveanythi
 - [ ] Move to `app.records` with `recordType` + `ref`.
 - [ ] Adopt the `ref` syntax in §3.
 - [ ] Add a `records` block to `app.manifest.json`.
-- [ ] Replace bespoke admin browser with `<RecordsAdminShell>` from `@proveanything/ui-utils`.
+- [ ] Replace bespoke admin browser with `<RecordsAdminShell>` from `@proveanything/smartlinks-utils-ui`.
 - [ ] Replace bespoke public hook with `useResolvedRecord`.
-- [ ] Remove any "is variants enabled?" config — probe instead (§6).
+- [ ] Remove any "is variants enabled?" config — use `collection.variants` / `collection.batches` flags instead (§6).
 
 ---
 

package/dist/docs/ui-utils.md

@@ -1,67 +1,133 @@
-# SmartLinks UI Utils (`@proveanything/ui-utils`)
+# SmartLinks UI Utils (`@proveanything/smartlinks-utils-ui`)
 
-> Companion module to the SmartLinks SDK. Provides React primitives, hooks, and admin shells for building consistent microapp UIs.
+> Companion React component library for the SmartLinks SDK. Ships the heavy, opinionated admin UI pieces that almost every SmartLinks microapp ends up needing — built once, theme-able, tree-shakeable, and wired straight into the SmartLinks SDK.
 >
-> Package: `@proveanything/ui-utils`  
-> Install: `npm install @proveanything/ui-utils`
+> Package: `@proveanything/smartlinks-utils-ui`  
+> Tracks: `@proveanything/smartlinks ≥ 1.9`
 
 ---
 
 ## What is this module for?
 
-`@proveanything/ui-utils` sits on top of `@proveanything/smartlinks`. The core SDK handles data — authentication, records, configurations, interactions. This module handles **UI** — the shared React components, hooks, and shell primitives that translate SDK data into consistent admin and public interfaces.
+`@proveanything/smartlinks-utils-ui` sits on top of `@proveanything/smartlinks`. The core SDK handles data — records, configurations, interactions. This module handles **UI** — the shared React components, hooks, and admin shells that translate SDK data into consistent admin interfaces.
 
 **When do you need it?**
 
 - You are building an admin UI for a records-based microapp (see [records-admin-pattern.md](records-admin-pattern.md))
+- You need a media asset picker, icon picker, or font picker in an admin panel
+- You need a recursive rule/conditions editor for targeting or audience logic
 - You want the standard inheritance/override editor for scoped records
 - You need the `useResolvedRecord` hook on the public widget side
-- You are using `parseRef` / `buildRef` for the standard `ref` convention
 
 You do **not** need it for apps that only use `appConfiguration`, basic widgets without scoped data, or executor bundles.
 
+> **Admin-only**: all components call the SDK with `admin: true`. Do not render them in public-facing views.
+
 ---
 
-## Key exports
+## Install
+
+```bash
+npm install @proveanything/smartlinks-utils-ui
+```
+
+Peer dependencies (you already have these in a SmartLinks app):
+
+```bash
+npm install react react-dom @proveanything/smartlinks
+# Recommended — enables caching and pagination in Records Admin Shell:
+npm install @tanstack/react-query
+```
 
-### Records admin shell
+Import the compiled styles **once** in your app entry (e.g. `main.tsx`):
 
 ```tsx
-import { RecordsAdminShell } from '@proveanything/ui-utils';
+import '@proveanything/smartlinks-utils-ui/styles.css';
+```
+
+Components inherit your shadcn-compatible CSS variables (`--primary`, `--background`, `--border`, …) so they pick up your theme automatically.
+
+---
 
-// Drop-in admin interface for any records-based app.
-// Reads the app's manifest `records` block to determine tabs and scopes.
-<RecordsAdminShell
+## What's in the box
+
+| Module | What it is | When to reach for it |
+|--------|------------|----------------------|
+| [Records Admin Shell](#records-admin-shell) | Full admin UI for `app.records` with scope inheritance | Per-product / per-variant / per-batch / per-facet config tools |
+| [Asset Picker](#asset-picker) | Browse / upload / paste / URL-import images and files | Any time the admin needs to pick or upload media |
+| [Icon Picker](#icon-picker) | Searchable Font Awesome 7 Pro picker | Configurable buttons, badges, menus, tiles |
+| [Font Picker](#font-picker) | Google Fonts + custom uploaded fonts | Theme editors, brand customisation panels |
+| [Conditions Editor](#conditions-editor) | Recursive AND/OR rule builder for 12 condition types | Targeting, gating, audience rules, segmentation |
+
+---
+
+## Records Admin Shell
+
+The primary export. A complete admin UI for managing `app.records` — typed JSON blobs attached to facets, products, variants, and batches — with scope inheritance built in. You provide the form for one record; the shell handles everything else.
+
+```tsx
+import {
+  RecordsAdminShell,
+  InheritanceMarker,
+  type EditorContext,
+} from '@proveanything/smartlinks-utils-ui/records-admin';
+import * as SL from '@proveanything/smartlinks';
+
+<RecordsAdminShell<NutritionData>
+  SL={SL}
   collectionId={collectionId}
   appId={appId}
   recordType="nutrition"
-  renderForm={(record, parentRecord) => <NutritionForm record={record} parent={parentRecord} />}
+  label="Nutrition info"
+  scopes={['facet', 'product', 'variant', 'batch']}
+  contextScope={{ productId, variantId, batchId }}   // from iframe URL — optional
+  defaultData={() => ({})}
+  csvSchema={{ columns: [/* ... */] }}
+  renderEditor={(ctx) => <NutritionForm ctx={ctx} />}
+  renderPreview={({ resolved }) => <pre>{JSON.stringify(resolved, null, 2)}</pre>}
 />
 ```
 
-`RecordsAdminShell` handles: left-rail product/scope browsing, variant/batch tab discovery, the "New record" button, inheritance markers, bulk operations, CSV import/export, and telemetry events. Your app only provides the domain form.
+**What it handles:**
+
+- **Browser pane** with scope tabs (Facet / Product / Variant / Batch), search, and status filter pills (All / Configured / Partial / Empty)
+- **Editor pane** with sticky save / discard / delete footer
+- **Per-field `<InheritanceMarker>`** showing whether a value is the record's own or inherited from a parent scope, with one-click revert-to-inherited
+- **Inheritance resolver** walks `batch → variant → product → facet` and returns both the resolved and parent values
+- **Collection-aware tabs**: calls `collection.get` and hides Variants / Batches tabs unless `collection.variants` / `collection.batches` are true — no flicker
+- **Server-side pagination** via `useInfiniteQuery` — handles thousands of products with a "Load more" button
+- **Context-aware**: pass `contextScope` from your iframe URL (`productId` / `variantId` / `batchId`) and the browser is constrained to that subtree with the right tab auto-selected
+- **CSV import / export** with a schema you define; failed rows come back as an annotated CSV
+- **Bulk actions menu** (apply-to-many, copy-from, clear) via `bulkUpsert` / `bulkDelete`
+- **Telemetry hook** (`onTelemetry`) emits typed events for save, delete, scope change, CSV import/export, bulk apply
+- **i18n strings** fully overridable
+
+> Requires a `<QueryClientProvider>` from `@tanstack/react-query` somewhere up the tree.
 
-### Record editor primitive
+### Lower-level pieces (advanced use)
 
 ```tsx
-import { RecordEditor } from '@proveanything/ui-utils';
-
-// Lower-level editor with inheritance diffing. Use when you need
-// custom layout but still want the inherited/override markers.
-<RecordEditor
-  record={variantRecord}
-  parentRecord={productRecord}
-  fields={nutritionFields}
-  onSave={(data) => app.records.update(collectionId, appId, record.id, { data }, true)}
-/>
+import {
+  // Hooks
+  useRecordList, useRecordEditor, useResolvedRecord, useScopeProbe,
+  // Data helpers
+  parseRef, buildRef, resolutionChain,
+  listRecords, getRecordByRef, upsertRecord, deleteRecord,
+  bulkUpsert, bulkDelete,
+  exportCsv, importCsv, downloadBlob,
+  // UI pieces
+  RecordBrowser, RecordEditor, ScopeBreadcrumb,
+  InheritanceMarker, ResolvedPreview, BulkActionsMenu,
+} from '@proveanything/smartlinks-utils-ui/records-admin';
 ```
 
 ### `useResolvedRecord` hook
 
 ```ts
-import { useResolvedRecord } from '@proveanything/ui-utils/records';
+import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
 
 const { data, source, isLoading } = useResolvedRecord({
+  SL,
   appId,
   recordType: 'nutrition',
   collectionId,
@@ -73,27 +139,12 @@ const { data, source, isLoading } = useResolvedRecord({
 // source: 'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'default' | null
 ```
 
-Walks the resolution chain defined in [records-admin-pattern.md §4](records-admin-pattern.md#4-resolution-order-required) and returns the first matching record plus its source scope.
-
-### `resolveRecord` function
-
-```ts
-import { resolveRecord } from '@proveanything/ui-utils/records';
-
-// Async, non-hook version for executors and server-side logic.
-const resolved = await resolveRecord({
-  appId,
-  recordType: 'nutrition',
-  scope: { collectionId, productId, variantId, batchId, proofId },
-  supportedScopes: ['product', 'facet'], // optional — skip unsupported scopes
-});
-// → { record: AppRecord, source: string } | null
-```
+Walks the resolution chain defined in [records-admin-pattern.md §4](records-admin-pattern.md#4-resolution-order-required). Use this on the **public widget side** to read the correct value for a given context.
 
 ### `parseRef` / `buildRef` utilities
 
 ```ts
-import { parseRef, buildRef } from '@proveanything/ui-utils/records';
+import { parseRef, buildRef } from '@proveanything/smartlinks-utils-ui/records-admin';
 
 const parsed = parseRef('variant:prod_abc:var_500ml');
 // → { kind: 'variant', productId: 'prod_abc', variantId: 'var_500ml' }
@@ -102,26 +153,142 @@ const ref = buildRef({ kind: 'facet', facetKey: 'bread_type', valueKey: 'sourdou
 // → 'facet:bread_type:sourdough'
 ```
 
-See [records-admin-pattern.md Appendix A](records-admin-pattern.md#appendix-a--ref-parser-reference) for the full `ParsedRef` type and standalone implementation.
+See [records-admin-pattern.md Appendix A](records-admin-pattern.md#appendix-a--ref-parser-reference) for the full `ParsedRef` type.
+
+---
+
+## Asset Picker
+
+```tsx
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui/asset-picker';
+
+<AssetPicker
+  scope={{ type: 'collection', collectionId: 'abc123' }}
+  mode="dialog"               // or "inline"
+  allowUpload
+  accept={['image/*']}        // MIME filtering
+  onSelect={(asset) => setHeroUrl(asset.url)}
+  trigger={<Button>Choose image</Button>}
+/>
+```
+
+**What it does:**
+- Browses assets at **collection** or **product** scope (dual-scope tabs)
+- Four ingest paths: file upload, URL import, clipboard paste (with rename preview), and selection from existing assets
+- Inline mode for embedding in a panel; dialog mode for modal pickers
+- Double-click a tile to confirm instantly
+
+---
+
+## Icon Picker
+
+```tsx
+import { IconPicker } from '@proveanything/smartlinks-utils-ui/icon-picker';
+
+<IconPicker
+  mode="dialog"
+  value="fa-solid fa-heart"
+  onSelect={(icon) => setIcon(icon.name)}
+  trigger={<Button>Pick icon</Button>}
+/>
+```
+
+**What it does:**
+- Searches **Font Awesome 7 Pro** (uses the shared kit `75493b59b3`)
+- Family hierarchy: Classic (Solid / Regular / Light), Duotone, and Brands
+- Search-first with a background catalogue crawler — first results appear instantly, the full index fills in behind
+- Auto-switches families intelligently (e.g. brand searches surface brand icons even when "Classic" is selected)
+
+> Requires the FA kit script to be present on the host page.
+
+---
+
+## Font Picker
+
+```tsx
+import { FontPicker } from '@proveanything/smartlinks-utils-ui/font-picker';
+
+<FontPicker
+  mode="dialog"
+  value="Inter"
+  showPreview
+  onSelect={(font) => {
+    console.log(font.family);        // "Inter"
+    console.log(font.cssFontFamily); // "'Inter', ui-sans-serif, system-ui, sans-serif"
+    console.log(font.loadSnippet);   // <link href="..." rel="stylesheet">
+  }}
+/>
+
+{/* With custom fonts uploaded into the collection */}
+<FontPicker
+  mode="dialog"
+  showCustomFonts
+  scope={{ collectionId: 'abc123' }}
+  onSelect={(font) => /* ... */}
+/>
+```
+
+**What it does:**
+- Full **Google Fonts** catalogue plus any **custom fonts** uploaded for the brand (stored via `appConfiguration` under `customFonts`)
+- Upload zone auto-detects weight/style from the filename (e.g. `MyFont-BoldItalic.woff2`)
+- Returns a `FontSelection` with `family`, `cssFontFamily`, and a ready-to-inject `loadSnippet` (`<link>` for Google fonts, `@font-face` CSS for custom uploads)
+- Lazy-loads previews via `IntersectionObserver`; includes a management UI for editing custom font definitions
+
+---
+
+## Conditions Editor
+
+```tsx
+import { ConditionsEditor } from '@proveanything/smartlinks-utils-ui/conditions-editor';
+
+<ConditionsEditor
+  value={rules}
+  onChange={setRules}
+  collectionId={collectionId}     // auto-loads facet definitions
+  versions={[{ title: 'Default', value: '' }]}
+  tags={['featured', 'new']}
+/>
+```
+
+**What it does:**
+- Recursive AND / OR group builder — nest conditions to any depth
+- **12 condition types:** Version, Country, Value, User, Date, Device, Tag, Facet, Geofence, Product, Item Status, Condition Reference
+- **Facet condition** auto-fetches definitions from `facets.publicList(collectionId, { includeValues: true })` when only `collectionId` is passed (SDK ≥ 1.9.20)
+- **Country picker** is a searchable multi-select with removable ISO 3166-1 chips and a "Use regions" toggle
+- Renders correctly inside iframe contexts — avoids `overflow-hidden` so dropdowns escape their cards
+
+---
+
+## Tree shaking
+
+Each component has its own subpath export:
+
+```tsx
+// Bundles only the Asset Picker
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui/asset-picker';
+
+// Barrel import — bundler tree-shakes the rest
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui';
+```
+
+If you use subpath imports, import `styles.css` separately — subpaths do not pull it in automatically.
 
 ---
 
 ## Relationship to the core SDK
 
 ```
-@proveanything/smartlinks       ← data layer (records, config, interactions, …)
+@proveanything/smartlinks            ← data layer (records, config, interactions, …)
         ↑
-@proveanything/ui-utils         ← UI layer (components, hooks, admin shells)
+@proveanything/smartlinks-utils-ui   ← UI layer (components, hooks, admin shells)
         ↑
-your microapp                   ← domain logic and custom forms
+your microapp                        ← domain logic and custom forms
 ```
 
-`ui-utils` imports from `@proveanything/smartlinks` internally. You should install both packages, but only import directly from each for their respective concerns — don't reach into `ui-utils` for SDK data primitives.
-
 ---
 
 ## Further reading
 
 - [records-admin-pattern.md](records-admin-pattern.md) — the data contract that `RecordsAdminShell` implements
-- [building-react-components.md](building-react-components.md) — dual-mode rendering rules that apply to all ui-utils components
+- [building-react-components.md](building-react-components.md) — dual-mode rendering rules that apply to all components
 - [app-manifest.md](app-manifest.md) — the `records` manifest block that drives tab generation

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.21  |  Generated: 2026-04-25T10:48:10.932Z
+Version: 1.9.22  |  Generated: 2026-04-25T11:11:00.344Z
 
 This is a concise summary of all available API functions and types.
 

package/docs/overview.md

@@ -67,7 +67,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Forms** | `docs/forms.md` | Form definitions, schema-driven rendering, submission patterns |
 | **Auth Kit** | `docs/auth-kit.md` | End-user sign-in: email/password, magic links, phone OTP, Google OAuth |
 | **Records Admin Pattern** | `docs/records-admin-pattern.md` | Standard pattern for per-product/facet/variant/batch admin UIs |
-| **UI Utils** | `docs/ui-utils.md` | `@proveanything/ui-utils` — React shells, hooks, and primitives for records-based apps |
+| **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 
 ---
 

package/docs/records-admin-pattern.md

@@ -79,7 +79,7 @@ Notes:
 - Variants and batches are **always nested under a product** in the SDK, so their refs include `productId`.
 - `facet:` refs are **collection-wide** — facets cross products by design.
 - `default` is a single record per (app, recordType) used as the global fallback.
-- Refs are opaque to the SDK. Apps parse them. A helper module (`@proveanything/ui-utils/records`) exports `parseRef`/`buildRef` so all apps agree on syntax. See Appendix A for the full implementation.
+- Refs are opaque to the SDK. Apps parse them. A helper module (`@proveanything/smartlinks-utils-ui/records-admin`) exports `parseRef`/`buildRef` so all apps agree on syntax. See Appendix A for the full implementation.
 
 ### Adding scopes later
 
@@ -99,10 +99,10 @@ proof → batch → variant → product → facet(*) → default
 
 > **Rule:** Resolution is **first-match-wins, not merge**. If you need field-level merging, build it on top with explicit `inheritsFrom` markers in the payload — but the default for shared infra is whole-record replacement, because it is far easier to reason about.
 
-The canonical resolver lives in `@proveanything/ui-utils/records` so every app behaves identically:
+The canonical resolver lives in `@proveanything/smartlinks-utils-ui/records-admin` so every app behaves identically:
 
 ```ts
-import { resolveRecord } from '@proveanything/ui-utils/records';
+import { resolveRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
 
 const resolved = await resolveRecord({
   appId,
@@ -147,29 +147,24 @@ See [app-manifest.md](app-manifest.md) for the full schema reference.
 
 ## 6. Discovering whether variants / batches are in use
 
-The SDK does **not** expose a `collection.variantsEnabled` flag, by design. Whether a product has variants/batches is an **emergent** property: it has them iff someone created some.
-
-The standard probe pattern:
+The `Collection` object exposes top-level `variants: boolean` and `batches: boolean` flags that indicate whether the collection has these features enabled. Read them directly rather than probing by listing:
 
 ```ts
-import { variant, batch } from '@proveanything/smartlinks';
+import { appConfiguration } from '@proveanything/smartlinks';
 
-const [variants, batches] = await Promise.all([
-  variant.list(collectionId, productId).catch(() => []),
-  batch.list(collectionId, productId).catch(() => []),
-]);
+const collection = await appConfiguration.getCollection(collectionId);
 
-// scopeConfig is the parsed manifest records entry for this recordType
-// e.g. manifest.records?.nutrition → { scopes: ['product', 'facet', 'batch'], ... }
-const showVariantTab = variants.length > 0 || scopeConfig?.scopes.includes('variant') === true;
-const showBatchTab   = batches.length  > 0 || scopeConfig?.scopes.includes('batch') === true;
+const showVariantTab = collection.variants && scopeConfig?.scopes.includes('variant') === true;
+const showBatchTab   = collection.batches  && scopeConfig?.scopes.includes('batch') === true;
 ```
 
+`scopeConfig` is the parsed manifest `records` entry for this `recordType` — e.g. `manifest.records?.nutrition`.
+
 Rules:
 
-1. If the app **declares** support for the scope, always offer "Add variant" / "Add batch" affordances even when the list is empty.
-2. If the app does **not** declare support, hide the tab entirely even if some exist (another app created them).
-3. Cache list results per `(collectionId, productId)` with a short TTL — the shell will hit them often.
+1. If the collection has the feature **and** the app **declares** support for the scope, show the tab and offer "Add variant" / "Add batch" affordances.
+2. If the app does **not** declare support, hide the tab entirely even if `collection.variants` is true (another app created them).
+3. If the collection does not have the feature enabled, hide the tab even if the app declares support.
 
 ---
 
@@ -181,7 +176,7 @@ Because resolution is first-match-wins, the admin UI must make inheritance **vis
 - Each field in the editor displays a small **↩ "Inherited"** marker when its value matches the parent and **● "Override"** when it differs.
 - A row-level "Reset to inherited" action removes the override (deletes the record at the current scope if all overrides are reset).
 
-Apps don't have to implement this themselves — the `<RecordEditor>` primitive in `@proveanything/ui-utils` does it given the resolved parent payload.
+Apps don't have to implement this themselves — the `<RecordEditor>` primitive in `@proveanything/smartlinks-utils-ui` does it given the resolved parent payload.
 
 ---
 
@@ -195,23 +190,19 @@ Standard verbs every shell should expose:
 | **Copy from**     | Pick a source scope, copy its payload to the current scope.          |
 | **Clear**         | Delete records at the current scope (children unaffected).           |
 
-The SDK does not currently expose a bulk write endpoint for records. Implement these by fanning out individual `app.records.create` / `app.records.update` calls with bounded concurrency (e.g. 10 in-flight at a time):
+Use the `bulkUpsert` / `bulkDelete` helpers from `@proveanything/smartlinks-utils-ui/records-admin`, which handle batching and error collection for you:
 
 ```ts
-import { app } from '@proveanything/smartlinks';
+import { bulkUpsert, bulkDelete } from '@proveanything/smartlinks-utils-ui/records-admin';
 
-// fan-out with concurrency cap
-const chunks = chunkArray(targetRefs, 10);
-for (const chunk of chunks) {
-  await Promise.all(
-    chunk.map((ref) =>
-      app.records.update(collectionId, appId, refToRecordId(ref), { data: payload }, true)
-    )
-  );
-}
+// Apply current payload to many refs
+await bulkUpsert({ SL, collectionId, appId, recordType, refs: targetRefs, data: payload });
+
+// Clear records at selected refs
+await bulkDelete({ SL, collectionId, appId, recordType, refs: targetRefs });
 ```
 
-If you are writing to **hundreds** of records at once, **flag it** to the platform team — a batch endpoint should be added rather than saturating the API from the browser.
+If you are using `<RecordsAdminShell>`, the bulk actions menu is included and wired automatically via the `onTelemetry` hook — you don't call these directly unless you're building a custom shell.
 
 ---
 
@@ -238,7 +229,7 @@ facet,bread_type/sourdough,240,11.0,...
 To keep widgets consistent across apps, expose one hook per record type (implemented in `@proveanything/ui-utils`):
 
 ```ts
-import { useResolvedRecord } from '@proveanything/ui-utils/records';
+import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
 
 const { data, source, isLoading } = useResolvedRecord({
   appId,
@@ -269,7 +260,7 @@ All admin shells emit these events. The `<RecordsAdminShell>` from `@proveanythi
 ## 12. Required reading for app authors
 
 1. This document.
-2. The companion **[UI utils guide](ui-utils.md)** — explains the React primitives that implement this pattern.
+2. The companion **[UI utils guide](ui-utils.md)** — explains the React primitives (`<RecordsAdminShell>`, `useResolvedRecord`, etc.) that implement this pattern.
 3. [PRODUCT_FACETS_SDK.md](PRODUCT_FACETS_SDK.md) — facet model.
 4. [app-data-storage.md](app-data-storage.md) — `app.records` surface.
 
@@ -279,9 +270,9 @@ All admin shells emit these events. The `<RecordsAdminShell>` from `@proveanythi
 - [ ] Move to `app.records` with `recordType` + `ref`.
 - [ ] Adopt the `ref` syntax in §3.
 - [ ] Add a `records` block to `app.manifest.json`.
-- [ ] Replace bespoke admin browser with `<RecordsAdminShell>` from `@proveanything/ui-utils`.
+- [ ] Replace bespoke admin browser with `<RecordsAdminShell>` from `@proveanything/smartlinks-utils-ui`.
 - [ ] Replace bespoke public hook with `useResolvedRecord`.
-- [ ] Remove any "is variants enabled?" config — probe instead (§6).
+- [ ] Remove any "is variants enabled?" config — use `collection.variants` / `collection.batches` flags instead (§6).
 
 ---
 

package/docs/ui-utils.md

@@ -1,67 +1,133 @@
-# SmartLinks UI Utils (`@proveanything/ui-utils`)
+# SmartLinks UI Utils (`@proveanything/smartlinks-utils-ui`)
 
-> Companion module to the SmartLinks SDK. Provides React primitives, hooks, and admin shells for building consistent microapp UIs.
+> Companion React component library for the SmartLinks SDK. Ships the heavy, opinionated admin UI pieces that almost every SmartLinks microapp ends up needing — built once, theme-able, tree-shakeable, and wired straight into the SmartLinks SDK.
 >
-> Package: `@proveanything/ui-utils`  
-> Install: `npm install @proveanything/ui-utils`
+> Package: `@proveanything/smartlinks-utils-ui`  
+> Tracks: `@proveanything/smartlinks ≥ 1.9`
 
 ---
 
 ## What is this module for?
 
-`@proveanything/ui-utils` sits on top of `@proveanything/smartlinks`. The core SDK handles data — authentication, records, configurations, interactions. This module handles **UI** — the shared React components, hooks, and shell primitives that translate SDK data into consistent admin and public interfaces.
+`@proveanything/smartlinks-utils-ui` sits on top of `@proveanything/smartlinks`. The core SDK handles data — records, configurations, interactions. This module handles **UI** — the shared React components, hooks, and admin shells that translate SDK data into consistent admin interfaces.
 
 **When do you need it?**
 
 - You are building an admin UI for a records-based microapp (see [records-admin-pattern.md](records-admin-pattern.md))
+- You need a media asset picker, icon picker, or font picker in an admin panel
+- You need a recursive rule/conditions editor for targeting or audience logic
 - You want the standard inheritance/override editor for scoped records
 - You need the `useResolvedRecord` hook on the public widget side
-- You are using `parseRef` / `buildRef` for the standard `ref` convention
 
 You do **not** need it for apps that only use `appConfiguration`, basic widgets without scoped data, or executor bundles.
 
+> **Admin-only**: all components call the SDK with `admin: true`. Do not render them in public-facing views.
+
 ---
 
-## Key exports
+## Install
+
+```bash
+npm install @proveanything/smartlinks-utils-ui
+```
+
+Peer dependencies (you already have these in a SmartLinks app):
+
+```bash
+npm install react react-dom @proveanything/smartlinks
+# Recommended — enables caching and pagination in Records Admin Shell:
+npm install @tanstack/react-query
+```
 
-### Records admin shell
+Import the compiled styles **once** in your app entry (e.g. `main.tsx`):
 
 ```tsx
-import { RecordsAdminShell } from '@proveanything/ui-utils';
+import '@proveanything/smartlinks-utils-ui/styles.css';
+```
+
+Components inherit your shadcn-compatible CSS variables (`--primary`, `--background`, `--border`, …) so they pick up your theme automatically.
+
+---
 
-// Drop-in admin interface for any records-based app.
-// Reads the app's manifest `records` block to determine tabs and scopes.
-<RecordsAdminShell
+## What's in the box
+
+| Module | What it is | When to reach for it |
+|--------|------------|----------------------|
+| [Records Admin Shell](#records-admin-shell) | Full admin UI for `app.records` with scope inheritance | Per-product / per-variant / per-batch / per-facet config tools |
+| [Asset Picker](#asset-picker) | Browse / upload / paste / URL-import images and files | Any time the admin needs to pick or upload media |
+| [Icon Picker](#icon-picker) | Searchable Font Awesome 7 Pro picker | Configurable buttons, badges, menus, tiles |
+| [Font Picker](#font-picker) | Google Fonts + custom uploaded fonts | Theme editors, brand customisation panels |
+| [Conditions Editor](#conditions-editor) | Recursive AND/OR rule builder for 12 condition types | Targeting, gating, audience rules, segmentation |
+
+---
+
+## Records Admin Shell
+
+The primary export. A complete admin UI for managing `app.records` — typed JSON blobs attached to facets, products, variants, and batches — with scope inheritance built in. You provide the form for one record; the shell handles everything else.
+
+```tsx
+import {
+  RecordsAdminShell,
+  InheritanceMarker,
+  type EditorContext,
+} from '@proveanything/smartlinks-utils-ui/records-admin';
+import * as SL from '@proveanything/smartlinks';
+
+<RecordsAdminShell<NutritionData>
+  SL={SL}
   collectionId={collectionId}
   appId={appId}
   recordType="nutrition"
-  renderForm={(record, parentRecord) => <NutritionForm record={record} parent={parentRecord} />}
+  label="Nutrition info"
+  scopes={['facet', 'product', 'variant', 'batch']}
+  contextScope={{ productId, variantId, batchId }}   // from iframe URL — optional
+  defaultData={() => ({})}
+  csvSchema={{ columns: [/* ... */] }}
+  renderEditor={(ctx) => <NutritionForm ctx={ctx} />}
+  renderPreview={({ resolved }) => <pre>{JSON.stringify(resolved, null, 2)}</pre>}
 />
 ```
 
-`RecordsAdminShell` handles: left-rail product/scope browsing, variant/batch tab discovery, the "New record" button, inheritance markers, bulk operations, CSV import/export, and telemetry events. Your app only provides the domain form.
+**What it handles:**
+
+- **Browser pane** with scope tabs (Facet / Product / Variant / Batch), search, and status filter pills (All / Configured / Partial / Empty)
+- **Editor pane** with sticky save / discard / delete footer
+- **Per-field `<InheritanceMarker>`** showing whether a value is the record's own or inherited from a parent scope, with one-click revert-to-inherited
+- **Inheritance resolver** walks `batch → variant → product → facet` and returns both the resolved and parent values
+- **Collection-aware tabs**: calls `collection.get` and hides Variants / Batches tabs unless `collection.variants` / `collection.batches` are true — no flicker
+- **Server-side pagination** via `useInfiniteQuery` — handles thousands of products with a "Load more" button
+- **Context-aware**: pass `contextScope` from your iframe URL (`productId` / `variantId` / `batchId`) and the browser is constrained to that subtree with the right tab auto-selected
+- **CSV import / export** with a schema you define; failed rows come back as an annotated CSV
+- **Bulk actions menu** (apply-to-many, copy-from, clear) via `bulkUpsert` / `bulkDelete`
+- **Telemetry hook** (`onTelemetry`) emits typed events for save, delete, scope change, CSV import/export, bulk apply
+- **i18n strings** fully overridable
+
+> Requires a `<QueryClientProvider>` from `@tanstack/react-query` somewhere up the tree.
 
-### Record editor primitive
+### Lower-level pieces (advanced use)
 
 ```tsx
-import { RecordEditor } from '@proveanything/ui-utils';
-
-// Lower-level editor with inheritance diffing. Use when you need
-// custom layout but still want the inherited/override markers.
-<RecordEditor
-  record={variantRecord}
-  parentRecord={productRecord}
-  fields={nutritionFields}
-  onSave={(data) => app.records.update(collectionId, appId, record.id, { data }, true)}
-/>
+import {
+  // Hooks
+  useRecordList, useRecordEditor, useResolvedRecord, useScopeProbe,
+  // Data helpers
+  parseRef, buildRef, resolutionChain,
+  listRecords, getRecordByRef, upsertRecord, deleteRecord,
+  bulkUpsert, bulkDelete,
+  exportCsv, importCsv, downloadBlob,
+  // UI pieces
+  RecordBrowser, RecordEditor, ScopeBreadcrumb,
+  InheritanceMarker, ResolvedPreview, BulkActionsMenu,
+} from '@proveanything/smartlinks-utils-ui/records-admin';
 ```
 
 ### `useResolvedRecord` hook
 
 ```ts
-import { useResolvedRecord } from '@proveanything/ui-utils/records';
+import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
 
 const { data, source, isLoading } = useResolvedRecord({
+  SL,
   appId,
   recordType: 'nutrition',
   collectionId,
@@ -73,27 +139,12 @@ const { data, source, isLoading } = useResolvedRecord({
 // source: 'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'default' | null
 ```
 
-Walks the resolution chain defined in [records-admin-pattern.md §4](records-admin-pattern.md#4-resolution-order-required) and returns the first matching record plus its source scope.
-
-### `resolveRecord` function
-
-```ts
-import { resolveRecord } from '@proveanything/ui-utils/records';
-
-// Async, non-hook version for executors and server-side logic.
-const resolved = await resolveRecord({
-  appId,
-  recordType: 'nutrition',
-  scope: { collectionId, productId, variantId, batchId, proofId },
-  supportedScopes: ['product', 'facet'], // optional — skip unsupported scopes
-});
-// → { record: AppRecord, source: string } | null
-```
+Walks the resolution chain defined in [records-admin-pattern.md §4](records-admin-pattern.md#4-resolution-order-required). Use this on the **public widget side** to read the correct value for a given context.
 
 ### `parseRef` / `buildRef` utilities
 
 ```ts
-import { parseRef, buildRef } from '@proveanything/ui-utils/records';
+import { parseRef, buildRef } from '@proveanything/smartlinks-utils-ui/records-admin';
 
 const parsed = parseRef('variant:prod_abc:var_500ml');
 // → { kind: 'variant', productId: 'prod_abc', variantId: 'var_500ml' }
@@ -102,26 +153,142 @@ const ref = buildRef({ kind: 'facet', facetKey: 'bread_type', valueKey: 'sourdou
 // → 'facet:bread_type:sourdough'
 ```
 
-See [records-admin-pattern.md Appendix A](records-admin-pattern.md#appendix-a--ref-parser-reference) for the full `ParsedRef` type and standalone implementation.
+See [records-admin-pattern.md Appendix A](records-admin-pattern.md#appendix-a--ref-parser-reference) for the full `ParsedRef` type.
+
+---
+
+## Asset Picker
+
+```tsx
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui/asset-picker';
+
+<AssetPicker
+  scope={{ type: 'collection', collectionId: 'abc123' }}
+  mode="dialog"               // or "inline"
+  allowUpload
+  accept={['image/*']}        // MIME filtering
+  onSelect={(asset) => setHeroUrl(asset.url)}
+  trigger={<Button>Choose image</Button>}
+/>
+```
+
+**What it does:**
+- Browses assets at **collection** or **product** scope (dual-scope tabs)
+- Four ingest paths: file upload, URL import, clipboard paste (with rename preview), and selection from existing assets
+- Inline mode for embedding in a panel; dialog mode for modal pickers
+- Double-click a tile to confirm instantly
+
+---
+
+## Icon Picker
+
+```tsx
+import { IconPicker } from '@proveanything/smartlinks-utils-ui/icon-picker';
+
+<IconPicker
+  mode="dialog"
+  value="fa-solid fa-heart"
+  onSelect={(icon) => setIcon(icon.name)}
+  trigger={<Button>Pick icon</Button>}
+/>
+```
+
+**What it does:**
+- Searches **Font Awesome 7 Pro** (uses the shared kit `75493b59b3`)
+- Family hierarchy: Classic (Solid / Regular / Light), Duotone, and Brands
+- Search-first with a background catalogue crawler — first results appear instantly, the full index fills in behind
+- Auto-switches families intelligently (e.g. brand searches surface brand icons even when "Classic" is selected)
+
+> Requires the FA kit script to be present on the host page.
+
+---
+
+## Font Picker
+
+```tsx
+import { FontPicker } from '@proveanything/smartlinks-utils-ui/font-picker';
+
+<FontPicker
+  mode="dialog"
+  value="Inter"
+  showPreview
+  onSelect={(font) => {
+    console.log(font.family);        // "Inter"
+    console.log(font.cssFontFamily); // "'Inter', ui-sans-serif, system-ui, sans-serif"
+    console.log(font.loadSnippet);   // <link href="..." rel="stylesheet">
+  }}
+/>
+
+{/* With custom fonts uploaded into the collection */}
+<FontPicker
+  mode="dialog"
+  showCustomFonts
+  scope={{ collectionId: 'abc123' }}
+  onSelect={(font) => /* ... */}
+/>
+```
+
+**What it does:**
+- Full **Google Fonts** catalogue plus any **custom fonts** uploaded for the brand (stored via `appConfiguration` under `customFonts`)
+- Upload zone auto-detects weight/style from the filename (e.g. `MyFont-BoldItalic.woff2`)
+- Returns a `FontSelection` with `family`, `cssFontFamily`, and a ready-to-inject `loadSnippet` (`<link>` for Google fonts, `@font-face` CSS for custom uploads)
+- Lazy-loads previews via `IntersectionObserver`; includes a management UI for editing custom font definitions
+
+---
+
+## Conditions Editor
+
+```tsx
+import { ConditionsEditor } from '@proveanything/smartlinks-utils-ui/conditions-editor';
+
+<ConditionsEditor
+  value={rules}
+  onChange={setRules}
+  collectionId={collectionId}     // auto-loads facet definitions
+  versions={[{ title: 'Default', value: '' }]}
+  tags={['featured', 'new']}
+/>
+```
+
+**What it does:**
+- Recursive AND / OR group builder — nest conditions to any depth
+- **12 condition types:** Version, Country, Value, User, Date, Device, Tag, Facet, Geofence, Product, Item Status, Condition Reference
+- **Facet condition** auto-fetches definitions from `facets.publicList(collectionId, { includeValues: true })` when only `collectionId` is passed (SDK ≥ 1.9.20)
+- **Country picker** is a searchable multi-select with removable ISO 3166-1 chips and a "Use regions" toggle
+- Renders correctly inside iframe contexts — avoids `overflow-hidden` so dropdowns escape their cards
+
+---
+
+## Tree shaking
+
+Each component has its own subpath export:
+
+```tsx
+// Bundles only the Asset Picker
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui/asset-picker';
+
+// Barrel import — bundler tree-shakes the rest
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui';
+```
+
+If you use subpath imports, import `styles.css` separately — subpaths do not pull it in automatically.
 
 ---
 
 ## Relationship to the core SDK
 
 ```
-@proveanything/smartlinks       ← data layer (records, config, interactions, …)
+@proveanything/smartlinks            ← data layer (records, config, interactions, …)
         ↑
-@proveanything/ui-utils         ← UI layer (components, hooks, admin shells)
+@proveanything/smartlinks-utils-ui   ← UI layer (components, hooks, admin shells)
         ↑
-your microapp                   ← domain logic and custom forms
+your microapp                        ← domain logic and custom forms
 ```
 
-`ui-utils` imports from `@proveanything/smartlinks` internally. You should install both packages, but only import directly from each for their respective concerns — don't reach into `ui-utils` for SDK data primitives.
-
 ---
 
 ## Further reading
 
 - [records-admin-pattern.md](records-admin-pattern.md) — the data contract that `RecordsAdminShell` implements
-- [building-react-components.md](building-react-components.md) — dual-mode rendering rules that apply to all ui-utils components
+- [building-react-components.md](building-react-components.md) — dual-mode rendering rules that apply to all components
 - [app-manifest.md](app-manifest.md) — the `records` manifest block that drives tab generation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.9.21",
+  "version": "1.9.22",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",