@proveanything/smartlinks 2.0.53 → 2.0.55

package/dist/api/appConfiguration.d.ts

@@ -379,21 +379,16 @@ export declare namespace appConfiguration {
      * ```typescript
      * // Fetch all widget data for a collection
      * const { apps } = await Api.AppConfiguration.getWidgets(collectionId);
-     * // Returns: [{ appId, manifestUrl, manifest, bundleSource, bundleCss }, ...]
-     *
-     * // Convert bundle source to dynamic imports
-     * for (const app of apps) {
-     *   const blob = new Blob([app.bundleSource], { type: 'application/javascript' });
-     *   const blobUrl = URL.createObjectURL(blob);
-     *   const widgetModule = await import(blobUrl);
-     *
-     *   // Inject CSS if present
-     *   if (app.bundleCss) {
-     *     const styleTag = document.createElement('style');
-     *     styleTag.textContent = app.bundleCss;
-     *     document.head.appendChild(styleTag);
-     *   }
-     * }
+     * // Returns: [{ appId, manifest, widget, container, admin }, ...]
+     * //   widget / container: { js: { umd?, esm? }, css?, source?, styles? }
+     * //     source / styles - the bundle inlined (when small enough); js / css - URLs otherwise.
+     * //   admin - URL of the app's app.admin.json (setup / tunable options), or null.
+     * // Bundles don't ship React: they resolve shared libraries from the HOST's globals
+     * // (host-dependency-contract.md), so loading one is a host's job.
+     * //
+     * // Inside a host (Portal / Hub), an app showing ANOTHER app's widget should not load
+     * // bundles itself - use the host-provided EmbeddedWidget prop:
+     * //   <EmbeddedWidget appId="raffle" size="standard" />   (docs/widgets.md)
      *
      * // Force refresh all widgets
      * const { apps } = await Api.AppConfiguration.getWidgets(collectionId, { force: true });

package/dist/api/appConfiguration.js

@@ -482,21 +482,16 @@ export var appConfiguration;
      * ```typescript
      * // Fetch all widget data for a collection
      * const { apps } = await Api.AppConfiguration.getWidgets(collectionId);
-     * // Returns: [{ appId, manifestUrl, manifest, bundleSource, bundleCss }, ...]
-     *
-     * // Convert bundle source to dynamic imports
-     * for (const app of apps) {
-     *   const blob = new Blob([app.bundleSource], { type: 'application/javascript' });
-     *   const blobUrl = URL.createObjectURL(blob);
-     *   const widgetModule = await import(blobUrl);
-     *
-     *   // Inject CSS if present
-     *   if (app.bundleCss) {
-     *     const styleTag = document.createElement('style');
-     *     styleTag.textContent = app.bundleCss;
-     *     document.head.appendChild(styleTag);
-     *   }
-     * }
+     * // Returns: [{ appId, manifest, widget, container, admin }, ...]
+     * //   widget / container: { js: { umd?, esm? }, css?, source?, styles? }
+     * //     source / styles - the bundle inlined (when small enough); js / css - URLs otherwise.
+     * //   admin - URL of the app's app.admin.json (setup / tunable options), or null.
+     * // Bundles don't ship React: they resolve shared libraries from the HOST's globals
+     * // (host-dependency-contract.md), so loading one is a host's job.
+     * //
+     * // Inside a host (Portal / Hub), an app showing ANOTHER app's widget should not load
+     * // bundles itself - use the host-provided EmbeddedWidget prop:
+     * //   <EmbeddedWidget appId="raffle" size="standard" />   (docs/widgets.md)
      *
      * // Force refresh all widgets
      * const { apps } = await Api.AppConfiguration.getWidgets(collectionId, { force: true });

package/dist/api/index.d.ts

@@ -10,7 +10,6 @@ export { auth } from "./auth.js";
 export { form } from "./form.js";
 export { authKit } from "./authKit.js";
 export { claimSet } from "./claimSet.js";
-export { sequence } from "./sequence.js";
 export { crate } from "./crate.js";
 export { batch } from "./batch.js";
 export { variant } from "./variant.js";

package/dist/api/index.js

@@ -12,7 +12,6 @@ export { auth } from "./auth.js";
 export { form } from "./form.js";
 export { authKit } from "./authKit.js";
 export { claimSet } from "./claimSet.js";
-export { sequence } from "./sequence.js";
 export { crate } from "./crate.js";
 export { batch } from "./batch.js";
 export { variant } from "./variant.js";

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.53  |  Generated: 2026-10-11T14:02:22.790Z
+Version: 2.0.55  |  Generated: 2026-10-12T20:04:55.294Z
 
 This is a concise summary of all available API functions and types.
 
@@ -154,7 +154,6 @@ The Smartlinks SDK is organized into the following namespaces:
 - **realtime** - Functions for realtime operations
 - **research** - Functions for research operations
 - **secrets** - Functions for secrets operations
-- **sequence** - Functions for sequence operations
 - **tags** - Functions for tags operations
 - **template** - Functions for template operations
 - **translations** - Functions for translations operations
@@ -9744,9 +9743,26 @@ interface SmartLinksWidgetProps {
   size?: 'compact' | 'standard' | 'large'
   lang?: string
   translations?: Record<string, string>
+  EmbeddedWidget?: EmbeddedWidgetComponent
 }
 ```
 
+**EmbeddedWidgetProps** (interface)
+```typescript
+interface EmbeddedWidgetProps {
+  appId: string
+  component?: string
+  size?: 'compact' | 'standard' | 'large'
+  widgetId?: string
+  props?: Record<string, unknown>
+  className?: string
+  fallback?: unknown
+  loading?: unknown
+}
+```
+
+**EmbeddedWidgetComponent** = `(props: EmbeddedWidgetProps) => any`
+
 ### appConfiguration (api)
 
 **AppConfigOptions** (type)
@@ -9852,26 +9868,6 @@ interface AppSecretOptions {
 }
 ```
 
-### sequence (api)
-
-**AllocateSequenceInput** (interface)
-```typescript
-interface AllocateSequenceInput {
-  appId: string
-  sequenceId: string
-  subjectId: string
-  productId?: string
-}
-```
-
-**AllocatedSequence** (interface)
-```typescript
-interface AllocatedSequence {
-  number: number
-  isNew: boolean
-}
-```
-
 ### conditions (utils)
 
 **BaseCondition** (interface)
@@ -10380,7 +10376,7 @@ Delete a keyed data item by ID within a scope. Requires admin authentication. ``
 
 **getWidgets**(collectionId: string,
     options?: GetCollectionWidgetsOptions) → `Promise<CollectionWidgetsResponse>`
-Fetches ALL widget data (manifests + bundle files) for a collection in one call. Returns everything needed to render widgets with zero additional requests. This solves N+1 query problems by fetching manifests, JavaScript bundles, and CSS files in parallel on the server. ```typescript // Fetch all widget data for a collection const { apps } = await Api.AppConfiguration.getWidgets(collectionId); // Returns: [{ appId, manifestUrl, manifest, bundleSource, bundleCss }, ...] // Convert bundle source to dynamic imports for (const app of apps) { const blob = new Blob([app.bundleSource], { type: 'application/javascript' }); const blobUrl = URL.createObjectURL(blob); const widgetModule = await import(blobUrl); // Inject CSS if present if (app.bundleCss) { const styleTag = document.createElement('style'); styleTag.textContent = app.bundleCss; document.head.appendChild(styleTag); } } // Force refresh all widgets const { apps } = await Api.AppConfiguration.getWidgets(collectionId, { force: true }); ```
+Fetches ALL widget data (manifests + bundle files) for a collection in one call. Returns everything needed to render widgets with zero additional requests. This solves N+1 query problems by fetching manifests, JavaScript bundles, and CSS files in parallel on the server. ```typescript // Fetch all widget data for a collection const { apps } = await Api.AppConfiguration.getWidgets(collectionId); // Returns: [{ appId, manifest, widget, container, admin }, ...] //   widget / container: { js: { umd?, esm? }, css?, source?, styles? } //     source / styles - the bundle inlined (when small enough); js / css - URLs otherwise. //   admin - URL of the app's app.admin.json (setup / tunable options), or null. // Bundles don't ship React: they resolve shared libraries from the HOST's globals // (host-dependency-contract.md), so loading one is a host's job. // // Inside a host (Portal / Hub), an app showing ANOTHER app's widget should not load // bundles itself - use the host-provided EmbeddedWidget prop: //   <EmbeddedWidget appId="raffle" size="standard" />   (docs/widgets.md) // Force refresh all widgets const { apps } = await Api.AppConfiguration.getWidgets(collectionId, { force: true }); ```
 
 **resolveFeature**(system: SystemBlock | undefined, flag: string) → `boolean`
 Resolve whether a feature flag is on, applying the `accountType` default: `enterprise` accounts default every flag to **on** unless `features[flag]` is explicitly `false`; `standard` accounts (or missing `accountType`) default every flag to **off** unless `features[flag]` is explicitly `true`. An explicit value always wins over the default either way. This is the same logic `isFeatureEnabled()` / `isFeatureEnabledSync()` use internally — call those instead in normal code. `system.features` and `accountType` are public data (no admin-only feature-check path exists), so there's no reason to fetch differently for an admin surface. This is exposed separately only for the rare case where you already have a `system` block in hand from somewhere other than `getAppConfig()` (e.g. server-rendered props) and want to resolve a flag from it directly. ```typescript const enabled = appConfiguration.resolveFeature(someSystemBlock, 'custom_domain'); ```
@@ -12234,11 +12230,6 @@ Soft-delete a secret. DELETE /secrets/:ref
     id: string,
     query: { limit?: number; offset?: number } = {}) → `Promise<SegmentRecipientsResponse>`
 
