enigma-memory 0.1.18 → 0.1.22

package/packages/snapcompact/src/index.js

@@ -0,0 +1,716 @@
+// Dense bitmap context transport inspired by the strategy in
+// @oh-my-pi/snapcompact (MIT): https://github.com/can1357/oh-my-pi/tree/main/packages/snapcompact
+// This is an independent Node implementation: it imports no upstream code or native package.
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { deflateSync, constants as zlibConstants } from 'node:zlib';
+
+export const SNAPCOMPACT_VERSION = '1.0.0';
+
+export const DEFAULT_LIMITS = deepFreeze({
+  maxCharacters: 2_000_000,
+  maxFrames: 64,
+  maxPixelsPerFrame: 4_194_304,
+  maxTotalPixels: 67_108_864,
+  maxPngBytes: 64 * 1024 * 1024,
+});
+
+const PROFILE_DEFINITIONS = {
+  anthropic: {
+    id: 'anthropic-8x13-11x16-1568',
+    provider: 'anthropic',
+    width: 1568,
+    maxHeight: 1568,
+    glyphWidth: 8,
+    glyphHeight: 13,
+    cellWidth: 11,
+    cellHeight: 16,
+    colorType: 0,
+    imageDetail: null,
+    modelFamilies: [
+      '^claude-3-(?:5|7)-sonnet(?:-[0-9]{8})?$',
+      '^claude-(?:sonnet|opus|haiku)-4(?:-[0-9]+)*(?:-[0-9]{8})?$',
+    ],
+  },
+  google: {
+    id: 'google-8x13-8x22-2048',
+    provider: 'google',
+    width: 2048,
+    maxHeight: 2048,
+    glyphWidth: 8,
+    glyphHeight: 13,
+    cellWidth: 8,
+    cellHeight: 22,
+    colorType: 0,
+    imageDetail: null,
+    modelFamilies: [
+      '^gemini-1\\.5-(?:pro|flash)(?:-[a-z0-9-]+)?$',
+      '^gemini-2\\.(?:0|5)-(?:pro|flash)(?:-[a-z0-9-]+)?$',
+      '^gemini-3(?:\\.[0-9]+)?-(?:pro|flash)(?:-[a-z0-9-]+)?$',
+    ],
+  },
+  openai: {
+    id: 'openai-8x13-8x22-1568-original',
+    provider: 'openai',
+    width: 1568,
+    maxHeight: 1568,
+    glyphWidth: 8,
+    glyphHeight: 13,
+    cellWidth: 8,
+    cellHeight: 22,
+    colorType: 0,
+    imageDetail: 'original',
+    modelFamilies: [
+      '^gpt-4o(?:-mini)?(?:-[0-9]{4}-[0-9]{2}-[0-9]{2})?$',
+      '^gpt-4\\.1(?:-mini|-nano)?(?:-[0-9]{4}-[0-9]{2}-[0-9]{2})?$',
+      '^gpt-5(?:\\.[0-9]+)?(?:-mini|-nano|-pro)?(?:-[0-9]{4}-[0-9]{2}-[0-9]{2})?$',
+    ],
+  },
+};
+
+/**
+ * Provider billing changes over time and varies by model. These estimates are
+ * deliberately labelled planning heuristics, not billing, latency, quality, or
+ * recall claims. Callers supply prices and can override both token estimates.
+ */
+export const TOKEN_ESTIMATE_ASSUMPTIONS = deepFreeze({
+  textCharactersPerToken: 4,
+  imagePixelsPerToken: 750,
+  basis: 'planning-only heuristic; verify current provider documentation and pricing before use',
+});
+
+export const PROVIDER_PROFILES = deepFreeze(Object.fromEntries(
+  Object.entries(PROFILE_DEFINITIONS).map(([provider, definition]) => [
+    provider,
+    {
+      ...definition,
+      columns: Math.floor(definition.width / definition.cellWidth),
+      rowsPerFrame: Math.floor(definition.maxHeight / definition.cellHeight),
+      tokenEstimate: TOKEN_ESTIMATE_ASSUMPTIONS,
+    },
+  ]),
+));
+
+const BDF_PATH = fileURLToPath(new URL('../assets/8x13-latin1.bdf', import.meta.url));
+let bundledFont;
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const item of Object.values(value)) deepFreeze(item);
+  return Object.freeze(value);
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function positiveInteger(value, fallback, name) {
+  const result = value === undefined ? fallback : value;
+  if (!Number.isSafeInteger(result) || result <= 0) throw new RangeError(`${name} must be a positive safe integer`);
+  return result;
+}
+
+function finiteNonNegative(value, fallback, name) {
+  const result = value === undefined ? fallback : value;
+  if (!Number.isFinite(result) || result < 0) throw new RangeError(`${name} must be a finite non-negative number`);
+  return result;
+}
+
+function mergeLimits(limits = {}) {
+  return {
+    maxCharacters: positiveInteger(limits.maxCharacters, DEFAULT_LIMITS.maxCharacters, 'maxCharacters'),
+    maxFrames: positiveInteger(limits.maxFrames, DEFAULT_LIMITS.maxFrames, 'maxFrames'),
+    maxPixelsPerFrame: positiveInteger(limits.maxPixelsPerFrame, DEFAULT_LIMITS.maxPixelsPerFrame, 'maxPixelsPerFrame'),
+    maxTotalPixels: positiveInteger(limits.maxTotalPixels, DEFAULT_LIMITS.maxTotalPixels, 'maxTotalPixels'),
+    maxPngBytes: positiveInteger(limits.maxPngBytes, DEFAULT_LIMITS.maxPngBytes, 'maxPngBytes'),
+  };
+}
+
+function codePointLabel(codePoint) {
+  return `[U+${codePoint.toString(16).toUpperCase().padStart(4, '0')}]`;
+}
+
+function elideDataUrls(input) {
+  return input.replace(
+    /data:([a-z0-9.+-]+\/[a-z0-9.+-]+)?((?:;[a-z0-9.+-]+=[^;,\s]*)*)(;base64)?,([^\s"'<>)]*)/giu,
+    (whole, mediaType = 'application/octet-stream', parameters = '', base64 = '', payload = '') => {
+      const payloadBytes = Buffer.byteLength(payload, 'utf8');
+      return `data:${mediaType}${parameters}${base64},[payload elided bytes=${payloadBytes} sha256=${sha256(payload)}]`;
+    },
+  );
+}
+
+/** Deterministically removes terminal styling and makes every unsupported code point visible. */
+export function normalizeText(input, options = {}) {
+  if (typeof input !== 'string') throw new TypeError('input must be a string');
+  const maxCharacters = positiveInteger(options.maxCharacters, DEFAULT_LIMITS.maxCharacters, 'maxCharacters');
+  if (input.length > maxCharacters) throw new RangeError(`input exceeds maxCharacters (${maxCharacters})`);
+  const tabWidth = positiveInteger(options.tabWidth, 4, 'tabWidth');
+
+  let text = elideDataUrls(input);
+  text = text
+    .replace(/\u001B\][^\u0007\u001B]*(?:\u0007|\u001B\\)/gu, '')
+    .replace(/\u001B\[[0-?]*[ -/]*[@-~]/gu, '')
+    .replace(/\u001B[@-_]/gu, '')
+    .replace(/\r\n?/gu, '\n')
+    .replace(/[\u2028\u2029]/gu, '\n')
+    .normalize('NFC');
+
+  const output = [];
+  let outputLength = 0;
+  let column = 0;
+  const append = (part) => {
+    outputLength += part.length;
+    if (outputLength > maxCharacters) throw new RangeError(`normalized text exceeds maxCharacters (${maxCharacters})`);
+    output.push(part);
+  };
+
+  for (const character of text) {
+    const codePoint = character.codePointAt(0);
+    if (character === '\n') {
+      append('\n');
+      column = 0;
+    } else if (character === '\t') {
+      const count = tabWidth - (column % tabWidth);
+      append(' '.repeat(count));
+      column += count;
+    } else if (codePoint >= 32 && codePoint <= 126 || codePoint >= 160 && codePoint <= 255) {
+      append(character);
+      column += 1;
+    } else {
+      const fallback = codePointLabel(codePoint);
+      append(fallback);
+      column += fallback.length;
+    }
+  }
+  return output.join('');
+}
+
+function summarizeBinary(value, mediaType = 'application/octet-stream') {
+  const buffer = Buffer.isBuffer(value) ? value : Buffer.from(value);
+  return `[binary mediaType=${mediaType} bytes=${buffer.byteLength} sha256=${sha256(buffer)}]`;
+}
+
+function stableJson(value, seen = new WeakSet(), depth = 0) {
+  if (depth > 32) return '"[depth-limit]"';
+  if (value === null || typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'bigint') return JSON.stringify(`${value}n`);
+  if (value === undefined) return 'null';
+  if (Buffer.isBuffer(value) || ArrayBuffer.isView(value)) return JSON.stringify(summarizeBinary(value));
+  if (value instanceof ArrayBuffer) return JSON.stringify(summarizeBinary(new Uint8Array(value)));
+  if (typeof value !== 'object') return JSON.stringify(String(value));
+  if (seen.has(value)) return '"[circular]"';
+  seen.add(value);
+  let result;
+  if (Array.isArray(value)) {
+    result = `[${value.map((item) => stableJson(item, seen, depth + 1)).join(',')}]`;
+  } else {
+    result = `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key], seen, depth + 1)}`).join(',')}}`;
+  }
+  seen.delete(value);
+  return result;
+}
+
+function capHeadTail(text, maxCharacters, label) {
+  if (text.length <= maxCharacters) return text;
+  // Binary summaries are already bounded, content-minimized atoms. Splitting
+  // one would destroy its media type, size, or digest and make the archive
+  // less useful than keeping the complete fixed-size placeholder.
+  if (/^"?\[binary mediaType=[^\]\r\n]+ bytes=\d+ sha256=[a-f0-9]{64}\]"?$/u.test(text)) {
+    return text;
+  }
+  const markerBudget = Math.min(160, Math.max(48, Math.floor(maxCharacters / 3)));
+  const available = maxCharacters - markerBudget;
+  if (available < 2) throw new RangeError(`${label} cap is too small`);
+  const headLength = Math.ceil(available / 2);
+  const tailLength = Math.floor(available / 2);
+  const omitted = text.slice(headLength, text.length - tailLength);
+  let marker = `\n[${label}: ${omitted.length} chars omitted sha256=${sha256(omitted)}]\n`;
+  if (marker.length > markerBudget) marker = marker.slice(0, markerBudget - 2) + ']\n';
+  return text.slice(0, headLength) + marker + text.slice(text.length - tailLength);
+}
+
+function blockToText(block) {
+  if (typeof block === 'string') return block;
+  if (!block || typeof block !== 'object') return stableJson(block);
+  const type = String(block.type ?? 'object').toLowerCase();
+  if (type === 'text' || type === 'input_text' || type === 'output_text') return String(block.text ?? block.content ?? '');
+  if (type === 'image' || type === 'input_image' || type === 'image_url') {
+    const source = block.source ?? block.image_url ?? block.imageUrl ?? block.data;
+    if (Buffer.isBuffer(source) || ArrayBuffer.isView(source) || source instanceof ArrayBuffer) {
+      return summarizeBinary(source, block.mediaType ?? block.mimeType ?? block.source?.media_type ?? 'image/unknown');
+    }
+    return `[image ${stableJson(source)}]`;
+  }
+  if (type === 'tool_use' || type === 'tool-call' || type === 'tool_call' || type === 'function') {
+    return `[tool-call name=${String(block.name ?? block.function?.name ?? 'unknown')} id=${String(block.id ?? '')}]\n${stableJson(block.input ?? block.arguments ?? block.function?.arguments ?? null)}`;
+  }
+  if (type === 'tool_result' || type === 'tool-result') {
+    return `[tool-result id=${String(block.tool_use_id ?? block.toolCallId ?? block.id ?? '')}]\n${contentToText(block.content ?? block.output ?? block.result ?? '')}`;
+  }
+  return `[${type}] ${stableJson(block)}`;
+}
+
+function contentToText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) return content.map(blockToText).join('\n');
+  if (content === undefined || content === null) return '';
+  return stableJson(content);
+}
+
+/** Serializes provider-neutral user/assistant/tool messages with deterministic head+tail caps. */
+export function serializeConversation(messages, options = {}) {
+  if (!Array.isArray(messages)) throw new TypeError('messages must be an array');
+  const maxMessageCharacters = positiveInteger(options.maxMessageCharacters, 24_000, 'maxMessageCharacters');
+  const maxCharacters = positiveInteger(options.maxCharacters, 500_000, 'maxCharacters');
+  const sections = messages.map((message, index) => {
+    if (!message || typeof message !== 'object') throw new TypeError(`message ${index} must be an object`);
+    const role = String(message.role ?? 'unknown').toLowerCase();
+    const metadata = [];
+    const toolName = message.name ?? message.toolName;
+    const toolCallId = message.toolCallId ?? message.tool_call_id;
+    if (toolName !== undefined) metadata.push(`name=${String(toolName)}`);
+    if (toolCallId !== undefined) metadata.push(`toolCallId=${String(toolCallId)}`);
+    const header = `--- message ${index + 1} role=${role}${metadata.length ? ` ${metadata.join(' ')}` : ''} ---`;
+    const normalized = normalizeText(contentToText(message.content ?? message.output ?? message.result ?? ''), {
+      maxCharacters: Math.max(maxCharacters, maxMessageCharacters, DEFAULT_LIMITS.maxCharacters),
+      tabWidth: options.tabWidth,
+    });
+    return `${header}\n${capHeadTail(normalized, maxMessageCharacters, 'message content')}`;
+  });
+  return capHeadTail(sections.join('\n\n'), maxCharacters, 'conversation');
+}
+
+/** Lossily run-length-compacts identical lines only when explicitly requested. */
+export function compactRepeatedLines(text, options = {}) {
+  if (typeof text !== 'string') throw new TypeError('text must be a string');
+  const minimumRun = positiveInteger(options.minimumRun, 3, 'minimumRun');
+  const lines = text.split('\n');
+  const output = [];
+  for (let index = 0; index < lines.length;) {
+    let end = index + 1;
+    while (end < lines.length && lines[end] === lines[index]) end += 1;
+    const count = end - index;
+    if (count >= minimumRun) {
+      output.push(lines[index], `[previous line repeated ${count - 1} more times]`);
+    } else {
+      for (let cursor = index; cursor < end; cursor += 1) output.push(lines[cursor]);
+    }
+    index = end;
+  }
+  return output.join('\n');
+}
+
+/** Parses an X11 BDF font into bitmap rows. No system-font APIs are used. */
+export function parseBdf(source) {
+  if (Buffer.isBuffer(source)) source = source.toString('utf8');
+  if (typeof source !== 'string') throw new TypeError('BDF source must be a string or Buffer');
+  const lines = source.replace(/\r\n?/gu, '\n').split('\n');
+  let fontBox;
+  const glyphs = new Map();
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.startsWith('FONTBOUNDINGBOX ')) {
+      const values = line.slice(16).trim().split(/\s+/u).map(Number);
+      if (values.length !== 4 || values.some((value) => !Number.isInteger(value))) throw new Error('Invalid FONTBOUNDINGBOX');
+      fontBox = { width: values[0], height: values[1], xOffset: values[2], yOffset: values[3] };
+    }
+    if (!line.startsWith('STARTCHAR ')) continue;
+    const name = line.slice(10).trim();
+    let encoding;
+    let advance;
+    let box;
+    let bitmap;
+    for (index += 1; index < lines.length && lines[index] !== 'ENDCHAR'; index += 1) {
+      const glyphLine = lines[index];
+      if (glyphLine.startsWith('ENCODING ')) encoding = Number(glyphLine.slice(9).trim().split(/\s+/u)[0]);
+      else if (glyphLine.startsWith('DWIDTH ')) advance = Number(glyphLine.slice(7).trim().split(/\s+/u)[0]);
+      else if (glyphLine.startsWith('BBX ')) {
+        const values = glyphLine.slice(4).trim().split(/\s+/u).map(Number);
+        if (values.length !== 4 || values.some((value) => !Number.isInteger(value))) throw new Error(`Invalid BBX for ${name}`);
+        box = { width: values[0], height: values[1], xOffset: values[2], yOffset: values[3] };
+      } else if (glyphLine === 'BITMAP') {
+        if (!box) throw new Error(`BITMAP precedes BBX for ${name}`);
+        bitmap = [];
+        for (let row = 0; row < box.height; row += 1) {
+          const hex = lines[++index]?.trim();
+          if (!hex || !/^[0-9A-F]+$/iu.test(hex)) throw new Error(`Invalid bitmap row for ${name}`);
+          bitmap.push(BigInt(`0x${hex}`));
+        }
+      }
+    }
+    if (Number.isInteger(encoding) && encoding >= 0) {
+      if (!box || !bitmap || bitmap.length !== box.height) throw new Error(`Incomplete glyph ${name}`);
+      glyphs.set(encoding, Object.freeze({ name, encoding, advance: advance ?? box.width, ...box, bitmap: Object.freeze(bitmap) }));
+    }
+  }
+  if (!fontBox || fontBox.width <= 0 || fontBox.height <= 0) throw new Error('BDF is missing a valid FONTBOUNDINGBOX');
+  if (glyphs.size === 0) throw new Error('BDF contains no encoded glyphs');
+  return Object.freeze({ ...fontBox, glyphs });
+}
+
+function getBundledFont() {
+  if (!bundledFont) bundledFont = parseBdf(readFileSync(BDF_PATH));
+  return bundledFont;
+}
+
+function canonicalProvider(provider) {
+  const value = String(provider ?? '').trim().toLowerCase();
+  if (value === 'gemini' || value === 'google-ai' || value === 'google-generative-ai') return 'google';
+  return value;
+}
+
+/** Returns a frozen descriptor only for an explicitly allowlisted provider/model family. */
+export function resolveProviderProfile(provider, model) {
+  const profile = PROVIDER_PROFILES[canonicalProvider(provider)];
+  const modelId = String(model ?? '').trim().toLowerCase();
+  if (!profile || !modelId) return null;
+  return profile.modelFamilies.some((pattern) => new RegExp(pattern, 'iu').test(modelId)) ? profile : null;
+}
+
+function resolveProfileRequest(profileOrRequest) {
+  if (profileOrRequest && typeof profileOrRequest === 'object' && typeof profileOrRequest.id === 'string') {
+    const known = Object.values(PROVIDER_PROFILES).find((candidate) => candidate === profileOrRequest || candidate.id === profileOrRequest.id);
+    if (!known) throw new Error('profile must be one of PROVIDER_PROFILES');
+    return known;
+  }
+  const profile = resolveProviderProfile(profileOrRequest?.provider, profileOrRequest?.model);
+  if (!profile) throw new Error('provider/model does not have a validated bitmap profile');
+  return profile;
+}
+
+function planLayout(source, profile, options = {}) {
+  const limits = mergeLimits(options.limits);
+  const normalized = options.normalized === true ? source : normalizeText(source, {
+    maxCharacters: limits.maxCharacters,
+    tabWidth: options.tabWidth,
+  });
+  if (normalized.length > limits.maxCharacters) throw new RangeError(`source exceeds maxCharacters (${limits.maxCharacters})`);
+  const renderedText = options.collapseRepeatedLines ? compactRepeatedLines(normalized, options.repetition) : normalized;
+  const columns = Math.floor(profile.width / profile.cellWidth);
+  const rowsPerFrame = Math.floor(profile.maxHeight / profile.cellHeight);
+  if (columns < 1 || rowsPerFrame < 1) throw new RangeError('profile cannot fit one glyph cell');
+
+  const rows = [];
+  for (const logicalLine of renderedText.split('\n')) {
+    const characters = Array.from(logicalLine);
+    if (characters.length === 0) rows.push('');
+    else for (let offset = 0; offset < characters.length; offset += columns) rows.push(characters.slice(offset, offset + columns).join(''));
+  }
+  const frameCount = Math.ceil(rows.length / rowsPerFrame);
+  if (frameCount > limits.maxFrames) throw new RangeError(`render requires ${frameCount} frames, exceeding maxFrames (${limits.maxFrames})`);
+
+  const pages = [];
+  let totalPixels = 0;
+  for (let frame = 0; frame < frameCount; frame += 1) {
+    const startRow = frame * rowsPerFrame;
+    const pageRows = rows.slice(startRow, startRow + rowsPerFrame);
+    const width = profile.width;
+    const height = pageRows.length * profile.cellHeight;
+    const pixels = width * height;
+    if (!Number.isSafeInteger(pixels) || pixels > limits.maxPixelsPerFrame) {
+      throw new RangeError(`frame ${frame} exceeds maxPixelsPerFrame (${limits.maxPixelsPerFrame})`);
+    }
+    totalPixels += pixels;
+    if (!Number.isSafeInteger(totalPixels) || totalPixels > limits.maxTotalPixels) {
+      throw new RangeError(`render exceeds maxTotalPixels (${limits.maxTotalPixels})`);
+    }
+    pages.push({ index: frame, width, height, rows: pageRows, rowCount: pageRows.length, startRow, endRow: startRow + pageRows.length - 1, pixels });
+  }
+  return { normalized, renderedText, columns, rowsPerFrame, frameCount, pages, totalPixels, limits };
+}
+
+/** Counts frames using the exact same wrapping and page-height algorithm as rendering. */
+export function countFrames(source, profileOrRequest, options = {}) {
+  if (typeof source !== 'string') throw new TypeError('source must be a string');
+  const profile = resolveProfileRequest(profileOrRequest);
+  const plan = planLayout(source, profile, { ...options, normalized: false });
+  return Object.freeze({
+    profileId: profile.id,
+    frameCount: plan.frameCount,
+    sourceCharacters: plan.normalized.length,
+    renderedCharacters: plan.renderedText.length,
+    columns: plan.columns,
+    rowsPerFrame: plan.rowsPerFrame,
+    rowCount: plan.pages.reduce((sum, page) => sum + page.rowCount, 0),
+    pixelCount: plan.totalPixels,
+    pages: Object.freeze(plan.pages.map((page) => Object.freeze({
+      index: page.index,
+      width: page.width,
+      height: page.height,
+      rows: page.rowCount,
+      startRow: page.startRow,
+      endRow: page.endRow,
+    }))),
+  });
+}
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let value = 0; value < 256; value += 1) {
+    let crc = value;
+    for (let bit = 0; bit < 8; bit += 1) crc = crc & 1 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1;
+    table[value] = crc >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buffers) {
+  let crc = 0xffffffff;
+  for (const buffer of buffers) for (const byte of buffer) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function pngChunk(type, data) {
+  const typeBuffer = Buffer.from(type, 'ascii');
+  const chunk = Buffer.allocUnsafe(12 + data.length);
+  chunk.writeUInt32BE(data.length, 0);
+  typeBuffer.copy(chunk, 4);
+  data.copy(chunk, 8);
+  chunk.writeUInt32BE(crc32([typeBuffer, data]), 8 + data.length);
+  return chunk;
+}
+
+function encodeGrayscalePng(pixels, width, height, maxPngBytes) {
+  const stride = width;
+  const rawBytes = (stride + 1) * height;
+  if (!Number.isSafeInteger(rawBytes) || rawBytes > maxPngBytes) throw new RangeError(`raw PNG exceeds maxPngBytes (${maxPngBytes})`);
+  const scanlines = Buffer.allocUnsafe(rawBytes);
+  for (let row = 0; row < height; row += 1) {
+    const destination = row * (stride + 1);
+    scanlines[destination] = 0;
+    pixels.copy(scanlines, destination + 1, row * stride, (row + 1) * stride);
+  }
+  const compressed = deflateSync(scanlines, { level: 9, strategy: zlibConstants.Z_DEFAULT_STRATEGY });
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width, 0);
+  header.writeUInt32BE(height, 4);
+  header[8] = 8;
+  header[9] = 0;
+  header[10] = 0;
+  header[11] = 0;
+  header[12] = 0;
+  const png = Buffer.concat([
+    Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    pngChunk('IHDR', header),
+    pngChunk('IDAT', compressed),
+    pngChunk('IEND', Buffer.alloc(0)),
+  ]);
+  if (png.length > maxPngBytes) throw new RangeError(`encoded PNG exceeds maxPngBytes (${maxPngBytes})`);
+  return png;
+}
+
+function rasterizePage(page, profile, font, maxPngBytes) {
+  const pixels = Buffer.alloc(page.pixels, 255);
+  const cellXOffset = Math.floor((profile.cellWidth - font.width) / 2);
+  const cellYOffset = Math.floor((profile.cellHeight - font.height) / 2);
+  for (let rowIndex = 0; rowIndex < page.rows.length; rowIndex += 1) {
+    const characters = Array.from(page.rows[rowIndex]);
+    for (let column = 0; column < characters.length; column += 1) {
+      const codePoint = characters[column].codePointAt(0);
+      const glyph = font.glyphs.get(codePoint);
+      if (!glyph) throw new Error(`normalized source contains missing glyph ${codePointLabel(codePoint)}`);
+      const rowOffset = font.height + font.yOffset - glyph.height - glyph.yOffset;
+      const bytesPerGlyphRow = Math.ceil(glyph.width / 8);
+      const encodedBits = bytesPerGlyphRow * 8;
+      for (let glyphRow = 0; glyphRow < glyph.height; glyphRow += 1) {
+        const y = rowIndex * profile.cellHeight + cellYOffset + rowOffset + glyphRow;
+        if (y < 0 || y >= page.height) continue;
+        for (let glyphColumn = 0; glyphColumn < glyph.width; glyphColumn += 1) {
+          const mask = 1n << BigInt(encodedBits - glyphColumn - 1);
+          if ((glyph.bitmap[glyphRow] & mask) === 0n) continue;
+          const x = column * profile.cellWidth + cellXOffset + glyph.xOffset + glyphColumn;
+          if (x >= 0 && x < page.width) pixels[y * page.width + x] = 0;
+        }
+      }
+    }
+  }
+  return encodeGrayscalePng(pixels, page.width, page.height, maxPngBytes);
+}
+
+function providerBlock(profile, png) {
+  const data = png.toString('base64');
+  if (profile.provider === 'anthropic') {
+    return { type: 'image', source: { type: 'base64', media_type: 'image/png', data } };
+  }
+  if (profile.provider === 'google') {
+    return { inlineData: { mimeType: 'image/png', data } };
+  }
+  return { type: 'input_image', image_url: `data:image/png;base64,${data}`, detail: 'original' };
+}
+
+/** Renders real, black-on-white, 8-bit grayscale PNG pages entirely in memory. */
+export function renderBitmapContext(source, request = {}) {
+  if (typeof source !== 'string') throw new TypeError('source must be a string');
+  const profile = request.profile ? resolveProfileRequest(request.profile) : resolveProfileRequest(request);
+  const plan = planLayout(source, profile, { ...request, normalized: false });
+  const font = getBundledFont();
+  if (font.width !== profile.glyphWidth || font.height !== profile.glyphHeight) throw new Error('bundled font does not match profile glyph dimensions');
+
+  const pages = plan.pages.map((page) => {
+    const png = rasterizePage(page, profile, font, plan.limits.maxPngBytes);
+    const pageSourceSha256 = sha256(`${profile.id}\0${page.rows.join('\n')}`);
+    return Object.freeze({
+      index: page.index,
+      width: page.width,
+      height: page.height,
+      png,
+      bytes: png.byteLength,
+      sha256: sha256(png),
+      sourceSha256: pageSourceSha256,
+    });
+  });
+  const sourceSha256 = sha256(plan.normalized);
+  const contextDigest = sha256(`${SNAPCOMPACT_VERSION}\0${profile.id}\0${plan.normalized}`);
+  const payloadDigest = sha256(Buffer.concat(pages.map((page) => page.png)));
+  const receipt = deepFreeze({
+    version: SNAPCOMPACT_VERSION,
+    profile: profile.id,
+    contextDigest,
+    sourceSha256,
+    payloadDigest,
+    pageSha256s: pages.map((page) => page.sha256),
+    pageSourceSha256s: pages.map((page) => page.sourceSha256),
+    sourceCharacters: plan.normalized.length,
+    renderedCharacters: plan.renderedText.length,
+    lineCount: plan.renderedText.split('\n').length,
+    frameCount: pages.length,
+    pixelCount: plan.totalPixels,
+    byteCount: pages.reduce((sum, page) => sum + page.bytes, 0),
+  });
+  return Object.freeze({
+    version: SNAPCOMPACT_VERSION,
+    profile,
+    textFallback: plan.normalized,
+    pages: Object.freeze(pages),
+    blocks: Object.freeze(pages.map((page) => deepFreeze(providerBlock(profile, page.png)))),
+    receipt,
+  });
+}
+
+function estimateTokens(plan, profile, overrides = {}) {
+  const textCharactersPerToken = finiteNonNegative(overrides.textCharactersPerToken, TOKEN_ESTIMATE_ASSUMPTIONS.textCharactersPerToken, 'textCharactersPerToken');
+  const imagePixelsPerToken = finiteNonNegative(overrides.imagePixelsPerToken, TOKEN_ESTIMATE_ASSUMPTIONS.imagePixelsPerToken, 'imagePixelsPerToken');
+  if (textCharactersPerToken === 0 || imagePixelsPerToken === 0) throw new RangeError('token estimate divisors must be greater than zero');
+  return {
+    text: Math.ceil(plan.normalized.length / textCharactersPerToken),
+    image: Math.ceil(plan.totalPixels / imagePixelsPerToken),
+    assumptions: deepFreeze({ textCharactersPerToken, imagePixelsPerToken, basis: profile.tokenEstimate.basis }),
+  };
+}
+
+/** Fail-closed eligibility and caller-priced transport comparison. */
+export function decideContextTransport(request = {}) {
+  const source = request.source;
+  if (typeof source !== 'string') throw new TypeError('source must be a string');
+  const profile = resolveProviderProfile(request.provider, request.model);
+  const textFallback = normalizeText(source, { maxCharacters: request.limits?.maxCharacters, tabWidth: request.tabWidth });
+  const fallback = (reason, extra = {}) => deepFreeze({
+    selected: 'text',
+    eligible: false,
+    reason,
+    profile: profile?.id ?? null,
+    textFallback,
+    ...extra,
+  });
+  if (request.vision !== true) return fallback('vision-capability-required');
+  if (!profile) return fallback('unvalidated-model-profile');
+  if (!request.costs || typeof request.costs !== 'object') return fallback('cost-input-required');
+
+  const plan = planLayout(textFallback, profile, { ...request, normalized: true });
+  const tokens = estimateTokens(plan, profile, request.tokenEstimates);
+  if (request.costs.textInputUsdPerMillion === undefined || request.costs.imageInputUsdPerMillion === undefined) {
+    return fallback('cost-input-required');
+  }
+  const expectedReuse = positiveInteger(request.expectedReuse, 1, 'expectedReuse');
+  const textInputUsdPerMillion = finiteNonNegative(request.costs.textInputUsdPerMillion, 0, 'textInputUsdPerMillion');
+  const imageInputUsdPerMillion = finiteNonNegative(request.costs.imageInputUsdPerMillion, 0, 'imageInputUsdPerMillion');
+  const outputUsdPerMillion = finiteNonNegative(request.costs.outputUsdPerMillion, 0, 'outputUsdPerMillion');
+  const decodeOutputTokens = finiteNonNegative(request.costs.decodeOutputTokens, 0, 'decodeOutputTokens');
+  const decodeFixedUsd = finiteNonNegative(request.costs.decodeFixedUsd, 0, 'decodeFixedUsd');
+  const textUsd = tokens.text * textInputUsdPerMillion / 1_000_000 * expectedReuse;
+  const imageInputUsd = tokens.image * imageInputUsdPerMillion / 1_000_000 * expectedReuse;
+  const oneTimeDecodeUsd = decodeOutputTokens * outputUsdPerMillion / 1_000_000 + decodeFixedUsd;
+  const imageUsd = imageInputUsd + oneTimeDecodeUsd;
+  const selected = imageUsd < textUsd ? 'bitmap-png' : 'text';
+  return deepFreeze({
+    selected,
+    eligible: true,
+    reason: selected === 'bitmap-png' ? 'lower-estimated-input-cost' : 'text-is-lossless-or-not-more-expensive',
+    profile: profile.id,
+    textFallback,
+    expectedReuse,
+    frameCount: plan.frameCount,
+    estimates: {
+      textTokens: tokens.text,
+      imageTokens: tokens.image,
+      textUsd,
+      imageInputUsd,
+      oneTimeDecodeUsd,
+      imageUsd,
+      assumptions: tokens.assumptions,
+    },
+  });
+}
+
+function textDescriptor(text) {
+  const bytes = Buffer.byteLength(text, 'utf8');
+  const digest = sha256(text);
+  return deepFreeze({
+    codec: 'utf8',
+    version: SNAPCOMPACT_VERSION,
+    profile: null,
+    contextDigest: digest,
+    payloadDigest: digest,
+    dimensions: [],
+    bytes,
+    counts: { characters: text.length, frames: 0, pixels: 0 },
+  });
+}
+
+/** SDK-facing context pack: always includes recoverable normalized text fallback. */
+export function createContextCarrier(request = {}) {
+  if ((request.source === undefined) === (request.messages === undefined)) {
+    throw new TypeError('provide exactly one of source or messages');
+  }
+  const source = request.messages === undefined
+    ? normalizeText(request.source, { maxCharacters: request.limits?.maxCharacters, tabWidth: request.tabWidth })
+    : serializeConversation(request.messages, request.serialization);
+  const decision = decideContextTransport({ ...request, source });
+  if (decision.selected !== 'bitmap-png') {
+    return Object.freeze({
+      selected: 'text',
+      textFallback: decision.textFallback,
+      blocks: Object.freeze([]),
+      pages: Object.freeze([]),
+      descriptor: textDescriptor(decision.textFallback),
+      decision,
+    });
+  }
+  const rendered = renderBitmapContext(decision.textFallback, request);
+  const descriptor = deepFreeze({
+    codec: 'bitmap-png',
+    version: SNAPCOMPACT_VERSION,
+    profile: rendered.profile.id,
+    contextDigest: rendered.receipt.contextDigest,
+    payloadDigest: rendered.receipt.payloadDigest,
+    dimensions: rendered.pages.map((page) => ({ width: page.width, height: page.height })),
+    bytes: rendered.receipt.byteCount,
+    counts: {
+      characters: rendered.receipt.sourceCharacters,
+      frames: rendered.receipt.frameCount,
+      pixels: rendered.receipt.pixelCount,
+    },
+  });
+  return Object.freeze({
+    selected: 'bitmap-png',
+    textFallback: rendered.textFallback,
+    blocks: rendered.blocks,
+    pages: rendered.pages,
+    descriptor,
+    decision,
+  });
+}