@salesforce/vite-plugin-lwc-ui-bundle 3.1.0 → 3.1.1

package/docs/consumer-guide.md

@@ -19,6 +19,68 @@ The plugin compiles your LWC components into a single self-contained `dist/index
 
 ---
 
+## Strategy & Responsibilities
+
+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 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)):
+
+- `lightning/uiRecordApi` — `getRecord` (wire), `createRecord` (imperative mutation), `updateRecord` (imperative mutation)
+- `lightning/uiObjectInfoApi` — `getObjectInfo_imperative` (legacy-shape imperative read)
+- `lightning/graphql` — `graphql` (wire) + `executeMutation`
+
+### Configuring `builtins.lds()`
+
+Pass an overrides object to extend or replace adapters:
+
+```js
+import lwcVitePlugin, { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+lwcVitePlugin({
+  providers: [
+    // ...
+    builtins.lds({
+      "lightning/uiListApi": {
+        getListUi: {
+          type: "wire",
+          mcp: { toolName: "getListUiMcpTool" },
+          configJsonSchema: {
+            /* ... */
+          },
+        },
+      },
+    }),
+  ],
+});
+```
+
+**Merge semantics** (see `mergeWithDefaults` in [`src/providers/lds/index.ts:332-338`](../src/providers/lds/index.ts)):
+
+- **Per specifier:** your overrides spread on top of defaults — `{ ...defaults[specifier], ...your[specifier] }`. Adding `getListUi` to `lightning/uiListApi` does not affect `lightning/uiRecordApi`.
+- **Per adapter name within a specifier:** override-by-key. You can replace `getRecord` without losing siblings like `createRecord`.
+- **Within an adapter entry:** **wholesale replacement, not deep merge.** If you redeclare `lightning/uiRecordApi` → `getRecord`, your `configJsonSchema` replaces the default's entirely. Repeat any default fields you want to keep.
+
+### Data waterfall awareness
+
+**Recommendation:** treat inefficient data access as the anti-pattern. Every LDS adapter call in an uplifted bundle becomes an independent, isolated MCP `callTool` — a fresh round-trip with tooling overhead the on-platform LDS path doesn't pay, and no shared cache. Multiple adapters requesting the same data (within a component, across components, or on re-render) all result in independent tool calls.
+
+**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.
+
+**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).
+
+**Detection:** compile-time detection is impractical (the plugin can't tell which components share data). This documentation is the primary guardrail. If you suspect inefficient data access, profile the bundle in DevTools Network: every `callTool` shows up as a separate request to the MCP host, and repeat visits don't get cached.
+
+---
+
 ## Off-Platform Build
 
 ### Project Structure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/vite-plugin-lwc-ui-bundle",
-  "version": "3.1.0",
+  "version": "3.1.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",
@@ -54,8 +54,8 @@
   },
   "peerDependencies": {
     "@lwc/rollup-plugin": "^9.0.0",
-    "@salesforce/platform-sdk-chat": "^3.1.0",
-    "@salesforce/ui-bundle": "^3.1.0",
+    "@salesforce/platform-sdk-chat": "^3.1.1",
+    "@salesforce/ui-bundle": "^3.1.1",
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
     "zod": "^3.23.8"
   },
@@ -75,7 +75,7 @@
   "devDependencies": {
     "@conduit-client/bindings-utils": "3.19.3",
     "@conduit-client/command-base": "3.19.3",
-    "@salesforce/platform-sdk-chat": "^3.1.0",
+    "@salesforce/platform-sdk-chat": "^3.1.1",
     "typescript": "^5.9.3",
     "vite": "^7.0.0",
     "vite-plugin-dts": "^4.5.4",

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

@@ -321,3 +321,47 @@ No skill change needed.
 `require.resolve()` check after `npm install` and installs the three
 packages only when they are actually missing AND the component tree
 uses LDS specifiers.
+
+## 14. Inefficient data access: latency and lack of caching
+
+**Symptom:** Data takes longer to load and the widget makes an
+increased number of network calls. DevTools Network panel shows
+multiple `callTool` requests; repeat visits don't get faster; two
+components reading the same record each fire their own request.
+
+**Cause:** Every LDS adapter call in an uplifted bundle becomes an
+independent, isolated MCP `callTool`. Two effects compound:
+
+- **Per-call latency.** Each `callTool` round-trips through the MCP
+  host before reaching a Salesforce server, adding tooling overhead
+  the on-platform LDS path doesn't pay. Adapters that fire
+  independently run in parallel, but adapters that are **chained**
+  (one's `config` depends on another's output) serialize — and the
+  per-call latencies sum link-by-link.
+- **No caching.** Unlike on-platform LDS, the MCP runtime has no
+  durable, shared cache. If multiple adapters request the same data
+  — within one component, across components, or on re-render — they
+  all result in independent and isolated tool calls.
+
+The plugin cannot detect this at compile time: whether two adapter
+calls request the same data is a property of the runtime component
+tree, not the source.
+
+**Fix:**
+
+- **Consolidate / minimize calls within each component.** GraphQL or
+  batch-enabled adapters are an alternative — one query / one batch
+  call replaces N separate adapter calls.
+- **Share data across components via an LWC state manager.** A
+  state manager serves as a single source of truth for data that is
+  shared cross-component.
+
+**Prevention:** Review the component tree before uplift. Look for
+overlapping data needs across components (state-manager candidates)
+and chained adapters within a component, where one's `config`
+depends on another's output (graphql consolidation candidates).
+Independent adapter declarations that fan out in parallel are not
+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.