@lewismoten/gamemaker-sandbox-archives 0.0.0-stage → 3.2.0

package/dist/scan.js

@@ -0,0 +1,263 @@
+import { normalize as y, cdName as R, GameFiles as q, IGNORED_FILE as U } from "@lewismoten/gamemaker-sandbox-engine/core/gameFiles";
+import { listZip as X, crc32 as V, isZip as K } from "./zip.js";
+import { gameTitle as Q, parseGame as Y } from "@lewismoten/gamemaker-sandbox-engine/formats/game";
+import { isFli as tt } from "@lewismoten/gamemaker-sandbox-engine/formats/fli";
+import { isGif as et } from "@lewismoten/gamemaker-sandbox-engine/formats/gif";
+import { isVoc as st } from "@lewismoten/gamemaker-sandbox-engine/formats/voc";
+import { markZipLeftovers as nt } from "./project/importLeftovers.js";
+const at = {
+  fli: ["an animation (FLI)", tt],
+  gif: ["a picture (GIF)", et],
+  voc: ["a sound (VOC)", st]
+};
+async function it(t) {
+  const s = [];
+  for (const a of t) {
+    const i = at[/\.([^./\\]+)$/.exec(a.path)?.[1].toLowerCase() ?? ""];
+    if (!i || !a.size) continue;
+    const o = await a.read().catch(() => {
+    });
+    o && !i[1](o) && s.push({ path: a.path, says: i[0] });
+  }
+  return s;
+}
+const S = (t, s) => /\.exe$/i.test(t) && s === 160598, D = 3, ot = 64 << 20, rt = (t) => /\.exe$/i.test(t), ct = /\.(txt|doc|diz|nfo|me|1st|htm|html|md|wri|rtf|cfg|conf|bat)$/i, H = (t) => `${t} (a self-extracting archive)`;
+function pt(t, s) {
+  const a = t.filter((e) => !P(u(e.path))), i = a.map((e) => M(u(e.path)));
+  if (!a.length) return "it is empty";
+  if (a.length === 1) return `only ${i[0]}${s.has(a[0]) ? ", a self-extracting archive with no game" : ""}`;
+  if (a.every((e) => ct.test(e.path))) return `only text files (${i.join(", ")})`;
+  const o = i.slice(0, 3).join(", ");
+  return `${a.length} files, such as ${o}${a.length > 3 ? "…" : ""}`;
+}
+const u = (t) => t.replace(/\\/g, "/").replace(/^(\.\/|\/)+/, ""), B = (t) => t.includes("/") ? t.slice(0, t.lastIndexOf("/")) : "", M = (t) => t.slice(t.lastIndexOf("/") + 1), P = (t) => /(^|\/)__MACOSX\//i.test(t) || /^\._|^\.ds_store$|^thumbs\.db$/i.test(M(t)), W = (t) => /\.gam$/i.test(t), F = (t) => /\.zip$/i.test(t), lt = (t) => !F(t.path) && (!U.test(M(t.path)) || S(t.path, t.size));
+function ht(t, s = /* @__PURE__ */ new Set()) {
+  const a = t.filter((n) => !P(u(n.path)) && !F(n.path)), i = [...new Set(a.filter((n) => W(n.path) || s.has(n)).map((n) => B(u(n.path))))].sort((n, r) => r.length - n.length), o = new Map(i.map((n) => [n, []])), e = [];
+  for (const n of a) {
+    const r = B(u(n.path)), d = i.length === 1 ? i[0] : i.find((g) => g === "" || r === g || r.startsWith(`${g}/`));
+    d === void 0 ? e.push(n) : lt(n) && o.get(d).push(n);
+  }
+  return {
+    games: [...o].map(([n, r]) => ({ dir: n, files: r })).sort((n, r) => n.dir.localeCompare(r.dir, void 0, { numeric: !0, sensitivity: "base" })),
+    loose: e
+  };
+}
+function ft(t) {
+  let s = "";
+  for (let a = 0; a < 4 && t[153270 + a]; a++) s += String.fromCharCode(t[153270 + a]);
+  return s = s.trim().toLowerCase(), s === "." || !s ? "" : s;
+}
+async function mt(t) {
+  const s = /* @__PURE__ */ new Map(), a = /* @__PURE__ */ new Set(), i = /* @__PURE__ */ new Map(), o = t.filter((e) => !P(u(e.path)));
+  for (const e of o.filter((n) => S(n.path, n.size))) {
+    const n = await e.read().catch(() => {
+    });
+    if (!n) continue;
+    i.set(e, V(n));
+    const r = ft(n), d = u(e.path), g = o.filter((l) => l !== e && B(u(l.path)) === B(d)), O = y(`${M(d).replace(/\.[^.]*$/, "")}${r}`), I = g.find((l) => y(l.path) === O);
+    if (I && (s.set(e, I), a.add(I)), r && r !== ".gam")
+      for (const l of g) y(l.path).endsWith(r) && a.add(l);
+  }
+  return { players: s, games: a, crcs: i };
+}
+function ut(t, s) {
+  if (!t) return 0;
+  const a = new Set(s.flatMap((i) => [y(i.path), R(i.path)]));
+  try {
+    return [...new Set(
+      Y(t).scenes.flatMap((o) => o.files).filter((o) => o && !/\.(his|sav|rec)$/i.test(o)).map(y)
+    )].filter((o) => !a.has(o) && !a.has(R(o))).length;
+  } catch {
+    return 0;
+  }
+}
+function dt(t, s) {
+  try {
+    if (t) return Q(Y(t)) || s;
+  } catch {
+  }
+  return s;
+}
+const J = (t, s) => [...t, s ? `${s}/` : ""].filter(Boolean).join(" › "), gt = () => new Promise((t) => setTimeout(t, 0));
+async function It(t, { signal: s, onProgress: a, onStep: i, zipLimits: o } = {}) {
+  const e = { games: [], zips: 0, emptyZips: [], badZips: [], loose: [] }, n = t.filter((l) => F(l.path));
+  let r = 0;
+  const d = async (l, $, E, x) => {
+    const { players: G, games: C, crcs: Z } = await mt(l), { games: _, loose: L } = ht(l, C);
+    (e.misnamed ??= []).push(...await it(l.filter((c) => !F(c.path)))), $.length || e.loose.push(...L);
+    let m = 0;
+    const v = async (c, p, z, j, A) => {
+      const N = [];
+      let h = "", f = 0;
+      for (const [b, w] of p.entries()) {
+        const T = await w.read().catch(() => {
+        });
+        T && N.push(V(T)), b === 0 && (h = dt(T, j ?? y(w.path)), f = ut(T, z));
+      }
+      const k = z.map((b) => Z.get(b)).filter((b) => b !== void 0);
+      e.games.push({
+        name: h,
+        from: J($.length ? [$[0].path, ...E].map(u) : [], c.dir),
+        gamCrcs: N,
+        ...k.length ? { playerCrcs: k } : {},
+        fileCount: z.length,
+        bytes: z.reduce((b, w) => b + w.size, 0),
+        zips: $.slice(0, 1),
+        inner: E,
+        paths: z.map((b) => b.path),
+        gam: j,
+        ...f ? { missing: f } : {},
+        ...A?.(f) ? { leftover: A(f) } : {}
+      }), m++;
+    };
+    for (const c of _) {
+      const p = c.files.filter((h) => W(h.path) || C.has(h)).sort((h, f) => y(h.path).localeCompare(y(f.path)));
+      if (p.length < 2) {
+        await v(c, p, c.files);
+        continue;
+      }
+      const z = new Map([...G].filter(([h, f]) => c.files.includes(h) && c.files.includes(f)).map(([h, f]) => [f, h])), j = new Set(z.values()), A = c.files.some((h) => S(h.path, h.size)), N = $.length ? "the zip" : "the folder";
+      for (const h of [...p].sort((f, k) => Number(z.has(k)) - Number(z.has(f)))) {
+        const f = z.get(h), k = c.files.filter((w) => w === h || !p.includes(w) && (!f || !j.has(w) || w === f)), b = y(`${M(u(h.path)).replace(/\.[^.]*$/, "")}.gam`);
+        await v(
+          c,
+          [h],
+          k,
+          b,
+          (w) => w && !f ? `${b.toUpperCase()}: ${w} of its files ${w === 1 ? "isn’t" : "aren’t"} in ${N}${A ? "; no player loads it" : ""}` : void 0
+        );
+      }
+    }
+    for (const c of l.filter((p) => F(p.path) && !P(u(p.path)))) {
+      s?.throwIfAborted();
+      const p = x === 0;
+      p && a?.(r++, n.length, c.path);
+      const z = await O(c, p ? [c] : $, p ? [] : [...E, c.path], x);
+      m += z ?? 0, p && await gt();
+    }
+    if (x < D)
+      for (const c of L.filter((p) => rt(p.path) && !S(p.path, p.size) && p.size <= ot)) {
+        s?.throwIfAborted();
+        const p = await O(c, x === 0 ? [c] : $, x === 0 ? [] : [...E, c.path], x, !0);
+        p !== void 0 && (g.add(c), m += p);
+      }
+    return m;
+  }, g = /* @__PURE__ */ new Set(), O = async (l, $, E, x, G = !1) => {
+    const C = [$[0].path, ...E].map(u).join(" › ");
+    let Z;
+    try {
+      i?.("unpack", C);
+      const m = await l.read();
+      if (G) {
+        if (!m || m[0] !== 77 || m[1] !== 90) return;
+        try {
+          Z = X(m, o).map((v) => ({ path: v.name, size: v.size, read: v.read }));
+        } catch {
+          return;
+        }
+      } else {
+        if (!m || !K(m)) throw new Error("It is not a zip file.");
+        Z = X(m, o).map((v) => ({ path: v.name, size: v.size, read: v.read }));
+      }
+    } catch (m) {
+      return e.zips++, e.badZips.push({ path: C, error: m.message || "It could not be read." }), 0;
+    }
+    e.zips++, G && I.add(C);
+    const _ = x + 1 >= D ? Z.filter((m) => !F(m.path)) : Z;
+    i?.("find", C);
+    const L = await d(_, $, E, x + 1);
+    return L || e.emptyZips.push({ path: G ? H(C) : C, held: pt(_, g) }), L;
+  }, I = /* @__PURE__ */ new Set();
+  return await d(t, [], [], 0), e.games = nt(wt(e.games, I)), e.loose = e.loose.filter((l) => !g.has(l)), e.games.sort((l, $) => l.from.localeCompare($.from, void 0, { numeric: !0, sensitivity: "base" })), a?.(n.length, n.length), e;
+}
+function wt(t, s) {
+  const a = (e) => {
+    const n = [...s].find((r) => e.from === r || e.from.startsWith(`${r} › `));
+    return n ? e.from.replace(n, H(n)) : e.from || "the files picked";
+  }, i = /* @__PURE__ */ new Map(), o = [];
+  for (const e of t) {
+    if (!e.gamCrcs.length) {
+      o.push(e);
+      continue;
+    }
+    const n = [...e.gamCrcs].sort().join(","), r = i.get(n);
+    r ? r.push(e) : i.set(n, [e]);
+  }
+  for (const e of i.values()) {
+    const n = e.reduce((d, g) => g.fileCount > d.fileCount ? g : d), r = e.filter((d) => d !== n);
+    o.push(r.length ? { ...n, alsoIn: r.map(a) } : n);
+  }
+  return o;
+}
+function Zt(t) {
+  const s = (o, e, n = `${e}s`) => `${o} ${o === 1 ? e : n}`, a = [`${s(t.games.length, "game")} found`];
+  t.emptyZips.length && a.push(`${s(t.emptyZips.length, "zip")} had no game`), t.badZips.length && a.push(`${s(t.badZips.length, "zip")} could not be read`), t.misnamed?.length && a.push(`${s(t.misnamed.length, "file")} not what ${t.misnamed.length === 1 ? "its" : "their"} extension says`);
+  const i = t.games.reduce((o, e) => o + (e.alsoIn?.length ?? 0), 0);
+  return i && a.push(`${s(i, "copy", "copies")} of the same ${i === 1 ? "game" : "games"} left out`), !t.games.length && t.zips && !t.emptyZips.length && !t.badZips.length && a.push(`in ${s(t.zips, "zip")}`), a.join(", ");
+}
+async function yt(t, s) {
+  const a = new q(), i = [];
+  for (const [o, e] of t.entries()) {
+    await s?.(o, t.length, e.path);
+    const n = M(u(e.path));
+    if (S(n, e.size)) {
+      const r = await e.read();
+      r && i.push({ name: n, bytes: r });
+    } else if (!U.test(n)) {
+      const r = await e.read();
+      r && a.set(n, r);
+    }
+  }
+  return { files: a, players: i };
+}
+class kt {
+  constructor(s, a) {
+    this.zipLimits = a, this.loose = new Map(s.map((i) => [i.path, i]));
+  }
+  zipLimits;
+  loose;
+  last;
+  /** One of a found game's files by its DOS name (its title screen's), without reading the rest. */
+  async file(s, a) {
+    const i = s.zips.length ? await this.zipEntries(s) : this.loose, o = y(a), e = R(a), n = s.paths.find((r) => y(r) === o) ?? s.paths.find((r) => y(r) === e);
+    return n ? i.get(n)?.read() : void 0;
+  }
+  /** The .gam a found game plays: its own when its folder holds others, else the first. */
+  mainGam(s) {
+    return s.gam ?? s.paths.filter(W).map(y).sort()[0];
+  }
+  async read(s, a) {
+    const i = s.zips.length ? await this.zipEntries(s) : this.loose, o = await yt(
+      s.paths.map((e) => i.get(e)).filter((e) => !!e),
+      a
+    );
+    return s.gam ? { ...o, name: s.name, gam: s.gam } : o;
+  }
+  async zipEntries(s) {
+    const a = [s.zips[0].path, ...s.inner].join(`
+`);
+    if (this.last?.key === a) return this.last.entries;
+    this.last = void 0;
+    let i = await s.zips[0].read();
+    for (const e of s.inner) {
+      const n = i && X(i, this.zipLimits).find((r) => r.name === e);
+      i = n ? await n.read() : void 0;
+    }
+    if (!i) throw new Error(`${J([s.zips[0].path, ...s.inner].map(u), "")} could not be read again.`);
+    const o = new Map(X(i, this.zipLimits).map((e) => [e.name, { path: e.name, size: e.size, read: e.read }]));
+    return this.last = { key: a, entries: o }, o;
+  }
+}
+function Ft(t, s = t.webkitRelativePath || t.name) {
+  return { path: s, size: t.size, read: async () => new Uint8Array(await t.arrayBuffer()) };
+}
+export {
+  kt as GameReader,
+  S as PLAYER_EXE,
+  yt as gameFromFiles,
+  ht as groupGames,
+  mt as playedBy,
+  Ft as scanFile,
+  It as scanImport,
+  Zt as scanSummary
+};

