@avocadostudio-ai/site-sdk 0.5.1 → 0.7.0

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

@@ -0,0 +1,20 @@
+/** Where the standalone orchestrator listens, and what the editor assumes. */
+export declare const DEFAULT_ORCHESTRATOR = "http://localhost:4200";
+/**
+ * The warning that makes "the site should appear in the dashboard" honest, or
+ * `null` when it already is.
+ *
+ * Registration went to whichever orchestrator `--orchestrator` named. The
+ * editor reads exactly one, `VITE_ORCHESTRATOR_URL`, baked in at build time,
+ * and it defaults to :4200. A library-mode site registers with its own handler
+ * at, say, `:3002/api/avocado`, whose registry holds a completely different
+ * set of sites — so "the site should appear in the dashboard" is followed by a
+ * dashboard listing somebody else's sites, with nothing reporting a problem.
+ *
+ * Nothing *is* wrong. There are two registries and this command cannot know
+ * which one the editor was built against. It can say which one it just wrote
+ * to, and it says so only when the two visibly disagree: printing an
+ * environment variable after every default-target registration would be noise
+ * on the path almost everyone is on.
+ */
+export declare function orchestratorMismatchNotice(orchestrator: string): string | null;

package/dist/cli/register-notice.js

@@ -0,0 +1,34 @@
+/*
+ * Lives apart from `register.ts` because `register.ts` calls `main()` at module
+ * scope — importing it to reach one helper *registers a site*, which is a poor
+ * thing for a test to do and a worse thing for it to do by accident.
+ */
+/** Where the standalone orchestrator listens, and what the editor assumes. */
+export const DEFAULT_ORCHESTRATOR = "http://localhost:4200";
+/**
+ * The warning that makes "the site should appear in the dashboard" honest, or
+ * `null` when it already is.
+ *
+ * Registration went to whichever orchestrator `--orchestrator` named. The
+ * editor reads exactly one, `VITE_ORCHESTRATOR_URL`, baked in at build time,
+ * and it defaults to :4200. A library-mode site registers with its own handler
+ * at, say, `:3002/api/avocado`, whose registry holds a completely different
+ * set of sites — so "the site should appear in the dashboard" is followed by a
+ * dashboard listing somebody else's sites, with nothing reporting a problem.
+ *
+ * Nothing *is* wrong. There are two registries and this command cannot know
+ * which one the editor was built against. It can say which one it just wrote
+ * to, and it says so only when the two visibly disagree: printing an
+ * environment variable after every default-target registration would be noise
+ * on the path almost everyone is on.
+ */
+export function orchestratorMismatchNotice(orchestrator) {
+    if (orchestrator.replace(/\/+$/, "") === DEFAULT_ORCHESTRATOR)
+        return null;
+    return (`\nThis is not the default orchestrator (${DEFAULT_ORCHESTRATOR}), and the editor\n` +
+        `reads one URL baked in at build time. For the site to show up there, the\n` +
+        `editor has to be built against this one:\n\n` +
+        `  VITE_ORCHESTRATOR_URL=${orchestrator}\n\n` +
+        `Set it in the editor's .env and restart it. A dashboard listing other\n` +
+        `sites, or none, is the symptom of it pointing somewhere else.\n`);
+}

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

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

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

@@ -0,0 +1,21 @@
+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/cli/register.js

