@next-buildr/payload 0.0.0-stage → 2.0.0

package/dist/adapter/index.js

@@ -0,0 +1,5 @@
+// @next-buildr/payload/adapter: createPayloadAdapter, createPayloadCanvasDataSource - the
+// browser-side fetch client. Must never import the `payload` framework itself.
+export { createPayloadCanvasDataSource } from './canvas-data-source.js';
+export { createPayloadAdapter } from './document-adapter.js';
+export { AdapterError } from './http.js';

package/dist/admin/index.d.ts

@@ -0,0 +1,4 @@
+export { LayoutField } from './layout-field.tsx';
+export type { LayoutFieldViewProps } from './layout-field-view.tsx';
+export { editorUrl, editorWindowName, LayoutFieldView } from './layout-field-view.tsx';
+//# sourceMappingURL=index.d.ts.map

package/dist/admin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/admin/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/admin/index.js

@@ -0,0 +1,2 @@
+export { LayoutField } from './layout-field.js';
+export { editorUrl, editorWindowName, LayoutFieldView } from './layout-field-view.js';

package/dist/admin/layout-field-connected.d.ts

@@ -0,0 +1,6 @@
+/** The field wired to Payload form and document state; loaded on demand (see `LayoutField`). */
+export declare function ConnectedLayoutField(props: {
+    readonly path: string;
+    readonly editorRoute?: string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=layout-field-connected.d.ts.map

package/dist/admin/layout-field-connected.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-field-connected.d.ts","sourceRoot":"","sources":["../../src/admin/layout-field-connected.tsx"],"names":[],"mappings":"AAUA,gGAAgG;AAChG,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,+BAWA"}

package/dist/admin/layout-field-connected.js

@@ -0,0 +1,16 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useDocumentInfo, useField } from '@payloadcms/ui';
+import { LayoutFieldView } from './layout-field-view.js';
+const countNodes = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const nodes = value.nodes;
+    return typeof nodes === 'object' && nodes !== null ? Object.keys(nodes).length : undefined;
+};
+/** The field wired to Payload form and document state; loaded on demand (see `LayoutField`). */
+export function ConnectedLayoutField(props) {
+    const { value } = useField({ path: props.path });
+    const info = useDocumentInfo();
+    return (_jsx(LayoutFieldView, { nodeCount: countNodes(value), id: info.id, collection: info.collectionSlug ?? '', editorRoute: props.editorRoute ?? '/buildr/edit' }));
+}

package/dist/admin/layout-field-view.d.ts

@@ -0,0 +1,16 @@
+export interface LayoutFieldViewProps {
+    /** Nodes in the stored document; `undefined` when nothing was built yet. */
+    readonly nodeCount: number | undefined;
+    /** `undefined` for a document that is not saved yet. */
+    readonly id: string | number | undefined;
+    readonly collection: string;
+    readonly editorRoute: string;
+    /** Opens a window; injected so the button can be tested without a browser. */
+    readonly open?: (url: string, name: string) => void;
+}
+/** The window name is per document, so a second click reuses the tab that is already open. */
+export declare const editorWindowName: (collection: string, id: string | number) => string;
+export declare const editorUrl: (editorRoute: string, collection: string, id: string | number) => string;
+/** A summary of the layout and the button that opens the builder (docs/payload.md). */
+export declare function LayoutFieldView(props: LayoutFieldViewProps): import("react").JSX.Element;
+//# sourceMappingURL=layout-field-view.d.ts.map

package/dist/admin/layout-field-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-field-view.d.ts","sourceRoot":"","sources":["../../src/admin/layout-field-view.tsx"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED,8FAA8F;AAC9F,eAAO,MAAM,gBAAgB,eAAgB,MAAM,MAAM,MAAM,GAAG,MAAM,WAC1C,CAAC;AAE/B,eAAO,MAAM,SAAS,gBAAiB,MAAM,cAAc,MAAM,MAAM,MAAM,GAAG,MAAM,WACmB,CAAC;AAE1G,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,+BAwB1D"}

