@greensecurity/javascript-sdk 0.46.0 → 0.47.0-beta.1

package/src/apps/manifest.ts

@@ -10,7 +10,16 @@
  */
 
 import * as z from "zod/v4";
-import { SURFACES } from "./surfaces.js";
+import {
+  APP_ROUTES_MAX,
+  CONCRETE_ROUTE_PATH_PATTERN,
+  isConcreteRoutePath,
+  matchAppRoute,
+  ROUTE_PATH_MAX_CHARS,
+  ROUTE_PATH_PATTERN,
+  routeSetIssues,
+} from "./routes.js";
+import { SURFACES, type Portal } from "./surfaces.js";
 import {
   CSP_SOURCE_MAX_CHARS,
   CSP_SOURCE_PATTERN,
@@ -37,6 +46,21 @@ export {
   isParsableHttpsUrl,
 } from "./url.js";
 
+// The route grammar and matcher live in the zod-free `routes.ts` for the same reason.
+export {
+  APP_ROUTES_MAX,
+  CONCRETE_ROUTE_PATH_PATTERN,
+  isConcreteRoutePath,
+  isRoutePath,
+  matchAppRoute,
+  normalizeRoutePath,
+  ROUTE_PATH_MAX_CHARS,
+  ROUTE_PATH_MAX_SEGMENTS,
+  ROUTE_PATH_PATTERN,
+  routeSetIssues,
+  type AppRouteMatch,
+  type RouteSetIssue,
+} from "./routes.js";
 
 /** A single SRI hash with the digest length its algorithm produces (32, 48 or 64 bytes, base64). */
 export const SRI_PATTERN = "^(sha256-[A-Za-z0-9+/]{43}=|sha384-[A-Za-z0-9+/]{64}|sha512-[A-Za-z0-9+/]{86}==)$";
@@ -78,7 +102,11 @@ const PLATFORM_PERMISSION_NAMES: ReadonlySet<string> = new Set(PLATFORM_PERMISSI
 export function isPlatformPermission(value: unknown): value is PlatformPermission {
   return typeof value === "string" && PLATFORM_PERMISSION_NAMES.has(value);
 }
-const SURFACE_IDS = SURFACES.map((s) => s.id) as [string, ...string[]];
+// A view's viewport. `page` is not one: an app declares its pages in `routes`, not in `views`.
+const SURFACE_IDS = SURFACES.filter((s) => s.kind !== "page").map((s) => s.id) as [string, ...string[]];
+
+/** Portals an app page may be offered in (`routes[].portals`). */
+const ROUTE_PORTALS = ["company", "vendor", "facility", "system"] as const satisfies readonly Portal[];
 
 /** Lifecycle events an app's own webhook endpoint can receive (see C19). */
 export const APP_WEBHOOK_EVENTS = [
@@ -148,6 +176,50 @@ export const appViewSchema = z.strictObject({
   component: z.string().max(100).regex(new RegExp(COMPONENT_NAME_PATTERN)),
 });
 
+/** Reports {@link routeSetIssues} (segment cap, repeated params, duplicate paths, repeated portals). */
+export function addRouteIssues(
+  routes: ReadonlyArray<{ path: string; portals?: readonly string[] | undefined; navigation?: unknown }> | undefined,
+  ctx: z.RefinementCtx,
+  path: ReadonlyArray<string | number>,
+): void {
+  for (const issue of routeSetIssues(routes ?? [])) {
+    ctx.addIssue({ code: "custom", path: [...path, issue.index, issue.field], message: issue.message });
+  }
+}
+
+/**
+ * One app page. The host renders `component` at `/{portal}/apps/{appId}/pages{path}`.
+ *
+ * `title` is required here, for new manifests. The server keeps accepting title-less entries in a
+ * bundle-less v1 manifest, which stored `routes[{ path, component }]` before pages were rendered;
+ * such a manifest has nothing to render them with, and the host never shows them.
+ */
+/**
+ * Text a person reads (a page title, a sidebar label): at least one character that isn't
+ * whitespace. The host never shows a blank one, so the manifest can't publish one.
+ *
+ * This is JavaScript's `\S` spelled out (ASCII whitespace, the Unicode space separators,
+ * U+2028/U+2029 and U+FEFF), because the generated schema's patterns also run as Ruby regexps, and
+ * Ruby's `\S` is ASCII-only: there, a title of no-break spaces would pass.
+ */
+export const NON_BLANK_PATTERN =
+  "[^\\t\\n\\v\\f\\r \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]";
+
+export const appRouteSchema = z.strictObject({
+  path: z.string().max(ROUTE_PATH_MAX_CHARS).regex(new RegExp(ROUTE_PATH_PATTERN)),
+  component: z.string().max(100).regex(new RegExp(COMPONENT_NAME_PATTERN)),
+  /** Page header title. */
+  title: z.string().min(1).max(100).regex(new RegExp(NON_BLANK_PATTERN), { message: "must not be blank" }),
+  /** Portals the page is offered in. Absent = every portal the host renders. */
+  portals: z.array(z.enum(ROUTE_PORTALS)).min(1).max(ROUTE_PORTALS.length).optional(),
+  /** Offer the page in the sidebar / mobile drawer menu under this label (default: `title`). */
+  navigation: z
+    .strictObject({
+      label: z.string().min(1).max(40).regex(new RegExp(NON_BLANK_PATTERN), { message: "must not be blank" }).optional(),
+    })
+    .optional(),
+});
+
 /** Constants are delivered to every view as `environment.constants`. */
 export const appConstantsSchema = z.record(
   z.string().max(100).regex(/^[A-Za-z_][A-Za-z0-9_]*$/),
@@ -192,21 +264,20 @@ export const appManifestSchema = z
           integrity: z.string().max(200).regex(new RegExp(SRI_PATTERN)),
         }).optional(),
         views: z.array(appViewSchema).max(200).optional(),
-        /** Reserved for a future FullPageView. Stored and validated, not rendered. */
-        routes: z
-          .array(z.strictObject({
-            path: z.string().max(200).regex(/^\/[a-z0-9\-/:]*$/),
-            component: z.string().max(100).regex(new RegExp(COMPONENT_NAME_PATTERN)),
-          }))
-          .max(50)
-          .optional(),
+        /** App pages, each a full screen under `/{portal}/apps/{appId}/pages`. */
+        routes: z.array(appRouteSchema).max(APP_ROUTES_MAX).optional(),
         csp: appCspSchema.optional(),
       })
       .optional(),
     post_install_action: z
       .strictObject({
-        type: z.enum(["url", "app_settings_view", "app_main_view"]),
+        type: z.enum(["url", "app_settings_view", "app_main_view", "app_page"]),
         url: httpsUrlSchema.optional(),
+        /**
+         * For `app_page` only: the page to open, a concrete path (no `:params`) that one of
+         * `ui_extensions.routes` matches, such as `/welcome` or `/reports/7`.
+         */
+        path: z.string().max(ROUTE_PATH_MAX_CHARS).regex(new RegExp(CONCRETE_ROUTE_PATH_PATTERN)).optional(),
       })
       .optional(),
     // The app's own webhook endpoint: registered by the catalog when the manifest is published, not
