@volter/twin-instagram 0.1.0

package/dist/src/instagram-errors.js

@@ -0,0 +1,73 @@
+// Meta's Graph API error envelope, as the Instagram Platform answers it.
+//
+// SHAPE. `{ error: { message, type, code, error_subcode?, is_transient, error_user_title?,
+// error_user_msg?, fbtrace_id } }` — the Graph API "Handle Errors" guide's sample and the Instagram
+// Platform "Error Codes" reference sample (developers.facebook.com, read 2026-09-27). Codes and
+// subcodes below are that reference's table (-2/2207020 expired, 9/2207042 publish limit,
+// 24/2207006 unknown media, 24/2207008 unknown or expired creation id, 9007/2207027 not ready,
+// 352/2207026 unsupported video format, 1/2207057 thumb offset, 36004/2207010 caption length,
+// 100/2207040 too many @ tags, 100/2207023 unknown media type) and the Graph guide's general codes
+// (190 invalid token, 10 / 200-299 permission, 100 invalid parameter).
+//
+// EVIDENCE BOUNDARY. The codes and subcodes are the docs'. The `message` wording is quoted where the
+// table gives a "User Message"; elsewhere it states the refusal plainly and is not claimed to be
+// Meta's (`instagram.errors.message_wording`). `fbtrace_id` is opaque at Meta; the twin draws it from
+// a digest of the request so the same request answers the same body (R9).
+//
+// THE RUPLOAD HOST answers its own envelope — `{ success, message }` on success and
+// `{ debug_info: { retriable, type, message } }` on failure (the Content Publishing guide's samples).
+import { blobDigest } from '@volter/world-core';
+const JSON_HEADERS = { 'content-type': 'application/json; charset=UTF-8' };
+/** The fbtrace_id of a refusal: 11 characters drawn from what was refused — stable for one request. */
+const TRACE_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+function traceId(seed) {
+    const hex = blobDigest(new TextEncoder().encode(seed));
+    let out = '';
+    for (let i = 0; i < 11; i += 1)
+        out += TRACE_ALPHABET[parseInt(hex.slice(i * 2, i * 2 + 2), 16) % 64];
+    return out;
+}
+export function graphError(status, code, message, extra = {}) {
+    return {
+        status,
+        headers: { ...JSON_HEADERS },
+        body: {
+            error: {
+                message,
+                type: extra.type ?? 'OAuthException',
+                code,
+                ...(extra.subcode !== undefined ? { error_subcode: extra.subcode } : {}),
+                is_transient: extra.transient ?? false,
+                ...(extra.title ? { error_user_title: extra.title } : {}),
+                ...(extra.userMsg ? { error_user_msg: extra.userMsg } : {}),
+                fbtrace_id: traceId(`${status}|${code}|${extra.subcode ?? ''}|${message}`),
+            },
+        },
+    };
+}
+/** No token at all. (Code 104 and its wording are the Graph API's long-standing answer; not in the
+ *  pages this build read — `instagram.errors.message_wording`.) */
+export const noToken = () => graphError(400, 104, 'An access token is required to request this resource.');
+/** A token the twin never issued. */
+export const invalidToken = () => graphError(400, 190, 'Invalid OAuth access token - Cannot parse access token');
+/** A token without the permission this edge needs (Graph code 10, "API Permission Denied"). */
+export const permissionDenied = (what) => graphError(400, 10, `(#10) Application does not have permission for this action: ${what}`);
+/** An unknown node or edge (Graph's "Unsupported get request" family, code 100 subcode 33). */
+export const unsupported = (method, id) => graphError(400, 100, `Unsupported ${method.toLowerCase()} request. Object with ID '${id}' does not exist, cannot be loaded due to missing permissions, or does not support this operation. Please read the Graph API documentation at https://developers.facebook.com/docs/graph-api`, { type: 'GraphMethodException', subcode: 33 });
+/** A path the Graph API does not know. */
+export const unknownPath = (path) => graphError(400, 2500, `Unknown path components: ${path}`);
+export const invalidParam = (message, subcode) => graphError(400, 100, `(#100) ${message}`, subcode !== undefined ? { subcode } : {});
+export const missingParam = (name) => graphError(400, 100, `(#100) The parameter ${name} is required`);
+/** Real Instagram Platform surface this twin does not model: refused by name, never answered as a success. */
+export const unmodeled = (what) => graphError(422, 100, `[twin gap] ${what} is real Instagram Platform surface this twin does not model`);
+export const readOnlyRefusal = () => graphError(405, 3, '(#3) This twin is read-only');
+export function ok(body, status = 200) {
+    return { status, body, headers: { ...JSON_HEADERS } };
+}
+// ── rupload.facebook.com ────────────────────────────────────────────────────────────────────
+export const ruploadOk = () => ok({ success: true, message: 'Upload successful.' });
+/** The rupload failure envelope. `type` names are the twin's where the guide gives only its one
+ *  sample (`ProcessingFailedError`, "unauthorized user request"). */
+export function ruploadFailure(status, type, message, retriable = false) {
+    return { status, headers: { ...JSON_HEADERS }, body: { debug_info: { retriable, type, message: JSON.stringify({ success: false, error: { message } }) } } };
+}

