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

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

@@ -0,0 +1,318 @@
+/*
+ * Hand-written. Tests for app page routes (`ui_extensions.routes`): the grammar and uniqueness
+ * rules in the manifest schema, the shared matcher, the `page` surface and the `appPage`
+ * descriptor. The route sets and match cases come from `fixtures/routes.json`, which the server
+ * specs read 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 {
+  APP_PAGES_SEGMENT,
+  APP_ROUTES_MAX,
+  appPagePathname,
+  effectivePostInstallAction,
+  getSurface,
+  isConcreteRoutePath,
+  isRouteDescriptor,
+  isRoutePath,
+  isSurfaceId,
+  manifestJsonSchema,
+  matchAppRoute,
+  normalizeRoutePath,
+  ROUTE_PATH_MAX_SEGMENTS,
+  ROUTE_PATH_PATTERN,
+  SURFACES,
+  surfacesForPortal,
+  validateManifest,
+  type AppManifestV2,
+  type ExtensionContext,
+  type PageRoute,
+  type ViewType,
+} from "../../apps/index.js";
+import { NON_BLANK_PATTERN } from "../../apps/manifest.js";
+
+// Resolved from the package root (vitest's cwd), as contract.test.ts does for shared/app-platform.
+const FIXTURES = resolve(process.cwd(), "src", "__tests__", "apps", "fixtures", "routes.json");
+
+interface RouteSet {
+  name: string;
+  routes: unknown[];
+}
+interface RejectedSet extends RouteSet {
+  reason: string;
+  issue: string;
+}
+interface MatchCase {
+  name: string;
+  routes: string[];
+  pathname: string;
+  expected: { index: number; path: string; params: Record<string, string> } | null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function loadFixtures(): { accepted: RouteSet[]; rejected: RejectedSet[]; matches: MatchCase[] } {
+  const parsed: unknown = JSON.parse(readFileSync(FIXTURES, "utf8"));
+  if (
+    !isRecord(parsed) ||
+    !Array.isArray(parsed["accepted"]) ||
+    !Array.isArray(parsed["rejected"]) ||
+    !Array.isArray(parsed["matches"])
+  ) {
+    throw new Error("fixtures/routes.json needs accepted, rejected and matches arrays");
+  }
+  return {
+    accepted: parsed["accepted"] as RouteSet[],
+    rejected: parsed["rejected"] as RejectedSet[],
+    matches: parsed["matches"] as MatchCase[],
+  };
+}
+
+const fixtures = loadFixtures();
+
+function manifestWithRoutes(routes: unknown, overrides: Record<string, unknown> = {}): 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,
+    },
+    ...overrides,
+  };
+}
+
+function issuePaths(input: unknown): string[] {
+  const result = validateManifest(input);
+  return result.ok ? [] : result.issues.map((i) => i.path);
+}
+
+const page = (path: string) => ({ path, component: "Page", title: "Page" });
+
+describe("route fixtures: manifest schema", () => {
+  test("the fixture file has cases of every kind", () => {
+    expect(fixtures.accepted.length).toBeGreaterThan(0);
+    expect(fixtures.rejected.length).toBeGreaterThan(0);
+    expect(fixtures.matches.length).toBeGreaterThan(0);
+  });
+
+  test.each(fixtures.accepted.map((set) => [set.name, set] as const))("accepts %s", (_name, set) => {
+    const result = validateManifest(manifestWithRoutes(set.routes));
+    expect(result.ok ? [] : result.issues).toEqual([]);
+  });
+
+  test.each(fixtures.rejected.map((set) => [set.name, set] as const))("rejects %s", (_name, set) => {
+    expect(issuePaths(manifestWithRoutes(set.routes))).toContain(`ui_extensions.${set.issue}`);
+  });
+
+  test.each(
+    fixtures.rejected
+      .filter((set) => /^(path_format|path_too_long|too_many_segments)$/.test(set.reason))
+      .map((set) => [set.name, set] as const),
+  )("isRoutePath refuses the path of %s", (_name, set) => {
+    const route = set.routes[0];
+    expect(isRecord(route) && isRoutePath(route["path"])).toBe(false);
+  });
+
+  test("every accepted path is a route path, and every static-only one is concrete", () => {
+    for (const set of fixtures.accepted) {
+      for (const route of set.routes) {
+        const path = isRecord(route) ? route["path"] : undefined;
+        expect(isRoutePath(path), String(path)).toBe(true);
+        if (typeof path === "string") expect(isConcreteRoutePath(path)).toBe(!path.includes(":"));
+      }
+    }
+  });
+});
+
+describe("route fixtures: matchAppRoute", () => {
+  test.each(fixtures.matches.map((c) => [c.name, c] as const))("%s", (_name, c) => {
+    const routes = c.routes.map((path) => ({ path }));
+    const match = matchAppRoute(routes, c.pathname);
+    if (c.expected === null) {
+      expect(match).toBeNull();
+    } else {
+      expect(match).toEqual({ route: routes[c.expected.index], params: c.expected.params, index: c.expected.index });
+      expect(match?.route.path).toBe(c.expected.path);
+    }
+  });
+
+  test("returns the caller's own route object", () => {
+    const routes = [{ path: "/reports/:id", component: "Report", title: "Report" }];
+    expect(matchAppRoute(routes, "/reports/7")?.route).toBe(routes[0]);
+  });
+});
+
+describe("route rules", () => {
+  test("NON_BLANK_PATTERN is JavaScript's \\S on every code point, spelled out for Ruby", () => {
+    const pattern = new RegExp(NON_BLANK_PATTERN);
+    const differ: string[] = [];
+    for (let code = 0; code <= 0x10ffff; code++) {
+      if (code >= 0xd800 && code <= 0xdfff) continue;
+      const char = String.fromCodePoint(code);
+      if (pattern.test(char) !== /\S/.test(char)) differ.push(code.toString(16));
+    }
+    expect(differ).toEqual([]);
+  });
+
+  test("normalizeRoutePath renames every param to :_", () => {
+    expect(normalizeRoutePath("/")).toBe("/");
+    expect(normalizeRoutePath("/reports")).toBe("/reports");
+    expect(normalizeRoutePath("/vendors/:id/edit")).toBe("/vendors/:_/edit");
+    expect(normalizeRoutePath("/:a/:b")).toBe(normalizeRoutePath("/:x/:y"));
+  });
+
+  test("the JSON Schema carries the path grammar", () => {
+    const schema = manifestJsonSchema() as {
+      properties: {
+        ui_extensions: {
+          properties: { routes: { items: { properties: { path: { pattern: string } }; required: string[] } } };
+        };
+      };
+    };
+    const item = schema.properties.ui_extensions.properties.routes.items;
+    // zod writes `/` as `\/`; the two patterns are the same regular expression.
+    expect(item.properties.path.pattern.replace(/\\\//g, "/")).toBe(ROUTE_PATH_PATTERN);
+    expect(item.required).toEqual(["path", "component", "title"]);
+    expect(ROUTE_PATH_MAX_SEGMENTS).toBe(8);
+  });
+
+  test(`a manifest takes at most ${APP_ROUTES_MAX} routes`, () => {
+    const routes = Array.from({ length: APP_ROUTES_MAX + 1 }, (_, i) => page(`/p${i}`));
+    expect(validateManifest(manifestWithRoutes(routes.slice(0, APP_ROUTES_MAX))).ok).toBe(true);
+    expect(issuePaths(manifestWithRoutes(routes))).toContain("ui_extensions.routes");
+  });
+
+  test("routes need a bundle and a version, like views", () => {
+    const noBundle = manifestWithRoutes([page("/reports")]);
+    noBundle["ui_extensions"] = { routes: [page("/reports")] };
+    expect(issuePaths(noBundle)).toContain("ui_extensions.bundle");
+
+    const noVersion = manifestWithRoutes([page("/reports")]);
+    delete noVersion["version"];
+    noVersion["ui_extensions"] = { routes: [page("/reports")] };
+    expect(issuePaths(noVersion)).toEqual(expect.arrayContaining(["ui_extensions.bundle", "version"]));
+  });
+
+  test("a root route is a main view; any other route is not", () => {
+    const root = manifestWithRoutes([page("/")]);
+    expect(effectivePostInstallAction(root as AppManifestV2)).toEqual({ type: "app_main_view" });
+    expect(validateManifest({ ...root, post_install_action: { type: "app_main_view" } }).ok).toBe(true);
+
+    const nested = manifestWithRoutes([page("/reports")]);
+    expect(effectivePostInstallAction(nested as AppManifestV2)).toBeNull();
+    expect(issuePaths({ ...nested, post_install_action: { type: "app_main_view" } })).toContain(
+      "post_install_action.type",
+    );
+  });
+});
+
+describe("the page surface", () => {
+  test("is portal-less, wave 1, under the reserved prefix", () => {
+    expect(getSurface("page")).toEqual({
+      id: "page",
+      portal: null,
+      kind: "page",
+      objectType: null,
+      route: `/[portal]/apps/[appId]/${APP_PAGES_SEGMENT}/[...path]`,
+      idParam: "appId",
+      wave: 1,
+    });
+    expect(isSurfaceId("page")).toBe(true);
+  });
+
+  test("no other surface lives under the app pages prefix", () => {
+    // Literal portal segments too: `/company/apps/[appId]/pages` is the same place for a company user.
+    const reserved = new RegExp(`^/[^/]+/apps/\\[appId\\]/${APP_PAGES_SEGMENT}(/|$)`);
+    const offenders = SURFACES.filter((s) => s.id !== "page" && reserved.test(s.route)).map((s) => s.id);
+    expect(offenders).toEqual([]);
+  });
+
+  test("is never listed as a portal surface", () => {
+    for (const portal of ["company", "vendor", "facility", "system"] as const) {
+      expect(surfacesForPortal(portal, 2).map((s) => s.id)).not.toContain("page");
+    }
+  });
+
+  test("is not a view viewport: pages are declared as routes", () => {
+    const m = manifestWithRoutes([page("/reports")]);
+    (m["ui_extensions"] as Record<string, unknown>)["views"] = [{ viewport: "page", component: "Page" }];
+    expect(issuePaths(m)).toContain("ui_extensions.views.0.viewport");
+  });
+
+  test("appPagePathname puts the root page at the prefix itself", () => {
+    expect(appPagePathname("company", 42, "/")).toBe("/company/apps/42/pages");
+    expect(appPagePathname("vendor", 42, "/reports/7")).toBe("/vendor/apps/42/pages/reports/7");
+  });
+
+  test.each(["/../settings", "/reports/../../settings", "//evil.example", "/reports/:id", "reports", "", "/Reports"])(
+    "appPagePathname rejects %j, which is not a concrete route path",
+    (path) => {
+      expect(() => appPagePathname("company", 42, path)).toThrow(RangeError);
+    },
+  );
+
+  test.each([0, -1, 1.5, Number.NaN])("appPagePathname rejects app id %p", (appId) => {
+    expect(() => appPagePathname("company", appId, "/")).toThrow(RangeError);
+  });
+});
+
+describe("appPage route descriptors", () => {
+  test("take a concrete path in the route grammar", () => {
+    expect(isRouteDescriptor({ type: "appPage", path: "/" })).toBe(true);
+    expect(isRouteDescriptor({ type: "appPage", path: "/reports/7" })).toBe(true);
+    expect(isRouteDescriptor({ type: "appPage", path: "/pages/foo", envParams: { tab: "a" } })).toBe(true);
+    expect(isRouteDescriptor({ type: "appPage", path: "/settings" })).toBe(true);
+  });
+
+  test.each([
+    "/vendors/:id",
+    "/../settings",
+    "/reports/..",
+    "/%2e%2e/settings",
+    "/Reports",
+    "/reports/",
+    "/reports//7",
+    "reports",
+    "",
+    "/reports?x=1",
+    "https://evil.example/x",
+    `/${"a".repeat(200)}`,
+    "/a/b/c/d/e/f/g/h/i",
+  ])("refuse %j", (path) => {
+    expect(isRouteDescriptor({ type: "appPage", path })).toBe(false);
+  });
+
+  test("refuse a missing path, a non-string path and bad envParams", () => {
+    expect(isRouteDescriptor({ type: "appPage" })).toBe(false);
+    expect(isRouteDescriptor({ type: "appPage", path: 7 })).toBe(false);
+    expect(isRouteDescriptor({ type: "appPage", path: "/reports", envParams: { a: 1 } })).toBe(false);
+  });
+
+  test("the page surface is not a surface target, like settings", () => {
+    expect(isRouteDescriptor({ type: "surface", surfaceId: "page" })).toBe(false);
+    expect(isRouteDescriptor({ type: "surface", surfaceId: "page", objectId: 7 })).toBe(false);
+  });
+});
+
+describe("page context types", () => {
+  test("environment.route and the page view type type-check", () => {
+    const route: PageRoute = { path: "/reports/:id", pathname: "/reports/7", params: { id: "7" } };
+    const env: Pick<ExtensionContext["environment"], "surfaceId" | "route"> = { surfaceId: "page", route };
+    const viewType: ViewType = "page";
+    expect(env.route?.params["id"]).toBe("7");
+    expect(viewType).toBe("page");
+  });
+});

package/src/__tests__/vendors.test.ts

@@ -121,7 +121,7 @@ test("Vendors List Vendor Credits", async () => {
       page: 1,
       useUrlParams: false,
     },
-    creditBalance: 6004.18,
+    creditBalance: 6030.32,
   });
 });
 

package/src/__tests__/zoneDevicesCreate.test.ts

@@ -0,0 +1,56 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Typed parameters so mock.calls is the argument tuple; see smartBadgeGetPsks.test.ts.
+const { doPostMock, doGetSingleMock } = vi.hoisted(() => ({
+  doPostMock: vi.fn((_route: string, _body: unknown) => Promise.resolve([{ ok: true }, { status: "complete" }])),
+  doGetSingleMock: vi.fn((_route: string, _query: unknown) =>
+    Promise.resolve([{ ok: true }, { status: "complete" }])
+  ),
+}));
+
+vi.mock("../admin-funcs/doAdmin.js", () => ({
+  $doPost: doPostMock,
+  $doGetSingle: doGetSingleMock,
+}));
+
+import { __internal } from "../index.extras.js";
+
+describe("__internal.zoneDevices", () => {
+  beforeEach(() => {
+    doPostMock.mockClear();
+    doGetSingleMock.mockClear();
+  });
+
+  it("posts the gateway body verbatim to /zone-devices", () => {
+    const body = {
+      zone_id: 7,
+      network_id: 3,
+      connection_type: "ethernet" as const,
+      mac_address: "AA:BB:CC:DD:EE:FF",
+      name: "Lobby gateway",
+    };
+
+    __internal.zoneDevices.create(body);
+
+    expect(doPostMock).toHaveBeenCalledWith("/zone-devices", body);
+  });
+
+  it("sends the MAC as a query parameter to the availability check", () => {
+    __internal.zoneDevices.macAvailability("AA:BB:CC:DD:EE:FF");
+
+    expect(doGetSingleMock).toHaveBeenCalledWith("/zone-devices/mac-availability", {
+      mac_address: "AA:BB:CC:DD:EE:FF",
+    });
+  });
+
+  // a5d10295d4 once dropped these from __internal while gatekeeper-client still called them.
+  it("keeps the gatekeeper networks and zone device calls exported", () => {
+    expect(__internal.networks).toEqual({
+      list: expect.any(Function),
+      get: expect.any(Function),
+      create: expect.any(Function),
+    });
+    expect(__internal.zoneDevices.list).toEqual(expect.any(Function));
+    expect(__internal.zoneDevices.get).toEqual(expect.any(Function));
+  });
+});

package/src/__tests__/zones.test.ts

@@ -39,32 +39,7 @@ test("Zones List Or Search Security Zones", async () => {
         facility: {},
       },
       {
-        facility: {
-          contacts: {
-            contact: {
-              status: "Active",
-              department: 123,
-            },
-            adminContact: {
-              status: "Inactive",
-              department: 123,
-            },
-            techContact: {
-              status: "Active",
-              department: 123,
-            },
-            greenSecurityCsm: {
-              status: "Active",
-              department: 123,
-            },
-            accountManager: null,
-          },
-          vendorGuestPolicy: {
-            enabled: false,
-            vendorGuestLimitAndOr: "and",
-            vendorGuestRequireEmail: true,
-          },
-        },
+        facility: {},
       },
     ],
   });
@@ -82,8 +57,9 @@ test("Zones Security Zone Checkin", async () => {
   });
 
   const result = await greenSecurity.zones.securityZoneCheckin({
-    qrCode: "<value>",
-    zoneId: 776072,
+    longitude: 5032.22,
+    latitude: 327.09,
+    zoneId: 542452,
   });
   expect(result).toBeDefined();
   expect(result).toEqual({});

package/src/admin-funcs/zoneDevicesCreate.ts

@@ -0,0 +1,22 @@
+import { APIPromise } from "../types/async.js";
+import { $doPost, internalApiResult } from "./doAdmin.js";
+
+export type zoneDeviceConnectionType = "ethernet" | "wifi";
+
+// Wire names, posted verbatim like networksCreateRequest.
+export type zoneDevicesCreateRequest = {
+  zone_id: number;
+  network_id: number;
+  connection_type: zoneDeviceConnectionType;
+  mac_address: string;
+  name: string;
+};
+
+// Saves an MG6 gateway from the Gatekeeper create-gateway flow (GSSD-7286). Provisioning is a
+// separate call.
+//
+// Internal for the same reason as zoneDevicesList. 409 means the MAC is already a gateway
+// somewhere; the server never says where.
+export function zoneDevicesCreate(request: zoneDevicesCreateRequest): internalApiResult {
+  return new APIPromise($doPost("/zone-devices", request));
+}

package/src/admin-funcs/zoneDevicesMacAvailability.ts

@@ -0,0 +1,8 @@
+import { APIPromise } from "../types/async.js";
+import { $doGetSingle, internalApiResult } from "./doAdmin.js";
+
+// Whether a scanned MAC is free to become a gateway: `{ mac_address, available }`, with the MAC
+// normalized. A query parameter rather than a path segment, so no separator needs escaping.
+export function zoneDevicesMacAvailability(macAddress: string): internalApiResult {
+  return new APIPromise($doGetSingle("/zone-devices/mac-availability", { mac_address: macAddress }));
+}

package/src/apps/components.ts

@@ -163,11 +163,176 @@ const isConfirmCloseMessages = (v: unknown): v is ConfirmCloseMessages =>
 
 const TABLE_CELL = { align: p.enum(["start", "center", "end"] as const), width: p.enum(WIDTHS) };
 
+// ---------------------------------------------------------------------------------------------
+// Charts
+//
+// Charts take data only. Colours come from a named `theme`; there are no colour, font, size or
+// style props. Every value is a finite number >= 0 (v1 draws no negative axis), and every label
+// and series name is visible text the host draws on an axis, legend or tooltip.
+
+/** Named palettes the host draws charts with. The host uses `"green"` when `theme` is omitted. */
+export const CHART_THEMES = ["green", "grayscale", "vibrant"] as const;
+
+/** Most series a stacked, line or area chart may draw: one per palette colour. */
+export const MAX_CHART_SERIES = 6;
+/**
+ * Largest accepted chart value. Every chart caps its item and series counts, so with each value at
+ * most this, any total a chart computes (a stack, a pie) stays finite; two values near
+ * `Number.MAX_VALUE` would otherwise sum to `Infinity`.
+ */
+export const MAX_CHART_VALUE = Number.MAX_SAFE_INTEGER;
+
+/** Longest label or series name, in characters. */
+export const MAX_CHART_LABEL_LENGTH = 60;
+
+/** One bar or slice: `label` names it, `value` is its size. */
+export interface ChartDatum { label: string; value: number }
+/** A named series with one value per label of the chart it belongs to. */
+export interface ChartSeries { name: string; values: number[] }
+/** Labels along the category axis and the series drawn against them. */
+export interface SeriesChartData { labels: string[]; series: ChartSeries[] }
+/** Bars and a line drawn over the same labels. */
+export interface ComboChartData { labels: string[]; bars: ChartSeries; line: ChartSeries }
+/**
+ * The detail of a chart's `onClick`: the position and label of the pressed bar, point or slice,
+ * its value, and, on a multi-series chart, the name of its series.
+ */
+export interface ChartClickEvent { index: number; label: string; value: number; series?: string }
+
+/** Item-count bounds for {@link isChartData}. */
+export interface ChartDataLimits { minItems: number; maxItems: number }
+/** Label- and series-count bounds for {@link isSeriesChartData}; `maxSeries` defaults to {@link MAX_CHART_SERIES}. */
+export interface SeriesChartDataLimits { minLabels: number; maxLabels: number; maxSeries?: number }
+/** Label-count bounds for {@link isComboChartData}. */
+export interface ComboChartDataLimits { minLabels: number; maxLabels: number }
+
+/** The bounds each chart component's `data` is checked against. */
+export const CHART_DATA_LIMITS = {
+  BarChart: { minItems: 1, maxItems: 31 },
+  HorizontalBarChart: { minItems: 1, maxItems: 25 },
+  StackedBarChart: { minLabels: 1, maxLabels: 31, maxSeries: MAX_CHART_SERIES },
+  LineChart: { minLabels: 2, maxLabels: 60, maxSeries: MAX_CHART_SERIES },
+  AreaChart: { minLabels: 2, maxLabels: 60, maxSeries: MAX_CHART_SERIES },
+  ComboChart: { minLabels: 1, maxLabels: 31 },
+  // The host folds everything past the sixth slice into one "Other" slice.
+  PieChart: { minItems: 1, maxItems: 50 },
+} as const satisfies Record<string, ChartDataLimits | SeriesChartDataLimits | ComboChartDataLimits>;
+
+// Plain data only, as JSON and remote-dom carry it: no class instances (Date, Map, a subclassed
+// Array) whose prototype the host would otherwise have to trust.
+const isPlainObject = (v: unknown): v is Record<string, unknown> => {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const proto: unknown = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+};
+const isPlainArray = (v: unknown): v is unknown[] => Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype;
+// Exactly these keys: the shapes are closed, which also bounds their nesting depth.
+const hasExactKeys = (v: Record<string, unknown>, keys: readonly string[]): boolean => {
+  const own = Object.keys(v);
+  return own.length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(v, k));
+};
+const isChartValue = (v: unknown): v is number =>
+  typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= MAX_CHART_VALUE;
+const isChartLabel = (v: unknown): v is string => isVisibleText(v, MAX_CHART_LABEL_LENGTH);
+
+// Indexed loops rather than `every`, which skips the holes of a sparse array.
+function isLabelList(v: unknown, min: number, max: number): v is string[] {
+  if (!isPlainArray(v) || v.length < min || v.length > max) return false;
+  const seen = new Set<string>();
+  for (let i = 0; i < v.length; i++) {
+    const label = v[i];
+    if (!isChartLabel(label) || seen.has(label)) return false;
+    seen.add(label);
+  }
+  return true;
+}
+
+function isChartSeries(v: unknown, length: number): v is ChartSeries {
+  if (!isPlainObject(v) || !hasExactKeys(v, ["name", "values"]) || !isChartLabel(v["name"])) return false;
+  const values = v["values"];
+  if (!isPlainArray(values) || values.length !== length) return false;
+  for (let i = 0; i < values.length; i++) if (!isChartValue(values[i])) return false;
+  return true;
+}
+
+/**
+ * `ChartDatum[]` with between `minItems` and `maxItems` items, each a visible, unique label of at
+ * most {@link MAX_CHART_LABEL_LENGTH} characters and a value from 0 to {@link MAX_CHART_VALUE}.
+ */
+export function isChartData(value: unknown, limits: ChartDataLimits): value is ChartDatum[] {
+  if (!isPlainArray(value) || value.length < limits.minItems || value.length > limits.maxItems) return false;
+  const seen = new Set<string>();
+  for (let i = 0; i < value.length; i++) {
+    const item = value[i];
+    if (!isPlainObject(item) || !hasExactKeys(item, ["label", "value"])) return false;
+    const label = item["label"];
+    if (!isChartLabel(label) || seen.has(label) || !isChartValue(item["value"])) return false;
+    seen.add(label);
+  }
+  return true;
+}
+
+/** Label of the slice a pie chart creates when it combines items beyond {@link MAX_CHART_SERIES}. */
+export const CHART_OTHER_LABEL = "Other";
+
+/**
+ * Pie chart data: {@link isChartData} with `CHART_DATA_LIMITS.PieChart`. When there are more
+ * items than {@link MAX_CHART_SERIES}, the host combines the extras into a {@link CHART_OTHER_LABEL}
+ * slice, so a caller's own `Other` label (any case, ignoring surrounding spaces) is rejected:
+ * the chart would show two slices with that name and their click events could not be told apart.
+ */
+export function isPieChartData(value: unknown): value is ChartDatum[] {
+  if (!isChartData(value, CHART_DATA_LIMITS.PieChart)) return false;
+  if (value.length <= MAX_CHART_SERIES) return true;
+  const reserved = CHART_OTHER_LABEL.toLowerCase();
+  return value.every((item) => item.label.trim().toLowerCase() !== reserved);
+}
+
+/**
+ * `SeriesChartData` with between `minLabels` and `maxLabels` unique labels and between 1 and
+ * `maxSeries` uniquely named series, each with exactly one value from 0 to {@link MAX_CHART_VALUE} per label.
+ */
+export function isSeriesChartData(value: unknown, limits: SeriesChartDataLimits): value is SeriesChartData {
+  if (!isPlainObject(value) || !hasExactKeys(value, ["labels", "series"])) return false;
+  const labels = value["labels"];
+  const series = value["series"];
+  const maxSeries = limits.maxSeries ?? MAX_CHART_SERIES;
+  if (!isLabelList(labels, limits.minLabels, limits.maxLabels)) return false;
+  if (!isPlainArray(series) || series.length < 1 || series.length > maxSeries) return false;
+  const names = new Set<string>();
+  for (let i = 0; i < series.length; i++) {
+    const s = series[i];
+    if (!isChartSeries(s, labels.length) || names.has(s.name)) return false;
+    names.add(s.name);
+  }
+  return true;
+}
+
+/**
+ * `ComboChartData` with between `minLabels` and `maxLabels` unique labels, and a `bars` and a
+ * `line` series with different names, each with exactly one value from 0 to {@link MAX_CHART_VALUE} per label.
+ */
+export function isComboChartData(value: unknown, limits: ComboChartDataLimits): value is ComboChartData {
+  if (!isPlainObject(value) || !hasExactKeys(value, ["labels", "bars", "line"])) return false;
+  const labels = value["labels"];
+  const bars = value["bars"];
+  const line = value["line"];
+  return isLabelList(labels, limits.minLabels, limits.maxLabels) &&
+    isChartSeries(bars, labels.length) && isChartSeries(line, labels.length) && bars.name !== line.name;
+}
+
+const chart = <T>(check: (v: unknown) => v is T) => ({
+  props: { data: p.json(check, { required: true }), theme: p.enum(CHART_THEMES), interactive: p.boolean() },
+  events: { onClick: ev<ChartClickEvent>("click") },
+  children: [] as const,
+});
+
 // ---------------------------------------------------------------------------------------------
 // Catalog
 
 export const COMPONENTS = {
-  // View roots. An app's view component must render exactly one of these at its top level.
+  // View roots. An app's view component must render exactly one of these at its top level:
+  // ContextView on a surface, SettingsView on the settings page, PageView on an app page.
   ContextView: spec("ui-context-view", {
     root: true,
     props: { title: p.string({ required: true, maxLength: 100 }), description: p.string({ maxLength: 300 }), externalLink: p.json(isExternalLink) },
@@ -190,6 +355,13 @@ export const COMPONENTS = {
     // `values` maps every form field's `name` to its current value.
     events: { onSave: ev<Record<string, string>>("save") },
   }),
+  // An app page (`ui_extensions.routes`), rendered full width inside the portal's own chrome. The
+  // title is the page header; `actions` join the portal header's actions, `banner` sits above the body.
+  PageView: spec("ui-page-view", {
+    root: true,
+    props: { title: p.string({ required: true, maxLength: 100 }), description: p.string({ maxLength: 300 }) },
+    slots: ["actions", "banner"] as const,
+  }),
 
   // Layout
   Box: spec("ui-box", { props: { ...layout, ...typography }, text: true }),
@@ -368,6 +540,16 @@ export const COMPONENTS = {
   FormFieldGroup: spec("ui-form-field-group", {
     props: { legend: p.string({ maxLength: 200 }), description: p.string({ maxLength: 500 }), layout: p.enum(["row", "column"] as const) },
   }),
+
+  // Charts. Data only: `theme` picks the palette, `interactive` turns on press feedback and
+  // tooltips, and `onClick` receives a `ChartClickEvent`. Bounds are in `CHART_DATA_LIMITS`.
+  BarChart: spec("ui-bar-chart", chart((v): v is ChartDatum[] => isChartData(v, CHART_DATA_LIMITS.BarChart))),
+  HorizontalBarChart: spec("ui-horizontal-bar-chart", chart((v): v is ChartDatum[] => isChartData(v, CHART_DATA_LIMITS.HorizontalBarChart))),
+  StackedBarChart: spec("ui-stacked-bar-chart", chart((v): v is SeriesChartData => isSeriesChartData(v, CHART_DATA_LIMITS.StackedBarChart))),
+  LineChart: spec("ui-line-chart", chart((v): v is SeriesChartData => isSeriesChartData(v, CHART_DATA_LIMITS.LineChart))),
+  AreaChart: spec("ui-area-chart", chart((v): v is SeriesChartData => isSeriesChartData(v, CHART_DATA_LIMITS.AreaChart))),
+  ComboChart: spec("ui-combo-chart", chart((v): v is ComboChartData => isComboChartData(v, CHART_DATA_LIMITS.ComboChart))),
+  PieChart: spec("ui-pie-chart", chart(isPieChartData)),
 } as const;
 
 // Checked by assignment rather than `satisfies`: `satisfies` would hand `ComponentSpec` to every