-### sequence
-
-**allocate**(collectionId: string, input: AllocateSequenceInput) → `Promise<AllocatedSequence>`
-Allocate (or return the existing) sequence number for a subject. Idempotent — safe to call on load (auto-enter) and on a button tap; a subject that already has a number gets it back with `isNew: false`. const { number, isNew } = await sequence.allocate(collectionId, { appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId, }) `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
-
 ### sessions
 
 **stats**(collectionId: string) → `Promise<SessionStatistics>`

package/dist/docs/containers.md

@@ -226,6 +226,13 @@ All standard widget props apply:
 
 ---
 
+### Showing another app's widget
+
+A container can show another installed app's widget inline with the host-provided `EmbeddedWidget` prop:
+`<EmbeddedWidget appId="raffle" size="standard" />`. The host loads it, isolates it and contains any crash.
+See [widgets.md → Using another app's widget](widgets.md#using-another-apps-widget). Don't hand-roll a
+widget loader.
+
 ## Cross-App Navigation
 
 Containers support the same **structured navigation requests** as widgets. When a container needs to navigate to another app within the portal, it emits a `NavigationRequest` via the `onNavigate` callback. The portal orchestrator interprets the request, preserves hierarchy context, and performs the navigation.

package/dist/docs/overview.md

@@ -93,7 +93,6 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Container Tracking** | `docs/container-tracking.md` | Physical/logical **item** container groupings — *not* app containers (see containers.md) |
 | **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
 | **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
-| **Sequences** | `docs/sequences.md` | RETIRING — number things in your own server function: `ctx.sl.counters` + `appRecords.claim` (server-functions.md) |
 | **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
 | **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
 | **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |

package/dist/docs/widgets.md

@@ -146,6 +146,7 @@ interface SmartLinksWidgetProps {
 | `size` | `string?` | Size hint: 'compact', 'standard', or 'large' |
 | `lang` | `string?` | Language code (e.g., 'en', 'de', 'fr') |
 | `translations` | `object?` | Translation overrides |
+| `EmbeddedWidget` | `component?` | Host-provided: show another app's widget inside yours — see [Using another app's widget](#using-another-apps-widget) |
 
 ---
 
@@ -557,6 +558,56 @@ If `VITE_ENABLE_WIDGETS` is not set to `true`, the build produces a minimal stub
 
 ---
 
+## Using another app's widget
+
+Your container, page or widget can show **another installed app's widget** inline (a raffle entry, a
+donate button, a loyalty card), natively, with no iframe. **The host does the work.** Portal and Hub pass
+every app they mount an `EmbeddedWidget` component:
+
+```tsx
+export function EventGuide({ EmbeddedWidget, ...props }: SmartLinksContainerProps) {
+  return (
+    <section>
+      <h2>Win a signed shirt</h2>
+      {EmbeddedWidget ? (
+        <EmbeddedWidget appId="raffle" size="standard" fallback={null} />
+      ) : null}
+    </section>
+  );
+}
+```
+
+| Prop | What it does |
+|---|---|
+| `appId` | The app whose widget to show, as installed on this collection. |
+| `component` | Which of its widget components (`widgets.components[].name` in its manifest). Default: the first. |
+| `size` | `'compact' \| 'standard' \| 'large'` — a hint the widget may honour. Default `standard`. |
+| `widgetId` | A configured instance, for apps with widget instances (see [Widget Instance Resolution](#widget-instance-resolution)). |
+| `props` | Extra props for the widget: its documented props and settings. |
+| `fallback` / `loading` | What to show if it can't be shown / while it loads. Default: nothing. |
+
+What the host does for you:
+- Loads the widget through its own bundle cache: the same code that renders the portal's widgets. It
+  provides the shared libraries (React, the SDK, the router, …) and picks the component.
+- Gives it the same context you have: collection, product, proof, user, language, and navigation
+  (`onNavigate` goes straight to the portal, so the widget's links work as they do anywhere else).
+- Mounts it in **its own router**, so it never touches your routes. Don't wrap it in a router.
+- Contains any crash: a broken widget renders `fallback`, never takes down your page.
+- Renders `fallback` when the app isn't installed on this collection, exports no widget, or isn't allowed.
+
+**What can be embedded:** first-party SmartLinks widgets (app IDs without a developer handle), and your
+own publisher's apps (`acme--raffle` from `acme--events`). The host enforces this; anything else renders
+`fallback`, with a console warning. An app can't embed itself, and nesting stops two levels deep.
+
+**Don't build your own loader** (getWidgets → evaluate the bundle → shared globals → require shim). Every
+copy drifts and breaks; `EmbeddedWidget` is absent outside a host, so render nothing there.
+
+**Finding out what's available:** in Forge, `forge-widgets catalog` lists the widgets you can embed
+(apps installed on the preview's collection), and `forge-widgets describe <app>` gives a widget's
+components, sizes, props, settings and setup options.
+
+---
+
 ## Parent Integration
 
 ### Dynamic Import

package/dist/openapi.yaml

@@ -30830,10 +30830,36 @@ components:
           type: object
           additionalProperties:
             type: string
+        EmbeddedWidget:
+          $ref: "#/components/schemas/EmbeddedWidgetComponent"
       required:
         - collectionId
         - appId
         - SL
+    EmbeddedWidgetProps:
+      type: object
+      properties:
+        appId:
+          type: string
+        component:
+          type: string
+        size:
+          type: string
+          enum:
+            - compact
+            - standard
+            - large
+        widgetId:
+          type: string
+        props:
+          type: object
+          additionalProperties: true
+        className:
+          type: string
+        fallback: {}
+        loading: {}
+      required:
+        - appId
     AppConfigOptions:
       type: object
       properties:
@@ -30932,28 +30958,3 @@ components:
       properties:
         appId:
           type: string
-    AllocateSequenceInput:
-      type: object
-      properties:
-        appId:
-          type: string
-        sequenceId:
-          type: string
-        subjectId:
-          type: string
-        productId:
-          type: string
-      required:
-        - appId
-        - sequenceId
-        - subjectId
-    AllocatedSequence:
-      type: object
-      properties:
-        number:
-          type: number
-        isNew:
-          type: boolean
-      required:
-        - number
-        - isNew

package/dist/types/widgets.d.ts

@@ -83,4 +83,32 @@ export interface SmartLinksWidgetProps {
     lang?: string;
     /** Translation key overrides */
     translations?: Record<string, string>;
+    /**
+     * Show ANOTHER app's widget inside this app, rendered by the host (Portal / Hub):
+     * `<EmbeddedWidget appId="raffle" size="standard" widgetId="…" />`. The host loads it, gives it the
+     * same context you have, keeps it in its own router and contains any crash. Absent outside a host.
+     * Only first-party widgets and your own publisher's apps can be embedded. See docs/widgets.md
+     * "Using another app's widget".
+     */
+    EmbeddedWidget?: EmbeddedWidgetComponent;
+}
+/** Props of the host-provided `EmbeddedWidget` (see {@link SmartLinksWidgetProps.EmbeddedWidget}). */
+export interface EmbeddedWidgetProps {
+    /** The app whose widget to show, as installed on this collection. */
+    appId: string;
+    /** Which of its widget components (its manifest `widgets.components[].name`). Default: the first. */
+    component?: string;
+    /** Size hint the widget may honour. */
+    size?: 'compact' | 'standard' | 'large';
+    /** A configured instance of the widget (apps with widget instances — see "Widget Instance Resolution"). */
+    widgetId?: string;
+    /** Extra props for the widget: its documented props / settings. */
+    props?: Record<string, unknown>;
+    className?: string;
+    /** Shown when the widget can't be shown (not installed, no widget, not allowed, failed). Default: nothing. */
+    fallback?: unknown;
+    /** Shown while it loads. Default: nothing. */
+    loading?: unknown;
 }
+/** A React component taking {@link EmbeddedWidgetProps} (typed loosely: the SDK doesn't depend on React). */
+export type EmbeddedWidgetComponent = (props: EmbeddedWidgetProps) => any;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.53  |  Generated: 2026-10-11T14:02:22.790Z
+Version: 2.0.55  |  Generated: 2026-10-12T20:04:55.294Z
 
 This is a concise summary of all available API functions and types.
 
@@ -154,7 +154,6 @@ The Smartlinks SDK is organized into the following namespaces:
 - **realtime** - Functions for realtime operations
 - **research** - Functions for research operations
 - **secrets** - Functions for secrets operations
-- **sequence** - Functions for sequence operations
 - **tags** - Functions for tags operations
 - **template** - Functions for template operations
 - **translations** - Functions for translations operations
@@ -9744,9 +9743,26 @@ interface SmartLinksWidgetProps {
   size?: 'compact' | 'standard' | 'large'
   lang?: string
   translations?: Record<string, string>
+  EmbeddedWidget?: EmbeddedWidgetComponent
 }
 ```
 
