@avocadostudio-ai/site-sdk 0.1.0 → 0.2.0

package/dist/middleware.d.ts

@@ -1,24 +1,10 @@
-import { NextResponse, type NextRequest } from "next/server";
+import { type EditorProxyOptions } from "./proxy.ts";
 /**
  * Options for the editor middleware factory.
+ *
+ * @deprecated Use {@link EditorProxyOptions} from `@avocadostudio-ai/site-sdk/proxy`.
  */
-export type EditorMiddlewareOptions = {
-    /**
-     * The internal route prefix that the dynamic editor/draft page lives under.
-     * @default "/preview-draft"
-     */
-    previewRoute?: string;
-    /**
-     * Query parameter that signals an editor iframe request.
-     * @default "__editor"
-     */
-    editorParam?: string;
-    /**
-     * Name of the Next.js draft-mode bypass cookie.
-     * @default "__prerender_bypass"
-     */
-    draftCookie?: string;
-};
+export type EditorMiddlewareOptions = EditorProxyOptions;
 /**
  * Create a Next.js middleware function that rewrites editor/draft requests
  * to a dynamic preview route, keeping the main page route fully static.
@@ -28,9 +14,25 @@ export type EditorMiddlewareOptions = {
  * import { createEditorMiddleware } from "@avocadostudio-ai/site-sdk/middleware"
  * export const { middleware, config } = createEditorMiddleware()
  * ```
+ *
+ * @deprecated Next.js 16 renamed the `middleware` file convention to `proxy`.
+ * Rename `middleware.ts` to `proxy.ts` and switch to `createEditorProxy` from
+ * `@avocadostudio-ai/site-sdk/proxy`. Note that Next 16 rejects this destructured
+ * form — `config` must be a static object literal in the file:
+ * ```ts
+ * import { createEditorProxy } from "@avocadostudio-ai/site-sdk/proxy"
+ *
+ * export const proxy = createEditorProxy().proxy
+ *
+ * export const config = {
+ *   matcher: ["/((?!_next|preview-draft|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)"],
+ * }
+ * ```
+ * This entry point stays for Next.js 15 sites, where the destructured form
+ * works, and returns the identical rewrite under the older export name.
  */
 export declare function createEditorMiddleware(options?: EditorMiddlewareOptions): {
-    middleware: (request: NextRequest) => NextResponse<unknown>;
+    middleware: (request: import("next/server").NextRequest) => import("next/server").NextResponse<unknown>;
     config: {
         matcher: string[];
     };

package/dist/middleware.js

@@ -1,4 +1,4 @@
-import { NextResponse } from "next/server";
+import { createEditorProxy } from "./proxy.js";
 /**
  * Create a Next.js middleware function that rewrites editor/draft requests
  * to a dynamic preview route, keeping the main page route fully static.
@@ -8,27 +8,24 @@ import { NextResponse } from "next/server";
  * import { createEditorMiddleware } from "@avocadostudio-ai/site-sdk/middleware"
  * export const { middleware, config } = createEditorMiddleware()
  * ```
+ *
+ * @deprecated Next.js 16 renamed the `middleware` file convention to `proxy`.
+ * Rename `middleware.ts` to `proxy.ts` and switch to `createEditorProxy` from
+ * `@avocadostudio-ai/site-sdk/proxy`. Note that Next 16 rejects this destructured
+ * form — `config` must be a static object literal in the file:
+ * ```ts
+ * import { createEditorProxy } from "@avocadostudio-ai/site-sdk/proxy"
+ *
+ * export const proxy = createEditorProxy().proxy
+ *
+ * export const config = {
+ *   matcher: ["/((?!_next|preview-draft|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)"],
+ * }
+ * ```
+ * This entry point stays for Next.js 15 sites, where the destructured form
+ * works, and returns the identical rewrite under the older export name.
  */
 export function createEditorMiddleware(options) {
-    const previewRoute = options?.previewRoute ?? "/preview-draft";
-    const editorParam = options?.editorParam ?? "__editor";
-    const draftCookie = options?.draftCookie ?? "__prerender_bypass";
-    function middleware(request) {
-        const isEditor = request.nextUrl.searchParams.get(editorParam) === "1";
-        const hasDraftCookie = request.cookies.has(draftCookie);
-        if (isEditor || hasDraftCookie) {
-            const url = request.nextUrl.clone();
-            url.pathname = `${previewRoute}${url.pathname}`;
-            return NextResponse.rewrite(url);
-        }
-        return NextResponse.next();
-    }
-    // Escape special regex chars in the route prefix (strip leading slash for the pattern)
-    const escapedRoute = previewRoute.slice(1).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const config = {
-        matcher: [
-            `/((?!_next|${escapedRoute}|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)`
-        ],
-    };
-    return { middleware, config };
+    const { proxy, config } = createEditorProxy(options);
+    return { middleware: proxy, config };
 }

package/dist/next-config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/next-config.test.js

@@ -0,0 +1,253 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+// @ts-expect-error — plain ESM, deliberately not TypeScript (see the module's own note)
+import { withAvocado, linkedAvocadoPackages, AVOCADO_SERVER_EXTERNALS } from "../next-config.mjs";
+/**
+ * The list of packages to transpile is derived, not written down, because the
+ * hand-written version breaks retroactively: adding a package to Avocado, or
+ * re-exporting one from another, silently breaks every consumer that pinned the
+ * old list. That is not hypothetical — it took out every route of the Sanity
+ * example the day `@avocadostudio-ai/richtext` was added.
+ */
+function fixture(packages) {
+    const root = mkdtempSync(join(tmpdir(), "avocado-next-config-"));
+    for (const [name, pkg] of Object.entries(packages)) {
+        const [scope, bare] = name.split("/");
+        const dir = join(root, "node_modules", scope, bare);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "package.json"), JSON.stringify({ name, ...pkg }));
+    }
+    return root;
+}
+test("a package whose entry point is TypeScript needs transpiling", () => {
+    const root = fixture({ "@avocadostudio-ai/shared": { main: "src/index.ts" } });
+    assert.deepEqual(linkedAvocadoPackages(root), ["@avocadostudio-ai/shared"]);
+});
+test("a package installed from a registry does not", () => {
+    // Published, `main` points at built JavaScript — listing it would be noise.
+    const root = fixture({ "@avocadostudio-ai/shared": { main: "dist/index.js" } });
+    assert.deepEqual(linkedAvocadoPackages(root), []);
+});
+test("a TypeScript entry hidden in an exports map still counts", () => {
+    const root = fixture({
+        "@avocadostudio-ai/blocks": {
+            main: "dist/index.js",
+            exports: { ".": { import: "./src/index.ts" }, "./styles.css": "./src/styles.css" }
+        }
+    });
+    assert.deepEqual(linkedAvocadoPackages(root), ["@avocadostudio-ai/blocks"]);
+});
+test("both scopes are scanned", () => {
+    const root = fixture({
+        "@avocadostudio-ai/richtext": { main: "src/index.ts" },
+        "@ai-site-editor/immersive-widget": { main: "src/index.ts" },
+        "@unrelated/thing": { main: "src/index.ts" }
+    });
+    assert.deepEqual(linkedAvocadoPackages(root), [
+        "@ai-site-editor/immersive-widget",
+        "@avocadostudio-ai/richtext"
+    ]);
+});
+test("withAvocado adds what is missing and keeps what was declared", () => {
+    const root = fixture({
+        "@avocadostudio-ai/shared": { main: "src/index.ts" },
+        "@avocadostudio-ai/richtext": { main: "src/index.ts" }
+    });
+    const config = withAvocado({ transpilePackages: ["@avocadostudio-ai/shared", "some-other-package"], reactStrictMode: true }, { cwd: root, silent: true });
+    assert.deepEqual(config.transpilePackages, [
+        "@avocadostudio-ai/shared",
+        "some-other-package",
+        "@avocadostudio-ai/richtext"
+    ]);
+    assert.equal(config.reactStrictMode, true, "the rest of the config is untouched");
+});
+test("a config that already declares everything is returned unchanged", () => {
+    /*
+     * The other two halves are switched off because they always have something to
+     * add — image hosts, and the server externals — and this test is about the
+     * transpile contract on its own: when there is nothing to add, the wrapper
+     * hands back the very object it was given rather than a copy.
+     */
+    const root = fixture({ "@avocadostudio-ai/shared": { main: "src/index.ts" } });
+    const input = { transpilePackages: ["@avocadostudio-ai/shared"] };
+    assert.equal(withAvocado(input, { cwd: root, silent: true, images: false, serverExternals: false }), input);
+});
+test("merging image hosts does not disturb the transpile list", () => {
+    const root = fixture({ "@avocadostudio-ai/shared": { main: "src/index.ts" } });
+    const config = withAvocado({ transpilePackages: ["some-other-package"] }, { cwd: root, silent: true });
+    assert.deepEqual(config.transpilePackages, ["some-other-package", "@avocadostudio-ai/shared"]);
+    assert.ok(config.images.remotePatterns.length > 0);
+});
+test("a config with no transpilePackages at all gets the full list", () => {
+    const root = fixture({ "@avocadostudio-ai/shared": { main: "src/index.ts" } });
+    assert.deepEqual(withAvocado({}, { cwd: root, silent: true }).transpilePackages, ["@avocadostudio-ai/shared"]);
+});
+test("an unreadable manifest is skipped rather than thrown on", () => {
+    const root = mkdtempSync(join(tmpdir(), "avocado-next-config-"));
+    const dir = join(root, "node_modules", "@avocadostudio-ai", "broken");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package.json"), "{ not json");
+    assert.deepEqual(linkedAvocadoPackages(root), []);
+});
+test("a directory that does not exist returns nothing instead of failing the build", () => {
+    // The whole point of the helper is that it cannot break `next.config`.
+    assert.deepEqual(linkedAvocadoPackages(join(tmpdir(), "definitely-not-here-9f3a")), []);
+});
+test("this workspace's own linked packages are found", () => {
+    const found = linkedAvocadoPackages(new URL("..", import.meta.url).pathname);
+    assert.ok(found.includes("@avocadostudio-ai/shared"), `shared missing from ${found.join(", ")}`);
+    assert.ok(found.includes("@avocadostudio-ai/blocks"), `blocks missing from ${found.join(", ")}`);
+});
+test("a real consumer picks up the package that broke it", () => {
+    /*
+     * pnpm links only declared dependencies, so this has to be asked from a real
+     * app rather than from this package: `site-sdk` does not depend on
+     * `richtext`, but the Sanity example does — transitively, through `shared`,
+     * which is exactly the shape that caught everyone out.
+     */
+    const found = linkedAvocadoPackages(new URL("../../../examples/sanity-site", import.meta.url).pathname);
+    assert.ok(found.includes("@avocadostudio-ai/richtext"), `richtext missing from ${found.join(", ")}`);
+});
+// ── images.remotePatterns ────────────────────────────────────────────────
+//
+// Four apps in this repo carried the same hand-copied `remotePatterns` block,
+// and the integration docs never mentioned it — so an integrator who followed
+// them got a 500 the first time a user generated an image.
+const NO_ENV = { NODE_ENV: "production" };
+/** A tree with no linked Avocado packages, so these tests see only the image merge. */
+const EMPTY_DIR = mkdtempSync(join(tmpdir(), "avocado-next-config-images-"));
+test("Avocado's own image hosts are added to a config that declares none", () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: NO_ENV });
+    const hosts = config.images.remotePatterns.map((p) => p.hostname);
+    assert.ok(hosts.includes("images.unsplash.com"), hosts.join(", "));
+    assert.ok(hosts.includes("oaidalleapiprodscus.blob.core.windows.net"), hosts.join(", "));
+    assert.ok(hosts.includes("placehold.co"), hosts.join(", "));
+});
+test("the app's own hosts are kept, first and unduplicated", () => {
+    const config = withAvocado({
+        images: {
+            formats: ["image/avif"],
+            remotePatterns: [
+                { protocol: "https", hostname: "cdn.sanity.io" },
+                { protocol: "https", hostname: "images.unsplash.com" },
+            ],
+        },
+    }, { cwd: EMPTY_DIR, env: NO_ENV });
+    const hosts = config.images.remotePatterns.map((p) => p.hostname);
+    assert.equal(hosts[0], "cdn.sanity.io", "the app's own list must keep its order");
+    assert.equal(hosts.filter((h) => h === "images.unsplash.com").length, 1, "duplicated a host the app declared");
+    // Unrelated image settings survive.
+    assert.deepEqual(config.images.formats, ["image/avif"]);
+});
+test("the orchestrator's own origin is allowed when it is configured", () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: { ORCHESTRATOR_URL: "https://orch.example.com" } });
+    const match = config.images.remotePatterns.find((p) => p.hostname === "orch.example.com");
+    assert.ok(match, "orchestrator host missing");
+    assert.equal(match.protocol, "https");
+});
+test("a port on the orchestrator origin is carried through", () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: { ORCHESTRATOR_URL: "http://localhost:4200" } });
+    const match = config.images.remotePatterns.find((p) => p.hostname === "localhost");
+    assert.ok(match, "orchestrator host missing");
+    assert.equal(match.port, "4200");
+});
+test("localhost is assumed in development but never in production", () => {
+    const dev = withAvocado({}, { cwd: EMPTY_DIR, env: { NODE_ENV: "development" } });
+    assert.ok(dev.images.remotePatterns.some((p) => p.hostname === "localhost"), "a local build should reach a local orchestrator without extra config");
+    const prod = withAvocado({}, { cwd: EMPTY_DIR, env: NO_ENV });
+    assert.equal(prod.images.remotePatterns.some((p) => p.hostname === "localhost"), false, "a deployed site must not open its image optimizer to localhost");
+});
+test("a garbage orchestrator URL is ignored rather than thrown on", () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: { ...NO_ENV, ORCHESTRATOR_URL: "not a url" } });
+    assert.ok(Array.isArray(config.images.remotePatterns));
+});
+test("images: false leaves the config's image settings untouched", () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, images: false, env: NO_ENV });
+    assert.equal(config.images, undefined);
+});
+/*
+ * Server externals.
+ *
+ * `orchestrator-core` reaches native binaries and provider SDKs, and a bundler
+ * that swallows either produces a build that succeeds: `sharp` bundled crashes
+ * loading its `.node` file on the first request, and Turbopack — which resolves
+ * `await import(...)` statically — fails `Module not found` over an optional
+ * peer that was deliberately never installed.
+ *
+ * `serverExternalPackages` is the documented knob and is not sufficient alone:
+ * `transpilePackages`, which this same helper fills in, wins for a transitive
+ * dependency. Both halves are asserted here because shipping one is shipping a
+ * fix that does not hold.
+ */
+/** Run the merged `webpack` hook and read back what it externalised. */
+function serverExternals(config) {
+    const result = config.webpack({}, { isServer: true });
+    const fns = (result.externals ?? []).filter((e) => typeof e === "function");
+    return (request) => {
+        for (const fn of fns) {
+            let answer;
+            fn({ request }, (_e, r) => { answer = r; });
+            if (answer)
+                return answer;
+        }
+        return undefined;
+    };
+}
+test("the native and provider dependencies are declared external", () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: NO_ENV });
+    for (const name of ["better-sqlite3", "sharp", "@google/genai", "googleapis"]) {
+        assert.ok(config.serverExternalPackages.includes(name), `${name} must not be bundled into the server build`);
+    }
+});
+test("an app's own server externals are kept, and not duplicated", () => {
+    const config = withAvocado({ serverExternalPackages: ["@sanity/client", "sharp"] }, { cwd: EMPTY_DIR, env: NO_ENV });
+    assert.equal(config.serverExternalPackages[0], "@sanity/client", "the app's own list keeps its order");
+    assert.equal(config.serverExternalPackages.filter((n) => n === "sharp").length, 1, "a package the app already listed must not appear twice");
+});
+test("the webpack hook externalises the same packages, because the array alone does not", () => {
+    // `transpilePackages` overrides `serverExternalPackages` for a transitive
+    // dependency — which is exactly how orchestrator-core reaches sharp.
+    const external = serverExternals(withAvocado({}, { cwd: EMPTY_DIR, env: NO_ENV }));
+    assert.equal(external("better-sqlite3"), "commonjs better-sqlite3");
+    // A deep import has to travel with the package root, or half of it is bundled.
+    assert.equal(external("sharp/lib/libvips.js"), "commonjs sharp/lib/libvips.js");
+    // A package that merely starts with the same letters is not a match.
+    assert.equal(external("sharpen-image"), undefined);
+    assert.equal(external("react"), undefined);
+});
+test("the client bundle is left alone", () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: NO_ENV });
+    assert.equal(config.webpack({}, { isServer: false }).externals, undefined);
+});
+test("an app's own webpack hook still runs, and still wins", () => {
+    const calls = [];
+    const config = withAvocado({
+        webpack(webpackConfig, context) {
+            calls.push(`app:${context.isServer}`);
+            return { ...webpackConfig, resolve: { extensionAlias: { ".js": [".ts"] } } };
+        },
+    }, { cwd: EMPTY_DIR, env: NO_ENV });
+    const result = config.webpack({}, { isServer: true });
+    assert.deepEqual(calls, ["app:true"], "the app's hook must be called exactly once");
+    assert.deepEqual(result.resolve.extensionAlias, { ".js": [".ts"] }, "whatever the app's hook did survives");
+    assert.equal(serverExternals(config)("sharp"), "commonjs sharp");
+});
+test("serverExternals: false leaves both halves to the app", () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, serverExternals: false, env: NO_ENV });
+    assert.equal(config.serverExternalPackages, undefined);
+    assert.equal(config.webpack, undefined, "no hook is attached at all");
+});
+test("externals are applied even when there is nothing to transpile", () => {
+    // The transpile derivation returns early twice — on a config that already
+    // lists every linked package, and on any filesystem error. Neither may skip
+    // the externals, which is why they are applied first.
+    const config = withAvocado({}, { cwd: "/nonexistent-path-for-this-test", env: NO_ENV });
+    assert.ok(config.serverExternalPackages.includes("better-sqlite3"));
+});
+test("the exported list is what the helper actually applies", () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: NO_ENV });
+    assert.deepEqual(config.serverExternalPackages, AVOCADO_SERVER_EXTERNALS);
+});