package/dist/types/index.d.ts

@@ -0,0 +1,25 @@
+import { type ScanFile } from './project/importScan.js';
+import { type ImportedPlayer } from './project/importPlayer.js';
+export { scanImport, GameReader, scanFile, gameFromFiles, scanSummary, groupGames, playedBy, PLAYER_EXE, type ScanFile, type ScanOptions, type ScanReport, type FoundGame, type ReadGame, } from './project/importScan.js';
+export { createZip, readZip, listZip, isZip, crc32, type ZipEntry, type ZipListing, type ZipLimits } from './project/zip.js';
+export interface UnpackOptions {
+    /** Optional source name, used for messages and archive detection. */
+    name?: string;
+    signal?: AbortSignal;
+    /** Bounds per archive and on the returned game's file data. Defaults: 8192 files, 128 MiB. */
+    maxEntries?: number;
+    maxBytes?: number;
+}
+export interface UnpackedGame {
+    name: string;
+    gam: string;
+    /** Portable tuples: pass these to the engine's own GameFiles constructor. */
+    entries: [string, Uint8Array][];
+    /** The game's player, when one was supplied: its Game-Maker build (`origin`) and, if customized, its settings. */
+    player?: ImportedPlayer;
+}
+export type GameInput = Uint8Array | ArrayBuffer | Iterable<ScanFile | File>;
+/** Discover and read games from folders, ZIPs, ZIP-based SFX EXEs, nested archives, or GMPK packs. */
+export declare function unpackGames(input: GameInput, options?: UnpackOptions): Promise<UnpackedGame[]>;
+/** Read exactly one game; collections use unpackGames or scanImport plus GameReader. */
+export declare function unpackGame(input: GameInput, options?: UnpackOptions): Promise<UnpackedGame>;

