@salesforce/vite-plugin-lwc-ui-bundle 9.20.0 → 9.20.1

package/docs/consumer-guide.md

@@ -23,17 +23,51 @@ The plugin compiles your LWC components into a single self-contained `dist/index
 
 This section is for team leads and app developers deciding **how** to uplift LWCs into static bundles for agentic surfaces. It's not a setup guide — for that, see [Off-Platform Build](#off-platform-build) below.
 
-The plugin ships configuration for a default, foundational set of UI API adapters — including `lightning/graphql`. Most uplifted bundles can rely on these defaults without writing any adapter config. During development, consumers can supplement the defaults by passing additional config to `builtins.lds()` (see [Configuring `builtins.lds()`](#configuring-builtinslds) below). Once a configuration is stable and useful to others, open a PR against [`packages/vite-plugin-lwc-ui-bundle/src/providers/lds/index.ts`](../src/providers/lds/index.ts) to add it to `DEFAULT_ADAPTERS` so it ships in the next plugin release.
+The plugin ships configuration for a default, foundational set of UI API adapters — including `lightning/graphql`. Most uplifted bundles can rely on these defaults without writing any adapter config. During development, consumers can supplement the defaults by passing additional config to `builtins.lds()` (see [Configuring `builtins.lds()`](#configuring-builtinslds) below). Once a configuration is stable and useful to others, open a PR against [`packages/vite-plugin-lwc-ui-bundle/src/providers/lds/index.ts`](../src/providers/lds/index.ts) to add it to `DEFAULT_REGISTRY` so it ships in the next plugin release.
 
 The Data Orchestration Service team is not responsible for the implementation of MCP tooling, nor for the adapter configuration of capabilities outside DOS ownership. As far as external teams are concerned, DOS provides the mechanism that applies the uplift per configuration; what each adapter resolves to at runtime — and which MCP tools back it — is owned by the team that owns the underlying capability.
 
 ### What ships in the default registry today
 
-(see `DEFAULT_ADAPTERS` in [`src/providers/lds/index.ts`](../src/providers/lds/index.ts)):
+Every default entry is one of four **flavors**, keyed off its `type`. For the
+exhaustive, always-current specifier/adapter list, read `DEFAULT_REGISTRY` in
+[`src/providers/lds/index.ts`](../src/providers/lds/index.ts).
+
+- **Wire** (`wire` / `graphql-wire`) — `@wire`-driven reactive reads, e.g.
+  `lightning/uiRecordApi`→`getRecord`, `lightning/graphql`→`graphql`.
+- **Imperative** (`imperative-mutation` / `graphql-mutation` / `imperative-read` /
+  `graphql-imperative-read`) — promise-returning calls invoked directly, e.g.
+  `lightning/uiRecordApi`→`createRecord`/`updateRecord`,
+  `lightning/uiObjectInfoApi`→`getObjectInfo_imperative`.
+- **State manager** (`state-manager`) — externalized LWC state managers composed
+  through an upstream per-state-manager factory, e.g.
+  `lightning/stateManagerRecord`→`createSmRecord`. Off-core they do not
+  auto-refire ([pitfall #15](../skills/setup-lwc-vite-plugin/references/known-pitfalls.md#15-state-managers-off-core-do-not-auto-refire-no-shared-luvio-store)).
+- **State manager (graphql)** — the `lightning/stateManagerGraphQL`→`createSmGraphQL`
+  variant: same composition, but exposes `errors` (plural) and a `refresh()` that
+  off-core re-runs the query via a fresh MCP tool call.
+
+State-manager entries use a different config shape from wire and
+imperative entries — `LdsStateManagerConfig` carries
+`factoryModule` + `factoryName` instead of being purely runtime-driven.
+The load hook imports the named factory at build time and composes the
+externalized state manager around an MCP-backed imperative adapter
+synthesized from `mcp.toolName` + `configJsonSchema`:
+
+```ts
+{
+  type: 'state-manager',
+  factoryModule: '@salesforce/state-managers-uiapi/factory',
+  factoryName: 'createSmRecord',  // or 'createSmObjectInfo', 'createSmGraphQL'
+  mcp: { toolName: 'getRecordMcpTool' },
+  configJsonSchema: { /* same per-resource constant the wire entry uses */ },
+}
+```
 
-- `lightning/uiRecordApi` — `getRecord` (wire), `createRecord` (imperative mutation), `updateRecord` (imperative mutation)
-- `lightning/uiObjectInfoApi` — `getObjectInfo_imperative` (legacy-shape imperative read)
-- `lightning/graphql` — `graphql` (wire) + `executeMutation`
+All per-state-manager metadata (`definedBy`, `requiredKeys`,
+`optionalKeys`, predicate) lives in the upstream factory and reaches
+off-core verbatim through the externalized state manager — registry
+entries do **not** redeclare those fields.
 
 ### Configuring `builtins.lds()`
 
@@ -73,7 +107,7 @@ lwcVitePlugin({
 **What developers should do today:**
 
 - **Consolidate / minimize calls within each component.** GraphQL or batch-enabled adapters are an alternative — one `@wire(graphql)` query can request fields from multiple records / object types in one round-trip, replacing N separate `@wire(getRecord)` / `@wire(getObjectInfo)` calls.
-- **Share data across components via an LWC state manager.** A state manager serves as a single source of truth so descendants subscribe rather than re-fetching. This recovers the cross-component sharing that on-platform LDS provides for free.
+- **Share data across components via an LWC state manager.** A state manager serves as a single source of truth so descendants subscribe rather than re-fetching. The plugin's default registry now ships `lightning/stateManagerRecord`, `lightning/stateManagerObjectInfo`, and `lightning/stateManagerGraphQL` (see "What ships in the default registry today" above). This recovers most of the cross-component sharing that on-platform LDS provides for free, but because there's no shared Luvio store off-core, **state managers do not auto-refire** — a sibling component mutating the same record won't refresh other instances. See [Known pitfall #15](../skills/setup-lwc-vite-plugin/references/known-pitfalls.md#15-state-managers-off-core-do-not-auto-refire-no-shared-luvio-store) for the re-trigger pattern (call `setConfig` with the same args, or `refresh()`).
 
 **See also:** [Known pitfall #14 — Inefficient data access: latency and lack of caching](../skills/setup-lwc-vite-plugin/references/known-pitfalls.md#14-inefficient-data-access-latency-and-lack-of-caching).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/vite-plugin-lwc-ui-bundle",
-  "version": "9.20.0",
+  "version": "9.20.1",
   "description": "Vite plugin for compiling LWC components into static bundles for off-platform and MCP use",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "Salesforce",
@@ -59,9 +59,9 @@
   "peerDependencies": {
     "@lwc/rollup-plugin": "^9.0.0",
     "@salesforce/lds-adapters-onestore-graphql": "^1.440.0",
-    "@salesforce/platform-sdk": "^9.20.0",
+    "@salesforce/platform-sdk": "^9.20.1",
     "@salesforce/state-managers-uiapi": "^0.30.0",
-    "@salesforce/ui-bundle": "^9.20.0",
+    "@salesforce/ui-bundle": "^9.20.1",
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
     "zod": "^3.23.8"
   },
@@ -87,7 +87,7 @@
   "devDependencies": {
     "@conduit-client/bindings-utils": "3.19.6",
     "@conduit-client/command-base": "3.19.6",
-    "@salesforce/platform-sdk": "^9.20.0",
+    "@salesforce/platform-sdk": "^9.20.1",
     "typescript": "^5.9.3",
     "vite": "^7.0.0",
     "vite-plugin-dts": "^4.5.4",

package/skills/setup-lwc-vite-plugin/SKILL.md

@@ -137,6 +137,21 @@ Starting from the root component, trace the dependency tree:
      support (provider + mock branch)
    - `lightning/uiRecordApi` imported AND `@wire(getRecord` / `@wire(get*`
      actually used → needs LDS support (provider + mock branch)
+   - `lightning/stateManagerRecord` imported (default `smRecord` import)
+     → needs `builtins.lds()` provider (default registry covers it) +
+     the `getRecordMcpTool` `callTool` mock branch (same tool the
+     `@wire(getRecord)` path uses — one branch covers both). See
+     `known-pitfalls.md` for the no-auto-refire (no shared Luvio store)
+     reactivity contract.
+   - `lightning/stateManagerObjectInfo` imported (default `smObjectInfo`
+     import) → needs `builtins.lds()` provider + the
+     `getObjectInfoMcpTool` `callTool` mock branch.
+   - `lightning/stateManagerGraphQL` imported (default `smGraphQL`
+     import) → needs `builtins.lds()` provider + the `graphqlQuery`
+     `callTool` mock branch (same tool the `@wire(graphql)` path uses).
+     Note `smGraphQL` exposes `errors` (plural) on its outer shape,
+     matching its analogous wire adapter — distinct from UIAPI managers
+     which expose `error` (singular).
    - `lightning/*` base components → needs `lightning-base-components`
      npm package, plus `gate()`, `accessCheck()`, and `primitiveUtils()`
      providers because base components use these modules internally even
@@ -150,17 +165,23 @@ Starting from the root component, trace the dependency tree:
 
 **Be precise with LDS detection.** The LDS provider/mock is only needed
 when a component's `@wire` actually consumes `getRecord`/`getRecordUi`/
-similar adapters from `lightning/uiRecordApi`. **Do not trigger the LDS
-provider just because:**
+similar adapters from `lightning/uiRecordApi`, **or** when a component
+imports a `lightning/stateManager*` default export and calls its
+`setConfig` / setters. **Do not trigger the LDS provider just because:**
 
 - The app has a chat wrapper whose tool output happens to contain a
   record shape (`records[...]`) — that goes through
   `window.openai.toolOutput` + the mapper, not the LDS wire adapter.
 - A component imports `lightning/uiRecordApi` but doesn't `@wire` it.
-
-`builtins.lds()` wires up `@wire(getRecord)` specifically. If no
-component calls those wire adapters, omit both the provider and the
-`getRecordMcpTool` mock branch. A chat wrapper that maps
+- A component imports `lightning/stateManager*` but never instantiates
+  the state manager.
+
+`builtins.lds()` wires up `@wire(getRecord)`, `@wire(graphql)`, **and**
+the three `lightning/stateManager{Record,ObjectInfo,GraphQL}` virtual
+modules — they all live in the same default registry. If no component
+calls those wire adapters or instantiates a state manager, omit both
+the provider and the corresponding mock branch (`getRecordMcpTool` /
+`getObjectInfoMcpTool` / `graphqlQuery`). A chat wrapper that maps
 `window.openai.toolOutput.records[...]` into a component's `@api`
 props is independent of LDS.
 
@@ -201,6 +222,9 @@ Check in this order:
      `builtins.lds()` must be present (graphql specifiers are in the default registry)
    - Step 4 found `@wire(getRecord)` from `lightning/uiRecordApi` →
      `builtins.lds()` must be present (one `builtins.lds()` covers both)
+   - Step 4 found any `lightning/stateManager{Record,ObjectInfo,GraphQL}`
+     import that's actually instantiated → `builtins.lds()` must be
+     present (the default registry covers all three specifiers)
    - Step 4 found any `@salesforce/i18n/*` → `builtins.i18n()` must be
      present
    - Step 4 found any `@salesforce/client/*` → `builtins.client()` must
@@ -252,14 +276,20 @@ Ask the user whether to generate mocks. Mocks serve two independent
 purposes — list each one **only if Step 4 / Step 2 produced something
 to mock**, and skip lines that don't apply:
 
-- **`callTool` branches for wire adapters** — one branch per wire
-  provider actually detected in Step 4:
-  - `graphqlQuery` — only if Step 4 found `@wire(graphql)` in a
-    component's `.js`. Not needed otherwise.
-  - `getRecordMcpTool` — only if Step 4 found `@wire(getRecord)` in
-    a component's `.js`. Not needed just because a chat wrapper
-    passes record-shaped data; the wrapper reads `toolOutput`, not
-    `callTool`.
+- **`callTool` branches for wire adapters and state managers** — one
+  branch per tool actually detected in Step 4. State managers share
+  tool names with their sibling wire adapters, so one branch covers
+  both call paths:
+  - `graphqlQuery` — only if Step 4 found `@wire(graphql)` **or**
+    `lightning/stateManagerGraphQL` (default `smGraphQL`) usage. Not
+    needed otherwise.
+  - `getRecordMcpTool` — only if Step 4 found `@wire(getRecord)` **or**
+    `lightning/stateManagerRecord` (default `smRecord`) usage. Not
+    needed just because a chat wrapper passes record-shaped data;
+    the wrapper reads `toolOutput`, not `callTool`.
+  - `getObjectInfoMcpTool` — only if Step 4 found
+    `lightning/stateManagerObjectInfo` (default `smObjectInfo`) usage,
+    or a future `getObjectInfo` imperative-read consumer.
 - **Seed `window.openai.toolOutput`** — only if Step 2 generated a
   chat wrapper. This is what drives the wrapper's initial render; the
   mapper consumes it. It has nothing to do with `callTool`.
@@ -373,11 +403,15 @@ import lwcVitePlugin, { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
 // inside plugins -> lwcVitePlugin({ providers: [...] })
 builtins.lds(),                         // default registry:
                                         //   lightning/uiRecordApi, uiObjectInfoApi,
-                                        //   and lightning/graphql (tool: "graphqlQuery")
+                                        //   lightning/graphql (tool: "graphqlQuery"),
+                                        //   lightning/stateManagerRecord     -> getRecordMcpTool
+                                        //   lightning/stateManagerObjectInfo -> getObjectInfoMcpTool
+                                        //   lightning/stateManagerGraphQL    -> graphqlQuery
 
 // Add to / override the default registry. The argument is deep-merged onto
 // the defaults per specifier, so you only declare what you are changing —
-// unmentioned entries (e.g. `getRecord`, `createRecord`) are preserved.
+// unmentioned entries (e.g. `getRecord`, `createRecord`, the three
+// `lightning/stateManager*` defaults) are preserved.
 builtins.lds({
   "lightning/graphql": {
     graphql: { type: "graphql-wire", mcp: { toolName: "myGraphqlTool" } },
@@ -386,13 +420,55 @@ builtins.lds({
 }),
 ```
 
+**Registering or overriding a state manager** — the
+`LdsStateManagerConfig` discriminator (`type: 'state-manager'`)
+points the load hook at an upstream per-state-manager **factory**.
+Composition (the externalized state manager and all its per-manager
+metadata — `definedBy`, `requiredKeys`, `optionalKeys`, predicate)
+lives in the upstream factory; the registry entry only carries the
+factory specifier (`factoryModule` + `factoryName`), the MCP tool name,
+and the JSON schema for `setConfig` validation:
+
+```js
+builtins.lds({
+  "lightning/stateManagerRecord": {
+    default: {
+      type: "state-manager",
+      factoryModule: "@salesforce/state-managers-uiapi/factory",
+      factoryName: "createSmRecord",
+      mcp: { toolName: "getRecordMcpTool" },
+      configJsonSchema: {
+        /* same RECORD_SCHEMA used by getRecord wire entry */
+      },
+    },
+  },
+}),
+```
+
+The three default entries are:
+
+| Specifier                          | `factoryModule`                                     | `factoryName`        | Default `mcp.toolName` |
+| ---------------------------------- | --------------------------------------------------- | -------------------- | ---------------------- |
+| `lightning/stateManagerRecord`     | `@salesforce/state-managers-uiapi/factory`          | `createSmRecord`     | `getRecordMcpTool`     |
+| `lightning/stateManagerObjectInfo` | `@salesforce/state-managers-uiapi/factory`          | `createSmObjectInfo` | `getObjectInfoMcpTool` |
+| `lightning/stateManagerGraphQL`    | `@salesforce/lds-adapters-onestore-graphql/factory` | `createSmGraphQL`    | `graphqlQuery`         |
+
+State-manager entries do **not** carry `definedBy`, `requiredKeys`,
+`optionalKeys`, or any predicate — those live in the upstream factory
+and reach off-core verbatim through the externalized state manager.
+Within an adapter entry, the override is a **wholesale replacement,
+not a deep merge**, so when you redeclare the `default` adapter you
+must repeat every field you want to keep (including `factoryModule` /
+`factoryName`).
+
 Adapt based on earlier findings:
 
 - Set `dirs` for the detected project structure (SFDX vs namespaced).
 - Populate `builtins.label({...})` with values from Step 6.
 - Include `builtins.primitiveUtils()` if using `lightning-base-components`.
 - Include `builtins.lds()` if any component uses `lightning/uiRecordApi`,
-  `lightning/uiObjectInfoApi`, or `lightning/graphql`.
+  `lightning/uiObjectInfoApi`, `lightning/graphql`, or any of the
+  `lightning/stateManager{Record,ObjectInfo,GraphQL}` specifiers.
 - Include `viteSingleFile()` — without it, `vite build` emits multi-file
   output and the MCP host can't inline the bundle. See
   `known-pitfalls.md#6` for the full config block.
