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

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

@@ -0,0 +1,189 @@
+const permState = {
+  cache: /* @__PURE__ */ new Map(),
+  pending: /* @__PURE__ */ new Set(),
+  scheduled: false,
+  subscribers: /* @__PURE__ */ new Map()
+};
+const customPermState = {
+  cache: /* @__PURE__ */ new Map(),
+  pending: /* @__PURE__ */ new Set(),
+  scheduled: false,
+  subscribers: /* @__PURE__ */ new Map()
+};
+const i18nState = {
+  cache: /* @__PURE__ */ new Map(),
+  pending: /* @__PURE__ */ new Set(),
+  scheduled: false,
+  subscribers: /* @__PURE__ */ new Map()
+};
+let probePromise = null;
+const I18N_GRAPHQL_KEYS = [
+  "lang",
+  "dir",
+  "locale",
+  "currency",
+  "timeZone",
+  "firstDayOfWeek",
+  "defaultCalendar",
+  "defaultNumberingSystem"
+];
+const I18N_NUMERIC_KEYS = /* @__PURE__ */ new Set(["firstDayOfWeek"]);
+const PERM_QUERY = `query UserPermissions($names: [String!]!) {
+  uiapi { platform { userPermissions(names: $names) { name hasAccess } } }
+}`;
+const CUSTOM_PERM_QUERY = `query CustomPermissions($names: [String!]!) {
+  uiapi { platform { customPermissions(names: $names) { name hasAccess } } }
+}`;
+const I18N_QUERY = `query I18n {
+  uiapi { platform { i18n { ${I18N_GRAPHQL_KEYS.join(" ")} } } }
+}`;
+async function detectPlatformPath() {
+  try {
+    const response = await graphqlFetch(`{ uiapi { platform { __typename } } }`, {});
+    return !!response?.data?.uiapi?.platform;
+  } catch {
+    return false;
+  }
+}
+function getApiShape() {
+  if (!probePromise) {
+    probePromise = detectPlatformPath();
+  }
+  return probePromise;
+}
+function notify(state, key, value) {
+  if (state.cache.get(key) === value) return;
+  state.cache.set(key, value);
+  const set = state.subscribers.get(key);
+  if (set) for (const cb of set) cb(value);
+}
+function subscribeTo(state, key, current, callback) {
+  let set = state.subscribers.get(key);
+  if (!set) {
+    set = /* @__PURE__ */ new Set();
+    state.subscribers.set(key, set);
+  }
+  set.add(callback);
+  callback(current());
+  return () => {
+    state.subscribers.get(key)?.delete(callback);
+  };
+}
+function getUserPermission(name, fallback) {
+  if (permState.cache.has(name)) return permState.cache.get(name);
+  permState.cache.set(name, fallback);
+  permState.pending.add(name);
+  schedulePermFetch(permState, PERM_QUERY, "userPermissions");
+  return fallback;
+}
+function subscribeUserPermission(name, fallback, cb) {
+  return subscribeTo(permState, name, () => getUserPermission(name, fallback), cb);
+}
+function getCustomPermission(name, fallback) {
+  if (customPermState.cache.has(name)) return customPermState.cache.get(name);
+  customPermState.cache.set(name, fallback);
+  customPermState.pending.add(name);
+  schedulePermFetch(customPermState, CUSTOM_PERM_QUERY, "customPermissions");
+  return fallback;
+}
+function subscribeCustomPermission(name, fallback, cb) {
+  return subscribeTo(customPermState, name, () => getCustomPermission(name, fallback), cb);
+}
+function schedulePermFetch(state, query, field) {
+  if (state.scheduled) return;
+  state.scheduled = true;
+  Promise.resolve().then(() => {
+    state.scheduled = false;
+    if (state.pending.size === 0) return;
+    const names = [...state.pending];
+    state.pending.clear();
+    fetchPermissions(state, query, field, names);
+  });
+}
+async function fetchPermissions(state, query, field, names) {
+  if (!await getApiShape()) return;
+  for (let i = 0; i < names.length; i += 100) {
+    const batch = names.slice(i, i + 100);
+    try {
+      const response = await graphqlFetch(query, { names: batch });
+      const records = response?.data?.uiapi?.platform?.[field] ?? [];
+      for (const rec of records) {
+        if (!rec) continue;
+        notify(state, rec.name, !!rec.hasAccess);
+      }
+    } catch (e) {
+      console.warn(`[platform-graphql] ${field} fetch failed:`, e);
+    }
+  }
+}
+function getI18n(key, fallback) {
+  if (i18nState.cache.has(key)) return i18nState.cache.get(key);
+  i18nState.cache.set(key, fallback);
+  scheduleI18nFetch();
+  return fallback;
+}
+function subscribeI18n(key, fallback, cb) {
+  return subscribeTo(i18nState, key, () => getI18n(key, fallback), cb);
+}
+function scheduleI18nFetch() {
+  if (i18nState.scheduled) return;
+  i18nState.scheduled = true;
+  Promise.resolve().then(() => {
+    i18nState.scheduled = false;
+    fetchI18n();
+  });
+}
+async function fetchI18n() {
+  if (!await getApiShape()) return;
+  try {
+    const response = await graphqlFetch(I18N_QUERY, {});
+    const payload = response?.data?.uiapi?.platform?.i18n;
+    if (!payload) return;
+    for (const k of I18N_GRAPHQL_KEYS) {
+      if (payload[k] == null) continue;
+      const value = I18N_NUMERIC_KEYS.has(k) ? Number(payload[k]) : String(payload[k]);
+      notify(i18nState, k, value);
+    }
+  } catch (e) {
+    console.warn("[platform-graphql] i18n fetch failed:", e);
+  }
+}
+async function graphqlFetch(query, variables) {
+  let createDataSDK;
+  try {
+    ({ createDataSDK } = await import("@salesforce/platform-sdk"));
+  } catch {
+    console.warn(
+      "[platform-graphql] @salesforce/platform-sdk is not available. Using fallback values."
+    );
+    return {};
+  }
+  if (typeof createDataSDK !== "function") return {};
+  const sdk = await createDataSDK();
+  if (!sdk.graphql) return {};
+  const result = await sdk.graphql.query({ query, variables });
+  return { data: result.data, errors: result.errors };
+}
+function __resetForTest() {
+  for (const s of [permState, customPermState, i18nState]) {
+    s.cache.clear();
+    s.pending.clear();
+    s.scheduled = false;
+    s.subscribers.clear();
+  }
+  probePromise = null;
+}
+export {
+  I18N_GRAPHQL_KEYS,
+  I18N_NUMERIC_KEYS,
+  __resetForTest,
+  getApiShape,
+  getCustomPermission,
+  getI18n,
+  getUserPermission,
+  graphqlFetch,
+  subscribeCustomPermission,
+  subscribeI18n,
+  subscribeUserPermission
+};
+//# sourceMappingURL=runtime.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sources":["../../../src/providers/platform-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 * Shared runtime for scoped modules that resolve via `uiapi.platform.*` GraphQL\n * off-core through the Platform Data SDK:\n *\n * - `@salesforce/userPermission/<Name>`   → `userPermissions(names:)` → boolean\n * - `@salesforce/accessCheck/<Name>`      → `userPermissions(names:)` → boolean\n * - `@salesforce/customPermission/<Name>` → `customPermissions(names:)` → boolean\n * - `@salesforce/i18n/<key>`              → `i18n { ... }` (locale identity)\n *\n * Like the labels runtime, each accessor returns a synchronous value (the\n * build-time fallback) immediately and schedules a batched GraphQL fetch; the\n * resolved org value lands in the cache and notifies subscribers. Components opt\n * into reactivity via the generated module's `subscribe(cb)` export.\n */\n\ninterface DomainState<V> {\n\tcache: Map<string, V>;\n\tpending: Set<string>;\n\tscheduled: boolean;\n\tsubscribers: Map<string, Set<(value: V) => void>>;\n}\n\nconst permState: DomainState<boolean> = {\n\tcache: new Map(),\n\tpending: new Set(),\n\tscheduled: false,\n\tsubscribers: new Map(),\n};\nconst customPermState: DomainState<boolean> = {\n\tcache: new Map(),\n\tpending: new Set(),\n\tscheduled: false,\n\tsubscribers: new Map(),\n};\n// i18n values are mostly strings, but a few keys are contractually numeric\n// (see I18N_NUMERIC_KEYS) so the domain is `string | number`.\nconst i18nState: DomainState<string | number> = {\n\tcache: new Map(),\n\tpending: new Set(),\n\tscheduled: false,\n\tsubscribers: new Map(),\n};\n\nlet probePromise: Promise<boolean> | null = null;\n\n/** i18n scalar fields exposed by `uiapi.platform.i18n` (locale identity). */\nexport const I18N_GRAPHQL_KEYS = [\n\t\"lang\",\n\t\"dir\",\n\t\"locale\",\n\t\"currency\",\n\t\"timeZone\",\n\t\"firstDayOfWeek\",\n\t\"defaultCalendar\",\n\t\"defaultNumberingSystem\",\n] as const;\n\n/**\n * i18n identity keys whose `@salesforce/i18n/*` contract is a NUMBER, not a\n * string (e.g. `firstDayOfWeek` is `1`=Mon … `7`=Sun). These are coerced with\n * `Number()` rather than `String()` so consumers that do arithmetic or strict\n * equality on them keep working. All other identity keys are strings.\n */\nexport const I18N_NUMERIC_KEYS = new Set<string>([\"firstDayOfWeek\"]);\n\nconst PERM_QUERY = `query UserPermissions($names: [String!]!) {\n  uiapi { platform { userPermissions(names: $names) { name hasAccess } } }\n}`;\n\nconst CUSTOM_PERM_QUERY = `query CustomPermissions($names: [String!]!) {\n  uiapi { platform { customPermissions(names: $names) { name hasAccess } } }\n}`;\n\nconst I18N_QUERY = `query I18n {\n  uiapi { platform { i18n { ${I18N_GRAPHQL_KEYS.join(\" \")} } } }\n}`;\n\nasync function detectPlatformPath(): Promise<boolean> {\n\ttry {\n\t\tconst response = (await graphqlFetch(`{ uiapi { platform { __typename } } }`, {})) as {\n\t\t\tdata?: { uiapi?: { platform?: unknown } };\n\t\t};\n\t\treturn !!response?.data?.uiapi?.platform;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport function getApiShape(): Promise<boolean> {\n\tif (!probePromise) {\n\t\tprobePromise = detectPlatformPath();\n\t}\n\treturn probePromise;\n}\n\nfunction notify<V>(state: DomainState<V>, key: string, value: V): void {\n\tif (state.cache.get(key) === value) return;\n\tstate.cache.set(key, value);\n\tconst set = state.subscribers.get(key);\n\tif (set) for (const cb of set) cb(value);\n}\n\nfunction subscribeTo<V>(\n\tstate: DomainState<V>,\n\tkey: string,\n\tcurrent: () => V,\n\tcallback: (value: V) => void,\n): () => void {\n\tlet set = state.subscribers.get(key);\n\tif (!set) {\n\t\tset = new Set();\n\t\tstate.subscribers.set(key, set);\n\t}\n\tset.add(callback);\n\tcallback(current());\n\treturn () => {\n\t\tstate.subscribers.get(key)?.delete(callback);\n\t};\n}\n\n// ── Permissions (userPermissions / accessCheck) ──────────────────────────────\n\nexport function getUserPermission(name: string, fallback: boolean): boolean {\n\tif (permState.cache.has(name)) return permState.cache.get(name)!;\n\tpermState.cache.set(name, fallback);\n\tpermState.pending.add(name);\n\tschedulePermFetch(permState, PERM_QUERY, \"userPermissions\");\n\treturn fallback;\n}\n\nexport function subscribeUserPermission(\n\tname: string,\n\tfallback: boolean,\n\tcb: (v: boolean) => void,\n): () => void {\n\treturn subscribeTo(permState, name, () => getUserPermission(name, fallback), cb);\n}\n\nexport function getCustomPermission(name: string, fallback: boolean): boolean {\n\tif (customPermState.cache.has(name)) return customPermState.cache.get(name)!;\n\tcustomPermState.cache.set(name, fallback);\n\tcustomPermState.pending.add(name);\n\tschedulePermFetch(customPermState, CUSTOM_PERM_QUERY, \"customPermissions\");\n\treturn fallback;\n}\n\nexport function subscribeCustomPermission(\n\tname: string,\n\tfallback: boolean,\n\tcb: (v: boolean) => void,\n): () => void {\n\treturn subscribeTo(customPermState, name, () => getCustomPermission(name, fallback), cb);\n}\n\ninterface PermissionRecord {\n\tname: string;\n\thasAccess: boolean;\n}\n\nfunction schedulePermFetch(\n\tstate: DomainState<boolean>,\n\tquery: string,\n\tfield: \"userPermissions\" | \"customPermissions\",\n): void {\n\tif (state.scheduled) return;\n\tstate.scheduled = true;\n\tPromise.resolve().then(() => {\n\t\tstate.scheduled = false;\n\t\tif (state.pending.size === 0) return;\n\t\tconst names = [...state.pending];\n\t\tstate.pending.clear();\n\t\tfetchPermissions(state, query, field, names);\n\t});\n}\n\nasync function fetchPermissions(\n\tstate: DomainState<boolean>,\n\tquery: string,\n\tfield: \"userPermissions\" | \"customPermissions\",\n\tnames: string[],\n): Promise<void> {\n\t// platform.* path is required for these fields; if absent, keep fallbacks.\n\tif (!(await getApiShape())) return;\n\tfor (let i = 0; i < names.length; i += 100) {\n\t\tconst batch = names.slice(i, i + 100);\n\t\ttry {\n\t\t\tconst response = (await graphqlFetch(query, { names: batch })) as {\n\t\t\t\tdata?: { uiapi?: { platform?: Record<string, PermissionRecord[]> } };\n\t\t\t};\n\t\t\tconst records = response?.data?.uiapi?.platform?.[field] ?? [];\n\t\t\tfor (const rec of records) {\n\t\t\t\t// An unknown/invalid name yields a `null` array entry (with a\n\t\t\t\t// matching ValidationError in `errors`), positionally aligned with\n\t\t\t\t// the requested name. Skip it so one bad name in a mixed batch does\n\t\t\t\t// not abort resolution for the valid names alongside it — their\n\t\t\t\t// fallbacks would otherwise silently stick.\n\t\t\t\tif (!rec) continue;\n\t\t\t\tnotify(state, rec.name, !!rec.hasAccess);\n\t\t\t}\n\t\t} catch (e) {\n\t\t\tconsole.warn(`[platform-graphql] ${field} fetch failed:`, e);\n\t\t}\n\t}\n}\n\n// ── i18n (locale identity) ───────────────────────────────────────────────────\n\nexport function getI18n(key: string, fallback: string | number): string | number {\n\tif (i18nState.cache.has(key)) return i18nState.cache.get(key)!;\n\ti18nState.cache.set(key, fallback);\n\t// Any i18n key triggers a single fetch that resolves ALL identity fields at\n\t// once, so there is no per-key pending set to track (unlike permissions).\n\tscheduleI18nFetch();\n\treturn fallback;\n}\n\nexport function subscribeI18n(\n\tkey: string,\n\tfallback: string | number,\n\tcb: (v: string | number) => void,\n): () => void {\n\treturn subscribeTo(i18nState, key, () => getI18n(key, fallback), cb);\n}\n\nfunction scheduleI18nFetch(): void {\n\tif (i18nState.scheduled) return;\n\ti18nState.scheduled = true;\n\tPromise.resolve().then(() => {\n\t\ti18nState.scheduled = false;\n\t\tfetchI18n();\n\t});\n}\n\nasync function fetchI18n(): Promise<void> {\n\tif (!(await getApiShape())) return;\n\ttry {\n\t\tconst response = (await graphqlFetch(I18N_QUERY, {})) as {\n\t\t\tdata?: { uiapi?: { platform?: { i18n?: Record<string, unknown> } } };\n\t\t};\n\t\tconst payload = response?.data?.uiapi?.platform?.i18n;\n\t\tif (!payload) return;\n\t\tfor (const k of I18N_GRAPHQL_KEYS) {\n\t\t\tif (payload[k] == null) continue;\n\t\t\t// firstDayOfWeek (and any other numeric-contract key) stays a number;\n\t\t\t// everything else is a string. See I18N_NUMERIC_KEYS.\n\t\t\tconst value = I18N_NUMERIC_KEYS.has(k) ? Number(payload[k]) : String(payload[k]);\n\t\t\tnotify(i18nState, k, value);\n\t\t}\n\t} catch (e) {\n\t\tconsole.warn(\"[platform-graphql] i18n fetch failed:\", e);\n\t}\n}\n\n// ── Shared SDK transport ─────────────────────────────────────────────────────\n\n/**\n * Fetch through the Platform Data SDK — surface-aware (direct session GraphQL on\n * WebApp/MFE, window.openai bridge on OpenAI/MCP). Returns `{}` when no data\n * surface is available, so callers keep their build-time fallbacks.\n */\nexport async function graphqlFetch(\n\tquery: string,\n\tvariables: Record<string, unknown>,\n): Promise<unknown> {\n\tlet createDataSDK:\n\t\t| ((options?: unknown) => Promise<{\n\t\t\t\tgraphql?: { query: (opts: unknown) => Promise<{ data?: unknown; errors?: unknown }> };\n\t\t  }>)\n\t\t| undefined;\n\ttry {\n\t\t({ createDataSDK } = (await import(\"@salesforce/platform-sdk\")) as unknown as {\n\t\t\tcreateDataSDK: typeof createDataSDK;\n\t\t});\n\t} catch {\n\t\tconsole.warn(\n\t\t\t\"[platform-graphql] @salesforce/platform-sdk is not available. Using fallback values.\",\n\t\t);\n\t\treturn {};\n\t}\n\tif (typeof createDataSDK !== \"function\") return {};\n\tconst sdk = await createDataSDK();\n\tif (!sdk.graphql) return {};\n\tconst result = await sdk.graphql.query({ query, variables });\n\treturn { data: result.data, errors: result.errors };\n}\n\n/** Reset internal state — exposed for tests only. */\nexport function __resetForTest(): void {\n\tfor (const s of [permState, customPermState, i18nState]) {\n\t\ts.cache.clear();\n\t\ts.pending.clear();\n\t\ts.scheduled = false;\n\t\ts.subscribers.clear();\n\t}\n\tprobePromise = null;\n}\n"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import { UIBundleTarget } from '@salesforce/ui-bundle/app';
 import { Plugin } from 'vite';
 export interface Provider {
     prefix?: string;
@@ -27,6 +28,34 @@ export interface LwcVitePluginOptions {
     ignorePatterns?: string[];
     passthroughRules?: PassthroughRule[];
     bundle?: boolean;
+    /**
+     * Write the bundle's `*.uibundle-meta.xml` at build time, deriving its
+     * `<target>` element from {@link GenerateMetaXmlOptions.target}. The target
+     * is configured here, NOT in `ui-bundle.json` — the platform's manifest
+     * schema rejects a `target` field. `ui-bundle.json` (at the project root) is
+     * read only for the master-label fallback (`manifest.name`).
+     *
+     * Generation runs only when a `target` is supplied; without one there is
+     * nothing to contribute over a hand-authored meta XML. Enabled by default
+     * but inert until you pass a `target`. Set to `false` to disable outright,
+     * or pass an object to configure the target, paths, and metadata.
+     */
+    generateMetaXml?: boolean | GenerateMetaXmlOptions;
+}
+export interface GenerateMetaXmlOptions {
+    /**
+     * Deployment target for the bundle: "Experience", "CustomApplication", or
+     * "AppLauncher" (an alias for CustomApplication). Drives the generated
+     * `*.uibundle-meta.xml` `<target>`. Supplied here rather than in
+     * `ui-bundle.json` because the platform's manifest schema rejects a `target`
+     * field. When omitted, no `<target>` is emitted (and nothing is generated
+     * unless a description/label is otherwise needed).
+     */
+    target?: UIBundleTarget;
+    manifestPath?: string;
+    bundleName?: string;
+    description?: string;
+    overwriteExisting?: boolean;
 }
 export interface DiscoveredModule {
     name: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,MAAM,WAAW,QAAQ;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC5B,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAC9B,GAAG,CAAC,EAAE,CAAC,MAAM,GAAG,eAAe,CAAC,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC/B,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,eAAe;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACpC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,SAAS,CAAC,EAAE,CAAC,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,sBAAsB;IACtC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,MAAM,WAAW,QAAQ;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC5B,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAC9B,GAAG,CAAC,EAAE,CAAC,MAAM,GAAG,eAAe,CAAC,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC/B,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,eAAe;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACpC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,SAAS,CAAC,EAAE,CAAC,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;CACnD;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,sBAAsB;IACtC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC"}

package/docs/consumer-guide.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/vite-plugin-lwc-ui-bundle",
-  "version": "11.13.2",
+  "version": "11.15.0",
   "description": "Vite plugin for compiling LWC components into static bundles for off-platform and MCP use",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "Salesforce",
@@ -49,7 +49,7 @@
     "skills"
   ],
   "scripts": {
-    "build": "vite build && vite build --mode runtime-lds && vite build --mode runtime-labels-graphql",
+    "build": "vite build && vite build --mode runtime-lds && vite build --mode runtime-labels-graphql && vite build --mode runtime-platform-graphql",
     "clean": "rm -rf dist",
     "dev": "vite build --watch",
     "test": "vitest run",
@@ -74,9 +74,9 @@
   },
   "peerDependencies": {
     "@lwc/rollup-plugin": "^9.0.0",
-    "@salesforce/platform-sdk": "^11.13.2",
+    "@salesforce/platform-sdk": "^11.15.0",
     "@salesforce/state-managers-uiapi": "^0.31.0",
-    "@salesforce/ui-bundle": "^11.13.2",
+    "@salesforce/ui-bundle": "^11.15.0",
     "lwc": "^9.0.0",
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
     "zod": "^3.23.8"
@@ -100,7 +100,7 @@
   "devDependencies": {
     "@conduit-client/bindings-utils": "3.19.6",
     "@conduit-client/command-base": "3.19.6",
-    "@salesforce/platform-sdk": "^11.13.2",
+    "@salesforce/platform-sdk": "^11.15.0",
     "@types/ws": "^8.5.12",
     "typescript": "^5.9.3",
     "vite": "^7.0.0",

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

@@ -157,7 +157,15 @@ Starting from the root component, trace the dependency tree:
      providers because base components use these modules internally even
      if user code doesn't
    - `@salesforce/gate/*`, `@salesforce/accessCheck/*` → handled by
-     those providers
+     those providers (accessCheck deny-defaults to `false`, no per-name
+     config required)
+   - `@salesforce/userPermission/<Name>`, `@salesforce/customPermission/<Name>`
+     → **collect every `<Name>`.** These are named per-user permissions:
+     the default `platformGraphql()` provider **fails the build** unless
+     each imported name has a first-paint value declared in
+     `userPermissionDefaults` / `customPermissionDefaults`. Record the
+     exact names so Step 7 can generate them (default them to `false`
+     unless the user says otherwise). See `known-pitfalls.md#17`.
    - `@salesforce/i18n/*` → `i18n` provider
    - `@salesforce/client/*` → `client` provider (provides `formFactor`
      based on viewport width)
@@ -227,6 +235,13 @@ Check in this order:
      present (the default registry covers all three specifiers)
    - Step 4 found any `@salesforce/i18n/*` → `builtins.i18n()` must be
      present
+   - Step 4 found any `@salesforce/userPermission/<Name>` or
+     `@salesforce/customPermission/<Name>` → the default
+     `platformGraphql()` provider must declare a first-paint value for
+     **each** name in `userPermissionDefaults` / `customPermissionDefaults`,
+     or the build throws. Use the `defaultProviders({ platformGraphql: {…} })`
+     helper so the rest of the registry stays default. See
+     `references/known-pitfalls.md#17`.
    - Step 4 found any `@salesforce/client/*` → `builtins.client()` must
      be present
    - `modules.npm` includes `lightning-base-components` (or
@@ -465,6 +480,34 @@ Adapt based on earlier findings:
 
 - Set `dirs` for the detected project structure (SFDX vs namespaced).
 - Populate `builtins.label({...})` with values from Step 6.
+- **Declare a first-paint value for every named permission Step 4 found.**
+  Each `@salesforce/userPermission/<Name>` / `@salesforce/customPermission/<Name>`
+  import needs an entry, or the build throws (`known-pitfalls.md#17`).
+  Prefer the `defaultProviders()` helper so you configure only this while
+  keeping the rest of the default registry:
+
+  ```js
+  import lwcVitePlugin, { defaultProviders } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+  lwcVitePlugin({
+    modules: {
+      /* ... */
+    },
+    providers: defaultProviders({
+      platformGraphql: {
+        userPermissionDefaults: { ApiEnabled: false, CustomizeApplication: false },
+        customPermissionDefaults: { My_Custom_Perm: false },
+      },
+    }),
+  });
+  ```
+
+  Default each to `false` unless the user wants a `true` first paint; note
+  the resolved org value only reaches the DOM if the component imports the
+  module's `subscribe()` export (keep a plain default import if the same
+  source also deploys on-platform). `@salesforce/accessCheck/*` needs no
+  such config — it deny-defaults to `false`.
+
 - Include `builtins.primitiveUtils()` if using `lightning-base-components`.
 - Include `builtins.lds()` if any component uses `lightning/uiRecordApi`,
   `lightning/uiObjectInfoApi`, `lightning/graphql`, or any of the

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

@@ -440,3 +440,60 @@ the plugin with `livePreview({ debug: true })` (or run with plugin debug
 logging) — it logs the underlying import error. Note the bridge is a
 local-dev convenience only; its absence never affects the compiled
 bundle.
+
+## 17. Build fails: named permission imported with no first-paint value
+
+**Symptom:** `vite build` (or `npm run dev`) fails with:
+
+```
+[platform-graphql] @salesforce/userPermission/ApiEnabled was imported but
+has no first-paint value configured. A permission is per-user runtime
+state, so the plugin refuses to silently render a fabricated `false`. …
+```
+
+**Cause:** A component imports `@salesforce/userPermission/<Name>` or
+`@salesforce/customPermission/<Name>`, but no value was declared for that
+name. A named permission is an assertion about **per-user runtime state**;
+a plain default import binds the value **once** at module-eval time and
+never updates on its own (only the module's `subscribe()` export does).
+So a silently-defaulted `false` would render a permanent, wrong answer —
+even when the GraphQL fetch **succeeds**. Rather than guess, the plugin
+requires you to state the value shown before the org responds. (This is
+**not** the same as `@salesforce/accessCheck/*`, which is a feature gate
+and safely deny-defaults to `false` — see pitfall #8.)
+
+**Fix:** Declare each imported permission's first-paint value via the
+`defaultProviders()` helper (keeps every other default in place):
+
+```js
+import lwcVitePlugin, { defaultProviders } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+lwcVitePlugin({
+  modules: {
+    /* ... */
+  },
+  providers: defaultProviders({
+    platformGraphql: {
+      userPermissionDefaults: { ApiEnabled: false, CustomizeApplication: false },
+      customPermissionDefaults: { My_Custom_Perm: false },
+    },
+  }),
+});
+```
+
+Use `false` unless you have a specific reason to render `true` before the
+fetch resolves. To reflect the **resolved** org value in the DOM, import
+the module's `subscribe(callback)` export and assign to a reactive field:
+
+```js
+import apiEnabled, { subscribe } from "@salesforce/userPermission/ApiEnabled";
+// this.apiEnabled = apiEnabled;                    // first paint (configured)
+// connectedCallback() { subscribe(v => this.apiEnabled = v); }  // corrects in DOM
+```
+
+If the same component must also deploy on-platform (where the scoped
+module has no `subscribe` export), keep the plain default import.
+
+**Prevention:** SKILL.md Step 4 flags every `@salesforce/userPermission/*`
+and `@salesforce/customPermission/*` import so the generated config
+declares its first-paint value up front.