@greensecurity/javascript-sdk 0.46.0-beta.10 → 0.46.0-beta.11

package/src/apps/devpreview.ts

@@ -11,6 +11,9 @@ import * as z from "zod/v4";
 import {
   addCspBudgetIssue,
   addDuplicateViewportIssues,
+  addRouteIssues,
+  APP_ROUTES_MAX,
+  appRouteSchema,
   CSP_SOURCES_MAX_TOTAL_CHARS,
   cspSourcesTotalChars,
   appConstantsSchema,
@@ -44,7 +47,9 @@ const devCspSourceSchema = z.union([
 ]);
 
 /**
- * `green-app.dev.json`. It may override constants, CSP sources and views while iterating.
+ * `green-app.dev.json`. It may override constants, CSP sources, views and routes (app pages) while
+ * iterating, so a new view or page can be previewed before it is published. Views and routes are
+ * UI placements and grant nothing, and a dev session is shown only to its developer.
  * Permissions and the bundle cannot be overridden: permissions are granted to the app's role on
  * `upload`, and the bundle comes from the dev server.
  */
@@ -54,24 +59,27 @@ export const devManifestSchema = z
     constants: appConstantsSchema.optional(),
     ui_extensions: z.strictObject({
       views: z.array(appViewSchema).max(200).optional(),
+      routes: z.array(appRouteSchema).max(APP_ROUTES_MAX).optional(),
       csp: z.strictObject({
         connect_src: z.array(devCspSourceSchema).max(CSP_SOURCES_MAX_PER_DIRECTIVE).optional(),
         image_src: z.array(devCspSourceSchema).max(CSP_SOURCES_MAX_PER_DIRECTIVE).optional(),
       }).optional(),
     }).optional(),
   })
