@jini-ai/admin 0.4.5 → 0.4.6

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

@@ -1,12 +1,16 @@
+import { useEffect } from 'react';
+import { useMediaLibraryQuery } from './MediaQuery.hooks.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 = {}) {
-    const { controller, snapshot } = useController({ create: () => createLibraryController({ api: props.api }), dependencies: [props.api] }, {
+    const cached = useMediaLibraryQuery({ api: props.api });
+    const { controller, snapshot } = useController({ create: () => createLibraryController({ api: cached.api }), dependencies: [cached.api] }, {
         start: ({ controller }) => {
             void controller.load();
         },
     });
+    useEffect(() => { controller?.settleLibrary({ ...(cached.query.data ? { all: cached.query.data } : {}), error: cached.query.error }); }, [controller, cached.query.data, cached.query.error]);
     const actions = (snapshot?.items ?? [])
         .filter((item) => item.status === 'active' && acceptsMedia({ item, accept: props.accept }))
         .map((item) => ({ item, onChoose: () => props.onChoose(item) }));

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

@@ -0,0 +1,27 @@
+import type { MediaApiPort, MediaProvidersPort } from '../../ports.js';
+export declare const MEDIA_QUERY_KEYS: {
+    root: readonly ["media"];
+    library: readonly ["media", "library"];
+    providers: readonly ["media-providers"];
+};
+/** Full-library cache stays separate from the controller's local filtering/counts. Writes
+ * invalidate all mounted views, while controller locks retain the accepted-write ordering. */
+export declare function useMediaLibraryQuery({ api }: {
+    api: MediaApiPort;
+}, { enabled }?: {
+    enabled?: boolean;
+}): {
+    api: MediaApiPort;
+    query: import("@jini-ai/ui").QueryResult<readonly import("../../models.js").MediaAsset[]>;
+};
+/** null is an unavailable service, never a successful empty catalogue. The shared cache
+ * stores only public credential markers returned by the host, never the submitted key text. */
+export declare function useMediaProvidersQuery({ port }: {
+    port: MediaProvidersPort | undefined;
+}, { enabled }?: {
+    enabled?: boolean;
+}): {
+    query: import("@jini-ai/ui").QueryResult<readonly import("../../models.js").MediaProvider[]>;
+    loader: import("@jini-ai/ui").CachedLoader<readonly import("../../models.js").MediaProvider[]>;
+};
+//# sourceMappingURL=MediaQuery.hooks.d.ts.map

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

@@ -0,0 +1,41 @@
+import { useCallback, useMemo, useRef } from 'react';
+import { useCachedLoader, useFetchMutation, useFetchQuery } from '@jini-ai/ui/fetch-query';
+export const MEDIA_QUERY_KEYS = { root: ['media'], library: ['media', 'library'], providers: ['media-providers'] };
+/** Full-library cache stays separate from the controller's local filtering/counts. Writes
+ * invalidate all mounted views, while controller locks retain the accepted-write ordering. */
+export function useMediaLibraryQuery({ api }, { enabled = true } = {}) {
+    const fetch = useCallback(() => api.list({}), [api]);
+    const query = useFetchQuery({ key: MEDIA_QUERY_KEYS.library, fetch }, { enabled });
+    const loader = useCachedLoader({ key: MEDIA_QUERY_KEYS.library, fetch }, { staleTime: 0 });
+    const uploadMutation = useFetchMutation({ run: ({ input }) => api.upload(...input) }, { invalidates: [MEDIA_QUERY_KEYS.root] });
+    const trashMutation = useFetchMutation({ run: ({ input }) => api.trash(...input) }, { invalidates: [MEDIA_QUERY_KEYS.root] });
+    const deleteMutation = useFetchMutation({ run: ({ input }) => api.delete(...input) }, { invalidates: [MEDIA_QUERY_KEYS.root] });
+    const updateMutation = useFetchMutation({ run: ({ input }) => api.update(...input) }, { invalidates: [MEDIA_QUERY_KEYS.root] });
+    const restoreMutation = useFetchMutation({ run: ({ input }) => api.restore(...input) }, { invalidates: [MEDIA_QUERY_KEYS.root] });
+    const replaceMutation = useFetchMutation({ run: ({ input }) => api.replace(...input) }, { invalidates: [MEDIA_QUERY_KEYS.root] });
+    const current = useRef({ loader, uploadMutation, trashMutation, deleteMutation, updateMutation, restoreMutation, replaceMutation });
+    current.current = { loader, uploadMutation, trashMutation, deleteMutation, updateMutation, restoreMutation, replaceMutation };
+    const cachedApi = useMemo(() => ({ ...api, list: () => current.current.loader.load(),
+        upload: (...input) => current.current.uploadMutation.mutate({ input }),
+        trash: (...input) => current.current.trashMutation.mutate({ input }),
+        delete: (...input) => current.current.deleteMutation.mutate({ input }),
+        update: (...input) => current.current.updateMutation.mutate({ input }),
+        ...(api.restore ? { restore: (...input) => current.current.restoreMutation.mutate({ input }) } : {}),
+        ...(api.replace ? { replace: (...input) => current.current.replaceMutation.mutate({ input }) } : {}),
+    }), [api]);
+    return { api: cachedApi, query };
+}
+/** null is an unavailable service, never a successful empty catalogue. The shared cache
+ * stores only public credential markers returned by the host, never the submitted key text. */
+export function useMediaProvidersQuery({ port }, { enabled = true } = {}) {
+    const fetch = useCallback(async () => {
+        const items = await port?.list({});
+        if (!items)
+            throw new Error('Provider service unavailable');
+        return items;
+    }, [port]);
+    const query = useFetchQuery({ key: MEDIA_QUERY_KEYS.providers, fetch }, { enabled: enabled && !!port });
+    const loader = useCachedLoader({ key: MEDIA_QUERY_KEYS.providers, fetch }, { staleTime: 0 });
+    return { query, loader };
+}
+//# sourceMappingURL=MediaQuery.hooks.js.map

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

@@ -1,3 +1,5 @@
+import { useFetchMutation } from '@jini-ai/ui/fetch-query';
+import { MEDIA_QUERY_KEYS, useMediaProvidersQuery } from './MediaQuery.hooks.js';
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { useMediaProvidersTab, sortProvidersByConfigured, isEntryPresent, isMarkerOnlyEntry, maskedKeyLabel, isProviderBaseUrlInvalid, invalidBaseUrlProviderIds } from '@jini-ai/ui';
 import { useMediaPorts } from './MediaPorts.hooks.js';
@@ -10,6 +12,9 @@ function configuration({ items }, _optional = {}) {
 }
 export function useProvidersTab(_required = {}, _optional = {}) {
     const { mediaProviders } = useMediaPorts();
+    const cached = useMediaProvidersQuery({ port: mediaProviders });
+    const reads = useRef(cached.loader);
+    reads.current = cached.loader;
     const [discoveredCatalog, setDiscoveredCatalog] = useState([]);
     const [visibleKeys, setVisibleKeys] = useState(() => new Set());
     const lifetime = useRef(null);
@@ -20,13 +25,13 @@ export function useProvidersTab(_required = {}, _optional = {}) {
     }, [mediaProviders]);
     // Always invoke the hook. An unavailable optional port uses an inert, scoped fallback.
     // Reuse the established editor's send-time serialization, reload merge and clear rollback.
-    const editorPort = useMemo(() => {
+    const rawEditorPort = useMemo(() => {
         let lastRead = [];
         return {
             async fetchMediaProviders() {
                 try {
                     const signal = lifetime.current.signal;
-                    const items = await mediaProviders?.list({}, { signal });
+                    const items = await reads.current.load();
                     if (!items || signal.aborted)
                         return null;
                     lastRead = items;
@@ -75,6 +80,20 @@ export function useProvidersTab(_required = {}, _optional = {}) {
             },
         };
     }, [mediaProviders]);
+    const save = useFetchMutation({ run: async ({ input }) => {
+            const result = await rawEditorPort.saveMediaProviders(input);
+            return result;
+        } }, { invalidates: [MEDIA_QUERY_KEYS.providers] });
+    const saves = useRef(save);
+    saves.current = save;
+    const editorPort = useMemo(() => ({
+        fetchMediaProviders: async () => {
+            // staleTime: 0 on the loader forces a new settled read on explicit reload, while the
+            // initial editor read joins the observer's in-flight request instead of cancelling it.
+            return rawEditorPort.fetchMediaProviders();
+        },
+        saveMediaProviders: (providers) => saves.current.mutate({ input: providers }),
+    }), [rawEditorPort]);
     const editor = useMediaProvidersTab({ port: editorPort });
     const catalog = mediaProviders?.catalog ?? discoveredCatalog;
     const pinnedIds = mediaProviders?.pinnedProviderIds ?? [];

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

@@ -1,3 +1,4 @@
+export { useGallerySelection, type GallerySelectionImage } from './hooks/GallerySelection.hooks.js';
 import type { ReactNode } from 'react';
 import type { OverlayPort } from '../../react/overlays.js';
 import type { MediaApiPort } from '../ports.js';

package/dist/media/react/index.js

@@ -1,3 +1,4 @@
+export { useGallerySelection } from './hooks/GallerySelection.hooks.js';
 import { createElement } from 'react';
 import { bindReact } from '../../core/react/bind-react.js';
 import { mediaModule } from '../media.module.js';

package/dist/react/components/InteractiveHtmlEditor/InteractiveHtmlEditor.js

@@ -70,6 +70,7 @@ export function isProtectedEmbedElement({ el }) {
  */
 const EMBED_KIND_LABELS = {
     media: 'Media',
+    gallery: 'Gallery',
     widget: 'Widget',
     post: 'Post',
     content: 'Content',
@@ -140,6 +141,10 @@ export function describeEmbedPlaceholder({ el }) {
     if (typeof config.type !== 'string' || config.type === '')
         return undefined;
     const type = config.type.toLowerCase();
+    if (type === 'gallery') {
+        const count = Array.isArray(config.images) ? config.images.length : 0;
+        return { kindLabel: EMBED_KIND_LABELS.gallery, identityLabel: count === 0 ? 'no images set' : `${count} ${count === 1 ? 'image' : 'images'}` };
+    }
     return { kindLabel: EMBED_KIND_LABELS[type] ?? titleCase(type), identityLabel: identityLabel(config) };
 }
 export function InteractiveHtmlEditor(props) {

package/dist/react/components/Sidebar.d.ts

@@ -47,6 +47,12 @@ export interface SidebarProps {
      * @default false
      */
     railDefaultCollapsed?: boolean;
+    /** Temporary displayed rail state. A boolean controls it without changing the stored preference;
+     *  null/undefined restores that preference. @example railOverride={dockOpen ? true : null} */
+    railOverride?: boolean | null | undefined;
+    /** Toggle requests while `railOverride` is active. The host updates its override to accept them;
+     *  without a callback the controlled rail stays fixed. Uncontrolled toggles persist as usual. */
+    onRailCollapsedChange?: ((collapsed: boolean) => void) | undefined;
     /** Accessible name for the `<nav>` landmark. @default "Admin" */
     label?: string;
     /** Extra class names appended to `.cms-nav`. */

package/dist/react/components/Sidebar.js

@@ -136,6 +136,7 @@ const sidebarStorage = {
 function SidebarRoot(props) {
     const rail = useSidebarRail({ storage: sidebarStorage, events: window }, {
         storageKey: props.railStorageKey, defaultCollapsed: props.railDefaultCollapsed,
+        railOverride: props.railOverride, onCollapsedChange: props.onRailCollapsedChange,
     });
     const [tooltip, setTooltip] = useState(null);
     const open = props.open ?? false;

package/dist/react/entities/use-entity-edit.d.ts

@@ -18,7 +18,7 @@ export declare function useEntityEdit({ port, ...props }: EntityEditProps & {
     missing: readonly string[];
     invalid: readonly import("./rules.js").DraftFieldProblem[];
     canSave: boolean;
-    pending: "remove" | "save" | null;
+    pending: "save" | "remove" | null;
     failed: boolean;
     setField: ({ name, value }: {
         readonly name: string;

package/dist/react/hooks/use-sidebar-rail.d.ts

@@ -33,13 +33,22 @@ export interface SidebarRail {
  * (expanded), which is what every existing host gets by not passing it. A stored preference always
  * takes precedence — see {@link readPersisted} for why absent and `'0'` must stay distinguishable.
  *
+ * @param railOverride A boolean controls the displayed rail without changing its saved preference.
+ * Null/undefined releases control and reveals the latest preference, including cross-tab updates.
+ * @param onCollapsedChange Receives toggle requests only while an override is active. The host must
+ * update its override to accept the request; without this callback the controlled rail stays fixed.
+ * @returns Displayed collapse state and a toggle (persisted when uncontrolled, requested otherwise).
+ * @example useSidebarRail({ storage, events }, { railOverride: true, onCollapsedChange: setOverride })
+ *
  * @complexity O(1) — one state read/write per toggle, no derived computation.
  */
 export declare function useSidebarRail({ storage, events }: {
     readonly storage: Pick<Storage, 'getItem' | 'setItem'>;
     readonly events: Pick<Window, 'addEventListener' | 'removeEventListener'>;
-}, { storageKey, defaultCollapsed }?: {
+}, { storageKey, defaultCollapsed, railOverride, onCollapsedChange }?: {
     readonly storageKey?: string | undefined;
     readonly defaultCollapsed?: boolean | undefined;
+    readonly railOverride?: boolean | null | undefined;
+    readonly onCollapsedChange?: ((collapsed: boolean) => void) | undefined;
 }): SidebarRail;
 //# sourceMappingURL=use-sidebar-rail.d.ts.map

package/dist/react/hooks/use-sidebar-rail.js

@@ -62,17 +62,30 @@ function writePersisted(storageKey, collapsed, storage) {
  * (expanded), which is what every existing host gets by not passing it. A stored preference always
  * takes precedence — see {@link readPersisted} for why absent and `'0'` must stay distinguishable.
  *
+ * @param railOverride A boolean controls the displayed rail without changing its saved preference.
+ * Null/undefined releases control and reveals the latest preference, including cross-tab updates.
+ * @param onCollapsedChange Receives toggle requests only while an override is active. The host must
+ * update its override to accept the request; without this callback the controlled rail stays fixed.
+ * @returns Displayed collapse state and a toggle (persisted when uncontrolled, requested otherwise).
+ * @example useSidebarRail({ storage, events }, { railOverride: true, onCollapsedChange: setOverride })
+ *
  * @complexity O(1) — one state read/write per toggle, no derived computation.
  */
-export function useSidebarRail({ storage, events }, { storageKey = DEFAULT_SIDEBAR_RAIL_STORAGE_KEY, defaultCollapsed = false } = {}) {
+export function useSidebarRail({ storage, events }, { storageKey = DEFAULT_SIDEBAR_RAIL_STORAGE_KEY, defaultCollapsed = false, railOverride, onCollapsedChange } = {}) {
     const [collapsed, setCollapsed] = useState(() => readPersisted(storageKey, storage) ?? defaultCollapsed);
     const toggle = useCallback(() => {
+        // A temporary host layout choice must not become the operator's saved preference. Request
+        // changes outside the state updater so React's StrictMode replay cannot notify the host twice.
+        if (railOverride != null) {
+            onCollapsedChange?.(!railOverride);
+            return;
+        }
         setCollapsed((current) => {
             const next = !current;
             writePersisted(storageKey, next, storage);
             return next;
         });
-    }, [storageKey, storage]);
+    }, [storageKey, storage, railOverride, onCollapsedChange]);
     /** Cross-tab sync: two admin tabs open side by side should agree on the rail state rather than
      *  silently diverging the moment either one is toggled. */
     useEffect(() => {
@@ -88,6 +101,6 @@ export function useSidebarRail({ storage, events }, { storageKey = DEFAULT_SIDEB
         events.addEventListener('storage', onStorage);
         return () => events.removeEventListener('storage', onStorage);
     }, [storageKey, defaultCollapsed, events]);
-    return { collapsed, toggle };
+    return { collapsed: railOverride ?? collapsed, toggle };
 }
 //# sourceMappingURL=use-sidebar-rail.js.map

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

@@ -21,11 +21,21 @@ export interface SeoSitemapTransportPort {
         signal?: AbortSignal;
     }): Promise<Pick<Response, 'ok' | 'status' | 'headers' | 'text'>>;
 }
+/** Host supplies raw HEAD I/O; no browser globals, auth state or image implementation here. */
+export interface SeoImageTransportPort {
+    head(required: {
+        url: string;
+    }, optional?: {
+        signal?: AbortSignal;
+    }): Promise<Pick<Response, 'status' | 'headers'>>;
+}
 /** Preserves every existing SEO request path and body; basePath is the host workspace path. */
 export declare function createHttpSeoApi({ transport, basePath }: {
     transport: SeoTransportPort;
     basePath: string;
-}, { sitemapTransport }?: {
+}, { sitemapTransport, imageTransport, siteOrigin }?: {
     sitemapTransport?: SeoSitemapTransportPort;
+    imageTransport?: SeoImageTransportPort;
+    siteOrigin?: string | undefined;
 }): AdminSeoPort;
 //# sourceMappingURL=http.d.ts.map

package/dist/seo/adapters/http.js

@@ -1,5 +1,6 @@
+import { resolveMediaRefPreviewUrl } from '../rules.js';
 /** Preserves every existing SEO request path and body; basePath is the host workspace path. */
-export function createHttpSeoApi({ transport, basePath }, { sitemapTransport } = {}) {
+export function createHttpSeoApi({ transport, basePath }, { sitemapTransport, imageTransport, siteOrigin } = {}) {
     const base = basePath.replace(/\/$/, '');
     const entryPath = (entryId) => `${base}/seo/entries/${encodeURIComponent(entryId)}`;
     async function data(path, method, body) {
@@ -20,6 +21,15 @@ export function createHttpSeoApi({ transport, basePath }, { sitemapTransport } =
         listSeoPosts: () => choices('posts'),
         listSeoPages: () => choices('pages'),
         mediaOriginalUrl: ({ id }) => transport.url({ path: `${base}/media/${encodeURIComponent(id)}/original` }),
+        mediaPreviewUrl: ({ value }) => resolveMediaRefPreviewUrl({ value, mediaOriginalUrl: id => transport.url({ path: `${base}/media/${encodeURIComponent(id)}/original` }) }, { siteOrigin }),
+        ...(imageTransport ? { async inspectShareImage({ url }, options = {}) {
+                options.signal?.throwIfAborted();
+                const response = await imageTransport.head({ url }, options);
+                // Number(null) is zero: an omitted header must not accuse a healthy image of being empty.
+                const raw = response.headers.get('content-length');
+                const length = raw === null || raw.trim() === '' ? NaN : Number(raw);
+                return { status: response.status, byteSize: Number.isSafeInteger(length) && length >= 0 ? length : null };
+            } } : {}),
         async fetchSitemapXml(_required, options = {}) {
             if (!sitemapTransport)
                 throw new Error('SEO sitemap transport unavailable');

package/dist/seo/controllers/entry-picker.controller.d.ts

@@ -1,6 +1,8 @@
 import type { AdminSeoPort } from '../ports.js';
 import type { EntryPickerController, SeoTranslator, SeoErrorFormatter } from '../models.js';
 /** Two existing reads, combined posts first then pages; no new content repository. */
+/** @deprecated React entry picking uses the shared query owner in use-entry-picker.hooks.
+ * Retained for headless package consumers until an owner-approved export removal. */
 export declare function createEntryPickerController({ api }: {
     api: AdminSeoPort;
 }, { t, describeError }?: {

package/dist/seo/controllers/entry-picker.controller.js

@@ -1,6 +1,8 @@
 import { createControllerStore } from '../../core/module/controller-store.js';
 import { initialEntryPickerState, describeSeoError } from '../models.js';
 /** Two existing reads, combined posts first then pages; no new content repository. */
+/** @deprecated React entry picking uses the shared query owner in use-entry-picker.hooks.
+ * Retained for headless package consumers until an owner-approved export removal. */
 export function createEntryPickerController({ api }, { t = key => key, describeError = describeSeoError } = {}) {
     const store = createControllerStore({ initial: initialEntryPickerState });
     async function load(_required = {}, _optional = {}) {

package/dist/seo/models.d.ts

@@ -154,6 +154,14 @@ export interface MediaRefFieldController {
     /** The field's current value resolved to a thumbnail `<img src>`, or `null` when the value is
      *  empty or unparseable — see `resolveMediaRefPreviewUrl`'s own doc. */
     previewUrl: string | null;
+    /** Shared diagnostics for defaults, OG and Twitter fields; optional for injected legacy views. */
+    warning?: string | null;
+    onPreviewLoad?: (event: {
+        currentTarget: HTMLImageElement;
+    }) => void;
+    onPreviewError?: (event: {
+        currentTarget: HTMLImageElement;
+    }) => void;
     /** `MediaPickerDialog`'s `accept` — images only: every field this backs is an og:image /
      *  twitter:image, and a crawler cannot use a video there (2026-10-05, same filter the post
      *  featured-image chooser passes). */

package/dist/seo/react/components/MediaRefField.js

@@ -6,7 +6,7 @@ import { useWiredMediaRefField, useMediaRefPresentation, handleSpread } from "..
 export function MediaRefField({ locale, id, name, label, value, onChange, agentHandle: base, useField = useWiredMediaRefField, }, _optional = {}) {
     const t = useSeoCopy();
     const { Picker = MediaPickerBridge, storedReference } = useMediaRefPresentation({ value });
-    const { pickerOpen, openPicker, closePicker, handleSelect, clear, previewUrl, accept } = useField({ value, onChange });
-    return (_jsxs("div", { className: "jini-field jini-media-ref-field", children: [_jsx("label", { className: "jini-field-label", htmlFor: id, children: label }), _jsxs("div", { className: "jini-media-ref-field-row", children: [_jsx("input", { className: "jini-input", id: id, name: storedReference ? undefined : name, value: storedReference ? t({ locale, key: "Selected image" }) : value, readOnly: storedReference, onChange: (e) => onChange(e.target.value), ...(base ? agentHandle({ handle: base }, { role: "field", label }) : {}) }), storedReference && name ? _jsx("input", { type: "hidden", name: name, value: value }) : null, _jsx("button", { type: "button", className: "jini-btn jini-btn-secondary", onClick: openPicker, ...handleSpread({ ...(base === undefined ? {} : { base }), suffix: "choose", label: `Choose an image for: ${label}` }), children: t({ locale: locale, key: "Choose image" }) }), value ? (_jsx("button", { type: "button", className: "jini-btn jini-btn-secondary", onClick: clear, ...handleSpread({ ...(base === undefined ? {} : { base }), suffix: "clear", label: `Remove the selected image for: ${label}` }), children: t({ locale: locale, key: "Remove" }) })) : null] }), previewUrl ? _jsx("img", { className: "jini-media-ref-field-preview", src: previewUrl, alt: `${label} preview` }) : null, pickerOpen ? (_jsx(Picker, { onSelect: handleSelect, onCancel: closePicker, accept: accept, agentHandle: base ? `${base}-dialog` : undefined })) : null] }));
+    const { pickerOpen, openPicker, closePicker, handleSelect, clear, previewUrl, accept, warning, onPreviewLoad, onPreviewError } = useField({ value, onChange });
+    return (_jsxs("div", { className: "jini-field jini-media-ref-field", children: [_jsx("label", { className: "jini-field-label", htmlFor: id, children: label }), _jsxs("div", { className: "jini-media-ref-field-row", children: [_jsx("input", { className: "jini-input", id: id, name: storedReference ? undefined : name, value: storedReference ? t({ locale, key: "Selected image" }) : value, readOnly: storedReference, "aria-describedby": warning ? `${id}-warning` : undefined, onChange: (e) => onChange(e.target.value), ...(base ? agentHandle({ handle: base }, { role: "field", label }) : {}) }), storedReference && name ? _jsx("input", { type: "hidden", name: name, value: value }) : null, _jsx("button", { type: "button", className: "jini-btn jini-btn-secondary", onClick: openPicker, ...handleSpread({ ...(base === undefined ? {} : { base }), suffix: "choose", label: `Choose an image for: ${label}` }), children: t({ locale: locale, key: "Choose image" }) }), value ? (_jsx("button", { type: "button", className: "jini-btn jini-btn-secondary", onClick: clear, ...handleSpread({ ...(base === undefined ? {} : { base }), suffix: "clear", label: `Remove the selected image for: ${label}` }), children: t({ locale: locale, key: "Remove" }) })) : null] }), previewUrl ? _jsx("img", { className: "jini-media-ref-field-preview", src: previewUrl, alt: `${label} preview`, onLoad: onPreviewLoad, onError: onPreviewError }, previewUrl) : null, warning ? _jsx("p", { id: `${id}-warning`, className: "jini-notice jini-notice-warning", role: "status", children: warning }) : null, pickerOpen ? (_jsx(Picker, { onSelect: handleSelect, onCancel: closePicker, accept: accept, agentHandle: base ? `${base}-dialog` : undefined })) : null] }));
 }
 //# sourceMappingURL=MediaRefField.js.map

package/dist/seo/react/hooks/MediaRefField.hooks.d.ts

@@ -1,11 +1,13 @@
-import type { MediaRefFieldController } from '../../models.js';
+import type { MediaRefFieldController, SeoTranslator } from '../../models.js';
 import type { AdminSeoPort } from '../../ports.js';
 export type { MediaRefFieldController } from '../../models.js';
 export declare function useMediaRefField({ value, onChange, api }: {
     value: string;
     onChange: (value: string) => void;
     api: AdminSeoPort;
-}, _optional?: Record<string, never>): MediaRefFieldController;
+}, { t }?: {
+    t?: SeoTranslator | undefined;
+}): MediaRefFieldController;
 export declare function useWiredMediaRefField({ value, onChange }: {
     value: string;
     onChange: (value: string) => void;

package/dist/seo/react/hooks/MediaRefField.hooks.js

@@ -1,23 +1,28 @@
 import { useRef } from 'react';
+import { useShareImageWarning } from './use-share-image-warning.hooks.js';
 import { agentHandle } from '@jini-ai/agentic';
 import { useController } from '../../../core/react/use-controller.js';
 import { createMediaRefController } from '../../controllers/media-ref.controller.js';
 import { isStoredMediaRef, resolveMediaRefPreviewUrl } from '../../rules.js';
 import { useSeoPorts, useSeoOptions } from './SeoPorts.hooks.js';
-export function useMediaRefField({ value, onChange, api }, _optional = {}) {
+export function useMediaRefField({ value, onChange, api }, { t } = {}) {
     const change = useRef(onChange);
     change.current = onChange;
     const { controller, snapshot } = useController({ create: () => createMediaRefController({ onChange: value => change.current(value) }), dependencies: [] });
+    const previewUrl = api.mediaPreviewUrl ? api.mediaPreviewUrl({ value }) : resolveMediaRefPreviewUrl({ value, mediaOriginalUrl: id => api.mediaOriginalUrl({ id }) });
+    const diagnostics = useShareImageWarning({ value, previewUrl, api }, { t });
     return {
+        ...diagnostics,
         pickerOpen: snapshot?.pickerOpen ?? false,
         openPicker: () => controller?.openPicker({}), closePicker: () => controller?.closePicker({}),
         handleSelect: item => controller?.handleSelect({ item }), clear: () => controller?.clear({}),
-        previewUrl: resolveMediaRefPreviewUrl({ value, mediaOriginalUrl: id => api.mediaOriginalUrl({ id }) }), accept: ['image/*'],
+        previewUrl, accept: ['image/*'],
     };
 }
 export function useWiredMediaRefField({ value, onChange }, _optional = {}) {
     const { seoApi: api } = useSeoPorts();
-    return useMediaRefField({ value, onChange, api });
+    const { t } = useSeoOptions();
+    return useMediaRefField({ value, onChange, api }, { t });
 }
 /** Slot or existing promise picker; no picker implementation is forked into SEO. */
 export function useMediaRefPresentation({ value }, _optional = {}) {

package/dist/seo/react/hooks/SeoQuery.hooks.d.ts

@@ -0,0 +1,42 @@
+import { type SeoTranslator } from '../../models.js';
+import type { AdminSeoPort } from '../../ports.js';
+export declare const SEO_KEYS: {
+    settings: readonly ["seo", "settings"];
+    entries: readonly ["seo", "entry"];
+    entry: ({ entryId }: {
+        entryId: string;
+    }, _optional?: Record<string, never>) => readonly ["seo", "entry", string];
+    choices: readonly ["seo", "choices"];
+    sitemap: readonly ["seo", "sitemap"];
+};
+/** Controllers keep their draft/error contracts; these injected ports share the provider cache.
+ * Reads omit a controller's abort signal because another mounted consumer can own the same read.
+ * Controller generations/disposal still prevent that consumer from settling an obsolete screen. */
+export declare function useSeoSettingsQuery({ api }: {
+    api: AdminSeoPort;
+}, { t }?: {
+    t?: SeoTranslator;
+}): {
+    api: AdminSeoPort;
+    query: import("@jini-ai/ui").QueryResult<import("../../../core/index.js").AdminSeoSettings>;
+};
+export declare function useSeoEntryQuery({ api, entryId }: {
+    api: AdminSeoPort;
+    entryId: string;
+}, _optional?: Record<string, never>): {
+    api: AdminSeoPort;
+    query: import("@jini-ai/ui").QueryResult<{
+        resolved: import("../../../core/index.js").AdminSeoMeta;
+        analysis: import("../../../core/index.js").AdminSeoAnalysis;
+    }>;
+};
+export declare function useSitemapQuery({ api, enabled }: {
+    api: AdminSeoPort;
+    enabled: boolean;
+}, _optional?: Record<string, never>): {
+    api: AdminSeoPort;
+    query: import("@jini-ai/ui").QueryResult<{
+        text: string;
+    }>;
+};
+//# sourceMappingURL=SeoQuery.hooks.d.ts.map

package/dist/seo/react/hooks/SeoQuery.hooks.js

@@ -0,0 +1,65 @@
+import { useCallback, useMemo, useRef } from 'react';
+import { useCachedLoader, useFetchMutation, useFetchQuery } from '@jini-ai/ui/fetch-query';
+import { describeSeoError } from '../../models.js';
+export const SEO_KEYS = {
+    settings: ['seo', 'settings'],
+    entries: ['seo', 'entry'],
+    entry: ({ entryId }, _optional = {}) => ['seo', 'entry', entryId],
+    choices: ['seo', 'choices'],
+    sitemap: ['seo', 'sitemap'],
+};
+/** Controllers keep their draft/error contracts; these injected ports share the provider cache.
+ * Reads omit a controller's abort signal because another mounted consumer can own the same read.
+ * Controller generations/disposal still prevent that consumer from settling an obsolete screen. */
+export function useSeoSettingsQuery({ api }, { t = key => key } = {}) {
+    const translator = useRef(t);
+    translator.current = t;
+    const fetch = useCallback(async () => {
+        try {
+            return await api.getSeoSettings({});
+        }
+        catch (error) {
+            throw new Error(describeSeoError({ error, fallback: translator.current('failed to load SEO settings') }));
+        }
+    }, [api]);
+    const query = useFetchQuery({ key: SEO_KEYS.settings, fetch }, { staleTime: 0 });
+    const loader = useCachedLoader({ key: SEO_KEYS.settings, fetch }, { staleTime: 0 });
+    const save = useFetchMutation({ run: ({ input }) => api.putSeoSettings(...input) }, { invalidates: [SEO_KEYS.settings, SEO_KEYS.entries] });
+    const regenerate = useFetchMutation({ run: ({ input }) => api.regenerateSeoSitemap(...input) }, { invalidates: [SEO_KEYS.sitemap] });
+    const current = useRef({ loader, save, regenerate });
+    current.current = { loader, save, regenerate };
+    const cachedApi = useMemo(() => ({ ...api,
+        getSeoSettings: () => current.current.loader.load(),
+        putSeoSettings: (...input) => current.current.save.mutate({ input }),
+        regenerateSeoSitemap: (...input) => current.current.regenerate.mutate({ input }),
+    }), [api]);
+    return { api: cachedApi, query };
+}
+export function useSeoEntryQuery({ api, entryId }, _optional = {}) {
+    const key = useMemo(() => SEO_KEYS.entry({ entryId }), [entryId]);
+    const fetch = useCallback(async () => {
+        const [resolved, analysis] = await Promise.all([api.getSeoEntry({ entryId }), api.analyzeSeoEntry({ entryId })]);
+        return { resolved, analysis };
+    }, [api, entryId]);
+    const query = useFetchQuery({ key, fetch }, { enabled: !!entryId, staleTime: 0 });
+    const loader = useCachedLoader({ key, fetch }, { staleTime: 0 });
+    const save = useFetchMutation({ run: ({ input }) => api.putSeoEntry(...input) }, { invalidates: [SEO_KEYS.entries] });
+    const current = useRef({ loader, save });
+    current.current = { loader, save };
+    const cachedApi = useMemo(() => ({ ...api,
+        getSeoEntry: async () => (await current.current.loader.load()).resolved,
+        analyzeSeoEntry: async () => (await current.current.loader.load()).analysis,
+        putSeoEntry: (...input) => current.current.save.mutate({ input }),
+    }), [api, entryId]);
+    return { api: cachedApi, query };
+}
+export function useSitemapQuery({ api, enabled }, _optional = {}) {
+    const fetch = useCallback(() => api.fetchSitemapXml({}), [api]);
+    const query = useFetchQuery({ key: SEO_KEYS.sitemap, fetch }, { enabled });
+    const loader = useCachedLoader({ key: SEO_KEYS.sitemap, fetch });
+    const current = useRef(loader);
+    current.current = loader;
+    const cachedApi = useMemo(() => ({ ...api, fetchSitemapXml: () => current.current.load() }), [api]);
+    return { api: cachedApi, query };
+}
+//# sourceMappingURL=SeoQuery.hooks.js.map

package/dist/seo/react/hooks/use-entry-picker.hooks.js

@@ -1,16 +1,14 @@
 import { describeSeoError } from '../../models.js';
-import { useRef } from 'react';
-import { useController } from '../../../core/react/use-controller.js';
-import { createEntryPickerController } from '../../controllers/entry-picker.controller.js';
+import { useFetchQuery } from '@jini-ai/ui/fetch-query';
+import { SEO_KEYS } from './SeoQuery.hooks.js';
 import { initialEntryPickerState } from '../../models.js';
 import { useSeoOptions, useSeoPorts } from './SeoPorts.hooks.js';
 export function useEntryPicker({ api }, { t, describeError } = {}) {
-    const translator = useRef(t);
-    translator.current = t;
-    const formatter = useRef(describeError);
-    formatter.current = describeError;
-    const { snapshot } = useController({ create: () => createEntryPickerController({ api }, { t: (key, vars) => translator.current?.(key, vars) ?? key, describeError: required => formatter.current ? formatter.current(required) : describeSeoError(required) }), dependencies: [api] }, { start: ({ controller }) => { void controller.load({}); } });
-    return snapshot ?? initialEntryPickerState;
+    const query = useFetchQuery({ key: SEO_KEYS.choices, fetch: async () => {
+            const [posts, pages] = await Promise.all([api.listSeoPosts({}), api.listSeoPages({})]);
+            return [...posts, ...pages];
+        } });
+    return { ...initialEntryPickerState, entries: query.data ?? null, error: query.error ? (describeError ?? describeSeoError)({ error: query.error, fallback: t?.('failed to load entries') ?? 'failed to load entries' }) : null };
 }
 export function useWiredEntryPicker(_required = {}, _optional = {}) {
     const { seoApi: api } = useSeoPorts();

package/dist/seo/react/hooks/use-seo-entry-panel.hooks.js

@@ -1,15 +1,22 @@
 import { describeSeoError } from '../../models.js';
-import { useRef } from 'react';
+import { useEffect, useRef } from 'react';
+import { useSeoEntryQuery } from './SeoQuery.hooks.js';
 import { useController } from '../../../core/react/use-controller.js';
 import { createSeoEntryController } from '../../controllers/seo-entry.controller.js';
 import { initialSeoEntryState } from '../../models.js';
 import { useSeoOptions, useSeoPorts } from './SeoPorts.hooks.js';
 export function useSeoEntryPanel({ api, entryId }, { t, describeError } = {}) {
+    const cached = useSeoEntryQuery({ api, entryId });
     const translator = useRef(t);
     translator.current = t;
     const formatter = useRef(describeError);
     formatter.current = describeError;
-    const { controller, snapshot } = useController({ create: () => createSeoEntryController({ api, entryId }, { t: (key, vars) => translator.current?.(key, vars) ?? key, describeError: required => formatter.current ? formatter.current(required) : describeSeoError(required) }), dependencies: [api, entryId] }, { start: ({ controller }) => { void controller.load({}); } });
+    const { controller, snapshot } = useController({ create: () => createSeoEntryController({ api: cached.api, entryId }, { t: (key, vars) => translator.current?.(key, vars) ?? key, describeError: required => formatter.current ? formatter.current(required) : describeSeoError(required) }), dependencies: [cached.api, entryId] }, { start: ({ controller }) => { void controller.load({}); } });
+    useEffect(() => {
+        // Revalidation updates server truth without discarding touched override fields.
+        if (controller && cached.query.data)
+            controller.set({ patch: cached.query.data });
+    }, [controller, cached.query.data]);
     const state = snapshot ?? initialSeoEntryState;
     return {
         ...state,