@asteby/metacore-runtime-react 9.2.0 → 10.0.0

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';

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;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"}
+{"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';

package/dist/manifest-hotswap-subscriber.d.ts

@@ -0,0 +1,83 @@
+import { type AddonKeyMatcher } from './metadata-cache';
+/**
+ * `type` string the kernel/bridge emits. Exported so consumers can subscribe
+ * manually if they prefer to skip the hook/wire helper. Matches
+ * `bridge.WSManifestChangedType` in metacore-kernel.
+ */
+export declare const ADDON_MANIFEST_CHANGED_TYPE: "ADDON_MANIFEST_CHANGED";
+/**
+ * Shape of the WebSocket message the kernel emits. The keys mirror the
+ * `bridge.manifestChangedPayload` map in metacore-kernel/bridge — keep them
+ * in sync if the bridge ever evolves.
+ */
+export interface AddonManifestChangedMessage {
+    type: typeof ADDON_MANIFEST_CHANGED_TYPE;
+    payload: {
+        orgId?: string;
+        addonKey: string;
+        oldHash?: string;
+        newHash?: string;
+        version?: string;
+        timestamp?: string;
+    };
+}
+/**
+ * Structural client contract. The SDK's `@asteby/metacore-websocket`
+ * provider exposes `subscribe(type, handler)` (see `useWebSocket().subscribe`)
+ * that satisfies this interface — but any object with a compatible method
+ * works, so hosts that wrap their own transport (link's MQTT bridge, the
+ * kitchen-display ZeroMQ stub, …) can plug in without depending on the
+ * SDK websocket package.
+ */
+export interface ManifestHotSwapClient {
+    subscribe: (type: string, handler: (message: AddonManifestChangedMessage) => void) => () => void;
+}
+export interface WireHotSwapInvalidationOptions {
+    /**
+     * Optional matcher overriding the default cache-key heuristic
+     * (see `defaultAddonKeyMatcher`). Hosts that namespace cached
+     * `model` keys under prefixes other than `${addonKey}.|:|/` should
+     * supply one.
+     */
+    matcher?: AddonKeyMatcher;
+    /**
+     * Optional side-effect hook invoked after the cache invalidation.
+     * Useful for hosts that want to log/observe hot-swaps or trigger a
+     * `window.location.reload()` when the running addon's bundle hash
+     * changes (see the module-level comment above for the trade-off).
+     * `removed` is the number of cache entries flushed for this addon.
+     */
+    onSwap?: (msg: AddonManifestChangedMessage, removed: number) => void;
+}
+/**
+ * Imperative wire-up — no React required. Hosts that own a long-lived
+ * WebSocket client (link, ops, the kitchen-display Tauri shell) call this
+ * once at boot, after the client has been created. The returned function
+ * unsubscribes; most hosts will never call it because the subscription
+ * lives for the lifetime of the app.
+ *
+ *   const ws = createWebSocket(...)
+ *   const unsubscribe = wireHotSwapInvalidation(ws)
+ *   // …later, if needed:
+ *   unsubscribe()
+ *
+ * Accepts `undefined` so the call site does not need to branch when the
+ * client is constructed lazily — it returns a no-op unsubscribe.
+ */
+export declare function wireHotSwapInvalidation(client: ManifestHotSwapClient | undefined | null, options?: WireHotSwapInvalidationOptions): () => void;
+/**
+ * React-flavoured wrapper around {@link wireHotSwapInvalidation}. Mount it
+ * once high in the tree (typically next to the WebSocket provider) so the
+ * subscription lifetime matches the host shell. Passing `undefined` for
+ * the client is supported — the hook becomes a no-op until a real client
+ * is available, mirroring how `useWebSocket().subscribe` behaves before
+ * the socket opens.
+ *
+ *   function HostShell() {
+ *     const ws = useWebSocket()
+ *     useManifestHotSwapSubscriber(ws)
+ *     return <Outlet />
+ *   }
+ */
+export declare function useManifestHotSwapSubscriber(client: ManifestHotSwapClient | undefined | null, options?: WireHotSwapInvalidationOptions): void;
+//# sourceMappingURL=manifest-hotswap-subscriber.d.ts.map

package/dist/manifest-hotswap-subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-hotswap-subscriber.d.ts","sourceRoot":"","sources":["../src/manifest-hotswap-subscriber.ts"],"names":[],"mappings":"AA6CA,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEzE;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAG,wBAAiC,CAAA;AAE5E;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IACxC,IAAI,EAAE,OAAO,2BAA2B,CAAA;IACxC,OAAO,EAAE;QACL,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,SAAS,CAAC,EAAE,MAAM,CAAA;KACrB,CAAA;CACJ;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IAClC,SAAS,EAAE,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,OAAO,EAAE,2BAA2B,KAAK,IAAI,KACtD,MAAM,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,8BAA8B;IAC3C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,2BAA2B,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACnC,MAAM,EAAE,qBAAqB,GAAG,SAAS,GAAG,IAAI,EAChD,OAAO,GAAE,8BAAmC,GAC7C,MAAM,IAAI,CAeZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CACxC,MAAM,EAAE,qBAAqB,GAAG,SAAS,GAAG,IAAI,EAChD,OAAO,GAAE,8BAAmC,GAC7C,IAAI,CAON"}

package/dist/manifest-hotswap-subscriber.js

@@ -0,0 +1,104 @@
+// manifest-hotswap-subscriber — client-side closure of RFC-0001 D4.
+//
+// The kernel installer (see metacore-kernel/installer/broadcaster.go) emits a
+// WebSocket message every time it observes a manifest-hash change at persist
+// time. The bridge (metacore-kernel/bridge/installer_broadcaster.go) fans it
+// out per-org over `ws.Hub.SendToUsers` with this exact envelope:
+//
+//   {
+//     "type": "ADDON_MANIFEST_CHANGED",
+//     "payload": {
+//       "orgId": "<uuid>",
+//       "addonKey": "kitchen_display",
+//       "oldHash": "sha256:...",
+//       "newHash": "sha256:...",
+//       "version": "1.2.0",
+//       "timestamp": "2026-05-11T12:34:56Z"
+//     }
+//   }
+//
+// (The original RFC scratchpad used snake_case keys; the bridge canonicalised
+// them to camelCase so the SDK's metadata-cache reducer can consume the
+// payload verbatim. This module matches the bridge — the source of truth.)
+//
+// This module wires the message into `useMetadataCache().invalidateAddon` so
+// every cached table/modal metadata entry belonging to the bumped addon is
+// dropped from the zustand store. The next mount of any `DynamicTable` or
+// `DynamicCRUDPage` will refetch fresh metadata, picking up whatever the
+// new manifest changed (new fields, renamed actions, dropped relations…).
+//
+// IMPORTANT — a freshly-bumped addon whose `remoteEntry.js` URL changes will
+// also need its federation container reloaded. Cache invalidation handles
+// metadata; it does NOT swap the JS already executing in memory. If your
+// host wants the new code to take effect immediately, either:
+//
+//   1. force a full `window.location.reload()` when an `addon:manifest:changed`
+//      event arrives for the addon currently mounted, or
+//   2. for immersive addons (`layout: "immersive"`) where users tolerate a
+//      flicker, key the addon route component on `newHash` so React unmounts
+//      and remounts the AddonLoader with the new remoteEntry URL.
+//
+// The subscriber here intentionally stops at metadata-cache: deciding when
+// to reload is a host policy decision and we keep this module side-effect
+// free beyond the cache.
+import { useEffect } from 'react';
+import { useMetadataCache } from './metadata-cache';
+/**
+ * `type` string the kernel/bridge emits. Exported so consumers can subscribe
+ * manually if they prefer to skip the hook/wire helper. Matches
+ * `bridge.WSManifestChangedType` in metacore-kernel.
+ */
+export const ADDON_MANIFEST_CHANGED_TYPE = 'ADDON_MANIFEST_CHANGED';
+/**
+ * Imperative wire-up — no React required. Hosts that own a long-lived
+ * WebSocket client (link, ops, the kitchen-display Tauri shell) call this
+ * once at boot, after the client has been created. The returned function
+ * unsubscribes; most hosts will never call it because the subscription
+ * lives for the lifetime of the app.
+ *
+ *   const ws = createWebSocket(...)
+ *   const unsubscribe = wireHotSwapInvalidation(ws)
+ *   // …later, if needed:
+ *   unsubscribe()
+ *
+ * Accepts `undefined` so the call site does not need to branch when the
+ * client is constructed lazily — it returns a no-op unsubscribe.
+ */
+export function wireHotSwapInvalidation(client, options = {}) {
+    if (!client)
+        return () => { };
+    const { matcher, onSwap } = options;
+    const unsubscribe = client.subscribe(ADDON_MANIFEST_CHANGED_TYPE, (message) => {
+        const addonKey = message?.payload?.addonKey;
+        if (!addonKey)
+            return;
+        const removed = useMetadataCache
+            .getState()
+            .invalidateAddon(addonKey, matcher);
+        onSwap?.(message, removed);
+    });
+    return unsubscribe;
+}
+/**
+ * React-flavoured wrapper around {@link wireHotSwapInvalidation}. Mount it
+ * once high in the tree (typically next to the WebSocket provider) so the
+ * subscription lifetime matches the host shell. Passing `undefined` for
+ * the client is supported — the hook becomes a no-op until a real client
+ * is available, mirroring how `useWebSocket().subscribe` behaves before
+ * the socket opens.
+ *
+ *   function HostShell() {
+ *     const ws = useWebSocket()
+ *     useManifestHotSwapSubscriber(ws)
+ *     return <Outlet />
+ *   }
+ */
+export function useManifestHotSwapSubscriber(client, options = {}) {
+    const { matcher, onSwap } = options;
+    useEffect(() => {
+        if (!client)
+            return;
+        const unsubscribe = wireHotSwapInvalidation(client, { matcher, onSwap });
+        return unsubscribe;
+    }, [client, matcher, onSwap]);
+}

package/dist/metadata-cache.d.ts

@@ -4,6 +4,21 @@ export interface MetadataApiClient {
         data: any;
     }>;
 }
