@salesforce/vite-plugin-lwc-ui-bundle 11.13.0 → 11.13.2

package/README.md

@@ -4,6 +4,9 @@ Vite plugin for compiling and running LWC components off-platform. Bundles the f
 
 > **Getting started?** See the [Consumer Guide](docs/consumer-guide.md) for a
 > step-by-step walkthrough of adding this plugin to an existing LWC project.
+>
+> - **Porting a platform component?** See the [Migration Guide](docs/migration-guide.md).
+> - **What's not supported off-platform?** See [Limitations & Unsupported Features](docs/limitations.md).
 
 ## Installation
 

package/docs/consumer-guide.md

@@ -515,6 +515,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 +530,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>

package/docs/migration-guide.md

@@ -0,0 +1,334 @@
+# Migrating Platform LWC to an LWC UI Bundle
+
+This guide walks you through porting a Lightning Web Component that runs **inside a
+Salesforce org** to an **LWC UI Bundle** compiled off-platform with
+`@salesforce/vite-plugin-lwc-ui-bundle`. The build emits a static `dist/` (an
+`index.html` plus hashed `assets/*`, or a single inlined `dist/index.html` if you add
+`vite-plugin-singlefile`) that runs in any browser, an MCP host, or a Salesforce UI
+Bundle served from the `*.salesforce.app` domain.
+
+> **New to the plugin?** Read the [Consumer Guide](consumer-guide.md) first for the
+> baseline Vite setup. This guide focuses on what _changes_ when the component was
+> originally written for the platform, and links to the
+> [Limitations reference](limitations.md) for the features that don't come across.
+
+---
+
+## What actually changes
+
+A platform LWC and an LWC UI Bundle share the **same component source** — `.js`,
+`.html`, and `.css` files compile unchanged through `@lwc/rollup-plugin`. What
+changes is the _environment_ your component runs in:
+
+| On platform                                              | In an LWC UI Bundle                                                                             |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| The Lightning runtime mounts your component              | You mount it yourself in `bootstrap.js` via `createElement`                                     |
+| `@salesforce/*` modules resolve to live org services     | Scoped **providers** resolve them to generated JS (labels, i18n, gates, …)                      |
+| LDS wire adapters read from a reactive client-side store | Registered adapters dispatch through the Data SDK's host bridge to MCP tools; no reactive store |
+| Imperative Apex, LMS, and navigation are ambient         | They have **no provider** — you supply a stub or a GraphQL/REST replacement                     |
+| Metadata (`.js-meta.xml`) drives exposure and targets    | `.js-meta.xml` is ignored by the build; a `ui-bundle` manifest drives routing                   |
+
+The migration is therefore mostly about **the edges** of your component — how it gets
+mounted, how it gets data, and which platform capabilities it reaches for. The
+component logic in the middle usually ports verbatim.
+
+---
+
+## Migration at a glance
+
+1. [Inventory your dependencies](#step-1-inventory-your-dependencies) — find every
+   `import` that reaches the platform.
+2. [Set up the Vite project](#step-2-set-up-the-vite-project) — `vite.config.js`,
+   `index.html`, `bootstrap.js`.
+3. [Map each dependency](#step-3-map-each-dependency) to a provider, an SDK call, or
+   a stub.
+4. [Replace data access](#step-4-replace-data-access) — LDS/Apex → GraphQL or the
+   Data SDK.
+5. [Handle the unsupported edges](#step-5-handle-the-unsupported-edges) — LMS,
+   navigation, and other org-only APIs.
+6. [Build, run, and verify](#step-6-build-run-and-verify).
+
+---
+
+## Step 1: Inventory your dependencies
+
+Before touching config, list every non-relative import in your component tree. These
+are the imports that reach beyond your own `.js`/`.html` files and into the platform:
+
+```bash
+# From your LWC source root — list the platform-facing specifiers your bundle uses
+grep -rhoE "from \"(@salesforce/[^\"]+|lightning/[^\"]+|force/[^\"]+|aura)\"" \
+  force-app/main/default/lwc | sort -u
+```
+
+Sort what you find into four buckets — this table _is_ your migration plan:
+
+| Import pattern                                                                                        | Bucket             | Action                                                                               |
+| ----------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------ |
+| `lwc`, `lightning/*` base components                                                                  | **Compiles as-is** | Nothing — bundled via `@lwc/rollup-plugin` + npm                                     |
+| `@salesforce/label/*`, `@salesforce/i18n/*`, `client`, `gate`, `accessCheck`                          | **Has a provider** | Add the matching `builtins.*` provider                                               |
+| `lightning/graphql`, registered LDS adapters                                                          | **Data access**    | See [Step 4](#step-4-replace-data-access)                                            |
+| `@salesforce/apex/*`, `lightning/messageService`, `lightning/navigation`, `force/*`, `aura`, `logger` | **Unsupported**    | Replace with GraphQL/REST or a stub — [Step 5](#step-5-handle-the-unsupported-edges) |
+
+Anything in the last two buckets needs a decision. The [Limitations
+reference](limitations.md) covers each unsupported module and its recommended
+workaround in detail.
+
+---
+
+## Step 2: Set up the Vite project
+
+Follow [Consumer Guide → Off-Platform Build](consumer-guide.md#off-platform-build) to
+add `vite.config.js`, `index.html`, and `bootstrap.js`. The one part worth calling out
+for migrations is that **you now own mounting**. On platform, the framework
+instantiated your top-level component; off-platform, `bootstrap.js` does:
+
+```js
+// bootstrap.js
+import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.css";
+import "@lwc/synthetic-shadow";
+import { createElement } from "lwc";
+import App from "c/myApp"; // your existing root component, unchanged
+
+const el = createElement("c-my-app", { is: App });
+
+// Public @api properties the org used to set — set them here instead
+el.recordId = "001xx000003DGb2AAG";
+
+document.getElementById("app").appendChild(el);
+```
+
+Any `@api` property the org used to inject (`recordId`, `objectApiName`, flexipage
+attributes, etc.) now has no injector — set it explicitly when you mount, or read it
+from the URL/host. This is the single most common migration surprise.
+
+---
+
+## Step 3: Map each dependency
+
+For every import in the **"has a provider"** bucket, add the matching provider to
+your `vite.config.js`. The defaults cover the common set:
+
+```js
+import lwcVitePlugin, { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+lwcVitePlugin({
+  modules: {
+    dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }],
+    npm: ["lightning-base-components"],
+  },
+  providers: [
+    builtins.label(), // @salesforce/label/*
+    builtins.i18n(), // @salesforce/i18n/*
+    builtins.accessCheck(), // @salesforce/accessCheck/* (default false)
+    builtins.client(), // @salesforce/client/*
+    builtins.gate(), // @salesforce/gate/*   (default open)
+    builtins.primitiveUtils(), // lightning/primitiveUtils
+    builtins.lds(), // lightning/uiRecordApi, lightning/graphql, … (MCP-backed)
+  ],
+});
+```
+
+If you pass a `providers` array, it **replaces** the defaults — list every provider
+you need. Omit `providers` entirely to get the full default set: `label`, `i18n`,
+`accessCheck`, `client`, `gate`, `primitiveUtils`, and `lds`. Note there is no separate
+GraphQL provider — `lightning/graphql` is handled by `lds()`, whose default registry
+routes `graphql`/`executeMutation` to an MCP tool.
+
+A few provider-specific notes for migrated code:
+
+- **Labels** default to a human-readable fallback derived from the key
+  (`c.appTitle` → "App Title"). Port real values with
+  `builtins.label({ "c.appTitle": "My App" })`, or copy them from your
+  `CustomLabels.labels-meta.xml`. If you have a live data path and want translated
+  values at the user's locale, swap in `builtins.labelsGraphql()` instead — see
+  [Limitations → Custom Labels](limitations.md#custom-labels--static-default-or-live-via-graphql).
+- **Gates** default **open** and **access checks** default **false** off-platform.
+  If your component branches on either, pass overrides so its behavior matches the
+  org: `builtins.gate({ myGate: false })`, `builtins.accessCheck({ MyPerm: true })`.
+- **i18n** derives locale/currency from the browser via the `Intl` API; CLDR format
+  patterns use en-US defaults. Locale-identity is live, format specifics are static.
+
+---
+
+## Step 4: Replace data access
+
+This is the heart of most migrations. Platform LWC reaches org data three ways:
+**LDS wire adapters**, **imperative Apex**, and **`lightning/graphql`**. Off-platform,
+GraphQL is the through-line — it works in both a component wire and imperatively via
+the Data SDK.
+
+### LDS wire adapters (`getRecord`, `createRecord`, …)
+
+The `lds()` provider (on by default) routes a **registered** set of adapters to MCP
+tools. Out of the box that covers `getRecord`, `createRecord`, `updateRecord`
+(`lightning/uiRecordApi`) and `getObjectInfo_imperative` (`lightning/uiObjectInfoApi`). Code
+that uses only these ports **unchanged**:
+
+```js
+import { getRecord } from "lightning/uiRecordApi";
+
+// Same @wire on platform and off — the adapter resolves to an MCP tool off-platform
+@wire(getRecord, { recordId: "$recordId", fields: FIELDS })
+wiredRecord({ data, error }) { /* ... */ }
+```
+
+Two behavioral differences to plan for:
+
+- **No reactive store.** `subscribe()` on the imperative read shapes is a deliberate
+  no-op — the callback never fires. Data does not auto-refresh when it changes
+  elsewhere; call `refresh()` (on the `subscribable-refreshable` shape) or re-query.
+- **Only registered exports resolve.** Any LDS export not in the registry (e.g.
+  `getRelatedListRecords`, `getListUi`) passes through to normal `lightning/*`
+  resolution — which has no off-platform implementation, so the build fails to resolve
+  it. Register it with your own MCP tool via the `lds({ ... })` config, or replace the
+  call with GraphQL. See [Limitations → LDS](limitations.md#lds--partial-adapter-coverage-no-store).
+
+### Imperative Apex (`@salesforce/apex/MyClass.myMethod`)
+
+There is **no Apex provider**, and `@AuraEnabled` methods are **not** reachable
+off-platform. Migrate each imperative Apex call to one of:
+
+1. **GraphQL** — if the method just reads records, replace it with a UI API GraphQL
+   query (preferred; see below).
+2. **Apex REST** — expose the logic as an `@RestResource` and call it through the Data
+   SDK's `fetch`. Budget time to build this surface for any business logic you can't
+   express as GraphQL.
+
+See [Limitations → Imperative Apex](limitations.md#imperative-apex-salesforceapexmyclassmymethod)
+for the `sdk.fetch?.()` snippet and the `@AuraEnabled`-vs-`@RestResource` distinction.
+
+### `lightning/graphql` and the Data SDK
+
+`lightning/graphql` keeps working via the default `builtins.lds()` registry — no
+separate provider, and `@wire(graphql, …)` components port unchanged. The wire adapter
+dispatches through the MCP `graphqlQuery` tool. For imperative reads, use
+`@salesforce/platform-sdk` directly:
+
+```js
+import { createDataSDK, gql } from "@salesforce/platform-sdk";
+
+const sdk = await createDataSDK();
+const result = await sdk.graphql?.query({
+  query: gql`
+    query GetAccounts {
+      uiapi {
+        query {
+          Account(first: 10) {
+            edges {
+              node {
+                Id
+                Name {
+                  value
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  `,
+});
+```
+
+`sdk.graphql?.query(...)` resolves against whatever surface the bundle runs on — a real
+MCP host's bridge, or the authenticated same-origin session on `*.salesforce.app`. Where
+each data path gets live data (and why a bundle on any other origin `401`s) is covered in
+[Limitations → Data access & auth](limitations.md#data-access-and-authentication).
+
+For **local development without a real host**, install a guarded host-bridge mock in
+your entry script (on ChatGPT that's a `window.openai.callTool` shim) so
+`@wire(graphql)` / `@wire(getRecord)` return data — see
+[Consumer Guide → Step 4: `bootstrap.js`](consumer-guide.md#step-4-create-bootstrapjs).
+(`lwcProxy()` is a separate, optional companion plugin — it forwards `/services/*` for
+_legacy_ `lightning/*` modules that call REST directly, not for the MCP-backed LDS and
+GraphQL adapters.)
+
+---
+
+## Step 5: Handle the unsupported edges
+
+Some platform capabilities have no off-platform equivalent. The repo's convention is
+a **hand-written stub** wired through the plugin's `stubs` option — the same pattern
+the [`lwc-records` example](../../../examples/lwc-axl/lwc-records) uses for
+`force/navigation`, `aura`, and `logger`.
+
+Each unsupported capability has a recommended stub or replacement documented in the
+Limitations reference — this step is about wiring them through the plugin's `stubs`
+option. The pattern is the same for each: point the specifier at a hand-written stub
+file that exports the shapes your code imports.
+
+```js
+// vite.config.js — one entry per unsupported specifier
+lwcVitePlugin({
+  stubs: {
+    "lightning/navigation": "src/stubs/navigation.js",
+    "lightning/messageService": "src/stubs/message-service.js",
+    aura: "src/stubs/aura.js",
+    "force/someModule": "src/stubs/some-module.js",
+  },
+});
+```
+
+For the actual stub contents and per-module guidance:
+
+- **Navigation** (`lightning/navigation`, `force/navigation`) — no-op `NavigationMixin`,
+  then decide per call site: [Limitations → Navigation](limitations.md#navigation-lightningnavigation-forcenavigation).
+- **Lightning Message Service** (`lightning/messageService`) — `EventTarget`-backed bus
+  for same-bundle messaging, host bridge across surfaces:
+  [Limitations → LMS](limitations.md#lightning-message-service-lightningmessageservice).
+- **`aura`, `logger`, `force/*` and other core-only modules** — export just the bindings
+  your code imports (often no-ops): [Limitations → Aura and other `force/*`](limitations.md#aura-and-other-force--core-only-modules).
+
+If the build fails with `Rollup failed to resolve import "force/someModule"` (or
+`aura`), that specifier needs a stub. The `lwc-records` example ships real stubs for
+`force/navigation`, `aura`, and `logger`.
+
+---
+
+## Step 6: Build, run, and verify
+
+```bash
+npm run build     # → dist/ (index.html + assets/*, or a single dist/index.html
+                  #   if you added vite-plugin-singlefile)
+open dist/index.html
+
+npm run dev       # dev server with live reload (+ lwcProxy for live data)
+```
+
+A migration is done when:
+
+- The bundle **builds** with no unresolved imports (unresolved = a dependency you
+  haven't yet mapped to a provider, SDK call, or stub — go back to Step 3).
+- Every `@api` the org used to set is set at mount time or read from the host/URL.
+- Data reads succeed against your target surface (mock, `lwcProxy` dev, or a
+  `*.salesforce.app`-served deployed bundle).
+- Behavior that branched on gates/access checks matches the org, given your provider
+  overrides.
+
+---
+
+## Common migration errors
+
+| Symptom                                                      | Cause                                              | Fix                                                                     |
+| ------------------------------------------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------- |
+| `Rollup failed to resolve import "@salesforce/apex/…"`       | No Apex provider                                   | Migrate to GraphQL or Apex REST ([Step 4](#step-4-replace-data-access)) |
+| `Rollup failed to resolve import "lightning/navigation"`     | No navigation provider                             | Add a stub ([Step 5](#step-5-handle-the-unsupported-edges))             |
+| `Rollup failed to resolve import "force/…"`                  | Core-only module                                   | Add a stub via `stubs`                                                  |
+| `@wire(getRelatedListRecords)` builds but returns nothing    | Adapter not in the `lds()` registry                | Register an MCP tool or replace with GraphQL                            |
+| Wire data never refreshes                                    | `subscribe()` is a no-op off-platform              | Call `refresh()` or re-query explicitly                                 |
+| `Cannot read properties of undefined (reading 'isOpen')`     | Missing `gate()` provider (base components use it) | Add `builtins.gate()`                                                   |
+| Component mounts but is missing data it used to get for free | `@api` no longer injected by the platform          | Set the property in `bootstrap.js`                                      |
+| Deployed bundle `401`s on `/services/data/*`                 | Served from a non-`salesforce.app` origin          | Serve from `*.salesforce.app`, or use `lwcProxy` in dev                 |
+
+---
+
+## Reference
+
+- [Consumer Guide](consumer-guide.md) — baseline Vite setup and local-dev options
+- [Limitations & Unsupported Features](limitations.md) — the full constraint reference
+- [`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>
+  </invoke>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/vite-plugin-lwc-ui-bundle",
-  "version": "11.13.0",
+  "version": "11.13.2",
   "description": "Vite plugin for compiling LWC components into static bundles for off-platform and MCP use",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "Salesforce",
@@ -74,9 +74,9 @@
   },
   "peerDependencies": {
     "@lwc/rollup-plugin": "^9.0.0",
-    "@salesforce/platform-sdk": "^11.13.0",
+    "@salesforce/platform-sdk": "^11.13.2",
     "@salesforce/state-managers-uiapi": "^0.31.0",
-    "@salesforce/ui-bundle": "^11.13.0",
+    "@salesforce/ui-bundle": "^11.13.2",
     "lwc": "^9.0.0",
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
     "zod": "^3.23.8"
@@ -100,7 +100,7 @@
   "devDependencies": {
     "@conduit-client/bindings-utils": "3.19.6",
     "@conduit-client/command-base": "3.19.6",
-    "@salesforce/platform-sdk": "^11.13.0",
+    "@salesforce/platform-sdk": "^11.13.2",
     "@types/ws": "^8.5.12",
     "typescript": "^5.9.3",
     "vite": "^7.0.0",