@jini-ai/admin 0.4.2 → 0.4.4

package/dist/seo/models.d.ts

@@ -0,0 +1,179 @@
+import type { AdminSeoSettings, AdminSeoSettingsPatch, AdminSeoMeta, AdminSeoAnalysis, AdminSeoOverridesPatch, AdminSeoEntryChoice } from '../core/ports/seo.js';
+import type { MediaAsset } from '../contracts/media-picker.js';
+import type { SitemapUrlEntry } from './rules.js';
+export type SeoSettings = AdminSeoSettings;
+export type SeoSettingsPatch = AdminSeoSettingsPatch;
+export type SeoEntryMeta = AdminSeoMeta;
+export type SeoEntryAnalysis = AdminSeoAnalysis;
+export type SeoEntryOverridesPatch = AdminSeoOverridesPatch;
+export type SeoIssue = import('../core/ports/seo.js').AdminSeoIssue;
+/** Extra host fields survive picker reads; only id/title/status participate in rendering. */
+export type AdminPost = AdminSeoEntryChoice & {
+    readonly workspaceId?: string;
+    readonly kind?: string;
+    readonly slug?: string;
+    readonly bodyJson?: unknown;
+    readonly updatedAt?: string;
+    readonly version?: number;
+};
+/** The existing picker returns its media row unchanged; slug is an optional projection. */
+export interface SeoMediaSelection extends MediaAsset {
+    readonly slug?: string;
+    readonly workspaceId?: string;
+    readonly caption?: string;
+    readonly credit?: string;
+    readonly sha256?: string;
+    readonly status?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly version?: number;
+    readonly width?: number | null;
+    readonly height?: number | null;
+    readonly cssClass?: string | null;
+    readonly htmlAttributes?: string | null;
+}
+export type AdminMedia = SeoMediaSelection;
+export type SeoTranslator = (key: string, vars?: Record<string, string | number>) => string;
+/** Host API error classes remain host-owned; format their empty-message semantics at the seam. */
+export type SeoErrorFormatter = (required: {
+    error: unknown;
+    fallback: string;
+}, optional?: Record<string, never>) => string;
+export interface SeoController {
+    settings: SeoSettings | null;
+    error: string | null;
+    saving: boolean;
+    notice: string | null;
+    /** Takes a `SeoSettingsPatch` rather than a `Partial<SeoSettings>` so an emptied optional field
+     *  can send `null` and actually clear its site default — `setSeoSettings` is a merge, so an
+     *  omitted key means "unchanged" (see the core port's `AdminSeoSettingsPatch`). */
+    save: (patch: SeoSettingsPatch) => Promise<void>;
+    /** The site-wide default OG/Twitter image field's own controlled value (MediaRefField picker
+     *  support, 2026-09-05) — every OTHER default on this screen stays an uncontrolled `defaultValue`
+     *  (read via `FormData` on submit, `react/pages/SeoPage.tsx`'s own file header), but a picker needs somewhere to
+     *  WRITE a selection into, which an uncontrolled input has no seam for. Re-synced from `settings`
+     *  whenever it (re)loads — including after a successful save, so the field reflects what was
+     *  actually persisted rather than the operator's last unsaved edit. `""` until settings load. */
+    defaultOgImage: string;
+    setDefaultOgImage: (value: string) => void;
+    /** Resolves `true` on success, `false` on a caught failure (`error` is set either way this
+     *  already did) — `SitemapModal.tsx`'s own footer Regenerate button uses the boolean to decide
+     *  whether to refetch `/sitemap.xml`, so a failed attempt never re-fetches the same stale
+     *  content. The pre-existing caller, `react/pages/SeoPage.tsx`'s own Regenerate button, still just fires this as
+     *  a plain `onClick` and discards the return value — this is a widening, not a breaking change. */
+    regenerateSitemap: () => Promise<boolean>;
+    /** Whether `SitemapModal.tsx` ("View sitemap") is open. `react/pages/SeoPage.tsx` stays markup-only (this file's
+     *  own header) by keeping this state here alongside the rest of the screen's state, the same way
+     *  `SeoEntrySection`'s own `entryId` selection lives in `useSeoEntrySection` rather than in
+     *  `react/pages/SeoPage.tsx` itself. */
+    sitemapModalOpen: boolean;
+    openSitemapModal: () => void;
+    closeSitemapModal: () => void;
+    /** Legacy component metadata retained for the copied render contract. Translation is always
+     *  taken from the injected module t function, never from a package-owned locale dictionary. */
+    locale: string;
+}
+export interface EntryPickerController {
+    entries: readonly AdminPost[] | null;
+    error: string | null;
+}
+export interface SeoEntryPanelOptions {
+    entryId: string;
+}
+export interface SeoEntryPanelController {
+    resolved: SeoEntryMeta | null;
+    analysis: SeoEntryAnalysis | null;
+    loadError: string | null;
+    saving: boolean;
+    saveError: string | null;
+    notice: string | null;
+    /** Reads back whatever the operator touched for `key`, falling back to the resolved
+     *  (server-effective) value for any field not yet edited this session. A field the operator
+     *  EMPTIED reads back as `null` (the pending clear), which `react/pages/SeoPage.tsx`'s own `?? ""` renders as an
+     *  empty box — so the field the operator cleared stays cleared on screen. */
+    fieldValue: <K extends keyof SeoEntryOverridesPatch>(key: K, resolvedValue: SeoEntryOverridesPatch[K]) => SeoEntryOverridesPatch[K];
+    setField: <K extends keyof SeoEntryOverridesPatch>(key: K, value: SeoEntryOverridesPatch[K]) => void;
+    save: () => Promise<void>;
+    /** The patch `save` will PUT — only the fields the operator actually touched this session, with
+     *  `null` for each one they emptied. An untouched field is ABSENT, never `null`: "unchanged" must
+     *  never become "clear". */
+    touched: SeoEntryOverridesPatch;
+}
+export interface SeoEntrySectionController {
+    entryId: string;
+    setEntryId: (entryId: string) => void;
+}
+export type SitemapModalView = "table" | "raw";
+/** `"disabled"` is a real, terminal state, not a stalled `"loading"`: with `sitemapEnabled` false the
+ *  modal deliberately never fetches, so there is nothing in flight to be loading. Naming it keeps
+ *  `SitemapModal.tsx`'s header honest — `sitemapModalTitle`/`SitemapModalHeaderActions` both key off
+ *  `status === "ready"`, so a URL count and the raw/table toggle stay off a sitemap that is off. */
+export type SitemapModalStatus = "disabled" | "loading" | "error" | "ready";
+/** What {@link useSitemapModal} needs from its caller. An object rather than trailing positional
+ *  parameters specifically so the `SitemapModal.tsx` `useModal` test seam forwards it whole: a
+ *  positional `enabled` can be silently dropped by a shorter test double (TypeScript accepts a
+ *  function of fewer parameters), which is exactly how the "this never fetches" claim below went
+ *  untested while the fetch fired on every open. */
+export interface SitemapModalInputs {
+    /** `settings.sitemapEnabled` — when `false`, `/sitemap.xml` is never requested at all. */
+    enabled: boolean;
+    /** Retained for the existing hook ABI; SitemapModal forwards close directly to Jini. */
+    onClose: () => void;
+}
+/** What {@link useSitemapModal} (and {@link useWiredSitemapModal}) hands back to
+ *  `SitemapModal.tsx` — the modal's full render-time contract. */
+export interface SitemapModalController {
+    status: SitemapModalStatus;
+    /** A describable failure message, set only while `status === "error"`. */
+    error: string | null;
+    /** The exact response text from `GET /sitemap.xml`, set only while `status === "ready"`. */
+    xmlText: string;
+    /** Every parsed `<url>` entry, unfiltered — `SitemapModal.tsx`'s header URL count reads this. */
+    entries: SitemapUrlEntry[];
+    /** `entries` narrowed by {@link filter}. */
+    filteredEntries: SitemapUrlEntry[];
+    filter: string;
+    setFilter: (value: string) => void;
+    view: SitemapModalView;
+    setView: (view: SitemapModalView) => void;
+    /** Re-runs the fetch — `SitemapModal.tsx`'s footer Regenerate button calls this after a
+     *  successful regenerate, so the count/table/raw view all reflect the freshly rebuilt sitemap
+     *  without the operator closing and reopening the modal. */
+    refetch: () => void;
+}
+export interface MediaRefFieldController {
+    /** Whether `MediaPickerDialog` is open. */
+    pickerOpen: boolean;
+    openPicker: () => void;
+    closePicker: () => void;
+    /** `MediaPickerDialog`'s `onSelect` — writes the exact `{slug}:public` ref
+     *  (`buildMediaRef`, `rules.ts`, readable-slugs S5b) into the field and closes the dialog. */
+    handleSelect: (item: SeoMediaSelection) => void;
+    /** Clears the field to `""` — an OG image must be removable (SPEC intent). */
+    clear: () => void;
+    /** 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;
+    /** `MediaPickerDialog`'s `accept` — images only: every field this backs is an og:image /
+     *  twitter:image, and a crawler cannot use a video there (2026-10-05, same filter the post
+     *  featured-image chooser passes). */
+    accept: readonly string[];
+}
+export type SeoState = Omit<SeoController, 'save' | 'setDefaultOgImage' | 'regenerateSitemap' | 'openSitemapModal' | 'closeSitemapModal' | 'locale'>;
+export type SeoEntryState = Pick<SeoEntryPanelController, 'resolved' | 'analysis' | 'loadError' | 'saving' | 'saveError' | 'notice' | 'touched'>;
+export interface SitemapState {
+    status: SitemapModalStatus;
+    error: string | null;
+    xmlText: string;
+    filter: string;
+    view: SitemapModalView;
+}
+export declare const initialSeoState: SeoState;
+export declare const initialSeoEntryState: SeoEntryState;
+export declare const initialEntryPickerState: EntryPickerController;
+/** Error messages remain visible; the host transport owns decoding its API errors. */
+export declare function describeSeoError({ error, fallback }: {
+    error: unknown;
+    fallback: string;
+}, _optional?: Record<string, never>): string;
+//# sourceMappingURL=models.d.ts.map

