create-nextblock 0.15.9 → 0.16.1

package/templates/nextblock-template/components/seo/SocialPreviewDialog.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+import { useState } from 'react';
+import { Share2 } from 'lucide-react';
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@nextblock-cms/ui';
+import SocialPreview from './SocialPreview';
+
+/**
+ * The share-card rehearsal, moved behind a button.
+ *
+ * WHY A MODAL. `SocialPreview` renders three platform tabs above a 1.91:1 card that is up
+ * to 520px wide, so inline it costs roughly four hundred vertical pixels in the middle of
+ * a page/post settings form that is already long enough to scroll. That is a poor trade for
+ * something an author consults once while wording a description and then never looks at
+ * again for the rest of the session. Behind a trigger it costs one line, and the moment it
+ * IS wanted it gets the whole viewport instead of a squeezed column.
+ *
+ * WHY THE PRESENTATIONAL COMPONENT STAYS UNTOUCHED. `SocialPreview` knows how three feeds
+ * clip a headline and nothing else — no open state, no trigger, no dialog. Keeping that
+ * split means the same preview can still be dropped inline anywhere it earns the space
+ * (a future site-wide SEO screen, a publish-confirmation step) without having to be
+ * unwrapped from a modal first. This component owns the disclosure; that one owns the
+ * drawing.
+ *
+ * WHY IT STAYS LIVE WHILE OPEN. The props below are the caller's live form state, so every
+ * keystroke in the meta fields behind the dialog repaints the card — the same behaviour the
+ * inline version had. The dialog is a React portal, not a snapshot, so nothing is frozen at
+ * open time and there is no "reopen to refresh" trap.
+ *
+ * NOTHING HERE PERSISTS. This component holds exactly one piece of state — whether the
+ * modal is open — and it is read by nobody but Radix. It contributes no form field, no
+ * FormData entry, and no input to the caller's autosave diff.
+ */
+interface SocialPreviewDialogProps {
+  description: string;
+  imageUrl?: string | null;
+  siteName?: string | null;
+  title: string;
+  /** Optional override for the trigger label, for surfaces that word it differently. */
+  triggerLabel?: string;
+  url: string;
+}
+
+export default function SocialPreviewDialog({
+  description,
+  imageUrl,
+  siteName,
+  title,
+  triggerLabel = 'Preview share card',
+  url,
+}: SocialPreviewDialogProps) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <Dialog onOpenChange={setIsOpen} open={isOpen}>
+      {/* `asChild` so the trigger is the house `Button` rather than a bare Radix button, and
+          `type="button"` explicitly: this renders inside the page/post `<form>`, where a
+          button that inherits the default `submit` type would save the record instead of
+          opening a preview. The visible text is the accessible name, and Radix leaves the
+          element a real focusable button, so keyboard and pointer reach it identically. */}
+      <DialogTrigger asChild>
+        <Button className="h-7 px-2 text-[11px]" size="sm" type="button" variant="outline">
+          <Share2 aria-hidden="true" className="mr-1.5 h-3.5 w-3.5" />
+          {triggerLabel}
+        </Button>
+      </DialogTrigger>
+
+      {/* The card is tall and the platform switcher sits above it, so the panel is capped at
+          85% of the viewport and the BODY scrolls rather than the dialog growing past the
+          screen edge — on a laptop in a browser with devtools open, an uncapped panel would
+          push its own close button out of reach. `overflow-hidden` on the shell keeps the
+          rounded corners from being cut by the scrolling child. */}
+      <DialogContent className="flex max-h-[85vh] flex-col gap-0 overflow-hidden sm:max-w-[600px]">
+        {/* `pr-8` reserves room for the close affordance the dialog draws at top-right. */}
+        <DialogHeader className="flex-shrink-0 pb-4 pr-8">
+          <DialogTitle>Share preview</DialogTitle>
+          <DialogDescription>
+            How this link is likely to appear when it is shared. Edit the meta title and
+            description behind this dialog and the card updates as you type.
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="flex-grow overflow-y-auto py-1">
+          <SocialPreview
+            description={description}
+            imageUrl={imageUrl}
+            siteName={siteName}
+            title={title}
+            url={url}
+          />
+        </div>
+
+        {/* Stated once here rather than repeated on each tab: the numbers in the preview are
+            tuned to observed rendering, and every platform reserves the right to reflow. */}
+        <p className="flex-shrink-0 pt-3 text-[11px] leading-snug text-muted-foreground">
+          Truncation is approximate — each platform reflows link previews on its own terms —
+          so treat a card that clips here as a prompt to shorten the copy, not a guarantee.
+        </p>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/templates/nextblock-template/lib/cortex-ai/alt-text-request.ts

