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

package/src/__tests__/apps/contract.test.ts

@@ -12,6 +12,8 @@ import { describe, expect, test } from "vitest";
 import {
   canonicalBuildPayload,
   APP_WEBHOOK_EVENTS,
+  CHART_DATA_LIMITS,
+  CHART_THEMES,
   COMPONENTS,
   componentsCatalogJson,
   CSP_DENYLIST,
@@ -25,11 +27,18 @@ import {
   getSurface,
   isBootstrapToHost,
   isCalendarDate,
+  isChartData,
+  isPieChartData,
+  CHART_OTHER_LABEL,
+  MAX_CHART_VALUE,
+  isComboChartData,
   isPlatformPermission,
   isRouteDescriptor,
   isSensitivePermission,
+  isSeriesChartData,
   isSurfaceId,
   manifestJsonSchema,
+  MAX_CHART_SERIES,
   mergeDevManifest,
   permissionReviewIssues,
   PLATFORM_PERMISSIONS,
@@ -41,6 +50,9 @@ import {
   tokenNeedsRefresh,
   validateManifest,
   type AppManifestV2,
+  type ChartClickEvent,
+  type ComboChartData,
+  type SeriesChartData,
   type ComponentProps,
   type HostToBootstrap,
 } from "../../apps/index.js";
@@ -86,7 +98,7 @@ describe("surfaces", () => {
     expect(new Set(ids).size).toBe(ids.length);
 
     for (const s of SURFACES) {
-      if (s.id === "settings") continue;
+      if (s.portal === null) continue;
       expect(s.id).toMatch(/^gs\.(vendor|company|facility|system)\.[a-z_]+(\.[a-z_]+)*$/);
       expect(s.id.startsWith(`gs.${s.portal}.`)).toBe(true);
       expect(s.id.endsWith(s.kind)).toBe(true);
@@ -98,6 +110,11 @@ describe("surfaces", () => {
       expect(s.route.startsWith(s.portal === null ? "/[portal]/" : `/${s.portal}`)).toBe(true);
     }
     expect(getSurface("settings")?.route).toBe("/[portal]/apps/[appId]/settings");
+    expect(getSurface("page")?.route).toBe("/[portal]/apps/[appId]/pages/[...path]");
+  });
+
+  test("the only portal-less surfaces are the app's own settings page and pages", () => {
+    expect(SURFACES.filter((s) => s.portal === null).map((s) => s.id).sort()).toEqual(["page", "settings"]);
   });
 
   test("wave 1 is the vendor and company portals only", () => {
@@ -482,9 +499,18 @@ describe("components", () => {
     expect(COMPONENTS.Text.children).toEqual(["ui-inline", "ui-link"]);
   });
 
-  test("only ContextView and SettingsView are roots", () => {
+  test("only ContextView, SettingsView and PageView are roots", () => {
     const roots = Object.entries(COMPONENTS).filter(([, c]) => "root" in c).map(([name]) => name);
-    expect(roots.sort()).toEqual(["ContextView", "SettingsView"]);
+    expect(roots.sort()).toEqual(["ContextView", "PageView", "SettingsView"]);
+  });
+
+  test("PageView takes a required title, a description and the actions and banner slots", () => {
+    expect(COMPONENTS.PageView.tagName).toBe("ui-page-view");
+    expect(COMPONENTS.PageView.slots).toEqual(["actions", "banner"]);
+    expect(sanitizeProps("ui-page-view", { title: "Reports", description: "All of them" }).props).toEqual({ title: "Reports", description: "All of them" });
+    expect(sanitizeProps("ui-page-view", { title: "t".repeat(101) }).dropped).toEqual(["title"]);
+    expect(sanitizeProps("ui-page-view", { title: "Reports", description: "d".repeat(301) }).dropped).toEqual(["description"]);
+    expect(componentsCatalogJson().find((c) => c.name === "PageView")).toMatchObject({ tagName: "ui-page-view", root: true });
   });
 
   test("sanitizeProps keeps declared props of the right type and drops everything else", () => {
@@ -688,6 +714,281 @@ describe("components", () => {
   });
 });
 
+describe("charts", () => {
+  const CHART_TAGS: Record<string, string> = {
+    BarChart: "ui-bar-chart",
+    HorizontalBarChart: "ui-horizontal-bar-chart",
+    StackedBarChart: "ui-stacked-bar-chart",
+    LineChart: "ui-line-chart",
+    AreaChart: "ui-area-chart",
+    ComboChart: "ui-combo-chart",
+    PieChart: "ui-pie-chart",
+  };
+  const labels = (n: number) => Array.from({ length: n }, (_, i) => `L${i}`);
+  const datums = (n: number) => labels(n).map((label, i) => ({ label, value: i }));
+  const seriesData = (nLabels: number, nSeries = 2): SeriesChartData => ({
+    labels: labels(nLabels),
+    series: Array.from({ length: nSeries }, (_, s) => ({ name: `S${s}`, values: labels(nLabels).map((_, i) => i + s) })),
+  });
+  const combo = (n: number): ComboChartData => ({
+    labels: labels(n),
+    bars: { name: "Visits", values: labels(n).map((_, i) => i) },
+    line: { name: "Average", values: labels(n).map((_, i) => i / 2) },
+  });
+  const BAD_VALUES: unknown[] = [-1, Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY, "3", null];
+  const BAD_LABELS: unknown[] = ["", "   ", "x".repeat(61), 5, null];
+  class Datum { constructor(public label: string, public value: number) {} }
+  class DatumArray extends Array<unknown> {}
+
+  test("seven chart entries with the same data-only props, a click event and no children", () => {
+    for (const [name, tag] of Object.entries(CHART_TAGS)) {
+      const c = COMPONENTS[name as keyof typeof COMPONENTS];
+      expect(c.tagName, name).toBe(tag);
+      expect(Object.keys(c.props).sort(), name).toEqual(["data", "interactive", "theme"]);
+      expect(c.events, name).toEqual({ onClick: { event: "click" } });
+      expect(c.children, name).toEqual([]);
+      expect(c.text, name).toBe(false);
+      expect(c.slots, name).toEqual([]);
+      const json = componentsCatalogJson().find((j) => j.name === name)!;
+      expect(json.props["data"]).toEqual({ type: "json", required: true });
+      expect(json.props["theme"]).toEqual({ type: "enum", required: false, values: ["green", "grayscale", "vibrant"] });
+      expect(json.events).toEqual({ onClick: "click" });
+    }
+    expect(CHART_THEMES).toEqual(["green", "grayscale", "vibrant"]);
+    expect(MAX_CHART_SERIES).toBe(6);
+  });
+
+  test("sanitizeProps requires data, checks theme and drops styling props", () => {
+    expect(sanitizeProps("ui-bar-chart", { theme: "green" }).missing).toEqual(["data"]);
+    const result = sanitizeProps("ui-bar-chart", { data: datums(3), theme: "neon", interactive: true, color: "#f00", style: {} });
+    expect(result.props).toEqual({ data: datums(3), interactive: true });
+    expect(result.dropped.sort()).toEqual(["color", "style", "theme"]);
+    expect(result.missing).toEqual([]);
+    const bad = sanitizeProps("ui-line-chart", { data: seriesData(1) });
+    expect(bad.dropped).toEqual(["data"]);
+    expect(bad.missing).toEqual(["data"]);
+  });
+
+  describe("chart value bounds", () => {
+    test("accepts values up to MAX_CHART_VALUE and rejects larger ones", () => {
+      const bar = CHART_DATA_LIMITS.BarChart;
+      expect(isChartData([{ label: "a", value: MAX_CHART_VALUE }], bar)).toBe(true);
+      for (const value of [MAX_CHART_VALUE + 2, 1e308, Number.MAX_VALUE]) {
+        expect(isChartData([{ label: "a", value }], bar)).toBe(false);
+      }
+    });
+
+    test("keeps every accepted total finite", () => {
+      const pie = Array.from({ length: 50 }, (_, i) => ({ label: `s${i}`, value: MAX_CHART_VALUE }));
+      expect(isPieChartData(pie)).toBe(true);
+      expect(Number.isFinite(pie.reduce((sum, d) => sum + d.value, 0))).toBe(true);
+      const limits = CHART_DATA_LIMITS.StackedBarChart;
+      const series = Array.from({ length: 6 }, (_, i) => ({ name: `s${i}`, values: [MAX_CHART_VALUE] }));
+      expect(isSeriesChartData({ labels: ["a"], series }, limits)).toBe(true);
+      const huge = [{ name: "x", values: [1e308] }, { name: "y", values: [1e308] }];
+      expect(isSeriesChartData({ labels: ["a"], series: huge }, limits)).toBe(false);
+    });
+  });
+
+  describe("isPieChartData", () => {
+    const datums = (n: number, first?: string) =>
+      Array.from({ length: n }, (_, i) => ({ label: i === 0 && first !== undefined ? first : `s${i}`, value: i + 1 }));
+
+    test("allows an Other label when the pie will not combine slices", () => {
+      expect(isPieChartData(datums(6, CHART_OTHER_LABEL))).toBe(true);
+    });
+
+    test("rejects a caller Other label when extra items will be combined into Other", () => {
+      for (const label of [CHART_OTHER_LABEL, "other", " OTHER "]) expect(isPieChartData(datums(7, label))).toBe(false);
+      expect(isPieChartData(datums(7, "Other documents"))).toBe(true);
+    });
+
+    test("keeps the generic pie limits", () => {
+      expect(isPieChartData(datums(50))).toBe(true);
+      expect(isPieChartData(datums(51))).toBe(false);
+      expect(isPieChartData([])).toBe(false);
+    });
+
+    test("is the guard the PieChart catalog entry uses", () => {
+      expect(sanitizeProps("ui-pie-chart", { data: datums(7, "Other") }).missing).toContain("data");
+      expect(sanitizeProps("ui-pie-chart", { data: datums(7) }).missing).not.toContain("data");
+    });
+  });
+
+  describe("isChartData", () => {
+    const bar = CHART_DATA_LIMITS.BarChart;
+    test("accepts a valid sample, including zero values and 60-character labels", () => {
+      expect(isChartData([{ label: "Mon", value: 0 }, { label: "x".repeat(60), value: 12.5 }], bar)).toBe(true);
+    });
+    test.each(BAD_VALUES)("rejects value %s", (value) => {
+      expect(isChartData([{ label: "a", value }], bar)).toBe(false);
+    });
+    test.each(BAD_LABELS)("rejects label %j", (label) => {
+      expect(isChartData([{ label, value: 1 }], bar)).toBe(false);
+    });
+    test("rejects duplicate labels", () => {
+      expect(isChartData([{ label: "a", value: 1 }, { label: "a", value: 2 }], bar)).toBe(false);
+    });
+    test("enforces each component's item counts", () => {
+      expect(isChartData([], bar)).toBe(false);
+      expect(isChartData(datums(31), bar)).toBe(true);
+      expect(isChartData(datums(32), bar)).toBe(false);
+      expect(isChartData(datums(25), CHART_DATA_LIMITS.HorizontalBarChart)).toBe(true);
+      expect(isChartData(datums(26), CHART_DATA_LIMITS.HorizontalBarChart)).toBe(false);
+      expect(isChartData(datums(50), CHART_DATA_LIMITS.PieChart)).toBe(true);
+      expect(isChartData(datums(51), CHART_DATA_LIMITS.PieChart)).toBe(false);
+      expect(sanitizeProps("ui-bar-chart", { data: datums(32) }).dropped).toEqual(["data"]);
+      expect(sanitizeProps("ui-pie-chart", { data: datums(32) }).dropped).toEqual([]);
+    });
+    test("rejects non-arrays, class instances, sparse arrays and extra keys", () => {
+      for (const v of [undefined, null, "a", 1, { label: "a", value: 1 }, new Map()]) expect(isChartData(v, bar)).toBe(false);
+      expect(isChartData([new Datum("a", 1)], bar)).toBe(false);
+      expect(isChartData(DatumArray.from([{ label: "a", value: 1 }]), bar)).toBe(false);
+      // eslint-disable-next-line no-sparse-arrays
+      expect(isChartData([{ label: "a", value: 1 }, , { label: "b", value: 2 }], bar)).toBe(false);
+      expect(isChartData([{ label: "a", value: 1, color: "red" }], bar)).toBe(false);
+      expect(isChartData([Object.assign(Object.create(null) as object, { label: "a", value: 1 })], bar)).toBe(true);
+    });
+  });
+
+  describe("isSeriesChartData", () => {
+    const stacked = CHART_DATA_LIMITS.StackedBarChart;
+    const line = CHART_DATA_LIMITS.LineChart;
+    test("accepts a valid sample", () => {
+      expect(isSeriesChartData(seriesData(5, 3), stacked)).toBe(true);
+      expect(isSeriesChartData(seriesData(5, MAX_CHART_SERIES), line)).toBe(true);
+    });
+    test("rejects more than six series, and no series", () => {
+      expect(isSeriesChartData(seriesData(5, MAX_CHART_SERIES + 1), stacked)).toBe(false);
+      expect(isSeriesChartData(seriesData(5, MAX_CHART_SERIES + 1), line)).toBe(false);
+      expect(isSeriesChartData(seriesData(5, 0), stacked)).toBe(false);
+    });
+    test("rejects a series whose values length differs from the labels", () => {
+      const d = seriesData(4);
+      d.series[1]!.values.pop();
+      expect(isSeriesChartData(d, stacked)).toBe(false);
+      d.series[1]!.values.push(1, 2);
+      expect(isSeriesChartData(d, stacked)).toBe(false);
+    });
+    test.each(BAD_VALUES)("rejects value %s", (value) => {
+      const d = seriesData(3) as { series: Array<{ values: unknown[] }> };
+      d.series[0]!.values[1] = value;
+      expect(isSeriesChartData(d, stacked)).toBe(false);
+    });
+    test.each(BAD_LABELS)("rejects label or series name %j", (bad) => {
+      const withLabel = seriesData(3) as { labels: unknown[] };
+      withLabel.labels[0] = bad;
+      expect(isSeriesChartData(withLabel, stacked)).toBe(false);
+      const withName = seriesData(3) as { series: Array<{ name: unknown }> };
+      withName.series[0]!.name = bad;
+      expect(isSeriesChartData(withName, stacked)).toBe(false);
+    });
+    test("rejects duplicate labels and duplicate series names", () => {
+      const dupLabel = seriesData(3);
+      dupLabel.labels[2] = dupLabel.labels[0]!;
+      expect(isSeriesChartData(dupLabel, stacked)).toBe(false);
+      const dupName = seriesData(3);
+      dupName.series[1]!.name = dupName.series[0]!.name;
+      expect(isSeriesChartData(dupName, stacked)).toBe(false);
+    });
+    test("enforces each component's label counts", () => {
+      expect(isSeriesChartData(seriesData(1), stacked)).toBe(true);
+      expect(isSeriesChartData(seriesData(31), stacked)).toBe(true);
+      expect(isSeriesChartData(seriesData(32), stacked)).toBe(false);
+      expect(isSeriesChartData(seriesData(1), line)).toBe(false);
+      expect(isSeriesChartData(seriesData(60), line)).toBe(true);
+      expect(isSeriesChartData(seriesData(61), line)).toBe(false);
+      expect(isSeriesChartData(seriesData(61), CHART_DATA_LIMITS.AreaChart)).toBe(false);
+      expect(isSeriesChartData(seriesData(1), CHART_DATA_LIMITS.AreaChart)).toBe(false);
+    });
+    test("rejects non-objects, class instances and extra keys", () => {
+      for (const v of [undefined, null, [], "x", datums(3)]) expect(isSeriesChartData(v, stacked)).toBe(false);
+      const d = seriesData(2);
+      expect(isSeriesChartData({ labels: d.labels, series: DatumArray.from(d.series) }, stacked)).toBe(false);
+      expect(isSeriesChartData({ ...d, labels: DatumArray.from(d.labels) }, stacked)).toBe(false);
+      expect(isSeriesChartData(Object.assign(new (class Data {})(), d), stacked)).toBe(false);
+      expect(isSeriesChartData({ ...d, title: "x" }, stacked)).toBe(false);
+      expect(isSeriesChartData({ ...d, series: [{ ...d.series[0]!, color: "red" }] }, stacked)).toBe(false);
+    });
+  });
+
+  describe("isComboChartData", () => {
+    const limits = CHART_DATA_LIMITS.ComboChart;
+    test("accepts a valid sample", () => {
+      expect(isComboChartData(combo(1), limits)).toBe(true);
+      expect(isComboChartData(combo(31), limits)).toBe(true);
+    });
+    test("rejects over-cap and empty labels", () => {
+      expect(isComboChartData(combo(32), limits)).toBe(false);
+      expect(isComboChartData(combo(0), limits)).toBe(false);
+    });
+    test("rejects bars or line values whose length differs from the labels", () => {
+      const bars = combo(3);
+      bars.bars.values.pop();
+      expect(isComboChartData(bars, limits)).toBe(false);
+      const line = combo(3);
+      line.line.values.push(1);
+      expect(isComboChartData(line, limits)).toBe(false);
+    });
+    test.each(BAD_VALUES)("rejects value %s", (value) => {
+      for (const key of ["bars", "line"] as const) {
+        const d = combo(3) as unknown as Record<typeof key, { values: unknown[] }>;
+        d[key].values[0] = value;
+        expect(isComboChartData(d, limits)).toBe(false);
+      }
+    });
+    test.each(BAD_LABELS)("rejects label or series name %j", (bad) => {
+      const withLabel = combo(3) as unknown as { labels: unknown[] };
+      withLabel.labels[1] = bad;
+      expect(isComboChartData(withLabel, limits)).toBe(false);
+      const withName = combo(3) as unknown as { line: { name: unknown } };
+      withName.line.name = bad;
+      expect(isComboChartData(withName, limits)).toBe(false);
+    });
+    test("rejects duplicate labels and a line named like the bars", () => {
+      const dupLabel = combo(3);
+      dupLabel.labels[1] = dupLabel.labels[0]!;
+      expect(isComboChartData(dupLabel, limits)).toBe(false);
+      const dupName = combo(3);
+      dupName.line.name = dupName.bars.name;
+      expect(isComboChartData(dupName, limits)).toBe(false);
+    });
+    test("rejects non-objects, class instances, series arrays and extra keys", () => {
+      for (const v of [undefined, null, [], "x", seriesData(3)]) expect(isComboChartData(v, limits)).toBe(false);
+      const d = combo(2);
+      expect(isComboChartData({ ...d, bars: [d.bars] }, limits)).toBe(false);
+      expect(isComboChartData({ ...d, labels: DatumArray.from(d.labels) }, limits)).toBe(false);
+      expect(isComboChartData(Object.assign(new (class Data {})(), d), limits)).toBe(false);
+      expect(isComboChartData({ ...d, extra: 1 }, limits)).toBe(false);
+    });
+  });
+
+  test("ComponentProps types chart data and the click detail (compile-time)", () => {
+    const bar: ComponentProps<"BarChart"> = {
+      data: [{ label: "Mon", value: 3 }],
+      theme: "vibrant",
+      interactive: true,
+      onClick: (e: ChartClickEvent) => e.index + e.value + e.label.length,
+    };
+    const comboProps: ComponentProps<"ComboChart"> = {
+      data: combo(2),
+      onClick: (e: ChartClickEvent) => e.series ?? e.label,
+    };
+    const stacked: ComponentProps<"StackedBarChart"> = { data: seriesData(2) };
+    // @ts-expect-error data is required
+    const noData: ComponentProps<"BarChart"> = { theme: "green" };
+    // @ts-expect-error a bar chart takes ChartDatum[], not series data
+    const wrongShape: ComponentProps<"BarChart"> = { data: seriesData(2) };
+    // @ts-expect-error themes are a closed set
+    const neon: ComponentProps<"PieChart"> = { data: datums(2), theme: "neon" };
+    // @ts-expect-error there are no colour props
+    const colored: ComponentProps<"LineChart"> = { data: seriesData(2), colors: ["#f00"] };
+    // @ts-expect-error onClick receives a ChartClickEvent, not a string
+    const wrongDetail: ComponentProps<"ComboChart"> = { data: combo(2), onClick: (s: string) => s.length };
+    expect([bar, comboProps, stacked, noData, wrongShape, neon, colored, wrongDetail]).toHaveLength(8);
+  });
+});
+
 describe("protocol and helpers", () => {
   test("isBootstrapToHost accepts known envelopes only", () => {
     expect(isBootstrapToHost({ kind: "ready" })).toBe(true);
@@ -749,7 +1050,7 @@ describe("protocol and helpers", () => {
 describe("bundle hygiene", () => {
   // The host renderer imports these; a value import of zod (directly or via manifest.ts or
   // devpreview.ts) would pull zod into the host app bundle. Type-only imports are erased.
-  test.each(["surfaces.ts", "route.ts", "context.ts", "protocol.ts", "components.ts", "url.ts", "devsession.ts", "review.ts"])(
+  test.each(["surfaces.ts", "route.ts", "routes.ts", "context.ts", "protocol.ts", "components.ts", "url.ts", "devsession.ts", "review.ts"])(
     "%s has no value import of zod, manifest.ts or devpreview.ts",
     (file) => {
       const source = readFileSync(resolve(process.cwd(), "src", "apps", file), "utf8");

package/src/__tests__/apps/devpreview-routes.test.ts

@@ -0,0 +1,103 @@
+/*
+ * Hand-written. Dev manifests (`green-app.dev.json`) and app pages: a dev file may override
+ * `ui_extensions.routes` the way it overrides views, so `apps-cli dev` previews a page before it is
+ * published. The server mirrors these rules in `MarketplaceAppDevManifest`; see
+ * docs/third-party-apps/fullpageview-plan.md.
+ */
+
+import { describe, expect, test } from "vitest";
+import {
+  APP_ROUTES_MAX,
+  devManifestSchema,
+  DevManifestError,
+  mergeDevManifest,
+  validateManifest,
+  type AppManifestV2,
+} from "../../apps/index.js";
+
+function page(path: string, fields: Record<string, unknown> = {}): Record<string, unknown> {
+  return { path, component: "Page", title: "Page", ...fields };
+}
+
+function published(overrides: Record<string, unknown> = {}): AppManifestV2 {
+  const result = validateManifest({
+    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",
+      },
+      views: [{ viewport: "settings", component: "AppSettings" }],
+      routes: [page("/reports")],
+    },
+    ...overrides,
+  });
+  if (!result.ok) throw new Error("fixture invalid");
+  return result.manifest;
+}
+
+function issuePaths(value: unknown): string[] {
+  const result = devManifestSchema.safeParse(value);
+  return result.success ? [] : result.error.issues.map((issue) => issue.path.join("."));
+}
+
+describe("dev manifest routes", () => {
+  test("a dev file may declare routes, with the published route rules", () => {
+    const dev = {
+      extends: "green-app.json",
+      ui_extensions: { routes: [page("/", { navigation: { label: "Home" } }), page("/reports/:id", { portals: ["vendor"] })] },
+    };
+
+    expect(devManifestSchema.safeParse(dev).success).toBe(true);
+  });
+
+  test("dev routes are held to the grammar, title and portals rules", () => {
+    expect(issuePaths({ extends: "x", ui_extensions: { routes: [page("/../settings")] } })).toEqual(["ui_extensions.routes.0.path"]);
+    expect(issuePaths({ extends: "x", ui_extensions: { routes: [{ path: "/reports", component: "Page" }] } })).toEqual(["ui_extensions.routes.0.title"]);
+    expect(issuePaths({ extends: "x", ui_extensions: { routes: [page("/reports", { portals: ["admin"] })] } })).toEqual(["ui_extensions.routes.0.portals.0"]);
+    const tooMany = Array.from({ length: APP_ROUTES_MAX + 1 }, (_, i) => page(`/p${i}`));
+    expect(issuePaths({ extends: "x", ui_extensions: { routes: tooMany } })).toEqual(["ui_extensions.routes"]);
+  });
+
+  test("dev routes reject duplicate paths, repeated params and repeated portals, like published ones", () => {
+    expect(issuePaths({ extends: "x", ui_extensions: { routes: [page("/vendors/:id"), page("/vendors/:vendor_id")] } }))
+      .toEqual(["ui_extensions.routes.1.path"]);
+    expect(issuePaths({ extends: "x", ui_extensions: { routes: [page("/a/:id/b/:id")] } })).toEqual(["ui_extensions.routes.0.path"]);
+    expect(issuePaths({ extends: "x", ui_extensions: { routes: [page("/r", { portals: ["vendor", "vendor"] })] } }))
+      .toEqual(["ui_extensions.routes.0.portals"]);
+    expect(issuePaths({ extends: "x", ui_extensions: { routes: [page("/r/:id", { navigation: {} })] } }))
+      .toEqual(["ui_extensions.routes.0.navigation"]);
+  });
+
+  test("mergeDevManifest replaces the published routes when the dev file declares them", () => {
+    const routes = [page("/"), page("/reports/:id")];
+    const merged = mergeDevManifest(published(), devManifestSchema.parse({ extends: "green-app.json", ui_extensions: { routes } }));
+
+    expect(merged.ui_extensions?.routes).toEqual(routes);
+    expect(merged.ui_extensions?.views).toEqual([{ viewport: "settings", component: "AppSettings" }]);
+  });
+
+  test("mergeDevManifest keeps the published routes when the dev file leaves them out, and drops them for []", () => {
+    const base = published();
+
+    expect(mergeDevManifest(base, { extends: "green-app.json", ui_extensions: { views: [] } }).ui_extensions?.routes)
+      .toEqual([page("/reports")]);
+    expect(mergeDevManifest(base, { extends: "green-app.json" }).ui_extensions?.routes).toEqual([page("/reports")]);
+    expect(mergeDevManifest(base, { extends: "green-app.json", ui_extensions: { routes: [] } }).ui_extensions?.routes).toEqual([]);
+  });
+
+  test("a versionless (v1) base cannot be previewed with routes", () => {
+    const v1 = published({ version: undefined, ui_extensions: undefined });
+    const dev = devManifestSchema.parse({ extends: "green-app.json", ui_extensions: { routes: [page("/")] } });
+
+    expect(() => mergeDevManifest(v1, dev)).toThrow(DevManifestError);
+    expect(() => mergeDevManifest(v1, dev)).toThrow("the base manifest needs a version before its routes can be previewed");
+    expect(() => mergeDevManifest(v1, { extends: "green-app.json", ui_extensions: { routes: [] } })).not.toThrow();
+  });
+});

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([]);
+  });
 });