+**EmbeddedWidgetProps** (interface)
+```typescript
+interface EmbeddedWidgetProps {
+  appId: string
+  component?: string
+  size?: 'compact' | 'standard' | 'large'
+  widgetId?: string
+  props?: Record<string, unknown>
+  className?: string
+  fallback?: unknown
+  loading?: unknown
+}
+```
+
+**EmbeddedWidgetComponent** = `(props: EmbeddedWidgetProps) => any`
+
 ### appConfiguration (api)
 
 **AppConfigOptions** (type)
@@ -9852,26 +9868,6 @@ interface AppSecretOptions {
 }
 ```
 
-### sequence (api)
-
-**AllocateSequenceInput** (interface)
-```typescript
-interface AllocateSequenceInput {
-  appId: string
-  sequenceId: string
-  subjectId: string
-  productId?: string
-}
-```
-
-**AllocatedSequence** (interface)
-```typescript
-interface AllocatedSequence {
-  number: number
-  isNew: boolean
-}
-```
-
 ### conditions (utils)
 
 **BaseCondition** (interface)
@@ -10380,7 +10376,7 @@ Delete a keyed data item by ID within a scope. Requires admin authentication. ``
 
 **getWidgets**(collectionId: string,
     options?: GetCollectionWidgetsOptions) → `Promise<CollectionWidgetsResponse>`
-Fetches ALL widget data (manifests + bundle files) for a collection in one call. Returns everything needed to render widgets with zero additional requests. This solves N+1 query problems by fetching manifests, JavaScript bundles, and CSS files in parallel on the server. ```typescript // Fetch all widget data for a collection const { apps } = await Api.AppConfiguration.getWidgets(collectionId); // Returns: [{ appId, manifestUrl, manifest, bundleSource, bundleCss }, ...] // Convert bundle source to dynamic imports for (const app of apps) { const blob = new Blob([app.bundleSource], { type: 'application/javascript' }); const blobUrl = URL.createObjectURL(blob); const widgetModule = await import(blobUrl); // Inject CSS if present if (app.bundleCss) { const styleTag = document.createElement('style'); styleTag.textContent = app.bundleCss; document.head.appendChild(styleTag); } } // Force refresh all widgets const { apps } = await Api.AppConfiguration.getWidgets(collectionId, { force: true }); ```
+Fetches ALL widget data (manifests + bundle files) for a collection in one call. Returns everything needed to render widgets with zero additional requests. This solves N+1 query problems by fetching manifests, JavaScript bundles, and CSS files in parallel on the server. ```typescript // Fetch all widget data for a collection const { apps } = await Api.AppConfiguration.getWidgets(collectionId); // Returns: [{ appId, manifest, widget, container, admin }, ...] //   widget / container: { js: { umd?, esm? }, css?, source?, styles? } //     source / styles - the bundle inlined (when small enough); js / css - URLs otherwise. //   admin - URL of the app's app.admin.json (setup / tunable options), or null. // Bundles don't ship React: they resolve shared libraries from the HOST's globals // (host-dependency-contract.md), so loading one is a host's job. // // Inside a host (Portal / Hub), an app showing ANOTHER app's widget should not load // bundles itself - use the host-provided EmbeddedWidget prop: //   <EmbeddedWidget appId="raffle" size="standard" />   (docs/widgets.md) // Force refresh all widgets const { apps } = await Api.AppConfiguration.getWidgets(collectionId, { force: true }); ```
 
 **resolveFeature**(system: SystemBlock | undefined, flag: string) → `boolean`
 Resolve whether a feature flag is on, applying the `accountType` default: `enterprise` accounts default every flag to **on** unless `features[flag]` is explicitly `false`; `standard` accounts (or missing `accountType`) default every flag to **off** unless `features[flag]` is explicitly `true`. An explicit value always wins over the default either way. This is the same logic `isFeatureEnabled()` / `isFeatureEnabledSync()` use internally — call those instead in normal code. `system.features` and `accountType` are public data (no admin-only feature-check path exists), so there's no reason to fetch differently for an admin surface. This is exposed separately only for the rare case where you already have a `system` block in hand from somewhere other than `getAppConfig()` (e.g. server-rendered props) and want to resolve a flag from it directly. ```typescript const enabled = appConfiguration.resolveFeature(someSystemBlock, 'custom_domain'); ```
