@wildo-ai/saas-frontend-lib 1.1.2 → 1.1.4

package/dist/esm/core/external-providers/ProviderFilePickerHost.js

@@ -0,0 +1,114 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The framework side of a provider file picker: choose a provider, load its
+ * component on demand, mount it, and hold whatever it returns to the contract
+ * it declared.
+ *
+ * This is the seam issue #380 exists to create. Before it, a provider could not
+ * contribute a component at all, and resolution beside the registry was
+ * first-match — so a Drive picker and a Dropbox picker could not coexist for one
+ * field, and which one won depended on map order.
+ *
+ * ## What this component decides and what it deliberately does not
+ *
+ * It decides NOTHING about which provider is right. `useProviderComponentChoices`
+ * returns every live provider that carries a picker, in a stable order, and this
+ * host renders them for a person to choose between. A framework that picked one
+ * would be making a product decision in a lookup table, which is the defect the
+ * registry was rebuilt to remove.
+ *
+ * It also does not interpret a selection. Routing a `REMOTE_REFERENCE` to the
+ * application's executor door, or uploading a `BROWSER_READABLE_FILE`, is the
+ * FIELD's job — this host hands up an outcome that is already checked against
+ * the provider's declaration, so the field can branch on a `kind` it can trust.
+ *
+ * ## Chrome
+ *
+ * There is none beyond a list of buttons and the mounted component. Every label
+ * is an i18n KEY resolved by the caller: a provider's display name is
+ * locale-bound copy, and freezing it into a framework component is how a missing
+ * translation becomes invisible.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { BUILTIN_PROVIDER_CAPABILITY } from '@wildo-ai/saas-models/public-runtime';
+import { useApplication } from '../../core/runtime/useApplication.js';
+import { getManualCallsHttpClient } from '../../core/requests/wildo-http-client-manual-calls.frontend.service.js';
+import { ProviderComponentStatus, useProviderComponent, useProviderComponentChoices, } from '../../core/components-registry/useProviderComponent.frontend.hooks.js';
+import { receiveProviderFileSelections, } from './provider-file-selection.frontend.utils.js';
+const FILE_PICKER_CAPABILITY = BUILTIN_PROVIDER_CAPABILITY.FRONTEND_FILE_PICKER;
+export function ProviderFilePickerHost(props) {
+    const { providerComponentRegistry, frontendProviderRegistry } = useApplication();
+    const allChoices = useProviderComponentChoices(FILE_PICKER_CAPABILITY);
+    const acceptedStorages = props.acceptedStorages;
+    const choices = useMemo(() => allChoices.filter((choice) => choice.fileStorage === undefined || (acceptedStorages?.includes(choice.fileStorage) ?? false)), [allChoices, acceptedStorages]);
+    const [chosen, setChosen] = useState(
+    // A single provider needs no chooser: presenting one option as a choice is
+    // a click that carries no information. Several is a genuine decision and is
+    // never made here.
+    () => (choices.length === 1 ? choices[0]?.providerRef : undefined));
+    const soleProviderRef = choices.length === 1 ? choices[0]?.providerRef : undefined;
+    useEffect(() => {
+        // The initializer above runs ONCE. In today's runtime that is enough — the
+        // registry is populated before application services are handed out and the
+        // context gates children on them — but a host whose only correctness
+        // argument lives in another file's ordering is one refactor from rendering
+        // nothing at all: with a single late-arriving provider there would be no
+        // chooser (length is 1) and no picker (nothing chosen).
+        if (soleProviderRef !== undefined && chosen === undefined)
+            setChosen(soleProviderRef);
+    }, [soleProviderRef, chosen]);
+    const { status, Component } = useProviderComponent(FILE_PICKER_CAPABILITY, chosen);
+    const publicConfig = useMemo(() => {
+        if (chosen === undefined)
+            return {};
+        return frontendProviderRegistry?.getProviderByRef(chosen)?.publicConfig ?? {};
+    }, [chosen, frontendProviderRegistry]);
+    // Destructured, not read off `props` inside the callbacks: `props` is a fresh
+    // object every render, so depending on it would give both callbacks a new
+    // identity on every parent render — and a picker keying an effect on
+    // `onSelect` would then re-run its whole open sequence each time.
+    const { onSelect, onCancel, onProviderFailure } = props;
+    const handleSelect = useCallback((selections) => {
+        if (chosen === undefined)
+            return;
+        const outcome = receiveProviderFileSelections({
+            providerRef: chosen,
+            descriptor: providerComponentRegistry?.describe(FILE_PICKER_CAPABILITY, chosen),
+            selections,
+        });
+        if (outcome.rejections.length > 0) {
+            onProviderFailure?.({ providerRef: chosen, rejections: outcome.rejections });
+            return;
+        }
+        onSelect(chosen, outcome.accepted);
+    }, [chosen, providerComponentRegistry, onSelect, onProviderFailure]);
+    const handleError = useCallback((error) => {
+        if (chosen === undefined)
+            return;
+        onProviderFailure?.({ providerRef: chosen, error });
+    }, [chosen, onProviderFailure]);
+    const handleCancel = useCallback(() => onCancel?.(), [onCancel]);
+    // The caller's own token for the chosen provider, from the one door that hands one out (#394 P4).
+    // Resolved lazily — a picker asks when it opens, never before — and `undefined` when nothing is
+    // connected, which the picker reports in its own words. Never read from `publicConfig`, which is
+    // served to every browser.
+    const getAccessToken = useCallback(async () => {
+        if (chosen === undefined)
+            return undefined;
+        const granted = await getManualCallsHttpClient().getProviderConnectionAccessToken(chosen);
+        return granted?.accessToken;
+    }, [chosen]);
+    if (choices.length === 0)
+        return null;
+    const chooser = props.renderChooser?.({ choices, chosen, choose: setChosen })
+        ?? defaultChooser({ choices, chosen, choose: setChosen });
+    // `Component` is typed as the registry's opaque component: this package must
+    // not make the registry know any capability's props. The narrowing happens
+    // HERE, where the capability is known, and it is the only cast in the path.
+    const Picker = Component;
+    return (_jsxs(_Fragment, { children: [choices.length > 1 ? chooser : null, status === ProviderComponentStatus.READY && Picker !== null && chosen !== undefined ? (_jsx(Picker, { providerRef: chosen, publicConfig: publicConfig, constraints: props.constraints, getAccessToken: getAccessToken, onSelect: handleSelect, onCancel: handleCancel, onError: handleError })) : null] }));
+}
+function defaultChooser(input) {
+    return (_jsx("div", { role: "group", children: input.choices.map((choice) => (_jsx("button", { type: "button", "aria-pressed": choice.providerRef === input.chosen, onClick: () => input.choose(choice.providerRef), children: choice.displayName ?? choice.providerRef }, choice.providerRef))) }));
+}
+//# sourceMappingURL=ProviderFilePickerHost.js.map

