API Docs Restructure — Notes

A record of the effort that reorganized the Development → API section into one cohesive area and established our API-documentation convention. Living standard: API Reference Conventions.

Motivation

• The API section had grown ad-hoc: two narrative pages (Pane Controls, Guest↔Host RPC) that mixed architecture prose with embedded API tables and code.
• tranquil-rpc ships two authoritative TypeScript declaration files (tranquil-rpc/types/host-api.d.ts, tranquil-rpc/types/tranquil-rpc.d.ts) whose contents weren’t rendered anywhere — only referenced by path.
• A name collision made the section read as contradictory: two different register functions (the RPC guest capability vs. the host-side injector) were documented without disambiguation.

The three API surfaces

Surface	Entry point	Source of truth	Reference
RPC Host API (guest-facing)	window.tranquilHost	tranquil-rpc/types/host-api.d.ts	Host API
RPC Module API (consumer-facing)	require("tranquil-rpc")	tranquil-rpc/types/tranquil-rpc.d.ts	Module API
Pane Controls registration (host-side injector)	register(match, items)	tranquil-automations/lib/pane-controls.js	Pane Controls API

The two registers: window.tranquilHost.paneControls.register(items) (RPC capability; bare stub action) vs. register(match, items) (host-side injector; action(ctx)). The RPC capability bridges into the host-side one via pane-controls-capability.js. Every relevant page now spells this out.

Information architecture

API
 ├ API Overview              (map / landing)
 ├ Concepts
 │   ├ Pane Controls         (narrative)
 │   └ Guest↔Host RPC        (narrative)
 ├ Reference
 │   ├ Pane Controls API     (host register(match,items))
 │   ├ Host API              (RPC guest — window.tranquilHost)
 │   └ Module API            (RPC consumer — require("tranquil-rpc"))
 └ Contributing
     └ API Reference Conventions

Wired via nested subsections on the API section in src/lib/data/docs.ts.

Two documentation lanes

Surface type	Tool
HTTP/REST described by an OpenAPI/Swagger doc	Scalar interactive reference
Code / library / RPC (TS .d.ts, host caps, module/injector exports)	Hand-written reference pages

All three surfaces above are code/RPC interfaces, so they’re hand-written per the convention. Scalar is the agreed tool for HTTP APIs but is not yet installed or wired — no OpenAPI spec to point at.

What changed

Pages added

• development/api-overview — reader-facing map of the section.
• development/api-reference-conventions — the author-facing standard.
• development/host-api-reference — RPC guest surface (from host-api.d.ts).
• development/module-api-reference — RPC consumer surface (from tranquil-rpc.d.ts).
• development/pane-controls-api-reference — host-side register(match, items) (from lib/pane-controls.js), extracted from the Pane Controls narrative.

Pages refactored to pure narrative (API tables/code moved to the references, replaced with links)

• development/guest-host-rpc — trimmed the capability catalog table, the consumers code block, and the guest code block.
• development/pane-controls — removed the “Registration API” section (moved to the reference).

Follow-up / TODO

• Wire Scalar (@scalar/sveltekit, or the CDN @scalar/api-reference) once the Tranquil server’s OpenAPI spec (Hono + Zod OpenAPI, ADR-0007) has a stable URL. Surface it under the Reference subsection next to the hand-written pages.
• Graduate pane-controls items as the feature grows beyond the business mockups.
• Keep each reference in lockstep with its source — the .d.ts files and lib/pane-controls.js are the sources of truth.