@proveanything/smartlinks 2.0.5 → 2.0.9

package/dist/docs/containers.md

@@ -1,6 +1,6 @@
 # SmartLinks Containers
 
-> **Copy this file into `node_modules/@proveanything/smartlinks/docs/containers.md`** in the published SDK package.
+> **Not [container-tracking.md](container-tracking.md).** This doc is the embeddable full-app **bundle**; that one is about grouping physical/logical *items*.
 
 Containers are the **full public app experience** packaged as an embeddable React component. Unlike widgets (lightweight previews/cards), containers render the complete public interface — all pages, routing, and features — inside a parent React application.
 
@@ -15,7 +15,7 @@ Containers are the **full public app experience** packaged as an embeddable Reac
 | **Loading**     | Loaded immediately with page       | Lazy-loaded on demand                        |
 | **Routing**     | None (single component)            | MemoryRouter (parent owns URL bar)           |
 | **Use case**    | Cards, thumbnails, quick glance    | "Open full view", embedded experiences       |
-| **Build output**| `widgets.umd.js` / `widgets.es.js` | `containers.umd.js` / `containers.es.js`    |
+| **Build output**| `widgets.umd.js` / `widgets.esm.js` | `containers.umd.js` / `containers.esm.js`    |
 
 ### Why Separate Bundles?
 
