@proveanything/smartlinks 2.0.11 → 2.0.13

package/docs/css-baseline.md

@@ -0,0 +1,133 @@
+# SmartLinks CSS baseline (`sl-baseline`)
+
+> **Status: SHIPPED — `v1`, frozen.** The SDK ships `@proveanything/smartlinks/baseline.css`
+> (+ `baseline.classes.json`); the Portal/Hub serve it and apps opt in via
+> `meta.cssBaseline: "v1"`. `v1` is frozen: an existing `sl-*` rule's meaning never changes;
+> new capability ships as `v2` alongside. Supersedes the earlier "shared Tailwind base" idea —
+> that approach (sharing raw generated Tailwind) was too large and could never safely change;
+> this is the version that survives being frozen for years.
+
+A small, **frozen, namespaced** set of structural CSS helpers the platform guarantees are
+present, so any sub-app — and any AI/markdown/dynamic content renderer inside one — can rely
+on them. It is **mechanics, not aesthetics**: layout, spacing, sizing, type scale,
+responsive flow, radius/border/shadow, and a little motion. It never defines colours, fonts,
+or components — those are brand data and per-app.
+
+It is the CSS sibling of the JS shared-dependency contract, and like that contract **the SDK
+is the source of truth**: the SDK authors and ships the baseline; hosts and apps consume it.
+
+## Why this shape (and not the alternatives)
+
+- **Small + frozen** → maintainable for years. A 60–120-rule hand-authored contract can be
+  honoured indefinitely; a giant generated Tailwind sheet can't.
+- **Namespaced (`sl-`)** → zero collision with an app's own Tailwind (`flex`, `p-4`) or the
+  host. Apps use `sl-*` for the guaranteed floor *and* their own utilities side by side. This
+  is what removes the cascade/coexistence fragility.
+- **A stable contract, decoupled from Tailwind underneath** → the SDK may build it with
+  Tailwind 4/5/6 internally, but apps target `sl-*`, so Tailwind upgrades are free.
+- **Teachable** → ~100 stable primitives can be put in an AI prompt; the full Tailwind
+  surface cannot. Dynamic/AI content gets a guaranteed floor instead of hand-rolling CSS.
+- **A floor, not a ceiling** → opt-in, additive; apps are free to ignore it or write their
+  own CSS. It just guarantees a consistent structural baseline when they want it.
+
+## Responsive: container-query-backed, breakpoint-named
+
+Apps render **both** as containers (in the host document) and as iframes. Plain viewport
+`@media` is inconsistent across those — in an iframe it sees the iframe size (usually right),
+in a container it sees the *host* viewport (wrong for a sub-region). So the responsive
+primitives are **container-query based** (`@container`), exposed with familiar breakpoint
+names so authors/AI still think "phone / tablet / desktop":
+
+- The app's mount root is a **container context** (`sl-container`, i.e. `container-type:
+  inline-size`) — set by the host on container mounts and by the app root in iframe mode.
+- `sl-md-grid-2` then means "when **my** box is ≥ tablet width", correct in both embed modes.
+- Breakpoints (container widths): `sm` ≥ 480px, `md` ≥ 768px, `lg` ≥ 1024px.
+
+This is the "works well on mobile / tablet / desktop" house opinion, done correctly for an
+embed-first platform.
+
+## The v1 surface (frozen)
+
+All names `sl-`-prefixed. Responsive variants exist only for the layout-flow primitives
+marked ✦ (as `sl-{sm|md|lg}-<name>`), to keep the set teachable and small.
+
+**Reset & a11y**
+`sl-reset` (border-box + margin:0 on self/descendants) · `sl-media` (max-width:100%,
+height:auto) · `sl-focus` (keyboard-only focus ring) · `sl-sr-only` · `sl-container`
+(responsive container context)
+
+**Display ✦** `sl-block` · `sl-inline-block` · `sl-inline` · `sl-flex` · `sl-inline-flex` ·
+`sl-grid` · `sl-hidden`
+
+**Flex ✦(direction)** `sl-flex-row` · `sl-flex-col` · `sl-flex-wrap` · `sl-flex-nowrap` ·
+`sl-items-{start,center,end,stretch,baseline}` · `sl-justify-{start,center,end,between,around}`
+· `sl-flex-1` · `sl-flex-auto` · `sl-grow-0` · `sl-shrink-0`
+
+**Grid ✦(columns)** `sl-grid-{2,3,4}` (collapse to 1 col below `sm`) · `sl-grid-auto`
+(auto-fit minmax) · `sl-col-span-full`
+
+**Spacing** — curated 8-step scale `0,1,2,3,4,5,6,7` ≈ `0, .25, .5, .75, 1, 1.5, 2, 3 rem`.
+Logical properties (RTL-safe): `sl-gap-{0..7}` · `sl-p-{0..7}` · `sl-px-{0..7}` ·
+`sl-py-{0..7}` · `sl-ps-{0..7}` / `sl-pe-{0..7}` (inline start/end) · `sl-m-{0..7}` ·
+`sl-mx-auto` · `sl-mt-{0..7}` · `sl-mb-{0..7}`
+
+**Sizing** `sl-w-full` · `sl-h-full` · `sl-min-w-0` · `sl-max-w-{reading(42rem),prose(65ch),
+page(72rem)}` · `sl-aspect-{square,wide(16/9)}`
+
+**Typography** — static rem scale (predictable in any embed; use the responsive `✦` align
+and per-breakpoint sizing where you want type to change). `sl-text-{xs,sm,base,lg,xl,2xl,3xl,
+4xl}` · `sl-font-{normal,medium,semibold,bold}` · `sl-leading-{tight,normal,relaxed}` ·
+`sl-tracking-{tight,normal}` · `sl-text-{left,center,right}` ✦(align) · `sl-truncate` ·
+`sl-line-clamp-{2,3}` · `sl-balance` (text-wrap:balance) · `sl-pretty`
+
+**Radius / border / shadow** — neutral mechanics only (no brand colour). `sl-rounded-{sm,md,
+lg,xl,full}` · `sl-border` / `sl-border-0` (colour = `--sl-border`, a subtle
+`color-mix(currentColor 14%, transparent)` default, overridable) · `sl-shadow-{sm,md,lg}`
+(neutral)
+
+**Object-fit / overflow** `sl-cover` · `sl-contain` · `sl-overflow-hidden` · `sl-overflow-auto`
+
+**Position & layering** `sl-relative` · `sl-absolute` · `sl-sticky` · `sl-inset-0` ·
+`sl-z-{base,raised,overlay}` (named levels — a house layering convention so apps don't fight
+over z-index)
+
+**Motion** (small, reduced-motion-safe; keyframes are `sl-`-namespaced) `sl-transition`
+(standard ease/duration) · `sl-reveal` (fade-up on view) · `sl-hover-lift` · all motion is
+**disabled under `prefers-reduced-motion`**. Rich motion vocabularies stay per-app (and may
+become a separate versioned motion contract later if several apps want to share one).
+
+### Explicitly NOT in the baseline (non-goals)
+- **No colours** — brand data, delivered via CSS variables / theme params.
+- **No fonts** — per-app; the baseline sets a *scale*, never a family.
+- **No components** — no buttons/cards/nav; those are per-app aesthetics.
+- **No full utility surface** — anything bespoke ships in the app's own scoped CSS.
+
+## Delivery — one SDK source, two paths
+
+The SDK ships the compiled baseline as `@proveanything/smartlinks/baseline.css` (+ the
+machine-readable class list for the doctor). One authored source; two delivery mechanisms:
+
+| Embed mode | How the app gets it |
+|---|---|
+| **Container (ESM/UMD)** — same document as host | Host has already loaded `baseline.css`; the app **ships nothing** and just uses `sl-*`. Declares `meta.cssBaseline: "v1"`. |
+| **Iframe** — its own document | The app **imports the SDK's `baseline.css`** into its own document (it inherits nothing, exactly like it must carry its own modules). Byte-identical to the host copy. |
+
+Cascade: baseline loads first; app CSS after → app rules win ties. `sl-*` never collides with
+app utilities regardless.
+
+## SDK / build support (kept minimal — no CSS surgery)
+- The SDK **exports `baseline.css`** (and `baseline.classes.json`), built in the SDK's own
+  build so the file and the class list can't drift.
+- Manifest field **`meta.cssBaseline: "v1"`** — declares reliance so the host can guarantee
+  it's present.
+- `smartlinks-doctor`: warn if an app declares `cssBaseline` but uses an `sl-*` class outside
+  the declared version (the useful invariant — spirit of the JS import check). No subtraction
+  tooling needed: `sl-*` is a fixed vocabulary apps just use.
+
+## Versioning & freeze
+- `v1` is **frozen**: an existing `sl-*` class's meaning/output never changes in place.
+- New capability ships as `v2` **alongside** `v1` (both served), never a silent mutation.
+- Tailwind (or whatever builds it) may be upgraded underneath as long as the `sl-*` contract
+  keeps its meaning.
+- Governance: additions to the surface go through review (it's a decades-long contract);
+  err toward *stable and generous* over minimal, since the AI builders target it.

package/docs/host-dependency-contract.md

@@ -32,7 +32,8 @@ export default defineConfig({
         'react', 'react-dom', 'react/jsx-runtime',
         '@proveanything/smartlinks',
         'react-router-dom', '@tanstack/react-query',
-        'lucide-react', 'date-fns', 'liquidjs', 'marked', 'class-variance-authority',
+        'lucide-react', 'date-fns', 'liquidjs', 'marked', 'dompurify', 'clsx', 'tailwind-merge',
+        'class-variance-authority',
         '@radix-ui/react-slot', '@radix-ui/react-dialog', '@radix-ui/react-popover',
         '@radix-ui/react-tooltip', '@radix-ui/react-tabs', '@radix-ui/react-accordion',
         '@radix-ui/react-select', '@radix-ui/react-scroll-area', '@radix-ui/react-label',
@@ -44,7 +45,8 @@ export default defineConfig({
           '@proveanything/smartlinks': 'SL',
           'react-router-dom': 'ReactRouterDOM', '@tanstack/react-query': 'ReactQuery',
           'lucide-react': 'LucideReact', 'date-fns': 'dateFns', 'liquidjs': 'LiquidJS',
-          'marked': 'marked', 'class-variance-authority': 'CVA',
+          'marked': 'marked', 'dompurify': 'DOMPurify', 'clsx': 'clsx',
+          'tailwind-merge': 'tailwindMerge', 'class-variance-authority': 'CVA',
           '@radix-ui/react-slot': 'RadixSlot', '@radix-ui/react-dialog': 'RadixDialog',
           '@radix-ui/react-popover': 'RadixPopover', '@radix-ui/react-tooltip': 'RadixTooltip',
           '@radix-ui/react-tabs': 'RadixTabs', '@radix-ui/react-accordion': 'RadixAccordion',
@@ -72,6 +74,9 @@ export default defineConfig({
 | `date-fns` | `dateFns` | 4.4 |
 | `liquidjs` | `LiquidJS` | 10.27+ |
 | `marked` | `marked` | 12+ |
+| `dompurify` | `DOMPurify` | 3+ |
+| `clsx` | `clsx` | 2+ |
+| `tailwind-merge` | `tailwindMerge` | 3+ |
 | `class-variance-authority` | `CVA` | 0.7 |
 | `@radix-ui/react-slot` | `RadixSlot` | 1.2.4 |
 | `@radix-ui/react-dialog` | `RadixDialog` | 1.1.23 |
@@ -86,10 +91,15 @@ export default defineConfig({
 | `@radix-ui/react-progress` | `RadixProgress` | 1.1.8 |
 | `@radix-ui/react-avatar` | `RadixAvatar` | 1.1.11 |
 
-`liquidjs` and `marked` are **host-provided** — externalise them, don't ship a second copy
-(frequently missed). `marked` is new in **contract v6**: the portal and hub render markdown in the
-container, so an app should use the host's renderer rather than bundling its own. `marked` does not
-sanitise HTML — if you render untrusted markdown, sanitise the output (e.g. DOMPurify) yourself.
+`liquidjs`, `marked`, `dompurify`, `clsx` and `tailwind-merge` are **host-provided** — externalise
+them, don't ship a second copy (frequently missed). `marked` arrived in **v6**; `dompurify`, `clsx`
+and `tailwind-merge` in **v7**. The portal and hub render markdown in the container, so use the
+host's `marked` rather than bundling your own. `marked` does not sanitise HTML — pair it with the
+shared `dompurify`: `el.innerHTML = DOMPurify.sanitize(marked.parse(md))`. `window.DOMPurify` is the
+**configured instance** (callable, `.sanitize()`), so `import DOMPurify from 'dompurify'` behaves
+exactly like a bundled default import. `clsx` + `tailwind-merge` are the standard `cn()` pair
+(`import { clsx } from 'clsx'; import { twMerge } from 'tailwind-merge'`) — keep your local `cn()`
+helper if you like, it just stops paying the bundle cost.
 
 ## Backwards compatibility
 
@@ -111,11 +121,18 @@ Bundles ship their own compiled CSS, so the host's Tailwind version is irrelevan
 micro-app can stay on **Tailwind 3 indefinitely**, or adopt Tailwind 4 — its choice. (The starter
 app ships the Tailwind 4 CSS-first layout as the default; see its README.)
 
+> **CSS baseline (`sl-baseline` v1):** the CSS sibling of this JS contract, but deliberately
+> **not** a shared Tailwind dump. It's a small, frozen, `sl-`-namespaced set of structural
+> helpers (layout, spacing, responsive flow, type scale, motion — no colours, fonts, or
+> components) the SDK ships (`@proveanything/smartlinks/baseline.css`) and the host serves.
+> Opt-in via `meta.cssBaseline: "v1"`. See [css-baseline.md](css-baseline.md).
+
 ## The R5 host stack (reference)
 
 React **19.3** · Vite **8.3** · react-router-dom **7.18** · Tailwind **4.3** (CSS-first) ·
 TypeScript **6.0** · ESLint **10.11** · `@proveanything/smartlinks` **2.0.5** ·
-`@proveanything/smartlinks-utils-ui` **1.16.4** · liquidjs **10.29** · marked **12+**.
+`@proveanything/smartlinks-utils-ui` **1.16.4** · liquidjs **10.29** · marked **12+** ·
+dompurify **3+** · clsx **2+** · tailwind-merge **3+**.
 
 > **TypeScript 7** (the native/Go compiler) is **deliberately deferred** — tooling hasn't settled.
 > Target **TS 6** for R5; it compiles existing code with no source changes.
@@ -142,8 +159,8 @@ never drift:
 
 ```ts
 import {
-  SHARED_DEPENDENCY_CONTRACT_VERSION, // 'v6'
-  SHARED_DEPENDENCIES,                // [{ specifier, globalName, minVersion, importMapPath }, …] (26)
+  SHARED_DEPENDENCY_CONTRACT_VERSION, // 'v7'
+  SHARED_DEPENDENCIES,                // [{ specifier, globalName, minVersion, importMapPath }, …] (29)
   SHARED_DEPENDENCY_SPECIFIERS,       // bare specifiers — drop straight into a bundler `external` list
   getHostSharedDependencies,          // what the live host advertises at runtime, or null
 } from '@proveanything/smartlinks'