package/dist/admin/layout-field-view.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** The window name is per document, so a second click reuses the tab that is already open. */
+export const editorWindowName = (collection, id) => `buildr-${collection}-${id}`;
+export const editorUrl = (editorRoute, collection, id) => `${editorRoute.replace(/\/$/, '')}/${encodeURIComponent(collection)}/${encodeURIComponent(String(id))}`;
+/** A summary of the layout and the button that opens the builder (docs/payload.md). */
+export function LayoutFieldView(props) {
+    const { id, collection, nodeCount } = props;
+    const open = props.open ?? ((url, name) => void window.open(url, name));
+    const saved = id !== undefined && id !== '';
+    return (_jsxs("div", { className: "field-type buildr-layout-field", children: [_jsx("span", { className: "field-label", children: "Layout" }), _jsx("p", { "data-testid": "buildr-layout-summary", children: nodeCount === undefined ? 'Nothing built yet.' : `${nodeCount} elements.` }), _jsx("button", { type: "button", className: "btn btn--style-primary btn--size-medium", disabled: !saved, title: saved ? undefined : 'Save the document first', onClick: () => {
+                    if (saved)
+                        open(editorUrl(props.editorRoute, collection, id), editorWindowName(collection, id));
+                }, children: "Edit with Visual Builder" })] }));
+}

package/dist/admin/layout-field.d.ts

@@ -0,0 +1,6 @@
+/** The `layout` field of a collection with the plugin installed (referenced from the import map). */
+export declare function LayoutField(props: {
+    readonly path: string;
+    readonly editorRoute?: string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=layout-field.d.ts.map

package/dist/admin/layout-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-field.d.ts","sourceRoot":"","sources":["../../src/admin/layout-field.tsx"],"names":[],"mappings":"AAUA,qGAAqG;AACrG,wBAAgB,WAAW,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,+BAM1F"}

package/dist/admin/layout-field.js

@@ -0,0 +1,13 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { lazy, Suspense } from 'react';
+// Payload UI pulls in stylesheets, which a plain Node import (the Payload CLI, the entry-point
+// smoke test) cannot load; the bundler splits it out and only the admin ever renders it.
+const Connected = lazy(async () => {
+    const mod = await import('./layout-field-connected.js');
+    return { default: mod.ConnectedLayoutField };
+});
+/** The `layout` field of a collection with the plugin installed (referenced from the import map). */
+export function LayoutField(props) {
+    return (_jsx(Suspense, { fallback: null, children: _jsx(Connected, { ...props }) }));
+}

package/dist/admin/layout-field.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=layout-field.test.d.ts.map

package/dist/admin/layout-field.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-field.test.d.ts","sourceRoot":"","sources":["../../src/admin/layout-field.test.tsx"],"names":[],"mappings":""}

package/dist/admin/layout-field.test.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// @vitest-environment jsdom
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { editorUrl, editorWindowName, LayoutFieldView } from './layout-field-view.js';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+describe('LayoutFieldView', () => {
+    let container;
+    let root;
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.append(container);
+        root = createRoot(container);
+    });
+    afterEach(() => {
+        act(() => root.unmount());
+        container.remove();
+    });
+    const mount = (props, open = vi.fn()) => {
+        act(() => root.render(_jsx(LayoutFieldView, { nodeCount: 12, id: "42", collection: "pages", editorRoute: "/buildr/edit", open: open, ...props })));
+        return { open, button: container.querySelector('button') };
+    };
+    it('opens the editor of the document in a named window', () => {
+        const { open, button } = mount({});
+        expect(container.textContent).toContain('12 elements.');
+        act(() => button.click());
+        expect(open).toHaveBeenCalledWith('/buildr/edit/pages/42', 'buildr-pages-42');
+    });
+    it('is inactive for a document that is not saved yet', () => {
+        const { open, button } = mount({ id: undefined, nodeCount: undefined });
+        expect(button.disabled).toBe(true);
+        act(() => button.click());
+        expect(open).not.toHaveBeenCalled();
+        expect(container.textContent).toContain('Nothing built yet.');
+    });
+    it('builds the URL and window name safely', () => {
+        expect(editorUrl('/buildr/edit/', 'a b', 7)).toBe('/buildr/edit/a%20b/7');
+        expect(editorWindowName('pages', 7)).toBe('buildr-pages-7');
+    });
+});