@@ -220,34 +291,54 @@ export const appManifestSchema = z
       .optional(),
   })
   .superRefine((manifest, ctx) => {
-    addDuplicateViewportIssues(manifest.ui_extensions?.views, ctx, ["ui_extensions", "views"]);
-    addCspBudgetIssue(manifest.ui_extensions?.csp, ctx, ["ui_extensions", "csp"]);
     const events = manifest.webhooks?.events ?? [];
     if (new Set(events).size !== events.length) {
       ctx.addIssue({ code: "custom", path: ["webhooks", "events"], message: "events must not repeat" });
     }
+    if (manifest.post_install_action?.type === "url" && !manifest.post_install_action.url) {
+      ctx.addIssue({ code: "custom", path: ["post_install_action", "url"], message: "url is required for type=url" });
+    }
+    if (manifest.post_install_action?.type !== "app_page" && manifest.post_install_action?.path !== undefined) {
+      ctx.addIssue({ code: "custom", path: ["post_install_action", "path"], message: "path is only allowed for type=app_page" });
+    }
 
-    if (manifest.ui_extensions?.views?.length && !manifest.ui_extensions.bundle) {
+    // When a field under `ui_extensions` fails its own schema, zod hands this refinement the
+    // manifest without `ui_extensions`, so every rule below would report a problem that isn't
+    // there (a missing settings view, an unmatched post-install page). Report the real one only.
+    if (ctx.issues.some((issue) => issue.path?.[0] === "ui_extensions")) return;
+
+    addDuplicateViewportIssues(manifest.ui_extensions?.views, ctx, ["ui_extensions", "views"]);
+    addRouteIssues(manifest.ui_extensions?.routes, ctx, ["ui_extensions", "routes"]);
+    addCspBudgetIssue(manifest.ui_extensions?.csp, ctx, ["ui_extensions", "csp"]);
+
+    const hasViews = Boolean(manifest.ui_extensions?.views?.length);
+    const hasRoutes = Boolean(manifest.ui_extensions?.routes?.length);
+    if (hasViews && !manifest.ui_extensions?.bundle) {
       ctx.addIssue({
         code: "custom",
         path: ["ui_extensions", "bundle"],
         message: "bundle is required when views are declared",
       });
     }
+    if (hasRoutes && !manifest.ui_extensions?.bundle) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["ui_extensions", "bundle"],
+        message: "bundle is required when routes are declared",
+      });
+    }
 
     // `version` stays optional only for legacy (v1) manifests. Anything the host renders needs one:
     // it names the runtime URL and reaches views as `ExtensionContext.app.version`.