@@ -0,0 +1,86 @@
+/**
+ * Helpers for assembling a valid `POST /api/ai/seo/alt-text` body from what the CMS has
+ * on hand. Both call sites — the image block editor and the media library edit form —
+ * face the same two problems, so they are solved once here.
+ */
+
+/**
+ * Turn whatever the CMS has for an image into a URL the AI vision call can actually fetch.
+ *
+ * Why this is not just "pass the src along": `/api/ai/seo/alt-text` does not receive the
+ * image bytes, it receives a URL, and the AI SDK downloads that URL *server-side* before
+ * handing the image to the model. A relative path is meaningless in that context — there
+ * is no document base to resolve it against — so the route rejects anything that is not
+ * absolute http(s).
+ *
+ * And relative is the common case, not the exotic one. `resolveMediaUrl()` returns
+ * `/${objectKey}` whenever `NEXT_PUBLIC_R2_BASE_URL` is unset, which is exactly how the
+ * native Supabase-storage backend runs. So on a default install every single image in
+ * the library would otherwise fail the alt-text call. Resolving against
+ * `window.location.origin` fixes that for any deployment the browser can reach, which is
+ * the same origin the server is serving from.
+ *
+ * The remaining failure the caller must surface rather than swallow is a `blob:` or
+ * `data:` src (an un-uploaded local preview): the server cannot fetch either, so we
+ * return null and let the UI say so instead of firing a request that is certain to 400.
+ */
+export function toAbsoluteImageUrl(url: string | null | undefined): string | null {
+  const candidate = (url ?? '').trim();
+  if (!candidate) {
+    return null;
+  }
+
+  if (/^https?:\/\//i.test(candidate)) {
+    return candidate;
+  }
+
+  // Only the browser knows the origin this CMS is being served from; on the server we
+  // have no basis to invent one, so a relative path stays unusable and the caller warns.
+  if (typeof window === 'undefined') {
+    return null;
+  }
+
+  try {
+    const absolute = new URL(candidate, window.location.origin);
+    return absolute.protocol === 'http:' || absolute.protocol === 'https:'
+      ? absolute.toString()
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Shared copy for the inline warning shown when {@link toAbsoluteImageUrl} returns null. */
+export const UNRESOLVABLE_IMAGE_URL_MESSAGE =
+  'This image has no public http(s) address yet, so Cortex AI cannot look at it. Save it to the media library first.';
+
+/**
+ * The route validates `context` with `z.string().max(2000)` inside a `z.strictObject`, so
+ * an over-long value does not get trimmed server-side — it fails the whole request with a
+ * 400. Captions are free-text inputs with no length limit of their own, which makes that
+ * reachable: a long caption would break the alt-text button for reasons the operator could
+ * never guess from the error. Trimming client-side keeps the request valid, and losing the
+ * tail of a 2,000-character caption costs nothing, since context is a hint and the model
+ * has the image itself.
+ */
+const ALT_TEXT_CONTEXT_MAX_LENGTH = 2000;
+
+/**
+ * Join the context fragments a caller has into one string the route will accept, or return
+ * `undefined` when there is nothing worth sending — the field is optional, and an empty
+ * string is a different (and less honest) thing to send than no field at all.
+ */
+export function buildAltTextContext(...fragments: Array<string | null | undefined>): string | undefined {
+  const joined = fragments
+    .map((fragment) => (fragment ?? '').trim())
+    .filter(Boolean)
+    .join(' ');
+
+  if (!joined) {
+    return undefined;
+  }
+
+  return joined.length > ALT_TEXT_CONTEXT_MAX_LENGTH
+    ? joined.slice(0, ALT_TEXT_CONTEXT_MAX_LENGTH)
+    : joined;
+}

package/templates/nextblock-template/lib/cortex-ai/sandbox-headers.ts

@@ -0,0 +1,60 @@
+/**
+ * Sandbox credential passthrough for browser-initiated Cortex AI requests.
+ *
+ * On the hosted sandbox there is no server-side OpenRouter key, because every visitor
+ * shares one deployment and we will not spend the project's credits on strangers.
+ * Instead each visitor pastes their own key into the Cortex AI settings screen, which
+ * stores it in `localStorage`, and every AI call made from the browser forwards it on
+ * the request as a header. The route only reads those headers when
+ * `NEXT_PUBLIC_IS_SANDBOX === 'true'`, so on a real install the headers are ignored
+ * even if something were to send them.
+ *
+ * This lived inline in `NotionEditor.handleAiGenerate` and was about to be copied into
+ * three more call sites (image alt text, media alt text, page/post metadata). Copies
+ * drift: the day a storage key or header name changes, the forgotten copy silently
+ * stops authenticating and the sandbox user sees "no credentials" from one button and
+ * not another. One exported builder keeps that impossible.
+ */
+
+/** localStorage key holding the visitor's own OpenRouter API key on the sandbox. */
+export const CORTEX_AI_SANDBOX_API_KEY_STORAGE_KEY = 'cortex_ai_sandbox_openrouter_api_key';
+
+/** localStorage key holding the visitor's serialized model selection on the sandbox. */
+export const CORTEX_AI_SANDBOX_MODEL_STORAGE_KEY = 'cortex_ai_sandbox_openrouter_model_selection';
+
+/**
+ * Builds the headers for a JSON POST to a Cortex AI route, adding the sandbox
+ * credential headers when — and only when — this build is the sandbox and the visitor
+ * has actually stored a key.
+ *
+ * `localStorage` access is wrapped in try/catch on purpose: a browser configured to
+ * block site data throws on the *accessor itself*, not just on read, and an AI button
+ * that explodes before it can send a request is a far worse failure than one that sends
+ * an unauthenticated request and gets a clean 403 back.
+ */
+export function buildCortexAiRequestHeaders(): Record<string, string> {
+  const headers: Record<string, string> = {
+    'content-type': 'application/json',
+  };
+
+  if (process.env.NEXT_PUBLIC_IS_SANDBOX !== 'true' || typeof window === 'undefined') {
+    return headers;
+  }
+
+  try {
+    const sandboxKey = window.localStorage.getItem(CORTEX_AI_SANDBOX_API_KEY_STORAGE_KEY);
+    const sandboxModel = window.localStorage.getItem(CORTEX_AI_SANDBOX_MODEL_STORAGE_KEY);
+
+    if (sandboxKey) {
+      headers['x-sandbox-openrouter-key'] = sandboxKey;
+    }
+    if (sandboxModel) {
+      headers['x-sandbox-openrouter-model'] = sandboxModel;
+    }
+  } catch {
+    // Storage is unavailable (private window, blocked site data). Fall through with the
+    // plain content-type header; the route will answer 403 and the caller will toast it.
+  }
+
+  return headers;
+}

package/templates/nextblock-template/lib/seo/alt-text-write-back.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  altTextImageIdentity,
+  resolveAltTextWriteBack,
+  STALE_ALT_TEXT_MESSAGE,
+} from './alt-text-write-back';
+
+type ImageContent = {
+  alt_text: string | null;
+  caption: string | null;
+  external_url?: string | null;
+  media_id: string | null;
+  object_key: string | null;
+};
+
+function content(overrides: Partial<ImageContent> = {}): ImageContent {
+  return {
+    alt_text: '',
+    caption: '',
+    external_url: null,
+    media_id: 'media-1',
+    object_key: 'uploads/harvest.jpg',
+    ...overrides,
+  };
+}
+
+describe('altTextImageIdentity', () => {
+  it('identifies a stored image by its object key', () => {
+    expect(altTextImageIdentity(content())).toBe('stored:uploads/harvest.jpg');
+  });
+
+  it('falls back to the editor selection while content has not echoed it back yet', () => {
+    expect(altTextImageIdentity(content({ object_key: null }), 'uploads/just-picked.jpg')).toBe(
+      'stored:uploads/just-picked.jpg'
+    );
+  });
+
+  it('prefers the external URL, because that is the image the editor renders and sends', () => {
+    expect(
+      altTextImageIdentity(
+        content({ external_url: 'https://images.example.com/a.jpg', object_key: 'uploads/old.jpg' }),
+        'uploads/older.jpg'
+      )
+    ).toBe('external:https://images.example.com/a.jpg');
+  });
+
+  it('returns an empty identity when there is no image at all', () => {
+    expect(altTextImageIdentity(content({ media_id: null, object_key: null }))).toBe('');
+    expect(altTextImageIdentity(content({ object_key: '   ' }))).toBe('');
+  });
+
+  it('never confuses an external URL with an object key of the same text', () => {
+    expect(altTextImageIdentity({ external_url: 'x', object_key: null })).not.toBe(
+      altTextImageIdentity({ external_url: null, object_key: 'x' })
+    );
+  });
+});
+
+describe('resolveAltTextWriteBack', () => {
+  it('writes the description into the CURRENT content, not the copy captured at click time', () => {
+    // The caption was typed while the vision call was in flight. Merging into the captured
+    // copy would silently revert it.
+    const current = content({ caption: 'Typed while generating' });
+
+    expect(
+      resolveAltTextWriteBack({
+        capturedIdentity: 'stored:uploads/harvest.jpg',
+        currentContent: current,
+        currentIdentity: 'stored:uploads/harvest.jpg',
+        generatedAltText: 'A field of chamomile at dawn.',
+        objectKey: 'uploads/harvest.jpg',
+      })
+    ).toEqual({
+      alt_text: 'A field of chamomile at dawn.',
+      caption: 'Typed while generating',
+      external_url: null,
+      media_id: 'media-1',
+      object_key: 'uploads/harvest.jpg',
+    });
+  });
+
+  it('writes object_key from the editor selection, matching the typed-alt-text shape exactly', () => {
+    const result = resolveAltTextWriteBack({
+      capturedIdentity: 'stored:uploads/just-picked.jpg',
+      currentContent: content({ object_key: null }),
+      currentIdentity: 'stored:uploads/just-picked.jpg',
+      generatedAltText: 'Chamomile.',
+      objectKey: 'uploads/just-picked.jpg',
+    });
+
+    expect(result?.object_key).toBe('uploads/just-picked.jpg');
+  });
+
+  it('drops the response when the image was replaced mid-flight', () => {
+    // The regression this whole module exists for: alt text describing image A must never
+    // be attached to image B.
+    expect(
+      resolveAltTextWriteBack({
+        capturedIdentity: 'stored:uploads/harvest.jpg',
+        currentContent: content({ object_key: 'uploads/packaging.jpg' }),
+        currentIdentity: 'stored:uploads/packaging.jpg',
+        generatedAltText: 'A field of chamomile at dawn.',
+        objectKey: 'uploads/packaging.jpg',
+      })
+    ).toBeNull();
+  });
+
+  it('drops the response when the image was removed mid-flight, so nothing is resurrected', () => {
+    expect(
+      resolveAltTextWriteBack({
+        capturedIdentity: 'stored:uploads/harvest.jpg',
+        currentContent: content({ media_id: null, object_key: null }),
+        currentIdentity: '',
+        generatedAltText: 'A field of chamomile at dawn.',
+        objectKey: null,
+      })
+    ).toBeNull();
+  });
+
+  it('drops the response when a stored image was swapped for an external URL', () => {
+    const current = content({
+      external_url: 'https://images.example.com/new.jpg',
+      media_id: null,
+      object_key: null,
+    });
+
+    expect(
+      resolveAltTextWriteBack({
+        capturedIdentity: 'stored:uploads/harvest.jpg',
+        currentContent: current,
+        currentIdentity: altTextImageIdentity(current),
+        generatedAltText: 'A field of chamomile at dawn.',
+        objectKey: null,
+      })
+    ).toBeNull();
+  });
+
+  it('refuses to treat two empty identities as a match', () => {
+    expect(
+      resolveAltTextWriteBack({
+        capturedIdentity: '',
+        currentContent: content({ media_id: null, object_key: null }),
+        currentIdentity: '',
+        generatedAltText: 'A field of chamomile at dawn.',
+        objectKey: null,
+      })
+    ).toBeNull();
+  });
+
+  it('offers an explanation that tells the operator the description was discarded', () => {
+    expect(STALE_ALT_TEXT_MESSAGE).toContain('discarded');
+  });
+});

package/templates/nextblock-template/lib/seo/alt-text-write-back.ts

@@ -0,0 +1,109 @@
+/**
+ * The pure core of the "Generate with AI" alt-text write-back in `ImageBlockEditor`.
+ *
+ * A vision call takes seconds, and the block editor stays fully interactive while one is
+ * in flight: the author can remove the image, pick a different one from the library, or
+ * paste an external URL before the description ever arrives. The original handler assumed
+ * the block it started on would still be the block it finished on — it captured `content`
+ * at click time and wrote `{ ...capturedContent, alt_text: generated }` back on completion
+ * — and that assumption is wrong in exactly the cases that matter. Writing the captured
+ * copy back resurrects an image the author had deleted, or pairs a freshly chosen image
+ * with a description of the previous one. The second failure is worse than having no alt
+ * text at all: it is confidently wrong, and the screen-reader user it exists for has no
+ * way to detect that it describes a different picture.
+ *
+ * The fix is to capture the image's IDENTITY rather than a snapshot of the content, and to
+ * discard the response when the block no longer holds that image. This decision lives here
+ * rather than inline in the component because the component cannot be unit-tested in this
+ * workspace — there is no DOM environment — and a rule about what may overwrite an
+ * accessibility field deserves a test.
+ */
+
+/**
+ * The part of an image block's content that says which image is loaded.
+ *
+ * Deliberately structural and snake_case: these are the JSONB attribute names the block
+ * actually stores, so a caller passes its content object straight in without translating.
+ */
+export interface AltTextImageSource {
+  external_url?: string | null;
+  object_key?: string | null;
+}
+
+/**
+ * Shown when a generated description is thrown away because the image moved on. It is
+ * phrased as a fact plus the next step rather than as a failure, because nothing failed —
+ * the model answered, the answer is simply about an image that is no longer here.
+ */
+export const STALE_ALT_TEXT_MESSAGE =
+  'The image changed while Cortex AI was describing it, so that description was discarded. Generate again for the current image.';
+
+/**
+ * A stable string naming the image a block is currently showing, or `''` for no image.
+ *
+ * The external URL wins over the stored object key because that is the order the editor
+ * itself renders and sends in: a block with an `external_url` shows the external image
+ * regardless of any stale `object_key` left beside it. `fallbackObjectKey` mirrors the
+ * editor's `content.object_key || selectedMediaObjectKey` display rule, which exists
+ * because a just-picked image lives in component state for a beat before the parent
+ * echoes it back through `content`.
+ *
+ * The `external:` / `stored:` prefixes keep the two namespaces from ever colliding, so a
+ * URL that happens to equal an object key cannot be mistaken for the same image.
+ */
+export function altTextImageIdentity(
+  source: AltTextImageSource,
+  fallbackObjectKey?: string | null
+): string {
+  const externalUrl = source.external_url?.trim();
+  if (externalUrl) {
+    return `external:${externalUrl}`;
+  }
+
+  const objectKey = (source.object_key || fallbackObjectKey || '').trim();
+  if (objectKey) {
+    return `stored:${objectKey}`;
+  }
+
+  return '';
+}
+
+export interface AltTextWriteBackParams<TContent extends AltTextImageSource> {
+  /** The identity taken at click time, i.e. the image that was actually sent to the model. */
+  capturedIdentity: string;
+  /** The block's content as of right now — never the copy captured at click time. */
+  currentContent: TContent;
+  /** The identity of the image the block holds right now. */
+  currentIdentity: string;
+  generatedAltText: string;
+  /** The editor's `selectedMediaObjectKey`, written through unchanged (see below). */
+  objectKey: string | null | undefined;
+}
+
+/**
+ * Decide what — if anything — the generated description should write back.
+ *
+ * Returns `null` when the response must be dropped: either the image has been replaced or
+ * removed since the request went out, or there was no identifiable image to begin with (an
+ * empty captured identity, which the disabled button should already prevent, is treated as
+ * a mismatch rather than as a match against another empty).
+ *
+ * When it does write, it merges into the CURRENT content and reproduces the exact shape
+ * `handleAltTextChange` uses — the same key set, including `object_key` taken from the
+ * editor's selection state. Making the AI path indistinguishable from typing is what
+ * guarantees the value lands in the block's JSONB attributes through the one save path,
+ * instead of creating a second write shape to keep in sync forever.
+ */
+export function resolveAltTextWriteBack<TContent extends AltTextImageSource>(
+  params: AltTextWriteBackParams<TContent>
+): (TContent & { alt_text: string; object_key: string | null | undefined }) | null {
+  if (!params.capturedIdentity || params.capturedIdentity !== params.currentIdentity) {
+    return null;
+  }
+
+  return {
+    ...params.currentContent,
+    alt_text: params.generatedAltText,
+    object_key: params.objectKey,
+  };
+}

package/templates/nextblock-template/lib/seo/block-content.ts

@@ -0,0 +1,123 @@
+import { extractIntroExcerptFromBlocks, stripHtmlToText } from '../../app/lib/seo';
+
+/**
+ * Flatten a page's or post's block rows into plain prose for the metadata generator.
+ *
+ * `POST /api/ai/seo/metadata` wants the *body copy* — it has to read the page to write a
+ * title and description about it. What the CMS holds instead is a tree of block rows
+ * whose text is scattered across differently-named fields and nested one or two levels
+ * deep inside layout containers. This walks that tree once and returns the readable text.
+ *
+ * It deliberately reuses `stripHtmlToText` from `app/lib/seo.ts` rather than growing a
+ * fourth HTML stripper in this repo. That module was checked before importing it here:
+ * its only import is `import type { Metadata } from 'next'`, a type-only import that is
+ * erased at compile time, so nothing server-only is pulled into the client bundle even
+ * though `app/lib/site-settings.ts` — a different module — imports it under 'server-only'.
+ *
+ * The walk covers the containers that actually nest content today:
+ *  - `section` blocks hold their children in `content.column_blocks`,
+ *  - `hero` blocks hold theirs in `content.slides`,
+ * matching how `collectIntroTextCandidates` in `app/lib/seo.ts` traverses the same shapes.
+ * Anything unrecognized is skipped rather than guessed at, because feeding the model
+ * stray JSON keys produces worse metadata than feeding it less prose.
+ */
+function collectBlockText(value: unknown, collected: string[]): void {
+  if (!value) {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((item) => collectBlockText(item, collected));
+    return;
+  }
+
+  if (typeof value !== 'object') {
+    return;
+  }
+
+  const block = value as {
+    block_type?: string;
+    content?: Record<string, unknown>;
+  };
+
+  if (block.block_type === 'section' || block.block_type === 'hero') {
+    collectBlockText(block.content?.column_blocks, collected);
+    collectBlockText(block.content?.slides, collected);
+    return;
+  }
+
+  if (block.block_type === 'heading') {
+    const headingText = block.content?.text_content;
+    if (typeof headingText === 'string' && headingText.trim()) {
+      collected.push(stripHtmlToText(headingText));
+    }
+    return;
+  }
+
+  if (block.block_type === 'text') {
+    const htmlContent = block.content?.html_content;
+    const textContent = block.content?.text_content;
+    const candidate =
+      typeof htmlContent === 'string'
+        ? stripHtmlToText(htmlContent)
+        : typeof textContent === 'string'
+          ? stripHtmlToText(textContent)
+          : '';
+
+    if (candidate) {
+      collected.push(candidate);
+    }
+  }
+}
+
+/**
+ * Maximum prose we send to the metadata route.
+ *
+ * A meta title and description summarize the *top* of a page; the model does not need
+ * the whole of a 5,000-word article to write 160 characters, and shipping the whole of
+ * it costs tokens and latency on every click of the button. Cutting at a sentence-ish
+ * boundary keeps the tail from ending mid-word, which reads to the model as a typo.
+ */
+const MAX_CONTENT_CHARACTERS = 6000;
+
+export function extractPlainTextFromBlocks(blocks: unknown): string {
+  const collected: string[] = [];
+  collectBlockText(blocks, collected);
+
+  const joined = collected.join('\n\n').trim();
+  if (joined.length <= MAX_CONTENT_CHARACTERS) {
+    return joined;
+  }
+
+  const truncated = joined.slice(0, MAX_CONTENT_CHARACTERS);
+  const lastBoundary = Math.max(truncated.lastIndexOf('. '), truncated.lastIndexOf('\n'));
+  return (lastBoundary > MAX_CONTENT_CHARACTERS / 2
+    ? truncated.slice(0, lastBoundary + 1)
+    : truncated
+  ).trim();
+}
+
+/**
+ * Best available prose for the metadata call, in descending order of usefulness.
+ *
+ * A brand-new page has no blocks yet, and an operator clicking "Generate" on an empty
+ * page should still get something better than a disabled button — the title plus any
+ * editorial summary they have typed is a thin but genuine brief. `fallbacks` is where
+ * the caller passes those: a post's excerpt and subtitle, or a page's title.
+ */
+export function buildSeoContentForGeneration(
+  blocks: unknown,
+  ...fallbacks: Array<string | null | undefined>
+): string {
+  const fromBlocks = extractPlainTextFromBlocks(blocks);
+  if (fromBlocks) {
+    return fromBlocks;
+  }
+
+  const intro = extractIntroExcerptFromBlocks(blocks);
+  const parts = [intro, ...fallbacks]
+    .map((part) => (typeof part === 'string' ? stripHtmlToText(part) : ''))
+    .filter(Boolean);
+
+  return parts.join('\n\n').trim();
+}