@jini-ai/admin 0.4.11 → 0.4.12

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.4.12 — 2026-10-16
+
+- SEO: searchable entry picker and grouped per-entry form (6c128f9d); image fields name the file, styled analysis, slug for same-titled entries (bc1dbf0d); one Social preview section with an optional "Customize for X" (ff1a709f); X/Twitter labels, file names with extensions, muted inherited site-default image (4919371d); "Using image from page content" when the share image comes from the page (746457d9).
+- Peers: `@jini-ai/ui` `^0.5.5` (grouped Select) and `@jini-ai/cms` `^0.5.13` (share-image source).
+
 ## 0.4.11 — 2026-10-14
 
 - `FieldAttributesDialog` and `SitemapModal` use the neutral `jini-domain-dialog` class instead of a host-named one; hosts style `.jini-domain-dialog` (47b9fa4f).

package/dist/core/ports/seo.d.ts

@@ -76,6 +76,10 @@ export interface AdminSeoOpenGraph {
     readonly image?: string;
     /** Source reference before resizing, used to diagnose the selected share image. */
     readonly imageRef?: string;
+    /** Effective image provenance; absent from older hosts. */
+    readonly imageSource?: 'override' | 'content' | 'default';
+    /** Present (true) only when the entry stores its own image override; absent from older hosts. */
+    readonly imageOverridden?: true;
     readonly siteName?: string;
 }
 export interface AdminSeoTwitterCard {
@@ -149,6 +153,18 @@ export interface AdminSeoEntryChoice {
     readonly id: string;
     readonly title: string;
     readonly status: string;
+    /** Tells two same-titled entries apart in the picker; optional for hosts that omit it. */
+    readonly slug?: string;
+}
+/** What an image field shows for a chosen library file: its name and, when stored, its size. */
+export interface AdminSeoMediaSummary {
+    readonly id: string;
+    readonly slug?: string;
+    readonly title: string;
+    readonly width?: number | null;
+    readonly height?: number | null;
+    /** The stored bytes' sniffed type (`image/png`); gives the displayed name its extension. */
+    readonly contentType?: string | null;
 }
 export interface AdminSeoPort {
     getSeoEntry(requiredArgs: {
@@ -189,6 +205,10 @@ export interface AdminSeoPort {
     mediaPreviewUrl?(required: {
         value: string;
     }, optional?: Record<string, never>): string | null;
+    /** Optional: library rows so an image field can name its file instead of showing a reference. */
+    listSeoMedia?(required: Record<string, never>, optional?: {
+        signal?: AbortSignal;
+    }): Promise<readonly AdminSeoMediaSummary[]>;
     /** Original thumbnail URL; media-reference resolution stays on the server. */
     mediaOriginalUrl(requiredArgs: {
         id: string;

package/dist/seo/adapters/http.js

@@ -20,6 +20,11 @@ export function createHttpSeoApi({ transport, basePath }, { sitemapTransport, im
         analyzeSeoEntry: ({ entryId }) => data(`${entryPath(entryId)}/analyze`, 'GET'),
         listSeoPosts: () => choices('posts'),
         listSeoPages: () => choices('pages'),
+        // The admin media list route the picker already reads; projected so no media row type leaks in.
+        async listSeoMedia() {
+            const response = await transport.request({ path: `${base}/media`, method: 'GET' });
+            return response.media.map(({ id, slug, title, width, height, contentType }) => ({ id, title, ...(slug ? { slug } : {}), width: width ?? null, height: height ?? null, contentType: contentType ?? null }));
+        },
         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 = {}) {

package/dist/seo/messages.en.d.ts

@@ -20,21 +20,24 @@ export declare const seoMessagesEn: {
     readonly "Canonical URL": "Canonical URL";
     readonly Noindex: "Noindex";
     readonly Nofollow: "Nofollow";
-    readonly "OG title": "OG title";
-    readonly "OG description": "OG description";
-    readonly "OG image": "OG image";
-    readonly "Twitter title": "Twitter title";
-    readonly "Twitter description": "Twitter description";
-    readonly "Twitter image": "Twitter image";
+    readonly "Preview title": "Preview title";
+    readonly "Preview description": "Preview description";
+    readonly "Preview image": "Preview image";
+    readonly "X/Twitter title": "X/Twitter title";
+    readonly "X/Twitter description": "X/Twitter description";
+    readonly "X/Twitter image": "X/Twitter image";
+    readonly "Customize for X/Twitter (optional)": "Customize for X/Twitter (optional)";
+    readonly "Same as the preview image": "Same as the preview image";
+    readonly "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter": "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter";
     readonly "Saving\u2026": "Saving…";
     readonly "Save overrides": "Save overrides";
     readonly "Per-entry SEO": "Per-entry SEO";
     readonly "Search appearance": "Search appearance";
     readonly "Title template (must contain %s)": "Title template (must contain %s)";
     readonly "Default meta description": "Default meta description";
-    readonly "Social sharing": "Social sharing";
-    readonly "Default Open Graph / Twitter image": "Default Open Graph / Twitter image";
-    readonly "Twitter @site handle": "Twitter @site handle";
+    readonly "Social preview": "Social preview";
+    readonly "Default preview image": "Default preview image";
+    readonly "X/Twitter @handle": "X/Twitter @handle";
     readonly Crawling: "Crawling";
     readonly "Default noindex": "Default noindex";
     readonly "Default nofollow": "Default nofollow";
@@ -47,7 +50,7 @@ export declare const seoMessagesEn: {
     readonly "View sitemap": "View sitemap";
     readonly "Loading SEO settings\u2026": "Loading SEO settings…";
     readonly Marketing: "Marketing";
-    readonly "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.": "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.";
+    readonly "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.": "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.";
     readonly "Choose image": "Choose image";
     readonly Remove: "Remove";
     readonly "Sitemap \u00B7 {count} URLs": "Sitemap · {count} URLs";
@@ -75,5 +78,7 @@ export declare const seoMessagesEn: {
     readonly "failed to load the sitemap": "failed to load the sitemap";
     readonly "Could not load the sitemap (HTTP {status}).": "Could not load the sitemap (HTTP {status}).";
     readonly "Selected image": "Selected image";
+    readonly "Using site default: {name}": "Using site default: {name}";
+    readonly "Using image from page content: {name}": "Using image from page content: {name}";
 };
 //# sourceMappingURL=messages.en.d.ts.map

package/dist/seo/messages.en.js

@@ -20,21 +20,24 @@ export const seoMessagesEn = {
     "Canonical URL": "Canonical URL",
     "Noindex": "Noindex",
     "Nofollow": "Nofollow",
-    "OG title": "OG title",
-    "OG description": "OG description",
-    "OG image": "OG image",
-    "Twitter title": "Twitter title",
-    "Twitter description": "Twitter description",
-    "Twitter image": "Twitter image",
+    "Preview title": "Preview title",
+    "Preview description": "Preview description",
+    "Preview image": "Preview image",
+    "X/Twitter title": "X/Twitter title",
+    "X/Twitter description": "X/Twitter description",
+    "X/Twitter image": "X/Twitter image",
+    "Customize for X/Twitter (optional)": "Customize for X/Twitter (optional)",
+    "Same as the preview image": "Same as the preview image",
+    "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter": "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter",
     "Saving…": "Saving…",
     "Save overrides": "Save overrides",
     "Per-entry SEO": "Per-entry SEO",
     "Search appearance": "Search appearance",
     "Title template (must contain %s)": "Title template (must contain %s)",
     "Default meta description": "Default meta description",
-    "Social sharing": "Social sharing",
-    "Default Open Graph / Twitter image": "Default Open Graph / Twitter image",
-    "Twitter @site handle": "Twitter @site handle",
+    "Social preview": "Social preview",
+    "Default preview image": "Default preview image",
+    "X/Twitter @handle": "X/Twitter @handle",
     "Crawling": "Crawling",
     "Default noindex": "Default noindex",
     "Default nofollow": "Default nofollow",
@@ -47,7 +50,7 @@ export const seoMessagesEn = {
     "View sitemap": "View sitemap",
     "Loading SEO settings…": "Loading SEO settings…",
     "Marketing": "Marketing",
-    "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.": "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.",
+    "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.": "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.",
     "Choose image": "Choose image",
     "Remove": "Remove",
     "Sitemap · {count} URLs": "Sitemap · {count} URLs",
@@ -75,5 +78,7 @@ export const seoMessagesEn = {
     "failed to load the sitemap": "failed to load the sitemap",
     "Could not load the sitemap (HTTP {status}).": "Could not load the sitemap (HTTP {status}).",
     "Selected image": "Selected image",
+    "Using site default: {name}": "Using site default: {name}",
+    "Using image from page content: {name}": "Using image from page content: {name}",
 };
 //# sourceMappingURL=messages.en.js.map

package/dist/seo/models.d.ts

@@ -75,6 +75,8 @@ export interface SeoController {
 }
 export interface EntryPickerController {
     entries: readonly AdminPost[] | null;
+    /** Searchable-picker rows (grouped Pages/Posts); null while entries load. */
+    options?: import('./rules.js').SeoEntryPickerOption[] | null;
     error: string | null;
 }
 export interface SeoEntryPanelOptions {
@@ -98,6 +100,9 @@ export interface SeoEntryPanelController {
      *  `null` for each one they emptied. An untouched field is ABSENT, never `null`: "unchanged" must
      *  never become "clear". */
     touched: SeoEntryOverridesPatch;
+    /** The social preview image comes from content or the site default (`ogImageInherited`, rules.ts). Optional
+     *  for injected legacy views. */
+    ogImageInherited?: false | 'default' | 'content';
 }
 export interface SeoEntrySectionController {
     entryId: string;
@@ -153,6 +158,12 @@ 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;
+    /** The chosen file's display name and pixel size (`describeMediaRef`), or null when empty.
+     *  Optional for injected legacy views. */
+    file?: {
+        name: string;
+        size: string | null;
+    } | null;
     /** Shared diagnostics for defaults, OG and Twitter fields; optional for injected legacy views. */
     warning?: string | null;
     onPreviewLoad?: (event: {

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

@@ -1,7 +1,7 @@
 import { useWiredMediaRefField } from "../hooks/MediaRefField.hooks.js";
 /**
- * @file `MediaRefField` — a text input for an `{assetId}:{transformName}` media reference (or a
- * pasted absolute URL), plus a "Choose image" affordance that opens the existing
+ * @file `MediaRefField` — an `{assetId}:{transformName}` media reference (or an absolute URL),
+ * shown as the chosen file's thumbnail and name, plus a "Choose image" affordance that opens the existing
  * `MediaPickerDialog`, a thumbnail preview of the current value, and a Remove control.
  *
  * Built for `react/pages/SeoPage.tsx`'s `defaultOgImage`/`ogImage`/`twitterImage` fields (SPEC intent: "make the OG
@@ -16,11 +16,15 @@ import { useWiredMediaRefField } from "../hooks/MediaRefField.hooks.js";
  * 2026-10-08 polish: the original editable-input rationale above still applies to pasted URLs
  * and empty fields. A selected library reference now shows plain copy with its preview; Remove
  * returns to manual entry. A hidden input preserves the exact FormData value on defaults saves.
+ * 2026-10-15: superseded — the input is removed entirely (owner: the read-only box "looks
+ * useless"). An existing pasted URL still displays (by its file name) and still saves unchanged;
+ * a new URL can no longer be typed here, only chosen from the library.
  */
 export interface MediaRefFieldProps {
     locale: string;
-    /** `<input id>`/`<label htmlFor>` pairing — same `getByLabelText`-friendly shape `react/pages/SeoPage.tsx`'s
-     *  other explicit-`htmlFor` fields already use. */
+    /** Base id: the caption is `{id}-label` and names the row's `role="group"`; the hidden input (when
+     *  `name` is set) carries the id itself. Was an `<input id>`/`<label htmlFor>` pair until the text
+     *  box was removed (2026-10-15). */
     id: string;
     /** Forwarded to the `<input name>` only when set — `defaultOgImage` needs this (its `<form>` reads
      *  `FormData` by name on submit); the per-entry `ogImage`/`twitterImage` fields do not (they save
@@ -32,9 +36,17 @@ export interface MediaRefFieldProps {
     /** This field's own base handle — appended `-choose`/`-clear`/`-dialog` for its own controls, and
      *  forwarded as-is to the `<input>` itself. Omit to leave every element here untagged. */
     agentHandle?: string;
+    /** Shown in the file slot while no image is set — for a field that inherits another field's
+     *  image when empty (the X image falls back to the social preview image). */
+    emptyHint?: string;
+    /** The value comes from the site default or page content, with no SEO override of its own: the file
+     *  shows muted as "Using site default: …" or "Using image from page content: …"; size and Remove
+     *  are hidden — there is no SEO override to remove. "Choose image" is how an override starts
+     *  (owner, 2026-10-15). */
+    inherited?: false | 'default' | 'content';
     /** Injectable seam for the picker's own state — same convention as `MediaPickerDialog`'s own
      *  `useDialog` prop. Defaults to the real {@link useWiredMediaRefField}. */
     useField?: typeof useWiredMediaRefField;
 }
-export declare function MediaRefField({ locale, id, name, label, value, onChange, agentHandle: base, useField, }: MediaRefFieldProps, _optional?: Record<string, never>): import("react").JSX.Element;
+export declare function MediaRefField({ locale, id, name, label, value, onChange, agentHandle: base, emptyHint, inherited, useField, }: MediaRefFieldProps, _optional?: Record<string, never>): import("react").JSX.Element;
 //# sourceMappingURL=MediaRefField.d.ts.map

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

@@ -1,12 +1,22 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { agentHandle } from "@jini-ai/agentic";
+import { interpolate } from "@jini-ai/ui/i18n";
 import { MediaPickerBridge } from "./MediaPickerBridge.js";
 import { useSeoCopy } from "../hooks/SeoPorts.hooks.js";
 import { useWiredMediaRefField, useMediaRefPresentation, handleSpread } from "../hooks/MediaRefField.hooks.js";
-export function MediaRefField({ locale, id, name, label, value, onChange, agentHandle: base, useField = useWiredMediaRefField, }, _optional = {}) {
+export function MediaRefField({ locale, id, name, label, value, onChange, agentHandle: base, emptyHint, inherited = false, useField = useWiredMediaRefField, }, _optional = {}) {
     const t = useSeoCopy();
-    const { Picker = MediaPickerBridge, storedReference } = useMediaRefPresentation({ value });
-    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] }));
+    const { Picker = MediaPickerBridge } = useMediaRefPresentation({ value });
+    const { pickerOpen, openPicker, closePicker, handleSelect, clear, previewUrl, file, accept, onPreviewLoad, onPreviewError } = useField({ value, onChange });
+    const labelId = `${id}-label`;
+    /* One compact row: thumbnail, the file's name and size, then Choose/Remove kept together in their
+       own group so a narrow column wraps the pair as one unit instead of stranding Remove on a line of
+       its own (owner, 2026-10-15). The thumbnail used to sit under the row at 4rem, repeated per field.
+       `warning` (share-image size/byte/HTTP diagnostics) is still computed by the hook but no longer
+       painted: the owner called the yellow callout under every image "completely useless".
+       2026-10-15 (round 3): the text box is gone — for a library pick it only ever said a read-only
+       "Selected image" ("i can't change it and looks useless"), so the row names the file instead and
+       the picker is the one way in. The exact value still rides a hidden input for FormData saves. */
+    return (_jsxs("div", { className: "jini-field jini-media-ref-field", children: [_jsx("span", { className: "jini-field-label", id: labelId, children: label }), _jsxs("div", { className: "jini-media-ref-field-row", role: "group", "aria-labelledby": labelId, ...(base ? agentHandle({ handle: base }, { role: "region", label }) : {}), children: [file ? (_jsxs("span", { className: inherited ? "jini-media-ref-field-file jini-media-ref-field-file-inherited" : "jini-media-ref-field-file", children: [previewUrl ? _jsx("img", { className: "jini-media-ref-field-preview", src: previewUrl, alt: `${label} preview`, onLoad: onPreviewLoad, onError: onPreviewError }, previewUrl) : null, _jsx("span", { className: "jini-media-ref-field-name", title: file.name, children: inherited ? interpolate({ template: t({ locale: locale, key: inherited === 'content' ? "Using image from page content: {name}" : "Using site default: {name}", vars: { name: file.name } }), vars: { name: file.name } }) : file.name }), file.size && !inherited ? _jsx("span", { className: "jini-media-ref-field-size", children: file.size }) : null] })) : (emptyHint && _jsx("span", { className: "jini-media-ref-field-empty", children: emptyHint })), name ? _jsx("input", { type: "hidden", id: id, name: name, value: value }) : null, _jsxs("span", { className: "jini-media-ref-field-actions", children: [_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 && !inherited ? (_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] })] }), 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.js

@@ -3,16 +3,24 @@ 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 { describeMediaRef, isStoredMediaRef, resolveMediaRefPreviewUrl } from '../../rules.js';
+import { useFetchQuery } from '@jini-ai/ui/fetch-query';
+import { extensionForMimeType } from '@jini-ai/ui';
+import { SEO_KEYS } from './SeoQuery.hooks.js';
 import { useSeoPorts, useSeoOptions } from './SeoPorts.hooks.js';
 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 });
+    const { naturalWidth, naturalHeight, ...diagnostics } = useShareImageWarning({ value, previewUrl, api }, { t });
+    // One cached library read shared by every image field on the screen; only a library reference
+    // needs it (a URL names itself), and a host without `listSeoMedia` falls back to the slug.
+    const list = api.listSeoMedia;
+    const media = useFetchQuery({ key: SEO_KEYS.media, fetch: () => list ? list.call(api, {}) : Promise.resolve([]) }, { enabled: Boolean(list) && isStoredMediaRef({ value }) });
     return {
         ...diagnostics,
+        file: describeMediaRef({ value, media: media.data }, { width: naturalWidth, height: naturalHeight, t, extensionFor: extensionForMimeType }),
         pickerOpen: snapshot?.pickerOpen ?? false,
         openPicker: () => controller?.openPicker({}), closePicker: () => controller?.closePicker({}),
         handleSelect: item => controller?.handleSelect({ item }), clear: () => controller?.clear({}),

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

@@ -29,6 +29,7 @@ export declare function useAnalyzePanel({ analysis }: {
     analysis: SeoEntryAnalysis;
 }, _optional?: Record<string, never>): {
     sortedIssues: import("../../../core/index.js").AdminSeoIssue[];
+    tone: "warning" | "success" | "failure";
 };
 /** All seven defaults remain in one FormData submission; tabs never split this form. */
 export declare function useSeoDefaults({ save }: {

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

@@ -1,6 +1,6 @@
 import { createElement } from 'react';
 import { SeoDefaultsIcon, SeoSitemapIcon, SeoEntriesIcon } from '../components/SeoIcons.js';
-import { buildSeoSettingsPatch, resolveSeoTabId, sortIssuesBySeverity } from '../../rules.js';
+import { buildSeoSettingsPatch, resolveSeoTabId, sortIssuesBySeverity, scoreTone } from '../../rules.js';
 import { useSeoOptions } from './SeoPorts.hooks.js';
 export { buildSeoSettingsPatch, resolveSeoTabId } from '../../rules.js';
 export function resolveSeoTabs(_required = {}, { t = key => key } = {}) {
@@ -20,7 +20,7 @@ export function useSeoTabs({ tabId }, _optional = {}) {
     return { activeTabId: resolveSeoTabId({ tabId }), tabs: resolveSeoTabs({}, { t }) };
 }
 export function useAnalyzePanel({ analysis }, _optional = {}) {
-    return { sortedIssues: sortIssuesBySeverity({ issues: analysis.issues }) };
+    return { sortedIssues: sortIssuesBySeverity({ issues: analysis.issues }), tone: scoreTone({ score: analysis.score }) };
 }
 /** All seven defaults remain in one FormData submission; tabs never split this form. */
 export function useSeoDefaults({ save }, _optional = {}) {

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

@@ -8,6 +8,7 @@ export declare const SEO_KEYS: {
     }, _optional?: Record<string, never>) => readonly ["seo", "entry", string];
     choices: readonly ["seo", "choices"];
     sitemap: readonly ["seo", "sitemap"];
+    media: readonly ["seo", "media"];
 };
 /** 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.

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

@@ -7,6 +7,7 @@ export const SEO_KEYS = {
     entry: ({ entryId }, _optional = {}) => ['seo', 'entry', entryId],
     choices: ['seo', 'choices'],
     sitemap: ['seo', 'sitemap'],
+    media: ['seo', 'media'],
 };
 /** 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.

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

@@ -2,13 +2,18 @@ import { describeSeoError } from '../../models.js';
 import { useFetchQuery } from '@jini-ai/ui/fetch-query';
 import { SEO_KEYS } from './SeoQuery.hooks.js';
 import { initialEntryPickerState } from '../../models.js';
+import { entryPickerOptions } from '../../rules.js';
 import { useSeoOptions, useSeoPorts } from './SeoPorts.hooks.js';
 export function useEntryPicker({ api }, { t, describeError } = {}) {
     const query = useFetchQuery({ key: SEO_KEYS.choices, fetch: async () => {
             const [posts, pages] = await Promise.all([api.listSeoPosts({}), api.listSeoPages({})]);
-            return [...posts, ...pages];
+            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 };
+    const data = query.data;
+    return { ...initialEntryPickerState,
+        entries: data ? [...data.posts, ...data.pages] : null,
+        options: data ? entryPickerOptions(data, { t }) : 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,9 +1,11 @@
 import { describeSeoError } from '../../models.js';
 import { useEffect, useRef } from 'react';
-import { useSeoEntryQuery } from './SeoQuery.hooks.js';
+import { useSeoEntryQuery, SEO_KEYS } from './SeoQuery.hooks.js';
+import { useFetchQuery } from '@jini-ai/ui/fetch-query';
 import { useController } from '../../../core/react/use-controller.js';
 import { createSeoEntryController } from '../../controllers/seo-entry.controller.js';
 import { initialSeoEntryState } from '../../models.js';
+import { inheritedXFor, ogImageInherited } from '../../rules.js';
 import { useSeoOptions, useSeoPorts } from './SeoPorts.hooks.js';
 export function useSeoEntryPanel({ api, entryId }, { t, describeError } = {}) {
     const cached = useSeoEntryQuery({ api, entryId });
@@ -17,11 +19,20 @@ export function useSeoEntryPanel({ api, entryId }, { t, describeError } = {}) {
         if (controller && cached.query.data)
             controller.set({ patch: cached.query.data });
     }, [controller, cached.query.data]);
+    // The site defaults read the Site defaults tab already caches; only the default image is used here.
+    const settings = useFetchQuery({ key: SEO_KEYS.settings, fetch: () => api.getSeoSettings({}) });
     const state = snapshot ?? initialSeoEntryState;
     return {
         ...state,
+        ogImageInherited: state.resolved ? ogImageInherited({ meta: state.resolved, defaultOgImage: settings.data?.defaultOgImage, touched: state.touched }) : false,
         fieldValue: (key, resolvedValue) => controller ? controller.fieldValue({ key, resolvedValue }) : resolvedValue,
-        setField: (key, value) => controller?.setField({ key, value }),
+        setField: (key, value) => {
+            // An edit to the social preview also clears an X field that was following it (rules.ts).
+            const xKey = state.resolved ? inheritedXFor({ key, meta: state.resolved, touched: state.touched }) : null;
+            controller?.setField({ key, value });
+            if (xKey)
+                controller?.setField({ key: xKey, value: '' });
+        },
         save: async () => { await controller?.save({}); },
     };
 }

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

@@ -15,5 +15,8 @@ export declare function useShareImageWarning({ value, previewUrl, api }: {
     api: AdminSeoPort;
 }, { t }?: {
     t?: SeoTranslator | undefined;
-}): Pick<MediaRefFieldController, 'warning' | 'onPreviewLoad' | 'onPreviewError'>;
+}): Pick<MediaRefFieldController, 'warning' | 'onPreviewLoad' | 'onPreviewError'> & {
+    naturalWidth?: number | undefined;
+    naturalHeight?: number | undefined;
+};
 //# sourceMappingURL=use-share-image-warning.hooks.d.ts.map

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

@@ -62,6 +62,7 @@ export function useShareImageWarning({ value, previewUrl, api }, { t = key => ke
     const checked = inspection?.url === previewUrl ? inspection : null;
     const error = checked?.error;
     return {
+        naturalWidth: source?.width, naturalHeight: source?.height,
         warning: shareImageWarning({ value, previewUrl, width: source?.width, height: source?.height, previewFailed: source?.failed, byteSize: checked?.byteSize,
             error: error ? interpolate({ template: t(error.key, error.vars), vars: error.vars ?? {} }) : undefined }, { t }),
         onPreviewLoad: ({ currentTarget }) => {

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

@@ -36,21 +36,24 @@ export declare function seo({ siteUrl }: Pick<SeoReactOptions, 'siteUrl'>, optio
         readonly "Canonical URL": "Canonical URL";
         readonly Noindex: "Noindex";
         readonly Nofollow: "Nofollow";
-        readonly "OG title": "OG title";
-        readonly "OG description": "OG description";
-        readonly "OG image": "OG image";
-        readonly "Twitter title": "Twitter title";
-        readonly "Twitter description": "Twitter description";
-        readonly "Twitter image": "Twitter image";
+        readonly "Preview title": "Preview title";
+        readonly "Preview description": "Preview description";
+        readonly "Preview image": "Preview image";
+        readonly "X/Twitter title": "X/Twitter title";
+        readonly "X/Twitter description": "X/Twitter description";
+        readonly "X/Twitter image": "X/Twitter image";
+        readonly "Customize for X/Twitter (optional)": "Customize for X/Twitter (optional)";
+        readonly "Same as the preview image": "Same as the preview image";
+        readonly "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter": "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter";
         readonly "Saving\u2026": "Saving…";
         readonly "Save overrides": "Save overrides";
         readonly "Per-entry SEO": "Per-entry SEO";
         readonly "Search appearance": "Search appearance";
         readonly "Title template (must contain %s)": "Title template (must contain %s)";
         readonly "Default meta description": "Default meta description";
-        readonly "Social sharing": "Social sharing";
-        readonly "Default Open Graph / Twitter image": "Default Open Graph / Twitter image";
-        readonly "Twitter @site handle": "Twitter @site handle";
+        readonly "Social preview": "Social preview";
+        readonly "Default preview image": "Default preview image";
+        readonly "X/Twitter @handle": "X/Twitter @handle";
         readonly Crawling: "Crawling";
         readonly "Default noindex": "Default noindex";
         readonly "Default nofollow": "Default nofollow";
@@ -63,7 +66,7 @@ export declare function seo({ siteUrl }: Pick<SeoReactOptions, 'siteUrl'>, optio
         readonly "View sitemap": "View sitemap";
         readonly "Loading SEO settings\u2026": "Loading SEO settings…";
         readonly Marketing: "Marketing";
-        readonly "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.": "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.";
+        readonly "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.": "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.";
         readonly "Choose image": "Choose image";
         readonly Remove: "Remove";
         readonly "Sitemap \u00B7 {count} URLs": "Sitemap · {count} URLs";
@@ -91,6 +94,8 @@ export declare function seo({ siteUrl }: Pick<SeoReactOptions, 'siteUrl'>, optio
         readonly "failed to load the sitemap": "failed to load the sitemap";
         readonly "Could not load the sitemap (HTTP {status}).": "Could not load the sitemap (HTTP {status}).";
         readonly "Selected image": "Selected image";
+        readonly "Using site default: {name}": "Using site default: {name}";
+        readonly "Using image from page content: {name}": "Using image from page content: {name}";
     };
     pages: {
         readonly settings: {
@@ -158,21 +163,24 @@ export declare function seo({ siteUrl }: Pick<SeoReactOptions, 'siteUrl'>, optio
                 readonly "Canonical URL": "Canonical URL";
                 readonly Noindex: "Noindex";
                 readonly Nofollow: "Nofollow";
-                readonly "OG title": "OG title";
-                readonly "OG description": "OG description";
-                readonly "OG image": "OG image";
-                readonly "Twitter title": "Twitter title";
-                readonly "Twitter description": "Twitter description";
-                readonly "Twitter image": "Twitter image";
+                readonly "Preview title": "Preview title";
+                readonly "Preview description": "Preview description";
+                readonly "Preview image": "Preview image";
+                readonly "X/Twitter title": "X/Twitter title";
+                readonly "X/Twitter description": "X/Twitter description";
+                readonly "X/Twitter image": "X/Twitter image";
+                readonly "Customize for X/Twitter (optional)": "Customize for X/Twitter (optional)";
+                readonly "Same as the preview image": "Same as the preview image";
+                readonly "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter": "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter";
                 readonly "Saving\u2026": "Saving…";
                 readonly "Save overrides": "Save overrides";
                 readonly "Per-entry SEO": "Per-entry SEO";
                 readonly "Search appearance": "Search appearance";
                 readonly "Title template (must contain %s)": "Title template (must contain %s)";
                 readonly "Default meta description": "Default meta description";
-                readonly "Social sharing": "Social sharing";
-                readonly "Default Open Graph / Twitter image": "Default Open Graph / Twitter image";
-                readonly "Twitter @site handle": "Twitter @site handle";
+                readonly "Social preview": "Social preview";
+                readonly "Default preview image": "Default preview image";
+                readonly "X/Twitter @handle": "X/Twitter @handle";
                 readonly Crawling: "Crawling";
                 readonly "Default noindex": "Default noindex";
                 readonly "Default nofollow": "Default nofollow";
@@ -185,7 +193,7 @@ export declare function seo({ siteUrl }: Pick<SeoReactOptions, 'siteUrl'>, optio
                 readonly "View sitemap": "View sitemap";
                 readonly "Loading SEO settings\u2026": "Loading SEO settings…";
                 readonly Marketing: "Marketing";
-                readonly "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.": "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.";
+                readonly "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.": "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.";
                 readonly "Choose image": "Choose image";
                 readonly Remove: "Remove";
                 readonly "Sitemap \u00B7 {count} URLs": "Sitemap · {count} URLs";
@@ -213,6 +221,8 @@ export declare function seo({ siteUrl }: Pick<SeoReactOptions, 'siteUrl'>, optio
                 readonly "failed to load the sitemap": "failed to load the sitemap";
                 readonly "Could not load the sitemap (HTTP {status}).": "Could not load the sitemap (HTTP {status}).";
                 readonly "Selected image": "Selected image";
+                readonly "Using site default: {name}": "Using site default: {name}";
+                readonly "Using image from page content: {name}": "Using image from page content: {name}";
             };
             readonly pages: {
                 readonly settings: {
@@ -281,21 +291,24 @@ export declare function seo({ siteUrl }: Pick<SeoReactOptions, 'siteUrl'>, optio
                 readonly "Canonical URL": "Canonical URL";
                 readonly Noindex: "Noindex";
                 readonly Nofollow: "Nofollow";
-                readonly "OG title": "OG title";
-                readonly "OG description": "OG description";
-                readonly "OG image": "OG image";
-                readonly "Twitter title": "Twitter title";
-                readonly "Twitter description": "Twitter description";
-                readonly "Twitter image": "Twitter image";
+                readonly "Preview title": "Preview title";
+                readonly "Preview description": "Preview description";
+                readonly "Preview image": "Preview image";
+                readonly "X/Twitter title": "X/Twitter title";
+                readonly "X/Twitter description": "X/Twitter description";
+                readonly "X/Twitter image": "X/Twitter image";
+                readonly "Customize for X/Twitter (optional)": "Customize for X/Twitter (optional)";
+                readonly "Same as the preview image": "Same as the preview image";
+                readonly "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter": "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter";
                 readonly "Saving\u2026": "Saving…";
                 readonly "Save overrides": "Save overrides";
                 readonly "Per-entry SEO": "Per-entry SEO";
                 readonly "Search appearance": "Search appearance";
                 readonly "Title template (must contain %s)": "Title template (must contain %s)";
                 readonly "Default meta description": "Default meta description";
-                readonly "Social sharing": "Social sharing";
-                readonly "Default Open Graph / Twitter image": "Default Open Graph / Twitter image";
-                readonly "Twitter @site handle": "Twitter @site handle";
+                readonly "Social preview": "Social preview";
+                readonly "Default preview image": "Default preview image";
+                readonly "X/Twitter @handle": "X/Twitter @handle";
                 readonly Crawling: "Crawling";
                 readonly "Default noindex": "Default noindex";
                 readonly "Default nofollow": "Default nofollow";
@@ -308,7 +321,7 @@ export declare function seo({ siteUrl }: Pick<SeoReactOptions, 'siteUrl'>, optio
                 readonly "View sitemap": "View sitemap";
                 readonly "Loading SEO settings\u2026": "Loading SEO settings…";
                 readonly Marketing: "Marketing";
-                readonly "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.": "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.";
+                readonly "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.": "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.";
                 readonly "Choose image": "Choose image";
                 readonly Remove: "Remove";
                 readonly "Sitemap \u00B7 {count} URLs": "Sitemap · {count} URLs";
@@ -336,6 +349,8 @@ export declare function seo({ siteUrl }: Pick<SeoReactOptions, 'siteUrl'>, optio
                 readonly "failed to load the sitemap": "failed to load the sitemap";
                 readonly "Could not load the sitemap (HTTP {status}).": "Could not load the sitemap (HTTP {status}).";
                 readonly "Selected image": "Selected image";
+                readonly "Using site default: {name}": "Using site default: {name}";
+                readonly "Using image from page content: {name}": "Using image from page content: {name}";
             };
             readonly pages: {
                 readonly settings: {

package/dist/seo/react/pages/SeoPage.d.ts

@@ -65,6 +65,8 @@ import { useWiredSeo } from "../hooks/use-seo.hooks.js";
  */
 export interface SeoSectionProps {
     title: string;
+    /** Optional ⓘ explanation beside the title (explanations are tips, never loose paragraphs). */
+    tip?: string;
     children: ReactNode;
 }
 export interface EntryPickerProps {

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

@@ -2,8 +2,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useAnalyzePanel, useSeoDefaults, useSeoTabs, seoTabPanel } from "../hooks/SeoPage.hooks.js";
 import { agentHandle } from "@jini-ai/agentic";
 import { TabBar } from "@jini-ai/ui/tab-strip";
+import { InfoTip, Select } from "@jini-ai/ui/admin-widgets";
 import { useSeoCopy, useSeoOptions } from "../hooks/SeoPorts.hooks.js";
-import { actionLabel, orEmpty } from "../../rules.js";
+import { actionLabel, orEmpty, xIsCustomized, xResolvedValue } from "../../rules.js";
 import { useWiredEntryPicker } from "../hooks/use-entry-picker.hooks.js";
 import { useWiredSeoEntryPanel } from "../hooks/use-seo-entry-panel.hooks.js";
 import { useSeoEntrySection } from "../hooks/use-seo-entry-section.hooks.js";
@@ -29,31 +30,27 @@ import { SitemapModal } from "../components/SitemapModal.js";
  * overrides", which sits INSIDE the "Per-entry SEO" section — keeps its own `<h3>` and is not
  * routed through here.
  */
-function SeoSection({ title, children }) {
-    return (_jsxs("section", { className: "jini-seo-section", children: [_jsx("div", { className: "jini-seo-section-head", children: _jsx("h2", { className: "jini-seo-section-title", children: title }) }), _jsx("div", { className: "jini-seo-section-body", children: children })] }));
+function SeoSection({ title, tip, children }) {
+    return (_jsxs("section", { className: "jini-seo-section", children: [_jsx("div", { className: "jini-seo-section-head", children: _jsxs("h2", { className: "jini-seo-section-title", children: [title, tip ? _jsx(InfoTip, { label: tip }) : null] }) }), _jsx("div", { className: "jini-seo-section-body", children: children })] }));
 }
-/** Dropdown over every post + page, sourced from the already-existing `listPosts`/`listPages`
- * routes — cheapest entry-selection UX available given what's already built (REQ-06). */
+/** Searchable picker over every page + post, sourced from the already-existing `listPosts`/`listPages`
+ * routes (REQ-06). It was a native `<select>`; with a few dozen entries that opened as one tall OS
+ * list with "(published)" after every row (owner, 2026-10-15: "we have a searchable dropdown
+ * right?"). The shared admin-widgets `Select` already types-to-filter and handles the keyboard, so
+ * rows are just grouped Pages/Posts with a pill only for the non-published exceptions
+ * (`entryPickerOptions` in `rules.ts`). */
 function EntryPicker({ locale, entryId, onChange, useEntryPickerHook = useWiredEntryPicker }) {
     const t = useSeoCopy();
-    const { entries, error } = useEntryPickerHook();
+    const { entries, options, error } = useEntryPickerHook();
     if (error)
         return _jsx("div", { className: "jini-notice jini-notice-error", children: error });
     if (!entries)
         return _jsx("div", { className: "jini-notice", children: t({ locale: locale, key: "Loading entries…" }) });
     /* The "Entry" caption is no longer painted (owner, 2026-09-06: "you can actually just get rid of
-       'Entry'") — the placeholder option already says "Choose an entry…", so the visible word was
-       saying it twice, and with no gap between the two it read as one smashed-together control.
-       It stays a REAL label rather than becoming a placeholder-only select: this is the exact
-       `<label class="a11y-label-wrap">` + `.visually-hidden` idiom `styles/editor.css` documents for
-       the four controls a previous accessibility pass found unnamed — including, by name, a
-       `<select>` with no accessible name at all. `display: contents` drops the wrapper's own box, so
-       the select keeps the section body's sizing exactly as if the label were not there.
-       The i18n key is unchanged and still passed through `t`, so nothing dangles. */
-    return (_jsxs("label", { className: "jini-a11y-label-wrap", children: [_jsx("span", { className: "jini-visually-hidden", children: t({ locale: locale, key: "Entry" }) }), _jsxs("select", { className: "jini-select", value: entryId, onChange: (e) => onChange(e.target.value), ...agentHandle({ handle: "seo-entry-picker" }, {
-                    role: "field",
-                    label: "Choose which page or post to edit or analyze SEO for",
-                }), children: [_jsx("option", { value: "", children: t({ locale: locale, key: "Choose an entry…" }) }), entries.map((entry) => (_jsxs("option", { value: entry.id, children: [entry.title, " (", entry.status, ")"] }, entry.id)))] })] }));
+       'Entry'") — the placeholder already says "Choose an entry…", so the visible word was saying it
+       twice. It stays the control's accessible name (now `aria-label` on the combobox trigger) rather
+       than leaving a placeholder-only control with no name at all. The i18n key is unchanged. */
+    return (_jsx("div", { className: "jini-seo-entry-picker", children: _jsx(Select, { value: entryId, onChange: onChange, options: options ?? [], placeholder: t({ locale: locale, key: "Choose an entry…" }), "aria-label": t({ locale: locale, key: "Entry" }), agentHandle: "seo-entry-picker", translate: (key) => t({ locale, key }) }) }));
 }
 /** Read-only score + issues view (REQ-07) — exact field names read off `SeoAnalysis`/`SeoIssue`
  * (`src/seo/types.ts`), not guessed. No state of its own — only the severity sort, which lives in
@@ -61,8 +58,11 @@ function EntryPicker({ locale, entryId, onChange, useEntryPickerHook = useWiredE
 function AnalyzePanel(props) {
     const t = useSeoCopy();
     const { locale } = props;
-    const { sortedIssues } = useAnalyzePanel({ analysis: props.analysis });
-    return (_jsxs("div", { className: "jini-seo-analyze-panel", children: [_jsx("h3", { children: t({ locale: locale, key: "Analysis" }) }), _jsxs("p", { children: [t({ locale: locale, key: "Score:" }), " ", _jsx("strong", { children: props.analysis.score })] }), sortedIssues.length === 0 ? (_jsx("p", { className: "jini-muted-cell", children: t({ locale: locale, key: "No issues." }) })) : (_jsx("ul", { children: sortedIssues.map((issue, i) => (_jsxs("li", { children: [_jsx("span", { className: `jini-status jini-status-${issue.severity === "error" ? "failure" : issue.severity === "warning" ? "unavailable" : "success"}`, children: issue.severity }), " ", _jsx("code", { children: issue.code }), issue.field ? _jsxs("span", { className: "jini-muted-cell", children: [" (", issue.field, ")"] }) : null, " \u2014 ", issue.message] }, `${issue.code}-${i}`))) }))] }));
+    const { sortedIssues, tone } = useAnalyzePanel({ analysis: props.analysis });
+    /* Heading + score pill on one line, issues as a compact list (owner, 2026-10-15: the bare
+       "Score: 100 / No issues." read as unstyled text). The pill reuses the issue pills' status
+       tones, so the score and the issues under it speak one colour language. */
+    return (_jsxs("section", { className: "jini-seo-analyze-panel", "aria-labelledby": "seo-analysis-heading", children: [_jsxs("div", { className: "jini-seo-analyze-head", children: [_jsx("h3", { id: "seo-analysis-heading", children: t({ locale: locale, key: "Analysis" }) }), _jsxs("span", { className: `jini-status jini-status-${tone} jini-seo-score`, children: [t({ locale: locale, key: "Score:" }), " ", _jsx("strong", { children: props.analysis.score })] })] }), sortedIssues.length === 0 ? (_jsx("p", { className: "jini-seo-analyze-empty", children: t({ locale: locale, key: "No issues." }) })) : (_jsx("ul", { className: "jini-seo-issues", children: sortedIssues.map((issue, i) => (_jsxs("li", { className: "jini-seo-issue", children: [_jsx("span", { className: `jini-status jini-status-${issue.severity === "error" ? "failure" : issue.severity === "warning" ? "warning" : "success"}`, children: issue.severity }), _jsxs("span", { className: "jini-seo-issue-text", children: [issue.message, issue.field ? _jsxs("span", { className: "jini-muted-cell", children: [" (", issue.field, ")"] }) : null] })] }, `${issue.code}-${i}`))) }))] }));
 }
 /** Per-entry overrides edit form (REQ-06). Pre-fills from `getSeoEntry`'s resolved meta, but
  * tracks which fields the user actually touched so `putSeoEntry` only ever sends a genuine
@@ -80,14 +80,16 @@ function AnalyzePanel(props) {
 // the ceiling on their own. There is nothing to extract: splitting the eleven fields into their own
 // components would still evaluate the same fallback chains, just spread across more functions, for
 // no complexity benefit and a real loss of "one form, one place to read its fields."
+// 2026-10-15: now 27 — the X fields' placeholders (the live social preview value) add two more
+// flat `??` fallbacks of exactly that kind.
 function SeoEntryPanel({ locale, entryId, useSeoEntryPanelHook = useWiredSeoEntryPanel }) {
     const t = useSeoCopy();
-    const { resolved, analysis, loadError, saving, saveError, notice, fieldValue, setField, save, touched } = useSeoEntryPanelHook({ entryId });
+    const { resolved, analysis, loadError, saving, saveError, notice, fieldValue, setField, save, touched, ogImageInherited = false } = useSeoEntryPanelHook({ entryId });
     if (loadError)
         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.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] }));
+    return (_jsxs("div", { className: "jini-seo-entry-panel", children: [_jsx("div", { className: "jini-seo-entry-head", children: _jsxs("div", { className: "jini-seo-entry-head-bar", children: [_jsx("h3", { children: t({ locale: locale, key: "Per-entry overrides" }) }), _jsx(InfoTip, { label: `${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." })}` }), _jsx("span", { className: "jini-seo-entry-head-actions", children: _jsx("button", { type: "button", className: "jini-btn", 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" }) }) })] }) }), notice ? _jsx("div", { className: "jini-notice", children: notice }) : null, saveError ? (_jsx("div", { className: "jini-notice jini-notice-error", role: "alert", children: saveError })) : null, _jsxs("fieldset", { className: "jini-seo-entry-group", children: [_jsx("legend", { children: t({ locale: locale, key: "Search appearance" }) }), _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("div", { className: "jini-seo-entry-checks", children: [_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("fieldset", { className: "jini-seo-entry-group", children: [_jsxs("legend", { children: [t({ locale: locale, key: "Social preview" }), _jsx(InfoTip, { label: t({ locale: locale, key: "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter" }) })] }), _jsxs("label", { children: [t({ locale: locale, key: "Preview 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: "Preview 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: "Preview image" }), value: fieldValue("ogImage", resolved.openGraph.imageRef ?? resolved.openGraph.image ?? "") ?? "", onChange: (value) => setField("ogImage", value), inherited: ogImageInherited, agentHandle: "seo-entry-og-image" }), _jsxs("details", { className: "jini-seo-x-disclosure", open: xIsCustomized({ meta: resolved }), children: [_jsx("summary", { children: t({ locale: locale, key: "Customize for X/Twitter (optional)" }) }), _jsxs("div", { className: "jini-seo-x-fields", children: [_jsxs("label", { children: [t({ locale: locale, key: "X/Twitter title" }), _jsx("input", { className: "jini-input", value: fieldValue("twitterTitle", xResolvedValue({ key: "twitterTitle", meta: resolved })) ?? "", placeholder: fieldValue("ogTitle", resolved.openGraph.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: "X/Twitter description" }), _jsx("input", { className: "jini-input", value: fieldValue("twitterDescription", xResolvedValue({ key: "twitterDescription", meta: resolved })) ?? "", placeholder: fieldValue("ogDescription", resolved.openGraph.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: "X/Twitter image" }), value: fieldValue("twitterImage", xResolvedValue({ key: "twitterImage", meta: resolved })) ?? "", emptyHint: t({ locale: locale, key: "Same as the preview image" }), onChange: (value) => setField("twitterImage", value), agentHandle: "seo-entry-twitter-image" })] })] })] }), 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
@@ -139,7 +141,7 @@ export function SeoDefaultsTab({ controller }, _optional = {}) {
                                 }) })] }), _jsxs("div", { className: "jini-field", children: [_jsx("label", { className: "jini-field-label", htmlFor: "seo-default-description", children: t({ locale: locale, key: "Default meta description" }) }), _jsx("textarea", { className: "jini-textarea", id: "seo-default-description", name: "defaultDescription", defaultValue: orEmpty({ value: settings.defaultDescription }), ...agentHandle({ handle: "seo-default-description" }, {
                                     role: "field",
                                     label: "Fallback meta description for pages that set none of their own",
-                                }) })] })] }), _jsxs(SeoSection, { title: t({ locale: locale, key: "Social sharing" }), children: [_jsx(MediaRefField, { locale: locale, id: "seo-default-og-image", name: "defaultOgImage", label: t({ locale: locale, key: "Default Open Graph / Twitter image" }), value: defaultOgImage, onChange: setDefaultOgImage, agentHandle: "seo-default-og-image" }), _jsxs("div", { className: "jini-field", children: [_jsx("label", { className: "jini-field-label", htmlFor: "seo-twitter-site", children: t({ locale: locale, key: "Twitter @site handle" }) }), _jsx("input", { className: "jini-input", id: "seo-twitter-site", name: "twitterSite", defaultValue: orEmpty({ value: settings.twitterSite }), ...agentHandle({ handle: "seo-twitter-site" }, {
+                                }) })] })] }), _jsxs(SeoSection, { title: t({ locale: locale, key: "Social preview" }), tip: t({ locale: locale, key: "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter" }), children: [_jsx(MediaRefField, { locale: locale, id: "seo-default-og-image", name: "defaultOgImage", label: t({ locale: locale, key: "Default preview image" }), value: defaultOgImage, onChange: setDefaultOgImage, agentHandle: "seo-default-og-image" }), _jsxs("div", { className: "jini-field", children: [_jsx("label", { className: "jini-field-label", htmlFor: "seo-twitter-site", children: t({ locale: locale, key: "X/Twitter @handle" }) }), _jsx("input", { className: "jini-input", id: "seo-twitter-site", name: "twitterSite", defaultValue: orEmpty({ value: settings.twitterSite }), ...agentHandle({ handle: "seo-twitter-site" }, {
                                     role: "field",
                                     label: "The site's Twitter @handle, used in Twitter card metadata",
                                 }) })] })] }), _jsxs(SeoSection, { title: t({ locale: locale, key: "Crawling" }), children: [_jsxs("label", { className: "jini-form-checkbox-field", children: [_jsx("input", { className: "jini-input", type: "checkbox", name: "noindex", defaultChecked: settings.defaultRobots.noindex, ...agentHandle({ handle: "seo-default-noindex" }, {
@@ -208,7 +210,7 @@ export function Seo({ tabId, onTabChange, useSeoHook = useWiredSeo } = {}, _opti
         regenerateSitemap,
         openSitemapModal,
     };
-    return (_jsxs("div", { className: "jini-page jini-seo-page", children: [_jsxs("div", { className: "jini-page-header", children: [_jsxs("div", { className: "jini-page-header-text", children: [_jsx("p", { className: "jini-page-kicker", children: t({ locale: locale, key: "Marketing" }) }), _jsx("h1", { className: "jini-page-title", children: "SEO" }), _jsx("p", { className: "jini-page-description", children: t({ locale: locale, key: "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives." }) })] }), _jsx("div", { className: "jini-page-actions", children: headerActions })] }), error ? _jsx("div", { className: "jini-notice jini-notice-error", children: error }) : null, notice ? _jsx("div", { className: "jini-notice", children: notice }) : null, _jsx(TabBar, { ariaLabel: "SEO", tabs: tabs, activeId: activeTabId, onChange: changeTab, containerHandle: "seo-tab-bar" }), seoTabPanel({ activeTabId, controller, components: { SeoDefaultsTab, SeoSitemapTab, SeoEntrySection } }), sitemapModalOpen ? (_jsx(SitemapModal, { locale: locale, sitemapEnabled: settings.sitemapEnabled, regenerating: saving, onRegenerate: regenerateSitemap, onClose: closeSitemapModal })) : null] }));
+    return (_jsxs("div", { className: "jini-page jini-seo-page", children: [_jsxs("div", { className: "jini-page-header", children: [_jsxs("div", { className: "jini-page-header-text", children: [_jsx("p", { className: "jini-page-kicker", children: t({ locale: locale, key: "Marketing" }) }), _jsx("h1", { className: "jini-page-title", children: "SEO" }), _jsx("p", { className: "jini-page-description", children: t({ locale: locale, key: "Site-wide defaults for meta titles, descriptions, social previews, and robots directives." }) })] }), _jsx("div", { className: "jini-page-actions", children: headerActions })] }), error ? _jsx("div", { className: "jini-notice jini-notice-error", children: error }) : null, notice ? _jsx("div", { className: "jini-notice", children: notice }) : null, _jsx(TabBar, { ariaLabel: "SEO", tabs: tabs, activeId: activeTabId, onChange: changeTab, containerHandle: "seo-tab-bar" }), seoTabPanel({ activeTabId, controller, components: { SeoDefaultsTab, SeoSitemapTab, SeoEntrySection } }), sitemapModalOpen ? (_jsx(SitemapModal, { locale: locale, sitemapEnabled: settings.sitemapEnabled, regenerating: saving, onRegenerate: regenerateSitemap, onClose: closeSitemapModal })) : null] }));
 }
 export { Seo as SeoPage };
 export default Seo;

package/dist/seo/rules.d.ts

@@ -1,5 +1,6 @@
 import type { AdminSeoIssue as SeoIssue, AdminSeoSettingsPatch as SeoSettingsPatch } from "../core/ports/seo.js";
 import type { SeoTranslator } from './models.js';
+import type { AdminSeoEntryChoice, AdminSeoMediaSummary, AdminSeoMeta } from '../core/ports/seo.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
@@ -37,6 +38,36 @@ export declare function overrideOrClear<V>({ value }: {
 export declare function orEmpty({ value }: {
     value: string | undefined;
 }, _optional?: Record<string, never>): string;
+/** The X (twitter) fields the "Customize for X/Twitter" disclosure holds, each paired with the social
+ *  preview (Open Graph) value it falls back to. */
+export type SeoXFieldKey = 'twitterTitle' | 'twitterDescription' | 'twitterImage';
+/** Whether this entry's X card differs from its social preview in any field — i.e. an X override
+ *  is in effect, so the "Customize for X/Twitter" disclosure opens on load. (2026-10-15, owner: one
+ *  generic social preview, X only as an optional customization.)
+ *  @complexity O(1). */
+export declare function xIsCustomized({ meta }: {
+    meta: AdminSeoMeta;
+}, _optional?: Record<string, never>): boolean;
+/** An X field's untouched box value, handed to `fieldValue` as its resolved value (so a pending
+ *  edit or clear still wins there). An X value equal to the social preview's is inherited, so the
+ *  box stays empty and its placeholder shows the live social value — typing there is what creates
+ *  an X override.
+ *  @complexity O(1). */
+export declare function xResolvedValue({ key, meta }: {
+    key: SeoXFieldKey;
+    meta: AdminSeoMeta;
+}, _optional?: Record<string, never>): string;
+/** The X field an edit to a social preview field should carry along: when X still shows the
+ *  preview's value and has no pending edit of its own, the edit also clears X's stored override so
+ *  X keeps following the preview after save. Without it, an X override saved equal to the preview
+ *  (indistinguishable here, the screen sees only effective values) would silently pin X to the old
+ *  text. Clearing an override that does not exist is a no-op on the server.
+ *  @complexity O(1). */
+export declare function inheritedXFor({ key, meta, touched }: {
+    key: string;
+    meta: AdminSeoMeta;
+    touched: Readonly<Record<string, unknown>>;
+}, _optional?: Record<string, never>): SeoXFieldKey | null;
 /** A pending-action button's label — `react/pages/SeoPage.tsx` uses this for both the save-settings button
  *  ("Saving…"/"Save settings") and the regenerate-sitemap button ("Working…"/"Regenerate
  *  sitemap"), same `pending ? … : …` shape, different copy. Also reused by `SitemapModal.tsx`'s
@@ -85,6 +116,39 @@ export declare function filterSitemapEntries({ entries, query }: {
 export declare function isStoredMediaRef({ value }: {
     value: string;
 }, _optional?: Record<string, never>): boolean;
+/** What an image field shows for its value — the file's name and pixel size — in place of the raw
+ * `{slug}:public` reference or URL (owner, 2026-10-15: a read-only "Selected image" box "looks
+ * useless"). The library row wins when the host can list media; otherwise a readable slug or the
+ * URL's file name stands in, and an opaque id falls back to the translated "Image".
+ * Size prefers the stored dimensions, then the decoded preview's natural size.
+ * @example describeMediaRef({ value: 'sunset:public', media: [{ id: 'a1', slug: 'sunset', title: 'Sunset', width: 1200, height: 630 }] }) // { name: 'Sunset', size: '1200 × 630' }
+ * @complexity O(m) over the media rows; no I/O.
+ */
+export declare function describeMediaRef({ value, media }: {
+    value: string;
+    media?: readonly AdminSeoMediaSummary[] | null | undefined;
+}, { width, height, t, extensionFor }?: {
+    width?: number | undefined;
+    height?: number | undefined;
+    t?: SeoTranslator | undefined;
+    /** `image/png` → `.png`; injected (the host UI kit owns the table) so this file stays pure. */
+    extensionFor?: ((contentType: string) => string) | undefined;
+}): {
+    name: string;
+    size: string | null;
+} | null;
+/** Whether an entry's social preview image comes from content or the site default, with no override
+ * of its own, so the field shows its source muted. "Using site default" is the original copy (owner,
+ * 2026-10-15). A pending edit is the entry's own, and so is a stored override the host flags
+ * (`imageOverridden`) even when it equals the default. A host without that flag can't tell such an
+ * override apart, so it reads as inherited (same image either way). Returns 'content' for an image
+ * the host identifies as content, 'default' for the site default, and false for an own/absent image.
+ * @complexity O(1). */
+export declare function ogImageInherited({ meta, defaultOgImage, touched }: {
+    meta: AdminSeoMeta;
+    defaultOgImage: string | undefined;
+    touched: Readonly<Record<string, unknown>>;
+}, _optional?: Record<string, never>): false | 'default' | 'content';
 /** Builds the `{slug}:public` reference `MediaRefField` writes into the field on selection —
  *  prefers the asset's readable slug over its id (readable-slugs S5b, 2026-09-23), matching
  *  `resolveSeoImageRef`'s own id-or-slug lookup server-side (`findMediaByIdOrSlug`,
@@ -159,4 +223,31 @@ export type SeoTabId = (typeof SEO_TAB_IDS)[number];
 export declare function resolveSeoTabId({ tabId }: {
     tabId?: string | null | undefined;
 }, _optional?: Record<string, never>): SeoTabId;
+/** Colour band for the analysis score pill: the same success/warning/failure tones the issue pills
+ * use, so a 100 reads green and a failing page reads red at a glance.
+ * @example scoreTone({ score: 100 }) // 'success'
+ */
+export declare function scoreTone({ score }: {
+    score: number;
+}, _optional?: Record<string, never>): 'success' | 'warning' | 'failure';
+/** One row of the searchable entry picker: grouped Pages then Posts, status only when not live. */
+export interface SeoEntryPickerOption {
+    value: string;
+    label: string;
+    group: string;
+    badge?: string;
+    detail?: string;
+}
+/**
+ * Picker rows for the Pages & posts tab. Pages lead because they are fewer and are the usual SEO
+ * targets (home, about, pricing); a published entry carries no pill, so only the exceptions
+ * (draft, scheduled, …) draw the eye. An untitled entry stays pickable by its id.
+ * @example entryPickerOptions({ posts, pages }, { t }) // [{ value: 'p1', label: 'About', group: 'Pages' }, …]
+ */
+export declare function entryPickerOptions({ posts, pages }: {
+    posts: readonly AdminSeoEntryChoice[];
+    pages: readonly AdminSeoEntryChoice[];
+}, { t }?: {
+    t?: SeoTranslator | undefined;
+}): SeoEntryPickerOption[];
 //# sourceMappingURL=rules.d.ts.map

package/dist/seo/rules.js

@@ -46,6 +46,43 @@ export function overrideOrClear({ value }, _optional = {}) {
 export function orEmpty({ value }, _optional = {}) {
     return value ?? "";
 }
+/** One entry's effective X value next to its effective social preview value, per field. Images
+ *  compare by source ref (the resolved URL is resized), falling back to the URL for pasted ones. */
+function xAndSocial({ meta }) {
+    return {
+        twitterTitle: [meta.twitter.title, meta.openGraph.title],
+        twitterDescription: [meta.twitter.description, meta.openGraph.description],
+        twitterImage: [meta.twitter.imageRef ?? meta.twitter.image, meta.openGraph.imageRef ?? meta.openGraph.image],
+    };
+}
+/** Whether this entry's X card differs from its social preview in any field — i.e. an X override
+ *  is in effect, so the "Customize for X/Twitter" disclosure opens on load. (2026-10-15, owner: one
+ *  generic social preview, X only as an optional customization.)
+ *  @complexity O(1). */
+export function xIsCustomized({ meta }, _optional = {}) {
+    return Object.values(xAndSocial({ meta })).some(([x, social]) => x !== social);
+}
+/** An X field's untouched box value, handed to `fieldValue` as its resolved value (so a pending
+ *  edit or clear still wins there). An X value equal to the social preview's is inherited, so the
+ *  box stays empty and its placeholder shows the live social value — typing there is what creates
+ *  an X override.
+ *  @complexity O(1). */
+export function xResolvedValue({ key, meta }, _optional = {}) {
+    const [x, social] = xAndSocial({ meta })[key];
+    return x === social ? '' : x ?? '';
+}
+/** The X field an edit to a social preview field should carry along: when X still shows the
+ *  preview's value and has no pending edit of its own, the edit also clears X's stored override so
+ *  X keeps following the preview after save. Without it, an X override saved equal to the preview
+ *  (indistinguishable here, the screen sees only effective values) would silently pin X to the old
+ *  text. Clearing an override that does not exist is a no-op on the server.
+ *  @complexity O(1). */
+export function inheritedXFor({ key, meta, touched }, _optional = {}) {
+    const xKey = { ogTitle: 'twitterTitle', ogDescription: 'twitterDescription', ogImage: 'twitterImage' }[key];
+    if (!xKey || xKey in touched)
+        return null;
+    return xResolvedValue({ key: xKey, meta }) === '' ? xKey : null;
+}
 /** A pending-action button's label — `react/pages/SeoPage.tsx` uses this for both the save-settings button
  *  ("Saving…"/"Save settings") and the regenerate-sitemap button ("Working…"/"Regenerate
  *  sitemap"), same `pending ? … : …` shape, different copy. Also reused by `SitemapModal.tsx`'s
@@ -126,6 +163,64 @@ export function isStoredMediaRef({ value }, _optional = {}) {
     // A URL typed one character at a time reaches "https:/" before it reaches "https://".
     return !trimmed.includes(":/") && parseMediaRefAssetId(trimmed) !== null;
 }
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** What an image field shows for its value — the file's name and pixel size — in place of the raw
+ * `{slug}:public` reference or URL (owner, 2026-10-15: a read-only "Selected image" box "looks
+ * useless"). The library row wins when the host can list media; otherwise a readable slug or the
+ * URL's file name stands in, and an opaque id falls back to the translated "Image".
+ * Size prefers the stored dimensions, then the decoded preview's natural size.
+ * @example describeMediaRef({ value: 'sunset:public', media: [{ id: 'a1', slug: 'sunset', title: 'Sunset', width: 1200, height: 630 }] }) // { name: 'Sunset', size: '1200 × 630' }
+ * @complexity O(m) over the media rows; no I/O.
+ */
+export function describeMediaRef({ value, media }, { width, height, t = key => key, extensionFor } = {}) {
+    const trimmed = typeof value === 'string' ? value.trim() : '';
+    if (!trimmed)
+        return null;
+    const key = parseMediaRefAssetId(trimmed);
+    const row = key ? media?.find(item => item.id === key || item.slug === key) : undefined;
+    const name = row?.title ? withExtension({ name: row.title, extension: row.contentType && extensionFor ? extensionFor(row.contentType) : '' }) : fallbackMediaName({ key, value: trimmed, t });
+    return { name, size: pixelSize(row?.width ?? width, row?.height ?? height) };
+}
+/** A library title reads as a file name (owner, 2026-10-15: "it should be testing-page.png or
+ * whatever the extension is"). No original upload name is stored, so the extension comes from the
+ * stored bytes' type; a title that already ends in it is left alone. */
+function withExtension({ name, extension }) {
+    return extension && !name.toLowerCase().endsWith(extension) ? `${name}${extension}` : name;
+}
+/** Whether an entry's social preview image comes from content or the site default, with no override
+ * of its own, so the field shows its source muted. "Using site default" is the original copy (owner,
+ * 2026-10-15). A pending edit is the entry's own, and so is a stored override the host flags
+ * (`imageOverridden`) even when it equals the default. A host without that flag can't tell such an
+ * override apart, so it reads as inherited (same image either way). Returns 'content' for an image
+ * the host identifies as content, 'default' for the site default, and false for an own/absent image.
+ * @complexity O(1). */
+export function ogImageInherited({ meta, defaultOgImage, touched }, _optional = {}) {
+    if ('ogImage' in touched || meta.openGraph.imageOverridden)
+        return false;
+    const image = meta.openGraph.imageRef ?? meta.openGraph.image;
+    if (meta.openGraph.imageSource === 'content' && image)
+        return 'content';
+    return defaultOgImage && image === defaultOgImage ? 'default' : false;
+}
+function fallbackMediaName({ key, value, t }) {
+    if (!key)
+        return urlFileName(value);
+    return UUID_PATTERN.test(key) ? t('Image') : key;
+}
+function pixelSize(width, height) {
+    return width && height ? `${width} × ${height}` : null;
+}
+/** The last path segment of an image URL ("https://cdn.example/a/pic.png" → "pic.png"). */
+function urlFileName(value) {
+    try {
+        const url = new URL(value, 'https://placeholder.invalid');
+        const last = url.pathname.split('/').filter(Boolean).pop();
+        return last ? decodeURIComponent(last) : url.hostname || value;
+    }
+    catch {
+        return value;
+    }
+}
 /** Builds the `{slug}:public` reference `MediaRefField` writes into the field on selection —
  *  prefers the asset's readable slug over its id (readable-slugs S5b, 2026-09-23), matching
  *  `resolveSeoImageRef`'s own id-or-slug lookup server-side (`findMediaByIdOrSlug`,
@@ -259,4 +354,35 @@ export const SEO_TAB_IDS = ['defaults', 'sitemap', 'entries'];
 export function resolveSeoTabId({ tabId }, _optional = {}) {
     return SEO_TAB_IDS.find(id => id === tabId) ?? 'defaults';
 }
+/** Colour band for the analysis score pill: the same success/warning/failure tones the issue pills
+ * use, so a 100 reads green and a failing page reads red at a glance.
+ * @example scoreTone({ score: 100 }) // 'success'
+ */
+export function scoreTone({ score }, _optional = {}) {
+    if (score >= 80)
+        return 'success';
+    return score >= 50 ? 'warning' : 'failure';
+}
+/**
+ * Picker rows for the Pages & posts tab. Pages lead because they are fewer and are the usual SEO
+ * targets (home, about, pricing); a published entry carries no pill, so only the exceptions
+ * (draft, scheduled, …) draw the eye. An untitled entry stays pickable by its id.
+ * @example entryPickerOptions({ posts, pages }, { t }) // [{ value: 'p1', label: 'About', group: 'Pages' }, …]
+ */
+export function entryPickerOptions({ posts, pages }, { t = key => key } = {}) {
+    // Two entries can share a title ("Landing Page" twice, owner 2026-10-15); both stay listed and
+    // each duplicate shows its slug as muted secondary text so the operator can tell them apart.
+    const rows = (entries, group) => {
+        const labelOf = (entry) => entry.title.trim() || entry.id;
+        const counts = new Map();
+        for (const entry of entries)
+            counts.set(labelOf(entry), (counts.get(labelOf(entry)) ?? 0) + 1);
+        return entries.map((entry) => ({
+            value: entry.id, label: labelOf(entry), group,
+            ...(entry.status && entry.status !== 'published' ? { badge: t(entry.status) } : {}),
+            ...((counts.get(labelOf(entry)) ?? 0) > 1 ? { detail: entry.slug || entry.id } : {}),
+        }));
+    };
+    return [...rows(pages, t('Pages')), ...rows(posts, t('Posts'))];
+}
 //# sourceMappingURL=rules.js.map

package/dist/seo/seo.module.d.ts

@@ -29,21 +29,24 @@ export declare const seoModule: {
         readonly "Canonical URL": "Canonical URL";
         readonly Noindex: "Noindex";
         readonly Nofollow: "Nofollow";
-        readonly "OG title": "OG title";
-        readonly "OG description": "OG description";
-        readonly "OG image": "OG image";
-        readonly "Twitter title": "Twitter title";
-        readonly "Twitter description": "Twitter description";
-        readonly "Twitter image": "Twitter image";
+        readonly "Preview title": "Preview title";
+        readonly "Preview description": "Preview description";
+        readonly "Preview image": "Preview image";
+        readonly "X/Twitter title": "X/Twitter title";
+        readonly "X/Twitter description": "X/Twitter description";
+        readonly "X/Twitter image": "X/Twitter image";
+        readonly "Customize for X/Twitter (optional)": "Customize for X/Twitter (optional)";
+        readonly "Same as the preview image": "Same as the preview image";
+        readonly "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter": "Used by Facebook, LinkedIn, Slack, Discord, iMessage, WhatsApp and X/Twitter";
         readonly "Saving\u2026": "Saving…";
         readonly "Save overrides": "Save overrides";
         readonly "Per-entry SEO": "Per-entry SEO";
         readonly "Search appearance": "Search appearance";
         readonly "Title template (must contain %s)": "Title template (must contain %s)";
         readonly "Default meta description": "Default meta description";
-        readonly "Social sharing": "Social sharing";
-        readonly "Default Open Graph / Twitter image": "Default Open Graph / Twitter image";
-        readonly "Twitter @site handle": "Twitter @site handle";
+        readonly "Social preview": "Social preview";
+        readonly "Default preview image": "Default preview image";
+        readonly "X/Twitter @handle": "X/Twitter @handle";
         readonly Crawling: "Crawling";
         readonly "Default noindex": "Default noindex";
         readonly "Default nofollow": "Default nofollow";
@@ -56,7 +59,7 @@ export declare const seoModule: {
         readonly "View sitemap": "View sitemap";
         readonly "Loading SEO settings\u2026": "Loading SEO settings…";
         readonly Marketing: "Marketing";
-        readonly "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.": "Site-wide defaults for meta titles, descriptions, Open Graph/Twitter cards, and robots directives.";
+        readonly "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.": "Site-wide defaults for meta titles, descriptions, social previews, and robots directives.";
         readonly "Choose image": "Choose image";
         readonly Remove: "Remove";
         readonly "Sitemap \u00B7 {count} URLs": "Sitemap · {count} URLs";
@@ -84,6 +87,8 @@ export declare const seoModule: {
         readonly "failed to load the sitemap": "failed to load the sitemap";
         readonly "Could not load the sitemap (HTTP {status}).": "Could not load the sitemap (HTTP {status}).";
         readonly "Selected image": "Selected image";
+        readonly "Using site default: {name}": "Using site default: {name}";
+        readonly "Using image from page content: {name}": "Using image from page content: {name}";
     };
     readonly pages: {
         readonly settings: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/admin",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "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": {
@@ -440,10 +440,10 @@
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0",
     "@jini-ai/agentic": "^0.4.4",
-    "@jini-ai/ui": "^0.5.1",
+    "@jini-ai/ui": "^0.5.5",
     "@jini-ai/ui-kit": "^0.1.3",
     "@jini-ai/agent-plugins": "^0.4.3",
-    "@jini-ai/cms": "^0.5.11",
+    "@jini-ai/cms": "^0.5.13",
     "@jini-ai/core": "^0.4.3"
   },
   "peerDependenciesMeta": {
@@ -482,12 +482,12 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "@testing-library/user-event": "^14.6.1",
-    "@jini-ai/agent-plugins": "^0.4.6",
     "@jini-ai/agentic": "^0.4.4",
+    "@jini-ai/agent-plugins": "^0.4.7",
     "@jini-ai/ui-kit": "^0.1.4",
-    "@jini-ai/cms": "^0.5.12",
-    "@jini-ai/core": "^0.4.6",
-    "@jini-ai/ui": "^0.5.3"
+    "@jini-ai/cms": "^0.5.13",
+    "@jini-ai/core": "^0.4.7",
+    "@jini-ai/ui": "^0.5.5"
   },
   "typesVersions": {
     "*": {