-    if ((manifest.ui_extensions?.bundle || manifest.ui_extensions?.views?.length) && !manifest.version) {
+    if ((manifest.ui_extensions?.bundle || hasViews || hasRoutes) && !manifest.version) {
       ctx.addIssue({
         code: "custom",
         path: ["version"],
-        message: "version is required when ui_extensions declares a bundle or views",
+        message: "version is required when ui_extensions declares a bundle, views or routes",
       });
     }
 
-    if (manifest.post_install_action?.type === "url" && !manifest.post_install_action.url) {
-      ctx.addIssue({ code: "custom", path: ["post_install_action", "url"], message: "url is required for type=url" });
-    }
+    addAppPageActionIssues(manifest, ctx);
 
     // A back-end-only app has no views, so it cannot land installers on one. Checked only for
     // versioned (v2) manifests: v1 apps may carry a post-install view type from before views existed.
@@ -261,34 +352,67 @@ export const appManifestSchema = z
       });
     }
     // The settings page is not a main view: a settings-only app should land on app_settings_view.
-    const mainViewports = [...viewports].filter((v) => v !== "settings");
-    if (versioned && manifest.post_install_action?.type === "app_main_view" && mainViewports.length === 0) {
+    // A root page (route `/`) is one: installing opens `/{portal}/apps/{id}/pages`.
+    if (versioned && manifest.post_install_action?.type === "app_main_view" && !hasMainView(manifest)) {
       ctx.addIssue({
         code: "custom",
         path: ["post_install_action", "type"],
-        message: "app_main_view requires a view other than settings",
+        message: "app_main_view requires a view other than settings, or a root route",
       });
     }
   });
 
 export type AppManifestV2 = z.infer<typeof appManifestSchema>;
