@caretcms/core 0.2.0 → 0.4.0

package/static/cms/dev-toolbar/app.js

@@ -10,6 +10,19 @@ import { defineToolbarApp } from "astro/toolbar";
 // keeps working in `output: 'static'` projects where /__caret/ is not served.
 // If helpers.js changes, keep these two in sync.
 
+/**
+ * @typedef {{ collection: string | null, id: string | null, field: string }} ParsedBinding
+ * @typedef {{ collection: string, id: string, field: string }} ResolvedBinding
+ * @typedef {"text" | "image" | "rich"} BindingKind
+ * @typedef {{ el: Element, index: number, collection: string, id: string, field: string, key: string, kind: BindingKind }} PageBinding
+ * @typedef {{ el: Element, attr: string, kind: BindingKind, index: number }} OrphanBinding
+ * @typedef {{ bindings: PageBinding[], orphans: OrphanBinding[], duplicates: PageBinding[], stega: boolean, total: number }} BindingScan
+ */
+
+/**
+ * @param {string} attr
+ * @returns {ParsedBinding | null}
+ */
 function parseCaretAttr(attr) {
   const parts = attr.split("::");
   if (parts.length === 3) return { collection: parts[0], id: parts[1], field: parts[2] };
@@ -17,11 +30,18 @@ function parseCaretAttr(attr) {
   return null;
 }
 
+/**
+ * @param {Element} el
+ * @param {ParsedBinding | null} parsed
+ * @returns {ResolvedBinding | null}
+ */
 function resolveBinding(el, parsed) {
   if (!parsed) return null;
   // Explicit null check, not truthiness — mirrors helpers.js; see the parity
   // test (tests/unit/caret-parser-parity.test.ts).
-  if (parsed.collection !== null && parsed.id !== null) return parsed;
+  if (parsed.collection !== null && parsed.id !== null) {
+    return { collection: parsed.collection, id: parsed.id, field: parsed.field };
+  }
   let node = el.parentElement;
   while (node) {
     const scope = node.getAttribute("data-caret-scope");
@@ -35,13 +55,21 @@ function resolveBinding(el, parsed) {
 }
 
 function devConfig() {
-  const c = (typeof window !== "undefined" && window.__CARET_DEV__) || {};
+  const c =
+    (typeof window !== "undefined" &&
+      /** @type {Window & { __CARET_DEV__?: { mountPath?: unknown, apiBasePath?: unknown } }} */ (window)
+        .__CARET_DEV__) ||
+    {};
   return {
     mountPath: typeof c.mountPath === "string" ? c.mountPath : "/admin",
     apiBasePath: typeof c.apiBasePath === "string" ? c.apiBasePath : "/api/cms",
   };
 }
 
+/**
+ * @param {Element} el
+ * @returns {BindingKind}
+ */
 function classify(el) {
   if (el.tagName.toLowerCase() === "img") return "image";
   if (el.hasAttribute("data-caret-rich")) return "rich";
@@ -50,9 +78,12 @@ function classify(el) {
 
 // Walk the page and resolve every data-caret element to a full key, splitting
 // out orphans (field-only attrs with no resolvable scope) and duplicate keys.
+/** @returns {BindingScan} */
 function scanBindings() {
   const els = Array.from(document.querySelectorAll("[data-caret]"));
+  /** @type {PageBinding[]} */
   const bindings = [];
+  /** @type {OrphanBinding[]} */
   const orphans = [];
 
   els.forEach((el, i) => {
@@ -75,9 +106,10 @@ function scanBindings() {
     });
   });
 
+  /** @type {Map<string, number>} */
   const counts = new Map();
   bindings.forEach((b) => counts.set(b.key, (counts.get(b.key) || 0) + 1));
-  const duplicates = bindings.filter((b) => counts.get(b.key) > 1);
+  const duplicates = bindings.filter((b) => (counts.get(b.key) ?? 0) > 1);
 
   // Stega-encoded bindings (live-loader content) only become real data-caret
   // attributes after the editor's stega-hydrate.js runs, which needs auth — so
@@ -93,6 +125,7 @@ function scanBindings() {
 // be told apart when both are active at once.
 const HIGHLIGHT_STYLE_ID = "__caret-devtoolbar-highlight__";
 
+/** @param {boolean} active */
 function applyHighlight(active) {
   const existing = document.getElementById(HIGHLIGHT_STYLE_ID);
   if (existing) existing.remove();
@@ -107,22 +140,43 @@ function applyHighlight(active) {
   document.head.appendChild(style);
 }
 
+/**
+ * Repeated jumps share the first inline style snapshot so overlapping timers
+ * cannot restore a temporary outline and leave it stuck on the page.
+ * @type {WeakMap<HTMLElement | SVGElement, { outline: string, outlineOffset: string, timer: number }>}
+ */
+const scrollFlashes = new WeakMap();
+
+/** @param {Element} el */
 function scrollTo(el) {
   el.scrollIntoView({ behavior: "smooth", block: "center" });
-  const prev = el.style.outline;
-  const prevOffset = el.style.outlineOffset;
+  if (!(el instanceof HTMLElement || el instanceof SVGElement)) return;
+
+  const active = scrollFlashes.get(el);
+  if (active) window.clearTimeout(active.timer);
+  const outline = active?.outline ?? el.style.outline;
+  const outlineOffset = active?.outlineOffset ?? el.style.outlineOffset;
   el.style.outline = "3px solid #6366f1";
   el.style.outlineOffset = "3px";
-  setTimeout(() => {
-    el.style.outline = prev;
-    el.style.outlineOffset = prevOffset;
+  const timer = window.setTimeout(() => {
+    const current = scrollFlashes.get(el);
+    if (!current || current.timer !== timer) return;
+    el.style.outline = current.outline;
+    el.style.outlineOffset = current.outlineOffset;
+    scrollFlashes.delete(el);
   }, 1500);
+  scrollFlashes.set(el, { outline, outlineOffset, timer });
 }
 
+/** @type {Record<BindingKind, string>} */
 const KIND_LABEL = { text: "text", image: "image", rich: "rich" };
 
+/** @type {Record<string, string>} */
+const HTML_ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" };
+
+/** @param {string} s */
 function esc(s) {
-  return String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+  return s.replace(/[&<>"]/g, (c) => HTML_ESCAPES[c] ?? c);
 }
 
 const PANEL_CSS = `
@@ -169,19 +223,22 @@ export default defineToolbarApp({
     canvas.appendChild(win);
 
     let highlightOn = false;
+    /** @type {BindingScan} */
     let scan = { bindings: [], orphans: [], duplicates: [], stega: false, total: 0 };
 
     function render() {
       scan = scanBindings();
       const { mountPath } = devConfig();
-      const { bindings, orphans, duplicates, stega, total } = scan;
+      const { bindings, orphans, duplicates, stega } = scan;
 
       // Group bindings by collection::id, preserving first-seen order.
+      /** @type {Map<string, PageBinding[]>} */
       const groups = new Map();
       for (const b of bindings) {
         const gk = `${b.collection}::${b.id}`;
-        if (!groups.has(gk)) groups.set(gk, []);
-        groups.get(gk).push(b);
+        const rows = groups.get(gk);
+        if (rows) rows.push(b);
+        else groups.set(gk, [b]);
       }
 
       const dupKeys = new Set(duplicates.map((d) => d.key));
@@ -192,8 +249,8 @@ export default defineToolbarApp({
           <span class="count">${bindings.length} on page${orphans.length ? ` · ${orphans.length} orphan${orphans.length > 1 ? "s" : ""}` : ""}</span>
         </div>
         <div class="actions">
-          <button class="btn ${highlightOn ? "on" : ""}" data-action="highlight">${highlightOn ? "Hide" : "Highlight"} all</button>
-          <button class="btn" data-action="rescan">Rescan</button>
+          <button type="button" class="btn ${highlightOn ? "on" : ""}" data-action="highlight" aria-pressed="${highlightOn}">${highlightOn ? "Hide" : "Highlight"} all</button>
+          <button type="button" class="btn" data-action="rescan">Rescan</button>
         </div>
         <div class="scroll">`;
 
@@ -209,7 +266,7 @@ export default defineToolbarApp({
       }
 
       if (!bindings.length && !orphans.length) {
-        html += `<div class="empty">No <code>data-caret</code> bindings found on this page.${total ? "" : ""}</div>`;
+        html += `<div class="empty">No <code>data-caret</code> bindings found on this page.</div>`;
       }
 
       for (const [gk, rows] of groups) {
@@ -221,7 +278,7 @@ export default defineToolbarApp({
           html += `<div class="row">
             <span class="field ${dupKeys.has(b.key) ? "dup" : ""}">${esc(b.field)}</span>
             <span class="kind ${b.kind}">${KIND_LABEL[b.kind]}</span>
-            <button class="jump" data-action="scroll" data-index="${b.index}">scroll to</button>
+            <button type="button" class="jump" data-action="scroll" data-index="${b.index}">scroll to</button>
           </div>`;
         }
         html += `</div>`;
@@ -229,23 +286,27 @@ export default defineToolbarApp({
 
       html += `</div>`;
       wrap.innerHTML = html;
+      const probs = scan.orphans.length + scan.duplicates.length;
+      app.toggleNotification({ state: probs > 0, level: "warning" });
     }
 
+    /** @param {string | null} index */
     function elementByIndex(index) {
       const b = scan.bindings.find((x) => x.index === Number(index));
       return b ? b.el : null;
     }
 
     wrap.addEventListener("click", (event) => {
+      if (!(event.target instanceof Element)) return;
       const target = event.target.closest("[data-action]");
       if (!target) return;
       const action = target.getAttribute("data-action");
       if (action === "highlight") {
         highlightOn = !highlightOn;
         applyHighlight(highlightOn);
-        app.toggleState({ state: highlightOn });
         target.textContent = `${highlightOn ? "Hide" : "Highlight"} all`;
         target.classList.toggle("on", highlightOn);
+        target.setAttribute("aria-pressed", String(highlightOn));
       } else if (action === "rescan") {
         render();
       } else if (action === "scroll") {
@@ -258,8 +319,6 @@ export default defineToolbarApp({
     app.onToggled(({ state }) => {
       if (!state) return;
       render();
-      const probs = scan.orphans.length + scan.duplicates.length;
-      app.toggleNotification({ state: probs > 0, level: "warning" });
     });
   },
 });

package/static/cms/editor/config.js

@@ -1,4 +1,9 @@
 /** Runtime config injected by the integration bootstrap script. */
+/** @typedef {{ endpoint?: unknown, projectId?: unknown, contentPath?: unknown, publicToken?: unknown, environment?: unknown }} RawCloudConfig */
+/** @typedef {{ endpoint: string, projectId: string, contentPath: string, publicToken: string | null, environment: string | null }} CloudConfig */
+/** @typedef {{ mode?: unknown, mountPath?: unknown, apiBasePath?: unknown, cloud?: RawCloudConfig | null, delivery?: { mode?: unknown } | null, draftMode?: unknown }} RuntimeConfig */
+
+/** @type {RuntimeConfig} */
 const defaults = {
   mode: 'embedded',
   mountPath: '/admin',
@@ -6,8 +11,13 @@ const defaults = {
   cloud: null,
 };
 
-const cfg = (typeof window !== 'undefined' && window.__CARET__) || defaults;
+const injected = typeof window !== 'undefined'
+  ? /** @type {Window & { __CARET__?: RuntimeConfig }} */ (window).__CARET__
+  : undefined;
+/** @type {RuntimeConfig} */
+const cfg = injected || defaults;
 
+/** @param {unknown} value @param {string} fallback */
 function normalizePath(value, fallback) {
   if (!value || typeof value !== 'string') return fallback;
   const trimmed = value.trim();
@@ -18,11 +28,13 @@ function normalizePath(value, fallback) {
     : withLeadingSlash;
 }
 
+/** @param {unknown} value */
 function normalizeEndpoint(value) {
   if (!value || typeof value !== 'string') return '';
   return value.trim().replace(/\/$/, '');
 }
 
+/** @returns {CloudConfig | null} */
 function getCloudConfig() {
   if (!cfg || cfg.mode !== 'cloud' || !cfg.cloud || typeof cfg.cloud !== 'object') {
     return null;
@@ -48,6 +60,7 @@ function getCloudConfig() {
   };
 }
 
+/** @param {CloudConfig} cloud */
 function getStorageKey(cloud) {
   return `caretcms:cloud-session:${cloud.endpoint}:${cloud.projectId}`;
 }
@@ -57,6 +70,8 @@ export const CMS_MODE = cfg.mode === 'cloud' || cfg.mode === 'hybrid' ? cfg.mode
 export const DELIVERY_MODE =
   cfg.delivery && cfg.delivery.mode === 'static' ? 'static' : 'server';
 
+export function isPolicyDraftMode() { return cfg.draftMode === true; }
+
 export function isStaticDelivery() {
   return DELIVERY_MODE === 'static';
 }
@@ -64,8 +79,8 @@ export function isStaticDelivery() {
 export function isServerDelivery() {
   return !isStaticDelivery();
 }
-export const MOUNT_PATH = normalizePath(cfg.mountPath, defaults.mountPath);
-export const API_BASE = normalizePath(cfg.apiBasePath, defaults.apiBasePath);
+export const MOUNT_PATH = normalizePath(cfg.mountPath, '/admin');
+export const API_BASE = normalizePath(cfg.apiBasePath, '/api/cms');
 export const CLOUD = getCloudConfig();
 export const STUDIO_PATH = CLOUD ? null : `${MOUNT_PATH}/cms`;
 
@@ -74,9 +89,10 @@ export function isCloudMode() {
 }
 
 export function getCloudSessionToken() {
-  if (!isCloudMode() || typeof window === 'undefined') return null;
+  const cloud = CLOUD;
+  if (!cloud || CMS_MODE !== 'cloud' || typeof window === 'undefined') return null;
   try {
-    const value = window.localStorage.getItem(getStorageKey(CLOUD));
+    const value = window.localStorage.getItem(getStorageKey(cloud));
     return value && value.trim() ? value.trim() : null;
   } catch {
     return null;
@@ -84,23 +100,26 @@ export function getCloudSessionToken() {
 }
 
 export function clearCloudSessionToken() {
-  if (!isCloudMode() || typeof window === 'undefined') return;
+  const cloud = CLOUD;
+  if (!cloud || CMS_MODE !== 'cloud' || typeof window === 'undefined') return;
   try {
-    window.localStorage.removeItem(getStorageKey(CLOUD));
+    window.localStorage.removeItem(getStorageKey(cloud));
   } catch {
     // Ignore localStorage failures.
   }
 }
 
+/** @param {string} path @param {URLSearchParams | Record<string, string> | undefined} [search] */
 export function buildCmsUrl(path, search) {
   const normalizedPath = path.startsWith('/') ? path : `/${path}`;
   let url;
 
-  if (isCloudMode()) {
-    url = new URL(`${CLOUD.contentPath}${normalizedPath}`, `${CLOUD.endpoint}/`);
-    url.searchParams.set('projectId', CLOUD.projectId);
-    if (CLOUD.environment) {
-      url.searchParams.set('environment', CLOUD.environment);
+  const cloud = CLOUD;
+  if (CMS_MODE === 'cloud' && cloud) {
+    url = new URL(`${cloud.contentPath}${normalizedPath}`, `${cloud.endpoint}/`);
+    url.searchParams.set('projectId', cloud.projectId);
+    if (cloud.environment) {
+      url.searchParams.set('environment', cloud.environment);
     }
   } else {
     url = new URL(`${API_BASE}${normalizedPath}`, window.location.origin);
@@ -117,9 +136,10 @@ export function buildCmsUrl(path, search) {
 }
 
 export function getEditorLoginUrl(redirectTo = window.location.href) {
-  if (isCloudMode()) {
-    const url = new URL(`${CLOUD.contentPath}/admin`, `${CLOUD.endpoint}/`);
-    url.searchParams.set('projectId', CLOUD.projectId);
+  const cloud = CLOUD;
+  if (CMS_MODE === 'cloud' && cloud) {
+    const url = new URL(`${cloud.contentPath}/admin`, `${cloud.endpoint}/`);
+    url.searchParams.set('projectId', cloud.projectId);
     url.searchParams.set('redirect', redirectTo);
     return url.toString();
   }

package/static/cms/editor/content-map.css

@@ -78,12 +78,19 @@
   display: flex;
   align-items: center;
   justify-content: space-between;
+  width: 100%;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: left;
   padding: 5px 14px;
   cursor: pointer;
   transition: background 0.15s;
 }
 
-.cms-content-map-item:hover {
+.cms-content-map-item:hover,
+.cms-content-map-item:focus-visible {
   background: rgba(255, 255, 255, 0.05);
 }
 

package/static/cms/editor/content-map.js

@@ -1,22 +1,33 @@
 import { buildCmsUrl } from './config.js';
 import { readHeaders } from './security.js';
-import { parseCaretAttr, resolveBinding, getResolvedKey } from './helpers.js';
+import { parseCaretAttr, resolveBinding } from './helpers.js';
 
 /**
  * Content Map dev panel.
  * Lists all data-caret bindings on the current page with override status.
  */
 
+/** @typedef {{ collection: string, id: string, field: string }} ResolvedBinding */
+/** @typedef {{ el: Element, resolved: ResolvedBinding, isImg: boolean, isScoped: boolean, index: number }} MapBinding */
+
+/** @type {HTMLElement | null} */
 let panel = null;
 let isOpen = false;
+let refreshGeneration = 0;
+/** @type {WeakSet<Element>} */
+const mountedButtons = new WeakSet();
 
+/** @returns {HTMLElement} */
 function createPanel() {
   const el = document.createElement('div');
   el.className = 'cms-content-map';
+  el.setAttribute('role', 'region');
+  el.setAttribute('aria-label', 'Content map');
+  el.setAttribute('aria-hidden', 'true');
   el.innerHTML = `
     <div class="cms-content-map-header">
       <span class="cms-content-map-title">Content Map</span>
-      <button type="button" class="cms-content-map-close">&times;</button>
+      <button type="button" class="cms-content-map-close" aria-label="Close content map">&times;</button>
     </div>
     <div class="cms-content-map-body"></div>
   `;
@@ -29,19 +40,32 @@ function createPanel() {
   return el;
 }
 
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {unknown} payload @returns {Record<string, unknown> | null} */
+export function readOverrideData(payload) {
+  if (!isRecord(payload) || !Array.isArray(payload.entries)) return null;
+  const entry = payload.entries[0];
+  return isRecord(entry) && isRecord(entry.data) ? entry.data : null;
+}
+
+/** @param {Iterable<string>} entryKeys @returns {Promise<Map<string, Record<string, unknown>>>} */
 async function loadOverrides(entryKeys) {
+  /** @type {Map<string, Record<string, unknown>>} */
   const overrides = new Map();
   for (const key of entryKeys) {
     const [collection, id] = key.split('::');
+    if (!collection || !id) continue;
     try {
       const res = await fetch(buildCmsUrl('/entries', { collection, id }), {
         headers: readHeaders(),
       });
       if (res.ok) {
-        const data = await res.json();
-        if (data.entries && data.entries.length > 0) {
-          overrides.set(key, data.entries[0].data);
-        }
+        const data = readOverrideData(await res.json());
+        if (data) overrides.set(key, data);
       }
     } catch {
       // Skip failed loads
@@ -50,24 +74,33 @@ async function loadOverrides(entryKeys) {
   return overrides;
 }
 
+/** @param {unknown} data @param {string} path @returns {unknown} */
 function getNestedValue(data, path) {
   const keys = path.split('.');
+  /** @type {unknown} */
   let current = data;
   for (const key of keys) {
-    if (current === null || current === undefined) return undefined;
-    if (typeof current !== 'object') return undefined;
-    current = current[key];
+    if (Array.isArray(current)) {
+      if (!/^\d+$/.test(key)) return undefined;
+      current = current[Number(key)];
+    } else if (isRecord(current)) {
+      if (!Object.hasOwn(current, key)) return undefined;
+      current = current[key];
+    } else return undefined;
   }
   return current;
 }
 
 async function refresh() {
   if (!panel) return;
+  const generation = ++refreshGeneration;
   const body = panel.querySelector('.cms-content-map-body');
   if (!body) return;
 
   const elements = document.querySelectorAll('[data-caret]');
+  /** @type {MapBinding[]} */
   const bindings = [];
+  /** @type {Set<string>} */
   const entryKeys = new Set();
 
   elements.forEach((el) => {
@@ -79,19 +112,20 @@ async function refresh() {
     const key = `${resolved.collection}::${resolved.id}`;
     entryKeys.add(key);
 
-    const isScoped = parsed && !parsed.collection;
+    const isScoped = parsed?.collection === null;
     bindings.push({
       el,
       resolved,
-      fullKey: `${resolved.collection}::${resolved.id}::${resolved.field}`,
       isImg: el instanceof HTMLImageElement,
       isScoped,
+      index: bindings.length,
     });
   });
 
   body.innerHTML = `<div class="cms-content-map-loading">Loading...</div>`;
 
   const overrides = await loadOverrides(entryKeys);
+  if (!isOpen || generation !== refreshGeneration) return;
 
   if (bindings.length === 0) {
     body.innerHTML = `<div class="cms-content-map-empty">No data-caret bindings found on this page.</div>`;
@@ -99,11 +133,13 @@ async function refresh() {
   }
 
   // Group by collection::id
+  /** @type {Map<string, MapBinding[]>} */
   const groups = new Map();
   for (const b of bindings) {
-    const key = `${b.resolved.collection}::${b.resolved.id}`;
-    if (!groups.has(key)) groups.set(key, []);
-    groups.get(key).push(b);
+    const groupKey = `${b.resolved.collection}::${b.resolved.id}`;
+    const group = groups.get(groupKey) ?? [];
+    group.push(b);
+    groups.set(groupKey, group);
   }
 
   let html = '';
@@ -123,13 +159,13 @@ async function refresh() {
       const typeTag = f.isImg ? '<span class="cms-map-type">img</span>' : '';
 
       html += `
-        <div class="cms-content-map-item" data-caret-map-key="${escapeAttr(f.fullKey)}">
+        <button type="button" class="cms-content-map-item" data-caret-map-index="${f.index}">
           <span class="cms-content-map-field">${escapeHtml(f.resolved.field)}</span>
           <span class="cms-content-map-tags">
             ${typeTag}${scopeTag}
             <span class="cms-map-status ${statusClass}">${statusLabel}</span>
           </span>
-        </div>
+        </button>
       `;
     }
 
@@ -141,8 +177,9 @@ async function refresh() {
   // Click to scroll to element
   body.querySelectorAll('.cms-content-map-item').forEach((item) => {
     item.addEventListener('click', () => {
-      const key = item.getAttribute('data-caret-map-key');
-      const target = bindings.find((b) => b.fullKey === key);
+      const rawIndex = item.getAttribute('data-caret-map-index');
+      const index = rawIndex !== null && /^\d+$/.test(rawIndex) ? Number(rawIndex) : -1;
+      const target = bindings[index];
       if (target?.el) {
         target.el.scrollIntoView({ behavior: 'smooth', block: 'center' });
         target.el.classList.add('cms-map-highlight');
@@ -156,17 +193,19 @@ function toggle() {
   if (!panel) panel = createPanel();
   isOpen = !isOpen;
   panel.classList.toggle('cms-content-map-open', isOpen);
+  panel.setAttribute('aria-hidden', String(!isOpen));
   if (isOpen) refresh();
+  else refreshGeneration++;
 }
 
+/** @param {string} str @returns {string} */
 function escapeHtml(str) {
   return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
-function escapeAttr(str) {
-  return str.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
-}
-
+/** @param {{ mapButton: Element | null }} options */
 export function mountContentMap({ mapButton }) {
-  mapButton?.addEventListener('click', toggle);
+  if (!mapButton || mountedButtons.has(mapButton)) return;
+  mountedButtons.add(mapButton);
+  mapButton.addEventListener('click', toggle);
 }

package/static/cms/editor/deployment-status.js

@@ -0,0 +1,66 @@
+/** @typedef {'saving' | 'idle' | 'error'} ToolbarStatusState */
+/**
+ * @typedef {object} DeploymentStatusResponse
+ * @property {boolean} configured
+ * @property {'deploying' | 'live' | 'failed' | 'unknown'} state
+ * @property {unknown} [target]
+ * @property {unknown} [buildId]
+ */
+
+/**
+ * Poll the authenticated deployment route and translate provider states into
+ * the toolbar's small status surface.
+ *
+ * @param {{
+ *   fetchStatus: () => Promise<Response>,
+ *   setStatus: (state: ToolbarStatusState, text: string) => void,
+ *   setBuildId: (buildId: string | null) => void,
+ *   pollDelayMs?: number,
+ *   setTimer?: (callback: () => void, delay: number) => number,
+ *   clearTimer?: (timer: number) => void,
+ * }} options
+ */
+export function createDeploymentStatusPoller(options) {
+  const pollDelayMs = options.pollDelayMs ?? 1000;
+  const setTimer = options.setTimer ?? ((callback, delay) => window.setTimeout(callback, delay));
+  const clearTimer = options.clearTimer ?? ((timer) => window.clearTimeout(timer));
+  let timer = 0;
+
+  function stop() {
+    if (timer) clearTimer(timer);
+    timer = 0;
+  }
+
+  function schedule() {
+    stop();
+    timer = setTimer(() => { void refresh(); }, pollDelayMs);
+  }
+
+  async function refresh() {
+    try {
+      const response = await options.fetchStatus();
+      if (!response.ok) return;
+      const data = /** @type {DeploymentStatusResponse} */ (await response.json());
+      if (!data.configured || !data.target) return;
+      options.setBuildId(typeof data.buildId === 'string' ? data.buildId : null);
+      if (data.state === 'deploying') {
+        options.setStatus('saving', 'Deploying…');
+        schedule();
+      } else if (data.state === 'live') {
+        stop();
+        options.setStatus('idle', 'Live');
+      } else if (data.state === 'failed') {
+        stop();
+        options.setStatus('error', 'Deploy failed');
+      } else {
+        stop();
+        options.setStatus('error', 'Deploy status unknown');
+      }
+    } catch {
+      // A transient status lookup must not turn a successful content save into
+      // an error. A reload or a scheduled in-flight check can retry later.
+    }
+  }
+
+  return { refresh, schedule, stop };
+}