@@ -12234,11 +12230,6 @@ Soft-delete a secret. DELETE /secrets/:ref
     id: string,
     query: { limit?: number; offset?: number } = {}) → `Promise<SegmentRecipientsResponse>`
 
-### sequence
-
-**allocate**(collectionId: string, input: AllocateSequenceInput) → `Promise<AllocatedSequence>`
-Allocate (or return the existing) sequence number for a subject. Idempotent — safe to call on load (auto-enter) and on a button tap; a subject that already has a number gets it back with `isNew: false`. const { number, isNew } = await sequence.allocate(collectionId, { appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId, }) `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
-
 ### sessions
 
 **stats**(collectionId: string) → `Promise<SessionStatistics>`

package/docs/containers.md

@@ -226,6 +226,13 @@ All standard widget props apply:
 
 ---
 
+### Showing another app's widget
+
+A container can show another installed app's widget inline with the host-provided `EmbeddedWidget` prop:
+`<EmbeddedWidget appId="raffle" size="standard" />`. The host loads it, isolates it and contains any crash.
+See [widgets.md → Using another app's widget](widgets.md#using-another-apps-widget). Don't hand-roll a
+widget loader.
+
 ## Cross-App Navigation
 
 Containers support the same **structured navigation requests** as widgets. When a container needs to navigate to another app within the portal, it emits a `NavigationRequest` via the `onNavigate` callback. The portal orchestrator interprets the request, preserves hierarchy context, and performs the navigation.

package/docs/overview.md

@@ -93,7 +93,6 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Container Tracking** | `docs/container-tracking.md` | Physical/logical **item** container groupings — *not* app containers (see containers.md) |
 | **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
 | **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
-| **Sequences** | `docs/sequences.md` | RETIRING — number things in your own server function: `ctx.sl.counters` + `appRecords.claim` (server-functions.md) |
 | **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
 | **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
 | **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |

package/docs/widgets.md

@@ -146,6 +146,7 @@ interface SmartLinksWidgetProps {
 | `size` | `string?` | Size hint: 'compact', 'standard', or 'large' |
 | `lang` | `string?` | Language code (e.g., 'en', 'de', 'fr') |
 | `translations` | `object?` | Translation overrides |
+| `EmbeddedWidget` | `component?` | Host-provided: show another app's widget inside yours — see [Using another app's widget](#using-another-apps-widget) |
 
 ---
 
@@ -557,6 +558,56 @@ If `VITE_ENABLE_WIDGETS` is not set to `true`, the build produces a minimal stub
 
 ---
 
+## Using another app's widget
+
+Your container, page or widget can show **another installed app's widget** inline (a raffle entry, a
+donate button, a loyalty card), natively, with no iframe. **The host does the work.** Portal and Hub pass
+every app they mount an `EmbeddedWidget` component:
+
+```tsx
+export function EventGuide({ EmbeddedWidget, ...props }: SmartLinksContainerProps) {
+  return (
+    <section>
+      <h2>Win a signed shirt</h2>
+      {EmbeddedWidget ? (
+        <EmbeddedWidget appId="raffle" size="standard" fallback={null} />
+      ) : null}
+    </section>
+  );
+}
+```
+
+| Prop | What it does |
+|---|---|
+| `appId` | The app whose widget to show, as installed on this collection. |
+| `component` | Which of its widget components (`widgets.components[].name` in its manifest). Default: the first. |
+| `size` | `'compact' \| 'standard' \| 'large'` — a hint the widget may honour. Default `standard`. |
+| `widgetId` | A configured instance, for apps with widget instances (see [Widget Instance Resolution](#widget-instance-resolution)). |
+| `props` | Extra props for the widget: its documented props and settings. |
+| `fallback` / `loading` | What to show if it can't be shown / while it loads. Default: nothing. |
+
+What the host does for you:
+- Loads the widget through its own bundle cache: the same code that renders the portal's widgets. It
+  provides the shared libraries (React, the SDK, the router, …) and picks the component.
+- Gives it the same context you have: collection, product, proof, user, language, and navigation
+  (`onNavigate` goes straight to the portal, so the widget's links work as they do anywhere else).
+- Mounts it in **its own router**, so it never touches your routes. Don't wrap it in a router.
+- Contains any crash: a broken widget renders `fallback`, never takes down your page.
+- Renders `fallback` when the app isn't installed on this collection, exports no widget, or isn't allowed.
+
+**What can be embedded:** first-party SmartLinks widgets (app IDs without a developer handle), and your
+own publisher's apps (`acme--raffle` from `acme--events`). The host enforces this; anything else renders
+`fallback`, with a console warning. An app can't embed itself, and nesting stops two levels deep.
+
+**Don't build your own loader** (getWidgets → evaluate the bundle → shared globals → require shim). Every
+copy drifts and breaks; `EmbeddedWidget` is absent outside a host, so render nothing there.
+
+**Finding out what's available:** in Forge, `forge-widgets catalog` lists the widgets you can embed
+(apps installed on the preview's collection), and `forge-widgets describe <app>` gives a widget's
+components, sizes, props, settings and setup options.
+
+---
+
 ## Parent Integration
 
 ### Dynamic Import

package/openapi.yaml

@@ -30830,10 +30830,36 @@ components:
           type: object
           additionalProperties:
             type: string
+        EmbeddedWidget:
+          $ref: "#/components/schemas/EmbeddedWidgetComponent"
       required:
         - collectionId
         - appId
         - SL
+    EmbeddedWidgetProps:
+      type: object
+      properties:
+        appId:
+          type: string
+        component:
+          type: string
+        size:
+          type: string
+          enum:
+            - compact
+            - standard
+            - large
+        widgetId:
+          type: string
+        props:
+          type: object
+          additionalProperties: true
+        className:
+          type: string
+        fallback: {}
+        loading: {}
+      required:
+        - appId
     AppConfigOptions:
       type: object
       properties:
@@ -30932,28 +30958,3 @@ components:
       properties:
         appId:
           type: string
-    AllocateSequenceInput:
-      type: object
-      properties:
-        appId:
-          type: string
-        sequenceId:
-          type: string
-        subjectId:
-          type: string
-        productId:
-          type: string
-      required:
-        - appId
-        - sequenceId
-        - subjectId
-    AllocatedSequence:
-      type: object
-      properties:
-        number:
-          type: number
-        isNew:
-          type: boolean
-      required:
-        - number
-        - isNew

package/package.json

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

package/scripts/doctor.mjs

@@ -269,6 +269,50 @@ if (meta.respectsHostTheme) {
   }
 }
 
+// ---- showing another app's widget: use the host's EmbeddedWidget, for widgets it allows -----------
+// Hosts (Portal, Hub) pass every app an `EmbeddedWidget` prop (docs/widgets.md → "Using another app's
+// widget"). A hand-rolled loader (getWidgets → evaluate the bundle) drifts and breaks; and the host only
+// renders first-party widgets and the same publisher's apps, so anything else silently shows nothing.
+// Static scan of the source; WARN-only.
+{
+  const ownId = String(manifest.meta?.appId || '');
+  const handleOf = (id) => { const i = id.indexOf('--'); return i > 0 ? id.slice(0, i) : null; };
+  const EXT = /\.(tsx|ts|jsx|js)$/;
+  const SKIP = new Set(['node_modules', 'dist', '.git', 'public']);
+  const files = [];
+  (function walkSrc(dir) {
+    let entries = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isDirectory()) { if (!SKIP.has(e.name)) walkSrc(join(dir, e.name)); }
+      else if (EXT.test(e.name)) files.push(join(dir, e.name));
+    }
+  })(existsSync(join(appDir, 'src')) ? join(appDir, 'src') : appDir);
+  const rel = (f) => (f.startsWith(appDir) ? f.slice(appDir.length + 1) : f);
+  const handRolled = [];
+  const blocked = new Set();
+  let embeds = 0;
+  for (const f of files) {
+    const text = readFileSync(f, 'utf8');
+    if (/\bgetWidgets\s*\(/.test(text) && /(new\s+Blob\s*\(|new\s+Function\s*\(|createRequireShim|import\s*\(\s*\/\*\s*@vite-ignore)/.test(text)) handRolled.push(rel(f));
+    for (const m of text.matchAll(/<EmbeddedWidget\b[^>]*?\bappId\s*=\s*\{?\s*["'`]([A-Za-z0-9._-]+)["'`]/g)) {
+      embeds++;
+      const id = m[1];
+      const owner = handleOf(id);
+      if (id === ownId || (owner !== null && owner !== handleOf(ownId))) blocked.add(id);
+    }
+  }
+  if (handRolled.length) {
+    console.log(`${YELLOW}⚠${RESET} embedded widgets — a hand-rolled widget loader in ${handRolled.slice(0, 3).join(', ')}`);
+    warnings.push(`${handRolled.join(', ')} load${handRolled.length === 1 ? 's' : ''} another app's widget bundle by hand (getWidgets + evaluating it). Use the host's EmbeddedWidget prop instead: <EmbeddedWidget appId="…" /> (docs/widgets.md → "Using another app's widget").`);
+  }
+  if (blocked.size) {
+    console.log(`${YELLOW}⚠${RESET} embedded widgets — the host won't show: ${[...blocked].join(', ')}`);
+    warnings.push(`EmbeddedWidget for ${[...blocked].join(', ')} will render nothing: hosts only show first-party widgets and the same publisher's apps${ownId ? ` (this app is "${ownId}")` : ''}, and never the app itself.`);
+  }
+  if (embeds && !handRolled.length && !blocked.size) console.log(`${GREEN}✓${RESET} embedded widgets ${DIM}— ${embeds} via the host's EmbeddedWidget${RESET}`);
+}
+
 // ---- package.json scripts point at files that exist ------------------------------------------
 // An upgrade that copies a script LINE but not the script FILE breaks every build at that step
 // (e.g. `postbuild: node scripts/smartlinks-deploy.mjs` with no scripts/smartlinks-deploy.mjs).

