@volter/twin-instagram 0.1.0

package/src/instagram-media.ts

@@ -0,0 +1,403 @@
+// Media CONTAINERS and their BYTES for the Instagram twin — what `POST /{ig-user-id}/media` opens,
+// what the rupload host fills, and what `media_publish` makes public.
+//
+// The method is the YouTube pack's byte annex (youtube-blobs.ts) and the LinkedIn pack's asset
+// records (linkedin-media.ts). Bytes ride the KERNEL'S BLOB SEAM (`getActiveBlobStore()`, runtime
+// contract R11), content-addressed by sha256 under this service's own `resources` directory, and are
+// READ through the kernel's resource-blob helpers (`readResourceBlobRange`, `resourceBlobSize`), which
+// look in this branch and then its retained ancestors and read a RANGE natively — a seek never loads
+// the whole Reel.
+//
+// A CONTAINER IS STAGING, NOT A KERNEL ACTION. At Meta a container publishes nothing: it is a place to
+// put a video that only `media_publish` makes public, and it expires after 24 hours. Recording it
+// through `applyTwinWrite` would create a durably pending entry with no vendor write of its own and
+// wedge every deploy behind it. So the container (owner, parameters, upload progress, the finished
+// digest, the processing verdict) is a bare pointer record in the byte annex, and its uploaded chunks
+// are keys beside it. What becomes state is the PUBLISH: the media's own entry names its video by
+// DIGEST (instagram-twin.ts), and that is what a deploy performs (instagram-connector.ts creates a
+// container at Meta, uploads the bytes, waits, publishes).
+//
+// A container is authorized by the caller's ACCESS TOKEN on every request (the rupload host takes the
+// same token as the Graph API — `Authorization: OAuth <token>`); no upload URL is signed, so no secret
+// is held, and no token is ever written here or in the log.
+//
+// Every read-modify-write of a container record runs in that container's chain (`withContainer`).
+import { join } from 'node:path';
+import { blobDigest, getActiveBlobStore, readBranchMeta, readResourceBlob, readResourceBlobRange, resourceBlobSize, worldPaths } from '@volter/world-core';
+
+const SERVICE = 'instagram';
+
+// ── the Reels specification (IG User Media reference, "Reel Specifications", read 2026-09-27) ──
+
+/** "File size: 300MB maximum." Decimal, as written. */
+export const MAX_REEL_BYTES = 300_000_000;
+/** "Duration: 15 mins maximum, 3 seconds minimum." */
+export const MIN_REEL_MS = 3_000;
+export const MAX_REEL_MS = 15 * 60_000;
+/** "Maximum columns (horizontal pixels): 1920." */
+export const MAX_REEL_COLUMNS = 1920;
+/** "Required aspect ratio is between 0.01:1 and 10:1." */
+export const MIN_REEL_ASPECT = 0.01;
+export const MAX_REEL_ASPECT = 10;
+/** "Frame rate: 23-60 FPS." */
+export const MIN_REEL_FPS = 23;
+export const MAX_REEL_FPS = 60;
+/** "Audio codec: AAC, 48khz sample rate maximum, 1 or 2 channels." */
+export const MAX_AUDIO_HZ = 48_000;
+/** "Video bitrate: VBR, 25Mbps maximum"; "Audio bitrate: 128kbps". The twin reads no per-track sizes,
+ *  so it holds the file's AVERAGE bitrate (bytes × 8 over the duration) to the two together. */
+export const MAX_REEL_BITS_PER_S = 25_000_000 + 128_000;
+/** "Containers expire after 24 hours." */
+export const CONTAINER_LIFETIME_MS = 24 * 3_600_000;
+/** How long (world time) an uploaded Reel stays IN_PROGRESS before its verdict (FINISHED or ERROR).
+ *  THE TWIN'S VALUE: Meta publishes none. A read folds the state from the stored instant and the
+ *  request's own — reading never moves anything, and a frozen World clock keeps it IN_PROGRESS. */
+export const PROCESSING_MS = 5_000;
+
+/** The subcode a spec violation is answered with: "The video format is not supported. Please check
+ *  spec for supported {video} format" (Error Codes reference, 352 / 2207026). */
+export const SUBCODE_UNSUPPORTED_VIDEO = 2207026;
+/** "Thumbnail offset must be greater than or equal to 0 and less than video duration" (1 / 2207057). */
+export const SUBCODE_THUMB_OFFSET = 2207057;
+
+export type ContainerRecord = {
+  id: string;
+  /** The IG user id the container was created on. */
+  owner: string;
+  media_type: 'REELS';
+  upload_type: 'resumable';
+  caption?: string;
+  share_to_feed: boolean;
+  cover_url?: string;
+  thumb_offset?: number;
+  audio_name?: string;
+  is_ai_generated?: boolean;
+  created_ms: number;
+  /** The declared `file_size` of the rupload, fixed by its first POST. */
+  file_size?: number;
+  /** Bytes received so far, in order (the next POST's `offset` must equal this). */
+  received: number;
+  /** The world instant the last byte arrived; processing completes PROCESSING_MS later. */
+  uploaded_ms?: number;
+  sha256?: string;
+  size?: number;
+  video?: VideoInfo;
+  /** Set when processing refuses the file: the Error Codes subcode and why. */
+  error_subcode?: number;
+  error_reason?: string;
+};
+
+export type ContainerStatus = 'IN_PROGRESS' | 'FINISHED' | 'ERROR' | 'EXPIRED' | 'PUBLISHED';
+
+/**
+ * A container's status_code at `nowMs` — a pure fold of the record, the instant, and whether a
+ * published media names it: PUBLISHED once published; EXPIRED 24 h after creation if not; ERROR or
+ * FINISHED once PROCESSING_MS of world time has passed since the last byte; IN_PROGRESS before.
+ */
+export function containerStatus(c: ContainerRecord, nowMs: number, published: boolean): ContainerStatus {
+  if (published) return 'PUBLISHED';
+  if (nowMs >= c.created_ms + CONTAINER_LIFETIME_MS) return 'EXPIRED';
+  if (c.uploaded_ms === undefined || nowMs < c.uploaded_ms + PROCESSING_MS) return 'IN_PROGRESS';
+  return c.error_subcode !== undefined ? 'ERROR' : 'FINISHED';
+}
+
+const resourcesDir = (root?: string): string => worldPaths(SERVICE, root).resources;
+/** Where the bytes of a digest live under this service's resources (the key the ranged reads take). */
+export const blobKey = (sha256: string): string => join('blobs', 'sha256', sha256.slice(0, 2), sha256);
+const recordKey = (id: string): string => join('containers', `${safeId(id)}.json`);
+const chunkKey = (id: string, offset: number): string => join('container-chunks', safeId(id), `${String(offset).padStart(12, '0')}.part`);
+
+export function isNumericId(id: string): boolean {
+  return /^\d{1,25}$/.test(id);
+}
+
+function safeId(id: string): string {
+  if (!isNumericId(id)) throw new Error(`invalid Instagram container id for storage: ${JSON.stringify(id)}`);
+  return id;
+}
+
+/** Store bytes content-addressed; a re-upload of identical content is a no-op write. */
+export async function putInstagramBlob(bytes: Uint8Array, root?: string): Promise<{ sha256: string; size: number }> {
+  const sha256 = blobDigest(bytes);
+  const key = join(resourcesDir(root), blobKey(sha256));
+  if (!(await getActiveBlobStore().exists(key))) await getActiveBlobStore().put(key, bytes);
+  return { sha256, size: bytes.length };
+}
+
+/** A stored blob's size, here or at an ancestor; null when absent or the digest is malformed. */
+export async function instagramBlobSize(sha256: unknown, root?: string): Promise<number | null> {
+  if (typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256)) return null;
+  return resourceBlobSize(SERVICE, blobKey(sha256), root);
+}
+
+/** Bytes start..endInclusive of a stored blob, here or at an ancestor. */
+export async function readInstagramBlobRange(sha256: unknown, start: number, endInclusive: number, root?: string): Promise<Uint8Array | null> {
+  if (typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256)) return null;
+  return readResourceBlobRange(SERVICE, blobKey(sha256), start, endInclusive, root);
+}
+
+/** A whole stored blob (a deploy reads the Reel it uploads); null when absent. */
+export async function readInstagramBlob(sha256: unknown, root?: string): Promise<Uint8Array | null> {
+  if (typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256)) return null;
+  return readResourceBlob(SERVICE, blobKey(sha256), root);
+}
+
+export async function writeContainer(record: ContainerRecord, root?: string): Promise<void> {
+  await getActiveBlobStore().put(join(resourcesDir(root), recordKey(record.id)), new TextEncoder().encode(JSON.stringify(record)));
+}
+
+export async function readContainer(id: string, root?: string): Promise<ContainerRecord | undefined> {
+  if (!isNumericId(id)) return undefined;
+  try {
+    const stored = await readResourceBlob(SERVICE, recordKey(id), root);
+    if (stored === null) return undefined;
+    const parsed = JSON.parse(new TextDecoder().decode(stored)) as ContainerRecord;
+    return typeof parsed.id === 'string' && parsed.media_type === 'REELS' ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Every container this branch AND its retained ancestors hold (what a read could resolve). */
+export async function listContainers(root?: string): Promise<ContainerRecord[]> {
+  const ids = new Set<string>();
+  const seen = new Set<string>();
+  let current = worldPaths(SERVICE, root).root;
+  for (;;) {
+    if (seen.has(current)) break;
+    seen.add(current);
+    const prefix = `${join(worldPaths(SERVICE, current).resources, 'containers')}/`;
+    for (const key of await getActiveBlobStore().list(prefix)) {
+      if (key.startsWith(prefix) && !key.slice(prefix.length).includes('/') && key.endsWith('.json')) ids.add(key.slice(prefix.length, -'.json'.length));
+    }
+    const parent = readBranchMeta(SERVICE, current)?.parent;
+    if (!parent) break;
+    current = parent.at;
+  }
+  const out: ContainerRecord[] = [];
+  for (const id of ids) { const c = await readContainer(id, root); if (c) out.push(c); }
+  return out;
+}
+
+/** One uploaded chunk, keyed by the offset it starts at. Chunks are staging on THIS branch only. */
+export async function putChunk(id: string, offset: number, bytes: Uint8Array, root?: string): Promise<void> {
+  await getActiveBlobStore().put(join(resourcesDir(root), chunkKey(id, offset)), bytes);
+}
+
+/** Every chunk of a container, in byte order (the seam's sorted listing; offsets are zero-padded). */
+export async function readChunks(id: string, root?: string): Promise<Uint8Array[]> {
+  const prefix = `${join(resourcesDir(root), 'container-chunks', safeId(id))}/`;
+  const keys = (await getActiveBlobStore().list(prefix)).filter((k) => k.endsWith('.part')).sort();
+  const out: Uint8Array[] = [];
+  for (const key of keys) { const b = await getActiveBlobStore().get(key); if (b) out.push(b); }
+  return out;
+}
+
+export async function clearChunks(id: string, root?: string): Promise<void> {
+  const prefix = `${join(resourcesDir(root), 'container-chunks', safeId(id))}/`;
+  for (const key of await getActiveBlobStore().list(prefix)) {
+    try { await getActiveBlobStore().remove(key); } catch { /* already gone */ }
+  }
+}
+
+// cache: one chain of pending work per container record (`<resources dir>|<id>`), so two rupload POSTs
+// for one container never interleave their read-modify-write of `containers/<id>.json`.
+const chains = new Map<string, Promise<unknown>>();
+
+/** Run `fn` after every earlier `withContainer` of the same container in this process has settled. */
+export async function withContainer<T>(id: string, root: string | undefined, fn: () => Promise<T>): Promise<T> {
+  const key = `${resourcesDir(root)}|${id}`;
+  const prior = chains.get(key) ?? Promise.resolve();
+  const run = prior.then(fn, fn);
+  const settled = run.then(() => undefined, () => undefined);
+  chains.set(key, settled);
+  try { return await run; } finally { if (chains.get(key) === settled) chains.delete(key); }
+}
+
+// ── a perform's container, kept across retries ─────────────────────────────────────────────
+// A perform that uploaded a Reel to a container at Meta and then failed (the wait ran out, the publish
+// refused) keeps the vendor's container id here, keyed by the entry, so its retry publishes THAT
+// container instead of uploading the file a second time (the LinkedIn pack's kept video URN).
+
+/** `created_ms`: the LOCAL instant the container opened (its 24-hour lifetime is counted here);
+ *  `vendor_opened_ms`: the VENDOR's instant for it (a lost publish is matched on the vendor's clock);
+ *  `uploaded`: the bytes the vendor has confirmed, chunk by chunk — a retry resumes there; `unsure`: the
+ *  whole file is believed held only because a resumed POST was refused while the container processed. */
+export type PerformContainer = { container: string; sha256: string; created_ms: number; vendor_opened_ms?: number; uploaded: number; target: string; unsure?: boolean };
+const performKey = (actionId: string, root?: string): string => join(resourcesDir(root), 'perform-containers', `${blobDigest(new TextEncoder().encode(actionId))}.json`);
+
+export async function readPerformContainer(actionId: string, root?: string): Promise<PerformContainer | null> {
+  const stored = await getActiveBlobStore().get(performKey(actionId, root));
+  if (stored === null) return null;
+  try {
+    const v = JSON.parse(new TextDecoder().decode(stored)) as PerformContainer;
+    return typeof v.container === 'string' && typeof v.sha256 === 'string' && typeof v.created_ms === 'number' && typeof v.uploaded === 'number' && typeof v.target === 'string' ? v : null;
+  } catch { return null; }
+}
+export async function writePerformContainer(actionId: string, record: PerformContainer, root?: string): Promise<void> {
+  await getActiveBlobStore().put(performKey(actionId, root), new TextEncoder().encode(JSON.stringify(record)));
+}
+export async function clearPerformContainer(actionId: string, root?: string): Promise<void> {
+  try { await getActiveBlobStore().remove(performKey(actionId, root)); } catch { /* none */ }
+}
+
+// ── what the bytes are ──────────────────────────────────────────────────────────────────────
+// Meta decides a Reel's fitness from the file it received. The twin reads the same facts from the
+// ISO BMFF boxes — nothing is decoded: the brand, whether `moov` precedes `mdat` ("moov atom at the
+// front of the file"), the movie duration, and per track its handler, codec (the first stsd entry),
+// presented size (tkhd), frame count over media duration (stts, mdhd) and, for audio, the AAC entry's
+// channels and sample rate.
+
+export type VideoInfo = {
+  /** 'mp4' or 'mov' (ftyp major brand `qt  `). */
+  container: 'mp4' | 'mov';
+  moovFirst: boolean;
+  durationMs: number;
+  width: number;
+  height: number;
+  videoCodec: string;
+  fps?: number;
+  audioCodec?: string;
+  audioChannels?: number;
+  audioHz?: number;
+};
+
+type Box = [type: string, start: number, end: number];
+
+export function sniffVideo(bytes: Uint8Array): VideoInfo | undefined {
+  const b = bytes;
+  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  const type = (at: number) => String.fromCharCode(b[at + 4]!, b[at + 5]!, b[at + 6]!, b[at + 7]!);
+  const boxes = (start: number, end: number): Box[] => {
+    const out: Box[] = [];
+    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 child = (parent: Box | undefined, name: string): Box | undefined => (parent ? boxes(parent[1], parent[2]).find(([t]) => t === name) : undefined);
+  const top = boxes(0, b.length);
+  if (top[0]?.[0] !== 'ftyp') return undefined;
+  const brand = String.fromCharCode(b[top[0][1]]!, b[top[0][1] + 1]!, b[top[0][1] + 2]!, b[top[0][1] + 3]!);
+  const moovAt = top.findIndex(([t]) => t === 'moov');
+  const mdatAt = top.findIndex(([t]) => t === 'mdat');
+  if (moovAt < 0) return undefined;
+  const moov = top[moovAt]!;
+  const mvhd = child(moov, 'mvhd');
+  if (!mvhd || mvhd[2] - mvhd[1] < 32) return undefined;
+  const mv = b[mvhd[1]]!;
+  const movieScale = mv === 1 ? view.getUint32(mvhd[1] + 20) : view.getUint32(mvhd[1] + 12);
+  const movieDuration = mv === 1 ? Number(view.getBigUint64(mvhd[1] + 24)) : view.getUint32(mvhd[1] + 16);
+  if (movieScale === 0) return undefined;
+  const info: VideoInfo = {
+    container: brand === 'qt  ' ? 'mov' : 'mp4', moovFirst: mdatAt < 0 || moovAt < mdatAt,
+    durationMs: Math.round((movieDuration * 1000) / movieScale), width: 0, height: 0, videoCodec: '',
+  };
+  for (const trak of boxes(moov[1], moov[2]).filter(([t]) => t === 'trak')) {
+    const mdia = child(trak, 'mdia');
+    const hdlr = child(mdia, 'hdlr');
+    const handler = hdlr && hdlr[2] - hdlr[1] >= 12 ? String.fromCharCode(b[hdlr[1] + 8]!, b[hdlr[1] + 9]!, b[hdlr[1] + 10]!, b[hdlr[1] + 11]!) : '';
+    const stbl = child(child(mdia, 'minf'), 'stbl');
+    const stsd = child(stbl, 'stsd');
+    // stsd: version/flags (4), entry count (4), then the first sample entry box
+    const entry = stsd && stsd[2] - stsd[1] >= 16 ? stsd[1] + 8 : undefined;
+    const codec = entry !== undefined ? type(entry) : '';
+    if (handler === 'vide' && info.videoCodec === '') {
+      info.videoCodec = codec;
+      const tkhd = child(trak, 'tkhd');
+      if (tkhd) {
+        const v = b[tkhd[1]]!;
+        const at = tkhd[1] + (v === 1 ? 88 : 76);
+        if (at + 8 <= tkhd[2]) { info.width = view.getUint32(at) >>> 16; info.height = view.getUint32(at + 4) >>> 16; }
+      }
+      const mdhd = child(mdia, 'mdhd');
+      const stts = child(stbl, 'stts');
+      if (mdhd && stts && stts[2] - stts[1] >= 8) {
+        const v = b[mdhd[1]]!;
+        const scale = v === 1 ? view.getUint32(mdhd[1] + 20) : view.getUint32(mdhd[1] + 12);
+        const duration = v === 1 ? Number(view.getBigUint64(mdhd[1] + 24)) : view.getUint32(mdhd[1] + 16);
+        const n = view.getUint32(stts[1] + 4);
+        let frames = 0;
+        for (let i = 0; i < n && stts[1] + 8 + i * 8 + 8 <= stts[2]; i += 1) frames += view.getUint32(stts[1] + 8 + i * 8);
+        if (scale > 0 && duration > 0 && frames > 0) info.fps = Math.round((frames * scale * 100) / duration) / 100;
+      }
+    } else if (handler === 'soun' && info.audioCodec === undefined) {
+      info.audioCodec = codec;
+      // AudioSampleEntry: 8 box header, 6 reserved, 2 data-ref, 8 reserved, channelcount(2),
+      // samplesize(2), pre_defined(2), reserved(2), samplerate(4, 16.16)
+      if (entry !== undefined && entry + 36 <= stsd![2]) {
+        info.audioChannels = view.getUint16(entry + 24);
+        info.audioHz = view.getUint32(entry + 32) >>> 16;
+      }
+    }
+  }
+  if (info.videoCodec === '' || info.width === 0 || info.height === 0) return undefined;
+  return info;
+}
+
+/** Why a file is not a publishable Reel, or undefined when it is — the spec above, in order. */
+export function reelSpecViolation(info: VideoInfo | undefined, size: number, thumbOffset?: number): { subcode: number; reason: string } | undefined {
+  const bad = (reason: string) => ({ subcode: SUBCODE_UNSUPPORTED_VIDEO, reason });
+  if (!info) return bad('The file is not an MOV or MP4 (MPEG-4 Part 14) with a video track.');
+  if (!info.moovFirst) return bad('The moov atom is not at the front of the file.');
+  if (!['avc1', 'avc3', 'hvc1', 'hev1'].includes(info.videoCodec)) return bad(`Video codec ${info.videoCodec} is not HEVC or H264.`);
+  if (info.audioCodec !== undefined && info.audioCodec !== 'mp4a') return bad(`Audio codec ${info.audioCodec} is not AAC.`);
+  if (info.audioHz !== undefined && info.audioHz > MAX_AUDIO_HZ) return bad(`Audio sample rate ${info.audioHz} Hz is over 48 kHz.`);
+  if (info.audioChannels !== undefined && (info.audioChannels < 1 || info.audioChannels > 2)) return bad(`Audio has ${info.audioChannels} channels; 1 or 2 are accepted.`);
+  if (info.fps !== undefined && (info.fps < MIN_REEL_FPS || info.fps > MAX_REEL_FPS)) return bad(`Frame rate ${info.fps} FPS is outside 23-60 FPS.`);
+  if (info.width > MAX_REEL_COLUMNS) return bad(`${info.width} columns is over the 1920 maximum.`);
+  const aspect = info.width / info.height;
+  if (aspect < MIN_REEL_ASPECT || aspect > MAX_REEL_ASPECT) return bad(`Aspect ratio ${aspect.toFixed(3)}:1 is outside 0.01:1 to 10:1.`);
+  if (info.durationMs < MIN_REEL_MS || info.durationMs > MAX_REEL_MS) return bad(`Duration ${info.durationMs} ms is outside 3 seconds to 15 minutes.`);
+  if (size > MAX_REEL_BYTES) return bad(`File size ${size} bytes is over 300MB.`);
+  const bps = (size * 8 * 1000) / info.durationMs;
+  if (bps > MAX_REEL_BITS_PER_S) return bad(`Average bitrate ${Math.round(bps / 1000)} kbps is over the 25 Mbps video and 128 kbps audio maximum.`);
+  if (thumbOffset !== undefined && thumbOffset >= info.durationMs) {
+    return { subcode: SUBCODE_THUMB_OFFSET, reason: `Thumbnail offset must be greater than or equal to 0 and less than video duration, i.e. ${info.durationMs}` };
+  }
+  return undefined;
+}
+
+/** An image's type and size from its header — JPEG or PNG (a seeded profile picture). */
+export function sniffImage(bytes: Uint8Array): { mediaType: 'image/png' | 'image/jpeg'; width: number; height: number } | undefined {
+  const b = bytes;
+  const u16be = (i: number) => (b[i]! << 8) | b[i + 1]!;
+  const u32be = (i: number) => ((b[i]! << 24) >>> 0) + (b[i + 1]! << 16) + (b[i + 2]! << 8) + b[i + 3]!;
+  if (b.length >= 24 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return { mediaType: 'image/png', width: u32be(16), height: u32be(20) };
+  if (b.length >= 4 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) {
+    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; }
+      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 + u16be(i + 2);
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The thumbnail Meta cuts from a Reel at `thumb_offset` when no cover_url is given. The twin decodes
+ * no frames, so it serves a STAND-IN at the Reel's own aspect — a dark frame with a play glyph — and
+ * says so here (`instagram.media.frame_thumbnail`, a todo).
+ */
+export function reelPosterSvg(width: number, height: number): string {
+  const w = width > 0 ? width : 1080;
+  const h = height > 0 ? height : 1920;
+  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="#262626"/>`
+    + `<path d="M${cx - r * 0.35} ${cy - r * 0.5}L${cx + r * 0.55} ${cy}L${cx - r * 0.35} ${cy + r * 0.5}Z" fill="#fff"/></svg>`;
+}

package/src/instagram-mirror-ui.ts

@@ -0,0 +1,173 @@
+// INSTAGRAM MIRROR UI — instagram.com's own view of the twin's state: a professional account's
+// profile (its avatar, username, name, bio, and the posts / followers / following counts it holds),
+// its Reels grid (9:16 tiles with a play glyph), and a Reel viewer (a full-height vertical player with
+// the caption and username over it). A React/TSX app bundled by Bun that renders by consuming the
+// twin's OWN Graph API on the same origin (GET /v26.0/me and GET /v26.0/{ig-user-id}/media) — the same
+// routes any Instagram Platform client uses — so every screen is data-coupled to real twin state.
+// Archetype A (passthrough), transcribed from the X and LinkedIn mirrors: one serving code path, so
+// API↔UI parity cannot drift.
+//
+// SIGN-IN. instagram.com's login (username, then password) with the password replaced by the access
+// token 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. The username is checked against the token's
+// own account (`/me?fields=username`). Both are kept in the TAB'S sessionStorage.
+//
+// ROUTES are `#/…` hash routes, reached by LINKS (`<a href="#/…">`) — never by assigning location — so
+// under a World's <base> the served shell's own link handler keeps them on the shell
+// (world-core's mirror-shell.ts).
+//
+// 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, serveHttp } from '@volter/world-core';
+import { createInstagramTwinFetch } from './instagram-server.ts';
+
+const CLIENT_ENTRY = () => new URL('../client/instagram-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects a top-level relative import.meta.url
+const CLIENT_CSS = () => new URL('../client/instagram-mirror.css', import.meta.url).pathname;
+
+// ---------------------------------------------------------------------------
+// Pure, dependency-free render/format helpers (importable by the React client; Bun tree-shakes the
+// server-only exports out of the browser bundle). A capability verify renders the mirror's OWN
+// functions over twin state.
+// ---------------------------------------------------------------------------
+
+export type IgRow = Record<string, any>;
+
+/** The version the mirror's reads pin — the twin's newest. */
+export const MIRROR_VERSION = 'v26.0';
+
+/** The account fields the profile header reads. */
+export const PROFILE_FIELDS = 'id,username,name,biography,website,followers_count,follows_count,media_count,profile_picture_url';
+/** The media fields the grid and the viewer read. */
+export const REEL_FIELDS = 'id,media_type,media_product_type,media_url,thumbnail_url,permalink,caption,timestamp,shortcode,username,like_count,comments_count,is_shared_to_feed';
+
+/** instagram.com's count: "1,234" below ten thousand, then "12.5K", "1.2M" (one decimal, trailing .0 dropped). */
+export function compactCount(n: unknown): string {
+  const v = typeof n === 'number' && Number.isFinite(n) ? n : 0;
+  const one = (x: number, unit: string) => `${(Math.floor(x * 10) / 10).toFixed(1).replace(/\.0$/, '')}${unit}`;
+  if (v >= 1_000_000) return one(v / 1_000_000, 'M');
+  if (v >= 10_000) return one(v / 1_000, 'K');
+  return v.toLocaleString('en-US');
+}
+
+/** instagram.com's age of a post: "now", "5m", "3h", "2d", "3w", then the date ("March 4" / "March 4, 2025"). */
+export function timeAgo(timestamp: unknown, nowMs: number): string {
+  const ms = Date.parse(String(timestamp ?? '').replace(/([+-]\d\d)(\d\d)$/, '$1:$2'));
+  if (!Number.isFinite(ms)) return '';
+  const s = Math.max(0, Math.floor((nowMs - ms) / 1000));
+  if (s < 60) return 'now';
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86_400) return `${Math.floor(s / 3600)}h`;
+  if (s < 7 * 86_400) return `${Math.floor(s / 86_400)}d`;
+  if (s < 30 * 86_400) return `${Math.floor(s / (7 * 86_400))}w`;
+  const d = new Date(ms);
+  const month = d.toLocaleString('en-US', { month: 'long', timeZone: 'UTC' });
+  return d.getUTCFullYear() === new Date(nowMs).getUTCFullYear() ? `${month} ${d.getUTCDate()}` : `${month} ${d.getUTCDate()}, ${d.getUTCFullYear()}`;
+}
+
+export type Segment = { kind: 'text' | 'hashtag' | 'mention'; value: string };
+
+/** A caption as instagram.com draws it: `#tag` and `@user` as links, everything else text. */
+export function captionSegments(caption: unknown): Segment[] {
+  const source = typeof caption === 'string' ? caption : '';
+  const out: Segment[] = [];
+  let last = 0;
+  for (const m of source.matchAll(/(^|[^\w&])([#@])([\p{L}\p{N}_.]*[\p{L}\p{N}_])/gu)) {
+    const at = (m.index ?? 0) + m[1]!.length;
+    if (at > last) out.push({ kind: 'text', value: source.slice(last, at) });
+    out.push({ kind: m[2] === '#' ? 'hashtag' : 'mention', value: `${m[2]}${m[3]}` });
+    last = at + 1 + m[3]!.length;
+  }
+  if (last < source.length) out.push({ kind: 'text', value: source.slice(last) });
+  return out;
+}
+
+/** A profile as the mirror draws it, from the account read — every field from that answer, nothing else. */
+export type MirrorProfile = { id: string; username: string; name?: string; biography?: string; website?: string; avatarUrl?: string; posts?: number; followers?: number; following?: number };
+
+export function profileFromRead(me: IgRow): MirrorProfile {
+  return {
+    id: String(me.id), username: String(me.username),
+    ...(typeof me.name === 'string' && me.name !== '' ? { name: me.name } : {}),
+    ...(typeof me.biography === 'string' && me.biography !== '' ? { biography: me.biography } : {}),
+    ...(typeof me.website === 'string' && me.website !== '' ? { website: me.website } : {}),
+    ...(typeof me.profile_picture_url === 'string' ? { avatarUrl: me.profile_picture_url } : {}),
+    ...(typeof me.media_count === 'number' ? { posts: me.media_count } : {}),
+    ...(typeof me.followers_count === 'number' ? { followers: me.followers_count } : {}),
+    ...(typeof me.follows_count === 'number' ? { following: me.follows_count } : {}),
+  };
+}
+
+/** Whether a media is a Reel (the Content Publishing guide: request media_product_type, since a
+ *  published Reel's media_type reads VIDEO). */
+export function isReel(m: IgRow): boolean {
+  return m.media_product_type === 'REELS';
+}
+
+/** What a profile's tab shows: the Reels tab every Reel; the Posts tab only those shared to the feed
+ *  (IG Media: `is_shared_to_feed` false "indicates the reel can only appear in the Reels tab"). */
+export function tabReels(reels: IgRow[], tab: 'posts' | 'reels'): IgRow[] {
+  return tab === 'reels' ? reels : reels.filter((r) => r.is_shared_to_feed !== false);
+}
+
+/** The mirror's own route for a Reel: instagram.com's `/reel/<shortcode>/`. */
+export function reelRoute(shortcode: string): string {
+  return `#/reel/${encodeURIComponent(shortcode)}/`;
+}
+
+/** The read the grid and the viewer draw: the account's media, newest first. */
+export function mediaQuery(userId: string, after?: string): string {
+  return `/${MIRROR_VERSION}/${userId}/media?fields=${REEL_FIELDS}&limit=24${after ? `&after=${encodeURIComponent(after)}` : ''}`;
+}
+
+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>Instagram</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+
+let clientBundle: Promise<string> | null = null;
+/** Build the React/TSX mirror client to browser JS; memoized at module scope, so a pack on its own
+ *  does exactly one `Bun.build`. */
+export function buildInstagramMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = bundleClient(CLIENT_ENTRY()).catch((error) => { clientBundle = null; throw error; });
+  }
+  return clientBundle;
+}
+
+/** Serve the Instagram mirror UI (React app) + its backing Graph API on one origin. */
+export async function createInstagramMirrorServer(options: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; url: string; stop: () => void }> {
+  const twin = createInstagramTwinFetch(options);
+  const server = await serveHttp({
+    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 buildInstagramMirrorClient(), { 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 same closure createInstagramTwinServer 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). */
+export function instagramMirrorHtml(): string {
+  return APP_SHELL;
+}
+
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function instagramMirrorStyles(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}