@salesforce/vite-plugin-lwc-ui-bundle 1.133.0 → 1.133.2

package/dist/providers/lightning-graphql/runtime.js

@@ -31,9 +31,9 @@ function gql(strings, ...values) {
 async function runQuery(config) {
   const { query, variables } = config;
   if (!query) return { data: void 0, errors: void 0 };
-  if (typeof globalThis.__sfdc_sdk__ === "object" && typeof globalThis.__sfdc_sdk__?.graphql === "function") {
-    const sdkGraphql = globalThis.__sfdc_sdk__.graphql;
-    const result = await sdkGraphql({ query, variables: variables ?? {} });
+  const sdkRef = globalThis.__sfdc_sdk__;
+  if (sdkRef && typeof sdkRef.graphql === "function") {
+    const result = await sdkRef.graphql({ query, variables: variables ?? {} });
     return { data: result?.data, errors: result?.errors };
   }
   const sdk = await getChatSDK();

package/dist/providers/lightning-graphql/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sources":["../../../src/providers/shared/normalize-mcp-response.ts","../../../src/providers/lightning-graphql/runtime.ts"],"sourcesContent":["/**\n * Copyright (c) 2026, Salesforce, Inc.,\n * All rights reserved.\n * For full license text, see the LICENSE.txt file\n */\n\n/**\n * Unwraps the MCP tool transport envelope and returns the tool's payload as-is.\n *\n * Handles the three surface shapes `sdk.callTool()` can resolve with:\n * - MCP Apps surface: `{ structuredContent, content }`\n * - OpenAI surface: `{ result: \"<JSON string>\" }`, where the JSON may itself be\n *   an MCP content array (`[{ type: 'text', text: \"<JSON string>\" }, ...]`)\n * - Fallback: the raw value returned by `callTool`\n *\n * The shape of the unwrapped payload is the tool's responsibility — this helper\n * does not project out `data` / `error` / `errors`. Callers read whichever keys\n * their tool contract defines.\n */\nexport function normalizeMcpResponse(raw: unknown): unknown {\n\tif (raw && typeof raw === \"object\" && \"structuredContent\" in raw) {\n\t\treturn (raw as { structuredContent: unknown }).structuredContent;\n\t}\n\n\tif (raw && typeof raw === \"object\" && typeof (raw as { result?: unknown }).result === \"string\") {\n\t\tconst parsed = JSON.parse((raw as { result: string }).result);\n\t\tif (Array.isArray(parsed)) {\n\t\t\tconst textBlock = parsed.find(\n\t\t\t\t(b: { type?: string; text?: string }) =>\n\t\t\t\t\tb && b.type === \"text\" && typeof b.text === \"string\",\n\t\t\t);\n\t\t\tconst text = textBlock ? textBlock.text : null;\n\t\t\tif (text) {\n\t\t\t\treturn JSON.parse(text);\n\t\t\t}\n\t\t\treturn {};\n\t\t}\n\t\treturn parsed;\n\t}\n\n\treturn raw ?? {};\n}\n","/**\n * Copyright (c) 2026, Salesforce, Inc.,\n * All rights reserved.\n * For full license text, see the LICENSE.txt file\n */\nimport { getChatSDK } from \"@salesforce/sdk-chat\";\nimport { normalizeMcpResponse } from \"../shared/normalize-mcp-response\";\n\n// Overwritten at plugin-load time by the `lightningGraphql` Vite shim, which\n// appends `TOOL_NAME = \"<configured-name>\";` to the bundled output. The initial\n// value is the default.\n// eslint-disable-next-line prefer-const\nexport let TOOL_NAME = \"graphqlQuery\";\n\ninterface GraphqlConfig {\n\tquery?: string;\n\tvariables?: Record<string, unknown>;\n}\n\ninterface GraphqlResult {\n\tdata?: unknown;\n\terrors?: { message: string }[];\n}\n\ntype WireCallback = (result: {\n\tdata: unknown;\n\terrors: { message: string }[] | undefined;\n\trefresh: () => Promise<void>;\n}) => void;\n\nexport function gql(strings: TemplateStringsArray, ...values: unknown[]): string {\n\tlet result = \"\";\n\tstrings.forEach((string, i) => {\n\t\tresult += string;\n\t\tif (i < values.length) result += String(values[i]);\n\t});\n\treturn result;\n}\n\nasync function runQuery(config: GraphqlConfig): Promise<GraphqlResult> {\n\tconst { query, variables } = config;\n\tif (!query) return { data: undefined, errors: undefined };\n\n\t// 1. UIBundle / local dev: use globalThis.__sfdc_sdk__.graphql if available\n\tif (\n\t\ttypeof (globalThis as Record<string, unknown>).__sfdc_sdk__ === \"object\" &&\n\t\ttypeof ((globalThis as Record<string, unknown>).__sfdc_sdk__ as Record<string, unknown>)\n\t\t\t?.graphql === \"function\"\n\t) {\n\t\tconst sdkGraphql = (\n\t\t\t(globalThis as Record<string, unknown>).__sfdc_sdk__ as Record<string, unknown>\n\t\t).graphql as (args: {\n\t\t\tquery: string;\n\t\t\tvariables: Record<string, unknown>;\n\t\t}) => Promise<GraphqlResult>;\n\t\tconst result = await sdkGraphql({ query, variables: variables ?? {} });\n\t\treturn { data: result?.data, errors: result?.errors };\n\t}\n\n\t// 2. MCP surface: use getChatSDK().callTool\n\tconst sdk = await getChatSDK();\n\tif (typeof sdk.callTool !== \"function\") {\n\t\tthrow new Error(\n\t\t\t\"[lightning/graphql] No data surface available. \" +\n\t\t\t\t\"Either initialise globalThis.__sfdc_sdk__ with createDataSDK, \" +\n\t\t\t\t\"or run inside a ChatGPT / MCP Apps context.\",\n\t\t);\n\t}\n\n\tconst raw = await sdk.callTool({\n\t\ttoolName: TOOL_NAME,\n\t\tparams: { query, variables: variables ?? {} },\n\t});\n\n\treturn (normalizeMcpResponse(raw) as GraphqlResult) ?? {};\n}\n\nexport class graphql {\n\t_dataCallback: WireCallback;\n\t_config: GraphqlConfig | undefined;\n\n\tconstructor(dataCallback: WireCallback) {\n\t\tthis._dataCallback = dataCallback;\n\t}\n\n\tconnect() {\n\t\tthis._fetch();\n\t}\n\n\t// eslint-disable-next-line @typescript-eslint/no-empty-function\n\tdisconnect() {}\n\n\tupdate(config: GraphqlConfig) {\n\t\tthis._config = config;\n\t\tthis._fetch();\n\t}\n\n\trefresh() {\n\t\treturn this._fetch();\n\t}\n\n\tasync _fetch() {\n\t\ttry {\n\t\t\tconst result = await runQuery(this._config ?? {});\n\t\t\tthis._emit(result);\n\t\t} catch (error) {\n\t\t\tthis._emit({\n\t\t\t\tdata: undefined,\n\t\t\t\terrors: [{ message: (error as Error).message }],\n\t\t\t});\n\t\t}\n\t}\n\n\t_emit({ data, errors }: GraphqlResult) {\n\t\tthis._dataCallback({\n\t\t\tdata,\n\t\t\terrors: errors?.length ? errors : undefined,\n\t\t\trefresh: () => this.refresh(),\n\t\t});\n\t}\n}\n\nexport async function executeMutation(config: GraphqlConfig): Promise<GraphqlResult> {\n\tif (!config?.query) return { data: undefined, errors: [{ message: \"No query provided\" }] };\n\ttry {\n\t\treturn await runQuery(config);\n\t} catch (error) {\n\t\treturn { data: undefined, errors: [{ message: (error as Error).message }] };\n\t}\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime.js","sources":["../../../src/providers/shared/normalize-mcp-response.ts","../../../src/providers/lightning-graphql/runtime.ts"],"sourcesContent":["/**\n * Copyright (c) 2026, Salesforce, Inc.,\n * All rights reserved.\n * For full license text, see the LICENSE.txt file\n */\n\n/**\n * Unwraps the MCP tool transport envelope and returns the tool's payload as-is.\n *\n * Handles the three surface shapes `sdk.callTool()` can resolve with:\n * - MCP Apps surface: `{ structuredContent, content }`\n * - OpenAI surface: `{ result: \"<JSON string>\" }`, where the JSON may itself be\n *   an MCP content array (`[{ type: 'text', text: \"<JSON string>\" }, ...]`)\n * - Fallback: the raw value returned by `callTool`\n *\n * The shape of the unwrapped payload is the tool's responsibility — this helper\n * does not project out `data` / `error` / `errors`. Callers read whichever keys\n * their tool contract defines.\n */\nexport function normalizeMcpResponse(raw: unknown): unknown {\n\tif (raw && typeof raw === \"object\" && \"structuredContent\" in raw) {\n\t\treturn (raw as { structuredContent: unknown }).structuredContent;\n\t}\n\n\tif (raw && typeof raw === \"object\" && typeof (raw as { result?: unknown }).result === \"string\") {\n\t\tconst parsed = JSON.parse((raw as { result: string }).result);\n\t\tif (Array.isArray(parsed)) {\n\t\t\tconst textBlock = parsed.find(\n\t\t\t\t(b: { type?: string; text?: string }) =>\n\t\t\t\t\tb && b.type === \"text\" && typeof b.text === \"string\",\n\t\t\t);\n\t\t\tconst text = textBlock ? textBlock.text : null;\n\t\t\tif (text) {\n\t\t\t\treturn JSON.parse(text);\n\t\t\t}\n\t\t\treturn {};\n\t\t}\n\t\treturn parsed;\n\t}\n\n\treturn raw ?? {};\n}\n","/**\n * Copyright (c) 2026, Salesforce, Inc.,\n * All rights reserved.\n * For full license text, see the LICENSE.txt file\n */\nimport { getChatSDK } from \"@salesforce/sdk-chat\";\nimport { normalizeMcpResponse } from \"../shared/normalize-mcp-response\";\n\n// Overwritten at plugin-load time by the `lightningGraphql` Vite shim, which\n// appends `TOOL_NAME = \"<configured-name>\";` to the bundled output. The initial\n// value is the default.\n// eslint-disable-next-line prefer-const\nexport let TOOL_NAME = \"graphqlQuery\";\n\ninterface GraphqlConfig {\n\tquery?: string;\n\tvariables?: Record<string, unknown>;\n}\n\ninterface GraphqlResult {\n\tdata?: unknown;\n\terrors?: { message: string }[];\n}\n\ntype WireCallback = (result: {\n\tdata: unknown;\n\terrors: { message: string }[] | undefined;\n\trefresh: () => Promise<void>;\n}) => void;\n\nexport function gql(strings: TemplateStringsArray, ...values: unknown[]): string {\n\tlet result = \"\";\n\tstrings.forEach((string, i) => {\n\t\tresult += string;\n\t\tif (i < values.length) result += String(values[i]);\n\t});\n\treturn result;\n}\n\nasync function runQuery(config: GraphqlConfig): Promise<GraphqlResult> {\n\tconst { query, variables } = config;\n\tif (!query) return { data: undefined, errors: undefined };\n\n\t// 1. UIBundle / local dev: use globalThis.__sfdc_sdk__.graphql if available.\n\t// Invoke as a method (not a destructured reference) so class-based SDK\n\t// implementations keep their `this` binding — some SDKs implement\n\t// `graphql` as a method that calls `this.fetch(...)` internally.\n\tconst sdkRef = (globalThis as Record<string, unknown>).__sfdc_sdk__ as\n\t\t| {\n\t\t\t\tgraphql?: (args: {\n\t\t\t\t\tquery: string;\n\t\t\t\t\tvariables: Record<string, unknown>;\n\t\t\t\t}) => Promise<GraphqlResult>;\n\t\t  }\n\t\t| undefined;\n\tif (sdkRef && typeof sdkRef.graphql === \"function\") {\n\t\tconst result = await sdkRef.graphql({ query, variables: variables ?? {} });\n\t\treturn { data: result?.data, errors: result?.errors };\n\t}\n\n\t// 2. MCP surface: use getChatSDK().callTool\n\tconst sdk = await getChatSDK();\n\tif (typeof sdk.callTool !== \"function\") {\n\t\tthrow new Error(\n\t\t\t\"[lightning/graphql] No data surface available. \" +\n\t\t\t\t\"Either initialise globalThis.__sfdc_sdk__ with createDataSDK, \" +\n\t\t\t\t\"or run inside a ChatGPT / MCP Apps context.\",\n\t\t);\n\t}\n\n\tconst raw = await sdk.callTool({\n\t\ttoolName: TOOL_NAME,\n\t\tparams: { query, variables: variables ?? {} },\n\t});\n\n\treturn (normalizeMcpResponse(raw) as GraphqlResult) ?? {};\n}\n\nexport class graphql {\n\t_dataCallback: WireCallback;\n\t_config: GraphqlConfig | undefined;\n\n\tconstructor(dataCallback: WireCallback) {\n\t\tthis._dataCallback = dataCallback;\n\t}\n\n\tconnect() {\n\t\tthis._fetch();\n\t}\n\n\t// eslint-disable-next-line @typescript-eslint/no-empty-function\n\tdisconnect() {}\n\n\tupdate(config: GraphqlConfig) {\n\t\tthis._config = config;\n\t\tthis._fetch();\n\t}\n\n\trefresh() {\n\t\treturn this._fetch();\n\t}\n\n\tasync _fetch() {\n\t\ttry {\n\t\t\tconst result = await runQuery(this._config ?? {});\n\t\t\tthis._emit(result);\n\t\t} catch (error) {\n\t\t\tthis._emit({\n\t\t\t\tdata: undefined,\n\t\t\t\terrors: [{ message: (error as Error).message }],\n\t\t\t});\n\t\t}\n\t}\n\n\t_emit({ data, errors }: GraphqlResult) {\n\t\tthis._dataCallback({\n\t\t\tdata,\n\t\t\terrors: errors?.length ? errors : undefined,\n\t\t\trefresh: () => this.refresh(),\n\t\t});\n\t}\n}\n\nexport async function executeMutation(config: GraphqlConfig): Promise<GraphqlResult> {\n\tif (!config?.query) return { data: undefined, errors: [{ message: \"No query provided\" }] };\n\ttry {\n\t\treturn await runQuery(config);\n\t} catch (error) {\n\t\treturn { data: undefined, errors: [{ message: (error as Error).message }] };\n\t}\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/vite-plugin-lwc-ui-bundle",
-  "version": "1.133.0",
+  "version": "1.133.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",
@@ -73,7 +73,7 @@
     "magic-string": "^0.30.17"
   },
   "devDependencies": {
-    "@salesforce/sdk-chat": "^1.133.0",
+    "@salesforce/sdk-chat": "^1.133.2",
     "typescript": "^5.9.3",
     "vite": "^7.0.0",
     "vite-plugin-dts": "^4.5.4",

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

@@ -12,123 +12,237 @@ description: >
 
 # Setup @salesforce/vite-plugin-lwc-ui-bundle
 
-This skill adds `@salesforce/vite-plugin-lwc-ui-bundle` to an existing LWC project,
-producing a single `dist/index.html` that runs in any browser without a Salesforce org.
+Adds `@salesforce/vite-plugin-lwc-ui-bundle` to an existing LWC project,
+producing a single `dist/index.html` that runs in a browser without a
+Salesforce org.
 
-## What the plugin does
-
-It wraps the full LWC compilation pipeline behind a single Vite plugin: scoped module
-providers (labels, i18n, gates, etc.), Lightning npm resolution, missing CSS handling,
-and the Vite/LWC bridge. The output is a self-contained HTML file with all JS and CSS
-inlined.
+The plugin wraps the full LWC compilation pipeline behind one Vite plugin:
+scoped module providers (labels, i18n, gates, etc.), Lightning npm
+resolution, missing CSS handling, and the Vite/LWC bridge. Output is a
+self-contained HTML file with all JS and CSS inlined.
 
 ## Reference material
 
-The `references/consumer-guide.md` file contains exact file templates, dependency
-versions, and config snippets. Read it when you need to generate `vite.config.js`,
-`index.html`, `bootstrap.js`, or `package.json` updates. This skill tells you
-_when and why_ to use each piece; the consumer guide gives you the exact _what_.
+The skill dispatches to these reference files. Read each one when the
+relevant step arrives — don't try to inline everything from here:
+
+- **`references/consumer-guide.md`** — exact file templates (`vite.config.js`,
+  `index.html`, `bootstrap.js`, `package.json`), dependency list, and
+  troubleshooting. This is the source of truth for generated files.
+- **`references/chat-wrapper-flow.md`** — the full sub-flow for Step 2 (ask
+  about chat wrappers, analyze `@api` surface, confirm mapping, generate
+  `chatContextAdapter` + `<component>ChatMapper` + `<component>ChatWrapper`).
+- **`references/bootstrap-js-patterns.md`** — the conditional `callTool`
+  shim skeleton, envelope/tool-contract rules, how to handle an existing
+  `bootstrap.js`, and why mocks only work in `npm run dev`.
+- **`references/known-pitfalls.md`** — consolidated list of real bugs seen
+  in consumer projects, each with symptom / cause / fix. Consult when a
+  build or runtime fails with a confusing message.
 
-## Interactive Setup Flow
+## Interactive setup flow
 
-Walk the user through these steps in order. Ask questions — don't assume.
+Walk through these steps in order. Ask questions — don't assume. When a
+step points to a reference file, read it before proceeding.
 
 ### Step 1: Detect the project
 
-LWC projects come in two layouts, and the directory structure determines how
-`modules.dirs` must be configured. Detecting the layout first avoids misconfigured
-imports that silently fail at build time.
+LWC projects come in two layouts, and the directory structure determines
+how `modules.dirs` must be configured. Detecting the layout first avoids
+misconfigured imports that silently fail at build time.
 
 Check in order:
 
-1. `sfdx-project.json` in the project root → **SFDX project**. Components live at
-   `force-app/main/default/lwc/` in a flat structure where every component shares
-   the `c` namespace. Configure as `dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }]`.
-2. Directories matching `src/lwc/` or `modules/` → **off-core project**. Sub-directories
-   are namespaces (e.g., `src/lwc/myNs/myComponent/`). Configure as `dirs: ["src/lwc"]`.
+1. `sfdx-project.json` in the project root → **SFDX project**. Components
+   live at `force-app/main/default/lwc/` in a flat structure where every
+   component shares the `c` namespace. Configure as
+   `dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }]`.
+2. Directories matching `src/lwc/` or `modules/` → **off-core project**.
+   Sub-directories are namespaces (e.g., `src/lwc/myNs/myComponent/`).
+   Configure as `dirs: ["src/lwc"]`.
 3. If neither found, ask the user where their LWC components live.
 
-Read `package.json` to understand what's already installed — avoid adding duplicate
-dependencies later.
+Read `package.json` to understand what's already installed — avoid
+duplicates later. If the project already has `vite.config.js`,
+`bootstrap.js`, or `main.js`, read them too so the later steps can merge
+instead of overwriting.
+
+Check the user's Node.js version (`node --version`). Vite 8.x requires
+Node `^20.19.0 || >=22.12.0`. On older Node 20.x, builds fail deep inside
+rolldown with "Cannot find native binding" (see `known-pitfalls.md#1`).
+Surface this early:
+
+> "You're on Node 20.14.0. Vite 8 needs 20.19+. Options:
+> A) Upgrade Node (recommended — `nvm install 20.19` or `22`)
+> B) Pin `vite@^7` and a compatible `@lwc/rollup-plugin` major"
 
-### Step 2: Ask for the root component
+### Step 2: Ask about chat wrappers
+
+If the project will run inside a ChatGPT/MCP host (tool output drives
+the UI), components need a thin chat-aware wrapper + mapper. The wrapper
+reads tool output from the host, the mapper normalizes it into the
+component's `@api` props, and the component itself stays unchanged.
+
+Ask before proceeding to root-component selection:
+
+> "Will any component in this project need to be driven by ChatGPT/MCP
+> tool output? I can generate a chat wrapper + mapper for each one so the
+> component stays unchanged and the wrapper handles host integration.
+>
+> A) Yes — walk me through creating a wrapper
+> B) No — skip this step"
 
-The plugin compiles a tree starting from one root component that gets mounted in the
-HTML page. The user needs to tell you which one, since there's no reliable way to
-auto-detect the "main" component.
+If **B**, proceed directly to Step 3.
+
+If **A**, read `references/chat-wrapper-flow.md` and walk through its
+sub-steps 2a–2e for each component the user wants to wrap.
+
+### Step 3: Pick the root component
+
+The plugin compiles a tree starting from one root component that gets
+mounted in the HTML page. The user needs to tell you which one — there's
+no reliable way to auto-detect the "main" component.
 
 List the discovered components and ask:
 
-> "Which component should be the root of your app? This is the one that gets
-> mounted in the HTML page."
+> "Which component should be the root of your app? This is the one that
+> gets mounted in the HTML page."
 
-Present the component names as a numbered list for easy selection.
+Present the names as a numbered list for easy selection.
 
-### Step 3: Inspect the component tree
+### Step 4: Inspect the component tree
 
-This step drives every downstream decision: which providers to include, whether
-`lightning-base-components` is needed, and whether to offer Tier 2 (live org). Getting
-this right prevents cryptic build errors.
+This step drives every downstream decision: which providers to include,
+which `lightning-base-components` are needed, and which tools need mock
+branches for local dev. Getting this right prevents cryptic build
+errors.
 
 Starting from the root component, trace the dependency tree:
 
 1. Read the root component's `.html` file — find all `c-*` tags (or other
-   namespace tags) to identify child components
-2. Recursively read each child component's `.js` and `.html`
+   namespace tags) to identify child components.
+2. Recursively read each child component's `.js` and `.html`.
 3. Collect all imports across the tree:
    - `@salesforce/label/*` → label keys (need `builtins.label()`)
