@asteby/metacore-runtime-react 9.2.0 → 11.0.0

package/CHANGELOG.md

@@ -1,5 +1,167 @@
 # @asteby/metacore-runtime-react
 
+## 11.0.0
+
+### Patch Changes
+
+- 3a3ea4b: fix: unify slot priority ordering across SDK and runtime-react (was
+  inconsistent — DESC is now canonical, see `docs/slot-priority.md`).
+
+  `Registry.registerSlot` in `@asteby/metacore-sdk` sorted ascending
+  ("lower renders first") while `slotRegistry` in
+  `@asteby/metacore-runtime-react` sorted descending ("higher renders
+  first"). The runtime-react behaviour matches `docs/dynamic-ui.md`,
+  `mergeNavigation` and every other priority sort in the codebase, so the
+  SDK has been flipped to match. Addons that register a single
+  contribution per slot — i.e. every in-tree consumer we audited — are
+  unaffected. Addons relying on the inverted SDK order will need to swap
+  their priority values.
+
+- Updated dependencies [dee623a]
+- Updated dependencies [56d2013]
+- Updated dependencies [1c4a108]
+- Updated dependencies [3a3ea4b]
+  - @asteby/metacore-sdk@2.6.0
+
+## 10.0.0
+
+### Minor Changes
+
+- 9ce8269: feat: hot-swap reload policy (RFC-0001 D4 close)
+
+  Closes the gap between `useManifestHotSwapSubscriber` (already invalidates
+  the metadata cache) and the federation container of an already-mounted
+  addon, which keeps the old code in memory until something forces a
+  re-evaluation.
+
+  **runtime-react:**
+  - New `hotswap-reload-policy` module ships three policies and a single
+    hook that wires the chosen policy to the manifest hot-swap stream:
+    - `useHotSwapReload(client, { strategy })` returns `{ addonVersionMap }`
+      — a reactive map `addonKey → hashShort` that hosts wire into
+      `<AddonRoute version={addonVersionMap[addonKey]} ... />`. Default
+      strategy is `"rekey"`: React unmounts and remounts the addon subtree
+      on every swap, which forces the federation loader to re-fetch
+      `remoteEntry.js?v=<hash8>` and re-evaluate the exposed module.
+    - `strategy: "page-reload"` is an opt-in `window.location.reload()`
+      escape hatch for immersive addons with critical in-progress state
+      (POS, kitchen-display). Pair with `onBeforeReload` to surface an
+      "unsaved changes" prompt — returning `false` cancels the reload.
+    - `strategy: "manual"` only invokes `onSwap` with the message;
+      the host decides what to do.
+  - `clearFederationContainer(scope)` helper for hosts that hit
+    `Container already registered` after a re-key; call it from the
+    `onSwap` callback before the addon route re-mounts.
+  - `applyHotSwapReload` exported for non-React shells that want to
+    drive the policy from a vanilla container.
+
+  **sdk:**
+  - `loadFederatedAddon(spec, addonKey, version?)` accepts an optional
+    `version` so the loader cache-busts `remoteEntry.js` via
+    `?v=<hash8>` when the manifest hash bumps. Cache key includes the
+    version so a fresh hash triggers a fresh load instead of returning
+    the memoized old container.
+  - New `withVersionParam(url, hash)` helper (idempotent, fragment-safe,
+    replaces prior `v=` entries) exported for symmetry — the
+    runtime-react module re-uses the same algorithm.
+
+  **starter-core:**
+  - `<AddonRoute>` accepts a new optional `version?: string` prop. When
+    it changes, the route's children are wrapped in a `Fragment` with a
+    new `key`, forcing the federation loader to re-evaluate.
+
+  ### Host wire-up (4-5 lines)
+
+  ```tsx
+  const ws = useWebSocket()
+  useManifestHotSwapSubscriber(ws)                         // metadata cache
+  const { addonVersionMap } = useHotSwapReload(ws, { strategy: 'rekey' })
+  // …in your router:
+  <AddonRoute version={addonVersionMap[addonKey]} shell={renderShell}>
+    <AddonLoader scope={addonKey} url={remoteEntryUrl} api={api} />
+  </AddonRoute>
+  ```
+
+  Re-keying is intentionally destructive: any state inside the addon is
+  lost because the code version changed. Hosts that need a confirmation
+  gate should pass `onBeforeReload` and prompt the user before the swap
+  applies.
+
+- 04362f2: feat: immersive layout, federation shared-deps helper polish, wasm client
+
+  **sdk:**
+  - `FrontendSpec` now carries `layout?: "shell" | "immersive"`. Mirrors the
+    upcoming kernel-side `manifest.FrontendSpec.Layout` field. `undefined` is
+    treated as `"shell"` (legacy behaviour) so the change is purely additive.
+    Exposed as the `AddonLayout` type alias for explicit consumers.
+  - New `wasm-client` module — frontend twin of `kernel/runtime/wasm`. Ships
+    `loadAddonWasm({ url, integrity, imports })` (SRI verification + instantiate
+    pipeline) and `callAddonExport(instance, fn, payload)` honouring the same
+    `ptr<<32 | len` packed ABI the Go example backends use (`alloc`, `free`,
+    `memory`). Lets POS / kitchen-display / signage addons run their compiled
+    module locally for sub-50ms latency without a webhook round trip. Typed
+    errors (`WasmIntegrityError`, `WasmAbiError`) surface failure cause cleanly.
+
+  **runtime-react:**
+  - New `<AddonLayoutProvider>`, `useAddonLayout()`, `useAddonLayoutControl()`
+    and `useDeclareAddonLayout()` API in `addon-layout-context`. The host shell
+    reads the active layout and hides Sidebar / Topbar / breadcrumbs when an
+    addon declares `layout: "immersive"`. Cleanup restores chrome on unmount,
+    so navigating away from an immersive addon brings the shell back.
+  - `<AddonLoader>` accepts an optional `layout` prop and propagates it through
+    the context, so hosts get the chrome switch wired without per-route plumbing.
+
+  **starter-config:**
+  - `metacoreFederationShared()` now accepts `extra: Record<string, ShareConfig>`
+    for the typical "I just want to add a package with explicit config" case
+    (`extra: { lodash: { singleton: true } }`). The existing `extras: string[]`
+    and `overrides` knobs are retained for backwards compatibility.
+  - `METACORE_FEDERATION_SINGLETONS` adds `@asteby/metacore-app-providers` so
+    the SDK's transport-agnostic platform provider keeps a single instance
+    between host and addons.
+
+- ba60c8f: feat: immersive route wrapper + manifest hot-swap subscriber (RFC-0001 D1 + D4)
+
+  **runtime-react:**
+  - `metadata-cache` gains `invalidateAddon(addonKey, matcher?)` and `clearAll()`
+    so consumers can flush scoped cache entries when an addon's manifest hash
+    changes. The default matcher recognises `addonKey`, `${addonKey}.`,
+    `${addonKey}:` and `${addonKey}/` prefixes; hosts that namespace their
+    `model` keys differently can pass a custom matcher.
+  - New `manifest-hotswap-subscriber` module ships:
+    - `ADDON_MANIFEST_CHANGED_TYPE` — the `ws.MessageType` constant the kernel
+      emits via `bridge.WSManifestBroadcaster`.
+    - `wireHotSwapInvalidation(client, options?)` — imperative helper hosts call
+      once at boot. Accepts any object exposing `subscribe(type, handler)`
+      (structurally compatible with `useWebSocket().subscribe`), invalidates
+      the metadata cache for the bumped addon, and optionally invokes an
+      `onSwap` side-effect callback (handy for forcing a `window.location.reload()`
+      when the running addon's bundle hash changes, since metadata invalidation
+      alone does not swap the federation container already in memory).
+    - `useManifestHotSwapSubscriber(client)` — React hook variant for hosts
+      that prefer mounting the wire-up next to their WebSocket provider.
+
+  **starter-core:**
+  - New `AddonRoute` component closes the host side of RFC-0001 D1 (immersive
+    end-to-end). It reads `useAddonLayout()` from runtime-react and either
+    renders the addon inside a caller-provided shell renderer (default
+    `"shell"` layout) or strips chrome and pins the addon to the viewport
+    (`fixed inset-0 z-50`) when the active layout is `"immersive"`. Supports
+    both prop-driven layout (no shell flash for always-immersive routes like
+    POS / kitchen-display) and context-driven layout (addon calls
+    `useDeclareAddonLayout("immersive")` after mount). Cleanup restores
+    `"shell"` so navigating away brings the chrome back.
+
+  Together these closures unblock zero-polling hot-swap reloads in the
+  metadata layer and let immersive addons own the viewport without each app
+  re-implementing the shell branch.
+
+### Patch Changes
+
+- Updated dependencies [9ce8269]
+- Updated dependencies [04362f2]
+  - @asteby/metacore-sdk@2.5.0
+
 ## 9.2.0
 
 ### Minor Changes

package/dist/addon-layout-context.d.ts

@@ -0,0 +1,49 @@
+import type { AddonLayout } from '@asteby/metacore-sdk';
+export type { AddonLayout };
+interface AddonLayoutState {
+    /** Active layout. `"shell"` (default) or `"immersive"`. */
+    layout: AddonLayout;
+    /**
+     * Imperative setter for the host or an addon-loader to mutate the active
+     * layout. Exposed for advanced use; most callers should use
+     * `useDeclareAddonLayout(layout)` from a route component, which scopes the
+     * change to the route's mount lifetime.
+     */
+    setLayout: (layout: AddonLayout) => void;
+}
+export interface AddonLayoutProviderProps {
+    /** Initial layout — usually `"shell"`. */
+    initial?: AddonLayout;
+    children: React.ReactNode;
+}
+/**
+ * Wrap the host app once, above the router outlet. The provider keeps the
+ * currently-active layout in state; addon-loader and `useDeclareAddonLayout`
+ * mutate it from below.
+ */
+export declare function AddonLayoutProvider({ initial, children, }: AddonLayoutProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Read the currently-active layout. The host shell calls this and decides
+ * whether to render its chrome. Returns `"shell"` when no provider is
+ * mounted, so apps that have not adopted immersive addons keep working.
+ */
+export declare function useAddonLayout(): AddonLayout;
+/**
+ * Imperative API — the value returned mirrors `useAddonLayout()` but also
+ * exposes the setter for hosts that need to flip the layout outside of a
+ * route lifecycle (e.g. a hotkey forcing kiosk mode). Most addon entries do
+ * NOT need this; prefer `useDeclareAddonLayout`.
+ */
+export declare function useAddonLayoutControl(): AddonLayoutState;
+/**
+ * Declare the layout from the addon side. Mounts the value, restores
+ * `"shell"` on unmount. Skip when `layout` is undefined so route components
+ * can pass `manifest.frontend?.layout` directly without branching.
+ *
+ *   function PosEntry({ manifest }: { manifest: Manifest }) {
+ *     useDeclareAddonLayout(manifest.frontend?.layout)
+ *     return <PosScreen />
+ *   }
+ */
+export declare function useDeclareAddonLayout(layout: AddonLayout | undefined): void;
+//# sourceMappingURL=addon-layout-context.d.ts.map

package/dist/addon-layout-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon-layout-context.d.ts","sourceRoot":"","sources":["../src/addon-layout-context.tsx"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAEvD,YAAY,EAAE,WAAW,EAAE,CAAA;AAE3B,UAAU,gBAAgB;IACtB,2DAA2D;IAC3D,MAAM,EAAE,WAAW,CAAA;IACnB;;;;;OAKG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAA;CAC3C;AAWD,MAAM,WAAW,wBAAwB;IACrC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAChC,OAAiB,EACjB,QAAQ,GACX,EAAE,wBAAwB,2CAW1B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAExD;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAY3E"}

package/dist/addon-layout-context.js

@@ -0,0 +1,94 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// AddonLayoutContext — broadcast the active addon entry's layout selection
+// (`shell` vs `immersive`) up to the host so it can hide/show its chrome
+// (Sidebar, Topbar, breadcrumbs) when an immersive addon is mounted.
+//
+// Why a context rather than a prop on the host shell:
+//
+//   1. The host shell is rendered ABOVE the addon route in the tree, but the
+//      decision about what layout the addon wants comes from the addon itself
+//      (manifest.frontend.layout) which the AddonLoader knows about at mount
+//      time. A bottom-up signal via context inverts the dependency cleanly.
+//
+//   2. Addon entries can swap layouts at runtime (think a kiosk-mode toggle
+//      inside a POS). A context value reactively updates the host without
+//      asking each route to wire props.
+//
+//   3. When the user navigates AWAY from an immersive addon, the AddonLoader
+//      unmounts, its layout context updater fires `setLayout("shell")` from
+//      a cleanup effect, and the chrome restores automatically.
+//
+// Host integration (starter-core, ops, …):
+//
+//   function AppShell({ children }) {
+//     const layout = useAddonLayout()
+//     const chrome = layout !== "immersive"
+//     return (
+//       <div className={chrome ? "grid grid-cols-[280px_1fr]" : "h-dvh w-dvw"}>
+//         {chrome && <Sidebar />}
+//         <main>{chrome && <Topbar />}{children}</main>
+//       </div>
+//     )
+//   }
+//
+// The context defaults to `"shell"`, so apps that never mount an
+// `<AddonLayoutProvider>` keep the legacy behaviour.
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
+const defaultState = {
+    layout: 'shell',
+    setLayout: () => {
+        /* noop — provider missing; consumers degrade to legacy "shell" */
+    },
+};
+const AddonLayoutContext = createContext(defaultState);
+/**
+ * Wrap the host app once, above the router outlet. The provider keeps the
+ * currently-active layout in state; addon-loader and `useDeclareAddonLayout`
+ * mutate it from below.
+ */
+export function AddonLayoutProvider({ initial = 'shell', children, }) {
+    const [layout, setLayout] = useState(initial);
+    const value = useMemo(() => ({ layout, setLayout }), [layout]);
+    return (_jsx(AddonLayoutContext.Provider, { value: value, children: children }));
+}
+/**
+ * Read the currently-active layout. The host shell calls this and decides
+ * whether to render its chrome. Returns `"shell"` when no provider is
+ * mounted, so apps that have not adopted immersive addons keep working.
+ */
+export function useAddonLayout() {
+    return useContext(AddonLayoutContext).layout;
+}
+/**
+ * Imperative API — the value returned mirrors `useAddonLayout()` but also
+ * exposes the setter for hosts that need to flip the layout outside of a
+ * route lifecycle (e.g. a hotkey forcing kiosk mode). Most addon entries do
+ * NOT need this; prefer `useDeclareAddonLayout`.
+ */
+export function useAddonLayoutControl() {
+    return useContext(AddonLayoutContext);
+}
+/**
+ * Declare the layout from the addon side. Mounts the value, restores
+ * `"shell"` on unmount. Skip when `layout` is undefined so route components
+ * can pass `manifest.frontend?.layout` directly without branching.
+ *
+ *   function PosEntry({ manifest }: { manifest: Manifest }) {
+ *     useDeclareAddonLayout(manifest.frontend?.layout)
+ *     return <PosScreen />
+ *   }
+ */
+export function useDeclareAddonLayout(layout) {
+    const { setLayout } = useAddonLayoutControl();
+    // useCallback so the effect only re-runs on a real layout change, not on
+    // every render of the consumer that happens to forward an inline literal.
+    const apply = useCallback(setLayout, [setLayout]);
+    useEffect(() => {
+        if (!layout || layout === 'shell')
+            return;
+        apply(layout);
+        return () => {
+            apply('shell');
+        };
+    }, [layout, apply]);
+}

package/dist/addon-loader.d.ts

@@ -1,4 +1,4 @@
-import type { AddonAPI } from '@asteby/metacore-sdk';
+import type { AddonAPI, AddonLayout } from '@asteby/metacore-sdk';
 declare global {
     interface Window {
         [key: string]: any;
@@ -21,7 +21,19 @@ export interface AddonLoaderProps {
     onReady?: () => void;
     /** Called if loading fails. */
     onError?: (err: Error) => void;
+    /**
+     * Layout the host shell should render the addon under, mirroring
+     * `manifest.frontend.layout`. Default (undefined / `"shell"`) keeps the
+     * legacy chrome (Sidebar, Topbar, breadcrumbs). `"immersive"` flips the
+     * shared {@link useAddonLayout} context so the host shell hides chrome
+     * while the addon is mounted and restores it on unmount.
+     *
+     * Hosts that consume the context (see `useAddonLayout` /
+     * `<AddonLayoutProvider>`) do NOT need to branch on this prop themselves
+     * — the loader sets the context value via {@link useDeclareAddonLayout}.
+     */
+    layout?: AddonLayout;
     children?: React.ReactNode;
 }
-export declare function AddonLoader({ scope, url, module, api, fallback, onReady, onError, children, }: AddonLoaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function AddonLoader({ scope, url, module, api, fallback, onReady, onError, layout, children, }: AddonLoaderProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=addon-loader.d.ts.map

package/dist/addon-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"addon-loader.d.ts","sourceRoot":"","sources":["../src/addon-loader.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAEpD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,MAAM;QACZ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;QAClB,wBAAwB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QAC3D,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACrD;CACJ;AAED,MAAM,WAAW,gBAAgB;IAC7B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAA;IACX,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,GAAG,EAAE,QAAQ,CAAA;IACb,wCAAwC;IACxC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAA;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC7B;AAuCD,wBAAgB,WAAW,CAAC,EACxB,KAAK,EACL,GAAG,EACH,MAAqB,EACrB,GAAG,EACH,QAAe,EACf,OAAO,EACP,OAAO,EACP,QAAQ,GACX,EAAE,gBAAgB,2CAgClB"}
+{"version":3,"file":"addon-loader.d.ts","sourceRoot":"","sources":["../src/addon-loader.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAGjE,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,MAAM;QACZ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;QAClB,wBAAwB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QAC3D,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACrD;CACJ;AAED,MAAM,WAAW,gBAAgB;IAC7B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAA;IACX,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,GAAG,EAAE,QAAQ,CAAA;IACb,wCAAwC;IACxC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAA;IAC9B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC7B;AAuCD,wBAAgB,WAAW,CAAC,EACxB,KAAK,EACL,GAAG,EACH,MAAqB,EACrB,GAAG,EACH,QAAe,EACf,OAAO,EACP,OAAO,EACP,MAAM,EACN,QAAQ,GACX,EAAE,gBAAgB,2CAsClB"}

package/dist/addon-loader.js

@@ -3,6 +3,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 // waits for the `window[scope]` container to initialize, then calls the
 // addon's `register(api)` export with the AddonAPI injected by the host.
 import { useEffect, useRef, useState } from 'react';
+import { useDeclareAddonLayout } from './addon-layout-context';
 const loadedScripts = new Map();
 function loadScript(url, scope) {
     const key = `${scope}::${url}`;
@@ -34,10 +35,15 @@ async function loadRemote(scope, module) {
     const factory = await container.get(module);
     return factory();
 }
-export function AddonLoader({ scope, url, module = './register', api, fallback = null, onReady, onError, children, }) {
+export function AddonLoader({ scope, url, module = './register', api, fallback = null, onReady, onError, layout, children, }) {
     const [status, setStatus] = useState('loading');
     const [error, setError] = useState(null);
     const didRegister = useRef(false);
+    // Propagate the addon's preferred layout to the host shell via context.
+    // No-op when `layout` is undefined or `"shell"` (legacy default). Cleanup
+    // restores `"shell"` automatically when the loader unmounts, so chrome
+    // returns as soon as the user navigates away from an immersive addon.
+    useDeclareAddonLayout(layout);
     useEffect(() => {
         let cancelled = false;
         (async () => {

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"}