@avocadostudio-ai/site-sdk 0.6.0 → 0.8.0

package/dist/page-metadata.js

@@ -108,3 +108,67 @@ export function buildPageMetadata(page, options = {}) {
         ...(options.canonical ? { alternates: { canonical: options.canonical } } : {}),
     };
 }
+/** `&`, `<`, `>` and `"` inside an attribute value, which a title routinely contains. */
+function escapeAttribute(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * Render {@link PageMetadata} as the head tags it describes.
+ *
+ * Next consumes the object directly — a route exports `metadata` and the
+ * framework emits the tags — so nothing in this repo needed this until now.
+ * Every other host writes its own `<head>`, and an integrator left to do that
+ * by hand reproduces a subset: the title and description usually, Open Graph
+ * sometimes, `twitter:card` almost never, and the canonical link not at all.
+ * That is how `test:build` came to exist — three of those omissions had already
+ * shipped from the one route that built its head by hand.
+ *
+ * Returns a string because the alternative is a shape per templating language.
+ * The values are attribute-escaped; the caller inserts it as raw HTML
+ * (`set:html` in Astro, `v-html` in Vue, `{@html}` in Svelte).
+ *
+ * `og:image` and `twitter:image` are emitted exactly as given. A relative path
+ * is legal in the document but most crawlers will not resolve it, so pass
+ * absolute URLs — the same rule that applies to `buildPageMetadata`'s
+ * `canonical`.
+ */
+export function renderPageMetadata(metadata) {
+    const tags = [];
+    const meta = (attr, key, value) => {
+        if (value)
+            tags.push(`<meta ${attr}="${escapeAttribute(key)}" content="${escapeAttribute(value)}" />`);
+    };
+    if (metadata.title)
+        tags.push(`<title>${escapeAttribute(metadata.title)}</title>`);
+    meta("name", "description", metadata.description);
+    if (metadata.alternates?.canonical) {
+        tags.push(`<link rel="canonical" href="${escapeAttribute(metadata.alternates.canonical)}" />`);
+    }
+    const og = metadata.openGraph;
+    if (og) {
+        meta("property", "og:title", og.title);
+        meta("property", "og:description", og.description);
+        meta("property", "og:type", og.type);
+        meta("property", "og:site_name", og.siteName);
+        meta("property", "og:url", og.url);
+        for (const image of og.images ?? [])
+            meta("property", "og:image", image);
+    }
+    const twitter = metadata.twitter;
+    if (twitter) {
+        meta("name", "twitter:card", twitter.card);
+        meta("name", "twitter:title", twitter.title);
+        meta("name", "twitter:description", twitter.description);
+        for (const image of twitter.images ?? [])
+            meta("name", "twitter:image", image);
+    }
+    if (metadata.robots) {
+        const directives = [metadata.robots.index ? "index" : "noindex", metadata.robots.follow ? "follow" : "nofollow"];
+        meta("name", "robots", directives.join(", "));
+    }
+    return tags.join("\n");
+}

package/dist/proxy.d.ts

@@ -1,37 +1,16 @@
 import { NextResponse, type NextRequest } from "next/server";
+import { type EditorRewriteOptions } from "./editor-rewrite-core.ts";
 export { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.ts";
+export { decideEditorRewrite } from "./editor-rewrite-core.ts";
+export type { EditorRewriteDecision, EditorRewriteOptions } from "./editor-rewrite-core.ts";
 /**
  * Options for the editor proxy factory.
+ *
+ * `previewRoute`, `editorParam` and `draftCookie` are documented on
+ * {@link EditorRewriteOptions}, which every host shares; `trailingSlash` below
+ * is Next's alone.
  */
-export type EditorProxyOptions = {
-    /**
-     * 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, or `false` to ignore cookies
-     * entirely and key the rewrite on {@link EditorProxyOptions.editorParam} alone.
-     *
-     * The cookie is how navigation *inside* the editor iframe stays in draft mode:
-     * a link click carries no `__editor=1`, so without it the second page a user
-     * visits renders published content.
-     *
-     * But the cookie is Next's own, and it is not Avocado's to claim. Any other
-     * feature that calls `draftMode().enable()` sets the same
-     * `__prerender_bypass` — Sanity's Presentation tool and Contentful's live
-     * preview both do — and every one of *their* preview requests then lands on
-     * Avocado's preview route. On a site that already had Draft Mode before it had
-     * Avocado, pass `draftCookie: false` and the two stop fighting over it.
-     *
-     * @default "__prerender_bypass"
-     */
-    draftCookie?: string | false;
+export type EditorProxyOptions = EditorRewriteOptions & {
     /**
      * Set this to `true` on a site whose `next.config` sets `trailingSlash: true`.
      *
@@ -118,4 +97,4 @@ export declare function trailingSlashRedirect(request: NextRequest): NextRespons
  * The half of `createEditorProxy` a site with its own middleware needs; see
  * {@link trailingSlashRedirect} for the composition.
  */
-export declare function editorPreviewRewrite(request: NextRequest, options?: Pick<EditorProxyOptions, "previewRoute" | "editorParam" | "draftCookie">): NextResponse | null;
+export declare function editorPreviewRewrite(request: NextRequest, options?: EditorRewriteOptions): NextResponse | null;

package/dist/proxy.js

@@ -1,6 +1,8 @@
 import { NextResponse } from "next/server";
 import { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
+import { decideEditorRewrite } from "./editor-rewrite-core.js";
 export { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
+export { decideEditorRewrite } from "./editor-rewrite-core.js";
 /**
  * Create a Next.js proxy function that rewrites editor/draft requests
  * to a dynamic preview route, keeping the main page route fully static.
@@ -109,14 +111,22 @@ export function trailingSlashRedirect(request) {
  * {@link trailingSlashRedirect} for the composition.
  */
 export function editorPreviewRewrite(request, options) {
-    const previewRoute = options?.previewRoute ?? DEFAULT_PREVIEW_ROUTE;
-    const editorParam = options?.editorParam ?? "__editor";
-    const draftCookie = options?.draftCookie === undefined ? "__prerender_bypass" : options.draftCookie;
-    const isEditor = request.nextUrl.searchParams.get(editorParam) === "1";
-    const hasDraftCookie = draftCookie !== false && request.cookies.has(draftCookie);
-    if (!isEditor && !hasDraftCookie)
+    /*
+     * `nextUrl`, not `new URL(request.url)`: it has `basePath` stripped, and the
+     * preview prefix has to be prepended to the path Next routes on. The decision
+     * itself is shared with every other host — see `decideEditorRewrite`.
+     */
+    const decision = decideEditorRewrite({
+        pathname: request.nextUrl.pathname,
+        searchParams: request.nextUrl.searchParams,
+        hasCookie: (name) => request.cookies.has(name),
+    }, options);
+    if (decision.kind === "pass")
         return null;
     const url = request.nextUrl.clone();
-    url.pathname = `${previewRoute}${url.pathname}`;
-    return NextResponse.rewrite(url);
+    url.pathname = decision.pathname;
+    const headers = new Headers(request.headers);
+    for (const [name, value] of Object.entries(decision.headers))
+        headers.set(name, value);
+    return NextResponse.rewrite(url, { request: { headers } });
 }

package/dist/resolve-page-render.d.ts

@@ -0,0 +1,94 @@
+import type { PageDoc, SiteConfig } from "@avocadostudio-ai/shared";
+import type { SearchParamsRecord } from "./types.ts";
+import { type DraftModeAdapter } from "./draft-context-core.ts";
+import { type NavItem } from "./navigation.ts";
+import type { SiteHeaderBlock } from "./navigation.ts";
+export type PageSourceConfig = {
+    siteId: string;
+    /** Orchestrator draft session. @default "dev" */
+    session?: string;
+    getPage: (slug: string) => Promise<PageDoc | null> | PageDoc | null;
+    getSlugs: () => Promise<string[]> | string[];
+    getSiteConfig?: () => Promise<SiteConfig | undefined> | SiteConfig | undefined;
+    /** @default "/logo.svg" */
+    defaultLogo?: string;
+};
+/** The editor session this render belongs to, when it is one. */
+export type EditorRenderContext = {
+    session: string;
+    siteId: string;
+    /** `postMessage` target and the frame permitted to drive inline edits. Empty when none is trusted. */
+    editorOrigin: string;
+    /**
+     * `?session=…&siteId=…&editorOrigin=…`, to append to every link the preview
+     * renders. Without it the first in-preview navigation lands on the published
+     * page — the editor's own nav goes dead one click in.
+     */
+    editorQuery: string;
+};
+/** Site chrome, already resolved against the right slug list. */
+export type PageChrome = {
+    navItems: NavItem[];
+    siteName: string;
+    siteLogo: string;
+    homeHref: string;
+    /** The header as a block, for a host that renders Avocado's own chrome. */
+    header: SiteHeaderBlock;
+    siteConfig: SiteConfig;
+};
+export type PageRenderOutcome = 
+/** Render this page. `editor` is null for a published render. */
+{
+    kind: "page";
+    slug: string;
+    page: PageDoc;
+    editor: EditorRenderContext | null;
+    chrome: PageChrome;
+}
+/**
+ * No such page. The host must answer with a real 404 status — a rendered
+ * "404" body under HTTP 200 is a soft 404, which crawlers index as a page.
+ */
+ | {
+    kind: "not-found";
+    slug: string;
+}
+/**
+ * An editor render whose draft could not be fetched and which has no
+ * published fallback. Distinct from `not-found` because the page may well
+ * exist: the orchestrator is unreachable, and telling an editor "404" sends
+ * them looking for a content bug that is not there.
+ */
+ | {
+    kind: "draft-unavailable";
+    slug: string;
+    editor: EditorRenderContext;
+    chrome: PageChrome;
+};
+export type ResolvePageRenderInput = {
+    slug: string;
+    config: PageSourceConfig;
+    /**
+     * - `auto`: draft mode or a resolvable editor context switches to the editor render.
+     * - `static`: published content only. Search params are not read.
+     * - `preview`: always the editor render.
+     * @default "auto"
+     */
+    mode?: "auto" | "static" | "preview";
+    /** Required unless `mode` is `"static"`. */
+    search?: SearchParamsRecord;
+    /**
+     * How this runtime reports draft mode and reads cookies. Omit under
+     * `mode: "static"`; omit under `"preview"` only if the host has no draft-mode
+     * concept, in which case authorization rests on the `secret` query parameter.
+     */
+    adapter?: DraftModeAdapter;
+};
+/**
+ * Resolve what a page render should produce, without producing it.
+ *
+ * The published path reads the CMS. The editor path prefers the orchestrator's
+ * draft and falls back to the CMS for each of page and slug list independently
+ * — a session that has edited one page still needs the other twenty in its nav.
+ */
+export declare function resolvePageRender(input: ResolvePageRenderInput): Promise<PageRenderOutcome>;

package/dist/resolve-page-render.js

@@ -0,0 +1,80 @@
+import { resolveDraftContextCore } from "./draft-context-core.js";
+import { fetchEditorPage, fetchEditorSlugs } from "./draft-fetch.js";
+import { buildNavItems, buildSiteHeaderBlock } from "./navigation.js";
+const NO_DRAFT_MODE = { isDraftMode: false, getCookie: () => undefined };
+async function buildChrome(slug, navSlugs, siteConfig, config, editorQuery) {
+    const { navItems, siteName, siteLogo, homeHref } = buildNavItems({
+        navSlugs,
+        currentSlug: slug,
+        siteConfig,
+        siteId: config.siteId,
+        editorQuery,
+        defaultLogo: config.defaultLogo ?? "/logo.svg",
+    });
+    return {
+        navItems,
+        siteName,
+        siteLogo,
+        homeHref,
+        header: buildSiteHeaderBlock({ navItems, siteName, siteLogo, activePath: slug }),
+        siteConfig,
+    };
+}
+/**
+ * Resolve what a page render should produce, without producing it.
+ *
+ * The published path reads the CMS. The editor path prefers the orchestrator's
+ * draft and falls back to the CMS for each of page and slug list independently
+ * — a session that has edited one page still needs the other twenty in its nav.
+ */
+export async function resolvePageRender(input) {
+    const { slug, config } = input;
+    const mode = input.mode ?? "auto";
+    const defaultSession = config.session ?? "dev";
+    const getSiteConfig = () => config.getSiteConfig ? Promise.resolve(config.getSiteConfig()) : Promise.resolve({});
+    const editorCtx = mode === "static"
+        ? null
+        : await resolveDraftContextCore(input.search ?? {}, input.adapter ?? NO_DRAFT_MODE, {
+            defaultSession,
+            defaultSiteId: config.siteId,
+        });
+    const isEditorRender = mode === "preview" || (mode === "auto" && (input.adapter?.isDraftMode === true || Boolean(editorCtx)));
+    if (!isEditorRender) {
+        const [page, navSlugs, siteConfig] = await Promise.all([
+            config.getPage(slug),
+            config.getSlugs(),
+            getSiteConfig(),
+        ]);
+        // Before the chrome is built: none of it survives a 404.
+        if (!page)
+            return { kind: "not-found", slug };
+        return {
+            kind: "page",
+            slug,
+            page,
+            editor: null,
+            chrome: await buildChrome(slug, navSlugs, siteConfig ?? {}, config, ""),
+        };
+    }
+    const session = editorCtx?.session ?? defaultSession;
+    const currentSiteId = editorCtx?.siteId ?? config.siteId;
+    const editorOrigin = editorCtx?.editorOrigin ?? "";
+    const [page, navSlugs, siteConfig] = await Promise.all([
+        fetchEditorPage(slug, session, currentSiteId).then((p) => p ?? config.getPage(slug)),
+        fetchEditorSlugs(session, currentSiteId).then((s) => (s.length > 0 ? s : config.getSlugs())),
+        getSiteConfig(),
+    ]);
+    const params = new URLSearchParams({ session, siteId: currentSiteId });
+    if (editorOrigin)
+        params.set("editorOrigin", editorOrigin);
+    const editor = {
+        session,
+        siteId: currentSiteId,
+        editorOrigin,
+        editorQuery: `?${params.toString()}`,
+    };
+    const chrome = await buildChrome(slug, navSlugs, siteConfig ?? {}, config, editor.editorQuery);
+    if (!page)
+        return { kind: "draft-unavailable", slug, editor, chrome };
+    return { kind: "page", slug, page, editor, chrome };
+}

package/dist/routes-core.d.ts

@@ -0,0 +1,12 @@
+export { createDraftEnableHandlerCore, createDraftDisableHandlerCore } from "./draft-routes-core.ts";
+export type { DraftRouteAdapter } from "./draft-routes-core.ts";
+export { createEditorApiHandlerCore } from "./editor-api-handler-core.ts";
+export type { EditorApiHandlerConfig, EditorApiCoreConfig } from "./editor-api-handler-core.ts";
+export { createBlocksHandler, createPagesHandler, createPublishHandler } from "./editor-routes.ts";
+export type { OnPublishFn, InlineAsset, PublishContext } from "./editor-routes.ts";
+export { isSafeImageUrl, createImageResolver } from "./publish-utils.ts";
+export type { ImageUploader } from "./publish-utils.ts";
+export { createRevalidateHandler } from "./revalidate-handler.ts";
+export type { RevalidateHandlerConfig } from "./revalidate-handler.ts";
+export { getManifestImageFields } from "./manifest-utils.ts";
+export { DRAFT_SESSION_COOKIE, DRAFT_SITE_COOKIE, EDITOR_ORIGIN_COOKIE, normalizeOrigin, single, } from "./draft-common.ts";

package/dist/routes-core.js

@@ -0,0 +1,24 @@
+/*
+ * The editor API, for a host that is not Next.
+ *
+ * This is `./routes` with the two Next-shaped pieces replaced by their cores:
+ * the draft handlers take an adapter instead of calling `draftMode()`, and the
+ * catch-all handler takes the matched path instead of a Next route context.
+ * Everything else in `./routes` was already portable and is re-exported here
+ * unchanged — the same functions, not parallel implementations.
+ */
+// Draft route cores — supply a DraftRouteAdapter for your runtime.
+export { createDraftEnableHandlerCore, createDraftDisableHandlerCore } from "./draft-routes-core.js";
+// Catch-all editor API core.
+export { createEditorApiHandlerCore } from "./editor-api-handler-core.js";
+// Individual editor route handlers — already framework-free.
+export { createBlocksHandler, createPagesHandler, createPublishHandler } from "./editor-routes.js";
+// Publish utilities (SSRF check, image resolution).
+export { isSafeImageUrl, createImageResolver } from "./publish-utils.js";
+// Revalidation handler factory — takes a `revalidate` callback, so the host's
+// cache API never appears here.
+export { createRevalidateHandler } from "./revalidate-handler.js";
+// Manifest utilities (derive image fields from block manifest).
+export { getManifestImageFields } from "./manifest-utils.js";
+// Cookie names and the query-value helper the draft contract is written in.
+export { DRAFT_SESSION_COOKIE, DRAFT_SITE_COOKIE, EDITOR_ORIGIN_COOKIE, normalizeOrigin, single, } from "./draft-common.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,21 @@
       "import": "./dist/markers.js",
       "default": "./dist/markers.js"
     },
+    "./lens": {
+      "types": "./dist/lens/index.d.ts",
+      "import": "./dist/lens/index.js",
+      "default": "./dist/lens/index.js"
+    },
+    "./lens/storyblok": {
+      "types": "./dist/lens/storyblok.d.ts",
+      "import": "./dist/lens/storyblok.js",
+      "default": "./dist/lens/storyblok.js"
+    },
+    "./lens/sanity": {
+      "types": "./dist/lens/sanity.d.ts",
+      "import": "./dist/lens/sanity.js",
+      "default": "./dist/lens/sanity.js"
+    },
     "./blocks": {
       "types": "./dist/blocks.d.ts",
       "import": "./dist/blocks.js",
@@ -52,9 +67,9 @@
       "default": "./dist/draft-context-core.js"
     },
     "./routes/core": {
-      "types": "./dist/draft-routes-core.d.ts",
-      "import": "./dist/draft-routes-core.js",
-      "default": "./dist/draft-routes-core.js"
+      "types": "./dist/routes-core.d.ts",
+      "import": "./dist/routes-core.js",
+      "default": "./dist/routes-core.js"
     },
     "./publish-handlers/json-file": {
       "types": "./dist/publish-handlers/json-file.d.ts",
@@ -76,6 +91,11 @@
       "import": "./dist/proxy.js",
       "default": "./dist/proxy.js"
     },
+    "./proxy/core": {
+      "types": "./dist/editor-rewrite-core.d.ts",
+      "import": "./dist/editor-rewrite-core.js",
+      "default": "./dist/editor-rewrite-core.js"
+    },
     "./matcher": {
       "types": "./dist/editor-matcher.d.ts",
       "import": "./dist/editor-matcher.js",
@@ -91,6 +111,11 @@
       "import": "./dist/create-site-page.js",
       "default": "./dist/create-site-page.js"
     },
+    "./page/core": {
+      "types": "./dist/resolve-page-render.d.ts",
+      "import": "./dist/resolve-page-render.js",
+      "default": "./dist/resolve-page-render.js"
+    },
     "./seo": {
       "types": "./dist/page-metadata.d.ts",
       "import": "./dist/page-metadata.js",
@@ -106,11 +131,6 @@
       "default": "./next-config.mjs"
     }
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/avocadostudio-ai/avocado.git",
-    "directory": "packages/site-sdk"
-  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -122,16 +142,17 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "^0.6.0",
-    "@avocadostudio-ai/preview-adapter": "^0.6.0",
-    "@avocadostudio-ai/shared": "^0.6.0"
+    "@avocadostudio-ai/blocks": "^0.8.0",
+    "@avocadostudio-ai/preview-adapter": "^0.8.0",
+    "@avocadostudio-ai/richtext": "^0.8.0",
+    "@avocadostudio-ai/shared": "^0.8.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "better-sqlite3": ">=12.0.0",
-    "@avocadostudio-ai/orchestrator-core": "^0.6.0"
+    "@avocadostudio-ai/orchestrator-core": "^0.8.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {
@@ -161,7 +182,7 @@
   "license": "Apache-2.0",
   "homepage": "https://docs.avocadostudio.dev",
   "bugs": {
-    "url": "https://github.com/avocadostudio-ai/avocado/issues"
+    "url": "https://docs.avocadostudio.dev"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/dist/cli/register-notice.test.d.ts

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

package/dist/cli/register-notice.test.js

@@ -1,21 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { orchestratorMismatchNotice } from "./register-notice.js";
-/*
- * `avocado-register` ends with "the site should appear in the dashboard", and
- * for a library-mode site that is a promise it cannot keep: the registration
- * went to the site's own handler, and the editor reads one
- * `VITE_ORCHESTRATOR_URL` baked in at build time. The dashboard then opens on
- * a different registry's sites and reports no problem, because there is none —
- * there are simply two registries.
- */
-test("the default target says nothing — that is the path almost everyone is on", () => {
-    assert.equal(orchestratorMismatchNotice("http://localhost:4200"), null);
-    assert.equal(orchestratorMismatchNotice("http://localhost:4200/"), null, "a trailing slash is the same URL");
-});
-test("a library-mode target names the variable the editor needs", () => {
-    const notice = orchestratorMismatchNotice("http://localhost:3002/api/avocado");
-    assert.ok(notice);
-    assert.match(notice, /VITE_ORCHESTRATOR_URL=http:\/\/localhost:3002\/api\/avocado/);
-    assert.match(notice, /sites, or none/, "and names the symptom, which is what the reader is looking at");
-});

package/dist/draft-context-core.test.d.ts

@@ -1,10 +0,0 @@
-/**
- * Who may see unpublished content, and which frame may drive the editor.
- *
- * Both questions used to be answered by the query string. `?__editor=1` alone
- * turned on the draft content store — in production, on the customer's own
- * domain — and `editorOrigin` was accepted from the same URL after a check that
- * only asked whether it parsed as http(s). One GET rendered another session's
- * drafts and pointed the postMessage bridge wherever the caller said.
- */
-export {};