-   - `lightning/graphql` or `@wire(graphql` → needs GraphQL support
-   - `lightning/*` base components → needs `lightning-base-components` npm package,
-     plus `gate()`, `accessCheck()`, and `primitiveUtils()` providers because
-     base components use these modules internally even if user code doesn't
-   - `@salesforce/gate/*`, `@salesforce/accessCheck/*` → handled by providers
-   - `@salesforce/i18n/*` → i18n provider
-   - `@salesforce/client/*` → client provider (provides `formFactor` based on viewport width)
-   - `lightning/primitiveUtils` → primitiveUtils provider
-
-Report what you found:
+   - `lightning/graphql` AND `@wire(graphql` present → needs GraphQL
+     support (provider + mock branch)
+   - `lightning/uiRecordApi` imported AND `@wire(getRecord` / `@wire(get*`
+     actually used → needs LDS support (provider + mock branch)
+   - `lightning/*` base components → needs `lightning-base-components`
+     npm package, plus `gate()`, `accessCheck()`, and `primitiveUtils()`
+     providers because base components use these modules internally even
+     if user code doesn't
+   - `@salesforce/gate/*`, `@salesforce/accessCheck/*` → handled by
+     those providers
+   - `@salesforce/i18n/*` → `i18n` provider
+   - `@salesforce/client/*` → `client` provider (provides `formFactor`
+     based on viewport width)
+   - `lightning/primitiveUtils` → `primitiveUtils` provider
+
+**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:**
+
+- 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
+`window.openai.toolOutput.records[...]` into a component's `@api`
+props is independent of LDS.
+
+Report what you found — plainly, so the user can correct misdetections:
 
 > "I traced your component tree from `c/app`. Here's what I found:
 >
 > - 5 components total
 > - 3 label imports: `c.appTitle`, `c.greeting`, `c.save`
