@moonbase-machines/files 0.0.0-stage → 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Wharton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @moonbase-machines/files
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The formats the machines' files come in and go out as, for the tools that take a title's disks apart: a PNG
+written (`png.js`: from rows of pixels or from RGBA bytes, and sheets of pictures) and read (`png-read.js`), and a
+zip read (`zip.js`: every file, or the one a name matches). In Node only (`node:zlib`, `Buffer`); a CommonJS tool
+loads them with `require()`, Node 22.12 and later.
+
+Part of Moonbase (moonbase.au): Mark Wharton's titles of 1985 to 1995, running again in the browser on these
+machines. MIT; see LICENSE. Each file opens with what it is and what it covers.

package/index.js

@@ -0,0 +1,5 @@
+// @moonbase-machines/files: the formats the machines' files come in and go out as, read and written in Node
+// (each module its own: png.js, png-read.js, zip.js).
+export * as png from './png.js';
+export * as pngRead from './png-read.js';
+export * as zip from './zip.js';

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@moonbase-machines/files",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.1",
+  "description": "The formats the machines' files come in and go out as, in Node: PNG written and read, and zip read.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mark Wharton",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}

package/png-read.js

@@ -0,0 +1,39 @@
+// A PNG read, in Node: its size and each pixel's colour as six hex digits, for pictures such as
+// c64gfx's (paletted, 1 to 8 bits a pixel) and ordinary ones (RGB or RGBA, 8 bits a channel).
+//
+//   readPng(bytes)   { width, height, palette (hex strings, or null), at(x, y) -> 'rrggbb' }
+import { inflateSync } from 'node:zlib';
+
+export function readPng(b) {
+  if (b.readUInt32BE(0) !== 0x89504e47) throw new Error('not a PNG');
+  let i = 8, width, height, depth, type, palette = null;
+  const idat = [];
+  while (i < b.length) {
+    const n = b.readUInt32BE(i), t = b.toString('ascii', i + 4, i + 8), d = b.subarray(i + 8, i + 8 + n);
+    if (t === 'IHDR') { width = d.readUInt32BE(0); height = d.readUInt32BE(4); depth = d[8]; type = d[9]; if (d[12]) throw new Error('an interlaced PNG'); }
+    if (t === 'PLTE') { palette = []; for (let k = 0; k < n; k += 3) palette.push(d.subarray(k, k + 3).toString('hex')); }
+    if (t === 'IDAT') idat.push(d);
+    i += 12 + n;
+  }
+  const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[type];
+  if (!channels || (type !== 3 && depth !== 8)) throw new Error(`a PNG of type ${type}, depth ${depth}: not read here`);
+  const raw = inflateSync(Buffer.concat(idat)), bpp = Math.max(1, (channels * depth) >> 3), stride = Math.ceil(width * channels * depth / 8);
+  const out = Buffer.alloc(stride * height);
+  // (each row unfiltered: none, sub, up, average, Paeth)
+  for (let y = 0; y < height; y++) {
+    const f = raw[y * (stride + 1)], src = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1)), row = out.subarray(y * stride, (y + 1) * stride), up = y ? out.subarray((y - 1) * stride, y * stride) : null;
+    for (let x = 0; x < stride; x++) {
+      const a = x >= bpp ? row[x - bpp] : 0, u = up ? up[x] : 0, c = up && x >= bpp ? up[x - bpp] : 0;
+      const p = a + u - c, pa = Math.abs(p - a), pb = Math.abs(p - u), pc = Math.abs(p - c);
+      row[x] = (src[x] + [0, a, u, (a + u) >> 1, pa <= pb && pa <= pc ? a : pb <= pc ? u : c][f]) & 0xff;
+    }
+  }
+  const hex = (r, g, bl) => ((r << 16) | (g << 8) | bl).toString(16).padStart(6, '0');
+  const at = (x, y) => {
+    const row = y * stride;
+    if (type === 3) { const bit = x * depth, v = (out[row + (bit >> 3)] >> (8 - depth - (bit & 7))) & ((1 << depth) - 1); return palette[v]; }
+    const p = row + x * channels;
+    return channels >= 3 ? hex(out[p], out[p + 1], out[p + 2]) : hex(out[p], out[p], out[p]);
+  };
+  return { width, height, palette, at };
+}