package/dist/types/player/applyPatches.d.ts

@@ -0,0 +1,25 @@
+import { type PreservedParts } from './preservedRegions.js';
+export type { PreservedParts } from './preservedRegions.js';
+import { type PlayerPatches } from '@lewismoten/gamemaker-sandbox-engine/player/patchRules';
+/** Game-Maker 3.00's XFERPLAY.EXE as it came on the CD (cd/gm/xferplay.exe). */
+export declare const STOCK_PLAYER_MD5 = "fcaf47d50ececa0b59cd22b3fae3cda3";
+/**
+ * A patched copy of the CD's player, with an imported 3.00 player's preserved parts (`kept`)
+ * written back. Throws when `exe` is any other file, or when a patch is unknown or breaks its
+ * rules (nothing is written then).
+ */
+export declare function applyPlayerPatches(exe: Uint8Array, patches: PlayerPatches, kept?: PreservedParts): Uint8Array;
+interface ReadPlayer {
+    /** The changes that could be read as patches. */
+    patches: PlayerPatches;
+    /** True when those explain every byte that differs from the CD's player. */
+    explained: boolean;
+    /** Entries that differ but break their rules (left out of `patches`). */
+    unreadable: string[];
+}
+/**
+ * What a player of XFERPLAY 3.00's size differs from the CD's in, as patches, its renamed file
+ * extensions included (`explained` false when other bytes changed too, such as an About page of
+ * its own). Undefined for any other size.
+ */
+export declare function readPlayerPatches(exe: Uint8Array): ReadPlayer | undefined;