-> - Uses `lightning-card` (needs lightning-base-components)
-> - Uses `lightning/graphql` (needs lwcProxy for live data)
-> - No gate/accessCheck imports in your code, but lightning-base-components
->   uses them internally — I'll include those providers automatically."
-
-### Step 4: Decide the tier
-
-The plugin supports two tiers. This determines which dependencies and bootstrap
-code to generate.
-
-| Tier                            | What you get                               | Org required?      |
-| ------------------------------- | ------------------------------------------ | ------------------ |
-| **Tier 1: Off-Platform Build**  | Static bundle with mock data, labels, i18n | No                 |
-| **Tier 2: Live Org Connection** | Real GraphQL queries via `lwcProxy()`      | Yes (via `sf` CLI) |
+> - Uses `lightning-card` → needs lightning-base-components + the
+>   gate/accessCheck/primitiveUtils providers
+> - Uses `lightning/graphql` → needs `builtins.lightningGraphql()` + a
+>   graphql mock branch in `bootstrap.js`
+> - Uses `lightning/uiRecordApi` → needs `builtins.lds()` + a
+>   `getRecordMcpTool` mock branch"
+
+### Step 5: Decide the runtime mode
+
+Two runtime contexts, one compiled bundle:
+
+| Context                | Data source                                              | Notes                                                         |
+| ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
+| **Local dev**          | Mock `window.openai` shim in `bootstrap.js`              | `npm run dev` only. No org, no ChatGPT host.                  |
+| **ChatGPT / MCP host** | Host-provided `window.openai` (`callTool`, `toolOutput`) | Production. Same compiled bundle; mocks skipped by the guard. |
+
+The `if (!window.openai?.callTool)` guard is what makes one bundle work
+in both contexts. ChatGPT/MCP hosts set `window.openai` before loading
+the bundle, so the guard short-circuits.
+
+> `lwcProxy()` is intentionally not offered. It doesn't currently support
+> `lightning/uiRecordApi`, so it's not a reliable local-dev substitute
+> for components that use LDS. Keep the workflow simple: mock locally,
+> real host in ChatGPT.
+
+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`.
+- **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`.
+
+Build the question by combining whichever applies. For example, a
+project with graphql only:
+
+> "For local dev (`npm run dev`) I can add mocks in `bootstrap.js`. The
+> shim only activates when no host bridge is present, so the same
+> compiled bundle runs inside ChatGPT unchanged.
+>
+> Based on Step 4, the mock will need:
+>
+> - `callTool` branch for `graphqlQuery`
+>
+> A) Yes — generate mocks with sample data I'll describe
+> B) No — skip mocks
+>
+> If B, `@wire(graphql)` will return no data under `npm run dev`, but
+> the bundle will still render correctly when deployed to a real MCP
+> server as a UI resource — the host provides a real `window.openai`
+> there."
 
