geometryview 0.1.1 → 0.3.0

package/web/gallery-core.js

@@ -0,0 +1,359 @@
+// The gallery's layout core (Engine/include/gallery.h), in the engine's module: the folder tree, the
+// folder in view, and its display list, the same the Mac paints. Engine/browser/web_gallery.cpp
+// carries it across; this reads the items from the module's memory.
+
+export const Kinds = Object.freeze({ Rect: 0, Text: 1, Picture: 2, Line: 3 });
+export const Flags = Object.freeze({ Dashed: 1, Hatched: 2, Sticker: 4, Fading: 8, Fixed: 16, Sheet: 32, Stale: 64, Lost: 128,
+                                     Ruler: 256, Turn: 512, Detail: 1024 });
+export const Targets = Object.freeze({ None: 0, Folder: 1, File: 2, More: 3, Peek: 4, Reconnect: 5, Page: 6 });
+export const Actions = Object.freeze({ None: 0, Handled: 1, EnterFolder: 2, OpenFile: 3, Peek: 4, Leave: 5,
+                                       Reconnect: 6, Turn: 7 });
+export const Keys = Object.freeze({ Left: 0, Right: 1, Up: 2, Down: 3, Enter: 4, Space: 5, Escape: 6, FolderUp: 7 });
+export const Views = Object.freeze({ Plates: 0, Sheet: 1, Ladders: 2, Atlas: 3, Catalogue: 4 });
+export const ViewNames = Object.freeze(["Plates", "Sheet", "Ladders", "Atlas", "Catalogue"]);
+export const Scales = Object.freeze({ Fit: 0, Folder: 1, True: 2 });
+export const Sorts = Object.freeze({ Name: 0, Size: 1 });
+export const Transitions = Object.freeze({ None: 0, Switch: 1, Into: 2, Out: 3 });
+export const TrackKinds = Object.freeze({ Fly: 0, FadeIn: 1 });
+
+const kItemSize = 116; // GeoGalleryItem: 29 four-byte fields
+const kNone = 0xffffffff;
+
+/** A colour from the core: straight sRGB, red in the low byte, as CSS. */
+export function cssColour(rgba) {
+  if (!rgba) return "transparent";
+  const r = rgba & 0xff, g = (rgba >>> 8) & 0xff, b = (rgba >>> 16) & 0xff, a = (rgba >>> 24) / 255;
+  return a >= 1 ? `rgb(${r} ${g} ${b})` : `rgb(${r} ${g} ${b} / ${Math.round(a * 1000) / 1000})`;
+}
+
+export class GalleryCore {
+  #m;
+  #g;
+  #scratch;
+  #items = null;
+  #text = "";
+  #textBytes = null;
+
+  constructor(module) {
+    this.#m = module;
+    if (module._gv_gallery_item_size() !== kItemSize) throw new Error("The gallery's items are not the size the page reads.");
+    this.#g = module._gv_gallery_create();
+    this.#scratch = module._malloc(256);
+  }
+
+  destroy() {
+    this.#m._gv_gallery_destroy(this.#g);
+    this.#m._free(this.#scratch);
+  }
+
+  #string(text, use) {
+    const m = this.#m;
+    const size = m.lengthBytesUTF8(text) + 1;
+    const pointer = m._malloc(size);
+    m.stringToUTF8(text, pointer, size);
+    try {
+      return use(pointer);
+    } finally {
+      m._free(pointer);
+    }
+  }
+
+  /** Replaces the tree with a walk's entries: [{ path, folder, bytes, modified }]. */
+  setEntries(title, entries) {
+    const m = this.#m;
+    const n = entries.length;
+    const paths = entries.map((e) => e.path).join("\n");
+    const folders = m._malloc(Math.max(1, n));
+    const bytes = m._malloc(Math.max(8, n * 8));
+    const modified = m._malloc(Math.max(8, n * 8));
+    // Each call may grow the heap, which detaches views made before it: views after.
+    this.#string(paths, (p) => this.#string(title, (t) => {
+      m.HEAPU8.set(entries.map((e) => (e.folder ? 1 : 0)), folders);
+      new Float64Array(m.HEAPU8.buffer, bytes, n).set(entries.map((e) => e.bytes ?? 0));
+      new Float64Array(m.HEAPU8.buffer, modified, n).set(entries.map((e) => e.modified ?? 0));
+      m._gv_gallery_set_entries(this.#g, t, p, folders, bytes, modified, n);
+    }));
+    m._free(folders);
+    m._free(bytes);
+    m._free(modified);
+    this.#items = null;
+  }
+
+  get fileCount() { return this.#m._gv_gallery_file_count(this.#g); }
+  path(file) { return this.#m.UTF8ToString(this.#m._gv_gallery_file_path(this.#g, file)); }
+  fileAt(path) {
+    const file = this.#string(path, (p) => this.#m._gv_gallery_file_at(this.#g, p)) >>> 0;
+    return file === 0xffffffff ? null : file;
+  }
+
+  /** Facts as the library measured them: { size: [x, y, z], hasBox, estimated, parts, product, triangles }. */
+  setFacts(file, f) {
+    this.#string(f.product ?? "", (p) =>
+      this.#m._gv_gallery_set_facts(this.#g, file, f.size[0], f.size[1], f.size[2], f.hasBox ? 1 : 0,
+                                    f.estimated ? 1 : 0, f.parts ?? 0, p, f.triangles ?? 0));
+  }
+
+  /** A picture's note: { width, height, mmPerPixel, part: [x, y, w, h], ink: [x, y, w, h] }. */
+  setPicture(file, p) {
+    const m = this.#m;
+    const floats = new Float32Array(m.HEAPU8.buffer, this.#scratch, 8);
+    floats.set([...p.part, ...p.ink]);
+    m._gv_gallery_set_picture(this.#g, file, p.width, p.height, p.mmPerPixel, this.#scratch, this.#scratch + 16);
+  }
+
+  setFailure(file, message) {
+    this.#string(message || "This file could not be read.", (p) => this.#m._gv_gallery_set_failure(this.#g, file, p));
+  }
+
+  /** The view as a poster, printed with `date` in its foot. */
+  setPoster(poster, date = "") {
+    this.#string(date, (d) => this.#m._gv_gallery_set_poster(this.#g, poster ? 1 : 0, d));
+  }
+  get poster() { return this.#m._gv_gallery_poster(this.#g) !== 0; }
+
+  /** The last layout's lanes, which scroll sideways: [{ id, rect: [x, y, w, h], contentWidth }]. */
+  get lanes() {
+    const m = this.#m;
+    const n = m._gv_gallery_lanes(this.#g, 0, 0);
+    if (n === 0) return [];
+    const out = m._malloc(n * 24);
+    m._gv_gallery_lanes(this.#g, out, n);
+    const v = new Float32Array(m.HEAPU8.buffer, out, n * 6).slice();
+    m._free(out);
+    const lanes = [];
+    for (let i = 0; i < n; i++) {
+      lanes.push({ id: v[i * 6], rect: [v[i * 6 + 1], v[i * 6 + 2], v[i * 6 + 3], v[i * 6 + 4]], contentWidth: v[i * 6 + 5] });
+    }
+    return lanes;
+  }
+  setLaneScroll(lane, x) { this.#m._gv_gallery_set_lane_scroll(this.#g, lane, x); }
+  /** The selection's lane and the scroll that shows it, or null if it shows or is in none. */
+  revealLane() {
+    if (!this.#m._gv_gallery_reveal_lane(this.#g, this.#scratch)) return null;
+    const v = new Float32Array(this.#m.HEAPU8.buffer, this.#scratch, 2);
+    return { lane: v[0], x: v[1] };
+  }
+  /** Atlas's camera: { k, x, y, fit, level }, view points = map units × k + (x, y). */
+  get atlasCamera() {
+    this.#m._gv_gallery_atlas_camera(this.#g, this.#scratch);
+    const v = new Float32Array(this.#m.HEAPU8.buffer, this.#scratch, 4);
+    const [k, x, y, fit] = v;
+    return { k, x, y, fit, level: k < fit * 1.55 ? 0 : k < fit * 3.3 ? 1 : 2 };
+  }
+  /** Zooms the map by `factor` about a point of the view; pans it; or goes to a level (0–2). */
+  atlasZoom(factor, x, y) { this.#m._gv_gallery_atlas_zoom(this.#g, factor, x, y); }
+  atlasPan(dx, dy) { this.#m._gv_gallery_atlas_pan(this.#g, dx, dy); }
+  atlasLevel(level) { this.#m._gv_gallery_atlas_level(this.#g, level); }
+
+  /** Catalogue: { spread, spreads, index }: the spread in view, how many, and the index's first. */
+  get catalogue() {
+    this.#m._gv_gallery_catalogue(this.#g, this.#scratch);
+    const v = new Uint32Array(this.#m.HEAPU8.buffer, this.#scratch, 3);
+    return { spread: v[0], spreads: v[1], index: v[2] };
+  }
+  setCatalogueSpread(spread) { this.#m._gv_gallery_set_catalogue_spread(this.#g, spread); }
+  catalogueIndex() { this.#m._gv_gallery_catalogue_index(this.#g); }
+
+  /** Ladders' scale: each strip its own, or one shared. */
+  setLadders(shared) { this.#m._gv_gallery_set_ladders(this.#g, shared ? 1 : 0); }
+
+  /** The folder can no longer be read: what was last seen, faded, with Reconnect. */
+  setLost(lost) { this.#m._gv_gallery_set_lost(this.#g, lost ? 1 : 0); }
+
+  /** A file being read, 0 to 1, or negative once it is not. */
+  setReading(file, fraction) { this.#m._gv_gallery_set_reading(this.#g, file, fraction); }
+  /** A file changed on disk: a Δ until seen, its picture faded until a new one comes. */
+  setChanged(file, changed) { this.#m._gv_gallery_set_changed(this.#g, file, changed ? 1 : 0); }
+  setStyle(style) { this.#m._gv_gallery_set_style(this.#g, style); }
+  setViewport(width, height) { this.#m._gv_gallery_set_viewport(this.#g, width, height); }
+  setScroll(top) { this.#m._gv_gallery_set_scroll(this.#g, top); }
+  setFolder(path) { return this.#string(path, (p) => this.#m._gv_gallery_set_folder(this.#g, p)) !== 0; }
+  get folder() { return this.#m.UTF8ToString(this.#m._gv_gallery_folder(this.#g)); }
+  get title() { return this.#m.UTF8ToString(this.#m._gv_gallery_folder_title(this.#g)); }
+  get subtitle() { return this.#m.UTF8ToString(this.#m._gv_gallery_folder_subtitle(this.#g)); }
+  get contentHeight() { return this.#m._gv_gallery_content_height(this.#g); }
+  get picturePixels() { return this.#m._gv_gallery_picture_pixels(this.#g); }
+
+  /** Lays out if anything changed; returns whether it did. */
+  layout() {
+    const changed = this.#m._gv_gallery_layout(this.#g) !== 0;
+    if (changed) this.#items = null;
+    return changed;
+  }
+
+  /** The display list, decoded once a layout. */
+  get items() {
+    if (this.#items) return this.#items;
+    const m = this.#m;
+    const n = m._gv_gallery_item_count(this.#g);
+    const base = m._gv_gallery_items(this.#g);
+    const view = new DataView(m.HEAPU8.buffer, base, n * kItemSize);
+    const text = m._gv_gallery_text(this.#g);
+    const items = new Array(n);
+    let end = 0;
+    for (let i = 0; i < n; i++) {
+      const o = i * kItemSize;
+      const u = (k) => view.getUint32(o + k * 4, true);
+      const f = (k) => view.getFloat32(o + k * 4, true);
+      items[i] = {
+        kind: u(0), flags: u(1), x: f(2), y: f(3), width: f(4), height: f(5),
+        fill: u(6), stroke: u(7), shadow: u(8), lineWidth: f(9), radius: f(10),
+        text: u(11), textLength: u(12), fontSize: f(13), tracking: f(14), weight: u(15), align: u(16),
+        baseline: f(17), file: u(18), targetKind: u(19), target: u(20), key: u(21),
+        group: u(22), line: f(23), column: u(24), columnLine: f(25),
+        stickyTop: f(26), stickyUntil: f(27), lane: u(28),
+      };
+      end = Math.max(end, items[i].text + items[i].textLength);
+    }
+    this.#textBytes = m.HEAPU8.slice(text, text + end);
+    this.#items = items;
+    return items;
+  }
+
+  /** An item's text. */
+  text(item) {
+    return new TextDecoder().decode(this.#textBytes.subarray(item.text, item.text + item.textLength));
+  }
+
+  hit(x, y) {
+    const m = this.#m;
+    m._gv_gallery_hit(this.#g, x, y, this.#scratch);
+    const out = new Uint32Array(m.HEAPU8.buffer, this.#scratch, 3);
+    return { kind: out[0], target: out[1], key: out[2] };
+  }
+
+  hover(kind, target) { return this.#m._gv_gallery_hover(this.#g, kind, target) !== 0; }
+
+  #action(call) {
+    call(this.#scratch);
+    const out = new Uint32Array(this.#m.HEAPU8.buffer, this.#scratch, 2);
+    return { kind: out[0], target: out[1] };
+  }
+
+  click(kind, target, twice) {
+    return this.#action((out) => this.#m._gv_gallery_click(this.#g, kind, target, twice ? 1 : 0, out));
+  }
+
+  key(key) {
+    return this.#action((out) => this.#m._gv_gallery_key(this.#g, key, out));
+  }
+
+  // ---- Views, search, Peek and motion ----
+
+  /** The views that may be shown, a bit each (1 << Views.Plates ...). */
+  setViews(mask) { this.#m._gv_gallery_set_views(this.#g, mask); }
+  get views() { return this.#m._gv_gallery_views(this.#g) >>> 0; }
+  /** Shows a view if it is enabled; the folder in view remembers it. */
+  setView(view) { return this.#m._gv_gallery_set_view(this.#g, view) !== 0; }
+  get view() { return this.#m._gv_gallery_view(this.#g); }
+  /** Sheet's scale (Scales), cell size in points and order (Sorts). */
+  setSheet(scale, cell, sort) { this.#m._gv_gallery_set_sheet(this.#g, scale, cell, sort); }
+
+  setSearch(query) { this.#string(query, (p) => this.#m._gv_gallery_set_search(this.#g, p)); }
+  get search() { return this.#m.UTF8ToString(this.#m._gv_gallery_search(this.#g)); }
+  /** How many files the search found, or null with no search. */
+  get matches() {
+    const n = this.#m._gv_gallery_matches(this.#g) >>> 0;
+    return n === kNone ? null : n;
+  }
+
+  peek(file) { this.#m._gv_gallery_peek(this.#g, file ?? kNone); }
+  get peeking() {
+    const file = this.#m._gv_gallery_peeking(this.#g) >>> 0;
+    return file === kNone ? null : file;
+  }
+  /** Whether the file in Peek can turn: its turntable's frames have come. */
+  setPeekTurnable(turnable) { this.#m._gv_gallery_set_peek_turnable(this.#g, turnable); }
+  get peekTurnable() { return Boolean(this.#m._gv_gallery_peek_turnable(this.#g)); }
+
+  /** The selected file, or null. */
+  get selected() {
+    const file = this.#m._gv_gallery_selected(this.#g) >>> 0;
+    return file === kNone ? null : file;
+  }
+
+  /** Where to scroll so the selection shows, or null if it shows already. */
+  get reveal() {
+    const top = this.#m._gv_gallery_reveal(this.#g);
+    return top < 0 ? null : top;
+  }
+
+  /** What the last layout plays against the one before: { kind, rect: [x, y, w, h], duration, fadeOut }. */
+  get transition() {
+    const m = this.#m;
+    m._gv_gallery_transition(this.#g, this.#scratch);
+    const v = new Float32Array(m.HEAPU8.buffer, this.#scratch, 7);
+    return { kind: v[0], rect: [v[1], v[2], v[3], v[4]], duration: v[5], fadeOut: v[6] };
+  }
+
+  /** The last layout's tracks: [{ item, kind, from: [x, y, w, h], delay, duration }]. */
+  get tracks() {
+    const m = this.#m;
+    const n = m._gv_gallery_tracks(this.#g, 0, 0);
+    if (n === 0) return [];
+    const out = m._malloc(n * 32);
+    m._gv_gallery_tracks(this.#g, out, n);
+    const v = new Float32Array(m.HEAPU8.buffer, out, n * 8).slice();
+    m._free(out);
+    const tracks = new Array(n);
+    for (let i = 0; i < n; i++) {
+      const o = i * 8;
+      tracks[i] = { item: v[o], kind: v[o + 1], from: [v[o + 2], v[o + 3], v[o + 4], v[o + 5]],
+                    delay: v[o + 6], duration: v[o + 7] };
+    }
+    return tracks;
+  }
+
+  /** The files drawn large in view, nearest the middle first: those whose detail pictures are wanted. */
+  details() {
+    const m = this.#m;
+    const out = m._malloc(32 * 4);
+    const n = Math.min(32, m._gv_gallery_details(this.#g, out, 32));
+    const files = [...new Uint32Array(m.HEAPU8.buffer, out, n)];
+    m._free(out);
+    return files;
+  }
+
+  /** The files to draw, in the library's bands: [{ file, band, order, folderColor }]. */
+  wanted() {
+    const m = this.#m;
+    const n = m._gv_gallery_wanted(this.#g, 0, 0);
+    const out = m._malloc(Math.max(32, n * 32));
+    m._gv_gallery_wanted(this.#g, out, n);
+    const values = new Float64Array(m.HEAPU8.buffer, out, n * 4).slice();
+    m._free(out);
+    const wants = new Array(n);
+    for (let i = 0; i < n; i++) {
+      wants[i] = { file: values[i * 4], band: values[i * 4 + 1], order: values[i * 4 + 2], folderColor: values[i * 4 + 3] };
+    }
+    return wants;
+  }
+
+  /** The alignment groups painted more than `tolerance` apart: { over: [{ group, column, spread, items }], checked }. */
+  check(lines, columns, tolerance = 0.5) {
+    const m = this.#m;
+    const n = lines.length;
+    const l = m._malloc(Math.max(4, n * 4)), c = m._malloc(Math.max(4, n * 4));
+    const out = m._malloc(64 * 32), checked = m._malloc(4);
+    new Float32Array(m.HEAPU8.buffer, l, n).set(lines);
+    new Float32Array(m.HEAPU8.buffer, c, n).set(columns);
+    const over = m._gv_gallery_check(this.#g, l, c, tolerance, out, 64, checked);
+    const values = new Float64Array(m.HEAPU8.buffer, out, Math.min(over, 64) * 4).slice();
+    const count = new Uint32Array(m.HEAPU8.buffer, checked, 1)[0];
+    for (const p of [l, c, out, checked]) m._free(p);
+    const groups = [];
+    for (let i = 0; i < values.length / 4; i++) {
+      groups.push({ group: values[i * 4], column: values[i * 4 + 1] === 1, spread: values[i * 4 + 2], items: values[i * 4 + 3] });
+    }
+    return { over: groups, checked: count };
+  }
+
+  /** A style's sheet: { top, bottom, vignette, grid, gridAlpha, gridPitch, dark }. */
+  sheet(style) {
+    const m = this.#m;
+    m._gv_style_sheet(style, this.#scratch);
+    const v = new Float32Array(m.HEAPU8.buffer, this.#scratch, 13);
+    return { top: [v[0], v[1], v[2]], bottom: [v[3], v[4], v[5]], vignette: v[6], grid: [v[7], v[8], v[9]],
+             gridAlpha: v[10], gridPitch: v[11], dark: v[12] === 1 };
+  }
+}

package/web/gallery-library.js

@@ -0,0 +1,262 @@
+// The gallery's library in the browser: the files a gallery wants, in bands, become facts and
+// pictures, from what this browser kept where it can, else by importing and drawing, as the Mac's
+// library::Service does (Engine/library/service.h).
+//
+// A file is looked up by its key (kept.js): its facts and its picture in the current drawing spec.
+// Missing either, its kept import is drawn; missing that too, it is imported first, in the gallery's
+// lane of the page's importers (importers.js), so a file a person opens never waits behind it.
+// Pictures are drawn in the picture worker (thumbs.js), which keeps them and the facts.
+
+import { keptImport, keptPicture, keyOf, pictureKeyOf } from "./kept.js";
+
+const kBands = ["open", "visible", "near", "prefetch"];
+
+// A phone stops a page well before it would on a computer, and its gallery imports alongside its
+// pictures and page: a file larger than this is not imported there. It shows as a file that could
+// not be drawn, saying why, and opens on a computer. A STEP file's import takes many times its
+// size (a 16 MB file 390-700 MB on an iPhone 16 Pro), an STL file's about 115 bytes a triangle.
+export const kPhoneStepBytes = 12 * 1024 ** 2;
+export const kPhoneStlBytes = 16 * 1024 ** 2;
+
+function tooLargeForPhone(bytes) {
+  return new Error(`Too large to draw on a phone (${Math.round(bytes / 1024 ** 2)} MB). Open it on a computer.`);
+}
+
+export class GalleryLibrary {
+  #importers;
+  #thumbnailer;
+  #version;
+  #on;
+  #worker = null;
+  #folders = null; // the store's folders, which read a connected folder's files
+  #lost = false;
+
+  /** The folder can no longer be read: show only what was kept. */
+  setLost(lost) {
+    this.#lost = lost;
+    if (!lost) {
+      this.#done.clear();
+      this.#failed.clear();
+    }
+  }
+
+  // What was kept of a file, without reading it: its key from the last listing's size and time.
+  async #kept(w) {
+    const root = this.#root, spec = this.#spec;
+    if (!root || !spec) return;
+    const key = await keyOf({ source: root.name, path: w.path, size: w.bytes, modified: w.modified,
+                              version: this.#version });
+    const picture = await pictureKeyOf({ ...spec, folderColor: w.folderColor, version: this.#version });
+    const kept = await keptPicture(key, picture);
+    if (kept?.facts) this.#on.facts?.(w.path, kept.facts);
+    if (kept?.png && kept.note) this.#on.picture?.(w.path, kept.png, kept.note);
+  }
+  #root = null; // { id, name }
+  #spec = null;
+  #done = new Set(); // paths with their facts and picture in the current spec
+  #failed = new Set();
+  #phone;
+
+  /**
+   * `on` takes facts(path, facts), picture(path, png, note) and failed(path, message), as each is
+   * known, and reading(path, fraction) while a file is imported. `version` is the cache files'
+   * version, which keys hold.
+   */
+  // Whether the walk's sizes and times find a file in the caches, so the file itself is fetched
+  // only to import it: the shell's are its own, and fetching a file there reads all of it.
+  #walkStats;
+
+  constructor({ importers, thumbnailer, version, phone = false, walkStats = false }, on) {
+    this.#walkStats = walkStats;
+    this.#importers = importers;
+    this.#thumbnailer = thumbnailer;
+    this.#version = version;
+    this.#phone = phone;
+    this.#on = on;
+  }
+
+  /** The connected folder the gallery shows, and the store's folders that read it. */
+  setRoot(folders, root) {
+    this.#folders = folders;
+    this.#root = root;
+    this.#done.clear();
+    this.#failed.clear();
+  }
+
+  /** How pictures are drawn: { style, colorMode, pixels, pixelsPerPoint, lineScale }. */
+  setSpec(spec) {
+    this.#spec = spec;
+    this.#done.clear();
+  }
+
+  /**
+   * Replaces what is wanted: [{ path, band (1 in view .. 3 elsewhere), order, folderColor, bytes,
+   * modified }]. While the folder cannot be read, only what was kept is shown, found by the size and
+   * time the last listing gave.
+   */
+  want(wants) {
+    const jobs = [];
+    for (const w of wants) {
+      if (this.#done.has(w.path) || this.#failed.has(w.path)) continue;
+      jobs.push({ id: w.path, band: kBands[w.band] ?? "prefetch", order: w.order, bytes: w.bytes ?? 0,
+                  run: (signal) => (this.#lost ? this.#kept(w) : this.#draw(w.path, w.folderColor, signal, w)) });
+    }
+    this.#importers.want(jobs, {
+      onDone: (path) => this.#done.add(path),
+      onFailed: (path, error) => {
+        this.#failed.add(path);
+        this.#on.failed?.(path, String(error?.message ?? error));
+      },
+    });
+  }
+
+  // Where a file is in the caches: its key, from the size and time its walk gave where they are
+  // trusted, else from the file itself, fetched. { key, bytes, file }, the file null until needed.
+  async #locate(path, stat) {
+    const root = this.#root;
+    let file = null, bytes = stat?.bytes ?? 0, modified = stat?.modified ?? 0;
+    if (!this.#walkStats || !(bytes > 0 && modified > 0)) {
+      file = await this.#folders.file(root.id, path);
+      if (!file) throw new Error("This file could not be read.");
+      bytes = file.size;
+      modified = file.lastModified;
+      // Its size and time, kept with the listing, find its picture again if the folder cannot be read.
+      this.#on.measured?.(path, bytes, modified);
+    }
+    const key = await keyOf({ source: root.name, path, size: bytes, modified, version: this.#version });
+    return { key, bytes, file };
+  }
+
+  // The file itself, to import it: fetched now if its walk found it.
+  async #fileOf(path, located) {
+    located.file ??= await this.#folders.file(this.#root.id, path);
+    if (!located.file) throw new Error("This file could not be read.");
+    return located.file;
+  }
+
+  #tooLarge(path, bytes) {
+    return this.#phone && bytes > (/\.stl$/i.test(path) ? kPhoneStlBytes : kPhoneStepBytes);
+  }
+
+  async #draw(path, folderColor, signal, stat) {
+    const root = this.#root, spec = this.#spec;
+    if (!root || !spec) return;
+    const located = await this.#locate(path, stat);
+    const { key } = located;
+    const picture = await pictureKeyOf({ ...spec, folderColor, version: this.#version });
+    // Kept before: its facts at once, and its picture if drawn in this spec.
+    const kept = await keptPicture(key, picture);
+    if (kept?.facts) this.#on.facts?.(path, kept.facts);
+    if (kept?.png && kept.note) {
+      this.#on.picture?.(path, kept.png, kept.note);
+      return;
+    }
+    if (signal.aborted) throw new Error("cancelled");
+    // Its import kept before, or imported now.
+    let blob = (await keptImport(key, this.#version))?.blob;
+    if (!blob && this.#tooLarge(path, located.bytes)) throw tooLargeForPhone(located.bytes);
+    if (!blob) {
+      this.#on.reading?.(path, 0);
+      const file = await this.#fileOf(path, located);
+      blob = await this.#import(file, key, signal, (fraction) => this.#on.reading?.(path, fraction));
+    }
+    const drawn = await this.#thumbnailer.draw(blob, spec, -1, { folderColor, keep: { key, picture } });
+    drawn.bitmap?.close();
+    if (drawn.facts) this.#on.facts?.(path, drawn.facts);
+    this.#on.picture?.(path, drawn.png, { width: drawn.width, height: drawn.height, mmPerPixel: drawn.worldPerPixel,
+                                          part: drawn.partRect, ink: drawn.inkRect, firstColor: drawn.firstColor });
+  }
+
+  /**
+   * A file's detail picture, for where it is drawn large: the same picture at twice the pixels and
+   * twice the pixels a point, kept like the gallery's and read back if kept. The file is imported
+   * first if its import was not kept. Resolves to { png, note }, or null when it cannot be drawn.
+   */
+  async detail(path, folderColor, signal, stat) {
+    const root = this.#root, spec = this.#spec;
+    if (!root || !spec) return null;
+    const detail = { ...spec, pixels: spec.pixels * 2, pixelsPerPoint: spec.pixelsPerPoint * 2, supersample: 1 };
+    const located = await this.#locate(path, stat).catch(() => null);
+    if (!located) return null;
+    const { key } = located;
+    const picture = await pictureKeyOf({ ...detail, folderColor, version: this.#version });
+    const kept = await keptPicture(key, picture);
+    if (kept?.png && kept.note) return { png: kept.png, note: kept.note };
+    if (signal.aborted) return null;
+    let blob = (await keptImport(key, this.#version))?.blob;
+    if (!blob && this.#tooLarge(path, located.bytes)) return null;
+    if (!blob) blob = await this.#import(await this.#fileOf(path, located), key, signal);
+    if (signal.aborted) return null;
+    const drawn = await this.#thumbnailer.draw(blob, detail, -1, { folderColor, keep: { key, picture } });
+    drawn.bitmap?.close();
+    return { png: drawn.png, note: { width: drawn.width, height: drawn.height, mmPerPixel: drawn.worldPerPixel,
+                                     part: drawn.partRect, ink: drawn.inkRect } };
+  }
+
+  /**
+   * Peek's turntable: `frames` pictures of the file at `path`, `pixels` square, turned evenly about
+   * the upright at one scale (its box's diagonal, from `size` in millimetres, fits whichever way it
+   * faces), each handed to `onFrame(frame, bitmap, note)` as it is drawn. The file is imported first
+   * if its import was not kept. Stops when `signal` aborts.
+   */
+  async turn(path, folderColor, frames, pixels, size, onFrame, signal, stat) {
+    const root = this.#root, spec = this.#spec;
+    if (!root || !spec) return false;
+    const located = await this.#locate(path, stat).catch(() => null);
+    if (!located) return false;
+    const { key } = located;
+    let blob = (await keptImport(key, this.#version))?.blob;
+    if (!blob && this.#tooLarge(path, located.bytes)) return false; // too large here
+    if (!blob) {
+      if (signal.aborted) return false;
+      blob = await this.#import(await this.#fileOf(path, located), key, signal);
+    }
+    const worldPerPixel = size ? Math.hypot(...size) * 1.1 / pixels : 0;
+    for (let frame = 0; frame < frames; frame++) {
+      if (signal.aborted) return false;
+      // Drawn as a detail is: lines as thick for its size as a picture's, and not supersampled.
+      const drawn = await this.#thumbnailer.draw(blob, { ...spec, pixels, turn: (360 * frame) / frames, worldPerPixel,
+                                                         pixelsPerPoint: spec.pixelsPerPoint * pixels / spec.pixels,
+                                                         supersample: 1 }, -1, { folderColor });
+      onFrame(frame, drawn.bitmap, { width: drawn.width, height: drawn.height, ink: drawn.inkRect });
+    }
+    return !signal.aborted;
+  }
+
+  // Imports in the gallery's own worker; a file in a connected folder keeps no source copy.
+  async #import(file, key, signal, progress) {
+    this.#worker ??= new Worker(new URL("./import-worker.js", import.meta.url), { type: "module" });
+    const worker = this.#worker;
+    const stl = /\.stl$/i.test(file.name);
+    const result = await new Promise((resolve) => {
+      worker.onmessage = ({ data }) => {
+        if (data.type === "progress" && data.total > 0) progress?.(data.done / data.total);
+        if (data.type === "done" || data.type === "failed") resolve(data);
+      };
+      worker.onerror = (event) => resolve({ type: "failed", message: event.message ?? "The importer failed." });
+      signal.addEventListener("abort", () => worker.postMessage({ type: "cancel" }), { once: true });
+      worker.postMessage({ type: "import", file, kind: stl ? "stl" : "step", name: file.name, key, keepSource: false,
+                           workers: this.#phone ? 1 : 2, threads: false, progressive: false });
+    });
+    // A phone lets its importer go after each file: its heap only grows, and the page's memory is
+    // what the phone watches.
+    if (this.#phone) {
+      worker.terminate();
+      this.#worker = null;
+    }
+    if (result.type !== "done") throw new Error(result.message ?? "This file could not be read.");
+    const kept = await keptImport(key, this.#version);
+    if (!kept) throw new Error("The import was not kept.");
+    return kept.blob;
+  }
+}
+
+/** Facts as kept (scene::Facts' JSON) to the layout's: sides in millimetres, parts and name. */
+export function layoutFacts(facts) {
+  const hasBox = Array.isArray(facts.min) && Array.isArray(facts.max);
+  return {
+    size: hasBox ? facts.max.map((v, i) => v - facts.min[i]) : [0, 0, 0],
+    hasBox, estimated: Boolean(facts.estimated), parts: facts.parts ?? 0, product: facts.name ?? "",
+    triangles: facts.triangles ?? 0,
+  };
+}