@proveanything/smartlinks 1.8.3 → 1.8.5

package/dist/api/appConfiguration.d.ts

@@ -1,4 +1,5 @@
 import { CollectionWidgetsResponse, GetCollectionWidgetsOptions } from "../types/appManifest";
+import type { GetWidgetInstanceOptions, WidgetInstance, WidgetInstanceSummary } from "../types/appConfiguration";
 /**
  * Options for collection/product-scoped app configuration.
  * This data is set by admins and applies to all users within the scope.
@@ -193,6 +194,39 @@ export declare namespace appConfiguration {
      * ```
      */
     function getConfig(opts: AppConfigOptions): Promise<any>;
+    /**
+     * Resolve a configured widget instance by ID from an app's stored config.
+     * This is a thin convenience wrapper over `getConfig()` that reads `config.widgets[widgetId]`.
+     *
+     * @param opts - Scope options plus the widget instance ID
+     * @returns The configured widget instance
+     *
+     * @example
+     * ```typescript
+     * const widget = await appConfiguration.getWidgetInstance({
+     *   collectionId: 'my-collection',
+     *   appId: 'widget-toolkit',
+     *   widgetId: 'launch-countdown'
+     * })
+     * ```
+     */
+    function getWidgetInstance<TWidget = any>(opts: GetWidgetInstanceOptions): Promise<WidgetInstance<TWidget>>;
+    /**
+     * List configured widget instances for an app.
+     * Useful for picker UIs, setup schemas, and widget-to-widget references.
+     *
+     * @param opts - App config scope options
+     * @returns Array of widget instance summaries
+     *
+     * @example
+     * ```typescript
+     * const widgets = await appConfiguration.listWidgetInstances({
+     *   collectionId: 'my-collection',
+     *   appId: 'widget-toolkit'
+     * })
+     * ```
+     */
+    function listWidgetInstances(opts: Omit<GetWidgetInstanceOptions, 'widgetId'>): Promise<WidgetInstanceSummary[]>;
     /**
      * Set app configuration for a collection/product scope.
      * Requires admin authentication.

package/dist/api/appConfiguration.js

@@ -1,5 +1,24 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 // src/api/appConfiguration.ts
 import { request, post, del } from "../http";
+function getWidgetsMap(config) {
+    if (!config || typeof config !== 'object' || Array.isArray(config))
+        return {};
+    const widgets = config.widgets;
+    if (!widgets || typeof widgets !== 'object' || Array.isArray(widgets))
+        return {};
+    return widgets;
+}
 function buildAppPath(opts, type) {
     const base = opts.admin ? "admin" : "public";
     let path = `/${base}`;
@@ -228,6 +247,67 @@ export var appConfiguration;
         return request(path);
     }
     appConfiguration.getConfig = getConfig;
+    /**
+     * Resolve a configured widget instance by ID from an app's stored config.
+     * This is a thin convenience wrapper over `getConfig()` that reads `config.widgets[widgetId]`.
+     *
+     * @param opts - Scope options plus the widget instance ID
+     * @returns The configured widget instance
+     *
+     * @example
+     * ```typescript
+     * const widget = await appConfiguration.getWidgetInstance({
+     *   collectionId: 'my-collection',
+     *   appId: 'widget-toolkit',
+     *   widgetId: 'launch-countdown'
+     * })
+     * ```
+     */
+    async function getWidgetInstance(opts) {
+        const { widgetId } = opts, configOpts = __rest(opts, ["widgetId"]);
+        const config = await getConfig(configOpts);
+        const widgets = getWidgetsMap(config);
+        const instance = widgets[widgetId];
+        if (!instance || typeof instance !== 'object' || Array.isArray(instance)) {
+            throw new Error(`Widget instance \"${widgetId}\" not found for app \"${opts.appId}\"`);
+        }
+        return instance;
+    }
+    appConfiguration.getWidgetInstance = getWidgetInstance;
+    /**
+     * List configured widget instances for an app.
+     * Useful for picker UIs, setup schemas, and widget-to-widget references.
+     *
+     * @param opts - App config scope options
+     * @returns Array of widget instance summaries
+     *
+     * @example
+     * ```typescript
+     * const widgets = await appConfiguration.listWidgetInstances({
+     *   collectionId: 'my-collection',
+     *   appId: 'widget-toolkit'
+     * })
+     * ```
+     */
+    async function listWidgetInstances(opts) {
+        const config = await getConfig(opts);
+        const widgets = getWidgetsMap(config);
+        return Object.entries(widgets).map(([id, instance]) => {
+            var _a;
+            const widgetInstance = instance && typeof instance === 'object' && !Array.isArray(instance)
+                ? instance
+                : {};
+            const resolvedId = typeof widgetInstance.id === 'string' && widgetInstance.id.trim()
+                ? widgetInstance.id
+                : id;
+            return Object.assign(Object.assign({}, widgetInstance), { id: resolvedId, name: typeof widgetInstance.name === 'string' && widgetInstance.name.trim()
+                    ? widgetInstance.name
+                    : resolvedId, type: typeof ((_a = widgetInstance.widget) === null || _a === void 0 ? void 0 : _a.type) === 'string'
+                    ? widgetInstance.widget.type
+                    : undefined });
+        });
+    }
+    appConfiguration.listWidgetInstances = listWidgetInstances;
     /**
      * Set app configuration for a collection/product scope.
      * Requires admin authentication.

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.8.3  |  Generated: 2026-03-14T10:31:32.637Z
+Version: 1.8.5  |  Generated: 2026-03-14T14:43:55.897Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1283,6 +1283,39 @@ interface AppConfigurationResponse {
 }
 ```
 
+**GetWidgetInstanceOptions** (interface)
+```typescript
+interface GetWidgetInstanceOptions {
+  appId: string
+  collectionId?: string
+  productId?: string
+  variantId?: string
+  batchId?: string
+  admin?: boolean
+  widgetId: string
+}
+```
+
+**WidgetInstance<TWidget = any>** (interface)
+```typescript
+interface WidgetInstance<TWidget = any> {
+  id: string
+  name?: string
+  widget?: TWidget
+  [key: string]: any
+}
+```
+
+**WidgetInstanceSummary** (interface)
+```typescript
+interface WidgetInstanceSummary {
+  id: string
+  name: string
+  type?: string
+  [key: string]: any
+}
+```
+
 ### appManifest
 
 **AppBundle** (interface)
@@ -1324,6 +1357,16 @@ interface AppWidgetComponent {
 }
 ```
 
+**AppManifestWidgets** (interface)
+```typescript
+interface AppManifestWidgets {
+  files: AppManifestFiles;
+  components: AppWidgetComponent[];
+  instanceResolution?: boolean;
+  instanceParam?: string;
+}
+```
+
 **AppContainerComponent** (interface)
 ```typescript
 interface AppContainerComponent {
@@ -1525,10 +1568,7 @@ interface AppManifest {
   * (setup questions, import schema, tunable fields, metrics definitions).
   * Absent when the app has no admin UI.
   admin?: string;
-  widgets?: {
-  files: AppManifestFiles;
-  components: AppWidgetComponent[];
-  };
+  widgets?: AppManifestWidgets;
   containers?: {
   files: AppManifestFiles;
   components: AppContainerComponent[];
@@ -6016,6 +6056,9 @@ Get related threads and records for a case (admin only) GET /cases/:caseId/relat
 **getConfig**(opts: AppConfigOptions) → `Promise<any>`
 Get app configuration for a collection/product scope. ```typescript const config = await appConfiguration.getConfig({ appId: 'warranty-portal', collectionId: 'my-collection' }); ```
 
+**listWidgetInstances**(opts: Omit<GetWidgetInstanceOptions, 'widgetId'>) → `Promise<WidgetInstanceSummary[]>`
+List configured widget instances for an app. Useful for picker UIs, setup schemas, and widget-to-widget references. ```typescript const widgets = await appConfiguration.listWidgetInstances({ collectionId: 'my-collection', appId: 'widget-toolkit' }) ```
+
 **setConfig**(opts: AppConfigOptions) → `Promise<any>`
 Set app configuration for a collection/product scope. Requires admin authentication. ```typescript await appConfiguration.setConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true, config: { warrantyPeriod: 24, supportEmail: 'support@example.com' } }); ```
 

package/dist/docs/app-manifest.md

@@ -46,6 +46,8 @@ The manifest is loaded automatically by the platform for every collection page.
   "admin": "app.admin.json",
 
   "widgets": {
+    "instanceResolution": true,
+    "instanceParam": "widgetId",
     "files": {
       "js": {
         "umd": "dist/widgets.umd.js",
@@ -127,8 +129,36 @@ Declares the widget bundle. Omit if the app has no widget component.
 | `files.js.umd` | UMD bundle path — used for dynamic `<script>` loading |
 | `files.js.esm` | ESM bundle path — used for `import()` / native ES modules (optional but recommended) |
 | `files.css` | CSS bundle path — omit if the widget ships no styles |
+| `instanceResolution` | Optional boolean. When `true`, this app supports resolving configured widget instances by ID from app config |
+| `instanceParam` | Optional string. Query/hash param used for instance lookup. Defaults to `"widgetId"` |
 | `components[]` | One entry per exported widget component (see below) |
 
+**Widget instance resolution**
+
+Apps such as widget toolkits often store reusable widget instances in collection-scoped app config, for example under `config.widgets.launch-countdown`. When your widget bundle can self-configure from one of those stored instances, declare that capability in the manifest:
+
+```json
+"widgets": {
+  "instanceResolution": true,
+  "instanceParam": "widgetId",
+  "files": {
+    "js": {
+      "umd": "dist/widgets.umd.js",
+      "esm": "dist/widgets.es.js"
+    },
+    "css": null
+  },
+  "components": [
+    {
+      "name": "WidgetToolkitResolver",
+      "description": "Resolves and renders a configured widget instance by ID."
+    }
+  ]
+}
+```
+
+This tells the platform and other apps that they can deep-link into a stored widget instance using a URL or embed context such as `?appId=widget-toolkit&widgetId=launch-countdown`.
+
 **Component fields:**
 
 | Field | Type | Description |
@@ -281,6 +311,8 @@ Fetched only by the admin UI and AI-assisted setup flows — never loaded on the
 }
 ```
 
+> `dynamic-select` widget pickers are a reasonable future extension for admin schemas, but they are not a built-in question type in the SDK today. For now, treat widget-instance selection as an app-level UI convention powered by `appConfiguration.listWidgetInstances()`.
+
 ### Field Reference
 
 #### `aiGuide`

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

@@ -35,6 +35,8 @@ Deep-linkable states come from **two sources** depending on their nature:
 | **App manifest** (`app.manifest.json`) | Fixed routes built into the app | Only when the app itself is updated |
 | **App config** (`appConfig.linkable`) | Content-driven entries that vary by collection | When admins create, remove, or rename content |
 
+Widget-oriented apps can also use the same deep-link model with `widgetId` rather than `pageId`: the app config stores reusable widget instances, and the URL or embed context selects a specific instance to render.
+
 Consumers merge both sources to get the full set of navigable states for an app.
 
 ```text
@@ -232,6 +234,7 @@ The parent platform constructs the final navigation URL from an entry by combini
 | Entry | Resolved URL |
 |-------|--------------|
 | `{ title: "About Us", params: { pageId: "about-us" } }` | `https://app.example.com/#/?collectionId=abc&appId=my-app&pageId=about-us` |
+| `{ title: "Launch Countdown", params: { widgetId: "launch-countdown" } }` | `https://app.example.com/#/?collectionId=abc&appId=widget-toolkit&widgetId=launch-countdown` |
 | `{ title: "Advanced Settings", path: "/settings", params: { tab: "advanced" } }` | `https://app.example.com/admin.html#/settings?collectionId=abc&appId=my-app&tab=advanced` |
 | `{ title: "Gallery", path: "/gallery" }` | `https://app.example.com/#/gallery?collectionId=abc&appId=my-app` |
 | `{ title: "Home" }` | `https://app.example.com/#/?collectionId=abc&appId=my-app` |
@@ -259,6 +262,31 @@ This section only applies to **dynamic links stored in `appConfig.linkable`**. S
 
 Apps **MUST** update `appConfig.linkable` whenever the set of dynamic navigable states changes:
 
+For widget toolkits, that usually means syncing entries from your stored widget instance map:
+
+```typescript
+const widgets = await SL.appConfiguration.listWidgetInstances({
+  collectionId,
+  appId: 'widget-toolkit',
+  admin: true,
+})
+
+const linkable = widgets.map(widget => ({
+  title: widget.name,
+  params: { widgetId: widget.id },
+}))
+
+const current = await SL.appConfiguration.getConfig({ collectionId, appId: 'widget-toolkit', admin: true }) ?? {}
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId: 'widget-toolkit',
+  admin: true,
+  config: { ...current, linkable },
+})
+```
+
+This gives the portal and AI orchestrators the same discoverability for widget instances that page-driven apps already get for `pageId` content.
+
 - A page is created, deleted, published, or unpublished
 - A page's `deepLinkable` flag is toggled
 - A page title changes

package/dist/docs/manifests.md

@@ -19,7 +19,7 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
 |---------|---------|-------------|
 | `meta` | App identity, version, appId, SEO priority | All workflows |
 | `admin` | Pointer to `app.admin.json` | Admin orchestrators |
-| `widgets` | Bundle files + component definitions + settings schemas | Widget Builder |
+| `widgets` | Bundle files + component definitions + settings schemas; can also declare widget-instance resolution via `widgetId` | Widget Builder |
 | `containers` | Bundle files + component definitions | Container Loader |
 | `executor` | Bundle files, factory name, exports list | Server / AI |
 | `linkable` | Static deep-link routes | Portal menus / AI nav |
@@ -29,6 +29,8 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
   "meta": { "name": "My App", "appId": "my-app", "version": "1.0.0" },
   "admin": "app.admin.json",
   "widgets": {
+    "instanceResolution": true,
+    "instanceParam": "widgetId",
     "files": {
       "js": { "umd": "dist/widgets.umd.js", "esm": "dist/widgets.es.js" },
       "css": null
@@ -62,6 +64,8 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
 }
 ```
 
+When `instanceResolution` is enabled, the app is declaring that consumers can pass a widget instance identifier such as `?appId=widget-toolkit&widgetId=launch-countdown`, and the widget bundle will resolve its stored configuration from app config.
+
 > ⚠️ **`css` is `null` by default.** Most widgets and containers use Tailwind/shadcn classes inherited from the parent and produce **no CSS output file**. Set `"css": null` in the manifest. Only set it to a filename if your widget/container ships a custom CSS file that actually exists in `dist/`. The parent portal checks this value before injecting a `<link>` tag — a non-null value pointing to a missing file will cause a 404.
 
 ---

package/dist/docs/widgets.md

@@ -202,6 +202,141 @@ Widgets support two navigation patterns:
 
 ## Building a Widget
 
+---
+
+## Widget Instance Resolution
+
+Some apps expose a **widget resolver** instead of a single hard-coded widget. The resolver receives a `widgetId`, looks up a stored instance in app config, and renders the correct widget with its saved settings.
+
+This pattern is useful for widget toolkits, promo blocks, countdown libraries, CTA collections, and any app where admins create multiple reusable widget instances.
+
+### URL and embed convention
+
+Use `widgetId` the same way page-oriented apps use `pageId`:
+
+```text
+?appId=widget-toolkit&widgetId=launch-countdown
+```
+
+This works naturally in:
+
+- direct container or iframe links
+- widget-to-widget references
+- content slots that need to embed a preconfigured widget instance
+- platform deep-link routing when the manifest declares widget instance resolution
+
+### Manifest declaration
+
+Declare support in `app.manifest.json`:
+
+```json
+{
+  "widgets": {
+    "instanceResolution": true,
+    "instanceParam": "widgetId",
+    "files": {
+      "js": {
+        "umd": "dist/widgets.umd.js",
+        "esm": "dist/widgets.es.js"
+      },
+      "css": null
+    },
+    "components": [
+      {
+        "name": "WidgetToolkitResolver",
+        "description": "Resolves and renders widget instances by ID."
+      }
+    ]
+  }
+}
+```
+
+### SDK helpers
+
+The SDK now includes two thin helpers on `SL.appConfiguration`:
+
+```typescript
+const widget = await SL.appConfiguration.getWidgetInstance({
+  collectionId,
+  appId: 'widget-toolkit',
+  widgetId: 'launch-countdown',
+})
+
+const widgets = await SL.appConfiguration.listWidgetInstances({
+  collectionId,
+  appId: 'widget-toolkit',
+})
+```
+
+`getWidgetInstance()` is intentionally just a wrapper over `getConfig()` that reads `config.widgets[widgetId]`. That keeps the integration simple today while giving the platform freedom to optimize the lookup later.
+
+### Stored config shape
+
+The recommended storage shape is:
+
+```json
+{
+  "widgets": {
+    "launch-countdown": {
+      "id": "launch-countdown",
+      "name": "Launch Countdown",
+      "widget": {
+        "type": "countdown",
+        "targetDate": "2026-06-01T00:00:00Z",
+        "label": "Launching in..."
+      }
+    }
+  }
+}
+```
+
+### Resolver pattern
+
+```typescript
+const WidgetToolkitResolver: React.FC<SmartLinksWidgetProps & { widgetId?: string }> = ({
+  collectionId,
+  appId,
+  widgetId,
+  SL,
+  ...props
+}) => {
+  const [instance, setInstance] = React.useState<any | null>(null)
+
+  React.useEffect(() => {
+    if (!widgetId) return
+    SL.appConfiguration.getWidgetInstance({ collectionId, appId, widgetId })
+      .then(setInstance)
+      .catch(console.error)
+  }, [collectionId, appId, widgetId, SL])
+
+  if (!widgetId || !instance) return null
+
+  switch (instance.widget?.type) {
+    case 'countdown':
+      return <CountdownWidget {...props} {...instance.widget} />
+    case 'cta-button':
+      return <CtaButtonWidget {...props} {...instance.widget} />
+    default:
+      return null
+  }
+}
+```
+
+### Listing widget instances
+
+`listWidgetInstances()` is useful for picker UIs and cross-app references:
+
+```typescript
+const options = await SL.appConfiguration.listWidgetInstances({
+  collectionId,
+  appId: 'widget-toolkit',
+})
+
+// [{ id: 'launch-countdown', name: 'Launch Countdown', type: 'countdown' }]
+```
+
+This is a good foundation for future admin question types or dynamic selects, but the SDK does not currently define a built-in `dynamic-select` schema field.
+
 ### 1. Create the Widget Component
 
 ```typescript

package/dist/http.js

@@ -718,7 +718,7 @@ async function proxyStreamRequest(method, path, body, headers) {
     ensureProxyListener();
     const payloadBody = (typeof FormData !== 'undefined' && body instanceof FormData)
         ? serializeFormDataForProxy(body)
-        : body;
+        : sanitizeForPostMessage(body);
     const id = generateProxyId();
     const streamController = createProxyStreamIterable(id);
     proxyStreamPending.set(id, streamController);
@@ -749,6 +749,53 @@ function serializeFormDataForProxy(fd) {
     });
     return { _isFormData: true, entries };
 }
+function isAbortSignalLike(value) {
+    return !!value
+        && typeof value === 'object'
+        && 'aborted' in value
+        && 'addEventListener' in value
+        && 'removeEventListener' in value;
+}
+function sanitizeForPostMessage(value, seen = new WeakSet()) {
+    if (value == null)
+        return value;
+    const valueType = typeof value;
+    if (valueType === 'function' || valueType === 'symbol') {
+        return undefined;
+    }
+    if (valueType !== 'object') {
+        return value;
+    }
+    if (typeof Blob !== 'undefined' && value instanceof Blob) {
+        return value;
+    }
+    if (typeof ArrayBuffer !== 'undefined' && value instanceof ArrayBuffer) {
+        return value;
+    }
+    if (ArrayBuffer.isView(value)) {
+        return value;
+    }
+    if (isAbortSignalLike(value)) {
+        return undefined;
+    }
+    if (seen.has(value)) {
+        return undefined;
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value
+            .map(item => sanitizeForPostMessage(item, seen))
+            .filter(item => item !== undefined);
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+        return value;
+    }
+    const sanitizedEntries = Object.entries(value)
+        .map(([key, entryValue]) => [key, sanitizeForPostMessage(entryValue, seen)])
+        .filter(([, entryValue]) => entryValue !== undefined);
+    return Object.fromEntries(sanitizedEntries);
+}
 function sanitizeProxyRequestOptions(options) {
     if (!options)
         return undefined;
@@ -766,7 +813,7 @@ async function proxyRequest(method, path, body, headers, options) {
     ensureProxyListener();
     const payloadBody = (typeof FormData !== 'undefined' && body instanceof FormData)
         ? serializeFormDataForProxy(body)
-        : body;
+        : sanitizeForPostMessage(body);
     const id = generateProxyId();
     const msg = {
         _smartlinksProxyRequest: true,
@@ -1443,7 +1490,7 @@ export async function sendCustomProxyMessage(request, params) {
         _smartlinksCustomProxyRequest: true,
         id,
         request,
-        params,
+        params: sanitizeForPostMessage(params),
     };
     logDebug('[smartlinks] proxy:custom postMessage', { id, request, params: safeBodyPreview(params) });
     return new Promise((resolve, reject) => {

package/dist/openapi.yaml

@@ -11433,6 +11433,49 @@ components:
       required:
         - id
         - name
+    GetWidgetInstanceOptions:
+      type: object
+      properties:
+        appId:
+          type: string
+        collectionId:
+          type: string
+        productId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+        admin:
+          type: boolean
+        widgetId:
+          type: string
+      required:
+        - appId
+        - widgetId
+    WidgetInstance:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        widget:
+          $ref: "#/components/schemas/TWidget"
+      required:
+        - id
+    WidgetInstanceSummary:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        type:
+          type: string
+      required:
+        - id
+        - name
     AppBundle:
       type: object
       properties:
@@ -11493,6 +11536,22 @@ components:
           additionalProperties: true
       required:
         - name
+    AppManifestWidgets:
+      type: object
+      properties:
+        files:
+          $ref: "#/components/schemas/AppManifestFiles"
+        components:
+          type: array
+          items:
+            $ref: "#/components/schemas/AppWidgetComponent"
+        instanceResolution:
+          type: boolean
+        instanceParam:
+          type: string
+      required:
+        - files
+        - components
     AppContainerComponent:
       type: object
       properties:
@@ -11785,6 +11844,8 @@ components:
         admin:
           type: string
         widgets:
+          $ref: "#/components/schemas/AppManifestWidgets"
+        containers:
           type: object
           additionalProperties: true
         files:
@@ -11793,9 +11854,6 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/AppContainerComponent"
-        containers:
-          type: object
-          additionalProperties: true
         linkable:
           type: array
           items:
@@ -11809,8 +11867,6 @@ components:
         - function
         - files
         - components
-        - files
-        - components
     CollectionAppWidget:
       type: object
       properties:

package/dist/types/appConfiguration.d.ts

@@ -9,3 +9,27 @@ export interface AppConfigurationResponse {
     /** Key-value pairs representing configuration settings */
     settings?: Record<string, any>;
 }