package/dist/api/sequence.d.ts

@@ -1,38 +0,0 @@
-export interface AllocateSequenceInput {
-    /** The app that owns the sequence config. */
-    appId: string;
-    /** The configured sequence id — the key of data.sequenceConfigs on the app config. */
-    sequenceId: string;
-    /**
-     * The STABLE subject identity. For a `claimSet` sequence, pass the tap's virtual-proof id
-     * `<claimSetId>-<code>` (e.g. "23-oOkf8o") for a per-wristband raffle — the code is the tag's
-     * permanent id, so re-taps of the same wristband return the same number; the number is stamped
-     * on that code's doc and surfaces in `tagData`. Pass a bare claim-set id for one number per
-     * group. Never a value that changes per tap.
-     */
-    subjectId: string;
-    /** Optional product scope, when the sequence config is scoped per product. */
-    productId?: string;
-}
-export interface AllocatedSequence {
-    /** The allocated (or already-held) number. */
-    number: number;
-    /** True when this call allocated a new number; false when the subject already had one. */
-    isNew: boolean;
-}
-export declare namespace sequence {
-    /**
-     * Allocate (or return the existing) sequence number for a subject. Idempotent — safe to
-     * call on load (auto-enter) and on a button tap; a subject that already has a number gets
-     * it back with `isNew: false`.
-     *
-     * @example
-     *   const { number, isNew } = await sequence.allocate(collectionId, {
-     *     appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId,
-     *   })
-      *
-     * @deprecated Being removed. Number things in your app's own server function with
-     * `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
-     */
-    function allocate(collectionId: string, input: AllocateSequenceInput): Promise<AllocatedSequence>;
-}