-If GraphQL usage was detected in Step 3, ask:
+For a project with a chat wrapper **and** `@wire(graphql)`, include
+both the `callTool` branch and the `toolOutput` seed, but keep them
+as distinct items in the list:
 
-> "Your components use `lightning/graphql`. Do you want to connect to a real
-> Salesforce org for live data during development?
+> Based on Step 2 / Step 4, the mocks will include:
 >
-> A) Yes — I have an org connected via `sf` CLI (adds lwcProxy + Data SDK)
-> B) No — use mock data for now (GraphQL wire adapter returns empty results)"
+> - `callTool` branch for `graphqlQuery` (for the `@wire(graphql)` call)
+> - Seed for `window.openai.toolOutput` (drives the
+>   `<bcx-record-detail-chat-wrapper>` initial render)
 
-If no GraphQL detected, default to Tier 1 — there's no benefit to Tier 2 without
-GraphQL or live data needs.
+### Step 6: Resolve label values
 
-### Step 5: Resolve label values
+Labels need explicit values because the plugin can't read them from an
+org at build time. Getting them right here means the user sees realistic
+text immediately instead of placeholder keys.
 
-Labels need explicit values because the plugin can't read them from an org at build
-time. Getting them right here means the user sees realistic text immediately instead
-of placeholder keys.
-
-1. **SFDX project**: Check for `force-app/main/default/labels/CustomLabels.labels-meta.xml`.
-   If found, parse it and extract `<fullName>` → `<value>` pairs for the label
-   keys discovered in Step 3.
+1. **SFDX project**: Check for
+   `force-app/main/default/labels/CustomLabels.labels-meta.xml`. If found,
+   parse it and extract `<fullName>` → `<value>` pairs for the label keys
+   discovered in Step 4.
 2. **Off-core project or no labels XML**: For each label key found, use a
-   placeholder value derived from the key (e.g., `c.appTitle` → `"App Title"`).
+   placeholder value derived from the key (e.g., `c.appTitle` → `"App
+Title"`).
 
 Tell the user what labels you found and the values you'll use:
 
@@ -140,103 +254,186 @@ Tell the user what labels you found and the values you'll use:
 >
 > You can change these in `vite.config.js` later."
 
-If no labels were found at all, still include `builtins.label()` with no overrides.
-The plugin returns a human-readable fallback for unknown keys, and
-`lightning-base-components` may use labels internally.
+If no labels were found at all, still include `builtins.label()` with no
+overrides. The plugin returns a human-readable fallback for unknown keys,
+and `lightning-base-components` may use labels internally.
+
+### Step 7: Generate or update files
+
+Read `references/consumer-guide.md` for the exact file templates. For
+each file below, check whether it already exists:
+
+- **If it exists**: read it first, then merge changes instead of
+  overwriting. Ask the user before making destructive edits to
+  hand-written sections.
+- **If it doesn't exist**: generate from the consumer-guide template,
+  adapted to what Steps 1–6 found.
+
+#### `package.json`
+
+Merge in dependencies and scripts. Don't overwrite existing.
+
+- Add `"type": "module"` if not present.
+- Only add `lightning-base-components` and `@salesforce-ux/design-system`
+  if the component tree uses `lightning/*` base components.
+- **Do not hardcode versions from the consumer guide.** Pinned versions
+  drift out of date (prerelease / alpha tags get unpublished). Look up
+  the current version with `npm view <pkg> version` and pin using
+  caret-major. At minimum, look up:
+  - `@salesforce/vite-plugin-lwc-ui-bundle`
+  - `@lwc/rollup-plugin`
+  - `lwc`
+  - `lightning-base-components` (if used)
+  - `@salesforce-ux/design-system` (if used)
+  - `vite`
+  - `vite-plugin-singlefile`
+
+  If a registry lookup fails (offline / auth issue), ask the user for
+  the version rather than falling back to the stale snippet.
+
+#### `vite.config.js`
+
+See "Step 2" in the consumer guide for the template.
+
+**Import providers from the plugin, do not reimplement them.** All
+provider names (`label`, `i18n`, `client`, `gate`, `accessCheck`,
+`primitiveUtils`, `lightningGraphql`, `lds`) must come from the `builtins`
+export of `@salesforce/vite-plugin-lwc-ui-bundle`. Calling them invokes
+the plugin's real runtime — which includes
+`lightning/graphql` wire adapter, `normalizeMcpResponse` envelope
+parsing, LDS wire adapter, and more. Hand-rolling any of them bypasses
+all that and breaks host integration (see
+`references/known-pitfalls.md#3`).
+
+```js
+import lwcVitePlugin, { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+// inside plugins -> lwcVitePlugin({ providers: [...] })
+builtins.lightningGraphql(),            // default tool name: "graphqlQuery"
+builtins.lightningGraphql({ toolName: "yourCustomTool" }), // override
+builtins.lds(),                         // default registry
+```
+
+Adapt based on earlier findings:
 
-### Step 6: Generate files
+- 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.lightningGraphql()` only if GraphQL was detected.
+- Include `builtins.lds()` if any component uses `lightning/uiRecordApi`.
+- Include `viteSingleFile()` — without it, `vite build` emits multi-file
+  output and the MCP host can't inline the bundle. See
+  `known-pitfalls.md#7` for the full config block.
+- Remove `npm: ["lightning-base-components"]` if no base components used.
 
-Read `references/consumer-guide.md` for the exact file templates. Generate these
-files, adapting the templates based on what you learned in Steps 1-5:
+**Tool names** (canonical list — referenced elsewhere):
 
-#### Files to create or update
+- `builtins.lds()` default for `lightning/uiRecordApi.getRecord`:
+  `getRecordMcpTool`. Override via
+  `builtins.lds({ "lightning/uiRecordApi": { getRecord: { toolName: "..." } } })`.
+- `builtins.lightningGraphql()` default: `graphqlQuery` (**not**
+  `"graphql"` or `"lightningGraphql"`). Override via
+  `builtins.lightningGraphql({ toolName: "..." })`.
 
