@valbuild/shared 0.150.13 → 0.150.17

package/internal/dist/valbuild-shared-internal.esm.js

@@ -1,5 +1,5 @@
 import { f as _createForOfIteratorHelper, d as _objectSpread2, e as _toConsumableArray, _ as _typeof, g as _defineProperty, b as _asyncToGenerator, c as _regenerator, a as _slicedToArray } from '../../dist/createForOfIteratorHelper-9b80f1a2.esm.js';
-import { Internal, CODE_LANGUAGES, resolveSettingsModule, missingDeclaredKeys, localeOfValue, discriminatedUnionBranchOf, routePatternOf, matchRoutePattern, DEFAULT_COLOR_FORMAT, declaredKeySetOf } from '@valbuild/core';
+import { Internal, CODE_LANGUAGES, resolveSettingsModule, missingDeclaredKeys, localeOfValue, routePatternOf, matchRoutePattern, discriminatedUnionBranchOf, DEFAULT_COLOR_FORMAT, declaredKeySetOf } from '@valbuild/core';
 import { z } from 'zod';
 import { _ as _objectWithoutProperties } from '../../dist/protocol-55cfa3cf.esm.js';
 export { P as PublishProtocolError, b as parseArtifacts, p as parseBuildTarget, l as parseCancel, a as parseDeclare, m as parseDiscard, j as parseJob, n as parseNewestCiRun, h as parsePress, g as parseProblems, f as parseProjectSource, d as parsePromote, o as parsePublishToken, k as parseRenew, i as parseRequestStatus, e as parseStatus, q as parseUpdateTarget, c as parseVerify } from '../../dist/protocol-55cfa3cf.esm.js';
@@ -1663,6 +1663,40 @@ var AnalyticsBeacon = z.object({
 }, {
   message: "At most ".concat(MAX_ANALYTICS_PATHS_PER_BEACON, " paths a beacon")
 });
