@avocadostudio-ai/site-sdk 0.5.1 → 0.6.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/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/markers.d.ts

@@ -76,3 +76,35 @@ export declare function editableProps(path: string, options?: {
     readonly "data-editable-target": string;
     readonly "data-editable-target-label": string;
 };
+/**
+ * Mark an element as the scope its marked descendants sit inside.
+ *
+ * The field path is scoped from the block down — `items[3].question` — which
+ * a renderer can only write if it knows where it sits. That holds while one
+ * component draws the whole block, and stops holding the moment a list row is
+ * drawn by a component of its own: the child knows it has a `question` and
+ * cannot know it is `items[3]`. Without this, every component that can appear
+ * inside a list takes a prefix prop from its parent, and every parent passes
+ * one.
+ *
+ * Forgetting to is silent and *wrong*, not silent and absent. The child marks
+ * a bare `question`, the overlay resolves it against the enclosing block, and
+ * an edit to a headline inside a column patches a prop the section does not
+ * have.
+ *
+ * ```tsx
+ * {props.items.map((item, i) => (
+ *   <div key={item.id} {...editableScopeProps(`items[${i}]`)}>
+ *     <FaqRow item={item} />   // marks a bare "question"; needs no prefix
+ *   </div>
+ * ))}
+ * ```
+ *
+ * Scopes nest, and compose outermost first — a `left[1]` scope inside a
+ * `sections[0]` scope makes a child's `text` into `sections[0].left[1].text`.
+ * A block boundary ends the composition, so a scope outside a block never
+ * reaches into it.
+ */
+export declare function editableScopeProps(scope: string): {
+    readonly "data-editable-scope": string;
+};

package/dist/markers.js

@@ -85,3 +85,35 @@ export function editableProps(path, options) {
         ...(options?.kind ? { "data-editable-kind": options.kind } : {})
     };
 }
+/**
+ * Mark an element as the scope its marked descendants sit inside.
+ *
+ * The field path is scoped from the block down — `items[3].question` — which
+ * a renderer can only write if it knows where it sits. That holds while one
+ * component draws the whole block, and stops holding the moment a list row is
+ * drawn by a component of its own: the child knows it has a `question` and
+ * cannot know it is `items[3]`. Without this, every component that can appear
+ * inside a list takes a prefix prop from its parent, and every parent passes
+ * one.
+ *
+ * Forgetting to is silent and *wrong*, not silent and absent. The child marks
+ * a bare `question`, the overlay resolves it against the enclosing block, and
+ * an edit to a headline inside a column patches a prop the section does not
+ * have.
+ *
+ * ```tsx
+ * {props.items.map((item, i) => (
+ *   <div key={item.id} {...editableScopeProps(`items[${i}]`)}>
+ *     <FaqRow item={item} />   // marks a bare "question"; needs no prefix
+ *   </div>
+ * ))}
+ * ```
+ *
+ * Scopes nest, and compose outermost first — a `left[1]` scope inside a
+ * `sections[0]` scope makes a child's `text` into `sections[0].left[1].text`.
+ * A block boundary ends the composition, so a scope outside a block never
+ * reaches into it.
+ */
+export function editableScopeProps(scope) {
+    return { "data-editable-scope": scope };
+}

package/dist/middleware.d.ts

@@ -1,4 +1,5 @@
 import { type EditorProxyOptions } from "./proxy.ts";
