create-nextblock 0.16.1 → 0.16.3

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

@@ -1,109 +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,
-  };
-}
+/**
+ * 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

@@ -1,123 +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();
-}
+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();
+}