@tuongaz/seeflow 0.1.116 → 0.2.2

package/src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { closeSync, cpSync, existsSync, mkdirSync, openSync, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { runLogin, runLogout, runWhoami } from './cli-auth.ts';
 import {
   drainStdin,
   loadBody,
@@ -11,7 +12,9 @@ import {
 } from './cli-helpers.ts';
 import { COMMAND_MANIFEST, renderCommandHelp, renderCommandList } from './cli-manifest.ts';
 import { createCliOperations, registerProject } from './cli-ops.ts';
+import { DEFAULT_CLOUD_ENDPOINT } from './credentials.ts';
 import { createEventBus } from './events.ts';
+import { bundleProject } from './export-bundle.ts';
 import { JqError, applyJq } from './jq-filter.ts';
 import type { LayoutOptions } from './layout.ts';
 import {
@@ -22,6 +25,7 @@ import {
 } from './operations.ts';
 import { PROJECT_FLOW_FILENAME, seeflowHome } from './paths.ts';
 import { defaultProcessSpawner } from './process-spawner.ts';
+import { publishProject } from './publish.ts';
 import { type Registry, createRegistry, manifestOnlyEntryFilter } from './registry.ts';
 import {
   DEFAULT_CONFIG,
@@ -230,6 +234,14 @@ if (argv.includes('--version') || argv.includes('-v')) {
   await runE2e();
 } else if (sub === 'emit') {
   await runEmit();
+} else if (sub === 'login') {
+  await runLoginCmd();
+} else if (sub === 'logout') {
+  runLogoutCmd();
+} else if (sub === 'whoami') {
+  runWhoamiCmd();
+} else if (sub === 'export') {
+  await runExportCmd();
 } else {
   console.error(`Unknown subcommand: ${sub}`);
   printHelp();
@@ -300,6 +312,14 @@ Commands (require a running studio):
                        [--run-id <id>] [--payload <json>] [--studio-url <url>]
   e2e                  End-to-end validate a registered flow (--project <p> --flow <f> [--skip-nodes a,b])
 
+Cloud account:
+  login                Sign in to the cloud (opens a browser) [--endpoint <url>]
+  logout               Clear the stored cloud credential [--endpoint <url>]
+  whoami               Show the stored cloud identity [--endpoint <url>]
+  export [path]        Bundle a project (default: cwd) and export it to the cloud,
+                       creating it on first run and updating in place after
+                       [--endpoint <url>] [--dry-run]
+
 Meta:
   version              Print the CLI version
   help                 Show this help message
@@ -1331,3 +1351,55 @@ async function runIconsRemove() {
   removeIconPack(vendor, { cacheRoot: iconCacheRoot() });
   printOk({ removed: vendor });
 }
+
+// --- Cloud account verbs (generic, provider-agnostic) -----------------------
+// Declared as a hoisted function (not a const arrow) so the cloud command
+// handlers, which are invoked from the top-level dispatch above, can reach it
+// without tripping the temporal-dead-zone on the const binding.
+function cloudEndpoint(): string {
+  return flagValue('endpoint') ?? process.env.SEEFLOW_CLOUD_URL ?? DEFAULT_CLOUD_ENDPOINT;
+}
+
+async function runLoginCmd() {
+  const endpoint = cloudEndpoint();
+  console.error(`Opening ${endpoint} to sign in… (a browser window should open)`);
+  try {
+    const outcome = await runLogin({ endpoint });
+    printOk({
+      loggedIn: true,
+      endpoint: outcome.endpoint,
+      userId: outcome.userId,
+      email: outcome.email,
+    });
+  } catch (err) {
+    printError(`Login failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function runLogoutCmd() {
+  const endpoint = cloudEndpoint();
+  runLogout(endpoint);
+  printOk({ loggedOut: true, endpoint });
+}
+
+function runWhoamiCmd() {
+  printOk(runWhoami(cloudEndpoint()));
+}
+
+async function runExportCmd() {
+  const root = resolve(positionalArgs()[0] ?? '.');
+  const endpoint = cloudEndpoint();
+  // --dry-run bundles the project without any network call (no credential
+  // needed) — useful for inspecting what would be shipped.
+  if (hasFlag('dry-run')) {
+    const bundle = bundleProject(root);
+    printOk({ dryRun: true, endpoint, name: bundle.name, files: bundle.files.map((f) => f.path) });
+    return;
+  }
+  try {
+    const { projectId } = await publishProject({ root, baseUrl: endpoint });
+    printOk({ exported: true, endpoint, projectId });
+  } catch (err) {
+    printError(`Export failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}

package/src/cloud-login.ts

@@ -0,0 +1,82 @@
+import { DEFAULT_CLOUD_ENDPOINT } from './credentials.ts';
+
+export interface LoopbackLoginOptions {
+  /** Cloud base URL. Defaults to https://cloud.seeflow.dev. */
+  endpoint?: string;
+  /** Fixed loopback port. Defaults to 0 (ephemeral). */
+  port?: number;
+}
+
+export interface LoginResult {
+  token: string;
+  userId?: string;
+  email?: string;
+}
+
+export interface LoopbackLoginSession {
+  /** The URL to open in a browser to complete sign-in. */
+  loginUrl: string;
+  /** The bound loopback port. */
+  port: number;
+  /** The CSRF state echoed back by the callback. */
+  state: string;
+  /** Resolves once a valid callback delivers a token. */
+  result: Promise<LoginResult>;
+  /** Stop the loopback server (idempotent). */
+  close(): void;
+}
+
+const DONE_PAGE =
+  '<!doctype html><meta charset=utf-8><title>SeeFlow</title>' +
+  '<body style="font-family:system-ui;padding:3rem;text-align:center">' +
+  '<h1>You are logged in.</h1><p>You can close this window and return to the terminal.</p></body>';
+
+/**
+ * Start the local-loopback login flow (provider-agnostic). Spins a tiny HTTP
+ * server on 127.0.0.1, returns the cloud /cli/login URL to open, and resolves
+ * `result` when the cloud SPA redirects/POSTs the minted token back to
+ * /callback with a matching state. Does NOT open a browser or persist — the
+ * caller (CLI / studio) does that.
+ */
+export function startLoopbackLogin(
+  options: LoopbackLoginOptions = {},
+): Promise<LoopbackLoginSession> {
+  const endpoint = (options.endpoint ?? DEFAULT_CLOUD_ENDPOINT).replace(/\/+$/, '');
+  const state = crypto.randomUUID();
+
+  let resolveResult!: (r: LoginResult) => void;
+  const result = new Promise<LoginResult>((r) => {
+    resolveResult = r;
+  });
+
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname !== '/callback') return new Response('not found', { status: 404 });
+      if (url.searchParams.get('state') !== state) {
+        return new Response('state mismatch', { status: 400 });
+      }
+      const token = url.searchParams.get('token');
+      if (!token) return new Response('missing token', { status: 400 });
+      resolveResult({
+        token,
+        userId: url.searchParams.get('userId') ?? undefined,
+        email: url.searchParams.get('email') ?? undefined,
+      });
+      return new Response(DONE_PAGE, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+    },
+  });
+
+  const port = server.port ?? options.port ?? 0;
+  const loginUrl = `${endpoint}/cli/login?port=${port}&state=${state}`;
+
+  return Promise.resolve({
+    loginUrl,
+    port,
+    state,
+    result,
+    close: () => server.stop(true),
+  });
+}

package/src/cloud-meta.ts

@@ -0,0 +1,42 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeFileAtomic } from './atomic-write.ts';
+
+/**
+ * Local cloud-export metadata, stored at `<root>/.seeflow/cloud.json` (the
+ * project root's own `.seeflow`, distinct from the global seeflowHome()). Keyed
+ * by the cloud base URL so a single project can be exported to more than one
+ * cloud without the ids colliding. The stamped `projectId` is what makes
+ * re-export update the same cloud project in place.
+ */
+interface CloudMetaEntry {
+  projectId: string;
+  lastExportedAt: string;
+}
+type CloudMetaFile = Record<string, CloudMetaEntry>;
+
+function metaPath(root: string): string {
+  return join(root, '.seeflow', 'cloud.json');
+}
+
+function readFile(root: string): CloudMetaFile {
+  const path = metaPath(root);
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' ? (parsed as CloudMetaFile) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function readCloudProjectId(root: string, baseUrl: string): string | null {
+  return readFile(root)[baseUrl]?.projectId ?? null;
+}
+
+export function writeCloudProjectId(root: string, baseUrl: string, projectId: string): void {
+  const file = readFile(root);
+  file[baseUrl] = { projectId, lastExportedAt: new Date().toISOString() };
+  mkdirSync(join(root, '.seeflow'), { recursive: true });
+  writeFileAtomic(metaPath(root), JSON.stringify(file, null, 2));
+}

package/src/credentials.ts

@@ -0,0 +1,84 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/** Default hosted cloud endpoint. Overridable per call / via SEEFLOW_CLOUD_URL. */
+export const DEFAULT_CLOUD_ENDPOINT = 'https://cloud.seeflow.dev';
+
+export interface StoredCredential {
+  token: string;
+  userId?: string;
+  email?: string;
+  /** ISO-8601 timestamp set on save. */
+  savedAt: string;
+}
+
+/** endpoint host -> credential. */
+export type CredentialsFile = Record<string, StoredCredential>;
+
+/**
+ * Location of the shared credential file. Honors $XDG_CONFIG_HOME (Linux/XDG
+ * convention) and falls back to ~/.seeflow. Both the CLI and the local studio
+ * read/write this single file.
+ */
+export function credentialsPath(): string {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  if (xdg && xdg.length > 0) return join(xdg, 'seeflow', 'credentials.json');
+  return join(homedir(), '.seeflow', 'credentials.json');
+}
+
+/** Normalize an endpoint URL to its host key (so trailing slashes/paths don't fork keys). */
+export function endpointKey(endpoint: string): string {
+  try {
+    return new URL(endpoint).host;
+  } catch {
+    return endpoint;
+  }
+}
+
+export function readCredentials(): CredentialsFile {
+  const path = credentialsPath();
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' ? (parsed as CredentialsFile) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeCredentials(file: CredentialsFile): void {
+  const path = credentialsPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(file, null, 2));
+  // Tokens are secrets — owner-only.
+  chmodSync(path, 0o600);
+}
+
+export interface SaveCredentialInput {
+  endpoint: string;
+  token: string;
+  userId?: string;
+  email?: string;
+}
+
+export function saveCredential(input: SaveCredentialInput): void {
+  const file = readCredentials();
+  file[endpointKey(input.endpoint)] = {
+    token: input.token,
+    userId: input.userId,
+    email: input.email,
+    savedAt: new Date().toISOString(),
+  };
+  writeCredentials(file);
+}
+
+export function loadCredential(endpoint: string): StoredCredential | undefined {
+  return readCredentials()[endpointKey(endpoint)];
+}
+
+export function clearCredential(endpoint: string): void {
+  const file = readCredentials();
+  delete file[endpointKey(endpoint)];
+  writeCredentials(file);
+}

package/src/events.ts

@@ -1,7 +1,8 @@
 /**
- * In-memory pub/sub keyed by flowId. Subscribers receive every event published
- * for that demo until they unsubscribe; subscribers for other demos are not
- * notified.
+ * In-memory pub/sub keyed by (tenantId, flowId). Subscribers receive every
+ * event published for that (tenant, demo) until they unsubscribe; other
+ * tenants and other demos are not notified. `tenantId` is optional — omitting
+ * it uses a single shared partition (the single-tenant local studio).
  */
 
 export type StudioEventType =
@@ -16,6 +17,8 @@ export type StudioEventType =
 export interface StudioEvent {
   type: StudioEventType;
   flowId: string;
+  /** Optional tenant partition. Undefined = the single shared partition. */
+  tenantId?: string;
   /** Arbitrary JSON-serializable payload. Shape depends on event type. */
   payload: unknown;
   /** Server-side timestamp (ms since epoch). */
@@ -25,34 +28,40 @@ export interface StudioEvent {
 export type Subscriber = (event: StudioEvent) => void;
 
 export interface EventBus {
-  /** Subscribe to events for a specific demo. Returns an unsubscribe fn. */
-  subscribe(flowId: string, fn: Subscriber): () => void;
-  /** Broadcast an event to all subscribers of `flowId`. */
+  /** Subscribe to events for a (tenant, demo). Returns an unsubscribe fn. */
+  subscribe(flowId: string, fn: Subscriber, tenantId?: string): () => void;
+  /** Broadcast an event to all subscribers of (tenantId, flowId). */
   broadcast(event: Omit<StudioEvent, 'ts'> & { ts?: number }): void;
-  /** Number of active subscribers for a given demo (used in tests). */
-  subscriberCount(flowId: string): number;
+  /** Number of active subscribers for a (tenant, demo) (used in tests). */
+  subscriberCount(flowId: string, tenantId?: string): number;
 }
 
+/** Partition key: tenant-scoped when a tenant id is present, else shared. */
+const partitionKey = (flowId: string, tenantId?: string): string =>
+  tenantId && tenantId.length > 0 ? `${tenantId} ${flowId}` : flowId;
+
 export function createEventBus(): EventBus {
   const subs = new Map<string, Set<Subscriber>>();
 
   return {
-    subscribe(flowId, fn) {
-      let set = subs.get(flowId);
+    subscribe(flowId, fn, tenantId) {
+      const key = partitionKey(flowId, tenantId);
+      let set = subs.get(key);
       if (!set) {
         set = new Set();
-        subs.set(flowId, set);
+        subs.set(key, set);
       }
       set.add(fn);
       return () => {
-        const current = subs.get(flowId);
+        const current = subs.get(key);
         if (!current) return;
         current.delete(fn);
-        if (current.size === 0) subs.delete(flowId);
+        if (current.size === 0) subs.delete(key);
       };
     },
     broadcast(event) {
-      const set = subs.get(event.flowId);
+      const key = partitionKey(event.flowId, event.tenantId);
+      const set = subs.get(key);
       if (!set) return;
       const full: StudioEvent = { ...event, ts: event.ts ?? Date.now() };
       for (const fn of set) {
@@ -63,8 +72,8 @@ export function createEventBus(): EventBus {
         }
       }
     },
-    subscriberCount(flowId) {
-      return subs.get(flowId)?.size ?? 0;
+    subscriberCount(flowId, tenantId) {
+      return subs.get(partitionKey(flowId, tenantId))?.size ?? 0;
     },
   };
 }

package/src/export-bundle.ts

@@ -0,0 +1,78 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { PROJECT_FLOW_FILENAME } from './paths.ts';
+
+/**
+ * Transport-neutral snapshot of a project: a name plus the project files keyed
+ * by their forward-slash, project-root-relative path. Pure — no network. The
+ * cloud export endpoint receives exactly this shape; the local studio is the
+ * only thing that knows how to read a project off disk.
+ */
+export interface BundleFile {
+  /** Forward-slash, project-root-relative path (e.g. `nodes/n1/detail.md`). */
+  path: string;
+  content: string;
+}
+
+export interface ProjectBundle {
+  name: string;
+  files: BundleFile[];
+}
+
+/** Top-level files we include verbatim when present. */
+const TOP_LEVEL_FILES = ['flow.json', 'style.json', 'seeflow.json'] as const;
+/** Subtrees we recurse into when present. */
+const SUBTREES = ['nodes', 'flows'] as const;
+
+function relPath(root: string, abs: string): string {
+  // Normalize to forward slashes so the wire format is platform-stable.
+  return relative(root, abs).split(sep).join('/');
+}
+
+function collectTree(root: string, dir: string, out: BundleFile[]): void {
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry);
+    const st = statSync(abs);
+    if (st.isDirectory()) {
+      collectTree(root, abs, out);
+    } else if (st.isFile()) {
+      out.push({ path: relPath(root, abs), content: readFileSync(abs, 'utf8') });
+    }
+  }
+}
+
+export function bundleProject(root: string): ProjectBundle {
+  const flowPath = join(root, PROJECT_FLOW_FILENAME);
+  if (!existsSync(flowPath)) {
+    throw new Error(`no ${PROJECT_FLOW_FILENAME} found at ${root}`);
+  }
+
+  const files: BundleFile[] = [];
+  for (const name of TOP_LEVEL_FILES) {
+    const abs = join(root, name);
+    if (existsSync(abs) && statSync(abs).isFile()) {
+      files.push({ path: name, content: readFileSync(abs, 'utf8') });
+    }
+  }
+  for (const sub of SUBTREES) {
+    const abs = join(root, sub);
+    if (existsSync(abs) && statSync(abs).isDirectory()) {
+      collectTree(root, abs, files);
+    }
+  }
+
+  return { name: deriveName(root, files), files };
+}
+
+function deriveName(root: string, files: BundleFile[]): string {
+  const flow = files.find((f) => f.path === PROJECT_FLOW_FILENAME);
+  if (flow) {
+    try {
+      const parsed = JSON.parse(flow.content) as { name?: unknown };
+      if (typeof parsed.name === 'string' && parsed.name.length > 0) return parsed.name;
+    } catch {
+      // fall through to the directory name
+    }
+  }
+  return root.split(sep).filter(Boolean).pop() ?? 'project';
+}

package/src/paths.ts

@@ -6,10 +6,19 @@ import { join } from 'node:path';
 // inside the Docker image, where it defaults to /workspace — state lands in
 // the bind-mounted workspace so it survives `docker run --rm`. Otherwise it
 // falls back to ~/.seeflow for local installs.
-export function seeflowHome(): string {
+export function seeflowHome(tenantId?: string): string {
   const workspace = process.env.SEEFLOW_WORKSPACE;
-  if (workspace && workspace.length > 0) return join(workspace, '.seeflow');
-  return join(homedir(), '.seeflow');
+  const base =
+    workspace && workspace.length > 0 ? join(workspace, '.seeflow') : join(homedir(), '.seeflow');
+  if (tenantId && tenantId.length > 0) {
+    // Per-tenant nesting per the cloud tenancy design (§6.1):
+    //   workspace set -> <workspace>/users/<tenantId>/.seeflow
+    //   home fallback -> ~/.seeflow/users/<tenantId>/.seeflow
+    // The root differs so single- and multi-tenant layouts share one tree.
+    const root = workspace && workspace.length > 0 ? workspace : join(homedir(), '.seeflow');
+    return join(root, 'users', tenantId, '.seeflow');
+  }
+  return base;
 }
 
 // Per-project layout: everything lives at the project root. The studio never

package/src/publish.ts

@@ -0,0 +1,55 @@
+import { readCloudProjectId, writeCloudProjectId } from './cloud-meta.ts';
+import { DEFAULT_CLOUD_ENDPOINT, loadCredential } from './credentials.ts';
+import { bundleProject } from './export-bundle.ts';
+
+/**
+ * Generic, provider-agnostic publish/export provider. Bundles a project, POSTs
+ * it to a configurable cloud endpoint with a bearer token from the shared
+ * credential store, and stamps the returned project_id back into the project's
+ * local cloud-meta so a re-export updates the same cloud project in place.
+ *
+ * No cloud/Clerk/AWS specifics live here — the only knob is `baseUrl`. The
+ * `fetch` implementation is injected so tests never touch the network.
+ */
+export interface PublishOptions {
+  root: string;
+  baseUrl?: string;
+  /** Explicit token. `undefined` → read from the shared credential store; an
+   *  explicit `null` means "no credential" and is rejected. */
+  token?: string | null;
+  fetchImpl?: typeof fetch;
+}
+
+export interface PublishResult {
+  projectId: string;
+}
+
+export async function publishProject(opts: PublishOptions): Promise<PublishResult> {
+  const baseUrl = opts.baseUrl ?? DEFAULT_CLOUD_ENDPOINT;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const token = opts.token === undefined ? (loadCredential(baseUrl)?.token ?? null) : opts.token;
+  if (!token) {
+    throw new Error('not logged in — run `seeflow login` first');
+  }
+
+  const bundle = bundleProject(opts.root);
+  const existingId = readCloudProjectId(opts.root, baseUrl);
+
+  const res = await fetchImpl(`${baseUrl}/api/export`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify({ ...(existingId ? { projectId: existingId } : {}), bundle }),
+  });
+
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '');
+    throw new Error(`export failed (${res.status})${detail ? `: ${detail}` : ''}`);
+  }
+
+  const { projectId } = (await res.json()) as { projectId: string };
+  writeCloudProjectId(opts.root, baseUrl, projectId);
+  return { projectId };
+}

package/src/server.ts

@@ -16,6 +16,7 @@ import { type RegistryWatcher, createRegistryWatcher } from './registry-watcher.
 import { type Registry, createRegistry, manifestOnlyEntryFilter } from './registry.ts';
 import type { Spawner } from './shellout.ts';
 import { type StatusRunner, createStatusRunner } from './status-runner.ts';
+import { createTenantResolver } from './tenancy.ts';
 import { type FlowWatcher, createWatcher } from './watcher.ts';
 
 /** Absolute path to the vendored runtime asset directory. Resolved relative
@@ -79,6 +80,11 @@ export interface CreateAppOptions {
   /** Override the icon installer's fetcher. Production uses fetchWithProgress
    *  (real network); integration tests inject a fixture-returning closure. */
   iconFetcher?: IconFetcher;
+  /** Host-injected per-request tenant resolver. Returns a tenant id (e.g. the
+   *  authenticated user's id) from the request context, or undefined for the
+   *  single-tenant local studio. Provider-agnostic — the studio never learns
+   *  HOW the id is produced. See src/tenancy.ts. */
+  getTenantId?: (ctx: import('hono').Context) => string | undefined;
 }
 
 const DEFAULT_VITE_DEV_URL = 'http://localhost:5173';
@@ -108,6 +114,8 @@ export function createApp(options: CreateAppOptions = {}): Hono {
     options.statusRunner ??
     createStatusRunner({ registry, events, spawner: defaultProcessSpawner });
   const iconJobs = options.iconJobs ?? createJobRegistry();
+  const tenantResolver = createTenantResolver({ defaultRegistry: registry, defaultEvents: events });
+  const getTenantId = options.getTenantId;
 
   if (watcher && (options.watchAllOnBoot ?? true)) {
     watcher.watchAll();
@@ -118,6 +126,17 @@ export function createApp(options: CreateAppOptions = {}): Hono {
 
   const app = new Hono();
 
+  // Per-request tenant context. With no getTenantId hook this resolves the
+  // default singletons (local studio). The cloud injects a hook returning
+  // user.sub so each request reads/writes its own tenant tree.
+  // Route-by-route adoption of c.get('tenant') is deferred to Phase 2.
+  app.use('*', async (c, next) => {
+    const tenantId = getTenantId ? getTenantId(c) : undefined;
+    if (tenantId) c.set('tenantId', tenantId);
+    c.set('tenant', tenantResolver.resolve(tenantId));
+    return next();
+  });
+
   // CORS + token gate runs first so every downstream route inherits the
   // null-origin rule. No-ops on requests without an Origin header (CLI
   // calls, integration tests, top-level navigation).