package/png.js

@@ -0,0 +1,64 @@
+// A PNG written, in Node: one IDAT chunk, deflated, no filtering. From rows of pixels, each [r, g, b] or
+// [r, g, b, a] (with its alpha), or from RGBA bytes as a canvas or the machines' screens give them.
+//
+//   png(rows)                        a PNG's bytes from rows of [r, g, b] or [r, g, b, a]
+//   pngOfRGBA(rgba, width, height, { alpha })   a PNG's bytes from RGBA bytes, four a pixel, row by row; alpha
+//                                    false, written as RGB, its alpha left out (a picture with none to show)
+//   sheet(pictures, { across, gap, scale })   pictures (rows) on one sheet, `gap` gray dots between
+//   padded(pictures, fill)           pictures of different sizes padded to the largest, top left
+import { deflateSync } from 'node:zlib';
+
+const crcTable = Array.from({ length: 256 }, (_, n) => { for (let k = 0; k < 8; k++) n = n & 1 ? 0xedb88320 ^ (n >>> 1) : n >>> 1; return n >>> 0; });
+const crc = buf => { let c = 0xffffffff; for (const b of buf) c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };
+
+function chunk(type, data) {
+  const head = Buffer.alloc(4); head.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, 'latin1'), data]);
+  const tail = Buffer.alloc(4); tail.writeUInt32BE(crc(body));
+  return Buffer.concat([head, body, tail]);
+}
+
+// (the rows as PNG wants them, each a filter byte, 0, then its pixels; n bytes a pixel, 3 or 4)
+function encode(raw, w, h, n) {
+  const ihdr = Buffer.alloc(13); ihdr.writeUInt32BE(w, 0); ihdr.writeUInt32BE(h, 4); ihdr.set([8, n === 4 ? 6 : 2, 0, 0, 0], 8);
+  return Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk('IHDR', ihdr), chunk('IDAT', deflateSync(raw, { level: 9 })), chunk('IEND', Buffer.alloc(0))]);
+}
+
+export function png(pixels) {
+  const h = pixels.length, w = pixels[0].length, n = pixels[0][0].length;
+  const raw = Buffer.alloc(h * (w * n + 1));
+  pixels.forEach((row, y) => row.forEach((c, x) => raw.set(c, y * (w * n + 1) + 1 + x * n)));
+  return encode(raw, w, h, n);
+}
+
+export function pngOfRGBA(rgba, w, h, { alpha = true } = {}) {
+  const n = alpha ? 4 : 3, raw = Buffer.alloc(h * (w * n + 1));
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) raw.set(rgba.subarray((y * w + x) * 4, (y * w + x) * 4 + n), y * (w * n + 1) + 1 + x * n);
+  return encode(raw, w, h, n);
+}
+
+// Pictures scaled by `scale`, with `gap` gray dots between them, `across` to a row.
+export function sheet(pictures, { across = 3, gap = 8, scale = 1 } = {}) {
+  const GRAY = [60, 60, 60];
+  const w = pictures[0][0].length * scale, h = pictures[0].length * scale;
+  const out = [];
+  for (let r = 0; r * across < pictures.length; r++) {
+    if (r) for (let g = 0; g < gap; g++) out.push(Array((w + gap) * across - gap).fill(GRAY));
+    for (let y = 0; y < h; y++) {
+      const row = [];
+      for (let c = 0; c < across; c++) {
+        if (c) for (let g = 0; g < gap; g++) row.push(GRAY);
+        const p = pictures[r * across + c];
+        if (!p) { for (let x = 0; x < w; x++) row.push(GRAY); continue; }
+        for (const px of p[Math.floor(y / scale)]) for (let s = 0; s < scale; s++) row.push(px);
+      }
+      out.push(row);
+    }
+  }
+  return png(out);
+}
+
+export function padded(pictures, fill = [60, 60, 60]) {
+  const w = Math.max(...pictures.map(p => p[0].length)), h = Math.max(...pictures.map(p => p.length));
+  return pictures.map(p => Array.from({ length: h }, (_, y) => Array.from({ length: w }, (_, x) => (p[y] && p[y][x]) || fill)));
+}

