@proveanything/smartlinks 2.0.52 → 2.0.54

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/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.52  |  Generated: 2026-10-11T13:21:58.062Z
+Version: 2.0.54  |  Generated: 2026-10-12T17:51:26.609Z
 
 This is a concise summary of all available API functions and types.
 
@@ -9744,9 +9744,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)
@@ -10380,7 +10397,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'); ```

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/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:

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.52  |  Generated: 2026-10-11T13:21:58.062Z
+Version: 2.0.54  |  Generated: 2026-10-12T17:51:26.609Z
 
 This is a concise summary of all available API functions and types.
 
@@ -9744,9 +9744,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)
@@ -10380,7 +10397,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'); ```

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/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:

package/package.json

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

package/scripts/doctor.mjs

@@ -262,13 +262,57 @@ if (meta.respectsHostTheme) {
     const text = readFileSync(bp, 'utf8');
     const routers = ['MemoryRouter', 'HashRouter', 'BrowserRouter'].filter((r) => new RegExp(`\\b${r}\\b`).test(text));
     if (!routers.length) { console.log(`${GREEN}✓${RESET} containers ${DIM}— no router of their own (the host's is used)${RESET}`); break; }
-    if (/UNSAFE_LocationContext/.test(text)) { console.log(`${GREEN}✓${RESET} containers ${DIM}— own ${routers.join('/')} isolated from the host's router${RESET}`); break; }
+    if (/\bUNSAFE_LocationContext\b/.test(text)) { console.log(`${GREEN}✓${RESET} containers ${DIM}— own ${routers.join('/')} isolated from the host's router${RESET}`); break; }
     console.log(`${YELLOW}⚠${RESET} containers — ${routers.join('/')} without isolating it from the host's router`);
     warnings.push(`containers bundle renders its own ${routers.join('/')} but never resets the host's router context — inside an R5 host that throws "You cannot render a <Router> inside another <Router>". Wrap it in UNSAFE_LocationContext.Provider + UNSAFE_NavigationContext.Provider value={null} (docs/containers.md), or drop the router and use the host's.`);
     break;
   }
 }
 
+// ---- 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).