@asteby/metacore-runtime-react 9.1.0 → 10.0.0

package/dist/dynamic-relation.js

@@ -10,6 +10,7 @@ import { Plus, Trash2, Pencil } from 'lucide-react';
 import { useApi } from './api-context';
 import { useMetadataCache } from './metadata-cache';
 import { DynamicForm } from './dynamic-form';
+import { useOptionsResolver } from './use-options-resolver';
 import { buildCreatePayload, buildPivotAttachPayload, buildPivotRowIndex, buildRelationFilterParams, deriveRelationFormFields, diffSelection, extractSelectedTargetIds, pickOptionLabel, relationRowKey, } from './dynamic-relation-helpers';
 export { buildCreatePayload, buildPivotAttachPayload, buildPivotRowIndex, buildRelationFilterParams, deriveRelationFormFields, diffSelection, extractSelectedTargetIds, pickOptionLabel, relationRowKey, } from './dynamic-relation-helpers';
 const DEFAULT_STRINGS = {
@@ -140,33 +141,58 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
     const labels = { ...DEFAULT_STRINGS, ...(strings || {}) };
     const refKey = referencesKey || `${references}_id`;
     const pivotPath = pivotEndpoint || `/data/${through}`;
-    const targetPath = referencesEndpoint || `/data/${references}`;
+    // referencesEndpoint is preserved as a legacy escape hatch — when set
+    // we keep the old `/data/<references>` raw fetch path (so apps that
+    // depend on a custom server route do not break). When unset we use
+    // the canonical `/api/options/:references` endpoint via
+    // useOptionsResolver, which is what the kernel auto-derives Ref to.
+    const useResolver = !referencesEndpoint;
+    const legacyTargetPath = referencesEndpoint || `/data/${references}`;
     const cachedTargetMeta = getMetadata(references);
     const [targetMeta, setTargetMeta] = useState(cachedTargetMeta || null);
     const [targetRows, setTargetRows] = useState([]);
     const [pivotRows, setPivotRows] = useState([]);
     const [loading, setLoading] = useState(true);
     const [syncing, setSyncing] = useState(false);
-    const fetchAll = useCallback(async () => {
+    // Canonical path: SDK options resolver. Only fires when no legacy
+    // override is set. The hook is a no-op when `useResolver` is false.
+    const resolved = useOptionsResolver({
+        modelKey: '',
+        fieldKey: 'id',
+        ref: useResolver ? references : undefined,
+        enabled: useResolver,
+    });
+    const fetchPivotAndMeta = useCallback(async () => {
         setLoading(true);
         try {
             const params = buildRelationFilterParams(foreignKey, parentId);
-            const [metaRes, pivotRes, targetRes] = await Promise.all([
-                targetMeta ? Promise.resolve(null) : api.get(`/metadata/table/${references}`),
+            const tasks = [
                 api.get(pivotPath, { params }),
-                api.get(targetPath),
-            ]);
-            if (metaRes && metaRes.data?.success) {
-                const fresh = metaRes.data.data;
-                setTargetMeta(fresh);
-                cacheMetadata(references, fresh);
+            ];
+            if (!targetMeta)
+                tasks.push(api.get(`/metadata/table/${references}`));
+            // Legacy fallback path: the resolver is disabled, fetch the
+            // target rows the old way so callers that depend on a custom
+            // route keep working.
+            if (!useResolver)
+                tasks.push(api.get(legacyTargetPath));
+            const results = await Promise.all(tasks);
+            const pivotRes = results[0];
+            if (pivotRes.data.success)
+                setPivotRows(pivotRes.data.data || []);
+            let cursor = 1;
+            if (!targetMeta) {
+                const metaRes = results[cursor++];
+                if (metaRes.data?.success) {
+                    setTargetMeta(metaRes.data.data);
+                    cacheMetadata(references, metaRes.data.data);
+                }
+            }
+            if (!useResolver) {
+                const targetRes = results[cursor++];
+                if (targetRes.data.success)
+                    setTargetRows(targetRes.data.data || []);
             }
-            const pivotList = pivotRes.data;
-            if (pivotList.success)
-                setPivotRows(pivotList.data || []);
-            const targetList = targetRes.data;
-            if (targetList.success)
-                setTargetRows(targetList.data || []);
         }
         catch (err) {
             console.error('DynamicRelation m2m fetch error', err);
@@ -174,16 +200,22 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
         finally {
             setLoading(false);
         }
-    }, [api, pivotPath, targetPath, foreignKey, parentId, references, targetMeta, cacheMetadata]);
-    useEffect(() => { fetchAll(); }, [fetchAll]);
+    }, [api, pivotPath, foreignKey, parentId, references, targetMeta, cacheMetadata, useResolver, legacyTargetPath]);
+    useEffect(() => { fetchPivotAndMeta(); }, [fetchPivotAndMeta]);
     const options = useMemo(() => {
+        if (useResolver) {
+            return resolved.options.map((o) => ({
+                value: String(o.id),
+                label: o.label,
+            }));
+        }
         return targetRows
             .filter(r => r && r.id !== undefined && r.id !== null && r.id !== '')
             .map(r => ({
             value: String(r.id),
             label: pickOptionLabel(r, displayKey, targetMeta?.columns),
         }));
-    }, [targetRows, displayKey, targetMeta]);
+    }, [useResolver, resolved.options, targetRows, displayKey, targetMeta]);
     const selectedIds = useMemo(() => extractSelectedTargetIds(pivotRows, refKey), [pivotRows, refKey]);
     const pivotIndex = useMemo(() => buildPivotRowIndex(pivotRows, refKey), [pivotRows, refKey]);
     const handleChange = useCallback(async (next) => {
@@ -212,7 +244,12 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
                 if (!res.data?.success)
                     throw new Error('detach failed');
             }
-            await fetchAll();
+            await fetchPivotAndMeta();
+            // Refresh resolver-driven options when active so newly attached
+            // targets reflect immediately. Refetching the pivot rows alone
+            // is enough when the resolver branch is off.
+            if (useResolver)
+                resolved.refetch();
             onChange?.();
         }
         catch (err) {
@@ -221,6 +258,6 @@ function ManyToManyRelation({ kind, through, references, foreignKey, referencesK
         finally {
             setSyncing(false);
         }
-    }, [api, canCreate, canDelete, fetchAll, foreignKey, onChange, parentId, pivotIndex, pivotPath, refKey, selectedIds, syncing]);
-    return (_jsxs("div", { className: className, "data-relation-kind": kind, "data-relation-through": through, "data-relation-references": references, children: [labels.title && (_jsx("div", { className: "pb-3", children: _jsx("h3", { className: "text-sm font-medium", children: labels.title }) })), loading ? (_jsx(Skeleton, { className: "h-10 w-full" })) : options.length === 0 ? (_jsx("div", { className: "text-center text-sm text-muted-foreground py-8 border rounded-md bg-muted/30", children: labels.emptyState })) : (_jsx(MultiSelect, { options: options, selected: selectedIds, onChange: handleChange, placeholder: labels.selectPlaceholder, searchPlaceholder: labels.selectSearchPlaceholder, emptyMessage: labels.selectEmpty }))] }));
+    }, [api, canCreate, canDelete, fetchPivotAndMeta, useResolver, resolved, foreignKey, onChange, parentId, pivotIndex, pivotPath, refKey, selectedIds, syncing]);
+    return (_jsxs("div", { className: className, "data-relation-kind": kind, "data-relation-through": through, "data-relation-references": references, children: [labels.title && (_jsx("div", { className: "pb-3", children: _jsx("h3", { className: "text-sm font-medium", children: labels.title }) })), (loading || (useResolver && resolved.loading)) ? (_jsx(Skeleton, { className: "h-10 w-full" })) : options.length === 0 ? (_jsx("div", { className: "text-center text-sm text-muted-foreground py-8 border rounded-md bg-muted/30", children: labels.emptyState })) : (_jsx(MultiSelect, { options: options, selected: selectedIds, onChange: handleChange, placeholder: labels.selectPlaceholder, searchPlaceholder: labels.selectSearchPlaceholder, emptyMessage: labels.selectEmpty }))] }));
 }