@@ -406,9 +482,19 @@ Adapt based on earlier findings:
 - `builtins.lds()` default for `lightning/graphql` (both `graphql` wire
   and `executeMutation`): `graphqlQuery`. Override by registering the
   specifier explicitly — see example above.
+- `builtins.lds()` default for `lightning/stateManagerRecord`:
+  `getRecordMcpTool` (shared with the `getRecord` wire entry — one
+  mock branch covers both).
+- `builtins.lds()` default for `lightning/stateManagerObjectInfo`:
+  `getObjectInfoMcpTool`.
+- `builtins.lds()` default for `lightning/stateManagerGraphQL`:
+  `graphqlQuery` (shared with the `graphql` wire entry).
 
 Whatever tool names you settle on here **must match** the branches in
-`bootstrap.js` mocks (Step 8).
+`bootstrap.js` mocks (Step 8). For state-manager consumers, also note
+that `smGraphQL`'s outer shape exposes `errors` (plural), matching its
+sibling wire adapter — UIAPI managers (`smRecord`, `smObjectInfo`)
+expose `error` (singular).
 
 #### `index.html`
 
@@ -466,6 +552,10 @@ Run this check **only** if Step 4 found actual usage of any of:
 - `lightning/uiRecordApi` with real `@wire` usage of `getRecord` /
   `createRecord` / `updateRecord`
 - `lightning/uiObjectInfoApi` with real usage
