@volter/twin-linkedin 0.1.0

package/src/linkedin-media.ts

@@ -0,0 +1,363 @@
+// Image and video ASSETS for the LinkedIn twin — what `POST /rest/images?action=initializeUpload`,
+// `POST /rest/videos?action=initializeUpload`, the upload PUTs and `action=finalizeUpload` hold
+// before a post names the asset.
+//
+// The method is the slack pack's (slack-blobs.ts), as the X pack transcribed it (x-media.ts). Bytes
+// ride the KERNEL'S BLOB SEAM (`getActiveBlobStore()`, runtime contract R11), content-addressed by
+// sha256, under this service's own `resources` directory. An upload is NOT a kernel action: at
+// LinkedIn an uploaded image or video publishes nothing — it is an asset only a later
+// `POST /rest/posts` makes public. Recording the upload through `applyTwinWrite` would create a
+// durably pending entry with no vendor write of its own to perform, and wedge every deploy behind
+// it. So the asset record (owner, status, parts, finished digest) is a bare pointer record in the
+// same byte annex, carrying no approval weight. What becomes state is the POST: the post's own
+// entry names its asset by URN and DIGEST (linkedin-twin.ts), and that is what a deploy performs
+// (linkedin-connector.ts uploads the bytes to the vendor, then posts).
+//
+// Reads go through `readResourceBlob`, which looks in this branch and then its retained ancestors,
+// so a World branch sees assets its parent uploaded and a perform finds the bytes a post names.
+//
+// UPLOAD URLS ARE SIGNED, as LinkedIn's are. The vendor hands back an upload URL on
+// www.linkedin.com/dms-uploads/… carrying its own authorization in the query; a video part's PUT
+// carries no bearer, and an image's PUT carries the member's access token as well (the handler checks
+// it, linkedin-twin.ts `receiveUpload`). The twin signs the same way: each URL names the asset and the
+// slot (a video part, an image, a thumbnail) and carries `ut`, an HMAC-SHA256 over
+// `<asset>/<slot>/<expiresAt>` keyed by THAT ASSET'S OWN secret, drawn from entropy at initialize and
+// kept in its record. No key is shared: two clones (or branches, or processes) each sign only the assets
+// they created, a push carrying an asset carries the one secret its URLs were signed with, and nothing is
+// created on first use, so there is nothing to race. The PUT is refused unless the signature holds, its
+// expiry is the asset's own, and it has not passed.
+//
+// Every read-modify-write of an asset record runs in that asset's chain (`withAsset`).
+import { join } from 'node:path';
+import { blobDigest, getActiveBlobStore, readBranchMeta, readResourceBlob, worldPaths } from '@volter/world-core';
+
+const SERVICE = 'linkedin';
+
+export type AssetStatus = 'WAITING_UPLOAD' | 'PROCESSING' | 'AVAILABLE' | 'PROCESSING_FAILED';
+
+/** One part of a video's multipart upload, as the upload instructions name it. */
+export type VideoPart = { firstByte: number; lastByte: number; etag?: string; sha256?: string };
+
+/** The stored asset: an image or a video, keyed by its URN's id. */
+export type AssetRecord = {
+  kind: 'image' | 'video';
+  /** The asset id — the tail of `urn:li:image:<id>` / `urn:li:video:<id>`. */
+  id: string;
+  /** `urn:li:organization:<id>` (or a person) — who may attach it. */
+  owner: string;
+  status: AssetStatus;
+  created_ms: number;
+  /** Epoch ms after which the upload URLs refuse. */
+  upload_expires_ms: number;
+  /** IMAGE: the whole file. VIDEO: the assembled file once finalized. */
+  sha256?: string;
+  size?: number;
+  media_type?: string;
+  width?: number;
+  height?: number;
+  duration_ms?: number;
+  /** VIDEO: the declared size and its parts. */
+  file_size_bytes?: number;
+  parts?: VideoPart[];
+  upload_thumbnail?: boolean;
+  upload_captions?: boolean;
+  thumbnail_sha256?: string;
+  thumbnail_media_type?: string;
+  /** VIDEO: the world instant finalize accepted the file; processing completes PROCESSING_MS later. */
+  finalized_ms?: number;
+  processing_failure_reason?: string;
+  /** The asset's own upload secret (hex): the key its upload URLs are signed with. Per asset, so no key
+   *  is shared between assets, branches or clones, and nothing is ever created on first use. */
+  upload_secret: string;
+};
+
+/** LinkedIn cuts a video into 4 MB parts: 0-4194303, 4194304-8388607, … (videos-api). */
+export const VIDEO_PART_BYTES = 4_194_304;
+/** Videos API, "Video File Size Specifications": "File size: Between 75kb and 500MB." — decimal
+ *  units as written: 75,000 and 500,000,000 bytes. */
+export const MIN_VIDEO_BYTES = 75_000;
+export const MAX_VIDEO_BYTES = 500_000_000;
+/** Videos API: "Length: Three seconds to 30 minutes." */
+export const MIN_VIDEO_MS = 3_000;
+export const MAX_VIDEO_MS = 30 * 60_000;
+/** Images API: "Images with less than 36,152,320 pixels." */
+export const MAX_IMAGE_PIXELS = 36_152_320;
+/** How long (world time) a finalized video stays PROCESSING before it is AVAILABLE. A read folds the
+ *  state from the stored instant and the request's own — reading never moves anything. */
+export const PROCESSING_MS = 2_000;
+/** "Typically URLs expire 30 days from the time an upload is initialized." */
+export const UPLOAD_URL_LIFETIME_MS = 30 * 86_400_000;
+
+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('assets', `${safeId(id)}.json`);
+const partKey = (id: string, index: number): string => join('asset-parts', safeId(id), String(index).padStart(4, '0'));
+
+export function isAssetId(id: string): boolean {
+  return /^[A-Za-z0-9_-]{8,40}$/.test(id);
+}
+
+function safeId(id: string): string {
+  if (!isAssetId(id)) throw new Error(`invalid LinkedIn asset 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 putLinkedinBlob(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 };
+}
+
+/** Stored bytes by digest (this branch, then its ancestors); null when absent or malformed. */
+export async function readLinkedinBlob(sha256: string, root?: string): Promise<Uint8Array | null> {
+  if (!/^[0-9a-f]{64}$/.test(sha256)) return null;
+  return await readResourceBlob(SERVICE, blobKey(sha256), root);
+}
+
+export async function writeAsset(record: AssetRecord, root?: string): Promise<void> {
+  await getActiveBlobStore().put(join(resourcesDir(root), recordKey(record.id)), new TextEncoder().encode(JSON.stringify(record)));
+}
+
+export async function readAsset(id: string, root?: string): Promise<AssetRecord | undefined> {
+  if (!isAssetId(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 AssetRecord;
+    return typeof parsed.id === 'string' ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Whether this BRANCH holds the asset's record itself (not only an ancestor it reads through). A
+ *  branch writes only its own assets: an upload an ancestor started is finished there. */
+export async function assetIsOwn(id: string, root?: string): Promise<boolean> {
+  return isAssetId(id) && (await getActiveBlobStore().exists(join(resourcesDir(root), recordKey(id))));
+}
+
+/** Whether a record carries the per-asset upload secret its URLs are signed with (records written
+ *  before per-asset secrets have none, and are never signed with an empty key). */
+export function hasUploadSecret(asset: Pick<AssetRecord, 'upload_secret'>): boolean {
+  return typeof asset.upload_secret === 'string' && /^[0-9a-f]{64}$/.test(asset.upload_secret);
+}
+
+/** An asset as it stands at `nowMs`: a finalized video is AVAILABLE once PROCESSING_MS of world time
+ *  has passed since finalize. A pure fold of the stored record and the instant — nothing is written. */
+export function assetAsOf(asset: AssetRecord, nowMs: number): AssetRecord {
+  if (asset.kind === 'video' && asset.status === 'PROCESSING' && typeof asset.finalized_ms === 'number' && nowMs >= asset.finalized_ms + PROCESSING_MS) {
+    return { ...asset, status: 'AVAILABLE' };
+  }
+  return asset;
+}
+
+/** Every asset id this branch AND its retained ancestors hold (what a read could resolve). */
+export async function listAssetIds(root?: string): Promise<string[]> {
+  const out = 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, 'assets')}/`;
+    for (const key of await getActiveBlobStore().list(prefix)) {
+      if (key.startsWith(prefix) && !key.slice(prefix.length).includes('/') && key.endsWith('.json')) out.add(key.slice(prefix.length, -'.json'.length));
+    }
+    const parent = readBranchMeta(SERVICE, current)?.parent;
+    if (!parent) break;
+    current = parent.at;
+  }
+  return [...out];
+}
+
+/** One video part, stored under its index (a retried PUT overwrites, as a re-upload does). */
+export async function putPart(id: string, index: number, bytes: Uint8Array, root?: string): Promise<void> {
+  await getActiveBlobStore().put(join(resourcesDir(root), partKey(id, index)), bytes);
+}
+
+/** A part as stored on THIS branch. Parts are staging, not state a branch inherits: an upload is
+ *  finalized where its parts were PUT (a parent's later PUTs never leak into a child's finalize). */
+export async function readPart(id: string, index: number, root?: string): Promise<Uint8Array | null> {
+  return await getActiveBlobStore().get(join(resourcesDir(root), partKey(id, index)));
+}
+
+export async function clearParts(id: string, root?: string): Promise<void> {
+  const prefix = `${join(resourcesDir(root), 'asset-parts', safeId(id))}/`;
+  for (const key of await getActiveBlobStore().list(prefix)) {
+    try { await getActiveBlobStore().remove(key); } catch { /* already gone */ }
+  }
+}
+
+// ── signed upload URLs ────────────────────────────────────────────────────────────────────────
+
+const hex = (bytes: ArrayBuffer): string => [...new Uint8Array(bytes)].map((b) => b.toString(16).padStart(2, '0')).join('');
+
+/** A fresh per-asset upload secret: 32 bytes of entropy, hex. */
+export function newUploadSecret(): string {
+  return hex(crypto.getRandomValues(new Uint8Array(32)).buffer as ArrayBuffer);
+}
+
+/** The `ut` a signed upload URL carries for one slot of one asset, keyed by that asset's own secret. */
+export async function signUpload(asset: Pick<AssetRecord, 'id' | 'upload_secret'>, slot: string, expiresMs: number): Promise<string> {
+  // never an empty or missing key (Bun's WebCrypto refuses a zero-length HMAC key with a DataError anyway)
+  if (!hasUploadSecret(asset)) throw new Error(`linkedin: asset ${asset.id} has no upload secret to sign with`);
+  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(asset.upload_secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  return hex(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${asset.id}/${slot}/${expiresMs}`)));
+}
+
+/** Constant-time check of a presented `ut` against the one the asset's secret signs. */
+export async function verifyUpload(asset: Pick<AssetRecord, 'id' | 'upload_secret'>, slot: string, expiresMs: number, presented: string): Promise<boolean> {
+  const expected = await signUpload(asset, slot, expiresMs);
+  if (presented.length !== expected.length) return false;
+  let diff = 0;
+  for (let i = 0; i < expected.length; i += 1) diff |= expected.charCodeAt(i) ^ presented.charCodeAt(i);
+  return diff === 0;
+}
+
+// cache: one chain of pending work per asset record (`<resources dir>|<id>`): every read-modify-write
+// of `assets/<id>.json` (a part's ETag, a thumbnail, finalize) runs one after another, so concurrent
+// part PUTs keep every ETag and a late part can never overwrite a finalized record.
+const assetChains = new Map<string, Promise<unknown>>();
+
+/** Run `fn` after every earlier `withAsset` of the same asset in this process has settled. */
+export async function withAsset<T>(id: string, root: string | undefined, fn: () => Promise<T>): Promise<T> {
+  const key = `${resourcesDir(root)}|${id}`;
+  const prior = assetChains.get(key) ?? Promise.resolve();
+  const run = prior.then(fn, fn);
+  const settled = run.then(() => undefined, () => undefined);
+  assetChains.set(key, settled);
+  try { return await run; } finally { if (assetChains.get(key) === settled) assetChains.delete(key); }
+}
+
+// ── a perform's finalized video, kept across retries ─────────────────────────────────────────
+// A perform that finalized a video at the vendor and then failed (the wait, the post) keeps the
+// vendor's video URN here, keyed by the entry, so its retry posts THAT video instead of uploading the
+// file a second time (YouTube's saved session, the same annex pattern).
+
+export type PerformVideo = { video: string; sha256: string };
+const performKey = (actionId: string, root?: string): string => join(resourcesDir(root), 'perform-videos', `${blobDigest(new TextEncoder().encode(actionId))}.json`);
+
+export async function readPerformVideo(actionId: string, root?: string): Promise<PerformVideo | null> {
+  const stored = await getActiveBlobStore().get(performKey(actionId, root));
+  if (stored === null) return null;
+  try { const v = JSON.parse(new TextDecoder().decode(stored)) as PerformVideo; return typeof v.video === 'string' && typeof v.sha256 === 'string' ? v : null; } catch { return null; }
+}
+export async function writePerformVideo(actionId: string, record: PerformVideo, root?: string): Promise<void> {
+  await getActiveBlobStore().put(performKey(actionId, root), new TextEncoder().encode(JSON.stringify(record)));
+}
+export async function clearPerformVideo(actionId: string, root?: string): Promise<void> {
+  try { await getActiveBlobStore().remove(performKey(actionId, root)); } catch { /* none */ }
+}
+
+// ── what the bytes are ──────────────────────────────────────────────────────────────────────
+// LinkedIn decides an image's type and size from the bytes it received. The twin does the same:
+// the three formats the Images API accepts (JPG, GIF, PNG), read from their headers. Transcribed
+// from x-media.ts (a cross-pack import is refused by scripts/architecture.test.ts, A3).
+
+export type ImageInfo = { mediaType: 'image/png' | 'image/jpeg' | 'image/gif'; width: number; height: number };
+
+export function sniffImage(bytes: Uint8Array): ImageInfo | undefined {
+  const b = bytes;
+  const u16be = (i: number) => (b[i]! << 8) | b[i + 1]!;
+  const u16le = (i: number) => b[i]! | (b[i + 1]! << 8);
+  const u32be = (i: number) => ((b[i]! << 24) >>> 0) + (b[i + 1]! << 16) + (b[i + 2]! << 8) + b[i + 3]!;
+  if (b.length >= 24 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) {
+    return { mediaType: 'image/png', width: u32be(16), height: u32be(20) };
+  }
+  if (b.length >= 10 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38) {
+    return { mediaType: 'image/gif', width: u16le(6), height: u16le(8) };
+  }
+  if (b.length >= 4 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) {
+    let i = 2;
+    while (i + 9 < b.length) {
+      if (b[i] !== 0xff) { i += 1; continue; }
+      const marker = b[i + 1]!;
+      if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) { i += 2; continue; }
+      const length = u16be(i + 2);
+      if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return { mediaType: 'image/jpeg', height: u16be(i + 5), width: u16be(i + 7) };
+      }
+      i += 2 + length;
+    }
+  }
+  return undefined;
+}
+
+export type VideoInfo = { width: number; height: number; durationMs: number };
+
+/** An MP4 (ISO BMFF) read from its boxes: `ftyp`, then `moov` (anywhere) holding `mvhd` (timescale +
+ *  duration) and a `trak` whose `tkhd` carries the presented size. Nothing is decoded. */
+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): Array<[string, number, number]> => {
+    const out: Array<[string, number, number]> = [];
+    let at = start;
+    while (at + 8 <= end) {
+      let size = view.getUint32(at);
+      let header = 8;
+      if (size === 1) {
+        if (at + 16 > end) break;
+        size = Number(view.getBigUint64(at + 8));
+        header = 16;
+      } else if (size === 0) size = end - at;
+      if (size < header || at + size > end) break;
+      out.push([type(at), at + header, at + size]);
+      at += size;
+    }
+    return out;
+  };
+  const top = boxes(0, b.length);
+  if (top[0]?.[0] !== 'ftyp') return undefined;
+  const moov = top.find(([t]) => t === 'moov');
+  if (!moov) return undefined;
+  let durationMs: number | undefined;
+  let width = 0;
+  let height = 0;
+  for (const [t, start, end] of boxes(moov[1], moov[2])) {
+    if (t === 'mvhd' && end - start >= 32) {
+      const version = b[start]!;
+      const timescale = version === 1 ? view.getUint32(start + 20) : view.getUint32(start + 12);
+      const duration = version === 1 ? Number(view.getBigUint64(start + 24)) : view.getUint32(start + 16);
+      if (timescale > 0) durationMs = Math.round((duration * 1000) / timescale);
+    }
+    if (t === 'trak') {
+      const tkhd = boxes(start, end).find(([k]) => k === 'tkhd');
+      if (!tkhd) continue;
+      const version = b[tkhd[1]]!;
+      const at = tkhd[1] + (version === 1 ? 88 : 76);
+      if (at + 8 > tkhd[2]) continue;
+      const w = view.getUint32(at) >>> 16;
+      const h = view.getUint32(at + 4) >>> 16;
+      if (w > 0 && h > 0 && width === 0) { width = w; height = h; }
+    }
+  }
+  if (durationMs === undefined || width === 0) return undefined;
+  return { width, height, durationMs };
+}
+
+/** The reduced aspect ratio LinkedIn reports (16:9 → 16 and 9). */
+export function aspectRatio(width: number, height: number): { w: number; h: number } {
+  const gcd = (a: number, b: number): number => (b === 0 ? a : gcd(b, a % b));
+  const g = gcd(width, height) || 1;
+  return { w: width / g, h: height / g };
+}
+
+/**
+ * The system thumbnail LinkedIn cuts from a video when the uploader sends none. The twin decodes
+ * nothing, so it serves a STAND-IN at the video's own aspect — a dark frame with a play glyph — and
+ * says so here; an uploaded thumbnail (`uploadThumbnail: true`) is served as uploaded.
+ */
+export function videoPosterSvg(width: number, height: number): string {
+  const w = width > 0 ? width : 1280;
+  const h = height > 0 ? height : 720;
+  const r = Math.round(Math.min(w, h) * 0.09);
+  const cx = w / 2;
+  const cy = h / 2;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}"><rect width="${w}" height="${h}" fill="#1d2226"/>`
+    + `<circle cx="${cx}" cy="${cy}" r="${r}" fill="rgba(0,0,0,0.6)" stroke="#fff" stroke-width="${Math.max(2, r * 0.06)}"/><path d="M${cx - r * 0.3} ${cy - r * 0.45}L${cx + r * 0.5} ${cy}L${cx - r * 0.3} ${cy + r * 0.45}Z" fill="#fff"/></svg>`;
+}

package/src/linkedin-mirror-ui.ts

@@ -0,0 +1,182 @@
+// LINKEDIN MIRROR UI — linkedin.com's own view of the twin's state: an organization's company page
+// (its header with logo, name and follower line, and its Posts feed), a post card with commentary
+// and an inline video player or image or article card, and a single post's page. A React/TSX app
+// bundled by Bun that renders by consuming the twin's OWN LinkedIn API on the same origin
+// (GET /v2/userinfo, /rest/organizationAcls, /rest/organizations, /rest/networkSizes,
+// /rest/posts?q=author, /rest/posts/{urn}, /rest/images/{urn}, /rest/videos/{urn}) — the same routes
+// any LinkedIn client uses — so every screen is data-coupled to real twin state. Archetype A
+// (passthrough), transcribed from the X mirror: one serving code path, so API↔UI parity cannot drift.
+//
+// SIGN-IN. linkedin.com's own two-step sign-in (email, then password) with the password leg 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 email is checked against
+// the token's own member (`/v2/userinfo`), and the page it opens is the organization that member
+// administers (`organizationAcls?q=roleAssignee`). Both are kept in the TAB'S sessionStorage.
+//
+// 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 { createLinkedinTwinFetch } from './linkedin-server.ts';
+
+const CLIENT_ENTRY = () => new URL('../client/linkedin-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects a top-level relative import.meta.url
+const CLIENT_CSS = () => new URL('../client/linkedin-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 LiRow = Record<string, any>;
+
+/** The version the mirror's reads pin — the twin's newest. */
+export const MIRROR_VERSION = '202609';
+
+/** linkedin.com's feed timestamp: "now", "5m", "3h", "2d", "1w", "3mo", "1yr". `nowMs` is passed in. */
+export function relativeTime(ms: unknown, nowMs: number): string {
+  if (typeof ms !== 'number' || !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`;
+  if (s < 365 * 86_400) return `${Math.floor(s / (30 * 86_400))}mo`;
+  return `${Math.floor(s / (365 * 86_400))}yr`;
+}
+
+/** "12,480 followers" — the follower line under a page's name and a post's author. */
+export function followerLine(count: unknown): string {
+  const n = typeof count === 'number' && Number.isFinite(count) ? count : 0;
+  return `${n.toLocaleString('en-US')} ${n === 1 ? 'follower' : 'followers'}`;
+}
+
+export type Segment = { kind: 'text' | 'hashtag' | 'mention' | 'url'; value: string; urn?: string };
+
+/**
+ * A post's commentary as linkedin.com draws it, from the little text format LinkedIn stores:
+ * `{hashtag|\#|coding}` is the hashtag `#coding`, `@[Devtestco](urn:li:organization:2414183)` the
+ * mention `Devtestco`, a URL a link; everything else plain text (backslash escapes undone).
+ */
+export function commentarySegments(commentary: unknown): Segment[] {
+  const source = typeof commentary === 'string' ? commentary : '';
+  const out: Segment[] = [];
+  const re = /\{hashtag\|\\?#\|([^}]+)\}|@\[([^\]]+)\]\((urn:li:[A-Za-z]+:[A-Za-z0-9_-]+)\)|(https?:\/\/[^\s]+)/g;
+  let last = 0;
+  const text = (s: string) => { if (s !== '') out.push({ kind: 'text', value: s.replace(/\\([()[\]{}<>@|~_*#\\])/g, '$1') }); };
+  for (const m of source.matchAll(re)) {
+    const at = m.index ?? 0;
+    text(source.slice(last, at));
+    if (m[1] !== undefined) out.push({ kind: 'hashtag', value: `#${m[1]}` });
+    else if (m[2] !== undefined) out.push({ kind: 'mention', value: m[2], urn: m[3] });
+    else {
+      const value = m[4]!.replace(/[.,;:!?)\]'"]+$/, '');
+      out.push({ kind: 'url', value });
+      last = at + value.length;
+      continue;
+    }
+    last = at + m[0].length;
+  }
+  text(source.slice(last));
+  return out;
+}
+
+/** Whether a commentary needs linkedin.com's "…more" fold: over three lines or ~210 characters. */
+export function needsFold(commentary: unknown): boolean {
+  const s = typeof commentary === 'string' ? commentary : '';
+  return s.split('\n').length > 3 || s.length > 210;
+}
+
+/** The kind of asset a post's content names, from its URN. */
+export function mediaKind(post: LiRow): 'image' | 'video' | 'article' | undefined {
+  const content = post.content as LiRow | undefined;
+  if (content?.article) return 'article';
+  const id = content?.media?.id;
+  if (typeof id !== 'string') return undefined;
+  if (id.startsWith('urn:li:video:')) return 'video';
+  if (id.startsWith('urn:li:image:')) return 'image';
+  return undefined;
+}
+
+/** A URL's host, as an article card prints its source ("github.com"). */
+export function sourceHost(url: unknown): string {
+  try { return new URL(String(url)).host.replace(/^www\./, ''); } catch { return ''; }
+}
+
+/** A company page as the mirror draws it, from the reads it makes: the public lookup by vanity name,
+ *  the administered organization (its description; absent when the viewer is not an admin), the
+ *  follower count, and the logo image. Every field comes from those answers, nothing else. */
+export type MirrorOrg = { id: number; urn: string; name: string; vanity: string; logoUrl?: string; followers?: number; description?: string; website?: string };
+
+export function orgFromReads(pub: LiRow, admin: LiRow | null, size: LiRow | null, logo: LiRow | null): MirrorOrg {
+  return {
+    id: Number(pub.id), urn: `urn:li:organization:${pub.id}`, name: String(pub.localizedName), vanity: String(pub.vanityName),
+    ...(logo && typeof logo.downloadUrl === 'string' ? { logoUrl: logo.downloadUrl } : {}),
+    ...(size && typeof size.firstDegreeSize === 'number' ? { followers: size.firstDegreeSize } : {}),
+    ...(admin && typeof admin.localizedDescription === 'string' ? { description: admin.localizedDescription } : {}),
+    ...(typeof pub.localizedWebsite === 'string' ? { website: pub.localizedWebsite } : {}),
+  };
+}
+
+/** The mirror's own route for a post: linkedin.com's `/feed/update/<urn>`. */
+export function postRoute(urn: string): string {
+  return `#/feed/update/${encodeURIComponent(urn)}`;
+}
+
+/** The finder read a company page's feed draws. */
+export function postsQuery(orgUrn: string, start = 0): string {
+  return `/rest/posts?q=author&author=${encodeURIComponent(orgUrn)}&count=10&start=${start}&sortBy=CREATED`;
+}
+
+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>LinkedIn</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 buildLinkedinMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = bundleClient(CLIENT_ENTRY()).catch((error) => { clientBundle = null; throw error; });
+  }
+  return clientBundle;
+}
+
+/** Serve the LinkedIn mirror UI (React app) + its backing LinkedIn API on one origin. */
+export async function createLinkedinMirrorServer(options: { root?: string; port?: number; readOnly?: boolean }): Promise<{ port: number; url: string; stop: () => void }> {
+  const twin = createLinkedinTwinFetch(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 buildLinkedinMirrorClient(), { 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 createLinkedinTwinServer 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 linkedinMirrorHtml(): 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 linkedinMirrorStyles(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}