@asteby/metacore-runtime-react 45.0.0 → 45.3.0

package/src/document/use-document-sources.ts

@@ -0,0 +1,91 @@
+import { useCallback, useEffect, useState } from 'react'
+import { useApi } from '../api-context'
+import { buildRelationFilterParams } from '../dynamic-relation-helpers'
+import type { DocumentSourceDef } from './types'
+
+const DEFAULT_LIMIT = 50
+// El kernel ≥ 0.139.2 acepta listas `in:` largas; se parte para no exceder la URL.
+const VIA_CHUNK = 40
+
+type Rows = Record<string, unknown>[]
+
+export interface DocumentSourcesState {
+    sources: Record<string, Record<string, unknown>[]>
+    loading: boolean
+    /** Vuelve a pedir todas las fuentes (tras ejecutar una acción). */
+    reload: () => void
+}
+
+/**
+ * Carga las filas relacionadas con el documento (pagos, REP, notas de crédito…)
+ * que alimentan contadores, pestañas y derivados. Un fallo en una fuente deja
+ * esa fuente vacía: la página sigue siendo usable.
+ */
+export function useDocumentSources(
+    defs: DocumentSourceDef[] | undefined,
+    recordId: string | number | undefined,
+): DocumentSourcesState {
+    const api = useApi()
+    const [sources, setSources] = useState<Record<string, Record<string, unknown>[]>>({})
+    const [loading, setLoading] = useState(false)
+    const [nonce, setNonce] = useState(0)
+    const reload = useCallback(() => setNonce((n) => n + 1), [])
+
+    useEffect(() => {
+        if (!defs || defs.length === 0 || recordId === undefined || recordId === null) {
+            setSources({})
+            return
+        }
+        let cancelled = false
+        setLoading(true)
+        const fetchRows = async (d: DocumentSourceDef, params: Record<string, string>): Promise<Rows> => {
+            try {
+                const res = await api.get(`/data/${d.model}`, {
+                    params: { ...params, page: 1, per_page: d.limit ?? DEFAULT_LIMIT },
+                })
+                const body = res.data
+                const rows = (body?.data ?? body) as unknown
+                return Array.isArray(rows) ? (rows as Rows) : []
+            } catch {
+                return []
+            }
+        }
+        const direct = defs.filter((d) => !d.via)
+        const hopped = defs.filter((d) => d.via)
+        ;(async () => {
+            const out: Record<string, Rows> = {}
+            await Promise.all(
+                direct.map(async (d) => {
+                    out[d.key] = await fetchRows(d, buildRelationFilterParams(d.foreignKey, recordId, d.where))
+                }),
+            )
+            // Segundo salto: depende de las filas del primero.
+            for (const d of hopped) {
+                const ids = Array.from(
+                    new Set((out[d.via!.source] ?? []).map((r) => r[d.via!.field]).filter((v) => v != null && v !== '').map(String)),
+                )
+                const chunks: string[][] = []
+                for (let i = 0; i < ids.length; i += VIA_CHUNK) chunks.push(ids.slice(i, i + VIA_CHUNK))
+                const parts = await Promise.all(
+                    chunks.map((c) => {
+                        const params: Record<string, string> = { [`f_${d.foreignKey}`]: `in:${c.join(',')}` }
+                        for (const [k, v] of Object.entries(d.where ?? {})) params[`f_${k}`] = `eq:${v}`
+                        return fetchRows(d, params)
+                    }),
+                )
+                out[d.key] = parts.flat()
+            }
+            return out
+        })()
+            .then((out) => {
+                if (cancelled) return
+                setSources(out)
+                setLoading(false)
+            })
+        return () => {
+            cancelled = true
+        }
+    }, [api, defs, recordId, nonce])
+
+    return { sources, loading, reload }
+}

package/src/dynamic-columns.tsx