@@ -104,54 +104,7 @@ export const PublicContainer = (props: Record<string, any>) => {
 
 ### The `useAppContext()` Pattern
 
-To write containers that work identically in both modes, use this abstraction pattern:
-
-```tsx
-// src/hooks/useAppContext.ts
-import { useContext, createContext, useMemo } from 'react';
-import { useSearchParams } from 'react-router-dom';
-
-export interface AppContextValue {
-  collectionId: string;
-  appId: string;
-  productId?: string;
-  proofId?: string;
-  pageId?: string;
-  initialPath?: string;
-  lang?: string;
-  user?: { id: string; email: string; name?: string };
-  SL: typeof import('@proveanything/smartlinks');
-  onNavigate?: (request: any) => void;
-}
-
-export const AppContext = createContext<AppContextValue | null>(null);
-
-/**
- * Returns app context regardless of rendering mode.
- * - Direct component mode: reads from AppContext (props)
- * - Iframe mode: reads from URL search params
- */
-export function useAppContext(): AppContextValue {
-  const ctx = useContext(AppContext);
-  
-  // If context exists, we're in direct-component mode
-  if (ctx) return ctx;
-  
-  // Otherwise, we're in iframe mode — read from URL params
-  const [searchParams] = useSearchParams();
-  const SL = (window as any).SL ?? require('@proveanything/smartlinks');
-
-  return useMemo(() => ({
-    collectionId: searchParams.get('collectionId') ?? '',
-    appId: searchParams.get('appId') ?? '',
-    productId: searchParams.get('productId') ?? undefined,
-    proofId: searchParams.get('proofId') ?? undefined,
-    pageId: searchParams.get('pageId') ?? undefined,
-    lang: searchParams.get('lang') ?? undefined,
-    SL,
-  }), [searchParams, SL]);
-}
-```
+Containers read their context through the same shared **`useAppContext()`** hook as widgets, so one codebase works in both direct-component and iframe modes. See **[building-react-components.md](building-react-components.md#the-useappcontext-pattern)** for the canonical hook + `AppContext` provider — don't re-define it. Containers additionally carry an **`initialPath?`** field on the context (the entry route the host asked for).
 
 **Usage in your container:**
 
@@ -323,7 +276,7 @@ Parent App (owns URL bar, provides globals)
 
 ```typescript
 // Lazy-load the container only when needed
-const { PublicContainer } = await import('https://my-app.com/containers.es.js');
+const { PublicContainer } = await import('https://my-app.com/containers.esm.js');
 
 <PublicContainer
   collectionId="abc"
@@ -345,27 +298,22 @@ const { PublicContainer } = await import('https://my-app.com/containers.es.js');
 <!-- Ensure shared globals are set up first (see Shared Dependencies Contract) -->
 <script src="https://my-app.com/containers.umd.js"></script>
 <script>
-  const { PublicContainer } = window.SmartLinksContainers;
-  // Render with React
+  // The UMD global is PER-APP NAMESPACED — read the name from the manifest
+  // (manifest.meta.globals.containers), e.g. "SmartLinksContainers__myApp".
+  // Do NOT use a bare `window.SmartLinksContainers` — it collides across apps.
+  const globalName = manifest.meta.globals.containers;
+  const { PublicContainer } = window[globalName];
+  // Render with React (or prefer the ESM path: import from containers.esm.js)
 </script>
 ```
 
 ---
 
-## Shared Dependencies Contract
-
-Containers use the **exact same Shared Dependencies Contract** as widgets. No additional globals are needed. The parent app must expose these globals before loading container bundles:
-
-- React, ReactDOM, jsxRuntime
-- SL (SmartLinks SDK)
-- CVA (class-variance-authority) — **uppercase to avoid `cva.cva` collision**
-- ReactRouterDOM, ReactQuery
-- LucideReact, dateFns, LiquidJS
-- 12 Radix UI primitives (Slot, Dialog, Popover, Tooltip, Tabs, Accordion, Select, ScrollArea, Label, Toast, Progress, Avatar)
+## Shared dependencies
 
-See `widgets.md` for the complete table with globals and version expectations.
+Containers externalize the **exact same shared-dependency contract** as widgets — resolved from host globals (UMD) or the import map (ESM); no extra globals are needed. **The full versioned list, window-global names, and Vite `external`/`globals` config are canonical in [host-dependency-contract.md](host-dependency-contract.md)** — externalize exactly that set (from the SDK's `SHARED_DEPENDENCY_SPECIFIERS`) and never bundle your own React.
 
-> **Why `CVA` not `cva`?** The `class-variance-authority` package exports a named function called `cva`. If the UMD global is also `cva`, the wrapper resolves it as `window.cva.cva` — a double-nesting bug. Using uppercase `CVA` avoids this collision.
+> **Why `CVA` not `cva`?** `class-variance-authority` exports a function named `cva`; if the UMD global were also `cva`, the wrapper resolves it as `window.cva.cva` — a double-nesting bug. The contract uses uppercase `CVA` to avoid the collision.
 
 ---
 
@@ -396,7 +344,7 @@ vite build --config vite.config.container.ts
 ```text
 dist/
 ├── containers.umd.js    # Full app container (UMD)
-├── containers.es.js     # Full app container (ESM)
+├── containers.esm.js    # Full app container (ESM)
 └── containers.css       # Container styles
 ```
 

package/dist/docs/deploying-apps.md

@@ -1,8 +1,7 @@
 # Deploying & registering an app
 
-> **Preview — SmartLinks SDK 2.0.0-alpha.** Part of the installable-app platform being built
-> toward 2.0.0 stable. These APIs may change before then. Published under the npm `next` tag;
-> `latest` remains 1.x.
+> **SmartLinks SDK 2.x** (current `latest`). Part of the installable-app platform. Install
+> `@proveanything/smartlinks@^2`.
 
 A SmartLinks app is a bundle (widgets, containers, and — new — [server functions](server-functions.md))
 described by an `app.manifest.json`. Deploying an app has two halves:
@@ -56,6 +55,12 @@ no secret; it's rate-limited and de-duped per app.
 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.
 
+**If a publish doesn't appear:** because the ping is fire-and-forget, a failure (e.g. the build
+hash never went live, or an invalid manifest) happens in the background — it won't show in your
+build output. Every attempt (success *and* failure, with the reason) is recorded, and the platform
+owner can see it in the console at **Admin → App Registry → Recent activity**. That's the place to
+look for "I hit Publish but dev didn't change."
+
 ### B. From local / CI / Claude — `smartlinks-publish`
 
 If you build somewhere you control (so you can hold a dev key locally — never committed), push the

package/dist/docs/executor.md

@@ -1,12 +1,12 @@
 # SmartLinks Executor Model
 
-> **SDK minimum:** `@proveanything/smartlinks@1.4.1`
+> **SDK:** `@proveanything/smartlinks@^2.0` (R5 baseline; build against 2.0.7+)
 
 ---
 
 ## What Is an Executor?
 
-An executor is a **standalone JavaScript library** (`executor.umd.js` / `executor.es.js`) that a SmartLinks app ships alongside its widget and container bundles. It exposes programmatic functions that external systems — AI orchestrators, the Hub server, setup wizards — can call **without rendering the app's UI**.
+An executor is a **standalone JavaScript library** (`executor.umd.js` / `executor.esm.js`) that a SmartLinks app ships alongside its widget and container bundles. It exposes programmatic functions that external systems — AI orchestrators, the Hub server, setup wizards — can call **without rendering the app's UI**.
 
 Every app can optionally ship an executor. The executor pattern solves three problems that iframe-based apps can't address on their own:
 
@@ -38,7 +38,7 @@ Every executor is declared in `app.manifest.json` so the platform can discover a
   },
   "executor": {
     "files": {
-      "js": { "umd": "dist/executor.umd.js", "esm": "dist/executor.es.js" }
+      "js": { "umd": "dist/executor.umd.js", "esm": "dist/executor.esm.js" }
     },
     "factory": "createMyAppExecutor",
     "exports": ["createMyAppExecutor", "getSEO", "getLLMContent"],
@@ -61,7 +61,7 @@ Every executor is declared in `app.manifest.json` so the platform can discover a
 
 ```typescript
 // ESM (modern bundlers, Deno, Node 18+)
-const { createMyAppExecutor } = await import('https://my-app.smartlinks.app/dist/executor.es.js');
+const { createMyAppExecutor } = await import('https://my-app.smartlinks.app/dist/executor.esm.js');
 
 // UMD (script tag, legacy environments)
 // After loading executor.umd.js:

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

@@ -0,0 +1,159 @@
+# Host dependency contract (R5)
+
+> **SmartLinks SDK 2.x** (current `latest`). The portal host (R5) provides a fixed set of runtime
+> libraries as window globals. Micro-apps **externalise** these and resolve them from the host —
+> they must **not** bundle their own copies. This keeps one instance of React (and friends) on the
+> page and keeps bundles small.
+
+## The one rule that matters: externalise, never bundle
+
+A container/widget/executor bundle **must externalise `react`, `react-dom`, and every shared
+dependency below**, resolving them from the host globals. **Bundling your own React is the one
+hard failure** — two React instances on the page → hooks break → crash. (Bundling `liquidjs` or
+another shared lib is wasteful and can double-load, but React is the fatal one.)
+
+React-18-built bundles keep working on the R5 host: they externalise React and run against the
+host's **React 19** runtime. A bundle compiled against React 18 *typings* runs fine on the 19
+*runtime* — see backwards-compatibility below.
+
+## Vite / Rollup config
+
+Externalise the shared deps and map each to its window global:
+
+```ts
+// vite.config.ts (library build for a container/widget/executor)
+import { defineConfig } from 'vite'
+export default defineConfig({
+  build: {
+    lib: { entry: 'src/index.tsx', formats: ['umd'], name: 'MyApp', fileName: () => 'widgets.umd.js' },
+    rollupOptions: {
+      // Everything the host provides — do NOT bundle these.
+      external: [
+        'react', 'react-dom', 'react/jsx-runtime',
+        '@proveanything/smartlinks',
+        'react-router-dom', '@tanstack/react-query',
+        'lucide-react', 'date-fns', 'liquidjs', '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',
+        '@radix-ui/react-toast', '@radix-ui/react-progress', '@radix-ui/react-avatar',
+      ],
+      output: {
+        globals: {
+          'react': 'React', 'react-dom': 'ReactDOM', 'react/jsx-runtime': 'jsxRuntime',
+          '@proveanything/smartlinks': 'SL',
+          'react-router-dom': 'ReactRouterDOM', '@tanstack/react-query': 'ReactQuery',
+          'lucide-react': 'LucideReact', 'date-fns': 'dateFns', 'liquidjs': 'LiquidJS',
+          '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',
+          '@radix-ui/react-select': 'RadixSelect', '@radix-ui/react-scroll-area': 'RadixScrollArea',
+          '@radix-ui/react-label': 'RadixLabel', '@radix-ui/react-toast': 'RadixToast',
+          '@radix-ui/react-progress': 'RadixProgress', '@radix-ui/react-avatar': 'RadixAvatar',
+        },
+      },
+    },
+  },
+})
+```
+
+## Host-provided globals (build against versions ≤ these)
+
+| Import | Window global | Host provides (R5) |
+|---|---|---|
+| `react` | `React` | 19.3 (accepts 18.3 builds) |
+| `react-dom` | `ReactDOM` | 19.3 (accepts 18.3 builds) |
+| `react/jsx-runtime` | `jsxRuntime` | 19.3 |
+| `@proveanything/smartlinks` | `SL` | 2.0.5 |
+| `react-router-dom` | `ReactRouterDOM` | 7.18 (accepts 6.x builds) |
+| `@tanstack/react-query` | `ReactQuery` | 5.103 |
+| `lucide-react` | `LucideReact` | 1.47 |
+| `date-fns` | `dateFns` | 4.4 |
+| `liquidjs` | `LiquidJS` | 10.27+ |
+| `class-variance-authority` | `CVA` | 0.7 |
+| `@radix-ui/react-slot` | `RadixSlot` | 1.2.4 |
+| `@radix-ui/react-dialog` | `RadixDialog` | 1.1.23 |
+| `@radix-ui/react-popover` | `RadixPopover` | 1.1.1 |
+| `@radix-ui/react-tooltip` | `RadixTooltip` | 1.2.8 |
+| `@radix-ui/react-tabs` | `RadixTabs` | 1.1.13 |
+| `@radix-ui/react-accordion` | `RadixAccordion` | 1.2.12 |
+| `@radix-ui/react-select` | `RadixSelect` | 2.3.7 |
+| `@radix-ui/react-scroll-area` | `RadixScrollArea` | 1.2.10 |
+| `@radix-ui/react-label` | `RadixLabel` | 2.1.8 |
+| `@radix-ui/react-toast` | `RadixToast` | 1.2.15 |
+| `@radix-ui/react-progress` | `RadixProgress` | 1.1.8 |
+| `@radix-ui/react-avatar` | `RadixAvatar` | 1.1.11 |
+
+`liquidjs` is **host-provided** — externalise it, don't ship a second copy (frequently missed).
+
+## Backwards compatibility
+
+React-18-built containers and widgets keep working unchanged on R5. A pre-existing bundle only
+breaks if it:
+
+- calls `ReactDOM.render` / `hydrate` / `unmountComponentAtNode` (self-mounting — containers are
+  mounted by the host, so this only affects apps that mount themselves);
+- relies on `defaultProps` / `propTypes` on **function** components (React 19 silently ignores
+  these → missing defaults, not a crash);
+- uses string refs, `findDOMNode`, or legacy context;
+- **bundles its own React** instead of externalising it → two instances → crash (the one hard
+  failure);
+- imports a `lucide-react` icon renamed/removed in the 0.x → 1.x move.
+
+## Tailwind is *not* part of the contract
+
+Bundles ship their own compiled CSS, so the host's Tailwind version is irrelevant to them. A
+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.)
+
+## 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**.
+
+> **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.
+
+## Security floor
+
+An R5 app must ship with **`npm audit` reporting zero vulnerabilities**. Run it against the real
+registry — `npm audit --registry=https://registry.npmjs.org` — because the sandbox mirror doesn't
+implement the audit endpoint. Two high-severity advisories are already pinned out in the R5 set and
+must stay pinned:
+
+- **`react-router` 7.12.0–7.18.1** — RSC-mode CSRF bypass. Build against **7.18.4+** (the host
+  provides ≥7.18.4). Never ship a router below 7.18.4.
+- **`browserslist` ≤4.28.6** — unbounded memory growth / prototype write. It's a transitive build
+  dependency, so pin it with an `overrides` entry (`"overrides": { "browserslist": "^4.29" }`), not
+  a direct dependency.
+
+Both are compile-time/build-time concerns for the app's own toolchain; neither is a host global.
+
+## Reading the contract programmatically (one source of truth)
+
+Don't hard-code the externalized list — import it from the SDK, so hosts and apps
+never drift:
+
+```ts
+import {
+  SHARED_DEPENDENCY_CONTRACT_VERSION, // 'v5'
+  SHARED_DEPENDENCIES,                // [{ specifier, globalName, minVersion, importMapPath }, …] (25)
+  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'
+
+// Build config: externalize exactly the contract.
+export const external = [...SHARED_DEPENDENCY_SPECIFIERS]
+
+// Runtime: degrade gracefully on an older host that lacks the import map.
+const host = getHostSharedDependencies()
+if (host && host.version !== SHARED_DEPENDENCY_CONTRACT_VERSION) {
+  console.warn(`Built against ${SHARED_DEPENDENCY_CONTRACT_VERSION}, host serves ${host.version}`)
+}
+```
+
+The host publishes its live contract on `window.__SMARTLINKS_SHARED__` (`{ version, specifiers }`),
+which `getHostSharedDependencies()` reads. Import-map shim paths follow `importMapPathFor(specifier)`
+(`/sl-shared/<version>/<slug>.js`), so both the portal and the SDK generate identical paths.

package/dist/docs/iframe-responder.md

@@ -468,3 +468,311 @@ import type {
 ### Portal back exits the app too early
 - Set `state.parentPath` on route changes for screens that should navigate "up" inside the app.
 - Make sure the receiving app listens for `smartlinks-navigate` if the SDK version in use does not already handle it.
+
+---
+
+## Streaming in a hand-rolled parent (without IframeResponder)
+
+The following applies **only if you build your own parent proxy** instead of using the `IframeResponder` class above — which already handles AI streaming for you. It is the wire protocol for forwarding SSE/streaming responses to a child app in proxy mode.
+### Goal
+
+Keep the existing architecture:
+
+- local mode: child calls API directly
+- iframe proxy mode: child never owns auth state and streams through the parent
+
+This keeps user/session authority in the parent while making AI streaming behave like the rest of the SDK transport.
+
+### What changed
+
+Previously, proxy mode only supported one-shot request/response messages:
+
+- `_smartlinksProxyRequest`
+- `_smartlinksProxyResponse`
+
+Streaming now adds a second protocol for long-lived responses:
+
+- `_smartlinksProxyStreamRequest`
+- `_smartlinksProxyStream`
+- `_smartlinksProxyStreamAbort`
+
+### New parent message handling
+
+#### 1. Listen for stream requests
+
+The iframe child may now send this message:
+
+```ts
+{
+  _smartlinksProxyStreamRequest: true,
+  id: string,
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: any,
+  headers?: Record<string, string>
+}
+```
+
+Parent behavior:
+
+- treat this like a proxied API request
+- build the real API URL from your configured base URL plus `path`
+- send the request using the parent's current auth/session context
+- expect an SSE / streaming response body
+- keep the request open until the stream ends or is aborted
+
+#### 2. Forward stream lifecycle messages back to the child
+
+The parent should send messages back to the iframe using this envelope:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id: string,
+  phase: 'open' | 'event' | 'end' | 'error',
+  data?: any,
+  error?: string,
+  status?: number
+}
+```
+
+Phases:
+
+- `open`
+  - optional but recommended
+  - indicates the upstream streaming request was accepted and a body exists
+- `event`
+  - contains one parsed JSON event from an SSE `data:` frame
+  - send one message per logical event payload
+- `end`
+  - sent once when the stream finishes normally
+- `error`
+  - sent if the upstream request fails before or during streaming
+
+#### 3. Support abort from the child
+
+The child may stop reading early and send:
+
+```ts
+{
+  _smartlinksProxyStreamAbort: true,
+  id: string
+}
+```
+
+Parent behavior:
+
+- look up the active stream by `id`
+- abort the underlying fetch / reader
+- clean up any local state for that stream
+- do not keep streaming after abort
+
+### SSE forwarding rules
+
+The upstream AI endpoints return SSE-like frames. The parent should:
+
+- read the response body as a stream
+- buffer text until line boundaries
+- collect `data:` lines for a single event
+- join multi-line `data:` payloads with `\n`
+- ignore blank events
+- stop on `data: [DONE]`
+- JSON-parse each event payload
+- forward parsed payloads to the iframe as `_smartlinksProxyStream` with `phase: 'event'`
+
+Minimal parsing behavior:
+
+1. accumulate bytes into text
+2. split on `\r?\n`
+3. collect each `data:` line
+4. on blank line, finalize the event
+5. if payload is `[DONE]`, finish
+6. otherwise `JSON.parse(payload)` and forward
+
+### Auth and session expectations
+
+The parent remains the source of truth for auth.
+
+That means the parent stream handler should:
+
+- use the same auth headers/token source as normal proxied requests
+- not require the iframe to know the bearer token or API key
+- naturally pick up the current logged-in user when the stream starts
+- cancel active streams if your app invalidates session state on logout or account switch
+
+In practice, the stream request should use the same header-building logic as your normal parent proxy transport.
+
+### Error handling expectations
+
+If the upstream fetch returns a non-2xx status:
+
+- try to read the JSON error body
+- derive a useful message
+- send one `_smartlinksProxyStream` message with `phase: 'error'`
+- include `status` when available
+- do not send `end` afterward
+
+If the stream body is missing unexpectedly:
+
+- send `phase: 'error'`
+
+If JSON parsing fails for a single event chunk:
+
+- safest behavior is to ignore that malformed chunk and continue
+
+### State the parent should keep
+
+Track active streams in a map keyed by `id`:
+
+```ts
+Map<string, AbortController>
+```
+
+Recommended cleanup points:
+
+- on normal stream end
+- on error
+- on child abort
+- on iframe detach/unmount
+- on parent auth reset/logout if you want all in-flight streams cancelled immediately
+
+### Parent implementation outline
+
+```ts
+const activeStreams = new Map<string, AbortController>()
+
+window.addEventListener('message', async (event) => {
+  const msg = event.data
+
+  if (msg?._smartlinksProxyStreamAbort && msg.id) {
+    activeStreams.get(msg.id)?.abort()
+    activeStreams.delete(msg.id)
+    return
+  }
+
+  if (msg?._smartlinksProxyStreamRequest && msg.id) {
+    const controller = new AbortController()
+    activeStreams.set(msg.id, controller)
+
+    try {
+      const response = await fetch(buildUrl(msg.path), {
+        method: msg.method,
+        headers: msg.headers,
+        body: msg.body ? JSON.stringify(msg.body) : undefined,
+        signal: controller.signal,
+      })
+
+      if (!response.ok || !response.body) {
+        postError(...)
+        return
+      }
+
+      postOpen(...)
+      await forwardSse(response.body, parsed => postEvent(...parsed))
+      postEnd(...)
+    } catch (err) {
+      if (err?.name !== 'AbortError') postError(...)
+    } finally {
+      activeStreams.delete(msg.id)
+    }
+  }
+})
+```
+
+### Exact protocol summary
+
+#### Child → parent
+
+Standard stream request:
+
+```ts
+{
+  _smartlinksProxyStreamRequest: true,
+  id,
+  method,
+  path,
+  body,
+  headers
+}
+```
+
+Abort request:
+
+```ts
+{
+  _smartlinksProxyStreamAbort: true,
+  id
+}
+```
+
+#### Parent → child
+
+Open:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'open'
+}
+```
+
+Event:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'event',
+  data: parsedJsonEvent
+}
+```
+
+End:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'end'
+}
+```
+
+Error:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'error',
+  error: 'message',
+  status?: number
+}
+```
+
+### What does not change
+
+These parts of the parent iframe integration stay the same:
+
+- normal `_smartlinksProxyRequest` request/response flow
+- upload proxy flow
+- auth login/logout postMessage handling
+- route/deep-link handling
+- resize handling
+
+This is an additive protocol, not a replacement.
+
+### Current SDK reference
+
+The SDK implementation lives in:
+
+- [src/http.ts](src/http.ts)
+- [src/iframeResponder.ts](src/iframeResponder.ts)
+- [src/types/iframeResponder.ts](src/types/iframeResponder.ts)
+- [src/api/ai.ts](src/api/ai.ts)
+
+### Practical recommendation
+
+If your parent already uses `IframeResponder`, prefer upgrading to the SDK version with these changes instead of re-implementing the protocol manually.
+
+If your parent has a custom iframe bridge, implement exactly the three new message types above and reuse your existing auth/header logic from normal proxied requests.

package/dist/docs/item-context.md

@@ -1,7 +1,5 @@
 # Item Context (container prop)
 
-> **Copy this file into `node_modules/@proveanything/smartlinks/docs/item-context.md`** in the published SDK package.
-
 When the URL points at a specific item — either a **serial proof URL** or an
 **NFC tap** — the portal derives an `ItemContext` describing what it found
 and hands it to the container as the **`itemContext`** prop.