@volter/twin-tiktok 0.1.0

package/dist/client/tiktok-mirror.tsx

@@ -0,0 +1,492 @@
+// TikTok mirror — React/TSX client. tiktok.com's own view of the twin's state: log in as the creator,
+// read their profile over the Videos grid, and open a post in the vertical player. Every read is the
+// twin's OWN Display API on the same origin (GET /v2/user/info/, POST /v2/video/list/); the player
+// plays the posted bytes from the twin's media route. Nothing is kept but the signed-in username and
+// token, in the tab's sessionStorage.
+import { createRoot } from 'react-dom/client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  avatarHue, avatarInitial, BASIC_FIELDS, captionOf, captionSegments, clock, compactCount, mediaSource, PROFILE_FIELDS, profileStats,
+  VIDEO_PAGE_SIZE, VIDEO_READ_FIELDS, type TtRow,
+} from '../src/tiktok-mirror-ui.ts';
+
+// 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 resolves inside that prefix.
+const WIRE_BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
+
+const SESSION_HANDLE = 'tiktok-mirror.username';
+const SESSION_TOKEN = 'tiktok-mirror.token';
+
+type Session = { handle: string; token: string };
+type Wire = { status: number; body: TtRow };
+
+function readSession(): Session | null {
+  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: string, path: string, init?: { method?: string; body?: unknown }): Promise<Wire> {
+  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: TtRow = {};
+  try { body = await res.json() as TtRow; } catch { body = {}; }
+  return { status: res.status, body };
+}
+
+/** TikTok's nested error, as one sentence for the screen. */
+const errorText = (w: Wire): string => String(w.body?.error?.message ?? `HTTP ${w.status}`);
+const errorCode = (w: Wire): string => String(w.body?.error?.code ?? '');
+
+/** The signed-in creator: every profile field, or — for a token without the profile/stats scopes —
+ *  the basic ones, so the header shows what the twin returns and nothing it does not. */
+async function readMe(token: string): Promise<Wire> {
+  const full = await wire(token, `/v2/user/info/?fields=${PROFILE_FIELDS}`);
+  if (full.status === 401 && errorCode(full) === 'scope_not_authorized') return wire(token, `/v2/user/info/?fields=${BASIC_FIELDS}`);
+  return full;
+}
+
+// ── routing: hash routes, so the shell answers every screen under any mount ─────────────────────
+type Route = { page: 'login' } | { page: 'profile'; handle: string } | { page: 'video'; handle: string; id: string };
+
+function parseRoute(hash: string): Route | null {
+  const parts = hash.replace(/^#\/?/, '').split('/').filter(Boolean);
+  if (parts.length === 0) return null;
+  if (parts[0] === 'login') return { page: 'login' };
+  const handle = decodeURIComponent(parts[0]!).replace(/^@/, '');
+  if (parts[1] === 'video' && parts[2]) return { page: 'video', handle, id: parts[2] };
+  return { page: 'profile', handle };
+}
+const go = (path: string) => { location.hash = `#/${path}`; };
+
+// ── icons (vendor mirror: tiktok.com's look, drawn here) ────────────────────────────────────────
+const NOTE = 'M16.6 5.82s.51.5 0 0A4.28 4.28 0 0 1 15.54 3h-3.09v12.4a2.59 2.59 0 0 1-2.59 2.5c-1.42 0-2.6-1.16-2.6-2.6 0-1.72 1.66-3.01 3.37-2.48V9.66c-3.45-.46-6.47 2.22-6.47 5.64 0 3.33 2.76 5.7 5.69 5.7 3.14 0 5.69-2.55 5.69-5.7V9.01a7.35 7.35 0 0 0 4.3 1.38V7.3s-1.88.09-3.24-1.48z';
+export function Logo({ size = 34, word = true }: { size?: number; word?: boolean }) {
+  return (
+    <span className="logo">
+      <svg viewBox="0 0 24 24" width={size} height={size} aria-hidden="true">
+        <path d={NOTE} fill="#25F4EE" transform="translate(-0.9 -0.7)" />
+        <path d={NOTE} fill="#FE2C55" transform="translate(0.9 0.7)" />
+        <path d={NOTE} fill="currentColor" />
+      </svg>
+      {word ? <span className="logo-word">TikTok</span> : null}
+    </span>
+  );
+}
+function Icon({ d, size = 24, fill = false, className }: { d: string[]; size?: number; fill?: boolean; className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" width={size} height={size} aria-hidden="true"
+      fill={fill ? 'currentColor' : 'none'} stroke={fill ? 'none' : 'currentColor'} strokeWidth={2} strokeLinecap="round" strokeLinejoin="round">
+      {d.map((p) => <path key={p} d={p} />)}
+    </svg>
+  );
+}
+const I_HOME = ['M3 10.5 12 3l9 7.5V21h-6v-6H9v6H3z'];
+const I_EXPLORE = ['M12 22a10 10 0 1 0 0-20 10 10 0 0 0 0 20z', 'm16.2 7.8-2.1 6.3-6.3 2.1 2.1-6.3z'];
+const I_FOLLOWING = ['M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2', 'M9 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8z', 'M19 8v6', 'M22 11h-6'];
+const I_FRIENDS = ['M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2', 'M9 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8z', 'M23 21v-2a4 4 0 0 0-3-3.87', 'M16 3.13a4 4 0 0 1 0 7.75'];
+const I_LIVE = ['M4 6h16v12H4z', 'm10 9 5 3-5 3z'];
+const I_UPLOAD = ['M12 5v14', 'M5 12h14'];
+const I_PROFILE = ['M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2', 'M12 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8z'];
+const I_PLAY = ['M7 4.5v15l12-7.5z'];
+const I_PAUSE = ['M7 4h3.5v16H7z', 'M13.5 4H17v16h-3.5z'];
+const I_CLOSE = ['M18 6 6 18', 'm6 6 12 12'];
+const I_UP = ['m18 15-6-6-6 6'];
+const I_DOWN = ['m6 9 6 6 6-6'];
+const I_SHARE_ARROW = ['M14 4.5V9C7 9 3.5 13 3 19.5c2-3.5 5-5 11-5V19l7-7.25z'];
+const I_HEART = ['M12 21s-7.5-4.6-9.6-9.2C.9 8.4 2.9 4.5 6.7 4.5c2.2 0 3.7 1.2 5.3 3 1.6-1.8 3.1-3 5.3-3 3.8 0 5.8 3.9 4.3 7.3C19.5 16.4 12 21 12 21z'];
+const I_COMMENT = ['M12 3C6.5 3 2 6.9 2 11.7c0 2.6 1.3 4.9 3.4 6.5L4.7 22l4.6-2.4c.9.2 1.8.3 2.7.3 5.5 0 10-3.9 10-8.7S17.5 3 12 3z'];
+const I_BOOKMARK = ['M6 2.5h12a1 1 0 0 1 1 1V22l-7-4.5L5 22V3.5a1 1 0 0 1 1-1z'];
+const I_VERIFIED = ['M12 1.5 14.6 3.4l3.2-.2.9 3.1 2.8 1.6-1 3.1 1 3.1-2.8 1.6-.9 3.1-3.2-.2L12 22.5l-2.6-1.9-3.2.2-.9-3.1-2.8-1.6 1-3.1-1-3.1 2.8-1.6.9-3.1 3.2.2z'];
+const I_CHECK = ['m7.5 12.2 3 3 6-6.4'];
+const I_MUSIC = ['M9 18V5l12-2v13', 'M6 21a3 3 0 1 0 0-6 3 3 0 0 0 0 6z', 'M18 19a3 3 0 1 0 0-6 3 3 0 0 0 0 6z'];
+const I_VOLUME = ['M11 5 6 9H2v6h4l5 4z', 'M15.5 8.5a5 5 0 0 1 0 7', 'M19 5a10 10 0 0 1 0 14'];
+const I_MUTED = ['M11 5 6 9H2v6h4l5 4z', 'm22 9-6 6', 'm16 9 6 6'];
+const I_LOCK = ['M5 11h14v10H5z', 'M8 11V7a4 4 0 0 1 8 0v4'];
+const I_GRID = ['M4 4h7v7H4z', 'M13 4h7v7h-7z', 'M4 13h7v7H4z', 'M13 13h7v7h-7z'];
+
+// ── pieces ───────────────────────────────────────────────────────────────────────────────────────
+export function Avatar({ user, size }: { user: TtRow | undefined; size: number }) {
+  return (
+    <div className="avatar" style={{ width: size, height: size, fontSize: size * 0.42, background: `hsl(${avatarHue(user?.union_id ?? user?.username)} 55% 45%)` }} aria-hidden="true">
+      {avatarInitial(user)}
+    </div>
+  );
+}
+
+function Verified({ size = 20 }: { size?: number }) {
+  return (
+    <span className="verified" title="Verified account">
+      <Icon d={I_VERIFIED} fill size={size} />
+      <Icon d={I_CHECK} size={size} className="verified-check" />
+    </span>
+  );
+}
+
+export function Caption({ text }: { text: unknown }) {
+  return (
+    <span className="caption">
+      {captionSegments(text).map((s, i) => s.kind === 'text' ? <span key={i}>{s.value}</span> : <strong key={i} className="tag">{s.value}</strong>)}
+    </span>
+  );
+}
+
+/** The profile header: avatar, @username (h1) with the verified tick, the nickname, the buttons a
+ *  creator sees on their own page, the three counts (only those the twin returned) and the bio. */
+export function ProfileHeader({ user, own }: { user: TtRow; own: boolean }) {
+  const stats = profileStats(user);
+  return (
+    <header className="profile-header">
+      <Avatar user={user} size={212} />
+      <div className="profile-info">
+        <div className="profile-names">
+          <h1 className="profile-username">{String(user.username ?? user.display_name ?? '')}</h1>
+          {user.is_verified === true ? <Verified /> : null}
+          <h2 className="profile-nickname">{String(user.display_name ?? '')}</h2>
+        </div>
+        <div className="profile-buttons">
+          {own ? (
+            <>
+              <button className="btn btn-red">Edit profile</button>
+              <button className="btn btn-gray">Promote post</button>
+            </>
+          ) : (
+            <>
+              <button className="btn btn-red">Follow</button>
+              <button className="btn btn-gray">Message</button>
+            </>
+          )}
+        </div>
+        {stats.length > 0 ? (
+          <div className="profile-stats">
+            {stats.map((s) => <span key={s.label} className="stat" data-stat={s.label}><strong>{s.value}</strong><span className="stat-label">{s.label}</span></span>)}
+          </div>
+        ) : null}
+        {typeof user.bio_description === 'string' && user.bio_description !== '' ? <p className="profile-bio">{user.bio_description}</p> : <p className="profile-bio muted">No bio yet.</p>}
+      </div>
+    </header>
+  );
+}
+
+/** One grid tile: the post's own first frame (the twin serves no cover image), 9:16, with the play
+ *  count at the bottom left. A post whose bytes the twin does not hold shows its caption instead. */
+export function VideoTile({ video, src, onOpen }: { video: TtRow; src: string; onOpen: () => void }) {
+  const [broken, setBroken] = useState(false);
+  return (
+    <div className="tile" data-video-id={String(video.id)} onClick={onOpen} role="link" tabIndex={0} onKeyDown={(e) => { if (e.key === 'Enter') onOpen(); }}>
+      {broken ? <div className="tile-fallback"><Caption text={captionOf(video)} /></div> : (
+        <video className="tile-video" src={`${src}#t=0.1`} preload="metadata" muted playsInline onError={() => setBroken(true)}
+          onMouseEnter={(e) => { void e.currentTarget.play().catch(() => undefined); }}
+          onMouseLeave={(e) => { e.currentTarget.pause(); }} />
+      )}
+      {typeof video.view_count === 'number' ? (
+        <span className="tile-views"><Icon d={I_PLAY} size={16} />{compactCount(video.view_count)}</span>
+      ) : null}
+    </div>
+  );
+}
+
+export function VideoGrid({ videos, sourceOf, onOpen }: { videos: TtRow[]; sourceOf: (id: string) => string; onOpen: (id: string) => void }) {
+  return (
+    <div className="grid">
+      {videos.map((v) => <VideoTile key={String(v.id)} video={v} src={sourceOf(String(v.id))} onOpen={() => onOpen(String(v.id))} />)}
+    </div>
+  );
+}
+
+/** The player's overlay: @handle, the caption with its tags, and the sound line TikTok prints for a
+ *  video's own audio ("original sound - <nickname>"). */
+export function PlayerCaption({ user, video }: { user: TtRow; video: TtRow }) {
+  return (
+    <div className="player-caption">
+      <div className="player-author">@{String(user.username ?? user.display_name ?? '')}{user.is_verified === true ? <Verified size={16} /> : null}</div>
+      <div className="player-text"><Caption text={captionOf(video)} /></div>
+      <div className="player-sound"><Icon d={I_MUSIC} size={14} /><span>original sound - {String(user.display_name ?? user.username ?? '')}</span></div>
+    </div>
+  );
+}
+
+/** The right-hand action rail: the creator's avatar, then like / comment / save / share, each with the
+ *  count the Video Object carries — and no number where the Display API returns none (saves). */
+export function ActionRail({ user, video }: { user: TtRow; video: TtRow }) {
+  const count = (raw: unknown) => (typeof raw === 'number' ? compactCount(raw) : '');
+  return (
+    <div className="rail">
+      <div className="rail-avatar"><Avatar user={user} size={48} /><span className="rail-plus">+</span></div>
+      <div className="rail-item"><span className="rail-btn"><Icon d={I_HEART} fill size={26} /></span><strong>{count(video.like_count)}</strong></div>
+      <div className="rail-item"><span className="rail-btn"><Icon d={I_COMMENT} fill size={26} /></span><strong>{count(video.comment_count)}</strong></div>
+      <div className="rail-item"><span className="rail-btn"><Icon d={I_BOOKMARK} fill size={24} /></span><strong /></div>
+      <div className="rail-item"><span className="rail-btn"><Icon d={I_SHARE_ARROW} fill size={26} /></span><strong>{count(video.share_count)}</strong></div>
+    </div>
+  );
+}
+
+/** The full-height vertical player: the post playing, looped, in a 9:16 frame as tall as the window,
+ *  over a blurred copy of itself; tap to pause; the caption and the rail over it; up/down to the
+ *  neighbouring posts; close back to the profile. */
+function Player({ user, video, src, prev, next, onClose }: { user: TtRow; video: TtRow; src: string; prev?: string; next?: string; onClose: () => void }) {
+  const ref = useRef<HTMLVideoElement | null>(null);
+  const [paused, setPaused] = useState(false);
+  const [muted, setMuted] = useState(false);
+  const [time, setTime] = useState({ at: 0, of: Number(video.duration) || 0 });
+  const toggle = () => {
+    const el = ref.current;
+    if (!el) return;
+    if (el.paused) { void el.play().catch(() => undefined); setPaused(false); } else { el.pause(); setPaused(true); }
+  };
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+      if (e.key === 'ArrowUp' && prev) go(`@${user.username}/video/${prev}`);
+      if (e.key === 'ArrowDown' && next) go(`@${user.username}/video/${next}`);
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [prev, next, onClose, user.username]);
+  return (
+    <div className="player-page" data-video-id={String(video.id)}>
+      <video className="player-backdrop" src={src} muted autoPlay loop playsInline aria-hidden="true" />
+      <button className="player-close" aria-label="Close" onClick={onClose}><Icon d={I_CLOSE} size={24} /></button>
+      <div className="player-logo"><Logo size={30} /></div>
+      <div className="player-stage">
+        <div className="player-frame" onClick={toggle}>
+          <button className="player-sound-toggle" aria-label={muted ? 'Unmute' : 'Mute'} onClick={(e) => { e.stopPropagation(); setMuted(!muted); }}><Icon d={muted ? I_MUTED : I_VOLUME} size={20} /></button>
+          <video ref={ref} className="player-video" src={src} autoPlay loop playsInline muted={muted}
+            onTimeUpdate={(e) => setTime({ at: e.currentTarget.currentTime, of: e.currentTarget.duration || time.of })}
+            onPlay={() => setPaused(false)} onPause={() => setPaused(true)} />
+          {paused ? <span className="player-paused"><Icon d={I_PLAY} fill size={64} /></span> : null}
+          <div className="player-shade" />
+          <PlayerCaption user={user} video={video} />
+          <div className="player-bar" onClick={(e) => e.stopPropagation()}>
+            <button className="player-toggle" aria-label={paused ? 'Play' : 'Pause'} onClick={toggle}><Icon d={paused ? I_PLAY : I_PAUSE} fill size={18} /></button>
+            <div className="player-track"><div className="player-progress" style={{ width: `${time.of > 0 ? Math.min(100, (time.at / time.of) * 100) : 0}%` }} /></div>
+            <span className="player-time">{clock(time.at)}/{clock(time.of)}</span>
+          </div>
+        </div>
+        <ActionRail user={user} video={video} />
+      </div>
+      <div className="player-nav">
+        <button aria-label="Previous video" disabled={!prev} onClick={() => prev && go(`@${user.username}/video/${prev}`)}><Icon d={I_UP} size={26} /></button>
+        <button aria-label="Next video" disabled={!next} onClick={() => next && go(`@${user.username}/video/${next}`)}><Icon d={I_DOWN} size={26} /></button>
+      </div>
+    </div>
+  );
+}
+
+// ── the creator's videos: POST /v2/video/list/, newest first, paged on the vendor's own cursor ────
+function useVideos(session: Session | null, reloadKey: number): { videos: TtRow[]; error: string | null; more: (() => void) | null; loaded: boolean } {
+  const [videos, setVideos] = useState<TtRow[]>([]);
+  const [cursor, setCursor] = useState<number | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loaded, setLoaded] = useState(false);
+  const load = useCallback(async (from: number | null, prev: TtRow[]) => {
+    if (!session) return;
+    const w = await wire(session.token, `/v2/video/list/?fields=${VIDEO_READ_FIELDS}`, { method: 'POST', body: { max_count: VIDEO_PAGE_SIZE, ...(from !== null ? { cursor: from } : {}) } });
+    setLoaded(true);
+    if (w.status !== 200) { setError(errorCode(w) === 'scope_not_authorized' ? "This token can't read the account's videos (it needs video.list)." : errorText(w)); return; }
+    setError(null);
+    const page = Array.isArray(w.body?.data?.videos) ? w.body.data.videos as TtRow[] : [];
+    setVideos([...prev, ...page]);
+    setCursor(w.body?.data?.has_more === true ? Number(w.body.data.cursor) : null);
+  }, [session]);
+  useEffect(() => { setVideos([]); setCursor(null); setLoaded(false); void load(null, []); }, [load, reloadKey]);
+  return { videos, error, loaded, more: cursor !== null ? () => void load(cursor, videos) : null };
+}
+
+// ── screens ──────────────────────────────────────────────────────────────────────────────────────
+function SideNav({ me, active, onSignOut }: { me: TtRow | null; active: 'profile' | 'none'; onSignOut: () => void }) {
+  const item = (icon: string[], label: string, on = false, onClick?: () => void) => (
+    <button className={on ? 'nav-item active' : 'nav-item'} onClick={onClick}><Icon d={icon} size={26} /><span>{label}</span></button>
+  );
+  return (
+    <nav className="sidenav">
+      <a className="nav-logo" href={me ? `#/@${me.username}` : '#/'}><Logo /></a>
+      <div className="nav-search"><span>Search</span></div>
+      {item(I_HOME, 'For You')}
+      {item(I_EXPLORE, 'Explore')}
+      {item(I_FOLLOWING, 'Following')}
+      {item(I_FRIENDS, 'Friends')}
+      {item(I_UPLOAD, 'Upload')}
+      {item(I_LIVE, 'LIVE')}
+      {me ? (
+        <button className={active === 'profile' ? 'nav-item active' : 'nav-item'} onClick={() => go(`@${me.username}`)}>
+          <Avatar user={me} size={32} /><span>Profile</span>
+        </button>
+      ) : item(I_PROFILE, 'Profile')}
+      <div className="nav-foot">
+        {me ? <button className="nav-signout" onClick={onSignOut}>Log out @{String(me.username ?? '')}</button> : null}
+        <div className="muted">© 2026 TikTok</div>
+      </div>
+    </nav>
+  );
+}
+
+function ProfileScreen({ session, me, handle }: { session: Session; me: TtRow; handle: string }) {
+  const own = handle === String(me.username ?? '');
+  const read = useVideos(own ? session : null, 0);
+  const [tab, setTab] = useState<'videos' | 'reposts' | 'favorites' | 'liked'>('videos');
+  if (!own) {
+    // The Display API reads only the token's own account; another creator's page is not readable here.
+    return <div className="profile-missing"><h2>Couldn't find this account</h2><p className="muted">Looking for videos? Try browsing our trending creators, hashtags, and sounds.</p></div>;
+  }
+  return (
+    <div className="profile">
+      <ProfileHeader user={me} own />
+      <div className="profile-tabs">
+        <button className={tab === 'videos' ? 'ptab active' : 'ptab'} onClick={() => setTab('videos')}><Icon d={I_GRID} size={18} />Videos</button>
+        <button className={tab === 'reposts' ? 'ptab active' : 'ptab'} onClick={() => setTab('reposts')}>Reposts</button>
+        <button className={tab === 'favorites' ? 'ptab active' : 'ptab'} onClick={() => setTab('favorites')}><Icon d={I_LOCK} size={16} />Favorites</button>
+        <button className={tab === 'liked' ? 'ptab active' : 'ptab'} onClick={() => setTab('liked')}><Icon d={I_LOCK} size={16} />Liked</button>
+        {tab === 'videos' ? <div className="sort"><span className="sort-on">Latest</span><span>Popular</span><span>Oldest</span></div> : null}
+      </div>
+      {tab !== 'videos' ? <div className="empty"><h3>Nothing here yet</h3><p className="muted">This twin models the account's own posts.</p></div>
+        : read.error ? <div className="empty" role="alert">{read.error}</div>
+        : read.loaded && read.videos.length === 0 ? <div className="empty"><h3>Upload your first video</h3><p className="muted">Your videos will appear here</p></div>
+        : (
+          <>
+            <VideoGrid videos={read.videos} sourceOf={(id) => mediaSource(WIRE_BASE, id, session.token)} onOpen={(id) => go(`@${me.username}/video/${id}`)} />
+            {read.more ? <button className="show-more" onClick={read.more}>Load more</button> : null}
+          </>
+        )}
+    </div>
+  );
+}
+
+function VideoScreen({ session, me, id }: { session: Session; me: TtRow; id: string }) {
+  const read = useVideos(session, 0);
+  const at = read.videos.findIndex((v) => String(v.id) === id);
+  const close = useCallback(() => go(`@${me.username}`), [me.username]);
+  if (!read.loaded) return <div className="player-page" />;
+  if (at < 0) return <div className="player-page"><div className="player-missing">Video currently unavailable</div><button className="player-close" aria-label="Close" onClick={close}><Icon d={I_CLOSE} size={24} /></button></div>;
+  return (
+    <Player key={id} user={me} video={read.videos[at]!} src={mediaSource(WIRE_BASE, id, session.token)}
+      {...(at > 0 ? { prev: String(read.videos[at - 1]!.id) } : {})}
+      {...(at < read.videos.length - 1 ? { next: String(read.videos[at + 1]!.id) } : {})}
+      onClose={close} />
+  );
+}
+
+function LoginScreen({ onSignedIn }: { onSignedIn: (s: Session, me: TtRow) => void }) {
+  const [step, setStep] = useState<'username' | 'token'>('username');
+  const [handle, setHandle] = useState('');
+  const [token, setToken] = useState('');
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const clean = handle.trim().replace(/^@/, '');
+  const next = () => {
+    if (!/^[A-Za-z0-9_.]{2,24}$/.test(clean)) { setError("Couldn't find this account"); return; }
+    setError(null); setStep('token');
+  };
+  const login = async () => {
+    setBusy(true);
+    const w = await readMe(token.trim());
+    setBusy(false);
+    if (w.status === 401 && errorCode(w) === 'access_token_invalid') { setError('Incorrect account or password'); return; }
+    if (w.status !== 200 || !w.body?.data?.user) { setError(errorText(w)); return; }
+    const me = w.body.data.user as TtRow;
+    // Is this token THIS account's? The Display API answers the token's own account, so the answer says.
+    if (me.username !== undefined && String(me.username) !== clean) { setError(`That token does not log in as @${clean}.`); return; }
+    onSignedIn({ handle: clean, token: token.trim() }, { ...me, username: me.username ?? clean });
+  };
+  return (
+    <div className="login-backdrop">
+      <div className="login">
+        <div className="login-logo"><Logo size={40} word={false} /></div>
+        {step === 'username' ? (
+          <form className="login-form" onSubmit={(e) => { e.preventDefault(); next(); }}>
+            <h1>Log in to TikTok</h1>
+            <div className="login-sub">Username</div>
+            <input autoFocus name="username" className="login-input" placeholder="Username" value={handle} onChange={(e) => setHandle(e.target.value)} autoComplete="username" />
+            {error ? <div className="login-error" role="alert">{error}</div> : null}
+            <button className="btn-login" type="submit" disabled={clean === ''}>Next</button>
+            <div className="muted login-note">This twin logs you in with the access token it issued for the account (<code>/_twin/tokens</code>), in place of a password.</div>
+          </form>
+        ) : (
+          <form className="login-form" onSubmit={(e) => { e.preventDefault(); void login(); }}>
+            <h1>Log in</h1>
+            <div className="login-sub">@{clean} <button type="button" className="link" onClick={() => { setStep('username'); setError(null); }}>Change</button></div>
+            <input autoFocus name="token" className="login-input" type="password" placeholder="Access token" value={token} onChange={(e) => setToken(e.target.value)} autoComplete="current-password" />
+            {error ? <div className="login-error" role="alert">{error}</div> : null}
+            <button className="btn-login" type="submit" disabled={token.trim() === '' || busy}>Log in</button>
+          </form>
+        )}
+        <div className="login-foot">Don't have an account? <span className="link-red">Sign up</span></div>
+      </div>
+    </div>
+  );
+}
+
+function App() {
+  const [session, setSession] = useState<Session | null>(readSession);
+  const [me, setMe] = useState<TtRow | null>(null);
+  const [route, setRoute] = useState<Route | null>(() => parseRoute(typeof location === 'undefined' ? '' : location.hash));
+
+  useEffect(() => {
+    const onHash = () => { setRoute(parseRoute(location.hash)); window.scrollTo(0, 0); };
+    // a `#/…` link is one of the mirror's own routes; under a World's <base> the browser would resolve
+    // it against the base and leave the shell, so it moves the hash here
+    const onClick = (e: MouseEvent) => {
+      const a = (e.target as Element | null)?.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); };
+  }, []);
+
+  const signOut = useCallback(() => {
+    sessionStorage.removeItem(SESSION_HANDLE);
+    sessionStorage.removeItem(SESSION_TOKEN);
+    setSession(null);
+    setMe(null);
+    go('login');
+  }, []);
+
+  // who am I: the signed-in creator, read back through the vendor's own user read
+  useEffect(() => {
+    if (!session) { setMe(null); return; }
+    void readMe(session.token).then((w) => {
+      if (w.status === 200 && w.body?.data?.user) setMe({ ...w.body.data.user, username: w.body.data.user.username ?? session.handle });
+      else if (w.status === 401) signOut();
+    });
+  }, [session, signOut]);
+
+  const signIn = (s: Session, user: TtRow) => {
+    sessionStorage.setItem(SESSION_HANDLE, s.handle);
+    sessionStorage.setItem(SESSION_TOKEN, s.token);
+    setSession(s);
+    setMe(user);
+    go(`@${s.handle}`);
+  };
+
+  if (!session || route?.page === 'login') {
+    return session && route?.page === 'login' ? <LoginRedirect handle={session.handle} /> : <LoginScreen onSignedIn={signIn} />;
+  }
+  if (!me) return <div className="loading"><Logo /></div>;
+  const current: Route = route ?? { page: 'profile', handle: String(me.username) };
+  if (current.page === 'video') return <VideoScreen session={session} me={me} id={current.id} />;
+  return (
+    <div className="layout">
+      <SideNav me={me} active={current.page === 'profile' && current.handle === me.username ? 'profile' : 'none'} onSignOut={signOut} />
+      <main className="main">
+        <ProfileScreen session={session} me={me} handle={current.page === 'profile' ? current.handle : String(me.username)} />
+      </main>
+    </div>
+  );
+}
+
+function LoginRedirect({ handle }: { handle: string }) {
+  useEffect(() => { go(`@${handle}`); }, [handle]);
+  return null;
+}
+
+if (typeof document !== 'undefined') {
+  const el = document.getElementById('root');
+  if (el) createRoot(el).render(<App />);
+}

