@proveanything/smartlinks 2.0.51 → 2.0.52

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.51  |  Generated: 2026-10-10T07:57:23.889Z
+Version: 2.0.52  |  Generated: 2026-10-11T13:21:58.062Z
 
 This is a concise summary of all available API functions and types.
 

package/dist/docs/containers.md

@@ -62,7 +62,39 @@ Iframe Mode:
 **Where routing goes:**
 - ✅ Your **iframe entry point** (`App.tsx` / `main.tsx`) should use `HashRouter` 
 - ✅ Your **exported container** (`PublicContainer.tsx`) should include `<Routes>` and `<Route>` elements
-- ❌ Your **exported container** should NOT include any `<Router>` wrapper
+- ❌ Your **exported container** should NOT include any `<Router>` wrapper — *unless isolated* (below)
+
+### Pages that read their context from the URL: an isolated router
+
+The example app's pages read `collectionId` / `productId` / `proofId` from the URL. The framework's
+router starts at `/` without them, so the example's container keeps **its own** `MemoryRouter` (seeded
+with those params) — and **isolates** it from the host's router first. Since R5, `react-router-dom` is a
+shared dependency (the host's copy), so a plain nested router is the same library as the host's and
+throws _"You cannot render a `<Router>` inside another `<Router>`"_. Resetting the parent's location and
+navigation context gives your container a router of its own — the same isolation portal-framework puts
+around every direct component:
+
+```tsx
+import { MemoryRouter, Routes, Route, UNSAFE_LocationContext, UNSAFE_NavigationContext } from 'react-router-dom';
+
+export const PublicContainer = ({ collectionId, appId, productId, proofId }: SmartLinksContainerProps) => {
+  const q = new URLSearchParams({ collectionId, appId, ...(productId ? { productId } : {}), ...(proofId ? { proofId } : {}) });
+  return (
+    <UNSAFE_LocationContext.Provider value={null as any}>
+      <UNSAFE_NavigationContext.Provider value={null as any}>
+        <MemoryRouter initialEntries={[`/?${q}`]}>
+          <Routes>
+            <Route path="/*" element={<PublicPage />} />
+          </Routes>
+        </MemoryRouter>
+      </UNSAFE_NavigationContext.Provider>
+    </UNSAFE_LocationContext.Provider>
+  );
+};
+```
+
+Your container's own navigation then stays inside it (it isn't mirrored into the portal's deep link).
+`smartlinks-doctor` warns when a containers bundle uses a router without this isolation.
 
 ### The Router Contract
 

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.51  |  Generated: 2026-10-10T07:57:23.889Z
+Version: 2.0.52  |  Generated: 2026-10-11T13:21:58.062Z
 
 This is a concise summary of all available API functions and types.
 

package/docs/containers.md

@@ -62,7 +62,39 @@ Iframe Mode:
 **Where routing goes:**
 - ✅ Your **iframe entry point** (`App.tsx` / `main.tsx`) should use `HashRouter` 
 - ✅ Your **exported container** (`PublicContainer.tsx`) should include `<Routes>` and `<Route>` elements
-- ❌ Your **exported container** should NOT include any `<Router>` wrapper
+- ❌ Your **exported container** should NOT include any `<Router>` wrapper — *unless isolated* (below)
+
+### Pages that read their context from the URL: an isolated router
+
+The example app's pages read `collectionId` / `productId` / `proofId` from the URL. The framework's
+router starts at `/` without them, so the example's container keeps **its own** `MemoryRouter` (seeded
+with those params) — and **isolates** it from the host's router first. Since R5, `react-router-dom` is a
+shared dependency (the host's copy), so a plain nested router is the same library as the host's and
+throws _"You cannot render a `<Router>` inside another `<Router>`"_. Resetting the parent's location and
+navigation context gives your container a router of its own — the same isolation portal-framework puts
+around every direct component:
+
+```tsx
+import { MemoryRouter, Routes, Route, UNSAFE_LocationContext, UNSAFE_NavigationContext } from 'react-router-dom';
+
+export const PublicContainer = ({ collectionId, appId, productId, proofId }: SmartLinksContainerProps) => {
+  const q = new URLSearchParams({ collectionId, appId, ...(productId ? { productId } : {}), ...(proofId ? { proofId } : {}) });
+  return (
+    <UNSAFE_LocationContext.Provider value={null as any}>
+      <UNSAFE_NavigationContext.Provider value={null as any}>
+        <MemoryRouter initialEntries={[`/?${q}`]}>
+          <Routes>
+            <Route path="/*" element={<PublicPage />} />
+          </Routes>
+        </MemoryRouter>
+      </UNSAFE_NavigationContext.Provider>
+    </UNSAFE_LocationContext.Provider>
+  );
+};
+```
+
+Your container's own navigation then stays inside it (it isn't mirrored into the portal's deep link).
+`smartlinks-doctor` warns when a containers bundle uses a router without this isolation.
 
 ### The Router Contract
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.51",
+  "version": "2.0.52",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",

package/scripts/doctor.mjs

@@ -168,16 +168,26 @@ if (meta.cssBaseline) {
     for (const c of ['sl-mobile-admin']) baseSet.add(c);
     // Class usage lives in compiled markup strings — present in every bundle regardless
     // of module format, so scan both umd + esm across all surfaces.
+    // `sl-…` NOT preceded by a word char or hyphen: a class name, never a CSS custom property
+    // (`var(--sl-color-accent)`, `--sl-widget-accent`) — those are theme tokens, not classes.
+    // Classes the app defines itself (`.sl-foo {…}` in its own CSS) aren't missing either.
     const used = new Set();
+    const defined = new Set();
     for (const [, block] of surfaces) {
-      for (const p of [block?.files?.js?.umd, block?.files?.js?.esm]) {
-        if (!p) continue;
+      for (const p of [block?.files?.js?.umd, block?.files?.js?.esm, block?.files?.css]) {
+        if (!p || typeof p !== 'string') continue;
         const bp = resolveBundle(p);
         if (!bp) continue;
-        for (const m of readFileSync(bp, 'utf8').matchAll(/\bsl-[a-z0-9-]+/g)) used.add(m[0]);
+        const text = readFileSync(bp, 'utf8');
+        for (const m of text.matchAll(/(?<![\w-])sl-[a-z0-9-]+/g)) used.add(m[0]);
+        for (const m of text.matchAll(/\.(sl-[a-z0-9-]+)/g)) defined.add(m[1]);
       }
     }
-    const unknown = [...used].filter((c) => !baseSet.has(c)).sort();
+    const ownSl = [...defined].filter((c) => !baseSet.has(c)).sort();
+    if (ownSl.length) {
+      warnings.push(`the app's own classes use the platform's sl- prefix: ${ownSl.join(', ')} — rename them (e.g. drop the "sl-") so they can't collide with a future baseline class.`);
+    }
+    const unknown = [...used].filter((c) => !baseSet.has(c) && !defined.has(c)).sort();
     if (used.size === 0) {
       console.log(`${DIM}cssBaseline (${baseline.version}) — declared; no sl-* classes found in the bundles.${RESET}`);
     } else if (unknown.length === 0) {
@@ -238,6 +248,51 @@ if (meta.respectsHostTheme) {
   }
 }
 
+// ---- containers: a router of their own must be isolated from the host's ------------------------
+// Since R5, react-router-dom is SHARED with the host, so a container that wraps itself in a
+// MemoryRouter/HashRouter/BrowserRouter inside the host's router throws "You cannot render a <Router>
+// inside another <Router>" — unless it resets the parent's router context first (docs/containers.md →
+// "Pages that read their context from the URL"). Heuristic on the built bundle names; WARN-only.
+{
+  const block = manifest.containers;
+  for (const p of [block?.files?.js?.esm, block?.files?.js?.umd]) {
+    if (!p) continue;
+    const bp = resolveBundle(p);
+    if (!bp) continue;
+    const text = readFileSync(bp, 'utf8');
+    const routers = ['MemoryRouter', 'HashRouter', 'BrowserRouter'].filter((r) => new RegExp(`\\b${r}\\b`).test(text));
+    if (!routers.length) { console.log(`${GREEN}✓${RESET} containers ${DIM}— no router of their own (the host's is used)${RESET}`); break; }
+    if (/UNSAFE_LocationContext/.test(text)) { console.log(`${GREEN}✓${RESET} containers ${DIM}— own ${routers.join('/')} isolated from the host's router${RESET}`); break; }
+    console.log(`${YELLOW}⚠${RESET} containers — ${routers.join('/')} without isolating it from the host's router`);
+    warnings.push(`containers bundle renders its own ${routers.join('/')} but never resets the host's router context — inside an R5 host that throws "You cannot render a <Router> inside another <Router>". Wrap it in UNSAFE_LocationContext.Provider + UNSAFE_NavigationContext.Provider value={null} (docs/containers.md), or drop the router and use the host's.`);
+    break;
+  }
+}
+
+// ---- package.json scripts point at files that exist ------------------------------------------
+// An upgrade that copies a script LINE but not the script FILE breaks every build at that step
+// (e.g. `postbuild: node scripts/smartlinks-deploy.mjs` with no scripts/smartlinks-deploy.mjs).
+// WARN — the doctor runs inside the build, and a skipped hook (Forge builds skip pre/post) is harmless.
+try {
+  const pkg = JSON.parse(readFileSync(join(appDir, 'package.json'), 'utf8'));
+  const missing = [];
+  for (const [name, cmd] of Object.entries(pkg.scripts || {})) {
+    if (typeof cmd !== 'string') continue;
+    for (const m of cmd.matchAll(/(?:^|[;&|]\s*|\s)(?:node|tsx|ts-node|bash|sh)\s+(?:-{1,2}[\w-]+(?:=\S+)?\s+)*((?:\.{1,2}\/)?[\w./-]+\.(?:mjs|cjs|js|ts|sh))\b/g)) {
+      if (!existsSync(join(appDir, m[1]))) missing.push(`"${name}" runs ${m[1]}`);
+    }
+  }
+  if (missing.length) {
+    console.log(`${YELLOW}⚠${RESET} package.json scripts — ${missing.length} point${missing.length === 1 ? 's' : ''} at a file that doesn't exist:`);
+    for (const x of missing) console.log(`    ${YELLOW}${x}${RESET}`);
+    warnings.push(`package.json ${missing.join('; ')} — but the file is missing. Add the file, or remove the script (a pre/post hook like postbuild fails every \`npm run build\` without it).`);
+  } else {
+    console.log(`${GREEN}✓${RESET} package.json scripts ${DIM}— every script file they run exists${RESET}`);
+  }
+} catch {
+  /* no package.json — not an npm app */
+}
+
 console.log('');
 for (const w of warnings) console.log(`${YELLOW}⚠ ${w}${RESET}`);