@asteby/metacore-runtime-react 9.2.0 → 11.0.0

package/src/manifest-hotswap-subscriber.ts

@@ -0,0 +1,164 @@
+// 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, 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 const ADDON_MANIFEST_CHANGED_TYPE = 'ADDON_MANIFEST_CHANGED' as const
+
+/**
+ * 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 function wireHotSwapInvalidation(
+    client: ManifestHotSwapClient | undefined | null,
+    options: WireHotSwapInvalidationOptions = {},
+): () => void {
+    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: ManifestHotSwapClient | undefined | null,
+    options: WireHotSwapInvalidationOptions = {},
+): void {
+    const { matcher, onSwap } = options
+    useEffect(() => {
+        if (!client) return
+        const unsubscribe = wireHotSwapInvalidation(client, { matcher, onSwap })
+        return unsubscribe
+    }, [client, matcher, onSwap])
+}

package/src/metadata-cache.ts

@@ -14,6 +14,31 @@ export interface MetadataApiClient {
     get: (url: string, config?: any) => Promise<{ 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 function defaultAddonKeyMatcher(cacheKey: string, addonKey: string): boolean {
+    if (!addonKey) return false
+    if (cacheKey === addonKey) return true
+    return (
+        cacheKey.startsWith(`${addonKey}.`) ||
+        cacheKey.startsWith(`${addonKey}:`) ||
+        cacheKey.startsWith(`${addonKey}/`)
+    )
+}
+
 interface MetadataCacheState {
     cache: Record<string, TableMetadata>
     modalCache: Record<string, TableMetadata>
@@ -26,6 +51,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 const useMetadataCache = create<MetadataCacheState>()(
@@ -54,6 +99,47 @@ export const useMetadataCache = create<MetadataCacheState>()(
             hasMetadata: (key: string) => key in get().cache,
             hasModalMetadata: (key: string) => key in get().modalCache,
 
+            invalidateAddon: (addonKey: string, matcher = defaultAddonKeyMatcher) => {
+                if (!addonKey) return 0
+                let removed = 0
+                const state = get()
+                const nextCache: Record<string, TableMetadata> = {}
+                for (const [key, value] of Object.entries(state.cache)) {
+                    if (matcher(key, addonKey)) {
+                        removed += 1
+                        continue
+                    }
+                    nextCache[key] = value
+                }
+                const nextModalCache: Record<string, TableMetadata> = {}
+                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: MetadataApiClient) => {
                 if (get().prefetched) return
                 try {

package/src/slot.tsx

@@ -22,6 +22,8 @@ class SlotRegistryImpl {
         const entry: SlotEntry = { id: slotId, component, priority: opts?.priority ?? 0, source: opts?.source }
         const list = this.slots.get(slotId) ?? []
         list.push(entry)
+        // Higher priority renders first — canonical across SDK and runtime-react.
+        // See docs/slot-priority.md.
         list.sort((a, b) => b.priority - a.priority)
         this.slots.set(slotId, list)
         this.emit()