docs: measure the runtime and the generated client modules

Adds a per-subsystem measurement of reactive.js, made by minifying it
repeatedly with one subsystem removed rather than counting source bytes.

This corrects the earlier audit on both figures and on the conclusion drawn
from them. Component controllers are 23,722 bytes minified / 6,660 gzipped --
30.6% of transfer, not the "about 18%" previously claimed -- and splitting them
out saves 6.6 kB gzipped on a typical page, not "3-4 kB". Measured against the
example app, / and /login use none of the ten controllers and /layout uses one,
so most pages download and parse the lot for nothing.

The larger finding is that the runtime is not where the weight is. One page
parses 490,212 decoded bytes across 11 generated client modules while
transferring 21,026, and the largest module is 89.8% duplicated lines: the
state-restore prologue appears 162 times because client-codegen.ts inlines the
sync into every peer alias of every client function. Gzip hides it on the wire,
but parse cost follows decoded bytes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

examples/inter-app-api-showcase/README.md

@@ -0,0 +1,19 @@
+# Inter-app + external API showcase
+
+`GET /api/product-summary?sku=starter` demonstrates one request handler making:
+
+1. an RPC request to the `catalog` app (`getProduct`);
+2. an external HTTPS request to GitHub's public REST API; and
+3. an RPC request to the `audit` app (`recordLookup`).
+
+The handler deliberately forwards `as: ctx` only to WRNexus peer apps. The RPC package turns that into a short-lived subject/tenant token; it is never forwarded to GitHub. Each peer app must implement the same contract from `app/lib/contracts.ts` (normally a shared workspace package) under `app/services/`, and must authorize its own procedures.
+
+Before running this app, configure all three apps with the same private internal-origin map and a distinct, 32+ character RPC secret:
+
+```sh
+WRNEXUS_RPC_SECRET=replace-with-a-private-32-character-minimum-secret
+WRNEXUS_APP_NAME=product-summary
+WRNEXUS_INTERNAL_ORIGINS={"catalog":"http://127.0.0.1:4101","audit":"http://127.0.0.1:4102"}
+```
+
+The peer app processes must remain private; the public gateway blocks the RPC route by design. Run with `bun run --cwd examples/inter-app-api-showcase dev`.

examples/inter-app-api-showcase/app/api/product-summary.ts

@@ -0,0 +1,60 @@
+import type { Context } from "@wrnexus/core";
+import { httpTransport, serviceClient } from "@wrnexus/rpc";
+import { auditService, catalogService } from "../lib/contracts.ts";
+
+interface GitHubRepository {
+  full_name?: unknown;
+  stargazers_count?: unknown;
+}
+
+function requestedSku(ctx: Context): string {
+  return new URL(ctx.req.url).searchParams.get("sku")?.trim() || "starter";
+}
+
+/** GET /api/product-summary?sku=starter */
+export async function GET(ctx: Context): Promise<Response> {
+  const sku = requestedSku(ctx);
+  const transport = httpTransport();
+
+  // Inter-app call #1: query the catalog app. `{ as: ctx }` forwards the
+  // signed subject/tenant context; catalog still authorizes independently.
+  const catalog = serviceClient(catalogService, { app: "catalog", as: ctx, transport });
+  const product = await catalog.getProduct({ sku });
+
+  // External API call: GitHub's public repository endpoint. Do not send the
+  // user's RPC identity token or internal headers to external services.
+  let githubResponse: Response;
+  try {
+    githubResponse = await fetch("https://api.github.com/repos/octocat/Hello-World", {
+      headers: { accept: "application/vnd.github+json", "user-agent": "wrnexus-example" },
+      signal: ctx.req.signal,
+    });
+  } catch {
+    return Response.json({ error: "External repository lookup failed." }, { status: 502 });
+  }
+  if (!githubResponse.ok) {
+    return Response.json({ error: "External repository lookup failed." }, { status: 502 });
+  }
+  const github = (await githubResponse.json()) as GitHubRepository;
+  if (typeof github.full_name !== "string" || typeof github.stargazers_count !== "number") {
+    return Response.json(
+      { error: "External repository returned an unexpected response." },
+      { status: 502 },
+    );
+  }
+
+  // Inter-app call #2: record the completed lookup in the audit app. This is
+  // intentionally awaited: callers learn whether the audit record was saved.
+  const audit = serviceClient(auditService, { app: "audit", as: ctx, transport });
+  const receipt = await audit.recordLookup({
+    sku: product.sku,
+    repository: github.full_name,
+    stars: github.stargazers_count,
+  });
+
+  return Response.json({
+    product,
+    external: { repository: github.full_name, stars: github.stargazers_count },
+    audit: receipt,
+  });
+}

examples/inter-app-api-showcase/app/example.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+test("product summary composes one external request with two peer-app calls", () => {
+  const source = readFileSync(join(import.meta.dir, "api", "product-summary.ts"), "utf8");
+  expect(source).toContain('serviceClient(catalogService, { app: "catalog", as: ctx, transport })');
+  expect(source).toContain('serviceClient(auditService, { app: "audit", as: ctx, transport })');
+  expect(source).toContain('fetch("https://api.github.com/repos/octocat/Hello-World"');
+  expect(source).toContain("ctx.req.signal");
+});

examples/inter-app-api-showcase/app/lib/contracts.ts

@@ -0,0 +1,34 @@
+import { defineService, procedure } from "@wrnexus/rpc";
+import { v } from "@wrnexus/validation";
+
+/**
+ * In a real multi-app workspace, put these contracts in a shared package and
+ * import that package from this app and each peer. They live together here so
+ * the example is self-contained.
+ */
+export const catalogService = defineService({
+  name: "catalog",
+  procedures: {
+    getProduct: procedure
+      .input(v.object({ sku: v.string() }))
+      .output<{ sku: string; displayName: string; enabled: boolean }>()
+      .idempotent()
+      .build(),
+  },
+});
+
+export const auditService = defineService({
+  name: "audit",
+  procedures: {
+    recordLookup: procedure
+      .input(
+        v.object({
+          sku: v.string(),
+          repository: v.string(),
+          stars: v.number(),
+        }),
+      )
+      .output<{ eventId: string }>()
+      .build(),
+  },
+});

examples/inter-app-api-showcase/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "inter-app-api-showcase",
+  "version": "0.8.6",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun run ../../packages/cli/src/index.ts dev .",
+    "build": "bun run ../../packages/cli/src/index.ts build .",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "check": "bun run typecheck && bun run test && bun run build"
+  },
+  "dependencies": {
+    "@wrnexus/core": "workspace:*",
+    "@wrnexus/rpc": "workspace:*",
+    "@wrnexus/validation": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^5.9.2"
+  }
+}

examples/inter-app-api-showcase/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": { "lib": ["ESNext", "DOM", "DOM.Iterable"] },
+  "include": ["app"]
+}