pixelweaver 0.1.0

package/src/lib/export/download.ts

@@ -0,0 +1,201 @@
+/**
+ * Platform-adaptive file download helper.
+ *
+ * On desktop (pywebview): opens a native save dialog, then writes the file
+ * via the pywebview bridge. For batch exports, opens a directory picker
+ * and writes all files into the chosen folder.
+ *
+ * On browser: falls back to the classic <a download> trick with
+ * URL.createObjectURL.
+ */
+
+// ---------------------------------------------------------------------------
+// Base64 helper
+// ---------------------------------------------------------------------------
+
+function uint8ArrayToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]!);
+  }
+  return btoa(binary);
+}
+
+// ---------------------------------------------------------------------------
+// Desktop detection
+// ---------------------------------------------------------------------------
+
+/** Check if running inside a pywebview desktop window. */
+export function isDesktop(): boolean {
+  return !!window.pywebview;
+}
+
+// ---------------------------------------------------------------------------
+// Single-file download
+// ---------------------------------------------------------------------------
+
+export interface DownloadFileOptions {
+  /** The blob to save. */
+  blob: Blob;
+  /** Suggested filename including extension (e.g. "sprite.png"). */
+  filename: string;
+  /** Filter label for the native dialog (e.g. "PNG Image"). */
+  filterName?: string;
+  /** Allowed extensions without dot (e.g. ["png"]). */
+  filterExtensions?: string[];
+}
+
+/**
+ * Download / save a single file. On desktop a native save dialog is shown;
+ * on browser the file is downloaded directly.
+ *
+ * Returns `true` if the file was saved, `false` if the user cancelled
+ * the native dialog (browser always returns `true`).
+ */
+export async function downloadFile(opts: DownloadFileOptions): Promise<boolean> {
+  if (isDesktop()) {
+    return downloadFileDesktop(opts);
+  }
+  downloadFileBrowser(opts.blob, opts.filename);
+  return true;
+}
+
+async function downloadFileDesktop(opts: DownloadFileOptions): Promise<boolean> {
+  const ext = opts.filterExtensions
+    ?? [opts.filename.split('.').pop() ?? 'bin'];
+  const filterName = opts.filterName
+    ?? ext.map((e) => e.toUpperCase()).join('/') + ' File';
+
+  const buffer = new Uint8Array(await opts.blob.arrayBuffer());
+  const b64 = uint8ArrayToBase64(buffer);
+
+  const path = await window.pywebview!.api.save_file(
+    b64, opts.filename, filterName, ext,
+  );
+  return path !== null;
+}
+
+function downloadFileBrowser(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  setTimeout(() => {
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+  }, 100);
+}
+
+// ---------------------------------------------------------------------------
+// Multi-file download (batch)
+// ---------------------------------------------------------------------------
+
+export interface BatchFileEntry {
+  blob: Blob;
+  filename: string;
+}
+
+/**
+ * Download multiple files. On desktop a directory picker is shown and all
+ * files are written into the chosen folder. On browser the files are
+ * downloaded sequentially with a small delay between each to avoid
+ * throttling.
+ *
+ * Returns `true` if files were saved, `false` if the user cancelled
+ * the directory picker (browser always returns `true`).
+ */
+export async function downloadBatch(entries: BatchFileEntry[]): Promise<boolean> {
+  if (entries.length === 0) return true;
+  if (isDesktop()) {
+    return downloadBatchDesktop(entries);
+  }
+  downloadBatchBrowser(entries, 0);
+  return true;
+}
+
+async function downloadBatchDesktop(entries: BatchFileEntry[]): Promise<boolean> {
+  const dir = await window.pywebview!.api.pick_directory();
+  if (!dir) return false;
+
+  const files = await Promise.all(
+    entries.map(async (entry) => ({
+      name: entry.filename,
+      data: uint8ArrayToBase64(new Uint8Array(await entry.blob.arrayBuffer())),
+    })),
+  );
+
+  return window.pywebview!.api.write_files_to_directory(dir, files);
+}
+
+/**
+ * Trigger browser downloads one at a time with a small delay between
+ * each to prevent the browser from blocking rapid successive downloads.
+ */
+function downloadBatchBrowser(entries: BatchFileEntry[], index: number): void {
+  if (index >= entries.length) return;
+  const entry = entries[index];
+  if (!entry) return;
+  downloadFileBrowser(entry.blob, entry.filename);
+  // 50ms gap so the browser does not throttle/block consecutive downloads.
+  setTimeout(() => { downloadBatchBrowser(entries, index + 1); }, 50);
+}
+
+// ---------------------------------------------------------------------------
+// Multi-file companion download (e.g. PNG + JSON from same export)
+// ---------------------------------------------------------------------------
+
+/**
+ * Download multiple companion files from a single export operation.
+ * On desktop the first file gets a save dialog; subsequent files are written
+ * to the same directory as the first. On browser each file is downloaded.
+ *
+ * Returns `true` if files were saved, `false` if the user cancelled.
+ */
+export async function downloadCompanionFiles(
+  entries: DownloadFileOptions[],
+): Promise<boolean> {
+  if (entries.length === 0) return true;
+  if (isDesktop()) {
+    return downloadCompanionFilesDesktop(entries);
+  }
+  // Browser: download each file sequentially
+  for (const entry of entries) {
+    downloadFileBrowser(entry.blob, entry.filename);
+  }
+  return true;
+}
+
+async function downloadCompanionFilesDesktop(
+  entries: DownloadFileOptions[],
+): Promise<boolean> {
+  // Show save dialog for the first (primary) file
+  const first = entries[0]!;
+  const ext = first.filterExtensions
+    ?? [first.filename.split('.').pop() ?? 'bin'];
+  const filterName = first.filterName
+    ?? ext.map((e) => e.toUpperCase()).join('/') + ' File';
+
+  const buffer = new Uint8Array(await first.blob.arrayBuffer());
+  const b64 = uint8ArrayToBase64(buffer);
+
+  const path = await window.pywebview!.api.save_file(
+    b64, first.filename, filterName, ext,
+  );
+  if (!path) return false;
+
+  // Write companion files to the same directory
+  if (entries.length > 1) {
+    const dir = path.substring(0, path.lastIndexOf('/'));
+    const companionFiles = await Promise.all(
+      entries.slice(1).map(async (entry) => ({
+        name: entry.filename,
+        data: uint8ArrayToBase64(new Uint8Array(await entry.blob.arrayBuffer())),
+      })),
+    );
+    await window.pywebview!.api.write_files_to_directory(dir, companionFiles);
+  }
+
+  return true;
+}

