@asteby/metacore-runtime-react 31.1.0 → 32.0.0

package/src/__tests__/addon-fiber.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+    composeDisposables,
+    disposableFromRegisterResult,
+    isAddonFrontendCacheUrl,
+    resolvePluginExports,
+    runDispose,
+    shouldReregisterRemote,
+    markRemoteRegistered,
+    resetRemoteRegistry,
+} from '../addon-fiber'
+
+describe('isAddonFrontendCacheUrl', () => {
+    it('matches kernel and legacy frontend paths for that addon only', () => {
+        expect(
+            isAddonFrontendCacheUrl(
+                'https://app.example/api/metacore/addons/pos/frontend/remoteEntry.js?v=abc',
+                'pos',
+            ),
+        ).toBe(true)
+        expect(
+            isAddonFrontendCacheUrl(
+                'https://app.example/api/addons/pos/frontend.js',
+                'pos',
+            ),
+        ).toBe(true)
+        expect(
+            isAddonFrontendCacheUrl(
+                'https://app.example/api/metacore/addons/kds/frontend/remoteEntry.js',
+                'pos',
+            ),
+        ).toBe(false)
+        expect(
+            isAddonFrontendCacheUrl(
+                'https://app.example/api/metadata/pos',
+                'pos',
+            ),
+        ).toBe(false)
+    })
+})
+
+describe('resolvePluginExports', () => {
+    it('reads a named register export', () => {
+        const register = vi.fn()
+        expect(resolvePluginExports({ register }).register).toBe(register)
+    })
+
+    it('reads definePlugin default object', () => {
+        const register = vi.fn()
+        const dispose = vi.fn()
+        const resolved = resolvePluginExports({
+            default: { key: 'pos', register, dispose },
+        })
+        expect(resolved.register).toBeTypeOf('function')
+        expect(resolved.dispose).toBeTypeOf('function')
+    })
+
+    it('reads a default function module', () => {
+        const register = vi.fn()
+        expect(resolvePluginExports({ default: register }).register).toBe(register)
+    })
+
+    it('returns empty for null', () => {
+        expect(resolvePluginExports(null)).toEqual({})
+    })
+})
+
+describe('composeDisposables', () => {
+    it('runs disposers in reverse order (Cordis effects)', async () => {
+        const order: number[] = []
+        const d = composeDisposables(
+            () => {
+                order.push(1)
+            },
+            () => {
+                order.push(2)
+            },
+        )
+        await d()
+        expect(order).toEqual([2, 1])
+    })
+})
+
+describe('runDispose', () => {
+    it('swallows disposer errors', async () => {
+        await expect(
+            runDispose(() => {
+                throw new Error('boom')
+            }),
+        ).resolves.toBeUndefined()
+    })
+})
+
+describe('disposableFromRegisterResult', () => {
+    it('returns functions and ignores void', () => {
+        const d = () => {}
+        expect(disposableFromRegisterResult(d)).toBe(d)
+        expect(disposableFromRegisterResult(undefined)).toBeUndefined()
+    })
+})
+
+describe('remote registry', () => {
+    it('reregisters only when the entry URL changes', () => {
+        resetRemoteRegistry()
+        expect(shouldReregisterRemote('metacore_pos', '/r.js?v=1')).toBe(true)
+        markRemoteRegistered('metacore_pos', '/r.js?v=1')
+        expect(shouldReregisterRemote('metacore_pos', '/r.js?v=1')).toBe(false)
+        expect(shouldReregisterRemote('metacore_pos', '/r.js?v=2')).toBe(true)
+        resetRemoteRegistry()
+    })
+})

