@prenta/admin 0.92.0 → 0.94.0

package/src/components/seo/SeoEditorPane.tsx

@@ -15,7 +15,7 @@ import {
   type ReactElement,
   type ReactNode,
 } from 'react'
-import { Loader2, Monitor, Smartphone, Sparkles, Wand2 } from 'lucide-react'
+import { ImagePlus, Loader2, Monitor, Smartphone, Sparkles, Trash2, Wand2 } from 'lucide-react'
 import { toast } from 'sonner'
 import type { BrandAlignmentScoreResult } from '@prenta/core/brand-voice'
 import { resolveRenderedMetaTitle } from '@prenta/core/client'
@@ -25,6 +25,9 @@ import {
   stripHtmlTags,
   type SEOAnalysisResult,
 } from '@prenta/core/seo/analysis'
+import { auditPage, type PageAuditResult } from '@prenta/core/seo/page-audit'
+import { buildPageAuditInput } from '../../lib/page-audit-input.js'
+import type { PageSection } from '@prenta/core/page-sections'
 import {
   fetchSeoContentRecord,
   updateSeoFields,
@@ -39,13 +42,21 @@ import { fixBrandVoiceContent } from '../../lib/brand-voice-client.js'
 import { BrandVoiceAlignmentBadge } from '../BrandVoiceAlignmentBadge.js'
 import { InspectorPaneBody, InspectorPaneFooter, InspectorPaneHeader } from '../ui/InspectorPane.js'
 import { Toggle } from '../ui/Toggle.js'
+import { MediaPickerModal } from '../MediaPickerModal.js'
+import { PageAuditPanel } from './PageAuditPanel.js'
+import { SeoCharCount } from './SeoCharCount.js'
+import { SerpPreview } from './SerpPreview.js'
 import { SeoLoading, SeoErrorState, gradeMeta } from './primitives.js'
 import { SeoAccordion, SeoAccordionBadge, SeoAccordionItem } from './SeoAccordion.js'
 import { SeoAnalysisList } from './SeoAnalysisList.js'
 import { SeoInsightsMetrics } from './SeoInsightsMetrics.js'
 import { SeoLinkingSection } from './SeoLinkingSection.js'
 
+// Ranges the audit's title/description checks score against — one definition,
+// so the meter cannot tell an editor they are in range while the check fails.
+const META_TITLE_MIN = 30
 const META_TITLE_MAX = 60
+const META_DESC_MIN = 70
 const META_DESC_MAX = 160
 const KEY_TAKEAWAY_MAX = 240
 const LLMS_DESC_MAX = 160
@@ -66,15 +77,6 @@ function seoBrandChannel(field: AiField): string | undefined {
 const inputCls =
   'w-full rounded-[7px] border border-[var(--bdr)] bg-[var(--card)] px-2.5 py-1.5 text-[12.5px] text-[var(--txt)] placeholder:text-[var(--muted)] focus:border-[var(--acc)] focus:outline-none'
 
-function CharCount({ value, max }: { value: string; max: number }) {
-  const over = value.length > max
-  return (
-    <span className={`text-[11px] ${over ? 'text-[var(--err)]' : 'text-[var(--muted)]'}`}>
-      {value.length}/{max}
-    </span>
-  )
-}
-
 function PaneField({
   label,
   children,
@@ -131,6 +133,18 @@ function PaneToggleRow({
 
 export interface SeoEditorPaneProps {
   entityType: 'page' | 'post'
+  /**
+   * Sections for the page-level SEO/GEO audit. Omit to hide the twin rings —
+   * the audit reads structure (stats, quotes, image slots), which a post body
+   * alone cannot supply.
+   */
+  auditSections?: PageSection[]
+  /**
+   * Reports the audit upward so the rail's tab dot can show the same number
+   * this panel shows. Without it the dot and the panel compute independently
+   * and disagree — which is exactly what they did before the audit existed.
+   */
+  onAuditChange?: (audit: PageAuditResult | null) => void
   /** When absent, draft-only mode — meta fields sync via `onDraftChange`. */
   entityId: string | null
   onClose: () => void
@@ -145,6 +159,8 @@ export interface SeoEditorPaneProps {
 export function SeoEditorPane({
   entityType,
   entityId,
+  auditSections,
+  onAuditChange,
   onClose,
   onSaved,
   contentHtml = '',
@@ -165,6 +181,7 @@ export function SeoEditorPane({
   const [form, setForm] = useState<SeoFieldPayload>({})
   const [previewDevice, setPreviewDevice] = useState<'mobile' | 'desktop'>('mobile')
   const [socialPlatform, setSocialPlatform] = useState<'facebook' | 'twitter'>('facebook')
+  const [imagePickerOpen, setImagePickerOpen] = useState(false)
   const [remoteAnalysis, setRemoteAnalysis] = useState<SEOAnalysisResult | null>(null)
 
   useEffect(() => {
@@ -198,7 +215,24 @@ export function SeoEditorPane({
       .then((rec) => {
         if (!alive) return
         if (!rec) {
-          setError('Could not load this record.')
+          // Same situation as the catch below, reached without a throw.
+          setRecord(null)
+          setForm({
+            metaTitle: draftMeta?.seoTitle ?? '',
+            metaDescription: draftMeta?.seoDescription ?? '',
+            focusKeyword: '',
+            keyTakeaway: '',
+            ogTitle: '',
+            ogDescription: '',
+            canonicalUrl: '',
+            structuredDataType: 'WebPage',
+            noindex: false,
+            nofollow: false,
+            llmsInclude: 'AUTO',
+            llmsDescription: '',
+            llmsSection: '',
+            llmsOptional: false,
+          })
           return
         }
         setRecord(rec)
@@ -210,6 +244,7 @@ export function SeoEditorPane({
           keyTakeaway: rec.keyTakeaway ?? '',
           ogTitle: rec.ogTitle ?? '',
           ogDescription: rec.ogDescription ?? '',
+          ogImage: rec.ogImage ?? '',
           twitterTitle: rec.twitterTitle ?? '',
           twitterDescription: rec.twitterDescription ?? '',
           structuredDataType: rec.structuredDataType ?? 'WebPage',
@@ -221,12 +256,36 @@ export function SeoEditorPane({
           llmsOptional: rec.llmsOptional ?? false,
         })
       })
-      .catch((e: unknown) => alive && setError(e instanceof Error ? e.message : 'Failed to load'))
+      .catch(() => {
+        if (!alive) return
+        // No record is not a failure. Older cms-core resolves this endpoint
+        // through a PUBLISHED-only pipeline, so a saved draft 404s here even
+        // though the matching PUT accepts one — showing an error where the form
+        // belongs made a draft's SEO uneditable. Seed from the document's own
+        // meta instead; saving creates the record.
+        setRecord(null)
+        setForm({
+          metaTitle: draftMeta?.seoTitle ?? '',
+          metaDescription: draftMeta?.seoDescription ?? '',
+          focusKeyword: '',
+          keyTakeaway: '',
+          ogTitle: '',
+          ogDescription: '',
+          canonicalUrl: '',
+          structuredDataType: 'WebPage',
+          noindex: false,
+          nofollow: false,
+          llmsInclude: 'AUTO',
+          llmsDescription: '',
+          llmsSection: '',
+          llmsOptional: false,
+        })
+      })
       .finally(() => alive && setLoading(false))
     return () => {
       alive = false
     }
-  }, [entityType, entityId, isDraft])
+  }, [entityType, entityId, isDraft, draftMeta?.seoTitle, draftMeta?.seoDescription])
 
   useEffect(() => {
     if (isDraft || contentHtml.trim() || !entityId) return
@@ -374,6 +433,52 @@ export function SeoEditorPane({
   const url = record?.url ?? (slug ? `/${slug.replace(/^\//, '')}` : '')
   const displayUrl = record?.url ?? url
 
+  /**
+   * Page-level audit, distinct from `analyzeContent` below: binary checks over
+   * page structure and metadata, spanning a true 0-100. `analyzeContent` stays
+   * as the prose analysis (readability, density) it is good at.
+   *
+   * Built from LIVE form state so the score moves as the editor types. See
+   * `buildPageAuditInput` for which fields feed which check, and for why the
+   * OG image and author are reported as unknown rather than missing.
+   */
+  const audit = useMemo(() => {
+    if (!auditSections) return null
+    return auditPage(
+      buildPageAuditInput({
+        sections: auditSections,
+        // LIVE form state, not the saved record — the score has to move as the
+        // editor types. The page editor builds the same input from the saved
+        // record for its first-paint score; routing both through one builder is
+        // what keeps the two numbers from drifting apart.
+        meta: {
+          metaTitle: form.metaTitle ?? '',
+          metaDescription: form.metaDescription ?? '',
+          focusKeyword: form.focusKeyword ?? '',
+          structuredDataType: form.structuredDataType ?? '',
+          noindex: Boolean(form.noindex),
+          // Directives are edited in the Page tab, so this pane has no live
+          // value to offer — it reads the saved one. Defaulting to `false`
+          // instead would tell the GEO gate that snippets are allowed on a page
+          // that has turned them off.
+          nosnippet: Boolean(record?.nosnippet),
+          llmsInclude: form.llmsInclude ?? 'AUTO',
+          // Live value, so the check flips the moment an image is chosen or
+          // cleared rather than waiting for a save round-trip. `??` and not
+          // `||`: an empty string is a deliberate removal, not "unset".
+          hasOgImage: Boolean(form.ogImage ?? record?.ogImage),
+        },
+        slug,
+        record,
+        fallbackTitle: draftMeta?.seoTitle,
+      }),
+    )
+  }, [auditSections, form, slug, record, draftMeta?.seoTitle])
+
+  useEffect(() => {
+    onAuditChange?.(audit)
+  }, [audit, onAuditChange])
+
   const analysisInput = useMemo(
     () => ({
       title: record?.title ?? draftMeta?.seoTitle ?? '',
@@ -389,7 +494,7 @@ export function SeoEditorPane({
       canonical: form.canonicalUrl,
       ogTitle: form.ogTitle,
       ogDescription: form.ogDescription,
-      ogImage: record?.ogImage ?? undefined,
+      ogImage: (form.ogImage ?? record?.ogImage) || undefined,
     }),
     [record, draftMeta, slug, contentHtml, form, renderedTitle],
   )
@@ -426,6 +531,8 @@ export function SeoEditorPane({
     )
   }
 
+  const shareImage = form.ogImage ?? record?.ogImage ?? ''
+
   const socialTitle =
     socialPlatform === 'twitter'
       ? form.twitterTitle || form.ogTitle || renderedTitle
@@ -447,6 +554,7 @@ export function SeoEditorPane({
       </InspectorPaneHeader>
 
       <InspectorPaneBody>
+        {audit && !loading && <PageAuditPanel audit={audit} />}
         {loading ? (
           <div className="px-5 py-4">
             <SeoLoading />
@@ -520,7 +628,11 @@ export function SeoEditorPane({
                   label="Key takeaway"
                   hint={
                     <span className="flex items-center gap-2">
-                      <CharCount value={form.keyTakeaway ?? ''} max={KEY_TAKEAWAY_MAX} />
+                      <SeoCharCount
+                        value={form.keyTakeaway ?? ''}
+                        max={KEY_TAKEAWAY_MAX}
+                        bar={false}
+                      />
                       {aiButton('keyTakeaway')}
                     </span>
                   }
@@ -564,18 +676,21 @@ export function SeoEditorPane({
                     </button>
                   </div>
                 </div>
-                <div
-                  className={`rounded-[7px] border border-[var(--bdr)] bg-[var(--card)] p-3 ${previewDevice === 'mobile' ? 'max-w-[320px]' : ''}`}
-                >
-                  <p className="truncate text-[11px] text-[var(--suc)]">{displayUrl}</p>
-                  <p className="text-[15px] leading-snug text-[var(--acc)]">{renderedTitle}</p>
-                  <p className="line-clamp-2 text-[12px] text-[var(--sub)]">{desc}</p>
+                <div className={previewDevice === 'mobile' ? 'max-w-[320px]' : ''}>
+                  {/* The title previously rendered in the brand accent, which
+                      made the card a preview of the admin rather than of a
+                      search result. */}
+                  <SerpPreview title={renderedTitle} url={displayUrl} description={desc} />
                 </div>
                 <PaneField
                   label="SEO title"
                   hint={
                     <span className="flex items-center gap-2">
-                      <CharCount value={form.metaTitle ?? ''} max={META_TITLE_MAX} />
+                      <SeoCharCount
+                        value={form.metaTitle ?? ''}
+                        min={META_TITLE_MIN}
+                        max={META_TITLE_MAX}
+                      />
                       {aiButton('metaTitle')}
                     </span>
                   }
@@ -598,7 +713,11 @@ export function SeoEditorPane({
                   label="Meta description"
                   hint={
                     <span className="flex items-center gap-2">
-                      <CharCount value={form.metaDescription ?? ''} max={META_DESC_MAX} />
+                      <SeoCharCount
+                        value={form.metaDescription ?? ''}
+                        min={META_DESC_MIN}
+                        max={META_DESC_MAX}
+                      />
                       {aiButton('metaDescription')}
                     </span>
                   }
@@ -613,7 +732,19 @@ export function SeoEditorPane({
                 {alignmentRow('metaDescription')}
               </SeoAccordionItem>
 
-              <SeoAccordionItem value="social-appearance" title="Social appearance">
+              <SeoAccordionItem
+                value="social-appearance"
+                title="Social appearance"
+                badge={
+                  shareImage ? (
+                    <SeoAccordionBadge tone="good">Image set</SeoAccordionBadge>
+                  ) : (
+                    // A shared link with no image is the single biggest drop in
+                    // engagement, so it is worth stating while collapsed.
+                    <SeoAccordionBadge tone="warn">No image</SeoAccordionBadge>
+                  )
+                }
+              >
                 <p className="text-[11.5px] text-[var(--sub)]">
                   Customize title, description, and image used when sharing on social platforms.
                 </p>
@@ -630,19 +761,34 @@ export function SeoEditorPane({
                     </button>
                   ))}
                 </div>
+                {/*
+                  The share preview and the upload target are one object: the
+                  card an editor is judging is the control they change it with.
+                  Previously the image was display-only — there was no way to
+                  set an OG image from the SEO editor at all.
+                */}
                 <div className="overflow-hidden rounded-[7px] border border-[var(--bdr)]">
-                  {record?.ogImage ? (
+                  {shareImage ? (
                     // eslint-disable-next-line @next/next/no-img-element
                     <img
-                      src={record.ogImage}
+                      src={shareImage}
                       alt=""
-                      className="aspect-[1200/630] w-full bg-[var(--bg)] object-cover"
+                      className="aspect-1200/630 w-full bg-[var(--bg)] object-cover"
                     />
                   ) : (
-                    <div className="flex aspect-[1200/630] w-full items-center justify-center bg-[var(--bg)] text-[12px] text-[var(--muted)]">
-                      No social image — add a featured or OG image
-                    </div>
+                    <button
+                      type="button"
+                      onClick={() => setImagePickerOpen(true)}
+                      className="flex aspect-1200/630 w-full flex-col items-center justify-center gap-1 bg-[var(--bg)] text-[12px] text-[var(--muted)] transition-colors hover:bg-[var(--acc-l)] hover:text-[var(--acc)]"
+                    >
+                      <ImagePlus className="h-5 w-5" aria-hidden />
+                      Choose a share image
+                      <span className="text-[10.5px]">1200×630 or wider, about 1.91:1</span>
+                    </button>
                   )}
+                  {/* Domain / title / description sit between the frame and the
+                      toolbar so the card reads as the shared post, not as a
+                      form with a thumbnail on top. */}
                   <div className="p-2.5">
                     <p className="truncate text-[10.5px] text-[var(--muted)] uppercase">
                       {displayUrl.replace(/^https?:\/\//, '').split('/')[0] || 'yoursite.com'}
@@ -652,6 +798,30 @@ export function SeoEditorPane({
                     </p>
                     <p className="line-clamp-2 text-[12px] text-[var(--sub)]">{socialDesc}</p>
                   </div>
+                  {/* Always visible, never hover-only: a control an editor has
+                      to discover by hovering is a control most never find. */}
+                  <div className="flex items-center gap-2 border-t border-[var(--bdr)] bg-[var(--bg)] px-2.5 py-2">
+                    <span className="min-w-0 flex-1 truncate text-[11.5px] text-[var(--sub)]">
+                      {shareImage ? shareImage.split('/').pop() : 'No image selected'}
+                    </span>
+                    <button
+                      type="button"
+                      onClick={() => setImagePickerOpen(true)}
+                      className="shrink-0 rounded-[5px] px-2 py-1 text-[11.5px] font-medium text-[var(--acc)] transition-colors hover:bg-[var(--acc-l)]"
+                    >
+                      {shareImage ? 'Replace' : 'Choose'}
+                    </button>
+                    {shareImage && (
+                      <button
+                        type="button"
+                        onClick={() => update({ ogImage: '' })}
+                        aria-label="Remove share image"
+                        className="shrink-0 rounded-[5px] p-1 text-[var(--muted)] transition-colors hover:bg-[var(--err-l)] hover:text-[var(--err)]"
+                      >
+                        <Trash2 className="h-3.5 w-3.5" aria-hidden />
+                      </button>
+                    )}
+                  </div>
                 </div>
                 {socialPlatform === 'facebook' ? (
                   <>
@@ -775,7 +945,13 @@ export function SeoEditorPane({
                   </PaneField>
                   <PaneField
                     label="Agent description"
-                    hint={<CharCount value={form.llmsDescription ?? ''} max={LLMS_DESC_MAX} />}
+                    hint={
+                      <SeoCharCount
+                        value={form.llmsDescription ?? ''}
+                        max={LLMS_DESC_MAX}
+                        bar={false}
+                      />
+                    }
                   >
                     <textarea
                       className={`${inputCls} min-h-16 resize-y`}
@@ -808,6 +984,12 @@ export function SeoEditorPane({
             </SeoAccordion>
           </>
         )}
+        <MediaPickerModal
+          open={imagePickerOpen}
+          onClose={() => setImagePickerOpen(false)}
+          accept="image/*"
+          onSelect={(url) => update({ ogImage: url })}
+        />
       </InspectorPaneBody>
 
       <InspectorPaneFooter>

package/src/components/seo/SerpPreview.tsx

@@ -0,0 +1,41 @@
+'use client'
+
+/**
+ * A search-result preview for the SEO editor.
+ *
+ * Renders the three things a searcher actually sees, in the order and weight
+ * they see them, so an editor can judge a title and description as a result
+ * rather than as two form fields.
+ *
+ * The link blue is a literal, not a token: it is Google's result colour, and
+ * the point of the card is to look like the thing being previewed. Tokenising
+ * it would let a brand accent repaint it and quietly stop it being a preview.
+ * `#8ab4f8` is the dark-scheme equivalent.
+ */
+export interface SerpPreviewProps {
+  title: string
+  /** Full resolved URL, shown above the title as search engines display it. */
+  url: string
+  description: string
+}
+
+export function SerpPreview({ title, url, description }: SerpPreviewProps) {
+  return (
+    <div
+      className="border-border bg-card rounded-lg border px-3 py-[11px]"
+      role="group"
+      aria-label="Search result preview"
+    >
+      <p className="truncate text-[11px] text-emerald-700 dark:text-emerald-400">
+        {url || 'https://example.com/page'}
+      </p>
+      <p className="truncate text-[14px] leading-snug text-[#1a0dab] dark:text-[#8ab4f8]">
+        {title || 'Untitled page'}
+      </p>
+      {/* Two lines is what a result gets; more written here simply is not read. */}
+      <p className="text-muted-foreground line-clamp-2 text-[11.5px] leading-snug">
+        {description || 'No meta description set. Search engines will improvise one.'}
+      </p>
+    </div>
+  )
+}

package/src/hooks/usePageAudit.ts

@@ -0,0 +1,98 @@
+'use client'
+
+import { useCallback, useEffect, useState } from 'react'
+import type { PageSection } from '@prenta/core/page-sections'
+import { auditPage, type PageAuditResult } from '@prenta/core/seo/page-audit'
+import { fetchSeoContentRecord, type SeoContentRecord } from '../lib/seo-service.js'
+import { buildPageAuditInput, metaFromRecord } from '../lib/page-audit-input.js'
+
+export interface UsePageAuditArgs {
+  entityType: 'page' | 'post'
+  /** Null for an unsaved document — there is no record to audit against yet. */
+  entityId: string | null
+  sections: PageSection[]
+  slug: string
+  /**
+   * The document's own meta, used when no SEO record exists yet. A page that
+   * has never had SEO edited still has a title, a description and sections —
+   * it is scoreable, and refusing to score it leaves the header chip blank on
+   * exactly the pages that most need the nudge.
+   */
+  fallback?: { title?: string; description?: string }
+}
+
+/**
+ * The page's audit, from its saved SEO record — or from the document's own
+ * fields when no record exists yet, so every page has a number.
+ *
+ * This exists so the header chip and the rail's tab dot have a score from first
+ * paint. Previously the audit was computed inside the SEO pane, which mounts
+ * only when its tab is opened — so before that the chip showed a number from a
+ * different scorer with different bands, and the header read 53 beside rings
+ * reading 0 and 57.
+ *
+ * While the SEO pane is open it reports a LIVE audit built from unsaved form
+ * state, which supersedes this one. Both go through `buildPageAuditInput`, so
+ * they differ only in saved-versus-unsaved metadata — the difference an editor
+ * expects to see — and never in how a check is decided.
+ */
+export function usePageAudit({
+  entityType,
+  entityId,
+  sections,
+  slug,
+  fallback,
+}: UsePageAuditArgs): {
+  audit: PageAuditResult
+  record: SeoContentRecord | null
+  reload: () => void
+} {
+  const [record, setRecord] = useState<SeoContentRecord | null>(null)
+  const [nonce, setNonce] = useState(0)
+
+  useEffect(() => {
+    if (!entityId) {
+      setRecord(null)
+      return
+    }
+    let alive = true
+    fetchSeoContentRecord(entityType, entityId)
+      .then((rec) => {
+        if (alive) setRecord(rec)
+      })
+      .catch(() => {
+        // A page that has never had SEO saved has no record. That is not an
+        // error worth surfacing here — the audit simply reports what it can,
+        // and the SEO pane shows its own error state if the user opens it.
+        if (alive) setRecord(null)
+      })
+    return () => {
+      alive = false
+    }
+  }, [entityType, entityId, nonce])
+
+  /**
+   * With a record, audit the saved SEO. Without one, audit the document's own
+   * fields and treat the record-only inputs as unset — which is honest: no
+   * focus keyword has been chosen, no schema has been bound, and nothing has
+   * set noindex. The score is real, and it improves the moment SEO is filled in.
+   */
+  const meta = record
+    ? metaFromRecord(record)
+    : {
+        metaTitle: fallback?.title ?? '',
+        metaDescription: fallback?.description ?? '',
+        focusKeyword: '',
+        structuredDataType: '',
+        noindex: false,
+        nosnippet: false,
+        llmsInclude: 'AUTO',
+        hasOgImage: false,
+      }
+
+  const audit = auditPage(buildPageAuditInput({ sections, meta, slug, record }))
+
+  const reload = useCallback(() => setNonce((n) => n + 1), [])
+
+  return { audit, record, reload }
+}

package/src/hooks/useReflowGuard.ts

@@ -0,0 +1,96 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import type { BreakpointId } from '../lib/breakpoints.js'
+import {
+  probeFieldReflow,
+  reflowSeverity,
+  worstBreakpoint,
+  type FieldLineCount,
+  type ReflowSeverity,
+} from '../lib/reflow-probe.js'
+
+export interface ReflowRow extends FieldLineCount {
+  /** Lines this field ran to in the published version. */
+  was: number
+  /** `lines - was`. Only growth is treated as a problem. */
+  diff: number
+  state: ReflowSeverity
+}
+
+export interface ReflowGuardResult {
+  rows: ReflowRow[]
+  /** Breakpoints where the field now wraps to more lines than published. */
+  grown: ReflowRow[]
+  /** The one worth proofing on, or `null` when nothing grew. */
+  worst: BreakpointId | null
+  /** Character delta against the published string; 0 when there is no baseline. */
+  delta: number
+}
+
+const EMPTY: ReflowGuardResult = { rows: [], grown: [], worst: null, delta: 0 }
+
+/**
+ * Measures how one field wraps at every breakpoint, and how that compares to
+ * what is published.
+ *
+ * ── Why it runs on a delay ────────────────────────────────────────────────
+ *
+ * A pass clones the canvas and lays it out twelve times (six widths, current
+ * and published). That is far too much to do per keystroke, and it is also
+ * pointless — mid-word text tells an editor nothing. So it settles first.
+ *
+ * `null` from the probe means the field is not measurable: the section may be
+ * rendered by a consumer's own component that carries no `data-cms-field`
+ * markers. The guard then reports nothing rather than a number read off the
+ * wrong element — an editor treats a line count as a fact, and a confident
+ * wrong one is worse than a blank.
+ */
+export function useReflowGuard(options: {
+  canvas: HTMLElement | null
+  sectionId: string
+  fieldPath: string
+  /** Current field text. Only used to retrigger — the probe reads the DOM. */
+  value: string
+  /** Published text, or `undefined` when the field has never been published. */
+  baseline: string | undefined
+  /** Skip measuring entirely (field type isn't guarded, panel is collapsed). */
+  enabled?: boolean
+  delayMs?: number
+}): ReflowGuardResult {
+  const { canvas, sectionId, fieldPath, value, baseline, enabled = true, delayMs = 200 } = options
+  const [result, setResult] = useState<ReflowGuardResult>(EMPTY)
+
+  useEffect(() => {
+    if (!enabled || !canvas) {
+      setResult(EMPTY)
+      return
+    }
+
+    const timer = setTimeout(() => {
+      const probed = probeFieldReflow({ canvas, sectionId, fieldPath, baselineText: baseline })
+      if (!probed) {
+        setResult(EMPTY)
+        return
+      }
+
+      const rows: ReflowRow[] = probed.current.map((row) => {
+        const was = probed.baseline.find((b) => b.id === row.id)?.lines ?? row.lines
+        return { ...row, was, diff: row.lines - was, state: reflowSeverity(row.lines, was) }
+      })
+
+      setResult({
+        rows,
+        grown: rows.filter((r) => r.diff > 0),
+        worst: worstBreakpoint(probed.current, probed.baseline),
+        delta: baseline === undefined ? 0 : value.length - baseline.length,
+      })
+    }, delayMs)
+
+    return () => clearTimeout(timer)
+    // `value` is a dependency because the canvas re-renders as it changes —
+    // the probe reads the resulting DOM rather than the string itself.
+  }, [canvas, sectionId, fieldPath, value, baseline, enabled, delayMs])
+
+  return result
+}

package/src/layout/primitives/AdminShell.tsx

@@ -71,6 +71,16 @@ export function AdminShell({
           : { display: 'block', position: 'relative' }
       }
     >
+      {/*
+       * First focusable thing in the admin, so a keyboard user's very first
+       * Tab offers a jump past the sidebar's ~20 nav items. Off-screen until
+       * focused; styling lives in `responsive.css` because it has to survive
+       * a consumer whose Tailwind build does not scan this file.
+       */}
+      <a className="prenta-skip-link" href="#prenta-main">
+        Skip to content
+      </a>
+
       {!isDesktop && mobileSidebarOpen && (
         <div
           aria-hidden
@@ -111,7 +121,9 @@ export function AdminShell({
       >
         {header}
         {breadcrumbs}
-        <main className="min-h-0 flex-1 overflow-y-auto">{children}</main>
+        <main id="prenta-main" className="min-h-0 flex-1 overflow-y-auto">
+          {children}
+        </main>
       </div>
     </div>
   )