babavoss 0.0.1 → 0.0.2

package/src/desktop/index.ts

@@ -0,0 +1,323 @@
+// An optional shell, composed into the same state as the project's systems.
+// Configuration is code; all changing state is owned by this system.
+//
+// The model is small and the same at every door: an app is a kind the baba
+// registers; a window is one instance of it in a session, at a path; the
+// session shows one window, or nothing, and then the page shows its launcher.
+// Closing the window in front brings its neighbour forward, the one to its left
+// on the bar, else the one to its right, as a browser does. Opening is one verb,
+// `desktop-open`: it brings the window at that path to the front, else the
+// app's current window, else makes one; asked for a `fresh` window, an app
+// declared `many` gets another, any other app gives the one it has. The
+// launcher, a link in an app, the page's address, the CLI and another system's
+// ask all go through it, which is how workflows compose from one rule. A
+// window also remembers what its app asks it to, so an app keeps its state
+// per window in the state. A browser tab owns a session,
+// named by the system when the tab enters with no name, and the tab keeps the
+// key in its own storage, so a reload lands back in it; a link with
+// `?session=KEY` joins it. A call that names no session reaches the current one, the last
+// touched, so the CLI's `desktop-open` lands in the tab last used; a session
+// left empty for a day goes on its own. The theme is the baba's, one resource,
+// not a session's. The launcher is the page's: it shows while its search has
+// focus, or while nothing is in front. An app's icon is a Lucide name; the
+// system reads its drawing from the baba's Lucide package once and keeps it on
+// the app, so every door draws the same icon. An app may declare its routes,
+// the paths its windows may be at; a path none of them takes is refused.
+import { accept, effect, resource } from "../ecs/baba.ts";
+import { system, type ReaderOf, type StateOf } from "../ecs/system.ts";
+import { iconName, iconTags, readIcon } from "./icons.ts";
+import { canonicalPath, matchRoute } from "./routes.ts";
+import { s } from "../kernel/schema.ts";
+import type { Value } from "../ecs/state.ts";
+
+export const themes = ["system", "light", "dark"] as const;
+export type Theme = typeof themes[number];
+/** How long a session with nothing open is kept untouched: a day. */
+export const SESSION_IDLE = 24 * 60 * 60 * 1000;
+/** Sessions are named after trees, in this order, the first not taken; a name a person can read in a list and say. */
+export const sessionNames = [
+  "oak", "ash", "elm", "fir", "yew", "pine", "birch", "cedar", "maple", "willow", "alder", "aspen", "beech", "hazel", "holly", "larch",
+  "linden", "rowan", "spruce", "poplar", "olive", "palm", "plum", "pear", "fig", "lime", "teak", "ebony", "walnut", "chestnut", "cypress", "juniper",
+  "laurel", "magnolia", "myrtle", "sequoia", "sycamore", "acacia", "baobab", "ginkgo",
+] as const;
+export type { AppSpec } from "../ecs/baba.ts";
+export { route, matchRoute, canonicalPath, type RouteParams, type RouteMatch } from "./routes.ts";
+import type { AppSpec } from "../ecs/baba.ts";
+/** The old name. */
+export type Surface = AppSpec;
+export interface DesktopOptions {
+  apps?: readonly AppSpec[];
+  /** The old name of `apps`. */
+  surfaces?: readonly AppSpec[];
+  /** No longer read: there is no dock. Accepted for one release. */
+  dock?: { edge?: string; size?: number };
+}
+export function desktop(options: DesktopOptions) {
+  const catalog = (options.apps ?? options.surfaces ?? []).map((v, order) => ({ key: v.key, title: v.title, group: v.group ?? "", icon: v.icon ?? "", many: v.many ?? false, order, routes: [...(v.routes ?? [])] }));
+  if (new Set(catalog.map((v) => v.key)).size !== catalog.length || catalog.some((v) => !/^[a-z][a-z0-9-]*$/.test(v.key))) throw new Error("desktop app keys must be unique lowercase names");
+  const sessionArg = { session: s.optional(s.string()) };
+  const routeArg = { ...sessionArg, app: s.string(), path: s.optional(s.string()), fresh: s.optional(s.boolean()) };
+  const windowArg = { ...sessionArg, window: s.optional(s.entity("desktopWindow")) };
+  const appShape = { key: s.key(s.string()), title: s.string(), group: s.string(), icon: s.string(), many: s.boolean(), order: s.integer(), routes: s.optional(s.array(s.string())) };
+  /** A session: the window in front and when it was last touched. `theme` is no longer read, it is the baba's resource now; kept for one release so an older state fits. */
+  const sessionShape = {
+    key: s.key(s.string()), selected: s.nullable(s.entity()), theme: s.enum(...themes), touched: s.optional(s.integer()),
+  };
+  const settingsShape = { theme: s.enum(...themes) };
+  /** One instance of an app in a session: where it is, the title its app gave it, what its app asked it to remember. Windows are in the order they were opened. */
+  const windowShape = { session: s.entity(), app: s.entity(), path: s.string(), title: s.string(), memory: s.object({}, { open: true }) };
+  return system({
+    name: "desktop",
+    model: {
+      desktopApp: appShape,
+      desktopSession: sessionShape,
+      desktopWindow: windowShape,
+      desktopAsk: accept(routeArg),
+      desktopAnswer: { session: s.nullable(s.entity()), error: s.nullable(s.string()) },
+      /** An app's icon, drawn: the shapes of the Lucide icon its `icon` names, none when the baba has no such icon. */
+      desktopIcon: { name: s.string(), shapes: s.array(s.object({ tag: s.enum(...iconTags), attrs: s.object({}, { open: true }) })) },
+      /** The baba's settings, the same on every page: its theme. */
+      desktopSettings: resource(settingsShape, { theme: "system" }),
+    },
+    effects: {
+      desktopIconRead: effect({
+        summary: "a Lucide icon's shapes, read from the baba's lucide-static or lucide-react; none when neither has it",
+        args: s.object({ name: s.string() }),
+        retry: 30_000,
+        result: s.object({ name: s.string(), shapes: s.array(s.object({ tag: s.enum(...iconTags), attrs: s.object({}, { open: true }) })) }),
+        run: async ({ name }, ctx) => ({ name, shapes: await readIcon(name, ctx.fs) }),
+      }),
+    },
+  }, (desktop, p) => {
+    type W = StateOf<typeof desktop>;
+    /** The state as the state query reads it: helpers it shares take this. */
+    type R = ReaderOf<typeof desktop>;
+    const { desktopApp: app, desktopSession: session, desktopWindow: window, desktopAsk: ask, desktopAnswer: answer, desktopIcon: icon, desktopSettings: settings, desktopIconRead: iconReadEffect } = desktop;
+    type Win = { entity: number; desktopWindow: Value<typeof window> };
+    const touchedAt = (w: R, e: number) => w.get(e, session)?.touched ?? 0;
+    /** The current session: the one last touched, the latest made among equals; none before any tab has entered. */
+    function current(w: R): number | undefined {
+      let best: number | undefined;
+      for (const r of w.query(session)) if (best === undefined || touchedAt(w, r.entity) >= touchedAt(w, best)) best = r.entity;
+      return best;
+    }
+    /** A new session, named by the first tree not taken; past the trees, a tree with a number. */
+    function mint(w: W): number {
+      const taken = new Set(w.query(session).map((r) => r.desktopSession.key));
+      let key: string | undefined = sessionNames.find((n) => !taken.has(n));
+      for (let i = 2; key === undefined; i++) key = sessionNames.map((n) => `${n}-${i}`).find((n) => !taken.has(n));
+      return w.spawn(session, { key, selected: null, theme: "system", touched: w.now });
+    }
+    const touch = (w: W, e: number) => { w.add(e, session, { ...w.get(e, session)!, touched: w.now }); return e; };
+    /** The session a call means: the one named, made if missing; unnamed, the current one, or a first one. Only presence touches it: entering, opening, selecting, closing; an app naming or remembering does not. */
+    function ensure(w: W, key?: string) {
+      if (key === undefined) return current(w) ?? mint(w);
+      if (!key.trim()) throw new Error("session must have a name");
+      return w.find(session, key) ?? w.spawn(session, { key, selected: null, theme: "system", touched: w.now });
+    }
+    const windowsOf = (w: R, ws: number): Win[] => w.query(window).filter((r) => r.desktopWindow.session === ws);
+    function sync(w: W) {
+      for (const item of catalog) {
+        const e = w.find(app, item.key);
+        if (e === undefined) w.spawn(app, item);
+        else if (JSON.stringify(w.get(e, app)) !== JSON.stringify(item)) w.add(e, app, item);
+      }
+      for (const r of w.query(app)) if (!catalog.some((v) => v.key === r.desktopApp.key)) w.despawn(r.entity);
+      // An app declared `many` no longer keeps its earlier windows: the latest stays.
+      const seen = new Set<string>();
+      for (const r of [...w.query(window)].reverse()) {
+        const at = `${r.desktopWindow.session}:${r.desktopWindow.app}`;
+        const many = w.get(r.desktopWindow.app, app)?.many ?? false;
+        if (!w.has(r.desktopWindow.app, app) || !w.has(r.desktopWindow.session, session) || (!many && seen.has(at))) { w.despawn(r.entity); continue; }
+        seen.add(at);
+        // A window at a path its app's routes no longer take goes home: the state is fitted to the code.
+        const routes = w.get(r.desktopWindow.app, app)?.routes ?? [];
+        if (routes.length && !matchRoute(routes, r.desktopWindow.path)) w.add(r.entity, window, { ...r.desktopWindow, path: "/" });
+      }
+      const now = current(w);
+      for (const r of w.query(session)) {
+        const v = r.desktopSession;
+        // A theme chosen on a session before the theme was the baba's becomes the baba's, once.
+        if (v.theme !== "system") { if (w.get(settings).theme === "system") w.set(settings, { theme: v.theme }); w.add(r.entity, session, { ...v, theme: "system" }); }
+        if (v.selected !== null && !w.has(v.selected, window)) w.add(r.entity, session, { ...w.get(r.entity, session)!, selected: null });
+        // A session with nothing open that no tab has touched for a day goes; the current one stays, so a tab always has its session.
+        else if (v.selected === null && r.entity !== now && w.now - (v.touched ?? 0) > SESSION_IDLE && !windowsOf(w, r.entity).length) w.despawn(r.entity);
+      }
+      // No session is made here: every baba runs the shell, and one no page has entered keeps its state as its systems left it.
+    }
+    function show(w: W, e: number, win: number) {
+      w.add(e, session, { ...w.get(e, session)!, selected: win, touched: w.now });
+    }
+    /** The one way in: the window at that path, else the app's current one, else a new one; `fresh` makes another where the app allows many. */
+    function open(w: W, asked: { session?: string; app: string; path?: string; fresh?: boolean }) {
+      // Validate before making a session, including for asks (which are not actions).
+      const item = catalog.find((v) => v.key === asked.app);
+      if (!item) throw new Error(`unknown desktop app ${asked.app}`);
+      if (asked.path !== undefined && (!asked.path.startsWith("/") || asked.path.startsWith("//"))) throw new Error("an app path must start with one slash");
+      // One spelling of a path, the address's: a window is found by it whichever way the path was written.
+      const a = asked.path === undefined ? asked : { ...asked, path: canonicalPath(asked.path) };
+      if (a.path !== undefined && item.routes.length && !matchRoute(item.routes, a.path)) throw new Error(`${a.path} is not a path of ${a.app}; its routes: ${item.routes.join(", ")}`);
+      sync(w);
+      const e = ensure(w, a.session), target = w.find(app, item.key)!;
+      const ws = w.get(e, session)!;
+      const wins = windowsOf(w, e).filter((r) => r.desktopWindow.app === target);
+      let win = a.path !== undefined ? wins.find((r) => r.desktopWindow.path === a.path) : undefined;
+      if (!win && !(a.fresh && item.many)) win = wins.find((r) => r.entity === ws.selected) ?? wins.at(-1);
+      if (win) {
+        if (a.path !== undefined && win.desktopWindow.path !== a.path) w.add(win.entity, window, { ...win.desktopWindow, path: a.path });
+        show(w, e, win.entity);
+      } else {
+        show(w, e, w.spawn(window, { session: e, app: target, path: a.path ?? "/", title: "", memory: {} }));
+      }
+      return e;
+    }
+    /** A window of the session, the selected one unless named. */
+    function windowOf(w: W, e: number, id: number | undefined): Win {
+      const ws = w.get(e, session)!;
+      const target = id ?? ws.selected;
+      if (target === null || target === undefined) throw new Error(`no window is selected in ${ws.key}`);
+      const v = w.get(target, window);
+      if (!v || v.session !== e) throw new Error(`${target} is not a window of ${ws.key}`);
+      return { entity: target, desktopWindow: v };
+    }
+    return [
+      // An app whose icon is not drawn yet, or names another icon now, has it read; a name the baba has no icon for comes back with no shapes, and the app draws a dot.
+      p.on(iconReadEffect, {
+        for: (w) => w.query(app).filter((r) => iconName.test(r.desktopApp.icon) && w.get(r.entity, icon)?.name !== r.desktopApp.icon).map((r) => [r.entity, { name: r.desktopApp.icon }] as const),
+        // Filed under the name it was read for: a name changed meanwhile is read again.
+        done: (w, e, r) => { if (e !== null && w.has(e, app)) w.add(e, icon, { name: r.name, shapes: r.shapes }); },
+      }),
+
+      // Only a shell something has entered is kept in step each round: every baba runs it, and one never entered adds nothing to its state.
+      p.step("reconcile", (w) => { if (w.query(session).length) sync(w); }),
+
+      p.step("requests", (w) => {
+        for (const r of w.query(ask)) {
+          try { w.add(r.entity, answer, { session: open(w, r.desktopAsk), error: null }); }
+          catch (error) { w.add(r.entity, answer, { session: null, error: String(error) }); }
+          w.remove(r.entity, ask);
+        }
+      }),
+
+      p.action("desktop-open", {
+        summary: "open an app at a path: the window already there, else the app's current window, else a new one; `fresh` opens another where the app allows many", args: routeArg, result: s.entity(),
+        run: (w, a) => open(w, a),
+      }),
+
+      p.action("desktop-select", {
+        summary: "bring a window to the front", args: { ...sessionArg, window: s.entity("desktopWindow") }, result: s.entity(),
+        run: (w, a) => {
+          sync(w); const e = ensure(w, a.session); const win = windowOf(w, e, a.window); show(w, e, win.entity); return e;
+        },
+      }),
+
+      p.action("desktop-close", {
+        summary: "close a window, the selected one unless named; closing the one in front brings the window to its left forward, else the one to its right, else nothing, and the page shows its launcher", args: windowArg, result: s.entity(),
+        run: (w, a) => {
+          sync(w); const e = ensure(w, a.session); const ws = w.get(e, session)!;
+          const win = windowOf(w, e, a.window);
+          const order = windowsOf(w, e), at = order.findIndex((r) => r.entity === win.entity);
+          const next = order[at - 1] ?? order[at + 1];
+          w.despawn(win.entity);
+          w.add(e, session, { ...ws, selected: ws.selected === win.entity ? next?.entity ?? null : ws.selected, touched: w.now });
+          return e;
+        },
+      }),
+
+      p.action("desktop-title", {
+        summary: "name a window after what its app shows, the selected one unless named", args: { ...windowArg, title: s.string() }, result: s.entity(),
+        run: (w, a) => {
+          sync(w); const e = ensure(w, a.session); const win = windowOf(w, e, a.window);
+          if (win.desktopWindow.title !== a.title) w.add(win.entity, window, { ...win.desktopWindow, title: a.title });
+          return win.entity;
+        },
+      }),
+
+      p.action("desktop-remember", {
+        summary: "keep a value on a window for its app, the selected window unless named; null forgets the key", args: { ...windowArg, key: s.string(), value: s.unknown() }, result: s.entity(),
+        run: (w, a) => {
+          sync(w); const e = ensure(w, a.session); const win = windowOf(w, e, a.window);
+          const memory = { ...(win.desktopWindow.memory as Record<string, unknown>) };
+          if (a.value === null || a.value === undefined) delete memory[a.key]; else memory[a.key] = a.value;
+          w.add(win.entity, window, { ...win.desktopWindow, memory });
+          return win.entity;
+        },
+      }),
+
+      p.action("desktop-enter", {
+        summary: "enter a session: the session named, made if it is missing, else a new one with a name of its own; a tab enters on load and on focus, so the session it is on is the current one", args: sessionArg, result: s.entity(),
+        run: (w, a) => {
+          sync(w); return touch(w, a.session === undefined ? mint(w) : ensure(w, a.session));
+        },
+      }),
+
+      p.action("desktop-leave", {
+        summary: "end a session: its windows close and the session goes; the current one unless named", args: sessionArg, result: s.entity(),
+        run: (w, a) => {
+          sync(w); const e = ensure(w, a.session);
+          for (const r of windowsOf(w, e)) w.despawn(r.entity);
+          w.despawn(e);
+          return e;
+        },
+      }),
+
+      p.action("desktop-settings", {
+        summary: "set the baba's theme, the same on every page", args: { ...sessionArg, theme: s.optional(s.enum(...themes)) },
+        run: (w, a) => {
+          sync(w); if (a.theme) w.set(settings, { theme: a.theme });
+        },
+      }),
+
+      p.query("desktop-state", {
+        summary: "a session, the current one unless named: its record, apps and windows; every session beside it, last touched first; the theme", args: sessionArg,
+        result: s.object({
+          entity: s.nullable(s.entity()), session: s.nullable(s.object(sessionShape)), apps: s.array(s.object({ entity: s.entity(), ...appShape })), windows: s.array(s.object({ entity: s.entity(), ...windowShape })),
+          sessions: s.array(s.object({ entity: s.entity(), key: s.string(), touched: s.integer(), windows: s.integer(), front: s.nullable(s.string()) })), theme: s.enum(...themes),
+        }),
+        read: (w, a) => {
+          const e = a.session === undefined ? current(w) : w.find(session, a.session);
+          const sessions = w.query(session).map((r) => {
+            const wins = windowsOf(w, r.entity), front = wins.find((o) => o.entity === r.desktopSession.selected);
+            const label = front ? front.desktopWindow.title || (front.desktopWindow.path === "/" ? w.get(front.desktopWindow.app, app)?.title ?? null : front.desktopWindow.path) : null;
+            return { entity: r.entity, key: r.desktopSession.key, touched: r.desktopSession.touched ?? 0, windows: wins.length, front: label };
+          }).sort((x, y) => y.touched - x.touched || y.entity - x.entity);
+          return { entity: e ?? null, session: e === undefined ? null : w.get(e, session)!, apps: w.query(app).map((r) => ({ entity: r.entity, ...r.desktopApp })), windows: e === undefined ? [] : windowsOf(w, e).map((r) => ({ entity: r.entity, ...r.desktopWindow })), sessions, theme: w.get(settings).theme };
+        },
+      }),
+    ];
+  });
+}
+export type DesktopSystem = ReturnType<typeof desktop>;
+/** voss's own apps, after every baba's: the Maker, the state, the contract, the know-how, the settings. An interface may give one its own component; a baba may not declare one. */
+export const vossApps = [
+  { key: "maker", title: "Maker", icon: "hammer", group: "Voss" },
+  { key: "state", title: "State", icon: "database", group: "Voss" },
+  { key: "contract", title: "Contract", icon: "square-terminal", group: "Voss" },
+  { key: "promptware", title: "Promptware", icon: "book-open-text", group: "Voss" },
+  { key: "settings", title: "Settings", icon: "settings", group: "Voss" },
+] as const satisfies readonly AppSpec[];
+export type VossApp = typeof vossApps[number]["key"];
+/** The app a baba that declares none has: its interface, whatever it is, in one window. */
+export const viewApp = { key: "view", title: "View", icon: "app-window" } as const satisfies AppSpec;
+/** The catalog the shell runs: the baba's apps, or its one view, then voss's. */
+export function catalogOf(apps: readonly AppSpec[]): AppSpec[] {
+  for (const v of apps) if (vossApps.some((b) => b.key === v.key)) throw new Error(`the app ${v.key} is voss's; to draw it otherwise, give it a component in compose, without declaring it`);
+  return [...(apps.length ? apps : [viewApp]), ...vossApps];
+}
+
+/** The shell's references, for a system that asks it to open an app (`w.add(e, shell.desktopAsk, …)`) and for an app's tests: the same names as the system voss runs. */
+export const shell = desktop({});
+export type Session = Value<DesktopSystem["desktopSession"]>;
+export type DesktopApp = Value<DesktopSystem["desktopApp"]>;
+/** The old name. */
+export type DesktopSurface = DesktopApp;
+export type DesktopWindow = Value<DesktopSystem["desktopWindow"]>;
+
+/** The apps whose title, key or group contain every word, in catalog order. */
+export function searchApps<T extends DesktopApp>(items: readonly T[], text: string): T[] {
+  const words = text.toLowerCase().trim().split(/\s+/).filter(Boolean);
+  return items.filter((s) => words.every((word) => `${s.title} ${s.key} ${s.group}`.toLowerCase().includes(word))).sort((a, b) => a.order - b.order);
+}
+
+/** The old name. */
+export const searchSurfaces = searchApps;

