@jini-ai/admin 0.4.1 → 0.4.3

package/dist/forms/rules.js

@@ -0,0 +1,338 @@
+import { AdminApiError as ApiError, describeApiError as describeCoreApiError } from "../core/transport/errors.js";
+const describeApiError = (e, fallback) => describeCoreApiError({ e, fallback });
+/**
+ * @file Pure logic for the `forms` feature (`FormEditor.tsx` — see `FormsList.tsx`'s own
+ * `rules.ts`/hook for the list screen's extraction) — everything that computes a value rather than
+ * rendering one. Follows the convention `features/posts/rules.ts` establishes: no React, no
+ * hooks, importable and directly testable.
+ *
+ * One deliberate exception to "pure", same as `collections/rules.ts`'s `nextRowId`:
+ * {@link nextAttrRowId} is a module-level counter `attrRowsFromField`/`addAttrRow` advance. Only
+ * `FieldAttributesDialog` (via `use-field-attributes-dialog.hooks.ts`) consumes it today, so it
+ * would be equally correct sitting in that hook file — kept here instead for the same reason
+ * `collections/rules.ts` keeps its row-id counter alongside its other draft-list transforms: one
+ * place for "how draft rows get local keys" per feature, not split by which hook happens to use it
+ * first.
+ *
+ * `KEYS` (fetch-query migration, 2026-08-12): forms and form-submissions are two independent
+ * resources (separate ports, no method overlap — see `core/ports/forms.ts`/`form-submissions-
+ * port.hooks.ts`'s own doc comments), so they get two entirely separate top-level key namespaces
+ * rather than sharing one grandparent. Within each, `list`/`detail(id)` (and `submissionsList(formId)`/
+ * `submissionDetail(formId, id)`) are SIBLINGS, not parent/child — `@jini-ai/ui/fetch-query`'s
+ * `QueryKey` doc warns that invalidation matches by prefix, and `collections/rules.ts`'s own `KEYS`
+ * doc records the regression that bit the predecessor when a detail key nested under its list: every
+ * save silently fired 3 extra background requests because invalidating the list also invalidated the
+ * editor's own currently-open read. Fixed second-array-element ("list" vs "detail") rather than
+ * nesting keeps `KEYS.list`'s invalidation from ever touching an open `KEYS.form(id)`/
+ * `KEYS.submissionDetail(...)` read, regardless of what `id` happens to be.
+ */
+/**
+ * This screen's name on `lib/content-refresh-bus.ts` — see `taxonomy/rules.ts`'s `TAXONOMY_RESOURCE`
+ * for why this is a plain colocated constant rather than a shared registry. `forms_create_definition`/
+ * `forms_update_definition`/`forms_set_definition_status` (`apps/website/src/features/forms/agent-
+ * tools.ts`) are agent-callable, so `FormsList.tsx` needs the same "an assistant write shows up
+ * without a reload" fix `use-taxonomy.hooks.ts` shipped first.
+ */
+export const FORMS_LIST_RESOURCE = "forms";
+/** The list has no sort control: recently edited forms belong first. Copy before sorting so
+ * the query cache and injected repository keep their own order; ties retain response order. */
+export function newestUpdatedForms({ forms }, _optional = {}) {
+    return [...forms].sort((a, b) => (Date.parse(b.updatedAt) || 0) - (Date.parse(a.updatedAt) || 0));
+}
+/** One form event's compact local date and full tooltip. Shared by definitions and submissions;
+ * malformed legacy values stay visible as a dash rather than throwing during table rendering. */
+export function formDateDisplay({ iso, locale }, { timeZone } = {}) {
+    const date = new Date(iso);
+    if (Number.isNaN(date.getTime()))
+        return { text: "—", full: "—", dateTime: undefined };
+    return {
+        text: new Intl.DateTimeFormat(locale, { dateStyle: "short", timeStyle: "short", timeZone }).format(date),
+        full: new Intl.DateTimeFormat(locale, {
+            year: "numeric", month: "short", day: "numeric", hour: "numeric", minute: "2-digit", timeZone,
+        }).format(date),
+        dateTime: date.toISOString(),
+    };
+}
+/** Form-specific date copy. The shared admin timestamp helper intentionally slices ISO text
+ * and its relative helper is English-only; these two events need the operator's locale and
+ * browser time zone. Absolute dates remain accurate while the list stays open without a timer.
+ *
+ * Owner 2026-10-05: line 1 created, line 2 updated, each a compact short date + time with no event
+ * word; one line when updated shows the same date and minute as created. The comparison is on the
+ * displayed short text, so edits within the same minute collapse and the rule follows the locale's
+ * own precision. Intl picks the date order — never a hand-built "M/D/YY".
+ *
+ * @complexity O(1) time and space — two dates, fixed-size formatting.
+ */
+export function formDatesLines({ form, locale, t }, options = {}) {
+    const created = formDateDisplay({ iso: form.createdAt, locale }, options);
+    const updated = formDateDisplay({ iso: form.updatedAt, locale }, options);
+    if (created.text === updated.text) {
+        const label = t("Created {created} · Updated {updated}")
+            .replace("{created}", created.full)
+            .replace("{updated}", updated.full);
+        return [{ kind: "both", text: created.text, dateTime: created.dateTime, label }];
+    }
+    return [
+        { kind: "created", text: created.text, dateTime: created.dateTime, label: t("Created {date}").replace("{date}", created.full) },
+        { kind: "updated", text: updated.text, dateTime: updated.dateTime, label: t("Updated {date}").replace("{date}", updated.full) },
+    ];
+}
+export const KEYS = {
+    list: ["forms", "list"],
+    form: (id) => ["forms", "detail", id],
+    submissionsList: (formId) => ["form-submissions", "list", formId],
+    submissionDetail: (formId, submissionId) => [
+        "form-submissions",
+        "detail",
+        formId,
+        submissionId,
+    ],
+};
+/**
+ * `useFormEditor`'s error banner, extracted out of that hook (`refactor/fetch-query` complexity
+ * pass, 2026-08-12 — same reason `collections/rules.ts`'s `visibleEntryEditorError` was extracted:
+ * the hook's own precedence chain over four sources pushed it past the complexity ceiling).
+ *
+ * Precedence: an active write's own failure (update/create/status, in that order — mirrors
+ * `redirects/rules.ts`'s `firstWriteError` array-order precedence, since `update`/`status` can both
+ * apply to the SAME loaded form) always wins. The list-load failure only surfaces before the form
+ * has ever loaded — once `hasForm` is true, a later BACKGROUND refresh failure must not blank an
+ * editor the operator is actively using (same "a later failure must not erase what already
+ * rendered" guard `FormEditor.tsx`'s own file header already documents at the render layer; this is
+ * its data-layer half).
+ *
+ * @complexity Time/space: O(1) — four fixed checks, no iteration.
+ */
+export function visibleFormEditorError(params, _optional = {}) {
+    // Two distinct fallback strings, matching the pre-migration `handleSave`/`handleStatusToggle`
+    // catch blocks verbatim ("save failed" vs "status update failed") — not one shared string.
+    if (params.updateError)
+        return describeApiError(params.updateError, params.saveFallback);
+    if (params.createError)
+        return describeApiError(params.createError, params.saveFallback);
+    if (params.statusError)
+        return describeApiError(params.statusError, params.statusUpdateFallback);
+    if (params.hasForm)
+        return null;
+    return params.listError ? describeApiError(params.listError, params.loadFormFallback) : null;
+}
+/**
+ * `useFormsList`'s error banner: the row-toggle write's own failure outranks a background
+ * list-refresh failure, same precedence `redirects/rules.ts`'s `visibleRedirectsError` documents.
+ * Two sources only (not the three-plus that pushed `visibleFormEditorError`/`visibleTaxonomyError`
+ * out to `rules.ts`), kept here anyway rather than inlined so the hook body doesn't grow a nested
+ * ternary chain (`@jini-ai/ui/fetch-query`'s `resolveFetchQueryStatus` doc explains why a flat
+ * extraction beats a nested ternary of the same branch count for the complexity gate).
+ *
+ * @complexity Time/space: O(1) — two fixed checks, no iteration.
+ */
+export function formsListError(params, _optional = {}) {
+    // The delete's own failure outranks both the toggle's and a background list-refresh failure —
+    // same precedence tier `use-posts.hooks.ts`'s `removePost` gives its own delete, and a 404
+    // "already gone" resolves to `message: null` here so it never reaches this banner at all (see
+    // `describeTrashError`'s own doc for why).
+    const deleteMessage = describeTrashError({ error: params.deleteError, fallback: params.deleteFallback, versionChangedMessage: params.versionChangedMessage }).message;
+    if (deleteMessage)
+        return deleteMessage;
+    if (params.toggleError)
+        return describeApiError(params.toggleError, params.statusUpdateFallback);
+    if (params.hasForms)
+        return null;
+    return params.listError ? describeApiError(params.listError, params.loadFormsFallback) : null;
+}
+/**
+ * Classifies a failed `api.trash` call — shared by `useFormsList`'s `removeForm` (forms) and
+ * `useFormSubmissionDetail`'s `confirmDelete` (submissions), since both routes now go through the
+ * same generic `POST /trash/items` (`routes/trash/items.ts`) and its 404/409 contract:
+ *
+ * - 404 (`NOT_FOUND`/`FORMS_SUBMISSION_NOT_FOUND`/…): the row is already gone — another tab,
+ *   another operator, or a prior click that actually succeeded before a flaky response read as a
+ *   failure. `alreadyGone: true`, `message: null` — the caller's job is a quiet list refresh, not
+ *   an error banner blaming the operator for something that already happened.
+ * - 409 `TRASH_VERSION_CHANGED`: the row changed under the operator since this screen last read
+ *   it. Specific reload-and-retry copy, not the generic fallback.
+ * - Anything else (network failure, an unrelated `ApiError`, …): falls through to
+ *   `describeApiError`'s generic fallback message.
+ *
+ * @complexity O(1) — one `instanceof` check plus two fixed comparisons.
+ */
+export function describeTrashError({ error: e, fallback, versionChangedMessage }, _optional = {}) {
+    if (!e)
+        return { alreadyGone: false, message: null };
+    if (e instanceof ApiError || ("status" in e && typeof e.status === "number")) {
+        // Existing host transports may retain their own ApiError constructor; status/code are wire fields.
+        if (e.status === 404)
+            return { alreadyGone: true, message: null };
+        if ("code" in e && e.code === "TRASH_VERSION_CHANGED") {
+            return { alreadyGone: false, message: versionChangedMessage };
+        }
+    }
+    return { alreadyGone: false, message: describeApiError(e, fallback) };
+}
+/**
+ * The row-action menu for one form. `RowMenu` has no per-item `disabled` — the in-flight guard lives
+ * in `use-forms-list.hooks.ts`'s own `toggleStatus` (a no-op while `rowSavingId` is already set), the
+ * same shape `use-redirects.hooks.ts`'s `onToggleStatus` uses for its identical `if (saving) return;`
+ * guard. (CORRECTED 2026-09-05: this comment previously said the guard "stays in the caller's
+ * `onToggleStatus` closure (`FormsList.tsx`'s own `if (rowSavingId) return;`)" and claimed that was
+ * the same shape `Redirects.tsx` uses — false; `Redirects.tsx` never had such a guard inline, only its
+ * hook does. Flagged by the 2026-09-05 Gemini admin-tooling audit as a standing no-logic-in-`.tsx`
+ * violation; moving the guard into the hook also fixed the comment's own false precedent claim.)
+ *
+ * @complexity Time/space: O(1) — three fixed entries, no iteration.
+ */
+export function formRowMenuItems({ form, handlers, t }, _optional = {}) {
+    return [
+        // Slug, not id — the admin URL reads `/admin/forms/<slug>` (ui-fixes-backlog.md #8); the GET
+        // route still resolves an id too, so this is not a behavior change for any existing bookmark.
+        { key: "edit", label: t("Edit"), onSelect: () => handlers.onEdit(form) },
+        {
+            key: "toggle-status",
+            label: form.status === "active" ? t("Disable") : t("Enable"),
+            tone: form.status === "active" ? "warning" : "default",
+            onSelect: () => handlers.onToggleStatus(form),
+        },
+        // Opens `FormsList.tsx`'s `ConfirmDialog` — no network call from this selection itself, same
+        // "a click alone can never delete" contract `use-form-submission-detail.hooks.ts`'s
+        // `requestDelete` already documents for the sibling submission-delete flow.
+        { key: "delete", label: t("Delete"), tone: "danger", onSelect: () => handlers.onDelete(form) },
+    ];
+}
+export const FIELD_TYPES = ["text", "email", "textarea", "checkbox"];
+/** The two tab-panel views on an existing form's editor (`formId !== "new"`). */
+export const FORM_TABS = [
+    { id: "fields", label: "Fields" },
+    { id: "submissions", label: "Submissions" },
+];
+/**
+ * Roving-tabindex arrow-key step for the Fields/Submissions tablist — ArrowLeft/ArrowRight cycle
+ * between the two tabs, Home/End jump to the first/last.
+ *
+ * @complexity O(1) — `FORM_TABS` is a fixed 2-item array.
+ */
+export function nextTabIndex({ key, currentIndex }, _optional = {}) {
+    if (key === "ArrowRight")
+        return (currentIndex + 1) % FORM_TABS.length;
+    if (key === "ArrowLeft")
+        return (currentIndex - 1 + FORM_TABS.length) % FORM_TABS.length;
+    if (key === "Home")
+        return 0;
+    if (key === "End")
+        return FORM_TABS.length - 1;
+    return null;
+}
+export function blankField(_required = {}, _optional = {}) {
+    return { id: "", label: "", type: "text", required: false };
+}
+/** Shared "what do we call this field in a title/label" fallback — a blank draft field has neither
+ *  a label nor an id yet, so both the kebab's `aria-label` and the modal's own `<h2>` need the same
+ *  `label -> id -> "Field N"` chain rather than risking the two drifting apart. */
+export function fieldDisplayName({ field, index }, _optional = {}) {
+    return field.label || field.id || `Field ${index + 1}`;
+}
+/** @complexity O(n) in `fields.length`. */
+export function updateFormField({ fields, index, patch }, _optional = {}) {
+    return fields.map((f, i) => (i === index ? { ...f, ...patch } : f));
+}
+/** @complexity O(n) in `fields.length`. */
+export function addFormField({ fields }, _optional = {}) {
+    return [...fields, blankField()];
+}
+/** @complexity O(n) in `fields.length`. */
+export function removeFormField({ fields, index }, _optional = {}) {
+    return fields.filter((_, i) => i !== index);
+}
+/** The already-persisted field ids on a form — `FormFieldsEditor` disables the id input and the
+ *  Remove button for these (a saved field's id cannot be changed or removed once created). `null`
+ *  (form not loaded yet, or the "new form" case) has no existing ids. */
+export function existingFieldIdsOf({ form }, _optional = {}) {
+    return form ? form.fields.map((f) => f.id) : [];
+}
+// ---------------------------------------------------------------------------
+// Field attributes modal (per-field CSS classes + HTML attributes)
+// ---------------------------------------------------------------------------
+/** Mirrors `forms.ts`'s `ATTRIBUTE_NAME_PATTERN` exactly — see `FormEditor.tsx`'s own header
+ *  comment for why this is a fast-reject-only duplicate, not the authoritative check. Keep in sync
+ *  by hand if the server allowlist changes. */
+export const ATTRIBUTE_NAME_PATTERN = /^(aria-[a-z0-9-]+|data-[a-z0-9-]+|placeholder|autocomplete|inputmode|pattern|title|min|max|step|minlength|spellcheck|readonly)$/;
+/** Same bounds as `forms.ts`'s `MAX_CLASS_NAME_LENGTH`/`MAX_ATTRIBUTES_PER_FIELD` — client-side
+ *  early-reject only, not enforcement (see `ATTRIBUTE_NAME_PATTERN` above). */
+export const MAX_CLASS_NAME_LENGTH = 300;
+export const MAX_ATTRIBUTES_PER_FIELD = 12;
+/** A handful of the allowlisted names as real, pickable suggestions (the modal's own "here's what
+ *  you can do" surface — an operator has no other way to discover the allowlist) rather than every
+ *  one: `aria-*`/`data-*` are open namespaces, so `aria-label`/`data-testid` stand in for the whole
+ *  prefix family instead of listing every field-specific `aria-*` name that doesn't exist yet. */
+export const ATTRIBUTE_NAME_SUGGESTIONS = [
+    "aria-label",
+    "aria-describedby",
+    "data-testid",
+    "placeholder",
+    "autocomplete",
+    "inputmode",
+    "pattern",
+    "title",
+    "min",
+    "max",
+    "step",
+    "minlength",
+    "spellcheck",
+    "readonly",
+];
+/** Local-only row key for the modal's attribute list, so React can key a row before it has a
+ *  stable identity — same `_rowId`/module-counter pattern `collections/rules.ts`'s
+ *  `EditFieldsDialog` support uses for its own draft field rows. */
+let nextAttrRowId = 0;
+export function attrRowsFromField({ field }, _optional = {}) {
+    return Object.entries(field.attributes ?? {}).map(([name, value]) => ({ _rowId: nextAttrRowId++, name, value }));
+}
+/** @complexity O(n) in `rows.length`. */
+export function updateAttrRow({ rows, rowId, patch }, _optional = {}) {
+    return rows.map((r) => (r._rowId === rowId ? { ...r, ...patch } : r));
+}
+/** @complexity O(n) in `rows.length`. */
+export function removeAttrRow({ rows, rowId }, _optional = {}) {
+    return rows.filter((r) => r._rowId !== rowId);
+}
+/** @complexity O(n) in `rows.length`. */
+export function addAttrRow({ rows }, _optional = {}) {
+    return [...rows, { _rowId: nextAttrRowId++, name: "", value: "" }];
+}
+/**
+ * Validates + shapes `FieldAttributesDialog`'s draft into the `Partial<AdminFormField>` patch
+ * `onSave` applies: a class-name length cap, then every named attribute row against the allowlist
+ * (blank names are silently skipped — an empty trailing row is not an error), then a total-count
+ * cap on the surviving attributes. The security-relevant check is server-side (`forms.ts`'s
+ * `validateFieldDescriptors`); this is the fast, pre-save rejection only — see this feature's own
+ * `ATTRIBUTE_NAME_PATTERN` doc.
+ *
+ * @complexity O(n) in `rows.length`, short-circuiting on the first disallowed name.
+ */
+export function buildFieldAttributesPatch(draft, _optional = {}) {
+    const trimmedClassName = draft.className.trim();
+    if (trimmedClassName.length > MAX_CLASS_NAME_LENGTH) {
+        return { ok: false, error: `CSS classes must be at most ${MAX_CLASS_NAME_LENGTH} characters.` };
+    }
+    const attributes = {};
+    for (const row of draft.rows) {
+        const name = row.name.trim();
+        if (!name)
+            continue;
+        if (!ATTRIBUTE_NAME_PATTERN.test(name)) {
+            return { ok: false, error: `Attribute "${name}" isn't allowed. Use aria-*, data-*, or one of the suggested names.` };
+        }
+        attributes[name] = row.value;
+    }
+    if (Object.keys(attributes).length > MAX_ATTRIBUTES_PER_FIELD) {
+        return { ok: false, error: `At most ${MAX_ATTRIBUTES_PER_FIELD} attributes are allowed per field.` };
+    }
+    return {
+        ok: true,
+        patch: {
+            className: trimmedClassName || undefined,
+            attributes: Object.keys(attributes).length > 0 ? attributes : undefined,
+        },
+    };
+}
+//# sourceMappingURL=rules.js.map