package/dist/page-metadata.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Page metadata derivation — the `<title>`, description, and social card a
+ * `PageDoc` implies.
+ *
+ * This lived in `apps/site/lib/seo.ts` for most of the project's life, which
+ * meant the one route in the repo that emitted correct metadata was the one
+ * route that did *not* go through `createSitePage`. Every integrator using the
+ * factory shipped pages with no title and no description. Moving it here makes
+ * the good behaviour the default instead of the reference app's private trick.
+ *
+ * Nothing in this file imports from `next`. The return type is structural and
+ * assignable to Next's `Metadata`, but the derivation itself is just data, so
+ * it stays usable from a non-Next renderer.
+ */
+import type { PageDoc } from "./types.ts";
+export declare const DEFAULT_SITE_DESCRIPTION = "Welcome to our site.";
+/** Structurally assignable to Next's `Metadata`, without importing it. */
+export type PageMetadata = {
+    title?: string;
+    description?: string;
+    openGraph?: {
+        title?: string;
+        description?: string;
+        images?: string[];
+        siteName?: string;
+        url?: string;
+        type?: "website";
+    };
+    twitter?: {
+        card?: "summary_large_image";
+        title?: string;
+        description?: string;
+        images?: string[];
+    };
+    alternates?: {
+        canonical?: string;
+    };
+    robots?: {
+        index: boolean;
+        follow: boolean;
+    };
+};
+export declare function stripMarkdown(input: string): string;
+export declare function truncateForMeta(input: string, maxLength?: number): string;
+/**
+ * The best description available for a page: its own, then the first block
+ * that reads like prose, then a generated fallback. Never returns empty — a
+ * missing description is worse than a generic one.
+ */
+export declare function derivePageDescription(page: Pick<PageDoc, "title" | "meta" | "blocks">): string;
+/** The page's own title, falling back to the document title. */
+export declare function derivePageTitle(page: Pick<PageDoc, "title" | "meta">): string;
+export type BuildPageMetadataOptions = {
+    /** Appended as `Title — Site Name` when the page has no title of its own to carry. */
+    siteName?: string;
+    /** Absolute URL of this page, used for the canonical link and `og:url`. */
+    canonical?: string;
+};
+/**
+ * Build the full metadata object for a page.
+ *
+ * A social card needs an image to render as anything but a text link, so the
+ * `summary_large_image` twitter card is only claimed when there is actually an
+ * image to put in it.
+ */
+export declare function buildPageMetadata(page: Pick<PageDoc, "title" | "meta" | "blocks">, options?: BuildPageMetadataOptions): PageMetadata;