package/src/__tests__/prefill-from-record.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'vitest'
+import { buildPrefillRows, isPrefillSpec, applyPrefillLock, type PrefillSpec } from '../action-modal-dispatcher'
+import type { ActionFieldDef } from '../types'
+
+// receive-goods-style item_fields: the canonical use case ($prefillFromRecord
+// + map + remaining + lock), same shape inventory's receive_transfer and
+// purchases' receive_goods declare in their manifest.json.
+const receiveField = (overrides: Partial<ActionFieldDef> = {}): ActionFieldDef => ({
+    key: 'lines',
+    label: 'Renglones',
+    type: 'array',
+    itemFields: [
+        { key: 'product_id', label: 'Producto', type: 'dynamic_select', ref: 'Product' },
+        { key: 'ordered', label: 'Ordenado', type: 'number' },
+        { key: 'received_so_far', label: 'Ya recibido', type: 'number' },
+        { key: 'qty_received', label: 'Cantidad recibida', type: 'number', required: true },
+    ],
+    ...overrides,
+})
+
+describe('isPrefillSpec', () => {
+    it('reconoce un objeto con $prefillFromRecord como PrefillSpec', () => {
+        expect(isPrefillSpec({ $prefillFromRecord: 'items' })).toBe(true)
+    })
+
+    it('rechaza un default literal (string/number) o un objeto sin $prefillFromRecord', () => {
+        expect(isPrefillSpec('walk-in')).toBe(false)
+        expect(isPrefillSpec(42)).toBe(false)
+        expect(isPrefillSpec(null)).toBe(false)
+        expect(isPrefillSpec(undefined)).toBe(false)
+        expect(isPrefillSpec({ map: { a: 'b' } })).toBe(false)
+    })
+})
+
+describe('buildPrefillRows', () => {
+    it('proyecta record[$prefillFromRecord] a filas usando map', () => {
+        const spec: PrefillSpec = {
+            $prefillFromRecord: 'items',
+            map: { product_id: 'product_id', ordered: 'quantity' },
+        }
+        const record = {
+            items: [
+                { product_id: 'p1', quantity: 10 },
+                { product_id: 'p2', quantity: 5 },
+            ],
+        }
+        expect(buildPrefillRows(spec, record)).toEqual([
+            { product_id: 'p1', ordered: 10 },
+            { product_id: 'p2', ordered: 5 },
+        ])
+    })
+
+    it('calcula remaining.target = of - minus por fila', () => {
+        const spec: PrefillSpec = {
+            $prefillFromRecord: 'items',
+            map: { product_id: 'product_id' },
+            remaining: { target: 'qty_received', of: 'quantity', minus: 'received' },
+        }
+        const record = { items: [{ product_id: 'p1', quantity: 10, received: 4 }] }
+        expect(buildPrefillRows(spec, record)).toEqual([{ product_id: 'p1', qty_received: 6 }])
+    })
+
+    it('con remaining.minus omitido, remaining = of tal cual (minus lee como 0)', () => {
+        const spec: PrefillSpec = {
+            $prefillFromRecord: 'items',
+            remaining: { target: 'qty_received', of: 'quantity' },
+        }
+        const record = { items: [{ quantity: 7 }] }
+        expect(buildPrefillRows(spec, record)).toEqual([{ qty_received: 7 }])
+    })
+
+    it('omite filas ya satisfechas por completo (remaining <= 0)', () => {
+        const spec: PrefillSpec = {
+            $prefillFromRecord: 'items',
+            map: { product_id: 'product_id' },
+            remaining: { target: 'qty_received', of: 'quantity', minus: 'received' },
+        }
+        const record = {
+            items: [
+                { product_id: 'p1', quantity: 10, received: 10 }, // satisfecha -> fuera
+                { product_id: 'p2', quantity: 10, received: 12 }, // sobre-recibida -> fuera
+                { product_id: 'p3', quantity: 10, received: 3 }, // pendiente -> queda
+            ],
+        }
+        expect(buildPrefillRows(spec, record)).toEqual([{ product_id: 'p3', qty_received: 7 }])
+    })
+
+    it('combina map + remaining en el mismo caso real de receive_transfer/receive_goods', () => {
+        const spec: PrefillSpec = {
+            $prefillFromRecord: 'items',
+            map: { product_id: 'product_id', ordered: 'quantity', received_so_far: 'received' },
+            remaining: { target: 'qty_received', of: 'quantity', minus: 'received' },
+            lock: ['product_id', 'ordered', 'received_so_far'],
+        }
+        const record = { items: [{ product_id: 'p1', quantity: 10, received: 4 }] }
+        expect(buildPrefillRows(spec, record)).toEqual([
+            { product_id: 'p1', ordered: 10, received_so_far: 4, qty_received: 6 },
+        ])
+    })
+
+    it('registro sin filas (o campo ausente/no-array) da prefill vacío, sin explotar', () => {
+        const spec: PrefillSpec = { $prefillFromRecord: 'items' }
+        expect(buildPrefillRows(spec, { items: [] })).toEqual([])
+        expect(buildPrefillRows(spec, {})).toEqual([])
+        expect(buildPrefillRows(spec, { items: 'not-an-array' })).toEqual([])
+        expect(buildPrefillRows(spec, null)).toEqual([])
+    })
+
+    it('ignora entradas no-objeto dentro del array origen', () => {
+        const spec: PrefillSpec = { $prefillFromRecord: 'items', map: { product_id: 'product_id' } }
+        const record = { items: [null, { product_id: 'p1' }, undefined, 42] }
+        expect(buildPrefillRows(spec, record)).toEqual([{ product_id: 'p1' }])
+    })
+})
+
+describe('applyPrefillLock', () => {
+    it('marca readonly las columnas listadas en lock', () => {
+        const field = receiveField({
+            default: {
+                $prefillFromRecord: 'items',
+                lock: ['product_id', 'ordered', 'received_so_far'],
+            } as PrefillSpec,
+        } as Partial<ActionFieldDef>)
+        const patched = applyPrefillLock(field) as ActionFieldDef & { itemFields?: any[] }
+        const byKey = Object.fromEntries((patched.itemFields ?? []).map((c: any) => [c.key, c]))
+        expect(byKey.product_id.readonly).toBe(true)
+        expect(byKey.ordered.readonly).toBe(true)
+        expect(byKey.received_so_far.readonly).toBe(true)
+        expect(byKey.qty_received.readonly).toBeUndefined()
+    })
+
+    it('sin lock (o sin prefill spec) deja el field intacto', () => {
+        const plain = receiveField()
+        expect(applyPrefillLock(plain)).toBe(plain)
+
+        const noLock = receiveField({
+            default: { $prefillFromRecord: 'items' } as PrefillSpec,
+        } as Partial<ActionFieldDef>)
+        expect(applyPrefillLock(noLock)).toBe(noLock)
+    })
+
+    it('un default literal (no PrefillSpec) deja el field intacto', () => {
+        const field = receiveField({ default: 'walk-in' } as Partial<ActionFieldDef>)
+        expect(applyPrefillLock(field)).toBe(field)
+    })
+})

