@volter/twin-x 0.1.0

package/dist/client/x-mirror.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode } from 'react';
+import { type XRow } from '../src/x-mirror-ui.js';
+export declare function Avatar({ user, size }: {
+    user: XRow | undefined;
+    size?: number;
+}): import("react").JSX.Element;
+export declare function PostText({ text, big }: {
+    text: unknown;
+    big?: boolean;
+}): import("react").JSX.Element;
+/**
+ * A post's media as x.com draws it: one rounded, hairline-bordered block under the text. One image
+ * keeps its own aspect (capped in height); two to four tile a 2-column grid; a video is the player —
+ * the file's own first frame until it plays, controls, and the duration badge. Clicks inside the
+ * block stay inside it, so playing a video does not open the post.
+ */
+export declare function MediaBlock({ media, big }: {
+    media: XRow[];
+    big?: boolean;
+}): import("react").JSX.Element | null;
+/** One post as x.com's timeline draws it: avatar, name, @handle · time, text, the action row. */
+export declare function PostRow({ post, users, tweets, media, nowMs }: {
+    post: XRow;
+    users: Map<string, XRow>;
+    tweets: Map<string, XRow>;
+    media?: Map<string, XRow>;
+    nowMs: number;
+}): import("react").JSX.Element;
+type Page = {
+    rows: XRow[];
+    users: Map<string, XRow>;
+    tweets: Map<string, XRow>;
+    media: Map<string, XRow>;
+    next?: string;
+};
+export declare function Timeline({ page, nowMs, empty, filter }: {
+    page: Page;
+    nowMs: number;
+    empty: ReactNode;
+    filter?: (p: XRow) => boolean;
+}): import("react").JSX.Element | null;
+export declare function ProfileHeader({ user }: {
+    user: XRow;
+}): import("react").JSX.Element;
+export {};

package/dist/client/x-mirror.js