package/test/files.test.js

@@ -0,0 +1,70 @@
+// A PNG written and read back; a zip read, its files stored and deflated, a folder and a Mac's __MACOSX copy among
+// them. Made from bytes the tests build, nothing of a title's.
+//
+//   node --test test/*.test.js
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { deflateRawSync } from 'node:zlib';
+import { png, pngOfRGBA, sheet, padded } from '@moonbase-machines/files/png.js';
+import { readPng } from '@moonbase-machines/files/png-read.js';
+import { unzip, fromZip } from '@moonbase-machines/files/zip.js';
+
+test('a PNG of rows, with and without alpha, reads back pixel for pixel', () => {
+  const rows = [[[255, 0, 0], [0, 255, 0]], [[0, 0, 255], [17, 34, 51]]];
+  const p = readPng(png(rows));
+  assert.equal(p.width, 2); assert.equal(p.height, 2);
+  assert.deepEqual([p.at(0, 0), p.at(1, 0), p.at(0, 1), p.at(1, 1)], ['ff0000', '00ff00', '0000ff', '112233']);
+  const q = readPng(png([[[1, 2, 3, 128]]]));
+  assert.equal(q.at(0, 0), '010203');
+});
+
+test('a PNG of RGBA bytes reads back as the same picture as its rows', () => {
+  const rgba = new Uint8Array([10, 20, 30, 255, 40, 50, 60, 255, 70, 80, 90, 255, 1, 2, 3, 255]);
+  const p = readPng(pngOfRGBA(rgba, 2, 2));
+  assert.deepEqual([p.at(0, 0), p.at(1, 0), p.at(0, 1), p.at(1, 1)], ['0a141e', '28323c', '46505a', '010203']);
+  const rows = [[[10, 20, 30], [40, 50, 60]], [[70, 80, 90], [1, 2, 3]]];
+  assert.deepEqual(pngOfRGBA(rgba, 2, 2, { alpha: false }), png(rows), 'without its alpha, the same bytes as the rows\' PNG');
+});
+
+test('a sheet lays pictures out with gray between, the smaller padded to the largest', () => {
+  const a = [[[255, 255, 255]]], b = [[[0, 0, 0], [0, 0, 0]], [[0, 0, 0], [0, 0, 0]]];
+  const [pa, pb] = padded([a, b]);
+  assert.equal(pa.length, 2); assert.equal(pa[0].length, 2); assert.deepEqual(pa[1][1], [60, 60, 60]);
+  const s = readPng(sheet([pa, pb], { across: 2, gap: 1 }));
+  assert.equal(s.width, 5); assert.equal(s.height, 2);
+  assert.deepEqual([s.at(0, 0), s.at(2, 0), s.at(3, 0)], ['ffffff', '3c3c3c', '000000']);
+});
+
+// a zip as a zip tool writes one: local headers, the data, the central directory and its end
+function zip(entries) {
+  const locals = [], central = [];
+  let at = 0;
+  for (const { name, data, deflate } of entries) {
+    const body = deflate ? deflateRawSync(data) : data, n = Buffer.from(name, 'latin1');
+    const local = Buffer.alloc(30); local.writeUInt32LE(0x04034b50, 0); local.writeUInt16LE(deflate ? 8 : 0, 8); local.writeUInt32LE(body.length, 18); local.writeUInt32LE(data.length, 22); local.writeUInt16LE(n.length, 26);
+    const c = Buffer.alloc(46); c.writeUInt32LE(0x02014b50, 0); c.writeUInt16LE(deflate ? 8 : 0, 10); c.writeUInt32LE(body.length, 20); c.writeUInt32LE(data.length, 24); c.writeUInt16LE(n.length, 28); c.writeUInt32LE(at, 42);
+    locals.push(local, n, body); central.push(c, n);
+    at += 30 + n.length + body.length;
+  }
+  const dir = Buffer.concat(central), end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0); end.writeUInt16LE(entries.length, 8); end.writeUInt16LE(entries.length, 10); end.writeUInt32LE(dir.length, 12); end.writeUInt32LE(at, 16);
+  return Buffer.concat([...locals, dir, end]);
+}
+
+test('a zip read: every file but a folder, stored or deflated; one found by name, past __MACOSX', () => {
+  const disk = Buffer.alloc(300, 7);
+  const z = zip([
+    { name: 'disks/', data: Buffer.alloc(0) },
+    { name: '__MACOSX/disks/._Game.dsk', data: Buffer.from('mac') },
+    { name: 'disks/Game.dsk', data: disk, deflate: true },
+    { name: 'README.txt', data: Buffer.from('hello') },
+  ]);
+  const files = unzip(z);
+  assert.deepEqual(files.map(f => f.name), ['__MACOSX/disks/._Game.dsk', 'disks/Game.dsk', 'README.txt']);
+  assert.deepEqual(files.map(f => f.method), [0, 8, 0]);
+  assert.equal(files[2].body.toString(), 'hello');
+  const { name, body } = fromZip(z, /\.dsk$/i);
+  assert.equal(name, 'disks/Game.dsk'); assert.deepEqual(body, disk);
+  assert.throws(() => fromZip(z, /\.d64$/), /nothing in the zip matches/);
+  assert.throws(() => unzip(Buffer.alloc(40)), /not a zip/);
+});

