tapimo 0.0.2 → 0.2.0

package/src/apps/{webhooks.ts → data/routes/webhooks.ts}

@@ -2,19 +2,20 @@ import { type Context, Hono } from 'hono'
 import { type AbiEvent, parseAbiItem } from 'viem'
 import * as z from 'zod/mini'
 
-import type * as App from '../App.js'
-import * as Auth from '../internal/Auth.js'
-import * as Cache from '../internal/Cache.js'
-import * as Cursor from '../internal/Cursor.js'
-import * as OpenApi from '../internal/OpenApi.js'
-import * as Response from '../internal/Response.js'
-import * as Schema from '../internal/Schema.js'
-import * as Store from '../internal/Store.js'
-import type * as Tidx from '../internal/Tidx.js'
-import * as Ttl from '../internal/Ttl.js'
-import * as Value from '../internal/Value.js'
-import type * as Viem from '../internal/Viem.js'
-import * as Webhooks from '../internal/Webhooks.js'
+import type * as App from '../../../App.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as Cursor from '../../../internal/Cursor.js'
+import * as Db from '../../../db/Db.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as Store from '../../../internal/Store.js'
+import type * as Tidx from '../../../internal/Tidx.js'
+import * as Ttl from '../../../internal/Ttl.js'
+import * as Value from '../../../internal/Value.js'
+import type * as Viem from '../../../internal/Viem.js'
+import * as Webhooks from '../../../internal/Webhooks.js'
 import * as Receipts from './receipts.js'
 import * as Transactions from './transactions.js'
 import * as Transfers from './transfers.js'