package/dist/contract.d.ts

@@ -0,0 +1,289 @@
+import { z } from 'zod';
+/**
+ * The builder API contract (docs/payload.md#endpoint-contract): the request and response shapes of
+ * `/api/buildr/*`, defined once and shared by the endpoint implementations and the HTTP adapter.
+ * Documents travel as `unknown`; they are validated by `processLayout` on the server and by
+ * `parseDocument` in the adapter, not by these schemas.
+ */
+export declare const diagnosticSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+    path: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ContractDiagnostic = z.infer<typeof diagnosticSchema>;
+export declare const documentRefSchema: z.ZodObject<{
+    collection: z.ZodString;
+    id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+}, z.core.$strip>;
+export declare const sessionResponseSchema: z.ZodObject<{
+    user: z.ZodObject<{
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        email: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    permissions: z.ZodObject<{
+        canEdit: z.ZodBoolean;
+        canPublish: z.ZodBoolean;
+        canUnlockTemplates: z.ZodBoolean;
+    }, z.core.$strip>;
+    limits: z.ZodObject<{
+        maxNodes: z.ZodNumber;
+        maxBytes: z.ZodNumber;
+    }, z.core.$strip>;
+    publishPolicy: z.ZodOptional<z.ZodEnum<{
+        block: "block";
+        warn: "warn";
+    }>>;
+    locales: z.ZodOptional<z.ZodObject<{
+        locales: z.ZodArray<z.ZodString>;
+        default: z.ZodString;
+        fallback: z.ZodBoolean;
+        intl: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SessionResponse = z.infer<typeof sessionResponseSchema>;
+export declare const documentQuerySchema: z.ZodObject<{
+    draft: z.ZodOptional<z.ZodEnum<{
+        0: "0";
+        1: "1";
+    }>>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const documentResponseSchema: z.ZodObject<{
+    ref: z.ZodObject<{
+        collection: z.ZodString;
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    }, z.core.$strip>;
+    title: z.ZodString;
+    slug: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+    }>;
+    updatedAt: z.ZodString;
+    revision: z.ZodNumber;
+    document: z.ZodUnknown;
+    contextRef: z.ZodString;
+    layoutSource: z.ZodEnum<{
+        builtin: "builtin";
+        "default-template": "default-template";
+        document: "document";
+        template: "template";
+    }>;
+    layoutRef: z.ZodNullable<z.ZodString>;
+    previewPath: z.ZodNullable<z.ZodString>;
+    readOnly: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type DocumentResponse = z.infer<typeof documentResponseSchema>;
+/** `GET /api/buildr/documents/:collection/:id/revision`: the revision without the document. */
+export declare const revisionResponseSchema: z.ZodObject<{
+    revision: z.ZodNumber;
+    updatedAt: z.ZodString;
+    updatedBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RevisionResponse = z.infer<typeof revisionResponseSchema>;
+export declare const saveRequestSchema: z.ZodObject<{
+    document: z.ZodUnknown;
+    baseRevision: z.ZodNumber;
+    autosave: z.ZodBoolean;
+}, z.core.$strip>;
+export type SaveRequest = z.infer<typeof saveRequestSchema>;
+export declare const saveResponseSchema: z.ZodObject<{
+    revision: z.ZodNumber;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type SaveResponse = z.infer<typeof saveResponseSchema>;
+/** `PATCH /buildr/documents/:collection/:id`: renames the document; the layout is not touched. */
+export declare const renameRequestSchema: z.ZodObject<{
+    title: z.ZodString;
+}, z.core.$strip>;
+export type RenameRequest = z.infer<typeof renameRequestSchema>;
+export declare const renameResponseSchema: z.ZodObject<{
+    title: z.ZodString;
+}, z.core.$strip>;
+export type RenameResponse = z.infer<typeof renameResponseSchema>;
+export declare const publishRequestSchema: z.ZodObject<{
+    baseRevision: z.ZodNumber;
+}, z.core.$strip>;
+export type PublishRequest = z.infer<typeof publishRequestSchema>;
+export declare const publishResponseSchema: z.ZodObject<{
+    status: z.ZodLiteral<"published">;
+    publishedAt: z.ZodString;
+    revision: z.ZodNumber;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type PublishResponse = z.infer<typeof publishResponseSchema>;
+/** `409`: somebody saved in the meantime. */
+export declare const conflictResponseSchema: z.ZodObject<{
+    currentRevision: z.ZodNumber;
+}, z.core.$strip>;
+export type ConflictResponse = z.infer<typeof conflictResponseSchema>;
+/** `422`: the document is not acceptable; `diagnostics` say why. */
+export declare const invalidResponseSchema: z.ZodObject<{
+    diagnostics: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        severity: z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+        }>;
+        path: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type InvalidResponse = z.infer<typeof invalidResponseSchema>;
+/** Every other refusal (`400`, `401`, `403`, `404`). */
+export declare const errorResponseSchema: z.ZodObject<{
+    error: z.ZodString;
+}, z.core.$strip>;
+export type ErrorResponse = z.infer<typeof errorResponseSchema>;
+/** The base path of the builder API under Payload's `routes.api`. */
+export declare const BUILDR_API_PATH = "/buildr";
+/** `GET /buildr/data-schema/:collection` answers with core's `DataSchema`. */
+export declare const dataSchemaResponseSchema: z.ZodType<import("@next-buildr/core").DataSchema, unknown, z.core.$ZodTypeInternals<import("@next-buildr/core").DataSchema, unknown>>;
+export declare const dataContextQuerySchema: z.ZodObject<{
+    collection: z.ZodString;
+    id: z.ZodString;
+    draft: z.ZodOptional<z.ZodEnum<{
+        0: "0";
+        1: "1";
+    }>>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** The scopes a canvas binds against: `{ site, [context]: doc, route }`. */
+export declare const dataContextResponseSchema: z.ZodObject<{
+    scopes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type DataContextResponse = z.infer<typeof dataContextResponseSchema>;
+export declare const samplesResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SamplesResponse = z.infer<typeof samplesResponseSchema>;
+/** `POST /buildr/data/query`: one resolved query, answered with the access of the editing user. */
+export declare const dataQueryRequestSchema: z.ZodObject<{
+    spec: z.ZodType<import("@next-buildr/core").ResolvedQuerySpec, unknown, z.core.$ZodTypeInternals<import("@next-buildr/core").ResolvedQuerySpec, unknown>>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DataQueryRequest = z.infer<typeof dataQueryRequestSchema>;
+export declare const dataQueryResponseSchema: z.ZodType<import("@next-buildr/core").QueryResult, unknown, z.core.$ZodTypeInternals<import("@next-buildr/core").QueryResult, unknown>>;
+/** `POST /buildr/data/media`: media assets by id; unknown ids are left out. */
+export declare const dataMediaRequestSchema: z.ZodObject<{
+    ids: z.ZodArray<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DataMediaRequest = z.infer<typeof dataMediaRequestSchema>;
+export declare const dataMediaResponseSchema: z.ZodRecord<z.ZodString, z.ZodType<import("@next-buildr/core").MediaAsset, unknown, z.core.$ZodTypeInternals<import("@next-buildr/core").MediaAsset, unknown>>>;
+/** `GET /buildr/media?search&type&page`: the picker's listing. */
+export declare const mediaListQuerySchema: z.ZodObject<{
+    search: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        image: "image";
+        video: "video";
+    }>>;
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const mediaListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodType<import("@next-buildr/core").MediaAsset, unknown, z.core.$ZodTypeInternals<import("@next-buildr/core").MediaAsset, unknown>>>;
+    page: z.ZodNumber;
+    totalPages: z.ZodNumber;
+}, z.core.$strip>;
+export type MediaListResponse = z.infer<typeof mediaListResponseSchema>;
+/** How many documents a page of `GET /buildr/documents` holds. */
+export declare const DOCUMENT_LIST_PAGE_SIZE = 20;
+/** `GET /buildr/documents?collection&search&page`: the builder documents the user may read. */
+export declare const documentListQuerySchema: z.ZodObject<{
+    collection: z.ZodString;
+    search: z.ZodOptional<z.ZodString>;
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type DocumentListQuery = z.infer<typeof documentListQuerySchema>;
+/** One document in a listing (and the answer of a creation): enough to pick it and open it. */
+export declare const documentSummarySchema: z.ZodObject<{
+    ref: z.ZodObject<{
+        collection: z.ZodString;
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    }, z.core.$strip>;
+    title: z.ZodString;
+    slug: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+    }>;
+    updatedAt: z.ZodString;
+    revision: z.ZodNumber;
+    layoutSource: z.ZodEnum<{
+        builtin: "builtin";
+        "default-template": "default-template";
+        document: "document";
+        template: "template";
+    }>;
+    previewPath: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type DocumentSummary = z.infer<typeof documentSummarySchema>;
+export declare const documentListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        ref: z.ZodObject<{
+            collection: z.ZodString;
+            id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        }, z.core.$strip>;
+        title: z.ZodString;
+        slug: z.ZodNullable<z.ZodString>;
+        status: z.ZodEnum<{
+            draft: "draft";
+            published: "published";
+        }>;
+        updatedAt: z.ZodString;
+        revision: z.ZodNumber;
+        layoutSource: z.ZodEnum<{
+            builtin: "builtin";
+            "default-template": "default-template";
+            document: "document";
+            template: "template";
+        }>;
+        previewPath: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    page: z.ZodNumber;
+    totalPages: z.ZodNumber;
+}, z.core.$strip>;
+export type DocumentListResponse = z.infer<typeof documentListResponseSchema>;
+/** `POST /buildr/documents`: creates a draft (never published) in a builder collection. */
+export declare const createDocumentRequestSchema: z.ZodObject<{
+    collection: z.ZodString;
+    title: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+    template: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>;
+export type CreateDocumentRequest = z.infer<typeof createDocumentRequestSchema>;
+/** `201`: the new draft. */
+export declare const createDocumentResponseSchema: z.ZodObject<{
+    ref: z.ZodObject<{
+        collection: z.ZodString;
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    }, z.core.$strip>;
+    title: z.ZodString;
+    slug: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+    }>;
+    updatedAt: z.ZodString;
+    revision: z.ZodNumber;
+    layoutSource: z.ZodEnum<{
+        builtin: "builtin";
+        "default-template": "default-template";
+        document: "document";
+        template: "template";
+    }>;
+    previewPath: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type CreateDocumentResponse = DocumentSummary;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/contract.js

@@ -0,0 +1,176 @@
+import { dataSchemaSchema, mediaAssetSchema, queryResultSchema, resolvedQuerySpecSchema, } from '@next-buildr/core';
+import { z } from 'zod';
+/**
+ * The builder API contract (docs/payload.md#endpoint-contract): the request and response shapes of
+ * `/api/buildr/*`, defined once and shared by the endpoint implementations and the HTTP adapter.
+ * Documents travel as `unknown`; they are validated by `processLayout` on the server and by
+ * `parseDocument` in the adapter, not by these schemas.
+ */
+export const diagnosticSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+    severity: z.enum(['error', 'warning']),
+    path: z.array(z.union([z.string(), z.number()])).optional(),
+    details: z.record(z.string(), z.unknown()).optional(),
+});
+export const documentRefSchema = z.object({
+    collection: z.string(),
+    id: z.union([z.string(), z.number()]),
+});
+export const sessionResponseSchema = z.object({
+    user: z.object({ id: z.union([z.string(), z.number()]), email: z.string().optional() }),
+    permissions: z.object({
+        canEdit: z.boolean(),
+        canPublish: z.boolean(),
+        canUnlockTemplates: z.boolean(),
+    }),
+    limits: z.object({ maxNodes: z.number(), maxBytes: z.number() }),
+    /** `a11y.publish`: with `block`, a document with accessibility errors cannot be published. */
+    publishPolicy: z.enum(['warn', 'block']).optional(),
+    /** The languages of the site; absent without Payload localization. */
+    locales: z
+        .object({
+        locales: z.array(z.string()),
+        default: z.string(),
+        fallback: z.boolean(),
+        intl: z.record(z.string(), z.string()),
+    })
+        .optional(),
+});
+export const documentQuerySchema = z.object({
+    draft: z.enum(['0', '1']).optional(),
+    locale: z.string().optional(),
+});
+export const documentResponseSchema = z.object({
+    ref: documentRefSchema,
+    title: z.string(),
+    slug: z.string().nullable(),
+    status: z.enum(['draft', 'published']),
+    updatedAt: z.string(),
+    /** Changes with every builder save; the next save says which one it builds on. */
+    revision: z.number().int().nonnegative(),
+    document: z.unknown(),
+    /** What the canvas gets as its data context: `{collection}:{id}`. */
+    contextRef: z.string(),
+    /**
+     * Where `document` came from: the document's own layout, its template, the collection's default
+     * template, or nothing yet (`builtin`: the canvas is blank and the site shows the built-in layout).
+     */
+    layoutSource: z.enum(['document', 'template', 'default-template', 'builtin']),
+    /** `{collection}:{id}` of the document that holds the layout; `null` for `builtin`. */
+    layoutRef: z.string().nullable(),
+    /** The public path of the document, when the collection defines one. */
+    previewPath: z.string().nullable(),
+    readOnly: z.boolean().optional(),
+});
+/** `GET /api/buildr/documents/:collection/:id/revision`: the revision without the document. */
+export const revisionResponseSchema = z.object({
+    revision: z.number().int().nonnegative(),
+    updatedAt: z.string(),
+    /** Who made the last builder write (a name or an email); only with `mcp.enabled`. */
+    updatedBy: z.string().optional(),
+});
+export const saveRequestSchema = z.object({
+    document: z.unknown(),
+    baseRevision: z.number().int().nonnegative(),
+    autosave: z.boolean(),
+});
+export const saveResponseSchema = z.object({
+    revision: z.number().int().nonnegative(),
+    updatedAt: z.string(),
+});
+/** `PATCH /buildr/documents/:collection/:id`: renames the document; the layout is not touched. */
+export const renameRequestSchema = z.object({ title: z.string().trim().min(1).max(200) });
+export const renameResponseSchema = z.object({ title: z.string() });
+export const publishRequestSchema = z.object({ baseRevision: z.number().int().nonnegative() });
+export const publishResponseSchema = z.object({
+    status: z.literal('published'),
+    publishedAt: z.string(),
+    revision: z.number().int().nonnegative(),
+    updatedAt: z.string(),
+});
+/** `409`: somebody saved in the meantime. */
+export const conflictResponseSchema = z.object({ currentRevision: z.number().int().nonnegative() });
+/** `422`: the document is not acceptable; `diagnostics` say why. */
+export const invalidResponseSchema = z.object({ diagnostics: z.array(diagnosticSchema) });
+/** Every other refusal (`400`, `401`, `403`, `404`). */
+export const errorResponseSchema = z.object({ error: z.string() });
+/** The base path of the builder API under Payload's `routes.api`. */
+export const BUILDR_API_PATH = '/buildr';
+/** `GET /buildr/data-schema/:collection` answers with core's `DataSchema`. */
+export const dataSchemaResponseSchema = dataSchemaSchema;
+export const dataContextQuerySchema = z.object({
+    collection: z.string().min(1),
+    id: z.string().min(1),
+    draft: z.enum(['0', '1']).optional(),
+    locale: z.string().optional(),
+});
+/** The scopes a canvas binds against: `{ site, [context]: doc, route }`. */
+export const dataContextResponseSchema = z.object({ scopes: z.record(z.string(), z.unknown()) });
+export const samplesResponseSchema = z.object({
+    items: z.array(z.object({ id: z.string(), title: z.string() })),
+});
+/** `POST /buildr/data/query`: one resolved query, answered with the access of the editing user. */
+export const dataQueryRequestSchema = z.object({
+    spec: resolvedQuerySpecSchema,
+    locale: z.string().optional(),
+});
+export const dataQueryResponseSchema = queryResultSchema;
+/** `POST /buildr/data/media`: media assets by id; unknown ids are left out. */
+export const dataMediaRequestSchema = z.object({
+    ids: z.array(z.string().min(1)).max(100),
+    locale: z.string().optional(),
+});
+export const dataMediaResponseSchema = z.record(z.string(), mediaAssetSchema);
+/** `GET /buildr/media?search&type&page`: the picker's listing. */
+export const mediaListQuerySchema = z.object({
+    search: z.string().max(200).optional(),
+    type: z.enum(['image', 'video', 'audio']).optional(),
+    page: z.coerce.number().int().min(1).default(1),
+    locale: z.string().max(35).optional(),
+});
+export const mediaListResponseSchema = z.object({
+    items: z.array(mediaAssetSchema),
+    page: z.number().int(),
+    totalPages: z.number().int(),
+});
+/** How many documents a page of `GET /buildr/documents` holds. */
+export const DOCUMENT_LIST_PAGE_SIZE = 20;
+/** `GET /buildr/documents?collection&search&page`: the builder documents the user may read. */
+export const documentListQuerySchema = z.object({
+    collection: z.string().min(1),
+    search: z.string().max(200).optional(),
+    page: z.coerce.number().int().min(1).default(1),
+});
+/** One document in a listing (and the answer of a creation): enough to pick it and open it. */
+export const documentSummarySchema = z.object({
+    ref: documentRefSchema,
+    title: z.string(),
+    slug: z.string().nullable(),
+    status: z.enum(['draft', 'published']),
+    updatedAt: z.string(),
+    /** The `baseRevision` an open + save starts from. */
+    revision: z.number().int().nonnegative(),
+    layoutSource: z.enum(['document', 'template', 'default-template', 'builtin']),
+    previewPath: z.string().nullable(),
+});
+export const documentListResponseSchema = z.object({
+    items: z.array(documentSummarySchema),
+    page: z.number().int(),
+    totalPages: z.number().int(),
+});
+/** `POST /buildr/documents`: creates a draft (never published) in a builder collection. */
+export const createDocumentRequestSchema = z.object({
+    collection: z.string().min(1),
+    title: z.string().trim().min(1).max(200),
+    slug: z
+        .string()
+        .min(1)
+        .max(200)
+        .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'lowercase words separated by hyphens')
+        .optional(),
+    /** The id of a template of the collection (`buildr-templates`) the document starts from. */
+    template: z.union([z.string().min(1), z.number()]).optional(),
+});
+/** `201`: the new draft. */
+export const createDocumentResponseSchema = documentSummarySchema;

package/dist/data/build-context.d.ts

@@ -0,0 +1,20 @@
+import type { SchemaOptions, SchemaSource } from './schema-from-fields.ts';
+export interface BuildContextInput {
+    readonly source: SchemaSource;
+    readonly options: SchemaOptions;
+    readonly collection: string;
+    readonly doc: Record<string, unknown>;
+    /** The site global's document, when there is one and the user may read it. */
+    readonly site?: Record<string, unknown> | undefined;
+    readonly route: {
+        readonly path: string;
+        readonly locale: string;
+        readonly page?: number;
+    };
+}
+/**
+ * The data scopes of a document: `{ site, [context]: doc, route }`, shaped exactly like the schema
+ * `schemaFromCollection` derives (same allow-list), ready to be served to the canvas as `scopes`.
+ */
+export declare function buildContext(input: BuildContextInput): Record<string, unknown>;
+//# sourceMappingURL=build-context.d.ts.map