@valbuild/shared 0.150.13 → 0.150.17

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @valbuild/shared
 
+## 0.150.17
+
+### Patch Changes
+
+- [#992](https://github.com/valbuild/val/pull/992) [`ea3bf9b`](https://github.com/valbuild/val/commit/ea3bf9bbacd22bbb5485fd798d6b3a2d5916be81) Thanks [@freekh](https://github.com/freekh)! - Content analytics now counts on self-hosted sites (Custom hosting), not only on sites Val hosts.
+
+  A self-hosted app's own Val server now hands each analytics beacon on to Val's ingest, which counts it. To turn it on:
+
+  - Run the app with Val's content service: `VAL_API_KEY`, `VAL_SECRET` and `VAL_PROJECT` set. Most deployed apps already do.
+  - Set `VAL_ANALYTICS=true`. In TanStack Start, read it in your layout's loader (`{ enabled: process.env.VAL_ANALYTICS === "true" }`) and pass the result to `<ValProvider analytics>`. A self-hosted site has no platform to pass it for you.
+  - Switch analytics on for the project in Val's admin. While it is off there, the script on your pages is told so and stops sending.
+
+  The server forwards only same-origin beacons from a browser. It passes on the visitor's User-Agent and, where your host provides one (Vercel, Cloudflare or CloudFront), their country. It never passes on their IP address. If the api key is not accepted, the server logs one warning naming `VAL_API_KEY` and `VAL_PROJECT`. Local development (fs mode) works as before and counts nothing.
+
+  `VAL_ANALYTICS_INGEST_URL` overrides where beacons are sent. You will normally not need it.
+
+## 0.150.16
+
+### Patch Changes
+
+- [#940](https://github.com/valbuild/val/pull/940) [`3ac24d4`](https://github.com/valbuild/val/commit/3ac24d46691c646dd5d2789cf2e1d6e2734195d3) Thanks [@freekh](https://github.com/freekh)! - Picking a language in the Studio now scopes the whole Studio to it.
+
+  - The Pages tree, the Data list, lists inside a field and search show only content in that language, plus content in no language (settings, authors, images), which every language shares. A page is in a language when its route names it (`s.router(router, { locale: … }, item)`) or its content has an `s.locale()` field.
+  - Picking a language while you are on something in another one moves you: to the same entry in the new language where Val knows it (a record keyed by `s.locale()`, or a route that differs only in its language segment), otherwise to the nearest parent that is not in another language, otherwise to the Studio's start screen with nothing selected.
+  - A link or a reference to something in another language still opens it, and that one item is listed while you are on it.
+  - Publish, Discard all and the error count are not filtered: they act on every language.
+
+- [#969](https://github.com/valbuild/val/pull/969) [`7db39ef`](https://github.com/valbuild/val/commit/7db39ef722b4f743e6974effd5fedfadc76e6544) Thanks [@freekh](https://github.com/freekh)! - **Sketchpad**: work out a page's content and rough layout with the assistant before anyone builds it.
+
+  A sketchpad is a document of headings, text, boxes and columns, where you edit the text in place. A box can show an image or a video from a link: paste one, or drag an image in from a web page. The assistant sees the same sketch as text in one strict format, so what it reads is what is on screen. It has tools to list, create, read and write sketchpads, and **Send to AI** asks it to read the one you are on.
+
+  - Sketchpads live on the server, apart from any chat or page. They outlast the chat they started in, and the page a sketchpad is about can be changed. A sketchpad can be archived and reopened.
+  - Open one from a page's menu (**Sketch changes**), from the top bar, or when the assistant offers one.
+  - On a desktop the page, the sketchpad and the chat sit side by side, the chat docked beside them. On a phone a sketchpad can go full screen, with the page one tap away and the buttons at the bottom.
+  - In local development sketchpads are stored in `.val/sketchpads/`. A hosted project needs the content host's sketchpad API; without it the Studio does not offer sketchpads.
+
 ## 0.150.13
 
 ### Patch Changes

package/dist/declarations/src/internal/ApiRoutes.d.ts

@@ -82,6 +82,43 @@ export declare const AnalyticsBeacon: z.ZodObject<{
     viewed: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type AnalyticsBeacon = z.infer<typeof AnalyticsBeacon>;
+/**
+ * A Sketchpad, as the server keeps it: a rough page written in the strict
+ * format of `sketchpad/sketchFormat.ts`, owned by the project and nothing
+ * else. Not by an AI session -- the assistant that made it remembers its id,
+ * and any chat can read it again -- and not by a page: `page` is a label for
+ * which page it is about, and can be changed or cleared.
+ *
+ * `version` goes up by one on every change, and a change names the version
+ * it was made against, so two writers cannot overwrite each other unseen.
+ */
+export declare const Sketchpad: z.ZodObject<{
+    id: z.ZodString;
+    page: z.ZodNullable<z.ZodString>;
+    title: z.ZodNullable<z.ZodString>;
+    text: z.ZodString;
+    version: z.ZodNumber;
+    archived: z.ZodBoolean;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    createdBy: z.ZodNullable<z.ZodString>;
+    updatedBy: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SketchpadT = z.infer<typeof Sketchpad>;
+export declare const SketchpadSummary: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodNullable<z.ZodString>;
+    page: z.ZodNullable<z.ZodString>;
+    version: z.ZodNumber;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    archived: z.ZodBoolean;
+    createdBy: z.ZodNullable<z.ZodString>;
+    updatedBy: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SketchpadSummaryT = z.infer<typeof SketchpadSummary>;
+/** The most text a sketchpad holds, in UTF-8 bytes: a page, not a site. */
+export declare const SKETCHPAD_MAX_TEXT_LENGTH: number;
 export declare const Api: {
     "/draft/enable": {
         GET: {
@@ -139,6 +176,13 @@ export declare const Api: {
         POST: {
             req: {
                 body: z.ZodUnknown;
+                headers: {
+                    "sec-fetch-site": z.ZodOptional<z.ZodString>;
+                    "user-agent": z.ZodOptional<z.ZodString>;
+                    "x-vercel-ip-country": z.ZodOptional<z.ZodString>;
+                    "cf-ipcountry": z.ZodOptional<z.ZodString>;
+                    "cloudfront-viewer-country": z.ZodOptional<z.ZodString>;
+                };
             };
             res: z.ZodUnion<readonly [z.ZodObject<{
                 status: z.ZodLiteral<200>;
@@ -150,6 +194,11 @@ export declare const Api: {
                 json: z.ZodObject<{
                     message: z.ZodString;
                 }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<410>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
             }, z.core.$strip>]>;
         };
     };
@@ -700,6 +749,221 @@ export declare const Api: {
             }, z.core.$strip>;
         };
     };
+    /**
+     * The project's sketchpads: list them, or make one. See `Sketchpad`.
+     * Making one answers with its id, which is what an assistant keeps to
+     * read and change it later.
+     */
+    "/sketchpads": {
+        GET: {
+            req: {
+                query: {
+                    /** `exclude` (the default), `include`, or `only`. */
+                    archived: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>>;
+                    /** Only those about this page. */
+                    page: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>>;
+                };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<400>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    sketchpads: z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        title: z.ZodNullable<z.ZodString>;
+                        page: z.ZodNullable<z.ZodString>;
+                        version: z.ZodNumber;
+                        createdAt: z.ZodString;
+                        updatedAt: z.ZodString;
+                        archived: z.ZodBoolean;
+                        createdBy: z.ZodNullable<z.ZodString>;
+                        updatedBy: z.ZodNullable<z.ZodString>;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+        POST: {
+            req: {
+                body: z.ZodObject<{
+                    text: z.ZodString;
+                    page: z.ZodNullable<z.ZodString>;
+                }, z.core.$strip>;
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<400>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                    errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        line: z.ZodNumber;
+                        message: z.ZodString;
+                    }, z.core.$strip>>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<201>;
+                json: z.ZodObject<{
+                    sketchpad: z.ZodObject<{
+                        id: z.ZodString;
+                        page: z.ZodNullable<z.ZodString>;
+                        title: z.ZodNullable<z.ZodString>;
+                        text: z.ZodString;
+                        version: z.ZodNumber;
+                        archived: z.ZodBoolean;
+                        createdAt: z.ZodString;
+                        updatedAt: z.ZodString;
+                        createdBy: z.ZodNullable<z.ZodString>;
+                        updatedBy: z.ZodNullable<z.ZodString>;
+                    }, z.core.$strip>;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
+    /** One sketchpad: read it, or change its text, its page or whether it is archived. */
+    "/sketchpad": {
+        GET: {
+            req: {
+                query: {
+                    id: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<404>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    sketchpad: z.ZodObject<{
+                        id: z.ZodString;
+                        page: z.ZodNullable<z.ZodString>;
+                        title: z.ZodNullable<z.ZodString>;
+                        text: z.ZodString;
+                        version: z.ZodNumber;
+                        archived: z.ZodBoolean;
+                        createdAt: z.ZodString;
+                        updatedAt: z.ZodString;
+                        createdBy: z.ZodNullable<z.ZodString>;
+                        updatedBy: z.ZodNullable<z.ZodString>;
+                    }, z.core.$strip>;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+        PATCH: {
+            req: {
+                body: z.ZodObject<{
+                    id: z.ZodString;
+                    baseVersion: z.ZodNumber;
+                    text: z.ZodOptional<z.ZodString>;
+                    page: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    archived: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strip>;
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<404>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<400>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                    errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        line: z.ZodNumber;
+                        message: z.ZodString;
+                    }, z.core.$strip>>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<409>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                    sketchpad: z.ZodObject<{
+                        id: z.ZodString;
+                        page: z.ZodNullable<z.ZodString>;
+                        title: z.ZodNullable<z.ZodString>;
+                        text: z.ZodString;
+                        version: z.ZodNumber;
+                        archived: z.ZodBoolean;
+                        createdAt: z.ZodString;
+                        updatedAt: z.ZodString;
+                        createdBy: z.ZodNullable<z.ZodString>;
+                        updatedBy: z.ZodNullable<z.ZodString>;
+                    }, z.core.$strip>;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    sketchpad: z.ZodObject<{
+                        id: z.ZodString;
+                        page: z.ZodNullable<z.ZodString>;
+                        title: z.ZodNullable<z.ZodString>;
+                        text: z.ZodString;
+                        version: z.ZodNumber;
+                        archived: z.ZodBoolean;
+                        createdAt: z.ZodString;
+                        updatedAt: z.ZodString;
+                        createdBy: z.ZodNullable<z.ZodString>;
+                        updatedBy: z.ZodNullable<z.ZodString>;
+                    }, z.core.$strip>;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
     "/upload/patches": {
         POST: {
             req: {

package/dist/declarations/src/internal/aiTools/toolNames.d.ts

@@ -1,2 +1,2 @@
-export declare const toolNames: readonly ["get_all_schema", "get_source", "search_content", "validate_content", "create_patch", "add_session_image_to_gallery", "remove_image_gallery_entry", "navigate_to", "get_current_context", "get_patches", "get_source_path_from_route", "set_session_name", "show_compare_view", "ask_user_question", "duplicate_source", "empty_at_path", "count_entries", "get_record_keys"];
+export declare const toolNames: readonly ["get_all_schema", "get_source", "search_content", "validate_content", "create_patch", "add_session_image_to_gallery", "remove_image_gallery_entry", "navigate_to", "get_current_context", "get_patches", "get_source_path_from_route", "set_session_name", "show_compare_view", "ask_user_question", "duplicate_source", "empty_at_path", "count_entries", "get_record_keys", "list_sketchpads", "create_sketchpad", "read_sketchpad", "write_sketchpad"];
 export type ToolName = (typeof toolNames)[number];

package/dist/declarations/src/internal/index.d.ts

@@ -21,6 +21,7 @@ export * from "./getNextAppRouterSourceFolder.js";
 export * from "./routeValidation.js";
 export * from "./resolveSchemaSourceFixes.js";
 export * from "./localeAt.js";
+export * from "./localeRelocation.js";
 export * from "./getErrorMessageFromUnknownJson.js";
 export * from "./zod/SerializedSchema.js";
 export * from "./valCanvasProtocol.js";
@@ -30,6 +31,7 @@ export * from "./pageScreenshot.js";
 export * from "./quickPreview.js";
 export * from "./emptyOf.js";
 export * from "./aiTools/toolNames.js";
+export * from "./sketchpad/sketchFormat.js";
 export * from "./aiTools/aiImageToolPatches.js";
 export * from "./aiTools/aiSourceToolPatches.js";
 export * from "./validation/partitionValidationErrors.js";

package/dist/declarations/src/internal/localeAt.d.ts

@@ -1,4 +1,4 @@
-import { type SerializedEnumSchema, type SerializedSchema, type SourcePath } from "@valbuild/core";
+import { type Json, type JsonObject, type ModuleFilePath, type SerializedEnumSchema, type SerializedSchema, type SourcePath } from "@valbuild/core";
 import { type SchemaSourceSnapshot } from "./resolveSchemaSourceFixes.js";
 /**
  * Which of the project's languages governs a path, or `null` for none.
@@ -18,6 +18,52 @@ import { type SchemaSourceSnapshot } from "./resolveSchemaSourceFixes.js";
  * in most projects, and for every project that has not declared any languages.
  */
 export declare function localeAt(path: SourcePath, snapshot: SchemaSourceSnapshot): string | null;
+/**
+ * Where the scope governing a path opens, and how.
+ *
+ * - `field`: the node `depth` segments down has a locale field. `depth` 0 is the
+ *   module root.
+ * - `record-key`: segment `depth` is a key of a locale-keyed record, which sits
+ *   `depth` segments down.
+ * - `route-key`: segment `depth` is a route whose parameters name the language,
+ *   in the router `depth` segments down (in practice the module root).
+ *
+ * The opener is what decides where an editor goes when the Studio's language
+ * changes under them — the same entry in another language for a key, the
+ * parent for a field. See `relocateForLocale`.
+ */
+export type LocaleScope = {
+    locale: string;
+    depth: number;
+} & ({
+    kind: "field";
+} | {
+    kind: "record-key";
+    keySchema: SerializedSchema;
+} | {
+    kind: "route-key";
+    router: SerializedSchema & {
+        type: "record";
+    };
+});
+/**
+ * The scope that governs a path, read from that module's schema and source
+ * alone, or `null` where none does.
+ *
+ * {@link localeAt} for a caller that already has the module in hand — the
+ * Studio, which has the project's languages from its own provider and would
+ * otherwise have to assemble a snapshot of every module to ask about one.
+ */
+export declare function localeScopeAt(path: SourcePath, schema: SerializedSchema, source: Json, available: readonly string[]): LocaleScope | null;
+/**
+ * The language a whole module is in: the one its root's locale field names, or
+ * `null` where its root has none.
+ *
+ * The only way a module is in one language as a whole — a locale-keyed record
+ * or a router at the root is every one of its languages at once. Needs no path,
+ * so a list of modules can ask it of each.
+ */
+export declare function localeOfModuleRoot(schema: SerializedSchema, source: Json, available: readonly string[]): string | null;
 /**
  * The language a locale schema's value MEANS, or `null` if it means none of
  * the project's.
@@ -44,3 +90,42 @@ export declare function enumLocaleTag(schema: SerializedEnumSchema, value: strin
  * one.
  */
 export declare function isLocaleSchema(schema: SerializedSchema): boolean;
+/**
+ * Whether a router's URLs name the language each page is in — one of its route
+ * parameters is a locale (`s.router(router, { locale: … }, item)`).
+ */
+export declare function hasLocaleRouteParam(schema: SerializedSchema): boolean;
+/**
+ * The language a router's key is in, where one of its route parameters is a
+ * locale — `/nb/blog/hei` is `nb-NO` when `locale` maps `nb` to it.
+ *
+ * Answered from the key alone, with no content read: which is what lets the
+ * Studio's page tree filter every page of a site without loading one of them.
+ */
+export declare function localeOfRouteKey(schema: SerializedSchema & {
+    type: "record";
+}, moduleFilePath: ModuleFilePath, key: string, available: readonly string[]): string | null;
+/**
+ * The route parameters a key gives its router, and which of them is the
+ * language — or `null` where the router has no locale parameter or the key is
+ * not one of its URLs.
+ */
+export declare function localeParamOfRouteKey(schema: SerializedSchema & {
+    type: "record";
+}, moduleFilePath: ModuleFilePath, key: string): {
+    name: string;
+    schema: SerializedSchema;
+    value: string | null;
+    values: Record<string, string | null>;
+} | null;
+/** The child of a source value at a segment, or `null` where there is none. */
+export declare function childSource(source: Json, segment: string): Json;
+/**
+ * Whether `source` is a JSON object rather than an array or a primitive.
+ *
+ * A type predicate rather than the inline checks, because `Array.isArray` does
+ * NOT narrow `JsonArray` out of `Json` — it is `readonly Json[]`, and the
+ * built-in guard only narrows mutable arrays. Without this, every read of a
+ * property would need an assertion.
+ */
+export declare function isJsonObject(source: Json): source is JsonObject;

package/dist/declarations/src/internal/localeRelocation.d.ts

@@ -0,0 +1,46 @@
+import { type Json, type SerializedSchema, type SourcePath } from "@valbuild/core";
+/**
+ * Where an editor goes when the Studio's language changes under them.
+ *
+ * - `stay`: the path is in that language, or in none.
+ * - `path`: the same entry in that language (`counterpart`), or the nearest
+ *   parent that is not in another language (`parent`).
+ * - `home`: neither exists, so the editor goes to the Studio's start, with
+ *   nothing selected.
+ */
+export type LocaleRelocation = {
+    type: "stay";
+} | {
+    type: "path";
+    path: SourcePath;
+    reason: "counterpart" | "parent";
+} | {
+    type: "home";
+};
+/**
+ * Where to move a path to when the Studio is switched to `locale`.
+ *
+ * The rule, in the order it is tried:
+ *
+ * 1. **The same entry in `locale`, where Val KNOWS it.** That is two cases:
+ *    a locale-keyed record, where the counterpart of `"en-US"` is the
+ *    `"nb-NO"` key of the same record; and a router whose URLs name their
+ *    language, where `/about` and `/nb/about` differ only in it. Only a key
+ *    that exists is taken, and the rest of the path is kept as far as it
+ *    still exists, so an editor on a field lands on that field.
+ * 2. **Otherwise the nearest parent that is not in another language.** An
+ *    English post in a list of posts gives the list, now showing Norwegian.
+ * 3. **Otherwise the Studio's start**, which is `home`: nothing selected. That
+ *    is where an object at the module root opened the scope (the whole module
+ *    is in another language), and where the parent would be a router: a list
+ *    of pages is not a page, and the Pages tree is how an editor sees one.
+ *
+ * Not the site's root page, and not any other page: which language a page is
+ * in is the page's own business, and `/` can be in the language the editor
+ * just left. The start screen is in no language.
+ *
+ * Never a guess. Two pages whose URLs differ in more than the language — a
+ * Norwegian slug for a Norwegian page — are not known to be translations of
+ * each other, so that is `home` rather than whichever page looks closest.
+ */
+export declare function relocateForLocale(path: SourcePath, locale: string, schema: SerializedSchema, source: Json, available: readonly string[]): LocaleRelocation;

package/dist/declarations/src/internal/sketchpad/sketchFormat.d.ts

@@ -0,0 +1,118 @@
+/**
+ * A page sketch: a page written as indented text, with four primitives.
+ *
+ * ```
+ * # Our people                 text (a heading: #, ## or ###)
+ * We are 40 people in Oslo.    text (a paragraph)
+ * [image: Team photo]          placeholder: [kind] or [kind: label]
+ * [hero: Roof](image: /a.jpg)  a placeholder with an image (or video) in it
+ * icon hero M3 5h18v14H3z      how every [hero] box is drawn: SVG path data
+ * row                          its children side by side
+ *   col 2                      its children stacked; 2 shares of the row
+ *     ## Design
+ *   col
+ *     [button: Join us]
+ * ```
+ *
+ * It is a scratch pad, not a layout language: it says WHAT is on a page and
+ * roughly WHERE, so an assistant and a person can agree on a page's content
+ * before anyone worries about how it looks. The person never sees this text,
+ * only the page it describes; the assistant never sees the page, only this.
+ * So the two have to be the same thing, and the format is STRICT: there is
+ * exactly one way to write what is on the screen. `checkSketch` is that
+ * rule, and the server refuses a write that breaks it, with the line to fix.
+ *
+ * Parsing is still forgiving, so a sketch that breaks the rule shows what it
+ * can rather than nothing; that is for reading, never for accepting.
+ *
+ * A placeholder's kind is any word, and nothing here knows what one means. The
+ * assistant that writes the sketch also draws each kind's icon, as path data
+ * in a 24 by 24 box, so a kind nobody thought of looks as deliberate as an
+ * image. Media put in a box is written into the text too, so the assistant
+ * that builds the page reads it exactly as the person left it.
+ */
+export type SketchNode = SketchRow | SketchCol | SketchText | SketchPlaceholder;
+export type SketchRow = {
+    type: "row";
+    line: number;
+    children: SketchNode[];
+};
+export type SketchCol = {
+    type: "col";
+    line: number;
+    /** Shares of the enclosing row this column takes. */
+    weight: number;
+    children: SketchNode[];
+};
+export type SketchText = {
+    type: "text";
+    line: number;
+    /** 0 is a paragraph; 1-3 are headings. */
+    level: 0 | 1 | 2 | 3;
+    text: string;
+};
+export type SketchPlaceholder = {
+    type: "placeholder";
+    line: number;
+    kind: string;
+    label: string | null;
+    media: SketchMedia | null;
+};
+export type SketchMedia = {
+    type: "image" | "video";
+    src: string;
+};
+export type SketchError = {
+    /** 1-based, like an editor's gutter. */
+    line: number;
+    message: string;
+};
+export type ParsedSketch = {
+    /** The page itself is a column. */
+    blocks: SketchNode[];
+    /**
+     * SVG path data by kind, lower case. Drawn as a 24 by 24 line icon: stroked
+     * in the text colour, not filled.
+     */
+    icons: Record<string, string>;
+    errors: SketchError[];
+};
+export declare function parseSketch(source: string): ParsedSketch;
+/**
+ * The line a text block is written as. Line breaks become spaces, and a
+ * paragraph that would read as something else is kept as text with `\`.
+ */
+export declare function formatSketchText(level: SketchText["level"], text: string): string;
+/** The line a placeholder is written as. */
+export declare function formatSketchBox(placeholder: Pick<SketchPlaceholder, "kind" | "label" | "media">): string;
+/**
+ * The ONE way of writing `blocks` and `icons`: what `checkSketch` holds every
+ * other text to, and what the Studio's editor writes (its own serializer is
+ * tested against this one). Two spaces per level; an empty row gets an empty
+ * col, so it has somewhere to type; a col outside a row is written as its
+ * contents, which is all it shows; the icons last, after one blank line, and
+ * no blank line anywhere else; a final newline. Empty text is not written --
+ * it is not on the page.
+ */
+export declare function formatSketch(blocks: SketchNode[], icons: Record<string, string>): string;
+/**
+ * What a list names a sketch by: its first top-level heading, the biggest
+ * one first. Null for a sketch with no heading, which a list then names by
+ * its page.
+ */
+export declare function sketchTitle(blocks: SketchNode[]): string | null;
+/**
+ * Everything wrong with `source`, or nothing when it is a sketch exactly as
+ * `formatSketch` writes it.
+ *
+ * Strict on purpose. The person sees the page and the assistant sees the
+ * text, so a text with two spellings of one page -- a tab or two spaces, an
+ * icon line here or there, a blank line or none -- is a text the assistant
+ * cannot trust to be what is on the screen, and that would show it a change
+ * nobody made the next time the Studio writes it back. Holding every write
+ * to the one spelling rules all of that out at once.
+ *
+ * The parse errors come first; past those, the first line that is spelled
+ * differently, with how it should be spelled.
+ */
+export declare function checkSketch(source: string): SketchError[];