package/dist/media/react/hooks/EditMediaPanel.hooks.js

@@ -1,5 +1,5 @@
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { useController } from '../../../react/use-controller.js';
+import { useController } from '../../../core/react/use-controller.js';
 import { createEditMediaController } from '../../controllers/edit-media.controller.js';
 import { canReplaceMedia, mediaEmbedSnippet, parseOptionalPixelSize, safeMediaUrl } from '../../rules.js';
 import { parseMediaHtmlAttributes, describeMediaHtmlAttributeError } from '../../html-attributes.js';

package/dist/media/react/hooks/LibraryTab.hooks.d.ts

@@ -1,4 +1,4 @@
-import type { TabViewProps } from '../../../react/bind-react.js';
+import type { TabViewProps } from '../../../core/react/bind-react.js';
 import { createLibraryController } from '../../controllers/library.controller.js';
 import type { MediaAsset } from '../../models.js';
 export declare function useLibraryTab({ params, permissions }: TabViewProps, _optional?: Record<string, never>): {
@@ -67,8 +67,6 @@ export declare function useLibraryTab({ params, permissions }: TabViewProps, _op
     onOrder: ({ value }: {
         value: string;
     }) => void;
-    onOrderCreated: () => void;
-    onOrderAlphabetical: () => void;
     search: string;
     loading: boolean;
     busy: boolean;

package/dist/media/react/hooks/LibraryTab.hooks.js

@@ -1,5 +1,5 @@
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { useController } from '../../../react/use-controller.js';
+import { useController } from '../../../core/react/use-controller.js';
 import { createLibraryController } from '../../controllers/library.controller.js';
 import { useSharedMediaLibrary } from './MediaPage.hooks.js';
 import { useMediaPorts } from './MediaPorts.hooks.js';
@@ -51,7 +51,7 @@ export function useLibraryTab({ params, permissions = [] }, _optional = {}) {
     // Lightbox — an index into the list, not the item itself, so arrow-key/navigation
     // buttons move the number without re-deriving "what's next" from an item reference.
     const [lightboxIndex, setLightboxIndex] = useState(null);
-    const items = snapshot?.items ?? [];
+    const items = snapshot?.items ?? [], pendingIds = snapshot?.pendingIds ?? [];
     const canUpload = permissions.includes('media.upload');
     const canEdit = permissions.includes('media.update');
     const canTrash = permissions.includes('media.trash');
@@ -59,7 +59,7 @@ export function useLibraryTab({ params, permissions = [] }, _optional = {}) {
     const canPurge = permissions.includes('media.delete.force');
     const actions = items.map((item, index) => ({
         item,
-        busy: snapshot?.pendingIds.includes(item.id) ?? false,
+        busy: pendingIds.includes(item.id),
         ...(canEdit ? { onEdit: () => setEditing(item) } : {}),
         onPreview: () => setLightboxIndex(index),
         ...(canTrash
@@ -123,16 +123,6 @@ export function useLibraryTab({ params, permissions = [] }, _optional = {}) {
         onOrder: ({ value }) => {
             void controller?.setQuery({ query: { ...controller.getSnapshot().query, orderBy: value === 'alphabetical' ? 'alphabetical' : 'created' } });
         },
-        onOrderCreated: () => {
-            void controller?.setQuery({
-                query: { ...controller.getSnapshot().query, orderBy: 'created' },
-            });
-        },
-        onOrderAlphabetical: () => {
-            void controller?.setQuery({
-                query: { ...controller.getSnapshot().query, orderBy: 'alphabetical' },
-            });
-        },
         search: snapshot?.query.search ?? '',
         loading: !snapshot || (snapshot.items === null && snapshot.loading && !snapshot.error),
         busy: snapshot?.busy ?? false,
@@ -147,13 +137,14 @@ export function useLibraryTab({ params, permissions = [] }, _optional = {}) {
         },
         cancelPurge: () => controller?.cancelPurge(),
         confirmPurge: () => {
-            if (!canPurge || !controller)
+            const item = controller?.getSnapshot().pendingPurge;
+            // The controller refuses to purge without a pending item, so there is nothing to announce.
+            if (!canPurge || !controller || !item)
                 return;
-            const item = controller.getSnapshot().pendingPurge;
-            const index = items.findIndex(row => row.id === item?.id);
+            const index = items.findIndex(row => row.id === item.id);
             return controller.confirmPurge({ confirmed: true }).then(saved => {
                 if (saved) {
-                    setSuccess(item ? `Deleted permanently ${item.title}` : 'Deleted permanently');
+                    setSuccess(`Deleted permanently ${item.title}`);
                     setFocusAfterPurge(Math.max(0, index));
                 }
             });

package/dist/media/react/hooks/MediaCard.hooks.js

@@ -1,24 +1,11 @@
 import { useState } from 'react';
 import { safeMediaUrl, formatByteSize, formatUploadDate, mediaRowHandles } from '../../rules.js';
 export function useMediaCard(props, _optional = {}) {
-    /** Historical preview rationale, retained with the ported fallback chain:
-   * The hard problem this rewrite had to solve: **the media list response carried no content type**
-   * (neither `media` nor `asset_blobs` stored one — upload validated `contentType` then discarded
-   * it), so nothing in `AdminMedia` told the client whether a given asset was an image, a video, or
-   * something unpreviewable. `MediaPreview` below resolves this client-side with an optimistic
-   * render-and-fall-back chain (`<img>` → onError → `<video>` → onError → placeholder) rather than a
-   * HEAD probe per card. Chosen over the HEAD approach because: (1) the byte route's documented
-   * contract covers GET — sniffing/Range were specified for that, not for HEAD, so building on HEAD
-   * would be assuming a behavior nobody confirmed; (2) a HEAD-first design means every card blocks on
-   * a round trip before any pixel paints, working against the fixed-aspect-box + lazy-loading this
-   * grid needs anyway, whereas the optimistic path costs nothing extra for the common case (a real
-   * image just loads) and only "wastes" a request for the video/unsupported minority — and even then,
-   * a browser's image decoder typically fails off the header bytes rather than pulling the whole
-   * file; (3) it composes for free with the server's security defusal: a sniffed HTML/SVG comes back
-   * as `application/octet-stream` with `Content-Disposition: attachment`, which is not a valid image
-   * OR video MIME, so it fails both probes and lands on the placeholder with zero special-casing —
-   * this file never needs to detect "is this the defused case" itself.
-     */
+    /** Preview optimistically: image -> video -> placeholder. The list supplies no reliable media
+     * kind, and the byte route guarantees GET rather than HEAD, so probing headers would assume an
+     * unsupported contract and delay every card's first paint. Images load directly; failed decoders
+     * usually stop at header bytes. Defused HTML/SVG served as octet-stream attachments fails both
+     * decoders and reaches the placeholder without content-specific handling. */
     const src = safeMediaUrl({ url: props.api.originalUrl({ id: props.item.id, version: props.item.version }) });
     const [probe, setProbe] = useState({ src, stage: 'image' });
     // New bytes can change media type under the same id. Retry the fallback from image
@@ -45,8 +32,7 @@ export function useMediaCard(props, _optional = {}) {
         menuItems: [
             ...(props.onEdit ? [{ id: 'edit', label: 'Edit metadata', onPress: props.onEdit, disabled: props.busy === true }] : []),
             ...(props.onTrash && props.item.status !== 'trashed' ? [{ id: 'trash', label: 'Trash', onPress: props.onTrash, disabled: props.busy === true }] : []),
-            // Restore is owner-requested beyond legacy; it lives only in a trashed card's menu, so
-            // the card itself keeps the legacy look and active cards' menus stay legacy-identical.
+            // Restore belongs only in a trashed card's menu; active cards have nothing to restore.
             ...(props.onRestore && props.item.status === 'trashed' ? [{ id: 'restore', label: 'Restore', onPress: props.onRestore, disabled: props.busy === true }] : []),
             ...(props.onPurge && props.item.status === 'trashed' ? [{ id: 'purge', label: 'Delete permanently', attrs: { 'data-jini-variant': 'danger' }, onPress: props.onPurge, disabled: props.busy === true }] : []),
         ],

package/dist/media/react/hooks/MediaGrid.hooks.d.ts

@@ -11,13 +11,13 @@ export declare function useMediaGrid(props: MediaGridProps, _optional?: Record<s
     actions: {
         handleBase: string;
         busy?: boolean;
-        item: import("../../models.js").MediaAsset;
+        onPurge?: () => void;
         locale?: string;
+        item: import("../../models.js").MediaAsset;
         onEdit?: () => void;
         onPreview?: () => void;
         onTrash?: () => void;
         onRestore?: () => void;
-        onPurge?: () => void;
         onChoose?: () => void;
     }[];
     gridRef?: Ref<HTMLDivElement>;

package/dist/media/react/hooks/MediaPage.hooks.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { ModulePageProps } from '../../../react/bind-react.js';
+import type { ModulePageProps } from '../../../core/react/bind-react.js';
 import { createLibraryController } from '../../controllers/library.controller.js';
 import type { LibraryState } from '../../controllers/library.controller.js';
 export declare const MediaLibraryContext: import("react").Context<{

package/dist/media/react/hooks/MediaPage.hooks.js

@@ -1,5 +1,5 @@
 import { createElement, createContext, useContext, useEffect, useState } from 'react';
-import { useController } from '../../../react/use-controller.js';
+import { useController } from '../../../core/react/use-controller.js';
 import { createLibraryController } from '../../controllers/library.controller.js';
 import { useMediaPorts } from './MediaPorts.hooks.js';
 import { AllIcon, ImageIcon, VideoIcon, CloudIcon } from '../components/MediaIcons.js';

package/dist/media/react/hooks/MediaPicker.hooks.js

@@ -1,4 +1,4 @@
-import { useController } from '../../../react/use-controller.js';
+import { useController } from '../../../core/react/use-controller.js';
 import { createLibraryController } from '../../controllers/library.controller.js';
 import { acceptsMedia } from '../../rules.js';
 export function useMediaPicker(props, _optional = {}) {

package/dist/media/react/hooks/ProvidersTab.hooks.js

@@ -48,7 +48,11 @@ export function useProvidersTab(_required = {}, _optional = {}) {
                 }
                 // Older hosts retain the one-button editor; writes remain sequential and failures
                 // retain local edits. Atomic whole-set hosts should implement saveChanges instead.
-                for (const item of lastRead) {
+                // Submitted ids the last read never returned (catalog-only providers getting their
+                // first key or settings) start from an empty stored state, or their writes are lost.
+                const known = new Set(lastRead.map(item => item.id));
+                const unread = Object.keys(providers).filter(id => !known.has(id)).map(id => ({ id, configured: false }));
+                for (const item of [...lastRead, ...unread]) {
                     const entry = providers[item.id];
                     if (!entry) {
                         if (item.configured || item.baseUrl || item.model)

package/dist/media/react/hooks/UploadButton.hooks.d.ts

@@ -14,10 +14,17 @@ export interface UploadButtonProps {
 /** Reads a browser File at the React boundary; headless controllers only receive bytes. */
 export declare function readMediaFile({ file }: {
     file: File;
-}, { signal }?: {
+}, { signal, createReader }?: {
     signal?: AbortSignal;
+    createReader?: () => FileReader;
 }): Promise<UploadInput>;
-export declare function useUploadButton(props: UploadButtonProps, _optional?: Record<string, never>): {
+export declare function useUploadButton(props: UploadButtonProps, { readFile }?: {
+    readFile?: (required: {
+        file: File;
+    }, optional?: {
+        signal?: AbortSignal;
+    }) => Promise<UploadInput>;
+}): {
     alt: string;
     withAlt: boolean;
     multiple: boolean;

package/dist/media/react/hooks/UploadButton.hooks.js

@@ -1,9 +1,9 @@
 import { useEffect, useRef, useState } from 'react';
 /** Reads a browser File at the React boundary; headless controllers only receive bytes. */
-export function readMediaFile({ file }, { signal } = {}) {
+export function readMediaFile({ file }, { signal, createReader = () => new FileReader() } = {}) {
     return new Promise((resolve, reject) => {
         signal?.throwIfAborted();
-        const reader = new FileReader();
+        const reader = createReader();
         const abort = () => {
             reader.abort();
             reject(new Error('File read aborted'));
@@ -26,13 +26,15 @@ export function readMediaFile({ file }, { signal } = {}) {
         reader.readAsDataURL(file);
     });
 }
-export function useUploadButton(props, _optional = {}) {
+export function useUploadButton(props, { readFile = readMediaFile } = {}) {
     // Advisory picker formats mirror the host's standard ceiling, including video. The
     // injected server still validates/sniffs bytes; a file picker is never a security boundary.
     const inputRef = useRef(null);
     const [selectedFiles, setSelectedFiles] = useState([]);
     const [alt, setAlt] = useState(''), [busy, setBusy] = useState(false), [error, setError] = useState(null), [success, setSuccess] = useState(null);
-    const inFlight = useRef(false), lifetime = useRef(null);
+    // The mount effect swaps in a fresh controller (StrictMode replays it), so handlers,
+    // which only run after mount, always read a live signal.
+    const inFlight = useRef(false), lifetime = useRef(new AbortController());
     useEffect(() => {
         const abort = new AbortController();
         lifetime.current = abort;
@@ -48,7 +50,7 @@ export function useUploadButton(props, _optional = {}) {
     async function uploadFiles(files) {
         if (!files.length || inFlight.current || props.disabled)
             return;
-        const signal = lifetime.current?.signal;
+        const signal = lifetime.current.signal;
         inFlight.current = true;
         setBusy(true);
         setError(null);
@@ -57,12 +59,12 @@ export function useUploadButton(props, _optional = {}) {
         let remaining = [...files];
         try {
             for (const file of files) {
-                const input = await readMediaFile({ file }, signal ? { signal } : {});
-                if (signal?.aborted)
+                const input = await readFile({ file }, { signal });
+                if (signal.aborted)
                     return;
                 if (!await props.upload({ input, ...(alt.trim() ? { alt: alt.trim() } : {}) }))
                     throw new Error(`Upload failed for ${file.name}`);
-                if (signal?.aborted)
+                if (signal.aborted)
                     return;
                 uploaded.push(file.name);
                 remaining = remaining.slice(1);
@@ -72,12 +74,12 @@ export function useUploadButton(props, _optional = {}) {
                 inputRef.current.value = '';
         }
         catch (error) {
-            if (!signal?.aborted)
+            if (!signal.aborted)
                 setError(error instanceof Error ? error.message : 'Upload failed');
         }
         finally {
             inFlight.current = false;
-            if (!signal?.aborted) {
+            if (!signal.aborted) {
                 // Keep only failed/unattempted files: retry must not duplicate successes in a batch.
                 setSelectedFiles(remaining);
                 setBusy(false);

package/dist/media/react/index.js

@@ -1,5 +1,5 @@
 import { createElement } from 'react';
-import { bindReact } from '../../react/bind-react.js';
+import { bindReact } from '../../core/react/bind-react.js';
 import { mediaModule } from '../media.module.js';
 import { MediaPortsContext } from './hooks/MediaPorts.hooks.js';
 export { useMediaPorts } from './hooks/MediaPorts.hooks.js';

package/dist/media/react/tabs/LibraryTab.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 LibraryTab(props: TabViewProps, _optional?: Record<string, never>): import("react").JSX.Element;
 export default LibraryTab;
 //# sourceMappingURL=LibraryTab.d.ts.map

package/dist/media/react/tabs/ProvidersTab.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 ProvidersTab(_props: TabViewProps, _optional?: Record<string, never>): import("react").JSX.Element;
 export default ProvidersTab;
 //# sourceMappingURL=ProvidersTab.d.ts.map

package/dist/playground/react/components/Canvas.d.ts

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