package/docs/overview.md

@@ -63,6 +63,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Agent Tools** | `docs/agent-tools.md` | Exposing your app's actions to the SmartLinks agent — an MCP facade over server functions; **opt-in per app, additive, no migration**; complements `app.admin.json` (functions serve/adapt it, don't replace it); live loop staged |
 | **Deploying & Registering** | `docs/deploying-apps.md` | Getting your app into the platform: fast dev publish, channels, deploy keys, registering releases |
 | **Host Dependency Contract (R5)** | `docs/host-dependency-contract.md` | The libraries the host provides (React 19, Router 7, Radix, liquidjs, …), the externalise-don't-bundle rule + Vite config, and React-18 backwards-compat |
+| **CSS Baseline** (`sl-baseline` v1) | `docs/css-baseline.md` | A small, frozen, `sl-`-namespaced set of structural helpers (layout, spacing, responsive flow, type scale, motion) the SDK ships (`@proveanything/smartlinks/baseline.css`) and the host guarantees — a teachable floor for apps + AI content. No colours/fonts/components. Opt-in via `meta.cssBaseline` |
 | **Deep Linking** | `docs/deep-link-discovery.md` | URL state management, navigable states, portal menus, AI nav |
 | **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
 | **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |

package/openapi.yaml

@@ -17957,6 +17957,8 @@ components:
             - dual
         sharedDependencies:
           type: string