package/dist/esm/core/external-providers/ProviderFilePickerHost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderFilePickerHost.js","sourceRoot":"","sources":["../../../../src/core/external-providers/ProviderFilePickerHost.tsx"],"names":[],"mappings":"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","sourcesContent":["/**\n * The framework side of a provider file picker: choose a provider, load its\n * component on demand, mount it, and hold whatever it returns to the contract\n * it declared.\n *\n * This is the seam issue #380 exists to create. Before it, a provider could not\n * contribute a component at all, and resolution beside the registry was\n * first-match — so a Drive picker and a Dropbox picker could not coexist for one\n * field, and which one won depended on map order.\n *\n * ## What this component decides and what it deliberately does not\n *\n * It decides NOTHING about which provider is right. `useProviderComponentChoices`\n * returns every live provider that carries a picker, in a stable order, and this\n * host renders them for a person to choose between. A framework that picked one\n * would be making a product decision in a lookup table, which is the defect the\n * registry was rebuilt to remove.\n *\n * It also does not interpret a selection. Routing a `REMOTE_REFERENCE` to the\n * application's executor door, or uploading a `BROWSER_READABLE_FILE`, is the\n * FIELD's job — this host hands up an outcome that is already checked against\n * the provider's declaration, so the field can branch on a `kind` it can trust.\n *\n * ## Chrome\n *\n * There is none beyond a list of buttons and the mounted component. Every label\n * is an i18n KEY resolved by the caller: a provider's display name is\n * locale-bound copy, and freezing it into a framework component is how a missing\n * translation becomes invisible.\n */\n\nimport React, { useCallback, useEffect, useMemo, useState } from 'react';\nimport type { ProviderCapability } from '@wildo-ai/saas-models';\nimport { BUILTIN_PROVIDER_CAPABILITY } from '@wildo-ai/saas-models/public-runtime';\nimport type { FileStorageAccepted } from '@wildo-ai/saas-models/public-runtime';\nimport type {\n  ProviderFilePickerConstraints,\n  ProviderFilePickerProps,\n  ProviderFileSelection,\n} from '@wildo-ai/saas-models/public-runtime';\nimport { useApplication } from '~wildo-frontend-lib/core/runtime/useApplication';\nimport { getManualCallsHttpClient } from '~wildo-frontend-lib/core/requests/wildo-http-client-manual-calls.frontend.service';\nimport {\n  ProviderComponentStatus,\n  useProviderComponent,\n  useProviderComponentChoices,\n  type ProviderComponentChoice,\n} from '~wildo-frontend-lib/core/components-registry/useProviderComponent.frontend.hooks';\nimport {\n  receiveProviderFileSelections,\n  type ProviderFileSelectionRejection,\n} from './provider-file-selection.frontend.utils';\n\nconst FILE_PICKER_CAPABILITY = BUILTIN_PROVIDER_CAPABILITY.FRONTEND_FILE_PICKER as ProviderCapability;\n\nexport interface ProviderFilePickerHostProps {\n  readonly constraints: ProviderFilePickerConstraints;\n  /**\n   * The field's `z_file({ storageAccepted })` (#394 P5). A provider whose picker\n   * fronts a storage (a `REMOTE_REFERENCE` picker — the file stays at the\n   * vendor) is offered only when this names that storage, because the link it\n   * produces lands in that storage and the backend refuses it otherwise. A\n   * provider declaring no storage delivers bytes into the field's own storage\n   * and is offered regardless. Undefined — the field declared nothing — accepts\n   * no vendor storage: the default storage is the framework's.\n   */\n  readonly acceptedStorages?: ReadonlyArray<FileStorageAccepted>;\n  /**\n   * Called with selections that have already been checked against the chosen\n   * provider's declaration, so every `kind` here is the one that provider said\n   * it would produce.\n   */\n  onSelect(providerRef: string, selections: readonly ProviderFileSelection[]): void;\n  onCancel?(): void;\n  /**\n   * A provider's picker failed, or contradicted its own declaration. Both reach\n   * here because both mean the same thing to a user — this picker did not work —\n   * while the distinction that matters to a developer is in the rejection.\n   */\n  onProviderFailure?(failure: { readonly providerRef: string; readonly error?: Error; readonly rejections?: readonly ProviderFileSelectionRejection[] }): void;\n  /**\n   * Renders the chooser. Supplied by the caller, because a chooser is chrome and\n   * this package's components are injected rather than hard-coded. The default\n   * below is plain buttons: enough to be usable, not enough to be a design.\n   */\n  renderChooser?(input: {\n    readonly choices: readonly ProviderComponentChoice[];\n    readonly chosen: string | undefined;\n    choose(providerRef: string): void;\n  }): React.ReactNode;\n}\n\nexport function ProviderFilePickerHost(props: ProviderFilePickerHostProps): React.ReactElement | null {\n  const { providerComponentRegistry, frontendProviderRegistry } = useApplication();\n  const allChoices = useProviderComponentChoices(FILE_PICKER_CAPABILITY);\n  const acceptedStorages = props.acceptedStorages;\n  const choices = useMemo(\n    () => allChoices.filter((choice) => choice.fileStorage === undefined || (acceptedStorages?.includes(choice.fileStorage) ?? false)),\n    [allChoices, acceptedStorages],\n  );\n  const [chosen, setChosen] = useState<string | undefined>(\n    // A single provider needs no chooser: presenting one option as a choice is\n    // a click that carries no information. Several is a genuine decision and is\n    // never made here.\n    () => (choices.length === 1 ? choices[0]?.providerRef : undefined),\n  );\n\n  const soleProviderRef = choices.length === 1 ? choices[0]?.providerRef : undefined;\n  useEffect(() => {\n    // The initializer above runs ONCE. In today's runtime that is enough — the\n    // registry is populated before application services are handed out and the\n    // context gates children on them — but a host whose only correctness\n    // argument lives in another file's ordering is one refactor from rendering\n    // nothing at all: with a single late-arriving provider there would be no\n    // chooser (length is 1) and no picker (nothing chosen).\n    if (soleProviderRef !== undefined && chosen === undefined) setChosen(soleProviderRef);\n  }, [soleProviderRef, chosen]);\n  const { status, Component } = useProviderComponent(FILE_PICKER_CAPABILITY, chosen);\n\n  const publicConfig = useMemo(() => {\n    if (chosen === undefined) return {};\n    return frontendProviderRegistry?.getProviderByRef(chosen as never)?.publicConfig ?? {};\n  }, [chosen, frontendProviderRegistry]);\n\n  // Destructured, not read off `props` inside the callbacks: `props` is a fresh\n  // object every render, so depending on it would give both callbacks a new\n  // identity on every parent render — and a picker keying an effect on\n  // `onSelect` would then re-run its whole open sequence each time.\n  const { onSelect, onCancel, onProviderFailure } = props;\n\n  const handleSelect = useCallback(\n    (selections: readonly ProviderFileSelection[]) => {\n      if (chosen === undefined) return;\n\n      const outcome = receiveProviderFileSelections({\n        providerRef: chosen,\n        descriptor: providerComponentRegistry?.describe(FILE_PICKER_CAPABILITY, chosen),\n        selections,\n      });\n\n      if (outcome.rejections.length > 0) {\n        onProviderFailure?.({ providerRef: chosen, rejections: outcome.rejections });\n        return;\n      }\n\n      onSelect(chosen, outcome.accepted);\n    },\n    [chosen, providerComponentRegistry, onSelect, onProviderFailure],\n  );\n\n  const handleError = useCallback(\n    (error: Error) => {\n      if (chosen === undefined) return;\n      onProviderFailure?.({ providerRef: chosen, error });\n    },\n    [chosen, onProviderFailure],\n  );\n\n  const handleCancel = useCallback(() => onCancel?.(), [onCancel]);\n\n  // The caller's own token for the chosen provider, from the one door that hands one out (#394 P4).\n  // Resolved lazily — a picker asks when it opens, never before — and `undefined` when nothing is\n  // connected, which the picker reports in its own words. Never read from `publicConfig`, which is\n  // served to every browser.\n  const getAccessToken = useCallback(async (): Promise<string | undefined> => {\n    if (chosen === undefined) return undefined;\n    const granted = await getManualCallsHttpClient().getProviderConnectionAccessToken(chosen);\n    return granted?.accessToken;\n  }, [chosen]);\n\n  if (choices.length === 0) return null;\n\n  const chooser = props.renderChooser?.({ choices, chosen, choose: setChosen })\n    ?? defaultChooser({ choices, chosen, choose: setChosen });\n\n  // `Component` is typed as the registry's opaque component: this package must\n  // not make the registry know any capability's props. The narrowing happens\n  // HERE, where the capability is known, and it is the only cast in the path.\n  const Picker = Component as React.ComponentType<ProviderFilePickerProps> | null;\n\n  return (\n    <>\n      {choices.length > 1 ? chooser : null}\n      {status === ProviderComponentStatus.READY && Picker !== null && chosen !== undefined ? (\n        <Picker\n          providerRef={chosen}\n          publicConfig={publicConfig}\n          constraints={props.constraints}\n          getAccessToken={getAccessToken}\n          onSelect={handleSelect}\n          onCancel={handleCancel}\n          onError={handleError}\n        />\n      ) : null}\n    </>\n  );\n}\n\nfunction defaultChooser(input: {\n  readonly choices: readonly ProviderComponentChoice[];\n  readonly chosen: string | undefined;\n  choose(providerRef: string): void;\n}): React.ReactNode {\n  return (\n    <div role=\"group\">\n      {input.choices.map((choice) => (\n        <button\n          key={choice.providerRef}\n          type=\"button\"\n          aria-pressed={choice.providerRef === input.chosen}\n          onClick={() => input.choose(choice.providerRef)}\n        >\n          {/* The authored fallback, NOT a translation — a surface that has an\n              i18n service should pass `renderChooser` and resolve the key. */}\n          {choice.displayName ?? choice.providerRef}\n        </button>\n      ))}\n    </div>\n  );\n}\n"]}

package/dist/esm/core/external-providers/frontend-provider-display-label.frontend.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontend-provider-display-label.frontend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/core/external-providers/frontend-provider-display-label.frontend.utils.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,iCAAiC;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,uCAAuC,CACrD,SAAS,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,GAClD,MAAM,EAAE,CASV;AAED;;;;;;;;;GASG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,iCAAiC,GACvC,MAAM,CASR"}
+{"version":3,"file":"frontend-provider-display-label.frontend.utils.d.ts","sourceRoot":"","sources":["../../../../src/core/external-providers/frontend-provider-display-label.frontend.utils.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,iCAAiC;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,uCAAuC,CACrD,SAAS,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,GAClD,MAAM,EAAE,CASV;AAED;;;;;;;;;GASG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,iCAAiC,GACvC,MAAM,CASR"}

package/dist/esm/core/external-providers/frontend-provider-display-label.frontend.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontend-provider-display-label.frontend.utils.js","sourceRoot":"","sources":["../../../../../src/core/external-providers/frontend-provider-display-label.frontend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,sCAAsC,CAAC;AAcxF;;;;;;GAMG;AACH,MAAM,UAAU,uCAAuC,CACrD,SAAmD;IAEnD,OAAO,KAAK,CAAC,IAAI,CACf,IAAI,GAAG,CACL,SAAS,CAAC,MAAM,CACd,CAAC,QAAQ,EAAsB,EAAE,CAC/B,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CACtD,CACF,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mCAAmC,CACjD,KAAwC;IAExC,MAAM,QAAQ,GAAG,KAAK,CAAC,mBAAmB,IAAI,gCAAgC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAClG,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,CAAC;IAE/C,IAAI,UAAU,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,OAAO,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,WAAW,CAAC;AACvE,CAAC","sourcesContent":["import { buildProviderDisplayNameLabelKey } from '@wildo-ai/saas-models/public-runtime';\n\nexport interface FrontendProviderDisplayLabelInput {\n  providerRef: string;\n  displayName?: string;\n  displayNameLabelKey?: string;\n  /**\n   * Optional explicit fallback when the caller wants a non-ref technical\n   * fallback (for example a brand label sourced from a static map).\n   */\n  fallbackLabel?: string;\n  translate?: (key: string) => string;\n}\n\n/**\n * Collect unique, non-empty provider display-label keys for `useI18n({ keys })`.\n *\n * The helper intentionally stays tiny and framework-agnostic: call sites can\n * build whatever provider view-model they need, then hand only the optional\n * label keys here to get the deduped request list.\n */\nexport function collectFrontendProviderDisplayLabelKeys(\n  labelKeys: ReadonlyArray<string | undefined | null>,\n): string[] {\n  return Array.from(\n    new Set(\n      labelKeys.filter(\n        (labelKey): labelKey is string =>\n          typeof labelKey === 'string' && labelKey.length > 0,\n      ),\n    ),\n  );\n}\n\n/**\n * Resolve a user-facing provider label without freezing locale-bound copy into\n * provider metadata or generated artifacts.\n *\n * Order of preference:\n * 1. Translation resolved from the provider label key.\n * 2. Authored display name on the provider metadata.\n * 3. Optional caller-supplied fallback label.\n * 4. Raw provider ref as the technical last resort.\n */\nexport function resolveFrontendProviderDisplayLabel(\n  input: FrontendProviderDisplayLabelInput,\n): string {\n  const labelKey = input.displayNameLabelKey ?? buildProviderDisplayNameLabelKey(input.providerRef);\n  const translated = input.translate?.(labelKey);\n\n  if (translated && translated !== labelKey) {\n    return translated;\n  }\n\n  return input.displayName ?? input.fallbackLabel ?? input.providerRef;\n}\n"]}
+{"version":3,"file":"frontend-provider-display-label.frontend.utils.js","sourceRoot":"","sources":["../../../../src/core/external-providers/frontend-provider-display-label.frontend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,sCAAsC,CAAC;AAcxF;;;;;;GAMG;AACH,MAAM,UAAU,uCAAuC,CACrD,SAAmD;IAEnD,OAAO,KAAK,CAAC,IAAI,CACf,IAAI,GAAG,CACL,SAAS,CAAC,MAAM,CACd,CAAC,QAAQ,EAAsB,EAAE,CAC/B,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CACtD,CACF,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mCAAmC,CACjD,KAAwC;IAExC,MAAM,QAAQ,GAAG,KAAK,CAAC,mBAAmB,IAAI,gCAAgC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAClG,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,CAAC;IAE/C,IAAI,UAAU,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,OAAO,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,WAAW,CAAC;AACvE,CAAC","sourcesContent":["import { buildProviderDisplayNameLabelKey } from '@wildo-ai/saas-models/public-runtime';\n\nexport interface FrontendProviderDisplayLabelInput {\n  providerRef: string;\n  displayName?: string;\n  displayNameLabelKey?: string;\n  /**\n   * Optional explicit fallback when the caller wants a non-ref technical\n   * fallback (for example a brand label sourced from a static map).\n   */\n  fallbackLabel?: string;\n  translate?: (key: string) => string;\n}\n\n/**\n * Collect unique, non-empty provider display-label keys for `useI18n({ keys })`.\n *\n * The helper intentionally stays tiny and framework-agnostic: call sites can\n * build whatever provider view-model they need, then hand only the optional\n * label keys here to get the deduped request list.\n */\nexport function collectFrontendProviderDisplayLabelKeys(\n  labelKeys: ReadonlyArray<string | undefined | null>,\n): string[] {\n  return Array.from(\n    new Set(\n      labelKeys.filter(\n        (labelKey): labelKey is string =>\n          typeof labelKey === 'string' && labelKey.length > 0,\n      ),\n    ),\n  );\n}\n\n/**\n * Resolve a user-facing provider label without freezing locale-bound copy into\n * provider metadata or generated artifacts.\n *\n * Order of preference:\n * 1. Translation resolved from the provider label key.\n * 2. Authored display name on the provider metadata.\n * 3. Optional caller-supplied fallback label.\n * 4. Raw provider ref as the technical last resort.\n */\nexport function resolveFrontendProviderDisplayLabel(\n  input: FrontendProviderDisplayLabelInput,\n): string {\n  const labelKey = input.displayNameLabelKey ?? buildProviderDisplayNameLabelKey(input.providerRef);\n  const translated = input.translate?.(labelKey);\n\n  if (translated && translated !== labelKey) {\n    return translated;\n  }\n\n  return input.displayName ?? input.fallbackLabel ?? input.providerRef;\n}\n"]}

package/dist/esm/core/external-providers/frontend-provider-registry.frontend.service.d.ts

@@ -1,23 +1,41 @@
 /**
  * `FrontendProviderRegistryFrontendService` — frontend-side API for
- * reading the per-app provider catalog hydrated from the backend.
+ * reading the per-app provider catalog.
  *
- * Hydrated once at app start from
- * `FrontendAppBootstrapPayload.frontendProviders` (Phase 6 wiring); the
- * payload is built by `FrontendBootstrapBackendService.buildPayload()`,
- * which is the SOLE cross-facet seam where backend code projects a
- * `BackendProviderModule` into a `FrontendProviderEntry`. From the
- * frontend's perspective this service is the only legal way to read
- * provider information — direct imports from
- * `@wildo-ai/external-connectors-private/*` are a TypeScript error
- * because the frontend bundle does not depend on that package.
+ * The registry is built from TWO channels and no longer from a cast (#332):
  *
- * See `.cursor/plans/provider-registration-refactor-implementation-plan.md`
- * §Phase 0.8.
+ *   - **DATA** — `FrontendAppBootstrapPayload.frontendProviders`, hydrated
+ *     once at app start from `/application-config`. Built by
+ *     `FrontendBootstrapBackendService.buildPayload()`, which is the SOLE
+ *     cross-facet seam where backend code projects a `BackendProviderModule`
+ *     into a `FrontendProviderEntry`. It is the authority on WHICH providers
+ *     this frontend service has turned on, in this environment.
+ *   - **CODE** — `generatedFrontendProviderModules` from the app's own
+ *     `src/generated/frontend-providers.generated.ts`, written by
+ *     `wildo config sync` and passed in through `StartApplicationOptions`. It
+ *     is the authority on what code this bundle contains — an SDK loader, a
+ *     public-config validator — none of which JSON could ever carry.
+ *
+ * From the frontend's perspective this service is still the only legal way to
+ * read provider information — direct imports from
+ * `@wildo-ai/external-connectors-private/*` are a TypeScript error because the
+ * frontend bundle does not depend on that package.
  */
 import type { FrontendProvidersBlock, ProviderCapability } from '@wildo-ai/saas-models';
 import type { ProviderProtocol } from '@wildo-ai/saas-models/public-runtime';
-import type { FrontendAppProviderModule, FrontendAppProviderRef } from '@wildo-ai/external-connectors-public/app';
+import type { FrontendAppProviderModule, FrontendAppProviderRef, FrontendProviderHydrationDiagnostic, GeneratedAppProviderModules } from '@wildo-ai/external-connectors-public/app';
+/**
+ * Everything the registry needs to join the two channels.
+ *
+ * `modules` absent is the ordinary case for an application that declares no
+ * package-shipped frontend provider: `wildo config sync` writes no generated
+ * file, so there is nothing to import and nothing to pass.
+ */
+export interface FrontendProviderRegistryHydrationInput {
+    readonly entries?: FrontendProvidersBlock;
+    readonly modules?: GeneratedAppProviderModules;
+    readonly onDiagnostic?: (diagnostic: FrontendProviderHydrationDiagnostic) => void;
+}
 export interface FrontendProviderRegistryFrontendService {
     /** Hydrated from `FrontendAppBootstrapPayload` at app start. */
     getProviderByRef(ref: FrontendAppProviderRef): FrontendAppProviderModule | undefined;
@@ -29,12 +47,12 @@ export interface FrontendProviderRegistryFrontendService {
 }
 export declare class InMemoryFrontendProviderRegistryFrontendService implements FrontendProviderRegistryFrontendService {
     private registry;
-    initialize(frontendProviders?: FrontendProvidersBlock): void;
+    initialize(input?: FrontendProviderRegistryHydrationInput): void;
     getProviderByRef(ref: FrontendAppProviderRef): FrontendAppProviderModule | undefined;
     listByProviderCapability(providerCapability: ProviderCapability): ReadonlyArray<FrontendAppProviderModule>;
     findByProviderCapability(providerCapability: ProviderCapability): FrontendAppProviderModule | undefined;
     findByProviderCapabilityAndProtocol(providerCapability: ProviderCapability, providerProtocol: ProviderProtocol | string): FrontendAppProviderModule | undefined;
     listAll(): ReadonlyArray<FrontendAppProviderModule>;
 }
-export declare function createFrontendProviderRegistryFrontendService(frontendProviders?: FrontendProvidersBlock): FrontendProviderRegistryFrontendService;
+export declare function createFrontendProviderRegistryFrontendService(input?: FrontendProviderRegistryHydrationInput): FrontendProviderRegistryFrontendService;
 //# sourceMappingURL=frontend-provider-registry.frontend.service.d.ts.map

package/dist/esm/core/external-providers/frontend-provider-registry.frontend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontend-provider-registry.frontend.service.d.ts","sourceRoot":"","sources":["../../../../../src/core/external-providers/frontend-provider-registry.frontend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAE7E,OAAO,KAAK,EACV,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,0CAA0C,CAAC;AAElD,MAAM,WAAW,uCAAuC;IACtD,gEAAgE;IAChE,gBAAgB,CAAC,GAAG,EAAE,sBAAsB,GAAG,yBAAyB,GAAG,SAAS,CAAC;IAErF,wBAAwB,CACtB,kBAAkB,EAAE,kBAAkB,GACrC,aAAa,CAAC,yBAAyB,CAAC,CAAC;IAE5C,wBAAwB,CACtB,kBAAkB,EAAE,kBAAkB,GACrC,yBAAyB,GAAG,SAAS,CAAC;IAEzC,mCAAmC,CACjC,kBAAkB,EAAE,kBAAkB,EACtC,gBAAgB,EAAE,gBAAgB,GAAG,MAAM,GAC1C,yBAAyB,GAAG,SAAS,CAAC;IAEzC,iEAAiE;IACjE,OAAO,IAAI,aAAa,CAAC,yBAAyB,CAAC,CAAC;CACrD;AAED,qBAAa,+CACX,YAAW,uCAAuC;IAElD,OAAO,CAAC,QAAQ,CAEb;IAEH,UAAU,CAAC,iBAAiB,CAAC,EAAE,sBAAsB,GAAG,IAAI;IAW5D,gBAAgB,CACd,GAAG,EAAE,sBAAsB,GAC1B,yBAAyB,GAAG,SAAS;IAIxC,wBAAwB,CACtB,kBAAkB,EAAE,kBAAkB,GACrC,aAAa,CAAC,yBAAyB,CAAC;IAI3C,wBAAwB,CACtB,kBAAkB,EAAE,kBAAkB,GACrC,yBAAyB,GAAG,SAAS;IAIxC,mCAAmC,CACjC,kBAAkB,EAAE,kBAAkB,EACtC,gBAAgB,EAAE,gBAAgB,GAAG,MAAM,GAC1C,yBAAyB,GAAG,SAAS;IAQxC,OAAO,IAAI,aAAa,CAAC,yBAAyB,CAAC;CAGpD;AAED,wBAAgB,6CAA6C,CAC3D,iBAAiB,CAAC,EAAE,sBAAsB,GACzC,uCAAuC,CAIzC"}
+{"version":3,"file":"frontend-provider-registry.frontend.service.d.ts","sourceRoot":"","sources":["../../../../src/core/external-providers/frontend-provider-registry.frontend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAK7E,OAAO,KAAK,EACV,yBAAyB,EACzB,sBAAsB,EACtB,mCAAmC,EACnC,2BAA2B,EAC5B,MAAM,0CAA0C,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,2BAA2B,CAAC;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,mCAAmC,KAAK,IAAI,CAAC;CACnF;AAED,MAAM,WAAW,uCAAuC;IACtD,gEAAgE;IAChE,gBAAgB,CAAC,GAAG,EAAE,sBAAsB,GAAG,yBAAyB,GAAG,SAAS,CAAC;IAErF,wBAAwB,CACtB,kBAAkB,EAAE,kBAAkB,GACrC,aAAa,CAAC,yBAAyB,CAAC,CAAC;IAE5C,wBAAwB,CACtB,kBAAkB,EAAE,kBAAkB,GACrC,yBAAyB,GAAG,SAAS,CAAC;IAEzC,mCAAmC,CACjC,kBAAkB,EAAE,kBAAkB,EACtC,gBAAgB,EAAE,gBAAgB,GAAG,MAAM,GAC1C,yBAAyB,GAAG,SAAS,CAAC;IAEzC,iEAAiE;IACjE,OAAO,IAAI,aAAa,CAAC,yBAAyB,CAAC,CAAC;CACrD;AAED,qBAAa,+CACX,YAAW,uCAAuC;IAElD,OAAO,CAAC,QAAQ,CAEb;IAEH,UAAU,CAAC,KAAK,CAAC,EAAE,sCAAsC,GAAG,IAAI;IAQhE,gBAAgB,CACd,GAAG,EAAE,sBAAsB,GAC1B,yBAAyB,GAAG,SAAS;IAIxC,wBAAwB,CACtB,kBAAkB,EAAE,kBAAkB,GACrC,aAAa,CAAC,yBAAyB,CAAC;IAI3C,wBAAwB,CACtB,kBAAkB,EAAE,kBAAkB,GACrC,yBAAyB,GAAG,SAAS;IAIxC,mCAAmC,CACjC,kBAAkB,EAAE,kBAAkB,EACtC,gBAAgB,EAAE,gBAAgB,GAAG,MAAM,GAC1C,yBAAyB,GAAG,SAAS;IAQxC,OAAO,IAAI,aAAa,CAAC,yBAAyB,CAAC;CAGpD;AAED,wBAAgB,6CAA6C,CAC3D,KAAK,CAAC,EAAE,sCAAsC,GAC7C,uCAAuC,CAIzC"}

package/dist/esm/core/external-providers/frontend-provider-registry.frontend.service.js

@@ -1,31 +1,37 @@
 /**
  * `FrontendProviderRegistryFrontendService` — frontend-side API for
- * reading the per-app provider catalog hydrated from the backend.
+ * reading the per-app provider catalog.
  *
- * Hydrated once at app start from
- * `FrontendAppBootstrapPayload.frontendProviders` (Phase 6 wiring); the
- * payload is built by `FrontendBootstrapBackendService.buildPayload()`,
- * which is the SOLE cross-facet seam where backend code projects a
- * `BackendProviderModule` into a `FrontendProviderEntry`. From the
- * frontend's perspective this service is the only legal way to read
- * provider information — direct imports from
- * `@wildo-ai/external-connectors-private/*` are a TypeScript error
- * because the frontend bundle does not depend on that package.
+ * The registry is built from TWO channels and no longer from a cast (#332):
  *
- * See `.cursor/plans/provider-registration-refactor-implementation-plan.md`
- * §Phase 0.8.
+ *   - **DATA** — `FrontendAppBootstrapPayload.frontendProviders`, hydrated
+ *     once at app start from `/application-config`. Built by
+ *     `FrontendBootstrapBackendService.buildPayload()`, which is the SOLE
+ *     cross-facet seam where backend code projects a `BackendProviderModule`
+ *     into a `FrontendProviderEntry`. It is the authority on WHICH providers
+ *     this frontend service has turned on, in this environment.
+ *   - **CODE** — `generatedFrontendProviderModules` from the app's own
+ *     `src/generated/frontend-providers.generated.ts`, written by
+ *     `wildo config sync` and passed in through `StartApplicationOptions`. It
+ *     is the authority on what code this bundle contains — an SDK loader, a
+ *     public-config validator — none of which JSON could ever carry.
+ *
+ * From the frontend's perspective this service is still the only legal way to
+ * read provider information — direct imports from
+ * `@wildo-ai/external-connectors-private/*` are a TypeScript error because the
+ * frontend bundle does not depend on that package.
  */
-import { composeFrontendAppProviders } from '@wildo-ai/external-connectors-public/app';
+import { composeFrontendAppProviders, composeHydratedFrontendAppProviders, } from '@wildo-ai/external-connectors-public/app';
 export class InMemoryFrontendProviderRegistryFrontendService {
     registry = composeFrontendAppProviders({
         modules: new Map(),
     });
-    initialize(frontendProviders) {
-        const modules = new Map(Object.entries(frontendProviders?.providers ?? {}).map(([ref, provider]) => [
-            ref,
-            provider,
-        ]));
-        this.registry = composeFrontendAppProviders({ modules });
+    initialize(input) {
+        this.registry = composeHydratedFrontendAppProviders({
+            entries: input?.entries,
+            modules: input?.modules,
+            onDiagnostic: input?.onDiagnostic,
+        });
     }
     getProviderByRef(ref) {
         return this.registry.getProviderByRef(ref);
@@ -45,9 +51,9 @@ export class InMemoryFrontendProviderRegistryFrontendService {
         return [...this.registry.modules.values()];
     }
 }
-export function createFrontendProviderRegistryFrontendService(frontendProviders) {
+export function createFrontendProviderRegistryFrontendService(input) {
     const service = new InMemoryFrontendProviderRegistryFrontendService();
-    service.initialize(frontendProviders);
+    service.initialize(input);
     return service;
 }
 //# sourceMappingURL=frontend-provider-registry.frontend.service.js.map

package/dist/esm/core/external-providers/frontend-provider-registry.frontend.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontend-provider-registry.frontend.service.js","sourceRoot":"","sources":["../../../../../src/core/external-providers/frontend-provider-registry.frontend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,OAAO,EAAE,2BAA2B,EAAE,MAAM,0CAA0C,CAAC;AA2BvF,MAAM,OAAO,+CAA+C;IAGlD,QAAQ,GAAG,2BAA2B,CAAC;QAC7C,OAAO,EAAE,IAAI,GAAG,EAAqD;KACtE,CAAC,CAAC;IAEH,UAAU,CAAC,iBAA0C;QACnD,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC;YAC1E,GAA6B;YAC7B,QAAqC;SACtC,CAAC,CACH,CAAC;QAEF,IAAI,CAAC,QAAQ,GAAG,2BAA2B,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,gBAAgB,CACd,GAA2B;QAE3B,OAAO,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED,wBAAwB,CACtB,kBAAsC;QAEtC,OAAO,IAAI,CAAC,QAAQ,CAAC,gCAAgC,CAAC,kBAAkB,CAAC,CAAC;IAC5E,CAAC;IAED,wBAAwB,CACtB,kBAAsC;QAEtC,OAAO,IAAI,CAAC,QAAQ,CAAC,gCAAgC,CAAC,kBAAkB,CAAC,CAAC;IAC5E,CAAC;IAED,mCAAmC,CACjC,kBAAsC,EACtC,gBAA2C;QAE3C,OAAO,IAAI,CAAC,QAAQ;aACjB,gCAAgC,CAAC,kBAAkB,CAAC;aACpD,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CACjB,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,gBAAgB,CAAC,CACrE,CAAC;IACN,CAAC;IAED,OAAO;QACL,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7C,CAAC;CACF;AAED,MAAM,UAAU,6CAA6C,CAC3D,iBAA0C;IAE1C,MAAM,OAAO,GAAG,IAAI,+CAA+C,EAAE,CAAC;IACtE,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;IACtC,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["/**\n * `FrontendProviderRegistryFrontendService` — frontend-side API for\n * reading the per-app provider catalog hydrated from the backend.\n *\n * Hydrated once at app start from\n * `FrontendAppBootstrapPayload.frontendProviders` (Phase 6 wiring); the\n * payload is built by `FrontendBootstrapBackendService.buildPayload()`,\n * which is the SOLE cross-facet seam where backend code projects a\n * `BackendProviderModule` into a `FrontendProviderEntry`. From the\n * frontend's perspective this service is the only legal way to read\n * provider information — direct imports from\n * `@wildo-ai/external-connectors-private/*` are a TypeScript error\n * because the frontend bundle does not depend on that package.\n *\n * See `.cursor/plans/provider-registration-refactor-implementation-plan.md`\n * §Phase 0.8.\n */\n\nimport type {\n  FrontendProvidersBlock,\n  ProviderCapability,\n} from '@wildo-ai/saas-models';\nimport type { ProviderProtocol } from '@wildo-ai/saas-models/public-runtime';\nimport { composeFrontendAppProviders } from '@wildo-ai/external-connectors-public/app';\nimport type {\n  FrontendAppProviderModule,\n  FrontendAppProviderRef,\n} from '@wildo-ai/external-connectors-public/app';\n\nexport interface FrontendProviderRegistryFrontendService {\n  /** Hydrated from `FrontendAppBootstrapPayload` at app start. */\n  getProviderByRef(ref: FrontendAppProviderRef): FrontendAppProviderModule | undefined;\n\n  listByProviderCapability(\n    providerCapability: ProviderCapability,\n  ): ReadonlyArray<FrontendAppProviderModule>;\n\n  findByProviderCapability(\n    providerCapability: ProviderCapability,\n  ): FrontendAppProviderModule | undefined;\n\n  findByProviderCapabilityAndProtocol(\n    providerCapability: ProviderCapability,\n    providerProtocol: ProviderProtocol | string,\n  ): FrontendAppProviderModule | undefined;\n\n  /** All providers (read-only). For debug / introspection only. */\n  listAll(): ReadonlyArray<FrontendAppProviderModule>;\n}\n\nexport class InMemoryFrontendProviderRegistryFrontendService\n  implements FrontendProviderRegistryFrontendService\n{\n  private registry = composeFrontendAppProviders({\n    modules: new Map<FrontendAppProviderRef, FrontendAppProviderModule>(),\n  });\n\n  initialize(frontendProviders?: FrontendProvidersBlock): void {\n    const modules = new Map<FrontendAppProviderRef, FrontendAppProviderModule>(\n      Object.entries(frontendProviders?.providers ?? {}).map(([ref, provider]) => [\n        ref as FrontendAppProviderRef,\n        provider as FrontendAppProviderModule,\n      ]),\n    );\n\n    this.registry = composeFrontendAppProviders({ modules });\n  }\n\n  getProviderByRef(\n    ref: FrontendAppProviderRef,\n  ): FrontendAppProviderModule | undefined {\n    return this.registry.getProviderByRef(ref);\n  }\n\n  listByProviderCapability(\n    providerCapability: ProviderCapability,\n  ): ReadonlyArray<FrontendAppProviderModule> {\n    return this.registry.getProvidersByProviderCapability(providerCapability);\n  }\n\n  findByProviderCapability(\n    providerCapability: ProviderCapability,\n  ): FrontendAppProviderModule | undefined {\n    return this.registry.findProviderByProviderCapability(providerCapability);\n  }\n\n  findByProviderCapabilityAndProtocol(\n    providerCapability: ProviderCapability,\n    providerProtocol: ProviderProtocol | string,\n  ): FrontendAppProviderModule | undefined {\n    return this.registry\n      .getProvidersByProviderCapability(providerCapability)\n      .find((provider) =>\n        provider.protocols.some((protocol) => protocol === providerProtocol),\n      );\n  }\n\n  listAll(): ReadonlyArray<FrontendAppProviderModule> {\n    return [...this.registry.modules.values()];\n  }\n}\n\nexport function createFrontendProviderRegistryFrontendService(\n  frontendProviders?: FrontendProvidersBlock,\n): FrontendProviderRegistryFrontendService {\n  const service = new InMemoryFrontendProviderRegistryFrontendService();\n  service.initialize(frontendProviders);\n  return service;\n}\n"]}
+{"version":3,"file":"frontend-provider-registry.frontend.service.js","sourceRoot":"","sources":["../../../../src/core/external-providers/frontend-provider-registry.frontend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,OAAO,EACL,2BAA2B,EAC3B,mCAAmC,GACpC,MAAM,0CAA0C,CAAC;AA0ClD,MAAM,OAAO,+CAA+C;IAGlD,QAAQ,GAAG,2BAA2B,CAAC;QAC7C,OAAO,EAAE,IAAI,GAAG,EAAqD;KACtE,CAAC,CAAC;IAEH,UAAU,CAAC,KAA8C;QACvD,IAAI,CAAC,QAAQ,GAAG,mCAAmC,CAAC;YAClD,OAAO,EAAE,KAAK,EAAE,OAAO;YACvB,OAAO,EAAE,KAAK,EAAE,OAAO;YACvB,YAAY,EAAE,KAAK,EAAE,YAAY;SAClC,CAAC,CAAC;IACL,CAAC;IAED,gBAAgB,CACd,GAA2B;QAE3B,OAAO,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED,wBAAwB,CACtB,kBAAsC;QAEtC,OAAO,IAAI,CAAC,QAAQ,CAAC,gCAAgC,CAAC,kBAAkB,CAAC,CAAC;IAC5E,CAAC;IAED,wBAAwB,CACtB,kBAAsC;QAEtC,OAAO,IAAI,CAAC,QAAQ,CAAC,gCAAgC,CAAC,kBAAkB,CAAC,CAAC;IAC5E,CAAC;IAED,mCAAmC,CACjC,kBAAsC,EACtC,gBAA2C;QAE3C,OAAO,IAAI,CAAC,QAAQ;aACjB,gCAAgC,CAAC,kBAAkB,CAAC;aACpD,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CACjB,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,gBAAgB,CAAC,CACrE,CAAC;IACN,CAAC;IAED,OAAO;QACL,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7C,CAAC;CACF;AAED,MAAM,UAAU,6CAA6C,CAC3D,KAA8C;IAE9C,MAAM,OAAO,GAAG,IAAI,+CAA+C,EAAE,CAAC;IACtE,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC1B,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["/**\n * `FrontendProviderRegistryFrontendService` — frontend-side API for\n * reading the per-app provider catalog.\n *\n * The registry is built from TWO channels and no longer from a cast (#332):\n *\n *   - **DATA** — `FrontendAppBootstrapPayload.frontendProviders`, hydrated\n *     once at app start from `/application-config`. Built by\n *     `FrontendBootstrapBackendService.buildPayload()`, which is the SOLE\n *     cross-facet seam where backend code projects a `BackendProviderModule`\n *     into a `FrontendProviderEntry`. It is the authority on WHICH providers\n *     this frontend service has turned on, in this environment.\n *   - **CODE** — `generatedFrontendProviderModules` from the app's own\n *     `src/generated/frontend-providers.generated.ts`, written by\n *     `wildo config sync` and passed in through `StartApplicationOptions`. It\n *     is the authority on what code this bundle contains — an SDK loader, a\n *     public-config validator — none of which JSON could ever carry.\n *\n * From the frontend's perspective this service is still the only legal way to\n * read provider information — direct imports from\n * `@wildo-ai/external-connectors-private/*` are a TypeScript error because the\n * frontend bundle does not depend on that package.\n */\n\nimport type {\n  FrontendProvidersBlock,\n  ProviderCapability,\n} from '@wildo-ai/saas-models';\nimport type { ProviderProtocol } from '@wildo-ai/saas-models/public-runtime';\nimport {\n  composeFrontendAppProviders,\n  composeHydratedFrontendAppProviders,\n} from '@wildo-ai/external-connectors-public/app';\nimport type {\n  FrontendAppProviderModule,\n  FrontendAppProviderRef,\n  FrontendProviderHydrationDiagnostic,\n  GeneratedAppProviderModules,\n} from '@wildo-ai/external-connectors-public/app';\n\n/**\n * Everything the registry needs to join the two channels.\n *\n * `modules` absent is the ordinary case for an application that declares no\n * package-shipped frontend provider: `wildo config sync` writes no generated\n * file, so there is nothing to import and nothing to pass.\n */\nexport interface FrontendProviderRegistryHydrationInput {\n  readonly entries?: FrontendProvidersBlock;\n  readonly modules?: GeneratedAppProviderModules;\n  readonly onDiagnostic?: (diagnostic: FrontendProviderHydrationDiagnostic) => void;\n}\n\nexport interface FrontendProviderRegistryFrontendService {\n  /** Hydrated from `FrontendAppBootstrapPayload` at app start. */\n  getProviderByRef(ref: FrontendAppProviderRef): FrontendAppProviderModule | undefined;\n\n  listByProviderCapability(\n    providerCapability: ProviderCapability,\n  ): ReadonlyArray<FrontendAppProviderModule>;\n\n  findByProviderCapability(\n    providerCapability: ProviderCapability,\n  ): FrontendAppProviderModule | undefined;\n\n  findByProviderCapabilityAndProtocol(\n    providerCapability: ProviderCapability,\n    providerProtocol: ProviderProtocol | string,\n  ): FrontendAppProviderModule | undefined;\n\n  /** All providers (read-only). For debug / introspection only. */\n  listAll(): ReadonlyArray<FrontendAppProviderModule>;\n}\n\nexport class InMemoryFrontendProviderRegistryFrontendService\n  implements FrontendProviderRegistryFrontendService\n{\n  private registry = composeFrontendAppProviders({\n    modules: new Map<FrontendAppProviderRef, FrontendAppProviderModule>(),\n  });\n\n  initialize(input?: FrontendProviderRegistryHydrationInput): void {\n    this.registry = composeHydratedFrontendAppProviders({\n      entries: input?.entries,\n      modules: input?.modules,\n      onDiagnostic: input?.onDiagnostic,\n    });\n  }\n\n  getProviderByRef(\n    ref: FrontendAppProviderRef,\n  ): FrontendAppProviderModule | undefined {\n    return this.registry.getProviderByRef(ref);\n  }\n\n  listByProviderCapability(\n    providerCapability: ProviderCapability,\n  ): ReadonlyArray<FrontendAppProviderModule> {\n    return this.registry.getProvidersByProviderCapability(providerCapability);\n  }\n\n  findByProviderCapability(\n    providerCapability: ProviderCapability,\n  ): FrontendAppProviderModule | undefined {\n    return this.registry.findProviderByProviderCapability(providerCapability);\n  }\n\n  findByProviderCapabilityAndProtocol(\n    providerCapability: ProviderCapability,\n    providerProtocol: ProviderProtocol | string,\n  ): FrontendAppProviderModule | undefined {\n    return this.registry\n      .getProvidersByProviderCapability(providerCapability)\n      .find((provider) =>\n        provider.protocols.some((protocol) => protocol === providerProtocol),\n      );\n  }\n\n  listAll(): ReadonlyArray<FrontendAppProviderModule> {\n    return [...this.registry.modules.values()];\n  }\n}\n\nexport function createFrontendProviderRegistryFrontendService(\n  input?: FrontendProviderRegistryHydrationInput,\n): FrontendProviderRegistryFrontendService {\n  const service = new InMemoryFrontendProviderRegistryFrontendService();\n  service.initialize(input);\n  return service;\n}\n"]}

package/dist/esm/core/external-providers/provider-file-selection.frontend.utils.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Holding a provider's file picker to the selection contract it DECLARED.
+ *
+ * ## Why this exists at all
+ *
+ * Issue #383 (Q5) settled what "an application calls a third party directly from
+ * a custom frontend component" means when the component is a file picker, and
+ * the answer was **per vendor, declared**: a picker for a credentialed vendor
+ * hands back an opaque remote reference the backend resolves, a picker running
+ * on a browser-safe grant hands back bytes or a URL the browser already has, and
+ * a provider states which of the two it is.
+ *
+ * The union alone would have been the hedge that decision rejected. Three arms
+ * with a runtime discriminant is a shape that says *"one of these three, we will
+ * find out when it happens"* — and an application's file field cannot be written
+ * against that: the reference arm has to be posted to the executor door, the
+ * browser-readable arms go through the ordinary upload path, and choosing
+ * between them at runtime means every field carries both.
+ *
+ * So the declaration is enforced here. A provider that declares
+ * `REMOTE_REFERENCE` and hands back a `File` is refused, loudly, naming both
+ * sides. Without this the declaration would be decoration, and a reviewer
+ * reading a provider's manifest would be reading a wish rather than a contract.
+ *
+ * ## It is the SANCTIONED seam, not the only possible one
+ *
+ * `ProviderFilePickerHost` is the path that calls this, and it is what a surface
+ * should use. But the registry and the `useProviderComponent` hooks are public
+ * too — an application can resolve a provider's component itself, cast it and
+ * mount it, and a selection then reaches that application without passing
+ * through here.
+ *
+ * That is deliberate and it is stated rather than closed off: a framework that
+ * could only mount a provider component one way would be unable to serve a
+ * surface the framework has not thought of, which is the whole reason the
+ * capability vocabulary is open. What the framework guarantees is that ITS
+ * routing honours the declaration; an application taking the component directly
+ * has taken the contract with it, and should call this function.
+ *
+ * An earlier revision of this paragraph said "the one seam every selection
+ * crosses", which stopped being true in the same change that exported the other
+ * path. Kept as a correction because a load-bearing sentence that quietly goes
+ * false is how the next reader inherits a guarantee nobody makes.
+ *
+ * ## Why refusal is REPORTED rather than thrown
+ *
+ * This runs inside a picker's own callback, which is usually a vendor SDK's
+ * event handler rather than a React render. A throw there does not reach an
+ * error boundary — it reaches the vendor's own dispatcher, which typically
+ * swallows it — so the surface would stop responding with nothing on screen and
+ * nothing in the log. A returned result lets the mounting surface show the user
+ * that the picker misbehaved and lets the diagnostic name the provider.
+ */
+import { ProviderFrontendSelectionDelivery, type ProviderFileSelection, type ProviderFrontendComponentDescriptor } from '@wildo-ai/saas-models/public-runtime';
+/** Why a selection a picker produced was not accepted. */
+export declare enum ProviderFileSelectionRejectionKind {
+    /**
+     * The provider declared no `selectionDelivery` for its file picker, so the
+     * framework cannot know whether the result is a backend reference or bytes —
+     * and therefore cannot route it anywhere. An authoring defect in the provider
+     * package, not a user error.
+     */
+    PROVIDER_DECLARED_NO_DELIVERY = "PROVIDER_DECLARED_NO_DELIVERY",
+    /**
+     * The picker returned a selection whose kind is not the one it declared. This
+     * is the case the whole declaration exists to catch: a `REMOTE_REFERENCE`
+     * provider handing back a `File` means bytes reached the browser on a path
+     * nobody reviewed for it.
+     */
+    DELIVERY_CONTRADICTS_DECLARATION = "DELIVERY_CONTRADICTS_DECLARATION"
+}
+export interface ProviderFileSelectionRejection {
+    readonly kind: ProviderFileSelectionRejectionKind;
+    readonly providerRef: string;
+    readonly message: string;
+    /** The delivery the provider declared, when it declared one. */
+    readonly declared?: ProviderFrontendSelectionDelivery;
+    /** The kind the picker actually produced, for the contradiction case. */
+    readonly received?: ProviderFileSelection['kind'];
+}
+export interface ProviderFileSelectionOutcome {
+    /** Selections that match the declaration. Empty when anything was rejected — see below. */
+    readonly accepted: readonly ProviderFileSelection[];
+    readonly rejections: readonly ProviderFileSelectionRejection[];
+}
+/**
+ * Checks every selection against what the provider declared.
+ *
+ * **All or nothing.** One contradicting selection rejects the whole batch rather
+ * than the offending item, and that is deliberate: a picker that returned three
+ * files of which one has the wrong shape is a picker whose contract is not what
+ * it says, and accepting the other two would leave an application holding a
+ * partial result it never asked for from a component it can no longer trust.
+ * Silently dropping one of a user's three chosen files is the worse outcome —
+ * the user sees two, has no idea why, and nothing anywhere says so.
+ */
+export declare function receiveProviderFileSelections(input: {
+    readonly providerRef: string;
+    readonly descriptor: ProviderFrontendComponentDescriptor | undefined;
+    readonly selections: readonly ProviderFileSelection[];
+}): ProviderFileSelectionOutcome;
+//# sourceMappingURL=provider-file-selection.frontend.utils.d.ts.map

package/dist/esm/core/external-providers/provider-file-selection.frontend.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-file-selection.frontend.utils.d.ts","sourceRoot":"","sources":["../../../../src/core/external-providers/provider-file-selection.frontend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,EACL,iCAAiC,EACjC,KAAK,qBAAqB,EAC1B,KAAK,mCAAmC,EACzC,MAAM,sCAAsC,CAAC;AAE9C,0DAA0D;AAC1D,oBAAY,kCAAkC;IAC5C;;;;;OAKG;IACH,6BAA6B,kCAAkC;IAC/D;;;;;OAKG;IACH,gCAAgC,qCAAqC;CACtE;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,IAAI,EAAE,kCAAkC,CAAC;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,iCAAiC,CAAC;IACtD,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,4BAA4B;IAC3C,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACpD,QAAQ,CAAC,UAAU,EAAE,SAAS,8BAA8B,EAAE,CAAC;CAChE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,mCAAmC,GAAG,SAAS,CAAC;IACrE,QAAQ,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACvD,GAAG,4BAA4B,CAqC/B"}

package/dist/esm/core/external-providers/provider-file-selection.frontend.utils.js

@@ -0,0 +1,117 @@
+/**
+ * Holding a provider's file picker to the selection contract it DECLARED.
+ *
+ * ## Why this exists at all
+ *
+ * Issue #383 (Q5) settled what "an application calls a third party directly from
+ * a custom frontend component" means when the component is a file picker, and
+ * the answer was **per vendor, declared**: a picker for a credentialed vendor
+ * hands back an opaque remote reference the backend resolves, a picker running
+ * on a browser-safe grant hands back bytes or a URL the browser already has, and
+ * a provider states which of the two it is.
+ *
+ * The union alone would have been the hedge that decision rejected. Three arms
+ * with a runtime discriminant is a shape that says *"one of these three, we will
+ * find out when it happens"* — and an application's file field cannot be written
+ * against that: the reference arm has to be posted to the executor door, the
+ * browser-readable arms go through the ordinary upload path, and choosing
+ * between them at runtime means every field carries both.
+ *
+ * So the declaration is enforced here. A provider that declares
+ * `REMOTE_REFERENCE` and hands back a `File` is refused, loudly, naming both
+ * sides. Without this the declaration would be decoration, and a reviewer
+ * reading a provider's manifest would be reading a wish rather than a contract.
+ *
+ * ## It is the SANCTIONED seam, not the only possible one
+ *
+ * `ProviderFilePickerHost` is the path that calls this, and it is what a surface
+ * should use. But the registry and the `useProviderComponent` hooks are public
+ * too — an application can resolve a provider's component itself, cast it and
+ * mount it, and a selection then reaches that application without passing
+ * through here.
+ *
+ * That is deliberate and it is stated rather than closed off: a framework that
+ * could only mount a provider component one way would be unable to serve a
+ * surface the framework has not thought of, which is the whole reason the
+ * capability vocabulary is open. What the framework guarantees is that ITS
+ * routing honours the declaration; an application taking the component directly
+ * has taken the contract with it, and should call this function.
+ *
+ * An earlier revision of this paragraph said "the one seam every selection
+ * crosses", which stopped being true in the same change that exported the other
+ * path. Kept as a correction because a load-bearing sentence that quietly goes
+ * false is how the next reader inherits a guarantee nobody makes.
+ *
+ * ## Why refusal is REPORTED rather than thrown
+ *
+ * This runs inside a picker's own callback, which is usually a vendor SDK's
+ * event handler rather than a React render. A throw there does not reach an
+ * error boundary — it reaches the vendor's own dispatcher, which typically
+ * swallows it — so the surface would stop responding with nothing on screen and
+ * nothing in the log. A returned result lets the mounting surface show the user
+ * that the picker misbehaved and lets the diagnostic name the provider.
+ */
+/** Why a selection a picker produced was not accepted. */
+export var ProviderFileSelectionRejectionKind;
+(function (ProviderFileSelectionRejectionKind) {
+    /**
+     * The provider declared no `selectionDelivery` for its file picker, so the
+     * framework cannot know whether the result is a backend reference or bytes —
+     * and therefore cannot route it anywhere. An authoring defect in the provider
+     * package, not a user error.
+     */
+    ProviderFileSelectionRejectionKind["PROVIDER_DECLARED_NO_DELIVERY"] = "PROVIDER_DECLARED_NO_DELIVERY";
+    /**
+     * The picker returned a selection whose kind is not the one it declared. This
+     * is the case the whole declaration exists to catch: a `REMOTE_REFERENCE`
+     * provider handing back a `File` means bytes reached the browser on a path
+     * nobody reviewed for it.
+     */
+    ProviderFileSelectionRejectionKind["DELIVERY_CONTRADICTS_DECLARATION"] = "DELIVERY_CONTRADICTS_DECLARATION";
+})(ProviderFileSelectionRejectionKind || (ProviderFileSelectionRejectionKind = {}));
+/**
+ * Checks every selection against what the provider declared.
+ *
+ * **All or nothing.** One contradicting selection rejects the whole batch rather
+ * than the offending item, and that is deliberate: a picker that returned three
+ * files of which one has the wrong shape is a picker whose contract is not what
+ * it says, and accepting the other two would leave an application holding a
+ * partial result it never asked for from a component it can no longer trust.
+ * Silently dropping one of a user's three chosen files is the worse outcome —
+ * the user sees two, has no idea why, and nothing anywhere says so.
+ */
+export function receiveProviderFileSelections(input) {
+    const declared = input.descriptor?.selectionDelivery;
+    if (declared === undefined) {
+        return {
+            accepted: [],
+            rejections: [{
+                    kind: ProviderFileSelectionRejectionKind.PROVIDER_DECLARED_NO_DELIVERY,
+                    providerRef: input.providerRef,
+                    message: `Provider "${input.providerRef}" contributes a file picker but declares no `
+                        + '`selectionDelivery`, so the framework cannot tell whether a selection is a backend '
+                        + 'reference or bytes the browser already holds — and therefore cannot route it. Declare '
+                        + 'one on the component: `components: { FRONTEND_FILE_PICKER: { load, selectionDelivery } }`.',
+                }],
+        };
+    }
+    const rejections = [];
+    for (const selection of input.selections) {
+        if (selection.kind === declared)
+            continue;
+        rejections.push({
+            kind: ProviderFileSelectionRejectionKind.DELIVERY_CONTRADICTS_DECLARATION,
+            providerRef: input.providerRef,
+            declared,
+            received: selection.kind,
+            message: `Provider "${input.providerRef}" declared its file picker delivers "${declared}" and returned a `
+                + `"${selection.kind}" selection. Which one a provider emits is a declaration, not a runtime `
+                + 'choice (issue #383): a surface routes a selection before it mounts the picker, so a picker '
+                + 'that contradicts its own declaration is refused rather than guessed at.',
+        });
+    }
+    return rejections.length > 0
+        ? { accepted: [], rejections }
+        : { accepted: input.selections, rejections: [] };
+}
+//# sourceMappingURL=provider-file-selection.frontend.utils.js.map

package/dist/esm/core/external-providers/provider-file-selection.frontend.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-file-selection.frontend.utils.js","sourceRoot":"","sources":["../../../../src/core/external-providers/provider-file-selection.frontend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAQH,0DAA0D;AAC1D,MAAM,CAAN,IAAY,kCAeX;AAfD,WAAY,kCAAkC;IAC5C;;;;;OAKG;IACH,qGAA+D,CAAA;IAC/D;;;;;OAKG;IACH,2GAAqE,CAAA;AACvE,CAAC,EAfW,kCAAkC,KAAlC,kCAAkC,QAe7C;AAkBD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,6BAA6B,CAAC,KAI7C;IACC,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,EAAE,iBAAiB,CAAC;IAErD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO;YACL,QAAQ,EAAE,EAAE;YACZ,UAAU,EAAE,CAAC;oBACX,IAAI,EAAE,kCAAkC,CAAC,6BAA6B;oBACtE,WAAW,EAAE,KAAK,CAAC,WAAW;oBAC9B,OAAO,EACL,aAAa,KAAK,CAAC,WAAW,8CAA8C;0BAC1E,qFAAqF;0BACrF,wFAAwF;0BACxF,4FAA4F;iBACjG,CAAC;SACH,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAqC,EAAE,CAAC;IACxD,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACzC,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ;YAAE,SAAS;QAC1C,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,kCAAkC,CAAC,gCAAgC;YACzE,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,QAAQ;YACR,QAAQ,EAAE,SAAS,CAAC,IAAI;YACxB,OAAO,EACL,aAAa,KAAK,CAAC,WAAW,wCAAwC,QAAQ,mBAAmB;kBAC/F,IAAI,SAAS,CAAC,IAAI,0EAA0E;kBAC5F,6FAA6F;kBAC7F,yEAAyE;SAC9E,CAAC,CAAC;IACL,CAAC;IAED,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC;QAC1B,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAE;QAC9B,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;AACrD,CAAC","sourcesContent":["/**\n * Holding a provider's file picker to the selection contract it DECLARED.\n *\n * ## Why this exists at all\n *\n * Issue #383 (Q5) settled what \"an application calls a third party directly from\n * a custom frontend component\" means when the component is a file picker, and\n * the answer was **per vendor, declared**: a picker for a credentialed vendor\n * hands back an opaque remote reference the backend resolves, a picker running\n * on a browser-safe grant hands back bytes or a URL the browser already has, and\n * a provider states which of the two it is.\n *\n * The union alone would have been the hedge that decision rejected. Three arms\n * with a runtime discriminant is a shape that says *\"one of these three, we will\n * find out when it happens\"* — and an application's file field cannot be written\n * against that: the reference arm has to be posted to the executor door, the\n * browser-readable arms go through the ordinary upload path, and choosing\n * between them at runtime means every field carries both.\n *\n * So the declaration is enforced here. A provider that declares\n * `REMOTE_REFERENCE` and hands back a `File` is refused, loudly, naming both\n * sides. Without this the declaration would be decoration, and a reviewer\n * reading a provider's manifest would be reading a wish rather than a contract.\n *\n * ## It is the SANCTIONED seam, not the only possible one\n *\n * `ProviderFilePickerHost` is the path that calls this, and it is what a surface\n * should use. But the registry and the `useProviderComponent` hooks are public\n * too — an application can resolve a provider's component itself, cast it and\n * mount it, and a selection then reaches that application without passing\n * through here.\n *\n * That is deliberate and it is stated rather than closed off: a framework that\n * could only mount a provider component one way would be unable to serve a\n * surface the framework has not thought of, which is the whole reason the\n * capability vocabulary is open. What the framework guarantees is that ITS\n * routing honours the declaration; an application taking the component directly\n * has taken the contract with it, and should call this function.\n *\n * An earlier revision of this paragraph said \"the one seam every selection\n * crosses\", which stopped being true in the same change that exported the other\n * path. Kept as a correction because a load-bearing sentence that quietly goes\n * false is how the next reader inherits a guarantee nobody makes.\n *\n * ## Why refusal is REPORTED rather than thrown\n *\n * This runs inside a picker's own callback, which is usually a vendor SDK's\n * event handler rather than a React render. A throw there does not reach an\n * error boundary — it reaches the vendor's own dispatcher, which typically\n * swallows it — so the surface would stop responding with nothing on screen and\n * nothing in the log. A returned result lets the mounting surface show the user\n * that the picker misbehaved and lets the diagnostic name the provider.\n */\n\nimport {\n  ProviderFrontendSelectionDelivery,\n  type ProviderFileSelection,\n  type ProviderFrontendComponentDescriptor,\n} from '@wildo-ai/saas-models/public-runtime';\n\n/** Why a selection a picker produced was not accepted. */\nexport enum ProviderFileSelectionRejectionKind {\n  /**\n   * The provider declared no `selectionDelivery` for its file picker, so the\n   * framework cannot know whether the result is a backend reference or bytes —\n   * and therefore cannot route it anywhere. An authoring defect in the provider\n   * package, not a user error.\n   */\n  PROVIDER_DECLARED_NO_DELIVERY = 'PROVIDER_DECLARED_NO_DELIVERY',\n  /**\n   * The picker returned a selection whose kind is not the one it declared. This\n   * is the case the whole declaration exists to catch: a `REMOTE_REFERENCE`\n   * provider handing back a `File` means bytes reached the browser on a path\n   * nobody reviewed for it.\n   */\n  DELIVERY_CONTRADICTS_DECLARATION = 'DELIVERY_CONTRADICTS_DECLARATION',\n}\n\nexport interface ProviderFileSelectionRejection {\n  readonly kind: ProviderFileSelectionRejectionKind;\n  readonly providerRef: string;\n  readonly message: string;\n  /** The delivery the provider declared, when it declared one. */\n  readonly declared?: ProviderFrontendSelectionDelivery;\n  /** The kind the picker actually produced, for the contradiction case. */\n  readonly received?: ProviderFileSelection['kind'];\n}\n\nexport interface ProviderFileSelectionOutcome {\n  /** Selections that match the declaration. Empty when anything was rejected — see below. */\n  readonly accepted: readonly ProviderFileSelection[];\n  readonly rejections: readonly ProviderFileSelectionRejection[];\n}\n\n/**\n * Checks every selection against what the provider declared.\n *\n * **All or nothing.** One contradicting selection rejects the whole batch rather\n * than the offending item, and that is deliberate: a picker that returned three\n * files of which one has the wrong shape is a picker whose contract is not what\n * it says, and accepting the other two would leave an application holding a\n * partial result it never asked for from a component it can no longer trust.\n * Silently dropping one of a user's three chosen files is the worse outcome —\n * the user sees two, has no idea why, and nothing anywhere says so.\n */\nexport function receiveProviderFileSelections(input: {\n  readonly providerRef: string;\n  readonly descriptor: ProviderFrontendComponentDescriptor | undefined;\n  readonly selections: readonly ProviderFileSelection[];\n}): ProviderFileSelectionOutcome {\n  const declared = input.descriptor?.selectionDelivery;\n\n  if (declared === undefined) {\n    return {\n      accepted: [],\n      rejections: [{\n        kind: ProviderFileSelectionRejectionKind.PROVIDER_DECLARED_NO_DELIVERY,\n        providerRef: input.providerRef,\n        message:\n          `Provider \"${input.providerRef}\" contributes a file picker but declares no `\n          + '`selectionDelivery`, so the framework cannot tell whether a selection is a backend '\n          + 'reference or bytes the browser already holds — and therefore cannot route it. Declare '\n          + 'one on the component: `components: { FRONTEND_FILE_PICKER: { load, selectionDelivery } }`.',\n      }],\n    };\n  }\n\n  const rejections: ProviderFileSelectionRejection[] = [];\n  for (const selection of input.selections) {\n    if (selection.kind === declared) continue;\n    rejections.push({\n      kind: ProviderFileSelectionRejectionKind.DELIVERY_CONTRADICTS_DECLARATION,\n      providerRef: input.providerRef,\n      declared,\n      received: selection.kind,\n      message:\n        `Provider \"${input.providerRef}\" declared its file picker delivers \"${declared}\" and returned a `\n        + `\"${selection.kind}\" selection. Which one a provider emits is a declaration, not a runtime `\n        + 'choice (issue #383): a surface routes a selection before it mounts the picker, so a picker '\n        + 'that contradicts its own declaration is refused rather than guessed at.',\n    });\n  }\n\n  return rejections.length > 0\n    ? { accepted: [], rejections }\n    : { accepted: input.selections, rejections: [] };\n}\n"]}

package/dist/esm/core/features/FeatureGate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FeatureGate.d.ts","sourceRoot":"","sources":["../../../../../src/core/features/FeatureGate.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAM5F,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,YAAY,EAAE,mBAAmB,KAAK,KAAK,CAAC,SAAS,CAAC;CAC5E;AAED,wBAAgB,WAAW,CAAC,EAC1B,SAAS,EACT,QAAQ,EACR,iBAAiB,GAClB,EAAE,gBAAgB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,CA+B7C"}
+{"version":3,"file":"FeatureGate.d.ts","sourceRoot":"","sources":["../../../../src/core/features/FeatureGate.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAM5F,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,YAAY,EAAE,mBAAmB,KAAK,KAAK,CAAC,SAAS,CAAC;CAC5E;AAED,wBAAgB,WAAW,CAAC,EAC1B,SAAS,EACT,QAAQ,EACR,iBAAiB,GAClB,EAAE,gBAAgB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,CAgC7C"}

package/dist/esm/core/features/FeatureGate.js

@@ -20,6 +20,6 @@ export function FeatureGate({ featureId, children, renderUnavailable, }) {
     }
     // Default: policy-driven prompt. Inline FeatureGate surfaces do not expose a
     // generic "go back" action because they are embedded into the current page.
-    return (_jsx(FeatureUnavailablePrompt, { behavior: availability.behavior, missingFeatures: availability.missingFeatures, limitInfo: availability.limitInfo, upgradeOptionsCount: availability.upgradeOptions?.length, onDismiss: undefined, onAction: () => billingAction(availability) }));
+    return (_jsx(FeatureUnavailablePrompt, { behavior: availability.behavior, missingFeatures: availability.missingFeatures, limitInfo: availability.limitInfo, upgradeOptionsCount: availability.upgradeOptions?.length, customComponentRef: availability.customComponentRef, onDismiss: undefined, onAction: () => billingAction(availability) }));
 }
 //# sourceMappingURL=FeatureGate.js.map