+- `lightning/stateManagerRecord`, `lightning/stateManagerObjectInfo`,
+  or `lightning/stateManagerGraphQL` with real instantiation (default
+  `smRecord` / `smObjectInfo` / `smGraphQL` import that's actually
+  invoked) — these all flow through the same LDS runtime
 
 If none of the above are in the component tree, skip this sub-step
 entirely — the LDS runtime is never loaded and the peers don't matter.

package/skills/setup-lwc-vite-plugin/references/known-pitfalls.md

@@ -365,3 +365,49 @@ inherently a problem — only chains and overlapping fetches are. The
 strategy section in
 [`docs/consumer-guide.md`](../../../docs/consumer-guide.md#data-waterfall-awareness)
 walks through the recommendation.
+
+## 15. State managers off-core do not auto-refire (no shared Luvio store)
+
+**Symptom:** A `lightning/stateManager*` instance fetches once and then
+never updates on its own, even when sibling code in the same page
+mutates the same record. The `data` / `status` atoms stay frozen at
+their first-loaded values; no second `callTool` fires unless the
+consumer triggers it.
+
+**Cause:** On core, every `lightning/stateManager*` instance shares a
+single Luvio store. When any other code path mutates a record (a
+`@wire(getRecord)` re-fetch, an `updateRecord` call, another state
+manager observing the same key), Luvio re-publishes to every
+subscriber on the same key — so siblings re-fire automatically.
+Off-core through `vite-plugin-lwc-ui-bundle` there is no shared store:
+each state manager wraps its own MCP-backed adapter, and `subscribe` is
+a deliberate no-op (nothing fans changes out). Mutations elsewhere in
+the page do not propagate automatically.
+
+**Fix:** Re-trigger off-core state managers explicitly when the
+consumer knows the underlying data may have changed. Call the matching
+setter (`setRecordId`, `setFields`, …) or `setConfig(currentConfig)`
+with the same arguments to re-run the adapter; `smGraphQL` also exposes
+`refresh()` (upstream PR `lds-lightning-platform#7916`), which off-core
+re-issues the query as a fresh MCP tool call and resolves with the new
+result (rejecting only if that re-execute itself fails):
+
+```js
+import smRecord from "lightning/stateManagerRecord";
+
+const sm = smRecord();
+sm.setConfig({ recordId: "001…", fields: ["Account.Name"] }); // initial load
+// …later, after a sibling component mutates the same record:
+sm.setConfig({ recordId: "001…", fields: ["Account.Name"] }); // re-fires the call
+```
+
+**On-core behavior is unchanged** — the same upstream factories power
+both; on core the shared store means there's nothing to work around.
+
+**Prevention:** treat state managers off-core as imperative-with-atoms
+rather than reactive subscriptions. Audit every place where a data
+mutation in one component should be visible in another, and add an
+explicit re-trigger (`setConfig` / `refresh()`) at the mutation site,
+or a broadcast/event the dependent state managers listen for. The
+plugin cannot synthesize a Luvio store — that's a §11 Risk 1 contract
+baked into the off-core uplift.