package/dist/hotswap-reload-policy.d.ts

@@ -0,0 +1,155 @@
+import { type AddonManifestChangedMessage, type ManifestHotSwapClient, type WireHotSwapInvalidationOptions } from './manifest-hotswap-subscriber';
+/**
+ * One of three strategies for reacting to an `ADDON_MANIFEST_CHANGED` event:
+ *
+ *   * `"rekey"` — re-mount the addon route by flipping the key. Default.
+ *   * `"page-reload"` — `window.location.reload()`. Opt-in.
+ *   * `"manual"` — no automatic action; the host handles it via `onSwap`.
+ */
+export type HotSwapReloadStrategy = 'rekey' | 'page-reload' | 'manual';
+/**
+ * Config for {@link useHotSwapReload}. `strategy` is the only required field
+ * — pass `{ strategy: "rekey" }` for the default behaviour or omit the
+ * config entirely.
+ */
+export interface HotSwapReloadConfig {
+    /** Reload policy. See {@link HotSwapReloadStrategy}. */
+    strategy?: HotSwapReloadStrategy;
+    /**
+     * Optional gate invoked **before** the reload action fires. Return
+     * `false` (or a Promise resolving to `false`) to cancel — useful for
+     * "unsaved changes" prompts on immersive addons. Receives the original
+     * `ADDON_MANIFEST_CHANGED` message so the prompt can name the addon.
+     *
+     * Runs for `"page-reload"` (cancels the `window.location.reload()`)
+     * and `"rekey"` (cancels the version bump, leaving the addon mounted
+     * with the old code — the host can re-trigger the swap later by
+     * re-calling the hook output's `reload()` method).
+     *
+     * Ignored for `"manual"` — the host owns the reload there.
+     */
+    onBeforeReload?: (event: AddonManifestChangedMessage) => boolean | Promise<boolean>;
+    /**
+     * Side-effect hook invoked after the policy has run (or after
+     * `onBeforeReload` returned `false`). Receives the message and the
+     * effective action that was taken: `"rekey"`, `"page-reload"`,
+     * `"cancelled"` or `"manual"`. Hosts wire telemetry / toasts here.
+     */
+    onSwap?: (event: AddonManifestChangedMessage, action: 'rekey' | 'page-reload' | 'cancelled' | 'manual') => void;
+    /**
+     * Optional matcher forwarded to the underlying
+     * {@link useManifestHotSwapSubscriber} for cache invalidation.
+     */
+    matcher?: WireHotSwapInvalidationOptions['matcher'];
+}
+export interface UseHotSwapReloadResult {
+    /**
+     * Reactive map `addonKey → hashShort`. Stable identity per render
+     * (only changes when a swap lands). Wire it into
+     * `<AddonRoute version={addonVersionMap[addonKey]} ... />` so React
+     * re-keys the subtree on hash change.
+     *
+     * Missing entries return `undefined`; the AddonRoute treats that as
+     * "no version pinned yet" and keeps a stable key.
+     */
+    addonVersionMap: Record<string, string>;
+}
+/**
+ * Subscribe to manifest hot-swap events and apply a reload policy.
+ *
+ * **Strategy = `"rekey"` (default):**
+ *   maintains `addonVersionMap` so `<AddonRoute version=...>` re-keys
+ *   the subtree on every swap. The federation loader picks the new hash
+ *   up via {@link withVersionParam}, fetches a fresh `remoteEntry.js`,
+ *   and registers a new container.
+ *
+ * **Strategy = `"page-reload"` (opt-in):**
+ *   calls `onBeforeReload` (if supplied); if it resolves truthy,
+ *   `window.location.reload()` fires. The `addonVersionMap` is still
+ *   updated for callers that want to mirror it elsewhere.
+ *
+ * **Strategy = `"manual"`:**
+ *   no automatic action. The `onSwap` callback fires with `"manual"`;
+ *   the host decides what to do. `addonVersionMap` is updated so a
+ *   later opt-in remount picks up the right hash.
+ *
+ * @example
+ *   const ws = useWebSocket()
+ *   useManifestHotSwapSubscriber(ws) // invalidates metadata cache
+ *   const { addonVersionMap } = useHotSwapReload({ strategy: 'rekey' })
+ *   // …in your router:
+ *   <AddonRoute version={addonVersionMap[addonKey]}>
+ *     <AddonLoader scope={addonKey} url={url} api={api} />
+ *   </AddonRoute>
+ */
+/**
+ * Effect that {@link applyHotSwapReload} can take. Useful as a discriminator
+ * for tests and telemetry callbacks. `"noop"` is emitted when a malformed
+ * message is ignored (e.g. missing `addonKey`).
+ */
+export type HotSwapReloadAction = 'rekey' | 'page-reload' | 'cancelled' | 'manual' | 'noop';
+export interface HotSwapReloadDeps {
+    /** Hash → versionMap setter. Receives an updater fn, à la React state. */
+    setVersionMap: (updater: (prev: Record<string, string>) => Record<string, string>) => void;
+    /** Defaults to `window.location.reload`. Overridable for tests / SSR. */
+    reload?: () => void;
+}
+/**
+ * Pure (testable) implementation of the swap handler. Decides the action
+ * given a message + config + deps, applies side effects via `deps`, and
+ * returns the action it took so callers can fire telemetry.
+ *
+ * Exported for unit tests; the React hook below composes it with React
+ * state. Hosts that want to drive the policy from a non-React context
+ * (e.g. a vanilla web component shell) can call this directly.
+ */
+export declare function applyHotSwapReload(message: AddonManifestChangedMessage, config: HotSwapReloadConfig, deps: HotSwapReloadDeps): Promise<HotSwapReloadAction>;
+export declare function useHotSwapReload(client: ManifestHotSwapClient | undefined | null, config?: HotSwapReloadConfig): UseHotSwapReloadResult;
+/**
+ * Append a `?v=<hash8>` query string to a `remoteEntry.js` URL so the
+ * browser treats it as a distinct resource and bypasses any HTTP / module
+ * cache. Idempotent — calling twice with the same hash returns the same
+ * URL. Preserves existing query params; replaces a previous `v=` entry if
+ * present so successive bumps don't accumulate stale parameters.
+ *
+ * Pure function (no `window` access) — safe to call in SSR.
+ *
+ * @example
+ *   withVersionParam('/api/addons/pos/frontend/remoteEntry.js', 'abc123ef')
+ *   // → '/api/addons/pos/frontend/remoteEntry.js?v=abc123ef'
+ *
+ *   withVersionParam('/r.js?foo=1', 'abc123ef')
+ *   // → '/r.js?foo=1&v=abc123ef'
+ *
+ *   withVersionParam('/r.js?v=oldhash', 'abc123ef')
+ *   // → '/r.js?v=abc123ef'
+ */
+export declare function withVersionParam(url: string, hash: string | undefined): string;
+/**
+ * Remove the federation container previously registered on `window[scope]`.
+ * Hosts call this from `onSwap` before letting the addon route re-mount
+ * so the next `remoteEntry.js` injection creates a fresh container instead
+ * of short-circuiting on the cached one.
+ *
+ * Best-effort: if `window` is undefined (SSR) or the scope was never
+ * registered, this is a no-op. Returns `true` if a container was actually
+ * removed, `false` otherwise — useful for telemetry.
+ *
+ * **Caveat:** some federation runtimes wrap the container in a Proxy
+ * whose internal state survives `delete`. If you hit `Container already
+ * registered` after calling this, the federation runtime is holding the
+ * reference internally and the only reliable swap is `"page-reload"`.
+ */
+export declare function clearFederationContainer(scope: string): boolean;
+/**
+ * Normalise a manifest hash for cache-busting. Accepts the full kernel
+ * format (`sha256:abc...`), a bare hex digest, or `undefined`. Returns
+ * an 8-character lowercase prefix that's short enough to keep URLs
+ * readable while remaining collision-resistant across realistic addon
+ * versioning timelines.
+ *
+ * Exported for tests; hosts that want the full hash for their own
+ * telemetry should read `message.payload.newHash` directly.
+ */
+export declare function shortenHash(hash: string | undefined): string | undefined;
+//# sourceMappingURL=hotswap-reload-policy.d.ts.map