package/dist/page-metadata.js

@@ -0,0 +1,110 @@
+/**
+ * Page metadata derivation — the `<title>`, description, and social card a
+ * `PageDoc` implies.
+ *
+ * This lived in `apps/site/lib/seo.ts` for most of the project's life, which
+ * meant the one route in the repo that emitted correct metadata was the one
+ * route that did *not* go through `createSitePage`. Every integrator using the
+ * factory shipped pages with no title and no description. Moving it here makes
+ * the good behaviour the default instead of the reference app's private trick.
+ *
+ * Nothing in this file imports from `next`. The return type is structural and
+ * assignable to Next's `Metadata`, but the derivation itself is just data, so
+ * it stays usable from a non-Next renderer.
+ */
+export const DEFAULT_SITE_DESCRIPTION = "Welcome to our site.";
+/**
+ * Props scanned, in order, for a description when the page declares none.
+ *
+ * Ordered by how likely the value is to read as a summary rather than as a
+ * label: a `description` is written to be one, a `heading` is a last resort.
+ */
+const CANDIDATE_PROP_KEYS = ["description", "subheading", "subtitle", "summary", "excerpt", "body", "text", "heading"];
+/** Shortest block text accepted as a description. Below this it reads as a label, not a summary. */
+const MIN_BLOCK_TEXT = 40;
+/** Search engines truncate around here; writing longer just hides the tail. */
+const MAX_DESCRIPTION = 160;
+export function stripMarkdown(input) {
+    return input
+        .replace(/!\[[^\]]*]\([^)]*\)/g, " ")
+        // The group is load-bearing: without it `$1` has nothing to refer to and
+        // JavaScript inserts those two characters literally, so every description
+        // built from prose containing a link read "Book a $1 with our team".
+        .replace(/\[([^\]]+)]\([^)]*\)/g, "$1")
+        .replace(/[`*_>#~\-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function truncateForMeta(input, maxLength = MAX_DESCRIPTION) {
+    if (input.length <= maxLength)
+        return input;
+    const truncated = input.slice(0, maxLength + 1);
+    const lastSpace = truncated.lastIndexOf(" ");
+    const base = (lastSpace > 80 ? truncated.slice(0, lastSpace) : truncated.slice(0, maxLength)).trim();
+    // A cut that lands just after a sentence already ends in punctuation, and
+    // appending to that produced ".." — trailing punctuation is trimmed first so
+    // the ellipsis-substitute is always exactly one character.
+    return `${base.replace(/[.,;:!?\s]+$/, "")}.`;
+}
+function pickBlockText(page) {
+    for (const block of page.blocks) {
+        for (const key of CANDIDATE_PROP_KEYS) {
+            const value = block.props[key];
+            if (typeof value !== "string")
+                continue;
+            const normalized = stripMarkdown(value);
+            if (normalized.length >= MIN_BLOCK_TEXT)
+                return normalized;
+        }
+    }
+    return null;
+}
+/**
+ * The best description available for a page: its own, then the first block
+ * that reads like prose, then a generated fallback. Never returns empty — a
+ * missing description is worse than a generic one.
+ */
+export function derivePageDescription(page) {
+    const explicit = page.meta?.description?.trim();
+    if (explicit)
+        return truncateForMeta(stripMarkdown(explicit));
+    const blockText = pickBlockText(page);
+    if (blockText)
+        return truncateForMeta(blockText);
+    return truncateForMeta(`${page.title}. ${DEFAULT_SITE_DESCRIPTION}`);
+}
+/** The page's own title, falling back to the document title. */
+export function derivePageTitle(page) {
+    return page.meta?.title?.trim() || page.title;
+}
+/**
+ * Build the full metadata object for a page.
+ *
+ * A social card needs an image to render as anything but a text link, so the
+ * `summary_large_image` twitter card is only claimed when there is actually an
+ * image to put in it.
+ */
+export function buildPageMetadata(page, options = {}) {
+    const title = derivePageTitle(page);
+    const description = derivePageDescription(page);
+    const image = page.meta?.ogImage?.trim();
+    const images = image ? [image] : undefined;
+    return {
+        title,
+        description,
+        openGraph: {
+            title,
+            description,
+            type: "website",
+            ...(images ? { images } : {}),
+            ...(options.siteName ? { siteName: options.siteName } : {}),
+            ...(options.canonical ? { url: options.canonical } : {}),
+        },
+        twitter: {
+            ...(images ? { card: "summary_large_image", images } : {}),
+            title,
+            description,
+        },
+        ...(options.canonical ? { alternates: { canonical: options.canonical } } : {}),
+    };
+}

package/dist/page-metadata.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/page-metadata.test.js

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { buildPageMetadata, derivePageDescription, derivePageTitle, stripMarkdown, truncateForMeta } from "./page-metadata.js";
+const basePage = {
+    id: "p_test",
+    slug: "/test",
+    title: "Test Page",
+    updatedAt: "2026-03-13T00:00:00.000Z",
+    blocks: [],
+};
+test("derivePageDescription prefers an explicit description", () => {
+    const page = { ...basePage, meta: { description: "Explicit description for search snippets." } };
+    assert.equal(derivePageDescription(page), "Explicit description for search snippets.");
+});
+test("derivePageDescription falls back to the first block that reads like prose", () => {
+    const page = {
+        ...basePage,
+        blocks: [
+            { id: "b0", type: "Hero", props: { heading: "Avocados" } },
+            { id: "b1", type: "Hero", props: { subheading: "Learn how to pick, store, and prepare avocados quickly." } },
+        ],
+    };
+    assert.match(derivePageDescription(page), /pick, store, and prepare avocados quickly/i);
+});
+test("derivePageDescription skips block text too short to be a summary", () => {
+    const page = {
+        ...basePage,
+        blocks: [{ id: "b1", type: "CTA", props: { text: "Buy now" } }],
+    };
+    // "Buy now" is a label, not a description — the generated fallback wins.
+    assert.match(derivePageDescription(page), /^Test Page\./);
+});
+test("derivePageDescription strips markdown and caps length", () => {
+    const page = {
+        ...basePage,
+        blocks: [
+            {
+                id: "b2",
+                type: "RichText",
+                props: {
+                    body: "# Title\n\nThis is **a long markdown description** with [a link](https://example.com) that should be normalized and capped to a search-friendly length without weird symbols lingering around.",
+                },
+            },
+        ],
+    };
+    const description = derivePageDescription(page);
+    assert.ok(description.length <= 161, `too long: ${description.length}`);
+    assert.equal(description.includes("**"), false);
+    assert.equal(description.includes("[a link]"), false);
+    /*
+     * The words have to survive, not just the brackets. Asserting only that
+     * "[a link]" is gone passed while the replacement wrote a literal `$1` over
+     * the link text, because the pattern it referred to had no capture group.
+     */
+    assert.ok(description.includes("a link"), `link text was dropped: ${description}`);
+    assert.equal(description.includes("$1"), false, `replacement token leaked: ${description}`);
+});
+test("stripMarkdown keeps link text and drops the target", () => {
+    assert.equal(stripMarkdown("Book a [guided tour](/tours) with our team."), "Book a guided tour with our team.");
+    // An image has no text worth keeping — alt text describes the picture, not
+    // the sentence — so it goes entirely rather than leaving its alt behind.
+    assert.equal(stripMarkdown("Before ![a photo](/p.png) after."), "Before after.");
+});
+test("truncateForMeta ends in exactly one period", () => {
+    const cutAfterASentence = `${"A".repeat(100)} end of the first sentence here. ${"B".repeat(80)}`;
+    const out = truncateForMeta(cutAfterASentence);
+    assert.equal(out.endsWith(".."), false, `doubled the period: ${JSON.stringify(out.slice(-20))}`);
+    assert.equal(out.endsWith("."), true);
+    assert.ok(out.length <= 161, `too long: ${out.length}`);
+});
+test("derivePageDescription never returns empty", () => {
+    assert.ok(derivePageDescription(basePage).length > 0);
+});
+test("derivePageTitle prefers meta.title over the document title", () => {
+    assert.equal(derivePageTitle(basePage), "Test Page");
+    assert.equal(derivePageTitle({ ...basePage, meta: { title: "SEO Title" } }), "SEO Title");
+    // An all-whitespace meta title is not a title.
+    assert.equal(derivePageTitle({ ...basePage, meta: { title: "   " } }), "Test Page");
+});
+test("buildPageMetadata emits title, description and Open Graph", () => {
+    const meta = buildPageMetadata({ ...basePage, meta: { description: "A page about avocados and how to eat them." } });
+    assert.equal(meta.title, "Test Page");
+    assert.equal(meta.description, "A page about avocados and how to eat them.");
+    assert.equal(meta.openGraph?.title, "Test Page");
+    assert.equal(meta.openGraph?.description, "A page about avocados and how to eat them.");
+    assert.equal(meta.openGraph?.type, "website");
+});
+test("buildPageMetadata only claims a large image card when there is an image", () => {
+    const without = buildPageMetadata(basePage);
+    assert.equal(without.openGraph?.images, undefined);
+    assert.equal(without.twitter?.card, undefined);
+    const with_ = buildPageMetadata({ ...basePage, meta: { ogImage: "https://cdn.example.com/og.png" } });
+    assert.deepEqual(with_.openGraph?.images, ["https://cdn.example.com/og.png"]);
+    assert.equal(with_.twitter?.card, "summary_large_image");
+    assert.deepEqual(with_.twitter?.images, ["https://cdn.example.com/og.png"]);
+});
+test("buildPageMetadata carries siteName and canonical when given", () => {
+    const meta = buildPageMetadata(basePage, { siteName: "Avocado Co", canonical: "https://example.com/test" });
+    assert.equal(meta.openGraph?.siteName, "Avocado Co");
+    assert.equal(meta.openGraph?.url, "https://example.com/test");
+    assert.equal(meta.alternates?.canonical, "https://example.com/test");
+    const bare = buildPageMetadata(basePage);
+    assert.equal(bare.alternates, undefined);
+    assert.equal(bare.openGraph?.siteName, undefined);
+});