-1. **`package.json`** — merge in dependencies and scripts (don't overwrite existing).
-   See "Step 1: Install Dependencies" in the consumer guide for the full dep list.
-   - Add `"type": "module"` if not present
-   - Only add `lightning-base-components` and `@salesforce-ux/design-system` if
-     the component tree uses `lightning/*` base components
-   - For Tier 2, also add `@salesforce/sdk-data` and `@salesforce/ui-bundle`
+Whatever tool names you settle on here **must match** the branches in
+`bootstrap.js` mocks (Step 8).
 
-2. **`vite.config.js`** — see "Step 2" in the consumer guide for the template.
-   Adapt based on your findings:
-   - Set `dirs` for the detected project structure (SFDX vs namespaced)
-   - Populate `builtins.label({...})` with values from Step 5
-   - Include `builtins.primitiveUtils()` if using `lightning-base-components`
-   - Include `builtins.lightningGraphql()` only if GraphQL was detected
-   - Remove `npm: ["lightning-base-components"]` if no base components used
-   - For Tier 2, add `lwcProxy()` before `lwcVitePlugin()` in the plugins array
+#### `index.html`
 
-3. **`index.html`** — see "Step 3" in the consumer guide.
+See "Step 3" in the consumer guide.
 
-4. **`bootstrap.js`** (project root) — see "Step 4" (Tier 1) or "Step 3" (Tier 2)
-   in the consumer guide. Replace the component name with the actual root from
-   Step 2. Remove the SLDS CSS import if `lightning-base-components` is not used.
+#### `bootstrap.js`
 
-#### Advanced options (use only when needed)
+This file has its own dedicated reference. Read
+`references/bootstrap-js-patterns.md` now for:
 
-The plugin accepts additional options for complex projects. Only add these if the
-component tree inspection reveals a need:
+- The skeleton structure (mock data → conditional shim → dynamic imports).
+- The tool-contract / envelope rules (what shape each mock branch must
+  return, and why double-wrapping breaks the graphql wire adapter).
+- Guidance on merging into an existing `bootstrap.js` or `main.js`.
+- Why production builds don't work with mocks (rolldown module-init
+  order defeats the shim; mocks are dev-server only).
 
-- **`stubs`**: Map bare module specifiers to stub files for core-only modules
-  not available off-platform (e.g., `{ "force/someModule": "./stubs/someModule.js" }`).
-  Needed when components import platform modules like `aura`, `logger`, or
-  `force/*` that don't exist outside Salesforce.
-- **`lwcOptions`**: Pass-through options for `@lwc/rollup-plugin` to configure
-  LWC compiler behavior (e.g., `{ enableDynamicComponents: true }`). Only needed
-  for projects using advanced LWC features like dynamic component creation.
-- **`passthroughRules`**: Let specific imports bypass the provider system. Each
-  rule has a `specifierPrefix` and `importerPattern` — when both match, the import
-  resolves normally. Useful when an npm package (like `lightning-base-components`)
-  has its own label definitions that shouldn't be intercepted by your label provider.
-- **`ignorePatterns`**: Specifier prefixes that providers should never intercept.
-  Defaults include `@salesforce/sdk-*` and `@salesforce/core`. Extend this if
-  you have imports that look like provider-handled patterns but should resolve
-  through normal Node module resolution.
+Use that reference to write the file; don't reconstruct the skeleton
+from memory.
 
-### Step 7: Install and build
+If the user chose **B** in Step 5 (no mocks), skip the shim entirely.
+`@wire(graphql)` / `@wire(getRecord)` will return no data under
+`npm run dev`, but the bundle will render correctly once deployed to a
+real MCP server as a UI resource — the host provides `window.openai`
+there.
 
-Run:
+#### Advanced plugin options
+
+Only add these if the component tree inspection reveals a need:
+
+- **`stubs`**: Map bare module specifiers to stub files for core-only
+  modules not available off-platform (e.g., `{ "force/someModule":
+"./stubs/someModule.js" }`). Needed when components import platform
+  modules like `aura`, `logger`, or `force/*`.
+- **`lwcOptions`**: Pass-through options for `@lwc/rollup-plugin`.
+  Only for advanced LWC features like dynamic component creation.
+- **`passthroughRules`**: Let specific imports bypass the provider
+  system. Useful when an npm package has its own label definitions that
+  shouldn't be intercepted.
+- **`ignorePatterns`**: Specifier prefixes that providers should never
+  intercept. Defaults include `@salesforce/sdk-*` and `@salesforce/core`.
+
+### Step 8: Install and build
 
 ```bash
 npm install
 npm run build
 ```
 
-If the build succeeds, report the output file size and open it:
+If the build succeeds, report the output file size:
 
 ```bash
 open dist/index.html
 ```
 
-If the build fails, diagnose and fix. See the "Common Errors" section in
-`references/consumer-guide.md` for the full troubleshooting guide. The most
-frequent issues:
+A correctly built `dist/index.html` is typically 100 KB+. A 1-2 KB file
+is the un-inlined stub (see `known-pitfalls.md#7`).
+
+If the build fails, diagnose via `references/known-pitfalls.md`. The most
+frequent issues have symptoms that map directly to specific entries:
 
-- **`Cannot read properties of undefined (reading 'isOpen')`**: Missing `gate()`
-  or `accessCheck()` provider — `lightning-base-components` use gates internally.
-- **`Rollup failed to resolve import "lightning/button"`**: Missing
-  `npm: ["lightning-base-components"]` in modules config.
-- **`Unhandled import: @salesforce/label/...`**: Expected warning — the plugin
-  returns the key as display text. Add overrides to `builtins.label()` to customize.
-- **`Top-level await is not available`**: Missing `target: "esnext"` in build config.
-- **`Rollup failed to resolve import "force/someModule"`**: Core-only module. Add
-  a stub via the `stubs` option.
-- **Component renders but looks unstyled**: Missing SLDS CSS import in bootstrap.js.
+- "Cannot find native binding" inside rolldown → pitfall #1 (Node)
+- "No matching version found for \<pkg\>" → pitfall #2 (stale dep pins)
+- Missing `isOpen` / missing `lightning/button` → pitfalls #9 / #7
+- `force/someModule` not resolved → pitfall #10
+- Component renders but unstyled → missing SLDS CSS import in
+  `bootstrap.js`
 
-### Step 8: Test dev server (Tier 2 only)
+### Step 9: Verify local dev run
 
-If lwcProxy was configured:
+Start the dev server:
 
 ```bash
 npm run dev
 ```
 