package/dist/types/player/md5.d.ts

@@ -0,0 +1,2 @@
+/** The MD5 of `data`, as 32 lower-case hex digits. */
+export declare function md5Hex(data: Uint8Array): string;

package/dist/types/player/patchSpans.d.ts

@@ -0,0 +1,2 @@
+/** Every file offset patch `id` writes (none for an id it doesn't know). */
+export declare function patchSpans(id: string): number[];

package/dist/types/player/playerBuild.d.ts

@@ -0,0 +1,40 @@
+import { type BuildData } from './playerBuildData.js';
+type Confidence = 'high' | 'medium' | 'low';
+export interface PlayerIdentity {
+    /** '1.0', '1.04', '2.00', '2.02', '2.04', '3.00', '3.00-playgame', or 'unknown'. */
+    build: string;
+    /** For people: "Game-Maker 2.02", "Game-Maker 3.00 (PLAYGAME.EXE)" or "an unknown Game-Maker build". */
+    label: string;
+    confidence: Confidence;
+    reasons: string[];
+    /** True when every byte is the build's stock copy (its owner field aside). */
+    stock: boolean;
+    /** The About page's version line as this copy has it (an author could edit it). */
+    versionLine?: string;
+    /** Who replaced RSD's About text, as that text names them. */
+    aboutAuthor?: string;
+}
+export declare const buildData: (id: string) => BuildData | undefined;
+/** "Game-Maker 2.02"; the CD's PLAYGAME.EXE is named as such. */
+export declare function buildLabel(id: string): string;
+/** A copy with the build's owner field zeroed (what its MD5 and block CRCs were taken of). */
+export declare function withoutOwner(exe: Uint8Array, b: BuildData): Uint8Array;
+/** The About page's lines, read from the build's string slots. */
+export declare function aboutLines(exe: Uint8Array, b: BuildData): string[];
+/** The indexes of the 128-byte blocks of `exe` (owner field zeroed) that differ from the build's stock copy. */
+export declare function changedBlocks(exe: Uint8Array, b: BuildData): number[];
+/** True when a run of the About page's slots lies in a changed block. */
+export declare function aboutChanged(b: BuildData, blocks: number[]): boolean;
+export declare function identifyPlayer(exe: Uint8Array): PlayerIdentity;
+export interface FolderEstimate {
+    /** "3.00", "2.00 or later", "before 3.00", or "unknown". */
+    estimate: string;
+    confidence: Confidence;
+    reasons: string[];
+}
+/**
+ * What a folder without a readable player says about the build it was made with. Every
+ * pre-3.00 .gam is 6,600 bytes with no version in it, so this is an estimate with reasons.
+ */
+export declare function estimateFromFolder(names: string[], gams: Uint8Array[]): FolderEstimate;
+export {};