package/src/lib/export/png-metadata.ts

@@ -0,0 +1,181 @@
+/**
+ * PNG metadata injection -- embeds tEXt chunks into PNG files.
+ *
+ * PNG files have a well-defined chunk structure. After the 8-byte signature,
+ * the file is a sequence of chunks: [4-byte length][4-byte type][data][4-byte CRC].
+ * tEXt chunks store key-value pairs separated by a null byte.
+ *
+ * This module inserts tEXt chunks after IHDR and before the first IDAT chunk,
+ * which is the standard location for ancillary metadata chunks.
+ */
+
+// --- CRC32 ---
+
+/** Pre-computed CRC32 lookup table (IEEE polynomial 0xEDB88320). */
+const crcTable = buildCrcTable();
+
+function buildCrcTable(): Uint32Array {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[n] = c;
+  }
+  return table;
+}
+
+/** Compute CRC32 over one or more byte arrays. */
+function crc32(...buffers: Uint8Array[]): number {
+  let crc = 0xffffffff;
+  // Uint8Array indexing is `number | undefined` under noUncheckedIndexedAccess;
+  // ?? 0 fallbacks never trigger because i < buf.length and the table is dense.
+  for (const buf of buffers) {
+    for (let i = 0; i < buf.length; i++) {
+      crc = (crcTable[(crc ^ (buf[i] ?? 0)) & 0xff] ?? 0) ^ (crc >>> 8);
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+// --- Text encoding helpers ---
+
+const textEncoder = new TextEncoder();
+
+/** Encode a string as Latin-1 bytes (values > 255 are clamped). */
+function toLatin1(str: string): Uint8Array {
+  const bytes = new Uint8Array(str.length);
+  for (let i = 0; i < str.length; i++) {
+    bytes[i] = str.charCodeAt(i) & 0xff;
+  }
+  return bytes;
+}
+
+// --- tEXt chunk construction ---
+
+/** PNG chunk type identifier for tEXt. */
+const TEXT_TYPE = textEncoder.encode('tEXt');
+
+/**
+ * Build a complete PNG tEXt chunk (length + type + data + CRC).
+ *
+ * tEXt data format: keyword (1-79 Latin-1 chars) + null byte + value (Latin-1).
+ * The CRC covers the type field and data, but not the length field.
+ */
+function buildTextChunk(key: string, value: string): Uint8Array {
+  // Clamp key to 79 characters per PNG spec
+  const clampedKey = key.slice(0, 79);
+  const keyBytes = toLatin1(clampedKey);
+  const valueBytes = toLatin1(value);
+
+  // data = key + \0 + value
+  const dataLength = keyBytes.length + 1 + valueBytes.length;
+  // chunk = 4 (length) + 4 (type) + dataLength + 4 (CRC)
+  const chunk = new Uint8Array(4 + 4 + dataLength + 4);
+  const view = new DataView(chunk.buffer);
+
+  // Write length (big-endian)
+  view.setUint32(0, dataLength);
+
+  // Write chunk type "tEXt"
+  chunk.set(TEXT_TYPE, 4);
+
+  // Write key + null separator + value
+  chunk.set(keyBytes, 8);
+  chunk[8 + keyBytes.length] = 0;
+  chunk.set(valueBytes, 8 + keyBytes.length + 1);
+
+  // Compute CRC over type + data
+  const crcData = chunk.slice(4, 8 + dataLength);
+  const crcValue = crc32(crcData);
+  view.setUint32(8 + dataLength, crcValue);
+
+  return chunk;
+}
+
+// --- PNG parsing helpers ---
+
+/** PNG magic signature (8 bytes). */
+const PNG_SIGNATURE_LENGTH = 8;
+
+/**
+ * Read a 4-byte ASCII chunk type from a DataView at the given offset.
+ */
+function readChunkType(view: DataView, offset: number): string {
+  return String.fromCharCode(
+    view.getUint8(offset),
+    view.getUint8(offset + 1),
+    view.getUint8(offset + 2),
+    view.getUint8(offset + 3),
+  );
+}
+
+/**
+ * Find the byte offset of the first IDAT chunk in a PNG buffer.
+ *
+ * Walks the chunk list starting after the 8-byte signature.
+ * Returns the offset of the IDAT chunk's length field, which is where
+ * we want to splice in tEXt chunks.
+ */
+function findFirstIdatOffset(view: DataView): number {
+  let offset = PNG_SIGNATURE_LENGTH;
+
+  while (offset < view.byteLength) {
+    const chunkDataLength = view.getUint32(offset);
+    const chunkType = readChunkType(view, offset + 4);
+
+    if (chunkType === 'IDAT') {
+      return offset;
+    }
+
+    // Advance past this chunk: 4 (length) + 4 (type) + data + 4 (CRC)
+    offset += 4 + 4 + chunkDataLength + 4;
+  }
+
+  throw new Error('PNG has no IDAT chunk -- file is malformed.');
+}
+
+// --- Public API ---
+
+/**
+ * Embed tEXt metadata key-value pairs into a PNG blob.
+ *
+ * Inserts tEXt chunks after IHDR and before the first IDAT chunk.
+ * Returns a new Blob; the original is not mutated.
+ */
+export async function embedPngMetadata(
+  pngBlob: Blob,
+  metadata: Record<string, string>,
+): Promise<Blob> {
+  const buffer = await pngBlob.arrayBuffer();
+  const view = new DataView(buffer);
+
+  const insertOffset = findFirstIdatOffset(view);
+
+  // Build all tEXt chunks
+  const chunks: Uint8Array[] = [];
+  for (const [key, value] of Object.entries(metadata)) {
+    chunks.push(buildTextChunk(key, value));
+  }
+
+  // Total bytes to insert
+  const insertLength = chunks.reduce((sum, c) => sum + c.length, 0);
+
+  // Assemble: [before IDAT] + [tEXt chunks] + [IDAT onward]
+  const before = new Uint8Array(buffer, 0, insertOffset);
+  const after = new Uint8Array(buffer, insertOffset);
+
+  const result = new Uint8Array(before.length + insertLength + after.length);
+  result.set(before, 0);
+
+  let writeOffset = before.length;
+  for (const chunk of chunks) {
+    result.set(chunk, writeOffset);
+    writeOffset += chunk.length;
+  }
+
+  result.set(after, writeOffset);
+
+  return new Blob([result], { type: 'image/png' });
+}