@volter/twin-x 0.1.0

package/dist/src/x-media.js

@@ -0,0 +1,275 @@
+// 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';
+/** 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) => worldPaths(SERVICE, root).resources;
+const blobKey = (sha256) => join('blobs', 'sha256', sha256.slice(0, 2), sha256);
+const recordKey = (id) => join('media', `${safeId(id)}.json`);
+const segmentKey = (id, index) => join('media-segments', safeId(id), String(index).padStart(4, '0'));
+const typeKey = (sha256) => join('blob-types', `${sha256}.json`);
+/** The direct children under `relative` across the chain, nearest branch first per name. */
+async function listAcross(relative, root) {
+    const found = new Map();
+    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) {
+    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, contentType, root) {
+    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, root) {
+    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)).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, root) {
+    if (!/^[0-9a-f]{64}$/.test(sha256))
+        return null;
+    return await readResourceBlob(SERVICE, blobKey(sha256), root);
+}
+export async function writeMediaRecord(record, root) {
+    await getActiveBlobStore().put(join(resourcesDir(root), recordKey(record.id)), new TextEncoder().encode(JSON.stringify(record)));
+}
+export async function readMediaRecord(id, root) {
+    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));
+        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) {
+    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, index, bytes, root) {
+    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, root) {
+    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 = [];
+    for (const key of keys) {
+        const bytes = await getActiveBlobStore().get(key);
+        if (bytes !== null)
+            out.push(bytes);
+    }
+    return out;
+}
+export async function clearSegments(id, root) {
+    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 */ }
+    }
+}
+export function sniffImage(bytes) {
+    const b = bytes;
+    const u16be = (i) => (b[i] << 8) | b[i + 1];
+    const u16le = (i) => b[i] | (b[i + 1] << 8);
+    const u24le = (i) => b[i] | (b[i + 1] << 8) | (b[i + 2] << 16);
+    const u32be = (i) => ((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;
+}
+/**
+ * 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) {
+    const b = bytes;
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    const type = (at) => 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, end) => {
+        const out = [];
+        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;
+    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, height) {
+    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) {
+    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/dist/src/x-mirror-ui.d.ts

@@ -0,0 +1,61 @@
+export type XRow = Record<string, any>;
+/** 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 declare function relativeTime(iso: unknown, nowMs: number, timeZone?: string): string;
+/** The single-post page's stamp: "8:05 PM · Sep 26, 2026", in the viewer's zone. */
+export declare function fullTimestamp(iso: unknown, timeZone?: string): string;
+/** The profile header's "Joined September 2026". */
+export declare function joinedLabel(iso: unknown, timeZone?: string): string;
+/** The replies to one post among rows the viewer can read, oldest first as x.com lists them. */
+export declare function repliesTo(postId: string, rows: XRow[]): XRow[];
+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 declare function textSegments(text: unknown): TextSegment[];
+/** A link's target: a bare domain is https. */
+export declare function linkHref(url: string): string;
+/** The link text x.com shows for a URL: scheme stripped, long paths cut with an ellipsis. */
+export declare function displayUrl(url: string): string;
+/** The avatar placeholder's colour, a pure function of the handle (the twin serves no image). */
+export declare function avatarHue(handle: unknown): number;
+/** The placeholder's letter: the display name's first character, else the handle's. */
+export declare function avatarInitial(user: XRow | undefined): string;
+/** Users from a response's `includes`, by id. */
+export declare function usersById(includes: unknown): Map<string, XRow>;
+/** Posts from a response's `includes`, by id (the quoted / replied-to posts). */
+export declare function tweetsById(includes: unknown): Map<string, XRow>;
+/** The id a post references with the given type ('replied_to' | 'quoted'), if any. */
+export declare function referencedId(post: XRow, type: 'replied_to' | 'quoted'): string | undefined;
+/** Media from a response's `includes`, by media key. */
+export declare function mediaByKey(includes: unknown): Map<string, XRow>;
+/** The media a post carries, in its own `attachments.media_keys` order, as the read expanded them. */
+export declare function postMedia(post: XRow, media: Map<string, XRow>): XRow[];
+/** The playable file of a video: its MP4 variant with the highest bit rate. */
+export declare function videoSource(media: XRow): string | undefined;
+/** "0:03" — the duration badge x.com prints on a video. */
+export declare function durationLabel(ms: unknown): string;
+/** The query every post-rendering read asks for: the fields and expansions a post row draws. */
+export declare const POST_READ_QUERY: string;
+/** The query the profile header asks for. */
+export declare const PROFILE_READ_QUERY = "user.fields=created_at,description,location,url,verified,protected,most_recent_tweet_id";
+/** 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 declare function buildXMirrorClient(): Promise<string>;
+/** Serve the X mirror UI (React app) + its backing X API v2 on one origin. */
+export declare function createXMirrorServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    url: string;
+    stop: () => void;
+}>;
+/** The app-shell HTML (pure). The client itself is the React app. */
+export declare function xMirrorHtml(): string;
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export declare function xMirrorStyles(): Promise<string>;

package/dist/src/x-mirror-ui.js

@@ -0,0 +1,253 @@
+// 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.js";
+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
+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'];
+/** 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, timeZone) {
+    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) => 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, nowMs, timeZone) {
+    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, timeZone) {
+    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, timeZone) {
+    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, rows) {
+    const seen = new Set();
+    const out = [];
+    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));
+}
+/** 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) {
+    const source = typeof text === 'string' ? text : '';
+    const out = [];
+    // 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) { 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) {
+    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) {
+    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) {
+    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) {
+    const out = new Map();
+    const users = includes?.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) {
+    const out = new Map();
+    const tweets = includes?.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, type) {
+    const refs = post.referenced_tweets;
+    if (!Array.isArray(refs))
+        return undefined;
+    const hit = refs.find((r) => r?.type === type);
+    return hit ? String(hit.id) : undefined;
+}
+/** Media from a response's `includes`, by media key. */
+export function mediaByKey(includes) {
+    const out = new Map();
+    const media = includes?.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, media) {
+    const keys = post.attachments?.media_keys;
+    if (!Array.isArray(keys))
+        return [];
+    return keys.map((k) => media.get(String(k))).filter((m) => m !== undefined);
+}
+/** The playable file of a video: its MP4 variant with the highest bit rate. */
+export function videoSource(media) {
+    const variants = Array.isArray(media.variants) ? media.variants : [];
+    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;
+}
+/** "0:03" — the duration badge x.com prints on a video. */
+export function durationLabel(ms) {
+    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 = 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() {
+    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) {
+    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() {
+    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() {
+    return readFile(CLIENT_CSS(), 'utf8');
+}

package/dist/src/x-problems.d.ts

@@ -0,0 +1,38 @@
+export type XResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+/** The generic auth problem X answers a bad/absent/expired bearer with on /2 resources. */
+export declare function unauthorizedProblem(): XResponse;
+/** A user token whose scope set does not cover the endpoint. Wording: `x.errors.scope_wording`. */
+export declare function forbiddenProblem(detail: string): XResponse;
+/** An unmodelled /2 route fails like the vendor: 404 problem, never a fake success. */
+export declare function notFoundProblem(): XResponse;
+/**
+ * A named resource the request addressed does not exist — X's `resource-not-found` problem,
+ * which carries the offending value/resource_type rather than the bare about:blank form.
+ * Wording pinned by `x.errors.resource_not_found_wording`.
+ */
+export declare function resourceNotFoundError(value: string, resourceType: 'tweet' | 'user', parameter: string): Record<string, unknown>;
+export declare function resourceNotFoundProblem(value: string, resourceType: 'tweet' | 'user', parameter: string): XResponse;
+/**
+ * THE LOOKUP ENVELOPE, and why its status differs from the refusal above. X's *lookup* endpoints
+ * (`GET /2/tweets`, `GET /2/tweets/:id`) answer PARTIALLY: a request for five ids where two are
+ * missing has to return the three that exist AND say what happened to the other two, so the
+ * missing ones ride in a sibling `errors` array under HTTP 200 rather than turning the whole
+ * request into a 404. The bulk route FORCES that model — there is no other way to express a
+ * partial result — and X applies the same envelope to the single-id route. What matters for this
+ * twin, and what its verifies assert, is the half that is not a status: a `data` entry is NEVER
+ * fabricated for an id nobody created; the id comes back inside `errors`, by name.
+ *
+ * The exact `detail`/`title` WORDING is unpinned by this build, same boundary as every other
+ * envelope here (`x.errors.resource_not_found_wording`).
+ */
+export declare function lookupResult(data: unknown, errors: Array<Record<string, unknown>>, includes?: Record<string, unknown>): XResponse;
+/** The invalid-parameter envelope (OpenAPI InvalidRequestProblem + the wire's `errors` array). */
+export declare function invalidRequestProblem(parameters: Record<string, string[]>, message: string): XResponse;
+/** HTTP 429, legacy code 88 — the documented pair (docs.x.com fundamentals/rate-limits). */
+export declare function rateLimitExceeded(headers: Record<string, string>): XResponse;
+/** A write attempted against a read-only twin. Not a vendor shape — the kernel's own refusal. */
+export declare function readOnlyRefusal(): XResponse;