@asteby/metacore-runtime-react 31.1.1 → 32.1.0

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/__tests__/validator.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest'
+import { parseRuleString, checkValue, validateValues, bagHasErrors } from '../validator'
+import type { ActionFieldDef } from '../types'
+
+describe('parseRuleString', () => {
+    it('parses Laravel pipes', () => {
+        const s = parseRuleString('required|min:2|max:10|email')
+        expect(s.required).toBe(true)
+        expect(s.min).toBe(2)
+        expect(s.max).toBe(10)
+        expect(s.custom).toBe('email')
+    })
+    it('parses go-playground commas', () => {
+        const s = parseRuleString('required,min=2,max=100')
+        expect(s.required).toBe(true)
+        expect(s.min).toBe(2)
+        expect(s.max).toBe(100)
+    })
+    it('treats a slug as custom', () => {
+        expect(parseRuleString('$org.tax_id_validator').custom).toBe('$org.tax_id_validator')
+    })
+})
+
+describe('checkValue', () => {
+    it('required on empty', () => {
+        expect(checkValue('', { required: true })).toEqual([{ code: 'required' }])
+        expect(checkValue('x', { required: true })).toEqual([])
+    })
+    it('min/max length on strings', () => {
+        expect(checkValue('ab', { type: 'string', min: 3 })).toEqual([
+            { code: 'min', params: { min: 3, kind: 'length' } },
+        ])
+    })
+    it('regex + email', () => {
+        expect(checkValue('nope', { type: 'string', regex: '^[A-Z]+$' })[0]?.code).toBe('regex')
+        expect(checkValue('a@b.com', { custom: 'email' })).toEqual([])
+        expect(checkValue('not-an-email', { custom: 'email' })[0]?.code).toBe('email')
+    })
+    it('skips other rules when empty and not required', () => {
+        expect(checkValue('', { type: 'string', min: 3, custom: 'email' })).toEqual([])
+    })
+})
+
+describe('validateValues', () => {
+    const fields: ActionFieldDef[] = [
+        { key: 'name', label: 'Nombre', type: 'text', required: true },
+        { key: 'sku', label: 'SKU', type: 'text', validation: { min: 3, regex: '^[A-Z]+$' } },
+        {
+            key: 'items',
+            label: 'Renglones',
+            type: 'array',
+            required: true,
+            itemFields: [{ key: 'qty', label: 'Cantidad', type: 'number', required: true }],
+        },
+    ]
+    it('collects every field including dotted line-items', () => {
+        const bag = validateValues(fields, { sku: 'ab', items: [{ qty: '' }] })
+        expect(bag.name?.[0]?.code).toBe('required')
+        expect(bag.sku?.map(i => i.code).sort()).toEqual(['min', 'regex'])
+        expect(bag['items.0.qty']?.[0]?.code).toBe('required')
+        expect(bagHasErrors(bag)).toBe(true)
+    })
+    it('parses a laravel string on validation', () => {
+        const bag = validateValues(
+            [{ key: 'email', label: 'Email', type: 'text', validation: 'required|email' }],
+            { email: 'nope' },
+        )
+        expect(bag.email?.[0]?.code).toBe('email')
+    })
+})

package/src/action-modal-dispatcher.tsx

@@ -37,8 +37,10 @@ import {
 } from '@asteby/metacore-ui/primitives'
 import { Loader2 } from 'lucide-react'
 import { toast } from 'sonner'
-import { toastServerError, toastServerSuccess, extractFieldErrors, localizeFieldIssue } from './server-error'
+import { toastServerError, toastServerSuccess, extractFieldErrors, localizeFieldErrorMap } from './server-error'
 import type { Translate } from './server-error'
+import { validateValues, bagHasErrors } from './validator'
+import { validationCatalog } from './validation-catalog'
 import { useApi } from './api-context'
 import { DynamicIcon } from './dynamic-icon'
 import { DynamicLineItems } from './dynamic-line-items'