+        cssBaseline:
+          type: string
         globals:
           type: object
           additionalProperties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.11",
+  "version": "2.0.13",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,8 @@
       "import": "./dist/*.js",
       "default": "./dist/*.js"
     },
+    "./baseline.css": "./dist/baseline.css",
+    "./baseline.classes.json": "./dist/baseline.classes.json",
     "./package.json": "./package.json"
   },
   "bin": {
@@ -39,7 +41,7 @@
   ],
   "scripts": {
     "test": "node test/run.cjs",
-    "build": "tsc && node scripts/fix-esm-extensions.mjs && node generate-api-summary.cjs && node generate-openapi.cjs && node scripts/copy-docs-to-dist.cjs",
+    "build": "tsc && node scripts/fix-esm-extensions.mjs && node generate-api-summary.cjs && node generate-openapi.cjs && node scripts/copy-docs-to-dist.cjs && node scripts/build-baseline.mjs",
     "docs": "typedoc",
     "docs:summary": "node generate-api-summary.cjs",
     "docs:openapi": "node generate-openapi.cjs",
@@ -62,7 +64,8 @@
     "tag": "next"
   },
   "dependencies": {
-    "cross-fetch": "^3.1.5"
+    "cross-fetch": "^3.1.5",
+    "es-module-lexer": "^1.7.0"
   },
   "devDependencies": {
     "ts-node": "^10.9.1",

package/scripts/doctor.mjs

@@ -19,6 +19,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { bareImportsOf } from './lib/bare-imports.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -75,25 +76,9 @@ if (meta.sharedDependencies && meta.sharedDependencies !== SHARED_DEPENDENCY_CON
   warnings.push(`built against contract ${meta.sharedDependencies}, but this SDK ships ${SHARED_DEPENDENCY_CONTRACT_VERSION} — host may not serve a matching import map.`);
 }
 
-// Pull the bare imports out of a bundle (handles minified `from"x"` too).
-function bareImportsOf(code) {
-  const specs = new Set();
-  const patterns = [
-    /\bfrom\s*["']([^"']+)["']/g, // static import/export ... from "x"
-    /\bimport\s*["']([^"']+)["']/g, // side-effect import "x"
-    /\bimport\(\s*["']([^"']+)["']\s*\)/g, // dynamic import("x")
-  ];
-  for (const re of patterns) {
-    let m;
-    while ((m = re.exec(code))) {
-      const spec = m[1];
-      if (spec.startsWith('.') || spec.startsWith('/')) continue; // internal/relative
-      if (/^https?:/.test(spec)) continue; // absolute URL import
-      specs.add(spec);
-    }
-  }
-  return [...specs];
-}
+// bareImportsOf (scripts/lib/bare-imports.mjs) LEXES the bundle for real import
+// statements — so bundled data containing the word `from` (e.g. tailwind-merge's class
+// map) is not mistaken for an import.
 
 // Resolve a manifest-relative bundle path against the likely roots (dist paths
 // are sometimes relative to the app root, sometimes to the manifest dir).