flea-qml 0.0.0-stage → 0.1.0

package/docs/temml.md

@@ -0,0 +1,63 @@
+# Temml source and inherited notices
+
+`src/vendor/temml.mjs` is the unmodified Temml 0.14.0 npm distribution:
+
+- Source: https://cdn.jsdelivr.net/npm/temml@0.14.0/dist/temml.mjs
+- Size: 478952 bytes
+- SHA-256: `09e55a0c364d35b8ef66be49486b90884240a7e66c463a825e096faf27b0d59d`
+- Licence: [MIT-temml.txt](../src/vendor/LICENSES/MIT-temml.txt).
+
+No code or embedded attribution comments were changed. These additional notices
+identify inherited work; historical source references do not imply that whole
+source files are byte-identical to Temml's adapted implementation.
+
+## KaTeX and Perseus
+
+Temml's [0.14.0 README](https://cdn.jsdelivr.net/npm/temml@0.14.0/README.md)
+identifies it as a KaTeX fork and credits Khan Academy and KaTeX contributors.
+[MIT-katex.txt](../src/vendor/LICENSES/MIT-katex.txt) is copied unchanged from
+[KaTeX v0.16.0](https://github.com/KaTeX/KaTeX/blob/v0.16.0/LICENSE).
+This attribution reference is not a claim that Temml forked exactly that tag.
+
+Temml's `findEndOfMath` retains a comment crediting Khan/Perseus. The same
+brace-scanning algorithm and attribution appear in
+[KaTeX's 2015 auto-render source](https://github.com/KaTeX/KaTeX/blob/cd9bca4a89eddd77c542e23a4a9dc2deff2ab72c/contrib/auto-render/splitAtDelimiters.js).
+Its [contemporaneous licence](https://github.com/KaTeX/KaTeX/blob/cd9bca4a89eddd77c542e23a4a9dc2deff2ab72c/LICENSE.txt)
+is retained unchanged as [MIT-katex-2015.txt](../src/vendor/LICENSES/MIT-katex-2015.txt),
+including its original Underscore credit. This does not mean the full
+Underscore library is shipped.
+
+[MIT-perseus.txt](../src/vendor/LICENSES/MIT-perseus.txt) preserves the official
+[Perseus licence](https://raw.githubusercontent.com/Khan/perseus/master/LICENSE)
+retrieved on 2026-11-16. The precise original Perseus revision is not recorded
+in Temml's comment. This modern licence is supplementary attribution, not proof
+of the original revision's terms; the historical KaTeX source and licence above
+document the traceable adaptation.
+
+## React utilities
+
+Temml explicitly credits Facebook's React under Apache-2.0 for `hyphenate` and
+`escape`. Historical references exist in React v0.3.0:
+[hyphenate](https://github.com/facebook/react/blob/v0.3.0/src/vendor/core/hyphenate.js)
+and [escapeTextForBrowser](https://github.com/facebook/react/blob/v0.3.0/src/utils/escapeTextForBrowser.js).
+Its [Apache-2.0 licence](https://github.com/facebook/react/blob/v0.3.0/LICENSE)
+matches our [Apache-2.0.txt](../src/vendor/LICENSES/Apache-2.0.txt), apart from
+the latter's leading blank line.
+
+These are adapted utilities: Temml's escape helper converts to a string and
+uses a smaller replacement table. The exact React commit originally used is
+not identified by Temml; v0.3.0 documents the Apache-licensed historical source,
+not an assertion that it was the precise imported revision. Preserve the
+embedded attribution rather than substituting a later React release's licence.
+
+## Chemistry and physics extensions
+
+The shipped file preserves the original notices and adaptation descriptions for:
+
+- mhchem: Copyright (c) 2011–2015 The MathJax Consortium;
+  Copyright (c) 2015–2018 Martin Hensel.
+- Physics macros: Copyright (c) 2015–2016 Kolen Cheung.
+
+Their Apache-2.0 notices remain embedded in `temml.mjs`; the full licence is in
+[Apache-2.0.txt](../src/vendor/LICENSES/Apache-2.0.txt). Temml's revision notices
+are also retained. Temml's MIT licence does not replace these inherited credits.

package/index.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env bun
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {resolve, dirname} from 'node:path';
+import info from './package.json' with {type:'json'};
+
+export const entryURL = pathToFileURL(resolve(dirname(fileURLToPath(import.meta.url)), 'ui/boot/shell.qml')).href;
+const hasFrontend = args => args[0]?.startsWith('--') && args[0] !== '--';
+
+// Read the package specification only; never execute the script through a shell.
+export function browserPackage(script = info.scripts.browser) {
+  const match = /^bunx\s+(buninu-browser@[^\s;&|<>`$]+)\s*$/.exec(script ?? '');
+  if (!match) throw new Error('scripts.browser must be "bunx buninu-browser@VERSION"');
+  return match[1];
+}
+
+// Match buninu-browser's Casty launcher: npx needs Bun for the bin shebang.
+export function browserCommand(args, which = Bun.which, runtime = process.argv0) {
+  const pkg = browserPackage();
+  const npx = which('npx'), bun = which('bun');
+  if (npx && bun) return [npx, '--loglevel=error', '-p', pkg, '--', 'buninu-browser', ...args];
+  const bunx = which('bunx');
+  return bunx ? [bunx, pkg, ...args] : [bun ?? runtime, 'x', pkg, ...args];
+}
+
+export function selectFrontend(args, kitty, platform = process.platform) {
+  if (hasFrontend(args)) {
+    const [first, ...rest] = args;
+    return {frontend:first, args:rest};
+  }
+  return {frontend:kitty ? '--casty' : platform === 'win32' ? '--win32' : '--wayland', args};
+}
+
+// An actual inline graphics query, not a TERM-name guess. Restore stdin before
+// launching the child, and preserve input unrelated to the query response.
+export async function detectKitty(input = process.stdin, output = process.stdout, timeout = 800) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== 'function') return false;
+  const id = 100000 + Math.floor(Math.random()*1000000000);
+  const marker = Buffer.from(`\x1b_Gi=${id};`), end = Buffer.from('\x1b\\');
+  const wasRaw = input.isRaw, wasPaused = input.isPaused();
+  let bytes = Buffer.alloc(0), timer, onData, onError, onSignal;
+  try {
+    input.setRawMode(true);
+    return await new Promise((resolve, reject) => {
+      const finish = value => {clearTimeout(timer); resolve(value);};
+      onError = error => {clearTimeout(timer); reject(error);};
+      onSignal = () => onError(new Error('Interrupted during terminal detection'));
+      onData = chunk => {
+        bytes = Buffer.concat([bytes, Buffer.from(chunk)]);
+        const start = bytes.indexOf(marker);
+        const stop = start < 0 ? -1 : bytes.indexOf(end, start + marker.length);
+        if (stop < 0) {if (bytes.length > 65536) finish(false);return;}
+        const reply = bytes.subarray(start + marker.length, stop).toString();
+        bytes = Buffer.concat([bytes.subarray(0,start), bytes.subarray(stop+end.length)]);
+        finish(reply === 'OK' || reply.startsWith('OK '));
+      };
+      input.on('data', onData); input.on('error', onError); output.on('error', onError);
+      for (const signal of ['SIGINT','SIGTERM','SIGHUP']) process.on(signal,onSignal);
+      timer = setTimeout(() => finish(false), timeout);
+      input.resume();
+      output.write(`\x1b_Ga=q,t=d,f=24,s=1,v=1,i=${id},q=0;AAAA\x1b\\`);
+    });
+  } finally {
+    clearTimeout(timer);input.pause();
+    if (onData) input.off('data',onData);
+    if (onError) {input.off('error',onError);output.off('error',onError);}
+    if (onSignal) for (const signal of ['SIGINT','SIGTERM','SIGHUP']) process.off(signal,onSignal);
+    input.setRawMode(!!wasRaw);
+    if (bytes.length) input.unshift(bytes);
+    if (!wasPaused) input.resume();
+  }
+}
+
+export async function main(args = Bun.argv.slice(2)) {
+  if (args[0] === '--readme') {
+    process.stdout.write(Bun.markdown.ansi(await Bun.file(new URL('./README.md', import.meta.url)).text(), {hyperlinks:true}));
+    return 0;
+  }
+  if (['-h','--help'].includes(args[0])) {
+    console.log(`Usage: flea-qml [BROWSER_FRONTEND] [BROWSER_ARGS...]\n\nAutomatically probes Kitty graphics; otherwise Windows uses --win32,\nother platforms (including Linux/Android) use --wayland. The first argument\nis passed unchanged to buninu-browser and overrides detection (for example
+--casty, --win32, --wayland or --headless). Requires Bun on PATH. Remaining arguments go unchanged\nto buninu-browser after the absolute file URL of ui/boot/shell.qml.\n\n  --readme       Print the README as coloured ANSI Markdown\n  --version, -V  Print the package version\n  --help, -h     Show this help`);
+    return 0;
+  }
+  if (['-V','--version'].includes(args[0])) {console.log(`flea-qml ${info.version}\n${browserPackage()} (pinned)`);return 0;}
+  let kitty = false;
+  if (!hasFrontend(args)) {
+    try {kitty = await detectKitty();}
+    finally {
+      // The child inherits the terminal. The probe must neither consume its
+      // input nor keep this launcher alive after the child has exited.
+      process.stdin.pause();
+      process.stdin.unref?.();
+    }
+  }
+  const selection = selectFrontend(args, kitty);
+  const browserArgs = [selection.frontend, entryURL, ...selection.args];
+  const child = Bun.spawn({cmd:browserCommand(browserArgs),stdio:['inherit','inherit','inherit']});
+  const handlers = ['SIGINT','SIGTERM','SIGHUP'].map(signal => {
+    const handler = () => {try {child.kill(signal);} catch {}};
+    process.on(signal,handler);return [signal,handler];
+  });
+  try {return (await child.exited) ?? 1;}
+  finally {for(const [signal,handler] of handlers) process.off(signal,handler);}
+}
+if (import.meta.main) {
+  try {process.exitCode = await main();}
+  catch (error) {console.error('flea-qml: '+error.message);process.exitCode=1;}
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "flea-qml",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Flea QML is a cross-platform file manager written in Bun JavaScript & QML. It's an unofficial fork of Flea, the fast GUI file manager for Omarchy",
+  "type": "module",
+  "main": "./index.js",
+  "bin": {
+    "flea-qml": "./index.js"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Dr. John (醫者小智)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jjtseng93/flea-qml.git"
+  },
+  "homepage": "https://github.com/jjtseng93/flea-qml",
+  "bugs": {
+    "url": "https://github.com/jjtseng93/flea-qml/issues"
+  },
+  "keywords": [
+    "bun",
+    "qml",
+    "file-manager",
+    "quickshell",
+    "buninu"
+  ],
+  "scripts": {
+    "start": "bun index.js",
+    "test": "bun test",
+    "browser": "bunx buninu-browser@0.10.4"
+  }
+}

package/src/archive.js

@@ -0,0 +1,402 @@
+// Archive listings for the preview: what `tar -tf` and `unzip -l` would print, as
+// { name, dir, size } per member. The header and central-directory parsers come from
+// buninu-linux's initramfs/bin/tar and initramfs/bin/unzip@da0b394 (MIT, Dr. John), changed to read
+// through a descriptor: a zip reads its tail and central directory only, and a plain tar reads
+// each header and seeks past the member's data, so neither loads the archive. A compressed tar
+// cannot be sought through, so it is inflated as a stream and its member data dropped as it passes.
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { Readable } from "node:stream";
+import { createGunzip, createZstdDecompress, inflateRawSync } from "node:zlib";
+
+const BLOCK = 512;
+const MAX_RECORD = 1024 * 1024;
+function checkedSize(value) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error("invalid archive size");
+  return value;
+}
+const decoder = new TextDecoder(),
+  strictUtf8 = new TextDecoder("utf-8", { fatal: true });
+
+// Reads at an offset through a descriptor, or from bytes already in memory; short at the end.
+function fileReader(fd, size) {
+  return {
+    size,
+    read(position, length) {
+      checkedSize(position);
+      checkedSize(length);
+      if (position > size || length > size - position) throw new Error("truncated archive");
+      const n = length,
+        buffer = Buffer.alloc(n);
+      let done = 0;
+      while (done < n) {
+        const count = readSync(fd, buffer, done, n - done, position + done);
+        if (count === 0) break;
+        done += count;
+      }
+      return done === n ? buffer : buffer.subarray(0, done);
+    },
+  };
+}
+
+// ---- tar (buninu-linux initramfs/bin/tar scanEntries) ----
+
+const text = (block, offset, length) => {
+  let end = offset;
+  const stop = offset + length;
+  while (end < stop && block[end] !== 0) end++;
+  return decoder.decode(block.subarray(offset, end));
+};
+
+const octal = (block, offset, length) => {
+  // GNU base-256 encoding for values that do not fit the octal field.
+  if (block[offset] & 0x80) {
+    let value = block[offset] & 0x7f;
+    for (let index = offset + 1; index < offset + length; index++) value = value * 256 + block[index];
+    return value;
+  }
+  const value = Number.parseInt(text(block, offset, length).trim(), 8);
+  return Number.isFinite(value) ? value : 0;
+};
+
+// The header checksum is computed with its own field read as spaces. A mismatch means this is
+// not a tar header, so the listing fails rather than showing partial totals.
+const checksumMatches = (block) => {
+  let sum = 0;
+  for (let index = 0; index < BLOCK; index++) sum += index >= 148 && index < 156 ? 0x20 : block[index];
+  return sum === octal(block, 148, 8);
+};
+
+// Each record's length counts bytes, so the records are cut from the bytes and decoded one by one;
+// cutting a decoded string by that length breaks on any multi-byte name.
+const paxRecords = (data) => {
+  const records = Object.create(null);
+  let offset = 0;
+  while (offset < data.length) {
+    const space = data.indexOf(0x20, offset);
+    if (space === -1) break;
+    const length = Number.parseInt(decoder.decode(data.subarray(offset, space)), 10);
+    if (!Number.isFinite(length) || length <= 0 || offset + length > data.length) break;
+    const record = decoder.decode(data.subarray(space + 1, offset + length)).replace(/\n$/, "");
+    const equals = record.indexOf("=");
+    if (equals > 0) records[record.slice(0, equals)] = record.slice(equals + 1);
+    offset += length;
+  }
+  return records;
+};
+
+// The header logic both readers share: POSIX ustar, GNU long names (L/K), pax headers (x/X/g), and
+// tar streams joined end to end, as APK v2 does. `header` answers how many bytes of the member that
+// follows are wanted (a long name or pax record) and how many to skip; `record` takes the wanted ones.
+class TarHeaders {
+  constructor(visit) {
+    this.visit = visit;
+    this.longName = null;
+    this.extended = {};
+    this.global = {};
+    this.seen = 0;
+    this.done = false;
+    this.pending = null;
+  }
+  // Reject invalid headers even after valid members.
+  header(block) {
+    if (block.every((byte) => byte === 0)) {
+      this.longName = null;
+      this.extended = {};
+      this.global = {};
+      return { want: 0, skip: 0 };
+    }
+    if (!checksumMatches(block)) {
+      throw new Error("invalid tar header");
+    }
+    this.seen++;
+    const flag = String.fromCharCode(block[156] || 0x30);
+    const metadata = ["L", "K", "x", "X", "g"].includes(flag);
+    const attrs = { ...this.global, ...this.extended };
+    const size = checkedSize(!metadata && attrs.size !== undefined ? Number(attrs.size) : octal(block, 124, 12));
+    const padded = checkedSize(Math.ceil(size / BLOCK) * BLOCK);
+    if (metadata) {
+      if (size > MAX_RECORD) throw new Error("tar metadata record is too large");
+      this.pending = flag;
+      return { want: size, skip: padded - size };
+    }
+    if (flag !== "g") {
+      const prefix = text(block, 257, 5) === "ustar" ? text(block, 345, 155) : "",
+        stored = text(block, 0, 100);
+      const name = (attrs.path ?? this.longName ?? (prefix ? `${prefix}/${stored}` : stored)).replace(/^\.\//, "");
+      if (name) this.visit({ name: name.replace(/\/$/, ""), dir: flag === "5" || name.endsWith("/"), size: flag === "5" ? 0 : size });
+      this.longName = null;
+      this.extended = {};
+    }
+    return { want: 0, skip: padded };
+  }
+  record(data) {
+    if (this.pending === "L") this.longName = decoder.decode(data).replace(/\0+$/, "");
+    else if (this.pending === "x" || this.pending === "X") this.extended = { ...this.extended, ...paxRecords(data) };
+    else if (this.pending === "g") this.global = { ...this.global, ...paxRecords(data) };
+    this.pending = null;
+  }
+}
+
+// A plain tar through its descriptor: one read per header, a seek past every member's data.
+function scanTar(reader, visit) {
+  const headers = new TarHeaders(visit);
+  for (let offset = 0; offset < reader.size; ) {
+    const block = reader.read(offset, BLOCK);
+    if (block.length < BLOCK) break;
+    offset += BLOCK;
+    const { want, skip } = headers.header(block);
+    if (want + skip > reader.size - offset) throw new Error("truncated tar member");
+    if (want || headers.pending) headers.record(reader.read(offset, want));
+    offset += want + skip;
+  }
+}
+
+// A compressed tar, inflated as a stream: headers and their small records are kept, member data is
+// counted past and dropped, so memory stays one chunk however large the archive unpacks.
+function streamTar(fd, size, inflate, visit) {
+  return new Promise((resolve, reject) => {
+    const headers = new TarHeaders(visit),
+      // Keep ownership of the checked descriptor here. Some Bun versions close an
+      // fs.ReadStream's fd on destroy even when autoClose is false.
+      input = Readable.from((function* () {
+        const reader = fileReader(fd, size);
+        for (let offset = 0; offset < size; offset += 65536)
+          yield reader.read(offset, Math.min(65536, size - offset));
+      })()),
+      output = input.pipe(inflate);
+    let block = Buffer.alloc(0),
+      want = 0,
+      wanted = [],
+      skip = 0;
+    let settled = false;
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      input.destroy();
+      output.destroy();
+      error ? reject(error) : resolve();
+    };
+    output.on("data", (chunk) => {
+      try {
+        while (chunk.length && !headers.done) {
+          // A record's bytes come first, then the padding to its block, so want before skip.
+          if (want) {
+            const n = Math.min(want, chunk.length);
+            wanted.push(chunk.subarray(0, n));
+            want -= n;
+            chunk = chunk.subarray(n);
+            if (!want) {
+              headers.record(Buffer.concat(wanted));
+              wanted = [];
+            }
+          } else if (skip) {
+            const n = Math.min(skip, chunk.length);
+            skip -= n;
+            chunk = chunk.subarray(n);
+          } else {
+            const n = Math.min(BLOCK - block.length, chunk.length);
+            block = Buffer.concat([block, chunk.subarray(0, n)]);
+            chunk = chunk.subarray(n);
+            if (block.length === BLOCK) {
+              ({ want, skip } = headers.header(block));
+              if (!want && headers.pending) headers.record(Buffer.alloc(0));
+              block = Buffer.alloc(0);
+            }
+          }
+        }
+        if (headers.done) finish();
+      } catch (error) {
+        finish(error);
+      }
+    });
+    output.on("end", () => finish(want || skip || block.length ? new Error("truncated tar stream") : undefined));
+    output.on("error", finish);
+    input.on("error", finish);
+  });
+}
+
+// ---- zip (buninu-linux initramfs/bin/unzip) ----
+
+function scanZip(reader, visit) {
+  // End of central directory: in the last 64 KiB + 22 bytes, searched backwards.
+  const tailLength = Math.min(reader.size, 65557),
+    tail = reader.read(reader.size - tailLength, tailLength);
+  let eocd = -1;
+  for (let offset = tailLength - 22; offset >= 0; offset--)
+    if (tail.readUInt32LE(offset) === 0x06054b50 && offset + 22 + tail.readUInt16LE(offset + 20) === tail.length) {
+      eocd = offset;
+      break;
+    }
+  if (eocd < 0) throw new Error("not a zip archive");
+  // The bounds below follow buninu-linux's initramfs/bin/unzip: one disk only, and every range
+  // inside the space before the record that names it.
+  if (tail.readUInt16LE(eocd + 4) !== 0 || tail.readUInt16LE(eocd + 6) !== 0 || tail.readUInt16LE(eocd + 8) !== tail.readUInt16LE(eocd + 10))
+    throw new Error("split archives are not supported");
+  const uint64 = (buffer, offset) => checkedSize(Number(buffer.readBigUInt64LE(offset)));
+  let entryCount = tail.readUInt16LE(eocd + 10),
+    directorySize = tail.readUInt32LE(eocd + 12),
+    directoryOffset = tail.readUInt32LE(eocd + 16),
+    directoryLimit = reader.size - tailLength + eocd;
+  // zip64: the locator sits just before the end of central directory record.
+  if (eocd >= 20 && tail.readUInt32LE(eocd - 20) === 0x07064b50) {
+    if (tail.readUInt32LE(eocd - 16) !== 0 || tail.readUInt32LE(eocd - 4) !== 1) throw new Error("split zip64 archives are not supported");
+    const recordOffset = uint64(tail, eocd - 20 + 8);
+    if (recordOffset > directoryLimit - 20 - 56) throw new Error("bad zip64 record range");
+    const record = reader.read(recordOffset, 56);
+    if (record.length < 56 || record.readUInt32LE(0) !== 0x06064b50) throw new Error("bad zip64 end of central directory");
+    if (record.readUInt32LE(16) !== 0 || record.readUInt32LE(20) !== 0 || uint64(record, 24) !== uint64(record, 32) || uint64(record, 4) < 44)
+      throw new Error("bad or split zip64 directory");
+    directoryLimit = recordOffset;
+    entryCount = uint64(record, 32);
+    directorySize = uint64(record, 40);
+    directoryOffset = uint64(record, 48);
+  }
+  checkedSize(entryCount);
+  checkedSize(directoryOffset);
+  checkedSize(directorySize);
+  if (directoryOffset > directoryLimit || directorySize > directoryLimit - directoryOffset || entryCount > Math.floor(directorySize / 46))
+    throw new Error("bad central directory bounds");
+  let positionInDirectory = 0;
+  for (let index = 0; index < entryCount; index++) {
+    if (directorySize - positionInDirectory < 46) throw new Error("truncated central directory");
+    const header = reader.read(directoryOffset + positionInDirectory, 46);
+    const length = 46 + header.readUInt16LE(28) + header.readUInt16LE(30) + header.readUInt16LE(32);
+    if (length > directorySize - positionInDirectory) throw new Error("truncated central entry");
+    const central = reader.read(directoryOffset + positionInDirectory, length), offset = 0;
+    if (central.readUInt32LE(0) !== 0x02014b50) throw new Error("bad central directory");
+    if (central.readUInt16LE(34) !== 0) throw new Error("split members are not supported");
+    const flags = central.readUInt16LE(offset + 8),
+      nameLength = central.readUInt16LE(offset + 28),
+      extraLength = central.readUInt16LE(offset + 30),
+      commentLength = central.readUInt16LE(offset + 32);
+    let size = central.readUInt32LE(offset + 24),
+      compressed = central.readUInt32LE(offset + 20),
+      local = central.readUInt32LE(offset + 42),
+      mtime;
+    const wide = [size, compressed, local].filter((value) => value === 0xffffffff).length;
+    let foundWide = false;
+    // Info-ZIP writes UTF-8 names without the 0x800 flag, so a name that decodes as UTF-8 is read
+    // as UTF-8 and only the rest as the old code page's stand-in, latin1.
+    const raw = central.subarray(offset + 46, offset + 46 + nameLength);
+    let name;
+    try {
+      name = flags & 0x800 ? raw.toString("utf8") : strictUtf8.decode(raw);
+    } catch {
+      name = raw.toString("latin1");
+    }
+    // zip64 extra field: the 0xFFFFFFFF fields follow, uncompressed size first.
+    const extra = central.subarray(offset + 46 + nameLength, offset + 46 + nameLength + extraLength);
+    for (let position = 0; position + 4 <= extra.length; ) {
+      const id = extra.readUInt16LE(position),
+        length = extra.readUInt16LE(position + 2);
+      if (length > extra.length - position - 4) throw new Error("truncated zip extra field");
+      // "UT": the modification time in whole Unix seconds, which the DOS stamp rounds to two.
+      if (id === 0x5455 && length >= 5 && extra[position + 4] & 1) mtime = extra.readInt32LE(position + 5);
+      if (id === 0x0001 && !foundWide) {
+        foundWide = true;
+        // Only the fields that overflowed are present, in this order.
+        let at = position + 4;
+        const end = position + 4 + length;
+        const next = () => {
+          if (end - at < 8) throw new Error("truncated zip64 size");
+          const value = checkedSize(Number(extra.readBigUInt64LE(at)));
+          at += 8;
+          return value;
+        };
+        if (size === 0xffffffff) size = next();
+        if (compressed === 0xffffffff) compressed = next();
+        if (local === 0xffffffff) local = next();
+      }
+      position += 4 + length;
+    }
+    if (wide && !foundWide) throw new Error("missing zip64 extra field");
+    if (local > directoryOffset || directoryOffset - local < 30 || compressed > directoryOffset - local - 30)
+      throw new Error("bad zip member range");
+    // The second argument is what reading the member's bytes needs (openZip); a listing ignores it.
+    visit({ name: name.replace(/\/$/, ""), dir: name.endsWith("/"), size },
+      { method: central.readUInt16LE(offset + 10), encrypted: (flags & 1) === 1, compressed, local,
+        crc: central.readUInt32LE(offset + 16), madeBy: central.readUInt16LE(offset + 4) >> 8,
+        external: central.readUInt32LE(offset + 38), time: central.readUInt16LE(offset + 12), date: central.readUInt16LE(offset + 14), mtime });
+    positionInDirectory += length;
+  }
+}
+
+// ---- the listing ----
+
+const kindOf = (lower) =>
+  lower.endsWith(".zip")
+    ? "zip"
+    : lower.endsWith(".tar")
+      ? "tar"
+      : /\.(tar\.gz|tgz)$/.test(lower)
+        ? "tgz"
+        : /\.(tar\.zst|tzst)$/.test(lower)
+          ? "tzst"
+          : "";
+
+export const listable = (name) => kindOf(String(name).toLowerCase()) !== "";
+
+// Calls visit for every member of the archive at `path`, and settles once the listing is whole;
+// rejects for anything it cannot read. The open is non-blocking and re-checked on the descriptor,
+// so a FIFO is never waited on. A plain tar and a zip are read synchronously; a compressed tar
+// streams.
+export async function listArchive(path, name, visit) {
+  const kind = kindOf(String(name).toLowerCase());
+  if (!kind) throw new Error("format not read here");
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile()) throw new Error("not a file");
+    const reader = fileReader(fd, st.size);
+    if (kind === "zip") return scanZip(reader, visit);
+    if (kind === "tar") return scanTar(reader, visit);
+    return await streamTar(fd, st.size, kind === "tgz" ? createGunzip() : createZstdDecompress(), visit);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// ---- zip members (src/office.js) ----
+
+/** A zip opened for reading single members: `names` in directory order, `sizes` by name, and
+ * `read(name, cap)`, which answers the member's bytes, null for a name the zip does not hold, and
+ * throws for a member over `cap`, encrypted, or stored by a method other than store and deflate.
+ * `close()` releases the descriptor. */
+export function openZip(path) {
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile()) throw new Error("not a file");
+    const reader = fileReader(fd, st.size),
+      entries = new Map();
+    scanZip(reader, (entry, raw) => {
+      if (!entry.dir && !entries.has(entry.name)) entries.set(entry.name, { size: entry.size, ...raw });
+    });
+    return {
+      names: [...entries.keys()],
+      sizes: new Map([...entries].map(([name, entry]) => [name, entry.size])),
+      read(name, cap) {
+        const entry = entries.get(name);
+        if (!entry) return null;
+        if (entry.encrypted) throw new Error("encrypted zip member");
+        if (entry.size > cap) throw new Error("zip member too large");
+        const header = reader.read(entry.local, 30);
+        if (header.length < 30 || header.readUInt32LE(0) !== 0x04034b50) throw new Error("bad local header");
+        const data = reader.read(entry.local + 30 + header.readUInt16LE(26) + header.readUInt16LE(28), entry.compressed);
+        if (data.length !== entry.compressed) throw new Error("truncated zip member");
+        if (entry.method === 0) return data;
+        if (entry.method !== 8) throw new Error("unsupported zip method");
+        // The cap bounds the inflated bytes too, whatever size the directory claims.
+        return inflateRawSync(data, { maxOutputLength: Math.max(1, cap) });
+      },
+      close: () => closeSync(fd),
+    };
+  } catch (error) {
+    closeSync(fd);
+    throw error;
+  }
+}
+
+// The pieces src/archiveops.js reads member data with: extraction needs the type, mode, link and
+// bytes of every member, which the listing above never keeps.
+export { BLOCK, MAX_RECORD, checkedSize, checksumMatches, fileReader, kindOf, octal, paxRecords, scanZip, text };