@@ -81,7 +83,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 +96,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 +124,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 +136,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>> = []
@@ -423,34 +425,38 @@ function localizeActionFieldErrors(
     err: unknown,
     fields: readonly ActionFieldDef[] | undefined,
     t: Translate,
+    language?: string,
 ): Record<string, string> | undefined {
     const map = extractFieldErrors(err)
     if (!map) return undefined
-    const labelFor = (k: string) => {
-        const f = (fields ?? []).find(x => x.key === k)
-        return f?.label ? t(f.label, { defaultValue: f.label }) : humanizeKey(k)
+    const labels: Record<string, string> = {}
+    for (const f of fields ?? []) {
+        labels[f.key] = f.label ? t(f.label, { defaultValue: f.label }) : humanizeKey(f.key)
     }
-    const out: Record<string, string> = {}
-    for (const [k, issues] of Object.entries(map)) out[k] = localizeFieldIssue(issues[0], labelFor(k), t)
-    return out
+    return localizeFieldErrorMap(map, t, { labels, language })
 }
 
 /** Toast a failed action: a summary + localized per-field lines when the server
  *  returned a per-field `errors` map, else the standard cause-carrying toast.
  *  Used where inline rendering isn't wired (confirm / multi-step wizard). */
-function toastActionError(err: unknown, fields: readonly ActionFieldDef[] | undefined, t: Translate): void {
-    const localized = localizeActionFieldErrors(err, fields, t)
+function toastActionError(
+    err: unknown,
+    fields: readonly ActionFieldDef[] | undefined,
+    t: Translate,
+    language?: string,
+): void {
+    const localized = localizeActionFieldErrors(err, fields, t, language)
     if (localized) {
-        toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }), {
+        toast.error(t('validation.failed', { defaultValue: validationCatalog(language).failed }), {
             description: Object.values(localized).join('\n'),
         })
         return
     }
-    toastServerError(err, { t })
+    toastServerError(err, { t, language })
 }
 
 function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoint, onSuccess }: ActionModalProps) {
-    const { t } = useTranslation()
+    const { t, i18n } = useTranslation()
     const api = useApi()
     const [executing, setExecuting] = useState(false)
     // `action.label` is an addon-contributed i18n key; its locale bundle loads
@@ -468,10 +474,10 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
                 onOpenChange(false)
                 onSuccess()
             } else {
-                toastActionError({ response: { data: res.data } }, action.fields, t)
+                toastActionError({ response: { data: res.data } }, action.fields, t, i18n.language)
             }
         } catch (err: any) {
-            toastActionError(err, action.fields, t)
+            toastActionError(err, action.fields, t, i18n.language)
         } finally {
             setExecuting(false)
         }
