@valbuild/shared 0.121.0 → 0.123.0

package/internal/dist/valbuild-shared-internal.cjs.prod.js

@@ -6,6 +6,11 @@ var core = require('@valbuild/core');
 var utils = require('../../dist/utils-32bcaca2.cjs.prod.js');
 var zod = require('zod');
 var zodValidationError = require('zod-validation-error');
+var FlexSearch = require('flexsearch');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
+
+var FlexSearch__default = /*#__PURE__*/_interopDefault(FlexSearch);
 
 function _toPrimitive(t, r) {
   if ("object" != typeof t || !t) return t;
@@ -901,6 +906,12 @@ function _asyncToGenerator(n) {
   };
 }
 
+/**
+ * JSON, recursively — the shape of a Source over the wire.
+ *
+ * Exported because history reads stored Sources back and needs the same
+ * definition; a second copy is a second thing to keep in step.
+ */
 var JSONValue = zod.z.lazy(function () {
   return zod.z.union([zod.z.string(), zod.z.number(), zod.z["boolean"](), zod.z["null"](), zod.z.array(JSONValue), zod.z.record(zod.z.string(), JSONValue)]);
 });
@@ -1279,7 +1290,26 @@ var SerializedRouteSchema = zod.z.object({
   readonly: zod.z["boolean"]().optional(),
   hidden: zod.z["boolean"]().optional()
 });
-var SerializedSchema = zod.z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedColorSchema, SerializedCodeSchema, SerializedImageSchema]);
+
+// A settings module, and each section inside one, serialize as this - the
+// shape is recursive because `items` holds sections which are themselves
+// settings schemas. `s.settings()` never writes render/preview/customValidate
+// (see core/src/schema/settings.ts), but they are accepted here because they
+// are part of the declared type.
+var SerializedSettingsSchema = zod.z.lazy(function () {
+  return zod.z.object({
+    type: zod.z.literal("settings"),
+    render: FieldRender,
+    preview: zod.z.literal(true).optional(),
+    items: zod.z.record(zod.z.string(), SerializedSchema),
+    opt: zod.z["boolean"](),
+    customValidate: zod.z["boolean"]().optional(),
+    readonly: zod.z["boolean"]().optional(),
+    hidden: zod.z["boolean"]().optional(),
+    description: zod.z.string().optional()
+  });
+});
+var SerializedSchema = zod.z.union([SerializedStringSchema, SerializedLiteralSchema, SerializedBooleanSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedArraySchema, SerializedUnionSchema, SerializedRichTextSchema, SerializedRecordSchema, SerializedKeyOfSchema, SerializedRouteSchema, SerializedFileSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedColorSchema, SerializedCodeSchema, SerializedSettingsSchema, SerializedImageSchema]);
 
 var ValCommit = zod.z.object({
   commitSha: zod.z.string(),
@@ -1291,6 +1321,125 @@ var ValCommit = zod.z.object({
   commitMessage: zod.z.string().nullable()
 });
 
+/**
+ * The wire shapes for reading history.
+ *
+ * Here rather than in `@valbuild/server` because both sides of `/api/val` need
+ * them: the server builds these and the Studio parses them, and a second
+ * hand-written copy in the client is how the two drift.
+ *
+ * `HistoryError` is a closed union of everything that can go wrong
+ * reconstructing a commit - see `packages/server/src/history/HistoryError.ts`
+ * for what each one means. It travels as data rather than as a message because
+ * the Studio decides what to OFFER from it: a schema mismatch means "cannot
+ * restore this field", a missing source means "cannot restore this module at
+ * all", and a rendered string cannot be told apart.
+ */
+var HistoryError = zod.z.discriminatedUnion("kind", [zod.z.object({
+  kind: zod.z.literal("commit-not-found"),
+  commitSha: zod.z.string()
+}), zod.z.object({
+  kind: zod.z.literal("archive-unreadable"),
+  commitSha: zod.z.string(),
+  message: zod.z.string()
+}), zod.z.object({
+  kind: zod.z.literal("source-unavailable"),
+  moduleFilePath: zod.z.string()
+}), zod.z.object({
+  kind: zod.z.literal("schema-unreadable"),
+  moduleFilePath: zod.z.string(),
+  message: zod.z.string()
+}), zod.z.object({
+  kind: zod.z.literal("file-unavailable"),
+  gitPath: zod.z.string(),
+  message: zod.z.string()
+}), zod.z.object({
+  kind: zod.z.literal("not-supported-in-fs-mode")
+}), zod.z.object({
+  kind: zod.z.literal("transport"),
+  message: zod.z.string()
+})]);
+var HistoricalCommit = zod.z.object({
+  commitSha: zod.z.string(),
+  parentCommitSha: zod.z.string(),
+  clientCommitSha: zod.z.string(),
+  branch: zod.z.string(),
+  createdBranch: zod.z.string().nullable(),
+  creator: zod.z.string().nullable(),
+  message: zod.z.string().nullable(),
+  createdAt: zod.z.string(),
+  seqNum: zod.z.string(),
+  patchCount: zod.z.number(),
+  /** False for commits made before history was recorded. */
+  hasArchive: zod.z["boolean"]()
+});
+var FileChange = zod.z.union([zod.z.literal("added"), zod.z.literal("modified"), zod.z.literal("deleted")]);
+
+/**
+ * A binary file the commit touched - named, with a URL, and nothing fetched.
+ * Only an `<img src>` that mounts pays for the bytes.
+ */
+var BinaryFileRef = zod.z.object({
+  gitPath: zod.z.string(),
+  change: FileChange,
+  remote: zod.z["boolean"](),
+  url: zod.z.string()
+});
+var HistoricalModule = zod.z.object({
+  /** The module's data at this commit. Null if deleted, or unreadable. */
+  source: JSONValue.nullable(),
+  /**
+   * The schema at this commit, already validated against THIS Val.
+   *
+   * Null with a `schema-unreadable` failure means the stored schema came from a
+   * Val whose schema format this one does not know — expected, not damage.
+   */
+  schema: SerializedSchema.nullable(),
+  patchIds: zod.z.array(PatchId),
+  changedPaths: zod.z.array(zod.z.string()),
+  failures: zod.z.array(HistoryError)
+});
+var HistoricalPatchSet = zod.z.object({
+  commit: HistoricalCommit,
+  modules: zod.z.record(zod.z.string(), HistoricalModule),
+  patches: zod.z.array(zod.z.object({
+    patchId: PatchId,
+    moduleFilePath: zod.z.string(),
+    patch: zod.z.unknown(),
+    authorId: zod.z.string().nullable(),
+    createdAt: zod.z.string(),
+    baseSha: zod.z.string(),
+    coreVersion: zod.z.string()
+  })),
+  jsonEntries: zod.z.record(zod.z.string(), zod.z.unknown()),
+  binaryFiles: zod.z.array(BinaryFileRef),
+  warnings: zod.z.array(HistoryError)
+});
+/**
+ * Whether the historical value can be written back as the project stands.
+ *
+ * Computed in the Studio, not on the server: the verdict depends on the current
+ * source and the current schema, both of which the client already holds, and it
+ * runs against the same worker-thread validator that validates ordinary edits.
+ * The types stay here because they are what a restore preview hands to the UI.
+ *
+ * `blocked` carries its reasons so a refusal can name the field and say why,
+ * rather than being an unexplained disabled button.
+ */
+var RestoreVerdict = zod.z.union([zod.z.object({
+  status: zod.z.literal("restorable")
+}), zod.z.object({
+  status: zod.z.literal("blocked"),
+  reasons: zod.z.array(HistoryError)
+})]);
+var ModuleComparison = zod.z.object({
+  current: zod.z.unknown().nullable(),
+  /** Paths where the commit's result and the current source differ: what a
+   * restore would undo. */
+  changedVsCurrent: zod.z.array(zod.z.string()),
+  verdict: RestoreVerdict
+});
+
 var ModuleFilePath = zod.z.string().refine(function (_path) {
   return true;
 } // TODO: validation
@@ -1560,48 +1709,6 @@ var Api = {
       })
     }
   },
