@avocadostudio-ai/site-sdk 0.1.0 → 0.2.1

package/dist/next-config.test.js

@@ -0,0 +1,355 @@
+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", () => {
+    /*
+     * The shape every `@avocadostudio-ai` package actually has on npm, and the
+     * `types` field is the whole point of the fixture: `dist/index.d.ts` ends in
+     * `.ts`, so a naive TypeScript test matches it and transpiles the published
+     * package — which drags `orchestrator-core` into the bundle and fails the
+     * build on an optional peer.
+     *
+     * This test existed before that was found, with a fixture carrying `main`
+     * alone. It passed, on a package shape that does not occur on a registry.
+     */
+    const root = fixture({
+        "@avocadostudio-ai/shared": { main: "dist/index.js", types: "dist/index.d.ts" }
+    });
+    assert.deepEqual(linkedAvocadoPackages(root), []);
+});
+test("a declaration file in an exports map is not a reason to transpile either", () => {
+    // The same trap one level down: an `exports` map carries its own `types`.
+    const root = fixture({
+        "@avocadostudio-ai/richtext": {
+            main: "dist/index.js",
+            exports: {
+                ".": { types: "./dist/index.d.ts", import: "./dist/index.js" },
+                "./package.json": "./package.json"
+            }
+        }
+    });
+    assert.deepEqual(linkedAvocadoPackages(root), []);
+});
+test("a linked package is still caught when its types point at source", () => {
+    // A workspace checkout points both fields at `src/`; that must still count.
+    const root = fixture({
+        "@avocadostudio-ai/shared": { main: "src/index.ts", types: "src/index.ts" }
+    });
+    assert.deepEqual(linkedAvocadoPackages(root), ["@avocadostudio-ai/shared"]);
+});
+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");
+    assert.equal(config.turbopack, undefined, "and nothing is declared on its behalf");
+});
+/*
+ * On Next 16 Turbopack is the default, and a config with a `webpack` key and no
+ * `turbopack` key fails the build outright — measured, on 16.3.4, against a
+ * project that installed the SDK from a tarball:
+ *
+ *   ERROR: This build is using Turbopack, with a `webpack` config and no
+ *   `turbopack` config.
+ *
+ * Since the hook above is attached whether or not the app asked for one, the
+ * empty Turbopack config has to travel with it.
+ */
+test("attaching a webpack hook also declares the turbopack config Next 16 demands", () => {
+    const config = withAvocado({}, { cwd: EMPTY_DIR, env: NO_ENV });
+    assert.equal(typeof config.webpack, "function", "the hook is still attached");
+    assert.deepEqual(config.turbopack, {}, "an empty turbopack config must travel with it");
+});
+test("an app's own turbopack config is never overwritten", () => {
+    const config = withAvocado({ turbopack: { resolveAlias: { underscore: "lodash" } } }, { cwd: EMPTY_DIR, env: NO_ENV });
+    assert.deepEqual(config.turbopack, { resolveAlias: { underscore: "lodash" } });
+});
+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"));
+});
+/*
+ * Naming orchestrator-core's *dependencies* external does not stop Turbopack
+ * walking into orchestrator-core and resolving its `await import("googleapis")`
+ * statically. Measured on Next 16.3.4 against a real tarball install: the build
+ * fails on an optional peer the project never installed, with every provider
+ * SDK already in `serverExternalPackages`. Externalising the package itself is
+ * the fix, and it is only correct when the package arrived built.
+ */
+test("a registry-installed orchestrator-core is externalised, not walked", () => {
+    const root = fixture({
+        "@avocadostudio-ai/orchestrator-core": { main: "dist/index.js", types: "dist/index.d.ts" }
+    });
+    const config = withAvocado({}, { cwd: root, env: NO_ENV });
+    assert.ok(config.serverExternalPackages.includes("@avocadostudio-ai/orchestrator-core"), "a built orchestrator-core must be external, or Turbopack resolves its optional peers");
+});
+test("a linked orchestrator-core is transpiled instead, never externalised", () => {
+    // Externalising a package whose `main` is `src/index.ts` hands Node a
+    // TypeScript file to require — a build error traded for a runtime crash.
+    const root = fixture({ "@avocadostudio-ai/orchestrator-core": { main: "src/index.ts" } });
+    const config = withAvocado({}, { cwd: root, env: NO_ENV });
+    assert.deepEqual(config.transpilePackages, ["@avocadostudio-ai/orchestrator-core"]);
+    assert.equal(config.serverExternalPackages.includes("@avocadostudio-ai/orchestrator-core"), false, "a linked checkout must be compiled with the app, not handed to Node raw");
+});
+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);
+});
+/*
+ * `trailingSlash: true` is the setting that made the editor unreachable. Next
+ * applies its 308 to `/api/*` too, and a browser will not follow a redirect on
+ * a CORS preflight, so every editor API call failed before it was sent — with
+ * no error naming the config line responsible.
+ */
+test("a trailing-slash site stops redirecting, or the editor cannot reach it", () => {
+    const root = fixture({});
+    const config = withAvocado({ trailingSlash: true }, { cwd: root, silent: true });
+    assert.equal(config.skipTrailingSlashRedirect, true);
+    assert.equal(config.trailingSlash, true, "the app's own setting is not touched — only the redirect is");
+});
+test("a site without trailing slashes is left exactly as it was", () => {
+    const root = fixture({});
+    const config = withAvocado({}, { cwd: root, silent: true });
+    assert.equal(config.skipTrailingSlashRedirect, undefined, "the vast majority of sites never hit this, and must not inherit the workaround");
+});
+test("an app that already decided about the redirect keeps its decision", () => {
+    const root = fixture({});
+    const kept = withAvocado({ trailingSlash: true, skipTrailingSlashRedirect: false }, { cwd: root, silent: true });
+    assert.equal(kept.skipTrailingSlashRedirect, false, "a site that stated this has thought about it harder than a helper can");
+});
+test("trailingSlash: false leaves the whole thing to the app", () => {
+    const root = fixture({});
+    const config = withAvocado({ trailingSlash: true }, { cwd: root, silent: true, trailingSlash: false });
+    assert.equal(config.skipTrailingSlashRedirect, undefined);
+});

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);
+});