@volter/twin-x 0.1.0

package/src/x-media.ts

@@ -0,0 +1,295 @@
+// Media BYTES and upload sessions for the X twin — what `POST /2/media/upload` (one-shot) and the
+// chunked initialize / append / finalize protocol hold before a post attaches the media.
+//
+// The method is the slack pack's (slack-blobs.ts), transcribed. Bytes ride the KERNEL'S BLOB SEAM
+// (`getActiveBlobStore()`, runtime contract R11), content-addressed by sha256, under this service's
+// own `resources` directory, which `world scrub` already owns. An upload is NOT a kernel action:
+// at X, uploading media publishes nothing — a media id is a private, expiring handle that only a
+// later `POST /2/tweets` makes public. Recording the upload through `applyTwinWrite` would create a
+// durably pending entry with no vendor write of its own to perform, and wedge every deploy behind
+// it. So the upload SESSION (who uploaded it, its category, its segments, its finished digest) is a
+// bare pointer record in the same byte annex, carrying no approval weight. What becomes state is
+// the POST: the post's own entry names each attached media by key, id and digest, and that is the
+// record a deploy performs (x-connector.ts uploads the bytes, then posts).
+//
+// Reads go through `readResourceBlob`, which looks in this branch and then its retained ancestors,
+// so a World branch sees media its parent uploaded and a perform finds the bytes the post names.
+import { join } from 'node:path';
+import { blobDigest, getActiveBlobStore, readResourceBlob, resourceChain, worldPaths } from '@volter/world-core';
+
+const SERVICE = 'x';
+
+/** The stored upload session / finished media object, keyed by the media id X hands back. */
+export type XMediaRecord = {
+  id: string;
+  media_key: string;
+  account_id: string;
+  media_category: string;
+  /** The declared (initialize) or sniffed MIME type. */
+  media_type: string;
+  /** `initialized` while segments arrive; an image is `succeeded` once its bytes are whole; a video
+   *  is `processing` (X's pending → in_progress) until STATUS reads walk it to `succeeded`, or
+   *  `failed` when the bytes are not a video X would take. */
+  state: 'initialized' | 'processing' | 'succeeded' | 'failed';
+  /** A video's processing step counted in STATUS reads (0 = pending, 1 = in_progress, 2 = done). */
+  processing_step?: number;
+  /** World-clock epoch seconds of FINALIZE: processing also advances one step per
+   *  `check_after_secs` elapsed since, so a client that sleeps and then posts is not held back. */
+  finalized_at?: number;
+  /** Why processing failed, in X's words (served as a problem in the response's `errors`). */
+  error?: string;
+  duration_ms?: number;
+  total_bytes?: number;
+  sha256?: string;
+  size?: number;
+  width?: number;
+  height?: number;
+  additional_owners?: string[];
+  created_at: string;
+  /** Epoch seconds after which X no longer accepts the id on a post. */
+  expires_at: number;
+};
+
+/** X keeps an uploaded media id usable for a day (`expires_after_secs: 86400` on its answers). */
+export const MEDIA_EXPIRES_AFTER_SECS = 86_400;
+/** X's image ceiling: 5 MB. */
+export const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+/** X's video ceiling: 512 MB. */
+export const MAX_VIDEO_BYTES = 512 * 1024 * 1024;
+/** A `tweet_video` may run at most 140 seconds (longer videos are an `amplify_video` or a Premium entitlement). */
+export const MAX_TWEET_VIDEO_MS = 140_000;
+
+const resourcesDir = (root?: string): string => worldPaths(SERVICE, root).resources;
+const blobKey = (sha256: string): string => join('blobs', 'sha256', sha256.slice(0, 2), sha256);
+const recordKey = (id: string): string => join('media', `${safeId(id)}.json`);
+const segmentKey = (id: string, index: number): string => join('media-segments', safeId(id), String(index).padStart(4, '0'));
+const typeKey = (sha256: string): string => join('blob-types', `${sha256}.json`);
+
+
+/** The direct children under `relative` across the chain, nearest branch first per name. */
+async function listAcross(relative: string, root?: string): Promise<Map<string, string>> {
+  const found = new Map<string, string>();
+  for (const dir of resourceChain(SERVICE, root)) {
+    const prefix = `${join(dir, relative)}/`;
+    for (const key of await getActiveBlobStore().list(prefix)) {
+      if (!key.startsWith(prefix)) continue;
+      const name = key.slice(prefix.length);
+      if (name.includes('/') || found.has(name)) continue;
+      found.set(name, key);
+    }
+  }
+  return found;
+}
+
+function safeId(id: string): string {
+  if (!/^\d{1,19}$/.test(id)) throw new Error(`invalid X media id for storage: ${JSON.stringify(id)}`);
+  return id;
+}
+
+/** Store bytes content-addressed; a re-upload of identical content is a no-op write. The MIME
+ *  type the upload was read as rides beside them, so the bytes routes answer with the type the
+ *  twin decided, never one a URL's extension claims. */
+export async function putXBlob(bytes: Uint8Array, contentType: string, root?: string): Promise<{ sha256: string; size: number }> {
+  const sha256 = blobDigest(bytes);
+  const key = join(resourcesDir(root), blobKey(sha256));
+  if (!(await getActiveBlobStore().exists(key))) await getActiveBlobStore().put(key, bytes);
+  await getActiveBlobStore().put(join(resourcesDir(root), typeKey(sha256)), new TextEncoder().encode(JSON.stringify({ content_type: contentType })));
+  return { sha256, size: bytes.length };
+}
+
+/** The MIME type stored bytes were uploaded as (this branch, then its ancestors). */
+export async function readXBlobType(sha256: string, root?: string): Promise<string | undefined> {
+  if (!/^[0-9a-f]{64}$/.test(sha256)) return undefined;
+  try {
+    const stored = await readResourceBlob(SERVICE, typeKey(sha256), root);
+    const type = stored === null ? undefined : (JSON.parse(new TextDecoder().decode(stored)) as { content_type?: unknown }).content_type;
+    return typeof type === 'string' ? type : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Stored bytes by digest (this branch, then its ancestors); null when absent or malformed. */
+export async function readXBlob(sha256: string, root?: string): Promise<Uint8Array | null> {
+  if (!/^[0-9a-f]{64}$/.test(sha256)) return null;
+  return await readResourceBlob(SERVICE, blobKey(sha256), root);
+}
+
+export async function writeMediaRecord(record: XMediaRecord, root?: string): Promise<void> {
+  await getActiveBlobStore().put(join(resourcesDir(root), recordKey(record.id)), new TextEncoder().encode(JSON.stringify(record)));
+}
+
+export async function readMediaRecord(id: string, root?: string): Promise<XMediaRecord | undefined> {
+  if (!/^\d{1,19}$/.test(id)) return undefined;
+  try {
+    const stored = await readResourceBlob(SERVICE, recordKey(id), root);
+    if (stored === null) return undefined;
+    const parsed = JSON.parse(new TextDecoder().decode(stored)) as XMediaRecord;
+    return typeof parsed.id === 'string' ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Every media id this branch or an ancestor has minted — so a new media id (and a new post id)
+ *  steps past them all. */
+export async function listMediaIds(root?: string): Promise<string[]> {
+  return [...(await listAcross('media', root)).keys()]
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => name.slice(0, -'.json'.length))
+    .filter((id) => /^\d+$/.test(id));
+}
+
+/** One APPEND segment, stored under its index (a retried index overwrites, as at X). */
+export async function putSegment(id: string, index: number, bytes: Uint8Array, root?: string): Promise<void> {
+  await getActiveBlobStore().put(join(resourcesDir(root), segmentKey(id, index)), bytes);
+}
+
+/** Every segment of an upload, in index order, across the branch chain (the nearest copy of an
+ *  index wins, as a retried APPEND overwrites at X). */
+export async function readSegments(id: string, root?: string): Promise<Uint8Array[]> {
+  const found = await listAcross(join('media-segments', safeId(id)), root);
+  const keys = [...found.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, key]) => key);
+  const out: Uint8Array[] = [];
+  for (const key of keys) {
+    const bytes = await getActiveBlobStore().get(key);
+    if (bytes !== null) out.push(bytes);
+  }
+  return out;
+}
+
+export async function clearSegments(id: string, root?: string): Promise<void> {
+  const prefix = `${join(resourcesDir(root), 'media-segments', safeId(id))}/`;
+  for (const key of await getActiveBlobStore().list(prefix)) {
+    try { await getActiveBlobStore().remove(key); } catch { /* already gone */ }
+  }
+}
+
+// ── what the bytes are ──────────────────────────────────────────────────────────────────────
+// X decides an image's type and size from the bytes it received, not from what the client said.
+// The twin does the same: the four still-image formats X accepts, read from their headers.
+
+export type ImageInfo = { mediaType: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp'; width: number; height: number };
+
+export function sniffImage(bytes: Uint8Array): ImageInfo | undefined {
+  const b = bytes;
+  const u16be = (i: number) => (b[i]! << 8) | b[i + 1]!;
+  const u16le = (i: number) => b[i]! | (b[i + 1]! << 8);
+  const u24le = (i: number) => b[i]! | (b[i + 1]! << 8) | (b[i + 2]! << 16);
+  const u32be = (i: number) => ((b[i]! << 24) >>> 0) + (b[i + 1]! << 16) + (b[i + 2]! << 8) + b[i + 3]!;
+  if (b.length >= 24 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) {
+    return { mediaType: 'image/png', width: u32be(16), height: u32be(20) };
+  }
+  if (b.length >= 10 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38) {
+    return { mediaType: 'image/gif', width: u16le(6), height: u16le(8) };
+  }
+  if (b.length >= 4 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) {
+    // walk the marker segments to the first start-of-frame (SOF0..SOF15 except DHT/JPG/DAC)
+    let i = 2;
+    while (i + 9 < b.length) {
+      if (b[i] !== 0xff) { i += 1; continue; }
+      const marker = b[i + 1]!;
+      if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) { i += 2; continue; }
+      const length = u16be(i + 2);
+      if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return { mediaType: 'image/jpeg', height: u16be(i + 5), width: u16be(i + 7) };
+      }
+      i += 2 + length;
+    }
+    return undefined;
+  }
+  if (b.length >= 30 && String.fromCharCode(...b.slice(0, 4)) === 'RIFF' && String.fromCharCode(...b.slice(8, 12)) === 'WEBP') {
+    const chunk = String.fromCharCode(...b.slice(12, 16));
+    if (chunk === 'VP8 ') return { mediaType: 'image/webp', width: u16le(26) & 0x3fff, height: u16le(28) & 0x3fff };
+    if (chunk === 'VP8L') {
+      const bits = b[21]! | (b[22]! << 8) | (b[23]! << 16) | (b[24]! << 24);
+      return { mediaType: 'image/webp', width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+    }
+    if (chunk === 'VP8X') return { mediaType: 'image/webp', width: u24le(24) + 1, height: u24le(27) + 1 };
+  }
+  return undefined;
+}
+
+export type VideoInfo = { mediaType: 'video/mp4'; width: number; height: number; durationMs: number };
+
+/**
+ * An MP4 (ISO BMFF) read from its boxes: `ftyp` first, then `moov` (anywhere — ffmpeg writes it
+ * after `mdat` unless told to fast-start) holding `mvhd` (timescale + duration) and one `trak` per
+ * stream whose `tkhd` carries the presented width/height (16.16 fixed point); the video track is
+ * the one with a non-zero size. Nothing is decoded — the codec is the browser's business.
+ */
+export function sniffVideo(bytes: Uint8Array): VideoInfo | undefined {
+  const b = bytes;
+  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  const type = (at: number) => String.fromCharCode(b[at + 4]!, b[at + 5]!, b[at + 6]!, b[at + 7]!);
+  /** The child boxes of [start, end): [type, payloadStart, boxEnd]. */
+  const boxes = (start: number, end: number): Array<[string, number, number]> => {
+    const out: Array<[string, number, number]> = [];
+    let at = start;
+    while (at + 8 <= end) {
+      let size = view.getUint32(at);
+      let header = 8;
+      if (size === 1) {
+        if (at + 16 > end) break;
+        size = Number(view.getBigUint64(at + 8));
+        header = 16;
+      } else if (size === 0) size = end - at;
+      if (size < header || at + size > end) break;
+      out.push([type(at), at + header, at + size]);
+      at += size;
+    }
+    return out;
+  };
+  const top = boxes(0, b.length);
+  if (top[0]?.[0] !== 'ftyp') return undefined;
+  const moov = top.find(([t]) => t === 'moov');
+  if (!moov) return undefined;
+  let durationMs: number | undefined;
+  let width = 0;
+  let height = 0;
+  for (const [t, start, end] of boxes(moov[1], moov[2])) {
+    if (t === 'mvhd' && end - start >= 32) {
+      const version = b[start]!;
+      const timescale = version === 1 ? view.getUint32(start + 20) : view.getUint32(start + 12);
+      const duration = version === 1 ? Number(view.getBigUint64(start + 24)) : view.getUint32(start + 16);
+      if (timescale > 0) durationMs = Math.round((duration * 1000) / timescale);
+    }
+    if (t === 'trak') {
+      const tkhd = boxes(start, end).find(([k]) => k === 'tkhd');
+      if (!tkhd) continue;
+      const version = b[tkhd[1]]!;
+      const at = tkhd[1] + (version === 1 ? 88 : 76);
+      if (at + 8 > tkhd[2]) continue;
+      const w = view.getUint32(at) >>> 16;
+      const h = view.getUint32(at + 4) >>> 16;
+      if (w > 0 && h > 0 && width === 0) { width = w; height = h; }
+    }
+  }
+  if (durationMs === undefined || width === 0) return undefined;
+  return { mediaType: 'video/mp4', width, height, durationMs };
+}
+
+/**
+ * The video's preview image. X's is a frame its transcoder cut; the twin decodes nothing (the codec
+ * is the browser's), so it serves a STAND-IN at the video's own size and aspect — a dark frame with
+ * X's play glyph — and says so here. `x.media.video_poster_frame` is the todo for a real frame.
+ */
+export function videoPosterSvg(width: number, height: number): string {
+  const w = width > 0 ? width : 1280;
+  const h = height > 0 ? height : 720;
+  const r = Math.round(Math.min(w, h) * 0.09);
+  const cx = w / 2;
+  const cy = h / 2;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}"><rect width="${w}" height="${h}" fill="#16181c"/>`
+    + `<circle cx="${cx}" cy="${cy}" r="${r}" fill="#1d9bf0"/><path d="M${cx - r * 0.3} ${cy - r * 0.45}L${cx + r * 0.5} ${cy}L${cx - r * 0.3} ${cy + r * 0.45}Z" fill="#fff"/></svg>`;
+}
+
+/** The file extension pbs.twimg.com serves an image under. */
+export function mediaExtension(mediaType: string): string {
+  if (mediaType === 'image/jpeg') return 'jpg';
+  if (mediaType === 'image/png') return 'png';
+  if (mediaType === 'image/gif') return 'gif';
+  if (mediaType === 'image/webp') return 'webp';
+  return 'bin';
+}
+