package/dist/hotswap-reload-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hotswap-reload-policy.d.ts","sourceRoot":"","sources":["../src/hotswap-reload-policy.ts"],"names":[],"mappings":"AA+DA,OAAO,EAEH,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EACtC,MAAM,+BAA+B,CAAA;AAEtC;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,aAAa,GAAG,QAAQ,CAAA;AAEtE;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAChC,wDAAwD;IACxD,QAAQ,CAAC,EAAE,qBAAqB,CAAA;IAChC;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,CACb,KAAK,EAAE,2BAA2B,KACjC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CACL,KAAK,EAAE,2BAA2B,EAClC,MAAM,EAAE,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,KACvD,IAAI,CAAA;IACT;;;OAGG;IACH,OAAO,CAAC,EAAE,8BAA8B,CAAC,SAAS,CAAC,CAAA;CACtD;AAED,MAAM,WAAW,sBAAsB;IACnC;;;;;;;;OAQG;IACH,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GACzB,OAAO,GACP,aAAa,GACb,WAAW,GACX,QAAQ,GACR,MAAM,CAAA;AAEZ,MAAM,WAAW,iBAAiB;IAC9B,0EAA0E;IAC1E,aAAa,EAAE,CACX,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAChE,IAAI,CAAA;IACT,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACpC,OAAO,EAAE,2BAA2B,EACpC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,iBAAiB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CA6C9B;AAED,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,qBAAqB,GAAG,SAAS,GAAG,IAAI,EAChD,MAAM,GAAE,mBAAwB,GACjC,sBAAsB,CA2BxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAiB9E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAa/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOxE"}