package/dist/api/sequence.js

@@ -1,29 +0,0 @@
-// src/api/sequence.ts
-//
-// Sequences — allocate a guaranteed-unique, monotonic number (raffle tickets, "Nth to
-// claim", queue positions) and stamp it onto a record. The sequence (counter key, target,
-// field, scope) is configured server-side in app config (data.sequenceConfigs[sequenceId]);
-// this call supplies only the subject and is idempotent — a re-tap returns the same number.
-// See docs/sequences.md.
-import { post } from "../http.js";
-export var sequence;
-(function (sequence) {
-    const base = (collectionId) => `/public/collection/${encodeURIComponent(collectionId)}/sequence`;
-    /**
-     * Allocate (or return the existing) sequence number for a subject. Idempotent — safe to
-     * call on load (auto-enter) and on a button tap; a subject that already has a number gets
-     * it back with `isNew: false`.
-     *
-     * @example
-     *   const { number, isNew } = await sequence.allocate(collectionId, {
-     *     appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId,
-     *   })
-      *
-     * @deprecated Being removed. Number things in your app's own server function with
-     * `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
-     */
-    async function allocate(collectionId, input) {
-        return post(`${base(collectionId)}/allocate`, input);
-    }
-    sequence.allocate = allocate;
-})(sequence || (sequence = {}));

package/dist/docs/sequences.md