@@ -507,7 +513,7 @@ function ConfirmActionDialog({ open, onOpenChange, action, model, record, endpoi
 }
 
 function GenericActionModal({ open, onOpenChange, action, model, record, endpoint, onSuccess }: ActionModalProps) {
-    const { t } = useTranslation()
+    const { t, i18n } = useTranslation()
     // Addon-contributed labels (action + fields) are i18n keys whose locale
     // bundle loads asynchronously; translate at render so they don't render raw.
     // defaultValue keeps an already-localized string unchanged.
@@ -574,39 +580,25 @@ function GenericActionModal({ open, onOpenChange, action, model, record, endpoin
         })
     }
 
+    const lang = i18n.language
     const handleActionError = (err: unknown) => {
-        const localized = localizeActionFieldErrors(err, action.fields, t)
+        const localized = localizeActionFieldErrors(err, action.fields, t, lang)
         if (localized) {
             setFieldErrors(localized)
-            toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
+            toast.error(t('validation.failed', { defaultValue: validationCatalog(lang).failed }))
             return
         }
-        toastServerError(err, { t })
+        toastServerError(err, { t, language: lang })
     }
 
     const execute = async () => {
         if (action.fields) {
-            // Client-side required check → mark ALL missing fields inline.
-            const missing: Record<string, string> = {}
-            for (const field of action.fields) {
-                if (!field.required) continue
-                if (isLineItemsField(field)) {
-                    const rows = formData[field.key]
-                    if (!Array.isArray(rows) || rows.length === 0) {
-                        missing[field.key] = t('validation.line_items_required', {
-                            defaultValue: '{{label}} requiere al menos un renglón',
-                            label: tl(field.label),
-                        })
-                    }
-                    continue
-                }
-                if (!formData[field.key] && formData[field.key] !== false) {
-                    missing[field.key] = localizeFieldIssue({ code: 'required' }, tl(field.label), t)
-                }
-            }
-            if (Object.keys(missing).length) {
-                setFieldErrors(missing)
-                toast.error(t('dynamic.validation_failed', { defaultValue: 'Revisa los campos marcados' }))
+            const bag = validateValues(action.fields, formData)
+            if (bagHasErrors(bag)) {
+                const labels: Record<string, string> = {}
+                for (const f of action.fields) labels[f.key] = tl(f.label)
+                setFieldErrors(localizeFieldErrorMap(bag, t, { labels, language: lang }))
+                toast.error(t('validation.failed', { defaultValue: validationCatalog(lang).failed }))
                 return
             }
         }
@@ -738,28 +730,17 @@ function buildFieldDefaults(fields: ActionFieldDef[], record: any): Record<strin
     return defaults
 }
 
-// validateFields returns the first validation error for a set of required
-// fields, or null when they all pass. Shared by the wizard (per-step gate) and
-// mirrors GenericActionModal's inline checks. `tl` localizes the field label.
-function validateFields(
+function wizardStepErrors(
     fields: ActionFieldDef[],
     formData: Record<string, any>,
-    tl: (s: string) => string,
-): string | null {
-    for (const field of fields) {
-        if (!field.required) continue
-        if (isLineItemsField(field)) {
-            const rows = formData[field.key]
-            if (!Array.isArray(rows) || rows.length === 0) {
-                return `${tl(field.label)} requiere al menos un renglón`
-            }
-            continue
-        }
-        if (!formData[field.key] && formData[field.key] !== false) {
-            return `${tl(field.label)} es requerido`
-        }
-    }
-    return null
+    t: Translate,
+    language?: string,
+): Record<string, string> | undefined {
+    const bag = validateValues(fields, formData)
+    if (!bagHasErrors(bag)) return undefined
+    const labels: Record<string, string> = {}
+    for (const f of fields) labels[f.key] = t(f.label, { defaultValue: f.label })
+    return localizeFieldErrorMap(bag, t, { labels, language })
 }
 
 // WizardActionModal — the third render-path: a multi-step form. It accumulates
@@ -770,7 +751,7 @@ function validateFields(
 // so line-items, dynamic_select, uploads and dates behave identically to a
 // single-page action form — no widget is duplicated.
 function WizardActionModal({ open, onOpenChange, action, model, record, endpoint, onSuccess }: ActionModalProps) {
-    const { t } = useTranslation()
+    const { t, i18n } = useTranslation()
     const tl = (s: string) => t(s, { defaultValue: s })
     const api = useApi()
     const steps = action.steps ?? []
@@ -801,9 +782,11 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
     const widthPx = hasLineItems ? '820px' : undefined
 
     const goNext = () => {
-        const err = validateFields(stepFields, formData, tl)
-        if (err) {
-            toast.error(err)
+        const localized = wizardStepErrors(stepFields, formData, t, i18n.language)
+        if (localized) {
+            toast.error(t('validation.failed', { defaultValue: validationCatalog(i18n.language).failed }), {
+                description: Object.values(localized).join('\n'),
+            })
             return
         }
         setStepIndex((i) => Math.min(i + 1, steps.length - 1))
@@ -815,9 +798,11 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
         // Guard every step's required fields on final submit (a user could reach
         // the last step with an untouched earlier line-items grid otherwise).
         for (const s of steps) {
-            const err = validateFields(s.fields ?? [], formData, tl)
-            if (err) {
-                toast.error(err)
+            const localized = wizardStepErrors(s.fields ?? [], formData, t, i18n.language)
+            if (localized) {
+                toast.error(t('validation.failed', { defaultValue: validationCatalog(i18n.language).failed }), {
+                    description: Object.values(localized).join('\n'),
+                })
                 return
             }
         }
@@ -830,10 +815,10 @@ function WizardActionModal({ open, onOpenChange, action, model, record, endpoint
                 onOpenChange(false)
                 onSuccess()
             } else {
-                toastActionError({ response: { data: res.data } }, steps.flatMap(s => s.fields ?? []), t)
+                toastActionError({ response: { data: res.data } }, steps.flatMap(s => s.fields ?? []), t, i18n.language)
             }
         } catch (err: any) {
-            toastActionError(err, steps.flatMap(s => s.fields ?? []), t)
+            toastActionError(err, steps.flatMap(s => s.fields ?? []), t, i18n.language)
         } finally {
             setExecuting(false)
         }

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 }