+/** Options for resolving a configured widget instance from app config. */
+export interface GetWidgetInstanceOptions {
+    appId: string;
+    collectionId?: string;
+    productId?: string;
+    variantId?: string;
+    batchId?: string;
+    admin?: boolean;
+    widgetId: string;
+}
+/** A configured widget instance stored in `appConfig.widgets`. */
+export interface WidgetInstance<TWidget = any> {
+    id: string;
+    name?: string;
+    widget?: TWidget;
+    [key: string]: any;
+}
+/** Minimal summary shape for picker UIs and instance selectors. */
+export interface WidgetInstanceSummary {
+    id: string;
+    name: string;
+    type?: string;
+    [key: string]: any;
+}

package/dist/types/appManifest.d.ts

@@ -51,6 +51,15 @@ export interface AppWidgetComponent {
     /** JSON-Schema-style settings the widget accepts */
     settings?: Record<string, any>;
 }
+/** Widget bundle declaration in `app.manifest.json`. */
+export interface AppManifestWidgets {
+    files: AppManifestFiles;
+    components: AppWidgetComponent[];
+    /** Whether this app supports resolving configured widget instances by ID. */
+    instanceResolution?: boolean;
+    /** Query/hash parameter name used for instance resolution. Defaults to `widgetId`. */
+    instanceParam?: string;
+}
 /** A single container component defined in the manifest */
 export interface AppContainerComponent {
     name: string;
@@ -301,10 +310,7 @@ export interface AppManifest {
      */
     admin?: string;
     /** Widget bundle definition. Presence means a widget bundle exists for this app. */
-    widgets?: {
-        files: AppManifestFiles;
-        components: AppWidgetComponent[];
-    };
+    widgets?: AppManifestWidgets;
     /** Container bundle definition. Presence means a container bundle exists. */
     containers?: {
         files: AppManifestFiles;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.8.3  |  Generated: 2026-03-14T10:31:32.637Z
+Version: 1.8.5  |  Generated: 2026-03-14T14:43:55.897Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1283,6 +1283,39 @@ interface AppConfigurationResponse {
 }
 ```
 
+**GetWidgetInstanceOptions** (interface)
+```typescript
+interface GetWidgetInstanceOptions {
+  appId: string
+  collectionId?: string
+  productId?: string
+  variantId?: string
+  batchId?: string
+  admin?: boolean
+  widgetId: string
+}
+```
+
+**WidgetInstance<TWidget = any>** (interface)
+```typescript
+interface WidgetInstance<TWidget = any> {
+  id: string
+  name?: string
+  widget?: TWidget
+  [key: string]: any
+}
+```
+
+**WidgetInstanceSummary** (interface)
+```typescript
+interface WidgetInstanceSummary {
+  id: string
+  name: string
+  type?: string
+  [key: string]: any
+}
+```
+
 ### appManifest
 
 **AppBundle** (interface)
@@ -1324,6 +1357,16 @@ interface AppWidgetComponent {
 }
 ```
 
+**AppManifestWidgets** (interface)
+```typescript
+interface AppManifestWidgets {
+  files: AppManifestFiles;
+  components: AppWidgetComponent[];
+  instanceResolution?: boolean;
+  instanceParam?: string;
+}
+```
+
 **AppContainerComponent** (interface)
 ```typescript
 interface AppContainerComponent {
@@ -1525,10 +1568,7 @@ interface AppManifest {
   * (setup questions, import schema, tunable fields, metrics definitions).
   * Absent when the app has no admin UI.
   admin?: string;
-  widgets?: {
-  files: AppManifestFiles;
-  components: AppWidgetComponent[];
-  };
+  widgets?: AppManifestWidgets;
   containers?: {
   files: AppManifestFiles;
   components: AppContainerComponent[];
@@ -6016,6 +6056,9 @@ Get related threads and records for a case (admin only) GET /cases/:caseId/relat
 **getConfig**(opts: AppConfigOptions) → `Promise<any>`
 Get app configuration for a collection/product scope. ```typescript const config = await appConfiguration.getConfig({ appId: 'warranty-portal', collectionId: 'my-collection' }); ```
 
+**listWidgetInstances**(opts: Omit<GetWidgetInstanceOptions, 'widgetId'>) → `Promise<WidgetInstanceSummary[]>`
+List configured widget instances for an app. Useful for picker UIs, setup schemas, and widget-to-widget references. ```typescript const widgets = await appConfiguration.listWidgetInstances({ collectionId: 'my-collection', appId: 'widget-toolkit' }) ```
+
 **setConfig**(opts: AppConfigOptions) → `Promise<any>`
 Set app configuration for a collection/product scope. Requires admin authentication. ```typescript await appConfiguration.setConfig({ appId: 'warranty-portal', collectionId: 'my-collection', admin: true, config: { warrantyPeriod: 24, supportEmail: 'support@example.com' } }); ```
 

package/docs/app-manifest.md

@@ -46,6 +46,8 @@ The manifest is loaded automatically by the platform for every collection page.
   "admin": "app.admin.json",
 
   "widgets": {
+    "instanceResolution": true,
+    "instanceParam": "widgetId",
     "files": {
       "js": {
         "umd": "dist/widgets.umd.js",
@@ -127,8 +129,36 @@ Declares the widget bundle. Omit if the app has no widget component.
 | `files.js.umd` | UMD bundle path — used for dynamic `<script>` loading |
 | `files.js.esm` | ESM bundle path — used for `import()` / native ES modules (optional but recommended) |
 | `files.css` | CSS bundle path — omit if the widget ships no styles |
+| `instanceResolution` | Optional boolean. When `true`, this app supports resolving configured widget instances by ID from app config |
+| `instanceParam` | Optional string. Query/hash param used for instance lookup. Defaults to `"widgetId"` |
 | `components[]` | One entry per exported widget component (see below) |
 
+**Widget instance resolution**
+
+Apps such as widget toolkits often store reusable widget instances in collection-scoped app config, for example under `config.widgets.launch-countdown`. When your widget bundle can self-configure from one of those stored instances, declare that capability in the manifest:
+
+```json
+"widgets": {
+  "instanceResolution": true,
+  "instanceParam": "widgetId",
+  "files": {
+    "js": {
+      "umd": "dist/widgets.umd.js",
+      "esm": "dist/widgets.es.js"
+    },
+    "css": null
+  },
+  "components": [
+    {
+      "name": "WidgetToolkitResolver",
+      "description": "Resolves and renders a configured widget instance by ID."
+    }
+  ]
+}
+```
+
+This tells the platform and other apps that they can deep-link into a stored widget instance using a URL or embed context such as `?appId=widget-toolkit&widgetId=launch-countdown`.
+
 **Component fields:**
 
 | Field | Type | Description |
@@ -281,6 +311,8 @@ Fetched only by the admin UI and AI-assisted setup flows — never loaded on the
 }
 ```
 
+> `dynamic-select` widget pickers are a reasonable future extension for admin schemas, but they are not a built-in question type in the SDK today. For now, treat widget-instance selection as an app-level UI convention powered by `appConfiguration.listWidgetInstances()`.
+
 ### Field Reference
 
 #### `aiGuide`

package/docs/deep-link-discovery.md

@@ -35,6 +35,8 @@ Deep-linkable states come from **two sources** depending on their nature:
 | **App manifest** (`app.manifest.json`) | Fixed routes built into the app | Only when the app itself is updated |
 | **App config** (`appConfig.linkable`) | Content-driven entries that vary by collection | When admins create, remove, or rename content |
 
+Widget-oriented apps can also use the same deep-link model with `widgetId` rather than `pageId`: the app config stores reusable widget instances, and the URL or embed context selects a specific instance to render.
+
 Consumers merge both sources to get the full set of navigable states for an app.
 
 ```text
@@ -232,6 +234,7 @@ The parent platform constructs the final navigation URL from an entry by combini
 | Entry | Resolved URL |
 |-------|--------------|
 | `{ title: "About Us", params: { pageId: "about-us" } }` | `https://app.example.com/#/?collectionId=abc&appId=my-app&pageId=about-us` |
+| `{ title: "Launch Countdown", params: { widgetId: "launch-countdown" } }` | `https://app.example.com/#/?collectionId=abc&appId=widget-toolkit&widgetId=launch-countdown` |
 | `{ title: "Advanced Settings", path: "/settings", params: { tab: "advanced" } }` | `https://app.example.com/admin.html#/settings?collectionId=abc&appId=my-app&tab=advanced` |
 | `{ title: "Gallery", path: "/gallery" }` | `https://app.example.com/#/gallery?collectionId=abc&appId=my-app` |
 | `{ title: "Home" }` | `https://app.example.com/#/?collectionId=abc&appId=my-app` |
@@ -259,6 +262,31 @@ This section only applies to **dynamic links stored in `appConfig.linkable`**. S
 
 Apps **MUST** update `appConfig.linkable` whenever the set of dynamic navigable states changes:
 
+For widget toolkits, that usually means syncing entries from your stored widget instance map:
+
+```typescript
+const widgets = await SL.appConfiguration.listWidgetInstances({
+  collectionId,
+  appId: 'widget-toolkit',
+  admin: true,
+})
+
+const linkable = widgets.map(widget => ({
+  title: widget.name,
+  params: { widgetId: widget.id },
+}))
+
+const current = await SL.appConfiguration.getConfig({ collectionId, appId: 'widget-toolkit', admin: true }) ?? {}
+await SL.appConfiguration.setConfig({
+  collectionId,
+  appId: 'widget-toolkit',
+  admin: true,
+  config: { ...current, linkable },
+})
+```
+
+This gives the portal and AI orchestrators the same discoverability for widget instances that page-driven apps already get for `pageId` content.
+
 - A page is created, deleted, published, or unpublished
 - A page's `deepLinkable` flag is toggled
 - A page title changes

package/docs/manifests.md

@@ -19,7 +19,7 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
 |---------|---------|-------------|
 | `meta` | App identity, version, appId, SEO priority | All workflows |
 | `admin` | Pointer to `app.admin.json` | Admin orchestrators |
-| `widgets` | Bundle files + component definitions + settings schemas | Widget Builder |
+| `widgets` | Bundle files + component definitions + settings schemas; can also declare widget-instance resolution via `widgetId` | Widget Builder |
 | `containers` | Bundle files + component definitions | Container Loader |
 | `executor` | Bundle files, factory name, exports list | Server / AI |
 | `linkable` | Static deep-link routes | Portal menus / AI nav |
@@ -29,6 +29,8 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
   "meta": { "name": "My App", "appId": "my-app", "version": "1.0.0" },
   "admin": "app.admin.json",
   "widgets": {
+    "instanceResolution": true,
+    "instanceParam": "widgetId",
     "files": {
       "js": { "umd": "dist/widgets.umd.js", "esm": "dist/widgets.es.js" },
       "css": null
@@ -62,6 +64,8 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
 }
 ```
 
+When `instanceResolution` is enabled, the app is declaring that consumers can pass a widget instance identifier such as `?appId=widget-toolkit&widgetId=launch-countdown`, and the widget bundle will resolve its stored configuration from app config.
+
 > ⚠️ **`css` is `null` by default.** Most widgets and containers use Tailwind/shadcn classes inherited from the parent and produce **no CSS output file**. Set `"css": null` in the manifest. Only set it to a filename if your widget/container ships a custom CSS file that actually exists in `dist/`. The parent portal checks this value before injecting a `<link>` tag — a non-null value pointing to a missing file will cause a 404.
 
 ---

package/docs/widgets.md

@@ -202,6 +202,141 @@ Widgets support two navigation patterns:
 
 ## Building a Widget
 
+---
+
+## Widget Instance Resolution
+
+Some apps expose a **widget resolver** instead of a single hard-coded widget. The resolver receives a `widgetId`, looks up a stored instance in app config, and renders the correct widget with its saved settings.
+
+This pattern is useful for widget toolkits, promo blocks, countdown libraries, CTA collections, and any app where admins create multiple reusable widget instances.
+
+### URL and embed convention
+
+Use `widgetId` the same way page-oriented apps use `pageId`:
+
+```text
+?appId=widget-toolkit&widgetId=launch-countdown
+```
+
+This works naturally in:
+
+- direct container or iframe links
+- widget-to-widget references
+- content slots that need to embed a preconfigured widget instance
+- platform deep-link routing when the manifest declares widget instance resolution
+
+### Manifest declaration
+
+Declare support in `app.manifest.json`:
+
+```json
+{
+  "widgets": {
+    "instanceResolution": true,
+    "instanceParam": "widgetId",
+    "files": {
+      "js": {
+        "umd": "dist/widgets.umd.js",
+        "esm": "dist/widgets.es.js"
+      },
+      "css": null
+    },
+    "components": [
+      {
+        "name": "WidgetToolkitResolver",
+        "description": "Resolves and renders widget instances by ID."
+      }
+    ]
+  }
+}
+```
+
+### SDK helpers
+
+The SDK now includes two thin helpers on `SL.appConfiguration`:
+
+```typescript
+const widget = await SL.appConfiguration.getWidgetInstance({
+  collectionId,
+  appId: 'widget-toolkit',
+  widgetId: 'launch-countdown',
+})
+
+const widgets = await SL.appConfiguration.listWidgetInstances({
+  collectionId,
+  appId: 'widget-toolkit',
+})
+```
+
+`getWidgetInstance()` is intentionally just a wrapper over `getConfig()` that reads `config.widgets[widgetId]`. That keeps the integration simple today while giving the platform freedom to optimize the lookup later.
+
+### Stored config shape
+
+The recommended storage shape is:
+
+```json
+{
+  "widgets": {
+    "launch-countdown": {
+      "id": "launch-countdown",
+      "name": "Launch Countdown",
+      "widget": {
+        "type": "countdown",
+        "targetDate": "2026-06-01T00:00:00Z",
+        "label": "Launching in..."
+      }
+    }
+  }
+}
+```
+
+### Resolver pattern
+
+```typescript
+const WidgetToolkitResolver: React.FC<SmartLinksWidgetProps & { widgetId?: string }> = ({
+  collectionId,
+  appId,
+  widgetId,
+  SL,
+  ...props
+}) => {
+  const [instance, setInstance] = React.useState<any | null>(null)
+
+  React.useEffect(() => {
+    if (!widgetId) return
+    SL.appConfiguration.getWidgetInstance({ collectionId, appId, widgetId })
+      .then(setInstance)
+      .catch(console.error)
+  }, [collectionId, appId, widgetId, SL])
+
+  if (!widgetId || !instance) return null
+
+  switch (instance.widget?.type) {
+    case 'countdown':
+      return <CountdownWidget {...props} {...instance.widget} />
+    case 'cta-button':
+      return <CtaButtonWidget {...props} {...instance.widget} />
+    default:
+      return null
+  }
+}
+```
+
+### Listing widget instances
+
+`listWidgetInstances()` is useful for picker UIs and cross-app references:
+
+```typescript
+const options = await SL.appConfiguration.listWidgetInstances({
+  collectionId,
+  appId: 'widget-toolkit',
+})
+
+// [{ id: 'launch-countdown', name: 'Launch Countdown', type: 'countdown' }]
+```
+
+This is a good foundation for future admin question types or dynamic selects, but the SDK does not currently define a built-in `dynamic-select` schema field.
+
 ### 1. Create the Widget Component
 
 ```typescript

package/openapi.yaml

@@ -11433,6 +11433,49 @@ components:
       required:
         - id
         - name
+    GetWidgetInstanceOptions:
+      type: object
+      properties:
+        appId:
+          type: string
+        collectionId:
+          type: string
+        productId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+        admin:
+          type: boolean
+        widgetId:
+          type: string
+      required:
+        - appId
+        - widgetId
+    WidgetInstance:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        widget:
+          $ref: "#/components/schemas/TWidget"
+      required:
+        - id
+    WidgetInstanceSummary:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        type:
+          type: string
+      required:
+        - id
+        - name
     AppBundle:
       type: object
       properties:
@@ -11493,6 +11536,22 @@ components:
           additionalProperties: true
       required:
         - name
+    AppManifestWidgets:
+      type: object
+      properties:
+        files:
+          $ref: "#/components/schemas/AppManifestFiles"
+        components:
+          type: array
+          items:
+            $ref: "#/components/schemas/AppWidgetComponent"
+        instanceResolution:
+          type: boolean
+        instanceParam:
+          type: string
+      required:
+        - files
+        - components
     AppContainerComponent:
       type: object
       properties:
@@ -11785,6 +11844,8 @@ components:
         admin:
           type: string
         widgets:
+          $ref: "#/components/schemas/AppManifestWidgets"
+        containers:
           type: object
           additionalProperties: true
         files:
@@ -11793,9 +11854,6 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/AppContainerComponent"
-        containers:
-          type: object
-          additionalProperties: true
         linkable:
           type: array
           items:
@@ -11809,8 +11867,6 @@ components:
         - function
         - files
         - components
-        - files
-        - components
     CollectionAppWidget:
       type: object
       properties:

package/package.json

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