-  "/session": {
-    GET: {
-      req: {
-        cookies: {
-          val_session: zod.z.string().optional()
-        }
-      },
-      res: zod.z.union([zod.z.object({
-        status: zod.z.literal(200),
-        json: zod.z.object({
-          mode: zod.z.union([zod.z.literal("local"), zod.z.literal("proxy")]),
-          enabled: zod.z["boolean"]()
-        })
-      }), zod.z.object({
-        status: zod.z.union([
-        // TODO: Remove the ones we don't need.
-        zod.z.literal(400), zod.z.literal(401), zod.z.literal(403), zod.z.literal(404), zod.z.literal(500), zod.z.literal(501)]),
-        json: zod.z.object({
-          message: zod.z.string()
-        })
-      }), zod.z.object({
-        status: zod.z.literal(401),
-        json: zod.z.object({
-          message: zod.z.string(),
-          details: zod.z.union([zod.z.string(), zod.z.object({
-            reason: zod.z.string()
-          }), zod.z.object({
-            sub: zod.z.string(),
-            exp: zod.z.number(),
-            token: zod.z.string(),
-            org: zod.z.string(),
-            project: zod.z.string()
-          })])
-        })
-      }), zod.z.object({
-        status: zod.z.literal(500),
-        json: zod.z.object({
-          message: zod.z.string()
-        })
-      })])
-    }
-  },
   "/logout": {
     GET: {
       req: {
@@ -2393,6 +2500,144 @@ var Api = {
       })])
     }
   },