package/src/action-modal-dispatcher.tsx

@@ -81,7 +81,7 @@ export type { ActionMetadata, ActionModalProps }
 //     "map": { "product_id": "product_id" },
 //     "remaining": { "target": "qty_received", "of": "quantity", "minus": "received" }
 //   }
-interface PrefillSpec {
+export interface PrefillSpec {
     $prefillFromRecord: string
     map?: Record<string, string>
     remaining?: { target: string; of: string; minus?: string }
@@ -94,7 +94,7 @@ interface PrefillSpec {
     lock?: string[]
 }
 
-function isPrefillSpec(v: unknown): v is PrefillSpec {
+export function isPrefillSpec(v: unknown): v is PrefillSpec {
     return (
         typeof v === 'object' &&
         v !== null &&
@@ -122,7 +122,7 @@ function toNum(v: unknown): number {
 // untouched when there is no prefill spec or no lock list (the create flow,
 // which carries no prefill, stays fully editable). The readonly flag is set on
 // BOTH itemFields aliases the renderers tolerate.
-function applyPrefillLock(field: ActionFieldDef): ActionFieldDef {
+export function applyPrefillLock(field: ActionFieldDef): ActionFieldDef {
     const spec = lineItemsDefault(field)
     if (!isPrefillSpec(spec) || !spec.lock || spec.lock.length === 0) return field
     const lock = new Set(spec.lock)
@@ -134,7 +134,7 @@ function applyPrefillLock(field: ActionFieldDef): ActionFieldDef {
 }
 
 // buildPrefillRows projects record[spec.$prefillFromRecord] into modal rows.
-function buildPrefillRows(spec: PrefillSpec, record: any): Array<Record<string, any>> {
+export function buildPrefillRows(spec: PrefillSpec, record: any): Array<Record<string, any>> {
     const src = record?.[spec.$prefillFromRecord]
     if (!Array.isArray(src)) return []
     const rows: Array<Record<string, any>> = []

package/src/addon-fiber.ts

@@ -0,0 +1,155 @@
+/**
+ * Addon fiber primitives — Cordis-style dispose/reload for federated modules
+ * running inside a PWA host. Pure helpers so they unit-test without React
+ * or the Module Federation runtime.
+ */
+
+import type { AddonAPI, Disposable, Plugin } from '@asteby/metacore-sdk'
+
+export const PURGE_ADDON_MESSAGE = 'PURGE_ADDON' as const
+
+export interface PurgeAddonMessage {
+    type: typeof PURGE_ADDON_MESSAGE
+    key: string
+}
+
+/** Shape of the exposed `./register` (or `./plugin`) module. */
+export interface AddonRegisterModule {
+    register?: Plugin['register']
+    dispose?: Plugin['dispose']
+    default?: Plugin['register'] | Plugin
+}
+
+export interface ResolvedPlugin {
+    register?: Plugin['register']
+    dispose?: Plugin['dispose']
+}
+
+/**
+ * Accept every historical export shape:
+ *   - `{ register, dispose? }`
+ *   - `{ default: { register, dispose? } }`  (definePlugin)
+ *   - `{ default: (api) => ... }`            (function module)
+ */
+export function resolvePluginExports(mod: AddonRegisterModule | null | undefined): ResolvedPlugin {
+    if (!mod) return {}
+    const fromDefault =
+        mod.default && typeof mod.default === 'object'
+            ? (mod.default as Plugin)
+            : undefined
+    const registerFn =
+        typeof mod.register === 'function'
+            ? mod.register
+            : typeof fromDefault?.register === 'function'
+              ? fromDefault.register.bind(fromDefault)
+              : typeof mod.default === 'function'
+                ? mod.default
+                : undefined
+    const disposeFn =
+        typeof mod.dispose === 'function'
+            ? mod.dispose
+            : typeof fromDefault?.dispose === 'function'
+              ? fromDefault.dispose.bind(fromDefault)
+              : undefined
+    return { register: registerFn, dispose: disposeFn }
+}
+
+export async function runDispose(dispose?: Disposable | null): Promise<void> {
+    if (typeof dispose !== 'function') return
+    try {
+        await Promise.resolve(dispose())
+    } catch {
+        /* a failing disposer must not block the next fiber mount */
+    }
+}
+
+export function composeDisposables(...fns: Array<Disposable | undefined | null>): Disposable {
+    const list = fns.filter((f): f is Disposable => typeof f === 'function')
+    return async () => {
+        for (let i = list.length - 1; i >= 0; i--) {
+            await runDispose(list[i])
+        }
+    }
+}
+
+/**
+ * True when a Cache API / SW request is a federated frontend asset of `addonKey`.
+ * Matches both `/api/addons/<key>/frontend` and `/api/metacore/addons/<key>/frontend`.
+ */
+export function isAddonFrontendCacheUrl(url: string, addonKey: string): boolean {
+    if (!addonKey || !url) return false
+    try {
+        const path = new URL(url, 'http://local.invalid').pathname
+        const escaped = addonKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        return new RegExp(`/api/(metacore/)?addons/${escaped}/frontend(/|\\.js)`).test(path)
+    } catch {
+        return false
+    }
+}
+
+/**
+ * Drop cached federation assets for one addon. Primary path is the page-side
+ * Cache API (works even before the SW learns `PURGE_ADDON`). Also posts the
+ * message so a current SW can drop its own entries.
+ *
+ * Never unregisters the SW and never deletes other caches — L1, not L2.
+ */
+export async function purgeAddonFrontendCache(addonKey: string): Promise<void> {
+    if (!addonKey) return
+    try {
+        if (typeof caches !== 'undefined') {
+            const names = await caches.keys()
+            await Promise.all(
+                names.map(async (name) => {
+                    if (!name.includes('addon-federation')) return
+                    const cache = await caches.open(name)
+                    const requests = await cache.keys()
+                    await Promise.all(
+                        requests
+                            .filter((req) => isAddonFrontendCacheUrl(req.url, addonKey))
+                            .map((req) => cache.delete(req)),
+                    )
+                }),
+            )
+        }
+    } catch {
+        /* private mode / no Cache API */
+    }
+    try {
+        if (typeof navigator !== 'undefined' && 'serviceWorker' in navigator) {
+            const controller = navigator.serviceWorker.controller
+            controller?.postMessage({ type: PURGE_ADDON_MESSAGE, key: addonKey } satisfies PurgeAddonMessage)
+        }
+    } catch {
+        /* no SW */
+    }
+}
+
+/** Test seam: which remote URL is currently registered per federation scope. */
+export const remoteEntryByScope = new Map<string, string>()
+
+export function shouldReregisterRemote(scope: string, url: string): boolean {
+    return remoteEntryByScope.get(scope) !== url
+}
+
+export function markRemoteRegistered(scope: string, url: string): void {
+    remoteEntryByScope.set(scope, url)
+}
+
+/** @internal tests */
+export function resetRemoteRegistry(): void {
+    remoteEntryByScope.clear()
+}
+
+/**
+ * Safe no-op when `register()` returns void. Used by AddonLoader to treat
+ * both historical and fiber-style plugins uniformly.
+ */
+export function disposableFromRegisterResult(
+    result: void | Disposable,
+): Disposable | undefined {
+    return typeof result === 'function' ? result : undefined
+}
+
+/** Type-only re-export so AddonLoader does not import Plugin internals twice. */
+export type { AddonAPI, Disposable }

package/src/addon-loader.tsx

@@ -3,17 +3,26 @@
 // `remoteEntry.js` as an ESM container, loads the exposed `./register` module,
 // and calls `register(api)` with the AddonAPI injected by the host.
 //
-// Why @module-federation/runtime (not the old manual init/get machinery):
-// the host's Vite build uses `@module-federation/vite`'s `federation()` plugin,
-// which auto-initialises the shared scope at host boot. `registerRemotes` +
-// `loadRemote` then transparently wire the remote into that already-initialised
-// share scope — so the remote consumes the HOST's React/SDK singletons instead
-// of bundling its own. That's the whole point: it fixes the `useState`-null
-// crash WITHOUT this loader ever touching a share scope manually.
+// Fiber lifecycle (Cordis-style): when `url` (the `?v=` cache-bust) changes,
+// the previous plugin.dispose / returned Disposable run, the host registry
+// unbinds that addonKey, the SW addon-federation cache for that key is
+// purged, and register() runs again against the new remote. The host shell
+// (auth, QueryClient, WebSocket, service worker controller) is not touched.
 import { useEffect, useRef, useState } from 'react'
 import { registerRemotes, loadRemote } from '@module-federation/runtime'
-import type { AddonAPI, AddonLayout } from '@asteby/metacore-sdk'
+import type { AddonAPI, AddonLayout, Registry } from '@asteby/metacore-sdk'
 import { useDeclareAddonLayout } from './addon-layout-context'
+import {
+    composeDisposables,
+    disposableFromRegisterResult,
+    markRemoteRegistered,
+    purgeAddonFrontendCache,
+    resolvePluginExports,
+    runDispose,
+    shouldReregisterRemote,
+    type AddonRegisterModule,
+    type Disposable,
+} from './addon-fiber'
 
 export interface AddonLoaderProps {
     /** Unique key of the addon — maps to the federation container name. */
@@ -24,9 +33,25 @@ export interface AddonLoaderProps {
     module?: string
     /** Host-provided API passed to the addon's register() call. */
     api: AddonAPI
+    /**
+     * Host registry used to {@link Registry.unbind} this addon's contributions
+     * on dispose. Optional so legacy hosts keep compiling; without it, fiber
+     * remounts leak routes/actions.
+     */
+    hostRegistry?: Registry
+    /**
+     * Addon key for SW cache purge. Defaults to `api.manifest.key`.
+     */
+    addonKey?: string
+    /**
+     * Registry owner passed to {@link Registry.unbind}. Defaults to `addonKey`.
+     * Immersive `./plugin` fibers use `${key}::view` so they don't wipe the
+     * shell `./register` contributions of the same addon.
+     */
+    unbindKey?: string
     /** Optional rendering while loading. */
     fallback?: React.ReactNode
-    /** Called once the addon has successfully registered. */
+    /** Called once the addon has successfully registered (including re-register). */
     onReady?: () => void
     /** Called if loading fails. */
     onError?: (err: Error) => void
@@ -45,17 +70,6 @@ export interface AddonLoaderProps {
     children?: React.ReactNode
 }
 
-/** Shape of the exposed `./register` module. */
-interface AddonRegisterModule {
-    register?: (api: AddonAPI) => void | Promise<void>
-    default?: (api: AddonAPI) => void | Promise<void>
-}
-
-// `registerRemotes` is additive + idempotent across re-mounts; we still track
-// which scopes we've registered to avoid redundant `force` churn (each `force`
-// re-register wipes that remote's module cache and logs a runtime warning).
-const registered = new Set<string>()
-
 // Derive the `loadRemote` id from the scope + exposed module name. MF resolves
 // `"<remoteName>/<expose>"` — e.g. `metacore_tickets/register` for the
 // `"./register"` expose. We strip the leading `./` of the expose path.
@@ -100,28 +114,15 @@ async function loadAddon(
     url: string,
     module: string,
 ): Promise<AddonRegisterModule | null> {
-    // Register the remote container as an ES module. `type: 'module'` matches
-    // the `@module-federation/vite` remote (remoteEntry.js is an ESM bundle).
-    // The `url` already carries the `?v=` cache-bust the host computed, so the
-    // browser refetches a fresh remoteEntry when the addon version changes.
-    //
-    // Both calls are wrapped in `withRuntimeReady` because EITHER can throw
-    // RUNTIME-009 when an addon mounts ahead of the host's federation init —
-    // registration is what actually touches the (maybe-uninitialised) runtime.
-    if (!registered.has(scope)) {
+    // Re-register whenever the `?v=` URL changes so a fiber swap actually
+    // fetches the new remoteEntry. `force: true` wipes that remote's module
+    // cache — without it, loadRemote would keep serving the previous bundle.
+    if (shouldReregisterRemote(scope, url)) {
         await withRuntimeReady(() =>
-            registerRemotes(
-                [{ name: scope, entry: url, type: 'module' }],
-                // `force: true` so a re-registration with a new `?v=` URL (addon
-                // hot-swap / version bump) overwrites the stale entry + cache.
-                { force: true },
-            ),
+            registerRemotes([{ name: scope, entry: url, type: 'module' }], { force: true }),
         )
-        registered.add(scope)
+        markRemoteRegistered(scope, url)
     }
-    // loadRemote("<scope>/<expose>") returns the exposed module namespace (or
-    // null if it can't be resolved). No manual share-scope init — the host's
-    // federation runtime already initialised it.
     return withRuntimeReady(() =>
         loadRemote<AddonRegisterModule>(remoteId(scope, module)),
     )
@@ -132,6 +133,9 @@ export function AddonLoader({
     url,
     module = './register',
     api,
+    hostRegistry,
+    addonKey,
+    unbindKey,
     fallback = null,
     onReady,
     onError,
@@ -140,7 +144,7 @@ export function AddonLoader({
 }: AddonLoaderProps) {
     const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading')
     const [error, setError] = useState<Error | null>(null)
-    const didRegister = useRef(false)
+    const disposeRef = useRef<Disposable | undefined>(undefined)
 
     // Propagate the addon's preferred layout to the host shell via context.
     // No-op when `layout` is undefined or `"shell"` (legacy default). Cleanup
@@ -150,20 +154,28 @@ export function AddonLoader({
 
     useEffect(() => {
         let cancelled = false
+        const key = addonKey || api.manifest?.key
+        const owner = unbindKey || key
         ;(async () => {
             try {
+                setStatus('loading')
+                if (key) await purgeAddonFrontendCache(key)
                 const mod = await loadAddon(scope, url, module)
                 if (cancelled) return
-                const register = mod?.register ?? mod?.default
-                if (typeof register !== 'function') {
+                const plugin = resolvePluginExports(mod)
+                if (typeof plugin.register !== 'function') {
                     throw new Error(
                         `Addon "${scope}" module "${module}" has no register() export`,
                     )
                 }
-                if (!didRegister.current) {
-                    didRegister.current = true
-                    await Promise.resolve(register(api))
-                }
+                // Drop leftover contributions from a previous fiber of this key
+                // before the new register() runs (idempotent if none).
+                if (owner && hostRegistry) hostRegistry.unbind(owner)
+                const ret = await Promise.resolve(plugin.register(api))
+                disposeRef.current = composeDisposables(
+                    disposableFromRegisterResult(ret),
+                    plugin.dispose,
+                )
                 setStatus('ready')
                 onReady?.()
             } catch (e: unknown) {
@@ -176,8 +188,15 @@ export function AddonLoader({
         })()
         return () => {
             cancelled = true
+            const d = disposeRef.current
+            disposeRef.current = undefined
+            void runDispose(d)
+            if (owner && hostRegistry) hostRegistry.unbind(owner)
         }
-    }, [scope, url, module])
+        // api identity is expected to be stable per addon; including it would
+        // re-register on every parent render. Fiber identity is (scope, url, module).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [scope, url, module, addonKey, unbindKey, hostRegistry])
 
     if (status === 'loading') return <>{fallback}</>
     if (status === 'error')

package/src/index.ts

@@ -122,6 +122,17 @@ export {
     type ActionPlacement,
 } from './model-action-toolbar'
 export * from './addon-loader'
+export {
+    PURGE_ADDON_MESSAGE,
+    isAddonFrontendCacheUrl,
+    purgeAddonFrontendCache,
+    resolvePluginExports,
+    composeDisposables,
+    runDispose,
+    type PurgeAddonMessage,
+    type AddonRegisterModule,
+    type ResolvedPlugin,
+} from './addon-fiber'
 export {
     AddonLayoutProvider,
     useAddonLayout,