@@ -1,125 +0,0 @@
-# Sequences & claim-order allocation
-
-> **Retiring — don't build on this.** `SL.sequence.allocate` is being removed. Number things in your
-> app's own server function instead: `ctx.sl.counters.next()` for the next number and
-> `ctx.sl.appRecords.claim()` to key it to a tag/person and make sure no number is ever held twice —
-> see server-functions.md → "Uniqueness, numbering and people". (The counter here lived inside the
-> app config doc, where an admin save could rewind it.)
-
-> **SmartLinks SDK 2.x** (current `latest`). Install `@proveanything/smartlinks@^2`.
-
-A **sequence** hands out a guaranteed-unique, monotonic number — `1, 2, 3, …` — and stamps it
-onto a record. It's the primitive behind raffle tickets, "you're the Nth to claim", queue
-positions, and limited-edition numbering: cases where you need *the next number*, exactly
-once per subject, even with a whole room (or stadium) acting at the same instant.
-
-## The model: allocate, then stamp — and the target is the ledger
-
-Two steps, one call:
-
-1. **Allocate** — get the next number from an **atomic counter**. The counter lives inside
-   your **app-config** doc at `data.sequences.<key>`, so it's scoped exactly like your other
-   app config (per collection / product / variant / batch) and needs no dedicated storage.
-   It's incremented in a single statement, so 250 simultaneous taps each get a distinct
-   number in microseconds — never two the same.
-2. **Stamp** — write that number onto the **subject's own record** (a claim set, a proof, or
-   an app record). **That record is the ledger** — there's no separate bookkeeping table.
-   Next time you read the subject, the number is just there.
-
-Because the target is the ledger, allocation is **idempotent**: on a re-tap we read the
-subject first and return the number it already has, rather than allocating a second one.
-
-## Guarantees
-
-- **Unique + monotonic** — the counter is an atomic increment, never a read-modify-write, so
-  there are no duplicates and no lost updates under load.
-- **Idempotent per subject** — one number per subject; a re-tap returns the same number.
-- **Concurrency-safe at scale** — the only shared hot spot is the one counter row (Postgres
-  serializes it); the stamp is per-subject (its own record), so the model holds from 250 in a
-  room to 60,000 in a stadium. A concurrent double-tap on the *same* subject at worst skips
-  one number (a harmless gap) — never puts two numbers on one person.
-
-## Scoping
-
-- **Counter scope** — the app-config doc it lives on: collection-wide, or per product /
-  variant / batch. All wristbands mapped to one product? Scope the counter to that product.
-- **`key`** — a name within that doc (e.g. `raffle:2026-cup`), so one config doc can hold
-  several independent sequences.
-- **`start`** — the first number (default `1`); use it to reserve a block (start at `51` and
-  tell people it's `1`, or just filter `< N` at draw time).
-
-## Idempotency subject — use a *stable* id
-
-The number is deduped by the **subject id** you pass, so it must be the **stable** identity:
-- **Virtual-proof id `<claimSetId>-<code>`** (e.g. `23-oOkf8o`) — the right key for a
-  per-wristband raffle. The `code` is the physical tag's permanent id, so a re-tap of the same
-  wristband resolves to the same code doc → same number. The virtual proof record is transient,
-  but the **code** inside its id is stable — that's what the sink keys on (it splits the id and
-  uses only `<claimSetId>` + `<code>`).
-- **Bare claim-set id** — when one number per *group* is intended.
-- The authenticated **user/contact** — if they sign in / claim.
-
-Do **not** key on the transient part of a per-tap identity (a freshly-minted virtual proof
-record) — key on the stable **code**, which is exactly what the `<claimSetId>-<code>` subject
-carries.
-
-## Where the number is stored (the sink)
-
-The stamp target is configurable — the number lives wherever you'll read it:
-
-| Target | Subject id | Use |
-|---|---|---|
-| `claimSet` | the virtual-proof id `<claimSetId>-<code>` (e.g. `23-oOkf8o`) **or** a bare `<claimSetId>` | The Firestore claim-set world. **The subject decides the exact doc:** a `<claimSetId>-<code>` id stamps the individual **code** doc (per-wristband — rides back as `tagData` on the next tap, every wristband its own number); a bare id stamps the whole **set** doc (one shared value). Claim-set ids are hyphen-free, so a hyphen unambiguously means the per-code form. |
-| `proof` | the proof id | A minted proof (value or attestation) — when the number should travel with the proof. |
-| `appRecord` | the record id | A structured app record — for queryable, per-app data. |
-
-## Configure the sequence (once, server-side)
-
-You define the sequence **in your app config**, under `data.sequenceConfigs`. This is what
-makes the public endpoint safe: the target/field/scope are set by you, not the caller.
-
-```jsonc
-// app config: data.sequenceConfigs
-{
-  "raffle": {
-    "key":     "raffle:2026-cup",   // the named counter (data.sequences.<key>)
-    "target":  "claimSet",          // claimSet | proof | appRecord — the ledger domain
-    "field":   "raffleNumber",      // the property written on the target (comes back in tagData)
-    "start":   1                    // first number (optional, default 1)
-    // no productId → one collection-wide counter (all wristbands share the sequence)
-  }
-}
-```
-
-> **Per-wristband raffle.** Keep `target: "claimSet"` and pass the tap's virtual-proof id
-> (`<claimSetId>-<code>`) as the subject — the sink writes the individual tag's **code** doc, so
-> each wristband gets its own number and it surfaces in `tagData` on the next tap. Pass a bare
-> claim-set id instead only if you want one number for the whole group.
-
-## Call it (the widget)
-
-Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
-never the target/field:
-
-```
-POST /api/v1/public/collection/:collectionId/sequence/allocate
-{ "appId": "liveWidgets", "sequenceId": "raffle", "subjectId": "23-oOkf8o" }
-→ { "number": 42, "isNew": true }        // re-tap → { "number": 42, "isNew": false }
-```
-
-- **`subjectId`** is the STABLE identity. For `claimCode` it's the virtual-proof id
-  `<claimSetId>-<code>` (e.g. `23-oOkf8o`) straight off the tap — re-taps of the same wristband
-  collapse to one number. (For `claimSet` it's the claim-set id.)
-- **Idempotent**, so both your flows are the *same call*:
-  - **Auto:** on load, call allocate → get your number (existing or freshly minted).
-  - **Button:** click → animate → same call → "Your raffle number is 42."
-- **Refresh:** just read the `raffleNumber` field back off the claim set (or proof) — it's the
-  ledger. Or call allocate again; you'll get the same number with `isNew: false`.
-
-Errors: `404 SEQUENCE_NOT_FOUND` (not configured), `404 CLAIMSET_NOT_FOUND` (bad subject),
-`400 BAD_REQUEST` (missing fields).
-
-## Drawing the winner
-
-No separate ledger — query the claim sets (or proofs) where `raffleNumber` is set; that field
-is your entry list, in allocation order.

package/docs/sequences.md

@@ -1,125 +0,0 @@
-# Sequences & claim-order allocation
-
-> **Retiring — don't build on this.** `SL.sequence.allocate` is being removed. Number things in your
-> app's own server function instead: `ctx.sl.counters.next()` for the next number and
-> `ctx.sl.appRecords.claim()` to key it to a tag/person and make sure no number is ever held twice —
-> see server-functions.md → "Uniqueness, numbering and people". (The counter here lived inside the
-> app config doc, where an admin save could rewind it.)
-
-> **SmartLinks SDK 2.x** (current `latest`). Install `@proveanything/smartlinks@^2`.
-
-A **sequence** hands out a guaranteed-unique, monotonic number — `1, 2, 3, …` — and stamps it
-onto a record. It's the primitive behind raffle tickets, "you're the Nth to claim", queue
-positions, and limited-edition numbering: cases where you need *the next number*, exactly
-once per subject, even with a whole room (or stadium) acting at the same instant.
-
-## The model: allocate, then stamp — and the target is the ledger
-
-Two steps, one call:
-
-1. **Allocate** — get the next number from an **atomic counter**. The counter lives inside
-   your **app-config** doc at `data.sequences.<key>`, so it's scoped exactly like your other
-   app config (per collection / product / variant / batch) and needs no dedicated storage.
-   It's incremented in a single statement, so 250 simultaneous taps each get a distinct
-   number in microseconds — never two the same.
-2. **Stamp** — write that number onto the **subject's own record** (a claim set, a proof, or
-   an app record). **That record is the ledger** — there's no separate bookkeeping table.
-   Next time you read the subject, the number is just there.
-
-Because the target is the ledger, allocation is **idempotent**: on a re-tap we read the
-subject first and return the number it already has, rather than allocating a second one.
-
-## Guarantees
-
-- **Unique + monotonic** — the counter is an atomic increment, never a read-modify-write, so
-  there are no duplicates and no lost updates under load.
-- **Idempotent per subject** — one number per subject; a re-tap returns the same number.
-- **Concurrency-safe at scale** — the only shared hot spot is the one counter row (Postgres
-  serializes it); the stamp is per-subject (its own record), so the model holds from 250 in a
-  room to 60,000 in a stadium. A concurrent double-tap on the *same* subject at worst skips
-  one number (a harmless gap) — never puts two numbers on one person.
-
-## Scoping
-
-- **Counter scope** — the app-config doc it lives on: collection-wide, or per product /
-  variant / batch. All wristbands mapped to one product? Scope the counter to that product.
-- **`key`** — a name within that doc (e.g. `raffle:2026-cup`), so one config doc can hold
-  several independent sequences.
-- **`start`** — the first number (default `1`); use it to reserve a block (start at `51` and
-  tell people it's `1`, or just filter `< N` at draw time).
-
-## Idempotency subject — use a *stable* id
-
-The number is deduped by the **subject id** you pass, so it must be the **stable** identity:
-- **Virtual-proof id `<claimSetId>-<code>`** (e.g. `23-oOkf8o`) — the right key for a
-  per-wristband raffle. The `code` is the physical tag's permanent id, so a re-tap of the same
-  wristband resolves to the same code doc → same number. The virtual proof record is transient,
-  but the **code** inside its id is stable — that's what the sink keys on (it splits the id and
-  uses only `<claimSetId>` + `<code>`).
-- **Bare claim-set id** — when one number per *group* is intended.
-- The authenticated **user/contact** — if they sign in / claim.
-
-Do **not** key on the transient part of a per-tap identity (a freshly-minted virtual proof
-record) — key on the stable **code**, which is exactly what the `<claimSetId>-<code>` subject
-carries.
-
-## Where the number is stored (the sink)
-
-The stamp target is configurable — the number lives wherever you'll read it:
-
-| Target | Subject id | Use |
-|---|---|---|
-| `claimSet` | the virtual-proof id `<claimSetId>-<code>` (e.g. `23-oOkf8o`) **or** a bare `<claimSetId>` | The Firestore claim-set world. **The subject decides the exact doc:** a `<claimSetId>-<code>` id stamps the individual **code** doc (per-wristband — rides back as `tagData` on the next tap, every wristband its own number); a bare id stamps the whole **set** doc (one shared value). Claim-set ids are hyphen-free, so a hyphen unambiguously means the per-code form. |
-| `proof` | the proof id | A minted proof (value or attestation) — when the number should travel with the proof. |
-| `appRecord` | the record id | A structured app record — for queryable, per-app data. |
-
-## Configure the sequence (once, server-side)
-
-You define the sequence **in your app config**, under `data.sequenceConfigs`. This is what
-makes the public endpoint safe: the target/field/scope are set by you, not the caller.
-
-```jsonc
-// app config: data.sequenceConfigs
-{
-  "raffle": {
-    "key":     "raffle:2026-cup",   // the named counter (data.sequences.<key>)
-    "target":  "claimSet",          // claimSet | proof | appRecord — the ledger domain
-    "field":   "raffleNumber",      // the property written on the target (comes back in tagData)
-    "start":   1                    // first number (optional, default 1)
-    // no productId → one collection-wide counter (all wristbands share the sequence)
-  }
-}
-```
-
-> **Per-wristband raffle.** Keep `target: "claimSet"` and pass the tap's virtual-proof id
-> (`<claimSetId>-<code>`) as the subject — the sink writes the individual tag's **code** doc, so
-> each wristband gets its own number and it surfaces in `tagData` on the next tap. Pass a bare
-> claim-set id instead only if you want one number for the whole group.
-
-## Call it (the widget)
-
-Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
-never the target/field:
-
-```
-POST /api/v1/public/collection/:collectionId/sequence/allocate
-{ "appId": "liveWidgets", "sequenceId": "raffle", "subjectId": "23-oOkf8o" }
-→ { "number": 42, "isNew": true }        // re-tap → { "number": 42, "isNew": false }
-```
-
-- **`subjectId`** is the STABLE identity. For `claimCode` it's the virtual-proof id
-  `<claimSetId>-<code>` (e.g. `23-oOkf8o`) straight off the tap — re-taps of the same wristband
-  collapse to one number. (For `claimSet` it's the claim-set id.)
-- **Idempotent**, so both your flows are the *same call*:
-  - **Auto:** on load, call allocate → get your number (existing or freshly minted).
-  - **Button:** click → animate → same call → "Your raffle number is 42."
-- **Refresh:** just read the `raffleNumber` field back off the claim set (or proof) — it's the
-  ledger. Or call allocate again; you'll get the same number with `isNew: false`.
-
-Errors: `404 SEQUENCE_NOT_FOUND` (not configured), `404 CLAIMSET_NOT_FOUND` (bad subject),
-`400 BAD_REQUEST` (missing fields).
-
-## Drawing the winner
-
-No separate ledger — query the claim sets (or proofs) where `raffleNumber` is set; that field
-is your entry list, in allocation order.