akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/common/markdownBlocks.ts

@@ -0,0 +1,134 @@
+import { MarkdownTable, type TableBlock } from "./markdownTable";
+
+export interface MarkdownItem {
+  depth: number;
+  ordered: boolean;
+  num: number;
+  text: string;
+}
+
+export type MarkdownBlock =
+  | { kind: "code"; lang?: string; text: string }
+  | { kind: "heading"; level: number; text: string }
+  | { kind: "list"; items: MarkdownItem[] }
+  | { kind: "quote"; text: string }
+  | { kind: "rule" }
+  | { kind: "para"; text: string }
+  | TableBlock;
+
+const fence = /^ {0,3}(```|~~~)(.*)$/;
+const heading = /^ {0,3}(#{1,6})\s+(.*)$/;
+const rule = /^ {0,3}(?:-{3,}|\*{3,}|_{3,})\s*$/;
+const quote = /^ {0,3}> ?(.*)$/;
+const bullet = /^(\s*)[-*+]\s+(.*)$/;
+const ordered = /^(\s*)(\d{1,9})[.)]\s+(.*)$/;
+const lazyLine = /^\s+\S/;
+
+export class MarkdownBlocks {
+  static of(source: string): MarkdownBlock[] {
+    return new MarkdownBlocks(source).#run();
+  }
+
+  readonly #lines: string[];
+  readonly #blocks: MarkdownBlock[] = [];
+  #at = 0;
+
+  constructor(source: string) {
+    this.#lines = source.replace(/\r\n?/g, "\n").split("\n");
+  }
+
+  #run() {
+    while (this.#at < this.#lines.length) {
+      const line = this.#lines[this.#at];
+      const head = heading.exec(line);
+      const fenced = fence.exec(line);
+      const table = MarkdownTable.at(this.#lines, this.#at);
+      if (!line.trim()) this.#at += 1;
+      else if (fenced) this.#code(fenced[1], fenced[2]);
+      else if (rule.test(line)) this.#take({ kind: "rule" });
+      else if (head) this.#take({ kind: "heading", level: head[1].length, text: head[2] });
+      else if (quote.test(line)) this.#quote();
+      else if (ordered.test(line)) this.#list(true);
+      else if (bullet.test(line)) this.#list(false);
+      else if (table) {
+        this.#blocks.push(table.block);
+        this.#at = table.next;
+      } else this.#para();
+    }
+    return this.#blocks;
+  }
+
+  #take(block: MarkdownBlock) {
+    this.#blocks.push(block);
+    this.#at += 1;
+  }
+
+  #code(marker: string, info: string) {
+    
+    const lang = info.trim().split(/\s+/)[0];
+    this.#at += 1;
+    const body: string[] = [];
+    while (this.#at < this.#lines.length) {
+      const line = this.#lines[this.#at];
+      this.#at += 1;
+      if (line.trimStart().startsWith(marker)) break;
+      body.push(line);
+    }
+    this.#blocks.push({ kind: "code", ...(lang ? { lang } : {}), text: body.join("\n") });
+  }
+
+  #quote() {
+    const lines: string[] = [];
+    while (this.#at < this.#lines.length) {
+      const match = quote.exec(this.#lines[this.#at]);
+      if (!match) break;
+      lines.push(match[1]);
+      this.#at += 1;
+    }
+    this.#blocks.push({ kind: "quote", text: lines.join(" ").trim() });
+  }
+
+  #list(isOrdered: boolean) {
+    const items: MarkdownItem[] = [];
+    while (this.#at < this.#lines.length) {
+      const line = this.#lines[this.#at];
+      const item = MarkdownBlocks.#item(line, isOrdered);
+      const open = items.at(-1);
+      if (item) items.push(item);
+      else if (open && lazyLine.test(line)) open.text += ` ${line.trim()}`;
+      else break;
+      this.#at += 1;
+    }
+    this.#blocks.push({ kind: "list", items });
+  }
+
+  static #item(line: string, isOrdered: boolean): MarkdownItem | null {
+    const numbered = ordered.exec(line);
+    const bulleted = bullet.exec(line);
+    const other = isOrdered ? bulleted : numbered;
+    const match = (isOrdered ? numbered : bulleted) ?? (other?.[1].length ? other : null);
+    if (!match) return null;
+    const carriesNum = match === numbered;
+    return {
+      depth: Math.floor(match[1].length / 2),
+      ordered: carriesNum,
+      num: carriesNum ? Number(match[2]) : 0,
+      text: carriesNum ? match[3] : match[2],
+    };
+  }
+
+  #para() {
+    const lines: string[] = [];
+    while (this.#at < this.#lines.length) {
+      const line = this.#lines[this.#at];
+      if (!line.trim() || this.#opensBlock(line) || MarkdownTable.at(this.#lines, this.#at)) break;
+      lines.push(line.trim());
+      this.#at += 1;
+    }
+    this.#blocks.push({ kind: "para", text: lines.join(" ") });
+  }
+
+  #opensBlock(line: string) {
+    return [fence, heading, rule, quote, bullet, ordered].some((pattern) => pattern.test(line));
+  }
+}

package/common/markdownSpans.ts

@@ -0,0 +1,47 @@
+export type MarkdownSpan =
+  | { kind: "text"; text: string }
+  | { kind: "code"; text: string }
+  | { kind: "strong"; text: string }
+  | { kind: "em"; text: string }
+  | { kind: "del"; text: string }
+  | { kind: "link"; text: string; href: string }
+  /** A link whose href was refused, or an image: rendered as its label, by every host. */
+  | { kind: "plain"; text: string };
+
+const inline =
+  /(!?)\[([^\]]*)\]\(((?:[^\s()]|\([^\s()]*\))+)\)|`([^`]+)`|\*\*([\s\S]+?)\*\*|\*([^*\n]+?)\*|~~([\s\S]+?)~~/g;
+
+export class MarkdownSpans {
+  static of(text: string): MarkdownSpan[] {
+    const spans: MarkdownSpan[] = [];
+    let cut = 0;
+    for (const match of text.matchAll(inline)) {
+      const at = match.index;
+      const [, image, label, href, code, strong, em, del] = match;
+      if (at > cut) spans.push({ kind: "text", text: text.slice(cut, at) });
+      cut = at + match[0].length;
+      if (href !== undefined)
+        spans.push(
+          image || !MarkdownSpans.isSafeHref(href)
+            ? { kind: "plain", text: label ?? "" }
+            : { kind: "link", text: label ?? "", href },
+        );
+      else if (code !== undefined) spans.push({ kind: "code", text: code });
+      else if (strong !== undefined) spans.push({ kind: "strong", text: strong });
+      else if (em !== undefined) spans.push({ kind: "em", text: em });
+      else if (del !== undefined) spans.push({ kind: "del", text: del });
+    }
+    if (cut < text.length) spans.push({ kind: "text", text: text.slice(cut) });
+    return spans;
+  }
+
+  static isSafeHref(href: string) {
+    return !/^[a-z][a-z0-9+.-]*:/i.test(href) || /^(?:https?|mailto|tel):/i.test(href);
+  }
+
+  static plain(text: string): string {
+    return MarkdownSpans.of(text)
+      .map((span) => span.text)
+      .join("");
+  }
+}

package/common/markdownTable.ts

@@ -0,0 +1,50 @@
+export type Align = "left" | "center" | "right";
+
+export interface TableBlock {
+  kind: "table";
+  aligns: (Align | null)[];
+  head: string[];
+  rows: string[][];
+}
+
+const cellSplit = /(?<!\\)\|/;
+const delimiter = /^:?-+:?$/;
+
+export class MarkdownTable {
+  static at(lines: string[], at: number): { block: TableBlock; next: number } | null {
+    const header = lines[at];
+    const aligns = MarkdownTable.#aligns(lines[at + 1]);
+    if (!header?.includes("|") || !aligns) return null;
+    const head = MarkdownTable.#cells(header);
+    const rows: string[][] = [];
+    let next = at + 2;
+    for (; next < lines.length; next += 1) {
+      const line = lines[next];
+      if (!line.trim() || !line.includes("|")) break;
+      const cells = MarkdownTable.#cells(line);
+      
+      rows.push(head.map((_, idx) => cells[idx] ?? ""));
+    }
+    return { block: { kind: "table", aligns, head, rows }, next };
+  }
+
+  static #cells(line: string): string[] {
+    return line
+      .trim()
+      .replace(/^\|/, "")
+      .replace(/(?<!\\)\|$/, "")
+      .split(cellSplit)
+      .map((cell) => cell.trim().replace(/\\\|/g, "|"));
+  }
+
+  static #aligns(line: string | undefined): (Align | null)[] | null {
+    if (!line?.includes("|")) return null;
+    const cells = MarkdownTable.#cells(line);
+    if (!cells.every((cell) => delimiter.test(cell))) return null;
+    return cells.map((cell) => {
+      const closed = cell.endsWith(":");
+      if (cell.startsWith(":")) return closed ? "center" : "left";
+      return closed ? "right" : null;
+    });
+  }
+}

package/common/mcpExposure.ts

@@ -1,15 +1,5 @@
 import { capitalize } from "./capitalize";
 
-/**
- * What MCP says about one endpoint: whether it is published, why it is not, and the hints it carries.
- *
- * Structurally typed like the rest of `common/` so the same rules answer on both sides — the server builds its
- * catalogue from them and the browser API explorer badges an endpoint from them. A second implementation would
- * eventually disagree, and an audit surface that disagrees with the catalogue is worse than none.
- *
- * Every rejection returns the sentence an author reads, at boot in the server log and in the explorer. Fail-closed
- * with no reason leaves an author whose endpoint is missing from the catalogue nowhere to look but the source.
- */
 export interface McpExposureEndpoint {
   type: string;
   returns: { refName: string };
@@ -22,20 +12,15 @@ export interface McpExposureEndpoint {
 }
 
 export interface McpExposureOption {
-  /** The model the endpoint belongs to and the name it is published under: one rule reads the key, not the shape. */
   refName: string;
   key: string;
-  /**
-   * The read-only deployment valve, which is server configuration. The browser explorer cannot know it and so
-   * badges what the code decided; the boot log is where a read-only deployment says what it dropped.
-   */
+  /** The read-only deployment valve: server configuration the browser explorer cannot know. */
   readOnly?: boolean;
 }
 
-/** `Any` publishes as the empty schema, which tells a model nothing — so it is left out rather than described. */
+/** `Any` publishes as the empty schema, which tells a model nothing, so it is left out. */
 export const isMcpDescribableArg = (arg: { refName: string }) => arg.refName !== "Any";
 
-/** Which CRUD verb a generated endpoint key is, or `null` when the key is not one of the five. */
 export const mcpBaseVerbOf = (refName: string, key: string) => {
   const cap = capitalize(refName);
   if (key === refName || key === `light${cap}`) return "get" as const;
@@ -45,11 +30,7 @@ export const mcpBaseVerbOf = (refName: string, key: string) => {
   return null;
 };
 
-/**
- * The hints a client renders beside a tool. Hints only — clients are told to distrust them, so they inform a UI
- * and never stand in for a guard. `openWorldHint` is always false: every endpoint reaches this app's own
- * database, not the wider internet.
- */
+/** Hints never stand in for a guard; `openWorldHint` is false: every endpoint reaches this app's own database. */
 export const mcpHintsOf = (key: string, endpoint: { type: string }) => {
   const readOnly = endpoint.type === "query";
   const destructive = !readOnly && /^(remove|delete)/.test(key);
@@ -61,21 +42,17 @@ export const mcpHintsOf = (key: string, endpoint: { type: string }) => {
   };
 };
 
-/** The sentence explaining why this endpoint is not in the catalogue, or `null` when it is. */
 export const mcpRefusalOf = (
   endpoint: McpExposureEndpoint,
   { refName, key, readOnly }: McpExposureOption,
 ): string | null => {
-
   if (endpoint.mcp === false)
     return "it declares `mcp: false`, so it is deliberately off the agent shelf. HTTP still serves it.";
-
+  
   if (endpoint.agents === false)
     return `its guards (${(endpoint.guards ?? []).join(", ")}) admit no agent — an act reserved for a person, so it is off the agent shelf. HTTP still serves it.`;
-
   if (!endpoint.guards?.length)
     return "it declares no guards, and exposure follows them — write `guards: [Public]` if anonymous access is the intent.";
-
   if (key === `light${capitalize(refName)}`)
     return `it reads the same document as \`${refName}\` in a smaller shape — call \`${refName}\` instead.`;
   if (endpoint.type === "pubsub" || endpoint.type === "message")

package/common/objectPath.ts

@@ -0,0 +1,67 @@
+type PathSegment = string | number;
+type Indexable = Record<PathSegment, unknown>;
+type Container = Indexable | Map<PathSegment, unknown>;
+
+export const isIndexable = (value: unknown): value is Indexable => Object(value) === value;
+
+const readChild = (container: Container, key: PathSegment) =>
+  container instanceof Map ? container.get(key) : container[key];
+
+const writeChild = (container: Container, key: PathSegment, value: unknown) => {
+  if (container instanceof Map) container.set(key, value);
+  else container[key] = value;
+};
+
+/** `a.0.b` and `a[0].b` are the same segments, for writes and reads alike. */
+export const toPathSegments = (path: string | readonly PathSegment[]) =>
+  Array.isArray(path) ? [...path] : path.toString().match(/[^.[\]]+/g) || [];
+
+export const pathGet = (
+  path: string | (string | number)[],
+  obj: unknown,
+  separator = ".",
+  fallback: unknown = null,
+): unknown => {
+  
+  const properties = separator === "." ? toPathSegments(path) : Array.isArray(path) ? [...path] : path.split(separator);
+  return properties.reduce<unknown>(
+    (prev, curr) => (isIndexable(prev) ? (readChild(prev, curr) ?? fallback) : fallback),
+    obj,
+  );
+};
+
+export const pathSet = <T>(obj: T, path: string | readonly PathSegment[], value: unknown): T => {
+  if (Object(obj) !== obj) return obj;
+  const pathSegments = toPathSegments(path);
+  const parent = pathSegments.slice(0, -1).reduce<Container>((a, c, i) => {
+    const child = readChild(a, c);
+    if (Object(child) === child) return child as Container;
+    const created = Math.abs(Number(pathSegments[i + 1])) >> 0 === +pathSegments[i + 1] ? [] : {};
+    writeChild(a, c, created);
+    return created as unknown as Container;
+  }, obj as Container);
+  writeChild(parent, pathSegments[pathSegments.length - 1], value);
+  return obj;
+};
+
+/** Also tries joined prefixes, for keys whose segments contain the separator (an enum value like `gpt-5.6-terra`). */
+export const pathGetLoose = (
+  path: string | readonly string[],
+  obj: unknown,
+  separator = ".",
+  fallback: unknown = null,
+): unknown => {
+  const walk = (node: unknown, rest: readonly string[]): unknown => {
+    if (!rest.length) return node;
+    if (!isIndexable(node)) return undefined;
+    
+    for (let take = 1; take <= rest.length; take += 1) {
+      const child = node[rest.slice(0, take).join(separator)];
+      if (child === undefined) continue;
+      const found = walk(child, rest.slice(take));
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+  return walk(obj, Array.isArray(path) ? [...path] : (path as string).split(separator)) ?? fallback;
+};

package/common/objectify.ts

@@ -1,3 +1,5 @@
+import { isDayjs } from "./isDayjs";
+
 export const objectify = <T extends object>(obj: T, keys = Object.keys(obj) as (keyof T)[]): Partial<T> => {
   const val: Partial<T> = {};
   keys.forEach((key) => {
@@ -5,3 +7,53 @@ export const objectify = <T extends object>(obj: T, keys = Object.keys(obj) as (
   });
   return val;
 };
+
+export const plainFieldsOf = (source: object): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (const key in source) {
+    const value = (source as Record<string, unknown>)[key];
+    if (typeof value !== "function") out[key] = value;
+  }
+  return out;
+};
+
+interface DeepObjectifyOption {
+  serializable?: boolean;
+  convertDate?: "string" | "number";
+}
+
+const objectifyChild = (value: unknown, option: DeepObjectifyOption): unknown => {
+  const modelValue = value as { __ModelType__?: string } | null | undefined;
+  return modelValue?.__ModelType__ && !option.serializable ? value : deepObjectify(value, option);
+};
+
+export const deepObjectify = <T = unknown>(obj: T | null | undefined, option: DeepObjectifyOption = {}): T => {
+  if (isDayjs(obj) || obj?.constructor === Date) {
+    if (!option.serializable && !option.convertDate) return obj as T;
+    if (option.convertDate === "string") return obj.toISOString() as T;
+    else if (option.convertDate === "number")
+      return (isDayjs(obj) ? obj.toDate().getTime() : (obj as Date).getTime()) as T;
+    else return (isDayjs(obj) ? obj.toDate() : obj) as T;
+  } else if (Array.isArray(obj)) {
+    return obj.map((o: unknown) => deepObjectify(o, option)) as T;
+  } else if (obj instanceof Map) {
+    
+    const entries = [...obj.entries()].map(
+      ([key, value]: [string, unknown]) => [key, objectifyChild(value, option)] as const,
+    );
+    return (option.serializable ? Object.fromEntries(entries) : new Map(entries)) as T;
+  } else if (obj instanceof Set) {
+    const values = [...obj.values()].map((value: unknown) => objectifyChild(value, option));
+    return (option.serializable ? values : new Set(values)) as T;
+  } else if (obj && typeof obj === "object") {
+    const val: Record<string, unknown> = {};
+    const objRecord = obj as Record<string, unknown>;
+    
+    for (const key in objRecord) {
+      if (typeof objRecord[key] !== "function") val[key] = objectifyChild(objRecord[key], option);
+    }
+    return val as T;
+  } else {
+    return obj as unknown as T;
+  }
+};

package/common/phone.ts

@@ -0,0 +1,14 @@
+export const isPhoneNumber = (phone?: string | null) => {
+  if (!phone) return false;
+  const comp = phone.startsWith("0") ? phone.slice(1) : phone;
+  const regExp1 = /^\(?([0-9]{2})\)?[-. ]?([0-9]{4})[-. ]?([0-9]{4})$/;
+  const regExp2 = /^\(?([0-9]{2})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/;
+  return (regExp1.test(comp) || regExp2.test(comp)) && phone.split("-").length === 3;
+};
+
+export const formatPhone = (value: string) => {
+  if (!value) return "";
+  if (value.length === 10) return value.replace(/(\d{3})(\d{3})(\d{4})/, "$1-$2-$3");
+  else if (value.length === 13) return value.replace(/-/g, "").replace(/(\d{3})(\d{4})(\d{4})/, "$1-$2-$3");
+  else return value;
+};

package/common/randomPick.ts

@@ -1 +1,14 @@
 export const randomPick = <T = unknown>(arr: T[] | readonly T[]): T => arr[Math.floor(Math.random() * arr.length)];
+
+export const randomPicks = <T>(arr: T[] | readonly T[], count = 1, allowDuplicate = false): T[] => {
+  if (!allowDuplicate && arr.length <= count) return arr as T[];
+  const idxs: number[] = [];
+  let pickIdx: number;
+  for (let i = 0; i < count; i++) {
+    do {
+      pickIdx = Math.floor(Math.random() * arr.length);
+    } while (!allowDuplicate && idxs.includes(pickIdx));
+    idxs.push(pickIdx);
+  }
+  return idxs.map((idx) => arr[idx]);
+};

package/common/requestOrigin.ts

@@ -1,7 +1,3 @@
-/**
- * The origin a caller actually saw, and whether a body claims to be JSON. Both read only headers and a URL, so
- * they answer the same way for the cache layer, the CSRF gate, and anything else that has to compare origins.
- */
 export const originFromRequest = (headers: Headers, url: URL): string => {
   
   const forwardedProto = headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
@@ -16,22 +12,9 @@ export const originFromRequest = (headers: Headers, url: URL): string => {
   return url.origin;
 };
 
-/**
- * The host a caller addressed, which — unlike the scheme — every proxy that rewrites the request still reports.
- * `Host` is set by the browser from the URL it was told to open, so it names *this* deployment even for a
- * request some other page initiated.
- */
 export const hostFromRequest = (headers: Headers, url: URL): string =>
   headers.get("x-forwarded-host")?.split(",")[0]?.trim() ?? headers.get("host")?.split(",")[0]?.trim() ?? url.host;
 
-/**
- * Whether a request body may be read as JSON.
- *
- * `Request.json()` parses whatever bytes it holds regardless of this header, and the three content types a
- * cross-site form can send — `text/plain`, `application/x-www-form-urlencoded`, `multipart/form-data` — are
- * exactly the ones a browser sends with **no preflight**. Requiring the JSON type is therefore what puts a
- * preflight in front of every mutation that carries a body.
- */
 export const isJsonContentType = (contentType: string | null): boolean => {
   if (!contentType) return false;
   const essence = contentType.split(";")[0]?.trim().toLowerCase() ?? "";

package/common/restClient.ts

@@ -1,10 +1,3 @@
-/**
- * A plain REST client for a service that is not an Akan API: base url, headers, timeout, JSON in and out.
- *
- * Not `akanjs/fetch`'s `HttpClient`, which builds an Akan endpoint's path from its serialized args and restores
- * an `Err` from the response. Two classes of the same name in one package meant an app importing both barrels
- * got a collision, so this one is named for what it is.
- */
 export interface RestClientOptions {
   baseUrl?: string;
   headers?: HeadersInit;
@@ -94,12 +87,14 @@ export class RestClient {
 
   #makeBody(data: unknown): { body?: BodyInit; headers?: HeadersInit } {
     if (data === undefined) return {};
-    if (data instanceof FormData) return { body: data };
-    if (typeof data === "string") return { body: data };
-    if (data instanceof URLSearchParams) return { body: data };
-    if (data instanceof Blob) return { body: data };
-    if (data instanceof ArrayBuffer) return { body: data };
-
+    if (
+      typeof data === "string" ||
+      data instanceof FormData ||
+      data instanceof URLSearchParams ||
+      data instanceof Blob ||
+      data instanceof ArrayBuffer
+    )
+      return { body: data };
     return {
       body: JSON.stringify(data),
       headers: { "Content-Type": "application/json" },

package/common/round.ts

@@ -0,0 +1,4 @@
+export const round = (value: number, digits = 3): number => {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+};

package/common/routeConvention.ts

@@ -13,9 +13,7 @@ export const PAGE_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "default",
   "pageConfig",
   "head",
-  "metadata",
   "generateHead",
-  "generateMetadata",
   "Loading",
 ]);
 export const LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([...PAGE_ROUTE_EXPORTS, "NotFound", "Error"]);
@@ -27,7 +25,6 @@ export const ROOT_LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "reconnect",
   "wsConnect",
   "layoutStyle",
-  "gaTrackingId",
 ]);
 /** Root-layout exports that are plain config rather than components, so a PascalCase check cannot allow them. */
 export const RESERVED_ROUTE_CONFIG_EXPORTS: ReadonlySet<string> = new Set(
@@ -61,22 +58,19 @@ export interface ValidatePageSourceFileOptions {
   filePath?: string;
 }
 
+const toRouteKey = (filePath: string) =>
+  filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
+
 export function isRouteSourceFile(filePath: string): boolean {
   if (!SOURCE_EXT_RE.test(filePath)) return false;
-  const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
-  return tryParseRouteModuleKey(key) !== null;
+  return tryParseRouteModuleKey(toRouteKey(filePath)) !== null;
 }
 
-/**
- * Why a `page/` file breaks the route convention, or null when it is fine. Null also covers a non-source
- * asset, which `page/` tolerates. `akan sync <lib>` reports these alongside its other layout violations,
- * so the rule stays in one place instead of being restated where it cannot afford to throw.
- */
+/** `null` when the file is fine, including a non-source asset, which `page/` tolerates. */
 export function getPageSourceFileViolation(filePath: string): string | null {
   if (!SOURCE_EXT_RE.test(filePath)) return null;
 
-  const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
-  const match = ROUTE_SOURCE_RE.exec(key);
+  const match = ROUTE_SOURCE_RE.exec(toRouteKey(filePath));
   if (!match) return "invalid page source file";
 
   const file = match[1] as string;
@@ -96,8 +90,7 @@ export function validatePageSourceFile(filePath: string, options: ValidatePageSo
 
   const violation = getPageSourceFileViolation(filePath);
   if (!violation) return true;
-  const key = filePath.startsWith("./") ? filePath : `./${filePath.split(/[\\/]/).join("/")}`;
-  throw new Error(`[route-convention] ${violation}: ${options.filePath ?? key}`);
+  throw new Error(`[route-convention] ${violation}: ${options.filePath ?? toRouteKey(filePath)}`);
 }
 
 export function validateSubRoutePageKey(
@@ -222,6 +215,20 @@ export function matchRoutePattern(pattern: string, pathname: string): Record<str
   return params;
 }
 
+export function matchRoutePrefix(pattern: string, pathname: string): Record<string, string> | null {
+  const patternParts = pattern.split("/").filter(Boolean);
+  const pathParts = pathname.split("/").filter(Boolean);
+  if (patternParts.length > pathParts.length) return null;
+  const params: Record<string, string> = {};
+  for (let i = 0; i < patternParts.length; i++) {
+    const pat = patternParts[i];
+    const val = pathParts[i];
+    if (pat.startsWith(":")) params[pat.slice(1)] = decodeURIComponent(val);
+    else if (pat !== val) return null;
+  }
+  return params;
+}
+
 export function assertUniqueRoutePatterns(entries: { key: string; pattern: string }[]): void {
   const byPattern = new Map<string, string>();
   for (const entry of entries) {

package/common/sleep.ts

@@ -1,8 +1 @@
-/** Resolves after the requested delay in milliseconds. */
-export const sleep = async (ms: number) => {
-  return new Promise((resolve) => {
-    setTimeout(() => {
-      resolve(true);
-    }, ms);
-  });
-};
+export const sleep = async (ms: number) => new Promise((resolve) => setTimeout(() => resolve(true), ms));

package/common/subRoute.ts

@@ -14,13 +14,11 @@ export const parseBasePaths = (value: string | string[] | Set<string> | undefine
 
 const normalizeSubRouteHost = (host: string): string => host.trim().toLowerCase().replace(/:\d+$/, "");
 
-/** A hostname never contains these; a fragment carrying one is a malformed entry, not a host we failed to match. */
 const isSubRouteHost = (host: string): boolean => host.length > 0 && !/[\s/=]/.test(host);
 
 /**
- * `"soft=a.com,b.com;office=c.com"` -> `{ soft: ["a.com", "b.com"], office: ["c.com"] }`. A deployment platform
- * renders this value, so a malformed entry is skipped rather than thrown: one bad character must not CrashLoop
- * every pod that received it.
+ * `"soft=a.com,b.com;office=c.com"` -> `{ soft: ["a.com", "b.com"], office: ["c.com"] }`. A malformed entry is
+ * skipped, not thrown: a deployment platform renders this value, and one bad character must not CrashLoop pods.
  */
 export const parseSubRouteHosts = (value: string | undefined | null): Record<string, string[]> => {
   const hostsByBasePath: Record<string, string[]> = {};
@@ -44,9 +42,8 @@ export const parseSubRouteHosts = (value: string | undefined | null): Record<str
 };
 
 /**
- * Unions the env mapping onto the one baked into the build artifact, never replacing it — dropping the env is the
- * rollback path. A basePath the build does not serve is reported back instead of honoured: the route tree is a
- * build output, so accepting one would answer every request under it with a 404 and nothing to explain why.
+ * Unions the env mapping onto the build's own, never replacing it (dropping the env is the rollback path). A basePath
+ * the build does not serve is reported back, not honoured: the route tree is a build output.
  */
 export const resolveSubRouteHosts = ({
   subRoutes,

package/common/toError.ts

@@ -0,0 +1 @@
+export const toError = (reason: unknown): Error => (reason instanceof Error ? reason : new Error(String(reason)));