@jini-ai/admin 0.4.12 → 0.6.10

package/dist/agent-plugins/react/hooks/AgentPluginsPage.hooks.js

@@ -16,24 +16,36 @@ export function useAgentPluginsPage(props, _optional = {}) {
     const permissions = props.description.visible ? props.description.grants : [], key = permissions.join('\0');
     const { controller, snapshot } = useController({ create: () => createAgentPluginsController({ api: agentPluginsApi, permissions }), dependencies: [agentPluginsApi, key] }, { start: ({ controller }) => { void controller.load({}); } });
     const [localTab, setLocalTab] = useState('installed'), uninstallNoteId = useId();
-    const visible = props.description.visible ? props.description.tabs.filter(t => t.visible) : [];
-    const active = visible.find(t => t.id.endsWith(`.${props.requestedTab ?? localTab}`)) ?? visible[0];
-    const activeId = active?.id.slice(active.id.lastIndexOf('.') + 1) ?? 'installed';
-    const pending = snapshot?.pendingDisable, confirming = !!pending && !!snapshot?.busyIds.includes(pending.pluginId);
-    const confirmation = pending ? agentPluginDisableCopy(pending) : null;
-    const inspected = snapshot?.plugins?.find(p => p.pluginId === snapshot.inspectedId);
+    const { visible, active, activeId } = pageTabs({ description: props.description, tab: props.requestedTab ?? localTab });
     return {
         denied: !props.description.visible || !permissions.includes(AGENT_PLUGINS_READ),
         scope: { controller, snapshot, permissions, uninstallNoteId },
         activeId, ActiveTab: active ? props.tabs[activeId] : undefined, params: active?.params ?? {}, permissions,
-        items: visible.map(t => ({ id: t.id.slice(t.id.lastIndexOf('.') + 1), label: t.label, content: null })),
+        items: visible.map(t => ({ id: tabSuffix(t.id), label: t.label, content: null })),
         onValueChange({ value }, _optional = {}) { setLocalTab(value); props.onTabChange?.({ tab: value }); },
-        inspector: inspected ? { pluginId: inspected.pluginId, name: humanizeAgentPluginId({ pluginId: inspected.pluginId }) } : null,
+        ...pageDialogs({ snapshot }),
         closeInspector(_required, _optional = {}) { controller?.closeInspector({}); },
-        confirmation, confirming,
-        async confirm(_required, _optional = {}) { if (!await controller?.confirmDisable({}))
-            throw new Error('Activation was not updated'); },
+        async confirm(_required, _optional = {}) {
+            const pluginId = snapshot?.pendingDisable?.pluginId ?? '(none pending)';
+            if (!await controller?.confirmDisable({}))
+                throw new Error(`Activation was not updated for agent plugin ${pluginId}: the disable was refused or failed; retry, or reload the list if it changed`);
+        },
         cancel(_required, _optional = {}) { controller?.cancelDisable({}); },
     };
 }
+/** A tab id is namespaced (`agentPlugins.installed`); the page addresses tabs by the last segment. */
+const tabSuffix = (id) => id.slice(id.lastIndexOf('.') + 1);
+function pageTabs({ description, tab }, _optional = {}) {
+    const visible = description.visible ? description.tabs.filter(t => t.visible) : [];
+    const active = visible.find(t => t.id.endsWith(`.${tab}`)) ?? visible[0];
+    return { visible, active, activeId: active ? tabSuffix(active.id) : 'installed' };
+}
+function pageDialogs({ snapshot }, _optional = {}) {
+    const pending = snapshot?.pendingDisable, confirming = !!pending && !!snapshot?.busyIds.includes(pending.pluginId);
+    const inspected = snapshot?.plugins?.find(p => p.pluginId === snapshot.inspectedId);
+    return {
+        inspector: inspected ? { pluginId: inspected.pluginId, name: humanizeAgentPluginId({ pluginId: inspected.pluginId }) } : null,
+        confirmation: pending ? agentPluginDisableCopy(pending) : null, confirming,
+    };
+}
 //# sourceMappingURL=AgentPluginsPage.hooks.js.map

package/dist/browser/navigation.js

@@ -52,6 +52,45 @@ export function navigate({ routePath, window }, options = {}) {
         window.history.pushState(null, '', url);
     window.dispatchEvent(new Event(NAVIGATION_EVENT));
 }