package/dist/types/player/playerBuildData.d.ts

@@ -0,0 +1,13 @@
+export declare const BLOCK = 128;
+export interface BuildData {
+    id: string;
+    size: number;
+    md5: string;
+    owner?: [number, number];
+    version: number;
+    about: number[];
+    text?: Record<string, [number, number] | [number, number, string]>;
+    ext?: Record<string, number[]>;
+    crc: string;
+}
+export declare const BUILD_DATA: BuildData[];

package/dist/types/player/playerPreserve.d.ts

@@ -0,0 +1,10 @@
+import { type PlayerPatches } from '@lewismoten/gamemaker-sandbox-engine/player/patchRules';
+import { type BuildData } from './playerBuildData.js';
+import { type PreservedRegion } from './preservedRegions.js';
+interface PreservedPlayer {
+    patches: PlayerPatches;
+    regions: PreservedRegion[];
+}
+/** A known build's copy as patches plus the raw blocks they don't explain. */
+export declare function preservePlayer(exe: Uint8Array, b: BuildData): PreservedPlayer;
+export {};

package/dist/types/player/preservedRegions.d.ts

@@ -0,0 +1,19 @@
+import type { PlayerPatches } from '@lewismoten/gamemaker-sandbox-engine/player/patchRules';
+/** A run of an author's bytes: where it starts in the player, and its bytes in base64. */
+export interface PreservedRegion {
+    offset: number;
+    data: string;
+}
+/** What an import kept of a 3.00 player: its raw regions and the patches read from it then. */
+export interface PreservedParts {
+    regions: PreservedRegion[];
+    patches: PlayerPatches;
+}
+export declare const toBase64: (b: Uint8Array) => string;
+/**
+ * Writes the regions into `exe` (a patched copy of the same build), in place, except the bytes of
+ * patches whose value differs from the import's (those are the project author's newer choices).
+ */
+export declare function writePreserved(exe: Uint8Array, kept: PreservedParts, patches: PlayerPatches): void;
+/** The printable runs (4+ characters) of a region, for showing it: [offset, text]. */
+export declare function regionText(r: PreservedRegion): [number, string][];