+  // #region history
+  //
+  // Reading the past. Split across three routes on purpose, because they cache
+  // differently: a reconstructed commit cannot change and is immutable
+  // forever, the comparison against current source changes with every edit, and
+  // a file at a fixed commit is immutable too. Folding them together would mean
+  // the cheapest thing dragging the most expensive one's cache headers down to
+  // no-store.
+  "/history/commits": {
+    GET: {
+      req: {
+        query: {
+          branch: onlyOneStringQueryParam,
+          limit: onlyOneIntQueryParam.optional(),
+          /** The previous page's `nextCursor`. */
+          cursor: onlyOneStringQueryParam.optional()
+        },
+        cookies: {
+          val_session: zod.z.string().optional()
+        }
+      },
+      res: zod.z.union([unauthorizedResponse, notFoundResponse, zod.z.object({
+        status: zod.z.literal(400),
+        json: GenericError.and(zod.z.object({
+          kind: zod.z.string().optional()
+        }))
+      }), zod.z.object({
+        status: zod.z.literal(500),
+        json: GenericError.and(zod.z.object({
+          kind: zod.z.string().optional()
+        }))
+      }), zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          commits: zod.z.array(HistoricalCommit),
+          nextCursor: zod.z.string().nullable()
+        })
+      })])
+    }
+  },
+  /**
+   * One commit, reconstructed. IMMUTABLE for a given sha - it says nothing
+   * about the current source or schema, which is what lets it be cached
+   * forever and what makes comparing many commits cheap.
+   */
+  "/history/commit": {
+    GET: {
+      req: {
+        query: {
+          commit_sha: onlyOneStringQueryParam
+        },
+        cookies: {
+          val_session: zod.z.string().optional()
+        }
+      },
+      res: zod.z.union([unauthorizedResponse, notFoundResponse, zod.z.object({
+        status: zod.z.literal(400),
+        json: GenericError
+      }), zod.z.object({
+        status: zod.z.literal(500),
+        json: GenericError.and(zod.z.object({
+          kind: zod.z.string().optional()
+        }))
+      }), zod.z.object({
+        status: zod.z.literal(200),
+        json: HistoricalPatchSet
+      })])
+    }
+  },
+  /**
+   * ONE module, as of a commit — including a commit that did not change it.
+   *
+   * `/history/commit` covers what a commit changed, which is the narrow case:
+   * navigate the history pane to anything else and there would be nothing to
+   * show. This answers "how did this module look at that point", which is the
+   * question someone comparing two panes is actually asking. Immutable for the
+   * same reason: what a commit left behind cannot change.
+   */
+  "/history/module": {
+    GET: {
+      req: {
+        query: {
+          commit_sha: onlyOneStringQueryParam,
+          module_file_path: onlyOneStringQueryParam
+        },
+        cookies: {
+          val_session: zod.z.string().optional()
+        }
+      },
+      res: zod.z.union([unauthorizedResponse, notFoundResponse, zod.z.object({
+        status: zod.z.literal(400),
+        json: GenericError
+      }), zod.z.object({
+        status: zod.z.literal(500),
+        json: GenericError.and(zod.z.object({
+          kind: zod.z.string().optional()
+        }))
+      }), zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          moduleFilePath: zod.z.string(),
+          /**
+           * Null when history has no record of this module at or before the
+           * commit — it was last edited before recording started, or never.
+           * Distinct from a module the commit deleted.
+           */
+          module: HistoricalModule.nullable()
+        })
+      })])
+    }
+  },
+  /**
+   * One file as it was at one commit.
+   *
+   * The lazy half: `/history/commit` NAMES a commit's binary files and this is
+   * where their bytes come from, so nothing is fetched until an `<img>`
+   * actually mounts. A file at a fixed commit cannot change, so the response is
+   * immutable and the browser's own cache handles flipping between commits.
+   */
+  "/history/files": {
+    GET: {
+      req: {
+        query: {
+          commit_sha: onlyOneStringQueryParam,
+          path: onlyOneStringQueryParam,
+          remote: onlyOneStringQueryParam.optional()
+        }
+      },
+      res: zod.z.union([unauthorizedResponse, notFoundResponse, zod.z.object({
+        status: zod.z.literal(400),
+        json: GenericError
+      }), zod.z.object({
+        status: zod.z.literal(200),
+        body: zod.z["instanceof"](ReadableStream)
+      })])
+    }
+  },
+  // #endregion history
   "/files": {
     GET: {
       req: {
@@ -3030,96 +3275,444 @@ var urlOf = function urlOf() {
 };
 
 /**
- * The newest commit the client has been told about, or `null` if none.
- *
- * This is the **publish head**: unlike `baseSha`, which only moves once a
- * deployment lands, it moves the instant somebody publishes. That makes it the
- * one thing a client can carry to `/save` to say "this is the world I decided
- * against" — and the only way the server can tell that somebody else has
- * published since the review screen was read.
+ * Can this value, taken from one schema, be written into another?
  *
- * In `shared` because both sides need the SAME answer: the client names a head
- * and the server compares against one, so two implementations of "newest" is two
- * ways to disagree about whether a publish is stale.
+ * The question restore asks, and it is NOT the question validation asks.
+ * Validation checks a value against the schema it belongs to. This compares two
+ * schemas — the one a value was stored under and the one it is being written
+ * into — because a restore moves a value across a schema change, and possibly
+ * across paths.
  *
- * By `createdAt` rather than by position, because the list's order is the
- * content API's business and nothing here should depend on it. Ties keep the
- * first seen, which is arbitrary and does not matter: two commits sharing a
- * timestamp are equally "since", and either answer refuses the same publishes.
+ * Three answers, not two. `unknown` is where the comparison genuinely cannot
+ * decide, and it exists so that an editor is told "we are not sure" rather than
+ * being given a confident answer we made up. Treating unknown as compatible
+ * writes values that break; treating it as incompatible blocks restores that
+ * would have been fine.
  */
-function newestCommitSha(commits) {
-  var _newest$commitSha, _newest;
-  var newest = null;
-  var _iterator = _createForOfIteratorHelper(commits !== null && commits !== void 0 ? commits : []),
-    _step;
-  try {
-    for (_iterator.s(); !(_step = _iterator.n()).done;) {
-      var commit = _step.value;
-      if (newest === null || commit.createdAt > newest.createdAt) {
-        newest = commit;
-      }
-    }
-  } catch (err) {
-    _iterator.e(err);
-  } finally {
-    _iterator.f();
-  }
-  return (_newest$commitSha = (_newest = newest) === null || _newest === void 0 ? void 0 : _newest.commitSha) !== null && _newest$commitSha !== void 0 ? _newest$commitSha : null;
-}
 
-var VAL_CONFIG_SESSION_STORAGE_KEY = "val-config";
-var VAL_THEME_SESSION_STORAGE_KEY = "val-theme";
-var VAL_AI_SESSION_STORAGE_KEY = "val-ai-session";
+var compatible = {
+  status: "compatible"
+};
 
-var SharedValConfig = zod.z.object({
-  contentHostUrl: zod.z.string().optional(),
-  appHostUrl: zod.z.string().optional(),
-  project: zod.z.string().optional(),
-  root: zod.z.string().optional(),
-  gitCommit: zod.z.string().optional(),
-  gitBranch: zod.z.string().optional(),
-  defaultTheme: zod.z["enum"](["dark", "light"]).optional(),
-  ai: zod.z.object({
-    commitMessages: zod.z.object({
-      disabled: zod.z["boolean"]().optional()
-    }).optional()
-  }).optional()
-});
+/**
+ * `Array.isArray` cannot narrow `JsonArray` out of `Json`, because it is
+ * `readonly Json[]` — so the check that reads naturally does not type. This
+ * predicate is that check, said once.
+ */
+function isJsonObject(value) {
+  return _typeof(value) === "object" && value !== null && !Array.isArray(value);
+}
+function incompatible(reason) {
+  return {
+    status: "incompatible",
+    reason: reason
+  };
+}
 
 /**
- * Config that is shared between the client and server.
+ * "an object", "a string".
+ *
+ * Schema type names are data — `object`, `array`, `image` — so an interpolated
+ * "a" is wrong for three of them, in a sentence shown to editors the moment a
+ * restore is refused.
  */
+function withArticle(type) {
+  return /^[aeiou]/i.test(type) ? "an ".concat(type) : "a ".concat(type);
+}
 
-var ValDeployment = zod.z.object({
-  deploymentId: zod.z.string(),
-  deploymentState: zod.z.string(),
-  commitSha: zod.z.string(),
-  updatedAt: zod.z.string(),
-  createdAt: zod.z.string()
-});
+/**
+ * A sentence an editor can act on, for the popup that explains a refusal.
+ *
+ * Kept beside the reasons rather than in the UI so that adding a reason without
+ * wording for it is a type error rather than a blank dialog.
+ */
+function explainIncompatible(reason) {
+  switch (reason.kind) {
+    case "type-changed":
+      return "This was ".concat(withArticle(reason.from), " and the field here is ").concat(withArticle(reason.to), ".");
+    case "no-matching-variant":
+      return "This does not match any of the shapes allowed here: ".concat(reason.variants.join(", "), ".");
+    case "unknown-field":
+      return "The old value has ".concat(reason.keys.length === 1 ? "a field" : "fields", " that no longer exist here: ").concat(reason.keys.join(", "), ".");
+    case "missing-required":
+      return "The field here needs ".concat(reason.keys.join(", "), ", which the old value does not have.");
+    case "not-optional":
+      return "The old value was empty, and this field cannot be empty.";
+    case "literal-changed":
+      return "This has to be exactly \"".concat(reason.to, "\", and the old value was \"").concat(reason.from, "\".");
+    case "different-module":
+      return "This points into ".concat(reason.to, ", and the old value pointed into ").concat(reason.from, ".");
+  }
+}
 
-// Strictly speaking this should be in the next package but it's shared, because we want to use it in the ui package. We want to resolve that somehow
-function getNextAppRouterSitemapTree(srcFolder, paths) {
-  var root = {
-    type: "node",
-    name: "/",
-    children: []
-  };
-  var _iterator = _createForOfIteratorHelper(paths),
-    _step;
-  try {
-    var _loop = function _loop() {
-        var path = _step.value;
-        var urlPath = path.urlPath,
-          moduleFilePathS = path.moduleFilePath;
-        var moduleFilePath = moduleFilePathS;
-        if (!urlPath.startsWith("/")) {
-          console.error("urlPath must start with /: ".concat(urlPath));
-          return 0; // continue
-        }
-        var pattern = getPatternFromModuleFilePath(moduleFilePath, srcFolder);
-        if (urlPath === "/") {
-          var fullPath = "/";
+/**
+ * The variant of a union that a value actually is.
+ *
+ * `undefined` when the value does not identify itself — which is a real answer,
+ * not a failure: it is what makes the caller return `unknown` rather than guess.
+ */
+function variantOf(schema, value) {
+  if (schema.type !== "union") {
+    return undefined;
+  }
+  // String union: the value IS the discriminator.
+  if (typeof schema.key !== "string") {
+    if (typeof value !== "string") {
+      return undefined;
+    }
+    return schema.items.find(function (item) {
+      return item.type === "literal" && item.value === value;
+    });
+  }
+  // Object union: the discriminator is a literal at `key`.
+  var discriminator = schema.key;
+  if (!isJsonObject(value)) {
+    return undefined;
+  }
+  var tag = value[discriminator];
+  if (typeof tag !== "string") {
+    return undefined;
+  }
+  return schema.items.find(function (item) {
+    if (item.type !== "object") {
+      return false;
+    }
+    var keySchema = item.items[discriminator];
+    return (keySchema === null || keySchema === void 0 ? void 0 : keySchema.type) === "literal" && keySchema.value === tag;
+  });
+}
+function describeVariant(schema, key) {
+  if (schema.type === "literal") {
+    return schema.value;
+  }
+  if (schema.type === "object") {
+    var tag = schema.items[key];
+    if ((tag === null || tag === void 0 ? void 0 : tag.type) === "literal") {
+      return tag.value;
+    }
+  }
+  return schema.type;
+}
+function checkCompatibility(from, to) {
+  // Emptiness first: a null that lands in a field which cannot be empty is a
+  // break regardless of what the two schemas otherwise say.
+  if (from.value === null) {
+    return to.schema.opt ? compatible : incompatible({
+      kind: "not-optional"
+    });
+  }
+
+  // A changed union is not itself disqualifying. What matters is whether the
+  // variant being restored still has somewhere to go — comparing the unions
+  // wholesale would refuse a restore that is perfectly safe.
+  if (to.schema.type === "union") {
+    var key = typeof to.schema.key === "string" ? to.schema.key : "";
+    var _iterator = _createForOfIteratorHelper(to.schema.items),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var variant = _step.value;
+        if (checkCompatibility(from, {
+          schema: variant
+        }).status === "compatible") {
+          return compatible;
+        }
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+    return incompatible({
+      kind: "no-matching-variant",
+      variants: to.schema.items.map(function (item) {
+        return describeVariant(item, key);
+      })
+    });
+  }
+
+  // Coming FROM a union into something that is not one: only the variant this
+  // value actually is matters, so narrow before comparing.
+  if (from.schema.type === "union") {
+    var _variant = variantOf(from.schema, from.value);
+    if (_variant === undefined) {
+      return {
+        status: "unknown",
+        message: "The old value does not say which shape it is, so we cannot tell whether it fits here."
+      };
+    }
+    return checkCompatibility({
+      schema: _variant,
+      value: from.value
+    }, to);
+  }
+  if (from.schema.type !== to.schema.type) {
+    return incompatible({
+      kind: "type-changed",
+      from: from.schema.type,
+      to: to.schema.type
+    });
+  }
+  switch (to.schema.type) {
+    case "literal":
+      {
+        var fromValue = from.schema.type === "literal" ? from.schema.value : String(from.value);
+        return fromValue === to.schema.value ? compatible : incompatible({
+          kind: "literal-changed",
+          from: fromValue,
+          to: to.schema.value
+        });
+      }
+    case "object":
+      {
+        if (from.schema.type !== "object" || !isJsonObject(from.value)) {
+          return {
+            status: "unknown",
+            message: "The old value is not shaped like an object."
+          };
+        }
+        var _fromValue = from.value;
+        var target = to.schema.items;
+        var source = from.schema.items;
+
+        // Keys the old value carries that the field no longer has. Writing them
+        // would put data into a schema with nowhere to hold it.
+        var extra = Object.keys(source).filter(function (key) {
+          return !(key in target);
+        });
+        if (extra.length > 0) {
+          return incompatible({
+            kind: "unknown-field",
+            keys: extra
+          });
+        }
+
+        // Keys the field requires that the old value cannot supply.
+        var missing = Object.keys(target).filter(function (key) {
+          return !target[key].opt && !(key in source);
+        });
+        if (missing.length > 0) {
+          return incompatible({
+            kind: "missing-required",
+            keys: missing
+          });
+        }
+        var unknown = null;
+        for (var _i = 0, _Object$entries = Object.entries(target); _i < _Object$entries.length; _i++) {
+          var _fromValue$_key;
+          var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+            _key = _Object$entries$_i[0],
+            targetItem = _Object$entries$_i[1];
+          var sourceItem = source[_key];
+          if (sourceItem === undefined) {
+            continue; // optional and absent — already allowed above
+          }
+          var res = checkCompatibility({
+            schema: sourceItem,
+            value: (_fromValue$_key = _fromValue[_key]) !== null && _fromValue$_key !== void 0 ? _fromValue$_key : null
+          }, {
+            schema: targetItem
+          });
+          if (res.status === "incompatible") {
+            return res;
+          }
+          if (res.status === "unknown" && unknown === null) {
+            unknown = res;
+          }
+        }
+        return unknown !== null && unknown !== void 0 ? unknown : compatible;
+      }
+    case "array":
+      {
+        if (from.schema.type !== "array" || !Array.isArray(from.value)) {
+          return {
+            status: "unknown",
+            message: "The old value is not a list."
+          };
+        }
+        // An empty list has nothing to probe the item schema with. The item
+        // TYPES still have to agree, and that much can be decided without a
+        // value - so decide it rather than passing an empty list as proof.
+        if (from.value.length === 0) {
+          return from.schema.item.type === to.schema.item.type ? compatible : incompatible({
+            kind: "type-changed",
+            from: from.schema.item.type,
+            to: to.schema.item.type
+          });
+        }
+        var _unknown = null;
+        var _iterator2 = _createForOfIteratorHelper(from.value),
+          _step2;
+        try {
+          for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+            var item = _step2.value;
+            var _res = checkCompatibility({
+              schema: from.schema.item,
+              value: item
+            }, {
+              schema: to.schema.item
+            });
+            if (_res.status === "incompatible") {
+              return _res;
+            }
+            if (_res.status === "unknown" && _unknown === null) {
+              _unknown = _res;
+            }
+          }
+        } catch (err) {
+          _iterator2.e(err);
+        } finally {
+          _iterator2.f();
+        }
+        return _unknown !== null && _unknown !== void 0 ? _unknown : compatible;
+      }
+    case "record":
+      {
+        if (from.schema.type !== "record" || !isJsonObject(from.value)) {
+          return {
+            status: "unknown",
+            message: "The old value is not a record."
+          };
+        }
+        var _unknown2 = null;
+        for (var _i2 = 0, _Object$values = Object.values(from.value); _i2 < _Object$values.length; _i2++) {
+          var entry = _Object$values[_i2];
+          var _res2 = checkCompatibility({
+            schema: from.schema.item,
+            value: entry !== null && entry !== void 0 ? entry : null
+          }, {
+            schema: to.schema.item
+          });
+          if (_res2.status === "incompatible") {
+            return _res2;
+          }
+          if (_res2.status === "unknown" && _unknown2 === null) {
+            _unknown2 = _res2;
+          }
+        }
+        return _unknown2 !== null && _unknown2 !== void 0 ? _unknown2 : compatible;
+      }
+    case "keyOf":
+      {
+        // A key is only meaningful against the module it indexes.
+        if (from.schema.type !== "keyOf") {
+          return compatible;
+        }
+        return from.schema.path === to.schema.path ? compatible : incompatible({
+          kind: "different-module",
+          from: from.schema.path,
+          to: to.schema.path
+        });
+      }
+    case "richtext":
+      {
+        // The options decide which nodes are legal, and comparing them properly
+        // means comparing node trees against them. Not yet done, and saying so is
+        // better than a confident answer we cannot back.
+        return {
+          status: "unknown",
+          message: "Rich text can be restored, but we cannot yet confirm every mark and block is still allowed here."
+        };
+      }
+    default:
+      // Primitives and media: same type is the whole test. Constraints
+      // (maxLength, accept, …) are validated on write, which reports them
+      // better than a schema comparison could.
+      return compatible;
+  }
+}
+
+/**
+ * The newest commit the client has been told about, or `null` if none.
+ *
+ * This is the **publish head**: unlike `baseSha`, which only moves once a
+ * deployment lands, it moves the instant somebody publishes. That makes it the
+ * one thing a client can carry to `/save` to say "this is the world I decided
+ * against" — and the only way the server can tell that somebody else has
+ * published since the review screen was read.
+ *
+ * In `shared` because both sides need the SAME answer: the client names a head
+ * and the server compares against one, so two implementations of "newest" is two
+ * ways to disagree about whether a publish is stale.
+ *
+ * By `createdAt` rather than by position, because the list's order is the
+ * content API's business and nothing here should depend on it. Ties keep the
+ * first seen, which is arbitrary and does not matter: two commits sharing a
+ * timestamp are equally "since", and either answer refuses the same publishes.
+ */
+function newestCommitSha(commits) {
+  var _newest$commitSha, _newest;
+  var newest = null;
+  var _iterator = _createForOfIteratorHelper(commits !== null && commits !== void 0 ? commits : []),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var commit = _step.value;
+      if (newest === null || commit.createdAt > newest.createdAt) {
+        newest = commit;
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return (_newest$commitSha = (_newest = newest) === null || _newest === void 0 ? void 0 : _newest.commitSha) !== null && _newest$commitSha !== void 0 ? _newest$commitSha : null;
+}
+
+var VAL_CONFIG_SESSION_STORAGE_KEY = "val-config";
+var VAL_THEME_SESSION_STORAGE_KEY = "val-theme";
+var VAL_AI_SESSION_STORAGE_KEY = "val-ai-session";
+
+var SharedValConfig = zod.z.object({
+  contentHostUrl: zod.z.string().optional(),
+  appHostUrl: zod.z.string().optional(),
+  project: zod.z.string().optional(),
+  root: zod.z.string().optional(),
+  gitCommit: zod.z.string().optional(),
+  gitBranch: zod.z.string().optional(),
+  defaultTheme: zod.z["enum"](["dark", "light"]).optional(),
+  ai: zod.z.object({
+    commitMessages: zod.z.object({
+      disabled: zod.z["boolean"]().optional()
+    }).optional()
+  }).optional()
+});
+
+/**
+ * Config that is shared between the client and server.
+ */
+
+var ValDeployment = zod.z.object({
+  deploymentId: zod.z.string(),
+  deploymentState: zod.z.string(),
+  commitSha: zod.z.string(),
+  updatedAt: zod.z.string(),
+  createdAt: zod.z.string()
+});
+
+// Strictly speaking this should be in the next package but it's shared, because we want to use it in the ui package. We want to resolve that somehow
+function getNextAppRouterSitemapTree(srcFolder, paths) {
+  var root = {
+    type: "node",
+    name: "/",
+    children: []
+  };
+  var _iterator = _createForOfIteratorHelper(paths),
+    _step;
+  try {
+    var _loop = function _loop() {
+        var path = _step.value;
+        var urlPath = path.urlPath,
+          moduleFilePathS = path.moduleFilePath;
+        var moduleFilePath = moduleFilePathS;
+        if (!urlPath.startsWith("/")) {
+          console.error("urlPath must start with /: ".concat(urlPath));
+          return 0; // continue
+        }
+        var pattern = getPatternFromModuleFilePath(moduleFilePath, srcFolder);
+        if (urlPath === "/") {
+          var fullPath = "/";
           root.pattern = getPatternFromModuleFilePath(moduleFilePath, srcFolder);
           root.page = {
             fullPath: fullPath
@@ -4082,13 +4675,21 @@ function checkGallerySchema(moduleSchema) {
   };
 }
 function buildImageGalleryPatch(args, moduleSchema) {
+  var _args$metadata$alt;
   var wrong = checkGallerySchema(moduleSchema);
   if (wrong) return wrong;
   var remote = isRemoteSchema(moduleSchema);
   var patch = [{
     op: "add",
     path: [args.filePath],
-    value: _objectSpread2({}, args.metadata)
+    value: _objectSpread2(_objectSpread2({}, args.metadata), {}, {
+      // `alt` is a REQUIRED field of a gallery entry (`s.images()` gives it a
+      // nullable string schema), so an entry written without one is invalid
+      // the moment it lands — and the caller that had no alt to give is the
+      // common case, not the odd one. Null is what the Studio's own upload
+      // writes there.
+      alt: (_args$metadata$alt = args.metadata.alt) !== null && _args$metadata$alt !== void 0 ? _args$metadata$alt : null
+    })
   }, {
     op: "file",
     path: [args.filePath],
@@ -4534,6 +5135,13 @@ function isSkippableFixCode(fix) {
       // rewriting the module) and saving does not repair it either, so surface
       // it: the message names the command (`val validate --fix`) that does.
       return false;
+    case "external:upload":
+      // Same shape as `jsonValues:extract-entry` — an entry inlined in a
+      // `.val.ts` that belongs elsewhere — and more emphatically not skippable.
+      // Fixing it writes to a live store, which is why even the CLI does it only
+      // under `val external upload` and never under a blanket `--fix`. Surfacing
+      // it is the whole point: someone has to decide.
+      return false;
     default:
       {
         return false;
@@ -4573,15 +5181,723 @@ function filterBlockingValidationErrors(validationErrors, schemas, sources) {
   return partitionValidationErrors(resolved).surfaced;
 }
 
+/**
+ * Every decision `encode` makes, with none of the pixels.
+ *
+ * The re-encode itself happens in two places that share nothing: the Studio
+ * runs it on a `<canvas>` before the upload leaves the browser
+ * (`packages/ui/spa/utils/encodeImage.ts`), and the MCP image tool runs it on
+ * `sharp` in the server process (`@valbuild/mcp`). What must NOT differ between
+ * them is what `s.image({ encode })` means — which images are converted, how
+ * far they are scaled, and when the original wins anyway. So the decisions live
+ * here, once, and each side supplies only its own encoder.
+ *
+ * See `architecture/media.md`.
+ */
+
+var ENCODE_DEFAULTS = {
+  quality: 0.8,
+  maxWidth: 2560,
+  maxHeight: 2560
+};
+var ENCODE_MIME_TYPE_OF = {
+  webp: "image/webp"
+};
+
+/**
+ * Formats an encoder cannot round-trip without losing something: SVG is vector,
+ * an animated GIF keeps only its first frame, and AVIF is already smaller than
+ * anything we would produce.
+ */
+var NEVER_ENCODED = ["image/svg+xml", "image/gif", "image/avif"];
+
+/** A dimension bound the encoder can act on, else the default. */
+function usableBound(value, fallback) {
+  return value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+/**
+ * The schema's own option first, then the gallery it references, then off.
+ *
+ * Mirrors how `ImageField` resolves `accept` and `directory`. A gallery-backed
+ * field (`s.image(galleryVal)`) serializes with EMPTY options, so without the
+ * gallery fallback it could never inherit what the gallery asked for — and
+ * `s.image(galleryVal, { encode: false })` is how such a field opts back out.
+ *
+ * Nonsense numbers fall back to the defaults rather than through. `fitWithin`
+ * reads a bound of 0 (or NaN, or a negative) as "everything already fits", so
+ * an unusable `maxWidth` would otherwise SILENTLY disable the downscale it was
+ * asking for, and a `quality` outside 0–1 is ignored by `canvas.toBlob` just as
+ * quietly. Falling back is deliberately not throwing: a schema is evaluated by
+ * the CLI's `node:vm` sandbox and by the Next server, so a typo'd quality would
+ * take a whole project down over an upload-time optimisation.
+ */
+function resolveEncodeSettings(fieldOption, galleryOption) {
+  var option = fieldOption !== undefined ? fieldOption : galleryOption;
+  if (!option) {
+    return null;
+  }
+  var quality = option.quality;
+  return {
+    type: option.type,
+    quality: quality !== undefined && Number.isFinite(quality) && quality > 0 ? Math.min(quality, 1) : ENCODE_DEFAULTS.quality,
+    maxWidth: usableBound(option.maxWidth, ENCODE_DEFAULTS.maxWidth),
+    maxHeight: usableBound(option.maxHeight, ENCODE_DEFAULTS.maxHeight)
+  };
+}
+
+/**
+ * Dimensions scaled to fit inside the box, or null when the image already does.
+ *
+ * Null is the signal for "no downscale was needed", which the size comparison
+ * in {@link chooseEncoded} turns on.
+ */
+function fitWithin(width, height, maxWidth, maxHeight) {
+  if (!(width > 0) || !(height > 0) || !(maxWidth > 0) || !(maxHeight > 0) || width <= maxWidth && height <= maxHeight) {
+    return null;
+  }
+  var scale = Math.min(maxWidth / width, maxHeight / height);
+  return {
+    // At least one pixel: a very wide, very short image would otherwise round
+    // its height to zero, and a zero-sized canvas cannot be encoded.
+    width: Math.max(1, Math.round(width * scale)),
+    height: Math.max(1, Math.round(height * scale))
+  };
+}
+
+/**
+ * Whether a schema that declares `accept` would take this mime type.
+ *
+ * The same rules as `ImageSchema.executeValidate`, which validates the STORED
+ * mimeType against `accept` — so converting to a type `accept` forbids would
+ * upload a file the schema reports as invalid the moment it lands. Delegated to
+ * `@valbuild/core` rather than re-spelled, because a second reading of one
+ * `accept` string is how a converted image passes here and fails there.
+ */
+function isMimeTypeAccepted(mimeType, accept) {
+  if (!accept) {
+    return true;
+  }
+  return core.Internal.mimeTypeMatchesAccept(mimeType, accept);
+}
+
+/** Formats left alone: the lossy list, plus the target type when it already fits. */
+function isSkippedSource(sourceMimeType, targetMimeType, needsDownscale) {
+  if (NEVER_ENCODED.includes(sourceMimeType)) {
+    return true;
+  }
+  return sourceMimeType === targetMimeType && !needsDownscale;
+}
+
+/**
+ * Whether to upload what the encoder produced, or the file that was picked.
+ *
+ * Two ways the encoded bytes lose. They are not actually the type we asked for
+ * — `canvas.toBlob` answers an unsupported type with a PNG rather than with
+ * null, so "not null" is not the same question as "is a webp". Or they are
+ * simply bigger, which happens for small and flat images: measured, an 8x8
+ * solid PNG of 74 bytes becomes a 548 byte webp. A downscale overrides that,
+ * since the original is then the wrong size whatever it weighs.
+ */
+function chooseEncoded(input) {
+  if (input.encodedSize === null || input.encodedType !== input.targetMimeType) {
+    return false;
+  }
+  if (input.needsDownscale) {
+    return true;
+  }
+  return input.encodedSize < input.originalSize;
+}
+
+/**
+ * `photo.png` -> `photo.webp`. The extension is re-derived downstream too, but
+ * the name should not lie.
+ */
+function withExtension(filename, ext) {
+  var base = filename.split(".").slice(0, -1).join(".") || filename;
+  return "".concat(base, ".").concat(ext);
+}
+
+/**
+ * The one way to build a child's source path.
+ *
+ * There were five hand-rolled versions of this, three of them subtly different
+ * and two of them wrong, and the wrong ones were wrong in a way that hid: a
+ * module path segment has to be JSON-quoted if it is a string and bare if it is
+ * an array index, and both broken copies appended the raw key at the module
+ * root. An unquoted key parses fine as long as it contains no `.` — so every
+ * object field and every ordinary record key still resolved, and only a key with
+ * a dot in it broke. That is exactly what a media gallery is keyed by, so
+ * clicking a file in the Media panel navigated to
+ * `?p=/public/val/red-8x8_bfbd0.png`, which `splitModulePath` reads as the two
+ * segments `/public/val/red-8x8_bfbd0` and `png`, and the studio said the module
+ * was not found.
+ *
+ * So: one function, and never a template string. `Internal.createValPathOfItem`
+ * is the rule itself — `JSON.stringify` quotes a string and leaves a number
+ * bare, which is precisely the module-path grammar — and everything here defers
+ * to it rather than restating it.
+ */
+function sourcePathOfChild(parent, key) {
+  /**
+   * A parent that is already `…?p=` gets the key with no separator.
+   *
+   * The search index walks from `moduleFilePath + "?p="` rather than from the
+   * module file path, so that every path it produces has a module path — and
+   * `createValPathOfItem` would see the separator and join with a `.`, giving
+   * `?p=."title"`.
+   */
+  if (parent.endsWith(core.Internal.ModuleFilePathSep)) {
+    return "".concat(parent).concat(JSON.stringify(key));
+  }
+  var path = core.Internal.createValPathOfItem(parent, key);
+  if (path === undefined) {
+    // Only when the parent is empty, which callers cannot produce: every walk
+    // starts from a module file path. Thrown rather than skipped so a future
+    // change that breaks that assumption is loud.
+    throw new Error("Could not build a source path for '".concat(key, "' under ").concat(parent));
+  }
+  return path;
+}
+
+/**
+ * The same thing, for callers holding the module file path and module path apart.
+ *
+ * `ModulePath` is empty at the module root, which is the case both broken copies
+ * got wrong: there is no separator in the path yet, so the key is the first
+ * segment and still has to be quoted.
+ */
+function concatModulePath(moduleFilePath, modulePath, key) {
+  return sourcePathOfChild(modulePath ? core.Internal.joinModuleFilePathAndModulePath(moduleFilePath, modulePath) : moduleFilePath, key);
+}
+
+/**
+ * Traverses a schema and source pair, calling a callback for each leaf node.
+ * Handles all schema types including primitives, objects, arrays, records, unions, richtext, files, images, etc.
+ *
+ * @param source - The JSON source data
+ * @param schema - The serialized schema
+ * @param path - The current source path
+ * @param callback - Function called for each traversable node with { source, schema, path }
+ */
+function traverseSchemaSource(source, schema, path, callback) {
+  if (!(schema !== null && schema !== void 0 && schema.type)) {
+    throw new Error("Schema not found for " + path);
+  }
+  if (source === null) {
+    return;
+  }
+
+  // An un-loaded `.jsonValues()` entry is an opaque `{_type:"json"}` marker, not
+  // the value its schema describes. Skip it — its content is traversed once
+  // loaded, since the sync engine substitutes it in place of the marker.
+  //
+  // Without this the marker falls through to whichever branch its ITEM schema
+  // selects: an object/record item walks the marker's OWN keys, so an entry
+  // schema with a field named `_type` or `patch_id` would index the marker's
+  // internals as if they were content.
+  if (core.Internal.isJson(source)) {
+    return;
+  }
+
+  // Handle primitives
+  if (schema.type === "string") {
+    if (typeof source === "string") {
+      callback({
+        source: source,
+        schema: schema,
+        path: path
+      });
+    }
+    return;
+  }
+  if (schema.type === "number") {
+    if (typeof source === "number") {
+      callback({
+        source: source,
+        schema: schema,
+        path: path
+      });
+    }
+    return;
+  }
+  if (schema.type === "boolean") {
+    if (typeof source === "boolean") {
+      callback({
+        source: source,
+        schema: schema,
+        path: path
+      });
+    }
+    return;
+  }
+
+  // Handle richtext - flatten and call callback
+  if (schema.type === "richtext") {
+    callback({
+      source: source,
+      schema: schema,
+      path: path
+    });
+    return;
+  }
+
+  // Handle file/image
+  if (schema.type === "file" || schema.type === "image") {
+    if (source && _typeof(source) === "object" && "path" in source && typeof source.path === "string") {
+      callback({
+        source: source,
+        schema: schema,
+        path: path
+      });
+    }
+    return;
+  }
+
+  // Handle date
+  if (schema.type === "date") {
+    if (typeof source === "string") {
+      callback({
+        source: source,
+        schema: schema,
+        path: path
+      });
+    }
+    return;
+  }
+
+  // Handle dateTime
+  if (schema.type === "dateTime") {
+    if (typeof source === "string") {
+      callback({
+        source: source,
+        schema: schema,
+        path: path
+      });
+    }
+    return;
+  }
+
+  // Handle color
+  if (schema.type === "color") {
+    if (typeof source === "string") {
+      callback({
+        source: source,
+        schema: schema,
+        path: path
+      });
+    }
+    return;
+  }
+
+  // Handle code
+  if (schema.type === "code") {
+    if (typeof source === "string") {
+      callback({
+        source: source,
+        schema: schema,
+        path: path
+      });
+    }
+    return;
+  }
+
+  // Handle keyOf
+  if (schema.type === "keyOf") {
+    if (typeof source === "string" || typeof source === "number") {
+      callback({
+        source: source,
+        schema: schema,
+        path: path
+      });
+    }
+    return;
+  }
+
+  // Handle literal
+  if (schema.type === "literal") {
+    callback({
+      source: source,
+      schema: schema,
+      path: path
+    });
+    return;
+  }
+
+  // Handle route
+  if (schema.type === "route") {
+    if (typeof source === "string") {
+      callback({
+        source: source,
+        schema: schema,
+        path: path
+      });
+    }
+    return;
+  }
+
+  // Handle array
+  if (schema.type === "array") {
+    if (!Array.isArray(source)) {
+      return;
+    }
+    if (!schema.item) {
+      throw new Error("Schema (" + schema.type + ") item not found for " + path);
+    }
+    for (var i = 0; i < source.length; i++) {
+      var subPath = sourcePathOfChild(path, i);
+      traverseSchemaSource(source[i], schema.item, subPath, callback);
+    }
+    return;
+  }
+
+  // Handle object, record and settings
+  if (schema.type === "object" || schema.type === "record" ||
+  // Settings walks like an object, and starting from the SOURCE is what makes
+  // its optional keys work: an absent section has nothing to traverse.
+  schema.type === "settings") {
+    if (_typeof(source) !== "object" || source === null || Array.isArray(source)) {
+      return;
+    }
+    for (var key in source) {
+      var _schema$items;
+      var subSchema = schema.type === "record" ? schema.item : (_schema$items = schema.items) === null || _schema$items === void 0 ? void 0 : _schema$items[key];
+      if (!subSchema) {
+        continue;
+      }
+      var _subPath = sourcePathOfChild(path, key);
+      traverseSchemaSource(source[key], subSchema, _subPath, callback);
+    }
+    return;
+  }
+
+  // Handle union
+  if (schema.type === "union") {
+    var schemaKey = schema.key;
+    if (typeof schemaKey === "string") {
+      // Tagged union - find matching sub-schema
+      if (source && _typeof(source) === "object" && !Array.isArray(source) && schemaKey in source) {
+        var itemKey = source[schemaKey];
+        if (typeof itemKey === "string") {
+          var schemaOfItem = schema.items.filter(function (item) {
+            return item.type === "object";
+          }).find(function (item) {
+            var itemKeySchema = item.items[schemaKey];
+            if ((itemKeySchema === null || itemKeySchema === void 0 ? void 0 : itemKeySchema.type) === "literal") {
+              return itemKeySchema.value === itemKey;
+            }
+            return false;
+          });
+          if (schemaOfItem) {
+            traverseSchemaSource(source, schemaOfItem, path, callback);
+          }
+        }
+      }
+    } else {
+      // Literal union - treat as primitive
+      if (typeof source === "string") {
+        callback({
+          source: source,
+          schema: schema,
+          path: path
+        });
+      }
+    }
+    return;
+  }
+
+  // Exhaustive check
+  var exhaustiveCheck = schema;
+  throw new Error("Unsupported schema type: " + JSON.stringify(exhaustiveCheck));
+}
+
+/**
+ * Flattens richtext source to a plain string, extracting only text content.
+ * Used for indexing richtext content in search.
+ */
+function flattenRichText(source) {
+  var res = "";
+  function rec(child) {
+    if (typeof child === "string") {
+      res += child;
+    } else {
+      if (child && _typeof(child) === "object" && "children" in child && Array.isArray(child.children)) {
+        var _iterator = _createForOfIteratorHelper(child.children),
+          _step;
+        try {
+          for (_iterator.s(); !(_step = _iterator.n()).done;) {
+            var c = _step.value;
+            rec(c);
+          }
+        } catch (err) {
+          _iterator.e(err);
+        } finally {
+          _iterator.f();
+        }
+      }
+    }
+  }
+  rec({
+    children: source
+  });
+  return res;
+}
+
+/**
+ * Resolves a file ref (local path or remote URL) to a clean local-style path.
+ */
+function cleanRefPath(ref) {
+  var remoteRefRes = core.Internal.remote.splitRemoteRef(ref);
+  return remoteRefRes.status === "success" ? "/".concat(remoteRefRes.filePath) : ref;
+}
+
+/**
+ * Extract a human-readable filename from a file ref (local path or remote URL).
+ * Handles both remote refs (via splitRemoteRef) and plain `/public/...` paths.
+ */
+function getFilenameFromRef(ref) {
+  var cleanPath = cleanRefPath(ref);
+  return cleanPath.split("/").pop() || cleanPath;
+}
+
+/**
+ * Parse a file ref into its constituent parts: a clean path, filename, and
+ * folder (the path relative to `/public`).
+ *
+ * The `folder` strips the standard `/public` prefix so it shows a
+ * concise location like `/images` instead of `/public/images`.
+ */
+function getRefParts(ref) {
+  var cleanPath = cleanRefPath(ref);
+  var filename = cleanPath.split("/").pop() || cleanPath;
+  // Only strip a leading "/public" path segment: "/publicity/a.png" must keep its folder
+  var folder = cleanPath.replace(/^\/public(?=\/|$)/, "").replace(/\/[^/]+$/, "") || "/";
+  return {
+    cleanPath: cleanPath,
+    filename: filename,
+    folder: folder
+  };
+}
+
+/**
+ * The search index and the labels to render for its hits.
+ *
+ * Kept as a plain module rather than living inside a worker so it can be tested:
+ * a worker entry runs `self.onmessage` on import, which no test environment here
+ * provides.
+ *
+ * In `@valbuild/shared` rather than the Studio because there are now two
+ * realms searching the same content: the Studio's `SearchStore`, which keeps an
+ * index alive in a worker and re-indexes a module at a time, and the MCP
+ * `search_content` tool, which builds one per call and throws it away. What
+ * counts as a document, and what a hit is labelled, must not differ between
+ * them — an agent and an editor searching the same project should find the same
+ * things.
+ */
+
+/** An index with nothing in it. Fill it with {@link indexModule}. */
+function createSearchIndex() {
+  return {
+    index: new FlexSearch__default["default"].Index({
+      tokenize: "forward"
+    }),
+    pathToLabel: new Map(),
+    docsByModule: new Map()
+  };
+}
+
+/**
+ * Index one module, replacing whatever was previously indexed for it.
+ *
+ * Remove-then-add rather than `update`, because the set of paths in a module is
+ * not stable: deleting an array item or a record entry means documents that must
+ * disappear, and `update` only revises ids it is given.
+ *
+ * `.jsonValues()` entries are indexed only once their content is loaded — an
+ * un-loaded entry is an opaque marker that {@link traverseSchemaSource} skips, so
+ * the index is naturally PARTIAL and grows as batches land. That is why the search
+ * UI loads the entries on the first query and re-indexes (debounced) as they
+ * arrive, rather than pretending an empty result set is an answer.
+ */
+function indexModule(searchIndex, moduleFilePath, source, schema) {
+  var index = searchIndex.index,
+    pathToLabel = searchIndex.pathToLabel,
+    docsByModule = searchIndex.docsByModule;
+  removeModule(searchIndex, moduleFilePath);
+  var docs = new Set();
+  docsByModule.set(moduleFilePath, docs);
+  var path = moduleFilePath + "?p=";
+  traverseSchemaSource(source, schema, path, function (_ref) {
+    var source = _ref.source,
+      schema = _ref.schema,
+      path = _ref.path;
+    if (source === null) {
+      return;
+    }
+    var searchText = "";
+    var label = "";
+
+    // Handle primitives
+    if (schema.type === "string" || schema.type === "number" || schema.type === "boolean" || schema.type === "date" || schema.type === "dateTime" || schema.type === "color" || schema.type === "code" || schema.type === "keyOf" || schema.type === "route") {
+      var _source$toString, _source$toString2;
+      searchText = (_source$toString = source === null || source === void 0 ? void 0 : source.toString()) !== null && _source$toString !== void 0 ? _source$toString : "";
+      label = (_source$toString2 = source === null || source === void 0 ? void 0 : source.toString()) !== null && _source$toString2 !== void 0 ? _source$toString2 : "";
+    } else if (schema.type === "literal") {
+      searchText = schema.value.toString();
+      label = schema.value.toString();
+    }
+    // Handle richtext - flatten to get text content
+    else if (schema.type === "richtext") {
+      searchText = flattenRichText(source);
+      // Use first 50 chars as label
+      label = searchText.substring(0, 50) || "richtext";
+    }
+    // Handle file/image
+    else if (schema.type === "file" || schema.type === "image") {
+      if (source !== null && _typeof(source) === "object" && "path" in source && typeof source.path === "string") {
+        // The label is the bare filename - the folder is shown separately in
+        // the UI - but both are searchable.
+        var _getRefParts = getRefParts(source.path),
+          filename = _getRefParts.filename,
+          folder = _getRefParts.folder;
+        var alt = "alt" in source ? source.alt : "";
+        searchText = filename + " " + folder + " " + alt;
+        label = filename;
+      }
+    }
+
+    // Add to index if we have search text
+    if (searchText) {
+      var _Internal$splitModule = core.Internal.splitModuleFilePathAndModulePath(path),
+        _Internal$splitModule2 = _slicedToArray(_Internal$splitModule, 2),
+        modulePath = _Internal$splitModule2[1];
+      var cleanPath = fastRemoveNonWordChars(modulePath) + " ";
+      index.add(path, cleanPath + " " + path + " " + searchText);
+      pathToLabel.set(path, label);
+      docs.add(path);
+    }
+  });
+}
+
+/**
+ * Drop everything indexed for one module.
+ *
+ * Also used for a module that has gone away entirely — otherwise its documents
+ * stay searchable and a hit navigates to a path that no longer exists.
+ */
+function removeModule(searchIndex, moduleFilePath) {
+  var index = searchIndex.index,
+    pathToLabel = searchIndex.pathToLabel,
+    docsByModule = searchIndex.docsByModule;
+  var existing = docsByModule.get(moduleFilePath);
+  if (existing === undefined) return;
+  var _iterator = _createForOfIteratorHelper(existing),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var id = _step.value;
+      index.remove(id);
+      pathToLabel["delete"](id);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  docsByModule["delete"](moduleFilePath);
+}
+
+/**
+ * Index every module, from scratch.
+ *
+ * Now a loop over {@link indexModule} rather than its own walk, so the full
+ * build and the incremental one cannot drift in what they consider a document.
+ */
+function buildSearchIndex(modules) {
+  var searchIndex = createSearchIndex();
+  for (var moduleFilePathS in modules) {
+    var moduleFilePath = moduleFilePathS;
+    var _modules$moduleFilePa = modules[moduleFilePath],
+      source = _modules$moduleFilePa.source,
+      schema = _modules$moduleFilePa.schema;
+    indexModule(searchIndex, moduleFilePath, source, schema);
+  }
+  return searchIndex;
+}
+var NON_CHARS = new Set(["/", "-", "_", ".", ":", "?", "&", "=", "@", '"', "'"]);
+function fastRemoveNonWordChars(str) {
+  var result = "";
+  for (var i = 0; i < str.length; i++) {
+    var _char = str[i];
+    if (!NON_CHARS.has(_char)) {
+      result += _char;
+    } else {
+      result += " ";
+    }
+  }
+  return result;
+}
+
+/**
+ * How many hits are counted before `total` stops being a count.
+ *
+ * FlexSearch stops as soon as it has the number of ids it was asked for, so a
+ * `total` taken from a page-sized search is just the page size again — which
+ * reads as "that is all there is" to anyone who did not write it. Counting is
+ * asking for more ids than the page needs, so it costs an array of ids and no
+ * more; this bound is where that stops being free, and `totalIsLowerBound` says
+ * it was reached rather than letting the number quietly lie.
+ */
+var MAX_COUNTED_RESULTS = 10000;
+function performSearch(searchIndex, query) {
+  var limit = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 50;
+  var offset = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 0;
+  if (searchIndex === null || !query.trim()) {
+    return {
+      results: [],
+      total: 0,
+      totalIsLowerBound: false
+    };
+  }
+  var index = searchIndex.index,
+    pathToLabel = searchIndex.pathToLabel;
+  var counted = Math.max(offset + limit, MAX_COUNTED_RESULTS);
+  var searchResults = index.search(query, {
+    limit: counted
+  });
+  var total = searchResults.length;
+  var paged = searchResults.slice(offset, offset + limit);
+  return {
+    results: paged.map(function (id) {
+      return {
+        path: id,
+        label: pathToLabel.get(id) || id
+      };
+    }),
+    total: total,
+    totalIsLowerBound: total >= counted
+  };
+}
+
 exports.Api = Api;
+exports.BinaryFileRef = BinaryFileRef;
 exports.CodeOptions = CodeOptions;
 exports.ColorOptions = ColorOptions;
 exports.DEFAULT_ERROR_MESSAGE = DEFAULT_ERROR_MESSAGE;
 exports.DateOptions = DateOptions;
+exports.ENCODE_DEFAULTS = ENCODE_DEFAULTS;
+exports.ENCODE_MIME_TYPE_OF = ENCODE_MIME_TYPE_OF;
 exports.FileOptions = FileOptions;
+exports.HistoricalCommit = HistoricalCommit;
+exports.HistoricalModule = HistoricalModule;
+exports.HistoricalPatchSet = HistoricalPatchSet;
+exports.HistoryError = HistoryError;
 exports.ImageEncodeOption = ImageEncodeOption;
 exports.ImageOptions = ImageOptions;
+exports.JSONValue = JSONValue;
 exports.JSON_ENTRIES_BATCH_MAX = JSON_ENTRIES_BATCH_MAX;
+exports.ModuleComparison = ModuleComparison;
+exports.NEVER_ENCODED = NEVER_ENCODED;
 exports.ParentRef = ParentRef$1;
 exports.Patch = Patch;
 exports.PatchBlock = PatchBlock;
@@ -4599,6 +5915,7 @@ exports.RemirrorOrderedList = RemirrorOrderedList;
 exports.RemirrorParagraph = RemirrorParagraph;
 exports.RemirrorText = RemirrorText;
 exports.RemirrorTextMark = RemirrorTextMark;
+exports.RestoreVerdict = RestoreVerdict;
 exports.RichTextOptions = RichTextOptions;
 exports.SerializedArraySchema = SerializedArraySchema;
 exports.SerializedBooleanSchema = SerializedBooleanSchema;
@@ -4616,6 +5933,7 @@ exports.SerializedRecordSchema = SerializedRecordSchema;
 exports.SerializedRichTextSchema = SerializedRichTextSchema;
 exports.SerializedRouteSchema = SerializedRouteSchema;
 exports.SerializedSchema = SerializedSchema;
+exports.SerializedSettingsSchema = SerializedSettingsSchema;
 exports.SerializedStringSchema = SerializedStringSchema;
 exports.SerializedUnionSchema = SerializedUnionSchema;
 exports.SharedValConfig = SharedValConfig;
@@ -4634,22 +5952,35 @@ exports.buildEmptyAtPathPatch = buildEmptyAtPathPatch;
 exports.buildFileRefValue = buildFileRefValue;
 exports.buildImageGalleryPatch = buildImageGalleryPatch;
 exports.buildRemoveImageGalleryEntryPatch = buildRemoveImageGalleryEntryPatch;
+exports.buildSearchIndex = buildSearchIndex;
+exports.checkCompatibility = checkCompatibility;
+exports.chooseEncoded = chooseEncoded;
+exports.concatModulePath = concatModulePath;
 exports.createRegExpFromPattern = createRegExpFromPattern;
+exports.createSearchIndex = createSearchIndex;
 exports.createValClient = createValClient;
 exports.describeContainerAtPath = describeContainerAtPath;
 exports.emptyOf = emptyOf;
+exports.explainIncompatible = explainIncompatible;
 exports.filterBlockingValidationErrors = filterBlockingValidationErrors;
 exports.filterRoutesByPatterns = filterRoutesByPatterns;
 exports.findSimilar = findSimilar;
+exports.fitWithin = fitWithin;
+exports.flattenRichText = flattenRichText;
 exports.getErrorMessageFromUnknownJson = getErrorMessageFromUnknownJson;
+exports.getFilenameFromRef = getFilenameFromRef;
 exports.getInlineImgInfo = getInlineImgInfo;
 exports.getNextAppRouterSitemapTree = getNextAppRouterSitemapTree;
 exports.getNextAppRouterSourceFolder = getNextAppRouterSourceFolder;
 exports.getPatternFromModuleFilePath = getPatternFromModuleFilePath;
+exports.getRefParts = getRefParts;
 exports.getRoutesOf = getRoutesOf;
 exports.getRoutesWithModulePaths = getRoutesWithModulePaths;
 exports.getSourceAt = getSourceAt;
+exports.indexModule = indexModule;
+exports.isMimeTypeAccepted = isMimeTypeAccepted;
 exports.isRemoteSchema = isRemoteSchema;
+exports.isSkippedSource = isSkippedSource;
 exports.isValCanvasFrame = isValCanvasFrame;
 exports.isValCanvasPageMessage = isValCanvasPageMessage;
 exports.isValCanvasStudioMessage = isValCanvasStudioMessage;
@@ -4657,13 +5988,19 @@ exports.levenshtein = levenshtein;
 exports.newestCommitSha = newestCommitSha;
 exports.parseRoutePattern = parseRoutePattern;
 exports.partitionValidationErrors = partitionValidationErrors;
+exports.performSearch = performSearch;
 exports.remirrorToRichTextSource = remirrorToRichTextSource;
+exports.removeModule = removeModule;
+exports.resolveEncodeSettings = resolveEncodeSettings;
 exports.resolveSchemaSourceFixForError = resolveSchemaSourceFixForError;
 exports.resolveSchemaSourceFixes = resolveSchemaSourceFixes;
 exports.resolveSerializedSchemaAtPath = resolveSerializedSchemaAtPath;
 exports.richTextToRemirror = richTextToRemirror;
 exports.safeParsePatch = safeParsePatch;
+exports.sourcePathOfChild = sourcePathOfChild;
 exports.toolNames = toolNames;
+exports.traverseSchemaSource = traverseSchemaSource;
 exports.urlOf = urlOf;
 exports.validateRoutePatterns = validateRoutePatterns;
+exports.withExtension = withExtension;
 exports.withValCanvasParam = withValCanvasParam;