package/dist/hotswap-reload-policy.js

@@ -0,0 +1,227 @@
+// hotswap-reload-policy — closes the last piece of RFC-0001 D4 ("zero-polling
+// hot-swap") on the client. The {@link useManifestHotSwapSubscriber} hook
+// already invalidates the metadata cache when the kernel announces a manifest
+// change, but the federation container of an already-mounted addon keeps the
+// old code in memory. This module picks one of three policies for forcing the
+// new code to take effect:
+//
+//   1. `"rekey"` — the default, **recommended for most apps**. Maintains a
+//      reactive map `addonKey → hashShort` that the host wires into
+//      `<AddonRoute version={...} />`. When a swap arrives, the hash flips,
+//      React unmounts and remounts the addon subtree, which causes the
+//      federation loader to re-fetch `remoteEntry.js` (cache-busted via
+//      {@link withVersionParam}) and re-evaluate the exposed module. State
+//      inside the addon is lost — **intentional**, because the code version
+//      changed and stale closures over old props/state would be a footgun.
+//
+//   2. `"page-reload"` — `window.location.reload()`. Opt-in escape hatch
+//      for immersive addons with critical state (POS with an order in
+//      progress, kitchen-display with partial confirmations). Pair with
+//      `onBeforeReload` to surface an "unsaved changes" prompt before
+//      blowing the page away. Returning `false` from `onBeforeReload`
+//      cancels the reload.
+//
+//   3. `"manual"` — the hook only invokes the host-provided `onSwap`
+//      callback. The host decides what to do (e.g. show a toast: "New
+//      version available — reload when ready"). No automatic remount, no
+//      reload. The `addonVersionMap` is still updated so a host that wires
+//      `<AddonRoute version=...>` later in the lifecycle picks up the new
+//      hash on demand.
+//
+// ## Wiring example
+//
+// ```tsx
+// // Host shell (4-5 line wire-up):
+// const ws = useWebSocket()
+// useManifestHotSwapSubscriber(ws)                      // invalidates metadata
+// const { addonVersionMap } = useHotSwapReload({ strategy: "rekey" })
+// // …in your router:
+// <AddonRoute version={addonVersionMap[addonKey]} shell={renderShell}>
+//   <AddonLoader scope={addonKey} url={remoteEntryUrl} api={api} />
+// </AddonRoute>
+// ```
+//
+// ## Federation runtime caveat
+//
+// The `"rekey"` strategy re-fetches `remoteEntry.js` with a `?v=<hash8>` query
+// suffix (see {@link withVersionParam}). For the new container to replace the
+// old one, the federation loader **must** `delete window[Container]` before
+// loading the new script — otherwise the cached container object short-
+// circuits the loader and you get `Container already registered` style errors
+// or, worse, the old code silently keeps running. This module exports
+// {@link clearFederationContainer} for that purpose; the host's federation
+// loader should call it from its `onSwap` hook.
+//
+// We deliberately keep the `delete window[Container]` side-effect OUT of this
+// module's default behaviour. Some federation runtimes (vite-plugin-federation
+// in dev, webpack 5 with `runtime: false`) wrap the container in a `Proxy`
+// that mutates internal state on every access; blindly deleting it from
+// here would race against any unmounting consumer that still holds a
+// reference. Hosts that hit `Container already registered` should call
+// `clearFederationContainer(scope)` from `onSwap` as documented below.
+import { useMemo, useRef, useState } from 'react';
+import { useManifestHotSwapSubscriber, } from './manifest-hotswap-subscriber';
+/**
+ * Pure (testable) implementation of the swap handler. Decides the action
+ * given a message + config + deps, applies side effects via `deps`, and
+ * returns the action it took so callers can fire telemetry.
+ *
+ * Exported for unit tests; the React hook below composes it with React
+ * state. Hosts that want to drive the policy from a non-React context
+ * (e.g. a vanilla web component shell) can call this directly.
+ */
+export async function applyHotSwapReload(message, config, deps) {
+    const strategy = config.strategy ?? 'rekey';
+    const addonKey = message.payload?.addonKey;
+    if (!addonKey)
+        return 'noop';
+    const shortHash = shortenHash(message.payload?.newHash);
+    if (strategy === 'manual') {
+        if (shortHash) {
+            deps.setVersionMap((m) => ({ ...m, [addonKey]: shortHash }));
+        }
+        config.onSwap?.(message, 'manual');
+        return 'manual';
+    }
+    if (config.onBeforeReload) {
+        const proceed = await Promise.resolve(config.onBeforeReload(message));
+        if (!proceed) {
+            config.onSwap?.(message, 'cancelled');
+            return 'cancelled';
+        }
+    }
+    if (strategy === 'page-reload') {
+        config.onSwap?.(message, 'page-reload');
+        const reload = deps.reload ??
+            (typeof window !== 'undefined'
+                ? () => window.location.reload()
+                : undefined);
+        if (reload) {
+            // Defer so any setState before us commits before we tear down.
+            queueMicrotask(reload);
+        }
+        return 'page-reload';
+    }
+    // strategy === "rekey"
+    if (shortHash) {
+        deps.setVersionMap((m) => {
+            if (m[addonKey] === shortHash)
+                return m;
+            return { ...m, [addonKey]: shortHash };
+        });
+    }
+    config.onSwap?.(message, 'rekey');
+    return 'rekey';
+}
+export function useHotSwapReload(client, config = {}) {
+    const [addonVersionMap, setAddonVersionMap] = useState({});
+    // Keep config behind a ref so changing callbacks between renders does
+    // not re-subscribe to the WebSocket / tear down listeners.
+    const configRef = useRef(config);
+    configRef.current = config;
+    // Stable handler for the underlying subscriber — reads the latest
+    // config out of the ref every time the WS emits.
+    const handleSwap = useMemo(() => (message) => {
+        void applyHotSwapReload(message, configRef.current, {
+            setVersionMap: setAddonVersionMap,
+        });
+    }, []);
+    useManifestHotSwapSubscriber(client, {
+        matcher: config.matcher,
+        onSwap: handleSwap,
+    });
+    return { addonVersionMap };
+}
+/**
+ * Append a `?v=<hash8>` query string to a `remoteEntry.js` URL so the
+ * browser treats it as a distinct resource and bypasses any HTTP / module
+ * cache. Idempotent — calling twice with the same hash returns the same
+ * URL. Preserves existing query params; replaces a previous `v=` entry if
+ * present so successive bumps don't accumulate stale parameters.
+ *
+ * Pure function (no `window` access) — safe to call in SSR.
+ *
+ * @example
+ *   withVersionParam('/api/addons/pos/frontend/remoteEntry.js', 'abc123ef')
+ *   // → '/api/addons/pos/frontend/remoteEntry.js?v=abc123ef'
+ *
+ *   withVersionParam('/r.js?foo=1', 'abc123ef')
+ *   // → '/r.js?foo=1&v=abc123ef'
+ *
+ *   withVersionParam('/r.js?v=oldhash', 'abc123ef')
+ *   // → '/r.js?v=abc123ef'
+ */
+export function withVersionParam(url, hash) {
+    if (!hash)
+        return url;
+    const short = shortenHash(hash);
+    if (!short)
+        return url;
+    const hashIdx = url.indexOf('#');
+    const fragment = hashIdx >= 0 ? url.slice(hashIdx) : '';
+    const base = hashIdx >= 0 ? url.slice(0, hashIdx) : url;
+    const qIdx = base.indexOf('?');
+    if (qIdx < 0)
+        return `${base}?v=${short}${fragment}`;
+    const head = base.slice(0, qIdx);
+    const query = base.slice(qIdx + 1);
+    // Drop any previous v= entry and re-append.
+    const parts = query
+        .split('&')
+        .filter((p) => p.length > 0 && !p.startsWith('v='));
+    parts.push(`v=${short}`);
+    return `${head}?${parts.join('&')}${fragment}`;
+}
+/**
+ * Remove the federation container previously registered on `window[scope]`.
+ * Hosts call this from `onSwap` before letting the addon route re-mount
+ * so the next `remoteEntry.js` injection creates a fresh container instead
+ * of short-circuiting on the cached one.
+ *
+ * Best-effort: if `window` is undefined (SSR) or the scope was never
+ * registered, this is a no-op. Returns `true` if a container was actually
+ * removed, `false` otherwise — useful for telemetry.
+ *
+ * **Caveat:** some federation runtimes wrap the container in a Proxy
+ * whose internal state survives `delete`. If you hit `Container already
+ * registered` after calling this, the federation runtime is holding the
+ * reference internally and the only reliable swap is `"page-reload"`.
+ */
+export function clearFederationContainer(scope) {
+    if (typeof window === 'undefined')
+        return false;
+    if (!(scope in window))
+        return false;
+    try {
+        delete window[scope];
+        return true;
+    }
+    catch {
+        // Some browsers refuse to delete non-configurable globals. Set
+        // to undefined as a fallback so the loader's `if (!window[scope])`
+        // check still triggers a re-inject.
+        ;
+        window[scope] = undefined;
+        return true;
+    }
+}
+/**
+ * Normalise a manifest hash for cache-busting. Accepts the full kernel
+ * format (`sha256:abc...`), a bare hex digest, or `undefined`. Returns
+ * an 8-character lowercase prefix that's short enough to keep URLs
+ * readable while remaining collision-resistant across realistic addon
+ * versioning timelines.
+ *
+ * Exported for tests; hosts that want the full hash for their own
+ * telemetry should read `message.payload.newHash` directly.
+ */
+export function shortenHash(hash) {
+    if (!hash)
+        return undefined;
+    const colonIdx = hash.indexOf(':');
+    const digest = colonIdx >= 0 ? hash.slice(colonIdx + 1) : hash;
+    const trimmed = digest.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.slice(0, 8).toLowerCase();
+}

