@greensecurity/javascript-sdk 0.46.0-beta.9 → 0.47.0-beta.0

package/dist/commonjs/apps/hooks/index.js

@@ -6,7 +6,10 @@
  * Import as `@greensecurity/javascript-sdk/apps/hooks`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAppStore = void 0;
 exports.useExtensionContext = useExtensionContext;
+exports.usePageRoute = usePageRoute;
+exports.useNavParams = useNavParams;
 exports.useHostApi = useHostApi;
 exports.showToast = showToast;
 exports.navigate = navigate;
@@ -14,6 +17,8 @@ const react_1 = require("react");
 const protocol_js_1 = require("../protocol.js");
 const route_js_1 = require("../route.js");
 const session_js_1 = require("../runtime/session.js");
+var store_js_1 = require("./store.js");
+Object.defineProperty(exports, "createAppStore", { enumerable: true, get: function () { return store_js_1.createAppStore; } });
 const TOAST_TYPES = ["success", "caution", "pending"];
 function useSessionValue(hook) {
     const value = (0, react_1.useContext)(session_js_1.AppSessionContext);
@@ -26,6 +31,37 @@ function useSessionValue(hook) {
 function useExtensionContext() {
     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"]);
+ * ```
+ */
+function usePageRoute() {
+    return useSessionValue("usePageRoute").context.environment.route;
+}
+const NO_PARAMS = 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();
+ * ```
+ */
+function useNavParams() {
+    return useSessionValue("useNavParams").context.environment.navParams ?? NO_PARAMS;
+}
 /** The host API proxy for the view being rendered. Every method is async. */
 function useHostApi() {
     return useSessionValue("useHostApi").host;
@@ -58,7 +94,11 @@ function showToast(message, opts = {}) {
         return Promise.reject(error);
     }
 }
-/** 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`).
+ */
 function navigate(to, opts = {}) {
     if (!(0, route_js_1.isRouteDescriptor)(to))
         return Promise.reject(new TypeError("navigate() needs a valid RouteDescriptor"));

package/dist/commonjs/apps/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/apps/hooks/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/apps/hooks/index.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/apps/hooks/store.d.ts

@@ -0,0 +1,48 @@
+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 declare function createAppStore<T extends object>(initial: T): AppStore<T>;
+//# sourceMappingURL=store.d.ts.map

package/dist/commonjs/apps/hooks/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/apps/hooks/store.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC;AAElE,8EAA8E;AAC9E,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAExE,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM;IACxC,6EAA6E;IAC7E,QAAQ,IAAI,CAAC,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC1C,wGAAwG;IACxG,SAAS,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IACrD;;;;;OAKG;IACH,QAAQ,IAAI,CAAC,CAAC;IACd,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CA4BxE"}

package/dist/commonjs/apps/hooks/store.js

@@ -0,0 +1,87 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAppStore = createAppStore;
+const react_1 = require("react");
+/**
+ * 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.
+ */
+function createAppStore(initial) {
+    let state = initial;
+    const listeners = new Set();
+    const store = {
+        getState: () => state,
+        setState(update) {
+            const patch = typeof update === "function" ? update(state) : update;
+            const keys = Object.keys(patch);
+            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(selector) {
+            return useStoreValue(store, selector);
+        },
+    };
+    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(store, selector) {
+    // 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 = (0, react_1.useRef)(null);
+    const subscribe = store.subscribe;
+    const onStoreChange = (0, react_1.useCallback)((notify) => subscribe(() => notify()), [subscribe]);
+    const getSnapshot = () => {
+        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 (0, react_1.useSyncExternalStore)(onStoreChange, getSnapshot, getSnapshot);
+}
+//# sourceMappingURL=store.js.map

package/dist/commonjs/apps/hooks/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../../src/apps/hooks/store.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAqDH,wCA4BC;AA/ED,iCAAkE;AA4BlE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,cAAc,CAAmB,OAAU;IACzD,IAAI,KAAK,GAAG,OAAO,CAAC;IACpB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;IAEjD,MAAM,KAAK,GAAgB;QACzB,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK;QAErB,QAAQ,CAAC,MAAM;YACb,MAAM,KAAK,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACpE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAmB,CAAC;YAClD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,OAAO;YACpE,MAAM,QAAQ,GAAG,KAAK,CAAC;YACvB,KAAK,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC;YAC/B,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC;gBAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACnE,CAAC;QAED,SAAS,CAAC,QAAQ;YAChB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC7B,CAAC,CAAC;QACJ,CAAC;QAED,QAAQ,EAAE,SAAS,QAAQ,CAAI,QAA0B;YACvD,OAAO,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACxC,CAA4B;KAC7B,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAsB,KAAkB,EAAE,QAA0B;IACxF,4FAA4F;IAC5F,oFAAoF;IACpF,MAAM,KAAK,GAAG,IAAA,cAAM,EAA6E,IAAI,CAAC,CAAC;IACvG,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAClC,MAAM,aAAa,GAAG,IAAA,mBAAW,EAAC,CAAC,MAAkB,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAElG,MAAM,WAAW,GAAG,GAAU,EAAE;QAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC;QAC7B,IAAI,MAAM,IAAI,MAAM,CAAC,KAAK,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC;QAC5F,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QACrD,iGAAiG;QACjG,MAAM,MAAM,GAAG,MAAM,IAAI,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;QAC/E,KAAK,CAAC,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAC5D,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IAEF,OAAO,IAAA,4BAAoB,EAAC,aAAa,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;AACvE,CAAC"}

package/dist/commonjs/apps/manifest.d.ts

@@ -1,5 +1,6 @@
 import * as z from "zod/v4";
 export { IPV4_OCTET_PATTERN, PORT_PATTERN, CSP_PATH_CHAR, CSP_SOURCE_MAX_CHARS, CSP_SOURCE_PATTERN, CSP_SOURCES_MAX_PER_DIRECTIVE, CSP_SOURCES_MAX_TOTAL_CHARS, cspSourcesTotalChars, HTTPS_URL_PATTERN, isHttpsUrl, isParsableHttpsUrl, } from "./url.js";
+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 declare const SRI_PATTERN = "^(sha256-[A-Za-z0-9+/]{43}=|sha384-[A-Za-z0-9+/]{64}|sha512-[A-Za-z0-9+/]{86}==)$";
 /** SemVer 2.0.0 (semver.org's reference pattern): no empty or leading-zero numeric identifiers. */
@@ -45,6 +46,45 @@ export declare const appViewSchema: z.ZodObject<{
     }>;
     component: z.ZodString;
 }, z.core.$strict>;
+/** Reports {@link routeSetIssues} (segment cap, repeated params, duplicate paths, repeated portals). */
+export declare function addRouteIssues(routes: ReadonlyArray<{
+    path: string;
+    portals?: readonly string[] | undefined;
+    navigation?: unknown;
+}> | undefined, ctx: z.RefinementCtx, path: ReadonlyArray<string | number>): void;
+/**
+ * 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 declare const NON_BLANK_PATTERN = "[^\\t\\n\\v\\f\\r \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]";
+export declare const appRouteSchema: z.ZodObject<{
+    path: z.ZodString;
+    component: z.ZodString;
+    /** Page header title. */
+    title: z.ZodString;
+    /** Portals the page is offered in. Absent = every portal the host renders. */
+    portals: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        facility: "facility";
+        system: "system";
+        company: "company";
+        vendor: "vendor";
+    }>>>;
+    /** Offer the page in the sidebar / mobile drawer menu under this label (default: `title`). */
+    navigation: z.ZodOptional<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 /** Constants are delivered to every view as `environment.constants`. */
 export declare const appConstantsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
 export declare const appCspSchema: z.ZodObject<{
@@ -84,10 +124,23 @@ export declare const appManifestSchema: z.ZodObject<{
             }>;
             component: z.ZodString;
         }, z.core.$strict>>>;
-        /** Reserved for a future FullPageView. Stored and validated, not rendered. */
+        /** App pages, each a full screen under `/{portal}/apps/{appId}/pages`. */
         routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
             path: z.ZodString;
             component: z.ZodString;
+            /** Page header title. */
+            title: z.ZodString;
+            /** Portals the page is offered in. Absent = every portal the host renders. */
+            portals: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                facility: "facility";
+                system: "system";
+                company: "company";
+                vendor: "vendor";
+            }>>>;
+            /** Offer the page in the sidebar / mobile drawer menu under this label (default: `title`). */
+            navigation: z.ZodOptional<z.ZodObject<{
+                label: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
         }, z.core.$strict>>>;
         csp: z.ZodOptional<z.ZodObject<{
             connect_src: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -102,8 +155,14 @@ export declare const appManifestSchema: z.ZodObject<{
             url: "url";
             app_settings_view: "app_settings_view";
             app_main_view: "app_main_view";
+            app_page: "app_page";
         }>;
         url: z.ZodOptional<z.ZodString>;
+        /**
+         * 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.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     webhooks: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
@@ -115,12 +174,14 @@ export declare const appManifestSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type AppManifestV2 = z.infer<typeof appManifestSchema>;
+export type AppRoute = z.infer<typeof appRouteSchema>;
 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 declare function effectivePostInstallAction(manifest: Pick<AppManifestV2, "post_install_action" | "ui_extensions">): PostInstallAction | null;
 export type AppView = z.infer<typeof appViewSchema>;

package/dist/commonjs/apps/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/apps/manifest.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/apps/manifest.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/apps/manifest.js

@@ -43,14 +43,16 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.appManifestSchema = exports.appCspSchema = exports.appConstantsSchema = exports.appViewSchema = exports.cspSourceSchema = exports.httpsUrlSchema = exports.APP_WEBHOOK_EVENTS = exports.PLATFORM_PERMISSIONS = exports.PERMISSION_PATTERN = exports.SAFE_INTEGER_STRING_PATTERN = exports.COMPONENT_NAME_PATTERN = exports.SEMVER_PATTERN = exports.SRI_PATTERN = exports.isParsableHttpsUrl = exports.isHttpsUrl = exports.HTTPS_URL_PATTERN = exports.cspSourcesTotalChars = exports.CSP_SOURCES_MAX_TOTAL_CHARS = exports.CSP_SOURCES_MAX_PER_DIRECTIVE = exports.CSP_SOURCE_PATTERN = exports.CSP_SOURCE_MAX_CHARS = exports.CSP_PATH_CHAR = exports.PORT_PATTERN = exports.IPV4_OCTET_PATTERN = void 0;
+exports.appManifestSchema = exports.appCspSchema = exports.appConstantsSchema = exports.appRouteSchema = exports.NON_BLANK_PATTERN = exports.appViewSchema = exports.cspSourceSchema = exports.httpsUrlSchema = exports.APP_WEBHOOK_EVENTS = exports.PLATFORM_PERMISSIONS = exports.PERMISSION_PATTERN = exports.SAFE_INTEGER_STRING_PATTERN = exports.COMPONENT_NAME_PATTERN = exports.SEMVER_PATTERN = exports.SRI_PATTERN = exports.routeSetIssues = exports.ROUTE_PATH_PATTERN = exports.ROUTE_PATH_MAX_SEGMENTS = exports.ROUTE_PATH_MAX_CHARS = exports.normalizeRoutePath = exports.matchAppRoute = exports.isRoutePath = exports.isConcreteRoutePath = exports.CONCRETE_ROUTE_PATH_PATTERN = exports.APP_ROUTES_MAX = exports.isParsableHttpsUrl = exports.isHttpsUrl = exports.HTTPS_URL_PATTERN = exports.cspSourcesTotalChars = exports.CSP_SOURCES_MAX_TOTAL_CHARS = exports.CSP_SOURCES_MAX_PER_DIRECTIVE = exports.CSP_SOURCE_PATTERN = exports.CSP_SOURCE_MAX_CHARS = exports.CSP_PATH_CHAR = exports.PORT_PATTERN = exports.IPV4_OCTET_PATTERN = void 0;
 exports.isPlatformPermission = isPlatformPermission;
 exports.addCspBudgetIssue = addCspBudgetIssue;
 exports.addDuplicateViewportIssues = addDuplicateViewportIssues;
+exports.addRouteIssues = addRouteIssues;
 exports.effectivePostInstallAction = effectivePostInstallAction;
 exports.manifestJsonSchema = manifestJsonSchema;
 exports.validateManifest = validateManifest;
 const z = __importStar(require("zod/v4"));
+const routes_js_1 = require("./routes.js");
 const surfaces_js_1 = require("./surfaces.js");
 const url_js_1 = require("./url.js");
 // The URL and CSP-source rules live in the zod-free `url.ts` so the host renderer can use them
@@ -67,6 +69,18 @@ Object.defineProperty(exports, "cspSourcesTotalChars", { enumerable: true, get:
 Object.defineProperty(exports, "HTTPS_URL_PATTERN", { enumerable: true, get: function () { return url_js_2.HTTPS_URL_PATTERN; } });
 Object.defineProperty(exports, "isHttpsUrl", { enumerable: true, get: function () { return url_js_2.isHttpsUrl; } });
 Object.defineProperty(exports, "isParsableHttpsUrl", { enumerable: true, get: function () { return url_js_2.isParsableHttpsUrl; } });
+// The route grammar and matcher live in the zod-free `routes.ts` for the same reason.
+var routes_js_2 = require("./routes.js");
+Object.defineProperty(exports, "APP_ROUTES_MAX", { enumerable: true, get: function () { return routes_js_2.APP_ROUTES_MAX; } });
+Object.defineProperty(exports, "CONCRETE_ROUTE_PATH_PATTERN", { enumerable: true, get: function () { return routes_js_2.CONCRETE_ROUTE_PATH_PATTERN; } });
+Object.defineProperty(exports, "isConcreteRoutePath", { enumerable: true, get: function () { return routes_js_2.isConcreteRoutePath; } });
+Object.defineProperty(exports, "isRoutePath", { enumerable: true, get: function () { return routes_js_2.isRoutePath; } });
+Object.defineProperty(exports, "matchAppRoute", { enumerable: true, get: function () { return routes_js_2.matchAppRoute; } });
+Object.defineProperty(exports, "normalizeRoutePath", { enumerable: true, get: function () { return routes_js_2.normalizeRoutePath; } });
+Object.defineProperty(exports, "ROUTE_PATH_MAX_CHARS", { enumerable: true, get: function () { return routes_js_2.ROUTE_PATH_MAX_CHARS; } });
+Object.defineProperty(exports, "ROUTE_PATH_MAX_SEGMENTS", { enumerable: true, get: function () { return routes_js_2.ROUTE_PATH_MAX_SEGMENTS; } });
+Object.defineProperty(exports, "ROUTE_PATH_PATTERN", { enumerable: true, get: function () { return routes_js_2.ROUTE_PATH_PATTERN; } });
+Object.defineProperty(exports, "routeSetIssues", { enumerable: true, get: function () { return routes_js_2.routeSetIssues; } });
 /** A single SRI hash with the digest length its algorithm produces (32, 48 or 64 bytes, base64). */
 exports.SRI_PATTERN = "^(sha256-[A-Za-z0-9+/]{43}=|sha384-[A-Za-z0-9+/]{64}|sha512-[A-Za-z0-9+/]{86}==)$";
 /** SemVer 2.0.0 (semver.org's reference pattern): no empty or leading-zero numeric identifiers. */
@@ -100,7 +114,10 @@ const PLATFORM_PERMISSION_NAMES = new Set(exports.PLATFORM_PERMISSIONS.map((p) =
 function isPlatformPermission(value) {
     return typeof value === "string" && PLATFORM_PERMISSION_NAMES.has(value);
 }
-const SURFACE_IDS = surfaces_js_1.SURFACES.map((s) => s.id);
+// A view's viewport. `page` is not one: an app declares its pages in `routes`, not in `views`.
+const SURFACE_IDS = surfaces_js_1.SURFACES.filter((s) => s.kind !== "page").map((s) => s.id);
+/** Portals an app page may be offered in (`routes[].portals`). */
+const ROUTE_PORTALS = ["company", "vendor", "facility", "system"];
 /** Lifecycle events an app's own webhook endpoint can receive (see C19). */
 exports.APP_WEBHOOK_EVENTS = [
     "MarketplaceAppActivation.created",
@@ -153,6 +170,42 @@ exports.appViewSchema = z.strictObject({
     viewport: z.enum(SURFACE_IDS),
     component: z.string().max(100).regex(new RegExp(exports.COMPONENT_NAME_PATTERN)),
 });
+/** Reports {@link routeSetIssues} (segment cap, repeated params, duplicate paths, repeated portals). */
+function addRouteIssues(routes, ctx, path) {
+    for (const issue of (0, routes_js_1.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.
+ */
+exports.NON_BLANK_PATTERN = "[^\\t\\n\\v\\f\\r \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]";
+exports.appRouteSchema = z.strictObject({
+    path: z.string().max(routes_js_1.ROUTE_PATH_MAX_CHARS).regex(new RegExp(routes_js_1.ROUTE_PATH_PATTERN)),
+    component: z.string().max(100).regex(new RegExp(exports.COMPONENT_NAME_PATTERN)),
+    /** Page header title. */
+    title: z.string().min(1).max(100).regex(new RegExp(exports.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(exports.NON_BLANK_PATTERN), { message: "must not be blank" }).optional(),
+    })
+        .optional(),
+});
 /** Constants are delivered to every view as `environment.constants`. */
 exports.appConstantsSchema = z.record(z.string().max(100).regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.union([z.string().max(2048), z.number(), z.boolean()]));
 exports.appCspSchema = z.strictObject({
@@ -192,21 +245,20 @@ exports.appManifestSchema = z
             integrity: z.string().max(200).regex(new RegExp(exports.SRI_PATTERN)),
         }).optional(),
         views: z.array(exports.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(exports.COMPONENT_NAME_PATTERN)),
-        }))
-            .max(50)
-            .optional(),
+        /** App pages, each a full screen under `/{portal}/apps/{appId}/pages`. */
+        routes: z.array(exports.appRouteSchema).max(routes_js_1.APP_ROUTES_MAX).optional(),
         csp: exports.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: exports.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(routes_js_1.ROUTE_PATH_MAX_CHARS).regex(new RegExp(routes_js_1.CONCRETE_ROUTE_PATH_PATTERN)).optional(),
     })
         .optional(),
     // The app's own webhook endpoint: registered by the catalog when the manifest is published, not
@@ -220,31 +272,50 @@ exports.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.ui_extensions?.views?.length && !manifest.ui_extensions.bundle) {
+    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" });
+    }
+    // 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.
     const viewports = new Set((manifest.ui_extensions?.views ?? []).map((v) => v.viewport));
@@ -257,28 +328,58 @@ exports.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",
         });
     }
 });
+/**
+ * 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, ctx) {
+    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 (!(0, routes_js_1.isConcreteRoutePath)(action.path)) {
+        ctx.addIssue({ code: "custom", path, message: "path must be a page path without :params, such as /reports/7" });
+    }
+    else if ((0, routes_js_1.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) {
+    const views = manifest.ui_extensions?.views ?? [];
+    const routes = manifest.ui_extensions?.routes ?? [];
+    return views.some((v) => v.viewport !== "settings") || routes.some((r) => r.path === "/");
+}
 /**
  * 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.
  */
 function effectivePostInstallAction(manifest) {
     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"))
+    if (hasMainView(manifest))
         return { type: "app_main_view" };
-    if (viewports.includes("settings"))
+    if ((manifest.ui_extensions?.views ?? []).some((v) => v.viewport === "settings"))
         return { type: "app_settings_view" };
     return null;
 }