@jini-ai/admin 0.4.5 → 0.4.6

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

@@ -1,19 +1,37 @@
 import { useEffect, useRef } from 'react';
+import { useInvalidate } from '@jini-ai/ui/fetch-query';
+import { SEO_KEYS, useSeoSettingsQuery } from './SeoQuery.hooks.js';
 import { useController } from '../../../core/react/use-controller.js';
 import { createSeoController } from '../../controllers/seo.controller.js';
 import { initialSeoState } from '../../models.js';
 import { useSeoOptions, useSeoPorts } from './SeoPorts.hooks.js';
 export function useSeo({ api }, { t, events } = {}) {
+    const cached = useSeoSettingsQuery({ api }, { ...(t ? { t } : {}) });
+    const invalidate = useInvalidate();
     const translator = useRef(t);
     translator.current = t;
-    const { controller, snapshot } = useController({ create: () => createSeoController({ api }, { t: (key, vars) => translator.current?.(key, vars) ?? key }), dependencies: [api] }, { start: ({ controller }) => { void controller.load({}); } });
+    const { controller, snapshot } = useController({ create: () => createSeoController({ api: cached.api }, { t: (key, vars) => translator.current?.(key, vars) ?? key }), dependencies: [cached.api] }, {
+        // Uncontrolled form fields must first mount with this open's fresh settings. The loader
+        // joins the query's mount read; retained data would permanently fill defaultValue too early.
+        start: ({ controller }) => { void controller.load({}); },
+    });
+    useEffect(() => {
+        if (!controller || !cached.query.data)
+            return;
+        const state = controller.getSnapshot();
+        if (!state.settings)
+            return;
+        // Shared revalidation updates server truth while an unsaved image choice stays local.
+        const imageUntouched = state.defaultOgImage === (state.settings?.defaultOgImage ?? '');
+        controller.set({ patch: { settings: cached.query.data, ...(imageUntouched ? { defaultOgImage: cached.query.data.defaultOgImage ?? '' } : {}) } });
+    }, [controller, cached.query.data]);
     useEffect(() => {
         if (!controller || !events)
             return;
-        return events.subscribe({ onRefresh: () => { void controller.load({}); } });
-    }, [controller, events]);
+        return events.subscribe({ onRefresh: () => { invalidate({ key: SEO_KEYS.settings }); } });
+    }, [controller, events, invalidate]);
     return {
-        ...(snapshot ?? initialSeoState), locale: 'en',
+        ...(snapshot ?? initialSeoState), error: cached.query.error?.message ?? snapshot?.error ?? null, locale: 'en',
         save: async (patch) => { await controller?.save({ patch }); },
         setDefaultOgImage: value => controller?.setDefaultOgImage({ value }),
         regenerateSitemap: async () => await controller?.regenerateSitemap({}) ?? false,

package/dist/seo/react/hooks/use-share-image-warning.hooks.d.ts

@@ -0,0 +1,19 @@
+import type { AdminSeoPort } from '../../ports.js';
+import type { MediaRefFieldController, SeoTranslator } from '../../models.js';
+/** Probe original file size through the host port; decoded width comes from the existing preview.
+ * Unknown size is not zero. URL-keyed state and cancellation prevent a prior choice's response
+ * or image event from warning against the current selection. The probe has a 10-second bound.
+ * External HEAD responses need CORS, so only same-origin files are probed; decoded previews
+ * still report external loading failures and known widths. HTTP copy is translated at render.
+ * @param required Controlled reference, source preview URL and injected SEO API.
+ * @returns Non-blocking warning and the preview's native load/error handlers.
+ * @complexity O(1) state and one HEAD per selection; no image bytes are downloaded by the probe.
+ */
+export declare function useShareImageWarning({ value, previewUrl, api }: {
+    value: string;
+    previewUrl: string | null;
+    api: AdminSeoPort;
+}, { t }?: {
+    t?: SeoTranslator | undefined;
+}): Pick<MediaRefFieldController, 'warning' | 'onPreviewLoad' | 'onPreviewError'>;
+//# sourceMappingURL=use-share-image-warning.hooks.d.ts.map

package/dist/seo/react/hooks/use-share-image-warning.hooks.js

@@ -0,0 +1,79 @@
+import { useEffect, useRef, useState } from 'react';
+import { interpolate } from '@jini-ai/ui/panel-kit';
+import { shareImageWarning } from '../../rules.js';
+/** Probe original file size through the host port; decoded width comes from the existing preview.
+ * Unknown size is not zero. URL-keyed state and cancellation prevent a prior choice's response
+ * or image event from warning against the current selection. The probe has a 10-second bound.
+ * External HEAD responses need CORS, so only same-origin files are probed; decoded previews
+ * still report external loading failures and known widths. HTTP copy is translated at render.
+ * @param required Controlled reference, source preview URL and injected SEO API.
+ * @returns Non-blocking warning and the preview's native load/error handlers.
+ * @complexity O(1) state and one HEAD per selection; no image bytes are downloaded by the probe.
+ */
+export function useShareImageWarning({ value, previewUrl, api }, { t = key => key } = {}) {
+    const currentUrl = useRef(previewUrl);
+    currentUrl.current = previewUrl;
+    const [decoded, setDecoded] = useState(null);
+    const [inspection, setInspection] = useState(null);
+    useEffect(() => {
+        const inspect = api.inspectShareImage;
+        if (!previewUrl || !inspect)
+            return;
+        // Browser origin, rather than the public site's alias: a cross-origin HEAD cannot establish
+        // that an otherwise loadable external image is missing when the server omits CORS headers.
+        const location = globalThis.location;
+        if (!location)
+            return;
+        try {
+            if (new URL(previewUrl, location.href).origin !== location.origin)
+                return;
+        }
+        catch {
+            return;
+        }
+        const controller = new AbortController();
+        let active = true;
+        const timeout = setTimeout(() => {
+            active = false;
+            controller.abort();
+            setInspection({ url: previewUrl, error: { key: 'The share image check timed out after 10 seconds.' } });
+        }, 10_000);
+        inspect.call(api, { url: previewUrl }, { signal: controller.signal }).then(({ status, byteSize }) => {
+            if (!active)
+                return;
+            if (status === 404 || status === 410) {
+                setInspection({ url: previewUrl, error: { key: 'The share image is missing (HTTP {status}).', vars: { status } } });
+            }
+            else if (status < 200 || status >= 300) {
+                setInspection({ url: previewUrl, error: { key: 'The share image could not be checked (HTTP {status}).', vars: { status } } });
+            }
+            else {
+                setInspection({ url: previewUrl, byteSize });
+            }
+        }).catch((error) => {
+            if (!active)
+                return;
+            const detail = error instanceof Error ? error.message : String(error);
+            setInspection({ url: previewUrl, error: { key: 'The share image could not be checked: {detail}', vars: { detail } } });
+        }).finally(() => { clearTimeout(timeout); });
+        return () => { active = false; clearTimeout(timeout); controller.abort(); };
+    }, [previewUrl, api]);
+    const source = decoded?.url === previewUrl ? decoded : null;
+    const checked = inspection?.url === previewUrl ? inspection : null;
+    const error = checked?.error;
+    return {
+        warning: shareImageWarning({ value, previewUrl, width: source?.width, previewFailed: source?.failed, byteSize: checked?.byteSize,
+            error: error ? interpolate({ template: t(error.key, error.vars), vars: error.vars ?? {} }) : undefined }, { t }),
+        onPreviewLoad: ({ currentTarget }) => {
+            const url = currentTarget.getAttribute('src');
+            if (url && url === currentUrl.current)
+                setDecoded({ url, width: currentTarget.naturalWidth });
+        },
+        onPreviewError: ({ currentTarget }) => {
+            const url = currentTarget.getAttribute('src');
+            if (url && url === currentUrl.current)
+                setDecoded({ url, failed: true });
+        },
+    };
+}
+//# sourceMappingURL=use-share-image-warning.hooks.js.map

package/dist/seo/react/hooks/use-sitemap-modal.hooks.js

@@ -1,15 +1,17 @@
 import { useMemo } from 'react';
+import { useSitemapQuery } from './SeoQuery.hooks.js';
 import { useController } from '../../../core/react/use-controller.js';
 import { createSitemapController } from '../../controllers/sitemap.controller.js';
 import { parseSitemapXml, filterSitemapEntries } from '../../rules.js';
 import { useSeoPorts } from './SeoPorts.hooks.js';
 export function useSitemapModal({ api, enabled }, _optional = {}) {
-    const { controller, snapshot } = useController({ create: () => createSitemapController({ api, enabled }), dependencies: [api, enabled] }, { start: ({ controller }) => { void controller.load({}); } });
-    const state = snapshot ?? { status: enabled ? 'loading' : 'disabled', error: null, xmlText: '', filter: '', view: 'table' };
+    const cached = useSitemapQuery({ api, enabled });
+    const { controller, snapshot } = useController({ create: () => createSitemapController({ api: cached.api, enabled }), dependencies: [cached.api, enabled] }, { start: ({ controller }) => { void controller.load({}); } });
+    const state = { ...(snapshot ?? { filter: '', view: 'table' }), status: !enabled ? 'disabled' : cached.query.error ? 'error' : cached.query.data ? 'ready' : 'loading', error: cached.query.error?.message ?? null, xmlText: cached.query.data?.text ?? '' };
     // Parse only when text/status changes, never on each filter keystroke.
     const entries = useMemo(() => state.status === 'ready' ? parseSitemapXml({ xmlText: state.xmlText }) : [], [state.status, state.xmlText]);
     const filteredEntries = useMemo(() => filterSitemapEntries({ entries, query: state.filter }), [entries, state.filter]);
-    return { ...state, entries, filteredEntries, setFilter: value => controller?.setFilter({ value }), setView: view => controller?.setView({ view }), refetch: () => { void controller?.load({}); } };
+    return { ...state, entries, filteredEntries, setFilter: value => controller?.setFilter({ value }), setView: view => controller?.setView({ view }), refetch: cached.query.refetch };
 }
 export function useWiredSitemapModal({ enabled, onClose }, _optional = {}) {
     const { seoApi: api } = useSeoPorts();

package/dist/seo/react/pages/SeoPage.js

@@ -87,7 +87,7 @@ function SeoEntryPanel({ locale, entryId, useSeoEntryPanelHook = useWiredSeoEntr
         return _jsx("div", { className: "jini-notice jini-notice-error", children: loadError });
     if (!resolved)
         return _jsx("div", { className: "jini-notice", children: t({ locale: locale, key: "Loading entry SEO…" }) });
-    return (_jsxs("div", { className: "jini-seo-entry-panel", children: [_jsx("h3", { children: t({ locale: locale, key: "Per-entry overrides" }) }), _jsxs("p", { className: "jini-muted-cell", children: [t({ locale: locale, key: "Fields show the currently-effective value (author override, or site default, or derived from the entry). Only fields you change here are saved as overrides." }), " ", t({ locale: locale, key: "Empty a field and save to remove its override — the entry falls back to the site default." })] }), notice ? _jsx("div", { className: "jini-notice", children: notice }) : null, saveError ? (_jsx("div", { className: "jini-notice jini-notice-error", role: "alert", children: saveError })) : null, _jsxs("label", { children: [t({ locale: locale, key: "Title" }), _jsx("input", { className: "jini-input", value: fieldValue("title", resolved.title) ?? "", onChange: (e) => setField("title", e.target.value), ...agentHandle({ handle: "seo-entry-title" }, { role: "field", label: "This entry's SEO title override" }) })] }), _jsxs("label", { children: [t({ locale: locale, key: "Description" }), _jsx("textarea", { className: "jini-textarea", value: fieldValue("description", resolved.description ?? "") ?? "", onChange: (e) => setField("description", e.target.value), ...agentHandle({ handle: "seo-entry-description" }, { role: "field", label: "This entry's SEO description override" }) })] }), _jsxs("label", { children: [t({ locale: locale, key: "Canonical URL" }), _jsx("input", { className: "jini-input", value: fieldValue("canonical", resolved.canonical) ?? "", onChange: (e) => setField("canonical", e.target.value), ...agentHandle({ handle: "seo-entry-canonical" }, { role: "field", label: "This entry's canonical URL override" }) })] }), _jsxs("label", { children: [_jsx("input", { className: "jini-input", type: "checkbox", checked: fieldValue("noindex", resolved.robots.noindex) ?? false, onChange: (e) => setField("noindex", e.target.checked), ...agentHandle({ handle: "seo-entry-noindex" }, { role: "checkbox", label: "Override this entry's robots noindex directive" }) }), t({ locale: locale, key: "Noindex" })] }), _jsxs("label", { children: [_jsx("input", { className: "jini-input", type: "checkbox", checked: fieldValue("nofollow", resolved.robots.nofollow) ?? false, onChange: (e) => setField("nofollow", e.target.checked), ...agentHandle({ handle: "seo-entry-nofollow" }, { role: "checkbox", label: "Override this entry's robots nofollow directive" }) }), t({ locale: locale, key: "Nofollow" })] }), _jsxs("label", { children: [t({ locale: locale, key: "OG title" }), _jsx("input", { className: "jini-input", value: fieldValue("ogTitle", resolved.openGraph.title) ?? "", onChange: (e) => setField("ogTitle", e.target.value), ...agentHandle({ handle: "seo-entry-og-title" }, { role: "field", label: "This entry's Open Graph title override" }) })] }), _jsxs("label", { children: [t({ locale: locale, key: "OG description" }), _jsx("input", { className: "jini-input", value: fieldValue("ogDescription", resolved.openGraph.description ?? "") ?? "", onChange: (e) => setField("ogDescription", e.target.value), ...agentHandle({ handle: "seo-entry-og-description" }, { role: "field", label: "This entry's Open Graph description override" }) })] }), _jsx(MediaRefField, { locale: locale, id: "seo-entry-og-image", label: t({ locale: locale, key: "OG image" }), value: fieldValue("ogImage", resolved.openGraph.image ?? "") ?? "", onChange: (value) => setField("ogImage", value), agentHandle: "seo-entry-og-image" }), _jsxs("label", { children: [t({ locale: locale, key: "Twitter title" }), _jsx("input", { className: "jini-input", value: fieldValue("twitterTitle", resolved.twitter.title) ?? "", onChange: (e) => setField("twitterTitle", e.target.value), ...agentHandle({ handle: "seo-entry-twitter-title" }, { role: "field", label: "This entry's Twitter card title override" }) })] }), _jsxs("label", { children: [t({ locale: locale, key: "Twitter description" }), _jsx("input", { className: "jini-input", value: fieldValue("twitterDescription", resolved.twitter.description ?? "") ?? "", onChange: (e) => setField("twitterDescription", e.target.value), ...agentHandle({ handle: "seo-entry-twitter-description" }, { role: "field", label: "This entry's Twitter card description override" }) })] }), _jsx(MediaRefField, { locale: locale, id: "seo-entry-twitter-image", label: t({ locale: locale, key: "Twitter image" }), value: fieldValue("twitterImage", resolved.twitter.image ?? "") ?? "", onChange: (value) => setField("twitterImage", value), agentHandle: "seo-entry-twitter-image" }), _jsx("span", { className: "jini-editor-actions", children: _jsx("button", { type: "button", className: "jini-btn jini-btn-secondary", onClick: save, disabled: saving || Object.keys(touched).length === 0, ...agentHandle({ handle: "seo-entry-save-overrides" }, { role: "button", label: "Save this entry's SEO overrides" }), children: saving ? t({ locale: locale, key: "Saving…" }) : t({ locale: locale, key: "Save overrides" }) }) }), analysis ? _jsx(AnalyzePanel, { locale: locale, analysis: analysis }) : null] }));
+    return (_jsxs("div", { className: "jini-seo-entry-panel", children: [_jsx("h3", { children: t({ locale: locale, key: "Per-entry overrides" }) }), _jsxs("p", { className: "jini-muted-cell", children: [t({ locale: locale, key: "Fields show the currently-effective value (author override, or site default, or derived from the entry). Only fields you change here are saved as overrides." }), " ", t({ locale: locale, key: "Empty a field and save to remove its override — the entry falls back to the site default." })] }), notice ? _jsx("div", { className: "jini-notice", children: notice }) : null, saveError ? (_jsx("div", { className: "jini-notice jini-notice-error", role: "alert", children: saveError })) : null, _jsxs("label", { children: [t({ locale: locale, key: "Title" }), _jsx("input", { className: "jini-input", value: fieldValue("title", resolved.title) ?? "", onChange: (e) => setField("title", e.target.value), ...agentHandle({ handle: "seo-entry-title" }, { role: "field", label: "This entry's SEO title override" }) })] }), _jsxs("label", { children: [t({ locale: locale, key: "Description" }), _jsx("textarea", { className: "jini-textarea", value: fieldValue("description", resolved.description ?? "") ?? "", onChange: (e) => setField("description", e.target.value), ...agentHandle({ handle: "seo-entry-description" }, { role: "field", label: "This entry's SEO description override" }) })] }), _jsxs("label", { children: [t({ locale: locale, key: "Canonical URL" }), _jsx("input", { className: "jini-input", value: fieldValue("canonical", resolved.canonical) ?? "", onChange: (e) => setField("canonical", e.target.value), ...agentHandle({ handle: "seo-entry-canonical" }, { role: "field", label: "This entry's canonical URL override" }) })] }), _jsxs("label", { children: [_jsx("input", { className: "jini-input", type: "checkbox", checked: fieldValue("noindex", resolved.robots.noindex) ?? false, onChange: (e) => setField("noindex", e.target.checked), ...agentHandle({ handle: "seo-entry-noindex" }, { role: "checkbox", label: "Override this entry's robots noindex directive" }) }), t({ locale: locale, key: "Noindex" })] }), _jsxs("label", { children: [_jsx("input", { className: "jini-input", type: "checkbox", checked: fieldValue("nofollow", resolved.robots.nofollow) ?? false, onChange: (e) => setField("nofollow", e.target.checked), ...agentHandle({ handle: "seo-entry-nofollow" }, { role: "checkbox", label: "Override this entry's robots nofollow directive" }) }), t({ locale: locale, key: "Nofollow" })] }), _jsxs("label", { children: [t({ locale: locale, key: "OG title" }), _jsx("input", { className: "jini-input", value: fieldValue("ogTitle", resolved.openGraph.title) ?? "", onChange: (e) => setField("ogTitle", e.target.value), ...agentHandle({ handle: "seo-entry-og-title" }, { role: "field", label: "This entry's Open Graph title override" }) })] }), _jsxs("label", { children: [t({ locale: locale, key: "OG description" }), _jsx("input", { className: "jini-input", value: fieldValue("ogDescription", resolved.openGraph.description ?? "") ?? "", onChange: (e) => setField("ogDescription", e.target.value), ...agentHandle({ handle: "seo-entry-og-description" }, { role: "field", label: "This entry's Open Graph description override" }) })] }), _jsx(MediaRefField, { locale: locale, id: "seo-entry-og-image", label: t({ locale: locale, key: "OG image" }), value: fieldValue("ogImage", resolved.openGraph.imageRef ?? resolved.openGraph.image ?? "") ?? "", onChange: (value) => setField("ogImage", value), agentHandle: "seo-entry-og-image" }), _jsxs("label", { children: [t({ locale: locale, key: "Twitter title" }), _jsx("input", { className: "jini-input", value: fieldValue("twitterTitle", resolved.twitter.title) ?? "", onChange: (e) => setField("twitterTitle", e.target.value), ...agentHandle({ handle: "seo-entry-twitter-title" }, { role: "field", label: "This entry's Twitter card title override" }) })] }), _jsxs("label", { children: [t({ locale: locale, key: "Twitter description" }), _jsx("input", { className: "jini-input", value: fieldValue("twitterDescription", resolved.twitter.description ?? "") ?? "", onChange: (e) => setField("twitterDescription", e.target.value), ...agentHandle({ handle: "seo-entry-twitter-description" }, { role: "field", label: "This entry's Twitter card description override" }) })] }), _jsx(MediaRefField, { locale: locale, id: "seo-entry-twitter-image", label: t({ locale: locale, key: "Twitter image" }), value: fieldValue("twitterImage", resolved.twitter.imageRef ?? resolved.twitter.image ?? "") ?? "", onChange: (value) => setField("twitterImage", value), agentHandle: "seo-entry-twitter-image" }), _jsx("span", { className: "jini-editor-actions", children: _jsx("button", { type: "button", className: "jini-btn jini-btn-secondary", onClick: save, disabled: saving || Object.keys(touched).length === 0, ...agentHandle({ handle: "seo-entry-save-overrides" }, { role: "button", label: "Save this entry's SEO overrides" }), children: saving ? t({ locale: locale, key: "Saving…" }) : t({ locale: locale, key: "Save overrides" }) }) }), analysis ? _jsx(AnalyzePanel, { locale: locale, analysis: analysis }) : null] }));
 }
 /** Section wrapper (REQ-06/07) — entry picker over the per-entry edit + analyze panels. This IS the
  *  "Pages & posts" tab panel; it kept its name and its markup, because nothing about it changed

package/dist/seo/rules.d.ts

@@ -1,4 +1,5 @@
 import type { AdminSeoIssue as SeoIssue, AdminSeoSettingsPatch as SeoSettingsPatch } from "../core/ports/seo.js";
+import type { SeoTranslator } from './models.js';
 /**
  * Orders issues error-first, then warning, then info, matching the severities' natural urgency.
  * An unrecognized severity sorts last (falls back to `9`) rather than throwing, since this reads
@@ -99,7 +100,8 @@ export declare function buildMediaRef({ item }: {
     };
 }, _optional?: Record<string, never>): string;
 /** `MediaRefField`'s thumbnail `<img src>` for the field's current value. An absolute URL (the
- *  field's other legal shape — someone pasted a raw URL) renders directly; a `{assetId}:{transform}`
+ *  field's other legal shape — someone pasted a raw URL) renders directly unless siteOrigin
+ *  identifies it as this host's rendition, in which case diagnostics inspect its original; a `{assetId}:{transform}`
  *  ref resolves through the injected `mediaOriginalUrl` builder — the admin media library's own
  *  preview URL (`MediaPickerPort.mediaOriginalUrl`), same as `MediaPickerDialog`'s own grid
  *  thumbnails use, NOT the public `/m/...` rendition URL (that needs a live workspace/transform
@@ -115,7 +117,24 @@ export declare function buildMediaRef({ item }: {
 export declare function resolveMediaRefPreviewUrl({ value, mediaOriginalUrl }: {
     value: string;
     mediaOriginalUrl: (id: string) => string;
-}, _optional?: Record<string, never>): string | null;
+}, { siteOrigin }?: {
+    siteOrigin?: string | undefined;
+}): string | null;
+/** Diagnostic policy: unknown measurements stay unknown; measured failures name their reason.
+ * @param required Controlled field, decoded preview width and original HTTP metadata.
+ * @returns A non-blocking explanation, or null for an image without a measured problem.
+ * @complexity O(n) in value/error length; fixed-count checks, no I/O.
+ */
+export declare function shareImageWarning({ value, previewUrl, width, byteSize, error, previewFailed }: {
+    value: string;
+    previewUrl: string | null;
+    width?: number | undefined;
+    byteSize?: number | null | undefined;
+    error?: string | null | undefined;
+    previewFailed?: boolean | undefined;
+}, { t }?: {
+    t?: SeoTranslator | undefined;
+}): string | null;
 /**
  * The site-wide settings patch the defaults form submits — lifted out of the form's own inline
  * `onSubmit` when this screen gained tabs. Same seven fields, same `checkbox === "on"` reading of

package/dist/seo/rules.js

@@ -1,3 +1,4 @@
+import { interpolate } from '@jini-ai/ui/panel-kit';
 /**
  * @file Pure logic for the `seo` feature — everything that computes a value rather than rendering
  * one.
@@ -138,7 +139,8 @@ export function buildMediaRef({ item }, _optional = {}) {
     return `${key}:${SEO_IMAGE_TRANSFORM}`;
 }
 /** `MediaRefField`'s thumbnail `<img src>` for the field's current value. An absolute URL (the
- *  field's other legal shape — someone pasted a raw URL) renders directly; a `{assetId}:{transform}`
+ *  field's other legal shape — someone pasted a raw URL) renders directly unless siteOrigin
+ *  identifies it as this host's rendition, in which case diagnostics inspect its original; a `{assetId}:{transform}`
  *  ref resolves through the injected `mediaOriginalUrl` builder — the admin media library's own
  *  preview URL (`MediaPickerPort.mediaOriginalUrl`), same as `MediaPickerDialog`'s own grid
  *  thumbnails use, NOT the public `/m/...` rendition URL (that needs a live workspace/transform
@@ -151,15 +153,53 @@ export function buildMediaRef({ item }, _optional = {}) {
  *
  * @complexity O(1) — string parsing only, no I/O (the returned URL is a template; the browser
  * performs the actual fetch only once it is used as an `<img src>`). */
-export function resolveMediaRefPreviewUrl({ value, mediaOriginalUrl }, _optional = {}) {
+export function resolveMediaRefPreviewUrl({ value, mediaOriginalUrl }, { siteOrigin } = {}) {
     const trimmed = typeof value === "string" ? value.trim() : "";
     if (!trimmed)
         return null;
-    if (isAbsoluteMediaRef(trimmed))
-        return trimmed;
+    if (isAbsoluteMediaRef(trimmed)) {
+        const key = siteOrigin ? localRenditionAssetKey({ value: trimmed, siteOrigin }) : null;
+        return key ? mediaOriginalUrl(key) : trimmed;
+    }
     const assetId = parseMediaRefAssetId(trimmed);
     return assetId ? mediaOriginalUrl(assetId) : null;
 }
+/** Only same-origin public rendition URLs identify an original in this host's media library.
+ * External URLs retain their own source. @complexity O(n) URL parsing; no I/O.
+ */
+function localRenditionAssetKey({ value, siteOrigin }, _optional = {}) {
+    try {
+        const url = new URL(value, siteOrigin);
+        if (url.origin !== new URL(siteOrigin).origin)
+            return null;
+        const match = url.pathname.match(/^\/m\/([^/]+)\/[^/]+\.v\d+\/[^/]+$/);
+        return match ? decodeURIComponent(match[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Diagnostic policy: unknown measurements stay unknown; measured failures name their reason.
+ * @param required Controlled field, decoded preview width and original HTTP metadata.
+ * @returns A non-blocking explanation, or null for an image without a measured problem.
+ * @complexity O(n) in value/error length; fixed-count checks, no I/O.
+ */
+export function shareImageWarning({ value, previewUrl, width, byteSize, error, previewFailed }, { t = key => key } = {}) {
+    if (typeof value !== 'string' || !value.trim())
+        return t('No share image is selected. Link previews may show no picture.');
+    if (!previewUrl)
+        return t('The share image reference is invalid. Choose an image or enter an absolute image URL.');
+    if (error)
+        return error;
+    if (previewFailed)
+        return t('The share image could not be loaded. Choose an available image.');
+    const reasons = [];
+    if (width !== undefined && width < 600)
+        reasons.push(interpolate({ template: t('The share image is only {width} px wide; use an image at least 600 px wide.', { width }), vars: { width } }));
+    if (byteSize !== undefined && byteSize !== null && byteSize < 5120)
+        reasons.push(interpolate({ template: t('The share image is only {byteSize} bytes; use an image of at least 5 KB (5120 bytes).', { byteSize }), vars: { byteSize } }));
+    return reasons.length ? reasons.join(' ') : null;
+}
 /** One `FormData` field as a string, with the caller's fallback for an absent field. Its own named
  *  function purely so {@link buildSeoSettingsPatch} below stays readable at a glance: written
  *  inline, the seven fields' `?? `/`||` chains scored the patch builder at the ESLint ceiling

package/dist/widgets/react/hooks/WidgetsQuery.hooks.d.ts

@@ -0,0 +1,37 @@
+import type { AdminWidgetsPort } from '../../ports.js';
+export declare const WIDGET_QUERY_KEYS: {
+    root: readonly ["widgets"];
+    library: readonly ["widgets", "library"];
+    instances: readonly ["widgets", "instance"];
+    regions: readonly ["widgets", "regions"];
+    regionDetails: readonly ["widgets", "region"];
+};
+/** Query ports preserve headless controller APIs. Each hook owns one fixed resource key;
+ * mutable refs keep the injected port stable without capturing stale route ids or mutations. */
+export declare function useWidgetsListQuery({ api }: {
+    api: AdminWidgetsPort;
+}, _optional?: Record<string, never>): {
+    api: AdminWidgetsPort;
+    query: import("@jini-ai/ui").QueryResult<{
+        widgets: import("../../models.js").AdminWidget[];
+        skippedCount?: number | undefined;
+        skippedIds?: string[] | undefined;
+    }>;
+};
+export declare function useWidgetRegionsQuery({ api }: {
+    api: AdminWidgetsPort;
+}, _optional?: Record<string, never>): {
+    api: AdminWidgetsPort;
+    query: import("@jini-ai/ui").QueryResult<{
+        regions: import("../../models.js").AdminWidgetRegionBinding[];
+    }>;
+};
+export declare function useWidgetInstanceQuery({ api, widgetId }: {
+    api: AdminWidgetsPort;
+    widgetId: string | null;
+}, _optional?: Record<string, never>): AdminWidgetsPort;
+export declare function useWidgetRegionQuery({ api, regionKey }: {
+    api: AdminWidgetsPort;
+    regionKey: string;
+}, _optional?: Record<string, never>): AdminWidgetsPort;
+//# sourceMappingURL=WidgetsQuery.hooks.d.ts.map

package/dist/widgets/react/hooks/WidgetsQuery.hooks.js

@@ -0,0 +1,70 @@
+import { useCallback, useMemo, useRef } from 'react';
+import { useCachedLoader, useFetchMutation, useFetchQuery } from '@jini-ai/ui/fetch-query';
+export const WIDGET_QUERY_KEYS = {
+    root: ['widgets'],
+    library: ['widgets', 'library'],
+    instances: ['widgets', 'instance'],
+    regions: ['widgets', 'regions'],
+    regionDetails: ['widgets', 'region'],
+};
+/** Query ports preserve headless controller APIs. Each hook owns one fixed resource key;
+ * mutable refs keep the injected port stable without capturing stale route ids or mutations. */
+export function useWidgetsListQuery({ api }, _optional = {}) {
+    const fetch = useCallback(() => api.listWidgets({}), [api]);
+    const query = useFetchQuery({ key: WIDGET_QUERY_KEYS.library, fetch });
+    const loader = useCachedLoader({ key: WIDGET_QUERY_KEYS.library, fetch }, { staleTime: 0 });
+    const write = useFetchMutation({ run: ({ input }) => api.trashWidget(...input) }, { invalidates: [WIDGET_QUERY_KEYS.root] });
+    const current = useRef({ loader, write });
+    current.current = { loader, write };
+    const cachedApi = useMemo(() => ({ ...api,
+        listWidgets: () => current.current.loader.load(),
+        trashWidget: (...input) => current.current.write.mutate({ input }),
+    }), [api]);
+    return { api: cachedApi, query };
+}
+export function useWidgetRegionsQuery({ api }, _optional = {}) {
+    const fetch = useCallback(() => api.listWidgetRegions({}), [api]);
+    const query = useFetchQuery({ key: WIDGET_QUERY_KEYS.regions, fetch });
+    const loader = useCachedLoader({ key: WIDGET_QUERY_KEYS.regions, fetch }, { staleTime: 0 });
+    const write = useFetchMutation({ run: ({ input }) => api.bindWidgetRegion(...input) }, { invalidates: [WIDGET_QUERY_KEYS.root] });
+    const current = useRef({ loader, write });
+    current.current = { loader, write };
+    const cachedApi = useMemo(() => ({ ...api,
+        listWidgetRegions: () => current.current.loader.load(),
+        bindWidgetRegion: (...input) => current.current.write.mutate({ input }),
+    }), [api]);
+    return { api: cachedApi, query };
+}
+export function useWidgetInstanceQuery({ api, widgetId }, _optional = {}) {
+    const key = useMemo(() => [...WIDGET_QUERY_KEYS.instances, widgetId ?? ''], [widgetId]);
+    const fetch = useCallback(() => api.getWidget({ id: widgetId }), [api, widgetId]);
+    // The editor owns its draft: an imperative loader shares reads without replacing typed text
+    // merely because a sibling screen invalidated this widget.
+    const loader = useCachedLoader({ key, fetch }, { staleTime: 0 });
+    const create = useFetchMutation({ run: ({ input }) => api.createWidget(...input) }, { invalidates: [WIDGET_QUERY_KEYS.root] });
+    const update = useFetchMutation({ run: ({ input }) => api.updateWidget(...input) }, { invalidates: [WIDGET_QUERY_KEYS.root] });
+    const current = useRef({ loader, create, update });
+    current.current = { loader, create, update };
+    return useMemo(() => ({ ...api,
+        getWidget: () => current.current.loader.load(),
+        createWidget: (...input) => current.current.create.mutate({ input }),
+        updateWidget: (...input) => current.current.update.mutate({ input }),
+    }), [api]);
+}
+export function useWidgetRegionQuery({ api, regionKey }, _optional = {}) {
+    const key = useMemo(() => [...WIDGET_QUERY_KEYS.regionDetails, regionKey], [regionKey]);
+    const fetch = useCallback(() => api.getWidgetRegion({ regionKey }), [api, regionKey]);
+    const loader = useCachedLoader({ key, fetch }, { staleTime: 0 });
+    const save = useFetchMutation({ run: ({ input }) => api.mutateWidgetRegionPlacements(...input) }, { invalidates: [WIDGET_QUERY_KEYS.root] });
+    const widgetKey = useMemo(() => [...WIDGET_QUERY_KEYS.instances, 'lookup'], []);
+    const fetchWidget = useCallback(async () => { throw new Error('Widget id required'); }, []);
+    const widgetLookup = useCachedLoader({ key: widgetKey, fetch: fetchWidget });
+    const current = useRef({ loader, save, widgetLookup });
+    current.current = { loader, save, widgetLookup };
+    return useMemo(() => ({ ...api,
+        getWidgetRegion: () => current.current.loader.load(),
+        getWidget: ({ id }) => current.current.widgetLookup.load({ key: [...WIDGET_QUERY_KEYS.instances, id], fetch: () => api.getWidget({ id }) }),
+        mutateWidgetRegionPlacements: (...input) => current.current.save.mutate({ input }),
+    }), [api]);
+}
+//# sourceMappingURL=WidgetsQuery.hooks.js.map

package/dist/widgets/react/hooks/use-widget-instance-editor.hooks.js

@@ -1,4 +1,5 @@
-import { useEffect, useRef, useCallback } from 'react';
+import { useWidgetInstanceQuery } from './WidgetsQuery.hooks.js';
+import { useEffect, useRef } from 'react';
 import { useDirtyGuard } from '@jini-ai/ui/panel-kit';
 import { useController } from '../../../core/react/use-controller.js';
 import { createWidgetInstanceEditorController } from '../../controllers/instance-editor.controller.js';
@@ -8,16 +9,17 @@ import { useWidgetsPorts, useWidgetsOptions } from './WidgetsPorts.hooks.js';
 import { useWidgetsNavigate } from './navigation.hooks.js';
 export function staleVersionMessage({ t = widgetsEnglish } = {}, _optional = {}) { return t('This widget changed since you loaded it, refresh and try again.'); }
 export function useWidgetInstanceEditor({ params, api, defaultConfig }, { t = widgetsEnglish, locale = 'en', navigate, slugRedirectPath } = {}) {
+    const cachedApi = useWidgetInstanceQuery({ api, widgetId: params.widgetId });
     const paramsRef = useRef(params);
     // Saves compare with the latest rendered identity, before a route effect can run.
     const renderedKey = useRef(widgetEntityKey({ params }));
     renderedKey.current = widgetEntityKey({ params });
     const latest = useRef({ t, navigate, slugRedirectPath });
     latest.current = { t, navigate, slugRedirectPath };
-    const { controller, snapshot } = useController({ create: () => createWidgetInstanceEditorController({ api, params: paramsRef.current, defaultConfig }, {
+    const { controller, snapshot } = useController({ create: () => createWidgetInstanceEditorController({ api: cachedApi, params: paramsRef.current, defaultConfig }, {
             getEntityKey: () => renderedKey.current, t: key => latest.current.t(key), navigate: (path, options) => latest.current.navigate?.(path, options),
             slugRedirectPath: (base, id, item) => latest.current.slugRedirectPath?.(base, id, item) ?? null,
-        }), dependencies: [api, defaultConfig] }, { start: ({ controller }) => { void controller.load(); } });
+        }), dependencies: [cachedApi, defaultConfig] }, { start: ({ controller }) => { void controller.load(); } });
     useEffect(() => {
         if (paramsRef.current.widgetId === params.widgetId && paramsRef.current.widgetType === params.widgetType)
             return;

package/dist/widgets/react/hooks/use-widget-region-editor.hooks.js

@@ -1,3 +1,4 @@
+import { useWidgetRegionQuery } from './WidgetsQuery.hooks.js';
 import { useEffect, useRef } from 'react';
 import { useController } from '../../../core/react/use-controller.js';
 import { createWidgetRegionEditorController } from '../../controllers/region-editor.controller.js';
@@ -5,9 +6,10 @@ import { widgetsEnglish } from '../../messages.en.js';
 import { useWidgetsPorts, useWidgetsOptions } from './WidgetsPorts.hooks.js';
 export function staleVersionMessage({ t = widgetsEnglish } = {}, _optional = {}) { return t('This region changed since you loaded it, refresh and try again.'); }
 export function useWidgetRegionEditor({ regionKey, api }, { t = widgetsEnglish, locale = 'en' } = {}) {
+    const cachedApi = useWidgetRegionQuery({ api, regionKey });
     const keyRef = useRef(regionKey), latestT = useRef(t);
     latestT.current = t;
-    const { controller, snapshot } = useController({ create: () => createWidgetRegionEditorController({ api, regionKey: keyRef.current }, { t: key => latestT.current(key) }), dependencies: [api] }, { start: ({ controller }) => { void controller.load(); } });
+    const { controller, snapshot } = useController({ create: () => createWidgetRegionEditorController({ api: cachedApi, regionKey: keyRef.current }, { t: key => latestT.current(key) }), dependencies: [cachedApi] }, { start: ({ controller }) => { void controller.load(); } });
     useEffect(() => { if (keyRef.current !== regionKey) {
         keyRef.current = regionKey;
         controller?.setRegionKey({ regionKey });

package/dist/widgets/react/hooks/use-widget-regions.hooks.js

@@ -1,3 +1,5 @@
+import { useInvalidate } from '@jini-ai/ui/fetch-query';
+import { WIDGET_QUERY_KEYS, useWidgetRegionsQuery } from './WidgetsQuery.hooks.js';
 import { useEffect, useRef } from 'react';
 import { useController } from '../../../core/react/use-controller.js';
 import { createWidgetRegionsController } from '../../controllers/regions.controller.js';
@@ -5,12 +7,14 @@ import { widgetsEnglish } from '../../messages.en.js';
 import { WIDGETS_REGIONS_RESOURCE } from '../../rules.js';
 import { useWidgetsPorts, useWidgetsOptions } from './WidgetsPorts.hooks.js';
 export function useWidgetRegions({ api }, { t = widgetsEnglish, locale = 'en', events, navigate } = {}) {
+    const cached = useWidgetRegionsQuery({ api });
+    const invalidate = useInvalidate();
     const latest = useRef({ t, navigate });
     latest.current = { t, navigate };
-    const { controller, snapshot } = useController({ create: () => createWidgetRegionsController({ api }, { t: key => latest.current.t(key), navigate: path => latest.current.navigate?.(path) }), dependencies: [api] }, { start: ({ controller }) => { void controller.load(); } });
+    const { controller, snapshot } = useController({ create: () => createWidgetRegionsController({ api: cached.api }, { t: key => latest.current.t(key), navigate: path => latest.current.navigate?.(path) }), dependencies: [cached.api] }, { start: ({ controller }) => { void controller.load(); } });
     useEffect(() => { if (!controller)
-        return; return events?.subscribe({ resource: WIDGETS_REGIONS_RESOURCE, onRefresh: () => { void controller.load(); } }); }, [controller, events]);
-    return { ...(snapshot ?? { regions: null, error: null, newRegionKey: '', binding: false }), setNewRegionKey: value => controller?.setNewRegionKey({ value }), bind: async () => { await controller?.bind(); }, t };
+        return; return events?.subscribe({ resource: WIDGETS_REGIONS_RESOURCE, onRefresh: () => invalidate({ key: WIDGET_QUERY_KEYS.regions }) }); }, [controller, events, invalidate]);
+    return { ...(snapshot ?? { regions: null, error: null, newRegionKey: '', binding: false }), regions: cached.query.data?.regions ?? snapshot?.regions ?? null, error: snapshot?.error ?? cached.query.error?.message ?? null, setNewRegionKey: value => controller?.setNewRegionKey({ value }), bind: async () => { await controller?.bind(); }, t };
 }
 export function useWiredWidgetRegions() {
     const { widgetsApi: api, widgetsEvents: events, widgetsNavigation } = useWidgetsPorts();

package/dist/widgets/react/hooks/use-widgets-library.hooks.js

@@ -1,3 +1,5 @@
+import { useInvalidate } from '@jini-ai/ui/fetch-query';
+import { WIDGET_QUERY_KEYS, useWidgetsListQuery } from './WidgetsQuery.hooks.js';
 import { useEffect, useRef } from 'react';
 import { useController } from '../../../core/react/use-controller.js';
 import { createWidgetsLibraryController } from '../../controllers/library.controller.js';
@@ -5,13 +7,15 @@ import { widgetsEnglish } from '../../messages.en.js';
 import { WIDGETS_LIBRARY_RESOURCE } from '../../rules.js';
 import { useWidgetsPorts, useWidgetsOptions } from './WidgetsPorts.hooks.js';
 export function useWidgetsLibrary({ api }, { t = widgetsEnglish, locale = 'en', events } = {}) {
+    const cached = useWidgetsListQuery({ api });
+    const invalidate = useInvalidate();
     const latestT = useRef(t);
     latestT.current = t;
-    const { controller, snapshot } = useController({ create: () => createWidgetsLibraryController({ api }, { t: key => latestT.current(key) }), dependencies: [api] }, { start: ({ controller }) => { void controller.load(); } });
+    const { controller, snapshot } = useController({ create: () => createWidgetsLibraryController({ api: cached.api }, { t: key => latestT.current(key) }), dependencies: [cached.api] }, { start: ({ controller }) => { void controller.load(); } });
     useEffect(() => { if (!controller)
-        return; return events?.subscribe({ resource: WIDGETS_LIBRARY_RESOURCE, onRefresh: () => { void controller.load(); } }); }, [controller, events]);
+        return; return events?.subscribe({ resource: WIDGETS_LIBRARY_RESOURCE, onRefresh: () => invalidate({ key: WIDGET_QUERY_KEYS.library }) }); }, [controller, events, invalidate]);
     const state = snapshot ?? { widgets: null, error: null, skippedCount: 0, skippedIds: [], createType: 'text', pendingTrash: null, trashingId: null };
-    return { ...state, trashing: state.pendingTrash !== null && state.trashingId === state.pendingTrash.id,
+    return { ...state, widgets: cached.query.data?.widgets ?? state.widgets, skippedCount: cached.query.data?.skippedCount ?? state.skippedCount, skippedIds: cached.query.data?.skippedIds ?? state.skippedIds, error: state.error ?? cached.query.error?.message ?? null, trashing: state.pendingTrash !== null && state.trashingId === state.pendingTrash.id,
         setCreateType: type => controller?.setCreateType({ type }), requestTrash: widget => controller?.requestTrash({ widget }),
         confirmTrash: async () => { await controller?.confirmTrash(); }, cancelTrash: () => controller?.cancelTrash(), t, locale };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/admin",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Composable admin surface for Jini-hosted products: framework-free contracts, panel registry, and route model in `/core`; React shell and panels in `/react`. Import only the layers you need.",
   "license": "Apache-2.0",
   "repository": {
@@ -75,7 +75,8 @@
       "./widgets/react": "browser",
       "./widgets/adapters/http": "universal",
       "./widgets/adapters/memory": "universal",
-      "./widgets/conformance": "universal"
+      "./widgets/conformance": "universal",
+      "./consent/react": "browser"
     },
     "isolation": {
       "forbidden": {
@@ -406,6 +407,11 @@
       "types": "./dist/widgets/conformance/widgets-api.conformance.d.ts",
       "import": "./dist/widgets/conformance/widgets-api.conformance.js",
       "default": "./dist/widgets/conformance/widgets-api.conformance.js"
+    },
+    "./consent/react": {
+      "types": "./dist/consent/react/index.d.ts",
+      "import": "./dist/consent/react/index.js",
+      "default": "./dist/consent/react/index.js"
     }
   },
   "files": [
@@ -427,12 +433,12 @@
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0",
-    "@jini-ai/agentic": "^0.4.2",
-    "@jini-ai/ui": "^0.4.7",
-    "@jini-ai/ui-kit": "^0.1.1",
-    "@jini-ai/agent-plugins": "^0.4.1",
-    "@jini-ai/cms": "^0.5.5",
-    "@jini-ai/core": "^0.4.2"
+    "@jini-ai/agentic": "^0.4.4",
+    "@jini-ai/ui": "^0.4.8",
+    "@jini-ai/ui-kit": "^0.1.3",
+    "@jini-ai/agent-plugins": "^0.4.3",
+    "@jini-ai/cms": "^0.5.6",
+    "@jini-ai/core": "^0.4.3"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -470,12 +476,12 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "@testing-library/user-event": "^14.6.1",
-    "@jini-ai/ui-kit": "^0.1.2",
-    "@jini-ai/cms": "^0.5.5",
-    "@jini-ai/agentic": "^0.4.3",
-    "@jini-ai/agent-plugins": "^0.4.2",
-    "@jini-ai/ui": "^0.4.7",
-    "@jini-ai/core": "^0.4.2"
+    "@jini-ai/agentic": "^0.4.4",
+    "@jini-ai/cms": "^0.5.6",
+    "@jini-ai/agent-plugins": "^0.4.3",
+    "@jini-ai/core": "^0.4.3",
+    "@jini-ai/ui": "^0.4.8",
+    "@jini-ai/ui-kit": "^0.1.3"
   },
   "typesVersions": {
     "*": {