+/**
+ * Predicate matching a cache key against an addon. The default
+ * implementation (see {@link defaultAddonKeyMatcher}) treats `addonKey`
+ * itself plus any key beginning with `${addonKey}.`, `${addonKey}:` or
+ * `${addonKey}/` as belonging to the addon. Hosts that namespace their
+ * `model` strings differently can pass a custom matcher to
+ * {@link MetadataCacheState.invalidateAddon}.
+ */
+export type AddonKeyMatcher = (cacheKey: string, addonKey: string) => boolean;
+/**
+ * Default matcher used by {@link MetadataCacheState.invalidateAddon}.
+ * Mirrors the convention used by the kernel installer when it scopes
+ * model metadata under an addon's key.
+ */
+export declare function defaultAddonKeyMatcher(cacheKey: string, addonKey: string): boolean;
 interface MetadataCacheState {
     cache: Record<string, TableMetadata>;
     modalCache: Record<string, TableMetadata>;
@@ -16,6 +31,26 @@ interface MetadataCacheState {
     hasMetadata: (key: string) => boolean;
     hasModalMetadata: (key: string) => boolean;
     prefetchAll: (api: MetadataApiClient) => Promise<void>;
+    /**
+     * Remove cached entries belonging to a specific addon. Used by the
+     * hot-swap subscriber when the kernel announces a manifest change.
+     *
+     * Returns the number of entries removed across both caches, which is
+     * useful for tests and observability — `0` means the cache had nothing
+     * to flush (the addon either hadn't been hit yet or uses a key
+     * convention the default matcher doesn't recognise; pass a custom
+     * `matcher` if your host namespaces differently).
+     *
+     * Also resets `prefetched` to `false` so the next mount re-runs
+     * `prefetchAll()` and the `metadataVersion` is allowed to advance to
+     * the kernel's freshly-bumped hash.
+     */
+    invalidateAddon: (addonKey: string, matcher?: AddonKeyMatcher) => number;
+    /**
+     * Remove every cached entry. Heavier hammer for hosts that prefer a
+     * blanket flush on hot-swap rather than per-addon scoping.
+     */
+    clearAll: () => void;
 }
 export declare const useMetadataCache: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<MetadataCacheState>, "setState" | "persist"> & {
     setState(partial: MetadataCacheState | Partial<MetadataCacheState> | ((state: MetadataCacheState) => MetadataCacheState | Partial<MetadataCacheState>), replace?: false | undefined): unknown;

package/dist/metadata-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata-cache.d.ts","sourceRoot":"","sources":["../src/metadata-cache.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,CAAA;KAAE,CAAC,CAAA;CAC7D;AAED,UAAU,kBAAkB;IACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACzC,eAAe,EAAE,MAAM,CAAA;IACvB,UAAU,EAAE,OAAO,CAAA;IACnB,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAA;IACvD,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAA;IAC5D,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAA;IAC3D,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAA;IAChE,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IACrC,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IAC1C,WAAW,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACzD;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;EAwE5B,CAAA"}
+{"version":3,"file":"metadata-cache.d.ts","sourceRoot":"","sources":["../src/metadata-cache.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,CAAA;KAAE,CAAC,CAAA;CAC7D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAA;AAE7E;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQlF;AAED,UAAU,kBAAkB;IACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACzC,eAAe,EAAE,MAAM,CAAA;IACvB,UAAU,EAAE,OAAO,CAAA;IACnB,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAA;IACvD,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAA;IAC5D,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAA;IAC3D,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAA;IAChE,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IACrC,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IAC1C,WAAW,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD;;;;;;;;;;;;;OAaG;IACH,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,MAAM,CAAA;IACxE;;;OAGG;IACH,QAAQ,EAAE,MAAM,IAAI,CAAA;CACvB;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;EAiH5B,CAAA"}

package/dist/metadata-cache.js

@@ -8,6 +8,20 @@
 // never invokes prefetchAll, the `api` dep is not required.
 import { create } from 'zustand';
 import { persist } from 'zustand/middleware';
+/**
+ * Default matcher used by {@link MetadataCacheState.invalidateAddon}.
+ * Mirrors the convention used by the kernel installer when it scopes
+ * model metadata under an addon's key.
+ */
+export function defaultAddonKeyMatcher(cacheKey, addonKey) {
+    if (!addonKey)
+        return false;
+    if (cacheKey === addonKey)
+        return true;
+    return (cacheKey.startsWith(`${addonKey}.`) ||
+        cacheKey.startsWith(`${addonKey}:`) ||
+        cacheKey.startsWith(`${addonKey}/`));
+}
 export const useMetadataCache = create()(persist((set, get) => ({
     cache: {},
     modalCache: {},
@@ -27,6 +41,47 @@ export const useMetadataCache = create()(persist((set, get) => ({
     },
     hasMetadata: (key) => key in get().cache,
     hasModalMetadata: (key) => key in get().modalCache,
+    invalidateAddon: (addonKey, matcher = defaultAddonKeyMatcher) => {
+        if (!addonKey)
+            return 0;
+        let removed = 0;
+        const state = get();
+        const nextCache = {};
+        for (const [key, value] of Object.entries(state.cache)) {
+            if (matcher(key, addonKey)) {
+                removed += 1;
+                continue;
+            }
+            nextCache[key] = value;
+        }
+        const nextModalCache = {};
+        for (const [key, value] of Object.entries(state.modalCache)) {
+            if (matcher(key, addonKey)) {
+                removed += 1;
+                continue;
+            }
+            nextModalCache[key] = value;
+        }
+        if (removed === 0)
+            return 0;
+        set({
+            cache: nextCache,
+            modalCache: nextModalCache,
+            // Allow prefetchAll() to re-run so we pick up the new
+            // metadataVersion the kernel emits alongside the
+            // bumped manifest.
+            prefetched: false,
+        });
+        return removed;
+    },
+    clearAll: () => {
+        set({
+            cache: {},
+            modalCache: {},
+            metadataVersion: '',
+            prefetched: false,
+        });
+    },
     prefetchAll: async (api) => {
         if (get().prefetched)
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "9.2.0",
+  "version": "10.0.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",
@@ -32,7 +32,7 @@
     "lucide-react": ">=0.460",
     "date-fns": ">=3",
     "react-day-picker": ">=8",
-    "@asteby/metacore-sdk": "^2.4.0",
+    "@asteby/metacore-sdk": "^2.5.0",
     "@asteby/metacore-ui": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -60,7 +60,7 @@
     "typescript": "^6.0.0",
     "vitest": "^4.0.0",
     "zustand": "^5.0.0",
-    "@asteby/metacore-sdk": "2.4.0",
+    "@asteby/metacore-sdk": "2.5.0",
     "@asteby/metacore-ui": "2.0.0"
   },
   "scripts": {