+export type AppRoute = z.infer<typeof appRouteSchema>;
+
+/**
+ * The rules for `post_install_action.path`: required for `app_page` and allowed nowhere else, a
+ * concrete path within the route limits, and one that a declared route matches (`/reports/7` for a
+ * `/reports/:id` route), so installing never opens a page the app does not have.
+ */
+function addAppPageActionIssues(
+  manifest: Pick<AppManifestV2, "post_install_action" | "ui_extensions">,
+  ctx: z.RefinementCtx,
+): void {
+  const action = manifest.post_install_action;
+  if (action === undefined) return;
+  const path = ["post_install_action", "path"];
+
+  // `path` on another type is reported by the manifest refinement, before the rules that need
+  // `ui_extensions`.
+  if (action.type !== "app_page") return;
+  if (action.path === undefined) {
+    ctx.addIssue({ code: "custom", path, message: "path is required for type=app_page" });
+  } else if (!isConcreteRoutePath(action.path)) {
+    ctx.addIssue({ code: "custom", path, message: "path must be a page path without :params, such as /reports/7" });
+  } else if (matchAppRoute(manifest.ui_extensions?.routes ?? [], action.path) === null) {
+    ctx.addIssue({ code: "custom", path, message: "path must match one of ui_extensions.routes" });
+  }
+}
+
+/** Whether a manifest has a main view to land on: a view other than settings, or a root page `/`. */
+function hasMainView(manifest: { ui_extensions?: AppManifestV2["ui_extensions"] }): boolean {
+  const views = manifest.ui_extensions?.views ?? [];
+  const routes = manifest.ui_extensions?.routes ?? [];
+  return views.some((v) => v.viewport !== "settings") || routes.some((r) => r.path === "/");
+}
 
 export type PostInstallAction = NonNullable<AppManifestV2["post_install_action"]>;
 
 /**
  * What installing the app does when `post_install_action` is left out, so the server and the host
  * never land an installer on a view the app does not have: nothing for a back-end-only app, the
- * settings page for a settings-only app, and the app's main view otherwise. `null` means
- * "no post-install step". An explicit action is returned unchanged.
+ * settings page for a settings-only app, and the app's main view otherwise. A root page (route
+ * `/`) counts as a main view. `null` means "no post-install step". An explicit action, including
+ * `app_page`, is returned unchanged.
  */
 export function effectivePostInstallAction(
   manifest: Pick<AppManifestV2, "post_install_action" | "ui_extensions">,
 ): PostInstallAction | null {
   if (manifest.post_install_action) return manifest.post_install_action;
 
-  const viewports = (manifest.ui_extensions?.views ?? []).map((v) => v.viewport);
-  if (viewports.some((v) => v !== "settings")) return { type: "app_main_view" };
-  if (viewports.includes("settings")) return { type: "app_settings_view" };
+  if (hasMainView(manifest)) return { type: "app_main_view" };
+  if ((manifest.ui_extensions?.views ?? []).some((v) => v.viewport === "settings")) return { type: "app_settings_view" };
   return null;
 }
 export type AppView = z.infer<typeof appViewSchema>;

package/src/apps/protocol.ts

@@ -30,7 +30,7 @@ export type RemoteMutationRecord =
   | readonly [type: 2, textId: string, text: string]
   | readonly [type: 3, id: string, name: string, value: unknown, updateType?: 1 | 2 | 3];
 