@@ -1312,7 +1312,11 @@ export function makeDefaultGetDynamicColumns(
 
                         case 'tags': {
                             const list: string[] = Array.isArray(value)
-                                ? value.map(String)
+                                ? value.map((v) =>
+                                      v && typeof v === 'object'
+                                          ? String((v as { label?: unknown; name?: unknown; key?: unknown }).label ?? (v as { name?: unknown }).name ?? (v as { key?: unknown }).key ?? '')
+                                          : String(v),
+                                  ).filter(Boolean)
                                 : value
                                   ? String(value)
                                         .split(',')

package/src/dynamic-relation.tsx

@@ -83,6 +83,10 @@ export {
 export interface DynamicRelationStrings {
     title: string
     emptyState: string
+    /** Sub-tabla sin permiso de lectura (HTTP 403). Default: "Sin permiso para ver estos registros." */
+    forbiddenState?: string
+    /** Falla al cargar la sub-tabla (no 403). Default: "No se pudieron cargar los registros relacionados." */
+    errorState?: string
     addLabel: string
     editLabel: string
     removeLabel: string
@@ -252,6 +256,9 @@ function OneToManyRelation({
     const [optionsMap, setOptionsMap] = useState<Map<string, any[]>>(new Map())
     const [rows, setRows] = useState<any[]>([])
     const [loading, setLoading] = useState(true)
+    // HTTP status of the last failed fetch (null = ok). Without it a 403/500
+    // rendered the empty state and read as "no related rows" (PIT-045).
+    const [fetchErrorStatus, setFetchErrorStatus] = useState<number | null>(null)
     // Paginación server-side + scroll infinito, igual que <DynamicTable>.
     const [total, setTotal] = useState(0)
     const [page, setPage] = useState(1)
@@ -341,6 +348,7 @@ function OneToManyRelation({
                 cacheMetadata(model, fresh)
             }
             const list = (dataRes as { data: ApiResponse<any[]> }).data
+            setFetchErrorStatus(null)
             if (list.success) {
                 const fetched = list.data || []
                 setRows((prev) => (append ? dedupeById(prev, fetched) : fetched))
@@ -351,6 +359,7 @@ function OneToManyRelation({
             }
         } catch (err) {
             console.error('DynamicRelation fetch error', err)
+            setFetchErrorStatus((err as { response?: { status?: number } })?.response?.status ?? 0)
         } finally {
             if (append) setLoadingMore(false)
             else setLoading(false)
@@ -555,7 +564,11 @@ function OneToManyRelation({
                 </div>
             ) : rows.length === 0 ? (
                 <div className="text-center text-sm text-muted-foreground py-8 border rounded-md bg-muted/30">
-                    {labels.emptyState}
+                    {fetchErrorStatus === 403
+                        ? (labels.forbiddenState ?? 'Sin permiso para ver estos registros.')
+                        : fetchErrorStatus !== null
+                          ? (labels.errorState ?? 'No se pudieron cargar los registros relacionados.')
+                          : labels.emptyState}
                 </div>
             ) : (
                 // Real metadata-driven table — same metacore-ui primitives and

package/src/dynamic-row-actions.tsx

@@ -34,6 +34,7 @@ import {
     AlertDialogTitle,
 } from '@asteby/metacore-ui/primitives'
 import { useApi } from './api-context'
+import { useReasonPrompt } from './reason-prompt'
 import { ActionModalDispatcher } from './action-modal-dispatcher'
 import { DynamicRecordDialog } from './dialogs/dynamic-record'
 import { RequiresAddonDialog, resolveRequiresAddon } from './requires-addon'
@@ -102,6 +103,9 @@ export function useDynamicRowActions({
 
     const [rowToDelete, setRowToDelete] = useState<any | null>(null)
     const [isDeleting, setIsDeleting] = useState(false)
+    // Models that declare `reason_required.delete` answer a bare DELETE with 422
+    // errors.reason; the prompt asks once and retries with `?reason=`.
+    const reasonPrompt = useReasonPrompt()
 
     const [actionModal, setActionModal] = useState<{
         open: boolean
@@ -157,7 +161,14 @@ export function useDynamicRowActions({
         setIsDeleting(true)
         try {
             const deleteEndpoint = writeBase ? `${writeBase}/${rowToDelete.id}` : `/data/${model}/${rowToDelete.id}`
-            const res = await api.delete(deleteEndpoint)
+            const res = await reasonPrompt.run({
+                title: t('dynamic.delete_reason_title', { defaultValue: 'Eliminar registro' }),
+                description: t('dynamic.delete_reason_desc', { defaultValue: 'Este modelo pide el motivo de la eliminación.' }),
+                confirmLabel: t('dynamic.delete_confirm', { defaultValue: 'Eliminar' }),
+                request: (reason) => api.delete(deleteEndpoint, reason ? { params: { reason } } : undefined),
+            })
+            // El operador canceló el motivo: no se eliminó nada.
+            if (!res) return
             // CRUD estándar: no usar res.data.message (el endpoint dinámico
             // devuelve texto en inglés que se filtraría al toast). String localizado.
             if (res.data.success) { toast.success(t('dynamic.delete_success', { defaultValue: 'Registro eliminado correctamente' })); onRefresh() }
@@ -173,6 +184,7 @@ export function useDynamicRowActions({
 
     const dialogs = (
         <>
+            {reasonPrompt.dialog}
             <AlertDialog open={!!rowToDelete} onOpenChange={(open: boolean) => !open && setRowToDelete(null)}>
                 <AlertDialogContent>
                     <AlertDialogHeader>

package/src/dynamic-table.tsx

@@ -67,6 +67,7 @@ import { toast } from 'sonner'
 import { Progress } from './dialogs/_primitives'
 import { useMetadataCache } from './metadata-cache'
 import { useApi, useCurrentBranch } from './api-context'
+import { useReasonPrompt } from './reason-prompt'
 import type { ColumnFilterConfig, GetDynamicColumns } from './dynamic-columns-shim'
 import { defaultGetDynamicColumns, DATE_CELL_TYPES, aggregateOf, formatAggregateTotal } from './dynamic-columns'
 import { useFacetLoaders, isLongTextColumn } from './use-facet-loaders'
@@ -1123,6 +1124,7 @@ export function DynamicTable({
         onRefresh: handleRefresh,
     })
 
+    const bulkReasonPrompt = useReasonPrompt()
     const confirmBulkDelete = async () => {
         const selectedRows = table.getFilteredSelectedRowModel().rows
         if (selectedRows.length === 0) return
@@ -1130,13 +1132,29 @@ export function DynamicTable({
         setBulkDeleteTotal(selectedRows.length)
         setBulkDeleteProgress(0)
         let successCount = 0, errorCount = 0
+        // One reason for the whole batch: asked the first time a row is refused
+        // for lacking it (model declares reason_required.delete), reused after.
+        let bulkReason: string | undefined
+        let bulkCancelled = false
         for (let i = 0; i < selectedRows.length; i++) {
             const row = selectedRows[i]
+            if (bulkCancelled) { errorCount++; setBulkDeleteProgress(i + 1); continue }
             try {
                 const writeBase = mutationEndpoint ?? endpoint
                 const deleteEndpoint = writeBase ? `${writeBase}/${row.original.id}` : `/data/${model}/${row.original.id}`
-                const res = await api.delete(deleteEndpoint)
-                if (res.data.success) successCount++; else errorCount++
+                const res = await bulkReasonPrompt.run({
+                    title: t('dynamic.bulk_delete_reason_title', { count: selectedRows.length, defaultValue: 'Eliminar {{count}} registro(s)' }),
+                    description: t('dynamic.delete_reason_desc', { defaultValue: 'Este modelo pide el motivo de la eliminación.' }),
+                    confirmLabel: t('dynamic.delete_confirm', { defaultValue: 'Eliminar' }),
+                    reason: bulkReason,
+                    request: (reason) => {
+                        if (reason) bulkReason = reason
+                        return api.delete(deleteEndpoint, reason ? { params: { reason } } : undefined)
+                    },
+                })
+                if (!res) { bulkCancelled = true; errorCount++ }
+                else if (res.data.success) successCount++
+                else errorCount++
             } catch (e) { console.error('Error al eliminar', e); errorCount++ }
             setBulkDeleteProgress(i + 1)
         }
@@ -1863,6 +1881,8 @@ export function DynamicTable({
                 </AlertDialogContent>
             </AlertDialog>
 
+            {bulkReasonPrompt.dialog}
+
             {exportEnabled && (
                 <ExportDialog open={exportOpen} onOpenChange={setExportOpen} model={model} metadata={metadata} currentFilters={buildFilterParams()} hasActiveFilters={hasActiveFilters} />
             )}

package/src/index.ts

@@ -218,6 +218,35 @@ export {
     type CanFn,
     type PermissionsProviderProps,
 } from './permissions-context'
+export {
+    ApprovalPinDialog,
+    approvalErrorMessage,
+    type ApprovalPinDialogProps,
+    type ApprovalPinSubmit,
+} from './approval-pin-dialog'
+export {
+    ApprovalGateProvider,
+    useApprovalGate,
+    approvalCapability,
+    approvalRequiredInfo,
+    approvalGateAvailable,
+    APPROVAL_PARKED_EVENT,
+    APPROVAL_DECIDED_EVENT,
+    type ApprovalGateValue,
+    type ApprovalGrant,
+    type ApprovalRequiredInfo,
+    type RequestApprovalOptions,
+} from './approval-gate'
+export {
+    ReasonPromptDialog,
+    useReasonPrompt,
+    reasonRequiredInfo,
+    DEFAULT_REASON_MIN,
+    type ReasonPromptDialogProps,
+    type ReasonPromptApi,
+    type ReasonRequiredInfo,
+    type RunWithReasonOptions,
+} from './reason-prompt'
 export {
     useDynamicRowActions,
     type UseDynamicRowActionsParams,
@@ -282,6 +311,7 @@ export {
     type SidebarLayoutManagerProps,
 } from './sidebar-layout-manager'
 export * from './org-runtime-context'
+export * from './business'
 export * from './org-runtime-provider'
 export * from './navigation-builder'
 export * from './i18n-provider'
@@ -581,3 +611,6 @@ export {
     type AttributeClass,
     type AttributeClassSection,
 } from './attribute-classes'
+
+// Página de documento (benchmark §5/§6): cabecera, badges, acciones por estado, botones inteligentes.
+export * from './document'

package/src/reason-prompt.tsx

@@ -0,0 +1,247 @@
+// Mandatory reason on destructive operations (PER-4).
+//
+// A manifest model declares `reason_required` (delete and/or actions such as
+// cancel). The kernel then answers a DELETE / action WITHOUT a reason with
+// 422 `errors.reason: [{code: "required" | "min", params: {min}}]`. Instead of
+// every screen carrying its own "motivo" prompt, `useReasonPrompt().run()` wraps
+// the request: it tries it, and when the server says a reason is needed it asks
+// once (a dialog) and retries with the reason attached. Screens that already know
+// they need one can pass `reason` up front through the same helper.
+//
+// The reason is stamped on the canonical event by the kernel, so the activity log
+// (RecordHistory) shows who removed/cancelled what, when, and why.
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Loader2 } from 'lucide-react'
+import {
+    Button,
+    Dialog,
+    DialogContent,
+    DialogDescription,
+    DialogFooter,
+    DialogHeader,
+    DialogTitle,
+    Textarea,
+} from '@asteby/metacore-ui/primitives'
+
+/** What the server told us about the missing reason. */
+export interface ReasonRequiredInfo {
+    /** Minimum trimmed length the policy demands (default 3). */
+    min: number
+    /** True when a reason WAS sent but was too short. */
+    tooShort: boolean
+}
+
+export const DEFAULT_REASON_MIN = 3
+
+/**
+ * Detects the kernel's mandatory-reason refusal in an axios error (or a bare
+ * response body): HTTP 422 with `errors.reason[0].code` of `required` | `min`.
+ * Returns null for any other error.
+ */
+export function reasonRequiredInfo(err: unknown): ReasonRequiredInfo | null {
+    const data = (err as { response?: { data?: unknown } } | undefined)?.response?.data ?? err
+    const issues = (data as { errors?: { reason?: unknown } } | undefined)?.errors?.reason
+    if (!Array.isArray(issues) || issues.length === 0) return null
+    const first = issues[0] as { code?: string; params?: { min?: number } } | string
+    const code = typeof first === 'string' ? first : first?.code
+    if (code !== 'required' && code !== 'min') return null
+    const min = typeof first === 'object' && typeof first?.params?.min === 'number' ? first.params.min : DEFAULT_REASON_MIN
+    return { min, tooShort: code === 'min' }
+}
+
+export interface ReasonPromptDialogProps {
+    open: boolean
+    title: string
+    description?: React.ReactNode
+    /** Minimum trimmed length; the submit button stays disabled below it. */
+    min?: number
+    /** Label of the confirm button (default "Continuar"). */
+    confirmLabel?: string
+    /** Style the confirm button as destructive (delete / cancel). */
+    destructive?: boolean
+    /** Inline error from a previous attempt. */
+    error?: string | null
+    busy?: boolean
+    onSubmit: (reason: string) => void
+    onCancel: () => void
+}
+
+export function ReasonPromptDialog({
+    open,
+    title,
+    description,
+    min = DEFAULT_REASON_MIN,
+    confirmLabel,
+    destructive = true,
+    error,
+    busy,
+    onSubmit,
+    onCancel,
+}: ReasonPromptDialogProps) {
+    const { t } = useTranslation()
+    const [reason, setReason] = useState('')
+
+    useEffect(() => {
+        if (open) setReason('')
+    }, [open])
+
+    const ready = reason.trim().length >= min
+
+    return (
+        <Dialog open={open} onOpenChange={(o: boolean) => !o && !busy && onCancel()}>
+            <DialogContent className="sm:max-w-md">
+                <DialogHeader>
+                    <DialogTitle>{title}</DialogTitle>
+                    {description ? <DialogDescription>{description}</DialogDescription> : null}
+                </DialogHeader>
+                <div className="space-y-2">
+                    <label htmlFor="mc-reason" className="text-sm font-medium">
+                        {t('reason.label', { defaultValue: 'Motivo' })}
+                    </label>
+                    <Textarea
+                        id="mc-reason"
+                        autoFocus
+                        rows={3}
+                        value={reason}
+                        onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => setReason(e.target.value)}
+                        placeholder={t('reason.placeholder', { defaultValue: 'Explica por qué. Queda en la bitácora.' })}
+                    />
+                    {error ? <p className="text-destructive text-sm">{error}</p> : null}
+                    {!error && reason.length > 0 && !ready ? (
+                        <p className="text-muted-foreground text-xs">
+                            {t('reason.min', { min, defaultValue: 'Escribe al menos {{min}} caracteres.' })}
+                        </p>
+                    ) : null}
+                </div>
+                <DialogFooter>
+                    <Button variant="outline" onClick={onCancel} disabled={busy}>
+                        {t('common.cancel', { defaultValue: 'Cancelar' })}
+                    </Button>
+                    <Button
+                        variant={destructive ? 'destructive' : 'default'}
+                        disabled={!ready || busy}
+                        onClick={() => onSubmit(reason.trim())}
+                    >
+                        {busy ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : null}
+                        {confirmLabel ?? t('reason.confirm', { defaultValue: 'Continuar' })}
+                    </Button>
+                </DialogFooter>
+            </DialogContent>
+        </Dialog>
+    )
+}
+
+export interface RunWithReasonOptions<T> {
+    /** Dialog headline, e.g. "Eliminar registro". */
+    title: string
+    description?: React.ReactNode
+    confirmLabel?: string
+    destructive?: boolean
+    /**
+     * Performs the request. Called first WITHOUT a reason; when the server
+     * demands one it is called again with the operator's reason. Throw (axios
+     * style) on failure.
+     */
+    request: (reason?: string) => Promise<T>
+    /** A reason already collected (bulk operations reuse one for every row). */
+    reason?: string
+}
+
+export interface ReasonPromptApi {
+    /**
+     * Resolves the request's result, or `undefined` when the operator cancelled
+     * the reason prompt. Any error that is NOT a reason refusal is rethrown.
+     */
+    run: <T>(opts: RunWithReasonOptions<T>) => Promise<T | undefined>
+    /** Render once near the caller: the dialog the helper opens. */
+    dialog: React.ReactNode
+}
+
+interface PendingReason {
+    opts: RunWithReasonOptions<unknown>
+    info: ReasonRequiredInfo
+    resolve: (v: unknown) => void
+    reject: (e: unknown) => void
+    error: string | null
+}
+
+/** See the module comment. Render `dialog` somewhere in the caller's tree. */
+export function useReasonPrompt(): ReasonPromptApi {
+    const { t } = useTranslation()
+    const [pending, setPending] = useState<PendingReason | null>(null)
+    const [busy, setBusy] = useState(false)
+    const pendingRef = useRef<PendingReason | null>(null)
+    pendingRef.current = pending
+
+    const run = useCallback(<T,>(opts: RunWithReasonOptions<T>): Promise<T | undefined> => {
+        return new Promise<T | undefined>((resolve, reject) => {
+            opts
+                .request(opts.reason)
+                .then((v) => resolve(v))
+                .catch((err) => {
+                    const info = reasonRequiredInfo(err)
+                    if (!info) return reject(err)
+                    setPending({
+                        opts: opts as RunWithReasonOptions<unknown>,
+                        info,
+                        resolve: resolve as (v: unknown) => void,
+                        reject,
+                        error: null,
+                    })
+                })
+        })
+    }, [])
+
+    const submit = async (reason: string) => {
+        const p = pendingRef.current
+        if (!p) return
+        setBusy(true)
+        try {
+            const v = await p.opts.request(reason)
+            setPending(null)
+            p.resolve(v)
+        } catch (err) {
+            const info = reasonRequiredInfo(err)
+            if (info) {
+                // Server still not satisfied (a longer minimum): stay open, say why.
+                setPending({
+                    ...p,
+                    info,
+                    error: t('reason.min', {
+                        min: info.min,
+                        defaultValue: 'Escribe al menos {{min}} caracteres.',
+                    }),
+                })
+            } else {
+                setPending(null)
+                p.reject(err)
+            }
+        } finally {
+            setBusy(false)
+        }
+    }
+
+    const cancel = () => {
+        const p = pendingRef.current
+        setPending(null)
+        p?.resolve(undefined)
+    }
+
+    const dialog = (
+        <ReasonPromptDialog
+            open={pending !== null}
+            title={pending?.opts.title ?? ''}
+            description={pending?.opts.description}
+            min={pending?.info.min}
+            confirmLabel={pending?.opts.confirmLabel}
+            destructive={pending?.opts.destructive}
+            error={pending?.error}
+            busy={busy}
+            onSubmit={submit}
+            onCancel={cancel}
+        />
+    )
+
+    return { run, dialog }
+}

package/src/server-error.ts

@@ -11,6 +11,7 @@
 // the toast description, in ONE place so every call site behaves identically.
 import { toast } from 'sonner'
 import { validationCatalog, validationMessageKey } from './validation-catalog'
+import { APPROVAL_PARKED_EVENT, approvalGateAvailable, approvalRequiredInfo } from './approval-events'
 
 /** Structured, display-ready view of an error: a headline + an optional cause. */
 export interface ExtractedError {
@@ -234,6 +235,25 @@ export function toastServerError(
     const t = opts?.t
     const lang = opts?.language
     const cat = validationCatalog(lang)
+    // A write parked for approval is not a failure: say so, and when an
+    // <ApprovalGateProvider> is mounted offer to approve it right now with a PIN.
+    const parked = approvalRequiredInfo(err)
+    if (parked) {
+        const title = parked.label || (t ? t('approvals.sent', { defaultValue: 'Enviado a aprobación' }) : 'Enviado a aprobación')
+        toast.info(title, {
+            description: parked.roles.length
+                ? (t ? t('approvals.waiting_for', { defaultValue: 'Lo decide: {{roles}}', roles: parked.roles.join(', ') }) : parked.roles.join(', '))
+                : undefined,
+            action:
+                parked.requestId && approvalGateAvailable()
+                    ? {
+                          label: t ? t('approvals.approve_with_pin', { defaultValue: 'Aprobar con PIN' }) : 'Aprobar con PIN',
+                          onClick: () => window.dispatchEvent(new CustomEvent(APPROVAL_PARKED_EVENT, { detail: parked })),
+                      }
+                    : undefined,
+        })
+        return
+    }
     const map = extractFieldErrors(err)
     if (map) {
         const localized = t

package/src/use-addon-settings.ts

@@ -27,9 +27,19 @@ import {
 } from '@tanstack/react-query'
 import { useApi } from './api-context'
 
-/** Stable react-query key for an addon's per-org settings. */
-export function addonSettingsKey(addonKey: string) {
-    return ['addon-settings', addonKey] as const
+/** Stable react-query key for an addon's per-org settings (per branch when given). */
+export function addonSettingsKey(addonKey: string, branchId?: string | null) {
+    return branchId ? (['addon-settings', addonKey, branchId] as const) : (['addon-settings', addonKey] as const)
+}
+
+/**
+ * Settings URL. With a branch, the host answers the settings the addon runs
+ * with there: org values with each `scope: branch` key replaced by the branch's
+ * override (POS-1). Without one, the org values (legacy behaviour).
+ */
+export function addonSettingsUrl(addonKey: string, branchId?: string | null): string {
+    const base = `/api/addons/${addonKey}/settings`
+    return branchId ? `${base}?branch_id=${encodeURIComponent(branchId)}` : base
 }
 
 /**
@@ -63,6 +73,12 @@ export interface UseAddonSettingsOptions<T> {
     staleTime?: number
     /** Defer fetching (e.g. until the addon key is known). */
     enabled?: boolean
+    /**
+     * Read the settings as one branch sees them (manifest `scope: branch` keys
+     * resolve to the branch override, else the org value). Omit for org values.
+     * A terminal passes its active branch here.
+     */
+    branchId?: string | null
 }
 
 export interface UseAddonSettingsResult<T> {
@@ -92,12 +108,12 @@ export function useAddonSettings<T extends Record<string, unknown> = Record<stri
     opts: UseAddonSettingsOptions<T> = {},
 ): UseAddonSettingsResult<T> {
     const api = useApi()
-    const { defaults, staleTime, enabled } = opts
+    const { defaults, staleTime, enabled, branchId } = opts
 
     const query = useQuery<Partial<T>>({
-        queryKey: addonSettingsKey(addonKey),
+        queryKey: addonSettingsKey(addonKey, branchId),
         queryFn: async () => {
-            const res = await api.get(`/api/addons/${addonKey}/settings`)
+            const res = await api.get(addonSettingsUrl(addonKey, branchId))
             const body = (res as { data: any }).data
             // Host envelope: { success, data: { <key>: <value> } }.
             const values = body?.success ? body.data : body
@@ -134,18 +150,21 @@ export function useAddonSettings<T extends Record<string, unknown> = Record<stri
  */
 export function useUpdateAddonSettings<T extends Record<string, unknown> = Record<string, unknown>>(
     addonKey: string,
+    /** Write branch overrides (only `scope: branch` keys; `null` clears one) instead of org values. */
+    branchId?: string | null,
 ) {
     const api = useApi()
     const qc = useQueryClient()
 
     return useMutation<Partial<T>, Error, Partial<T>>({
         mutationFn: async (values) => {
-            const res = await api.put(`/api/addons/${addonKey}/settings`, values)
+            const res = await api.put(addonSettingsUrl(addonKey, branchId), values)
             const body = (res as { data: any }).data
             const saved = body?.success ? body.data : body
             return (saved ?? values) as Partial<T>
         },
         onSuccess: () => {
+            // Prefix match: refreshes the org read and every branch read.
             void qc.invalidateQueries({ queryKey: addonSettingsKey(addonKey) })
         },
     })