@jini-ai/admin 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.4.4 — 2026-10-08
+
+- Desktop 0.1.13 release fixes: see commits a2659d24 (admin), 5695a7c3 (chat, agent-runtime), 8ad4ac5c (devops).
+
+## 0.4.3
+
+### Patch Changes
+
+- Tovu clean-up release (2026-10-08): code Tovu moved into Jini, plus the Jini clean-up (see the commit log since 0.4.2).
+
 ## 0.4.2 — 2026-10-05
 
 - Catalog provider settings: on a host without `saveChanges`, a provider the last read did not return (a catalog-only provider's first key or settings) is now written instead of silently dropped while the tab reported Saved.
@@ -21,6 +31,11 @@
 
 ## Unreleased
 
+- Add portable Forms admin screens, HTTP/memory adapters and core-port conformance under ./forms*.
+- Add composable comments admin queue/settings module with HTTP and memory adapters and API conformance.
+- Add portable redirects admin module, React list, HTTP/memory adapters and API conformance.
+- Add portable SEO admin settings, sitemap viewer, entry overrides and analysis with HTTP/memory adapters and API conformance.
+- Add composable widgets admin screens, headless controllers, HTTP/memory adapters and API conformance.
 - Media Providers tab on hosts without `saveChanges`: saving the first key or
   settings of a catalog provider the last read did not return now writes them
   (previously nothing was written, yet the tab showed "Saved").

package/README.md

@@ -173,3 +173,10 @@ its presence does not imply matcher support. Hosts must verify support before of
 React controls keep importing `agentHandle` and `buildAgentListHandles` from
 `@jini-ai/agentic`; this is an allowed UI-to-agentic layer dependency. The helpers
 have not moved and consumers continue to use their original exports.
+
+Shared React binding helpers are also available from `@jini-ai/admin/core/react`.
+This is an explicit browser adapter entry: `@jini-ai/admin/core` and the package
+root remain framework free. Domain React entries call these shared helpers
+directly, and the existing `react/bind-react` and `react/use-controller` entries
+retain their exports through compatibility re-exports. Domain integration
+packages are optional peers; install the peers used by the selected entries.

package/dist/agent-plugins/react/components/AgentPluginListPanel.d.ts

@@ -1,4 +1,4 @@
-import type { TabViewProps } from '../../../react/bind-react.js';
+import type { TabViewProps } from '../../../core/react/bind-react.js';
 export declare function AgentPluginListPanel({ props, mode }: {
     props: TabViewProps;
     mode: 'installed' | 'downloaded';

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

@@ -1,5 +1,5 @@
 import { useEffect, useId, useRef, useState } from 'react';
-import { useController } from '../../../react/use-controller.js';
+import { useController } from '../../../core/react/use-controller.js';
 import { createAgentPluginFilesController } from '../../controllers/agent-plugin-files.controller.js';
 import { useAgentPluginsPorts } from './AgentPluginsPorts.hooks.js';
 import { AGENT_PLUGINS_READ, agentPluginFileNotice, selectAgentPluginFile } from '../../rules.js';

package/dist/agent-plugins/react/hooks/AgentPluginPanel.hooks.d.ts

@@ -1,4 +1,4 @@
-import type { TabViewProps } from '../../../react/bind-react.js';
+import type { TabViewProps } from '../../../core/react/bind-react.js';
 export declare function useAgentPluginPanel({ props, mode }: {
     props: TabViewProps;
     mode: 'installed' | 'downloaded';

package/dist/agent-plugins/react/hooks/AgentPluginsPage.hooks.d.ts

@@ -1,4 +1,4 @@
-import type { ModulePageProps } from '../../../react/bind-react.js';
+import type { ModulePageProps } from '../../../core/react/bind-react.js';
 import { createAgentPluginsController } from '../../controllers/agent-plugins.controller.js';
 import type { AgentPluginsState } from '../../models.js';
 export interface AgentPluginsPageScope {

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

@@ -1,5 +1,5 @@
 import { createContext, useContext, useId, useState } from 'react';
-import { useController } from '../../../react/use-controller.js';
+import { useController } from '../../../core/react/use-controller.js';
 import { createAgentPluginsController } from '../../controllers/agent-plugins.controller.js';
 import { AGENT_PLUGINS_READ, agentPluginDisableCopy, humanizeAgentPluginId } from '../../rules.js';
 import { useAgentPluginsPorts } from './AgentPluginsPorts.hooks.js';

package/dist/agent-plugins/react/hooks/MarketplaceTab.hooks.d.ts

@@ -1,4 +1,4 @@
-import type { TabViewProps } from '../../../react/bind-react.js';
+import type { TabViewProps } from '../../../core/react/bind-react.js';
 export declare function useMarketplaceTab({ permissions }: TabViewProps, _optional?: {}): {
     denied: boolean;
     specUrl: string;

package/dist/agent-plugins/react/index.js

@@ -1,4 +1,4 @@
-import { bindReact } from '../../react/bind-react.js';
+import { bindReact } from '../../core/react/bind-react.js';
 import { agentPluginsModule } from '../agent-plugins.module.js';
 import { AgentPluginsPortsContext } from './hooks/AgentPluginsPorts.hooks.js';
 import { agentPluginsMessagesEn as m } from '../messages.en.js';

package/dist/agent-plugins/react/pages/AgentPluginsPage.d.ts

@@ -1,4 +1,4 @@
-import type { ModulePageProps } from '../../../react/bind-react.js';
+import type { ModulePageProps } from '../../../core/react/bind-react.js';
 export declare function AgentPluginsPage(props: ModulePageProps, _optional?: {}): import("react").JSX.Element;
 export default AgentPluginsPage;
 //# sourceMappingURL=AgentPluginsPage.d.ts.map

package/dist/agent-plugins/react/tabs/DownloadedTab.d.ts

@@ -1,4 +1,4 @@
-import type { TabViewProps } from '../../../react/bind-react.js';
+import type { TabViewProps } from '../../../core/react/bind-react.js';
 export declare function DownloadedTab(props: TabViewProps, _optional?: {}): import("react").JSX.Element;
 export default DownloadedTab;
 //# sourceMappingURL=DownloadedTab.d.ts.map

package/dist/agent-plugins/react/tabs/InstalledTab.d.ts

@@ -1,4 +1,4 @@
-import type { TabViewProps } from '../../../react/bind-react.js';
+import type { TabViewProps } from '../../../core/react/bind-react.js';
 export declare function InstalledTab(props: TabViewProps, _optional?: {}): import("react").JSX.Element;
 export default InstalledTab;
 //# sourceMappingURL=InstalledTab.d.ts.map

package/dist/agent-plugins/react/tabs/MarketplaceTab.d.ts

@@ -1,4 +1,4 @@
-import type { TabViewProps } from '../../../react/bind-react.js';
+import type { TabViewProps } from '../../../core/react/bind-react.js';
 export declare function MarketplaceTab(props: TabViewProps, _optional?: {}): import("react").JSX.Element;
 export default MarketplaceTab;
 //# sourceMappingURL=MarketplaceTab.d.ts.map

package/dist/comments/adapters/http.d.ts

@@ -0,0 +1,29 @@
+import type { AdminCommentsPort } from '../../core/ports/comments.js';
+import type { CommentsSessionPort } from '../ports.js';
+/** The host owns auth, URL prefixes, retries, serialization, and decoded status/body errors. */
+export interface CommentsTransportPort {
+    request<T>(required: {
+        path: string;
+        method: 'GET' | 'POST' | 'PUT';
+        body?: unknown;
+    }, optional?: {
+        signal?: AbortSignal;
+    }): Promise<T>;
+    url(required: {
+        path: string;
+    }, optional?: Record<string, never>): string;
+}
+/** Adapt the existing workspace comments routes to the core port, unwrapping settings only.
+ * @param required Host transport and comments base path, e.g. `/workspaces/<id>/comments`.
+ * @returns The core comments API. Decoded status/body fields adopt the shared core error type.
+ */
+export declare function createHttpCommentsApi({ transport, basePath }: {
+    transport: CommentsTransportPort;
+    basePath: string;
+}, _optional?: Record<string, never>): AdminCommentsPort;
+/** Reuse the core auth `me` contract over the host's existing auth path. */
+export declare function createHttpCommentsSession({ transport, path }: {
+    transport: CommentsTransportPort;
+    path: string;
+}, _optional?: Record<string, never>): CommentsSessionPort;
+//# sourceMappingURL=http.d.ts.map

package/dist/comments/adapters/http.js

@@ -0,0 +1,50 @@
+import { AdminApiError } from '../../core/transport/errors.js';
+/** Preserve the host's decoded fields while adopting the shared core error owner. */
+async function request({ transport, ...required }, optional = {}) {
+    try {
+        return await transport.request(required, optional);
+    }
+    catch (error) {
+        if (error instanceof AdminApiError || !(error instanceof Error) || !('status' in error) || typeof error.status !== 'number')
+            throw error;
+        const decoded = error;
+        throw new AdminApiError({ message: decoded.message, status: decoded.status }, { code: decoded.code, body: decoded.body });
+    }
+}
+/** Adapt the existing workspace comments routes to the core port, unwrapping settings only.
+ * @param required Host transport and comments base path, e.g. `/workspaces/<id>/comments`.
+ * @returns The core comments API. Decoded status/body fields adopt the shared core error type.
+ */
+export function createHttpCommentsApi({ transport, basePath }, _optional = {}) {
+    const base = basePath.replace(/\/$/, '');
+    return {
+        listCommentsQueue(_required, options = {}) {
+            const params = new URLSearchParams();
+            if (options.status)
+                params.set('status', options.status);
+            if (options.cursor)
+                params.set('cursor', options.cursor);
+            if (options.limit)
+                params.set('limit', String(options.limit));
+            const qs = params.toString();
+            return request({ transport, path: `${base}/queue${qs ? `?${qs}` : ''}`, method: 'GET' });
+        },
+        async moderateComment({ commentId, action, expectedVersion }, options = {}) {
+            await request({ transport, path: `${base}/${encodeURIComponent(commentId)}/${action}`, method: 'POST', body: { expectedVersion, note: options.note } });
+        },
+        async purgeComment({ commentId }, options = {}) {
+            await request({ transport, path: `${base}/${encodeURIComponent(commentId)}/purge`, method: 'POST', body: { note: options.note } });
+        },
+        async getCommentsSettings(_required, _options = {}) {
+            return (await request({ transport, path: `${base}/settings`, method: 'GET' })).data;
+        },
+        async putCommentsSettings(_required, patch = {}) {
+            return (await request({ transport, path: `${base}/settings`, method: 'PUT', body: patch })).data;
+        },
+    };
+}
+/** Reuse the core auth `me` contract over the host's existing auth path. */
+export function createHttpCommentsSession({ transport, path }, _optional = {}) {
+    return { me: (_required, _options = {}) => request({ transport, path, method: 'GET' }) };
+}
+//# sourceMappingURL=http.js.map

package/dist/comments/adapters/memory.d.ts

@@ -0,0 +1,17 @@
+import type { AdminComment, AdminCommentsPort, CommentsSettings } from '../../core/ports/comments.js';
+/** 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
+ * host's layered settings ledger. No ingress, auth, outbox or trash-index service is simulated.
+ * @param required Seeded comments and settings, copied so later writes cannot alter input fixtures.
+ * @param optional Workspace scope and deterministic clock for moderation metadata.
+ * @returns The core API with immutable snapshots and decoded status/body errors.
+ */
+export declare function createMemoryCommentsApi({ items, settings }: {
+    items?: readonly AdminComment[];
+    settings?: CommentsSettings;
+}, { workspaceId, now }?: {
+    workspaceId?: string;
+    now?: () => string;
+}): AdminCommentsPort;
+//# sourceMappingURL=memory.d.ts.map

package/dist/comments/adapters/memory.js

@@ -0,0 +1,61 @@
+import { InMemoryCommentRepo } from '@jini-ai/cms/comments';
+import { optionalOneOf, readToolLimit } from '@jini-ai/core';
+import { AdminApiError } from '../../core/transport/errors.js';
+const DEFAULT_SETTINGS = {
+    enabled: true, requireModeration: true, maxDepth: 5, closeAfterDays: null,
+    spamAutoRejectScore: 0.5, maxPerIpPerHour: 20,
+};
+/** 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
+ * host's layered settings ledger. No ingress, auth, outbox or trash-index service is simulated.
+ * @param required Seeded comments and settings, copied so later writes cannot alter input fixtures.
+ * @param optional Workspace scope and deterministic clock for moderation metadata.
+ * @returns The core API with immutable snapshots and decoded status/body errors.
+ */
+export function createMemoryCommentsApi({ items = [], settings = DEFAULT_SETTINGS }, { workspaceId = items[0]?.workspaceId ?? '__comments-memory__', now = () => '2026-10-07T00:00:00.000Z' } = {}) {
+    const repo = new InMemoryCommentRepo({ initialComments: items.map(item => ({ ...item, workspaceId: item.workspaceId ?? workspaceId })) });
+    let storedSettings = Object.freeze({ ...settings });
+    function failure(message, status, body) {
+        throw new AdminApiError({ message, status }, { body });
+    }
+    return {
+        async listCommentsQueue(_required, options = {}) {
+            // Same validators as the moderation-queue route: omitted limit is 20, >100 is capped.
+            const status = optionalOneOf({ input: options, key: 'status', values: ['pending', 'approved', 'spam', 'trash'] }) ?? 'pending';
+            const limit = readToolLimit({ input: options, max: 100, fallback: 20 });
+            const page = await repo.listModerationQueue({ workspaceId, status, limit, ...(options.cursor ? { cursor: options.cursor } : {}) });
+            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;
+            if (!toStatus)
+                failure('Invalid moderation action', 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);
+        },
+        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);
+        },
+        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);
+            storedSettings = Object.freeze(next);
+            return Object.freeze({ ...storedSettings });
+        },
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/comments/comments.module.d.ts

@@ -0,0 +1,73 @@
+export declare const commentsModule: {
+    readonly id: "comments";
+    readonly requires: {
+        readonly commentsApi: import("../core/module/token.js").AdminPortToken<import("./index.js").AdminCommentsPort, "admin.comments.api">;
+        readonly commentsSession: import("../core/module/token.js").AdminPortToken<import("./ports.js").CommentsSessionPort, "admin.comments.session">;
+    };
+    readonly optional: {
+        readonly commentsEvents: import("../core/module/token.js").AdminPortToken<import("./ports.js").CommentsEventsPort, "admin.comments.events">;
+    };
+    readonly messages: {
+        readonly Status: "Status";
+        readonly "Actions for the comment by \"{author}\"": "Actions for the comment by \"{author}\"";
+        readonly Author: "Author";
+        readonly Comment: "Comment";
+        readonly Depth: "Depth";
+        readonly Created: "Created";
+        readonly More: "More";
+        readonly "Loading\u2026": "Loading…";
+        readonly "Load more": "Load more";
+        readonly "Loading comments\u2026": "Loading comments…";
+        readonly "No {status} comments.": "No {status} comments.";
+        readonly "Permanently delete this comment?": "Permanently delete this comment?";
+        readonly "Permanently delete this comment by \"{author}\"? This cannot be undone.": "Permanently delete this comment by \"{author}\"? This cannot be undone.";
+        readonly "Permanently delete": "Permanently delete";
+        readonly "Loading Comments settings\u2026": "Loading Comments settings…";
+        readonly Settings: "Settings";
+        readonly "Comments enabled": "Comments enabled";
+        readonly "Require moderation (new comments start pending)": "Require moderation (new comments start pending)";
+        readonly "Max thread depth": "Max thread depth";
+        readonly "Close submissions after (days, blank = never)": "Close submissions after (days, blank = never)";
+        readonly "Spam auto-reject score (0\u20131)": "Spam auto-reject score (0–1)";
+        readonly "Max submissions per IP per hour": "Max submissions per IP per hour";
+        readonly "Saving\u2026": "Saving…";
+        readonly "Save settings": "Save settings";
+        readonly "Loading Comments\u2026": "Loading Comments…";
+        readonly People: "People";
+        readonly Comments: "Comments";
+        readonly "Moderate incoming comments and configure workspace-wide comment behavior.": "Moderate incoming comments and configure workspace-wide comment behavior.";
+        readonly "You do not have permission to view the moderation queue.": "You do not have permission to view the moderation queue.";
+        readonly "This comment changed since you loaded it (current version {currentVersion}) \u2014 refresh and try again.": "This comment changed since you loaded it (current version {currentVersion}) — refresh and try again.";
+        readonly "This comment changed since you loaded it \u2014 refresh and try again.": "This comment changed since you loaded it — refresh and try again.";
+        readonly "Failed to update comment.": "Failed to update comment.";
+        readonly Approve: "Approve";
+        readonly Spam: "Spam";
+        readonly Trash: "Trash";
+        readonly Restore: "Restore";
+        readonly Purge: "Purge";
+        readonly "Spam auto-reject score must be between 0 and 1.": "Spam auto-reject score must be between 0 and 1.";
+        readonly "failed to load the moderation queue": "failed to load the moderation queue";
+        readonly "Failed to purge comment.": "Failed to purge comment.";
+        readonly "Saved.": "Saved.";
+        readonly "failed to save Comments settings": "failed to save Comments settings";
+        readonly "failed to load Comments settings": "failed to load Comments settings";
+        readonly pending: "Pending";
+        readonly approved: "Approved";
+        readonly spam: "Spam";
+        readonly trash: "Trash";
+    };
+    readonly pages: {
+        readonly queue: {
+            readonly path: "/comments";
+            readonly label: "Comments";
+            readonly permissions: readonly ["comments.read"];
+            readonly agentReachable: true;
+            readonly nav: {
+                readonly group: "people";
+                readonly icon: "message-circle";
+            };
+            readonly tabs: {};
+        };
+    };
+};
+//# sourceMappingURL=comments.module.d.ts.map

package/dist/comments/comments.module.js

@@ -0,0 +1,16 @@
+import { defineAdminModule } from '../core/module/define-admin-module.js';
+import { commentsApiToken, commentsSessionToken, commentsEventsToken } from './ports.js';
+import { commentsMessagesEn } from './messages.en.js';
+export const commentsModule = defineAdminModule({
+    id: 'comments',
+    requires: { commentsApi: commentsApiToken, commentsSession: commentsSessionToken },
+    optional: { commentsEvents: commentsEventsToken },
+    messages: commentsMessagesEn,
+    pages: {
+        queue: {
+            path: '/comments', label: 'Comments', permissions: ['comments.read'],
+            agentReachable: true, nav: { group: 'people', icon: 'message-circle' }, tabs: {},
+        },
+    },
+});
+//# sourceMappingURL=comments.module.js.map

package/dist/comments/conformance/comments-api.conformance.d.ts

@@ -0,0 +1,9 @@
+import type { AdminCommentsPort } from '../../core/ports/comments.js';
+/** 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 declare function runCommentsApiConformance({ api }: {
+    api: AdminCommentsPort;
+}, _optional?: Record<string, never>): Promise<readonly string[]>;
+//# sourceMappingURL=comments-api.conformance.d.ts.map

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

@@ -0,0 +1,63 @@
+/** 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 rejects(run, name) {
+        let rejected = false;
+        try {
+            await run();
+        }
+        catch {
+            rejected = true;
+        }
+        assert(rejected, name);
+    }
+    const first = await api.listCommentsQueue({}, { status: 'pending', limit: 1 });
+    const comment = first.items[0];
+    if (!comment || !first.nextCursor)
+        throw new Error('Conformance needs at least two pending comments');
+    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');
+    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');
+    assert((await api.getCommentsSettings({})).spamAutoRejectScore === settings.spamAutoRejectScore, 'invalid settings patch is atomic');
+    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 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 });
+    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 api.putCommentsSettings({}, settings);
+    return Object.freeze(checks);
+}
+//# sourceMappingURL=comments-api.conformance.js.map

package/dist/comments/controllers/comment-queue.controller.d.ts

@@ -0,0 +1,48 @@
+import type { AdminComment, AdminCommentsPort, AdminCommentsQueuePage, CommentModerationAction, CommentStatus } from '../../core/ports/comments.js';
+import type { CommentQueueState } from '../models.js';
+import { type RowActionState } from '../rules.js';
+import { type CommentsTranslator } from '../messages.en.js';
+/** Headless cursor accumulation and per-row actions; page one remains owned by fetch-query.
+ * Permissions are affordances, denied by default. Every server write must reauthorize.
+ * @param required The core API and current session grants.
+ * @param optional Translator and an invalidation callback for every cached status.
+ * @returns An instance-scoped store and actions; dispose makes pending settlements inert.
+ */
+export declare function createCommentQueueController({ api, permissions }: {
+    api: AdminCommentsPort;
+    permissions?: readonly string[];
+}, { t, onInvalidate }?: {
+    t?: CommentsTranslator;
+    onInvalidate?: () => void;
+}): {
+    getSnapshot: () => Readonly<CommentQueueState>;
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }) => () => void;
+    dispose: (_required?: Record<string, never>, _optional?: Record<string, never>) => void;
+    stateFor: ({ id }: {
+        id: string;
+    }, _optional?: Record<string, never>) => RowActionState;
+    configure: ({ permissions: nextPermissions, t: nextTranslator }: {
+        permissions: readonly string[];
+        t: CommentsTranslator;
+    }, _optional?: Record<string, never>) => void;
+    setStatus: ({ status }: {
+        status: CommentStatus;
+    }, _optional?: Record<string, never>) => void;
+    settleFirstPage: ({ page, error, status }: {
+        page: AdminCommentsQueuePage | null;
+        error: Error | null;
+        status: CommentStatus;
+    }, _optional?: Record<string, never>) => void;
+    loadMore: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+    onModerate: ({ comment, action }: {
+        comment: AdminComment;
+        action: CommentModerationAction;
+    }, _optional?: Record<string, never>) => Promise<void>;
+    setPendingPurge: ({ comment }: {
+        comment: AdminComment | null;
+    }, _optional?: Record<string, never>) => void;
+    onPurge: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+};
+//# sourceMappingURL=comment-queue.controller.d.ts.map