@salesforce/vite-plugin-lwc-ui-bundle 11.13.1 → 11.14.0

package/docs/consumer-guide.md

@@ -259,6 +259,21 @@ export default defineConfig({
 });
 ```
 
+**What is the `providers` array?** It is the list of resolvers for `@salesforce/*`
+scoped-module imports (`@salesforce/label/*`, `@salesforce/i18n/*`,
+`@salesforce/userPermission/*`, `@salesforce/gate/*`, …) that don't exist as
+real npm packages. Each `builtins.*()` returns a Vite plugin that intercepts one
+family of specifiers and generates the module the platform LWC compiler would
+otherwise provide.
+
+**You usually don't need it.** When you **omit** `providers` entirely, the plugin
+installs a default set that resolves labels, i18n, permissions, and access checks
+at runtime via GraphQL (see [GraphQL-backed scoped modules](#graphql-backed-scoped-modules-default)
+below). Pass `providers` only to opt a family **out** of the runtime fetch (e.g.
+`builtins.i18n()` for browser/`Intl`-derived locale identity, `builtins.label()`
+for static build-time labels) or to add extra config — the explicit list above
+shows the opt-out shape, not a required one.
+
 #### Component Directory Configuration
 
 The plugin supports two directory structures:
@@ -298,8 +313,22 @@ Components are importable as `myNamespace/myComponent`.
 
 #### Configuring Labels
 
-The `builtins.label()` provider handles `@salesforce/label/*` imports. How you
-configure it depends on your project:
+There are two providers for `@salesforce/label/*`:
+
+- **`builtins.labelsGraphql()` — the default.** Resolves labels at runtime via UI
+  API GraphQL through the Platform Data SDK (`createDataSDK()`), so labels reflect
+  the current user's translation. The SDK picks the transport per surface: a
+  direct session-authenticated GraphQL request in a full-page web app, or the
+  `window.openai` bridge in an MCP/ChatGPT host. Build-time values (or the
+  key-derived fallback) render until the runtime fetch resolves. Included
+  automatically when you omit the `providers` array.
+- **`builtins.label()` — static.** Resolves to a fixed build-time string. Use it
+  to opt out of runtime fetching (e.g. a pure off-core demo with no org).
+
+Both accept the same overrides object; `labelsGraphql` uses the overrides as the
+static fallback shown before/instead of a successful GraphQL fetch.
+
+How you configure labels depends on your project:
 
 **SFDX project with `CustomLabels.labels-meta.xml`:**
 
@@ -340,8 +369,95 @@ you'll get runtime errors like:
 Uncaught TypeError: Cannot read properties of undefined (reading 'isOpen')
 ```
 
-Always include `builtins.gate()` and `builtins.accessCheck()` when using
-`lightning-base-components`.
+Include `builtins.gate()` when using `lightning-base-components`. (When you omit
+the `providers` array entirely, the default set already covers these.)
+
+#### GraphQL-backed scoped modules (default)
+
+When you **omit** the `providers` array, these scoped modules resolve at runtime
+via UI API GraphQL through the Platform Data SDK (with build-time first-paint
+values):
+
+| Scoped module                          | GraphQL source (`uiapi.platform.*`) | Provider            | First-paint value                    |
+| -------------------------------------- | ----------------------------------- | ------------------- | ------------------------------------ |
+| `@salesforce/label/*`                  | `labels`                            | `labelsGraphql()`   | override or key-derived text         |
+| `@salesforce/i18n/*` (locale identity) | `i18n`                              | `platformGraphql()` | CLDR placeholder                     |
+| `@salesforce/userPermission/*`         | `userPermissions`                   | `platformGraphql()` | **required — you must configure it** |
+| `@salesforce/accessCheck/*`            | `userPermissions`                   | `platformGraphql()` | `false` (deny-by-default)            |
+| `@salesforce/customPermission/*`       | `customPermissions`                 | `platformGraphql()` | **required — you must configure it** |
+
+The generated modules export the first-paint value as `default` and an opt-in
+`subscribe(callback)` that fires with the resolved org value.
+
+##### Named permissions must be configured (no silent guess)
+
+A `@salesforce/userPermission/<Name>` or `@salesforce/customPermission/<Name>`
+import is an assertion about **per-user runtime state**. A plain default import
+binds the module's value **once** at module-eval time and never updates on its
+own — so if the plugin silently defaulted an unconfigured permission to `false`,
+your UI would render a permanent, wrong answer about what the current user can do
+(and it would be wrong even on the GraphQL **success** path, because a default
+import never re-reads the resolved value).
+
+Rather than guess, **the build fails** if you import a named permission without
+declaring the value it should show before the org responds:
+
+```
+[platform-graphql] @salesforce/userPermission/ApiEnabled was imported but has no
+first-paint value configured. …
+```
+
+Declare it with the `defaultProviders()` helper — which lets you configure this
+one provider while keeping every other default in place:
+
+```js
+import lwcVitePlugin, { defaultProviders } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+lwcVitePlugin({
+  modules: { dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }] },
+  providers: defaultProviders({
+    platformGraphql: {
+      userPermissionDefaults: { ApiEnabled: false, CustomizeApplication: false },
+      customPermissionDefaults: { My_Custom_Perm: false },
+    },
+  }),
+});
+```
+
+Use `false` unless you have a specific reason to render `true` before the fetch
+resolves. `@salesforce/accessCheck/*` is exempt: it's a feature **gate**, so an
+unconfigured check safely deny-defaults to `false` (base components rely on this),
+though you can still override it.
+
+##### Reflecting the resolved value reactively (`subscribe`)
+
+The configured value is only the **first paint**. To show the real org value once
+the GraphQL fetch lands, import the module's `subscribe(callback)` export and
+assign to a reactive field — the callback fires immediately with the current value
+and again when the resolved value differs:
+
+```js
+import apiEnabled, { subscribe } from "@salesforce/userPermission/ApiEnabled";
+
+export default class extends LightningElement {
+  apiEnabled = apiEnabled; // first paint (your configured value)
+  connectedCallback() {
+    subscribe((v) => (this.apiEnabled = v)); // corrects in the DOM when the org responds
+  }
+}
+```
+
+> **Dual-deploy note:** the `subscribe` export exists only when the module is
+> served by this plugin. If the **same** component source must also deploy as
+> on-platform LWC metadata (where `@salesforce/userPermission/*` has no `subscribe`
+> export), keep a plain default import — it will render the configured first-paint
+> value off-core and the platform-resolved value on-core.
+
+i18n number/date **format** patterns and calendar data stay static (CLDR reference
+data, no org source). `@salesforce/gate/*` also stays static — its GraphQL field is
+UiTier-context-only and not reachable off-core. The static `builtins.i18n()` /
+`builtins.accessCheck()` / `builtins.label()` providers remain available for
+explicit opt-out.
 
 ### Step 3: Create `index.html`
 
@@ -515,6 +631,9 @@ export const someExport = () => {};
 lwcVitePlugin({ stubs: { "force/someModule": "./stubs/someModule.js" } });
 ```
 
+See [Limitations → Not supported](limitations.md#not-supported--and-how-to-work-around-it)
+for stubbing navigation, LMS, Apex, and other core-only modules.
+
 ### Component renders but looks unstyled
 
 Add SLDS import to `bootstrap.js`:
@@ -527,6 +646,8 @@ import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-s
 
 ## Reference
 
+- **Migration Guide:** [migration-guide.md](migration-guide.md) — porting a platform LWC to a bundle
+- **Limitations & Unsupported Features:** [limitations.md](limitations.md) — what's not supported off-platform, and the workaround for each gap
 - **Live Preview & HMR verification:** [live-preview-hmr-verification.md](live-preview-hmr-verification.md) — how local dev (Live Preview, HMR, dev-gateway) works and is verified
 - **npm:** https://www.npmjs.com/package/@salesforce/vite-plugin-lwc-ui-bundle
 - **Source:** https://github.com/salesforce-experience-platform-emu/webapps/tree/main/packages/vite-plugin-lwc-ui-bundle

package/docs/limitations.md

@@ -0,0 +1,365 @@
+# LWC UI Bundle Limitations & Unsupported Features
+
+An LWC UI Bundle compiles your Lightning Web Components off-platform into a static
+`dist/` — an `index.html` plus hashed `assets/*.js`/`*.css` by default, or a single
+inlined `dist/index.html` if you add [`vite-plugin-singlefile`](https://www.npmjs.com/package/vite-plugin-singlefile)
+(see [Consumer Guide → Off-Platform Build](consumer-guide.md#off-platform-build)). The
+output runs anywhere with a DOM — an agentic MCP host (ChatGPT, MCP Apps), a plain
+website, or a `*.salesforce.app`-served page. Because there is **no Lightning runtime**
+around your component in any of those surfaces, some platform capabilities that are
+ambient on-platform have no equivalent off-platform. This document is the authoritative
+list of what is and isn't supported, _why_, and the recommended workaround for each gap.
+
+> Porting an existing platform component? Pair this reference with the
+> [Migration Guide](migration-guide.md), which walks through applying these
+> workarounds step by step.
+
+---
+
+## The core architectural constraint
+
+A platform LWC runs **inside** a Salesforce org: the Lightning runtime mounts it,
+`@salesforce/*` and `lightning/*` modules resolve to live org services, and Lightning
+Data Service (LDS) backs wire adapters with a **reactive client-side store** that
+pushes updates as records change.
+
+An LWC UI Bundle runs **anywhere with a DOM** — a browser tab, an MCP host, a
+`*.salesforce.app`-served page. There is no org runtime in the page. The plugin
+recreates the pieces it can as **scoped module providers**: small generated JS modules
+that stand in for `@salesforce/label/*`, `@salesforce/i18n/*`, and friends. Everything
+else — anything that needs a live authenticated session, a reactive store, a shared
+message bus, or platform navigation — either routes through an explicit data path
+(GraphQL / the Data SDK / an MCP tool) or is simply **not available** and must be
+stubbed.
+
+Two consequences flow from this and explain almost every limitation below:
+
+1. **No reactive store.** Wire adapters can fetch once, but nothing observes org state
+   to push updates. `subscribe()` is a no-op.
+2. **No ambient authenticated session** unless the bundle is served from a
+   `*.salesforce.app` app domain (deployed) or proxied to an org (`lwcProxy`, dev
+   only). A raw static file has no org to call.
+
+---
+
+## Support matrix
+
+| Capability                                              | Status         | Off-platform mechanism                                        |
+| ------------------------------------------------------- | -------------- | ------------------------------------------------------------- |
+| LWC component compilation (`.js/.html/.css`)            | ✅ Full        | `@lwc/rollup-plugin`                                          |
+| `lightning/*` base components                           | ✅ Full        | `lightning-base-components` (npm)                             |
+| Custom Labels (`@salesforce/label/*`)                   | ✅ Provider    | `builtins.label()` static · `builtins.labelsGraphql()` live   |
+| i18n (`@salesforce/i18n/*`)                             | ⚠️ Partial     | `builtins.i18n()` — live locale identity, static CLDR formats |
+| Client / form factor (`@salesforce/client/*`)           | ✅ Provider    | `builtins.client()`                                           |
+| Feature gates (`@salesforce/gate/*`)                    | ⚠️ Static      | `builtins.gate()` — **defaults open**, no live gate state     |
+| Access checks (`@salesforce/accessCheck/*`)             | ⚠️ Static      | `builtins.accessCheck()` — **defaults false**, no live perms  |
+| `lightning/primitiveUtils`                              | ✅ Provider    | `builtins.primitiveUtils()`                                   |
+| GraphQL (`lightning/graphql`)                           | ✅ Supported   | `builtins.lds()` default registry → MCP `graphqlQuery` tool   |
+| LDS wire/imperative adapters                            | ⚠️ Partial     | `builtins.lds()` — **only registered exports**; MCP-backed    |
+| REST / Apex REST                                        | ✅ Supported   | `createDataSDK().fetch?.()` → `/services/apexrest/*`          |
+| Imperative Apex (`@salesforce/apex/*`)                  | ❌ Unsupported | No provider — use GraphQL or Apex REST                        |
+| `@AuraEnabled` Apex methods                             | ❌ Unsupported | Expose as `@RestResource` instead                             |
+| Lightning Message Service (`lightning/messageService`)  | ❌ Unsupported | No provider — stub with `EventTarget` / host bridge           |
+| Navigation (`lightning/navigation`, `force/navigation`) | ❌ Unsupported | No provider — stub `NavigationMixin`                          |
+| LDS store subscriptions / auto-refresh                  | ❌ Unsupported | `subscribe()` is a no-op; use `refresh()` or re-query         |
+| Aura (`aura`) and other `force/*` modules               | ❌ Unsupported | No provider — supply a stub                                   |
+| Static Resources (`@salesforce/resourceUrl/*`)          | ❌ Unsupported | Bundle assets directly / import as Vite assets                |
+| Wire to `$CurrentPageReference`, User, Org context      | ❌ Unsupported | No provider — pass context in explicitly                      |
+
+Legend: ✅ works like platform · ⚠️ works with documented differences · ❌ no
+off-platform equivalent, workaround required.
+
+---
+
+## Supported with differences
+
+These work, but not identically to the platform. Know the difference before you rely
+on them.
+
+### i18n — live identity, static formats
+
+`builtins.i18n()` derives locale, language, currency, and time zone from the browser's
+`Intl` API at runtime, so `@salesforce/i18n/lang` and similar identity values are
+live. **Format patterns** (number/date/currency CLDR patterns), however, use en-US
+defaults rather than the org's locale data. If your component depends on exact
+locale-specific formatting matching the org, format through `Intl.NumberFormat` /
+`Intl.DateTimeFormat` explicitly rather than trusting the static patterns.
+
+### Feature gates — default open, not live
+
+`builtins.gate()` resolves every `@salesforce/gate/*` import to **open** by default.
+There is no connection to the org's live gate state. Pass overrides to model closed
+gates: `builtins.gate({ myFeature: false })`. Note that `lightning-base-components`
+use gates internally — you must include `builtins.gate()` or base components throw
+`Cannot read properties of undefined (reading 'isOpen')`.
+
+### Access checks — default false, not live
+
+`builtins.accessCheck()` resolves every `@salesforce/accessCheck/*` import to `false`
+by default — no live permission evaluation. Pass overrides for checks your UI depends
+on: `builtins.accessCheck({ MyCustomPerm: true })`. Because the default is `false`,
+permission-gated UI is hidden unless you opt it in; verify your overrides match the
+org behavior you're emulating.
+
+> **Coming soon — live permission evaluation.** A GraphQL-backed provider that resolves
+> `@salesforce/accessCheck/*` (plus `@salesforce/userPermission/*` and
+> `@salesforce/customPermission/*`) against the live user's permissions via UI API
+> GraphQL is in flight ([#670](https://github.com/salesforce-experience-platform-emu/webapps/pull/670)).
+> Until it merges, access checks are static-only as described above.
+
+### Custom Labels — static default, or live via GraphQL
+
+There are two label providers; pick per your data path:
+
+- **`builtins.label()` (static, the default).** Returns label strings from a defaults
+  map. Unknown keys get a human-readable fallback derived from the key
+  (`c.appTitle` → "App Title"). It does **not** fetch live translations. Provide real
+  values via `builtins.label({ "c.appTitle": "My App" })` or copy them from your
+  `CustomLabels.labels-meta.xml`. Translations for non-default languages are not
+  resolved.
+- **`builtins.labelsGraphql()` (live, opt-in).** Each `@salesforce/label/*` import
+  resolves to a runtime module that batches its key and fetches the translated value
+  via UI API GraphQL, so labels reflect the **current user's locale**. Static defaults
+  (and any `staticOverrides` you pass) act as the pre-fetch fallback. This needs a live
+  data path (a real MCP host, a mocked `callTool`, or a `*.salesforce.app`-served
+  bundle) — see [Data access and authentication](#data-access-and-authentication). To
+  use it, swap `label()` for `labelsGraphql()` in your `providers` array.
+
+### LDS — partial adapter coverage, no store
+
+The `lds()` provider (on by default) routes a **registered** set of adapters to MCP
+tools. The default registry covers:
+
+| Specifier                   | Export                     | Shape                    |
+| --------------------------- | -------------------------- | ------------------------ |
+| `lightning/uiRecordApi`     | `getRecord`                | wire                     |
+| `lightning/uiRecordApi`     | `createRecord`             | imperative-mutation      |
+| `lightning/uiRecordApi`     | `updateRecord`             | imperative-mutation      |
+| `lightning/uiObjectInfoApi` | `getObjectInfo_imperative` | imperative-read (legacy) |
+
+Code using only these exports ports unchanged, and each shape delegates to the same
+OneStore invoker used on-platform, so success payloads are deep-frozen and validation
+errors throw the same typed classes. Two hard limits:
+
+- **Unregistered exports don't resolve.** `getListUi`, `getRelatedListRecords`,
+  `deleteRecord`, and any other LDS export not in the registry pass through unresolved
+  and fail the build. Register your own MCP-backed adapter via the `lds({ … })` config
+  (see the [plugin README](../README.md#ldsadapters)), or replace the call with
+  GraphQL.
+- **`subscribe()` is a deliberate no-op.** Off-platform there is no reactive store to
+  observe, so the subscribe callback never fires and the returned unsubscribe is
+  idempotent. Data does not auto-update. Use `refresh()` (on the
+  `subscribable-refreshable` shape) or re-query when you need fresh data.
+
+---
+
+## Not supported — and how to work around it
+
+### Imperative Apex (`@salesforce/apex/MyClass.myMethod`)
+
+**No provider.** There is no way to invoke an `@AuraEnabled` Apex method off-platform.
+
+**Workarounds:**
+
+1. **GraphQL** — if the method only reads records, replace it with a UI API GraphQL
+   query. This is the preferred path and works both in a `@wire` and imperatively via
+   the Data SDK.
+2. **Apex REST** — for business logic that can't be expressed as GraphQL, expose it as
+   an `@RestResource` and call it through the Data SDK:
+
+   ```js
+   import { createDataSDK } from "@salesforce/platform-sdk";
+   const sdk = await createDataSDK();
+   const res = await sdk.fetch?.("/services/apexrest/property/listings");
+   const listings = await res?.json();
+   ```
+
+Note the distinction: **`@AuraEnabled` methods are not reachable; only `@RestResource`
+endpoints are.** Plan to expose an Apex REST surface for any imperative Apex you can't
+convert to GraphQL.
+
+### Lightning Message Service (`lightning/messageService`)
+
+**No provider.** LMS assumes a shared platform message bus (backed by
+`@salesforce/messageChannel/*` metadata) that doesn't exist off-platform.
+
+**Workaround — stub it, backed by a local bus:** for cross-component messaging _within
+the same bundle_, a module-scoped `EventTarget` reproduces publish/subscribe
+faithfully. For cross-surface messaging (bundle ↔ host), route through the MCP/host
+bridge instead.
+
+```js
+// src/stubs/message-service.js
+const bus = new EventTarget();
+
+export function createMessageContext() {
+  return {};
+}
+export function releaseMessageContext() {}
+export function publish(_ctx, channel, message) {
+  bus.dispatchEvent(new CustomEvent(channelKey(channel), { detail: message }));
+}
+export function subscribe(_ctx, channel, listener) {
+  const handler = (e) => listener(e.detail);
+  const key = channelKey(channel);
+  bus.addEventListener(key, handler);
+  return { key, handler };
+}
+export function unsubscribe(sub) {
+  if (sub) bus.removeEventListener(sub.key, sub.handler);
+}
+export const APPLICATION_SCOPE = Symbol("APPLICATION_SCOPE");
+export const MessageContext = Symbol("MessageContext");
+
+function channelKey(channel) {
+  return typeof channel === "string" ? channel : String(channel?.name ?? channel);
+}
+```
+
+```js
+// vite.config.js
+lwcVitePlugin({ stubs: { "lightning/messageService": "src/stubs/message-service.js" } });
+```
+
+`@salesforce/messageChannel/*` imports (the channel references) also have no provider —
+stub each to a plain identifier string, or import the channel name as a constant.
+
+### Navigation (`lightning/navigation`, `force/navigation`)
+
+**No provider.** There is no page reference resolver or router off-platform.
+
+**Workaround — a no-op `NavigationMixin` stub**, then decide per call site what
+navigation should mean (a real `window.location` change, a host callback, or nothing).
+This is exactly what the [`lwc-records` example](../../../examples/lwc-axl/lwc-records/sf/lwc/force/navigation/navigation.js)
+ships:
+
+```js
+// src/stubs/navigation.js
+export const CurrentPageReference = { adapter: Symbol("CurrentPageReference") };
+
+export const NavigationMixin = (Base) =>
+  class extends Base {
+    [NavigationMixin.Navigate]() {} // no-op, or window.location / host callback
+    [NavigationMixin.GenerateUrl]() {
+      return Promise.resolve("");
+    }
+  };
+NavigationMixin.Navigate = Symbol("Navigate");
+NavigationMixin.GenerateUrl = Symbol("GenerateUrl");
+```
+
+```js
+// vite.config.js
+lwcVitePlugin({ stubs: { "lightning/navigation": "src/stubs/navigation.js" } });
+```
+
+### Aura and other `force/*` / core-only modules
+
+**No provider.** `aura`, `logger`, and `force/*` / `runtime_*` modules are core-only.
+If the build fails with `Rollup failed to resolve import "force/someModule"`, add a
+stub exporting the shapes your code imports. The `lwc-records` example stubs several:
+
+```js
+// vite.config.js
+lwcVitePlugin({
+  stubs: {
+    aura: "src/stubs/aura-off-platform.js",
+    logger: "src/stubs/logger-stub.js",
+    "force/someModule": "src/stubs/some-module.js",
+  },
+});
+```
+
+A stub only needs to export the named bindings your components import — often no-ops or
+empty objects are enough to satisfy the bundler and let the rest of the app run.
+
+### Static Resources (`@salesforce/resourceUrl/*`) & content assets
+
+**No provider.** Off-platform there is no static resource CDN. Import assets through
+Vite instead (they get emitted into `dist/assets/`, or inlined into `index.html` if you
+build single-file), or reference them by absolute URL if hosted separately.
+
+### Org / user / page context wires
+
+Wire adapters that inject ambient context — `$CurrentPageReference`, current user,
+org info — have **no provider**. Pass the values your component needs in explicitly at
+mount time (`bootstrap.js`) or read them from the URL/host, rather than wiring them.
+
+---
+
+## Data access and authentication
+
+Even when your data code is correct, _where the bundle is served from_ determines
+whether it can reach the org. Off-platform there are **two distinct data paths**, and
+they resolve differently:
+
+1. **MCP-backed adapters** — `lightning/graphql` (`@wire(graphql)`) and the registered
+   `lightning/uiRecordApi` exports. These dispatch through the **host bridge** exposed
+   by `@salesforce/platform-sdk` — `getChatSDK().callTool(name, params)` with tool names
+   like `graphqlQuery`, `getRecordMcpTool`, …. The SDK detects the runtime surface and
+   picks the transport: on ChatGPT it calls `window.openai.callTool`; on MCP Apps it
+   sends a JSON-RPC `tools/call` request over the app's message channel. Either way the
+   adapter code is transport-agnostic. These do **not** hit `/services/*` and do **not**
+   use `lwcProxy`.
+2. **Same-origin REST** — the imperative Data SDK (`createDataSDK().graphql.query()` /
+   `.fetch()`) and any legacy `lightning/*` module that calls `/services/*` directly.
+   These make same-origin HTTP requests and need a real org session.
+
+How each path gets live data, by surface:
+
+| Surface                               | MCP-backed adapters              | Same-origin REST (Data SDK / legacy)                |
+| ------------------------------------- | -------------------------------- | --------------------------------------------------- |
+| **Local dev (`npm run dev`)**         | mock the host bridge (see below) | `lwcProxy()` forwards `/services/*` to `sf` CLI org |
+| **Real MCP host (ChatGPT, MCP Apps)** | host provides `callTool`         | n/a on this surface                                 |
+| **Deployed to `*.salesforce.app`**    | host bridge, if present          | authenticated same-origin session                   |
+| **Raw static file / other origin**    | no host bridge → no data         | no org session — `/services/data/*` returns `401`   |
+
+Key facts:
+
+- **`lwcProxy()` is development-only and REST-only.** It runs inside the Vite dev
+  server (not in the production `dist/index.html`) and exists for the same-origin REST
+  path — the Data SDK's imperative calls and legacy `lightning/*` modules that hit
+  `/services/*`. The MCP-backed `lightning/graphql` and `lightning/uiRecordApi`
+  adapters bypass it entirely; drive those with a real host or, in dev, a mocked host
+  bridge. On the ChatGPT surface that mock is a guarded `window.openai.callTool` shim in
+  your entry script; other surfaces (MCP Apps) resolve the bridge through their own
+  transport, so the SDK's `getChatSDK().callTool` picks the right one automatically.
+- **A deployed bundle needs the `*.salesforce.app` app domain** for the same-origin
+  REST path. Served from that domain, the Data SDK's cookie+CSRF flow against
+  `/services/data/v{version}/graphql` succeeds. Served from a different origin (a plain
+  static host, or the `my.salesforce.com` org domain), the same calls `401` — this is
+  by design, not a bug in your code.
+- **The Data SDK methods are optional.** Both `graphql?.query(...)` and `fetch?.()` may
+  be unavailable depending on the runtime surface — always call them with optional
+  chaining, and handle the `undefined` case.
+
+For the full data-access API, see [`@salesforce/platform-sdk`](../../sdk/platform-sdk/README.md).
+
+---
+
+## Quick reference: "which workaround?"
+
+| You were using…                               | Off-platform replacement                                         |
+| --------------------------------------------- | ---------------------------------------------------------------- |
+| Imperative `@AuraEnabled` Apex                | GraphQL query, or `@RestResource` + `sdk.fetch?.()`              |
+| `getRecord` / `createRecord` / `updateRecord` | Works via `lds()` (registered) — no change                       |
+| Other LDS adapter (`getListUi`, …)            | Register an MCP tool via `lds({ … })`, or use GraphQL            |
+| `lightning/messageService`                    | `EventTarget` stub (same-bundle) or host bridge (cross-surface)  |
+| `lightning/navigation`                        | No-op `NavigationMixin` stub + explicit routing                  |
+| `@salesforce/label/*`                         | `builtins.label()` (static) or `builtins.labelsGraphql()` (live) |
+| `@salesforce/gate/*`                          | `builtins.gate()` with overrides (defaults open)                 |
+| Static resource URL                           | Import the asset through Vite                                    |
+| Wire that auto-refreshes on store change      | `refresh()` or manual re-query — no reactive store off-platform  |
+
+---
+
+## Reference
+
+- [Migration Guide](migration-guide.md) — applying these workarounds step by step
+- [Consumer Guide](consumer-guide.md) — baseline setup and local-dev options
+- [Plugin README → Built-in Providers](../README.md#built-in-providers) — provider API
+- [Plugin README → `lds(adapters?)`](../README.md#ldsadapters) — registering adapters
+- [`lwc-records` example](../../../examples/lwc-axl/lwc-records) — real stubs for
+  `force/navigation`, `aura`, `logger`
+- [`@salesforce/platform-sdk`](../../sdk/platform-sdk/README.md) — GraphQL + REST data access
+  </content>