package/dist/index.d.ts

@@ -4,12 +4,15 @@ export * from './dynamic-table';
 export * from './dynamic-form';
 export { ActionModalDispatcher, type ActionModalProps, } from './action-modal-dispatcher';
 export * from './addon-loader';
+export { AddonLayoutProvider, useAddonLayout, useAddonLayoutControl, useDeclareAddonLayout, type AddonLayout, type AddonLayoutProviderProps, } from './addon-layout-context';
 export * from './slot';
 export * from './capability-gate';
 export * from './navigation-builder';
 export * from './i18n-provider';
 export * from './api-context';
 export * from './metadata-cache';
+export { ADDON_MANIFEST_CHANGED_TYPE, wireHotSwapInvalidation, useManifestHotSwapSubscriber, type AddonManifestChangedMessage, type ManifestHotSwapClient, type WireHotSwapInvalidationOptions, } from './manifest-hotswap-subscriber';
+export { useHotSwapReload, applyHotSwapReload, withVersionParam, clearFederationContainer, shortenHash, type HotSwapReloadStrategy, type HotSwapReloadConfig, type HotSwapReloadAction, type HotSwapReloadDeps, type UseHotSwapReloadResult, } from './hotswap-reload-policy';
 export * from './dynamic-icon';
 export type { ColumnFilterConfig, FilterOption as DynamicColumnFilterOption, GetDynamicColumns, DynamicIconComponent, } from './dynamic-columns-shim';
 export { defaultGetDynamicColumns, makeDefaultGetDynamicColumns, type DynamicColumnsHelpers, } from './dynamic-columns';