package/dist/types/project/extensionNames.d.ts

@@ -0,0 +1,4 @@
+/** `name` with its extension swapped by `map` (lower case, no dots), keeping its case; unchanged when the map has none for it. */
+export declare function swapExtension(name: string, map: Map<string, string>): string;
+/** Rewrites every file name with an extension in `map` inside `bytes` (a .gam, slide list or backdrop), in place, keeping its case. */
+export declare function rewriteNames(bytes: Uint8Array, map: Map<string, string>): Uint8Array;

package/dist/types/project/gamePack.d.ts

@@ -0,0 +1,17 @@
+/** The container of these files (not compressed). */
+export declare function encodePack(entries: Iterable<[string, Uint8Array]>): Uint8Array;
+/**
+ * Reads a pack as its bytes come in: push() each chunk (already unzipped) and get the files
+ * it completed. `done` once the end mark is read.
+ */
+export declare class PackReader {
+    private chunks;
+    private total;
+    /** Bytes the next step needs (it waits until that many are in, so a big file is joined once). */
+    private want;
+    private started;
+    done: boolean;
+    push(chunk: Uint8Array): [string, Uint8Array][];
+}
+/** Every file of a whole pack (not compressed). */
+export declare function decodePack(bytes: Uint8Array): [string, Uint8Array][];

package/dist/types/project/importLeftovers.d.ts

@@ -0,0 +1,3 @@
+import type { FoundGame } from './importScan.js';
+/** The games, those missing files beside a whole game of the same zip marked as leftovers. */
+export declare function markZipLeftovers(games: FoundGame[]): FoundGame[];

package/dist/types/project/importPlayer.d.ts

@@ -0,0 +1,39 @@
+import { type GameFiles } from '@lewismoten/gamemaker-sandbox-engine/core/gameFiles';
+import { type PlayerIdentity } from '../player/playerBuild.js';
+import type { PreservedRegion } from '../player/preservedRegions.js';
+import type { PlayerPatches } from '@lewismoten/gamemaker-sandbox-engine/player/patchRules';
+export { aboutLines, buildData, buildLabel, estimateFromFolder, identifyPlayer, type FolderEstimate, type PlayerIdentity } from '../player/playerBuild.js';
+export { BLOCK, BUILD_DATA, type BuildData } from '../player/playerBuildData.js';
+export { preservePlayer } from '../player/playerPreserve.js';
+export { regionText, type PreservedRegion } from '../player/preservedRegions.js';
+/** Where an imported game's player came from and what its author changed (the companion's record). */
+export interface PlayerOrigin extends PlayerIdentity {
+    /** The .EXE it came from. */
+    exe: string;
+    size: number;
+    md5: string;
+    /** The About page's lines when its author changed them (read-only: RSD's or the author's attribution). */
+    about?: string[];
+    /** Changed bytes no DOS player setting explains (an owner field never among them). */
+    regions: PreservedRegion[];
+    /** The settings read from it at import, so the DOS export can tell the project author's later changes. */
+    importPatches: PlayerPatches;
+}
+export interface ImportedPlayer {
+    /** The .EXE it came from. */
+    exe: string;
+    patches: PlayerPatches;
+    /** What was found, for a toast ('' when there's nothing to say, as for a stock player). */
+    message: string;
+    origin: PlayerOrigin;
+}
+/**
+ * Reads the player .EXE among an imported folder's files (`players`: the .EXEs the import
+ * otherwise leaves out): which Game-Maker build it is, its settings as DOS player patches (an
+ * older build's by 3.00's patch ids), and its other changed bytes, kept as they were; renames the
+ * game's files back if it renamed their extensions. Undefined when there is no player.
+ */
+export declare function adoptPlayer(files: GameFiles, players: {
+    name: string;
+    bytes: Uint8Array;
+}[]): ImportedPlayer | undefined;

