@volter/twin-postmark 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,144 @@
+# @volter/twin-postmark
+
+A local **Postmark** twin — a faithful, stateful local Postmark transactional-email API your
+real `postmark` SDK talks to **unmodified**. Send plain/templated/batch email; browse outbound
+message activity with per-message delivery events; bounces + delivery stats; templates with
+Mustachio rendering; message streams; suppressions; webhooks; servers, domains and sender
+signatures. A **deterministic offline delivery lifecycle** writes real `MessageEvents`, mints
+Bounce records and suppressions, and POSTs **Postmark's real (unsigned, Basic-auth/custom-header)
+webhook payloads** to your registered endpoints. Ships a **React activity mirror UI** rendered
+from real twin state. Built on the shared [`@volter/world-core`](../../world-core) kernel
+(append-only event log + projection, local-action writes, egress ledger, connectors, pack
+registry).
+
+```ts
+import { ServerClient, Models } from 'postmark';
+import { createPostmarkTwinServer } from '@volter/twin-postmark';
+
+const twin = createPostmarkTwinServer({ port: 0 });          // local, offline
+// The SDK's OWN public option points it at the twin — nothing is monkey-patched.
+const postmark = new ServerClient(
+  '11111111-2222-3333-4444-555555555555',
+  new Models.ClientOptions.Configuration(false, `127.0.0.1:${twin.port}`, 30),
+);
+
+const sent = await postmark.sendEmail({
+  From: 'Acme <notifications@acme.dev>',
+  To: 'ada@example.com',
+  Subject: 'Your login code',
+  TextBody: 'Your code is 123456',
+});                                    // → { MessageID, SubmittedAt, ErrorCode: 0, Message: 'OK' }
+
+const details = await postmark.getOutboundMessageDetails(sent.MessageID);
+details.MessageEvents;                 // → [{ Type: 'Delivered', … }]
+```
+
+Zero-edit redirection also works: set `POSTMARK_TWIN_URL` and the control-plane injector
+forwards `api.postmarkapp.com` to the twin, so an **unchanged** app finds it with no config.
+
+## CLI
+
+```
+world-postmark serve       [--port N] [--root DIR] [--read-only]   # the Postmark API twin
+world-postmark mirror      [--port N] [--root DIR]                 # the activity mirror UI
+world-postmark conformance [--root DIR]                            # spec-true validation
+```
+
+## How it works
+
+- **A repo, not a mock.** Every write is a local action appended to the kernel's log; every
+  read folds the projection. A sent message is **stored** in twin state — never put on the
+  wire — and `GET /messages/outbound` serves the same projection the mirror renders.
+- **Auth is Postmark's, faked locally.** `X-Postmark-Server-Token` on server-scoped routes and
+  `X-Postmark-Account-Token` on account-scoped ones (**not** a Bearer token). A twin holds no
+  account, so any non-empty token is accepted; a missing or empty one fails like the vendor
+  with `401 {ErrorCode: 10}` and the vendor's endpoint-scoped message text. The documented
+  public test token `POSTMARK_API_TEST` is modeled with its real `/email`-only restriction.
+- **A deterministic offline delivery lifecycle.** A send records `MessageEvents` on the stored
+  message: `Delivered`, plus `Opened`/`LinkClicked` **only when the message asked for that
+  tracking** (Postmark's tracking is opt-in). A recipient whose local part starts with
+  `bounce` hard-bounces; `spam`/`complaint` raises a spam complaint. Both mint a real Bounce
+  record **and a suppression**, so a later send to that address is refused with the vendor's
+  `422 {ErrorCode: 406}` — genuinely stateful behavior, not a fresh-root trick.
+- **Webhooks are Postmark's, which means UNSIGNED.** There is no svix/HMAC scheme anywhere in
+  Postmark's design. Deliveries carry a `RecordType` discriminator
+  (`Delivery`/`Open`/`Click`/`Bounce`/`SpamComplaint`) and are authenticated the two ways the
+  Webhooks API actually models: `HttpAuth` → an HTTP Basic header, and `HttpHeaders` → your
+  own headers. A webhook only receives a record type whose trigger is enabled, on its own
+  message stream. `postmark.honesty.no_webhook_signature` is a deliberate negative assertion
+  that keeps a future contributor from copying a sibling pack's signature scheme in here.
+- **The mirror is API passthrough (archetype A).** The browser client fetches **Postmark's own
+  real API paths**; there is exactly one handler serving both the screen and the SDK, so
+  API↔UI parity cannot drift.
+
+## Coverage
+
+**Partial and honest, and it is meant to read that way.** The capability manifest
+(`src/postmark-capabilities.ts`) is the **real vendor surface as the denominator** — all 15
+documented API groups and 86 endpoints from developer.postmarkapp.com's docs nav, enumerated
+top-down whether or not this twin has reached them. Coverage grows by building, and the
+percentage *drops* when the denominator honestly grows. See the generated table in the repo
+[README](../../../docs/contributing/conformance.md) for the live numbers.
+
+**Where the surface came from** (recorded in `spec-sources.json` as `kind: "none"` — Postmark
+publishes no OpenAPI/SDL):
+
+1. The **official `postmark` npm SDK v4.0.7**'s compiled route map and TypeScript models —
+   a first-party artifact naming every path, verb, field, casing and list envelope, plus its
+   `AuthHeaderNames` enum and `ApiInputError.ERROR_CODES`.
+2. developer.postmarkapp.com's published **API-error-codes table** (163 rows) — the source of
+   every `ErrorCode`/HTTP-status pair in `POSTMARK_ERRORS`.
+3. **Live read-only probes** of `api.postmarkapp.com` with the documented public test token,
+   made during this pack's build. These corrected three things the docs alone get wrong, each
+   annotated `[WIRE]` in `postmark-twin.ts`:
+   - **`Subject` is NOT required** on `POST /email` — a subject-less send succeeds;
+   - the **401 message text is endpoint-scoped** ("valid Server token" vs "valid Account
+     token"), not the merged string the docs table shows;
+   - **`POSTMARK_API_TEST` is `/email`-only**, answering `403` + `ErrorCode 10` anywhere else,
+     and `"Test job accepted"` rather than `"OK"` on a send.
+
+Anything not grounded in those three is marked `⚠ doc-unverified` in the source and never
+claimed beyond what a `verify()` proves.
+
+### Fidelity quirks deliberately preserved
+
+Postmark's API is inconsistent in ways a tidy-minded twin would silently "fix". These are
+modeled as-is, because a consumer's parsing depends on them:
+
+- `TotalCount` comes **first** on every list envelope **except** `/message-streams` (last) and
+  `/webhooks` (**absent entirely**).
+- `/senders` returns a **`SenderSignatures`** array, not `Senders`.
+- `/deliverystats`'s first bounce row is the `"All"` total and carries **no `Type` key**.
+- Batch sends answer **HTTP 200 with per-message errors inside a bare array** — never a
+  top-level 422 (only the >500 cap is).
+- Suppression deletion is a **POST to `…/suppressions/delete`**, not an HTTP `DELETE`.
+- "Not found" for a known route is **422 + a per-domain `ErrorCode`**, not 404; 404 is
+  reserved for a route that does not exist at all.
+- An outbound message **mixes two recipient shapes in one payload**: `To`/`Cc`/`Bcc` are
+  arrays of `{Email, Name}` **objects** while `Recipients`, right beside them, is an array of
+  **plain email strings** (all of To+Cc+Bcc flattened). This is the vendor's real shape, not a
+  twin bug — grounded in the outbound-search example on
+  postmarkapp.com/developer/api/messages-api (`"To":[{"Email":…,"Name":…}]` next to
+  `"Recipients":["…"]`) **and** the official `postmark` SDK's own types
+  (`OutboundMessage.To: Recipient[]` vs `Recipients: string[]`), and pinned by
+  `postmark.messages.outbound_recipient_shapes` so neither side is ever "fixed" into
+  consistency. (One sub-shape divergence, recorded honestly: for a bare address with no
+  display name the docs example shows `"Name": null` where this twin emits `""` — the string
+  the official SDK's non-nullable `Name: string` type declares.)
+
+### No UI mirror? — it has one, and here is the rule it was decided by
+
+Postmark's core job is done in **code** (an integrator calls `POST /email`), so `ui-scope.json`
+records `needsUi: false`: it is **not an agent navigation target**. The mirror exists as a
+**state visualization** — the local-dev outbox where a human inspects what the twin stored,
+which is exactly what Postmark's Activity dashboard is for. Same classification and same
+reasoning as the sibling `resend` pack. Every UI capability is **data-coupled** (seed through
+the twin's write path → fetch the same API the screen reads → assert), never a marker grep.
+
+### Known gaps (filed, not hidden)
+
+Tracked as `todo` capabilities and in `pull-audit.json`: the Bulk API lifecycle, real inbound
+ingestion, `PUT /templates/push`, webhook verify/statistics, full Mustachio blocks
+(`{{#each}}`/`{{#if}}`) and layout composition, the rate-limit response headers and 429 path,
+the `415` problem+json envelope, and connector pulls for account-token domains/sender
+signatures, stream-scoped suppressions, inbound messages, and >500-row pagination.

package/client/postmark-mirror.css

@@ -0,0 +1,79 @@
+:root {
+  --bg: #09090b;
+  --panel: #131316;
+  --panel-2: #1b1b20;
+  --border: #2a2a30;
+  --text: #ededf0;
+  --muted: #9a9aa5;
+  --accent: #ffe01b; /* Postmark yellow */
+  --accent-2: #facc15;
+  --ok: #22c55e;
+  --warn: #f59e0b;
+  --bad: #ef4444;
+  --neutral: #6b6b7b;
+}
+* { box-sizing: border-box; }
+html, body, #root { height: 100%; margin: 0; }
+body {
+  background: var(--bg);
+  color: var(--text);
+  font: 14px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+}
+.mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+.app { display: flex; flex-direction: column; height: 100%; }
+.topbar {
+  display: flex; align-items: baseline; gap: 12px;
+  padding: 12px 18px; border-bottom: 1px solid var(--border); background: var(--panel);
+}
+.brand { font-weight: 700; color: var(--accent); font-size: 16px; }
+.subtitle { color: var(--muted); font-size: 12px; }
+/* The pane a reader OPENED gets the width. Three near-fixed tracks left the detail with
+   whatever was left over — 325px inside an 865px mirror embedded in a Room — and its own
+   label column then took 220px of that, so a MessageID rendered four characters per line.
+   Both tracks answer to the width they are actually given now. */
+.body { display: grid; grid-template-columns: 200px minmax(220px, 0.8fr) minmax(0, 1.4fr); flex: 1; min-height: 0; }
+.nav { border-right: 1px solid var(--border); background: var(--panel); padding: 8px; overflow: auto; }
+.nav-item {
+  display: block; width: 100%; text-align: left; padding: 8px 10px; margin-bottom: 2px;
+  background: transparent; color: var(--text); border: 0; border-radius: 6px; cursor: pointer;
+}
+.nav-item:hover { background: var(--panel-2); }
+.nav-item.active { background: var(--panel-2); color: #fff; border-left: 3px solid var(--accent); }
+.list { border-right: 1px solid var(--border); overflow: auto; background: var(--bg); }
+.list-head { padding: 10px 14px; color: var(--muted); font-weight: 600; border-bottom: 1px solid var(--border); position: sticky; top: 0; background: var(--bg); }
+.row {
+  display: block; width: 100%; text-align: left; padding: 10px 14px; border: 0;
+  border-bottom: 1px solid var(--border); background: transparent; color: var(--text); cursor: pointer;
+}
+.row:hover { background: var(--panel-2); }
+.row.selected { background: var(--panel-2); border-left: 3px solid var(--accent-2); }
+.row-title { font-weight: 600; }
+.row-sub { color: var(--muted); font-size: 12px; }
+.detail { overflow: auto; padding: 16px 18px; }
+.detail-head { display: flex; align-items: center; gap: 10px; margin-bottom: 12px; }
+.message-view { margin-bottom: 16px; }
+.message-meta { color: var(--muted); font-size: 12px; margin-bottom: 10px; display: grid; gap: 2px; }
+.timeline { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 12px; }
+.timeline .event {
+  padding: 2px 8px; border-radius: 4px; font-size: 11px; text-transform: capitalize;
+  border: 1px solid var(--border); color: var(--muted);
+}
+.timeline .event.ok { color: var(--ok); border-color: var(--ok); }
+.timeline .event.warn { color: var(--warn); border-color: var(--warn); }
+.timeline .event.bad { color: var(--bad); border-color: var(--bad); }
+.message-html { width: 100%; height: 320px; border: 1px solid var(--border); border-radius: 6px; background: #fff; }
+.message-text { white-space: pre-wrap; word-break: break-word; background: var(--panel); padding: 12px; border-radius: 6px; border: 1px solid var(--border); }
+.detail-lines { margin: 12px 0 0; }
+.detail-line { display: grid; grid-template-columns: minmax(88px, min(220px, 38%)) minmax(0, 1fr); gap: 12px; padding: 4px 0; border-bottom: 1px solid var(--border); }
+.detail-line dt { color: var(--muted); overflow: hidden; text-overflow: ellipsis; }
+.detail-line dd { margin: 0; word-break: break-word; }
+.empty { padding: 16px; color: var(--muted); }
+.empty.error { color: var(--bad); }
+.pill {
+  display: inline-block; padding: 2px 8px; border-radius: 999px; font-size: 11px;
+  text-transform: capitalize; border: 1px solid var(--border);
+}
+.pill.ok { color: var(--ok); border-color: var(--ok); }
+.pill.warn { color: var(--warn); border-color: var(--warn); }
+.pill.bad { color: var(--bad); border-color: var(--bad); }
+.pill.neutral { color: var(--neutral); }

package/client/postmark-mirror.tsx

@@ -0,0 +1,221 @@
+// Postmark UI mirror — React/TSX client (Bun-bundled). A Postmark-dashboard-style console:
+// top bar + left nav + list/detail split, with Activity (the outbound message stream) as the
+// main screen, plus Bounces, Templates, Streams, Webhooks and Suppressions.
+//
+// It renders by consuming the twin's OWN REST API on the same origin, at POSTMARK'S REAL
+// PATHS (/messages/outbound, /messages/outbound/:id/details, /bounces, /templates,
+// /message-streams, /webhooks, /message-streams/outbound/suppressions/dump) — the exact
+// endpoints a real integration calls. One code path serves both, so API↔UI parity holds by
+// construction.
+//
+// The pure format helpers live in ../src/postmark-mirror-ui.ts so they can be unit-tested AND
+// shared here (Bun tree-shakes the server-only exports out of this browser bundle).
+import React, { useEffect, useMemo, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import {
+  recipientsOf, messageSubject, messageStatus, messagePreview, deliveryTimeline,
+  formatPostmarkDate, statusTone, flattenPostmarkValue, POSTMARK_MIRROR_SECTIONS,
+  type PostmarkRow, type FlatLine, type MirrorSection,
+} from '../src/postmark-mirror-ui.ts';
+
+// WHERE THIS MIRROR LIVES. Served at a vendor root the base is '' (fetches are root-relative, as
+// before); served under a path prefix with a <base> tag every read and write resolves inside that
+// prefix instead of escaping it.
+const WIRE_BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
+
+export function StatusPill({ value }: { value: any }) {
+  const v = String(value ?? '');
+  return <span className={`pill ${statusTone(v)}`}>{v || '—'}</span>;
+}
+
+/** The rendered body preview — html in an isolated frame, text in a <pre>. */
+export function MessageBody({ message }: { message: PostmarkRow }) {
+  const preview = messagePreview(message);
+  if (preview.kind === 'html') {
+    return <iframe className="message-html" title="message body" sandbox="" srcDoc={preview.value} />;
+  }
+  if (preview.kind === 'text') {
+    return <pre className="message-text">{preview.value}</pre>;
+  }
+  return <div className="empty">No body.</div>;
+}
+
+/** The MessageEvents timeline the twin recorded for a sent message. */
+export function DeliveryTimeline({ message }: { message: PostmarkRow }) {
+  const events = deliveryTimeline(message);
+  return (
+    <div className="timeline">
+      {events.map((ev, i) => (
+        <span key={`${ev}-${i}`} className={`event ${statusTone(ev)}`}>{ev}</span>
+      ))}
+    </div>
+  );
+}
+
+/** Render the flattened nested-field lines for the detail panel. */
+export function NestedLines({ lines }: { lines: FlatLine[] }) {
+  return (
+    <dl className="detail-lines">
+      {lines.map((ln, i) => (
+        <div className="detail-line" key={`${ln.key}-${i}`}>
+          <dt className="mono">{ln.key}</dt>
+          <dd className="mono">{ln.value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
+
+/** The one-line summary each nav section shows for a row. */
+function rowTitle(section: MirrorSection, r: PostmarkRow): string {
+  if (section.key === 'messages') return messageSubject(r);
+  if (section.key === 'bounces') return `${r.Type ?? 'Bounce'} · ${r.Email ?? ''}`;
+  if (section.key === 'templates') return String(r.Name ?? r.TemplateId ?? '');
+  if (section.key === 'streams') return String(r.Name ?? r.ID ?? '');
+  if (section.key === 'webhooks') return String(r.Url ?? r.ID ?? '');
+  if (section.key === 'suppressions') return String(r.EmailAddress ?? '');
+  return String(r[section.idKey] ?? '');
+}
+function rowSubtitle(section: MirrorSection, r: PostmarkRow): string {
+  if (section.key === 'messages') return `to ${recipientsOf(r)} · ${messageStatus(r)}`;
+  if (section.key === 'bounces') return `${r.Subject ?? ''} · ${r.Inactive ? 'inactive' : 'active'}`;
+  if (section.key === 'templates') return `${r.Alias ?? '(no alias)'} · ${r.TemplateType ?? ''}`;
+  if (section.key === 'streams') return `${r.MessageStreamType ?? ''} · ${r.ID ?? ''}`;
+  if (section.key === 'webhooks') return String(r.MessageStream ?? '');
+  if (section.key === 'suppressions') return `${r.SuppressionReason ?? ''} · ${r.Origin ?? ''}`;
+  return '';
+}
+/** The status value each section pins to its pill. */
+function rowStatus(section: MirrorSection, r: PostmarkRow): string {
+  if (section.key === 'messages') return messageStatus(r);
+  if (section.key === 'bounces') return String(r.Type ?? '');
+  if (section.key === 'templates') return r.Active ? 'Active' : 'Inactive';
+  if (section.key === 'streams') return r.ArchivedAt ? 'Blocked' : 'Active';
+  if (section.key === 'suppressions') return String(r.SuppressionReason ?? '');
+  return '';
+}
+
+function useCollection(section: MirrorSection): { rows: PostmarkRow[]; loading: boolean; error: string } {
+  const [rows, setRows] = useState<PostmarkRow[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+  useEffect(() => {
+    let live = true;
+    setLoading(true);
+    setError('');
+    fetch(`${WIRE_BASE}${section.path}`)
+      .then((r) => r.json())
+      .then((body) => {
+        if (!live) return;
+        const data = Array.isArray(body) ? body : Array.isArray(body?.[section.collection]) ? body[section.collection] : [];
+        setRows(data);
+        setLoading(false);
+      })
+      .catch((e) => { if (live) { setError(String(e)); setLoading(false); } });
+    return () => { live = false; };
+  }, [section.path, section.collection]);
+  return { rows, loading, error };
+}
+
+/** The Activity detail pane fetches the message's FULL record — Postmark's list endpoint
+ *  deliberately omits bodies + MessageEvents, exactly as the real API does. */
+function useMessageDetails(messageId: string | null): PostmarkRow | null {
+  const [detail, setDetail] = useState<PostmarkRow | null>(null);
+  useEffect(() => {
+    let live = true;
+    setDetail(null);
+    if (!messageId) return;
+    fetch(`${WIRE_BASE}/messages/outbound/${encodeURIComponent(messageId)}/details`)
+      .then((r) => r.json())
+      .then((body) => { if (live && body && !body.ErrorCode) setDetail(body); })
+      .catch(() => { /* the detail pane degrades to the list row */ });
+    return () => { live = false; };
+  }, [messageId]);
+  return detail;
+}
+
+export function App() {
+  const [sectionKey, setSectionKey] = useState<string>(POSTMARK_MIRROR_SECTIONS[0]!.key);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const section = POSTMARK_MIRROR_SECTIONS.find((s) => s.key === sectionKey)!;
+  const { rows, loading, error } = useCollection(section);
+  const selected = useMemo(
+    () => rows.find((r) => String(r[section.idKey]) === selectedId) ?? rows[0] ?? null,
+    [rows, selectedId, section.idKey],
+  );
+  const isMessages = section.key === 'messages';
+  const details = useMessageDetails(isMessages && selected ? String(selected.MessageID) : null);
+  const shown = details ?? selected;
+  const lines = useMemo(() => (shown ? flattenPostmarkValue(shown) : []), [shown]);
+
+  return (
+    <div className="app">
+      <header className="topbar">
+        <span className="brand">Postmark twin</span>
+        <span className="subtitle">local transactional email mirror — activity · bounces · templates · streams</span>
+      </header>
+      <div className="body">
+        <nav className="nav">
+          {POSTMARK_MIRROR_SECTIONS.map((s) => (
+            <button
+              key={s.key}
+              className={`nav-item ${s.key === sectionKey ? 'active' : ''}`}
+              onClick={() => { setSectionKey(s.key); setSelectedId(null); }}
+            >
+              {s.label}
+            </button>
+          ))}
+        </nav>
+        <section className="list">
+          <div className="list-head">{section.label}{!loading ? ` (${rows.length})` : ''}</div>
+          {loading && <div className="empty">Loading…</div>}
+          {error && <div className="empty error">{error}</div>}
+          {!loading && !error && rows.length === 0 && <div className="empty">No {section.label.toLowerCase()} yet.</div>}
+          {rows.map((r, i) => (
+            <button
+              key={`${String(r[section.idKey])}-${i}`}
+              className={`row ${selected && String(selected[section.idKey]) === String(r[section.idKey]) ? 'selected' : ''}`}
+              onClick={() => setSelectedId(String(r[section.idKey]))}
+            >
+              <div className="row-title">{rowTitle(section, r)}</div>
+              <div className="row-sub mono">{rowSubtitle(section, r)}</div>
+            </button>
+          ))}
+        </section>
+        <aside className="detail">
+          {shown ? (
+            <>
+              <div className="detail-head">
+                <span className="mono">{String(shown[section.idKey] ?? '')}</span>
+                <StatusPill value={rowStatus(section, shown)} />
+              </div>
+              {isMessages && (
+                <div className="message-view">
+                  <div className="message-meta mono">
+                    <div>from {String(shown.From ?? '—')}</div>
+                    <div>to {recipientsOf(shown)}</div>
+                    <div>{formatPostmarkDate(shown.ReceivedAt)} · stream {String(shown.MessageStream ?? '—')}</div>
+                  </div>
+                  <DeliveryTimeline message={shown} />
+                  <MessageBody message={shown} />
+                </div>
+              )}
+              <NestedLines lines={lines} />
+            </>
+          ) : (
+            <div className="empty">Select a record.</div>
+          )}
+        </aside>
+      </div>
+    </div>
+  );
+}
+
+// Browser-only mount. Guarded so the exported presentational components (StatusPill,
+// MessageBody, DeliveryTimeline, NestedLines) can be imported and renderToStaticMarkup'd in a
+// DOM-less test/SSR environment (the data-coupled UI verifies) without this top-level
+// `document` access throwing. The browser bundle still mounts exactly as before.
+if (typeof document !== 'undefined') {
+  const rootEl = document.getElementById('root');
+  if (rootEl) createRoot(rootEl).render(<App />);
+}