package/src/desktop/routes.ts

@@ -0,0 +1,98 @@
+// An app's routes: the paths its windows may be at, declared as data beside the app, so the desktop system
+// refuses a path no route takes, a system builds a path without importing the interface, and compose checks
+// a component for each. A pattern is segments after one slash: a literal, `:name` for one segment, and last
+// `*` for the rest, none or more. `/` is the app's home. Matching prefers literals to names, names to the rest.
+
+/** The parameters a pattern names, as `route` takes them. */
+export type RouteParams<P extends string> = Flat<Split<P extends `/${infer R}` ? R : P>>;
+type Seg<S extends string> = S extends `:${infer N}` ? { [K in N]: string | number } : S extends "*" ? { "*"?: string } : {};
+type Split<P extends string> = P extends `${infer A}/${infer B}` ? Seg<A> & Split<B> : Seg<P>;
+type Flat<T> = { [K in keyof T]: T[K] };
+
+/** A path matched: the pattern that took it, and its parameters, decoded. */
+export interface RouteMatch { route: string; params: Record<string, string> }
+
+const LITERAL = /^[A-Za-z0-9._~-]+$/, NAME = /^:[A-Za-z_][A-Za-z0-9_]*$/;
+const segments = (path: string) => path === "/" ? [] : path.slice(1).split("/");
+
+/** Why a pattern is not one, or null. */
+export function routeError(pattern: string): string | null {
+  if (!pattern.startsWith("/")) return `the route ${JSON.stringify(pattern)} must start with /`;
+  if (pattern !== "/" && pattern.endsWith("/")) return `the route ${pattern} must not end with /`;
+  const segs = segments(pattern), seen = new Set<string>();
+  for (const [i, s] of segs.entries()) {
+    if (s === "*") { if (i !== segs.length - 1) return `the route ${pattern}: * is only the last segment`; continue; }
+    if (NAME.test(s)) { if (seen.has(s)) return `the route ${pattern} names ${s} twice`; seen.add(s); continue; }
+    if (!LITERAL.test(s)) return `the route ${pattern}: ${JSON.stringify(s)} is neither a word, a :name nor *`;
+  }
+  return null;
+}
+
+/** Why a list of routes is not an app's, or null: each a pattern, none twice, and one of them takes `/`, the home. */
+export function routesError(routes: readonly string[]): string | null {
+  for (const r of routes) { const e = routeError(r); if (e) return e; }
+  if (new Set(routes).size !== routes.length) return "a route is declared twice";
+  if (routes.length && !matchRoute(routes, "/")) return "no route takes /, the app's home";
+  return null;
+}
+
+/** How specific a pattern is, segment by segment: a literal 2, a name 1, the rest -1; compared left to right, a pattern that has ended (0) before the rest, so `/files` takes `/files` from `/files/*`. */
+const rank = (pattern: string) => segments(pattern).map((s) => s === "*" ? -1 : s.startsWith(":") ? 1 : 2);
+function compare(a: number[], b: number[]) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) { const x = a[i] ?? 0, y = b[i] ?? 0; if (x !== y) return y - x; }
+  return 0;
+}
+
+/**
+ * A path in the one form the desktop keeps and the address shows: each segment decoded, then encoded, so `/task/a b`,
+ * `/task/a%20b` and the browser's spelling of either are one path. `.` and `..`, which a browser resolves away, are refused.
+ */
+export function canonicalPath(path: string): string {
+  if (path === "/") return path;
+  return "/" + path.slice(1).split("/").map((s) => {
+    let v = s;
+    try { v = decodeURIComponent(s); } catch { /* a malformed escape is kept as written, encoded */ }
+    if (v === "." || v === "..") throw new Error(`an app path has no . or .. segment: ${path}`);
+    return encodeURIComponent(v);
+  }).join("/");
+}
+
+/** The route that takes a path, the most specific; null when none does. A trailing slash is ignored. */
+export function matchRoute(routes: readonly string[], path: string): RouteMatch | null {
+  if (!path.startsWith("/")) return null;
+  const at = segments(path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path);
+  let best: { m: RouteMatch; rank: number[] } | null = null;
+  for (const route of routes) {
+    const pat = segments(route), params: Record<string, string> = {};
+    let ok = true;
+    try {
+      for (let i = 0; ok && i < pat.length; i++) {
+        const p = pat[i]!;
+        if (p === "*") { params["*"] = at.slice(i).map(decodeURIComponent).join("/"); break; }
+        if (i >= at.length) ok = false;
+        else if (p.startsWith(":")) { if (at[i] === "") ok = false; else params[p.slice(1)] = decodeURIComponent(at[i]!); }
+        else if (p !== at[i]) ok = false;
+      }
+    } catch { ok = false; }   // a malformed escape takes no route
+    if (ok && pat.at(-1) !== "*" && pat.length !== at.length) ok = false;
+    if (!ok) continue;
+    const r = rank(route);
+    if (!best || compare(r, best.rank) < 0) best = { m: { route, params }, rank: r };
+  }
+  return best?.m ?? null;
+}
+
+/** The path of a route with its parameters, each encoded: `route("/pr/:n", { n: 86 })` is `/pr/86`. */
+export function route<P extends string>(pattern: P, ...params: {} extends RouteParams<P> ? [RouteParams<P>?] : [RouteParams<P>]): string {
+  const e = routeError(pattern);
+  if (e) throw new Error(e);
+  const values = (params[0] ?? {}) as Record<string, string | number>;
+  const out = segments(pattern).flatMap((s) => {
+    if (s === "*") return String(values["*"] ?? "").split("/").filter(Boolean).map(encodeURIComponent);
+    if (!s.startsWith(":")) return [s];
+    const v = values[s.slice(1)];
+    if (v === undefined || v === "") throw new Error(`the route ${pattern} needs ${s}`);
+    return [encodeURIComponent(String(v))];
+  });
+  return canonicalPath("/" + out.join("/"));
+}