@proveanything/smartlinks 2.0.6 → 2.0.10

package/dist/shared-dependencies.js

@@ -0,0 +1,79 @@
+// src/shared-dependencies.ts
+// -----------------------------------------------------------------------------
+// The host↔app SHARED DEPENDENCY CONTRACT — the single source of truth for which
+// libraries the R5 portal (host) provides as singletons, so apps externalize them
+// instead of bundling their own copy.
+//
+// The host publishes these to modern (ESM) apps via a versioned import map, and to
+// legacy (UMD) apps via window globals. Both hosts and app authors should read THIS
+// list rather than hard-coding their own — a mismatch is what causes duplicate-React
+// crashes and silent blank containers.
+//
+// See docs/host-dependency-contract.md.
+/** Current contract revision. Bumped when the entry list or host versions change. */
+export const SHARED_DEPENDENCY_CONTRACT_VERSION = 'v5';
+/**
+ * Canonical import-map path for a specifier: drop the leading `@` scope marker and
+ * turn every `/` into `-`.
+ *   'react-dom/client'      -> '/sl-shared/v5/react-dom-client.js'
+ *   '@radix-ui/react-slot'  -> '/sl-shared/v5/radix-ui-react-slot.js'
+ * Hosts MUST serve shims at these paths so the map the SDK advertises resolves.
+ */
+export function importMapPathFor(specifier, version = SHARED_DEPENDENCY_CONTRACT_VERSION) {
+    const slug = specifier.replace(/^@/, '').replace(/\//g, '-');
+    return `/sl-shared/${version}/${slug}.js`;
+}
+// The 25-entry v5 contract: the historical 23 plus `react-dom/client` and
+// `react/jsx-dev-runtime`. minVersion follows the R5 host baseline (React 19,
+// Router 7.18.4 security floor, LiquidJS 10.27+, current Radix majors).
+const CONTRACT = [
+    { specifier: 'react', globalName: 'React', minVersion: '19.0.0' },
+    { specifier: 'react-dom', globalName: 'ReactDOM', minVersion: '19.0.0' },
+    { specifier: 'react-dom/client', globalName: 'ReactDOMClient', minVersion: '19.0.0' },
+    { specifier: 'react/jsx-runtime', globalName: 'jsxRuntime', minVersion: '19.0.0' },
+    { specifier: 'react/jsx-dev-runtime', globalName: 'jsxDevRuntime', minVersion: '19.0.0' },
+    { specifier: '@proveanything/smartlinks', globalName: 'SL', minVersion: '2.0.0' },
+    { specifier: '@proveanything/smartlinks-auth-ui', globalName: 'SmartlinksAuthUI', minVersion: '2.0.0' },
+    { specifier: 'react-router-dom', globalName: 'ReactRouterDOM', minVersion: '7.18.4' },
+    { specifier: '@tanstack/react-query', globalName: 'ReactQuery', minVersion: '5.0.0' },
+    { specifier: 'lucide-react', globalName: 'LucideReact', minVersion: '1.0.0' },
+    { specifier: 'date-fns', globalName: 'dateFns', minVersion: '4.0.0' },
+    { specifier: 'liquidjs', globalName: 'LiquidJS', minVersion: '10.27.0' },
+    { specifier: 'class-variance-authority', globalName: 'CVA', minVersion: '0.7.0' },
+    { specifier: '@radix-ui/react-slot', globalName: 'RadixSlot', minVersion: '1.2.0' },
+    { specifier: '@radix-ui/react-dialog', globalName: 'RadixDialog', minVersion: '1.1.0' },
+    { specifier: '@radix-ui/react-popover', globalName: 'RadixPopover', minVersion: '1.1.0' },
+    { specifier: '@radix-ui/react-tooltip', globalName: 'RadixTooltip', minVersion: '1.2.0' },
+    { specifier: '@radix-ui/react-tabs', globalName: 'RadixTabs', minVersion: '1.1.0' },
+    { specifier: '@radix-ui/react-accordion', globalName: 'RadixAccordion', minVersion: '1.2.0' },
+    { specifier: '@radix-ui/react-select', globalName: 'RadixSelect', minVersion: '2.3.0' },
+    { specifier: '@radix-ui/react-scroll-area', globalName: 'RadixScrollArea', minVersion: '1.2.0' },
+    { specifier: '@radix-ui/react-label', globalName: 'RadixLabel', minVersion: '2.1.0' },
+    { specifier: '@radix-ui/react-toast', globalName: 'RadixToast', minVersion: '1.2.0' },
+    { specifier: '@radix-ui/react-progress', globalName: 'RadixProgress', minVersion: '1.1.0' },
+    { specifier: '@radix-ui/react-avatar', globalName: 'RadixAvatar', minVersion: '1.1.0' },
+];
+/** The full shared-dependency contract for {@link SHARED_DEPENDENCY_CONTRACT_VERSION}. */
+export const SHARED_DEPENDENCIES = CONTRACT.map((d) => (Object.assign(Object.assign({}, d), { importMapPath: importMapPathFor(d.specifier) })));
+/** Just the bare specifiers — handy for a bundler `external` list. */
+export const SHARED_DEPENDENCY_SPECIFIERS = SHARED_DEPENDENCIES.map((d) => d.specifier);
+/**
+ * Read the shared-dependency contract the current host advertises at runtime
+ * (via `window.__SMARTLINKS_SHARED__`). Returns `null` when there is no host
+ * marker — e.g. an older portal, or the bundle running outside a portal — so an
+ * app can degrade gracefully or fail with an actionable message instead of a
+ * bare-specifier resolution crash.
+ */
+export function getHostSharedDependencies() {
+    const g = globalThis;
+    const marker = g.__SMARTLINKS_SHARED__;
+    if (!marker || typeof marker !== 'object')
+        return null;
+    const version = typeof marker.version === 'string' ? marker.version : null;
+    const specifiers = Array.isArray(marker.specifiers)
+        ? marker.specifiers.filter((s) => typeof s === 'string')
+        : null;
+    if (!version || !specifiers)
+        return null;
+    return { version, specifiers };
+}

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import type { AppFunctionDef, ServerFunctionContext } from '../types/appManifest';
+import type { AppFunctionDef, ServerFunctionContext } from '../types/appManifest.js';
 export declare class CapabilityError extends Error {
     capability: string;
     code: string;

package/dist/translationCache.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedTranslationItem, TranslationContext, TranslationHashOptions } from './types/translations';
+import type { ResolvedTranslationItem, TranslationContext, TranslationHashOptions } from './types/translations.js';
 interface LocalTranslationCacheEntry {
     collectionId: string;
     sourceLanguage: string;

package/dist/types/appManifest.d.ts

@@ -405,6 +405,29 @@ export interface AppManifest {
         version: string;
         platformRevision?: string;
         appId: string;
+        /**
+         * How this app's bundles are packaged, so the host knows how to load them:
+         * - `"umd"` (default when absent) — host loads the UMD bundle (`files.js.umd`)
+         *   via the CommonJS `require` shim, resolving shared deps from window globals.
+         *   Every existing app keeps working with no change.
+         * - `"dual"` — host prefers the ESM bundle (`files.js.esm`) when it has an import
+         *   map for the declared `sharedDependencies` contract; falls back to UMD otherwise.
+         * - `"esm"` — host loads ESM natively; if it has no matching import map it fails
+         *   with an actionable error rather than a bare-specifier resolution crash.
+         */
+        moduleFormat?: 'umd' | 'esm' | 'dual';
+        /**
+         * Shared-dependency contract version this bundle was built against, e.g. `"v5"`
+         * (see `SHARED_DEPENDENCY_CONTRACT_VERSION`). The host uses it to select a
+         * compatible import map for the ESM load path.
+         */
+        sharedDependencies?: string;
+        /**
+         * Per-app namespaced UMD globals (R4.7+), e.g. `{ widgets: "MyAppWidgets" }`.
+         * UMD-only: ESM bundles expose their exports through the module namespace and
+         * don't need this. Absent → legacy bundle (colliding `window.SmartLinks{Surface}`).
+         */
+        globals?: Record<string, string>;
         /**
          * SEO configuration for this app.
          * `priority` controls which app's singular fields (title, description, ogImage) win

package/dist/types/broadcasts.d.ts

@@ -44,7 +44,7 @@ export interface BroadcastList {
     offset: number;
 }
 export interface BroadcastRecipientsResponse {
-    items: import('./comms').Recipient[];
+    items: import('./comms.js').Recipient[];
     total: number;
     limit: number;
     offset: number;

package/dist/types/collection.d.ts

@@ -1,5 +1,5 @@
-import { AssetRef } from "./asset";
-import type { AppConfigSettings } from "./appConfiguration";
+import { AssetRef } from "./asset.js";
+import type { AppConfigSettings } from "./appConfiguration.js";
 /**
  * Represents a Collection object.
  */

package/dist/types/comms.d.ts

@@ -1,5 +1,5 @@
-import type { IdField } from './common';
-import type { BroadcastChannel } from './broadcasts';
+import type { IdField } from './common.js';
+import type { BroadcastChannel } from './broadcasts.js';
 /**
  * Target subject for notifications (product, collection, etc.)
  */
@@ -93,7 +93,7 @@ export interface AppendBulkResult {
     success: true;
     count: number;
 }
-export type Recipient = import('./contact').Contact;
+export type Recipient = import('./contact.js').Contact;
 export interface RecipientsPage {
     items: Recipient[];
     total: number;
@@ -181,7 +181,7 @@ export interface UnsubscribeResponse {
     };
 }
 export type ConsentChannels = Partial<Record<BroadcastChannel, boolean>>;
-type SubjectType = import('./contact').SubjectType;
+type SubjectType = import('./contact.js').SubjectType;
 export interface CommsConsentUpsertRequest {
     contactId: string;
     channels?: ConsentChannels;
@@ -229,7 +229,7 @@ export interface CommsListMethodsQuery {
 }
 export interface CommsListMethodsResponse {
     ok: true;
-    methods: import('./contact').CommMethod[];
+    methods: import('./contact.js').CommMethod[];
 }
 export interface RegisterEmailMethodRequest {
     contactId?: string;

package/dist/types/contact.d.ts

@@ -103,7 +103,7 @@ export interface PublicUpdateMyContactResponse {
     ok: boolean;
     contact: ContactPublic;
 }
-export type ChannelName = import('./broadcasts').BroadcastChannel;
+export type ChannelName = import('./broadcasts.js').BroadcastChannel;
 export type SubjectType = 'product' | 'proof' | 'batch';
 /** Registered delivery method for a contact */
 export interface CommMethodMeta {

package/dist/types/facets.d.ts

@@ -1,4 +1,4 @@
-import type { JsonValue, ProductQueryRequest } from "./product";
+import type { JsonValue, ProductQueryRequest } from "./product.js";
 export interface FacetDefinition {
     id?: string;
     orgId?: string;

package/dist/types/iframeResponder.d.ts

@@ -1,6 +1,6 @@
-export type { AuthKitUser } from './authKit';
-export type { AppConfig as CollectionApp } from './collection';
-import type { AppConfig } from './collection';
+export type { AuthKitUser } from './authKit.js';
+export type { AppConfig as CollectionApp } from './collection.js';
+import type { AppConfig } from './collection.js';
 export interface CachedData {
     collection?: Record<string, any>;
     product?: Record<string, any>;

package/dist/types/index.d.ts

@@ -1,44 +1,44 @@
-export * from "./collection";
-export * from "./facets";
-export * from "./product";
-export * from "./proof";
-export * from "./appConfiguration";
-export * from "./error";
-export * from "./asset";
-export * from "./batch";
-export * from "./variant";
-export * from "./claimSet";
-export * from "./auth";
-export * from "./comms";
-export * from "./nfc";
-export * from "./itemContext";
-export * from "./contact";
-export * from "./broadcasts";
-export * from "./segments";
-export * from "./common";
-export * from "./journeys";
-export * from "./journeysAnalytics";
-export * from "./qr";
-export * from "./template";
-export * from "./interaction";
-export * from "./analytics";
-export * from "./location";
-export * from "./jobs";
-export * from "./realtime";
-export * from "./tags";
-export * from "./navigation";
-export * from "./order";
-export * from "./crate";
-export * from "./attestations";
-export * from "./containers";
-export * from "./authKit";
-export * from "./iframeResponder";
-export * from "./ai";
-export * from "./appManifest";
-export * from "./appObjects";
-export * from "./loyalty";
-export * from "./translations";
-export * from "./integrations";
-export * from "./research";
-export * from "./config";
-export * from "./widgets";
+export * from "./collection.js";
+export * from "./facets.js";
+export * from "./product.js";
+export * from "./proof.js";
+export * from "./appConfiguration.js";
+export * from "./error.js";
+export * from "./asset.js";
+export * from "./batch.js";
+export * from "./variant.js";
+export * from "./claimSet.js";
+export * from "./auth.js";
+export * from "./comms.js";
+export * from "./nfc.js";
+export * from "./itemContext.js";
+export * from "./contact.js";
+export * from "./broadcasts.js";
+export * from "./segments.js";
+export * from "./common.js";
+export * from "./journeys.js";
+export * from "./journeysAnalytics.js";
+export * from "./qr.js";
+export * from "./template.js";
+export * from "./interaction.js";
+export * from "./analytics.js";
+export * from "./location.js";
+export * from "./jobs.js";
+export * from "./realtime.js";
+export * from "./tags.js";
+export * from "./navigation.js";
+export * from "./order.js";
+export * from "./crate.js";
+export * from "./attestations.js";
+export * from "./containers.js";
+export * from "./authKit.js";
+export * from "./iframeResponder.js";
+export * from "./ai.js";
+export * from "./appManifest.js";
+export * from "./appObjects.js";
+export * from "./loyalty.js";
+export * from "./translations.js";
+export * from "./integrations.js";
+export * from "./research.js";
+export * from "./config.js";
+export * from "./widgets.js";

package/dist/types/index.js

@@ -1,46 +1,46 @@
 // src/types/index.ts
 // Re-export all type modules so consumers can import types directly
-export * from "./collection";
-export * from "./facets";
-export * from "./product";
-export * from "./proof";
-export * from "./appConfiguration";
-export * from "./error";
-export * from "./asset";
-export * from "./batch";
-export * from "./variant";
-export * from "./claimSet";
-export * from "./auth";
-export * from "./comms";
-export * from "./nfc";
-export * from "./itemContext";
-export * from "./contact";
-export * from "./broadcasts";
-export * from "./segments";
-export * from "./common";
-export * from "./journeys";
-export * from "./journeysAnalytics";
-export * from "./qr";
-export * from "./template";
-export * from "./interaction";
-export * from "./analytics";
-export * from "./location";
-export * from "./jobs";
-export * from "./realtime";
-export * from "./tags";
-export * from "./navigation";
-export * from "./order";
-export * from "./crate";
-export * from "./attestations";
-export * from "./containers";
-export * from "./authKit";
-export * from "./iframeResponder";
-export * from "./ai";
-export * from "./appManifest";
-export * from "./appObjects";
-export * from "./loyalty";
-export * from "./translations";
-export * from "./integrations";
-export * from "./research";
-export * from "./config";
-export * from "./widgets";
+export * from "./collection.js";
+export * from "./facets.js";
+export * from "./product.js";
+export * from "./proof.js";
+export * from "./appConfiguration.js";
+export * from "./error.js";
+export * from "./asset.js";
+export * from "./batch.js";
+export * from "./variant.js";
+export * from "./claimSet.js";
+export * from "./auth.js";
+export * from "./comms.js";
+export * from "./nfc.js";
+export * from "./itemContext.js";
+export * from "./contact.js";
+export * from "./broadcasts.js";
+export * from "./segments.js";
+export * from "./common.js";
+export * from "./journeys.js";
+export * from "./journeysAnalytics.js";
+export * from "./qr.js";
+export * from "./template.js";
+export * from "./interaction.js";
+export * from "./analytics.js";
+export * from "./location.js";
+export * from "./jobs.js";
+export * from "./realtime.js";
+export * from "./tags.js";
+export * from "./navigation.js";
+export * from "./order.js";
+export * from "./crate.js";
+export * from "./attestations.js";
+export * from "./containers.js";
+export * from "./authKit.js";
+export * from "./iframeResponder.js";
+export * from "./ai.js";
+export * from "./appManifest.js";
+export * from "./appObjects.js";
+export * from "./loyalty.js";
+export * from "./translations.js";
+export * from "./integrations.js";
+export * from "./research.js";
+export * from "./config.js";
+export * from "./widgets.js";

package/dist/types/interaction.d.ts

@@ -1,4 +1,4 @@
-import type { IdField } from './common';
+import type { IdField } from './common.js';
 export interface AdminInteractionsQueryRequest {
     userId?: string;
     contactId?: string;

package/dist/types/itemContext.d.ts

@@ -1,4 +1,4 @@
-import type { TagContext } from './nfc';
+import type { TagContext } from './nfc.js';
 /**
  * Authenticity status for a specific item — a proof, resolved via an NFC
  * tap or a serial proof URL. Collection- and product-only URLs have no

package/dist/types/journeysAnalytics.d.ts

@@ -1,4 +1,4 @@
-import type { IdField } from './common';
+import type { IdField } from './common.js';
 export interface JourneyStatsRequest {
     idField?: IdField;
     from?: string;

package/dist/types/navigation.d.ts

@@ -1,4 +1,4 @@
-import type { CollectionAnalyticsEvent } from './analytics';
+import type { CollectionAnalyticsEvent } from './analytics.js';
 /** Where the link opens once resolved. */
 export type LinkOpenTarget = '_self' | '_blank';
 /**

package/dist/types/product.d.ts

@@ -1,4 +1,4 @@
-import { AssetRef } from "./asset";
+import { AssetRef } from "./asset.js";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | {
     [key: string]: JsonValue;

package/dist/types/proof.d.ts

@@ -1,4 +1,4 @@
-import { JsonValue, ScopedFieldDef } from './product';
+import { JsonValue, ScopedFieldDef } from './product.js';
 /**
  * `proof.values` — the owner + business-writable bag.
  * Public keys sit at the root (business + current owner can write, everyone

package/dist/types/segments.d.ts

@@ -95,7 +95,7 @@ export interface SegmentCalculateResult {
     note?: string;
 }
 export interface SegmentRecipientsResponse {
-    items: import('./comms').Recipient[];
+    items: import('./comms.js').Recipient[];
     limit: number;
     offset: number;
     total: number;

package/dist/types/widgets.d.ts

@@ -1,5 +1,5 @@
-import type { TagContext } from './nfc';
-import type { ItemContext } from './itemContext';
+import type { TagContext } from './nfc.js';
+import type { ItemContext } from './itemContext.js';
 /**
  * Structured navigation request emitted via the `onNavigate` prop when a
  * widget or container needs to navigate the parent platform shell to another

package/dist/utils/conditions.d.ts

@@ -1,4 +1,4 @@
-import type { ItemContext } from '../types/itemContext';
+import type { ItemContext } from '../types/itemContext.js';
 /**
  * Geographic region definitions for country-based conditions
  */

package/dist/utils/index.d.ts

@@ -2,6 +2,6 @@
  * Utility functions and helpers for working with smartlinks data.
  * @module utils
  */
-export * from './paths';
-export * from './conditions';
-export * from './anonId';
+export * from './paths.js';
+export * from './conditions.js';
+export * from './anonId.js';

package/dist/utils/index.js

@@ -3,6 +3,6 @@
  * Utility functions and helpers for working with smartlinks data.
  * @module utils
  */
-export * from './paths';
-export * from './conditions';
-export * from './anonId';
+export * from './paths.js';
+export * from './conditions.js';
+export * from './anonId.js';

package/dist/utils/paths.d.ts

@@ -1,7 +1,7 @@
-import type { Product } from '../types/product';
-import type { Collection } from '../types/collection';
-import type { BatchResponse } from '../types/batch';
-import type { Proof } from '../types/proof';
+import type { Product } from '../types/product.js';
+import type { Collection } from '../types/collection.js';
+import type { BatchResponse } from '../types/batch.js';
+import type { Proof } from '../types/proof.js';
 /**
  * Parameters for building a portal path.
  * Pass in objects where available - the function will extract the needed properties.

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.6  |  Generated: 2026-09-21T12:54:07.123Z
+Version: 2.0.10  |  Generated: 2026-09-21T16:50:28.412Z
 
 This is a concise summary of all available API functions and types.
 
@@ -17,15 +17,13 @@ For detailed guides on specific features:
 - **[Containers](containers.md)** - Building full-app embeddable containers (lazy-loaded)
 - **[Mobile Admin Container](mobile-admin-container.md)** - Building mobile-optimised operator/admin containers as a separate bundle
 - **[Container Tracking](container-tracking.md)** - Hierarchical physical/logical container groupings with item membership
-- **[Scanner Containers](scanner-container.md)** - Building scanner microapps for the SmartLinks Scanner Android host (RFID, NFC, QR, key events)
 - **[Multi-Page App Architecture](mpa.md)** - Vite MPA build pipeline: public/admin entry points, widget/container/executor bundles, content-hashed CDN assets
 - **[App Configuration Files](app-manifest.md)** - `app.manifest.json` and `app.admin.json` reference — bundles, components, setup questions, import schemas, tunable fields, and metrics
 - **[Executor Model](executor.md)** - Programmatic JS bundles for AI-driven setup, server-side SEO metadata generation, and LLM content for AI crawlers
 - **[Server Functions](server-functions.md)** - App-authored server-side "edge functions" (`async (ctx, event) => result`): http/event/cron triggers, the visibility/authority/capabilities security model, and the pre-scoped `ctx` (authority-scoped SDK, capability-gated secrets + fetch)
 - **[Deploying & Registering an App](deploying-apps.md)** - Publish → build → register: the app CDN layout (smartlinks.app), dev/beta/prod channels, channel-scoped deploy keys, the `POST /apps/:appId/releases` registration endpoint + validation, and how to wire it into your build so a bad manifest fails the deploy
 - **[Realtime](realtime.md)** - Real-time data updates and WebSocket connections
-- **[iframe Responder](iframe-responder.md)** - iframe integration and cross-origin communication
-- **[iframe Streaming Parent Changes](iframe-streaming-parent-changes.md)** - Parent-side changes required to support AI streaming in iframe proxy mode
+- **[iframe Responder](iframe-responder.md)** - iframe integration and cross-origin communication (incl. hand-rolled streaming protocol)
 - **[Utilities](utils.md)** - Helper functions for building portal paths, URLs, and common tasks
 - **[UI Utils](ui-utils.md)** - Reusable, themeable admin UI React component library for microapps
 - **[Caching](caching.md)** - Multi-tier caching strategy (in-memory, SessionStorage, IndexedDB) used by the SDK
@@ -63,7 +61,6 @@ For detailed guides on specific features:
 - **[Integrations](integrations.md)** - Inbound/outbound integration flows + the sealed-secret store; triggers (manual/event/schedule), field mappings, and the Syndigo/Event Hub outbound path
 - **[AI Tools & Skills](ai-tools-and-skills.md)** - The AI capability catalog: skills apps invoke by name (e.g. research.brand), the tools the AI reaches for (web fetch/screenshot/brand assets/image gen), the agent loop, and how apps discover them
 - **[Deep Link Discovery](deep-link-discovery.md)** - Registering and discovering navigable app states for portal menus and AI orchestration
-- **[AI-Native App Manifests](manifests.md)** - How AI workflows discover, configure, and import apps via structured manifests and prose guides
 - **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
 
 ## Choosing App Storage
@@ -220,8 +217,8 @@ Returns true if the SDK currently has any auth credential set (bearer token or A
 }) → `void`
 Configure the SDK's built-in in-memory GET cache. The cache is transparent — it sits inside the HTTP layer and requires no changes to your existing API calls. All GET requests benefit automatically. Per-resource rules (collections/products → 1 h, proofs → 30 s, etc.) override this value. in-memory only (`'none'`, default). Ignored in Node.js. fallback, from the original fetch time (default: 7 days). `SmartlinksOfflineError` with stale data instead of propagating the network error. caches on page load/refresh. IndexedDB persists for offline. ```ts // Enable IndexedDB persistence for offline support configureSdkCache({ persistence: 'indexeddb' }) // Disable cache entirely in test environments configureSdkCache({ enabled: false }) // Keep caches across page refreshes (not recommended for production) configureSdkCache({ clearOnPageLoad: false }) ```
 
-**invalidateCache**(urlPattern?: string) → `void`
-Manually invalidate entries in the SDK's GET cache. *contains* this string is removed. Omit (or pass `undefined`) to wipe the entire cache. ```ts invalidateCache()                     // clear everything invalidateCache('/collection/abc123') // one specific collection invalidateCache('/product/')          // all legacy singular product responses invalidateCache('/products/')         // all canonical plural product responses ```
+**invalidateCache**(urlPattern?: string, options?: InvalidateCacheOptions) → `void`
+Manually invalidate entries in the SDK's GET cache. Note: the GET cache is **in-memory, per page load** (with an optional L2 IndexedDB layer when persistence is enabled) — it does not persist across reloads unless you opt into persistence, so it rarely needs disabling "for correctness". *contains* this string is removed). With `{ exact: true }`, matches the path precisely. Omit to wipe the entire cache. ```ts invalidateCache()                                  // clear everything invalidateCache('/collection/abc123')              // that collection AND everything under it invalidateCache('/collection/abc123', { exact: true }) // ONLY that collection entry invalidateCache('/products/')                      // all canonical plural product responses ```
 
 **proxyUploadFormData**(path: string,
   formData: FormData,
@@ -1841,6 +1838,9 @@ interface AppManifest {
   version: string;
   platformRevision?: string;
   appId: string;
+  moduleFormat?: 'umd' | 'esm' | 'dual';
+  sharedDependencies?: string;
+  globals?: Record<string, string>;
   seo?: {
   strategy?: 'executor' | string;
   priority?: number;

package/docs/agent-tools.md

@@ -81,12 +81,21 @@ Identical to server functions — nothing new to reason about:
 Untrusted third-party tools run in the platform's isolated runner — the same boundary as untrusted
 server functions.
 
-## Replacing `app.admin.json` AI setup
+## Working with `app.admin.json` (complement, not replacement)
 
-This supersedes the `app.admin.json` "AI setup" schema-extraction model (the outer agent reading a
-schema and handing back JSON blobs). Instead the app owns its domain logic and exposes **real,
-capability-scoped actions** the agent invokes — with multi-turn and streaming. The AI-schema path is
-**deprecated as of V2** (still works through the V2 line; removed later).
+`app.admin.json` stays the **canonical declarative config contract** — setup questions, config schema,
+import fields, tunable settings, content hints. It's inspectable, validatable, deterministic, and
+reused by many consumers at once (the admin form renderer, AI setup, a signup journey asking the same
+questions, bulk import). Agent tools **do not replace it — they serve and adapt it**:
+
+- Keep the declarative schema as the default and source of truth.
+- When you want *dynamic, contextual* behaviour — "which questions for **this** collection?", "the
+  config schema as it stands right now", "apply these answers" — expose a small function/tool that
+  reads the declaration and returns a tailored result. **Static-first; dynamic only where it earns its
+  keep.**
+
+There's no rip-and-replace and nothing to migrate off: an app happy with its `app.admin.json` keeps
+it untouched.
 
 ## What ships now vs staged
 
@@ -96,16 +105,19 @@ capability-scoped actions** the agent invokes — with multi-turn and streaming.
 | SDK types for it; tool descriptors surfaced for discovery | `tools/call` streaming, cancellation, cross-app toolbelt arbitration |
 | Your handlers run today via http/event | Human-approval UX for `approval: "require"` |
 
-## Adopting this in an existing app
+## Adopting this — opt-in, per app, no fleet migration
+
+Agent tools are **purely additive**. There is **no migration pass**, and nothing breaks if you never
+adopt them — an existing app on the V2 SDK simply *gains the ability* to add them whenever you want.
+You do **not** touch every app; you turn it on for one app at a time.
 
-Do it in order — each step is a drop-in migration prompt (see the migration steps that ship with the
-SDK). Roughly:
+To turn them on for a single app (say, an FAQ app), once it's on the V2 SDK:
 
-1. **Server functions** — add the `functions` block + build target + test harness (if the app
-   doesn't have them). See [server-functions.md](server-functions.md).
+1. **Server functions** — add the `functions` block + build target + test harness if the app doesn't
+   already have them. See [server-functions.md](server-functions.md).
 2. **Expose tools** — add the `agent` block to the functions you want the agent to call; give each a
-   title/description/input schema and an approval mode.
-3. **Retire `app.admin.json` AI setup** — move any AI-authoring behaviour to tools; drop the
-   AI-schema block.
+   title / description / input schema and an approval mode.
 
-Steps 1–2 are safe to ship now; step 3 as you migrate each app off the old AI path.
+That's it — declare and build. The live agent loop is staged (see the table above); until it ships,
+your handlers still run via http/event, so declaring tools now is **forward-compatible, not
+speculative breakage**. `app.admin.json` stays as-is throughout — nothing to retire.