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

package/src/__tests__/apps/kit/example.test.ts

@@ -1,6 +1,6 @@
 /*
  * Hand-written. Keeps examples/apps/hello-green (the C15 template) valid against the C0
- * manifest contract. Building it and printing its SRI is `npm run build` in that folder.
+ * manifest contract, and renders its settings view and its pages. Building it and printing its SRI is `npm run build` in that folder.
  */
 
 import { spawnSync } from "node:child_process";
@@ -9,7 +9,7 @@ import { join } from "node:path";
 import { describe, expect, test, vi } from "vitest";
 import { createElement as h, type ComponentType } from "react";
 import { validateManifest } from "../../../apps/manifest.js";
-import { renderForTest } from "../../../apps/testing/index.js";
+import { mockPageRoute, renderForTest } from "../../../apps/testing/index.js";
 
 // The example imports the SDK by package name, which resolves to the built `dist/` copy. Point
 // those imports at the sources under test so the example and this harness share one runtime.
@@ -105,14 +105,103 @@ describe("examples/apps/hello-green", () => {
     60_000,
   );
 
-  test("every manifest view is registered with defineApp", () => {
+  test("every manifest view and page is registered with defineApp", () => {
     const result = validateManifest(manifest);
     if (!result.ok) throw new Error("invalid manifest");
     const entry = readFileSync(join(EXAMPLE_DIR, "src", "index.tsx"), "utf8");
     const views = /defineApp\(\{\s*views:\s*\{([^}]*)\}/.exec(entry)?.[1] ?? "";
     const registered = views.split(",").map((v) => v.trim()).filter(Boolean);
-    for (const view of result.manifest.ui_extensions?.views ?? []) {
-      expect(registered).toContain(view.component);
+    const components = [
+      ...(result.manifest.ui_extensions?.views ?? []).map((v) => v.component),
+      ...(result.manifest.ui_extensions?.routes ?? []).map((r) => r.component),
+    ];
+    expect(components).toEqual(expect.arrayContaining(["Reports", "ReportDetail"]));
+    for (const component of components) {
+      expect(registered).toContain(component);
     }
   });
+
+  test("it declares a listed reports page and a detail page", () => {
+    const result = validateManifest(manifest);
+    if (!result.ok) throw new Error("invalid manifest");
+    expect(result.manifest.ui_extensions?.routes).toEqual([
+      { path: "/reports", component: "Reports", title: "Reports", navigation: { label: "Hello reports" } },
+      { path: "/reports/:id", component: "ReportDetail", title: "Report" },
+    ]);
+  });
+});
+
+describe("hello-green pages", () => {
+  // Through a variable, for the same reason as AppSettings above.
+  const pagesModule = (name: string) => `../../../../examples/apps/hello-green/src/${name}.js`;
+
+  test("Reports links each row to its /reports/:id page by concrete path", async () => {
+    const { Reports } = (await import(/* @vite-ignore */ pagesModule("Reports"))) as { Reports: ComponentType };
+    const view = await renderForTest(h(Reports), {
+      context: { environment: { route: mockPageRoute("/reports") } },
+    });
+    expect(view.root.component).toBe("PageView");
+    expect(view.root.props["title"]).toBe("Reports");
+    await view.find("List")!.trigger("onAction", "8");
+    await view.root.slotted("actions")[0]!.trigger("onPress");
+    expect(view.host.callsTo("navigate")).toEqual([
+      [{ type: "appPage", path: "/reports/8" }],
+      [{ type: "appPage", path: "/reports/7" }],
+    ]);
+  });
+
+  test("the vendor panel and the Reports page share notes through the store, and the panel passes the vendor as navParams", async () => {
+    const { VendorPanel } = (await import(/* @vite-ignore */ pagesModule("VendorPanel"))) as { VendorPanel: ComponentType };
+    const { Reports } = (await import(/* @vite-ignore */ pagesModule("Reports"))) as { Reports: ComponentType };
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async () =>
+      new Response(JSON.stringify({ error: "Not found", success: false, code: 404 }), {
+        status: 404,
+        headers: { "content-type": "application/json" },
+      })) as typeof fetch;
+    try {
+      const panel = await renderForTest(h(VendorPanel), {
+        context: { environment: { surfaceId: "gs.company.vendor.detail", objectContext: { object: "vendor", id: 42 } } },
+      });
+      const reports = await renderForTest(h(Reports), {
+        context: { environment: { route: mockPageRoute("/reports"), navParams: { vendorId: "42" } } },
+      });
+      expect(reports.root.slotted("banner")[0]?.props["title"]).toBe("Opened from vendor #42");
+      expect(reports.text()).toContain("No notes saved this session.");
+
+      await panel.find("TextField")!.trigger("onChange", "Badge expired");
+      await panel.find("FocusView")!.slotted("primaryAction")[0]!.trigger("onPress");
+      await reports.settle();
+      expect(panel.text()).toContain("Notes saved this session: 1");
+      expect(reports.text()).toContain("Notes saved this session: 1. Latest, on vendor #42: Badge expired");
+
+      await panel.find("Button", (b) => b.text === "Open reports")!.trigger("onPress");
+      // `navigate()` without `{ host }` goes through the most recently mounted view's host, here
+      // the page's; both belong to the same app.
+      expect([...panel.host.callsTo("navigate"), ...reports.host.callsTo("navigate")]).toEqual([
+        [{ type: "appPage", path: "/reports", envParams: { vendorId: "42" } }],
+      ]);
+      expect([...panel.errors, ...reports.errors]).toEqual([]);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("ReportDetail reads its id from usePageRoute and follows a route change", async () => {
+    const { ReportDetail } = (await import(/* @vite-ignore */ pagesModule("ReportDetail"))) as { ReportDetail: ComponentType };
+    const view = await renderForTest(h(ReportDetail), {
+      context: { environment: { route: mockPageRoute("/reports/:id", "/reports/7") } },
+    });
+    expect(view.root.props["title"]).toBe("Weekly check-ins");
+
+    await view.updateContext({ environment: { ...view.context.environment, route: mockPageRoute("/reports/:id", "/reports/8") } });
+    expect(view.root.props["title"]).toBe("Expiring credentials");
+
+    await view.updateContext({ environment: { ...view.context.environment, route: mockPageRoute("/reports/:id", "/reports/99") } });
+    expect(view.root.props["title"]).toBe("Report not found");
+
+    await view.root.slotted("actions")[0]!.trigger("onPress");
+    expect(view.host.callsTo("navigate")).toEqual([[{ type: "appPage", path: "/reports" }]]);
+    expect(view.errors).toEqual([]);
+  });
 });

package/src/__tests__/apps/kit/pages.test.ts

@@ -0,0 +1,137 @@
+/*
+ * Hand-written. App pages in the developer kit (docs/third-party-apps/fullpageview-plan.md, P3):
+ * the PageView root, `usePageRoute()`, `navigate({ type: "appPage" })` through the hooks, and the
+ * testing kit's route support (`getMockContext`, `mockPageRoute`).
+ */
+
+import { createElement as h } from "react";
+import { describe, expect, test } from "vitest";
+import type { PageRoute } from "../../../apps/context.js";
+import { navigate, useHostApi, usePageRoute } from "../../../apps/hooks/index.js";
+import type { RouteDescriptor } from "../../../apps/route.js";
+import { getMockContext, mockPageRoute, renderForTest } from "../../../apps/testing/index.js";
+import { Button, ContextView, PageView, Text, type UiProps } from "../../../apps/ui/index.js";
+
+function ReportDetail() {
+  const route = usePageRoute();
+  const host = useHostApi();
+  return h(
+    PageView,
+    { title: `Report ${route?.params["id"] ?? "?"}`, actions: h(Button, { onPress: () => navigate({ type: "appPage", path: "/reports" }, { host }) }, "All reports") },
+    h(Text, null, route ? `${route.path} at ${route.pathname}` : "no route"),
+  );
+}
+
+describe("PageView", () => {
+  test("is a view root with the catalog's props and slots (checked by tsc)", () => {
+    const props: UiProps<"PageView"> = { title: "Reports", description: "All reports", actions: h(Button, null, "New"), banner: h(Text, null, "Beta") };
+    // @ts-expect-error title is required
+    const untitled: UiProps<"PageView"> = { description: "x" };
+    // @ts-expect-error PageView has no primaryAction slot (ContextView's)
+    const wrongSlot: UiProps<"PageView"> = { title: "t", primaryAction: h(Button, null, "Go") };
+    expect([props, untitled, wrongSlot]).toHaveLength(3);
+  });
+
+  test("renders as the root with its slots", async () => {
+    const view = await renderForTest(h(ReportDetail), {
+      context: { environment: { route: mockPageRoute("/reports/:id", "/reports/7") } },
+    });
+    expect(view.root.component).toBe("PageView");
+    expect(view.root.props["title"]).toBe("Report 7");
+    expect(view.root.slotted("actions").map((e) => e.text)).toEqual(["All reports"]);
+    expect(view.find("Text")!.text).toBe("/reports/:id at /reports/7");
+  });
+});
+
+describe("usePageRoute", () => {
+  test("is undefined on a view that is not a page", async () => {
+    const Panel = () => h(ContextView, { title: "Panel" }, h(Text, null, usePageRoute() === undefined ? "none" : "route"));
+    const view = await renderForTest(h(Panel));
+    expect(view.find("Text")!.text).toBe("none");
+  });
+
+  test("re-renders with the new route when the host pushes one through updateContext", async () => {
+    const view = await renderForTest(h(ReportDetail), {
+      context: { environment: { route: mockPageRoute("/reports/:id", "/reports/7") } },
+    });
+    expect(view.root.props["title"]).toBe("Report 7");
+
+    await view.updateContext({ environment: { ...view.context.environment, route: mockPageRoute("/reports/:id", "/reports/8") } });
+    expect(view.root.props["title"]).toBe("Report 8");
+    expect(view.find("Text")!.text).toBe("/reports/:id at /reports/8");
+    expect(view.errors).toEqual([]);
+  });
+
+  test("throws outside a mounted view", () => {
+    expect(() => usePageRoute()).toThrow();
+  });
+});
+
+describe("navigate to an app page", () => {
+  test("sends a concrete path to the host", async () => {
+    const view = await renderForTest(h(ReportDetail), {
+      context: { environment: { route: mockPageRoute("/reports/:id", "/reports/7") } },
+    });
+    await view.root.slotted("actions")[0]!.trigger("onPress");
+    expect(view.host.callsTo("navigate")).toEqual([[{ type: "appPage", path: "/reports" }]]);
+  });
+
+  test("rejects a declared (param) path, a path that climbs out and a missing path, before the host sees them", async () => {
+    const view = await renderForTest(h(ReportDetail), {
+      context: { environment: { route: mockPageRoute("/reports/:id", "/reports/7") } },
+    });
+    const bad: unknown[] = [
+      { type: "appPage", path: "/reports/:id" },
+      { type: "appPage", path: "/../settings" },
+      { type: "appPage", path: "reports" },
+      { type: "appPage" },
+    ];
+    for (const to of bad) {
+      await expect(navigate(to as RouteDescriptor, { host: view.host })).rejects.toThrow(TypeError);
+    }
+    expect(view.host.callsTo("navigate")).toEqual([]);
+  });
+
+  test("type-checks through the hook API", () => {
+    const ok: Parameters<typeof navigate>[0] = { type: "appPage", path: "/reports/7", envParams: { tab: "summary" } };
+    // @ts-expect-error appPage needs a path
+    const noPath: Parameters<typeof navigate>[0] = { type: "appPage" };
+    // @ts-expect-error an app can only open its own pages: there is no appId
+    const otherApp: Parameters<typeof navigate>[0] = { type: "appPage", path: "/x", appId: 2 };
+    expect([ok, noPath, otherApp]).toHaveLength(3);
+  });
+});
+
+describe("testing kit routes", () => {
+  test("mockPageRoute decodes params the way the host does", () => {
+    expect(mockPageRoute("/reports/:id", "/reports/7")).toEqual({ path: "/reports/:id", pathname: "/reports/7", params: { id: "7" } });
+    expect(mockPageRoute("/vendors/:vendor_id/notes/:note", "/vendors/a%20b/notes/3")).toEqual({
+      path: "/vendors/:vendor_id/notes/:note",
+      pathname: "/vendors/a%20b/notes/3",
+      params: { vendor_id: "a b", note: "3" },
+    });
+    expect(mockPageRoute("/reports")).toEqual({ path: "/reports", pathname: "/reports", params: {} });
+    expect(() => mockPageRoute("/reports/:id", "/vendors/7")).toThrow(/does not match/);
+  });
+
+  test("getMockContext has no route by default", () => {
+    const ctx = getMockContext();
+    expect(ctx.environment.route).toBeUndefined();
+    expect(ctx.environment.surfaceId).toBe("gs.company.drawer.default");
+  });
+
+  test("getMockContext takes a route, puts the view on the page surface and completes a partial one", () => {
+    const route: PageRoute = mockPageRoute("/reports/:id", "/reports/7");
+    const ctx = getMockContext({ environment: { route } });
+    expect(ctx.environment.route).toEqual(route);
+    expect(ctx.environment.surfaceId).toBe("page");
+    expect(ctx.environment.portal).toBe("company");
+
+    expect(getMockContext({ environment: { route: { path: "/reports" } } }).environment.route).toEqual({
+      path: "/reports",
+      pathname: "/reports",
+      params: {},
+    });
+    expect(getMockContext({ environment: { surfaceId: "custom", route: { path: "/" } } }).environment.surfaceId).toBe("custom");
+  });
+});

package/src/__tests__/apps/kit/render.test.ts

@@ -7,7 +7,7 @@
 import { createElement as h, Fragment, startTransition, useLayoutEffect, useState, type ReactNode } from "react";
 import { flushSync } from "react-dom";
 import { describe, expect, test } from "vitest";
-import { COMPONENTS, type ComponentName } from "../../../apps/components.js";
+import { COMPONENTS, type ChartClickEvent, type ComponentName } from "../../../apps/components.js";
 import { navigate, showToast, useExtensionContext, useHostApi } from "../../../apps/hooks/index.js";
 import { defineRemoteElements, ELEMENTS, ExtensionContextProvider } from "../../../apps/runtime/index.js";
 import { sessionForContext } from "../../../apps/runtime/session.js";
@@ -15,7 +15,9 @@ import { createMockHost, getMockContext, mockTokens, renderForTest, type MockHos
 import * as ui from "../../../apps/ui/index.js";
 import {
   Badge,
+  BarChart,
   Button,
+  ComboChart,
   ContextView,
   FocusView,
   Link,
@@ -199,6 +201,38 @@ describe("ui wrappers", () => {
   });
 });
 
+describe("charts", () => {
+  test("data reaches the host and onClick receives the ChartClickEvent detail", async () => {
+    const clicks: ChartClickEvent[] = [];
+    const data = [{ label: "Mon", value: 3 }, { label: "Tue", value: 5 }];
+    const combo = { labels: ["Q1", "Q2"], bars: { name: "Visits", values: [4, 6] }, line: { name: "Average", values: [2, 3] } };
+    const view = await renderForTest(
+      h(ContextView, { title: "Charts" },
+        h(BarChart, { data, theme: "vibrant", interactive: true, onClick: (e: ChartClickEvent) => { clicks.push(e); return e.index; } }),
+        h(ComboChart, { data: combo, onClick: (e: ChartClickEvent) => clicks.push(e) }),
+      ),
+    );
+    const bar = view.find("BarChart")!;
+    expect(bar.props).toEqual({ data, theme: "vibrant", interactive: true });
+    expect(bar.events).toEqual(["click"]);
+    const detail: ChartClickEvent = { index: 1, label: "Tue", value: 5 };
+    await expect(bar.trigger("onClick", detail)).resolves.toBe(1);
+
+    const comboNode = view.find("ComboChart")!;
+    expect(comboNode.props["data"]).toEqual(combo);
+    const lineDetail: ChartClickEvent = { index: 0, label: "Q1", value: 2, series: "Average" };
+    await comboNode.trigger("onClick", lineDetail);
+    expect(clicks).toEqual([detail, lineDetail]);
+  });
+
+  test("chart props are typed (checked by tsc)", () => {
+    const ok: UiProps<"BarChart"> = { data: [{ label: "a", value: 1 }], onClick: (e: ChartClickEvent) => e.label };
+    // @ts-expect-error styling props are not accepted
+    const styled: UiProps<"BarChart"> = { data: [{ label: "a", value: 1 }], color: "red" };
+    expect([ok, styled]).toHaveLength(2);
+  });
+});
+
 describe("FocusView", () => {
   function Panel(props: { onShownChange?: (shown: boolean) => void }) {
     const [shown, setShown] = useState(false);

package/src/__tests__/apps/kit/store.test.ts

@@ -0,0 +1,149 @@
+/*
+ * Hand-written. `createAppStore` (state shared by the views of one app) and `useNavParams`, through
+ * the real runtime. The host mounts every view of an app into one sandbox; here each
+ * `renderForTest` is its own runtime in the same module graph, which shares module state the
+ * same way.
+ */
+
+import { createElement as h } from "react";
+import { describe, expect, test, vi } from "vitest";
+import { createAppStore, useNavParams } from "../../../apps/hooks/index.js";
+import { getMockContext, mockPageRoute, renderForTest } from "../../../apps/testing/index.js";
+import { Button, ContextView, PageView, Text } from "../../../apps/ui/index.js";
+
+describe("createAppStore", () => {
+  test("setState merges fields, keeps the object when nothing changes, and tells listeners", () => {
+    const store = createAppStore({ count: 0, label: "a" });
+    const listener = vi.fn();
+    const unsubscribe = store.subscribe(listener);
+    const first = store.getState();
+
+    store.setState({ count: 1 });
+    expect(store.getState()).toEqual({ count: 1, label: "a" });
+    expect(listener).toHaveBeenCalledWith({ count: 1, label: "a" }, first);
+
+    const second = store.getState();
+    store.setState({ count: 1 });
+    store.setState((s) => ({ label: s.label }));
+    expect(store.getState()).toBe(second);
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    store.setState((s) => ({ count: s.count + 1 }));
+    expect(store.getState().count).toBe(2);
+    unsubscribe();
+    store.setState({ count: 3 });
+    expect(listener).toHaveBeenCalledTimes(2);
+  });
+
+  test("two mounted views see each other's updates", async () => {
+    const store = createAppStore({ saved: 0, last: "" });
+
+    function Panel() {
+      const saved = store.useStore((s) => s.saved);
+      return h(
+        ContextView,
+        { title: "Panel" },
+        h(Text, null, `saved ${saved}`),
+        h(Button, { onPress: () => store.setState((s) => ({ saved: s.saved + 1, last: "from panel" })) }, "Save"),
+      );
+    }
+    function Page() {
+      const state = store.useStore();
+      return h(
+        PageView,
+        { title: "Page" },
+        h(Text, null, `saved ${state.saved}, last ${state.last || "none"}`),
+        h(Button, { onPress: () => store.setState({ last: "from page" }) }, "Touch"),
+      );
+    }
+
+    const panel = await renderForTest(h(Panel));
+    const page = await renderForTest(h(Page), { context: { environment: { route: mockPageRoute("/") } } });
+    expect(page.find("Text")!.text).toBe("saved 0, last none");
+
+    await panel.find("Button")!.trigger("onPress");
+    await page.settle();
+    expect(panel.find("Text")!.text).toBe("saved 1");
+    expect(page.find("Text")!.text).toBe("saved 1, last from panel");
+
+    await page.find("Button")!.trigger("onPress");
+    await panel.settle();
+    expect(page.find("Text")!.text).toBe("saved 1, last from page");
+    // The panel selects `saved` only, which did not change.
+    expect(panel.find("Text")!.text).toBe("saved 1");
+    expect([...panel.errors, ...page.errors]).toEqual([]);
+  });
+
+  test("a view's subscription ends when it unmounts", async () => {
+    const store = createAppStore({ n: 0 });
+    let active = 0;
+    const subscribe = store.subscribe;
+    store.subscribe = (listener) => {
+      active += 1;
+      const unsubscribe = subscribe(listener);
+      return () => {
+        active -= 1;
+        unsubscribe();
+      };
+    };
+    let renders = 0;
+    function Counter() {
+      renders += 1;
+      return h(ContextView, { title: "Counter" }, h(Text, null, String(store.useStore((s) => s.n))));
+    }
+
+    const a = await renderForTest(h(Counter));
+    const b = await renderForTest(h(Counter));
+    expect(active).toBe(2);
+
+    await a.unmount();
+    expect(active).toBe(1);
+
+    const before = renders;
+    store.setState({ n: 1 });
+    await b.settle();
+    expect(b.find("Text")!.text).toBe("1");
+    expect(renders).toBe(before + 1); // only the mounted view rendered
+
+    await b.unmount();
+    expect(active).toBe(0);
+    store.setState({ n: 2 });
+    expect(renders).toBe(before + 1);
+  });
+
+  test("a selector that builds a new object from an unchanged state does not loop", async () => {
+    const store = createAppStore({ a: 1, b: 2 });
+    function Sum() {
+      const pair = store.useStore((s) => ({ sum: s.a + s.b }));
+      return h(ContextView, { title: "Sum" }, h(Text, null, String(pair.sum)));
+    }
+    const view = await renderForTest(h(Sum));
+    expect(view.find("Text")!.text).toBe("3");
+    store.setState({ a: 5 });
+    await view.settle();
+    expect(view.find("Text")!.text).toBe("7");
+    expect(view.errors).toEqual([]);
+  });
+});
+
+describe("useNavParams", () => {
+  function Target() {
+    const params = useNavParams();
+    return h(ContextView, { title: "Target" }, h(Text, null, JSON.stringify(params)));
+  }
+
+  test("is empty unless the view opened from a navigation", async () => {
+    const view = await renderForTest(h(Target));
+    expect(view.find("Text")!.text).toBe("{}");
+    expect(getMockContext().environment.navParams).toEqual({});
+  });
+
+  test("returns the navigation's envParams, separate from the URL query, and follows updateContext", async () => {
+    const view = await renderForTest(h(Target), {
+      context: { environment: { navParams: { vendorId: "42" }, queryParams: { vendorId: "666" } } },
+    });
+    expect(view.find("Text")!.text).toBe('{"vendorId":"42"}');
+    await view.updateContext({ environment: { ...view.context.environment, navParams: {} } });
+    expect(view.find("Text")!.text).toBe("{}");
+  });
+});

package/src/__tests__/apps/post-install-page.test.ts

@@ -0,0 +1,126 @@
+/*
+ * Hand-written. `post_install_action: { type: "app_page", path }`: installing opens one of the
+ * app's own pages. The cases come from `fixtures/post-install-page.json`, which the server's catalog
+ * spec reads too; see docs/third-party-apps/fullpageview-plan.md.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  CONCRETE_ROUTE_PATH_PATTERN,
+  effectivePostInstallAction,
+  manifestJsonSchema,
+  validateManifest,
+  type AppManifestV2,
+} from "../../apps/index.js";
+
+const FIXTURES = resolve(process.cwd(), "src", "__tests__", "apps", "fixtures", "post-install-page.json");
+
+interface Case { name: string; action: Record<string, unknown>; routes?: unknown[]; issue?: string }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function loadFixtures(): { routes: unknown[]; accepted: Case[]; rejected: Case[] } {
+  const parsed: unknown = JSON.parse(readFileSync(FIXTURES, "utf8"));
+  if (!isRecord(parsed) || !Array.isArray(parsed["routes"]) || !Array.isArray(parsed["accepted"]) || !Array.isArray(parsed["rejected"])) {
+    throw new Error("fixtures/post-install-page.json needs routes, accepted and rejected arrays");
+  }
+  return { routes: parsed["routes"], accepted: parsed["accepted"] as Case[], rejected: parsed["rejected"] as Case[] };
+}
+
+const fixtures = loadFixtures();
+
+function manifestFor(testCase: Case): Record<string, unknown> {
+  return {
+    id: 42,
+    name: "Acme Reports",
+    icon: "https://cdn.acme.com/icon.png",
+    short_description: "Reports about your vendors.",
+    version: "1.0.0",
+    configuration_instructions: "Install and sign in.",
+    support_instructions: "support@acme.com",
+    ui_extensions: {
+      bundle: {
+        url: "https://cdn.acme.com/gs-app/1.0.0/app.js",
+        integrity: "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC",
+      },
+      routes: testCase.routes ?? fixtures.routes,
+    },
+    post_install_action: testCase.action,
+  };
+}
+
+function issuePaths(testCase: Case): string[] {
+  const result = validateManifest(manifestFor(testCase));
+  return result.ok ? [] : result.issues.map((issue) => issue.path);
+}
+
+describe("post_install_action app_page", () => {
+  test.each(fixtures.accepted.map((c) => [c.name, c] as const))("accepts %s", (_name, testCase) => {
+    expect(issuePaths(testCase)).toEqual([]);
+  });
+
+  test.each(fixtures.rejected.map((c) => [c.name, c] as const))("rejects %s", (_name, testCase) => {
+    const paths = issuePaths(testCase);
+    expect(paths.length).toBeGreaterThan(0);
+    for (const path of paths) expect(path).toBe(testCase.issue);
+  });
+
+  test("an explicit app_page action is returned unchanged", () => {
+    const result = validateManifest(manifestFor({ name: "welcome", action: { type: "app_page", path: "/welcome" } }));
+    if (!result.ok) throw new Error("fixture invalid");
+    const manifest: AppManifestV2 = result.manifest;
+
+    expect(effectivePostInstallAction(manifest)).toEqual({ type: "app_page", path: "/welcome" });
+  });
+
+  test("the JSON schema carries the app_page type and the concrete path pattern", () => {
+    const schema: unknown = manifestJsonSchema();
+    if (!isRecord(schema) || !isRecord(schema["properties"])) throw new Error("schema has no properties");
+    const action = schema["properties"]["post_install_action"];
+    if (!isRecord(action) || !isRecord(action["properties"])) throw new Error("schema has no post_install_action");
+    const { type, path } = action["properties"];
+
+    expect(isRecord(type) && type["enum"]).toEqual(["url", "app_settings_view", "app_main_view", "app_page"]);
+    expect(isRecord(path) && path["maxLength"]).toBe(200);
+    // The generator escapes `/` as `\/`; the pattern is the same.
+    expect(isRecord(path) && typeof path["pattern"] === "string" && path["pattern"].replaceAll("\\/", "/"))
+      .toBe(CONCRETE_ROUTE_PATH_PATTERN);
+  });
+});
+
+describe("a failing ui_extensions field", () => {
+  test("is reported alone, without phantom post-install or view issues", () => {
+    const manifest = {
+      id: 1,
+      name: "A",
+      icon: "https://a.example.com/i.png",
+      short_description: "x",
+      configuration_instructions: "x",
+      support_instructions: "x",
+      version: "1.0.0",
+      ui_extensions: {
+        bundle: { url: "https://a.example.com/a.js", integrity: `sha384-${"A".repeat(64)}` },
+        views: [{ viewport: "settings", component: "S" }],
+        routes: [{ path: "/../settings", component: "P", title: "P" }],
+      },
+      post_install_action: { type: "app_settings_view" },
+    };
+    const result = validateManifest(manifest);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.issues.map((issue) => issue.path)).toEqual(["ui_extensions.routes.0.path"]);
+
+    const pageAction = validateManifest({ ...manifest, post_install_action: { type: "app_page", path: "/reports" } });
+    expect(pageAction.ok ? [] : pageAction.issues.map((issue) => issue.path)).toEqual(["ui_extensions.routes.0.path"]);
+
+    const strayPath = validateManifest({ ...manifest, post_install_action: { type: "url", url: "https://a.example.com/", path: "/x" } });
+    expect(strayPath.ok ? [] : strayPath.issues.map((issue) => issue.path)).toEqual([
+      "ui_extensions.routes.0.path",
+      "post_install_action.path",
+    ]);
+  });
+});