package/dist/src/instagram-media.d.ts

@@ -0,0 +1,134 @@
+/** "File size: 300MB maximum." Decimal, as written. */
+export declare const MAX_REEL_BYTES = 300000000;
+/** "Duration: 15 mins maximum, 3 seconds minimum." */
+export declare const MIN_REEL_MS = 3000;
+export declare const MAX_REEL_MS: number;
+/** "Maximum columns (horizontal pixels): 1920." */
+export declare const MAX_REEL_COLUMNS = 1920;
+/** "Required aspect ratio is between 0.01:1 and 10:1." */
+export declare const MIN_REEL_ASPECT = 0.01;
+export declare const MAX_REEL_ASPECT = 10;
+/** "Frame rate: 23-60 FPS." */
+export declare const MIN_REEL_FPS = 23;
+export declare const MAX_REEL_FPS = 60;
+/** "Audio codec: AAC, 48khz sample rate maximum, 1 or 2 channels." */
+export declare const MAX_AUDIO_HZ = 48000;
+/** "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 declare const MAX_REEL_BITS_PER_S: number;
+/** "Containers expire after 24 hours." */
+export declare const CONTAINER_LIFETIME_MS: number;
+/** 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 declare const PROCESSING_MS = 5000;
+/** 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 declare const SUBCODE_UNSUPPORTED_VIDEO = 2207026;
+/** "Thumbnail offset must be greater than or equal to 0 and less than video duration" (1 / 2207057). */
+export declare 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 declare function containerStatus(c: ContainerRecord, nowMs: number, published: boolean): ContainerStatus;
+/** Where the bytes of a digest live under this service's resources (the key the ranged reads take). */
+export declare const blobKey: (sha256: string) => string;
+export declare function isNumericId(id: string): boolean;
+/** Store bytes content-addressed; a re-upload of identical content is a no-op write. */
+export declare function putInstagramBlob(bytes: Uint8Array, root?: string): Promise<{
+    sha256: string;
+    size: number;
+}>;
+/** A stored blob's size, here or at an ancestor; null when absent or the digest is malformed. */
+export declare function instagramBlobSize(sha256: unknown, root?: string): Promise<number | null>;
+/** Bytes start..endInclusive of a stored blob, here or at an ancestor. */
+export declare function readInstagramBlobRange(sha256: unknown, start: number, endInclusive: number, root?: string): Promise<Uint8Array | null>;
+/** A whole stored blob (a deploy reads the Reel it uploads); null when absent. */
+export declare function readInstagramBlob(sha256: unknown, root?: string): Promise<Uint8Array | null>;
+export declare function writeContainer(record: ContainerRecord, root?: string): Promise<void>;
+export declare function readContainer(id: string, root?: string): Promise<ContainerRecord | undefined>;
+/** Every container this branch AND its retained ancestors hold (what a read could resolve). */
+export declare function listContainers(root?: string): Promise<ContainerRecord[]>;
+/** One uploaded chunk, keyed by the offset it starts at. Chunks are staging on THIS branch only. */
+export declare function putChunk(id: string, offset: number, bytes: Uint8Array, root?: string): Promise<void>;
+/** Every chunk of a container, in byte order (the seam's sorted listing; offsets are zero-padded). */
+export declare function readChunks(id: string, root?: string): Promise<Uint8Array[]>;
+export declare function clearChunks(id: string, root?: string): Promise<void>;
+/** Run `fn` after every earlier `withContainer` of the same container in this process has settled. */
+export declare function withContainer<T>(id: string, root: string | undefined, fn: () => Promise<T>): Promise<T>;
+/** `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;
+};
+export declare function readPerformContainer(actionId: string, root?: string): Promise<PerformContainer | null>;
+export declare function writePerformContainer(actionId: string, record: PerformContainer, root?: string): Promise<void>;
+export declare function clearPerformContainer(actionId: string, root?: string): Promise<void>;
+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;
+};
+export declare function sniffVideo(bytes: Uint8Array): VideoInfo | undefined;
+/** Why a file is not a publishable Reel, or undefined when it is — the spec above, in order. */
+export declare function reelSpecViolation(info: VideoInfo | undefined, size: number, thumbOffset?: number): {
+    subcode: number;
+    reason: string;
+} | undefined;
+/** An image's type and size from its header — JPEG or PNG (a seeded profile picture). */
+export declare function sniffImage(bytes: Uint8Array): {
+    mediaType: 'image/png' | 'image/jpeg';
+    width: number;
+    height: number;
+} | 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 declare function reelPosterSvg(width: number, height: number): string;

package/dist/src/instagram-media.js