@@ -20,4 +23,7 @@ export { DynamicCRUDPage, type DynamicCRUDPageProps, type DynamicCRUDPageStrings
 export { DynamicRelation, type DynamicRelationProps, type DynamicRelationStrings, type DynamicRelationKind, buildRelationFilterParams, buildCreatePayload, deriveRelationFormFields, relationRowKey, } from './dynamic-relation';
 export { registerModelExtension, getModelExtension, clearModelExtensions, type ModelExtension, type ModelExtensionProps, } from './model-extension-registry';
 export { isColumnVisibleInTable, getSearchableColumnKeys, } from './column-visibility';
+export { useOptionsResolver, projectOption, type ResolvedOption, type OptionsMeta, type UseOptionsResolverArgs, type UseOptionsResolverResult, } from './use-options-resolver';
+export { setOrgConfigBridge, getOrgConfigBridge, resolveValidatorToken, type OrgConfigBridge, } from './use-org-config-bridge';
+export { registerValidator } from './dynamic-form-schema';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,SAAS,CAAA;AACvB,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EACH,qBAAqB,EACrB,KAAK,gBAAgB,GACxB,MAAM,2BAA2B,CAAA;AAClC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,QAAQ,CAAA;AACtB,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,YAAY,EACR,kBAAkB,EAClB,YAAY,IAAI,yBAAyB,EACzC,iBAAiB,EACjB,oBAAoB,GACvB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACH,wBAAwB,EACxB,4BAA4B,EAC5B,KAAK,qBAAqB,GAC7B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EACH,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC9B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACH,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,GACjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GAC3B,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACH,sBAAsB,EACtB,uBAAuB,GAC1B,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,SAAS,CAAA;AACvB,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EACH,qBAAqB,EACrB,KAAK,gBAAgB,GACxB,MAAM,2BAA2B,CAAA;AAClC,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EACH,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,WAAW,EAChB,KAAK,wBAAwB,GAChC,MAAM,wBAAwB,CAAA;AAC/B,cAAc,QAAQ,CAAA;AACtB,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,OAAO,EACH,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,GACtC,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACH,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,EACX,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,GAC9B,MAAM,yBAAyB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,YAAY,EACR,kBAAkB,EAClB,YAAY,IAAI,yBAAyB,EACzC,iBAAiB,EACjB,oBAAoB,GACvB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACH,wBAAwB,EACxB,4BAA4B,EAC5B,KAAK,qBAAqB,GAC7B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EACH,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC9B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACH,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,GACjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACH,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GAC3B,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACH,sBAAsB,EACtB,uBAAuB,GAC1B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACH,kBAAkB,EAClB,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,GAChC,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACH,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,eAAe,GACvB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/index.js

@@ -9,12 +9,15 @@ export * from './dynamic-table';
 export * from './dynamic-form';
 export { ActionModalDispatcher, } from './action-modal-dispatcher';
 export * from './addon-loader';
+export { AddonLayoutProvider, useAddonLayout, useAddonLayoutControl, useDeclareAddonLayout, } from './addon-layout-context';
 export * from './slot';
 export * from './capability-gate';
 export * from './navigation-builder';
 export * from './i18n-provider';
 export * from './api-context';
 export * from './metadata-cache';
+export { ADDON_MANIFEST_CHANGED_TYPE, wireHotSwapInvalidation, useManifestHotSwapSubscriber, } from './manifest-hotswap-subscriber';
+export { useHotSwapReload, applyHotSwapReload, withVersionParam, clearFederationContainer, shortenHash, } from './hotswap-reload-policy';
 export * from './dynamic-icon';
 export { defaultGetDynamicColumns, makeDefaultGetDynamicColumns, } from './dynamic-columns';
 export { DynamicRecordDialog } from './dialogs/dynamic-record';
@@ -24,3 +27,6 @@ export { DynamicCRUDPage, } from './dynamic-crud-page';
 export { DynamicRelation, buildRelationFilterParams, buildCreatePayload, deriveRelationFormFields, relationRowKey, } from './dynamic-relation';
 export { registerModelExtension, getModelExtension, clearModelExtensions, } from './model-extension-registry';
 export { isColumnVisibleInTable, getSearchableColumnKeys, } from './column-visibility';
+export { useOptionsResolver, projectOption, } from './use-options-resolver';
+export { setOrgConfigBridge, getOrgConfigBridge, resolveValidatorToken, } from './use-org-config-bridge';
+export { registerValidator } from './dynamic-form-schema';