+export { trailingSlashRedirect, editorPreviewRewrite } from "./proxy.ts";
 /**
  * Options for the editor middleware factory.
  *

package/dist/middleware.js

@@ -1,4 +1,10 @@
 import { createEditorProxy } from "./proxy.js";
+/*
+ * A Next 15 site reaches for this entry point, and a Next 15 site that already
+ * has a `middleware.ts` needs the two halves rather than the whole factory.
+ * Re-exported here so composing does not mean importing from two subpaths.
+ */
+export { trailingSlashRedirect, editorPreviewRewrite } from "./proxy.js";
 /**
  * Create a Next.js middleware function that rewrites editor/draft requests
  * to a dynamic preview route, keeping the main page route fully static.

package/dist/proxy.d.ts

@@ -93,3 +93,29 @@ export declare function createEditorProxy(options?: EditorProxyOptions): {
         matcher: string[];
     };
 };
+/**
+ * Re-issue the trailing-slash redirect that `skipTrailingSlashRedirect` turned
+ * off, or `null` when the URL is already canonical.
+ *
+ * Exported because a site that already has a `middleware.ts` cannot use
+ * `createEditorProxy` as its whole middleware and has to compose — and the one
+ * line worth not writing twice is the first one below.
+ *
+ * ```ts
+ * export function middleware(request: NextRequest) {
+ *   const canonical = trailingSlashRedirect(request)
+ *   if (canonical) return canonical
+ *   return editorPreviewRewrite(request) ?? myOwnMiddleware(request)
+ * }
+ * ```
+ */
+export declare function trailingSlashRedirect(request: NextRequest): NextResponse | null;
+/**
+ * Rewrite an editor request to the dynamic preview route, or `null` when the
+ * request is not one — which is the caller's cue to run its own middleware
+ * rather than a decision to pass the request through.
+ *
+ * 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;

package/dist/proxy.js

@@ -33,8 +33,6 @@ export { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
  */
 export function createEditorProxy(options) {
     const previewRoute = options?.previewRoute ?? DEFAULT_PREVIEW_ROUTE;
-    const editorParam = options?.editorParam ?? "__editor";
-    const draftCookie = options?.draftCookie === undefined ? "__prerender_bypass" : options.draftCookie;
     const trailingSlash = options?.trailingSlash ?? false;
     function proxy(request) {
         /*
@@ -45,32 +43,80 @@ export function createEditorProxy(options) {
          * publishes only at `/about/`.
          */
         if (trailingSlash) {
-            /*
-             * Built from `request.url`, not from `request.nextUrl.clone()`. NextURL
-             * normalises a trailing slash back *off* when it stringifies, so a
-             * redirect built from a clone points at the URL it is trying to leave —
-             * a redirect loop, and one that only a browser would ever have shown us.
-             * A plain URL does no normalising. It also keeps `basePath`, which
-             * `nextUrl.pathname` has already stripped.
-             */
-            const url = new URL(request.url);
-            if (url.pathname.length > 1 && !url.pathname.endsWith("/")) {
-                url.pathname = `${url.pathname}/`;
-                // 308, not 307: the method is preserved *and* the redirect is
-                // permanent, which is what Next's own trailing-slash redirect sends
-                // and what the site's existing search rankings were built on.
-                return NextResponse.redirect(url, 308);
-            }
-        }
-        const isEditor = request.nextUrl.searchParams.get(editorParam) === "1";
-        const hasDraftCookie = draftCookie !== false && request.cookies.has(draftCookie);
-        if (isEditor || hasDraftCookie) {
-            const url = request.nextUrl.clone();
-            url.pathname = `${previewRoute}${url.pathname}`;
-            return NextResponse.rewrite(url);
+            const redirect = trailingSlashRedirect(request);
+            if (redirect)
+                return redirect;
         }
-        return NextResponse.next();
+        return editorPreviewRewrite(request, options) ?? NextResponse.next();
     }
     const config = { matcher: [buildEditorMatcher(previewRoute)] };
     return { proxy, config };
 }