package/dist/seo/models.js

@@ -0,0 +1,8 @@
+export const initialSeoState = { settings: null, error: null, saving: false, notice: null, defaultOgImage: '', sitemapModalOpen: false };
+export const initialSeoEntryState = { resolved: null, analysis: null, loadError: null, saving: false, saveError: null, notice: null, touched: {} };
+export const initialEntryPickerState = { entries: null, error: null };
+/** Error messages remain visible; the host transport owns decoding its API errors. */
+export function describeSeoError({ error, fallback }, _optional = {}) {
+    return error instanceof Error ? error.message : fallback;
+}
+//# sourceMappingURL=models.js.map

package/dist/seo/ports.d.ts

@@ -0,0 +1,11 @@
+import type { AdminSeoPort } from '../core/ports/seo.js';
+export type { AdminSeoPort } from '../core/ports/seo.js';
+export declare const seoApiToken: import("../core/module/token.js").AdminPortToken<AdminSeoPort, "admin.seo.api">;
+/** A host event invalidates this scope's settings; it carries no unauthorized rows. */
+export interface SeoEventsPort {
+    subscribe(required: {
+        onRefresh: () => void;
+    }, optional?: Record<string, never>): () => void;
+}
+export declare const seoEventsToken: import("../core/module/token.js").AdminPortToken<SeoEventsPort, "admin.seo.events">;
+//# sourceMappingURL=ports.d.ts.map