package/zip.js

@@ -0,0 +1,31 @@
+// A zip read, in Node: its central directory, at the end, names each file, its sizes and where its local header
+// is (a local header may leave the sizes as zero); each file's data follows its local header's 30 bytes, its name
+// and its extra field, stored as it is (method 0) or deflated (method 8).
+//
+//   unzip(zip)            every file, [{ name, body, method }] (a folder's entry left out; a method other than
+//                         0 or 8, its body null)
+//   fromZip(zip, wanted)  the first file whose name `wanted` (a RegExp) matches, outside a Mac's __MACOSX folder:
+//                         { name, body }; an error when none does
+import { inflateRawSync } from 'node:zlib';
+
+export function unzip(zip) {
+  let end = zip.length - 22;
+  while (end >= 0 && zip.readUInt32LE(end) !== 0x06054b50) end--;
+  if (end < 0) throw new Error('not a zip');
+  const files = [];
+  for (let at = zip.readUInt32LE(end + 16), n = zip.readUInt16LE(end + 10); n--; ) {
+    const method = zip.readUInt16LE(at + 10), size = zip.readUInt32LE(at + 20), nameLength = zip.readUInt16LE(at + 28);
+    const extra = zip.readUInt16LE(at + 30), comment = zip.readUInt16LE(at + 32), local = zip.readUInt32LE(at + 42);
+    const name = zip.toString('latin1', at + 46, at + 46 + nameLength);
+    const start = local + 30 + zip.readUInt16LE(local + 26) + zip.readUInt16LE(local + 28), data = zip.subarray(start, start + size);
+    if (!name.endsWith('/')) files.push({ name, body: method === 0 ? data : method === 8 ? inflateRawSync(data) : null, method });
+    at += 46 + nameLength + extra + comment;
+  }
+  return files;
+}
+
+export function fromZip(zip, wanted) {
+  const f = unzip(zip).find(f => wanted.test(f.name) && !f.name.startsWith('__MACOSX'));
+  if (!f) throw new Error('nothing in the zip matches ' + wanted);
+  return { name: f.name, body: f.body };
+}