-Confirm the terminal shows `[lwc-proxy] Connected to https://...`. Open
-`http://localhost:5173` and verify GraphQL queries return real data.
+Open `http://localhost:5173` and confirm:
+
+- The root component renders.
+- If `bootstrap.js` has mocks, the wrappers show mapped data and wire
+  adapters return the mock payloads.
+- If no mocks were generated, chat wrappers show "Waiting for tool
+  output..." and `@wire` adapters return no data. That's expected; the
+  bundle will work once deployed to a real MCP server.
+
+If something renders wrong, check `references/known-pitfalls.md`. The
+most common dev-time issues are graphql wire adapters returning empty
+data (pitfalls #3, #4, #5) and mapper returning `null` on Avro-wrapped
+payloads (#6).
+
+The same compiled `dist/index.html` runs in ChatGPT — the guard in
+`bootstrap.js` ensures local mocks are skipped when the host provides
+the real bridge.
 
 ## Reference
 
 - npm: https://www.npmjs.com/package/@salesforce/vite-plugin-lwc-ui-bundle
 - README: https://github.com/salesforce-experience-platform-emu/webapps/tree/main/packages/vite-plugin-lwc-ui-bundle
 - Consumer Guide: https://github.com/salesforce-experience-platform-emu/webapps/blob/main/packages/vite-plugin-lwc-ui-bundle/docs/consumer-guide.md
+- Chat Wrapper Guide: https://github.com/salesforce-experience-platform-emu/webapps/blob/main/packages/vite-plugin-lwc-ui-bundle/docs/chat-wrapper-guide.md

package/skills/setup-lwc-vite-plugin/references/bootstrap-js-patterns.md

@@ -0,0 +1,215 @@
+# `bootstrap.js` Patterns
+
+Read this reference when writing or editing the project's `bootstrap.js`
+entry file. The skill dispatches here from Step 5 after deciding whether
+the project needs local-dev mocks.
+
+## Runtime contexts
+
+The goal is one compiled bundle that runs in either context:
+
+| Context                | Data source                                              | Notes                                                         |
+| ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
+| **Local dev**          | Mock `window.openai` shim in `bootstrap.js`              | `npm run dev` only. No org, no ChatGPT host.                  |
+| **ChatGPT / MCP host** | Host-provided `window.openai` (`callTool`, `toolOutput`) | Production. Same compiled bundle; mocks skipped by the guard. |
+
+The guard `if (!window.openai?.callTool)` is what makes the bundle work
+in both contexts: ChatGPT sets `window.openai` before loading the
+bundle, so the guard short-circuits and real host calls run.
+
+### ⚠ Mocks are for `npm run dev` only
+
+Do **not** expect `npm run build && open dist/index.html` to render mock
+data. Rollup hoists module-init code to the top of the bundle, which
+means `@salesforce/sdk-chat`'s `detectSurface()` runs _before_ the
+`main.js` / `bootstrap.js` body executes the `if (!window.openai?.
+callTool)` block. The SDK caches surface = `"WebApp"` and never observes
+the mock — LDS / graphql wire adapters silently return empty data.
+
+- Dev server (`npm run dev`) works because Vite serves modules on demand
+  in source order; the entry file runs first.
+- Production builds only target the real MCP host (where the host sets
+  `window.openai` before the bundle loads, so surface detection sees
+  `OpenAI` correctly).
+
+When previewing production bundles locally (rare), drive the wrappers
+by deploying the bundle to a real MCP server as a UI resource; the host
+provides `window.openai` and wire adapters work there.
+
+## Authoring pattern
+
+Structure `bootstrap.js` as three ordered sections:
+
+1. **Define mock data** at the top — hardcoded sample objects shaped like
+   the real tool output. This is the part the user edits per project.
+2. **Install the shim** inside the `if (!window.openai?.callTool)`
+   guard. The shim returns responses shaped like the real MCP server's
+   responses.
+3. **Dynamic-import LWC / SDK modules _after_ the shim** — SDK surface
+   detection runs at module load and reads `window.openai` once. Static
+   imports at the top of the file would fire the detection before the
+   shim is installed.
+
+### Handling an existing `bootstrap.js`
+
+If the project already has `bootstrap.js`, `main.js`, or another entry
+file, do not overwrite it. Merge instead:
+
+- **Static → dynamic imports:** If the existing file statically imports
+  `lwc` / LWC components, move those imports to dynamic `await
+import(...)` calls after the shim install.
+- **Existing `window.openai`:** If the file already installs a mock,
+  extend it rather than replace. Verify any guard already uses
+  `if (!window.openai?.callTool)` semantics.
+- **Multiple roots:** If the existing file mounts more than one root
+  component, keep all of them; just make sure the shim install runs
+  before any dynamic import.
+
+When in doubt, read the existing file top-to-bottom first, then ask the
+user whether to edit or replace.
+
+## Skeleton
+
+Generate the following skeleton, adapting the mocked tool branches to
+what was found in Step 4 of SKILL.md:
+
+```js
+// 1) Mock data — shape after the real tool's sample output
+const mockAccounts = [
+  { id: "001a", name: "Acme", industry: "Technology", employees: 8500 },
+  { id: "001b", name: "Global Media", industry: "Media", employees: 3200 },
+];
+
+// 2) Install the shim only when no host bridge exists.
+//    In ChatGPT / MCP context, the host already set window.openai, so
+//    this block is skipped and the real bridge is used.
+if (!window.openai?.callTool) {
+  window.openai = {
+    ...window.openai,
+    callTool: async (name, args) => {
+      // ── LDS (lightning/uiRecordApi.getRecord) ──────────────────────
+      if (name === "getRecordMcpTool") {
+        const a = mockAccounts.find((m) => m.id === args?.recordId);
+        if (!a) return { structuredContent: { data: null, error: "Record not found" } };
+        return {
+          structuredContent: {
+            data: {
+              fields: {
+                Name: { value: a.name },
+                Industry: { value: a.industry },
+              },
+            },
+          },
+        };
+      }
+
+      // ── lightning/graphql (default tool name "graphqlQuery") ───────
+      if (name === "graphqlQuery") {
+        const query = args?.query ?? "";
+        if (query.includes("Account")) {
+          return {
+            result: JSON.stringify({
+              data: {
+                uiapi: {
+                  query: {
+                    Account: {
+                      edges: mockAccounts.map((a) => ({
+                        node: {
+                          Id: a.id,
+                          Name: { value: a.name },
+                          Industry: { value: a.industry },
+                          NumberOfEmployees: { value: a.employees },
+                        },
+                      })),
+                    },
+                  },
+                },
+              },
+            }),
+          };
+        }
+        return { result: JSON.stringify({ data: {} }) };
+      }
+
+      console.warn("[mock] unhandled tool:", name, args);
+      return { result: JSON.stringify({ data: {} }) };
+    },
+  };
+
+  // For chat wrappers: seed toolOutput so the wrapper renders immediately
+  // in local dev instead of sitting in the "waiting" state.
+  window.openai.toolOutput = {
+    // Shape after the mapper's confirmed contract from Step 2d.
+    // e.g. { records: { "001a": { apiName: "Account", id: "001a", fields: { ... } } } }
+  };
+}
+
+// 3) Dynamic-import AFTER the shim so SDK surface detection sees the mock
+const { createElement } = await import("lwc");
+const { default: App } = await import("c/app");
+document.getElementById("app").appendChild(createElement("c-app", { is: App }));
+```
+
+## How response envelopes are unwrapped
+
+The plugin's providers call `callTool()` and pass the result through
+`normalizeMcpResponse()` before handing it to the wire adapter. That
+helper accepts two shapes:
+
+- `{ structuredContent: <payload> }` — MCP Apps surface shape. Returns
+  `<payload>` directly.
+- `{ result: "<JSON string>" }` — OpenAI surface shape. Returns
+  `JSON.parse(<string>)`. (If the parsed value is an MCP-style content
+  array with a `text` block, it parses the inner JSON too.)
+- Anything else — returned as-is.
+
+**The wire adapter reads its tool-specific fields off the unwrapped
+payload.** That payload must match the tool's contract:
+
+- `getRecordMcpTool` (LDS wire adapter) reads `.data` and `.error` off
+  the unwrapped payload. Mock payload: `{ data: {...}, error?: ... }`.
+- `graphqlQuery` (graphql wire adapter) reads `.data` and `.errors`
+  (plural, graphql-shaped) off the unwrapped payload. Mock payload:
+  `{ data: {...}, errors?: [...] }`.
+
+Either envelope can carry either tool's payload. The tool-contract shape
+is what matters. If the mock returns
+`{ structuredContent: { data: {...} } }` for graphql, the wrapper reads
+`.data` off `{ data: {...} }` which is **one level too shallow** — it
+gets the real data. But if the mock instead nests another level, like
+`{ structuredContent: { structuredContent: { data: {...} } } }` or
+`{ structuredContent: { data: { data: {...} } } }`, the wire adapter
+sees `data: { data: {...} }` and the wrapped component receives
+`undefined` as graphql data.
+
+Summary:
+
+- **Don't re-wrap.** One envelope layer (`structuredContent` _or_
+  `result`), then the raw tool contract. No nested layers.
+- **Mirror the real MCP server's response** when the mock differs from
+  what you see in production. Both envelopes work; pick whichever the
+  real server uses for the closest parity.
+
+## Graphql query-based branching
+
+Because the graphql wire adapter sends every query through a single tool
+(`graphqlQuery` by default), the mock needs to branch on the query
+string to return different data for different queries:
+
+```js
+if (name === "graphqlQuery") {
+  const query = args?.query ?? "";
+  if (query.includes("Account")) {
+    /* account edges */
+  }
+  if (query.includes("Contact")) {
+    /* contact edges */
+  }
+  if (query.includes("Opportunity")) {
+    /* opportunity edges */
+  }
+  return { result: JSON.stringify({ data: {} }) };
+}
+```
+
+`args.variables` is also available if queries differ only by variables.

package/skills/setup-lwc-vite-plugin/references/chat-wrapper-flow.md

@@ -0,0 +1,227 @@
+# Chat Wrapper Flow
+
+Walk through this reference whenever the user answers "Yes" to the Step 2
+question in SKILL.md (any component needs to be driven by ChatGPT/MCP tool
+output).
+
+The chat-wrapper pattern inserts a thin adapter layer between the host's
+`window.openai.toolOutput` and your LWC's `@api` props, so the component
+stays unchanged and works in both standalone and host contexts:
+
+```
+tool output ─▶ chatContextAdapter ─▶ <component>ChatMapper ─▶ <component>ChatWrapper ─▶ <your-core-component>
+```
+
+Run the following sub-steps for each component the user wants to wrap.
+Repeat for additional components if requested.
+
+**Reference implementation:** the `recordDetail` example under
+`examples/lwc-axl/lwc-records/sf/lwc/bcx/` in the webapps repo shows all
+three bundles working together:
+
+- `recordDetail/` — the unchanged core component.
+- `recordDetailChatMapper/` — the full UI-API → `@api` mapper, including
+  `unwrapPropertiesMap`, envelope fallbacks, and GraphQL-edge support.
+- `recordDetailChatWrapper/` — the wrapper with the initial-payload
+  debug log, loading/waiting states, and core-component mount.
+- `chatContextAdapter/` — reusable across all wrappers in a project.
+
+Copy patterns from those files when generating new bundles. The
+instructions below describe the decision points; the reference code
+fills in the exact implementation.
+
+## 2a. Pick the target component
+
+List the discovered components and ask:
+
+> "Which component should get a chat wrapper? (Can repeat for more.)"
+
+## 2b. Analyze the component's `@api` surface
+
+Read the target component's `.js` file and extract the required prop
+contract:
+
+1. Collect every `@api <name>` declaration (and `@api get <name>()` pairs).
+2. For each prop, note whether it's primitive, object, or array from its
+   usage (`wire({recordId: '$recordId', fields: '$fields'})` →
+   `recordId: string`, `fields: string[]`).
+3. Note any `@wire` usage that consumes these props — those are the props
+   the mapper must populate.
+
+Report what you found:
+
+> "`bcx-record-detail` requires these `@api` props:
+>
+> - `recordId` (string) — identifies the record being displayed
+> - `data` (object) — the record value (fields + apiName + id)
+> - `fieldMetadata` (object) — per-field metadata from the org's objectInfos
+> - `layout` (object) — per-record layout descriptor
+> - `picklistValues` (object, optional)
+> - `changedFields` (array, optional)
+> - `expandable` (boolean, optional)"
+
+## 2c. Ask about tool output structure
+
+The mapper shape depends entirely on what the tool returns. Ask the user
+for a sample payload:
+
+> "What does the MCP tool output look like for this component? Paste a
+> sample JSON payload, or give me the path to a sample file (e.g. an
+> example file in the MCP server repo)."
+
+Parse the payload and identify where each required prop lives. For
+`getRecordDetails`-shaped output:
+
+- `recordId` → `records[firstKey].id` (or the first key of the `records`
+  map)
+- `fields` (qualified names like `"Account.Name"`) → derived from
+  `records[firstKey].apiName` + keys of `records[firstKey].fields`
+- Full record data (for components that render the record directly) →
+  `records[firstKey]` (possibly after `normalizeFieldValue` unwrapping)
+
+Accept common envelope variations: raw tool output, `structuredContent`
+wrapper, nested `recordDetail`/`record_detail` keys.
+
+### `.properties` unwrap for map-shaped fields
+
+Some MCP hosts re-serialize `structuredContent` through an Avro /
+JSON-schema view that wraps every map-typed field in a `.properties` key.
+So instead of `records: { "001…": {...} }` the wrapper sees
+`records: { properties: { "001…": {...} } }`. Without unwrapping, the
+mapper's "first key" becomes the literal string `"properties"`.
+
+**Rule:** every map-shaped field (`records`, `fields`, `objectInfos`,
+`layouts`, …) must go through an `unwrapPropertiesMap(value)` helper that
+returns `value.properties` when it looks like a properties-wrapped map,
+else `value`. Apply this before reading keys or selecting the first
+entry. The helper is small and always the same:
+
+```js
+function unwrapPropertiesMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (value.properties && typeof value.properties === "object") return value.properties;
+  return value;
+}
+```
+
+## 2d. Confirm the mapping with the user
+
+Before generating files, show the planned mapping and ask for confirmation:
+
+> "Here's how I'll map tool output → `bcx-record-detail` props:
+>
+> | Prop           | Source in tool output                                          |
+> | -------------- | -------------------------------------------------------------- |
+> | recordId       | `records[firstKey].id` (falls back to first key)               |
+> | data           | `records[firstKey]` (after `unwrapPropertiesMap` on `.fields`) |
+> | fieldMetadata  | `objectInfos[apiName]`                                         |
+> | layout         | `layouts[apiName][recordTypeId].Full.View`                     |
+> | picklistValues | derived from `objectInfos[apiName].fields[*].picklistValues`   |
+>
+> Fallback: if the envelope wraps in `structuredContent` or
+> `recordDetail`/`record_detail`, unwrap before reading.
+>
+> Does this mapping look correct? (yes / tell me what to change)"
+
+Iterate until the user confirms. Do not proceed to file generation until
+confirmation is explicit. Users frequently want to tweak field coverage or
+add aliases at this step — taking the correction once saves a round of
+re-generation.
+
+## 2e. Generate the three bundles
+
+Create three LWC bundles (adjust folder layout for the project type
+detected in SKILL.md Step 1 — SFDX uses `force-app/main/default/lwc/`,
+off-core uses `src/lwc/<namespace>/`):
+
+### `chatContextAdapter/` — one per project
+
+Reusable across every chat-wrapped component. Exports
+`accessToolOutput()` and `subscribeToolOutput(listener)`. Reads
+`window.openai.toolOutput`, subscribes to `openai:set_globals` and
+`ui/notifications/tool-result` postMessages. If `chatContextAdapter`
+already exists in the project, reuse it — don't regenerate.
+
+Copy the reference implementation verbatim from
+`docs/chat-wrapper-guide.md` in the plugin repo. It's stable and should
+not be customized.
+
+### `<component>ChatMapper/` — one per wrapped component
+
+Exports `map<Component>ToolOutput(toolOutput)` that returns the confirmed
+prop shape or `null` for invalid payloads. Keep it:
+
+- **Pure and side-effect free** — no console logs, no DOM access.
+- **Tolerant of envelope variations** — unwrap `structuredContent`,
+  `recordDetail`, `record_detail` where applicable.
+- **Null-on-invalid** — never throw. The wrapper renders a waiting state
+  on `null`.
+
+Always include the `unwrapPropertiesMap(value)` helper (see 2c) and call
+it before reading any map-shaped field.
+
+### `<component>ChatWrapper/` — one per wrapped component
+
+On `connectedCallback`:
+
+1. Call `subscribeToolOutput()` to listen for updates.
+2. Call `accessToolOutput()` for the initial state.
+3. Apply both through the mapper.
+
+Renders:
+
+- `loading` state while initializing
+- `waiting` state when the mapper returns `null`
+- the wrapped component with mapped props when mapping succeeds
+
+**Important debugging aid:** Always log the raw initial tool output in
+the wrapper's `connectedCallback`:
+
+```js
+const initial = accessToolOutput();
+console.log(`[${wrapperName}] initial tool output`, initial);
+```
+
+The shape varies by host (Avro/`.properties` wrap, `structuredContent`
+envelope, nested `recordDetail`, etc.). Seeing the real payload once tells
+the user exactly which keys their mapper needs to unwrap. Leave this log
+in by default — removing it makes iterative debugging much harder for
+little benefit.
+
+Each bundle needs the matching `.js-meta.xml` (SFDX) with
+`<isExposed>false</isExposed>` unless the user needs it exposed.
+
+### Announce the wrapper tag name
+
+Mention the wrapper tag name so it can be referenced in Step 3 if the
+user wants the wrapper itself (or a parent embedding it) as the root:
+
+> "Created `bcx-record-detail-chat-wrapper`. You can drop
+> `<bcx-record-detail-chat-wrapper>` into any parent (e.g. your root app
+> component), or pick it directly as the root in the next step."
+
+## Debugging the mapping
+
+If the wrapper stays in the "Waiting for tool output..." state even
+though the tool fires, **the initial-payload log is the single most
+useful debugging tool.** Check the DevTools console (or the MCP Jam
+widget log) for the `[…ChatWrapper] initial tool output` line and compare
+the actual shape to what the mapper expects.
+
+Common reasons the mapper returns `null`:
+
+- **`.properties` wrap:** `records` arrives as
+  `{ properties: { "001…": {...} } }` instead of `{ "001…": {...} }`.
+  Fix: add/verify `unwrapPropertiesMap` on every map-shaped field.
+- **Envelope mismatch:** payload is wrapped in `structuredContent`,
+  `recordDetail`, or `record_detail` and the mapper reads from the top
+  level. Fix: add the missing unwrap branch in `unwrapEnvelope`.
+- **Key-alias mismatch:** camelCase vs snake_case (`recordId` vs
+  `record_id`, `objectInfos` vs `object_infos`).
+- **Empty fields map:** the tool returned a record with no `fields`,
+  usually because the tool's `outputSchema` doesn't project the fields
+  the component needs. Fix the tool, not the mapper.
+
+Once the real shape is visible, update the mapper's unwraps to match,
+and confirm the mapper returns a non-null object by checking that the
+`[…ChatWrapper] mapper returned null` warning disappears.

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

@@ -0,0 +1,215 @@
+# Known Pitfalls
+
+Consolidated list of bugs and confusions that have surfaced in real
+consumer projects. Read this when setting up a new project, and consult
+it when debugging a project that's already set up but misbehaving.
+
+Each entry has a **Symptom**, **Cause**, and **Fix** so the skill can
+recognize an issue from console output alone.
+
+## 1. Node version mismatch (Vite 8 + rolldown)
+
+**Symptom:** `vite build` crashes inside `rolldown` with "Cannot find
+native binding. npm has a bug related to optional dependencies."
+
+**Cause:** Vite 8.x requires Node `^20.19.0 || >=22.12.0`. On older
+Node 20.x (e.g. 20.14) the rolldown optional dependency for the
+platform binary doesn't install, producing an opaque error instead of a
+clear engine mismatch.
+
+**Fix:** Either upgrade Node (`nvm install 20.19` or `22`), or pin
+`vite@^7` and a compatible `@lwc/rollup-plugin` major.
+
+## 2. Hardcoded dep versions (prerelease / alpha unpublished)
+
+**Symptom:** `npm install` fails with
+`No matching version found for <pkg>@^1.28.17-alpha` or similar.
+
+**Cause:** The consumer guide's package.json snippet includes example
+version pins (like `^1.28.17-alpha` for `lightning-base-components`).
+Prerelease tags get unpublished from the registry over time.
+
+**Fix:** Look up the current published version with
+`npm view <pkg> version` and pin to `^<that>` instead of copying from
+the snippet.
+
+## 3. Hand-rolled `lightningGraphql` in `vite.config.js`
+
+**Symptom:** `@wire(graphql)` returns empty data; console shows
+`No window.openai.callTool available` or a hand-written
+`[lightningGraphql] ...` log message.
+
+**Cause:** The generator treated the "include `builtins.lightningGraphql()`"
+instruction as "write a provider called `lightningGraphql`" and inlined
+a custom provider factory in `vite.config.js` instead of importing
+`builtins` from the plugin. The hand-rolled version bypasses the
+plugin's real runtime (which handles `globalThis.__sfdc_sdk__`,
+`getChatSDK()`, and `normalizeMcpResponse`).
+
+**Fix:** Replace with:
+
+```js
+import lwcVitePlugin, { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
+// inside lwcVitePlugin({ providers: [...] })
+builtins.lightningGraphql(),
+builtins.lds(),
+```
+
+Same rule for `lds` and every other provider — never hand-write them.
+
+## 4. `this`-binding bug in `lightning/graphql` runtime
+
+**Symptom:** `@wire(graphql)` with a class-based SDK (e.g.
+`@salesforce/sdk-data`'s `WebApp`) silently emits
+`{data: undefined, errors: [TypeError]}`; component falls through to an
+empty state.
+
+**Cause:** Plugin versions ≤ 1.132.0 destructure `graphql` off
+`globalThis.__sfdc_sdk__` before calling it, which loses the method's
+`this` binding. The method internally calls `this.fetch(...)` and
+blows up.
+
+**Fix:** Fixed in webapps PR #477 (plugin version > 1.132.0). Until the
+fix ships in a release, add this to `bootstrap.js` after creating the
+SDK:
+
+```js
+sdk.graphql = sdk.graphql.bind(sdk);
+sdk.fetch = sdk.fetch.bind(sdk);
+globalThis.__sfdc_sdk__ = sdk;
+```
+
+## 5. Wrong tool name in mock branch (graphql foot-gun)
+
+**Symptom:** `@wire(graphql)` returns empty data even though the mock
+shim is installed; console shows "[mock] unhandled tool: graphqlQuery"
+or the graphql mock branch is never entered.
+
+**Cause:** The wire adapter calls `callTool("graphqlQuery", { query,
+variables })` by default, but the mock branches on `"graphql"` or
+`"lightningGraphql"`.
+
+**Fix:** Name the branch `"graphqlQuery"` (literal default) — or pass
+the same custom name to both the provider and the mock:
+
+```js
+// vite.config.js
+builtins.lightningGraphql({ toolName: "myCustomGraphql" }),
+
+// bootstrap.js
+if (name === "myCustomGraphql") { /* ... */ }
+```
+
+The vite-config tool name and the mock-branch string must match
+exactly.
+
+## 6. `.properties` wrap in Avro/JSON-schema-serialized tool output
+
+**Symptom:** Chat wrapper renders "Waiting for tool output..." even
+though the host fired tool output; mapper's `Object.keys(records)[0]`
+returns the literal string `"properties"`.
+
+**Cause:** Some MCP hosts re-serialize `structuredContent` through an
+Avro / JSON-schema view that wraps every map-typed field in a
+`.properties` key. So `records: { "001…": {...} }` becomes
+`records: { properties: { "001…": {...} } }`.
+
+**Fix:** Every map-shaped field (`records`, `fields`, `objectInfos`,
+`layouts`, …) must go through an `unwrapPropertiesMap(value)` helper
+before reading keys:
+
+```js
+function unwrapPropertiesMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (value.properties && typeof value.properties === "object") return value.properties;
+  return value;
+}
+```
+
+Apply this in every mapper that reads map-shaped fields.
+
+## 7. Missing `viteSingleFile()`
+
+**Symptom:** `dist/index.html` is 1-2 KB (just a stub); component
+doesn't render when opened locally.
+
+**Cause:** `viteSingleFile()` is not in the Vite plugins array, so
+Vite emits its default multi-file output (HTML stub + separate
+`assets/*.js` + `assets/*.css`).
+
+**Fix:** Add to `vite.config.js`:
+
+```js
+import { viteSingleFile } from "vite-plugin-singlefile";
+// ...
+plugins: [
+    lwcVitePlugin({ /* ... */ }),
+    viteSingleFile(),
+],
+build: {
+    target: "esnext",
+    cssCodeSplit: false,
+    rollupOptions: { output: { inlineDynamicImports: true } },
+},
+```
+
+A correctly built `dist/index.html` is typically 100 KB+.
+
+## 8. `@salesforce/label/...` warnings
+
+**Symptom:** Build warns `Unhandled import: @salesforce/label/...`,
+but the build succeeds.
+
+**Cause:** Expected. The plugin returns the label key as display text
+when no override is provided.
+
+**Fix:** Not a bug. Add overrides to `builtins.label({...})` to
+customize the displayed text.
+
+## 9. Missing gate / accessCheck providers with lightning-base-components
+
+**Symptom:** Build fails with `Cannot read properties of undefined
+(reading 'isOpen')`.
+
+**Cause:** `lightning-base-components` use `@salesforce/gate/*` and
+`@salesforce/accessCheck/*` internally, even if user code doesn't
+import them.
+
+**Fix:** Always include `builtins.gate()` and `builtins.accessCheck()`
+(and `builtins.primitiveUtils()`) whenever `lightning-base-components`
+is in the modules config.
+
+## 10. Core-only imports
+
+**Symptom:** `Rollup failed to resolve import "force/someModule"` (or
+`aura`, `logger`, etc.).
+
+**Cause:** Platform-only modules that don't exist off-platform.
+
+**Fix:** Provide a stub via the plugin's `stubs` option:
+
+```js
+lwcVitePlugin({
+  // ...
+  stubs: { "force/someModule": "./stubs/someModule.js" },
+});
+```
+
+Point the stub at a minimal file that exports the shape the importer
+expects.
+
+## 11. Mock data doesn't work in production build
+
+**Symptom:** `npm run build && open dist/index.html` shows wrappers in
+"Waiting" state; `sdk.callTool is not available on this surface` in
+the console. Dev server (`npm run dev`) works fine.
+
+**Cause:** Rollup hoists module-init code to the top of the bundle.
+`@salesforce/sdk-chat`'s top-level `const surface = detectSurface()`
+runs before `main.js` / `bootstrap.js` installs the mock, so the SDK
+caches `surface = "WebApp"` forever.
+
+**Fix:** Not supported — mocks are for `npm run dev` only. Production
+builds only target real MCP hosts (where the host sets `window.openai`
+before the bundle loads, so surface detection correctly resolves to
+`OpenAI`). See `bootstrap-js-patterns.md` for the full explanation.