package/dist/seo/ports.js

@@ -0,0 +1,4 @@
+import { adminPort } from '../core/module/token.js';
+export const seoApiToken = adminPort({ id: 'admin.seo.api' });
+export const seoEventsToken = adminPort({ id: 'admin.seo.events' });
+//# sourceMappingURL=ports.js.map

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

@@ -0,0 +1,4 @@
+import type { SeoMediaPickerSlotProps } from '../options.js';
+/** The shared picker service owns its UI; this consumer never renders a second picker. */
+export declare function MediaPickerBridge(props: SeoMediaPickerSlotProps, _optional?: Record<string, never>): import("react").JSX.Element;
+//# sourceMappingURL=MediaPickerBridge.d.ts.map

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

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useMediaPickerBridge } from '../hooks/MediaPickerBridge.hooks.js';
+/** The shared picker service owns its UI; this consumer never renders a second picker. */
+export function MediaPickerBridge(props, _optional = {}) {
+    const { error, cancel } = useMediaPickerBridge(props);
+    return _jsx(_Fragment, { children: error && _jsxs("div", { role: "alert", children: [error, _jsx("button", { type: "button", onClick: cancel, children: "Cancel" })] }) });
+}
+//# sourceMappingURL=MediaPickerBridge.js.map

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

@@ -0,0 +1,40 @@
+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
+ * `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
+ * image selectable, with a preview") — the text input keeps working unchanged (an addition, not a
+ * replacement: anyone scripting or pasting a raw ref/URL still can), the picker is the new path.
+ *
+ * State — the dialog's open/closed flag, the selection handler, and the preview URL — lives in
+ * `react/hooks/MediaRefField.hooks.ts`, split out the same way `MediaPickerDialog`/`MediaPickerDialog.hooks
+ * .tsx` does; this file stays props-and-JSX only. `MediaPickerDialog` itself is reused unchanged
+ * (`components/MediaPickerDialog/MediaPickerDialog.tsx`) — no fork, no new picker UI.
+ *
+ * 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.
+ */
+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. */
+    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
+     *  through `fieldValue`/`setField`, never `FormData`), so it stays optional. */
+    name?: string;
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    /** 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;
+    /** 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;
+//# sourceMappingURL=MediaRefField.d.ts.map

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

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { agentHandle } from "@jini-ai/agentic";
+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 = {}) {
+    const t = useSeoCopy();
+    const { Picker = MediaPickerBridge, storedReference } = useMediaRefPresentation({ value });
+    const { pickerOpen, openPicker, closePicker, handleSelect, clear, previewUrl, accept } = useField({ value, onChange });
+    return (_jsxs("div", { className: "jini-field jini-media-ref-field", children: [_jsx("label", { className: "jini-field-label", htmlFor: id, children: label }), _jsxs("div", { className: "jini-media-ref-field-row", children: [_jsx("input", { className: "jini-input", id: id, name: storedReference ? undefined : name, value: storedReference ? t({ locale, key: "Selected image" }) : value, readOnly: storedReference, onChange: (e) => onChange(e.target.value), ...(base ? agentHandle({ handle: base }, { role: "field", label }) : {}) }), storedReference && name ? _jsx("input", { type: "hidden", name: name, value: value }) : null, _jsx("button", { type: "button", className: "jini-btn jini-btn-secondary", onClick: openPicker, ...handleSpread({ ...(base === undefined ? {} : { base }), suffix: "choose", label: `Choose an image for: ${label}` }), children: t({ locale: locale, key: "Choose image" }) }), value ? (_jsx("button", { type: "button", className: "jini-btn jini-btn-secondary", onClick: clear, ...handleSpread({ ...(base === undefined ? {} : { base }), suffix: "clear", label: `Remove the selected image for: ${label}` }), children: t({ locale: locale, key: "Remove" }) })) : null] }), previewUrl ? _jsx("img", { className: "jini-media-ref-field-preview", src: previewUrl, alt: `${label} preview` }) : null, pickerOpen ? (_jsx(Picker, { onSelect: handleSelect, onCancel: closePicker, accept: accept, agentHandle: base ? `${base}-dialog` : undefined })) : null] }));
+}
+//# sourceMappingURL=MediaRefField.js.map

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

@@ -0,0 +1,13 @@
+/** Site defaults — sliders, i.e. values that are set once and then apply to everything. */
+export declare function SeoDefaultsIcon({ size }: {
+    size?: number;
+}, _optional?: Record<string, never>): import("react").JSX.Element;
+/** Sitemap — a node branching into children, i.e. the shape of the file this tab rebuilds. */
+export declare function SeoSitemapIcon({ size }: {
+    size?: number;
+}, _optional?: Record<string, never>): import("react").JSX.Element;
+/** Pages & posts — stacked documents, i.e. the collection this tab edits one at a time. */
+export declare function SeoEntriesIcon({ size }: {
+    size?: number;
+}, _optional?: Record<string, never>): import("react").JSX.Element;
+//# sourceMappingURL=SeoIcons.d.ts.map

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

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Shared attributes for a decorative line icon — copied deliberately from
+ *  `deployment-visuals.tsx`'s own `LINE_ICON` so this tab row reads as the same family as the
+ *  Deployment tab row it was modelled on (24px grid, 1.5 stroke, round joins). Local rather than
+ *  imported across the feature boundary: `features/deployment/index.ts` is that feature's public
+ *  surface and does not export it, and this app ships no shared icon module — the sidebar's glyphs
+ *  in `App.tsx` and `SettingsUi.tsx`'s tab icons are both inline SVG for the same reason.
+ *  `aria-hidden` on every one: each sits directly beside the text label that already says the same
+ *  thing (`frontend-accessibility` — do not give an accessible name to decoration that duplicates
+ *  adjacent visible text). */
+const LINE_ICON = {
+    viewBox: "0 0 24 24",
+    fill: "none",
+    stroke: "currentColor",
+    strokeWidth: 1.5,
+    strokeLinecap: "round",
+    strokeLinejoin: "round",
+    "aria-hidden": true,
+};
+/** Site defaults — sliders, i.e. values that are set once and then apply to everything. */
+export function SeoDefaultsIcon({ size = 16 }, _optional = {}) {
+    return (_jsxs("svg", { ...LINE_ICON, width: size, height: size, children: [_jsx("path", { d: "M4 6h10M18 6h2M4 12h2M10 12h10M4 18h8M16 18h4" }), _jsx("circle", { cx: "16", cy: "6", r: "2" }), _jsx("circle", { cx: "8", cy: "12", r: "2" }), _jsx("circle", { cx: "14", cy: "18", r: "2" })] }));
+}
+/** Sitemap — a node branching into children, i.e. the shape of the file this tab rebuilds. */
+export function SeoSitemapIcon({ size = 16 }, _optional = {}) {
+    return (_jsxs("svg", { ...LINE_ICON, width: size, height: size, children: [_jsx("rect", { x: "9", y: "3", width: "6", height: "4", rx: "1" }), _jsx("rect", { x: "3", y: "17", width: "6", height: "4", rx: "1" }), _jsx("rect", { x: "15", y: "17", width: "6", height: "4", rx: "1" }), _jsx("path", { d: "M12 7v4M6 17v-2h12v2M12 11v4" })] }));
+}
+/** Pages & posts — stacked documents, i.e. the collection this tab edits one at a time. */
+export function SeoEntriesIcon({ size = 16 }, _optional = {}) {
+    return (_jsxs("svg", { ...LINE_ICON, width: size, height: size, children: [_jsx("path", { d: "M8 3h6l4 4v10a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2z" }), _jsx("path", { d: "M14 3v4h4" }), _jsx("path", { d: "M10 12h5M10 16h3" })] }));
+}
+//# sourceMappingURL=SeoIcons.js.map

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

@@ -0,0 +1,48 @@
+import { useWiredSitemapModal } from "../hooks/use-sitemap-modal.hooks.js";
+/**
+ * `SitemapModal` — "View sitemap" (owner request, `react/pages/SeoPage.tsx`'s Sitemap card). Reads the exact same
+ * `GET /sitemap.xml` bytes a crawler gets (`sitemap-dependencies.hooks.ts`'s `defaultSitemapPort`,
+ * via `siteUrl()`) and renders them as a filterable `URL | Last modified` table, with a Raw XML
+ * toggle for verifying the literal response text. `changefreq`/`priority` columns were considered
+ * and dropped: `server/inbound/public-http/routes/site/sitemap.ts` never emits either field (read
+ * directly, not guessed), so a column for them would only ever show blank.
+ *
+ * Jini's Dialog owns modality and focus confinement: aria-modal promises the background cannot
+ * be reached with Tab. `.sitemap-modal` widens the shared chrome to about 900px; its body is the
+ * single scrolling region between fixed header and footer.
+ *
+ * Domain state (fetch, parse, filter, view toggle) lives in `hooks/use-sitemap-modal
+ * .hooks.ts`; this file is markup only — the one bit of sequencing that belongs to neither that
+ * hook nor the outer `useSeo()` (refetching after a successful regenerate) lives in its own
+ * colocated `react/hooks/SitemapModal.hooks.ts`, see that file's header for why it isn't folded into either.
+ *
+ * ## Agent handles
+ * Every interactive element carries its own `agentHandle` (grep `agentHandle(` in `react/pages/SeoPage.tsx` for
+ * the convention this follows): the raw-XML link, the table/raw toggle, the filter box, each row's
+ * URL link (namespaced via `buildAgentListHandles`, the same per-item scheme `MediaPickerDialog
+ * .tsx` uses), the footer Regenerate button, and the footer Close button.
+ */
+export interface SitemapModalProps {
+    locale: string;
+    /** `settings.sitemapEnabled` from `useSeo()` — when `false`, the modal shows why instead of a
+     *  table (REQ 8: "disabled" and "on but zero URLs" are different facts, so this never fetches to
+     *  find out — it already knows).
+     *
+     *  Threaded into `useSitemapModal` as `SitemapModalInputs.enabled` so the fetch, header and Raw XML
+     *  toggle all agree with the disabled body. */
+    sitemapEnabled: boolean;
+    /** `saving` from `useSeo()` — shared with the outer page's own Save/Regenerate buttons, same as
+     *  today's single-flag convention (`react/pages/SeoPage.tsx`'s existing `disabled={saving}` on both). */
+    regenerating: boolean;
+    /** `regenerateSitemap` from `useSeo()`. Resolves `true` on success, `false` on a caught failure —
+     *  `handleRegenerate` below only refetches on `true`, matching REQ 7 ("after a SUCCESSFUL
+     *  regenerate it refetches"). */
+    onRegenerate: () => Promise<boolean>;
+    onClose: () => void;
+    /** Injectable seam for the modal's fetch/parse/filter/view state. Defaults to the real
+     *  {@link useWiredSitemapModal}; a test can pass a fake here to exercise this component's
+     *  rendering against a fixed `SitemapModalController`. */
+    useModal?: typeof useWiredSitemapModal;
+}
+export declare function SitemapModal({ locale, sitemapEnabled, regenerating, onRegenerate, onClose, useModal, }: SitemapModalProps, _optional?: Record<string, never>): import("react").JSX.Element;
+//# sourceMappingURL=SitemapModal.d.ts.map

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

@@ -0,0 +1,72 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { agentHandle } from "@jini-ai/agentic";
+import { Dialog } from "@jini-ai/ui-kit/react";
+import { formatTimestamp } from "@jini-ai/ui/panel-kit";
+import { useSeoCopy, useSeoOptions } from "../hooks/SeoPorts.hooks.js";
+import { actionLabel } from "../../rules.js";
+import { useWiredSitemapModal } from "../hooks/use-sitemap-modal.hooks.js";
+import { useSitemapModalRegenerate, useSitemapPresentation, useSitemapTable, useSitemapViewToggle } from "../hooks/SitemapModal.hooks.js";
+/** The header's raw-XML link + table/raw toggle — only shown once there is a real response to
+ *  point at (REQ 3/6). Its own component purely so {@link SitemapModal} stays a flat sequence of
+ *  blocks.
+ *
+ * @complexity O(1). */
+function SitemapModalHeaderActions({ locale, modal }) {
+    const { sourceUrl } = useSitemapPresentation({ locale, modal });
+    const { toggleView } = useSitemapViewToggle({ modal });
+    const t = useSeoCopy();
+    return (_jsxs("div", { className: "sitemap-modal-header-actions", children: [_jsx("a", { className: "sitemap-modal-source-link", href: sourceUrl, target: "_blank", rel: "noreferrer", ...agentHandle({ handle: "seo-sitemap-open-raw-link" }, {
+                    role: "link",
+                    label: "Open the real sitemap.xml file in a new tab",
+                }), children: t({ locale: locale, key: "sitemap.xml ↗" }) }), modal.status === "ready" ? (_jsx("button", { type: "button", className: "btn-secondary", "aria-pressed": modal.view === "raw", onClick: toggleView, ...agentHandle({ handle: "seo-sitemap-raw-toggle" }, {
+                    role: "button",
+                    label: "Toggle between the parsed table and the raw XML response",
+                }), children: modal.view === "raw" ? t({ locale: locale, key: "Table" }) : t({ locale: locale, key: "Raw XML" }) })) : null] }));
+}
+/** The parsed-table view: filter box + `URL | Last modified` table, or the empty-filter/empty-
+ *  sitemap notices in place of a table with nothing to show. Its own component for the same
+ *  flat-sequence-of-blocks reason as {@link SitemapModalHeaderActions}.
+ *
+ * @complexity O(1) to render — `entries`/`filteredEntries` are already computed by
+ *   `useSitemapModal` (memoized there), this only maps them to JSX. */
+function SitemapModalTable({ locale, modal }) {
+    const t = useSeoCopy();
+    const { formatDate = formatTimestamp } = useSeoOptions();
+    const { rowHandles } = useSitemapTable({ modal });
+    if (modal.entries.length === 0)
+        return _jsx("div", { className: "notice", children: t({ locale: locale, key: "The sitemap has no URLs yet." }) });
+    return (_jsxs(_Fragment, { children: [_jsx("input", { type: "search", className: "sitemap-modal-filter", "aria-label": t({ locale: locale, key: "Filter sitemap URLs" }), placeholder: t({ locale: locale, key: "Filter by URL…" }), value: modal.filter, onChange: (e) => modal.setFilter(e.target.value), ...agentHandle({ handle: "seo-sitemap-filter" }, {
+                    role: "field",
+                    label: "Narrow the sitemap table by a substring match on the URL",
+                }) }), modal.filteredEntries.length === 0 ? (_jsx("p", { className: "muted-cell", children: t({ locale: locale, key: "No URLs match this filter." }) })) : (_jsx("div", { className: "table-scroll", children: _jsxs("table", { className: "list-table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: t({ locale: locale, key: "URL" }) }), _jsx("th", { children: t({ locale: locale, key: "Last modified" }) })] }) }), _jsx("tbody", { children: modal.filteredEntries.map((entry, index) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx("a", { href: entry.loc, target: "_blank", rel: "noreferrer", ...agentHandle({ handle: rowHandles[index] }, { role: "link", label: "Open this URL on the live site" }), children: entry.loc }) }), _jsx("td", { children: entry.lastmod === null ? _jsx("span", { className: "muted-cell", children: t({ locale: locale, key: "—" }) }) : formatDate({ iso: entry.lastmod }) })] }, entry.loc))) })] }) }))] }));
+}
+/** The body's content-status switch (REQ 8/9: disabled, loading, error, then raw-vs-table) — kept
+ *  as its own flat sequence of guards rather than a nested ternary inline in {@link SitemapModal}.
+ *
+ * @complexity O(1) — delegates the actual list rendering to {@link SitemapModalTable}. */
+function SitemapModalBody({ locale, sitemapEnabled, modal, }) {
+    const t = useSeoCopy();
+    if (!sitemapEnabled) {
+        return (_jsx("div", { className: "notice", children: t({ locale: locale, key: 'Sitemap is off. Turn on "Sitemap enabled" above to publish one.' }) }));
+    }
+    if (modal.status === "loading")
+        return _jsx("div", { className: "notice", children: t({ locale: locale, key: "Loading sitemap…" }) });
+    if (modal.status === "error") {
+        return (_jsx("div", { className: "notice error", role: "alert", children: modal.error }));
+    }
+    if (modal.view === "raw")
+        return _jsx("pre", { className: "sitemap-modal-raw", children: modal.xmlText });
+    return _jsx(SitemapModalTable, { locale: locale, modal: modal });
+}
+export function SitemapModal({ locale, sitemapEnabled, regenerating, onRegenerate, onClose, useModal = useWiredSitemapModal, }, _optional = {}) {
+    const t = useSeoCopy();
+    const modal = useModal({ enabled: sitemapEnabled, onClose });
+    const { title } = useSitemapPresentation({ locale, modal });
+    const { handleRegenerate } = useSitemapModalRegenerate({ onRegenerate, refetch: modal.refetch });
+    // Native modality keeps Tab from reaching the background, as MediaPickerDialog now does too.
+    return (_jsxs(Dialog, { open: true, title: title, onClose: () => onClose(), className: "settings-dialog tovu-domain-dialog sitemap-modal", children: [_jsx("div", { className: "sitemap-modal-header", children: _jsx(SitemapModalHeaderActions, { locale: locale, modal: modal }) }), _jsx("div", { className: "sitemap-modal-body", children: _jsx(SitemapModalBody, { locale: locale, sitemapEnabled: sitemapEnabled, modal: modal }) }), _jsx("div", { className: "widget-picker-footer", children: _jsxs("span", { className: "editor-actions", children: [_jsx("button", { type: "button", className: "btn-secondary", onClick: handleRegenerate, disabled: regenerating, ...agentHandle({ handle: "seo-sitemap-modal-regenerate" }, {
+                                role: "button",
+                                label: "Rebuild the cached sitemap and refresh this view",
+                            }), children: actionLabel({ pending: regenerating, pendingLabel: t({ locale: locale, key: "Working…" }), idleLabel: t({ locale: locale, key: "Regenerate sitemap" }) }) }), _jsx("button", { type: "button", className: "btn-secondary", onClick: onClose, "data-jini-autofocus": "", ...agentHandle({ handle: "seo-sitemap-modal-close" }, { role: "button", label: "Close the sitemap viewer" }), children: t({ locale: locale, key: "Close" }) })] }) })] }));
+}
+//# sourceMappingURL=SitemapModal.js.map

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

@@ -0,0 +1,6 @@
+import type { SeoMediaPickerSlotProps } from '../options.js';
+export declare function useMediaPickerBridge(required: SeoMediaPickerSlotProps, _optional?: Record<string, never>): {
+    error: string | null;
+    cancel: () => void;
+};
+//# sourceMappingURL=MediaPickerBridge.hooks.d.ts.map

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

@@ -0,0 +1,27 @@
+import { useEffect, useRef, useState } from 'react';
+import { useSeoPorts } from './SeoPorts.hooks.js';
+export function useMediaPickerBridge(required, _optional = {}) {
+    const { mediaPicker } = useSeoPorts();
+    const callbacks = useRef(required);
+    callbacks.current = required;
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        if (!mediaPicker) {
+            setError('Media picker unavailable');
+            return;
+        }
+        const abort = new AbortController();
+        void mediaPicker.pick({ accept: callbacks.current.accept ?? ['image/*'] }, { signal: abort.signal }).then(item => {
+            if (abort.signal.aborted)
+                return;
+            if (item)
+                callbacks.current.onSelect(item);
+            else
+                callbacks.current.onCancel();
+        }).catch(error => { if (!abort.signal.aborted)
+            setError(error instanceof Error ? error.message : 'Media picker unavailable'); });
+        return () => abort.abort();
+    }, [mediaPicker]);
+    return { error, cancel: () => callbacks.current.onCancel() };
+}
+//# sourceMappingURL=MediaPickerBridge.hooks.js.map

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

@@ -0,0 +1,25 @@
+import type { MediaRefFieldController } from '../../models.js';
+import type { AdminSeoPort } from '../../ports.js';
+export type { MediaRefFieldController } from '../../models.js';
+export declare function useMediaRefField({ value, onChange, api }: {
+    value: string;
+    onChange: (value: string) => void;
+    api: AdminSeoPort;
+}, _optional?: Record<string, never>): MediaRefFieldController;
+export declare function useWiredMediaRefField({ value, onChange }: {
+    value: string;
+    onChange: (value: string) => void;
+}, _optional?: Record<string, never>): MediaRefFieldController;
+/** Slot or existing promise picker; no picker implementation is forked into SEO. */
+export declare function useMediaRefPresentation({ value }: {
+    value: string;
+}, _optional?: Record<string, never>): {
+    Picker: import("react").ComponentType<import("../options.js").SeoMediaPickerSlotProps> | undefined;
+    storedReference: boolean;
+};
+export declare function handleSpread({ base, suffix, label }: {
+    base?: string;
+    suffix: string;
+    label: string;
+}, _optional?: Record<string, never>): Record<string, unknown>;
+//# sourceMappingURL=MediaRefField.hooks.d.ts.map

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

@@ -0,0 +1,30 @@
+import { useRef } from 'react';
+import { agentHandle } from '@jini-ai/agentic';
+import { useController } from '../../../core/react/use-controller.js';
+import { createMediaRefController } from '../../controllers/media-ref.controller.js';
+import { isStoredMediaRef, resolveMediaRefPreviewUrl } from '../../rules.js';
+import { useSeoPorts, useSeoOptions } from './SeoPorts.hooks.js';
+export function useMediaRefField({ value, onChange, api }, _optional = {}) {
+    const change = useRef(onChange);
+    change.current = onChange;
+    const { controller, snapshot } = useController({ create: () => createMediaRefController({ onChange: value => change.current(value) }), dependencies: [] });
+    return {
+        pickerOpen: snapshot?.pickerOpen ?? false,
+        openPicker: () => controller?.openPicker({}), closePicker: () => controller?.closePicker({}),
+        handleSelect: item => controller?.handleSelect({ item }), clear: () => controller?.clear({}),
+        previewUrl: resolveMediaRefPreviewUrl({ value, mediaOriginalUrl: id => api.mediaOriginalUrl({ id }) }), accept: ['image/*'],
+    };
+}
+export function useWiredMediaRefField({ value, onChange }, _optional = {}) {
+    const { seoApi: api } = useSeoPorts();
+    return useMediaRefField({ value, onChange, api });
+}
+/** Slot or existing promise picker; no picker implementation is forked into SEO. */
+export function useMediaRefPresentation({ value }, _optional = {}) {
+    const { slots } = useSeoOptions();
+    return { Picker: slots?.MediaPickerDialog, storedReference: isStoredMediaRef({ value }) };
+}
+export function handleSpread({ base, suffix, label }, _optional = {}) {
+    return base ? agentHandle({ handle: `${base}-${suffix}` }, { role: 'button', label }) : {};
+}
+//# sourceMappingURL=MediaRefField.hooks.js.map

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

@@ -0,0 +1,14 @@
+import type { TabViewProps } from '../../../core/react/bind-react.js';
+import type { SeoTabController } from './SeoPage.hooks.js';
+export declare function SeoDefaultsModuleTab(_required: TabViewProps, _optional?: Record<string, never>): import("react").DetailedReactHTMLElement<{
+    className: string;
+}, HTMLElement> | import("react").ReactElement<{
+    controller: SeoTabController;
+}, string | import("react").JSXElementConstructor<any>>;
+export declare function SeoSitemapModuleTab(_required: TabViewProps, _optional?: Record<string, never>): import("react").DetailedReactHTMLElement<{
+    className: string;
+}, HTMLElement> | import("react").ReactElement<{
+    controller: SeoTabController;
+}, string | import("react").JSXElementConstructor<any>>;
+export declare function SeoEntriesModuleTab(_required: TabViewProps, _optional?: Record<string, never>): import("react").FunctionComponentElement<import("../pages/SeoPage.js").SeoEntrySectionProps>;
+//# sourceMappingURL=SeoModuleTabs.d.ts.map

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

@@ -0,0 +1,18 @@
+import { createElement } from 'react';
+import { SeoDefaultsTab, SeoSitemapTab, SeoEntrySection } from '../pages/SeoPage.js';
+import { useWiredSeo } from './use-seo.hooks.js';
+import { useSeoCopy } from './SeoPorts.hooks.js';
+/** Standalone lazy tab mounts share the same controllers and markup as the page-owned panels. */
+function useSettingsTab({ Panel }) {
+    const controller = useWiredSeo();
+    const t = useSeoCopy();
+    if (controller.error && !controller.settings)
+        return createElement('div', { className: 'notice error' }, controller.error);
+    if (!controller.settings)
+        return createElement('div', { className: 'notice' }, t({ key: 'Loading SEO settings…' }));
+    return createElement(Panel, { controller: { ...controller, settings: controller.settings } });
+}
+export function SeoDefaultsModuleTab(_required, _optional = {}) { return useSettingsTab({ Panel: SeoDefaultsTab }); }
+export function SeoSitemapModuleTab(_required, _optional = {}) { return useSettingsTab({ Panel: SeoSitemapTab }); }
+export function SeoEntriesModuleTab(_required, _optional = {}) { return createElement(SeoEntrySection, { locale: 'en' }); }
+//# sourceMappingURL=SeoModuleTabs.js.map