package/dist/src/cli.d.ts

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

package/dist/src/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// world-tiktok CLI: serve the TikTok twin, or run conformance.
+//
+// `serve` starts the twin. `mirror` starts the same twin with tiktok.com's profile and player in
+// front of it (tiktok-mirror-ui.ts: the shell at `/`, everything else the twin's own fetch adapter),
+// and prints both screens an operator asks to "see": the mirror, and a ready-to-open authorize URL
+// for the authorization page the twin serves at the vendor's own path.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { createTikTokTwinServer } from "./tiktok-server.js";
+import { createTiktokMirrorServer } from "./tiktok-mirror-ui.js";
+import { DEFAULT_CLIENT_KEY, defaultRedirectUris } from "./tiktok-store.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'); // a twin accepts writes unless started read-only
+if (cmd === 'serve' || cmd === 'mirror') {
+    const options = { readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) };
+    const s = cmd === 'mirror' ? await createTiktokMirrorServer(options) : await createTikTokTwinServer(options);
+    const origin = `http://127.0.0.1:${s.port}`;
+    process.stdout.write(`tiktok twin (Login Kit OAuth + Display API + Content Posting)${readOnly ? ' [read-only]' : ''} at ${origin}\n`);
+    if (cmd === 'mirror') {
+        process.stdout.write(`mirror (tiktok.com profile + player): ${origin}/\n`);
+        const url = new URL(`${origin}/v2/auth/authorize`);
+        url.searchParams.set('client_key', DEFAULT_CLIENT_KEY);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('redirect_uri', defaultRedirectUris(origin)[0]);
+        url.searchParams.set('scope', 'user.info.basic,user.info.profile,video.list');
+        url.searchParams.set('state', 'twin-demo-state');
+        process.stdout.write(`authorization page: ${url.toString()}\n`);
+    }
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    // dev-only; lazy so the bin runs without @volter/world-tooling in the runtime graph
+    const { checkTikTokConformance } = await import("./tiktok-conformance.js");
+    const report = await checkTikTokConformance({ ...(root ? { root } : {}) });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-tiktok serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,22 @@
+import { type TwinPack } from '@volter/world-core';
+export { ACCESS_TOKEN_TTL_SECONDS, API_ORIGIN, AUTH_CODE_TTL_SECONDS, AUTHORIZE_ORIGIN, CLIENT_TOKEN_TTL_SECONDS, handleTikTokTwinRequest, METERED_ENDPOINTS, RATE_LIMIT_PER_WINDOW, RATE_LIMITS, RATE_WINDOW_SECONDS, REFRESH_TOKEN_TTL_SECONDS, RESOURCE_TYPES, tiktokTwinSnapshot, USER_FIELDS, VIDEO_FIELDS, VIDEO_LIST_DEFAULT_COUNT, VIDEO_LIST_MAX_COUNT, VIDEO_QUERY_MAX_IDS, } from './tiktok-twin.js';
+export type { MeteredEndpoint, TikTokRequest, TikTokResponse } from './tiktok-twin.js';
+export { createTikTokConsentServer, createTikTokTwinFetch, createTikTokTwinServer, type TikTokTwinFetchOptions } from './tiktok-server.js';
+export { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_KEY, DEFAULT_CLIENT_SECRET, DEFAULT_VIDEOS, defaultRedirectUris, openIdFor, redirectUriAllowed, sessionAccount, } from './tiktok-store.js';
+export { CHALLENGE_METHOD, isSupportedChallengeMethod, isWellFormedVerifier, pkceVerifies, rfc7636Challenge, tiktokCodeChallenge } from './tiktok-pkce.js';
+export { describeScope, describeScopes, formatScopeParam, KNOWN_SCOPES, parseScopeParam, SCOPE_CATALOG, sortScopesForConsent, } from './tiktok-scopes.js';
+export type { ScopeInfo, ScopeProduct } from './tiktok-scopes.js';
+export { API_ERRORS, OAUTH_ERRORS } from './tiktok-errors.js';
+export { logId } from './tiktok-ids.js';
+export { renderUser, renderVideo, USER_FIELD_SCOPES, USER_INFO_SCOPES, VIDEO_SCOPE } from './tiktok-user.js';
+export { liveTikTokExecute, mapUserInfoAccount, mapVideo, performTikTokAction, PULL_USER_FIELDS, PULL_VIDEO_FIELDS, pullTikTok, pushPendingTikTokActions, syncTikTokFromReal, syncTikTokFromRemote, tiktokExecuteOver, } from './tiktok-connector.js';
+export type { LiveTikTokOptions, PullOptions, TikTokExecute } from './tiktok-connector.js';
+export { budgetedTikTokExecute, MAX_PUBLISH_WAIT_MS, TikTokRetryableError, PERFORM_CHUNK_BYTES, performChunkPlan, STATUS_POLL_MS, TikTokStillProcessingError, } from './tiktok-connector.js';
+export { checkChunkPlan, chunkLength, creatorOptions, DEFAULT_MAX_VIDEO_POST_DURATION_SEC, MAX_CHUNK_BYTES, MAX_CHUNK_COUNT, MAX_FINAL_CHUNK_BYTES, MAX_SERVED_RANGE, MAX_VIDEO_BYTES, MEDIA_PREFIX, MIN_CHUNK_BYTES, PRIVACY_LEVELS, processingMs, UPLOAD_ORIGIN, UPLOAD_PATH, UPLOAD_URL_TTL_MS, } from './tiktok-posting.js';
+export { POSTING_ERRORS } from './tiktok-errors.js';
+export { TIKTOK_BUDGET_BURST_CEILING, TIKTOK_BUDGET_CEILING, TIKTOK_BUDGET_MAX_RETRY_AFTER_S, TIKTOK_BUDGET_WINDOW_MS, TIKTOK_CALL_WEIGHTS, TIKTOK_RATE_BUDGET, TikTokBudget, TikTokBudgetError, tiktokBudgetPath, tiktokCallWeight, } from './tiktok-budget.js';
+export type { TikTokBudgetErrorKind, TikTokBudgetOptions, TikTokBudgetReservation, TikTokBudgetSnapshot, } from './tiktok-budget.js';
+export { CONSENT_CSS, consentPageHtml, errorPageHtml, tiktokConsentState } from './tiktok-consent-ui.js';
+export { captionOf, captionSegments, compactCount, createTiktokMirrorServer, mediaSource, profileStats } from './tiktok-mirror-ui.js';
+export type { ConsentAccount, ConsentScopeRow, ConsentView, ErrorPageProps } from './tiktok-consent-ui.js';
+export declare const pack: TwinPack;