@arraypress/extension-kit 1.11.1 → 1.13.0

package/README.md

@@ -21,6 +21,9 @@ The pieces ArrayPress's Chrome extensions share, so each is written once:
   every answer, cold starts, and the settings page's “Chrome’s built-in AI” row.
 - **Content-script helpers**: a big page worked through in slices that never hold it long, and a
   change watcher for single-page apps and endless lists.
+- **Files**: a ZIP written a file at a time with nothing but the platform (stored or deflated,
+  ZIP64 when it's needed, memory flat however big the files), and files saved through
+  `chrome.downloads` or a link's download.
 - **Build and test helpers** (Node): icon rendering, vendoring npm packages (with a staleness
   check), test builds, store screenshots, zipping for the Chrome Web Store, a fake
   `chrome.storage`, Playwright helpers with time limits, packaging checks, and a copied-code guard.
@@ -234,11 +237,20 @@ hostPatterns('github.com');                  // ['*://github.com/*', '*://*.gith
 originPattern('https://bit.ly/x');           // 'https://bit.ly/*' (permissions.request)
 siteLabel('https://example.com');            // 'example.com', as a list shows it
 withSite(['a.com', 'b.com'], 'a.com');       // ['b.com', 'a.com'], what a list keeps after Add (also withoutSite, withSiteReplaced)
+isWebUrl('mailto:a@example.com');            // false: only http and https are web pages
+isLocalUrl('http://192.168.1.1/admin');      // true: this computer or its network, not the internet
 ```
 
 A site is http or https with a dot in its host (or `localhost`); text without a scheme is https;
 `localhost:8080` is a host and port. Pure, so a content script can load `sites/sites.js` alone.
 
+`isLocalUrl` is for anything that follows links on a person's behalf (a redirect check, a link
+checker): `localhost` and names under it, a name without a dot, `.local`, `.lan`, `.internal`
+and `.home.arpa` names, and the loopback, private and link-local address ranges (IPv4 and IPv6,
+however written: `0x7f.1`, `2130706433`, `[::ffff:192.168.0.1]`). A hop from a site on the
+internet to one of these is where to stop: a request there can change something. It is told from
+the address alone; a public name that resolves to a private address can't be seen from here.
+
 ## A page's side
 
 ```js
@@ -464,6 +476,47 @@ in document order, into open and closed shadow roots (`shadowRootOf`, through
 (`MAX_ELEMENTS`). `otherSiteFrames(doc)` gives the origins of frames from other sites, which a
 reading of the tab leaves out until the person allows those sites.
 
+## Files
+
+```js
+const zip = createZip();
+await zip.add('Lake.jpg', blob);                               // a Blob: stored, read in 4 MiB slices
+await zip.add('notes/Read me.txt', encoder.encode('Hello'));   // or a Uint8Array: deflated
+await saveFiles([{ name: 'Trip.zip', blob: await zip.finish() }], chrome.downloads);
+```
+
+`createZip({store, zip64, heldBytes, date})` writes a ZIP with no library: `add(name, data, {store, date})`
+puts a `Blob` or `Uint8Array` in and resolves once it's written, in the order added (an `add` made
+before the last has resolved waits its turn); `count()`, `bytes()` (uncompressed), and `finish()`
+gives a `Blob` of type `application/zip`. Runs in a page, a worker or Node.
+
+- **Stored or deflated by name.** Formats that are compressed already (`isStoredName(name)`: JPEG,
+  PNG, WebP, MP4, PDF, ZIP, Office documents, WOFF…) are stored as they are; the rest goes through
+  the platform's `CompressionStream('deflate-raw')` (Chrome 103, Node 20.12). `store: true` stores
+  everything (or one file); an empty file is always stored.
+- **Memory stays flat.** ZIP bytes are held up to `heldBytes` (16 MiB, `HELD_BYTES`) and then handed
+  to a growing `Blob`, which Chrome keeps outside the page's memory. A `Blob` bigger than 4 MiB
+  (`SLICE_BYTES`) is read in slices, so a 2 GB video never sits in memory whole. A `Uint8Array` is
+  kept, not copied, until it's handed over: don't write into it again.
+- **Every reader opens it.** A stored file is read twice, once for its CRC-32, so its local header
+  is complete and no data descriptor follows (a stored entry with one can't be read forwards, and
+  some readers refuse it); only deflated files have a data descriptor, as every streaming writer's
+  do. Names are UTF-8 and say so (bit 11), with `/` between folders, and the ZIP says it was made
+  on Unix: Info-ZIP's `unzip` converts the names of an MS-DOS ZIP from an old code page, UTF-8 bit
+  or not, and “Zürich.png” then fails to extract. Checked with fflate, macOS's `unzip`, `ditto`
+  (Archive Utility's reader), `bsdtar` reading forwards and Python's `zipfile`.
+- **ZIP64 when it's needed**, and only then: a file of 4 GiB or more (from 16 MiB short of it), a
+  ZIP that has grown past 4 GiB, more than 65,535 files. `zip64: true` writes it regardless.
+- **A name already in the ZIP is refused** (two files of one name extract as one; give them
+  different names first), as is `add` after `finish`. A file that can't be read rejects its `add`
+  and leaves the ZIP as it was before it, so the rest can still be saved.
+
+`crc32(bytes, seed?)` is the same CRC-32 a PNG's chunks use; `seed` carries on from the bytes before.
+
+`saveFiles(files, downloads, doc?)` saves `{name, blob}` files in order: through `chrome.downloads`
+when the person has granted it (a name already taken gets a number), else as a link's download,
+which Chrome saves the same way. Each blob address is let go after a minute (`KEEP_URL_MS`).
+
 ## Time limits
 
 ```js
@@ -481,6 +534,27 @@ await eachLimited(files, 4, async (file) => save(file)); // at most four at once
 `eachLimited(items, limit, work)`: `work(item, slot, index)` on every item, at most `limit` at once;
 in the runtime half too (`/testing` exports it as well).
 
+## A worker's own requests
+
+```js
+// Manifest: "webRequest" (no install warning), and host access to the sites asked (optional is fine).
+const own = ownRequests({ webRequest: chrome.webRequest, extensionId: chrome.runtime.id });
+const stop = own.listen();                   // webRequest listeners, only while requests are made
+const answer = await own.request('https://bit.ly/abc', { headers: { 'If-None-Match': etag }, signal });
+if (answer.status >= 300 && answer.status < 400) next = new URL(answer.headers.get('location'), url).href;
+else html = await answer.response.text();
+stop();
+```
+
+One request that follows nothing: `redirect: 'manual'`, no cookies, no referrer, no cache. Chrome's
+`fetch` answers a manual redirect with an opaque response (no status, no `Location`); webRequest
+does see the worker's own requests to sites it has access to, so the redirect is read from its
+report of the same request (`status`, `headers.get('location')`, `response: null`). The caller
+decides whether to make the next hop: with `isLocalUrl`, a page on the internet never sends a
+check into the person's own network. `leavesWeb` marks a redirect to something that isn't a web
+address (`mailto:`), which Chrome refuses before showing where. `webRequest` must be a required
+permission (a listener added after an optional grant hears nothing until the worker restarts).
+
 ## Page components
 
 Chrome's own components, made in the page by script (no markup to copy), styled by `chrome-ui.css`.
@@ -639,6 +713,7 @@ A list with an Add button needs every key but `optionsRemoveLabel`; one with an
 | `testBuildDir(root, name)` | `.test-builds/<name>`, or under `$EXTENSION_TEST_BUILDS` (to test another build, or run two side by side). |
 | `storeFrame` | Store screenshots: `canvas`, `windowChrome` (and `windowChromeSvg`, from `frame/window.js`), `geometry`, `letterIcon`, `cursor`, `THEMES`, `W`×`H`. |
 | `storeShots({browser, dir, toolbarIcon})`, `storeShotHtml(shot)`, `contextMenuHtml(menu)`, `pngUrl(png)`, `PANEL_W`, `PANEL_HEADER_H` | The family's store screenshots in one style: a caption in sentence case over Chrome's light window with the extension pinned in the toolbar, real captures (taken at 2×) inside; what headless Chrome can't capture composed around the real extension UI: the popup page hung from the pressed toolbar button, the side panel page beside the page under a header with the extension's name, the right-click menu drawn as macOS draws Chrome's (the extension's real titles). `shoot(file, shot)` writes a 1280×800 PNG. |
+| `storePromoTile({browser, extension, file, line, glow?, name?, icon?})`, `promoTileHtml(tile)`, `PROMO_W`, `PROMO_H` | The store's small promo tile (440×280) in the family's one style: the extension's `icons/icon.svg` with a soft glow (its colour `glow`, default Chrome's blue), its English `extShortName` and one short `line`, on the store screenshots' light background. Writes the PNG and returns its path. |
 | `placeholderWarning`, `repositoryReminder`, `printReleaseChecks` | See About links. |
 | `findDisallowedClones({runJscpd})` | Run jscpd and return clones `.jscpd-allowlist.json` doesn't cover (the `extension-kit duplication` command). |
 
@@ -735,7 +810,7 @@ chrome://bookmarks in Chromium 156 / Chrome 157; the sources are listed at the t
 
 ## Development
 
-`npm test` runs ESLint, a strict TypeScript check of the JSDoc (`checkJs`), the tests (the menu,
+`npm test` runs ESLint, a strict TypeScript check of the JSDoc (`checkJs`), the tests (the menu, the ZIP writer in Chrome,
 the dialog, the toast, the dialog site list, the window frame, icon rendering and the Chrome readers in Playwright's
 Chromium, the rest in Node and jsdom), and the
 copied-code guard. The `.d.ts` files are generated from the JSDoc: `npm run types` writes them, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.11.1",
+  "version": "1.13.0",
   "description": "Shared pieces for Chrome extensions: Chrome's own page styles and components, a Chrome Sync settings store, the light/dark toolbar glyph, Chrome's on-device model, content-script helpers, About links, and build and test helpers.",
   "type": "module",
   "main": "src/index.js",
@@ -60,6 +60,7 @@
     "@types/jsdom": "^30.0.0",
     "@types/node": "^26.6.6",
     "eslint": "^10.14.0",
+    "fflate": "^0.8.3",
     "globals": "^17.14.0",
     "jscpd": "^5.4.3",
     "jsdom": "^31.0.0",

package/src/build/index.d.ts

@@ -6,6 +6,7 @@
  */
 export { clonesFromReport, disallowedClones, findDisallowedClones } from './duplication.js';
 export { placeholderWarning, printReleaseChecks, repositoryReminder } from './release-checks.js';
+export { PROMO_H, PROMO_W, promoTileHtml, storePromoTile } from './promo-tile.js';
 export * as storeFrame from './store-frame.js';
 export { PANEL_HEADER_H, PANEL_W, contextMenuHtml, pngUrl, storeShotHtml, storeShots } from './store-shots.js';
 export { HOOK_FILE, PANEL_OPENER, TEST_BUILDS_ENV, buildTestCopy, testBuildDir } from './test-build.js';

package/src/build/index.js

@@ -7,6 +7,7 @@
 
 export { clonesFromReport, disallowedClones, findDisallowedClones } from './duplication.js';
 export { placeholderWarning, printReleaseChecks, repositoryReminder } from './release-checks.js';
+export { PROMO_H, PROMO_W, promoTileHtml, storePromoTile } from './promo-tile.js';
 export * as storeFrame from './store-frame.js';
 export { PANEL_HEADER_H, PANEL_W, contextMenuHtml, pngUrl, storeShotHtml, storeShots } from './store-shots.js';
 export { HOOK_FILE, PANEL_OPENER, TEST_BUILDS_ENV, buildTestCopy, testBuildDir } from './test-build.js';

package/src/build/promo-tile.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The Chrome Web Store's small promo tile (440×280) for the whole family, in one style: the
+ * extension's icon (drawn from its SVG, so it's sharp at any size) with a soft glow, its name
+ * and one short line, on the store screenshots' light background.
+ *
+ * {@link promoTileHtml} lays it out (pure); {@link storePromoTile} reads the icon and name from
+ * the extension folder and writes the PNG.
+ *
+ * @module build/promo-tile
+ */
+/** The promo tile's width. */
+export declare const PROMO_W = 440;
+/** The promo tile's height. */
+export declare const PROMO_H = 280;
+export type PromoTile = {
+    /**
+     * The icon: SVG markup, or an image's URL (a data: URL, say).
+     */
+    icon: string;
+    /**
+     * The extension's name (`extShortName`).
+     */
+    name: string;
+    /**
+     * One short line under it, sentence case (“Prices in your currency”).
+     */
+    line: string;
+    /**
+     * The colour of the glow under the icon, any CSS colour: the icon's own (default Chrome's blue).
+     */
+    glow?: string;
+};
+/**
+ * One promo tile.
+ *
+ * @typedef {object} PromoTile
+ * @property {string} icon The icon: SVG markup, or an image's URL (a data: URL, say).
+ * @property {string} name The extension's name (`extShortName`).
+ * @property {string} line One short line under it, sentence case (“Prices in your currency”).
+ * @property {string} [glow] The colour of the glow under the icon, any CSS colour: the icon's own (default Chrome's blue).
+ */
+/**
+ * The tile's page: the icon, the name and the line, centred, at 440×280.
+ *
+ * @param {PromoTile} tile - What it shows.
+ * @returns {string} A whole HTML document.
+ * @example
+ * promoTileHtml({ icon: svg, name: 'Better Prices', line: 'Prices in your currency', glow: '#146c2e' });
+ */
+export declare function promoTileHtml({ icon, name, line, glow }: PromoTile): string;
+/**
+ * Write an extension's promo tile: its `icons/icon.svg` and English `extShortName` (unless
+ * `icon` or `name` is given), drawn by {@link promoTileHtml} in a page of the given browser.
+ *
+ * @param {object} options - What and where.
+ * @param {import('playwright').Browser | import('playwright').BrowserContext} options.browser - A browser (or a context) to draw in.
+ * @param {string} options.extension - The extension's folder (`extension`, or `src` where a build bundles it).
+ * @param {string} options.file - The PNG to write (its folder is made if missing), e.g. `store/promo-440x280.png`.
+ * @param {string} options.line - The line under the name.
+ * @param {string} [options.glow] - The glow's colour (see {@link PromoTile}).
+ * @param {string} [options.name] - The name, if not the extension's `extShortName`.
+ * @param {string} [options.icon] - The icon, if not the extension's `icons/icon.svg`.
+ * @returns {Promise<string>} The file written.
+ * @example
+ * await storePromoTile({ browser, extension: 'extension', file: 'store/promo-440x280.png', line: 'Prices in your currency' });
+ */
+export declare function storePromoTile({ browser, extension, file, line, glow, name, icon }: {
+    browser: import('playwright').Browser | import('playwright').BrowserContext;
+    extension: string;
+    file: string;
+    line: string;
+    glow?: string;
+    name?: string;
+    icon?: string;
+}): Promise<string>;

package/src/build/promo-tile.js

@@ -0,0 +1,87 @@
+/**
+ * The Chrome Web Store's small promo tile (440×280) for the whole family, in one style: the
+ * extension's icon (drawn from its SVG, so it's sharp at any size) with a soft glow, its name
+ * and one short line, on the store screenshots' light background.
+ *
+ * {@link promoTileHtml} lays it out (pure); {@link storePromoTile} reads the icon and name from
+ * the extension folder and writes the PNG.
+ *
+ * @module build/promo-tile
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { esc } from '../frame/window.js';
+import { THEMES } from './store-frame.js';
+
+/** The promo tile's width. */
+export const PROMO_W = 440;
+/** The promo tile's height. */
+export const PROMO_H = 280;
+
+/** The glow under the icon when none is given: Chrome's blue. */
+const GLOW = '#0b57d0';
+
+/**
+ * One promo tile.
+ *
+ * @typedef {object} PromoTile
+ * @property {string} icon The icon: SVG markup, or an image's URL (a data: URL, say).
+ * @property {string} name The extension's name (`extShortName`).
+ * @property {string} line One short line under it, sentence case (“Prices in your currency”).
+ * @property {string} [glow] The colour of the glow under the icon, any CSS colour: the icon's own (default Chrome's blue).
+ */
+
+/**
+ * The tile's page: the icon, the name and the line, centred, at 440×280.
+ *
+ * @param {PromoTile} tile - What it shows.
+ * @returns {string} A whole HTML document.
+ * @example
+ * promoTileHtml({ icon: svg, name: 'Better Prices', line: 'Prices in your currency', glow: '#146c2e' });
+ */
+export function promoTileHtml({ icon, name, line, glow = GLOW }) {
+  const art = icon.trimStart().startsWith('<') ? icon : `<img src="${icon}" alt="">`;
+  return `<!doctype html><html><head><meta charset="utf-8"><style>
+    html, body { margin: 0; }
+    body { width: ${PROMO_W}px; height: ${PROMO_H}px; overflow: hidden; display: grid; place-items: center; background: linear-gradient(160deg, ${THEMES.light.bg}, #dde3ea); -webkit-font-smoothing: antialiased; font-family: system-ui; }
+    .wrap { display: flex; flex-direction: column; align-items: center; gap: 12px; }
+    .icon { width: 112px; height: 112px; filter: drop-shadow(0 6px 14px color-mix(in srgb, ${glow} 28%, transparent)); }
+    .icon svg, .icon img { display: block; width: 100%; height: 100%; }
+    h1 { margin: 0; font: 600 30px/1.1 system-ui; color: #1f1f1f; letter-spacing: -.3px; }
+    p { margin: 0; font: 400 17px system-ui; color: #444746; }
+  </style></head><body><div class="wrap"><div class="icon">${art}</div><h1>${esc(name)}</h1><p>${esc(line)}</p></div></body></html>`;
+}
+
+/**
+ * Write an extension's promo tile: its `icons/icon.svg` and English `extShortName` (unless
+ * `icon` or `name` is given), drawn by {@link promoTileHtml} in a page of the given browser.
+ *
+ * @param {object} options - What and where.
+ * @param {import('playwright').Browser | import('playwright').BrowserContext} options.browser - A browser (or a context) to draw in.
+ * @param {string} options.extension - The extension's folder (`extension`, or `src` where a build bundles it).
+ * @param {string} options.file - The PNG to write (its folder is made if missing), e.g. `store/promo-440x280.png`.
+ * @param {string} options.line - The line under the name.
+ * @param {string} [options.glow] - The glow's colour (see {@link PromoTile}).
+ * @param {string} [options.name] - The name, if not the extension's `extShortName`.
+ * @param {string} [options.icon] - The icon, if not the extension's `icons/icon.svg`.
+ * @returns {Promise<string>} The file written.
+ * @example
+ * await storePromoTile({ browser, extension: 'extension', file: 'store/promo-440x280.png', line: 'Prices in your currency' });
+ */
+export async function storePromoTile({ browser, extension, file, line, glow, name, icon }) {
+  const svg = icon ?? await readFile(path.join(extension, 'icons', 'icon.svg'), 'utf8');
+  const title = name ?? JSON.parse(await readFile(path.join(extension, '_locales', 'en', 'messages.json'), 'utf8')).extShortName.message;
+  const context = 'newContext' in browser ? await browser.newContext({ viewport: { width: PROMO_W, height: PROMO_H }, deviceScaleFactor: 1 }) : null;
+  const page = context ? await context.newPage() : await /** @type {import('playwright').BrowserContext} */ (browser).newPage();
+  try {
+    await page.setViewportSize({ width: PROMO_W, height: PROMO_H });
+    await page.setContent(promoTileHtml({ icon: svg, name: String(title), line, glow }), { waitUntil: 'load' });
+    await page.evaluate(() => Promise.all([...document.images].map((img) => img.decode().catch(() => undefined))));
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, await page.screenshot({ type: 'png', scale: 'css', clip: { x: 0, y: 0, width: PROMO_W, height: PROMO_H } }));
+    return file;
+  } finally {
+    await (context ?? page).close();
+  }
+}

package/src/build/vendor.js

@@ -31,7 +31,7 @@ const SOURCE = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const KIT = '@arraypress/extension-kit';
 
 /** What a vendored copy of the kit holds, relative to `src/`: everything an extension page or worker may load. */
-export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'ai', 'commands', 'content', 'dom', 'frame', 'panel', 'scripting', 'settings', 'sites', 'styles', 'time', 'toolbar', 'ui']);
+export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'ai', 'commands', 'content', 'dom', 'files', 'frame', 'net', 'panel', 'scripting', 'settings', 'sites', 'styles', 'time', 'toolbar', 'ui']);
 
 /** The kit's stylesheet, an absolute path in the installed package. */
 export const STYLESHEET = path.join(SOURCE, 'styles', 'chrome-ui.css');

package/src/files/save.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Saving files a page has made: through Chrome's downloads when the person has allowed it (asked
+ * from the Download click: “Manage your downloads”), else as a link's download, which Chrome
+ * saves the same way, one file at a time.
+ *
+ * @module files/save
+ */
+/** How long a file's address is kept once Chrome has it (ms): long enough to finish saving it. */
+export declare const KEEP_URL_MS = 60000;
+export type SavedFile = {
+    /**
+     * Its name; with `chrome.downloads`, a path under the Downloads folder (`Trips/Lake.jpg`).
+     */
+    name: string;
+    /**
+     * Its contents.
+     */
+    blob: Blob;
+};
+/**
+ * A file to save.
+ *
+ * @typedef {object} SavedFile
+ * @property {string} name Its name; with `chrome.downloads`, a path under the Downloads folder (`Trips/Lake.jpg`).
+ * @property {Blob} blob Its contents.
+ */
+/**
+ * Save files, in order. Each gets a blob address, let go after {@link KEEP_URL_MS}. With
+ * `chrome.downloads`, a name already taken gets a number (“Lake (1).jpg”) and each download is
+ * started before the next; without, Chrome saves each link's download to the Downloads folder
+ * (and asks before a page saves several).
+ *
+ * @param {readonly SavedFile[]} files - The files.
+ * @param {Pick<typeof chrome.downloads, 'download'> | undefined} downloads - `chrome.downloads`, once granted (undefined until then).
+ * @param {Document} [doc] - The page, for a link's download. Default `document` (not read in a worker, which has `chrome.downloads` or nothing).
+ * @returns {Promise<void>} Once Chrome has every file's address.
+ * @example
+ * await saveFiles([{ name: 'Capture.zip', blob: await zip.finish() }], chrome.downloads);
+ */
+export declare function saveFiles(files: readonly SavedFile[], downloads: Pick<typeof chrome.downloads, 'download'> | undefined, doc?: Document): Promise<void>;

package/src/files/save.js

@@ -0,0 +1,46 @@
+/**
+ * Saving files a page has made: through Chrome's downloads when the person has allowed it (asked
+ * from the Download click: “Manage your downloads”), else as a link's download, which Chrome
+ * saves the same way, one file at a time.
+ *
+ * @module files/save
+ */
+
+/** How long a file's address is kept once Chrome has it (ms): long enough to finish saving it. */
+export const KEEP_URL_MS = 60_000;
+
+/**
+ * A file to save.
+ *
+ * @typedef {object} SavedFile
+ * @property {string} name Its name; with `chrome.downloads`, a path under the Downloads folder (`Trips/Lake.jpg`).
+ * @property {Blob} blob Its contents.
+ */
+
+/**
+ * Save files, in order. Each gets a blob address, let go after {@link KEEP_URL_MS}. With
+ * `chrome.downloads`, a name already taken gets a number (“Lake (1).jpg”) and each download is
+ * started before the next; without, Chrome saves each link's download to the Downloads folder
+ * (and asks before a page saves several).
+ *
+ * @param {readonly SavedFile[]} files - The files.
+ * @param {Pick<typeof chrome.downloads, 'download'> | undefined} downloads - `chrome.downloads`, once granted (undefined until then).
+ * @param {Document} [doc] - The page, for a link's download. Default `document` (not read in a worker, which has `chrome.downloads` or nothing).
+ * @returns {Promise<void>} Once Chrome has every file's address.
+ * @example
+ * await saveFiles([{ name: 'Capture.zip', blob: await zip.finish() }], chrome.downloads);
+ */
+export async function saveFiles(files, downloads, doc = globalThis.document) {
+  for (const file of files) {
+    const url = URL.createObjectURL(file.blob);
+    setTimeout(() => URL.revokeObjectURL(url), KEEP_URL_MS);
+    if (downloads) {
+      await downloads.download({ url, filename: file.name, conflictAction: 'uniquify' });
+    } else {
+      const link = doc.createElement('a');
+      link.href = url;
+      link.download = file.name;
+      link.click();
+    }
+  }
+}

package/src/files/zip.d.ts

@@ -0,0 +1,217 @@
+/**
+ * A ZIP written a file at a time, with nothing but the platform: each file's
+ * bytes go into the ZIP as they're added and from there into a Blob (which
+ * Chrome keeps outside the page's memory, on disk once large), so a page
+ * never holds the files and the ZIP together. Files already compressed
+ * (images, audio, video, PDFs, archives) are stored as they are; the rest
+ * (SVG, CSV, plain text) is deflated by `CompressionStream('deflate-raw')`
+ * (Chrome 103, Node 20.12). ZIP64 is written when a file, the ZIP or the
+ * number of files passes what a plain ZIP can say. Runs anywhere (page,
+ * worker, Node).
+ *
+ * How each entry is written, and why:
+ *
+ * - **Stored** entries are read twice: once for the CRC-32, then the local
+ *   header is written with the real CRC and sizes, then the bytes. No data
+ *   descriptor: a stored entry whose header says "sizes follow the data"
+ *   can't be read forwards (nothing marks where its data ends), and readers
+ *   that go by the local headers refuse it or stop there. A Blob is read in
+ *   slices both times, so a 2 GB video never sits in memory whole.
+ * - **Deflated** entries are read once and followed by a data descriptor
+ *   (general-purpose bit 3), as every streaming ZIP writer does: the
+ *   compressed size is known only afterwards, and a deflate stream marks its
+ *   own end, so every reader copes.
+ *
+ * @module files/zip
+ */
+/** ZIP bytes held in memory before they're handed to the Blob: 16 MiB. */
+export declare const HELD_BYTES: number;
+/** How much of a Blob is read at a time: 4 MiB. A smaller Blob is read whole. */
+export declare const SLICE_BYTES: number;
+/**
+ * The CRC-32 of some bytes (ZIP's, PNG's and gzip's), or of more bytes after others: give the
+ * CRC so far as `seed` and the result is the CRC of both together.
+ *
+ * @param {Uint8Array} bytes - The bytes.
+ * @param {number} [seed] - The CRC of what came before. Default 0 (nothing).
+ * @returns {number} The CRC, 0 to 0xFFFFFFFF.
+ * @example
+ * crc32(new TextEncoder().encode('123456789')); // 0xCBF43926
+ * crc32(rest, crc32(start)); // the CRC of start followed by rest
+ */
+export declare function crc32(bytes: Uint8Array, seed?: number): number;
+/**
+ * Whether a file of this name is stored in a ZIP as it is, going by its extension: formats that
+ * are compressed already (JPEG, PNG, WebP, MP4, PDF, ZIP, Office documents, WOFF…). Anything else
+ * (SVG, CSV, JSON, text, BMP, WAV) is deflated.
+ *
+ * @param {string} name - The file's name or path.
+ * @returns {boolean} True for a compressed format.
+ * @example
+ * isStoredName('Lake.JPG'); // true
+ * isStoredName('icons/logo.svg'); // false
+ */
+export declare function isStoredName(name: string): boolean;
+export type Record = {
+    /**
+     * Two bytes.
+     */
+    u16: (value: number) => Record;
+    /**
+     * Four bytes.
+     */
+    u32: (value: number) => Record;
+    /**
+     * Eight bytes (a whole number up to 2^53).
+     */
+    u64: (value: number) => Record;
+    /**
+     * Bytes as they are.
+     */
+    raw: (part: Uint8Array) => Record;
+    /**
+     * The record.
+     */
+    bytes: Uint8Array<ArrayBuffer>;
+};
+export type Entry = {
+    /**
+     * The name, UTF-8.
+     */
+    name: Uint8Array;
+    /**
+     * Stored (method 0) rather than deflated (method 8, with a data descriptor).
+     */
+    stored: boolean;
+    /**
+     * Sizes and offset written as ZIP64.
+     */
+    zip64: boolean;
+    /**
+     * Its time.
+     */
+    when: {
+        time: number;
+        day: number;
+    };
+    /**
+     * Where its local header starts.
+     */
+    offset: number;
+    /**
+     * Its CRC-32.
+     */
+    crc: number;
+    /**
+     * Its size.
+     */
+    size: number;
+    /**
+     * Its size in the ZIP.
+     */
+    packed: number;
+};
+export type ZipOptions = {
+    /**
+     * Store every file as it is, deflating none (a ZIP of PNGs whatever
+     * their names, or when time matters more than size). Default: by name, see {@link isStoredName}.
+     */
+    store?: boolean;
+    /**
+     * Write ZIP64 records for every file and for the ZIP's end, however
+     * small. Default: only when needed (a file of about 4 GiB or more, a ZIP that has grown past
+     * 4 GiB, more than 65,535 files).
+     */
+    zip64?: boolean;
+    /**
+     * ZIP bytes held in memory before they're handed to the Blob.
+     * Default {@link HELD_BYTES}, 16 MiB.
+     */
+    heldBytes?: number;
+    /**
+     * The files' time in the ZIP (local time, as ZIP keeps it). Default now.
+     */
+    date?: Date;
+};
+export type ZipEntryOptions = {
+    /**
+     * Store this file as it is (true), or go by its name (false) even
+     * if the ZIP stores everything.
+     */
+    store?: boolean;
+    /**
+     * This file's time.
+     */
+    date?: Date;
+};
+export type ZipWriter = {
+    /**
+     *   Put a file in; resolves once it's written. Files are written in the order they're added,
+     *   one at a time (an `add` made before the last has resolved waits for it). The name is used
+     *   as it is, `/` between folders; a name already in the ZIP is refused (two files of one name
+     *   extract as one), as is `add` after `finish`. A file that can't be read rejects and leaves
+     *   the ZIP as it was before it. Bytes given as a `Uint8Array` are kept, not copied, until
+     *   they're handed to the Blob: don't write into them again.
+     */
+    add: (name: string, data: Blob | Uint8Array, options?: ZipEntryOptions) => Promise<void>;
+    /**
+     * How many files are in.
+     */
+    count: () => number;
+    /**
+     * Their size in all, uncompressed.
+     */
+    bytes: () => number;
+    /**
+     * Close the ZIP and give it, of type `application/zip` (once).
+     */
+    finish: () => Promise<Blob>;
+};
+/**
+ * How a ZIP is written.
+ *
+ * @typedef {object} ZipOptions
+ * @property {boolean} [store] Store every file as it is, deflating none (a ZIP of PNGs whatever
+ *   their names, or when time matters more than size). Default: by name, see {@link isStoredName}.
+ * @property {boolean} [zip64] Write ZIP64 records for every file and for the ZIP's end, however
+ *   small. Default: only when needed (a file of about 4 GiB or more, a ZIP that has grown past
+ *   4 GiB, more than 65,535 files).
+ * @property {number} [heldBytes] ZIP bytes held in memory before they're handed to the Blob.
+ *   Default {@link HELD_BYTES}, 16 MiB.
+ * @property {Date} [date] The files' time in the ZIP (local time, as ZIP keeps it). Default now.
+ */
+/**
+ * How one file is written, where it differs from the ZIP's own options.
+ *
+ * @typedef {object} ZipEntryOptions
+ * @property {boolean} [store] Store this file as it is (true), or go by its name (false) even
+ *   if the ZIP stores everything.
+ * @property {Date} [date] This file's time.
+ */
+/**
+ * A ZIP being written.
+ *
+ * @typedef {object} ZipWriter
+ * @property {(name: string, data: Blob | Uint8Array, options?: ZipEntryOptions) => Promise<void>} add
+ *   Put a file in; resolves once it's written. Files are written in the order they're added,
+ *   one at a time (an `add` made before the last has resolved waits for it). The name is used
+ *   as it is, `/` between folders; a name already in the ZIP is refused (two files of one name
+ *   extract as one), as is `add` after `finish`. A file that can't be read rejects and leaves
+ *   the ZIP as it was before it. Bytes given as a `Uint8Array` are kept, not copied, until
+ *   they're handed to the Blob: don't write into them again.
+ * @property {() => number} count How many files are in.
+ * @property {() => number} bytes Their size in all, uncompressed.
+ * @property {() => Promise<Blob>} finish Close the ZIP and give it, of type `application/zip` (once).
+ */
+/**
+ * Start a ZIP.
+ *
+ * @param {ZipOptions} [options] - How to write it.
+ * @returns {ZipWriter} The ZIP.
+ * @example
+ * const zip = createZip();
+ * await zip.add('Lake.jpg', blob); // stored
+ * await zip.add('notes/Read me.txt', new TextEncoder().encode('Hello')); // deflated
+ * const blob = await zip.finish();
+ */
+export declare function createZip(options?: ZipOptions): ZipWriter;