@avocadostudio-ai/astro 0.8.0

package/dist/draft-cookie.js

@@ -0,0 +1,86 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/*
+ * Astro's draft cookie, which Astro does not have.
+ *
+ * On Next, `draftMode().enable()` sets `__prerender_bypass` — a cookie the
+ * framework signs, sets and checks, and which the preview rewrite keys on so
+ * that clicking a link inside the editor iframe stays in the preview. Astro has
+ * no equivalent: there is no draft mode, so there is no cookie, so the second
+ * page a user visits is the published one and the editor's own navigation dies
+ * one click in.
+ *
+ * So the integration names and signs its own. The value is not a secret and
+ * carries nothing private — it is the draft session and site, which already
+ * travel in the URL. What the signature buys is that a visitor cannot mint one:
+ * the cookie is what makes a request eligible for an on-demand draft render, and
+ * an unsigned one would let anybody who guessed a session id read unpublished
+ * content by setting a cookie in their own browser.
+ *
+ * It is deliberately the same secret `/api/editor/draft` already validates
+ * (`DRAFT_MODE_SECRET`). A second secret is a second thing to configure and to
+ * get wrong, and the two grant exactly the same access.
+ */
+export const ASTRO_DRAFT_COOKIE = "avocado_draft";
+/** How long a draft cookie stays valid. An editing session outlives a short one, and a long one outlives the tab. */
+export const DRAFT_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 12;
+function base64url(input) {
+    return Buffer.from(input, "utf8").toString("base64url");
+}
+function sign(payload, secret) {
+    return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+/**
+ * A cookie value for this draft session, or `null` when no secret is configured
+ * — in which case the integration must not set one at all, rather than set an
+ * unsigned one that verification would have to accept.
+ */
+export function mintDraftCookie(payload, secret, now = Date.now()) {
+    if (!secret)
+        return null;
+    const body = {
+        ...payload,
+        exp: Math.floor(now / 1000) + DRAFT_COOKIE_MAX_AGE_SECONDS,
+    };
+    const encoded = base64url(JSON.stringify(body));
+    return `${encoded}.${sign(encoded, secret)}`;
+}
+/**
+ * The session a cookie authorizes, or `null` if it does not.
+ *
+ * Returns null rather than throwing for every failure — malformed, unsigned,
+ * wrongly signed, expired — because every one of them means the same thing to
+ * the caller: this request is not authorized to see drafts.
+ */
+export function verifyDraftCookie(value, secret, now = Date.now()) {
+    if (!value || !secret)
+        return null;
+    const dot = value.lastIndexOf(".");
+    if (dot <= 0)
+        return null;
+    const encoded = value.slice(0, dot);
+    const provided = Buffer.from(value.slice(dot + 1));
+    const expected = Buffer.from(sign(encoded, secret));
+    /*
+     * Compared in constant time, and only after the lengths match:
+     * `timingSafeEqual` throws on a length mismatch rather than returning false,
+     * and a thrown error here would be a 500 on every request carrying a
+     * truncated cookie.
+     */
+    if (provided.length !== expected.length || !timingSafeEqual(provided, expected))
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+        if (typeof payload?.session !== "string" || typeof payload?.siteId !== "string")
+            return null;
+        if (typeof payload.exp !== "number" || payload.exp * 1000 <= now)
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+/** The secret both this cookie and `/api/editor/draft` are checked against. */
+export function draftSecret(env = process.env) {
+    return env.DRAFT_MODE_SECRET?.trim() || env.NEXT_DRAFT_MODE_SECRET?.trim() || undefined;
+}

package/dist/editor-api-route.d.ts

@@ -0,0 +1,2 @@
+export declare const prerender = false;
+export declare const GET: import("astro").APIRoute, POST: import("astro").APIRoute, OPTIONS: import("astro").APIRoute;

package/dist/editor-api-route.js

@@ -0,0 +1,20 @@
+import content from "avocado:content";
+import { createAvocadoEditorApi } from "./editor-api.js";
+/*
+ * The editor API route, injected by the integration rather than written by the
+ * site.
+ *
+ * It has to be on-demand — it answers per request — and on a static build
+ * Astro refuses an on-demand route without an adapter. A site whose whole point
+ * is a static build (AstroWind is one: see its
+ * `.agents/skills/content-at-build-time.md`) therefore cannot keep this route
+ * file in its own `src/pages`, because its mere existence fails
+ * `astro build` with `NoAdapterInstalled`.
+ *
+ * Injecting it means the integration decides when it exists: during `astro
+ * dev`, always, and in a build only when the site has an adapter to serve it.
+ * Editing then happens against the dev server, publishing writes the site's
+ * content files, and the production build never sees this route.
+ */
+export const prerender = false;
+export const { GET, POST, OPTIONS } = createAvocadoEditorApi(content);

package/dist/editor-api.d.ts

@@ -0,0 +1,30 @@
+import type { APIRoute } from "astro";
+import { type EditorApiHandlerConfig } from "@avocadostudio-ai/site-sdk/routes/core";
+export type AvocadoEditorApiConfig = EditorApiHandlerConfig & {
+    /** Where the catch-all is mounted. @default "/api/editor" */
+    basePath?: string;
+    secret?: string;
+};
+/**
+ * The editor API as Astro endpoints.
+ *
+ * Mount at `src/pages/api/editor/[...path].ts`:
+ * ```ts
+ * import { createAvocadoEditorApi } from "@avocadostudio-ai/astro/editor-api"
+ * export const prerender = false
+ * export const { GET, POST, OPTIONS } = createAvocadoEditorApi({ getPages, onPublish })
+ * ```
+ *
+ * `prerender = false` is not optional and not defaultable: these routes answer
+ * per request, and Astro would otherwise build them once and serve the answer
+ * as a file.
+ *
+ * Astro gives `params.path` as a single joined string for a rest parameter,
+ * where Next gives an array. The core takes either — or derives the path from
+ * the URL when neither is available.
+ */
+export declare function createAvocadoEditorApi(config: AvocadoEditorApiConfig): {
+    GET: APIRoute;
+    POST: APIRoute;
+    OPTIONS: APIRoute;
+};

package/dist/editor-api.js

@@ -0,0 +1,36 @@
+import { createEditorApiHandlerCore } from "@avocadostudio-ai/site-sdk/routes/core";
+import { createAstroDraftAdapter } from "./draft-adapter.js";
+/**
+ * The editor API as Astro endpoints.
+ *
+ * Mount at `src/pages/api/editor/[...path].ts`:
+ * ```ts
+ * import { createAvocadoEditorApi } from "@avocadostudio-ai/astro/editor-api"
+ * export const prerender = false
+ * export const { GET, POST, OPTIONS } = createAvocadoEditorApi({ getPages, onPublish })
+ * ```
+ *
+ * `prerender = false` is not optional and not defaultable: these routes answer
+ * per request, and Astro would otherwise build them once and serve the answer
+ * as a file.
+ *
+ * Astro gives `params.path` as a single joined string for a rest parameter,
+ * where Next gives an array. The core takes either — or derives the path from
+ * the URL when neither is available.
+ */
+export function createAvocadoEditorApi(config) {
+    const core = createEditorApiHandlerCore({
+        ...config,
+        basePath: config.basePath ?? "/api/editor",
+        draftAdapter: createAstroDraftAdapter({ secret: config.secret }),
+    });
+    const segments = (params) => {
+        const path = params.path;
+        return typeof path === "string" ? path.split("/").filter(Boolean) : undefined;
+    };
+    return {
+        GET: ({ request, params }) => core.GET(request, segments(params)),
+        POST: ({ request, params }) => core.POST(request, segments(params)),
+        OPTIONS: ({ request }) => core.OPTIONS(request),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import type { AstroIntegration } from "astro";
+export type AvocadoIntegrationOptions = {
+    /** Site identifier the orchestrator keys drafts by. Also readable from `AVOCADO_SITE_ID`. */
+    siteId: string;
+    /**
+     * Editor origins this site will talk to.
+     *
+     * The editor origin becomes a `postMessage` target and names the frame
+     * permitted to drive inline edits, so it cannot be whatever the URL says. A
+     * candidate not on this list degrades to the first entry. In development an
+     * unlisted origin is accepted, because the editor's port moves and refusing it
+     * looks like the integration is broken.
+     */
+    editorOrigins?: string[];
+    /** Orchestrator draft session. @default "dev" */
+    session?: string;
+    /**
+     * Where the editor API is mounted.
+     * @default "/api/editor"
+     */
+    editorApiPath?: string;
+    /**
+     * Path to the module that says where this site's content lives — its default
+     * export is an {@link AvocadoEditorApiConfig}: `getPages`, `onPublish`, and
+     * optionally `registerBlocks` and `blockTypes`.
+     *
+     * Relative to the project root. Given this, the integration injects the
+     * editor API route itself; see below for why the site cannot own that file.
+     */
+    content?: string;
+    /**
+     * The pages the editor may preview, as project-relative component paths —
+     * `["src/pages/index.astro"]`. `*` matches within a path segment, `**` across
+     * segments.
+     *
+     * These render on demand during `astro dev` and are prerendered in a build,
+     * which is the only arrangement that satisfies both halves of the problem.
+     *
+     * A prerendered route has no request: `Astro.request.headers` is empty and
+     * Astro warns, so the middleware sees no `__editor` parameter and no draft
+     * cookie and resolves every request as a visitor's. The preview then renders
+     * the published page, correctly and with no markers — which looks exactly
+     * like an integration nobody wired up.
+     *
+     * The site cannot fix that itself. `export const prerender = false` on the
+     * page makes `astro build` fail with `NoAdapterInstalled`, and
+     * `!import.meta.env.DEV` is not a literal by the time Astro's route analysis
+     * reads it, so the route stays prerendered regardless.
+     *
+     * It is a list rather than "every page" because a route built from
+     * `getStaticPaths` cannot render on demand at all: its `Astro.props` come
+     * from the path it was generated for, so on demand they are `undefined` and
+     * the route throws on the first property it reads. Naming the pages leaves
+     * paginated and collection routes exactly as they were.
+     */
+    editablePages?: string[];
+    /**
+     * Load the live-preview bridge on every page.
+     *
+     * The script is a few hundred bytes and its first action is to check whether
+     * it is inside the editor's iframe — outside one it attaches nothing. Turn it
+     * off only for a site that must ship zero Avocado bytes to visitors, and mount
+     * the bridge from a preview-only layout instead.
+     * @default true
+     */
+    bridge?: boolean;
+};
+/**
+ * Avocado Studio for Astro.
+ *
+ * ```ts
+ * // astro.config.ts
+ * import avocado from "@avocadostudio-ai/astro"
+ * export default defineConfig({
+ *   integrations: [avocado({ siteId: "my-site" })],
+ * })
+ * ```
+ *
+ * **The site stays static.** This integration adds no adapter and changes no
+ * route's rendering mode. Astro decides that per route at build time, and a
+ * prerendered page is a file on disk that no middleware can turn into a
+ * function — so the integration marks requests rather than rewriting them, and
+ * a site that wants on-demand preview in production marks the route it wants
+ * previewable with `export const prerender = false` and installs an adapter of
+ * its own choosing. Under `astro dev` every route already renders on demand, so
+ * a site whose content lives in its own source needs neither.
+ *
+ * What it does add: middleware that resolves the editor session onto
+ * `Astro.locals.avocado`, and the preview bridge.
+ */
+export default function avocado(options: AvocadoIntegrationOptions): AstroIntegration;
+export type { AvocadoLocals } from "./runtime.ts";
+export { resolveEditorRequest } from "./runtime.ts";
+export { ASTRO_DRAFT_COOKIE } from "./draft-cookie.ts";

package/dist/index.js

@@ -0,0 +1,147 @@
+import { ASTRO_DRAFT_COOKIE } from "./draft-cookie.js";
+/**
+ * Avocado Studio for Astro.
+ *
+ * ```ts
+ * // astro.config.ts
+ * import avocado from "@avocadostudio-ai/astro"
+ * export default defineConfig({
+ *   integrations: [avocado({ siteId: "my-site" })],
+ * })
+ * ```
+ *
+ * **The site stays static.** This integration adds no adapter and changes no
+ * route's rendering mode. Astro decides that per route at build time, and a
+ * prerendered page is a file on disk that no middleware can turn into a
+ * function — so the integration marks requests rather than rewriting them, and
+ * a site that wants on-demand preview in production marks the route it wants
+ * previewable with `export const prerender = false` and installs an adapter of
+ * its own choosing. Under `astro dev` every route already renders on demand, so
+ * a site whose content lives in its own source needs neither.
+ *
+ * What it does add: middleware that resolves the editor session onto
+ * `Astro.locals.avocado`, and the preview bridge.
+ */
+export default function avocado(options) {
+    const bridgeEnabled = options.bridge ?? true;
+    /** `src/pages/**` + `/*.astro` as a regex over the project-relative path. */
+    const GLOBSTAR = "__AVOCADO_GLOBSTAR__";
+    const editable = (options.editablePages ?? []).map((pattern) => new RegExp(`^${pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*\//g, GLOBSTAR)
+        .replace(/\*/g, "[^/]*")
+        .replace(GLOBSTAR, "(?:.*/)?")}$`));
+    let isDev = false;
+    return {
+        name: "@avocadostudio-ai/astro",
+        hooks: {
+            "astro:route:setup": ({ route, logger }) => {
+                if (!isDev || editable.length === 0)
+                    return;
+                if (!editable.some((pattern) => pattern.test(route.component)))
+                    return;
+                /*
+                 * Only while developing, and only for a page the site named. In a build
+                 * this hook does nothing at all, so every route is prerendered and the
+                 * output is as static as it was before Avocado was installed.
+                 */
+                route.prerender = false;
+                logger.debug(`${route.component} renders on demand so the editor can preview it`);
+            },
+            "astro:config:setup": ({ addMiddleware, injectRoute, injectScript, updateConfig, config: astroConfig, command, logger }) => {
+                isDev = command === "dev";
+                const virtualModuleId = "avocado:config";
+                const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+                const avocadoConfig = {
+                    siteId: options.siteId,
+                    session: options.session ?? "dev",
+                    editorOrigins: options.editorOrigins ?? [],
+                    editorApiPath: options.editorApiPath ?? "/api/editor",
+                    draftCookie: ASTRO_DRAFT_COOKIE,
+                };
+                const contentModuleId = "avocado:content";
+                const resolvedContentModuleId = `\0${contentModuleId}`;
+                const contentPath = options.content ? new URL(options.content, astroConfig.root).pathname : null;
+                updateConfig({
+                    vite: {
+                        plugins: [
+                            {
+                                name: "vite-plugin-avocado-config",
+                                resolveId(id) {
+                                    if (id === virtualModuleId)
+                                        return resolvedVirtualModuleId;
+                                    if (id === contentModuleId)
+                                        return resolvedContentModuleId;
+                                    return undefined;
+                                },
+                                load(id) {
+                                    if (id === resolvedContentModuleId) {
+                                        if (!contentPath) {
+                                            throw new Error("avocado(): the editor API route was injected without a `content` option. This is a bug in the integration.");
+                                        }
+                                        return `export { default } from ${JSON.stringify(contentPath)}`;
+                                    }
+                                    if (id !== resolvedVirtualModuleId)
+                                        return undefined;
+                                    /*
+                                     * Serialised into the module rather than read from
+                                     * `process.env` at runtime, because the bridge half of it runs
+                                     * in the browser where there is no environment to read. The
+                                     * values here are all public — a site id, an origin allowlist
+                                     * and a route prefix. The draft secret is not among them and
+                                     * must never be: it is read server-side, from the environment,
+                                     * at the point it is checked.
+                                     */
+                                    return `export default ${JSON.stringify(avocadoConfig)}`;
+                                },
+                            },
+                        ],
+                    },
+                });
+                /*
+                 * `order: "pre"` so `Astro.locals.avocado` is populated before the
+                 * site's own middleware runs. A site gating analytics on it — which is
+                 * the main reason to read it in middleware at all — would otherwise see
+                 * `undefined` on every request and mount the trackers into the editor's
+                 * iframe.
+                 */
+                addMiddleware({ entrypoint: "@avocadostudio-ai/astro/middleware-entry", order: "pre" });
+                if (bridgeEnabled) {
+                    /*
+                     * `"page"` rather than `"head-inline"`: the bridge needs the document
+                     * body to exist before it can attach, and a `head-inline` script runs
+                     * against an empty one. It is also a module, so it defers by default.
+                     */
+                    injectScript("page", `import { startAvocadoBridge } from "@avocadostudio-ai/astro/bridge";startAvocadoBridge();`);
+                }
+                /*
+                 * The editor API answers per request, and Astro refuses an on-demand
+                 * route in a static build with no adapter — so on a static site the
+                 * route file cannot live in `src/pages` at all: its existence alone
+                 * fails `astro build` with `NoAdapterInstalled`, whether or not anyone
+                 * intends to serve it.
+                 *
+                 * Injecting it puts that decision here. It exists during `astro dev`,
+                 * where every route is on-demand anyway, and in a build only when the
+                 * site has an adapter to run it. A static site is then edited against
+                 * the dev server and rebuilt from what publishing wrote, and its
+                 * production output contains no Avocado route.
+                 */
+                const canServeOnDemand = command === "dev" || Boolean(astroConfig.adapter);
+                if (options.content && canServeOnDemand) {
+                    injectRoute({
+                        pattern: `${avocadoConfig.editorApiPath}/[...path]`,
+                        entrypoint: "@avocadostudio-ai/astro/editor-api-route",
+                        prerender: false,
+                    });
+                }
+                if (options.content && !canServeOnDemand) {
+                    logger.info("Static build with no adapter: the editor API is not included. Edit against `astro dev`.");
+                }
+                logger.info(`Avocado Studio wired for site "${avocadoConfig.siteId}"${options.content && canServeOnDemand ? `, editor API at ${avocadoConfig.editorApiPath}` : ""}.`);
+            },
+        },
+    };
+}
+export { resolveEditorRequest } from "./runtime.js";
+export { ASTRO_DRAFT_COOKIE } from "./draft-cookie.js";

package/dist/markers.d.ts

@@ -0,0 +1,31 @@
+import type { FieldKind } from "@avocadostudio-ai/shared";
+export { editableProps, editableScopeProps } from "@avocadostudio-ai/site-sdk/markers";
+/**
+ * Mark the element that is one block, so the editor can select it.
+ *
+ * Selection is built entirely on `[data-block-id]`: a click in the preview
+ * resolves through `closest("[data-block-id]")`, and no match reads as "clicked
+ * outside any block", which *clears* the selection. Marking fields without this
+ * gives a preview that frames, renders and scrolls correctly and deselects on
+ * every click — indistinguishable from selection mode being switched off.
+ *
+ * Returns `{}` outside editor mode, so the published page renders precisely the
+ * markup it rendered before.
+ *
+ * ```astro
+ * <div {...blockProps(editable, block.id, block.type)}>
+ * ```
+ */
+export declare function blockProps(editorMode: boolean, blockId: string, blockType: string): {
+    readonly "data-block-id"?: undefined;
+    readonly "data-block-type"?: undefined;
+    class?: undefined;
+    readonly style?: undefined;
+} | {
+    "data-block-id": string;
+    "data-block-type": string;
+    class: string;
+    style: string;
+};
+/** The attribute an image field's wrapper carries. Never put it on the `<img>`. */
+export declare const IMAGE_KIND: FieldKind;

package/dist/markers.js

@@ -0,0 +1,49 @@
+/*
+ * The preview markers, in Astro's spelling.
+ *
+ * `editableProps` and `editableScopeProps` in
+ * `@avocadostudio-ai/site-sdk/markers` return plain data attributes and spread
+ * into an `.astro` element unchanged, so they are re-exported here rather than
+ * rewritten — one implementation, and a site imports all three markers from one
+ * place.
+ *
+ * `getPreviewWrapperProps` is the exception: it returns React's spelling,
+ * `className` and a `style` object. Astro wants `class` and a style string, and
+ * spreading React's version produces an element with a literal `className`
+ * attribute that no stylesheet matches and an object stringified into `style`.
+ * Both are silent — the preview renders, and nothing can be selected.
+ */
+export { editableProps, editableScopeProps } from "@avocadostudio-ai/site-sdk/markers";
+/**
+ * Mark the element that is one block, so the editor can select it.
+ *
+ * Selection is built entirely on `[data-block-id]`: a click in the preview
+ * resolves through `closest("[data-block-id]")`, and no match reads as "clicked
+ * outside any block", which *clears* the selection. Marking fields without this
+ * gives a preview that frames, renders and scrolls correctly and deselects on
+ * every click — indistinguishable from selection mode being switched off.
+ *
+ * Returns `{}` outside editor mode, so the published page renders precisely the
+ * markup it rendered before.
+ *
+ * ```astro
+ * <div {...blockProps(editable, block.id, block.type)}>
+ * ```
+ */
+export function blockProps(editorMode, blockId, blockType) {
+    if (!editorMode)
+        return {};
+    return {
+        "data-block-id": blockId,
+        "data-block-type": blockType,
+        class: "editor-selectable",
+        /*
+         * Named for view transitions so a block keeps its identity across the
+         * `<main>` swap a refresh performs — without it a re-render of the list
+         * cross-fades the whole page instead of the block that changed.
+         */
+        style: `view-transition-name: block-${blockId}`,
+    };
+}
+/** The attribute an image field's wrapper carries. Never put it on the `<img>`. */
+export const IMAGE_KIND = "image";

package/dist/middleware-entry.d.ts

@@ -0,0 +1 @@
+export declare const onRequest: import("astro").MiddlewareHandler;

package/dist/middleware-entry.js

@@ -0,0 +1,12 @@
+import avocadoConfig from "avocado:config";
+import { createAvocadoMiddleware } from "./middleware.js";
+/*
+ * The module `addMiddleware` points at. Astro takes an entrypoint specifier,
+ * not a function, so the options cannot be passed in directly — they arrive
+ * through the virtual module the integration writes.
+ */
+export const onRequest = createAvocadoMiddleware({
+    siteId: avocadoConfig.siteId,
+    session: avocadoConfig.session,
+    editorOrigins: avocadoConfig.editorOrigins,
+});

package/dist/middleware.d.ts

@@ -0,0 +1,22 @@
+import type { MiddlewareHandler } from "astro";
+import { type ResolveEditorRequestOptions } from "./runtime.ts";
+/**
+ * Astro middleware that tells every render whether it is the editor's.
+ *
+ * Deliberately *not* a rewrite. Next needs one because its static and dynamic
+ * renders are different routes, so a preview has to be routed somewhere else
+ * entirely. Astro decides per route, at build time, with `prerender` — a route
+ * is either a file on disk or a function, and no middleware can turn one into
+ * the other. Rewriting a prerendered page to a preview route would mean the
+ * integration owning a catch-all that renders the site's own components, which
+ * it cannot know.
+ *
+ * So the request is marked rather than moved, and the site marks the route it
+ * wants previewable with `export const prerender = false`. Everything else stays
+ * a static file — which is the point of using Astro, and which the editor does
+ * not need to change to do its job.
+ *
+ * In `astro dev` every route is rendered on demand already, so a site whose
+ * content lives in its own source needs nothing further.
+ */
+export declare function createAvocadoMiddleware(options?: ResolveEditorRequestOptions): MiddlewareHandler;

package/dist/middleware.js

@@ -0,0 +1,55 @@
+import { resolveEditorRequest } from "./runtime.js";
+/**
+ * Astro middleware that tells every render whether it is the editor's.
+ *
+ * Deliberately *not* a rewrite. Next needs one because its static and dynamic
+ * renders are different routes, so a preview has to be routed somewhere else
+ * entirely. Astro decides per route, at build time, with `prerender` — a route
+ * is either a file on disk or a function, and no middleware can turn one into
+ * the other. Rewriting a prerendered page to a preview route would mean the
+ * integration owning a catch-all that renders the site's own components, which
+ * it cannot know.
+ *
+ * So the request is marked rather than moved, and the site marks the route it
+ * wants previewable with `export const prerender = false`. Everything else stays
+ * a static file — which is the point of using Astro, and which the editor does
+ * not need to change to do its job.
+ *
+ * In `astro dev` every route is rendered on demand already, so a site whose
+ * content lives in its own source needs nothing further.
+ */
+export function createAvocadoMiddleware(options) {
+    /*
+     * Emit editor markup for every render, including prerendered ones.
+     *
+     * `editableCoverage` compares the block manifest against the markers a
+     * preview actually draws, and it can only be run against editor-mode HTML —
+     * pointed at a published page it finds no blocks and reports zero, which
+     * reads identically to an integration that marks nothing. A site served on
+     * demand can be asked for a preview over HTTP. A static one has no server to
+     * ask, so the only way to produce that HTML is to build it.
+     *
+     * Read from the environment rather than taken as an option so that a CI job
+     * can turn it on for one build without the site's committed config mentioning
+     * it, and so that nothing in a normal build can set it by accident.
+     */
+    const forced = process.env.AVOCADO_FORCE_EDITOR === "1";
+    return async (context, next) => {
+        const locals = forced
+            ? { isEditor: true, session: options?.session ?? "dev", siteId: options?.siteId ?? "", editorOrigin: "", editorQuery: "" }
+            : resolveEditorRequest(context.request, options);
+        context.locals.avocado = locals;
+        const response = await next();
+        if (locals.isEditor) {
+            /*
+             * A preview must never be cached, by the browser or by anything between:
+             * the whole point is that it reflects a draft that changes as somebody
+             * types. It must never be indexed either — a preview URL in a search
+             * index is a bug, and it carries a session id.
+             */
+            response.headers.set("Cache-Control", "no-store, must-revalidate");
+            response.headers.set("X-Robots-Tag", "noindex, nofollow");
+        }
+        return response;
+    };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What a page learns about the request it is rendering.
+ *
+ * Reachable from any `.astro` file as `Astro.locals.avocado`, and from a layout
+ * — which is the half that matters. A layout is where a site mounts its consent
+ * banner, its analytics and its tag manager, and the natural implementation
+ * mounts all three inside the editor iframe. Measured on one integration: a
+ * cookie banner covering the page being edited, and a pageview written to the
+ * site's own analytics for every block someone clicked.
+ */
+export type AvocadoLocals = {
+    /** Whether this render is the editor's preview. */
+    isEditor: boolean;
+    /** The draft session, when this is an editor render. */
+    session?: string;
+    siteId?: string;
+    /** `postMessage` target and the frame permitted to drive inline edits. */
+    editorOrigin?: string;
+    /**
+     * `?session=…&siteId=…&editorOrigin=…` — append to every link the page
+     * renders, or the first in-preview navigation lands on the published page.
+     */
+    editorQuery?: string;
+};
+export type ResolveEditorRequestOptions = {
+    /** Falls back to `AVOCADO_SITE_ID`. */
+    siteId?: string;
+    /** @default "dev" */
+    session?: string;
+    /** Trusted editor origins. A candidate not listed degrades to the first entry. */
+    editorOrigins?: string[];
+    secret?: string;
+};
+/**
+ * Resolve what a request means, for Astro's middleware and for anything else
+ * holding a `Request`.
+ *
+ * Two things can mark a request as the editor's: the `__editor=1` parameter the
+ * editor puts on the iframe URL, and the signed draft cookie that keeps
+ * navigation *inside* the iframe in preview. The parameter alone authorizes
+ * nothing on its own — it is a routing hint with no secret in it — so a request
+ * carrying only the parameter is treated as an editor render but the session it
+ * reports comes from the URL, and the content it may see is decided by
+ * `/api/editor/draft` having minted a cookie or by a valid `secret`. This
+ * mirrors `resolveDraftContextCore`, deliberately.
+ */
+export declare function resolveEditorRequest(request: Request, options?: ResolveEditorRequestOptions): AvocadoLocals;
+export { ASTRO_DRAFT_COOKIE } from "./draft-cookie.ts";