+/**
+ * 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.
+ */
+var Sketchpad = z.object({
+  id: z.string(),
+  page: z.string().nullable(),
+  /** Its first heading, for a list to name it by. */
+  title: z.string().nullable(),
+  text: z.string(),
+  version: z.number()["int"](),
+  archived: z["boolean"](),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  /** Profile ids; null where nobody was signed in (local dev, the demo). */
+  createdBy: z.string().nullable(),
+  updatedBy: z.string().nullable()
+});
+var SketchpadSummary = Sketchpad.omit({
+  text: true
+});
+/** A line of a sketch the server would not take, and why. */
+var SketchErrorZ = z.object({
+  line: z.number(),
+  message: z.string()
+});
+/** The most text a sketchpad holds, in UTF-8 bytes: a page, not a site. */
+var SKETCHPAD_MAX_TEXT_LENGTH = 256 * 1024;
 var Api = {
   "/draft/enable": {
     GET: {
@@ -1713,11 +1747,22 @@ var Api = {
       // Parsed by the handler rather than here, so a beacon of a version this
       // server does not know is ignored instead of refused.
       req: {
-        body: z.unknown()
+        body: z.unknown(),
+        // What a server that forwards beacons to Val's ingest has to check
+        // and pass on itself: a forward loses the browser's own headers. The
+        // visitor's IP is deliberately not one of them.
+        headers: {
+          "sec-fetch-site": z.string().optional(),
+          "user-agent": z.string().optional(),
+          "x-vercel-ip-country": z.string().optional(),
+          "cf-ipcountry": z.string().optional(),
+          "cloudfront-viewer-country": z.string().optional()
+        }
       },
       res: z.union([
-      // `counted` is false wherever nothing stores the counts -- every
-      // server but the hosted platform's, for now.
+      // `counted` is true only where the beacon was handed to Val's ingest
+      // and it counted it: the hosted platform, or a self-hosted server in
+      // http mode. False everywhere else, local dev included.
       z.object({
         status: z.literal(200),
         json: z.object({
@@ -1726,6 +1771,12 @@ var Api = {
       }), z.object({
         status: z.literal(400),
         json: GenericError
+      }),
+      // Analytics is switched off for this project in Val's admin. The
+      // browser script stops sending when it sees this.
+      z.object({
+        status: z.literal(410),
+        json: GenericError
       })])
     }
   },
@@ -2394,6 +2445,124 @@ var Api = {
       })
     }
   },
+  /**
+   * 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: onlyOneStringQueryParam.optional(),
+          /** Only those about this page. */
+          page: onlyOneStringQueryParam.optional()
+        },
+        cookies: {
+          val_session: z.string().optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, z.object({
+        status: z.literal(400),
+        json: GenericError
+      }), z.object({
+        status: z.literal(500),
+        json: GenericError
+      }), z.object({
+        status: z.literal(200),
+        json: z.object({
+          sketchpads: z.array(SketchpadSummary)
+        })
+      })])
+    },
+    POST: {
+      req: {
+        body: z.object({
+          text: z.string(),
+          page: z.string().nullable()
+        }),
+        cookies: {
+          val_session: z.string().optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, z.object({
+        status: z.literal(400),
+        json: z.object({
+          message: z.string(),
+          /** Lines of the text that are not in the sketch format. */
+          errors: z.array(SketchErrorZ).optional()
+        })
+      }), z.object({
+        status: z.literal(500),
+        json: GenericError
+      }), z.object({
+        status: z.literal(201),
+        json: z.object({
+          sketchpad: Sketchpad
+        })
+      })])
+    }
+  },
+  /** One sketchpad: read it, or change its text, its page or whether it is archived. */
+  "/sketchpad": {
+    GET: {
+      req: {
+        query: {
+          id: onlyOneStringQueryParam
+        },
+        cookies: {
+          val_session: z.string().optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, notFoundResponse, z.object({
+        status: z.literal(500),
+        json: GenericError
+      }), z.object({
+        status: z.literal(200),
+        json: z.object({
+          sketchpad: Sketchpad
+        })
+      })])
+    },
+    PATCH: {
+      req: {
+        body: z.object({
+          id: z.string(),
+          /** The version this change was made against. */
+          baseVersion: z.number()["int"](),
+          text: z.string().optional(),
+          page: z.string().nullable().optional(),
+          archived: z["boolean"]().optional()
+        }),
+        cookies: {
+          val_session: z.string().optional()
+        }
+      },
+      res: z.union([unauthorizedResponse, notFoundResponse, z.object({
+        status: z.literal(400),
+        json: z.object({
+          message: z.string(),
+          errors: z.array(SketchErrorZ).optional()
+        })
+      }), /** Changed since `baseVersion`: here is how it is now. */
+      z.object({
+        status: z.literal(409),
+        json: z.object({
+          message: z.string(),
+          sketchpad: Sketchpad
+        })
+      }), z.object({
+        status: z.literal(500),
+        json: GenericError
+      }), z.object({
+        status: z.literal(200),
+        json: z.object({
+          sketchpad: Sketchpad
+        })
+      })])
+    }
+  },
   "/upload/patches": {
     POST: {
       req: {
@@ -5363,6 +5532,7 @@ function resolveSchemaSourceFixes(validationErrors, snapshot) {
  * in most projects, and for every project that has not declared any languages.
  */
 function localeAt(path, snapshot) {
+  var _localeScopeAt$locale, _localeScopeAt;
   var available = declaredLocales(snapshot);
   if (available.length === 0) {
     // Nothing can be one of no languages. Answering `null` rather than reading
@@ -5371,18 +5541,66 @@ function localeAt(path, snapshot) {
     return null;
   }
   var _Internal$splitModule = Internal.splitModuleFilePathAndModulePath(path),
-    _Internal$splitModule2 = _slicedToArray(_Internal$splitModule, 2),
-    moduleFilePath = _Internal$splitModule2[0],
-    modulePath = _Internal$splitModule2[1];
+    _Internal$splitModule2 = _slicedToArray(_Internal$splitModule, 1),
+    moduleFilePath = _Internal$splitModule2[0];
   var schema = snapshot.schemas[moduleFilePath];
   var source = snapshot.sources[moduleFilePath];
   if (schema === undefined || source === undefined) {
     return null;
   }
+  return (_localeScopeAt$locale = (_localeScopeAt = localeScopeAt(path, schema, source, available)) === null || _localeScopeAt === void 0 ? void 0 : _localeScopeAt.locale) !== null && _localeScopeAt$locale !== void 0 ? _localeScopeAt$locale : 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`.
+ */
+
+/**
+ * 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.
+ */
+function localeScopeAt(path, schema, source, available) {
+  if (available.length === 0) {
+    return null;
+  }
+  var _Internal$splitModule3 = Internal.splitModuleFilePathAndModulePath(path),
+    _Internal$splitModule4 = _slicedToArray(_Internal$splitModule3, 2),
+    moduleFilePath = _Internal$splitModule4[0],
+    modulePath = _Internal$splitModule4[1];
   var segments = modulePath ? Internal.splitModulePath(modulePath) : [];
   return walk(schema, source, segments, available, moduleFilePath);
 }
 
+/**
+ * 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.
+ */
+function localeOfModuleRoot(schema, source, available) {
+  if (available.length === 0) {
+    return null;
+  }
+  return enter(schema, source, available).locale;
+}
+
 /**
  * The language a locale schema's value MEANS, or `null` if it means none of
  * the project's.
@@ -5428,11 +5646,32 @@ function isLocaleSchema(schema) {
   return schema.type === "locale" || schema.type === "enum" && schema.locales !== undefined;
 }
 
+/**
+ * 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)`).
+ */
+function hasLocaleRouteParam(schema) {
+  return schema.type === "record" && schema.params !== undefined && Object.values(schema.params).some(isLocaleSchema);
+}
+
 /**
  * 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.
  */
 function localeOfRouteKey(schema, moduleFilePath, key, available) {
+  var param = localeParamOfRouteKey(schema, moduleFilePath, key);
+  return param === null ? null : localeMeantBy(param.schema, param.value, available);
+}
+
+/**
+ * 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.
+ */
+function localeParamOfRouteKey(schema, moduleFilePath, key) {
   if (schema.params === undefined || schema.router === undefined) {
     return null;
   }
@@ -5449,7 +5688,12 @@ function localeOfRouteKey(schema, moduleFilePath, key, available) {
       name = _Object$entries$_i[0],
       param = _Object$entries$_i[1];
     if (isLocaleSchema(param) && Object.prototype.hasOwnProperty.call(values, name)) {
-      return localeMeantBy(param, values[name], available);
+      return {
+        name: name,
+        schema: param,
+        value: values[name],
+        values: values
+      };
     }
   }
   return null;
@@ -5469,16 +5713,22 @@ function localeOfRouteKey(schema, moduleFilePath, key, available) {
  */
 function walk(schema, source, segments, available, moduleFilePath) {
   var entered = enter(schema, source, available);
-  var locale = entered.locale;
+  var scope = entered.locale === null ? null : {
+    kind: "field",
+    locale: entered.locale,
+    depth: 0
+  };
   var currentSchema = entered.schema;
   var currentSource = source;
-  var _iterator = _createForOfIteratorHelper(segments),
+  var _iterator = _createForOfIteratorHelper(segments.entries()),
     _step;
   try {
     for (_iterator.s(); !(_step = _iterator.n()).done;) {
-      var segment = _step.value;
+      var _step$value = _slicedToArray(_step.value, 2),
+        index = _step$value[0],
+        segment = _step$value[1];
       if (currentSchema === undefined) {
-        return locale;
+        return scope;
       }
       if (currentSchema.type === "record") {
         if (currentSchema.key !== undefined && isLocaleSchema(currentSchema.key)) {
@@ -5487,14 +5737,24 @@ function walk(schema, source, segments, available, moduleFilePath) {
           // the tag it stands for when the key is an enum with `.locales()`.
           var resolved = localeMeantBy(currentSchema.key, segment, available);
           if (resolved !== null) {
-            locale = resolved;
+            scope = {
+              kind: "record-key",
+              locale: resolved,
+              depth: index,
+              keySchema: currentSchema.key
+            };
           }
         } else if (currentSchema.params !== undefined) {
           // A router whose URL names the language: the key is a URL, and one of
           // its parameters is the answer.
           var _resolved = localeOfRouteKey(currentSchema, moduleFilePath, segment, available);
           if (_resolved !== null) {
-            locale = _resolved;
+            scope = {
+              kind: "route-key",
+              locale: _resolved,
+              depth: index,
+              router: currentSchema
+            };
           }
         }
         currentSchema = currentSchema.item;
@@ -5504,13 +5764,17 @@ function walk(schema, source, segments, available, moduleFilePath) {
         currentSchema = currentSchema.items[segment];
       } else {
         // A leaf, or richtext's internal structure. Nothing below opens a scope.
-        return locale;
+        return scope;
       }
       currentSource = childSource(currentSource, segment);
       entered = enter(currentSchema, currentSource, available);
       currentSchema = entered.schema;
       if (entered.locale !== null) {
-        locale = entered.locale;
+        scope = {
+          kind: "field",
+          locale: entered.locale,
+          depth: index + 1
+        };
       }
     }
   } catch (err) {
@@ -5518,7 +5782,7 @@ function walk(schema, source, segments, available, moduleFilePath) {
   } finally {
     _iterator.f();
   }
-  return locale;
+  return scope;
 }
 
 /**
@@ -5608,6 +5872,187 @@ function isJsonObject(source) {
   return _typeof(source) === "object" && source !== null && !Array.isArray(source);
 }
 
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+function relocateForLocale(path, locale, schema, source, available) {
+  var scope = localeScopeAt(path, schema, source, available);
+  if (scope === null || scope.locale === locale) {
+    return {
+      type: "stay"
+    };
+  }
+  var _Internal$splitModule = Internal.splitModuleFilePathAndModulePath(path),
+    _Internal$splitModule2 = _slicedToArray(_Internal$splitModule, 2),
+    moduleFilePath = _Internal$splitModule2[0],
+    modulePath = _Internal$splitModule2[1];
+  var segments = modulePath ? Internal.splitModulePath(modulePath) : [];
+  var at = function at(parts) {
+    return Internal.joinModuleFilePathAndModulePath(moduleFilePath, Internal.patchPathToModulePath(parts));
+  };
+  var prefix = segments.slice(0, scope.depth);
+  var rest = segments.slice(scope.depth + 1);
+  if (scope.kind === "record-key") {
+    var record = sourceAt(source, prefix);
+    var key = isJsonObject(record) ? Object.keys(record).find(function (candidate) {
+      return localeMeantBy(scope.keySchema, candidate, available) === locale;
+    }) : undefined;
+    if (key !== undefined) {
+      return {
+        type: "path",
+        path: at(existingPart(source, [].concat(_toConsumableArray(prefix), [key]), rest)),
+        reason: "counterpart"
+      };
+    }
+    return {
+      type: "path",
+      path: at(prefix),
+      reason: "parent"
+    };
+  }
+  if (scope.kind === "route-key") {
+    var router = sourceAt(source, prefix);
+    var current = localeParamOfRouteKey(scope.router, moduleFilePath, segments[scope.depth]);
+    if (isJsonObject(router) && current !== null) {
+      var _key = Object.keys(router).find(function (candidate) {
+        var other = localeParamOfRouteKey(scope.router, moduleFilePath, candidate);
+        return other !== null && localeMeantBy(other.schema, other.value, available) === locale && sameRouteExcept(current.values, other.values, current.name);
+      });
+      if (_key !== undefined) {
+        return {
+          type: "path",
+          path: at(existingPart(source, [].concat(_toConsumableArray(prefix), [_key]), rest)),
+          reason: "counterpart"
+        };
+      }
+    }
+    return {
+      type: "home"
+    };
+  }
+
+  // A locale FIELD opened the scope, on the node `depth` segments down.
+  if (scope.depth === 0) {
+    return {
+      type: "home"
+    };
+  }
+  var parent = segments.slice(0, scope.depth - 1);
+  if (parent.length === 0 && schema.type === "record" && schema.router !== undefined) {
+    return {
+      type: "home"
+    };
+  }
+  return {
+    type: "path",
+    path: at(parent),
+    reason: "parent"
+  };
+}
+
+/** The source at `parts` below `source`, or `null` where it runs out. */
+function sourceAt(source, parts) {
+  var current = source;
+  var _iterator = _createForOfIteratorHelper(parts),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var part = _step.value;
+      current = childSource(current, part);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return current;
+}
+
+/**
+ * `base`, followed by as much of `rest` as the source still has.
+ *
+ * The counterpart of a field is the same field in the other language's entry,
+ * but that entry can be `null` — declared and not yet written — or shorter (a
+ * list with fewer items). Landing on the entry then is the right answer: it is
+ * the translation the editor is about to write.
+ */
+function existingPart(source, base, rest) {
+  var parts = _toConsumableArray(base);
+  var current = sourceAt(source, base);
+  var _iterator2 = _createForOfIteratorHelper(rest),
+    _step2;
+  try {
+    for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+      var part = _step2.value;
+      var next = childSource(current, part);
+      if (next === null) {
+        break;
+      }
+      parts.push(part);
+      current = next;
+    }
+  } catch (err) {
+    _iterator2.e(err);
+  } finally {
+    _iterator2.f();
+  }
+  return parts;
+}
+
+/** Whether two routes' parameters agree on everything but `ignore`. */
+function sameRouteExcept(a, b, ignore) {
+  var names = new Set([].concat(_toConsumableArray(Object.keys(a)), _toConsumableArray(Object.keys(b))));
+  var _iterator3 = _createForOfIteratorHelper(names),
+    _step3;
+  try {
+    for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+      var _a$name, _b$name;
+      var name = _step3.value;
+      if (name !== ignore && ((_a$name = a[name]) !== null && _a$name !== void 0 ? _a$name : null) !== ((_b$name = b[name]) !== null && _b$name !== void 0 ? _b$name : null)) {
+        return false;
+      }
+    }
+  } catch (err) {
+    _iterator3.e(err);
+  } finally {
+    _iterator3.f();
+  }
+  return true;
+}
+
 /**
  * Local `yyyy-MM-dd`, which is the one thing this module used `date-fns` for.
  *
@@ -5785,7 +6230,383 @@ function emptyRecord(schema, context) {
   }));
 }
 
-var toolNames = ["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"];
+var toolNames = ["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"];
+
+/**
+ * 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.
+ */
+
+var CONTAINER = /^(row|col)(?:\s+(\d+))?$/;
+var PLACEHOLDER = /^\[([^\]:]*)(?::([^\]]*))?\](?:\((image|video):\s*([^\s)]+)\s*\))?$/;
+var HAS_MEDIA = /^\[[^\]]*\]\(/;
+var ICON = /^icon\s+(\S+)\s+([Mm][\d\s.-].*)$/;
+var PATH_DATA = /^[Mm][MmLlHhVvCcSsQqTtAaZz\d\s.,-]*$/;
+var HEADING = /^(#{1,3})\s+(.*)$/;
+function parseSketch(source) {
+  var blocks = [];
+  var errors = [];
+  var icons = {};
+  // The containers that are open at the current line, innermost last.
+  var stack = [{
+    type: "page",
+    indent: -1,
+    children: blocks,
+    lastIndent: null
+  }];
+  source.split(/\r?\n/).forEach(function (raw, index) {
+    var line = index + 1;
+    var expanded = raw.replace(/\t/g, "  ");
+    var content = expanded.trim();
+    if (content === "") {
+      return;
+    }
+    var indent = expanded.length - expanded.trimStart().length;
+
+    // An icon is not a block, so it can go anywhere and closes nothing.
+    var icon = ICON.exec(content);
+    if (icon) {
+      var path = icon[2].trim();
+      if (PATH_DATA.test(path)) {
+        icons[icon[1].toLowerCase()] = path;
+      } else {
+        errors.push({
+          line: line,
+          message: 'An icon is SVG path data for a 24 by 24 box, like "icon stat M3 17l6-6 4 4 8-8". Only path commands and numbers are allowed.'
+        });
+      }
+      return;
+    }
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+    var parent = stack[stack.length - 1];
+    var node = parseContent(content, line, errors);
+
+    // Indented further than the block above it, and that block is not a
+    // container. Keep it as that block's sibling rather than dropping it.
+    if (parent.lastIndent !== null && indent > parent.lastIndent) {
+      errors.push({
+        line: line,
+        message: "Only row and col can hold other blocks. Indent this as much as the line above it."
+      });
+    } else {
+      parent.lastIndent = indent;
+    }
+    if (node.type === "col" && parent.type !== "row") {
+      errors.push({
+        line: line,
+        message: "A col only goes directly inside a row."
+      });
+    }
+    if (node.type === "row" && parent.type === "row") {
+      errors.push({
+        line: line,
+        message: "A row goes in a col, not directly in another row."
+      });
+    }
+    parent.children.push(node);
+    if (node.type === "row" || node.type === "col") {
+      stack.push({
+        type: node.type,
+        indent: indent,
+        children: node.children,
+        lastIndent: null
+      });
+    }
+  });
+  return {
+    blocks: blocks,
+    icons: icons,
+    errors: errors
+  };
+}
+function parseContent(content, line, errors) {
+  // A leading backslash keeps a line that looks like a keyword as text.
+  if (content.startsWith("\\")) {
+    return {
+      type: "text",
+      line: line,
+      level: 0,
+      text: content.slice(1)
+    };
+  }
+  var container = CONTAINER.exec(content);
+  if (container) {
+    if (container[1] === "row") {
+      if (container[2] !== undefined) {
+        errors.push({
+          line: line,
+          message: "A row takes no number. Put it on a col: \"col ".concat(container[2], "\".")
+        });
+      }
+      return {
+        type: "row",
+        line: line,
+        children: []
+      };
+    }
+    var weight = container[2] === undefined ? 1 : Number(container[2]);
+    if (weight === 0) {
+      errors.push({
+        line: line,
+        message: "A col needs a weight of 1 or more."
+      });
+    }
+    return {
+      type: "col",
+      line: line,
+      weight: Math.max(weight, 1),
+      children: []
+    };
+  }
+  if (content.startsWith("[")) {
+    var placeholder = PLACEHOLDER.exec(content);
+    if (placeholder) {
+      var _placeholder$;
+      var kind = placeholder[1].trim();
+      var label = (_placeholder$ = placeholder[2]) === null || _placeholder$ === void 0 ? void 0 : _placeholder$.trim();
+      if (/\s/.test(kind)) {
+        // An icon line names a kind by one word, so a kind has to be one.
+        errors.push({
+          line: line,
+          message: "A box's kind is one word: \"[".concat(kind.replace(/\s+/g, "-")).concat(label ? ": ".concat(label) : "", "]\".")
+        });
+      }
+      var mediaType = placeholder[3];
+      return {
+        type: "placeholder",
+        line: line,
+        kind: kind === "" ? "block" : kind,
+        label: label ? label : null,
+        media: mediaType === "image" || mediaType === "video" ? {
+          type: mediaType,
+          src: placeholder[4]
+        } : null
+      };
+    }
+    if (HAS_MEDIA.test(content)) {
+      errors.push({
+        line: line,
+        message: 'Media in a box is written after it as (image: url) or (video: url), like "[hero: Team photo](image: /public/val/team.jpg)".'
+      });
+      return {
+        type: "text",
+        line: line,
+        level: 0,
+        text: content
+      };
+    }
+    errors.push({
+      line: line,
+      message: 'A placeholder is written [kind] or [kind: label], on a line of its own, like "[image: Team photo]".'
+    });
+    return {
+      type: "text",
+      line: line,
+      level: 0,
+      text: content
+    };
+  }
+  var heading = HEADING.exec(content);
+  if (heading) {
+    var level = heading[1].length === 1 ? 1 : heading[1].length === 2 ? 2 : 3;
+    return {
+      type: "text",
+      line: line,
+      level: level,
+      text: heading[2]
+    };
+  }
+  return {
+    type: "text",
+    line: line,
+    level: 0,
+    text: content
+  };
+}
+
+/**
+ * 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 `\`.
+ */
+function formatSketchText(level, text) {
+  var flat = text.replace(/\s+/g, " ").trim();
+  if (level > 0) {
+    return "#".repeat(level) + " " + flat;
+  }
+  var ambiguous = flat.startsWith("\\") || flat.startsWith("[") || CONTAINER.test(flat) || HEADING.test(flat) || ICON.test(flat);
+  return ambiguous ? "\\" + flat : flat;
+}
+
+/** The line a placeholder is written as. */
+function formatSketchBox(placeholder) {
+  var clean = function clean(text) {
+    return text.replace(/[[\]]/g, "").replace(/\s+/g, " ").trim();
+  };
+  var kind = clean(placeholder.kind).replace(/:/g, "") || "block";
+  var label = placeholder.label === null ? "" : clean(placeholder.label);
+  var media = placeholder.media ? "(".concat(placeholder.media.type, ": ").concat(placeholder.media.src.replace(/[\s)]/g, encodeURIComponent), ")") : "";
+  return "[".concat(kind).concat(label ? ": ".concat(label) : "", "]").concat(media);
+}
+
+/**
+ * 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.
+ */
+function formatSketch(blocks, icons) {
+  var lines = [];
+  var _walk = function walk(node, depth, inRow) {
+    var indent = "  ".repeat(depth);
+    switch (node.type) {
+      case "text":
+        if (node.text) {
+          lines.push(indent + formatSketchText(node.level, node.text));
+        }
+        return;
+      case "placeholder":
+        lines.push(indent + formatSketchBox(node));
+        return;
+      case "row":
+        lines.push(indent + "row");
+        if (node.children.length === 0) {
+          lines.push(indent + "  col");
+        }
+        node.children.forEach(function (child) {
+          return _walk(child, depth + 1, true);
+        });
+        return;
+      case "col":
+        if (!inRow) {
+          node.children.forEach(function (child) {
+            return _walk(child, depth, false);
+          });
+          return;
+        }
+        lines.push(indent + (node.weight === 1 ? "col" : "col ".concat(node.weight)));
+        node.children.forEach(function (child) {
+          return _walk(child, depth + 1, false);
+        });
+        return;
+    }
+  };
+  blocks.forEach(function (block) {
+    return _walk(block, 0, false);
+  });
+  var iconLines = Object.entries(icons).map(function (_ref) {
+    var _ref2 = _slicedToArray(_ref, 2),
+      kind = _ref2[0],
+      path = _ref2[1];
+    return "icon ".concat(kind, " ").concat(path);
+  });
+  var all = [].concat(lines, _toConsumableArray(iconLines.length > 0 ? [""].concat(_toConsumableArray(iconLines)) : []));
+  return all.length > 0 ? all.join("\n") + "\n" : "";
+}
+
+/**
+ * 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.
+ */
+function sketchTitle(blocks) {
+  var _loop = function _loop() {
+      var level = _arr[_i];
+      var heading = blocks.find(function (block) {
+        return block.type === "text" && block.level === level && block.text !== "";
+      });
+      if (heading) {
+        return {
+          v: heading.text
+        };
+      }
+    },
+    _ret;
+  for (var _i = 0, _arr = [1, 2, 3]; _i < _arr.length; _i++) {
+    _ret = _loop();
+    if (_ret) return _ret.v;
+  }
+  return 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.
+ */
+function checkSketch(source) {
+  var _parseSketch = parseSketch(source),
+    blocks = _parseSketch.blocks,
+    icons = _parseSketch.icons,
+    errors = _parseSketch.errors;
+  if (errors.length > 0) {
+    return errors;
+  }
+  var canonical = formatSketch(blocks, icons);
+  if (canonical === source) {
+    return [];
+  }
+  if (canonical !== "" && !source.endsWith("\n")) {
+    return [{
+      line: source.split("\n").length,
+      message: "A sketch ends with a newline."
+    }];
+  }
+  // Compared without the final newline, so an extra one is an extra line.
+  var given = source.slice(0, -1).split("\n");
+  var wanted = canonical.slice(0, -1).split("\n");
+  for (var i = 0; i < Math.max(given.length, wanted.length); i++) {
+    if (given[i] !== wanted[i]) {
+      return [{
+        line: i + 1,
+        message: wanted[i] === undefined ? "Nothing goes here: the sketch ends on the line before." : given[i] === "" ? "No blank lines: the one blank line in a sketch is before its icons." : given[i] === undefined ? "The sketch goes on: \"".concat(wanted[i], "\".") : "This line is written ".concat(JSON.stringify(wanted[i]), " in a sketch: two spaces per level, the icons last after one blank line, and no other blank lines.")
+      }];
+    }
+  }
+  return [];
+}
 
 function buildFileRefValue(filePath, metadata) {
   return _objectSpread2({
@@ -8726,4 +9547,4 @@ var messageOf = function messageOf(error) {
   return error instanceof Error ? error.message : String(error);
 };
 
-export { AA_LARGE, AA_TEXT, AIToolCallSummaries, AnalyticsBeacon, Api, BRAND_CONTRAST_PAIRS, BinaryFileRef, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, ENCODE_DEFAULTS, ENCODE_MIME_TYPE_OF, FileOptions, HistoricalCommit, HistoricalModule, HistoricalPatchSet, HistoryError, ImageEncodeOption, ImageOptions, JSONValue, JSON_ENTRIES_BATCH_MAX, LOCAL_FILE_IN_REMOTE_PROJECT_HINT, LOCAL_FILE_IN_REMOTE_PROJECT_WARNING, ModuleComparison, NEVER_ENCODED, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchId, PatchJSON, PatchSets, PlanRefusalError, RAMP_STEPS, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RestoreVerdict, RichTextOptions, SCHEMA_SOURCE_FIXES, SELF_CHECK_VERSION, STUDIO_FIXES, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedLocaleSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SerializedValViewSchema, SerializedVideoSchema, SharedValConfig, VAL_ENABLE_COOKIE_NAME, VAL_GREEN_RAMP, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, VAL_STUDIO_HEADER, ValCommit, ValDeployment, VideoOptions, VideoStreamOption, WARNING_FIXES, WASM_ENCODED_MIME_TYPES, accentRamp, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, buildSearchIndex, chainHeadOf, checkCompatibility, chooseEncoded, concatModulePath, contrastRatio, createRegExpFromPattern, createSearchIndex, createValClient, declaredLocales, describeContainerAtPath, emptyOf, enumLocaleTag, explainIncompatible, fallbackMimeType, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, forEachRichTextImage, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getKeyOfRecordAt, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, getValDemo, indexModule, isInsidePatchSetPath, isLocaleSchema, isMimeTypeAccepted, isRemoteSchema, isRepairedOnSave, isSchemaSourceFixError, isSkippedSource, isStudioFix, isValidationWarning, isWarningFix, joinSharedChanges, keyOfRecordPath, levenshtein, localeAt, localeMeantBy, memoizePerRequest, newestCommitSha, partitionValidationErrors, performSearch, proposalCustomProperties, relativeLuminance, remirrorToRichTextSource, removeModule, resolveEncodeSettings, resolvePairGround, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextImageSchema, richTextToRemirror, safeParsePatch, schemaErrorsOf, schemaTypesOfPath, selectionClosure, selfCheck, shouldEncodeWithWasm, sideFiles, sideSource, sourcePathOfChild, themeCustomProperties, toolNames, traverseSchemaSource, urlOf, validateRoutePatterns, withExtension };
+export { AA_LARGE, AA_TEXT, AIToolCallSummaries, AnalyticsBeacon, Api, BRAND_CONTRAST_PAIRS, BinaryFileRef, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, ENCODE_DEFAULTS, ENCODE_MIME_TYPE_OF, FileOptions, HistoricalCommit, HistoricalModule, HistoricalPatchSet, HistoryError, ImageEncodeOption, ImageOptions, JSONValue, JSON_ENTRIES_BATCH_MAX, LOCAL_FILE_IN_REMOTE_PROJECT_HINT, LOCAL_FILE_IN_REMOTE_PROJECT_WARNING, ModuleComparison, NEVER_ENCODED, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchId, PatchJSON, PatchSets, PlanRefusalError, RAMP_STEPS, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RestoreVerdict, RichTextOptions, SCHEMA_SOURCE_FIXES, SELF_CHECK_VERSION, SKETCHPAD_MAX_TEXT_LENGTH, STUDIO_FIXES, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedLocaleSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SerializedValViewSchema, SerializedVideoSchema, SharedValConfig, Sketchpad, SketchpadSummary, VAL_ENABLE_COOKIE_NAME, VAL_GREEN_RAMP, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, VAL_STUDIO_HEADER, ValCommit, ValDeployment, VideoOptions, VideoStreamOption, WARNING_FIXES, WASM_ENCODED_MIME_TYPES, accentRamp, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, buildSearchIndex, chainHeadOf, checkCompatibility, checkSketch, childSource, chooseEncoded, concatModulePath, contrastRatio, createRegExpFromPattern, createSearchIndex, createValClient, declaredLocales, describeContainerAtPath, emptyOf, enumLocaleTag, explainIncompatible, fallbackMimeType, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, forEachRichTextImage, formatSketch, formatSketchBox, formatSketchText, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getKeyOfRecordAt, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, getValDemo, hasLocaleRouteParam, indexModule, isInsidePatchSetPath, isJsonObject, isLocaleSchema, isMimeTypeAccepted, isRemoteSchema, isRepairedOnSave, isSchemaSourceFixError, isSkippedSource, isStudioFix, isValidationWarning, isWarningFix, joinSharedChanges, keyOfRecordPath, levenshtein, localeAt, localeMeantBy, localeOfModuleRoot, localeOfRouteKey, localeParamOfRouteKey, localeScopeAt, memoizePerRequest, newestCommitSha, parseSketch, partitionValidationErrors, performSearch, proposalCustomProperties, relativeLuminance, relocateForLocale, remirrorToRichTextSource, removeModule, resolveEncodeSettings, resolvePairGround, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextImageSchema, richTextToRemirror, safeParsePatch, schemaErrorsOf, schemaTypesOfPath, selectionClosure, selfCheck, shouldEncodeWithWasm, sideFiles, sideSource, sketchTitle, sourcePathOfChild, themeCustomProperties, toolNames, traverseSchemaSource, urlOf, validateRoutePatterns, withExtension };