-  // Same invariant as published manifests: dev views replace the published list, so a duplicate
-  // here would make view resolution order-dependent.
+  // Same invariants as published manifests: dev views and routes replace the published lists, so a
+  // duplicate here would make view resolution or route matching order-dependent.
   .superRefine((dev, ctx) => {
     addDuplicateViewportIssues(dev.ui_extensions?.views, ctx, ["ui_extensions", "views"]);
+    addRouteIssues(dev.ui_extensions?.routes, ctx, ["ui_extensions", "routes"]);
     addCspBudgetIssue(dev.ui_extensions?.csp, ctx, ["ui_extensions", "csp"]);
   });
 
 export type DevManifest = z.infer<typeof devManifestSchema>;
 
 /**
- * Applies a dev manifest over the published one. Object fields merge; arrays (`views`, CSP
- * sources) replace, so a developer can drop a view locally without editing the base file.
+ * Applies a dev manifest over the published one. Object fields merge; arrays (`views`, `routes`,
+ * CSP sources) replace, so a developer can drop a view or a page locally without editing the base
+ * file.
  * Throws {@link DevManifestError} if the merged CSP sources exceed the header budget.
  */
 export function mergeDevManifest(base: AppManifestV2, dev: DevManifest): AppManifestV2 {
@@ -85,14 +93,19 @@ export function mergeDevManifest(base: AppManifestV2, dev: DevManifest): AppMani
 
   if (base.ui_extensions === undefined && dev.ui_extensions === undefined) return merged;
 
-  // A preview renders views, and every rendered view needs a version (`ExtensionContext.app.version`).
-  // A dev file cannot supply one, so a versionless (v1) base cannot be previewed with views.
+  // A preview renders views and pages, and every rendered one needs a version
+  // (`ExtensionContext.app.version`). A dev file cannot supply one, so a versionless (v1) base
+  // cannot be previewed with views or routes.
   if (devUi.views !== undefined && devUi.views.length > 0 && base.version === undefined) {
     throw new DevManifestError("the base manifest needs a version before its views can be previewed");
   }
+  if (devUi.routes !== undefined && devUi.routes.length > 0 && base.version === undefined) {
+    throw new DevManifestError("the base manifest needs a version before its routes can be previewed");
+  }
 
   const ui: NonNullable<AppManifestV2["ui_extensions"]> = { ...baseUi };
   if (devUi.views !== undefined) ui.views = devUi.views;
+  if (devUi.routes !== undefined) ui.routes = devUi.routes;
   if (devUi.csp !== undefined) {
     ui.csp = {
       ...(baseUi.csp ?? { purpose: "Local development" }),

package/src/apps/hooks/index.ts

@@ -6,11 +6,13 @@
  */
 
 import { useContext } from "react";
-import type { ExtensionContext } from "../context.js";
+import type { ExtensionContext, PageRoute } from "../context.js";
 import { TOAST_MAX_LENGTH, type HostApi, type ToastType } from "../protocol.js";
 import { isRouteDescriptor, type RouteDescriptor } from "../route.js";
 import { AppSessionContext, currentSession, type AppSessionValue } from "../runtime/session.js";
 
+export { createAppStore, type AppStore, type AppStoreListener, type AppStoreUpdate } from "./store.js";
+
 const TOAST_TYPES: readonly ToastType[] = ["success", "caution", "pending"];
 
 function useSessionValue(hook: string): AppSessionValue {
@@ -26,6 +28,40 @@ export function useExtensionContext(): ExtensionContext {
   return useSessionValue("useExtensionContext").context;
 }
 
+/**
+ * The app page being shown, on views rendered as one of the app's `ui_extensions.routes`
+ * (`environment.route`): the declared `path` (`/reports/:id`), the concrete `pathname`
+ * (`/reports/7`) and the decoded `params` (`{ id: "7" }`, always strings). `undefined` on every
+ * other view. Re-renders with the new route when the host moves to another path of the same page
+ * (an `updateContext`), so read params here rather than once on mount.
+ *
+ * ```tsx
+ * const route = usePageRoute();
+ * const id = Number(route?.params["id"]);
+ * ```
+ */
+export function usePageRoute(): PageRoute | undefined {
+  return useSessionValue("usePageRoute").context.environment.route;
+}
+
+const NO_PARAMS: Readonly<Record<string, string>> = Object.freeze({});
+
+/**
+ * The `envParams` this app passed to the `navigate` call that opened this view
+ * (`environment.navParams`). Only this app can set them, and they never appear in an address, so
+ * they are the place for navigation data the view relies on. The page's URL query
+ * (`environment.queryParams`) is different: anyone can put anything in a link, so treat it as
+ * untrusted input. Empty (`{}`) when the view did not open from a navigation.
+ *
+ * ```tsx
+ * // VendorPanel: navigate({ type: "appPage", path: "/reports", envParams: { vendorId: "42" } })
+ * const { vendorId } = useNavParams();
+ * ```
+ */
+export function useNavParams(): Readonly<Record<string, string>> {
+  return useSessionValue("useNavParams").context.environment.navParams ?? NO_PARAMS;
+}
+
 /** The host API proxy for the view being rendered. Every method is async. */
 export function useHostApi(): HostApi {
   return useSessionValue("useHostApi").host;
@@ -68,7 +104,11 @@ export function showToast(message: string, opts: ShowToastOptions = {}): Promise
   }
 }
 
-/** Asks the host to navigate. Apps name a destination; the host owns its routes. */
+/**
+ * Asks the host to navigate. Apps name a destination; the host owns its routes. To open one of
+ * the app's own pages, pass a concrete path in the app's space:
+ * `navigate({ type: "appPage", path: "/reports/7" })` (not `/reports/:id`).
+ */
 export function navigate(to: RouteDescriptor, opts: { host?: HostApi } = {}): Promise<void> {
   if (!isRouteDescriptor(to)) return Promise.reject(new TypeError("navigate() needs a valid RouteDescriptor"));
   try {

package/src/apps/hooks/store.ts

@@ -0,0 +1,115 @@
+/*
+ * Hand-written (not generated by Speakeasy). Third-party app developer kit (C10); see
+ * docs/third-party-apps/plan.md.
+ *
+ * State shared by the views of one app. The host runs one sandbox (one worker) per app and mounts
+ * every view of that app into it, each as its own React root. React context therefore stops at a
+ * view's edge, but module state does not: a store created at module level is the same object in
+ * every view.
+ */
+
+import { useCallback, useRef, useSyncExternalStore } from "react";
+
+export type AppStoreListener<T> = (state: T, previous: T) => void;
+
+/** Fields to change, or a function of the current state that returns them. */
+export type AppStoreUpdate<T> = Partial<T> | ((state: T) => Partial<T>);
+
+export interface AppStore<T extends object> {
+  /** The current state. The same object until a `setState` changes a field. */
+  getState(): T;
+  /**
+   * Shallow-merges `update` into the state, like React's class `setState`: fields left out keep
+   * their values. A new state object is made, and listeners run, only when a field changes
+   * (`Object.is`), so setting a field to its current value re-renders nothing.
+   */
+  setState(update: AppStoreUpdate<T>): void;
+  /** Calls `listener` after each change, with the new and the previous state. Returns the unsubscribe. */
+  subscribe(listener: AppStoreListener<T>): () => void;
+  /**
+   * Reads the store in a component and re-renders it when the value changes. Without a selector
+   * the component re-renders on every change; with one, only when the selected value changes
+   * (`Object.is`), so select a field (or derive a primitive) rather than build a new object.
+   * The subscription ends when the component unmounts.
+   */
+  useStore(): T;
+  useStore<S>(selector: (state: T) => S): S;
+}
+
+/**
+ * Creates a store that every view of this app can read and update. Create it once, at module
+ * level, in a file the views import:
+ *
+ * ```ts
+ * // src/store.ts
+ * export const notes = createAppStore({ saved: 0 });
+ * // in a view
+ * const saved = notes.useStore((s) => s.saved);
+ * notes.setState((s) => ({ saved: s.saved + 1 }));
+ * ```
+ *
+ * What it guarantees, and what it does not:
+ * - Shared by every view of this app that is open in the same browser tab (web) or the same app
+ *   session (iOS, Android): a ContextView, its FocusView, the settings page and the app's pages
+ *   all see one state, and an update in one re-renders the others.
+ * - In memory only. Nothing is written to storage or sent anywhere.
+ * - Lost whenever the sandbox restarts: after a crash, a rebuild in a dev preview, sign-out, a
+ *   reload of the web page, or a restart of the mobile app. Each restart begins again from
+ *   `initial`. Keep anything that must last in your own backend or the Secret Store.
+ * - Never shared with other apps: each app has its own sandbox.
+ * - Not shared across devices, browser tabs or users.
+ */
+export function createAppStore<T extends object>(initial: T): AppStore<T> {
+  let state = initial;
+  const listeners = new Set<AppStoreListener<T>>();
+
+  const store: AppStore<T> = {
+    getState: () => state,
+
+    setState(update) {
+      const patch = typeof update === "function" ? update(state) : update;
+      const keys = Object.keys(patch) as Array<keyof T>;
+      if (!keys.some((key) => !Object.is(state[key], patch[key]))) return;
+      const previous = state;
+      state = { ...state, ...patch };
+      for (const listener of [...listeners]) listener(state, previous);
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    useStore: function useStore<S>(selector?: (state: T) => S): S | T {
+      return useStoreValue(store, selector);
+    } as AppStore<T>["useStore"],
+  };
+  return store;
+}
+
+/**
+ * `useSyncExternalStore` over `store`. `store.subscribe` is read at render time, so it is the
+ * store's own function (or whatever replaced it), and the subscription follows it.
+ */
+function useStoreValue<T extends object, S>(store: AppStore<T>, selector?: (state: T) => S): S | T {
+  // The last selection, so a selector that derives a new object from an unchanged state still
+  // gives React the same snapshot (React requires a stable snapshot between changes).
+  const cache = useRef<{ state: T; selector: ((state: T) => S) | undefined; value: S | T } | null>(null);
+  const subscribe = store.subscribe;
+  const onStoreChange = useCallback((notify: () => void) => subscribe(() => notify()), [subscribe]);
+
+  const getSnapshot = (): S | T => {
+    const current = store.getState();
+    const cached = cache.current;
+    if (cached && cached.state === current && cached.selector === selector) return cached.value;
+    const value = selector ? selector(current) : current;
+    // A changed state whose selection is equal keeps the previous value, so the view skips a render.
+    const stable = cached && Object.is(cached.value, value) ? cached.value : value;
+    cache.current = { state: current, selector, value: stable };
+    return stable;
+  };
+
+  return useSyncExternalStore(onStoreChange, getSnapshot, getSnapshot);
+}

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;
   }