package/src/x-mirror-ui.ts

@@ -0,0 +1,263 @@
+// X MIRROR UI — x.com's own view of the twin's state: the org account's profile, its timeline,
+// a single post's page, its mentions, and the compose box. A React/TSX app bundled by Bun that
+// renders by consuming the twin's OWN X API v2 on the same origin (GET /2/users/by/username/:u,
+// /2/users/:id/tweets, /2/users/:id/timelines/reverse_chronological, /2/users/:id/mentions,
+// /2/tweets/:id) and writes through POST /2/tweets — the same routes any X client uses — so the
+// screen is data-coupled to real twin state. Archetype A (passthrough), transcribed from the
+// Discord mirror: there is exactly ONE serving code path, so API<->UI parity cannot drift.
+//
+// SIGN-IN. x.com's own login (handle, then password) with the password leg replaced by the
+// bearer the twin issued through /_twin/tokens: the mirror is a client like any other and
+// presents a registered token rather than bypassing the auth gate. Both are kept in the TAB'S
+// sessionStorage; the mirror keeps no other state.
+//
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's
+// own fetch adapter as its API backend and reads every byte of state back over the wire.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createXTwinFetch } from './x-server.ts';
+
+const CLIENT_ENTRY = () => new URL('../client/x-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects a top-level relative import.meta.url
+const CLIENT_CSS = () => new URL('../client/x-mirror.css', import.meta.url).pathname;    // lazy: same reason
+
+// ---------------------------------------------------------------------------
+// Pure, dependency-free render/format helpers (importable by the React client; Bun tree-shakes
+// the server-only exports out of the browser bundle). Keep free of any @volter/world-core / Bun /
+// handler usage — a capability verify renders the mirror's OWN functions over twin state.
+// ---------------------------------------------------------------------------
+
+export type XRow = Record<string, any>;
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const LONG_MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+
+type Parts = { year: number; month: number; day: number; hour: number; minute: number };
+
+/** A wall-clock reading of an instant in a time zone. x.com shows the VIEWER'S local time, so the
+ *  browser passes none (its own zone); a verify passes 'UTC' so the output is a pure function. */
+function wallClock(ms: number, timeZone?: string): Parts {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    ...(timeZone ? { timeZone } : {}), year: 'numeric', month: 'numeric', day: 'numeric', hour: 'numeric', minute: 'numeric', hourCycle: 'h23',
+  }).formatToParts(new Date(ms));
+  const get = (type: string) => Number(parts.find((p) => p.type === type)?.value ?? 0);
+  return { year: get('year'), month: get('month') - 1, day: get('day'), hour: get('hour') % 24, minute: get('minute') };
+}
+
+/** x.com's timeline timestamp: "now"/"42s", "5m", "3h" inside a day, "Sep 26" inside the year,
+ *  "Sep 26, 2025" before it. `nowMs` is passed in, never read. */
+export function relativeTime(iso: unknown, nowMs: number, timeZone?: string): string {
+  if (typeof iso !== 'string') return '';
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return '';
+  const s = Math.max(0, Math.floor((nowMs - t) / 1000));
+  if (s < 60) return s < 5 ? 'now' : `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86_400) return `${Math.floor(s / 3600)}h`;
+  const d = wallClock(t, timeZone);
+  const day = `${MONTHS[d.month]} ${d.day}`;
+  return d.year === wallClock(nowMs, timeZone).year ? day : `${day}, ${d.year}`;
+}
+
+/** The single-post page's stamp: "8:05 PM · Sep 26, 2026", in the viewer's zone. */
+export function fullTimestamp(iso: unknown, timeZone?: string): string {
+  if (typeof iso !== 'string') return '';
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return '';
+  const d = wallClock(t, timeZone);
+  const hour12 = d.hour % 12 === 0 ? 12 : d.hour % 12;
+  return `${hour12}:${String(d.minute).padStart(2, '0')} ${d.hour < 12 ? 'AM' : 'PM'} · ${MONTHS[d.month]} ${d.day}, ${d.year}`;
+}
+
+/** The profile header's "Joined September 2026". */
+export function joinedLabel(iso: unknown, timeZone?: string): string {
+  if (typeof iso !== 'string') return '';
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return '';
+  const d = wallClock(t, timeZone);
+  return `Joined ${LONG_MONTHS[d.month]} ${d.year}`;
+}
+
+/** The replies to one post among rows the viewer can read, oldest first as x.com lists them. */
+export function repliesTo(postId: string, rows: XRow[]): XRow[] {
+  const seen = new Set<string>();
+  const out: XRow[] = [];
+  for (const row of rows) {
+    const id = String(row.id);
+    if (seen.has(id) || referencedId(row, 'replied_to') !== postId) continue;
+    seen.add(id);
+    out.push(row);
+  }
+  return out.sort((a, b) => (BigInt(String(a.id)) < BigInt(String(b.id)) ? -1 : 1));
+}
+
+export type TextSegment = { kind: 'text' | 'mention' | 'hashtag' | 'url'; value: string };
+
+/** A post's text split the way x.com colours it: @mentions, #hashtags and links are entities,
+ *  everything else is plain text. Pure; the twin does not model `entities`, so the mirror reads
+ *  them out of the text exactly as the twin's own mentions timeline does. */
+export function textSegments(text: unknown): TextSegment[] {
+  const source = typeof text === 'string' ? text : '';
+  const out: TextSegment[] = [];
+  // x.com links a bare domain too (`volter.ai/changelog`): a generic TLD always, a country code only with
+  // `www.` or a path (so `install.sh` stays text); an @ inside a URL stays part of it. The TLDs are the
+  // common ones, not X's full list.
+  const re = /(https?:\/\/[^\s]+|\b(?:www\.)?(?:[A-Za-z0-9-]+\.)+(?:com|org|net|dev|app|xyz)\b(?:\/[^\s]*)?|\b(?:www\.(?:[A-Za-z0-9-]+\.)+(?:ai|io|co|sh|me|so|gg|tv)\b(?:\/[^\s]*)?|(?:[A-Za-z0-9-]+\.)+(?:ai|io|co|sh|me|so|gg|tv)\/[^\s]*))|(@[A-Za-z0-9_]{1,15})|(#[\p{L}\p{N}_]+)/gu;
+  let last = 0;
+  for (const m of source.matchAll(re)) {
+    const at = m.index ?? 0;
+    // an @ or # glued to a preceding word character is not an entity at X (e.g. an email address)
+    if ((m[2] || m[3]) && at > 0 && /[A-Za-z0-9_]/.test(source[at - 1]!)) continue;
+    if (at > last) out.push({ kind: 'text', value: source.slice(last, at) });
+    // closing punctuation after a URL is the sentence's, not the link's
+    let value = m[1] ? m[0].replace(/[.,;:!?\]'"]+$/, '') : m[0];
+    // a `)` closes the URL's own `(` (wiki/Foo_(bar)) or else the sentence's
+    while (m[1] && value.endsWith(')') && (value.match(/\(/g)?.length ?? 0) < (value.match(/\)/g)?.length ?? 0)) value = value.slice(0, -1).replace(/[.,;:!?\]'"]+$/, '');
+    out.push({ kind: m[1] ? 'url' : m[2] ? 'mention' : 'hashtag', value });
+    last = at + value.length;
+  }
+  if (last < source.length) out.push({ kind: 'text', value: source.slice(last) });
+  return out;
+}
+
+/** A link's target: a bare domain is https. */
+export function linkHref(url: string): string { return /^https?:\/\//i.test(url) ? url : `https://${url}`; }
+
+/** The link text x.com shows for a URL: scheme stripped, long paths cut with an ellipsis. */
+export function displayUrl(url: string): string {
+  const bare = url.replace(/^https?:\/\/(www\.)?/, '');
+  return bare.length > 30 ? `${bare.slice(0, 29)}…` : bare;
+}
+
+/** The avatar placeholder's colour, a pure function of the handle (the twin serves no image). */
+export function avatarHue(handle: unknown): number {
+  const s = String(handle ?? '').toLowerCase();
+  let h = 0;
+  for (let i = 0; i < s.length; i += 1) h = (h * 31 + s.charCodeAt(i)) % 360;
+  return h;
+}
+
+/** The placeholder's letter: the display name's first character, else the handle's. */
+export function avatarInitial(user: XRow | undefined): string {
+  const source = String(user?.name ?? user?.username ?? '?').trim();
+  return (Array.from(source)[0] ?? '?').toUpperCase();
+}
+
+/** Users from a response's `includes`, by id. */
+export function usersById(includes: unknown): Map<string, XRow> {
+  const out = new Map<string, XRow>();
+  const users = (includes as XRow | undefined)?.users;
+  if (Array.isArray(users)) for (const u of users) out.set(String(u.id), u);
+  return out;
+}
+
+/** Posts from a response's `includes`, by id (the quoted / replied-to posts). */
+export function tweetsById(includes: unknown): Map<string, XRow> {
+  const out = new Map<string, XRow>();
+  const tweets = (includes as XRow | undefined)?.tweets;
+  if (Array.isArray(tweets)) for (const t of tweets) out.set(String(t.id), t);
+  return out;
+}
+
+/** The id a post references with the given type ('replied_to' | 'quoted'), if any. */
+export function referencedId(post: XRow, type: 'replied_to' | 'quoted'): string | undefined {
+  const refs = post.referenced_tweets;
+  if (!Array.isArray(refs)) return undefined;
+  const hit = refs.find((r: XRow) => r?.type === type);
+  return hit ? String(hit.id) : undefined;
+}
+
+/** Media from a response's `includes`, by media key. */
+export function mediaByKey(includes: unknown): Map<string, XRow> {
+  const out = new Map<string, XRow>();
+  const media = (includes as XRow | undefined)?.media;
+  if (Array.isArray(media)) for (const m of media) out.set(String(m.media_key), m);
+  return out;
+}
+
+/** The media a post carries, in its own `attachments.media_keys` order, as the read expanded them. */
+export function postMedia(post: XRow, media: Map<string, XRow>): XRow[] {
+  const keys = post.attachments?.media_keys;
+  if (!Array.isArray(keys)) return [];
+  return keys.map((k: unknown) => media.get(String(k))).filter((m): m is XRow => m !== undefined);
+}
+
+/** The playable file of a video: its MP4 variant with the highest bit rate. */
+export function videoSource(media: XRow): string | undefined {
+  const variants = Array.isArray(media.variants) ? (media.variants as XRow[]) : [];
+  const mp4 = variants.filter((v) => v.content_type === 'video/mp4' && typeof v.url === 'string');
+  mp4.sort((a, b) => Number(b.bit_rate ?? 0) - Number(a.bit_rate ?? 0));
+  return mp4[0]?.url as string | undefined;
+}
+
+/** "0:03" — the duration badge x.com prints on a video. */
+export function durationLabel(ms: unknown): string {
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) return '';
+  const total = Math.round(ms / 1000);
+  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
+}
+
+/** The query every post-rendering read asks for: the fields and expansions a post row draws. */
+export const POST_READ_QUERY = 'tweet.fields=created_at,author_id,conversation_id,in_reply_to_user_id,referenced_tweets'
+  + '&expansions=author_id,in_reply_to_user_id,referenced_tweets.id,referenced_tweets.id.author_id,attachments.media_keys'
+  + '&user.fields=verified,protected'
+  + '&media.fields=url,type,width,height,duration_ms,preview_image_url,variants';
+
+/** The query the profile header asks for. */
+export const PROFILE_READ_QUERY = 'user.fields=created_at,description,location,url,verified,protected,most_recent_tweet_id';
+
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<base href="/"><title>X</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+
+let clientBundle: Promise<string> | null = null;
+/** Build the React/TSX mirror client to browser JS (Bun bundles TSX); memoized at module scope,
+ *  which is why a pack on its own does exactly one `Bun.build`. */
+export function buildXMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = bundleClient(CLIENT_ENTRY())
+      .catch((error) => { clientBundle = null; throw error; });
+  }
+  return clientBundle;
+}
+
+/** Serve the X mirror UI (React app) + its backing X API v2 on one origin. */
+export async function createXMirrorServer(options: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; url: string; stop: () => void }> {
+  const twin = createXTwinFetch(options);
+  const server = await serveHttp({
+    // LOOPBACK-SPECIFIC bind, as the Discord mirror: a wildcard bind on `port: 0` can be shadowed
+    // by a long-running app already listening on 127.0.0.1 at the same port.
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+        try { return new Response(await buildXMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } }); }
+        catch (error) { return new Response(String(error), { status: 500 }); }
+      }
+      if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+        return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+        return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+      }
+      // Everything else -> the twin's OWN FETCH ADAPTER: the React client fetches X's real v2
+      // paths, and the adapter is the same closure `createXTwinServer` serves.
+      return twin(request);
+    },
+  });
+  const port = server.port ?? options.port ?? 0;
+  return { port, url: `http://127.0.0.1:${port}`, stop: () => server.stop(true) };
+}
+
+/** The app-shell HTML (pure). The client itself is the React app. */
+export function xMirrorHtml(): string {
+  return APP_SHELL;
+}
+
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function xMirrorStyles(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}