@@ -0,0 +1,417 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// X mirror — React/TSX client. x.com's own view of the twin's state: sign in as the org account,
+// read its profile, its posts, a single post, its mentions and its home timeline, and compose a
+// post. Every read is the twin's OWN X API v2 on the same origin; the composer writes through
+// POST /2/tweets — the same path the handler serves to any SDK. Nothing is kept but the signed-in
+// handle and bearer, in the tab's sessionStorage.
+import { createRoot } from 'react-dom/client';
+import { useCallback, useEffect, useState } from 'react';
+import { avatarHue, avatarInitial, displayUrl, durationLabel, linkHref, fullTimestamp, joinedLabel, mediaByKey, POST_READ_QUERY, postMedia, PROFILE_READ_QUERY, referencedId, relativeTime, repliesTo, textSegments, tweetsById, usersById, videoSource, } from "../src/x-mirror-ui.js";
+// WHERE THIS MIRROR LIVES. Served at a vendor root the base is '' (fetches are root-relative);
+// served under a path prefix with a <base> tag every read and write resolves inside that prefix.
+const WIRE_BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
+const SESSION_HANDLE = 'x-mirror.handle';
+const SESSION_TOKEN = 'x-mirror.token';
+function readSession() {
+    if (typeof sessionStorage === 'undefined')
+        return null;
+    const handle = sessionStorage.getItem(SESSION_HANDLE);
+    const token = sessionStorage.getItem(SESSION_TOKEN);
+    return handle && token ? { handle, token } : null;
+}
+async function wire(token, path, init) {
+    const res = await fetch(`${WIRE_BASE}${path}`, {
+        method: init?.method ?? 'GET',
+        headers: { authorization: `Bearer ${token}`, ...(init?.body !== undefined ? { 'content-type': 'application/json' } : {}) },
+        ...(init?.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+    });
+    let body = {};
+    try {
+        body = await res.json();
+    }
+    catch {
+        body = {};
+    }
+    return { status: res.status, body };
+}
+/** X's problem envelope, as one sentence for the screen. */
+function problemText(w) {
+    const b = w.body;
+    const first = Array.isArray(b.errors) ? b.errors[0] : undefined;
+    return String(first?.message ?? first?.detail ?? b.detail ?? b.title ?? `HTTP ${w.status}`);
+}
+function parseRoute(hash) {
+    const parts = hash.replace(/^#\/?/, '').split('/').filter(Boolean);
+    if (parts.length === 0)
+        return null;
+    if (parts[0] === 'i' && parts[1] === 'flow' && parts[2] === 'login')
+        return { page: 'login' };
+    if (parts[0] === 'home')
+        return { page: 'home' };
+    if (parts[0] === 'notifications')
+        return { page: 'notifications' };
+    if (parts[1] === 'status' && parts[2])
+        return { page: 'status', handle: parts[0], id: parts[2] };
+    return { page: 'profile', handle: parts[0], tab: parts[1] === 'with_replies' ? 'replies' : 'posts' };
+}
+const go = (path) => { location.hash = `#/${path}`; };
+// ── icons (vendor mirror: x.com's look, drawn here) ─────────────────────────────────────────────
+function Icon({ d, fill = false, size = 18, className }) {
+    return (_jsx("svg", { className: className, viewBox: "0 0 24 24", width: size, height: size, "aria-hidden": "true", fill: fill ? 'currentColor' : 'none', stroke: fill ? 'none' : 'currentColor', strokeWidth: 1.8, strokeLinecap: "round", strokeLinejoin: "round", children: d.map((p) => _jsx("path", { d: p }, p)) }));
+}
+const X_LOGO = ['M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z'];
+const VERIFIED = ['M22.25 12c0-1.43-.88-2.67-2.19-3.34.46-1.39.2-2.9-.81-3.91s-2.52-1.27-3.91-.81c-.66-1.31-1.91-2.19-3.34-2.19s-2.67.88-3.33 2.19c-1.4-.46-2.91-.2-3.92.81s-1.26 2.52-.8 3.91c-1.31.67-2.2 1.91-2.2 3.34s.89 2.67 2.2 3.34c-.46 1.39-.21 2.9.8 3.91s2.52 1.26 3.91.81c.67 1.31 1.91 2.19 3.34 2.19s2.68-.88 3.34-2.19c1.39.45 2.9.2 3.91-.81s1.27-2.52.81-3.91c1.31-.67 2.19-1.91 2.19-3.34zm-11.71 4.2L6.8 12.46l1.41-1.42 2.26 2.26 4.8-5.23 1.47 1.36-6.2 6.77z'];
+const I_REPLY = ['M7.9 20A9 9 0 1 0 4 16.1L2 22Z'];
+const I_REPOST = ['m2 9 3-3 3 3', 'M13 18H7a2 2 0 0 1-2-2V6', 'm22 15-3 3-3-3', 'M11 6h6a2 2 0 0 1 2 2v10'];
+const I_LIKE = ['M19 14c1.49-1.46 3-3.21 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.76 0-3 .5-4.5 2-1.5-1.5-2.74-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4.05 3 5.5l7 7Z'];
+const I_VIEWS = ['M18 20V10', 'M12 20V4', 'M6 20v-6'];
+const I_BOOKMARK = ['m19 21-7-4-7 4V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2v16z'];
+const I_SHARE = ['M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4', 'M17 8l-5-5-5 5', 'M12 3v12'];
+const I_HOME = ['M3 9.5 12 3l9 6.5V20a1 1 0 0 1-1 1h-5v-6H9v6H4a1 1 0 0 1-1-1z'];
+const I_BELL = ['M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9', 'M10.3 21a1.94 1.94 0 0 0 3.4 0'];
+const I_USER = ['M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2', 'M12 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8z'];
+const I_BACK = ['m12 19-7-7 7-7', 'M19 12H5'];
+const I_CAL = ['M5 4h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2z', 'M16 2v4', 'M8 2v4', 'M3 10h18'];
+const I_PIN = ['M20 10c0 6-8 12-8 12s-8-6-8-12a8 8 0 0 1 16 0Z', 'M12 13a3 3 0 1 0 0-6 3 3 0 0 0 0 6z'];
+const I_LINK = ['M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71', 'M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71'];
+const I_LOCK = ['M5 11h14a2 2 0 0 1 2 2v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-7a2 2 0 0 1 2-2z', 'M7 11V7a5 5 0 0 1 10 0v4'];
+// ── pieces ───────────────────────────────────────────────────────────────────────────────────────
+export function Avatar({ user, size = 40 }) {
+    const hue = avatarHue(user?.username);
+    return (_jsx("div", { className: "avatar", style: { width: size, height: size, fontSize: size * 0.42, background: `hsl(${hue} 45% 38%)` }, "aria-hidden": "true", children: avatarInitial(user) }));
+}
+export function PostText({ text, big = false }) {
+    return (_jsx("div", { className: big ? 'post-text post-text-big' : 'post-text', children: textSegments(text).map((s, i) => {
+            if (s.kind === 'text')
+                return _jsx("span", { children: s.value }, i);
+            if (s.kind === 'url')
+                return _jsx("a", { className: "entity", href: linkHref(s.value), target: "_blank", rel: "noreferrer", onClick: (e) => e.stopPropagation(), children: displayUrl(s.value) }, i);
+            if (s.kind === 'mention')
+                return _jsx("a", { className: "entity", href: `#/${s.value.slice(1)}`, onClick: (e) => e.stopPropagation(), children: s.value }, i);
+            return _jsx("span", { className: "entity", children: s.value }, i);
+        }) }));
+}
+function NameLine({ user, children }) {
+    return (_jsxs("div", { className: "name-line", children: [_jsx("span", { className: "display-name", children: String(user?.name ?? 'Unknown') }), user?.verified === true ? _jsx(Icon, { d: VERIFIED, fill: true, size: 17, className: "badge" }) : null, user?.protected === true ? _jsx(Icon, { d: I_LOCK, size: 15, className: "lock" }) : null, _jsxs("span", { className: "muted handle", children: ["@", String(user?.username ?? 'unknown')] }), children] }));
+}
+/** The engagement row. The twin models no public_metrics, so the row carries NO counts — an
+ *  empty slot where x.com prints a number, never an invented zero. */
+function ActionRow({ big = false }) {
+    return (_jsxs("div", { className: big ? 'actions actions-big' : 'actions', children: [_jsx("span", { className: "action reply", title: "Reply", children: _jsx(Icon, { d: I_REPLY }) }), _jsx("span", { className: "action repost", title: "Repost", children: _jsx(Icon, { d: I_REPOST }) }), _jsx("span", { className: "action like", title: "Like", children: _jsx(Icon, { d: I_LIKE }) }), _jsx("span", { className: "action views", title: "View post analytics", children: _jsx(Icon, { d: I_VIEWS }) }), _jsxs("span", { className: "action-end", children: [_jsx("span", { className: "action", title: "Bookmark", children: _jsx(Icon, { d: I_BOOKMARK }) }), _jsx("span", { className: "action", title: "Share post", children: _jsx(Icon, { d: I_SHARE }) })] })] }));
+}
+function QuoteCard({ quoted, users, nowMs }) {
+    const author = users.get(String(quoted.author_id));
+    return (_jsxs("div", { className: "quote", onClick: (e) => { e.stopPropagation(); go(`${author?.username ?? 'i'}/status/${quoted.id}`); }, children: [_jsxs("div", { className: "quote-head", children: [_jsx(Avatar, { user: author, size: 20 }), _jsxs(NameLine, { user: author, children: [_jsx("span", { className: "muted", children: "\u00B7" }), _jsx("span", { className: "muted", children: relativeTime(quoted.created_at, nowMs) })] })] }), _jsx(PostText, { text: quoted.text })] }));
+}
+/**
+ * A post's media as x.com draws it: one rounded, hairline-bordered block under the text. One image
+ * keeps its own aspect (capped in height); two to four tile a 2-column grid; a video is the player —
+ * the file's own first frame until it plays, controls, and the duration badge. Clicks inside the
+ * block stay inside it, so playing a video does not open the post.
+ */
+export function MediaBlock({ media, big = false }) {
+    if (media.length === 0)
+        return null;
+    const video = media.find((m) => m.type === 'video');
+    if (video)
+        return _jsx(VideoPlayer, { video: video, big: big });
+    const photos = media.filter((m) => m.type === 'photo' && typeof m.url === 'string').slice(0, 4);
+    if (photos.length === 0)
+        return null;
+    const one = photos.length === 1 ? photos[0] : undefined;
+    return (_jsx("div", { className: `${big ? 'media media-big' : 'media'} media-${photos.length}`, children: photos.map((m) => (_jsx("img", { className: "media-img", src: String(m.url), alt: "Image", loading: "lazy", style: one && Number(m.width) > 0 && Number(m.height) > 0 ? { aspectRatio: `${m.width} / ${m.height}` } : undefined }, String(m.media_key)))) }));
+}
+/** x.com's player before it plays: the still frame, a centred play button and the duration badge;
+ *  once started, the player's own controls. No `poster`: the preview the twin serves is a stand-in,
+ *  so the frame shown is the file's own first frame (`#t=`). */
+function VideoPlayer({ video, big }) {
+    const [started, setStarted] = useState(false);
+    const src = videoSource(video);
+    const ratio = Number(video.width) > 0 && Number(video.height) > 0 ? `${video.width} / ${video.height}` : '16 / 9';
+    const start = (e) => {
+        e.stopPropagation();
+        const el = e.currentTarget.closest('.media')?.querySelector('video');
+        setStarted(true);
+        void el?.play().catch(() => undefined);
+    };
+    return (_jsxs("div", { className: big ? 'media media-big' : 'media', "data-media-key": String(video.media_key), onClick: (e) => e.stopPropagation(), children: [src ? _jsx("video", { className: "media-video", style: { aspectRatio: ratio }, src: `${src}#t=0.001`, controls: started, playsInline: true, preload: "metadata" }) : null, !started && src ? (_jsx("button", { className: "media-play", "aria-label": "Play", onClick: start, children: _jsx("svg", { viewBox: "0 0 24 24", width: "30", height: "30", "aria-hidden": "true", children: _jsx("path", { d: "M8 5v14l11-7z", fill: "currentColor" }) }) })) : null, !started && durationLabel(video.duration_ms) ? _jsx("span", { className: "media-badge", children: durationLabel(video.duration_ms) }) : null] }));
+}
+/** One post as x.com's timeline draws it: avatar, name, @handle · time, text, the action row. */
+export function PostRow({ post, users, tweets, media = new Map(), nowMs }) {
+    const author = users.get(String(post.author_id));
+    const repliedTo = post.in_reply_to_user_id ? users.get(String(post.in_reply_to_user_id)) : undefined;
+    const quotedId = referencedId(post, 'quoted');
+    const quoted = quotedId ? tweets.get(quotedId) : undefined;
+    return (_jsxs("article", { className: "post-row", "data-post-id": String(post.id), onClick: () => go(`${author?.username ?? 'i'}/status/${post.id}`), children: [_jsx(Avatar, { user: author }), _jsxs("div", { className: "post-body", children: [_jsxs(NameLine, { user: author, children: [_jsx("span", { className: "muted", children: "\u00B7" }), _jsx("time", { className: "muted", dateTime: String(post.created_at ?? ''), title: fullTimestamp(post.created_at), children: relativeTime(post.created_at, nowMs) })] }), repliedTo ? _jsxs("div", { className: "muted replying", children: ["Replying to ", _jsxs("span", { className: "entity", children: ["@", String(repliedTo.username)] })] }) : null, post.text ? _jsx(PostText, { text: post.text }) : null, _jsx(MediaBlock, { media: postMedia(post, media) }), quoted ? _jsx(QuoteCard, { quoted: quoted, users: users, nowMs: nowMs }) : null, _jsx(ActionRow, {})] })] }));
+}
+const EMPTY_PAGE = { rows: [], users: new Map(), tweets: new Map(), media: new Map() };
+function mergePage(prev, body) {
+    const rows = Array.isArray(body.data) ? body.data : [];
+    const users = new Map(prev.users);
+    for (const [k, v] of usersById(body.includes))
+        users.set(k, v);
+    const tweets = new Map(prev.tweets);
+    for (const [k, v] of tweetsById(body.includes))
+        tweets.set(k, v);
+    const media = new Map(prev.media);
+    for (const [k, v] of mediaByKey(body.includes))
+        media.set(k, v);
+    const next = typeof body.meta?.next_token === 'string' ? body.meta.next_token : undefined;
+    return { rows: [...prev.rows, ...rows], users, tweets, media, ...(next ? { next } : {}) };
+}
+export function Timeline({ page, nowMs, empty, filter }) {
+    const rows = filter ? page.rows.filter(filter) : page.rows;
+    if (rows.length === 0)
+        return empty === null ? null : _jsx("div", { className: "empty", children: empty });
+    return _jsx("div", { className: "timeline", children: rows.map((p) => _jsx(PostRow, { post: p, users: page.users, tweets: page.tweets, media: page.media, nowMs: nowMs }, String(p.id))) });
+}
+/** A paged timeline read: first page on mount, "Show more" follows meta.next_token. */
+function usePagedRead(session, path, reloadKey) {
+    const [page, setPage] = useState(EMPTY_PAGE);
+    const [error, setError] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const load = useCallback(async (token, prev) => {
+        if (path === null)
+            return;
+        setLoading(true);
+        const w = await wire(session.token, `${path}${path.includes('?') ? '&' : '?'}max_results=50&${POST_READ_QUERY}${token ? `&pagination_token=${encodeURIComponent(token)}` : ''}`);
+        setLoading(false);
+        if (w.status !== 200) {
+            setError(problemText(w));
+            return;
+        }
+        setError(null);
+        setPage(mergePage(prev, w.body));
+    }, [path, session.token]);
+    useEffect(() => { setPage(EMPTY_PAGE); void load(undefined, EMPTY_PAGE); }, [load, reloadKey]);
+    return { page, error, loading, more: () => { if (page.next)
+            void load(page.next, page); } };
+}
+function MoreButton({ read }) {
+    if (!read.page.next)
+        return null;
+    return _jsx("button", { className: "show-more", disabled: read.loading, onClick: read.more, children: "Show more posts" });
+}
+// ── the composer: POST /2/tweets, the vendor's own write ────────────────────────────────────────
+const LIMIT = 280;
+function Composer({ session, me, onPosted, replyTo }) {
+    const [draft, setDraft] = useState('');
+    const [error, setError] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const length = Array.from(draft).length;
+    const left = LIMIT - length;
+    const post = async () => {
+        if (draft.trim() === '' || busy)
+            return;
+        setBusy(true);
+        // a reply is the SAME route with reply.in_reply_to_tweet_id — X's own discriminator
+        const body = replyTo ? { text: draft, reply: { in_reply_to_tweet_id: replyTo.id } } : { text: draft };
+        const w = await wire(session.token, '/2/tweets', { method: 'POST', body });
+        setBusy(false);
+        if (w.status !== 201 && w.status !== 200) {
+            setError(problemText(w));
+            return;
+        }
+        setError(null);
+        setDraft('');
+        onPosted(String(w.body.data?.id ?? ''));
+    };
+    const pct = Math.min(1, length / LIMIT);
+    return (_jsxs("div", { className: replyTo ? 'composer composer-reply' : 'composer', children: [_jsx(Avatar, { user: me ?? { username: session.handle } }), _jsxs("div", { className: "composer-body", children: [replyTo ? _jsxs("div", { className: "muted replying", children: ["Replying to ", _jsxs("span", { className: "entity", children: ["@", replyTo.handle] })] }) : null, _jsx("textarea", { className: "composer-input", placeholder: replyTo ? 'Post your reply' : 'What is happening?!', value: draft, rows: replyTo ? 1 : 2, onChange: (e) => setDraft(e.target.value), onKeyDown: (e) => { if (e.key === 'Enter' && (e.metaKey || e.ctrlKey))
+                            void post(); } }), error ? _jsx("div", { className: "composer-error", role: "alert", children: error }) : null, _jsxs("div", { className: "composer-bar", children: [_jsx("span", { className: "composer-reach", children: replyTo ? '' : 'Everyone can reply' }), _jsxs("span", { className: "composer-right", children: [length > 0 ? (_jsxs("span", { className: left < 0 ? 'counter over' : left <= 20 ? 'counter warn' : 'counter', children: [_jsxs("svg", { viewBox: "0 0 20 20", width: "20", height: "20", "aria-hidden": "true", children: [_jsx("circle", { cx: "10", cy: "10", r: "8", fill: "none", stroke: "#2f3336", strokeWidth: "2" }), _jsx("circle", { cx: "10", cy: "10", r: "8", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeDasharray: `${pct * 50.27} 50.27`, transform: "rotate(-90 10 10)" })] }), left <= 20 ? _jsx("span", { className: "counter-num", children: left }) : null] })) : null, _jsx("button", { className: "btn-post", disabled: draft.trim() === '' || busy, onClick: () => void post(), children: replyTo ? 'Reply' : 'Post' })] })] })] })] }));
+}
+// ── screens ──────────────────────────────────────────────────────────────────────────────────────
+function Header({ title, sub, back }) {
+    return (_jsxs("div", { className: "col-header", children: [back ? _jsx("button", { className: "back", "aria-label": "Back", onClick: () => history.back(), children: _jsx(Icon, { d: I_BACK, size: 20 }) }) : null, _jsxs("div", { children: [_jsx("div", { className: "col-title", children: title }), sub ? _jsx("div", { className: "muted col-sub", children: sub }) : null] })] }));
+}
+export function ProfileHeader({ user }) {
+    return (_jsxs("div", { className: "profile", children: [_jsx("div", { className: "banner" }), _jsx("div", { className: "profile-top", children: _jsx("div", { className: "profile-avatar", children: _jsx(Avatar, { user: user, size: 134 }) }) }), _jsxs("div", { className: "profile-info", children: [_jsxs("div", { className: "profile-name", children: [_jsx("span", { children: String(user.name ?? '') }), user.verified === true ? _jsx(Icon, { d: VERIFIED, fill: true, size: 22, className: "badge" }) : null, user.protected === true ? _jsx(Icon, { d: I_LOCK, size: 18, className: "lock" }) : null] }), _jsxs("div", { className: "muted profile-handle", children: ["@", String(user.username ?? '')] }), typeof user.description === 'string' && user.description !== '' ? _jsx("div", { className: "profile-bio", children: _jsx(PostText, { text: user.description }) }) : null, _jsxs("div", { className: "muted profile-meta", children: [typeof user.location === 'string' && user.location !== '' ? _jsxs("span", { children: [_jsx(Icon, { d: I_PIN, size: 16 }), user.location] }) : null, typeof user.url === 'string' && user.url !== '' ? _jsxs("span", { children: [_jsx(Icon, { d: I_LINK, size: 16 }), _jsx("a", { className: "entity", href: linkHref(user.url), target: "_blank", rel: "noreferrer", children: displayUrl(user.url) })] }) : null, user.created_at ? _jsxs("span", { children: [_jsx(Icon, { d: I_CAL, size: 16 }), joinedLabel(user.created_at)] }) : null] })] })] }));
+}
+function ProfileScreen({ session, handle, tab, nowMs, reloadKey }) {
+    const [user, setUser] = useState(null);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        setUser(null);
+        setError(null);
+        void wire(session.token, `/2/users/by/username/${encodeURIComponent(handle)}?${PROFILE_READ_QUERY}`).then((w) => {
+            if (w.status === 200 && w.body.data)
+                setUser(w.body.data);
+            else
+                setError(w.status === 200 ? 'This account doesn’t exist' : problemText(w));
+        });
+    }, [handle, session.token, reloadKey]);
+    const read = usePagedRead(session, user ? `/2/users/${user.id}/tweets` : null, reloadKey);
+    if (error)
+        return _jsxs(_Fragment, { children: [_jsx(Header, { title: handle, back: true }), _jsxs("div", { className: "empty", children: [_jsx("div", { className: "empty-title", children: error }), _jsx("div", { className: "muted", children: "Try searching for another." })] })] });
+    if (!user)
+        return _jsxs(_Fragment, { children: [_jsx(Header, { title: handle, back: true }), _jsx("div", { className: "loading" })] });
+    const isReply = (p) => referencedId(p, 'replied_to') !== undefined;
+    return (_jsxs(_Fragment, { children: [_jsx(Header, { title: String(user.name ?? handle), sub: `${read.page.rows.length}${read.page.next ? '+' : ''} ${read.page.rows.length === 1 && !read.page.next ? 'post' : 'posts'}`, back: true }), _jsx(ProfileHeader, { user: user }), _jsxs("nav", { className: "tabs", children: [_jsx("a", { className: tab === 'posts' ? 'tab active' : 'tab', href: `#/${user.username}`, children: "Posts" }), _jsx("a", { className: tab === 'replies' ? 'tab active' : 'tab', href: `#/${user.username}/with_replies`, children: "Replies" })] }), read.error ? _jsx("div", { className: "empty", children: read.error }) : null, _jsx(Timeline, { page: read.page, nowMs: nowMs, filter: tab === 'posts' ? (p) => !isReply(p) : undefined, empty: _jsxs(_Fragment, { children: [_jsx("div", { className: "empty-title", children: `@${user.username} hasn’t posted` }), _jsx("div", { className: "muted", children: "When they do, their posts will show up here." })] }) }), _jsx(MoreButton, { read: read })] }));
+}
+/** The replies the signed-in account can read: its own posts and its mentions, the two timelines
+ *  the twin serves it. A reply by an account that neither is nor mentions the viewer is not
+ *  readable here, exactly as it is not readable through the API. */
+function useReplies(session, me, id, reloadKey) {
+    const [page, setPage] = useState(EMPTY_PAGE);
+    useEffect(() => {
+        if (!me)
+            return;
+        let live = true;
+        void Promise.all([
+            wire(session.token, `/2/users/${me.id}/tweets?max_results=100&${POST_READ_QUERY}`),
+            wire(session.token, `/2/users/${me.id}/mentions?max_results=100&${POST_READ_QUERY}`),
+        ]).then(([own, mentions]) => {
+            if (!live)
+                return;
+            const merged = [own, mentions].reduce((acc, w) => (w.status === 200 ? mergePage(acc, w.body) : acc), EMPTY_PAGE);
+            setPage({ rows: repliesTo(id, merged.rows), users: merged.users, tweets: merged.tweets, media: merged.media });
+        });
+        return () => { live = false; };
+    }, [session.token, me, id, reloadKey]);
+    return page;
+}
+function StatusScreen({ session, me, id, nowMs, reloadKey, onPosted }) {
+    const [w, setW] = useState(null);
+    useEffect(() => { setW(null); void wire(session.token, `/2/tweets/${encodeURIComponent(id)}?${POST_READ_QUERY}`).then(setW); }, [id, session.token, reloadKey]);
+    const replies = useReplies(session, me, id, reloadKey);
+    if (w === null)
+        return _jsxs(_Fragment, { children: [_jsx(Header, { title: "Post", back: true }), _jsx("div", { className: "loading" })] });
+    const post = w.body.data;
+    if (w.status !== 200 || !post) {
+        return _jsxs(_Fragment, { children: [_jsx(Header, { title: "Post", back: true }), _jsxs("div", { className: "empty", children: [_jsx("div", { className: "empty-title", children: "Hmm...this page doesn\u2019t exist." }), _jsx("div", { className: "muted", children: problemText(w) })] })] });
+    }
+    const users = usersById(w.body.includes);
+    const tweets = tweetsById(w.body.includes);
+    const media = mediaByKey(w.body.includes);
+    const author = users.get(String(post.author_id));
+    const parentId = referencedId(post, 'replied_to');
+    const parent = parentId ? tweets.get(parentId) : undefined;
+    const quotedId = referencedId(post, 'quoted');
+    const quoted = quotedId ? tweets.get(quotedId) : undefined;
+    return (_jsxs(_Fragment, { children: [_jsx(Header, { title: "Post", back: true }), parent ? _jsx(PostRow, { post: parent, users: users, tweets: tweets, media: media, nowMs: nowMs }) : null, _jsxs("article", { className: "status", "data-post-id": String(post.id), children: [_jsxs("div", { className: "status-head", children: [_jsx(Avatar, { user: author }), _jsxs("div", { className: "status-names", children: [_jsxs("div", { className: "name-line", children: [_jsx("span", { className: "display-name", children: String(author?.name ?? 'Unknown') }), author?.verified === true ? _jsx(Icon, { d: VERIFIED, fill: true, size: 17, className: "badge" }) : null] }), _jsxs("div", { className: "muted", children: ["@", String(author?.username ?? 'unknown')] })] })] }), post.in_reply_to_user_id && users.get(String(post.in_reply_to_user_id))
+                        ? _jsxs("div", { className: "muted replying", children: ["Replying to ", _jsxs("span", { className: "entity", children: ["@", String(users.get(String(post.in_reply_to_user_id)).username)] })] }) : null, post.text ? _jsx(PostText, { text: post.text, big: true }) : null, _jsx(MediaBlock, { media: postMedia(post, media), big: true }), quoted ? _jsx(QuoteCard, { quoted: quoted, users: users, nowMs: nowMs }) : null, _jsx("div", { className: "muted status-time", children: _jsx("time", { dateTime: String(post.created_at ?? ''), children: fullTimestamp(post.created_at) }) }), _jsx(ActionRow, { big: true })] }), _jsx(Composer, { session: session, me: me, onPosted: onPosted, replyTo: { id: String(post.id), handle: String(author?.username ?? '') } }), _jsx(Timeline, { page: replies, nowMs: nowMs, empty: null })] }));
+}
+function HomeScreen({ session, me, nowMs, reloadKey, onPosted }) {
+    const read = usePagedRead(session, me ? `/2/users/${me.id}/timelines/reverse_chronological` : null, reloadKey);
+    return (_jsxs(_Fragment, { children: [_jsx("nav", { className: "tabs tabs-top", children: _jsx("span", { className: "tab active", children: "Following" }) }), _jsx(Composer, { session: session, me: me, onPosted: onPosted }), read.error ? _jsx("div", { className: "empty", children: read.error }) : null, _jsx(Timeline, { page: read.page, nowMs: nowMs, empty: _jsxs(_Fragment, { children: [_jsx("div", { className: "empty-title", children: "Welcome to X!" }), _jsx("div", { className: "muted", children: "Posts from you and the accounts you follow show up here." })] }) }), _jsx(MoreButton, { read: read })] }));
+}
+function NotificationsScreen({ session, me, nowMs, reloadKey }) {
+    const read = usePagedRead(session, me ? `/2/users/${me.id}/mentions` : null, reloadKey);
+    return (_jsxs(_Fragment, { children: [_jsx(Header, { title: "Notifications" }), _jsx("nav", { className: "tabs", children: _jsx("span", { className: "tab active", children: "Mentions" }) }), read.error ? _jsx("div", { className: "empty", children: read.error }) : null, _jsx(Timeline, { page: read.page, nowMs: nowMs, empty: _jsxs(_Fragment, { children: [_jsx("div", { className: "empty-title", children: "Nothing to see here \u2014 yet" }), _jsx("div", { className: "muted", children: "When someone mentions you, you\u2019ll find it here." })] }) }), _jsx(MoreButton, { read: read })] }));
+}
+// ── sign-in: x.com's two-step login, the password leg being the twin-issued bearer ──────────────
+function LoginScreen({ onSignedIn }) {
+    const [step, setStep] = useState('handle');
+    const [handle, setHandle] = useState('');
+    const [token, setToken] = useState('');
+    const [error, setError] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const cleanHandle = handle.trim().replace(/^@/, '');
+    const next = () => {
+        if (!/^[A-Za-z0-9_]{1,15}$/.test(cleanHandle)) {
+            setError('Sorry, we could not find your account.');
+            return;
+        }
+        setError(null);
+        setStep('token');
+    };
+    const login = async () => {
+        setBusy(true);
+        const w = await wire(token.trim(), `/2/users/by/username/${encodeURIComponent(cleanHandle)}`);
+        if (w.status === 401) {
+            setBusy(false);
+            setError('Wrong token!');
+            return;
+        }
+        if (w.status !== 200 || !w.body.data) {
+            setBusy(false);
+            setError(w.status === 200 ? 'Sorry, we could not find your account.' : problemText(w));
+            return;
+        }
+        const me = w.body.data;
+        // Is this token THIS account's? X serves the home timeline only to its own account, so the
+        // vendor's own refusal answers it; a token for another account is refused here, not later.
+        const own = await wire(token.trim(), `/2/users/${me.id}/timelines/reverse_chronological?max_results=5`);
+        setBusy(false);
+        if (own.status === 403) {
+            setError(`That token does not sign in as @${me.username}.`);
+            return;
+        }
+        if (own.status !== 200) {
+            setError(problemText(own));
+            return;
+        }
+        onSignedIn({ handle: String(me.username), token: token.trim() }, me);
+    };
+    return (_jsx("div", { className: "login-backdrop", children: _jsxs("div", { className: "login", children: [_jsx("div", { className: "login-logo", children: _jsx(Icon, { d: X_LOGO, fill: true, size: 32 }) }), step === 'handle' ? (_jsxs("form", { className: "login-form", onSubmit: (e) => { e.preventDefault(); next(); }, children: [_jsx("h1", { children: "Sign in to X" }), _jsxs("label", { className: "field", children: [_jsx("span", { children: "Phone, email, or username" }), _jsx("input", { autoFocus: true, name: "handle", value: handle, onChange: (e) => setHandle(e.target.value), autoComplete: "username" })] }), error ? _jsx("div", { className: "login-error", role: "alert", children: error }) : null, _jsx("button", { className: "btn-white", type: "submit", disabled: cleanHandle === '', children: "Next" }), _jsxs("div", { className: "muted login-note", children: ["This twin signs you in with the access token it issued for the account (", _jsx("code", { children: "/_twin/tokens" }), "), in place of a password."] })] })) : (_jsxs("form", { className: "login-form", onSubmit: (e) => { e.preventDefault(); void login(); }, children: [_jsx("h1", { children: "Enter your password" }), _jsxs("label", { className: "field field-disabled", children: [_jsx("span", { children: "Username" }), _jsx("input", { value: `@${cleanHandle}`, disabled: true })] }), _jsxs("label", { className: "field", children: [_jsx("span", { children: "Access token" }), _jsx("input", { autoFocus: true, name: "token", type: "password", value: token, onChange: (e) => setToken(e.target.value), autoComplete: "current-password" })] }), error ? _jsx("div", { className: "login-error", role: "alert", children: error }) : null, _jsx("button", { className: "btn-white", type: "submit", disabled: token.trim() === '' || busy, children: "Log in" }), _jsx("button", { className: "btn-link", type: "button", onClick: () => { setStep('handle'); setError(null); }, children: "Use another account" })] }))] }) }));
+}
+function App() {
+    const [session, setSession] = useState(readSession);
+    const [me, setMe] = useState(null);
+    const [route, setRoute] = useState(() => parseRoute(typeof location === 'undefined' ? '' : location.hash));
+    const [reloadKey, setReloadKey] = useState(0);
+    const [toast, setToast] = useState(null);
+    const [nowMs, setNowMs] = useState(() => Date.now());
+    useEffect(() => {
+        const onHash = () => { setRoute(parseRoute(location.hash)); setNowMs(Date.now()); window.scrollTo(0, 0); };
+        // a `#/…` link is one of the mirror's own routes; under a World's <base> (the twin's place, not the
+        // shell's) the browser would resolve it against the base and leave the shell, so it moves the hash here
+        const onClick = (e) => {
+            const a = e.target?.closest?.('a[href^="#/"]');
+            if (!a || e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
+                return;
+            e.preventDefault();
+            location.hash = a.getAttribute('href');
+        };
+        window.addEventListener('hashchange', onHash);
+        document.addEventListener('click', onClick, true);
+        return () => { window.removeEventListener('hashchange', onHash); document.removeEventListener('click', onClick, true); };
+    }, []);
+    useEffect(() => { const t = setInterval(() => setNowMs(Date.now()), 30_000); return () => clearInterval(t); }, []);
+    // who am I: the signed-in handle, read back through the vendor's own user lookup
+    useEffect(() => {
+        if (!session) {
+            setMe(null);
+            return;
+        }
+        void wire(session.token, `/2/users/by/username/${encodeURIComponent(session.handle)}?user.fields=verified,protected`).then((w) => {
+            if (w.status === 200 && w.body.data)
+                setMe(w.body.data);
+            else if (w.status === 401)
+                signOut();
+        });
+    }, [session]);
+    const signIn = (s, user) => {
+        sessionStorage.setItem(SESSION_HANDLE, s.handle);
+        sessionStorage.setItem(SESSION_TOKEN, s.token);
+        setMe(user);
+        setSession(s);
+        go(s.handle);
+    };
+    const signOut = () => {
+        sessionStorage.removeItem(SESSION_HANDLE);
+        sessionStorage.removeItem(SESSION_TOKEN);
+        setSession(null);
+        setMe(null);
+        go('i/flow/login');
+    };
+    const onPosted = (id) => { setReloadKey((k) => k + 1); setNowMs(Date.now()); setToast({ id }); setTimeout(() => setToast(null), 6000); };
+    if (!session || route?.page === 'login')
+        return _jsx(LoginScreen, { onSignedIn: signIn });
+    const r = route ?? { page: 'profile', handle: session.handle, tab: 'posts' };
+    const handle = me?.username ? String(me.username) : session.handle;
+    let screen;
+    if (r.page === 'home')
+        screen = _jsx(HomeScreen, { session: session, me: me, nowMs: nowMs, reloadKey: reloadKey, onPosted: onPosted });
+    else if (r.page === 'notifications')
+        screen = _jsx(NotificationsScreen, { session: session, me: me, nowMs: nowMs, reloadKey: reloadKey });
+    else if (r.page === 'status')
+        screen = _jsx(StatusScreen, { session: session, me: me, id: r.id, nowMs: nowMs, reloadKey: reloadKey, onPosted: onPosted });
+    else
+        screen = _jsx(ProfileScreen, { session: session, handle: r.page === 'profile' ? r.handle : handle, tab: r.page === 'profile' ? r.tab : 'posts', nowMs: nowMs, reloadKey: reloadKey });
+    const onProfile = r.page === 'profile' && r.handle.toLowerCase() === handle.toLowerCase();
+    return (_jsxs("div", { className: "layout", children: [_jsxs("header", { className: "sidenav", children: [_jsx("a", { className: "nav-logo", href: "#/home", "aria-label": "X", children: _jsx(Icon, { d: X_LOGO, fill: true, size: 30 }) }), _jsxs("a", { className: r.page === 'home' ? 'nav-item active' : 'nav-item', href: "#/home", children: [_jsx(Icon, { d: I_HOME, size: 26 }), _jsx("span", { children: "Home" })] }), _jsxs("a", { className: r.page === 'notifications' ? 'nav-item active' : 'nav-item', href: "#/notifications", children: [_jsx(Icon, { d: I_BELL, size: 26 }), _jsx("span", { children: "Notifications" })] }), _jsxs("a", { className: onProfile ? 'nav-item active' : 'nav-item', href: `#/${handle}`, children: [_jsx(Icon, { d: I_USER, size: 26 }), _jsx("span", { children: "Profile" })] }), _jsx("button", { className: "btn-nav-post", onClick: () => go('home'), children: "Post" }), _jsxs("div", { className: "nav-account", title: "Log out", onClick: signOut, children: [_jsx(Avatar, { user: me ?? { username: session.handle } }), _jsxs("div", { className: "nav-account-names", children: [_jsx("div", { className: "display-name", children: String(me?.name ?? session.handle) }), _jsxs("div", { className: "muted", children: ["@", handle] })] }), _jsx("span", { className: "muted nav-logout", children: "Log out" })] })] }), _jsx("main", { className: "column", children: screen }), _jsx("aside", { className: "rail" }), toast ? (_jsxs("div", { className: "toast", role: "status", children: [_jsx("span", { children: "Your post was sent." }), toast.id ? _jsx("a", { href: `#/${handle}/status/${toast.id}`, children: "View" }) : null] })) : null] }));
+}
+const el = typeof document !== 'undefined' ? document.getElementById('root') : null;
+if (el)
+    createRoot(el).render(_jsx(App, {}));

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createXTwinServer } from "./x-server.js";
+import { createXMirrorServer } from "./x-mirror-ui.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+if (cmd === 'serve') {
+    const server = await createXTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+    process.stdout.write(`x twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${server.port}\n`);
+    await keepProcessAlive();
+}
+else if (cmd === 'mirror') {
+    const s = await createXMirrorServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+    process.stdout.write(`x mirror UI (x.com: sign in, profile, timeline, post, compose) at ${s.url}\n`);
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    const { checkXConformance } = await import("./x-conformance.js");
+    const report = await checkXConformance({ ...(root ? { root } : {}) });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-x serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+export { handleXTwinRequest } from './x-twin.js';
+export type { XRequest } from './x-twin.js';
+export { createXTwinFetch, createXTwinServer, type XTwinFetchOptions } from './x-server.js';
+export { budgetedXExecute, liveXExecute, MAX_PROCESSING_POLLS, MAX_PROCESSING_WAIT_MS, XVideoStillProcessingError, mapTimelinePost, pullXMentions, pullXOwnTimeline, pushPendingXActions, pushXAction, performXAction, PULL_TWEET_FIELDS, syncXFromReal, xRequestForAction, } from './x-connector.js';
+export type { LiveXOptions, XExecute } from './x-connector.js';
+export { forbiddenProblem, invalidRequestProblem, notFoundProblem, rateLimitExceeded, readOnlyRefusal, resourceNotFoundProblem, unauthorizedProblem, } from './x-problems.js';
+export type { XResponse } from './x-problems.js';
+export { avatarHue, avatarInitial, buildXMirrorClient, createXMirrorServer, displayUrl, durationLabel, fullTimestamp, joinedLabel, mediaByKey, postMedia, PROFILE_READ_QUERY, POST_READ_QUERY, referencedId, relativeTime, textSegments, tweetsById, usersById, videoSource, xMirrorHtml, xMirrorStyles, } from './x-mirror-ui.js';
+export type { TextSegment, XRow } from './x-mirror-ui.js';
+export { missingScopes, parseScopeList, REQUIRED_SCOPES, X_SCOPES } from './x-scopes.js';
+export { X_BUDGET_BURST_CEILING, X_BUDGET_CEILING, X_BUDGET_MAX_RETRY_AFTER_S, X_BUDGET_WINDOW_MS, X_CALL_WEIGHTS, X_RATE_BUDGET, XBudget, XBudgetError, xBudgetPath, xCallWeight, } from './x-budget.js';
+export type { XBudgetErrorKind, XBudgetOptions, XBudgetReservation, XBudgetSnapshot } from './x-budget.js';
+import type { TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,68 @@
+export { handleXTwinRequest } from "./x-twin.js";
+export { createXTwinFetch, createXTwinServer } from "./x-server.js";
+export { budgetedXExecute, liveXExecute, MAX_PROCESSING_POLLS, MAX_PROCESSING_WAIT_MS, XVideoStillProcessingError, mapTimelinePost, pullXMentions, pullXOwnTimeline, pushPendingXActions, pushXAction, performXAction, PULL_TWEET_FIELDS, syncXFromReal, xRequestForAction, } from "./x-connector.js";
+export { forbiddenProblem, invalidRequestProblem, notFoundProblem, rateLimitExceeded, readOnlyRefusal, resourceNotFoundProblem, unauthorizedProblem, } from "./x-problems.js";
+export { avatarHue, avatarInitial, buildXMirrorClient, createXMirrorServer, displayUrl, durationLabel, fullTimestamp, joinedLabel, mediaByKey, postMedia, PROFILE_READ_QUERY, POST_READ_QUERY, referencedId, relativeTime, textSegments, tweetsById, usersById, videoSource, xMirrorHtml, xMirrorStyles, } from "./x-mirror-ui.js";
+export { missingScopes, parseScopeList, REQUIRED_SCOPES, X_SCOPES } from "./x-scopes.js";
+// The client-side rate budget — the fail-closed backstop `liveXExecute` routes every live
+// request through. The mechanism is the kernel's (`@volter/world-core` -> rateBudget.ts); these are
+// this vendor's numbers and the typed bindings around them.
+export { X_BUDGET_BURST_CEILING, X_BUDGET_CEILING, X_BUDGET_MAX_RETRY_AFTER_S, X_BUDGET_WINDOW_MS, X_CALL_WEIGHTS, X_RATE_BUDGET, XBudget, XBudgetError, xBudgetPath, xCallWeight, } from "./x-budget.js";
+import { X_RATE_BUDGET as RATE_BUDGET } from "./x-budget.js";
+/**
+ * The api.x.com / api.twitter.com paths THIS pack serves, as a RegExp SOURCE for the descriptor's
+ * `hosts` path rule (the injector compiles it with `new RegExp` and tests it against the pathname).
+ * The POSTING slice — create/quote/reply (one route), retract, post lookup (single and bulk),
+ * recent search, the three per-user timelines (mentions, the account's own posts, the home
+ * timeline), user lookup by id and by username, and image upload (one-shot and chunked) — plus the
+ * twin-only control prefix. The user-id
+ * rule EXCLUDES `/2/users/me`: that route is xidentity's, and the two claims stay disjoint. ANCHORED: an unanchored claim would swallow
+ * `/2/tweetsomething`. Everything else on api.x.com stays unclaimed, so an unmodelled X call
+ * refuses loudly rather than landing in a twin that cannot serve it.
+ */
+const X_API_PATHS = '^(?:/2/media/upload/?|/2/media/upload/initialize/?|/2/media/upload/[0-9]+/(?:append|finalize)/?|/2/tweets/?|/2/tweets/[^/]+/?|/2/tweets/search/recent/?|/2/users/(?!me/?$)[^/]+/?|/2/users/by/username/[^/]+/?|/2/users/[^/]+/mentions/?|/2/users/[^/]+/tweets/?|/2/users/[^/]+/timelines/reverse_chronological/?)$|^/_twin/';
+export const pack = {
+    vendor: 'x',
+    // The SAME object x-budget.ts declares at module load — one source of truth, so registering
+    // the pack and importing the connector arm identical numbers.
+    rateBudget: RATE_BUDGET,
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-x',
+    resources: ['account', 'token', 'post', 'follow', 'rate_limit'],
+    specSource: 'X API v2 posting surface — POST /2/tweets (original post, QUOTE and reply, told apart by quote_tweet_id / reply.in_reply_to_tweet_id), DELETE /2/tweets/:id, GET /2/tweets/:id and GET /2/tweets?ids=, GET /2/tweets/search/recent, GET /2/users/:id/{mentions,tweets,timelines/reverse_chronological}, GET /2/users/:id and GET /2/users/by/username/:username, with tweet.fields/user.fields/expansions projection and next_token paging. Routes and body shapes grounded in the pinned twitter-api-v2@1.29.1 client source; error envelopes and the scope catalog transcribed from packages/twin/xidentity (X API v2 OpenAPI 2.167). See test-fixtures/x-openapi-operations.SOURCE.md.',
+    description: "X twin — the org's public voice: post, quote, reply to a mention, retract, look a post or an account back up, and read the mentions / own / home timelines and recent search, offline, with X's own tweet.fields projection, bearer/scope gate and problem envelopes. OAuth itself is xidentity's and stays there.",
+    // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+    // 2026-08-31).
+    //
+    // `twitter-api-v2` is claimed by THIS pack, not by `xidentity`: it is a third-party library
+    // spanning the whole X API (posts, streams, DMs), and this pack models the POSTING surface it is
+    // actually installed for. No env stem is claimed — X_CLIENT_ID / X_CLIENT_SECRET and
+    // TWITTER_CLIENT_ID name the OAuth APP credentials, which is xidentity's surface; a repo that
+    // posts holds a user access token that flow minted, so the app credential and the posting client
+    // are the same integration seen from two sides and both twins report as covered.
+    adoption: {
+        // COMMUNITY: X ships no Python SDK (its official clients are `@xdevplatform/xdk` and the legacy
+        // `twitter-api-sdk`, both TypeScript). `tweepy` is the de-facto Python client of the X API and is
+        // claimed HERE rather than on `xidentity` because its dominant use is exactly this pack's surface
+        // - posting and reading tweets/mentions - not the OAuth token exchange. One name, one pack.
+        pypi: ['tweepy'],
+        sdks: ['twitter-api-v2'],
+    },
+    // The POSTING surface — the org's public voice. Path-scoped for the same reason xidentity is:
+    // api.x.com is the whole X API v2 host and this pack models one slice. The two packs' path sets
+    // are DISJOINT BY CONSTRUCTION: `xidentity` claims `/2/oauth2/{token,revoke}` and `/2/users/me`;
+    // this claims `/2/tweets*`, the per-user timelines, `/2/users/{id}` and
+    // `/2/users/by/username/{username}`. The user-id rule carries a `(?!me/?$)` lookahead and the
+    // timeline rules need a trailing segment, so `/2/users/me` matches none of them and no request
+    // is claimable by both. ANCHORED, the
+    // googleoauth lesson: an unanchored claim swallows `/2/tweetsomething`. Everything else on
+    // api.x.com — DMs, spaces, lists, media metadata — stays unclaimed, so an unmodelled X call
+    // refuses loudly rather than landing in a twin that cannot serve it. api.twitter.com is claimed
+    // alongside api.x.com because that is the host X's own legacy clients still target.
+    hosts: [
+        { host: 'api.x.com', pathPattern: X_API_PATHS },
+        { host: 'api.twitter.com', pathPattern: X_API_PATHS },
+    ],
+    browserRouting: { apiPathPrefix: '/2/', loaderHost: 'https://api.x.com' },
+};