@proveanything/smartlinks 2.1.2 → 2.1.3

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.2  |  Generated: 2026-10-26T14:58:53.408Z
+Version: 2.1.3  |  Generated: 2026-10-26T21:00:54.277Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2585,9 +2585,11 @@ interface AppContainerComponent {
 **DeepLinkEntry** (interface)
 ```typescript
 interface DeepLinkEntry {
+  id?: string;
   title: string;
   path?: string;
   params?: Record<string, string>;
+  accepts?: PublicViewParams;
   widget?: true;
 }
 ```
@@ -7479,6 +7481,7 @@ interface IframeResponderOptions {
   version?: string;
   appUrl?: string;
   initialPath?: string;
+  params?: Record<string, string>;
   isAdmin?: boolean;
   cache?: CachedData;
   onAuthLogin?: (

package/dist/docs/app-manifest.md

@@ -326,11 +326,28 @@ Static deep-linkable states built into the app — fixed routes that exist regar
 
 See the [Deep Link Discovery guide](deep-link-discovery.md) for the full dual-source pattern (static manifest routes + dynamic `appConfig.linkable`).
 
+These are the app's **pages that a host opens**: portal menus and tabs, and websites that embed the app
+(websites.md → "Using another app's pages"). A host opens them with its own signed-in session, so one
+app can offer several pages that each know the visitor: book, upcoming bookings, past bookings, change a
+booking.
+
+```json
+"linkable": [
+  { "id": "book", "title": "Book an appointment", "path": "/",
+    "accepts": { "optional": ["service", "staff", "date"] } },
+  { "id": "upcoming", "title": "Your upcoming bookings", "path": "/my-bookings" },
+  { "id": "change", "title": "Change a booking", "path": "/booking",
+    "accepts": { "required": ["id"] } }
+]
+```
+
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `id` | string | ❌ | Stable id, unique within the app: hosts and sites refer to the page by it |
 | `title` | string | ✅ | Human-readable label shown in menus and offered to AI agents |
 | `path` | string | ❌ | Hash route within the app (defaults to `"/"` if omitted) |
-| `params` | object | ❌ | App-specific query params appended to the URL — do **not** include platform params (`collectionId`, `productId`, etc.) |
+| `params` | object | ❌ | Params this entry PINS, appended to the URL — do **not** include platform params (`collectionId`, `productId`, etc.) |
+| `accepts` | `{ required?: string[]; optional?: string[] }` | ❌ | The params a host may supply when it opens the page (e.g. which service to start on) |
 
 #### `publicViews`
 
@@ -371,7 +388,7 @@ An app can have any combination of three setup styles. Only public views are ext
 | Style | Declared by | Lives | Context |
 |-------|-------------|-------|---------|
 | **Portal components** — where the app renders inside portal (collection / product / batch / variant / proof) | module registry `components.*` (set at publish) | Inside portal | Physical twin (QR/NFC scan) |
-| **Portal deep links** — the entry points portal menus/tabs/side-menus link to (e.g. list view vs calendar view) | `linkable` / `DeepLinkEntry` | Inside portal | Portal (menu picks the entry) |
+| **App pages** — the entry points portal menus/tabs link to and websites embed (e.g. list vs calendar; book vs my bookings) | `linkable` / `DeepLinkEntry` | Inside a host: portal or a website | The host: its signed-in session, plus the page's `accepts` params |
 | **Public views** — standalone external screens | `publicViews` (this block) | Outside portal | URL params only |
 
 #### `records`

package/dist/docs/deep-link-discovery.md

@@ -172,6 +172,9 @@ Both sources use the same entry shape:
 
 ```typescript
 interface DeepLinkEntry {
+  /** Stable id, unique within the app (optional): hosts and websites refer to the page by it */
+  id?: string;
+
   /** Human-readable label for this state (required) */
   title: string;
 
@@ -193,6 +196,13 @@ interface DeepLinkEntry {
    */
   params?: Record<string, string>;
 
+  /**
+   * The params a host may supply when it opens this page (optional), e.g. a booking page that can
+   * start on one service: `{ optional: ['service', 'staff', 'date'] }`. `params` are pinned by the
+   * entry; `accepts` are filled in by whoever opens it.
+   */
+  accepts?: { required?: string[]; optional?: string[] };
+
   /**
    * When `true`, this entry is also available as a dynamic data context for widgets.
    *
@@ -211,7 +221,9 @@ interface DeepLinkEntry {
 |-------|----------|-------|
 | `title` | ✅ | Displayed in menus and offered to AI agents. Should be concise and human-readable. |
 | `path` | ❌ | Hash route within the app. Defaults to `/` if omitted. |
+| `id` | ❌ | Stable id for hosts and websites to refer to the page by. |
 | `params` | ❌ | App-specific query params only. Platform params are injected automatically. |
+| `accepts` | ❌ | The params whoever opens the page may supply (`required` / `optional`). |
 | `widget` | ❌ | Set to `true` to make this entry selectable in the widget config picker as a dynamic data context. |
 
 > **Tip:** Different entries can share the same `path` if they differ by `params` — for example, two entries pointing at `/settings` with different `tab` params.

package/dist/docs/iframe-responder.md

@@ -103,6 +103,7 @@ interface IframeResponderOptions {
   version?: 'stable' | 'development'; // App version (default: 'stable')
   appUrl?: string;              // Override URL (for local dev)
   initialPath?: string;         // Initial hash path (e.g., '/settings')
+  params?: Record<string, string>; // The page's own params (e.g. { service: 'svc_123' }); context params win
   
   // Data
   cache?: CachedData;           // Pre-cached data

package/dist/docs/websites.md

@@ -66,6 +66,32 @@ bytes. `_server/` is never served to visitors.
   doing work that belongs in a server function or a scheduled job.
 - **No secrets** in the server bundle and no Node built-ins beyond `nodejs_compat`.
 
+## Using another app's pages
+
+Some apps do a job a site shouldn't rebuild: a booking journey holds the time rules, the clash
+handling and the confirmation; "my bookings" holds who may change what. Those apps declare their pages
+in `linkable` (app-manifest.md), each with a stable `id`, a `path` and the params it `accepts`. A site
+embeds one with **`IframeResponder`** (iframe-responder.md), from the browser:
+
+```typescript
+const site = SL.site.current()
+const responder = new SL.IframeResponder({
+  collectionId: site.collectionId,
+  appId: 'appointments',            // the app's id on this collection
+  initialPath: '/my-bookings',      // the page's `path`
+  params: { service: 'svc_123' },   // what the page `accepts`
+  onResize: (h) => { iframe.style.height = `${h}px` },
+})
+iframe.src = await responder.attach(iframe)
+```
+
+- **The visitor's session goes with it.** The page's API calls are proxied through the site, so it
+  acts as whoever is signed in to the site (or as a guest). Never pass a token in the URL.
+- **The app must be installed** on the site's collection; its address comes from there.
+- **Show the app's content natively where you can** (its `headless` data: services, staff, events)
+  for your own design and SEO, and embed the page only for the part that does the work.
+- Pages render on the client, after load: they aren't part of the server-rendered HTML.
+
 ## Caching
 
 The router keeps a rendered page at the edge when your response says it may:

package/dist/iframeResponder.d.ts

@@ -100,4 +100,6 @@ export declare function buildIframeSrc(options: {
         secondary?: string;
     };
     initialPath?: string;
+    /** The page's own params; the context params above always win. */
+    params?: Record<string, string>;
 }): string;

package/dist/iframeResponder.js

@@ -155,11 +155,16 @@ export class IframeResponder {
     // URL Building
     // ===========================================================================
     buildIframeSrc() {
-        var _a, _b;
+        var _a, _b, _c;
         if (!this.appUrl) {
             throw new Error('App URL not resolved');
         }
         const params = new URLSearchParams();
+        // The page's own params first: the platform's context below always wins.
+        for (const [key, value] of Object.entries((_a = this.options.params) !== null && _a !== void 0 ? _a : {})) {
+            if (value != null && value !== '')
+                params.set(key, String(value));
+        }
         // Required context
         params.set('collectionId', this.options.collectionId);
         params.set('appId', this.options.appId);
@@ -171,13 +176,13 @@ export class IframeResponder {
         if (this.options.isAdmin)
             params.set('isAdmin', 'true');
         // Dark mode from collection
-        const isDark = (_b = (_a = this.cache.collection) === null || _a === void 0 ? void 0 : _a.dark) !== null && _b !== void 0 ? _b : false;
+        const isDark = (_c = (_b = this.cache.collection) === null || _b === void 0 ? void 0 : _b.dark) !== null && _c !== void 0 ? _c : false;
         params.set('dark', isDark ? '1' : '0');
         // Parent URL for redirects
         try {
             params.set('parentUrl', window.location.href);
         }
-        catch (_c) {
+        catch (_d) {
             // Ignore if can't access location
         }
         // Encode theme from collection
@@ -192,7 +197,7 @@ export class IframeResponder {
                     params.set('theme', btoa(JSON.stringify(themeData)));
                 }
             }
-            catch (_d) {
+            catch (_e) {
                 // Ignore encoding errors
             }
         }
@@ -210,7 +215,8 @@ export class IframeResponder {
                 const path = this.options.initialPath.startsWith('/') ? this.options.initialPath : '/' + this.options.initialPath;
                 // Insert path before the ?
                 const [beforeHash, afterHash] = baseWithHash.split('#');
-                finalUrl = `${beforeHash}#${afterHash || ''}${path}?${existingParams.toString()}`;
+                // App addresses end in "#/": join without doubling the slash ("#//my-bookings" matches no route).
+                finalUrl = `${beforeHash}#${(afterHash || '').replace(/\/+$/, '')}${path}?${existingParams.toString()}`;
             }
             else {
                 finalUrl = `${baseWithHash}?${existingParams.toString()}`;
@@ -765,8 +771,12 @@ export function isAdminFromRoles(user, collection, proof) {
  * Standalone helper for cases where you don't need the full IframeResponder.
  */
 export function buildIframeSrc(options) {
-    var _a, _b;
+    var _a, _b, _c;
     const params = new URLSearchParams();
+    for (const [key, value] of Object.entries((_a = options.params) !== null && _a !== void 0 ? _a : {})) {
+        if (value != null && value !== '')
+            params.set(key, String(value));
+    }
     params.set('collectionId', options.collectionId);
     params.set('appId', options.appId);
     if (options.productId)
@@ -776,14 +786,14 @@ export function buildIframeSrc(options) {
     if (options.isAdmin)
         params.set('isAdmin', 'true');
     params.set('dark', options.dark ? '1' : '0');
-    if (((_a = options.theme) === null || _a === void 0 ? void 0 : _a.primary) || ((_b = options.theme) === null || _b === void 0 ? void 0 : _b.secondary)) {
+    if (((_b = options.theme) === null || _b === void 0 ? void 0 : _b.primary) || ((_c = options.theme) === null || _c === void 0 ? void 0 : _c.secondary)) {
         const themeData = { p: options.theme.primary, s: options.theme.secondary };
         params.set('theme', btoa(JSON.stringify(themeData)));
     }
     try {
         params.set('parentUrl', window.location.href);
     }
-    catch (_c) {
+    catch (_d) {
         // Ignore
     }
     let base = options.appUrl.replace(/#\/?$/, '').replace(/\/$/, '');

package/dist/openapi.yaml

@@ -19909,6 +19909,8 @@ components:
     DeepLinkEntry:
       type: object
       properties:
+        id:
+          type: string
         title:
           type: string
         path:
@@ -19917,6 +19919,8 @@ components:
           type: object
           additionalProperties:
             type: string
+        accepts:
+          $ref: "#/components/schemas/PublicViewParams"
         widget:
           type: object
           additionalProperties: true
@@ -27652,6 +27656,10 @@ components:
           type: string
         initialPath:
           type: string
+        params:
+          type: object
+          additionalProperties:
+            type: string
         isAdmin:
           type: boolean
         cache:

package/dist/types/appManifest.d.ts

@@ -109,6 +109,12 @@ export interface AppContainerComponent {
  *   { "title": "About Us", "params": { "pageId": "about-us" } }
  */
 export interface DeepLinkEntry {
+    /**
+     * Stable id for this page, unique within the app (optional). Hosts and websites refer to the page
+     * by it (e.g. a site embeds `{ app: 'appointments', page: 'book' }`), so a renamed `title` or a moved
+     * `path` doesn't break them.
+     */
+    id?: string;
     /** Human-readable label shown in menus and offered to AI agents */
     title: string;
     /**
@@ -123,6 +129,12 @@ export interface DeepLinkEntry {
      * those are injected by the platform automatically.
      */
     params?: Record<string, string>;
+    /**
+     * The params a host may supply when it opens this page (in addition to the platform's own), e.g. a
+     * booking page that can start on one service: `{ optional: ['service', 'staff', 'date'] }`. `params`
+     * above are the values this entry PINS; `accepts` are the ones the caller fills in.
+     */
+    accepts?: PublicViewParams;
     /**
      * When `true`, this entry is also available as a dynamic data context for widgets
      * (in addition to being a navigable page / container route).
@@ -856,10 +868,10 @@ export interface AppManifest {
         components: AppContainerComponent[];
     };
     /**
-     * PORTAL deep-linkable states built into this app — the entry points the portal's menu system
-     * (bottom menu, side menus, tabs) can link to. Use these when one app has several ways to enter/load
-     * its portal component (e.g. a list view and a calendar view, or a viewer and an editor) that
-     * different parts of portal should link to independently. These live INSIDE portal.
+     * The app's PAGES that a host opens — portal menus (bottom menu, side menus, tabs) and WEBSITES that
+     * embed the app (IframeResponder). Use these when one app has several ways in (a list view and a
+     * calendar view; book, upcoming bookings, change a booking). A host opens them with its own signed-in
+     * session: the page's API calls go through the host, so it acts as the person signed in there.
      * Fixed routes are declared here at build time; dynamic content entries (e.g. CMS pages) are stored
      * separately in `appConfig.linkable` — merge both for the full navigable set.
      * @see DeepLinkEntry

package/dist/types/iframeResponder.d.ts

@@ -24,6 +24,12 @@ export interface IframeResponderOptions {
     appUrl?: string;
     /** Initial hash path (e.g., '/settings') */
     initialPath?: string;
+    /**
+     * The page's own params (a `linkable` entry's pinned `params` plus what it `accepts`), e.g.
+     * `{ service: 'svc_123' }`. Added to the app's URL alongside the platform's context params, which
+     * always win (collectionId, appId, productId, proofId, isAdmin, dark, theme, parentUrl).
+     */
+    params?: Record<string, string>;
     /** Is user an admin of this collection */
     isAdmin?: boolean;
     cache?: CachedData;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.2  |  Generated: 2026-10-26T14:58:53.408Z
+Version: 2.1.3  |  Generated: 2026-10-26T21:00:54.277Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2585,9 +2585,11 @@ interface AppContainerComponent {
 **DeepLinkEntry** (interface)
 ```typescript
 interface DeepLinkEntry {
+  id?: string;
   title: string;
   path?: string;
   params?: Record<string, string>;
+  accepts?: PublicViewParams;
   widget?: true;
 }
 ```
@@ -7479,6 +7481,7 @@ interface IframeResponderOptions {
   version?: string;
   appUrl?: string;
   initialPath?: string;
+  params?: Record<string, string>;
   isAdmin?: boolean;
   cache?: CachedData;
   onAuthLogin?: (

package/docs/app-manifest.md

@@ -326,11 +326,28 @@ Static deep-linkable states built into the app — fixed routes that exist regar
 
 See the [Deep Link Discovery guide](deep-link-discovery.md) for the full dual-source pattern (static manifest routes + dynamic `appConfig.linkable`).
 
+These are the app's **pages that a host opens**: portal menus and tabs, and websites that embed the app
+(websites.md → "Using another app's pages"). A host opens them with its own signed-in session, so one
+app can offer several pages that each know the visitor: book, upcoming bookings, past bookings, change a
+booking.
+
+```json
+"linkable": [
+  { "id": "book", "title": "Book an appointment", "path": "/",
+    "accepts": { "optional": ["service", "staff", "date"] } },
+  { "id": "upcoming", "title": "Your upcoming bookings", "path": "/my-bookings" },
+  { "id": "change", "title": "Change a booking", "path": "/booking",
+    "accepts": { "required": ["id"] } }
+]
+```
+
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `id` | string | ❌ | Stable id, unique within the app: hosts and sites refer to the page by it |
 | `title` | string | ✅ | Human-readable label shown in menus and offered to AI agents |
 | `path` | string | ❌ | Hash route within the app (defaults to `"/"` if omitted) |
-| `params` | object | ❌ | App-specific query params appended to the URL — do **not** include platform params (`collectionId`, `productId`, etc.) |
+| `params` | object | ❌ | Params this entry PINS, appended to the URL — do **not** include platform params (`collectionId`, `productId`, etc.) |
+| `accepts` | `{ required?: string[]; optional?: string[] }` | ❌ | The params a host may supply when it opens the page (e.g. which service to start on) |
 
 #### `publicViews`
 
@@ -371,7 +388,7 @@ An app can have any combination of three setup styles. Only public views are ext
 | Style | Declared by | Lives | Context |
 |-------|-------------|-------|---------|
 | **Portal components** — where the app renders inside portal (collection / product / batch / variant / proof) | module registry `components.*` (set at publish) | Inside portal | Physical twin (QR/NFC scan) |
-| **Portal deep links** — the entry points portal menus/tabs/side-menus link to (e.g. list view vs calendar view) | `linkable` / `DeepLinkEntry` | Inside portal | Portal (menu picks the entry) |
+| **App pages** — the entry points portal menus/tabs link to and websites embed (e.g. list vs calendar; book vs my bookings) | `linkable` / `DeepLinkEntry` | Inside a host: portal or a website | The host: its signed-in session, plus the page's `accepts` params |
 | **Public views** — standalone external screens | `publicViews` (this block) | Outside portal | URL params only |
 
 #### `records`

package/docs/deep-link-discovery.md

@@ -172,6 +172,9 @@ Both sources use the same entry shape:
 
 ```typescript
 interface DeepLinkEntry {
+  /** Stable id, unique within the app (optional): hosts and websites refer to the page by it */
+  id?: string;
+
   /** Human-readable label for this state (required) */
   title: string;
 
@@ -193,6 +196,13 @@ interface DeepLinkEntry {
    */
   params?: Record<string, string>;
 
+  /**
+   * The params a host may supply when it opens this page (optional), e.g. a booking page that can
+   * start on one service: `{ optional: ['service', 'staff', 'date'] }`. `params` are pinned by the
+   * entry; `accepts` are filled in by whoever opens it.
+   */
+  accepts?: { required?: string[]; optional?: string[] };
+
   /**
    * When `true`, this entry is also available as a dynamic data context for widgets.
    *
@@ -211,7 +221,9 @@ interface DeepLinkEntry {
 |-------|----------|-------|
 | `title` | ✅ | Displayed in menus and offered to AI agents. Should be concise and human-readable. |
 | `path` | ❌ | Hash route within the app. Defaults to `/` if omitted. |
+| `id` | ❌ | Stable id for hosts and websites to refer to the page by. |
 | `params` | ❌ | App-specific query params only. Platform params are injected automatically. |
+| `accepts` | ❌ | The params whoever opens the page may supply (`required` / `optional`). |
 | `widget` | ❌ | Set to `true` to make this entry selectable in the widget config picker as a dynamic data context. |
 
 > **Tip:** Different entries can share the same `path` if they differ by `params` — for example, two entries pointing at `/settings` with different `tab` params.

package/docs/iframe-responder.md

@@ -103,6 +103,7 @@ interface IframeResponderOptions {
   version?: 'stable' | 'development'; // App version (default: 'stable')
   appUrl?: string;              // Override URL (for local dev)
   initialPath?: string;         // Initial hash path (e.g., '/settings')
+  params?: Record<string, string>; // The page's own params (e.g. { service: 'svc_123' }); context params win
   
   // Data
   cache?: CachedData;           // Pre-cached data

package/docs/websites.md

@@ -66,6 +66,32 @@ bytes. `_server/` is never served to visitors.
   doing work that belongs in a server function or a scheduled job.
 - **No secrets** in the server bundle and no Node built-ins beyond `nodejs_compat`.
 
+## Using another app's pages
+
+Some apps do a job a site shouldn't rebuild: a booking journey holds the time rules, the clash
+handling and the confirmation; "my bookings" holds who may change what. Those apps declare their pages
+in `linkable` (app-manifest.md), each with a stable `id`, a `path` and the params it `accepts`. A site
+embeds one with **`IframeResponder`** (iframe-responder.md), from the browser:
+
+```typescript
+const site = SL.site.current()
+const responder = new SL.IframeResponder({
+  collectionId: site.collectionId,
+  appId: 'appointments',            // the app's id on this collection
+  initialPath: '/my-bookings',      // the page's `path`
+  params: { service: 'svc_123' },   // what the page `accepts`
+  onResize: (h) => { iframe.style.height = `${h}px` },
+})
+iframe.src = await responder.attach(iframe)
+```
+
+- **The visitor's session goes with it.** The page's API calls are proxied through the site, so it
+  acts as whoever is signed in to the site (or as a guest). Never pass a token in the URL.
+- **The app must be installed** on the site's collection; its address comes from there.
+- **Show the app's content natively where you can** (its `headless` data: services, staff, events)
+  for your own design and SEO, and embed the page only for the part that does the work.
+- Pages render on the client, after load: they aren't part of the server-rendered HTML.
+
 ## Caching
 
 The router keeps a rendered page at the edge when your response says it may:

package/openapi.yaml

@@ -19909,6 +19909,8 @@ components:
     DeepLinkEntry:
       type: object
       properties:
+        id:
+          type: string
         title:
           type: string
         path:
@@ -19917,6 +19919,8 @@ components:
           type: object
           additionalProperties:
             type: string
+        accepts:
+          $ref: "#/components/schemas/PublicViewParams"
         widget:
           type: object
           additionalProperties: true
@@ -27652,6 +27656,10 @@ components:
           type: string
         initialPath:
           type: string
+        params:
+          type: object
+          additionalProperties:
+            type: string
         isAdmin:
           type: boolean
         cache:

package/package.json

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