@caltho/site-kit 0.1.0 → 0.2.0

package/dist/next/preview.js

@@ -0,0 +1,277 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// CalOS's preview of a draft: the site's own components, drawn in the browser with the content
+// CalOS sends. A site gives it a page at PREVIEW_PATH (`app/calos-preview/page.tsx`) and how it draws
+// a page; CalOS frames it, sends the draft as it changes, and hears back which field a click meant.
+// Nothing is shown until CalOS sends something, and only the business's CalOS addresses (all of
+// them: its caltho.app address and its own domain, from the build) are listened to.
+//
+// CalOS → page: { type: "calos:show", site, images, path, selected?, scroll?, labels? }
+// page → CalOS: { type: "calos:ready" }, { type: "calos:pick", path, block }, { type: "calos:go", path },
+//               { type: "calos:error", message }
+import { Component, useEffect, useRef, useState } from "react";
+import { fieldForImage, fieldForText } from "../preview-match.js";
+import { setPrepared } from "./data.js";
+export function SitePreview({ origins, render }) {
+    const [shown, setShown] = useState(null);
+    const [round, setRound] = useState(0);
+    const latest = useRef(null);
+    // Answers go to the address CalOS is open at; until it's spoken, "ready" goes to each it may be.
+    const replyTo = useRef(null);
+    const post = (msg) => {
+        if (window.parent === window)
+            return;
+        for (const o of replyTo.current ? [replyTo.current] : origins)
+            window.parent.postMessage(msg, o);
+    };
+    const key = origins.join(" ");
+    useEffect(() => {
+        if (!origins.length)
+            return;
+        const onMessage = (e) => {
+            if (!origins.includes(e.origin) || e.source !== window.parent)
+                return;
+            const m = e.data;
+            if (m?.type !== "calos:show")
+                return;
+            replyTo.current = e.origin;
+            setPrepared({ site: m.site, images: m.images, csp: {} });
+            latest.current = m;
+            setShown(m);
+            setRound((r) => r + 1);
+        };
+        window.addEventListener("message", onMessage);
+        // Said until CalOS answers: its page may still be starting when this one is ready.
+        let tries = 0;
+        const hello = () => {
+            if (latest.current || tries++ > 60)
+                return clearInterval(timer);
+            post({ type: "calos:ready" });
+        };
+        const timer = setInterval(hello, 250);
+        hello();
+        return () => {
+            clearInterval(timer);
+            window.removeEventListener("message", onMessage);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key]);
+    // Clicks pick a field, never follow a link or send a form; a link in the menu goes to that page.
+    useEffect(() => {
+        const onClick = (e) => {
+            const m = latest.current;
+            const target = e.target;
+            if (!m || !target)
+                return;
+            e.preventDefault();
+            e.stopPropagation();
+            const main = document.querySelector("main");
+            const link = target.closest("a");
+            if (link && !main?.contains(link)) {
+                const to = internalPath(link.getAttribute("href"), m.site);
+                if (to)
+                    post({ type: "calos:go", path: to });
+                return;
+            }
+            // A picture under the pointer counts, even when something over it (a frame, a caption's box) took the click.
+            const under = document.elementsFromPoint(e.clientX, e.clientY).find((el) => el.tagName === "IMG") ?? target;
+            post({ type: "calos:pick", ...pick(under, m, wordsAt(e.clientX, e.clientY)) });
+        };
+        const onSubmit = (e) => e.preventDefault();
+        // Under the pointer: the section, named, and the words or picture a click would edit.
+        const onMove = (e) => {
+            const m = latest.current;
+            const target = e.target;
+            const blocks = m ? blockElements(m) : null;
+            const n = blocks && target ? blocks.findIndex((el) => el.contains(target)) : -1;
+            const selected = m ? blockElement(m) : null;
+            hovered = n >= 0 ? blocks[n] : null;
+            outline("section", hovered && hovered !== selected ? hovered : null, n >= 0 ? m?.labels?.[n] : undefined);
+            outline("hover", hoverable(target));
+        };
+        const leave = () => {
+            hovered = null;
+            outline("section", null);
+            outline("hover", null);
+        };
+        document.documentElement.style.cursor = "pointer";
+        window.addEventListener("click", onClick, true);
+        window.addEventListener("submit", onSubmit, true);
+        window.addEventListener("pointermove", onMove, { passive: true });
+        document.documentElement.addEventListener("pointerleave", leave);
+        return () => {
+            window.removeEventListener("click", onClick, true);
+            window.removeEventListener("submit", onSubmit, true);
+            window.removeEventListener("pointermove", onMove);
+            document.documentElement.removeEventListener("pointerleave", leave);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key]);
+    // The selected block outlined (and brought into view when CalOS asks), after each drawing.
+    useEffect(() => {
+        if (!shown)
+            return;
+        const el = blockElement(shown);
+        const label = (m) => (m?.selected && typeof m.selected[3] === "number" ? m.labels?.[m.selected[3]] : undefined);
+        outline("selected", el, label(shown));
+        // The section just chosen is outlined as chosen, not as under the pointer too.
+        if (el && hovered === el)
+            outline("section", null);
+        // Scrolled here only: scrollIntoView would scroll CalOS's page around the frame too.
+        if (el && shown.scroll)
+            window.scrollTo({ top: el.getBoundingClientRect().top + window.scrollY - window.innerHeight / 4, behavior: "smooth" });
+        const keep = () => outline("selected", blockElement(latest.current), label(latest.current));
+        window.addEventListener("scroll", keep, { passive: true });
+        window.addEventListener("resize", keep);
+        return () => {
+            window.removeEventListener("scroll", keep);
+            window.removeEventListener("resize", keep);
+        };
+    }, [shown, round]);
+    if (!shown)
+        return null;
+    const page = shown.site.pages.find((p) => p.path === shown.path) ?? shown.site.pages[0];
+    if (!page)
+        return null;
+    return (_jsx(Fallback, { onError: (message) => post({ type: "calos:error", message }), children: render(page, shown.site) }, round));
+}
+/** A path on this site from a link's address, as the content writes it; null for anywhere else. */
+function internalPath(href, site) {
+    if (!href || href.startsWith("#") || /^(mailto|tel):/.test(href))
+        return null;
+    const url = new URL(href, location.href);
+    if (url.origin !== location.origin && url.origin !== new URL(site.url).origin)
+        return null;
+    const bare = url.pathname.replace(/\/$/, "") || "/";
+    const withSlash = bare === "/" ? "/" : `${bare}/`;
+    return site.pages.some((p) => p.path === bare) ? bare : site.pages.some((p) => p.path === withSlash) ? withSlash : null;
+}
+const pageIndex = (m) => m.site.pages.findIndex((p) => p.path === m.path);
+/** The page's blocks as drawn: `main`'s children, when there's one for each block. */
+function blockElements(m) {
+    const main = document.querySelector("main");
+    const page = m.site.pages[pageIndex(m)];
+    if (!main || !page)
+        return null;
+    const kids = [...main.children];
+    return kids.length === page.blocks.length ? kids : null;
+}
+function blockElement(m) {
+    if (!m?.selected)
+        return null;
+    const [k, p, b, n] = m.selected;
+    if (k !== "pages" || p !== pageIndex(m) || b !== "blocks" || typeof n !== "number")
+        return null;
+    return blockElements(m)?.[n] ?? null;
+}
+/** The words of the text under the pointer: a name set beside other things in one element (a caption with an email and a phone) is still just the name. */
+function wordsAt(x, y) {
+    const doc = document;
+    const node = doc.caretPositionFromPoint?.(x, y)?.offsetNode ?? doc.caretRangeFromPoint?.(x, y)?.startContainer;
+    return node?.nodeType === Node.TEXT_NODE ? (node.textContent?.trim() ?? null) || null : null;
+}
+/** What a click on `target` meant: the field, and the block it's in. `words`: the text right under the pointer, tried first. */
+function pick(target, m, words = null) {
+    const pi = pageIndex(m);
+    const page = m.site.pages[pi];
+    const blocks = blockElements(m);
+    const n = blocks ? blocks.findIndex((el) => el.contains(target)) : -1;
+    const block = n >= 0 ? ["pages", pi, "blocks", n] : null;
+    const scope = n >= 0 ? page.blocks[n] : null;
+    // What the whole site shares (its founders, its case studies), which a section may show too; the
+    // pages' own fields are found through the section or, outside one, the page.
+    const shared = { ...m.site, pages: [] };
+    const pageOwn = { ...page, blocks: [] };
+    const img = target.closest("img");
+    if (img) {
+        const url = img.currentSrc || img.src;
+        const found = (scope && fieldForImage(scope, block, url, m.images)) ?? fieldForImage(shared, [], url, m.images) ?? fieldForImage(pageOwn, ["pages", pi], url, m.images);
+        if (found)
+            return { path: found, block: blockOf(found) ?? block };
+    }
+    if (words) {
+        const exact = (scope && fieldForText(scope, block, words, false)) ?? fieldForText(shared, [], words, false) ?? fieldForText(pageOwn, ["pages", pi], words, false);
+        if (exact)
+            return { path: exact, block: blockOf(exact) ?? block };
+    }
+    // The clicked element's words, then its parents' until the block's edge: at each, the section's
+    // own fields first, then the site's shared ones, so a parent holding more of the section isn't
+    // mistaken for what was clicked.
+    for (let el = target; el && el !== document.body; el = el.parentElement) {
+        const text = el.innerText ?? el.textContent ?? "";
+        if (text.trim() && text.length < 2000) {
+            // The same words anywhere first (the founder's name in the founders, not inside the intro
+            // that mentions them), then a field that holds the words.
+            const at = (loose) => (scope && fieldForText(scope, block, text, loose)) ?? fieldForText(shared, [], text, loose) ?? (n < 0 ? fieldForText(pageOwn, ["pages", pi], text, loose) : null);
+            const found = at(false) ?? at(true);
+            if (found)
+                return { path: found, block: blockOf(found) ?? block };
+        }
+        if (n >= 0 && el === blocks[n])
+            break;
+    }
+    return { path: block, block };
+}
+const blockOf = (path) => (path[0] === "pages" && path[2] === "blocks" && typeof path[3] === "number" ? path.slice(0, 4) : null);
+/** The smallest thing under the pointer that's words or a picture. */
+function hoverable(el) {
+    for (let at = el; at && at !== document.body; at = at.parentElement) {
+        if (at.tagName === "IMG")
+            return at;
+        if ([...at.childNodes].some((c) => c.nodeType === Node.TEXT_NODE && c.textContent?.trim()))
+            return at;
+    }
+    return null;
+}
+// Outlines drawn over the page, sized through the style object (allowed by the content security
+// policy, where a style attribute in the markup isn't), never catching the pointer. A section's
+// outline carries its name.
+const BLUE = "#2563eb";
+const looks = {
+    selected: { outline: `2px solid ${BLUE}`, outlineOffset: "-2px", borderRadius: "2px" },
+    section: { outline: `1px solid ${BLUE}80`, outlineOffset: "-1px", borderRadius: "2px" },
+    hover: { outline: `1px dashed ${BLUE}`, outlineOffset: "3px", borderRadius: "3px" },
+};
+let hovered = null;
+const boxes = {};
+function outline(which, el, label) {
+    let made = boxes[which];
+    if (!made) {
+        const box = document.createElement("div");
+        Object.assign(box.style, { position: "fixed", pointerEvents: "none", zIndex: "2147483647", ...looks[which] });
+        const tag = document.createElement("span");
+        Object.assign(tag.style, {
+            position: "absolute",
+            top: "0",
+            left: "0",
+            padding: "3px 8px",
+            font: "500 12px/1.3 system-ui, -apple-system, sans-serif",
+            color: "#fff",
+            background: which === "selected" ? BLUE : `${BLUE}cc`,
+            borderBottomRightRadius: "4px",
+            whiteSpace: "nowrap",
+        });
+        box.appendChild(tag);
+        document.body.appendChild(box);
+        made = boxes[which] = { box, tag };
+    }
+    if (!el)
+        return void (made.box.style.display = "none");
+    const r = el.getBoundingClientRect();
+    Object.assign(made.box.style, { display: "block", top: `${r.top}px`, left: `${r.left}px`, width: `${r.width}px`, height: `${r.height}px` });
+    made.tag.textContent = label ?? "";
+    made.tag.style.display = label ? "block" : "none";
+}
+/** A draft that can't be drawn yet (a block half filled in) says so instead of a blank page. */
+class Fallback extends Component {
+    state = { error: null };
+    static getDerivedStateFromError(e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    componentDidCatch(e) {
+        this.props.onError(e instanceof Error ? e.message : String(e));
+    }
+    render() {
+        return this.state.error ? null : this.props.children;
+    }
+}

package/dist/prepare.d.ts

@@ -15,6 +15,10 @@ export type PreparedImage = {
 export type Prepared = {
     site: Site;
     images: Record<string, PreparedImage>;
+    /** Sources the site's content security policy allows beyond its own, by directive (from defineSite). */
+    csp: Record<string, string[]>;
+    /** The addresses of the CalOS this content came from (every one the business uses it on): those that may draw drafts in the preview. */
+    editors?: string[];
 };
 type Log = (line: string) => void;
 export declare function prepare(root: string, env?: Record<string, string | undefined>, log?: Log): Promise<Prepared>;

package/dist/prepare.js

@@ -15,7 +15,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, extname, join, relative } from "node:path";
 import sharp from "sharp";
 import { pathToFileURL } from "node:url";
@@ -29,15 +29,27 @@ export async function prepare(root, env = process.env, log = console.log) {
     // The content: CalOS's when told where, the site's own otherwise.
     let raw;
     let from;
-    if (env.CALOS_CONTENT_URL) {
-        const res = await fetch(env.CALOS_CONTENT_URL, {
+    let editors = [];
+    // A site CalOS has nothing published for yet (just made, its content not brought in) builds from
+    // its own until there is: 404 is "nothing published", any other refusal is an error.
+    const res = env.CALOS_CONTENT_URL
+        ? await fetch(env.CALOS_CONTENT_URL, {
             headers: env.CALOS_SITE_TOKEN ? { authorization: `Bearer ${env.CALOS_SITE_TOKEN}` } : {},
             signal: AbortSignal.timeout(30_000),
-        });
+        })
+        : null;
+    const editorsIn = (body) => (Array.isArray(body?.editors) ? body.editors.filter((o) => typeof o === "string" && /^https?:\/\/[a-z0-9.-]+(:\d+)?$/i.test(o)) : []);
+    if (res && res.status === 404) {
+        // Who may edit it is known before anything's published: its preview can be drawn from the start.
+        editors = editorsIn((await res.json().catch(() => null)));
+        log("site-kit: nothing published in CalOS yet; building from content/site.json");
+    }
+    if (res && res.status !== 404) {
         if (!res.ok)
             throw new Error(`Couldn't get the content from CalOS (${env.CALOS_CONTENT_URL}): ${res.status}`);
         const body = (await res.json());
         raw = body.content;
+        editors = editorsIn(body);
         from = "CalOS";
         // Pictures uploaded in CalOS, fetched into the images folder once each.
         for (const [name, url] of Object.entries(body.images ?? {})) {
@@ -66,9 +78,15 @@ export async function prepare(root, env = process.env, log = console.log) {
     if (parsed.problems)
         throw new Error(`The site's content needs fixing (${from}):\n  - ${parsed.problems.join("\n  - ")}`);
     const site = parsed.site;
-    await writeFile(join(out, "schema.json"), JSON.stringify(definition.jsonSchema(), null, 2) + "\n");
+    for (const w of parsed.warnings)
+        log(`site-kit: warning: ${w}`);
+    const schema = definition.jsonSchema();
+    await writeFile(join(out, "schema.json"), JSON.stringify(schema, null, 2) + "\n");
+    // Content from CalOS: tell it what this build says is editable, so its forms match the site's code.
+    if (env.CALOS_CONTENT_URL)
+        await pushSchema(env.CALOS_CONTENT_URL, env.CALOS_SCHEMA_URL, env.CALOS_SITE_TOKEN, schema, log);
     const images = await pictures(site, imagesDir, pub, log);
-    const prepared = { site, images };
+    const prepared = { site, images, csp: definition.csp, ...(editors.length ? { editors } : {}) };
     await writeFile(join(out, "prepared.json"), JSON.stringify(prepared));
     log(`site-kit: content from ${from}, ${site.pages.length} pages, ${Object.keys(images).length} images`);
     return prepared;
@@ -108,7 +126,11 @@ async function pictures(site, imagesDir, pub, log) {
         for (const w of widths.length ? widths : [width]) {
             const name = `${base}.${hash}.${w}.webp`;
             if (!existsSync(join(dir, name))) {
-                await sharp(bytes).rotate().resize({ width: w }).webp({ quality: 78 }).toFile(join(dir, name));
+                // A WebP that's already the size wanted is kept as it is: encoding it again only loses quality.
+                if (meta.format === "webp" && w === width && !meta.orientation)
+                    await copyFile(join(imagesDir, src), join(dir, name));
+                else
+                    await sharp(bytes).rotate().resize({ width: w }).webp({ quality: 78 }).toFile(join(dir, name));
                 made++;
             }
             srcset.push({ w, url: `/_img/${name}` });
@@ -157,3 +179,20 @@ async function loadDefinition(root) {
         throw new Error(`${relative(root, file)} should export default defineSite({ ...blocks })`);
     return mod.default;
 }
+/** Tells CalOS the declaration (every build; it keeps the latest). A refusal is said, not fatal: the build has its content. */
+async function pushSchema(contentUrl, schemaUrl, token, schema, log) {
+    const url = schemaUrl ?? contentUrl.replace(/\/content(\?.*)?$/, "/schema");
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+            body: JSON.stringify(schema),
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (!res.ok)
+            log(`site-kit: warning: CalOS didn't take the site's schema (${url}): ${res.status}`);
+    }
+    catch (err) {
+        log(`site-kit: warning: couldn't tell CalOS the site's schema (${url}): ${err.message}`);
+    }
+}

package/dist/preview-match.d.ts

@@ -0,0 +1,23 @@
+export type Path = (string | number)[];
+/** Words as they read on the page: Markdown's marks gone, a link's address gone, spacing and case evened. */
+export declare function readable(text: string): string;
+/** Every string in `value`, with where it is. */
+export declare function textsIn(value: unknown, base?: Path): {
+    path: Path;
+    key: string;
+    text: string;
+}[];
+/**
+ * The field whose words best match what was clicked: the same words first; then the longest field
+ * the clicked element's words contain, if it's a fair share of them (a card holding a title and a
+ * line picks the longer); then the field that contains the clicked words (a bold phrase inside a
+ * paragraph).
+ */
+export declare function fieldForText(value: unknown, base: Path, clicked: string, loose?: boolean): Path | null;
+/** The field naming the picture shown at `url`: its content path, by the prepared images' addresses. */
+export declare function fieldForImage(value: unknown, base: Path, url: string, images: Record<string, {
+    src: string;
+    srcset?: {
+        url: string;
+    }[];
+}>): Path | null;

package/dist/preview-match.js

@@ -0,0 +1,78 @@
+// Which field of the content a click in CalOS's preview landed on, with no markers in the site's
+// components: the words clicked are matched against the content's text, a picture by its address.
+// Pure, so it's tested here and runs in the preview in the browser.
+/** Keys that hold no words a visitor reads: never what a click on words means. */
+const SKIP = new Set(["type", "id", "href", "path", "style", "menuStyle", "footer", "ratio", "tone"]);
+/** Words as they read on the page: Markdown's marks gone, a link's address gone, spacing and case evened. */
+export function readable(text) {
+    return text
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/^#{1,6}\s+/gm, "")
+        .replace(/^\s*(?:[-*+]|\d+\.)\s+/gm, "")
+        .replace(/[*_`>~]/g, "")
+        .replace(/[‘’]/g, "'")
+        .replace(/[“”]/g, '"')
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+/** Every string in `value`, with where it is. */
+export function textsIn(value, base = []) {
+    const out = [];
+    const visit = (v, path) => {
+        const key = String(path.filter((p) => typeof p === "string").at(-1) ?? "");
+        if (typeof v === "string") {
+            if (!SKIP.has(key) && v.trim())
+                out.push({ path, key, text: v });
+        }
+        else if (Array.isArray(v))
+            v.forEach((x, i) => visit(x, [...path, i]));
+        else if (v && typeof v === "object")
+            for (const [k, x] of Object.entries(v))
+                visit(x, [...path, k]);
+    };
+    visit(value, base);
+    return out;
+}
+/**
+ * The field whose words best match what was clicked: the same words first; then the longest field
+ * the clicked element's words contain, if it's a fair share of them (a card holding a title and a
+ * line picks the longer); then the field that contains the clicked words (a bold phrase inside a
+ * paragraph).
+ */
+export function fieldForText(value, base, clicked, loose = true) {
+    const want = readable(clicked);
+    if (!want)
+        return null;
+    const all = textsIn(value, base)
+        .filter((t) => !t.key.endsWith("src") && !/^https?:|^\//.test(t.text))
+        .map((t) => ({ ...t, words: readable(t.text) }))
+        .filter((t) => t.words);
+    const same = all.find((t) => t.words === want);
+    if (same)
+        return same.path;
+    // Only a field that's a fair share of what was clicked: a container holding a whole section's
+    // words would otherwise match whichever field is longest in it.
+    const inside = all.filter((t) => want.includes(t.words) && t.words.length >= want.length * 0.4).sort((a, b) => b.words.length - a.words.length)[0];
+    if (inside)
+        return inside.path;
+    // Without `loose`, only those: a field elsewhere with exactly these words is a better match than one here that merely holds them.
+    if (!loose)
+        return null;
+    const around = all.filter((t) => t.words.includes(want)).sort((a, b) => a.words.length - b.words.length)[0];
+    return around?.path ?? null;
+}
+/** The field naming the picture shown at `url`: its content path, by the prepared images' addresses. */
+export function fieldForImage(value, base, url, images) {
+    const clean = (u) => u.replace(/^https?:\/\/[^/]+/, "").split("?")[0];
+    const shown = clean(url);
+    const names = Object.entries(images).filter(([, m]) => clean(m.src) === shown || m.srcset?.some((s) => clean(s.url) === shown)).map(([name]) => name);
+    if (!names.length)
+        return null;
+    const hit = textsIn(value, base).find((t) => t.key.endsWith("src") && names.includes(t.text));
+    if (!hit)
+        return null;
+    // The picture's group (its src and alt together) is what's edited.
+    return hit.path.slice(0, -1).length > base.length ? hit.path.slice(0, -1) : hit.path;
+}

package/dist/schema.d.ts

@@ -0,0 +1,60 @@
+export type Schema = {
+    type?: string | string[];
+    properties?: Record<string, Schema>;
+    required?: string[];
+    items?: Schema;
+    anyOf?: Schema[];
+    oneOf?: Schema[];
+    enum?: unknown[];
+    const?: unknown;
+    default?: unknown;
+    pattern?: string;
+    format?: string;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+    title?: string;
+    description?: string;
+    /** How an editor draws it: "textarea", "markdown", "image", "image-file". */
+    "x-ui"?: string;
+    /** What to say when it's wrong, where the pattern's own words wouldn't help. */
+    "x-error"?: string;
+    $ref?: string;
+    $defs?: Record<string, Schema>;
+};
+export type Issue = {
+    path: (string | number)[];
+    message: string;
+};
+/** Follows a `$ref` to its definition in the same document. */
+export declare function resolve(s: Schema, root: Schema): Schema;
+/** A union of objects told apart by a `type` field: its branches by that field's value; else null. */
+export declare function branches(s: Schema, root: Schema): Record<string, Schema> | null;
+/** The kinds of block (or any discriminated list item) a list's items can be, in the order the site gave them. */
+export declare function kindsOf(items: Schema, root: Schema): string[];
+/** What's wrong with `value` against `schema`, as places and plain messages. */
+export declare function validate(schema: Schema, value: unknown, root?: Schema, path?: (string | number)[]): Issue[];
+/** A blank value for a schema: what a new list entry or block starts as, with what's needed in place. */
+export declare function blank(schema: Schema, root?: Schema, kindOfBlock?: string): unknown;
+export type StructureIssue = Issue;
+/**
+ * What's wrong with a site's content that no field's shape can say: two pages at one path, no home
+ * page, a link to a page that isn't there or to a part of a page that isn't. Pure, on the content as
+ * data, so CalOS can run the same check on a draft as the build does.
+ */
+export declare function checkStructure(site: {
+    pages: {
+        path: string;
+        blocks: {
+            id?: unknown;
+        }[];
+    }[];
+    [extra: string]: unknown;
+}): StructureIssue[];
+/** "pages[2] (/services/) › blocks[1] (services) › items[0].title", readable in a build log or an editor. */
+export declare function describePath(raw: unknown, path: PropertyKey[]): string;
+/** The last named field in a path, for a short label. */
+export declare const fieldOf: (path: (string | number)[]) => string | undefined;