@@ -377,7 +378,7 @@ export namespace schema {
           .record(z.string(), z.unknown())
           .check(
             z.describe(
-              'Match decoded event arguments by name (indexed or non-indexed). Requires `signature`. Each value is an exact value or an operator object.',
+              'Match decoded event arguments by name (indexed or non-indexed). Requires `signature`. Each value is an exact value or a super admin object.',
             ),
             z.meta({ examples: [{ to: '0x9e39034aae71fb89f66061a2602eb6efec271754' }] }),
           ),
@@ -1224,21 +1225,25 @@ export namespace schema {
  */
 export function webhooks(options: webhooks.Options = {}) {
   const hidden = !options.enabled
-  return (
-    new Hono<App.Environment>()
-      .use('*', async (c, next) => {
-        // Gate the whole resource on a configured state store. Without it the
-        // outbound-HTTP surface is disabled (read-only deployment).
-        if (!c.get('webhook')) return notEnabled(c) as never
+  // Gate the whole resource on a configured state store. Without it the
+  // outbound-HTTP surface is disabled (read-only deployment).
+  const gate = async (c: Context<App.Environment>, next: () => Promise<void>) => {
+    if (!c.get('webhook')) return notEnabled(c) as never
 
-        await next()
+    await next()
 
-        // Subscriptions are principal-scoped, mutating, and stateful: never cache.
-        if (!c.res.headers.has('Cache-Control')) c.res.headers.set('Cache-Control', 'no-store')
-        return
-      })
+    // Subscriptions are principal-scoped, mutating, and stateful: never cache.
+    if (!c.res.headers.has('Cache-Control')) c.res.headers.set('Cache-Control', 'no-store')
+    return
+  }
+  return (
+    new Hono<App.Environment>()
+      // `/v1/webhooks/*` does not match the collection root, so it gets its
+      // own registration.
+      .use('/v1/webhooks', gate)
+      .use('/v1/webhooks/*', gate)
       .get(
-        '/event-types',
+        '/v1/webhooks/event-types',
         Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
         OpenApi.describeRoute({
           description: 'See which onchain event types Tempo can POST to your webhook URL.',
@@ -1274,7 +1279,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .post(
-        '/',
+        '/v1/webhooks',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('json', schema.createWebhook.Body, {
           code: 'body_invalid',
@@ -1306,7 +1311,7 @@ export function webhooks(options: webhooks.Options = {}) {
             })
 
           const webhook = c.get('webhook')!
-          const store = webhook.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
@@ -1315,7 +1320,7 @@ export function webhooks(options: webhooks.Options = {}) {
 
           try {
             const subscription = await Webhooks.createSubscription(
-              store,
+              db,
               {
                 chainId,
                 ...(body.context === undefined ? {} : { context: body.context }),
@@ -1337,7 +1342,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .get(
-        '/',
+        '/v1/webhooks',
         Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }),
         OpenApi.validate('query', schema.listWebhooks.Query, {
           code: 'query_invalid',
@@ -1365,7 +1370,7 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the query parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
@@ -1375,12 +1380,12 @@ export function webhooks(options: webhooks.Options = {}) {
             // run it concurrently with the page list. Best-effort: a failure
             // omits `meta` rather than failing the page.
             const countPromise = include.includes('totalCount')
-              ? Webhooks.countSubscriptions(store, owner).catch(() => undefined)
+              ? Webhooks.countSubscriptions(db, owner).catch(() => undefined)
               : undefined
 
             // Fetch one extra to detect a further page without a second round-trip.
             // `page` translates to a positional slice of `(page - 1) * limit` rows.
-            const rows = await Webhooks.listSubscriptions(store, owner, {
+            const rows = await Webhooks.listSubscriptions(db, owner, {
               cursor,
               limit: limit + 1,
               offset: page !== undefined && page > 1 ? (page - 1) * limit : undefined,
@@ -1411,7 +1416,7 @@ export function webhooks(options: webhooks.Options = {}) {
       // constraint, this API-key-only route's policy would be collected for the
       // event-types request and override its (intentionally public) access.
       .get(
-        '/:id{wh_[A-Za-z0-9_-]+}',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}',
         Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }),
         OpenApi.validate('param', schema.getWebhook.Params, {
           code: 'param_invalid',
@@ -1445,13 +1450,13 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the path parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
           const { id } = c.req.valid('param')
           try {
-            const subscription = await Webhooks.getSubscription(store, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id)
             if (!subscription) return notFound(c)
             return c.json(
               Response.validated(schema.getWebhook.Response, toPublic(subscription)),
@@ -1463,7 +1468,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .get(
-        '/:id{wh_[A-Za-z0-9_-]+}/deliveries',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}/deliveries',
         Auth.policy({ apiKey: { scopes: ['webhooks:read'] } }),
         OpenApi.validate('param', schema.listWebhookDeliveries.Params, {
           code: 'param_invalid',
@@ -1506,7 +1511,7 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the query parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
@@ -1515,19 +1520,19 @@ export function webhooks(options: webhooks.Options = {}) {
           try {
             // Owner-scope first: resolving the subscription under the caller's owner
             // key 404s ids they don't own (indistinguishable from "doesn't exist").
-            const subscription = await Webhooks.getSubscription(store, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id)
             if (!subscription) return notFound(c)
 
             // `totalCount` is opt-in and exact (the delivery log is TTL-bounded);
             // run it concurrently with the page list. Best-effort: a failure
             // omits `meta` rather than failing the page.
             const countPromise = include.includes('totalCount')
-              ? Webhooks.countDeliveries(store, id).catch(() => undefined)
+              ? Webhooks.countDeliveries(db, id).catch(() => undefined)
               : undefined
 
             // Fetch one extra to detect a further page without a second round-trip.
             // `page` translates to a positional slice of `(page - 1) * limit` rows.
-            const rows = await Webhooks.listDeliveries(store, id, {
+            const rows = await Webhooks.listDeliveries(db, id, {
               cursor,
               limit: limit + 1,
               offset: page !== undefined && page > 1 ? (page - 1) * limit : undefined,
@@ -1554,7 +1559,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .post(
-        '/:id{wh_[A-Za-z0-9_-]+}/ping',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}/ping',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.pingWebhook.Params, {
           code: 'param_invalid',
@@ -1589,20 +1594,20 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the path parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
           const { id } = c.req.valid('param')
           try {
             // Owner-scope first so unowned/unknown ids are indistinguishable (404).
-            const subscription = await Webhooks.getSubscription(store, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id)
             if (!subscription) return notFound(c)
 
             // Inline delivery (not the queue) so the caller gets an immediate
             // result. `ping` never mutates the subscription's failure/lifecycle
             // state — a test must not disable a healthy endpoint.
-            const { envelope, result } = await Webhooks.ping(store, subscription)
+            const { envelope, result } = await Webhooks.ping(db, subscription)
             return c.json(
               Response.validated(schema.pingWebhook.Response, {
                 delivered: result.ok,
@@ -1619,7 +1624,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .post(
-        '/:id{wh_[A-Za-z0-9_-]+}/deliveries/:deliveryId/retry',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}/deliveries/:deliveryId/retry',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.retryWebhookDelivery.Params, {
           code: 'param_invalid',
@@ -1653,17 +1658,17 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the path parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
           const { deliveryId, id } = c.req.valid('param')
           try {
             // Owner-scope the subscription first so unowned ids 404 like elsewhere.
-            const subscription = await Webhooks.getSubscription(store, owner, id)
+            const subscription = await Webhooks.getSubscription(db, owner, id)
             if (!subscription) return notFound(c)
 
-            const delivery = await Webhooks.getDelivery(store, id, deliveryId)
+            const delivery = await Webhooks.getDelivery(db, id, deliveryId)
             if (!delivery)
               return Response.error(c, {
                 code: 'delivery_not_found',
@@ -1673,7 +1678,7 @@ export function webhooks(options: webhooks.Options = {}) {
 
             // Replay the exact persisted envelope inline. Unlike `ping`, this is a
             // real event, so the outcome updates the subscription's failure state.
-            const result = await Webhooks.deliverAndRecord(store, subscription, delivery.envelope)
+            const result = await Webhooks.deliverAndRecord(db, subscription, delivery.envelope)
             return c.json(
               Response.validated(schema.retryWebhookDelivery.Response, {
                 delivered: result.ok,
@@ -1690,7 +1695,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .patch(
-        '/:id{wh_[A-Za-z0-9_-]+}',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.updateWebhook.Params, {
           code: 'param_invalid',
@@ -1733,7 +1738,7 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the request body and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
@@ -1746,11 +1751,11 @@ export function webhooks(options: webhooks.Options = {}) {
             // persisting — otherwise a bad filter would silently widen the match
             // set at scan time.
             if (patch.filters !== undefined) {
-              const existing = await Webhooks.getSubscription(store, owner, id)
+              const existing = await Webhooks.getSubscription(db, owner, id)
               if (!existing) return notFound(c)
               parseFilters(existing.eventType, patch.filters)
             }
-            const subscription = await Webhooks.updateSubscription(store, owner, id, patch)
+            const subscription = await Webhooks.updateSubscription(db, owner, id, patch)
             if (!subscription) return notFound(c)
             return c.json(
               Response.validated(schema.updateWebhook.Response, toPublic(subscription)),
@@ -1762,7 +1767,7 @@ export function webhooks(options: webhooks.Options = {}) {
         },
       )
       .delete(
-        '/:id{wh_[A-Za-z0-9_-]+}',
+        '/v1/webhooks/:id{wh_[A-Za-z0-9_-]+}',
         Auth.policy({ apiKey: { scopes: ['webhooks:write'] } }),
         OpenApi.validate('param', schema.deleteWebhook.Params, {
           code: 'param_invalid',
@@ -1796,13 +1801,13 @@ export function webhooks(options: webhooks.Options = {}) {
               message: 'Check the path parameters and try again.',
             })
 
-          const store = c.get('webhook')!.store
+          const db = Db.get(c.get('db'))
           const owner = ownerFor(c)
           if (!owner) return unauthorized(c)
 
           const { id } = c.req.valid('param')
           try {
-            const deleted = await Webhooks.deleteSubscription(store, owner, id)
+            const deleted = await Webhooks.deleteSubscription(db, owner, id)
             if (!deleted) return notFound(c)
             return c.json(Response.validated(schema.deleteWebhook.Response, { id }), 200)
           } catch (cause) {
@@ -1874,12 +1879,13 @@ type ScanPage = {
 export async function poll(options: poll.Options): Promise<poll.Result> {
   const {
     batchSize = 100,
+    cache: cache_metadata = Store.memory(),
     chainId,
     client,
     confirmations = 2,
+    db,
     eventTypes = ['token:transfer', 'transaction:included', 'log:emitted', 'block:created'],
     maxBlocks = 1_000,
-    store,
     tidx,
   } = options
   const now = options.now ?? (() => new Date())
@@ -1888,7 +1894,7 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
   // Queue producer instead and the consumer runs `deliverAndRecord`.
   const dispatch =
     options.dispatch ??
-    (({ envelope, subscription }) => Webhooks.deliverAndRecord(store, subscription, envelope))
+    (({ envelope, subscription }) => Webhooks.deliverAndRecord(db, subscription, envelope))
 
   // Head resolution is lazy and per-source. RPC types work back from the live
   // RPC head; the legacy TIDX types from the indexed head (never ahead of the
@@ -1901,6 +1907,9 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
     (tidxHead ??= tidx ? await getIndexedHead(tidx, chainId) : await resolveRpcHead())
 
   const rpcSafeBlock = Math.max(0, (await resolveRpcHead()) - confirmations)
+  // Reclaim expired rows (MPP-owned subscriptions, aged delivery logs) once
+  // per tick; reads filter expiry at query time, so this is hygiene only.
+  await Webhooks.pruneExpired(db, { now }).catch(() => {})
   // Per-tick lazy cache so multiple subscriptions of the same/related types
   // share fetched blocks and receipts instead of refetching the same window.
   const cache = createChainCache(client)
@@ -1916,19 +1925,15 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
   for (const eventType of eventTypes) {
     const legacy = eventType === 'token:transfer'
     const safeBlock = legacy ? Math.max(0, (await resolveTidxHead()) - confirmations) : rpcSafeBlock
-    const subscriptions = await Webhooks.listActive(store, chainId, eventType)
+    const subscriptions = await Webhooks.listActive(db, chainId, eventType)
     for (const subscription of subscriptions) {
       result.subscriptions++
-      const cursor = await Webhooks.getCursor(store, subscription.id)
+      const cursor = await Webhooks.getCursor(db, subscription.id)
       if (cursor === null) {
         // First time we've seen this subscription: anchor it at the head of the
         // confirmed window so we never backfill from genesis. Events start
         // flowing from the next tick onward.
-        await Webhooks.setCursor(
-          store,
-          subscription.id,
-          Cursor.encode([safeBlock, endOfBlockIndex]),
-        )
+        await Webhooks.setCursor(db, subscription.id, Cursor.encode([safeBlock, endOfBlockIndex]))
         continue
       }
       const page = await scanSubscription({
@@ -1951,7 +1956,7 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
         // payloads) can render `amount` in token units. Non-fatal on failure.
         const data =
           eventType === 'token:transfer'
-            ? await withTokenMetadata(item.data, { chainId, client, store })
+            ? await withTokenMetadata(item.data, { cache: cache_metadata, chainId, client })
             : item.data
         const envelope = Webhooks.buildEnvelope({
           blockNumber: item.cursor[0],
@@ -1976,21 +1981,16 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
       // matches); keyset scanners advance past the last dispatched row, or — on
       // a complete empty page — to the end of the confirmed window.
       if (failed) {
-        if (accepted) await Webhooks.setCursor(store, subscription.id, Cursor.encode([...accepted]))
+        if (accepted) await Webhooks.setCursor(db, subscription.id, Cursor.encode([...accepted]))
       } else if (page.scannedThrough !== undefined)
         await Webhooks.setCursor(
-          store,
+          db,
           subscription.id,
           Cursor.encode([page.scannedThrough, endOfBlockIndex]),
         )
-      else if (accepted)
-        await Webhooks.setCursor(store, subscription.id, Cursor.encode([...accepted]))
+      else if (accepted) await Webhooks.setCursor(db, subscription.id, Cursor.encode([...accepted]))
       else if (!page.hasMore)
-        await Webhooks.setCursor(
-          store,
-          subscription.id,
-          Cursor.encode([safeBlock, endOfBlockIndex]),
-        )
+        await Webhooks.setCursor(db, subscription.id, Cursor.encode([safeBlock, endOfBlockIndex]))
     }
   }
 
@@ -2009,12 +2009,16 @@ export declare namespace poll {
   type Options = {
     /** Max matching rows scanned per subscription per tick (default 100). */
     batchSize?: number | undefined
+    /** Cache store for the token-metadata memoize (defaults to a fresh in-memory store; pass a persistent one to share lookups across ticks). */
+    cache?: Store.Store | undefined
     /** Chain to poll. Callers loop over chains. */
     chainId: number
     /** viem RPC client for the chain (used by the RPC monitoring scanners). */
     client: Viem.getClient.ReturnType
     /** Reorg-safety window: only emit blocks this far behind head (default 2). */
     confirmations?: number | undefined
+    /** Database holding subscriptions + cursors. */
+    db: Db.Db
     /**
      * Delivery transport. Defaults to inline {@link Webhooks.deliverAndRecord} (self-host);
      * on Cloudflare pass a Queue producer so retry/backoff/DLQ are native.
@@ -2028,8 +2032,6 @@ export declare namespace poll {
     maxBlocks?: number | undefined
     /** Clock for envelope timestamps; injectable for tests. */
     now?: (() => Date) | undefined
-    /** Webhook state store (subscriptions + cursors). */
-    store: Store.State
     /** TIDX query client for the legacy `token:transfer` type. */
     tidx?: Tidx.Client | undefined
   }
@@ -2059,9 +2061,9 @@ export declare namespace poll {
 async function withTokenMetadata(
   data: unknown,
   deps: {
+    cache: Store.Store
     chainId: number
     client: Viem.getClient.ReturnType
-    store: Store.State
   },
 ): Promise<unknown> {
   if (typeof data !== 'object' || data === null) return data
@@ -2079,7 +2081,7 @@ async function withTokenMetadata(
  */
 async function resolveTokenMetadata(
   address: string,
-  deps: { chainId: number; client: Viem.getClient.ReturnType; store: Store.State },
+  deps: { cache: Store.Store; chainId: number; client: Viem.getClient.ReturnType },
 ): Promise<{ decimals: number; symbol: string } | undefined> {
   try {
     return await Store.memoize(
@@ -2089,7 +2091,7 @@ async function resolveTokenMetadata(
       },
       {
         key: `webhook:token-meta:v1:${deps.chainId}:${address}`,
-        store: deps.store,
+        store: deps.cache,
         ttl: Ttl.minutes(5),
       },
     )

package/src/apps/docs/App.ts

@@ -0,0 +1,136 @@
+import { Hono } from 'hono'
+import { Handler as vocs_Handler } from 'vocs/server'
+
+import type * as App from '../../App.js'
+import * as Metadata from '../metadata.js'
+import openrpcSpec from '../../openrpc.json' with { type: 'json' }
+import { pilatFontFaces } from './fonts.js'
+import { logoUrl } from './logo.js'
+
+/**
+ * The docs route group: the Vocs API reference served at the app root.
+ *
+ * ```ts
+ * import { docs } from 'tapimo/docs'
+ * App.create(options).route('/', data()).route('/', platform()).route('/', docs())
+ * ```
+ *
+ * The group registers no routes itself: it carries a reference factory (via
+ * {@link Metadata}) that `App.create` mounts on finalize, after every group and
+ * the OpenAPI/OpenRPC documents — so the reference always renders the full
+ * composed surface and its catch-all stays behind API routes, wherever the
+ * group sits in the composition chain.
+ *
+ * Lives in the `tapimo/docs` subpath (never re-exported from `tapimo/apps`) so
+ * the Vocs renderer and its multi-MB icon/font data are bundled only by
+ * deployments that actually serve docs.
+ */
+export function docs(options: docs.Options = {}) {
+  return Metadata.attach(new Hono<App.Environment>(), {
+    docs: ({ spec }) =>
+      vocs_Handler.openApi(
+        {
+          // Inline the OpenRPC doc so vocs expands it without a self-subrequest
+          // (see `inlineOpenrpc`); the public `/openapi.json` keeps the URL ref.
+          spec: () => spec().then(inlineOpenrpc),
+          sidebar: { collapsed: true },
+          vocs: { logoUrl, title: 'Tempo API Reference', ...options },
+        },
+        { css, fallback: 'next' },
+      ),
+  })
+}
+
+export declare namespace docs {
+  /** Vocs API reference options (theme, top navigation, logo, socials, …). */
+  type Options = NonNullable<Parameters<typeof vocs_Handler.openApi>[0]['vocs']>
+}
+
+/**
+ * Custom CSS injected into the standalone reference's shell `<head>` (via
+ * `Handler.openApi(_, { css })`), after the Vocs design-system styles so it
+ * overrides them:
+ *
+ * - Page/surface backgrounds use Tempo's near-black dark palette and pure-white
+ *   light palette via `light-dark(<light>, <dark>)`.
+ * - The dark border color is darkened (the light theme keeps its default).
+ * - Every corner is squared. The universal `!important` rule beats hard-coded
+ *   `border-radius` values and inline styles (e.g. the Scalar playground), which
+ *   overriding the radius scale variables alone would miss.
+ * - The default sans/body font is Pilat (Vocs reads `--vocs-font-family`); the
+ *   webfont is embedded via {@link pilatFontFaces}. Body stays at the default
+ *   weight (400); headings are pinned to 500, which renders Pilat Demi (the
+ *   family has no 500 cut, so Demi covers the 500-600 range — see
+ *   {@link pilatFontFaces}).
+ */
+const css = `${pilatFontFaces}
+
+:root {
+  --vocs-font-family: "Pilat", Arial, Helvetica, sans-serif;
+  --vocs-background-color-primary: light-dark(#fafafa, #0a0a0a);
+  --vocs-background-color-surface: light-dark(#fff, #121212);
+}
+
+:is(h1, h2, h3, h4, h5, h6)[data-v] {
+  font-weight: 500;
+}
+
+/* Nudge the header logo a touch larger than the default max-h-7 (1.75rem). */
+[data-v-logo-image] {
+  max-height: 2rem;
+}
+
+/* Sidebar leaf items render Regular (the nav's 450 default otherwise resolves to
+ * Demi via the 500-600 range). Group labels ([data-v-sidebar-section-header])
+ * keep their heavier weight. */
+[data-v-sidebar-item] {
+  font-weight: 400;
+}
+
+[data-vocs-theme='dark'] {
+  --vocs-color-gray4: oklch(20% 0 0);
+  --vocs-color-gray5: oklch(0.23 0 0);
+  --vocs-border-color-primary: oklch(0.25 0 0);
+  --vocs-border-color-secondary: oklch(0.25 0 0);
+}
+
+*,
+*::before,
+*::after {
+  border-radius: 0 !important;
+}`
+
+/**
+ * Returns a shallow copy of `spec` with the JSON-RPC passthrough operation's
+ * `x-openrpc` replaced by the inline OpenRPC document, for the docs handler.
+ *
+ * Vocs expands `x-openrpc` at request time. A URL reference (as kept in the
+ * public `/openapi.json` by `App.create`'s `applyOpenrpcLink`) would make the
+ * docs worker fetch its own `/openrpc.json` — a self-subrequest that is
+ * unreliable on Cloudflare Workers and silently falls back to a single,
+ * unexpanded operation. Inlining the committed artifact keeps expansion
+ * deterministic across local and deployed environments, without bloating the
+ * public spec. Only the affected path/op are cloned; the rest of the (large)
+ * document is shared by reference.
+ */
+function inlineOpenrpc<spec extends { paths: Record<string, unknown> }>(spec: spec): spec {
+  const paths: Record<string, unknown> = {}
+  for (const [pathname, item] of Object.entries(spec.paths)) {
+    let next = item
+    if (isRecord(item))
+      for (const [method, op] of Object.entries(item))
+        if (isRpcOperation(op)) next = { ...item, [method]: { ...op, 'x-openrpc': openrpcSpec } }
+    paths[pathname] = next
+  }
+  return { ...spec, paths }
+}
+
+// The JSON-RPC passthrough's operation id, set by its route definition and
+// targeted by `App.create`'s `applyOpenrpcLink`.
+function isRpcOperation(op: unknown): op is Record<string, unknown> {
+  return isRecord(op) && op['operationId'] === 'rpcRequest'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}

package/src/apps/docs/index.ts

@@ -0,0 +1 @@
+export { docs } from './App.js'

package/src/apps/index.ts

@@ -0,0 +1,3 @@
+export { data } from './data/index.js'
+export { platform } from './platform/index.js'
+export { relay } from './relay/index.js'

package/src/apps/metadata.ts

@@ -0,0 +1,23 @@
+import type { Hono } from 'hono'
+
+import type * as App from '../App.js'
+
+// Hono's `.route()` drops sub-app metadata, so a group's OpenAPI metadata can't
+// ride the instance through it. Each group attaches its metadata here and
+// `App.create` reads it back on mount. The `WeakMap` keeps the association off
+// the app's type, so `testClient`/`hc` inference is untouched.
+const registry = new WeakMap<Hono<any, any>, App.create.Metadata>()
+
+/** Attaches a group's OpenAPI metadata to its app instance for `create` to collect on mount. */
+export function attach<const app extends Hono<any, any>>(
+  app: app,
+  metadata: App.create.Metadata,
+): app {
+  registry.set(app, metadata)
+  return app
+}
+
+/** Reads the OpenAPI metadata attached to an app instance, if any. */
+export function read(app: Hono<any, any>): App.create.Metadata | undefined {
+  return registry.get(app)
+}