+/**
+ * Whether the browser should leave this click to us.
+ *
+ * Anything but an unmodified primary click is the browser's to handle: cmd/ctrl-click opens a
+ * tab, shift-click a window, alt-click downloads.
+ */
+function isPlainPrimaryClick({ event }) {
+    if (event.defaultPrevented || event.button !== 0)
+        return false;
+    return !(event.metaKey || event.ctrlKey || event.shiftKey || event.altKey);
+}
+/** The clicked `<a>` when it asks for an ordinary in-place navigation to a non-fragment href, else `null`. */
+function findInPlaceAnchor({ event }) {
+    const anchor = event.target?.closest?.('a');
+    if (!anchor || anchor.hasAttribute('download'))
+        return null;
+    // An explicit target (`_blank`, a frame name) is an explicit request not to navigate in place.
+    const target = anchor.getAttribute('target');
+    if (target && target !== '_self')
+        return null;
+    const href = anchor.getAttribute('href');
+    if (!href || href.startsWith('#'))
+        return null;
+    return anchor;
+}
+/** The route path (with query and hash) `anchor` points at, or `null` when it leaves the same-origin `base`. */
+function internalRoutePath({ anchor, window, base }) {
+    // `anchor.href` is the resolved absolute form, which is what makes relative hrefs and
+    // cross-origin links both fall out correctly.
+    const url = new URL(anchor.href, window.location.href);
+    if (url.origin !== window.location.origin)
+        return null;
+    if (url.pathname !== base && !url.pathname.startsWith(`${base}/`))
+        return null;
+    // `url.hash` is carried through: an in-page fragment (`/admin/settings#seo-defaults`) is not a
+    // routing concern, but dropping it silently loses the anchor. It never reaches the matcher —
+    // the route snapshot is path + query only — so preserving it cannot affect routing.
+    return `${currentRoutePath({ pathname: url.pathname }, { base })}${url.search}${url.hash}`;
+}
 /**
  * Turns clicks on internal `<a href="/admin/...">` links into SPA navigations.
  *
@@ -65,38 +104,16 @@ export function navigate({ routePath, window }, options = {}) {
  */
 export function installInternalLinkInterceptor({ window, document }, { base = DEFAULT_ADMIN_BASE } = {}) {
     const onClick = (event) => {
-        // Anything but an unmodified primary click is the browser's to handle: cmd/ctrl-click opens a
-        // tab, shift-click a window, alt-click downloads.
-        if (event.defaultPrevented)
+        if (!isPlainPrimaryClick({ event }))
             return;
-        if (event.button !== 0)
-            return;
-        if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
-            return;
-        const anchor = event.target?.closest?.('a');
+        const anchor = findInPlaceAnchor({ event });
         if (!anchor)
             return;
-        if (anchor.hasAttribute('download'))
-            return;
-        // An explicit target (`_blank`, a frame name) is an explicit request not to navigate in place.
-        const target = anchor.getAttribute('target');
-        if (target && target !== '_self')
-            return;
-        const href = anchor.getAttribute('href');
-        if (!href || href.startsWith('#'))
-            return;
-        // `anchor.href` is the resolved absolute form, which is what makes relative hrefs and
-        // cross-origin links both fall out correctly.
-        const url = new URL(anchor.href, window.location.href);
-        if (url.origin !== window.location.origin)
-            return;
-        if (url.pathname !== base && !url.pathname.startsWith(`${base}/`))
+        const routePath = internalRoutePath({ anchor, window, base });
+        if (routePath === null)
             return;
         event.preventDefault();
-        // `url.hash` is carried through: an in-page fragment (`/admin/settings#seo-defaults`) is not a
-        // routing concern, but dropping it silently loses the anchor. It never reaches the matcher —
-        // the route snapshot is path + query only — so preserving it cannot affect routing.
-        navigate({ window, routePath: `${currentRoutePath({ pathname: url.pathname }, { base })}${url.search}${url.hash}` }, { base });
+        navigate({ window, routePath }, { base });
     };
     document.addEventListener('click', onClick);
     return () => document.removeEventListener('click', onClick);

package/dist/comments/adapters/memory.js

@@ -5,6 +5,24 @@ const DEFAULT_SETTINGS = {
     enabled: true, requireModeration: true, maxDepth: 5, closeAfterDays: null,
     spamAutoRejectScore: 0.5, maxPerIpPerHour: 20,
 };
+const MODERATION_STATUSES = { approve: 'approved', spam: 'spam', trash: 'trash', restore: 'approved' };
+function isNumberIn({ value, min, max }, { integer = false } = {}) {
+    return Number.isFinite(value) && (!integer || Number.isInteger(value)) && value >= min && value <= max;
+}
+/** Each settings field with its fixture-level shape check and the expectation a refusal names. */
+const SETTINGS_RULES = [
+    ['enabled', value => typeof value === 'boolean', 'a boolean'],
+    ['requireModeration', value => typeof value === 'boolean', 'a boolean'],
+    ['maxDepth', value => isNumberIn({ value, min: 0, max: 20 }, { integer: true }), 'an integer from 0 to 20'],
+    ['closeAfterDays', value => value === null || isNumberIn({ value, min: 0, max: Infinity }, { integer: true }), 'null or a non-negative integer'],
+    ['spamAutoRejectScore', value => isNumberIn({ value, min: 0, max: 1 }), 'a number from 0 to 1'],
+    ['maxPerIpPerHour', value => isNumberIn({ value, min: 1, max: 1000 }, { integer: true }), 'an integer from 1 to 1000'],
+];
+/** @returns A refusal reason naming the first invalid field, or null when every field is valid. */
+function describeInvalidSettings({ settings }, _optional = {}) {
+    const rule = SETTINGS_RULES.find(([field, isValid]) => !isValid(settings[field]));
+    return rule ? `${rule[0]} must be ${rule[2]}` : null;
+}
 /** Isolated admin contract fixture over the existing CMS memory repository.
  * Keyset paging, optimistic concurrency and deletion belong to that repository, not this screen.
  * Settings here are an ephemeral read-your-writes fixture; production persistence stays in the
@@ -28,31 +46,31 @@ export function createMemoryCommentsApi({ items = [], settings = DEFAULT_SETTING
             return Object.freeze({ items: Object.freeze(page.items.map(item => Object.freeze({ ...item }))), nextCursor: page.nextCursor });
         },
         async moderateComment({ commentId, action, expectedVersion }, { note } = {}) {
-            const statuses = { approve: 'approved', spam: 'spam', trash: 'trash', restore: 'approved' };
-            const toStatus = Object.hasOwn(statuses, action) ? statuses[action] : undefined;
+            const toStatus = Object.hasOwn(MODERATION_STATUSES, action) ? MODERATION_STATUSES[action] : undefined;
             if (!toStatus)
-                failure('Invalid moderation action', 400);
+                failure(`Invalid moderation action "${action}": use approve, spam, trash or restore`, 400);
             const result = await repo.applyModeration({ workspaceId, id: commentId, expectedVersion,
                 action: action === 'spam' ? 'mark_spam' : action, toStatus,
                 actorPrincipalId: '__admin-memory__', note: note ?? null, at: now() });
-            if (!result.ok)
-                failure(result.reason === 'conflict' ? 'Comment changed' : 'Comment was not found', result.reason === 'conflict' ? 409 : 404, result.reason === 'conflict' ? { currentVersion: result.currentVersion } : undefined);
+            if (result.ok)
+                return;
+            if (result.reason === 'conflict') {
+                failure(`Comment ${commentId} changed since it was loaded (current version ${result.currentVersion}); reload the queue and retry`, 409, { currentVersion: result.currentVersion });
+            }
+            failure(`Comment ${commentId} was not found in this workspace`, 404);
         },
         async purgeComment({ commentId }, { note } = {}) {
             const result = await repo.purge({ workspaceId, id: commentId, actorPrincipalId: '__admin-memory__', note: note ?? null, at: now() });
             if (!result.ok)
-                failure('Comment was not found', 404);
+                failure(`Comment ${commentId} was not found in this workspace`, 404);
         },
         async getCommentsSettings(_required, _options = {}) { return Object.freeze({ ...storedSettings }); },
         async putCommentsSettings(_required, patch = {}) {
             // Only fixture-level shape checks: the durable ledger remains the production validator.
             const next = { ...storedSettings, ...patch };
-            if (typeof next.enabled !== 'boolean' || typeof next.requireModeration !== 'boolean'
-                || !Number.isInteger(next.maxDepth) || next.maxDepth < 0 || next.maxDepth > 20
-                || (next.closeAfterDays !== null && (!Number.isInteger(next.closeAfterDays) || next.closeAfterDays < 0))
-                || !Number.isFinite(next.spamAutoRejectScore) || next.spamAutoRejectScore < 0 || next.spamAutoRejectScore > 1
-                || !Number.isInteger(next.maxPerIpPerHour) || next.maxPerIpPerHour < 1 || next.maxPerIpPerHour > 1000)
-                failure('Invalid Comments settings', 400);
+            const invalid = describeInvalidSettings({ settings: next });
+            if (invalid)
+                failure(`Invalid Comments settings: ${invalid}`, 400);
             storedSettings = Object.freeze(next);
             return Object.freeze({ ...storedSettings });
         },

package/dist/comments/conformance/comments-api.conformance.js

@@ -1,24 +1,24 @@
-/** Destructive checklist for an isolated fixture containing at least two pending comments.
- * Uses only the core port, works against HTTP and memory, and throws at the first failed check.
- * @returns Named passed checks. The first seeded comment is purged; never use production data.
- */
-export async function runCommentsApiConformance({ api }, _optional = {}) {
-    const checks = [];
-    function assert(condition, name) {
-        if (!condition)
-            throw new Error(`Comments API conformance: ${name}`);
-        checks.push(name);
+async function settle({ run }, _optional = {}) {
+    try {
+        await run();
+        return { threw: false };
     }
-    async function rejects(run, name) {
-        let rejected = false;
-        try {
-            await run();
-        }
-        catch {
-            rejected = true;
-        }
-        assert(rejected, name);
+    catch (error) {
+        return { threw: true, error };
     }
+}
+async function rejects({ check, run, name }, _optional = {}) {
+    check.assert((await settle({ run })).threw, name);
+}
+function hasConflictVersion({ settled, version }, _optional = {}) {
+    if (!settled.threw)
+        return false;
+    const e = settled.error;
+    return e instanceof Error && 'status' in e && e.status === 409 && 'body' in e
+        && e.body?.currentVersion === version;
+}
+async function checkPaging({ check }, _optional = {}) {
+    const { api, assert } = check;
     const first = await api.listCommentsQueue({}, { status: 'pending', limit: 1 });
     const comment = first.items[0];
     if (!comment || !first.nextCursor)
@@ -26,37 +26,59 @@ export async function runCommentsApiConformance({ api }, _optional = {}) {
     assert(first.items.length === 1 && comment.status === 'pending', 'status and limit filter');
     const second = await api.listCommentsQueue({}, { status: 'pending', limit: 1, cursor: first.nextCursor });
     assert(second.items.length === 1 && second.items[0]?.id !== comment.id, 'cursor advances without repeating rows');
+    return { first, comment, cursor: first.nextCursor, second };
+}
+async function checkSettings({ check }, _optional = {}) {
+    const { api, assert } = check;
     const settings = await api.getCommentsSettings({});
     const updated = await api.putCommentsSettings({}, { maxDepth: settings.maxDepth + 1, closeAfterDays: null });
     assert(updated.maxDepth === settings.maxDepth + 1 && updated.closeAfterDays === null && updated.enabled === settings.enabled, 'partial settings patch preserves siblings and null');
     assert((await api.getCommentsSettings({})).maxDepth === updated.maxDepth, 'settings read your writes');
-    await rejects(() => api.putCommentsSettings({}, { spamAutoRejectScore: 2 }), 'invalid settings patch rejects');
+    await rejects({ check, run: () => api.putCommentsSettings({}, { spamAutoRejectScore: 2 }), name: 'invalid settings patch rejects' });
     assert((await api.getCommentsSettings({})).spamAutoRejectScore === settings.spamAutoRejectScore, 'invalid settings patch is atomic');
+    return settings;
+}
+async function checkModerationCycle({ check, comment }, _optional = {}) {
+    const { api, assert } = check;
     let current = comment;
     for (const [action, status] of [['approve', 'approved'], ['spam', 'spam'], ['trash', 'trash'], ['restore', 'approved']]) {
         const reply = await api.moderateComment({ commentId: current.id, action, expectedVersion: current.version });
         assert(reply === undefined, `${action} has no response body`);
-        const page = await api.listCommentsQueue({}, { status: status });
+        const page = await api.listCommentsQueue({}, { status });
         const row = page.items.find(item => item.id === current.id);
         assert(row?.status === status && row.version === current.version + 1, `${action} changes status and increments version`);
         current = row;
     }
-    assert(comment.version === first.items[0]?.version && comment.status === 'pending', 'earlier queue snapshot is unchanged');
-    try {
-        await api.moderateComment({ commentId: current.id, action: 'trash', expectedVersion: comment.version });
-        throw new Error('Stale moderation unexpectedly succeeded');
-    }
-    catch (e) {
-        assert(e instanceof Error && 'status' in e && e.status === 409 && 'body' in e
-            && e.body?.currentVersion === current.version, 'stale version rejects with status and currentVersion');
-    }
-    const remaining = await api.listCommentsQueue({}, { status: 'pending', limit: 1, cursor: first.nextCursor });
+    return current;
+}
+async function checkCursorAndPurge({ check, current, cursor, second }, _optional = {}) {
+    const { api, assert } = check;
+    const remaining = await api.listCommentsQueue({}, { status: 'pending', limit: 1, cursor });
     assert(remaining.items[0]?.id === second.items[0]?.id, 'cursor survives its marker leaving the status');
     await api.moderateComment({ commentId: current.id, action: 'trash', expectedVersion: current.version });
     assert(await api.purgeComment({ commentId: current.id }) === undefined, 'purge has no version guard or response body');
     assert(!(await api.listCommentsQueue({}, { status: 'trash' })).items.some(item => item.id === current.id), 'purge removes the row');
-    await rejects(() => api.purgeComment({ commentId: current.id }), 'missing purge rejects');
-    await rejects(() => api.moderateComment({ commentId: current.id, action: 'approve', expectedVersion: current.version }), 'missing moderation rejects');
+    await rejects({ check, run: () => api.purgeComment({ commentId: current.id }), name: 'missing purge rejects' });
+    await rejects({ check, run: () => api.moderateComment({ commentId: current.id, action: 'approve', expectedVersion: current.version }), name: 'missing moderation rejects' });
+}
+/** Destructive checklist for an isolated fixture containing at least two pending comments.
+ * Uses only the core port, works against HTTP and memory, and throws at the first failed check.
+ * @returns Named passed checks. The first seeded comment is purged; never use production data.
+ */
+export async function runCommentsApiConformance({ api }, _optional = {}) {
+    const checks = [];
+    const check = { api, assert(condition, name) {
+            if (!condition)
+                throw new Error(`Comments API conformance: ${name}`);
+            checks.push(name);
+        } };
+    const { first, comment, cursor, second } = await checkPaging({ check });
+    const settings = await checkSettings({ check });
+    const current = await checkModerationCycle({ check, comment });
+    check.assert(comment.version === first.items[0]?.version && comment.status === 'pending', 'earlier queue snapshot is unchanged');
+    const stale = await settle({ run: () => api.moderateComment({ commentId: current.id, action: 'trash', expectedVersion: comment.version }) });
+    check.assert(hasConflictVersion({ settled: stale, version: current.version }), 'stale version rejects with status and currentVersion');
+    await checkCursorAndPurge({ check, current, cursor, second });
     await api.putCommentsSettings({}, settings);
     return Object.freeze(checks);
 }

package/dist/comments/controllers/comment-queue.controller.js

@@ -57,6 +57,8 @@ export function createCommentQueueController({ api, permissions = [] }, { t = en
         if (store.signal.aborted)
             return;
         permissions = nextPermissions;
+        if (t === nextTranslator)
+            return;
         t = nextTranslator;
         publishPages();
     }
@@ -81,6 +83,13 @@ export function createCommentQueueController({ api, permissions = [] }, { t = en
         firstError = error;
         publishPages();
     }
+    /** A cursor read may only publish while it is still the newest one and the store is live. */
+    function isCurrentRead({ generation }, _optional = {}) {
+        return generation === pageGeneration && !store.signal.aborted;
+    }
+    function readMorePage({ status, cursor }, _optional = {}) {
+        return loadPage ? loadPage({ status, cursor }) : api.listCommentsQueue({}, { status, cursor });
+    }
     async function loadMore(_required = {}, _optional = {}) {
         const { nextCursor, status } = store.getSnapshot();
         if (store.signal.aborted || !nextCursor || loadingMore)
@@ -91,22 +100,22 @@ export function createCommentQueueController({ api, permissions = [] }, { t = en
         store.set({ patch: { loadingMore: true } });
         publishPages();
         try {
-            const page = await (loadPage ? loadPage({ status, cursor: nextCursor }) : api.listCommentsQueue({}, { status, cursor: nextCursor }));
-            if (generation !== pageGeneration || store.signal.aborted)
+            const page = await readMorePage({ status, cursor: nextCursor });
+            if (!isCurrentRead({ generation }))
                 return;
             morePages = [...morePages, ...page.items];
             store.set({ patch: { nextCursor: page.nextCursor } });
             publishPages();
         }
         catch (e) {
-            if (generation !== pageGeneration || store.signal.aborted)
+            if (!isCurrentRead({ generation }))
                 return;
             moreError = describeApiError({ e, fallback: t('failed to load the moderation queue') });
             publishPages();
         }
         finally {
             // The reset already released a superseded call's lock; it must not unlock a newer call.
-            if (generation === pageGeneration && !store.signal.aborted) {
+            if (isCurrentRead({ generation })) {
                 loadingMore = false;
                 store.set({ patch: { loadingMore: false } });
             }

package/dist/comments/react/hooks/use-comment-queue.hooks.d.ts

@@ -1,8 +1,20 @@
-import { type Dispatch, type SetStateAction } from 'react';
+import { type Dispatch, type SetStateAction, type ReactNode } from 'react';
 import type { AdminComment, AdminCommentsPort, CommentModerationAction, CommentStatus } from '../../../core/ports/comments.js';
 import { type RowActionState } from '../../rules.js';
 import type { CommentsEventsPort } from '../../ports.js';
 import { type CommentsTranslator } from '../../messages.en.js';
+/** Host-owned identity; never infer tenancy or the current operator from returned rows. */
+export interface CommentQueueScope {
+    readonly workspaceId: string;
+    readonly principalId: string;
+}
+/** Supply live workspace/principal identity to wired queues, including with a singleton API.
+ * Update scope at the authentication boundary before rendering the next principal's children.
+ */
+export declare function CommentQueueScopeProvider({ scope, children }: {
+    scope: CommentQueueScope;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<CommentQueueScope | null>>;
 export interface CommentQueueController {
     status: CommentStatus;
     setStatus: Dispatch<SetStateAction<CommentStatus>>;
@@ -20,9 +32,12 @@ export interface CommentQueueController {
 /** Effects attach to injected ports; cursor/row state belongs to the headless controller.
  * The shared cache guards stale page-one keys. Cursor settlement is guarded separately because
  * one fixed query key cannot represent an accumulated list of appended pages.
+ * All read/invalidation keys include explicit workspace/principal identity and API identity.
+ * A scope change hides the previous controller immediately, before effect cleanup runs.
  */
-export declare function useCommentQueue({ api, permissions }: {
+export declare function useCommentQueue({ api, scope, permissions }: {
     api: AdminCommentsPort;
+    scope: CommentQueueScope;
     permissions?: readonly string[];
 }, { t, events }?: {
     t?: CommentsTranslator;

package/dist/comments/react/hooks/use-comment-queue.hooks.js

@@ -1,58 +1,107 @@
-import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { createContext, createElement, useContext, useCallback, useEffect, useMemo, useRef } from 'react';
 import { useCachedLoader, useFetchQuery, useInvalidate } from '@jini-ai/ui/fetch-query';
+import { AdminConfigError } from '../../../core/module/create-admin.js';
 import { useController } from '../../../core/react/use-controller.js';
 import { createCommentQueueController } from '../../controllers/comment-queue.controller.js';
 import { KEYS, emptyRowState } from '../../rules.js';
 import { englishComments } from '../../messages.en.js';
 import { useCommentsPorts, useCommentsTranslation } from './CommentsPorts.hooks.js';
 const NO_GRANTS = [];
+/** What renders before the controller's first snapshot; mirrors the controller's initial state. */
+const BEFORE_FIRST_SNAPSHOT = Object.freeze({
+    status: 'pending', items: null, nextCursor: null, error: null, loadingMore: false, rowState: {}, pendingPurge: null,
+});
+const CommentQueueScopeContext = createContext(null);
+/** Supply live workspace/principal identity to wired queues, including with a singleton API.
+ * Update scope at the authentication boundary before rendering the next principal's children.
+ */
+export function CommentQueueScopeProvider({ scope, children }) {
+    return createElement(CommentQueueScopeContext.Provider, { value: scope }, children);
+}
+// Weak API keys preserve sharing between consumers without retaining APIs from previous sessions.
+// Explicit workspace/principal keys below also isolate hosts that retain one API across sessions.
+const queueScopes = new WeakMap();
+let nextQueueScope = 0;
+/** Allocate the API portion of a namespace; workspace/principal identity is keyed separately. */
+function queueScope({ api }, _optional = {}) {
+    let scope = queueScopes.get(api);
+    if (scope === undefined) {
+        scope = ++nextQueueScope;
+        queueScopes.set(api, scope);
+    }
+    return scope;
+}
+/** Preserve the hook's loading defaults while no controller from the current scope is attached. */
+function queueDisplay({ snapshot }, _optional = {}) {
+    const { status, items, nextCursor, error, loadingMore, pendingPurge } = snapshot ?? BEFORE_FIRST_SNAPSHOT;
+    return { status, items, nextCursor, error, loadingMore, pendingPurge };
+}
+/** Resolve React's value/updater forms against the attached controller's current snapshot. */
+function resolveSetState({ value, current }, _optional = {}) {
+    return typeof value === 'function' ? value(current) : value;
+}
+/** Adapt public React setters/actions to the attached headless controller.
+ * Before the controller exists every gesture is inert and every row reads as idle.
+ */
+function bindQueueActions({ controller }, _optional = {}) {
+    return {
+        setStatus: value => { if (controller)
+            controller.setStatus({ status: resolveSetState({ value, current: controller.getSnapshot().status }) }); },
+        loadMore: () => controller?.loadMore({}),
+        stateFor: id => controller?.stateFor({ id }) ?? emptyRowState(),
+        onModerate: async (comment, action) => { await controller?.onModerate({ comment, action }); },
+        setPendingPurge: value => { if (controller)
+            controller.setPendingPurge({ comment: resolveSetState({ value, current: controller.getSnapshot().pendingPurge }) }); },
+        onPurge: async () => { await controller?.onPurge({}); },
+    };
+}
+/** Cursor pages share page one's scoped cache prefix, so invalidation stays within that scope. */
+function useCursorPageLoader({ api, queueRoot, status, cursor }, _optional = {}) {
+    const cursorKey = useMemo(() => [...queueRoot, status, 'cursor', cursor], [queueRoot, status, cursor]);
+    const fetchCursor = useCallback(() => api.listCommentsQueue({}, { status, cursor }), [api, status, cursor]);
+    const cursorLoader = useCachedLoader({ key: cursorKey, fetch: fetchCursor }, { staleTime: 0 });
+    return ({ status: requestedStatus, cursor: requestedCursor }) => cursorLoader.load({
+        key: [...queueRoot, requestedStatus, 'cursor', requestedCursor],
+        fetch: () => api.listCommentsQueue({}, { status: requestedStatus, cursor: requestedCursor }),
+    });
+}
 /** Effects attach to injected ports; cursor/row state belongs to the headless controller.
  * The shared cache guards stale page-one keys. Cursor settlement is guarded separately because
  * one fixed query key cannot represent an accumulated list of appended pages.
+ * All read/invalidation keys include explicit workspace/principal identity and API identity.
+ * A scope change hides the previous controller immediately, before effect cleanup runs.
  */
-export function useCommentQueue({ api, permissions = NO_GRANTS }, { t = englishComments, events } = {}) {
+export function useCommentQueue({ api, scope, permissions = NO_GRANTS }, { t = englishComments, events } = {}) {
     const invalidate = useInvalidate();
-    const invalidateQueue = useCallback(() => invalidate({ key: KEYS.queueRoot }), [invalidate]);
+    const queueRoot = useMemo(() => [...KEYS.queueRoot, queueScope({ api }), scope.workspaceId, scope.principalId], [api, scope.workspaceId, scope.principalId]);
+    const invalidateQueue = useCallback(() => invalidate({ key: queueRoot }), [invalidate, queueRoot]);
     const loadPageRef = useRef(null);
-    const { controller, snapshot } = useController({
-        create: () => createCommentQueueController({ api, permissions }, { t, onInvalidate: invalidateQueue, loadPage: required => loadPageRef.current(required) }),
+    const { controller: attachedController, snapshot: attachedSnapshot } = useController({
+        create: () => ({ ...createCommentQueueController({ api, permissions }, { t, onInvalidate: invalidateQueue, loadPage: required => loadPageRef.current(required) }), queueRoot }),
         dependencies: [api, invalidateQueue],
     });
+    // Effects replace the controller after commit; hide the previous scope during that render too.
+    const controller = attachedController?.queueRoot === queueRoot ? attachedController : null;
+    const snapshot = controller ? attachedSnapshot : null;
     useEffect(() => { controller?.configure({ permissions, t }); }, [controller, permissions, t]);
-    const status = snapshot?.status ?? 'pending';
-    const cursor = snapshot?.nextCursor ?? '';
-    const cursorKey = useMemo(() => [...KEYS.queue(status), 'cursor', cursor], [status, cursor]);
-    const fetchCursor = useCallback(() => api.listCommentsQueue({}, { status, cursor }), [api, status, cursor]);
-    const cursorLoader = useCachedLoader({ key: cursorKey, fetch: fetchCursor }, { staleTime: 0 });
+    const display = queueDisplay({ snapshot });
+    const { status } = display;
     // The gesture remains controller-owned, including its same-tick lock and generation fence.
     // Only I/O changes: cursor pages now share page one's provider and status invalidation prefix.
-    loadPageRef.current = ({ status: requestedStatus, cursor: requestedCursor }) => cursorLoader.load({
-        key: [...KEYS.queue(requestedStatus), 'cursor', requestedCursor],
-        fetch: () => api.listCommentsQueue({}, { status: requestedStatus, cursor: requestedCursor }),
-    });
-    const firstPage = useFetchQuery({ key: KEYS.queue(status), fetch: () => api.listCommentsQueue({}, { status }) });
+    loadPageRef.current = useCursorPageLoader({ api, queueRoot, status, cursor: display.nextCursor ?? '' });
+    const firstPage = useFetchQuery({ key: [...queueRoot, status], fetch: () => api.listCommentsQueue({}, { status }) });
     useEffect(() => { controller?.settleFirstPage({ page: firstPage.data ?? null, error: firstPage.error, status }); }, [controller, firstPage.data, firstPage.error, status]);
     // Stable identity avoids resubscribing on every render. The host filters out unrelated
     // resources. Unmount removes the subscription even if another cache observer remains active.
     useEffect(() => events?.subscribe({ onRefresh: invalidateQueue }), [events, invalidateQueue]);
-    return {
-        status,
-        setStatus: value => { if (controller)
-            controller.setStatus({ status: typeof value === 'function' ? value(controller.getSnapshot().status) : value }); },
-        items: snapshot?.items ?? null, nextCursor: snapshot?.nextCursor ?? null,
-        error: snapshot?.error ?? null, loadingMore: snapshot?.loadingMore ?? false,
-        loadMore: () => controller?.loadMore({}),
-        stateFor: id => controller?.stateFor({ id }) ?? emptyRowState(),
-        onModerate: async (comment, action) => { await controller?.onModerate({ comment, action }); },
-        pendingPurge: snapshot?.pendingPurge ?? null,
-        setPendingPurge: value => { if (controller)
-            controller.setPendingPurge({ comment: typeof value === 'function' ? value(controller.getSnapshot().pendingPurge) : value }); },
-        onPurge: async () => { await controller?.onPurge({}); },
-    };
+    return { ...display, ...bindQueueActions({ controller }) };
 }
 export function useWiredCommentQueue({ permissions }, _optional = {}) {
     const { commentsApi, commentsEvents } = useCommentsPorts();
     const t = useCommentsTranslation();
-    return useCommentQueue({ api: commentsApi, permissions }, { t, ...(commentsEvents ? { events: commentsEvents } : {}) });
+    const scope = useContext(CommentQueueScopeContext);
+    if (!scope)
+        throw new AdminConfigError({ issues: ['Comment queue requires an explicit workspace/principal scope'] });
+    return useCommentQueue({ api: commentsApi, scope, permissions }, { t, ...(commentsEvents ? { events: commentsEvents } : {}) });
 }
 //# sourceMappingURL=use-comment-queue.hooks.js.map

package/dist/comments/react/hooks/use-comment-settings.hooks.js

@@ -5,6 +5,10 @@ import { createCommentSettingsController } from '../../controllers/comment-setti
 import { KEYS } from '../../rules.js';
 import { englishComments } from '../../messages.en.js';
 import { useCommentsPorts, useCommentsTranslation } from './CommentsPorts.hooks.js';
+const CONFIGURE_GRANTS = Object.freeze(['comments.configure']);
+const NO_GRANTS = Object.freeze([]);
+/** What renders before the controller's first snapshot; mirrors the controller's initial state. */
+const BEFORE_FIRST_SNAPSHOT = Object.freeze({ settings: null, error: null, saving: false, notice: null });
 /** No refresh-event subscription: background settings reads cannot re-seed an uncontrolled form.
  * The cache envelope is retained for observers of the existing KEYS.settings resource.
  */
@@ -12,15 +16,15 @@ export function useCommentSettings({ api, canConfigure }, { t = englishComments
     // AC-10: even GET is comments.configure-gated. Skip the doomed read for a denied principal.
     const list = useFetchQuery({ key: KEYS.settings, fetch: async () => ({ data: await api.getCommentsSettings({}) }) }, { enabled: canConfigure });
     const invalidate = useInvalidate();
+    const grants = canConfigure ? CONFIGURE_GRANTS : NO_GRANTS;
     const { controller, snapshot } = useController({
-        create: () => createCommentSettingsController({ api, permissions: canConfigure ? ['comments.configure'] : [] }, { t, onInvalidate: () => invalidate({ key: KEYS.settings }) }),
+        create: () => createCommentSettingsController({ api, permissions: grants }, { t, onInvalidate: () => invalidate({ key: KEYS.settings }) }),
         dependencies: [api, invalidate],
     });
-    useEffect(() => { controller?.configure({ permissions: canConfigure ? ['comments.configure'] : [], t }); }, [controller, canConfigure, t]);
+    useEffect(() => { controller?.configure({ permissions: grants, t }); }, [controller, grants, t]);
     useEffect(() => { controller?.settleRead({ settings: list.data?.data ?? null, error: list.error }); }, [controller, list.data, list.error]);
-    return { settings: snapshot?.settings ?? null, error: snapshot?.error ?? null,
-        saving: snapshot?.saving ?? false, notice: snapshot?.notice ?? null,
-        save: async (form) => { await controller?.save({ form }); } };
+    const { settings, error, saving, notice } = snapshot ?? BEFORE_FIRST_SNAPSHOT;
+    return { settings, error, saving, notice, save: async (form) => { await controller?.save({ form }); } };
 }
 export function useWiredCommentSettings({ canConfigure }, _optional = {}) {
     const { commentsApi } = useCommentsPorts();

package/dist/comments/react/index.d.ts

@@ -3,7 +3,8 @@ export type { CommentsProps } from './pages/CommentsPage.js';
 export type { QueueSectionProps } from './components/QueueSection.js';
 export type { SettingsSectionProps } from './components/SettingsSection.js';
 export { useComments, useWiredComments } from './hooks/use-comments.hooks.js';
-export { useCommentQueue, useWiredCommentQueue } from './hooks/use-comment-queue.hooks.js';
+export type { CommentQueueScope } from './hooks/use-comment-queue.hooks.js';
+export { CommentQueueScopeProvider, useCommentQueue, useWiredCommentQueue } from './hooks/use-comment-queue.hooks.js';
 export { useCommentSettings, useWiredCommentSettings } from './hooks/use-comment-settings.hooks.js';
 export { useCommentsPorts } from './hooks/CommentsPorts.hooks.js';
 /** One comments module per admin scope. Host translation is scoped without adding rendered DOM.

package/dist/comments/react/index.js

@@ -4,7 +4,7 @@ import { commentsModule } from '../comments.module.js';
 import { englishComments } from '../messages.en.js';
 import { CommentsPortsContext, CommentsTranslationContext } from './hooks/CommentsPorts.hooks.js';
 export { useComments, useWiredComments } from './hooks/use-comments.hooks.js';
-export { useCommentQueue, useWiredCommentQueue } from './hooks/use-comment-queue.hooks.js';
+export { CommentQueueScopeProvider, useCommentQueue, useWiredCommentQueue } from './hooks/use-comment-queue.hooks.js';
 export { useCommentSettings, useWiredCommentSettings } from './hooks/use-comment-settings.hooks.js';
 export { useCommentsPorts } from './hooks/CommentsPorts.hooks.js';
 /** One comments module per admin scope. Host translation is scoped without adding rendered DOM.