package/dist/types/project/importScan.d.ts

@@ -0,0 +1,133 @@
+import { GameFiles } from '@lewismoten/gamemaker-sandbox-engine/core/gameFiles';
+import { type ZipLimits } from './zip.js';
+/** A file to look at: picked, dropped or in a zip. Its path is from the top of what was given. */
+export interface ScanFile {
+    path: string;
+    size: number;
+    read: () => Promise<Uint8Array | undefined>;
+}
+/** A game found, without its files' bytes. */
+export interface FoundGame {
+    /** Its title (the first scene's), else its .gam file's name. */
+    name: string;
+    /** Where it is: "games/zark.zip › zark/", or the folder, or "" for the files picked. */
+    from: string;
+    /** Its .gam files' CRC-32s (a CD shareware game is matched by these). */
+    gamCrcs: number[];
+    /** Its player .EXEs' CRC-32s, with gamCrcs its fingerprint (imported/fingerprint.ts). */
+    playerCrcs?: number[];
+    /** The files it brings (the .EXEs DOS alone needs are left out). */
+    fileCount: number;
+    /** The size of those files together, in bytes. */
+    bytes?: number;
+    /** The picked zip it is in (none for loose files), and the paths of the zips inside that one it is in, outermost first. */
+    zips: ScanFile[];
+    inner: string[];
+    /** Its files' paths, inside that zip or among the loose files. */
+    paths: string[];
+    /** When a folder holds several games, each with its own player: the .gam this one plays (named as it is once renamed back), and its title. */
+    gam?: string;
+    /** Where else the same game is (its .gam files byte for byte): those copies are left out. */
+    alsoIn?: string[];
+    /** Files its .gam names that are not here. */
+    missing?: number;
+    /** Why it is left unticked: a leftover .gam beside the real game, lacking files, that no player loads. */
+    leftover?: string;
+}
+export interface ScanReport {
+    games: FoundGame[];
+    /** Zips looked in (inside others too). */
+    zips: number;
+    /** Zips with no .gam file in them, and what they did hold ("only text files"). */
+    emptyZips: {
+        path: string;
+        held: string;
+    }[];
+    /** Zips that could not be read, and why. */
+    badZips: {
+        path: string;
+        error: string;
+    }[];
+    /** Files in no game, zips aside (none of them is imported, unless no game was found at all). */
+    loose: ScanFile[];
+    /** Files whose contents aren't what their extension says (a renamed text file named .FLI). */
+    misnamed?: {
+        path: string;
+        says: string;
+    }[];
+}
+/** A game's own player is an .EXE of XFERPLAY 3.00's size; the import reads those and leaves out the rest. */
+export declare const PLAYER_EXE: (name: string, size: number) => boolean;
+interface Group {
+    dir: string;
+    files: ScanFile[];
+}
+/**
+ * The games among these files (by their folders) and the files in none. Zips are left out.
+ * `played`: game files a player .EXE names with an extension of its own (playedBy).
+ */
+export declare function groupGames(files: ScanFile[], played?: ReadonlySet<ScanFile>): {
+    games: Group[];
+    loose: ScanFile[];
+};
+/**
+ * Each player .EXE here and the game file beside it that it plays: the one named after it, with
+ * the .gam extension it asks for (Acord Games' players ask for .z0g; Virtual Mario's for none).
+ * `games`: the files with an extension a player beside them asks for in place of .gam (a
+ * leftover SPACE.Z0G beside ZAPAK.EXE too).
+ */
+export declare function playedBy(files: ScanFile[]): Promise<{
+    players: Map<ScanFile, ScanFile>;
+    games: Set<ScanFile>;
+    crcs: Map<ScanFile, number>;
+}>;
+export interface ScanOptions {
+    signal?: AbortSignal;
+    /** Optional bounds for every archive opened, including nested archives. */
+    zipLimits?: ZipLimits;
+    /** Told before each zip given (not those inside them) is read, and once at the end. */
+    onProgress?: (done: number, total: number, path?: string) => void;
+    /** Told which step a zip is at: 'unpack' while it is read, 'find' while its games are looked for. */
+    onStep?: (step: 'unpack' | 'find', path: string) => void;
+}
+/** Looks through what was given for its games. Throws an AbortError when canceled. */
+export declare function scanImport(given: ScanFile[], { signal, onProgress, onStep, zipLimits }?: ScanOptions): Promise<ScanReport>;
+/** "212 games found, 3 zips had no game" */
+export declare function scanSummary(r: Pick<ScanReport, 'games' | 'emptyZips' | 'badZips' | 'zips'> & {
+    misnamed?: ScanReport['misnamed'];
+}): string;
+/** A found game's files, ready to import. */
+export interface ReadGame {
+    files: GameFiles;
+    /** Its player .EXEs (left out of the files): a hand-edited one becomes DOS player patches. */
+    players: {
+        name: string;
+        bytes: Uint8Array;
+    }[];
+    /** Its title and the .gam it plays, when its folder holds others (FoundGame.gam); else the project names them. */
+    name?: string;
+    gam?: string;
+}
+/** Told before each file is read (the number done, the total, its path); it may return a promise to wait for. */
+export type FileProgress = (done: number, total: number, path: string) => void | Promise<void>;
+/** Fills a game's files from these, as an import of the game's own files always has. */
+export declare function gameFromFiles(list: ScanFile[], onFile?: FileProgress): Promise<ReadGame>;
+/**
+ * Reads found games' files again, from the files given. The zip read last is kept (read the
+ * games in the order found, and a zip with several is read once); none before it is.
+ */
+export declare class GameReader {
+    private readonly zipLimits?;
+    private loose;
+    private last?;
+    constructor(given: ScanFile[], zipLimits?: ZipLimits | undefined);
+    /** One of a found game's files by its DOS name (its title screen's), without reading the rest. */
+    file(game: FoundGame, name: string): Promise<Uint8Array | undefined>;
+    /** The .gam a found game plays: its own when its folder holds others, else the first. */
+    mainGam(game: FoundGame): string | undefined;
+    read(game: FoundGame, onFile?: FileProgress): Promise<ReadGame>;
+    private zipEntries;
+}
+/** A picked or dropped file as one to look at (`path` is where it was under the folder given). */
+export declare function scanFile(file: File, path?: string): ScanFile;
+export {};

package/dist/types/project/zip.d.ts

@@ -0,0 +1,32 @@
+export interface ZipEntry {
+    name: string;
+    data: Uint8Array;
+    /** Unix file mode (e.g. 0o100755 for a program); stored so unzipping keeps it executable. */
+    mode?: number;
+    /** Kept uncompressed (stored), as an ePub's first file, `mimetype`, must be. */
+    store?: boolean;
+}
+export declare function crc32(data: Uint8Array): number;
+export declare function createZip(entries: ZipEntry[], date?: Date): Promise<Uint8Array>;
+/** Limits for a zip from somewhere untrusted (linkIn/): more entries or bytes than these throw. */
+export interface ZipLimits {
+    maxEntries: number;
+    /** Unpacked bytes in all, as the directory says and as actually inflated. */
+    maxBytes: number;
+}
+/** An entry of a zip's directory, read only when asked (listZip). */
+export interface ZipListing {
+    name: string;
+    /** Unpacked bytes, as the directory says. */
+    size: number;
+    /** Inflates it (stored and deflated entries; others give undefined). */
+    read: () => Promise<Uint8Array | undefined>;
+}
+/**
+ * A zip's files from its central directory, without inflating any (a self-extracting .EXE's
+ * too, which is never run): an import looks for the
+ * .gam files first and reads the rest only for the games picked (project/importScan.ts).
+ */
+export declare function listZip(bytes: Uint8Array, limits?: ZipLimits): ZipListing[];
+export declare function readZip(bytes: Uint8Array, limits?: ZipLimits): Promise<ZipEntry[]>;
+export declare function isZip(bytes: Uint8Array): boolean;