-export type ViewType = "context" | "focus" | "settings";
+export type ViewType = "context" | "focus" | "settings" | "page";
 
 /** Implemented inside the worker by the SDK runtime (`defineApp`). */
 export interface SandboxExports {

package/src/apps/route.ts

@@ -2,20 +2,28 @@
  * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
  * see docs/third-party-apps/plan.md.
  *
- * Apps never navigate by path. They name a destination and the host maps it to its own routes,
- * which keeps host URLs free to change and stops an app from steering users to arbitrary pages.
+ * Apps never navigate by host path. They name a destination and the host maps it to its own
+ * routes, which keeps host URLs free to change and stops an app from steering users to arbitrary
+ * pages. The one path an app writes, `appPage`, is a path inside its own pages space.
  */
 
-import { isSurfaceId, type SurfaceId } from "./surfaces.js";
+import { isConcreteRoutePath } from "./routes.js";
+import { getSurface, type SurfaceId } from "./surfaces.js";
 
-/** Values the destination view receives as `environment.queryParams`. Strings only. */
+/** Values the destination view receives as `environment.navParams`, never as `queryParams`. Strings only. */
 export type EnvParams = Record<string, string>;
 
 export type RouteDescriptor =
   /** The screen a surface lives on, optionally for one record (detail surfaces). */
   | { type: "surface"; surfaceId: SurfaceId; objectId?: number; envParams?: EnvParams }
   /** The calling app's own settings page (the `settings` surface). */
-  | { type: "appSettings"; envParams?: EnvParams };
+  | { type: "appSettings"; envParams?: EnvParams }
+  /**
+   * One of the calling app's own pages, by concrete path in the app's space (`/reports/7`, not
+   * `/reports/:id`). The host checks that it matches one of the app's routes offered in the
+   * current portal. There is no `appId`: an app can only open its own pages.
+   */
+  | { type: "appPage"; path: string; envParams?: EnvParams };
 
 export function isRouteDescriptor(value: unknown): value is RouteDescriptor {
   if (typeof value !== "object" || value === null || !("type" in value)) return false;
@@ -25,14 +33,18 @@ export function isRouteDescriptor(value: unknown): value is RouteDescriptor {
 
   switch (v["type"]) {
     case "surface":
-      // Only catalog surfaces: the host has no route for anything else. Safe integers only, so a
-      // record id is never silently rounded on its way through JSON. `settings` is reachable only
-      // as `appSettings`, which always means the calling app: as a plain surface its `objectId`
-      // would name another app's settings page.
-      return isSurfaceId(v["surfaceId"]) && v["surfaceId"] !== "settings" &&
+      // Only catalog surfaces of a portal: the host has no route for anything else. Safe integers
+      // only, so a record id is never silently rounded on its way through JSON. The portal-less
+      // surfaces belong to an app and are reachable only through descriptors that always mean the
+      // calling app (`appSettings`, `appPage`): as a plain surface, `objectId` would name another
+      // app's settings page or pages.
+      return typeof v["surfaceId"] === "string" && (getSurface(v["surfaceId"])?.portal ?? null) !== null &&
         (v["objectId"] === undefined || (Number.isSafeInteger(v["objectId"]) && (v["objectId"] as number) > 0));
     case "appSettings":
       return true;
+    case "appPage":
+      // Concrete paths only, in the route grammar: no params, dots, escapes or empty segments.
+      return isConcreteRoutePath(v["path"]);
     default:
       return false;
   }

package/src/apps/routes.ts

@@ -0,0 +1,230 @@
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/fullpageview-plan.md.
+ *
+ * App page routes (`ui_extensions.routes[]`): the path grammar, the uniqueness rule and the one
+ * matcher every consumer shares (the host, `apps-cli validate`, the contract tests). Deliberately
+ * dependency-free (no zod) so the host renderer can import it without bundling zod; `manifest.ts`
+ * re-exports it because it is part of the manifest contract.
+ *
+ * The server mirrors the grammar and `normalizeRoutePath` in Ruby and reads the same fixtures
+ * (`src/__tests__/apps/fixtures/routes.json`).
+ */
+
+/** A static segment: lower-case letters, digits and inner hyphens. */
+const STATIC_SEGMENT = "[a-z0-9](?:[a-z0-9-]*[a-z0-9])?";
+/** A param segment: `:` and a lower-case name. */
+const PARAM_SEGMENT = ":[a-z][a-z0-9_]*";
+
+/**
+ * A declared route path: `/`, or `/seg(/seg)*` where each segment is static or a `:param`. No dots,
+ * percent-escapes, upper case, empty segments or trailing slash, so no path can climb out of the
+ * app's own space. `pages` is not reserved inside that space: `/pages/foo` is an ordinary path.
+ */
+export const ROUTE_PATH_PATTERN =
+  "^/(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|:[a-z][a-z0-9_]*)(?:/(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|:[a-z][a-z0-9_]*))*)?$";
+
+/** A concrete path an app navigates to (`{ type: "appPage" }`): the same grammar without params. */
+export const CONCRETE_ROUTE_PATH_PATTERN = `^/(?:${STATIC_SEGMENT}(?:/${STATIC_SEGMENT})*)?$`;
+
+export const ROUTE_PATH_MAX_CHARS = 200;
+/** Segments in one path; `/` has none. */
+export const ROUTE_PATH_MAX_SEGMENTS = 8;
+/** Routes in one manifest. */
+export const APP_ROUTES_MAX = 50;
+
+/** What every param segment becomes in {@link normalizeRoutePath}. */
+const PARAM_PLACEHOLDER = ":_";
+
+const ROUTE_PATH_RE = new RegExp(ROUTE_PATH_PATTERN);
+const CONCRETE_ROUTE_PATH_RE = new RegExp(CONCRETE_ROUTE_PATH_PATTERN);
+const PARAM_SEGMENT_RE = new RegExp(`^${PARAM_SEGMENT}$`);
+
+/** The segments of a path in the grammar; `/` has none. */
+function segmentsOf(path: string): string[] {
+  return path === "/" ? [] : path.slice(1).split("/");
+}
+
+function withinLimits(path: string): boolean {
+  return path.length <= ROUTE_PATH_MAX_CHARS && segmentsOf(path).length <= ROUTE_PATH_MAX_SEGMENTS;
+}
+
+/** A declared route path: the {@link ROUTE_PATH_PATTERN} grammar, ≤ 200 characters and ≤ 8 segments. */
+export function isRoutePath(value: unknown): value is string {
+  return typeof value === "string" && ROUTE_PATH_RE.test(value) && withinLimits(value);
+}
+
+/** A concrete route path (no `:param` segments) within the same limits as a declared one. */
+export function isConcreteRoutePath(value: unknown): value is string {
+  return typeof value === "string" && CONCRETE_ROUTE_PATH_RE.test(value) && withinLimits(value);
+}
+
+/**
+ * Renames every param segment to `:_`. Two paths that normalize to the same string claim the same
+ * URLs (`/vendors/:id` and `/vendors/:vendor_id`), so a manifest may declare only one of them.
+ */
+export function normalizeRoutePath(path: string): string {
+  return path
+    .split("/")
+    .map((segment) => (segment.startsWith(":") ? PARAM_PLACEHOLDER : segment))
+    .join("/");
+}
+
+export interface RouteSetIssue {
+  /** Index of the offending entry in `routes`. */
+  index: number;
+  field: "path" | "portals" | "navigation";
+  message: string;
+}
+
+/**
+ * The rules over a set of routes that a pattern alone cannot express: the segment cap, a param
+ * name used twice in one path, two paths claiming the same URLs, and a repeated portal. Grammar,
+ * length and the per-field limits are the schema's job; a path that fails the grammar is skipped
+ * here. The zod schema and `apps-cli validate` both report these, and the server repeats them.
+ */
+export function routeSetIssues(
+  routes: ReadonlyArray<{ path: string; portals?: readonly string[] | undefined; navigation?: unknown }>,
+): RouteSetIssue[] {
+  const issues: RouteSetIssue[] = [];
+  const claimed = new Map<string, string>();
+
+  routes.forEach((route, index) => {
+    const portals = route.portals ?? [];
+    if (new Set(portals).size !== portals.length) {
+      issues.push({ index, field: "portals", message: "portals must not repeat" });
+    }
+
+    if (!ROUTE_PATH_RE.test(route.path)) return;
+
+    const segments = segmentsOf(route.path);
+    if (segments.length > ROUTE_PATH_MAX_SEGMENTS) {
+      issues.push({
+        index,
+        field: "path",
+        message: `${route.path} has ${segments.length} segments; the limit is ${ROUTE_PATH_MAX_SEGMENTS}`,
+      });
+    }
+
+    const params = segments.filter((s) => s.startsWith(":"));
+    if (new Set(params).size !== params.length) {
+      issues.push({ index, field: "path", message: `${route.path} uses a param name twice` });
+    }
+    // A sidebar entry links to one fixed address, and a path with params has none.
+    if (params.length > 0 && route.navigation !== undefined) {
+      issues.push({
+        index,
+        field: "navigation",
+        message: `${route.path} has params, so it cannot have a navigation entry; add one to a path without params`,
+      });
+    }
+
+    const normalized = normalizeRoutePath(route.path);
+    const earlier = claimed.get(normalized);
+    if (earlier === undefined) {
+      claimed.set(normalized, route.path);
+    } else {
+      issues.push({
+        index,
+        field: "path",
+        message: `${route.path} is declared twice (as ${earlier}); each path takes one page`,
+      });
+    }
+  });
+
+  return issues;
+}
+
+export interface AppRouteMatch<R> {
+  route: R;
+  /** Param values by name, percent-decoded. Always strings: the app parses ids itself. */
+  params: Record<string, string>;
+  /** Index of `route` in the list passed to {@link matchAppRoute}. */
+  index: number;
+}
+
+/**
+ * Decodes one pathname segment into a param value, or returns `null` when it cannot be one: a
+ * malformed escape, an empty value, `.` or `..`, or a value containing `/` or `:` (raw or
+ * encoded). A param therefore never carries a path or a host-looking value into the app.
+ */
+function paramValue(segment: string): string | null {
+  if (segment.includes(":")) return null;
+  let value: string;
+  try {
+    value = decodeURIComponent(segment);
+  } catch {
+    return null;
+  }
+  if (value === "" || value === "." || value === ".." || value.includes("/") || value.includes(":")) return null;
+  return value;
+}
+
+/**
+ * Finds the route a pathname in the app's own space renders (`/reports/7` for
+ * `/{portal}/apps/{appId}/pages/reports/7`), or `null` when none does.
+ *
+ * `pathname` is URL-encoded, as it appears in a URL: `/` or `/seg(/seg)*` with no empty segment,
+ * trailing slash, query or fragment (anything else matches nothing). A host that receives decoded
+ * segments encodes each with `encodeURIComponent` before joining them.
+ *
+ * A static route segment matches only the identical pathname segment. A param segment matches any
+ * other segment that decodes to a plain value (see `paramValue`); a segment containing `:` never
+ * matches a param. When several routes match, the one with a static segment at the first position
+ * where they differ wins (static before param, left to right); among equals, the first declared.
+ * Routes whose path is not in the grammar are ignored, so a stale or hand-edited feed entry can
+ * never match.
+ */
+export function matchAppRoute<R extends { path: string }>(
+  routes: readonly R[],
+  pathname: string,
+): AppRouteMatch<R> | null {
+  if (!pathname.startsWith("/") || /[?#]/.test(pathname)) return null;
+  const segments = segmentsOf(pathname);
+  if (segments.some((s) => s === "")) return null;
+
+  let best: { match: AppRouteMatch<R>; rank: boolean[] } | null = null;
+
+  for (const [index, route] of routes.entries()) {
+    const candidate = matchOne(route, index, segments);
+    if (candidate !== null && (best === null || outranks(candidate.rank, best.rank))) best = candidate;
+  }
+
+  return best === null ? null : best.match;
+}
+
+/** Matches one route against the pathname's segments, with its static/param rank. */
+function matchOne<R extends { path: string }>(
+  route: R,
+  index: number,
+  segments: readonly string[],
+): { match: AppRouteMatch<R>; rank: boolean[] } | null {
+  if (!isRoutePath(route.path)) return null;
+  const pattern = segmentsOf(route.path);
+  if (pattern.length !== segments.length) return null;
+
+  const params: Record<string, string> = {};
+  const rank: boolean[] = [];
+  for (let i = 0; i < pattern.length; i++) {
+    const expected = pattern[i] ?? "";
+    const actual = segments[i] ?? "";
+    if (PARAM_SEGMENT_RE.test(expected)) {
+      const value = paramValue(actual);
+      if (value === null) return null;
+      params[expected.slice(1)] = value;
+      rank.push(false);
+    } else {
+      if (expected !== actual) return null;
+      rank.push(true);
+    }
+  }
+  return { match: { route, params, index }, rank };
+}
+
+/** Whether `a` has a static segment at the first position where it and `b` differ. */
+function outranks(a: readonly boolean[], b: readonly boolean[]): boolean {
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return a[i] === true;
+  }
+  return false;
+}