@@ -33,6 +33,7 @@
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { DEFAULT_ORCHESTRATOR, orchestratorMismatchNotice } from "./register-notice.js";
 function parseArgs(argv) {
     const out = {};
     for (let i = 0; i < argv.length; i++) {
@@ -224,7 +225,7 @@ async function main() {
     // Resolve port
     const port = args.port ?? detectPortFromPackageJson(pkg) ?? 3000;
     // Resolve orchestrator URL
-    const orchestrator = (args.orchestrator ?? process.env.ORCHESTRATOR_URL ?? "http://localhost:4200").replace(/\/+$/, "");
+    const orchestrator = (args.orchestrator ?? process.env.ORCHESTRATOR_URL ?? DEFAULT_ORCHESTRATOR).replace(/\/+$/, "");
     /*
      * A credentialed orchestrator refuses `/sites/register` like any other route,
      * and this CLI had no way to present a token — so the documented path for
@@ -323,7 +324,11 @@ async function main() {
     process.stdout.write(`\nNext steps:\n`);
     process.stdout.write(`  1. Start your site:    pnpm dev   (in this directory)\n`);
     process.stdout.write(`  2. Open the editor:    http://localhost:4100\n`);
-    process.stdout.write(`  3. The site should appear in the dashboard. If not, refresh the page.\n\n`);
+    process.stdout.write(`  3. The site should appear in the dashboard. If not, refresh the page.\n`);
+    const mismatch = orchestratorMismatchNotice(orchestrator);
+    if (mismatch)
+        process.stdout.write(mismatch);
+    process.stdout.write(`\n`);
 }
 function humanize(s) {
     return s

package/dist/draft.d.ts

@@ -1,3 +1,4 @@
 export { resolveEditorContext, single } from "./draft-context.ts";
+export { isEditorRender, isEditorRenderFrom, EDITOR_RENDER_HEADER } from "./editor-render.ts";
 export { getOrchestratorUrl, fetchEditorPage, fetchEditorSlugs, fetchEditorSiteConfig } from "./draft-fetch.ts";
 export { DRAFT_SESSION_COOKIE, DRAFT_SITE_COOKIE, EDITOR_ORIGIN_COOKIE } from "./draft-common.ts";

package/dist/draft.js

@@ -1,5 +1,8 @@
 // Editor context resolution
 export { resolveEditorContext, single } from "./draft-context.js";
+// Whether this render is the editor's preview — answerable from a layout,
+// where `resolveEditorContext` cannot reach because layouts get no searchParams.
+export { isEditorRender, isEditorRenderFrom, EDITOR_RENDER_HEADER } from "./editor-render.js";
 // Editor content fetching
 export { getOrchestratorUrl, fetchEditorPage, fetchEditorSlugs, fetchEditorSiteConfig } from "./draft-fetch.js";
 // Draft cookie constants

package/dist/editor-render.d.ts

@@ -0,0 +1,43 @@
+declare const EDITOR_RENDER_HEADER = "x-avocado-editor-render";
+export { EDITOR_RENDER_HEADER };
+/**
+ * The pure half, so the decision is testable without a Next request.
+ *
+ * `getHeader` is whatever `headers()` gives you; `isDraftMode` is
+ * `draftMode().isEnabled`.
+ */
+export declare function isEditorRenderFrom(getHeader: (name: string) => string | null | undefined, isDraftMode: boolean): boolean;
+/**
+ * `true` when this render is being drawn inside the Avocado editor.
+ *
+ * Call it in the root layout and gate everything a preview should not carry:
+ *
+ * ```tsx
+ * export default async function RootLayout({ children }) {
+ *   const inEditor = await isEditorRender()
+ *   return (
+ *     <html lang="de">
+ *       <body>
+ *         {children}
+ *         {!inEditor && <CookieConsent />}
+ *         {!inEditor && <Analytics />}
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * **It answers a rendering question, not an authorization one.** What may see
+ * unpublished content is decided by `resolveEditorContext`, which requires draft
+ * mode or a valid secret; this only decides whether to mount third-party
+ * scripts. The header can be sent by anyone, and the worst a forged one does is
+ * opt that visitor out of the site's own analytics and consent banner — which
+ * is self-consistent, because the tracking those scripts set up does not happen
+ * either. Never gate content or credentials on it.
+ *
+ * Reading `headers()` opts the calling segment into dynamic rendering. That is
+ * already true of any layout that reads cookies for a session, and it is the
+ * price of a layout knowing anything about the request at all — but it is worth
+ * knowing before adding the call to a fully static layout.
+ */
+export declare function isEditorRender(): Promise<boolean>;

package/dist/editor-render.js

@@ -0,0 +1,71 @@
+/*
+ * Whether this render is the editor's preview, answerable from a layout.
+ *
+ * `resolveEditorContext()` already tells a *page* it is being previewed, and
+ * that is the wrong half of the tree for the thing sites keep getting wrong.
+ * Consent banners, analytics, tag managers and other visual editors' bridges
+ * are mounted in the root layout, and a Next layout receives no `searchParams`
+ * — so the natural implementation renders the real layout and brings all of
+ * them into the iframe.
+ *
+ * Measured on one integration, per preview render: three uncaught cross-origin
+ * errors from the consent platform reaching for `parent.location`, a cookie
+ * banner covering the page being edited, and a `page_view` written into the
+ * site's own analytics for every block an editor clicked through — twenty
+ * blocks, twenty pageviews, attributed to whoever was editing. Nobody would
+ * choose that, and nobody was asked.
+ *
+ * The signal is a request header the proxy sets when it rewrites to the preview
+ * route, because that is the one thing available to a layout regardless of
+ * where the site put its own state. Draft mode is checked too, for a site whose
+ * preview reaches the route some other way.
+ */
+const EDITOR_RENDER_HEADER = "x-avocado-editor-render";
+export { EDITOR_RENDER_HEADER };
+/**
+ * The pure half, so the decision is testable without a Next request.
+ *
+ * `getHeader` is whatever `headers()` gives you; `isDraftMode` is
+ * `draftMode().isEnabled`.
+ */
+export function isEditorRenderFrom(getHeader, isDraftMode) {
+    return getHeader(EDITOR_RENDER_HEADER) === "1" || isDraftMode;
+}
+/**
+ * `true` when this render is being drawn inside the Avocado editor.
+ *
+ * Call it in the root layout and gate everything a preview should not carry:
+ *
+ * ```tsx
+ * export default async function RootLayout({ children }) {
+ *   const inEditor = await isEditorRender()
+ *   return (
+ *     <html lang="de">
+ *       <body>
+ *         {children}
+ *         {!inEditor && <CookieConsent />}
+ *         {!inEditor && <Analytics />}
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ *
+ * **It answers a rendering question, not an authorization one.** What may see
+ * unpublished content is decided by `resolveEditorContext`, which requires draft
+ * mode or a valid secret; this only decides whether to mount third-party
+ * scripts. The header can be sent by anyone, and the worst a forged one does is
+ * opt that visitor out of the site's own analytics and consent banner — which
+ * is self-consistent, because the tracking those scripts set up does not happen
+ * either. Never gate content or credentials on it.
+ *
+ * Reading `headers()` opts the calling segment into dynamic rendering. That is
+ * already true of any layout that reads cookies for a session, and it is the
+ * price of a layout knowing anything about the request at all — but it is worth
+ * knowing before adding the call to a fully static layout.
+ */
+export async function isEditorRender() {
+    const { headers, draftMode } = await import("next/headers");
+    const [headerList, draft] = await Promise.all([headers(), draftMode()]);
+    return isEditorRenderFrom((name) => headerList.get(name), draft.isEnabled);
+}

package/dist/editor-render.test.d.ts

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

package/dist/editor-render.test.js

@@ -0,0 +1,44 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { EDITOR_RENDER_HEADER, isEditorRenderFrom } from "./editor-render.js";
+import { editorPreviewRewrite } from "./proxy.js";
+import { NextRequest } from "next/server";
+const noHeaders = () => null;
+test("a layout with neither the header nor draft mode is rendering the public page", () => {
+    assert.equal(isEditorRenderFrom(noHeaders, false), false);
+});
+test("the header the proxy stamps is what a layout reads", () => {
+    const get = (name) => (name === EDITOR_RENDER_HEADER ? "1" : null);
+    assert.equal(isEditorRenderFrom(get, false), true);
+});
+/*
+ * The editor renders the site in a cross-origin iframe, where the draft cookie
+ * is frequently blocked outright — which is why the header exists at all. Draft
+ * mode still counts, for a site whose preview reaches the route some other way.
+ */
+test("draft mode alone is enough, for a preview that arrives without the proxy", () => {
+    assert.equal(isEditorRenderFrom(noHeaders, true), true);
+});
+test("only the exact value counts, so a stray header does not blank the site's analytics", () => {
+    assert.equal(isEditorRenderFrom(() => "true", false), false);
+    assert.equal(isEditorRenderFrom(() => "", false), false);
+});
+/*
+ * The two halves have to agree: a header the proxy does not set is a layout
+ * that never learns, and the failure is silent — the preview simply keeps
+ * loading the consent banner.
+ */
+test("the preview rewrite stamps the header isEditorRender reads", () => {
+    const response = editorPreviewRewrite(new NextRequest("https://site.test/about?__editor=1"));
+    assert.ok(response, "an editor request must be rewritten");
+    assert.equal(response.headers.get(`x-middleware-request-${EDITOR_RENDER_HEADER}`), "1");
+});
+test("a published request is not rewritten and carries no header", () => {
+    assert.equal(editorPreviewRewrite(new NextRequest("https://site.test/about")), null);
+});
+test("a header the client sent is replaced by the proxy's own answer", () => {
+    const response = editorPreviewRewrite(new NextRequest("https://site.test/about?__editor=1", {
+        headers: { [EDITOR_RENDER_HEADER]: "0" }
+    }));
+    assert.equal(response?.headers.get(`x-middleware-request-${EDITOR_RENDER_HEADER}`), "1");
+});

package/dist/editor.d.ts

@@ -1,6 +1,6 @@
 export { EditorOverlay } from "./editor-overlay.tsx";
 export { buildEditorQuerySuffix } from "./editor-query.ts";
-export { getPreviewWrapperProps, editableProps } from "./markers.ts";
+export { getPreviewWrapperProps, editableProps, editableScopeProps } from "./markers.ts";
 export { renderBlocks } from "./render-blocks.tsx";
 export { RenderedBlocks, PreviewBlock } from "./live-preview-blocks.tsx";
 export { LivePreviewProvider, useLivePreviewBlocks } from "@avocadostudio-ai/preview-adapter";

package/dist/editor.js

@@ -11,7 +11,7 @@ export { buildEditorQuerySuffix } from "./editor-query.js";
  * for the two-line attribute helper from here drags the whole editor into the
  * public bundle: +66 kB First Load JS, for identical markup.
  */
-export { getPreviewWrapperProps, editableProps } from "./markers.js";
+export { getPreviewWrapperProps, editableProps, editableScopeProps } from "./markers.js";
 // Block rendering helper
 export { renderBlocks } from "./render-blocks.js";
 // Live-preview store renderer (streams field drafts through React)

package/dist/lens/create-lens.d.ts

@@ -0,0 +1,48 @@
+import type { FieldTable, LocaleLens, Primitives } from "./types.ts";
+export type LensOptions<L extends string = string> = {
+    table: FieldTable;
+    locale: LocaleLens<L>;
+    primitives: Primitives;
+};
+/** Where a write was refused or degraded, and why. */
+export type MergeWarning = {
+    /** `/preise > hero_section > title` — where it happened. */
+    where: string;
+    reason: string;
+};
+export type MergeResult<D> = {
+    doc: D;
+    changed: boolean;
+    warnings: MergeWarning[];
+};
+export type ProjectOptions = {
+    /**
+     * `true` when the document already came out of the CMS with a language
+     * applied, so the bare keys hold the right values and the localised slots
+     * must not be consulted.
+     *
+     * Delivery APIs resolve; management APIs do not. Getting this wrong is
+     * silent in one direction — a resolved document read as raw finds nothing in
+     * the suffixed keys and falls back to the same values it already had.
+     */
+    resolved?: boolean;
+};
+type Doc = Record<string, unknown>;
+declare function humanise(key: string): string;
+export declare function createLens<L extends string = string>(options: LensOptions<L>): {
+    project: (doc: Doc, type: string, lang: L, opts?: ProjectOptions) => Doc;
+    merge: (source: Doc, props: Doc, type: string, lang: L, where?: string, opts?: {
+        checkLang?: L;
+    }) => MergeResult<Doc>;
+    roundTrip: (doc: Doc, type: string, lang: L, opts?: ProjectOptions) => {
+        clean: boolean;
+        fields: string[];
+        warnings: MergeWarning[];
+    };
+    table: FieldTable;
+    locale: LocaleLens<L>;
+    primitives: Primitives;
+    label: typeof humanise;
+};
+export type Lens<L extends string = string> = ReturnType<typeof createLens<L>>;
+export {};