+/**
+ * Re-issue the trailing-slash redirect that `skipTrailingSlashRedirect` turned
+ * off, or `null` when the URL is already canonical.
+ *
+ * Exported because a site that already has a `middleware.ts` cannot use
+ * `createEditorProxy` as its whole middleware and has to compose — and the one
+ * line worth not writing twice is the first one below.
+ *
+ * ```ts
+ * export function middleware(request: NextRequest) {
+ *   const canonical = trailingSlashRedirect(request)
+ *   if (canonical) return canonical
+ *   return editorPreviewRewrite(request) ?? myOwnMiddleware(request)
+ * }
+ * ```
+ */
+export function trailingSlashRedirect(request) {
+    /*
+     * Built from `request.url`, not from `request.nextUrl.clone()`. NextURL
+     * normalises a trailing slash back *off* when it stringifies, so a redirect
+     * built from a clone points at the URL it is trying to leave — every page on
+     * the site enters an infinite redirect, and only in a browser: `curl`
+     * without `-L` sees one perfectly ordinary 308. A plain URL does no
+     * normalising. It also keeps `basePath`, which `nextUrl.pathname` has
+     * already stripped.
+     */
+    const url = new URL(request.url);
+    const { pathname } = url;
+    if (pathname.length <= 1 || pathname.endsWith("/"))
+        return null;
+    /*
+     * The set that must never gain a trailing slash. `createEditorProxy`'s own
+     * matcher already excludes all of it, so these are no-ops there — they are
+     * for the hand-composed case, where the site's matcher is its own and is
+     * usually wider. Redirecting `/api/editor/blocks` to `/api/editor/blocks/`
+     * here would re-create, by hand, the exact 308 that
+     * `skipTrailingSlashRedirect` was turned on to stop.
+     */
+    if (pathname.startsWith("/api/") || pathname.startsWith("/_next/"))
+        return null;
+    if (pathname.slice(pathname.lastIndexOf("/") + 1).includes("."))
+        return null;
+    url.pathname = `${pathname}/`;
+    // 308, not 307: the method is preserved *and* the redirect is permanent,
+    // which is what Next's own trailing-slash redirect sends and what the site's
+    // existing search rankings were built on.
+    return NextResponse.redirect(url, 308);
+}
+/**
+ * Rewrite an editor request to the dynamic preview route, or `null` when the
+ * request is not one — which is the caller's cue to run its own middleware
+ * rather than a decision to pass the request through.
+ *
+ * The half of `createEditorProxy` a site with its own middleware needs; see
+ * {@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)
+        return null;
+    const url = request.nextUrl.clone();
+    url.pathname = `${previewRoute}${url.pathname}`;
+    return NextResponse.rewrite(url);
+}

package/dist/proxy.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { NextRequest } from "next/server";
-import { buildEditorMatcher, createEditorProxy, DEFAULT_PREVIEW_ROUTE } from "./proxy.js";
+import { NextRequest, NextResponse } from "next/server";
+import { buildEditorMatcher, createEditorProxy, editorPreviewRewrite, trailingSlashRedirect, DEFAULT_PREVIEW_ROUTE } from "./proxy.js";
 import { createEditorMiddleware } from "./middleware.js";
 /*
  * The rewrite that keeps the published route static and sends editor traffic to
@@ -121,3 +121,62 @@ test("draftCookie: false leaves Next's draft cookie to whoever else is using it"
     assert.equal(rewriteOf(proxy(request("https://site.test/about", "__prerender_bypass=abc"))), null, "a Sanity or Contentful preview must not be hijacked into Avocado's route");
     assert.equal(rewriteOf(proxy(request("https://site.test/about?__editor=1"))), "https://site.test/preview-draft/about?__editor=1", "the explicit editor parameter still works — that is the whole point of the opt-out");
 });
+/*
+ * The two halves, on their own.
+ *
+ * A site that already has a `middleware.ts` cannot hand the whole file to
+ * `createEditorProxy` and has to compose — which until now meant re-deriving
+ * the trailing-slash redirect from the docs. One integration did, and wrote
+ * `request.nextUrl.clone()`, because that is what every Next example uses for
+ * a URL you intend to modify. A `NextURL` re-applies trailing-slash
+ * normalisation when it serialises, so the redirect stripped the slash it had
+ * just added and pointed at the URL it came from: every page on the site in an
+ * infinite redirect, reproducing only in a browser. `curl` without `-L` sees
+ * one perfectly ordinary 308, which is how it survived a session and a half.
+ */
+test("the redirect is built from request.url, not from a NextURL that would undo it", () => {
+    const response = trailingSlashRedirect(request("https://site.test/bern"));
+    assert.equal(response?.status, 308);
+    assert.equal(response?.headers.get("location"), "https://site.test/bern/", "a location without the slash is the loop: the browser asks again and gets the same answer");
+});
+test("an already-canonical URL, the root, and a file are left alone", () => {
+    assert.equal(trailingSlashRedirect(request("https://site.test/bern/")), null);
+    assert.equal(trailingSlashRedirect(request("https://site.test/")), null, "redirecting / never terminates");
+    assert.equal(trailingSlashRedirect(request("https://site.test/logo.svg")), null);
+});
+test("the API routes are never redirected, whatever the caller's matcher says", () => {
+    /*
+     * The proxy's own matcher excludes these, but a hand-composed middleware
+     * brings its own matcher and it is usually wider. A slash added here
+     * re-creates by hand the exact 308 on `/api/editor/*` that
+     * `skipTrailingSlashRedirect` was turned on to stop — and the symptom is a
+     * CORS error that names nothing.
+     */
+    assert.equal(trailingSlashRedirect(request("https://site.test/api/editor/blocks")), null);
+    assert.equal(trailingSlashRedirect(request("https://site.test/_next/static/chunk")), null);
+});
+test("the redirect keeps the query string when called directly too", () => {
+    const response = trailingSlashRedirect(request("https://site.test/bern?__editor=1"));
+    assert.equal(response?.headers.get("location"), "https://site.test/bern/?__editor=1");
+});
+test("editorPreviewRewrite answers null for a visitor, so the caller runs its own middleware", () => {
+    assert.equal(editorPreviewRewrite(request("https://site.test/about")), null, "null is 'not mine', not 'pass this through' — a composing caller has its own work to do");
+    assert.equal(rewriteOf(editorPreviewRewrite(request("https://site.test/about?__editor=1"))), "https://site.test/preview-draft/about?__editor=1");
+});
+test("the composed form behaves like the factory it was extracted from", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    const compose = (r) => trailingSlashRedirect(r) ?? editorPreviewRewrite(r) ?? NextResponse.next();
+    for (const url of [
+        "https://site.test/bern",
+        "https://site.test/bern/",
+        "https://site.test/bern?__editor=1",
+        "https://site.test/bern/?__editor=1",
+        "https://site.test/"
+    ]) {
+        const fromFactory = proxy(request(url));
+        const fromParts = compose(request(url));
+        assert.equal(fromParts.status, fromFactory.status, url);
+        assert.equal(fromParts.headers.get("location"), fromFactory.headers.get("location"), url);
+        assert.equal(rewriteOf(fromParts), rewriteOf(fromFactory), url);
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -122,16 +122,16 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "^0.5.1",
-    "@avocadostudio-ai/preview-adapter": "^0.5.1",
-    "@avocadostudio-ai/shared": "^0.5.1"
+    "@avocadostudio-ai/blocks": "^0.6.0",
+    "@avocadostudio-ai/preview-adapter": "^0.6.0",
+    "@avocadostudio-ai/shared": "^0.6.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.5.1"
+    "@avocadostudio-ai/orchestrator-core": "^0.6.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {