akanjs 3.0.1 → 3.0.2-rc.0

package/vendor/@akanjs/native/packages/cli/src/lib/bplist.ts

@@ -0,0 +1,91 @@
+
+
+/** A number written as a real even when it is whole: Finder reads `iconSize` and `textSize` as reals. */
+export class Real {
+  constructor(readonly value: number) {}
+}
+
+export type BplistValue = string | number | boolean | Uint8Array | Real | { [key: string]: BplistValue };
+
+class DictNode {
+  readonly keys: number[] = [];
+  readonly values: number[] = [];
+}
+type Node = Exclude<BplistValue, { [key: string]: BplistValue }> | DictNode;
+
+const sizeOf = (max: number) => (max < 2 ** 8 ? 1 : max < 2 ** 16 ? 2 : 4);
+
+function uint(value: number, size: number): number[] {
+  const out: number[] = [];
+  for (let i = size - 1; i >= 0; i--) out.push(Math.floor(value / 2 ** (8 * i)) & 0xff);
+  return out;
+}
+
+function float64(value: number): number[] {
+  const data = new Uint8Array(8);
+  new DataView(data.buffer).setFloat64(0, value);
+  return [0x23, ...data];
+}
+
+function lengthMarker(kind: number, length: number): number[] {
+  if (length < 15) return [kind | length];
+  const size = length < 2 ** 8 ? 0 : length < 2 ** 16 ? 1 : 2;
+  return [kind | 0x0f, 0x10 | size, ...uint(length, 2 ** size)];
+}
+
+function encode(node: Node, refSize: number): number[] {
+  if (typeof node === "boolean") return [node ? 0x09 : 0x08];
+  if (node instanceof Real) return float64(node.value);
+  if (typeof node === "number") {
+    if (!Number.isInteger(node)) return float64(node);
+    if (node < 0) {
+      const data = new Uint8Array(8);
+      new DataView(data.buffer).setBigInt64(0, BigInt(node));
+      return [0x13, ...data];
+    }
+    const size = node < 2 ** 8 ? 0 : node < 2 ** 16 ? 1 : node < 2 ** 32 ? 2 : 3;
+    return [0x10 | size, ...uint(node, 2 ** size)];
+  }
+  if (typeof node === "string") {
+    if ([...node].every((c) => c.charCodeAt(0) < 0x80))
+      return [...lengthMarker(0x50, node.length), ...[...node].map((c) => c.charCodeAt(0))];
+    const out = lengthMarker(0x60, node.length);
+    for (let i = 0; i < node.length; i++) out.push(...uint(node.charCodeAt(i), 2));
+    return out;
+  }
+  if (node instanceof Uint8Array) return [...lengthMarker(0x40, node.length), ...node];
+  return [
+    ...lengthMarker(0xd0, node.keys.length),
+    ...[...node.keys, ...node.values].flatMap((ref) => uint(ref, refSize)),
+  ];
+}
+
+export function writeBplist(root: { [key: string]: BplistValue }): Uint8Array {
+  const nodes: Node[] = [];
+  const add = (value: BplistValue): number => {
+    const idx = nodes.length;
+    if (typeof value !== "object" || value instanceof Uint8Array || value instanceof Real) {
+      nodes.push(value);
+      return idx;
+    }
+    const dict = new DictNode();
+    nodes.push(dict);
+    const entries = Object.entries(value);
+    for (const [key] of entries) dict.keys.push(add(key));
+    for (const [, item] of entries) dict.values.push(add(item));
+    return idx;
+  };
+  add(root);
+  const refSize = sizeOf(nodes.length);
+  const bytes: number[] = [..."bplist00"].map((c) => c.charCodeAt(0));
+  const offsets: number[] = [];
+  for (const node of nodes) {
+    offsets.push(bytes.length);
+    bytes.push(...encode(node, refSize));
+  }
+  const tableOffset = bytes.length;
+  const offsetSize = sizeOf(tableOffset);
+  for (const offset of offsets) bytes.push(...uint(offset, offsetSize));
+  bytes.push(0, 0, 0, 0, 0, 0, offsetSize, refSize, ...uint(nodes.length, 8), ...uint(0, 8), ...uint(tableOffset, 8));
+  return Uint8Array.from(bytes);
+}

package/vendor/@akanjs/native/packages/cli/src/lib/configkeys.ts

@@ -37,6 +37,15 @@ const KNOWN: Shape = {
     screenCapture: true,
     server: { dir: true, entry: true, env: true },
     bin: true,
+    dmg: {
+      background: true,
+      background2x: true,
+      window: { x: true, y: true, width: true, height: true },
+      iconSize: true,
+      textSize: true,
+      app: { x: true, y: true },
+      applications: { x: true, y: true },
+    },
   },
   keyboard: { resize: true },
   push: {

package/vendor/@akanjs/native/packages/cli/src/lib/dmg.ts

@@ -0,0 +1,331 @@
+
+
+import {
+  closeSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+import type { DmgConfig } from "../config.ts";
+import { Real, writeBplist } from "./bplist.ts";
+import { type DsStoreRecord, writeDsStore } from "./dsStore.ts";
+import { exec, execOrThrow } from "./exec.ts";
+import { aliasRecord } from "./macAlias.ts";
+import { PACKAGE_ROOT } from "./root.ts";
+
+interface Point {
+  x: number;
+  y: number;
+}
+
+export interface ResolvedDmg {
+  /** Absolute; null for a plain window. */
+  background: { image: string; image2x?: string } | null;
+  /** The window's size defaults to the background's. */
+  window: { x: number; y: number; width?: number; height?: number };
+  iconSize: number;
+  textSize: number;
+  app: Point;
+  applications: Point;
+}
+
+const DEFAULT_BACKGROUND = {
+  image: join(PACKAGE_ROOT, "native", "macos", "dmg", "background.png"),
+  image2x: join(PACKAGE_ROOT, "native", "macos", "dmg", "background@2x.png"),
+};
+const DEFAULT_SIZE = { width: 660, height: 400 };
+
+const TITLE_BAR = 28;
+export const DMG_DEFAULTS = {
+  window: { x: 200, y: 120 },
+  iconSize: 128,
+  textSize: 13,
+  app: { x: 180, y: 170 },
+  applications: { x: 480, y: 170 },
+} as const;
+
+const isNumber = (value: unknown, min = 0): value is number =>
+  typeof value === "number" && Number.isFinite(value) && value >= min;
+
+export function validateDmg(dmg: DmgConfig | undefined, appDir: string, problems: string[]): ResolvedDmg {
+  const raw: DmgConfig = dmg && typeof dmg === "object" ? dmg : {};
+  if (dmg !== undefined && (!dmg || typeof dmg !== "object")) problems.push("desktop.dmg must be an object");
+  const file = (key: "background" | "background2x", value: unknown): string | undefined => {
+    if (value === undefined) return undefined;
+    const path = typeof value === "string" && value ? resolve(appDir, value) : null;
+    if (!path || !existsSync(path) || !statSync(path).isFile()) {
+      problems.push(`desktop.dmg.${key} must be an image file (got ${JSON.stringify(value)})`);
+      return undefined;
+    }
+    return path;
+  };
+  if (raw.background !== undefined && raw.background !== false && typeof raw.background !== "string")
+    problems.push(`desktop.dmg.background must be an image file or false (got ${JSON.stringify(raw.background)})`);
+  const image = raw.background === false ? undefined : file("background", raw.background);
+  const image2x = file("background2x", raw.background2x);
+  if (raw.background2x !== undefined && typeof raw.background !== "string")
+    problems.push("desktop.dmg.background2x needs desktop.dmg.background, the same picture at its size in points");
+  const window = { ...DMG_DEFAULTS.window, ...(raw.window && typeof raw.window === "object" ? raw.window : {}) };
+  for (const [key, value] of Object.entries(window))
+    if (!isNumber(value, key === "width" || key === "height" ? 1 : 0))
+      problems.push(`desktop.dmg.window.${key} must be a positive number of points (got ${JSON.stringify(value)})`);
+  for (const key of ["iconSize", "textSize"] as const)
+    if (raw[key] !== undefined && !isNumber(raw[key], 1))
+      problems.push(`desktop.dmg.${key} must be a positive number of points (got ${JSON.stringify(raw[key])})`);
+  const point = (key: "app" | "applications"): Point => {
+    const value = raw[key];
+    if (value === undefined) return DMG_DEFAULTS[key];
+    if (!value || typeof value !== "object" || !isNumber(value.x) || !isNumber(value.y)) {
+      problems.push(`desktop.dmg.${key} must be { x, y }, the icon's center in points (got ${JSON.stringify(value)})`);
+      return DMG_DEFAULTS[key];
+    }
+    return { x: value.x, y: value.y };
+  };
+  return {
+    background:
+      raw.background === false
+        ? null
+        : raw.background === undefined
+          ? DEFAULT_BACKGROUND
+          : image
+            ? { image, ...(image2x ? { image2x } : {}) }
+            : null,
+    window,
+    iconSize: raw.iconSize ?? DMG_DEFAULTS.iconSize,
+    textSize: raw.textSize ?? DMG_DEFAULTS.textSize,
+    app: point("app"),
+    applications: point("applications"),
+  };
+}
+
+/** A PNG's size from its header, anything else's from sips. */
+async function imageSize(path: string): Promise<{ width: number; height: number }> {
+  const head = readFileSync(path).subarray(0, 24);
+  if (head.length === 24 && head.readUInt32BE(0) === 0x89504e47)
+    return { width: head.readUInt32BE(16), height: head.readUInt32BE(20) };
+  const { stdout } = await execOrThrow(["sips", "-g", "pixelWidth", "-g", "pixelHeight", path], { echo: false });
+  const width = Number(/pixelWidth: (\d+)/.exec(stdout)?.[1]);
+  const height = Number(/pixelHeight: (\d+)/.exec(stdout)?.[1]);
+  if (!width || !height) throw new Error(`cannot read the size of ${path}`);
+  return { width, height };
+}
+
+/** The picture the image carries: a 1x and 2x pair as one multi-resolution TIFF, which Finder picks from per display. */
+async function stageBackground(background: NonNullable<ResolvedDmg["background"]>, dir: string): Promise<string> {
+  mkdirSync(dir, { recursive: true });
+  if (background.image2x) {
+    const out = join(dir, "background.tiff");
+    await execOrThrow(["tiffutil", "-cathidpicheck", background.image, background.image2x, "-out", out], {
+      echo: false,
+    });
+    return out;
+  }
+  const out = join(dir, `background${extname(background.image).toLowerCase() || ".png"}`);
+  copyFileSync(background.image, out);
+  return out;
+}
+
+export function dmgRecords(
+  layout: ResolvedDmg,
+  {
+    appName,
+    size,
+    backgroundAlias,
+  }: { appName: string; size: { width: number; height: number }; backgroundAlias?: Uint8Array },
+): DsStoreRecord[] {
+  const { x, y } = layout.window;
+  const blob = (value: Uint8Array) => ({ type: "blob" as const, value });
+  const iconAt = ({ x, y }: Point) => {
+    const value = new Uint8Array(16);
+    const view = new DataView(value.buffer);
+    view.setUint32(0, Math.round(x));
+    view.setUint32(4, Math.round(y));
+    view.setUint32(8, 0xffffffff);
+    view.setUint32(12, 0xffff0000);
+    return blob(value);
+  };
+  const bwsp = writeBplist({
+    WindowBounds: `{{${x}, ${y}}, {${size.width}, ${size.height + TITLE_BAR}}}`,
+    ShowToolbar: false,
+    ShowSidebar: false,
+    ShowStatusBar: false,
+    ShowPathbar: false,
+    ShowTabView: false,
+    ContainerShowSidebar: false,
+    PreviewPaneVisibility: false,
+    SidebarWidth: 0,
+  });
+  const icvp = writeBplist({
+    viewOptionsVersion: 1,
+    backgroundType: backgroundAlias ? 2 : 0,
+    ...(backgroundAlias ? { backgroundImageAlias: backgroundAlias } : {}),
+    backgroundColorRed: new Real(1),
+    backgroundColorGreen: new Real(1),
+    backgroundColorBlue: new Real(1),
+    gridOffsetX: new Real(0),
+    gridOffsetY: new Real(0),
+    gridSpacing: new Real(100),
+    arrangeBy: "none",
+    showIconPreview: true,
+    showItemInfo: false,
+    labelOnBottom: true,
+    textSize: new Real(layout.textSize),
+    iconSize: new Real(layout.iconSize),
+    scrollPositionX: new Real(0),
+    scrollPositionY: new Real(0),
+  });
+  return [
+    { name: ".", code: "bwsp", value: blob(bwsp) },
+    { name: ".", code: "icvp", value: blob(icvp) },
+    { name: ".", code: "icvl", value: { type: "type", value: "icnv" } },
+    { name: ".", code: "vSrn", value: { type: "long", value: 1 } },
+    { name: appName, code: "Iloc", value: iconAt(layout.app) },
+    { name: "Applications", code: "Iloc", value: iconAt(layout.applications) },
+  ];
+}
+
+const CUSTOM_ICON_FINDER_INFO = `${"0".repeat(16)}0400${"0".repeat(44)}`;
+
+async function detach(mountPoint: string): Promise<void> {
+  for (let attempt = 0; ; attempt++) {
+    const result = await exec(["hdiutil", "detach", mountPoint, ...(attempt >= 3 ? ["-force"] : [])], { echo: false });
+    if (result.code === 0) return;
+    
+    if (attempt >= 5)
+      throw new Error(`hdiutil detach ${mountPoint} failed: ${(result.stderr || result.stdout).trim()}`);
+    await Bun.sleep(1000 * (attempt + 1));
+  }
+}
+
+export async function buildDmg(
+  appPath: string,
+  dmgPath: string,
+  volumeName: string,
+  workDir: string,
+  { layout, volumeIcon }: { layout: ResolvedDmg; volumeIcon?: string },
+): Promise<void> {
+  const staging = join(workDir, "dmg");
+  const writable = join(workDir, "dmg-rw.dmg");
+  const mountPoint = join(workDir, "dmg-mount");
+  rmSync(staging, { recursive: true, force: true });
+  rmSync(writable, { force: true });
+  mkdirSync(staging, { recursive: true });
+  const appName = basename(appPath);
+  await execOrThrow(["ditto", appPath, join(staging, appName)], { echo: false });
+  symlinkSync("/Applications", join(staging, "Applications"));
+  
+  mkdirSync(join(staging, ".fseventsd"));
+  writeFileSync(join(staging, ".fseventsd", "no_log"), "");
+  const background = layout.background ? await stageBackground(layout.background, join(staging, ".background")) : null;
+  if (volumeIcon && existsSync(volumeIcon)) copyFileSync(volumeIcon, join(staging, ".VolumeIcon.icns"));
+  const size = {
+    ...(layout.background ? await imageSize(layout.background.image) : DEFAULT_SIZE),
+    ...(layout.window.width ? { width: layout.window.width } : {}),
+    ...(layout.window.height ? { height: layout.window.height } : {}),
+  };
+
+  const { stdout } = await execOrThrow(["du", "-sk", staging], { echo: false });
+  const kilobytes = Number(stdout.trim().split(/\s+/)[0]) || 0;
+  await execOrThrow(
+    [
+      "hdiutil",
+      "create",
+      "-volname",
+      volumeName,
+      "-srcfolder",
+      staging,
+      "-fs",
+      "HFS+",
+      "-format",
+      "UDRW",
+      "-size",
+      `${Math.ceil(kilobytes * 1.1) + 10 * 1024}k`,
+      "-ov",
+      writable,
+    ],
+    { echo: false },
+  );
+  const volumeCreated = volumeHeaderCreateDate(writable);
+  rmSync(mountPoint, { recursive: true, force: true });
+  mkdirSync(mountPoint, { recursive: true });
+  await execOrThrow(
+    ["hdiutil", "attach", writable, "-readwrite", "-noverify", "-noautoopen", "-nobrowse", "-mountpoint", mountPoint],
+    { echo: false },
+  );
+  try {
+    const backgroundAlias = background
+      ? aliasFor(mountPoint, { volumeName, volumeCreated }, join(".background", basename(background)))
+      : undefined;
+    const records = dmgRecords(layout, { appName, size, ...(backgroundAlias ? { backgroundAlias } : {}) });
+    writeFileSync(join(mountPoint, ".DS_Store"), writeDsStore(records));
+    const hidden = [".background", ".VolumeIcon.icns", ".DS_Store", ".fseventsd"].map((name) => join(mountPoint, name));
+    await execOrThrow(["chflags", "hidden", ...hidden.filter((path) => existsSync(path))], { echo: false });
+    if (existsSync(join(mountPoint, ".VolumeIcon.icns")))
+      await execOrThrow(["xattr", "-wx", "com.apple.FinderInfo", CUSTOM_ICON_FINDER_INFO, mountPoint], { echo: false });
+    rmSync(join(mountPoint, ".Trashes"), { recursive: true, force: true });
+  } finally {
+    await detach(mountPoint);
+  }
+  rmSync(dmgPath, { force: true });
+  await execOrThrow(
+    ["hdiutil", "convert", writable, "-format", "UDZO", "-imagekey", "zlib-level=9", "-ov", "-o", dmgPath],
+    { echo: false },
+  );
+  rmSync(writable, { force: true });
+  rmSync(staging, { recursive: true, force: true });
+  rmSync(mountPoint, { recursive: true, force: true });
+}
+
+/**
+ * The createDate of the HFS+ volume a read-write image holds: its header ("H+", version 4) sits 1024 bytes into the
+ * partition, which `hdiutil create` puts within the image's first mebibyte, its data stored as is.
+ */
+export function volumeHeaderCreateDate(image: string): number {
+  const head = new Uint8Array(1024 * 1024);
+  const fd = openSync(image, "r");
+  const length = (() => {
+    try {
+      return readSync(fd, head, 0, head.length, 0);
+    } finally {
+      closeSync(fd);
+    }
+  })();
+  for (let offset = 1024; offset + 512 <= length; offset += 512)
+    if (head[offset] === 0x48 && head[offset + 1] === 0x2b && head[offset + 2] === 0 && head[offset + 3] === 4)
+      return new DataView(head.buffer, offset).getUint32(16);
+  throw new Error(`no HFS+ volume header in the first MiB of ${image}`);
+}
+
+/** The background's alias as the mounted image names it, while it is mounted where it is being written. */
+function aliasFor(
+  mountPoint: string,
+  { volumeName, volumeCreated }: { volumeName: string; volumeCreated: number },
+  relative: string,
+): Uint8Array {
+  const target = join(mountPoint, relative);
+  const parent = join(target, "..");
+  const file = lstatSync(target);
+  const folder = lstatSync(parent);
+  return aliasRecord({
+    volumeName,
+    volumeCreated,
+    volumePath: join("/Volumes", volumeName),
+    kind: "file",
+    name: basename(target),
+    cnid: file.ino,
+    created: file.birthtime,
+    parentName: basename(parent),
+    parentCnid: folder.ino,
+    cnidPath: [folder.ino],
+    posixPath: `/${relative}`,
+  });
+}

package/vendor/@akanjs/native/packages/cli/src/lib/dsStore.ts

@@ -0,0 +1,191 @@
+
+
+export type DsStoreValue =
+  | { type: "long"; value: number }
+  | { type: "bool"; value: boolean }
+  | { type: "type"; value: string }
+  | { type: "blob"; value: Uint8Array }
+  | { type: "ustr"; value: string };
+
+export interface DsStoreRecord {
+  /** The file the record is about, "." for the folder itself. */
+  name: string;
+  /** Four letters: Iloc (icon location), bwsp (window), icvp (icon view), vSrn, icvl … */
+  code: string;
+  value: DsStoreValue;
+}
+
+const PAGE_SIZE = 4096;
+
+class Writer {
+  #chunks: Uint8Array[] = [];
+  length = 0;
+  bytes(data: Uint8Array): this {
+    this.#chunks.push(data);
+    this.length += data.length;
+    return this;
+  }
+  u8(value: number): this {
+    return this.bytes(Uint8Array.of(value));
+  }
+  u32(value: number): this {
+    const data = new Uint8Array(4);
+    new DataView(data.buffer).setUint32(0, value >>> 0);
+    return this.bytes(data);
+  }
+  fourCC(code: string): this {
+    if (!/^[\x20-\x7e]{4}$/.test(code)) throw new Error(`not a four-letter code: ${JSON.stringify(code)}`);
+    return this.bytes(new TextEncoder().encode(code));
+  }
+  utf16(text: string): this {
+    const data = new Uint8Array(text.length * 2);
+    const view = new DataView(data.buffer);
+    for (let i = 0; i < text.length; i++) view.setUint16(i * 2, text.charCodeAt(i));
+    return this.bytes(data);
+  }
+  toBytes(): Uint8Array {
+    const out = new Uint8Array(this.length);
+    let at = 0;
+    for (const chunk of this.#chunks) {
+      out.set(chunk, at);
+      at += chunk.length;
+    }
+    return out;
+  }
+}
+
+/** Finder compares names as HFS+ does, case-insensitively; a window's few ASCII names need nothing more. */
+function compareRecords(a: DsStoreRecord, b: DsStoreRecord): number {
+  const left = a.name.toLowerCase();
+  const right = b.name.toLowerCase();
+  if (left !== right) return left < right ? -1 : 1;
+  return a.code < b.code ? -1 : a.code > b.code ? 1 : 0;
+}
+
+function writeRecord(out: Writer, { name, code, value }: DsStoreRecord): void {
+  out.u32(name.length).utf16(name).fourCC(code).fourCC(value.type);
+  if (value.type === "long") out.u32(value.value);
+  else if (value.type === "bool") out.u8(value.value ? 1 : 0);
+  else if (value.type === "type") out.fourCC(value.value);
+  else if (value.type === "blob") out.u32(value.value.length).bytes(value.value);
+  else out.u32(value.value.length).utf16(value.value);
+}
+
+/** The buddy allocator's free lists after the given allocations, each address a power-of-two block. */
+class Buddy {
+  readonly free: number[][] = Array.from({ length: 32 }, () => []);
+  constructor() {
+    this.free[31]?.push(0);
+  }
+  allocate(size: number): { offset: number; width: number } {
+    const width = Math.max(5, Math.ceil(Math.log2(size)));
+    let w = width;
+    while (w < 32 && !this.free[w]?.length) w++;
+    const offset = this.free[w]?.shift();
+    if (offset === undefined) throw new Error(`no free block of ${size} bytes`);
+    while (w > width) {
+      w--;
+      this.free[w]?.push(offset + 2 ** w);
+      this.free[w]?.sort((a, b) => a - b);
+    }
+    return { offset, width };
+  }
+}
+
+export function writeDsStore(records: DsStoreRecord[]): Uint8Array {
+  const sorted = [...records].sort(compareRecords);
+  const leaf = new Writer().u32(0).u32(sorted.length);
+  for (const record of sorted) writeRecord(leaf, record);
+  if (leaf.length > PAGE_SIZE)
+    throw new Error(
+      `${sorted.length} .DS_Store records need ${leaf.length} bytes, more than one ${PAGE_SIZE}-byte node`,
+    );
+
+  const buddy = new Buddy();
+  buddy.allocate(32); 
+  const root = buddy.allocate(2048);
+  const header = buddy.allocate(32);
+  const node = buddy.allocate(PAGE_SIZE);
+  const address = ({ offset, width }: { offset: number; width: number }) => offset | width;
+
+  const dsdb = new Writer().u32(2).u32(0).u32(sorted.length).u32(1).u32(PAGE_SIZE);
+  const blocks = [root, header, node];
+  const allocator = new Writer().u32(blocks.length).u32(0);
+  for (const block of blocks) allocator.u32(address(block));
+  for (let i = blocks.length; i < 256; i++) allocator.u32(0);
+  allocator.u32(1).u8(4).fourCC("DSDB").u32(1);
+  for (const list of buddy.free) {
+    allocator.u32(list.length);
+    for (const offset of list) allocator.u32(offset);
+  }
+  if (allocator.length > 2 ** root.width) throw new Error(".DS_Store allocator block overflows");
+
+  const end = Math.max(...blocks.map(({ offset, width }) => offset + 2 ** width));
+  const file = new Uint8Array(4 + end);
+  const view = new DataView(file.buffer);
+  view.setUint32(0, 1);
+  file.set(new TextEncoder().encode("Bud1"), 4);
+  view.setUint32(8, root.offset);
+  view.setUint32(12, 2 ** root.width);
+  view.setUint32(16, root.offset);
+  file.set(allocator.toBytes(), 4 + root.offset);
+  file.set(dsdb.toBytes(), 4 + header.offset);
+  file.set(leaf.toBytes(), 4 + node.offset);
+  return file;
+}
+
+/** Reads back what writeDsStore wrote (one leaf): the tests' check, and a way to look at a .DS_Store. */
+export function readDsStore(file: Uint8Array): DsStoreRecord[] {
+  const view = new DataView(file.buffer, file.byteOffset, file.byteLength);
+  if (view.getUint32(0) !== 1 || new TextDecoder().decode(file.subarray(4, 8)) !== "Bud1")
+    throw new Error("not a .DS_Store");
+  const rootOffset = view.getUint32(8);
+  const blockAt = (index: number) => {
+    const raw = view.getUint32(4 + rootOffset + 8 + index * 4);
+    return 4 + (raw & ~0x1f);
+  };
+  const dsdb = blockAt(1);
+  const leafIndex = view.getUint32(dsdb);
+  let at = blockAt(leafIndex);
+  if (view.getUint32(at) !== 0) throw new Error("only a single-leaf .DS_Store is read");
+  const count = view.getUint32(at + 4);
+  at += 8;
+  const fourCC = () => {
+    const code = new TextDecoder().decode(file.subarray(at, at + 4));
+    at += 4;
+    return code;
+  };
+  const utf16 = (units: number) => {
+    let text = "";
+    for (let i = 0; i < units; i++) text += String.fromCharCode(view.getUint16(at + i * 2));
+    at += units * 2;
+    return text;
+  };
+  const records: DsStoreRecord[] = [];
+  for (let i = 0; i < count; i++) {
+    const nameLength = view.getUint32(at);
+    at += 4;
+    const name = utf16(nameLength);
+    const code = fourCC();
+    const type = fourCC();
+    let value: DsStoreValue;
+    if (type === "long") {
+      value = { type, value: view.getUint32(at) };
+      at += 4;
+    } else if (type === "bool") {
+      value = { type, value: file[at] === 1 };
+      at += 1;
+    } else if (type === "type") value = { type, value: fourCC() };
+    else if (type === "blob") {
+      const length = view.getUint32(at);
+      value = { type, value: file.slice(at + 4, at + 4 + length) };
+      at += 4 + length;
+    } else if (type === "ustr") {
+      const length = view.getUint32(at);
+      at += 4;
+      value = { type, value: utf16(length) };
+    } else throw new Error(`unsupported .DS_Store type ${type}`);
+    records.push({ name, code, value });
+  }
+  return records;
+}