@@ -0,0 +1,388 @@
+// 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;
+/**
+ * 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, nowMs, published) {
+    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) => 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) => join('blobs', 'sha256', sha256.slice(0, 2), sha256);
+const recordKey = (id) => join('containers', `${safeId(id)}.json`);
+const chunkKey = (id, offset) => join('container-chunks', safeId(id), `${String(offset).padStart(12, '0')}.part`);
+export function isNumericId(id) {
+    return /^\d{1,25}$/.test(id);
+}
+function safeId(id) {
+    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, root) {
+    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, root) {
+    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, start, endInclusive, root) {
+    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, root) {
+    if (typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256))
+        return null;
+    return readResourceBlob(SERVICE, blobKey(sha256), root);
+}
+export async function writeContainer(record, root) {
+    await getActiveBlobStore().put(join(resourcesDir(root), recordKey(record.id)), new TextEncoder().encode(JSON.stringify(record)));
+}
+export async function readContainer(id, root) {
+    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));
+        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) {
+    const ids = new Set();
+    const seen = new Set();
+    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 = [];
+    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, offset, bytes, root) {
+    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, root) {
+    const prefix = `${join(resourcesDir(root), 'container-chunks', safeId(id))}/`;
+    const keys = (await getActiveBlobStore().list(prefix)).filter((k) => k.endsWith('.part')).sort();
+    const out = [];
+    for (const key of keys) {
+        const b = await getActiveBlobStore().get(key);
+        if (b)
+            out.push(b);
+    }
+    return out;
+}
+export async function clearChunks(id, root) {
+    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();
+/** Run `fn` after every earlier `withContainer` of the same container in this process has settled. */
+export async function withContainer(id, root, fn) {
+    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);
+    }
+}
+const performKey = (actionId, root) => join(resourcesDir(root), 'perform-containers', `${blobDigest(new TextEncoder().encode(actionId))}.json`);
+export async function readPerformContainer(actionId, root) {
+    const stored = await getActiveBlobStore().get(performKey(actionId, root));
+    if (stored === null)
+        return null;
+    try {
+        const v = JSON.parse(new TextDecoder().decode(stored));
+        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, record, root) {
+    await getActiveBlobStore().put(performKey(actionId, root), new TextEncoder().encode(JSON.stringify(record)));
+}
+export async function clearPerformContainer(actionId, root) {
+    try {
+        await getActiveBlobStore().remove(performKey(actionId, root));
+    }
+    catch { /* none */ }
+}
+export function sniffVideo(bytes) {
+    const b = bytes;
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    const type = (at) => String.fromCharCode(b[at + 4], b[at + 5], b[at + 6], b[at + 7]);
+    const boxes = (start, end) => {
+        const out = [];
+        let at = start;
+        while (at + 8 <= end) {
+            let size = view.getUint32(at);
+            let header = 8;
+            if (size === 1) {
+                if (at + 16 > end)
+                    break;
+                size = Number(view.getBigUint64(at + 8));
+                header = 16;
+            }
+            else if (size === 0)
+                size = end - at;
+            if (size < header || at + size > end)
+                break;
+            out.push([type(at), at + header, at + size]);
+            at += size;
+        }
+        return out;
+    };
+    const child = (parent, name) => (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 = {
+        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, size, thumbOffset) {
+    const bad = (reason) => ({ 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) {
+    const b = bytes;
+    const u16be = (i) => (b[i] << 8) | b[i + 1];
+    const u32be = (i) => ((b[i] << 24) >>> 0) + (b[i + 1] << 16) + (b[i + 2] << 8) + b[i + 3];
+    if (b.length >= 24 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47)
+        return { mediaType: 'image/png', width: u32be(16), height: u32be(20) };
+    if (b.length >= 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, height) {
+    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/dist/src/instagram-mirror-ui.d.ts

@@ -0,0 +1,57 @@
+export type IgRow = Record<string, any>;
+/** The version the mirror's reads pin — the twin's newest. */
+export declare const MIRROR_VERSION = "v26.0";
+/** The account fields the profile header reads. */
+export declare 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 declare 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 declare function compactCount(n: unknown): string;
+/** instagram.com's age of a post: "now", "5m", "3h", "2d", "3w", then the date ("March 4" / "March 4, 2025"). */
+export declare function timeAgo(timestamp: unknown, nowMs: number): string;
+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 declare function captionSegments(caption: unknown): Segment[];
+/** 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 declare function profileFromRead(me: IgRow): MirrorProfile;
+/** Whether a media is a Reel (the Content Publishing guide: request media_product_type, since a
+ *  published Reel's media_type reads VIDEO). */
+export declare function isReel(m: IgRow): boolean;
+/** 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 declare function tabReels(reels: IgRow[], tab: 'posts' | 'reels'): IgRow[];
+/** The mirror's own route for a Reel: instagram.com's `/reel/<shortcode>/`. */
+export declare function reelRoute(shortcode: string): string;
+/** The read the grid and the viewer draw: the account's media, newest first. */
+export declare function mediaQuery(userId: string, after?: string): string;
+/** 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 declare function buildInstagramMirrorClient(): Promise<string>;
+/** Serve the Instagram mirror UI (React app) + its backing Graph API on one origin. */
+export declare function createInstagramMirrorServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    url: string;
+    stop: () => void;
+}>;
+/** The app-shell HTML (pure). */
+export declare function instagramMirrorHtml(): string;
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export declare function instagramMirrorStyles(): Promise<string>;