@swiftbrowser/web 0.19.0 → 0.23.0

package/app/index.html

@@ -40,9 +40,16 @@
         var coarse = typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches;
         var device = mode === 'device' || (mode !== 'frame' && (coarse || site.pageMode === 'device'));
         document.documentElement.setAttribute('data-sb-mode', device ? 'device' : 'frame');
+        // The preview's device (src/deviceFrame.ts in @swiftbrowser/web): ?device=, else the last one picked.
+        var frame = new URLSearchParams(location.search).get('device');
+        var embedded = new URLSearchParams(location.search).get('embed') === '1';
+        try { frame = frame || (embedded ? null : localStorage.getItem('sb-device-frame')); } catch (e) {}
+        document.documentElement.setAttribute('data-sb-frame', frame === 'ipad' || frame === 'none' ? frame : 'iphone');
+        // ?toolbar=0: the toolbar's close button hid it (src/deviceFrame.ts).
+        if (new URLSearchParams(location.search).get('toolbar') === '0') document.documentElement.setAttribute('data-sb-toolbar', 'hidden');
         // ?embed=1: the page is in another's frame (the playground's
         // simulator), which has its own controls: the device alone.
-        if (new URLSearchParams(location.search).get('embed') === '1') document.documentElement.setAttribute('data-sb-embed', '');
+        if (embedded) document.documentElement.setAttribute('data-sb-embed', '');
       })();
       // Point the manifest, the home-screen icon and the titles at the app
       // this page runs (?app=, else the site's default), so Share -> Add to
@@ -73,9 +80,6 @@
   </head>
   <body>
     <header class="toolbar" role="toolbar" aria-label="SwiftBrowser controls">
-      <span class="toolbar-brand">SwiftBrowser</span>
-      <span class="toolbar-sep" aria-hidden="true"></span>
-      <span class="toolbar-label">App</span>
       <span id="app-name" class="toolbar-value">Loading…</span>
       <span class="toolbar-spacer"></span>
       <span id="build-status" class="toolbar-build" role="status" aria-live="polite" hidden>Rebuilding…</span>
@@ -114,9 +118,9 @@
               </svg>
               <!-- Wi-Fi -->
               <svg class="glyph glyph-wifi" viewBox="0 0 16.3 12.33" width="16.3" height="12.33">
-                <path class="wifi-band" d="M1.08 3.87A11.0 11.0 0 0 1 15.22 3.87" stroke-width="2.6" />
-                <path class="wifi-band" d="M3.91 7.24A6.6 6.6 0 0 1 12.39 7.24" stroke-width="2.9" />
-                <path d="M8.15 12.3L5.64 9.31A3.9 3.9 0 0 1 10.66 9.31Z" />
+                <path d="M0.02 3.3A12.15 12.15 0 0 1 16.28 3.3L14.41 5.38A9.35 9.35 0 0 0 1.89 5.38Z" />
+                <path d="M2.8 6.38A8 8 0 0 1 13.5 6.38L11.66 8.43A5.25 5.25 0 0 0 4.64 8.43Z" />
+                <path d="M8.15 12.33L5.54 9.43A3.9 3.9 0 0 1 10.76 9.43Z" />
               </svg>
               <!-- Battery -->
               <svg class="glyph glyph-battery" viewBox="0 0 28 13" width="28" height="13">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swiftbrowser/web",
-  "version": "0.19.0",
+  "version": "0.23.0",
   "type": "module",
   "description": "SwiftBrowser web renderer and dev server: applies render ops from a Swift/Wasm app to the DOM inside an iPhone frame.",
   "repository": {

package/src/appFiles.ts

@@ -125,10 +125,15 @@ export interface FilesPersistence {
   clear(): Promise<void>;
 }
 
-/** A row of the `entries` store: a file's bytes or a directory, with when it was last written where the writer said. */
+/**
+ * A row of the `entries` store: a file's bytes or a directory, with when it
+ * was last written where the writer said. A React app's `fileManager`
+ * (files.ts) may keep a file as the `Blob` the viewer handed over, which
+ * IndexedDB stores without reading; the module's loader reads one on load.
+ */
 export interface EntryRow {
   path: string;
-  data?: Uint8Array;
+  data?: Uint8Array | Blob;
   directory?: boolean;
   /** Milliseconds since the epoch; rows the module wrote (and older rows) have none. */
   modified?: number;
@@ -181,7 +186,11 @@ export function indexedDBFiles(app: string, factory: IDBFactory = indexedDB): Fi
       const db = await database();
       const rows = await request(db.transaction(ENTRIES, 'readonly').objectStore(ENTRIES).getAll() as IDBRequest<EntryRow[]>);
       const entries: HomeEntries = new Map();
-      for (const row of rows) entries.set(row.path, row.directory ? null : new Uint8Array(row.data ?? new Uint8Array()));
+      for (const row of rows) {
+        if (row.directory) entries.set(row.path, null);
+        else if (row.data !== undefined && typeof Blob !== 'undefined' && row.data instanceof Blob) entries.set(row.path, new Uint8Array(await row.data.arrayBuffer()));
+        else entries.set(row.path, new Uint8Array((row.data as Uint8Array | undefined) ?? new Uint8Array()));
+      }
       return entries;
     },
     apply(changes) {

package/src/audioEngine.ts

@@ -68,10 +68,11 @@ export type AudioEngineCommand =
   | { action: 'playerTime'; node: number }
   | { action: 'loadZones'; node: number; zones: SamplerZone[]; attack: number; release: number }
   | { action: 'loadInstrument'; node: number; url: string; program?: number; bankMSB?: number; bankLSB?: number }
-  | { action: 'startNote'; node: number; note: number; velocity: number; channel: number }
-  | { action: 'stopNote'; node: number; note: number; channel: number }
-  | { action: 'controller'; node: number; controller: number; value: number; channel: number }
-  | { action: 'pitchBend'; node: number; value: number; channel: number }
+  // `beat`: when on a package node's transport (a DSP program's); a sampler ignores it.
+  | { action: 'startNote'; node: number; note: number; velocity: number; channel: number; beat?: number }
+  | { action: 'stopNote'; node: number; note: number; channel: number; beat?: number }
+  | { action: 'controller'; node: number; controller: number; value: number; channel: number; beat?: number }
+  | { action: 'pitchBend'; node: number; value: number; channel: number; beat?: number }
   | { action: 'meter'; node: number };
 
 /** The note commands an instrument takes: a sampler, or a node of a kind a package adds. */
@@ -149,7 +150,7 @@ export function browserAudioEngine(files: () => FilesHost | undefined): AudioEng
   if (typeof AudioContext === 'undefined') return undefined;
   let context: AudioContext | null = null;
   return new WebAudioEngineHost({
-    context: () => (context ??= new AudioContext({ latencyHint: 'interactive' })),
+    context: () => (context ??= resumeOnActivation(new AudioContext({ latencyHint: 'interactive' }))),
     read: async (url) => {
       const host = files();
       if (url.startsWith('file:') && host) {
@@ -166,6 +167,29 @@ export function browserAudioEngine(files: () => FilesHost | undefined): AudioEng
   });
 }
 
+/**
+ * Resumes `context` at each user activation while it is not running. A
+ * page's context starts only inside one, and a touch's start is not one
+ * (Safari and Chrome count its end, a click, a key): an app that starts its
+ * engine as a finger lands, a keyboard's note, would otherwise leave the
+ * context suspended and the engine silent. Safari also suspends or
+ * interrupts a running context (a call, the page in the background), and the
+ * next tap brings it back.
+ */
+function resumeOnActivation(context: AudioContext): AudioContext {
+  if (typeof document === 'undefined') return context;
+  const events = ['touchend', 'pointerup', 'click', 'keydown'] as const;
+  const resume = (): void => {
+    if (context.state === 'closed') {
+      for (const type of events) document.removeEventListener(type, resume, true);
+      return;
+    }
+    if (context.state !== 'running') context.resume().catch(() => undefined);
+  };
+  for (const type of events) document.addEventListener(type, resume, { capture: true, passive: true });
+  return context;
+}
+
 /** Decibels as a gain. */
 export const gainOf = (decibels: number): number => Math.pow(10, decibels / 20);
 

package/src/deviceFrame.ts

@@ -0,0 +1,188 @@
+/**
+ * Which device a desktop preview draws the app in (frame mode only; a real
+ * phone or tablet is device mode, deviceMode.ts): an iPhone (the default),
+ * an iPad in landscape, or no device at all, the app filling the window
+ * under the toolbar. styles.css and page.css draw each from the document's
+ * `data-sb-frame`; the layout engine gets the device's safe area, and its
+ * size from the screen's box, so an iPad (or a wide window) lays out in the
+ * regular size class, sidebars and all.
+ *
+ * `?device=iphone|ipad|none` picks one (and is what the picker writes, so a
+ * link shares it); otherwise the last one picked on this site, from
+ * localStorage. The toolbar's close button (an x in a circle, at its end)
+ * hides the toolbar and writes `?toolbar=0`, so a link shows the app alone;
+ * without that parameter the toolbar is back. The pages' inline scripts apply the same rule before the
+ * first paint (app/index.html's, and the native apps' web/index.html), so
+ * an iPad never flashes an iPhone first.
+ */
+
+import type { EdgeInsets } from './layout';
+
+export type DeviceFrame = 'iphone' | 'ipad' | 'none';
+
+export const DEVICE_FRAMES: readonly { id: DeviceFrame; label: string }[] = [
+  { id: 'iphone', label: 'iPhone' },
+  { id: 'ipad', label: 'iPad' },
+  { id: 'none', label: 'None' },
+];
+
+/**
+ * The safe area each device gives the app: an iPhone 15 Pro's status bar and
+ * home indicator, an iPad's (24 and 20 points, as iPadOS draws them in
+ * landscape), and none without a device.
+ */
+export const FRAME_SAFE_AREAS: Readonly<Record<DeviceFrame, EdgeInsets>> = {
+  iphone: { top: 59, leading: 0, bottom: 34, trailing: 0 },
+  ipad: { top: 24, leading: 0, bottom: 20, trailing: 0 },
+  none: { top: 0, leading: 0, bottom: 0, trailing: 0 },
+};
+
+/** Where the last device picked is kept. */
+export const DEVICE_FRAME_KEY = 'sb-device-frame';
+
+const isFrame = (value: unknown): value is DeviceFrame => value === 'iphone' || value === 'ipad' || value === 'none';
+
+/** `?device=`, else the stored choice, else the iPhone. */
+export function decideDeviceFrame(search: string = location.search, storage: Pick<Storage, 'getItem'> | null = safeStorage()): DeviceFrame {
+  const asked = new URLSearchParams(search).get('device');
+  if (isFrame(asked)) return asked;
+  let stored: string | null = null;
+  try {
+    stored = storage?.getItem(DEVICE_FRAME_KEY) ?? null;
+  } catch {
+    // Storage blocked: the default.
+  }
+  return isFrame(stored) ? stored : 'iphone';
+}
+
+/**
+ * Marks the document with the device (`data-sb-frame`) and gives the status
+ * bar the date an iPad shows beside the time.
+ */
+export function applyDeviceFrame(frame: DeviceFrame, doc: Document = document): void {
+  doc.documentElement.dataset['sbFrame'] = frame;
+  const time = doc.querySelector('.status-time');
+  if (time && !time.querySelector('.status-date')) {
+    const date = doc.createElement('span');
+    date.className = 'status-date';
+    date.textContent = 'Tue Jan 9';
+    time.append(date);
+  }
+}
+
+/** What the picker drives: the renderer (or a mounted React root's). */
+export interface DeviceFrameTarget {
+  setSafeArea(insets: EdgeInsets | null): void;
+  viewportChanged(): void;
+}
+
+export interface DeviceFramePickerOptions {
+  /** The page's toolbar, which gets the picker. */
+  toolbar?: HTMLElement | null;
+  /** The toolbar item the picker goes before; the theme toggle by default, else the end. */
+  before?: Element | null;
+  search?: string;
+  storage?: Pick<Storage, 'getItem' | 'setItem'> | null;
+  /** Called after each change of device, the new one applied. */
+  onChange?: (frame: DeviceFrame) => void;
+  /** The close button at the toolbar's end (`installToolbarClose`); on unless false. */
+  closeButton?: boolean;
+}
+
+/**
+ * A desktop preview's device: applies the chosen one, lays the app out for
+ * it, and adds a Device picker to the toolbar that switches it in place (the
+ * app keeps its state) and remembers it. Does nothing in device mode, where
+ * the page is the device. Returns the device in use.
+ */
+export function installDeviceFrame(target: DeviceFrameTarget, options: DeviceFramePickerOptions = {}): DeviceFrame {
+  const doc = document;
+  if (doc.documentElement.dataset['sbMode'] === 'device') return 'iphone';
+  const storage = options.storage === undefined ? safeStorage() : options.storage;
+  let frame = decideDeviceFrame(options.search ?? location.search, storage);
+  const show = (next: DeviceFrame): void => {
+    frame = next;
+    applyDeviceFrame(next, doc);
+    target.setSafeArea(FRAME_SAFE_AREAS[next]);
+    target.viewportChanged();
+  };
+  show(frame);
+
+  const toolbar = options.toolbar === undefined ? doc.querySelector<HTMLElement>('.toolbar') : options.toolbar;
+  if (toolbar && options.closeButton !== false) installToolbarClose(toolbar, target);
+  if (!toolbar || toolbar.querySelector('#device-frame')) return frame;
+  const label = doc.createElement('label');
+  label.className = 'toolbar-label';
+  label.htmlFor = 'device-frame';
+  label.textContent = 'Device';
+  const select = doc.createElement('select');
+  select.id = 'device-frame';
+  select.className = 'toolbar-select';
+  for (const { id, label: text } of DEVICE_FRAMES) select.append(new Option(text, id, false, id === frame));
+  select.addEventListener('change', () => {
+    if (!isFrame(select.value)) return;
+    show(select.value);
+    try {
+      storage?.setItem(DEVICE_FRAME_KEY, select.value);
+    } catch {
+      // Storage full or blocked: the choice lasts the page.
+    }
+    const url = new URL(location.href);
+    if (select.value === 'iphone') url.searchParams.delete('device');
+    else url.searchParams.set('device', select.value);
+    history.replaceState(history.state, '', url);
+    options.onChange?.(frame);
+  });
+  const before = options.before === undefined ? toolbar.querySelector('#theme-toggle') : options.before;
+  if (before && before.parentElement === toolbar) {
+    toolbar.insertBefore(label, before);
+    toolbar.insertBefore(select, before);
+  } else {
+    toolbar.append(label, select);
+  }
+  return frame;
+}
+
+/** Whether the URL asks for the page without its toolbar (`?toolbar=0`). */
+export function toolbarHidden(search: string = location.search): boolean {
+  return new URLSearchParams(search).get('toolbar') === '0';
+}
+
+/**
+ * An x in a circle at the end of the toolbar that hides it, for the app
+ * alone in the page (a screenshot, a demo): the document gets
+ * `data-sb-toolbar="hidden"` (page.css), the URL `?toolbar=0` so a reload
+ * or a shared link keeps it hidden, and the renderer re-reads the screen's
+ * size, which grows without a device. The pages' inline scripts hide the
+ * toolbar before the first paint when the URL asks.
+ */
+export function installToolbarClose(toolbar: HTMLElement, target?: Pick<DeviceFrameTarget, 'viewportChanged'>): HTMLButtonElement {
+  const doc = toolbar.ownerDocument;
+  const existing = toolbar.querySelector<HTMLButtonElement>('.toolbar-close');
+  if (existing) return existing;
+  if (toolbarHidden()) doc.documentElement.dataset['sbToolbar'] = 'hidden';
+  const button = doc.createElement('button');
+  button.type = 'button';
+  button.className = 'toolbar-close';
+  button.setAttribute('aria-label', 'Hide the toolbar');
+  button.title = 'Hide the toolbar (remove ?toolbar=0 from the address to show it again)';
+  button.innerHTML =
+    '<svg viewBox="0 0 20 20" width="20" height="20" aria-hidden="true"><circle cx="10" cy="10" r="10" /><path d="M6.5 6.5l7 7M13.5 6.5l-7 7" /></svg>';
+  button.addEventListener('click', () => {
+    doc.documentElement.dataset['sbToolbar'] = 'hidden';
+    const url = new URL(location.href);
+    url.searchParams.set('toolbar', '0');
+    history.replaceState(history.state, '', url);
+    target?.viewportChanged();
+  });
+  toolbar.append(button);
+  return button;
+}
+
+function safeStorage(): Storage | null {
+  try {
+    return typeof localStorage === 'undefined' ? null : localStorage;
+  } catch {
+    return null;
+  }
+}

package/src/dragDrop.ts

@@ -32,6 +32,12 @@ export interface DragDropHost {
   readonly root: HTMLElement;
   send(event: RendererEvent): void;
   nodeOf(id: ElementId): LayoutNode | undefined;
+  /**
+   * How a dropped file reaches the app: as base64 `data` (a Swift app, whose
+   * events cross into linear memory), or by `reference` (a React app in the
+   * same page gets the `File` itself, and a dropped folder's files by path).
+   */
+  fileDrops?(): 'bytes' | 'reference';
 }
 
 function idOf(el: Element | null): ElementId | null {
@@ -488,7 +494,7 @@ export class ExternalDrops {
     const scale = scaleOf(this.host.root);
     const point = { x: round2((event.clientX - rect.left) / scale), y: round2((event.clientY - rect.top) / scale) };
     const patterns = patternsOf(destination);
-    void readItems(transfer, patterns).then((items) => {
+    void readItems(transfer, patterns, { reference: this.host.fileDrops?.() === 'reference' }).then((items) => {
       if (items.length === 0) return;
       const drop: DropEvent = { type: 'drop', id, phase: 'performed', items, x: point.x, y: point.y };
       this.host.send(drop);
@@ -514,36 +520,86 @@ export class ExternalDrops {
   }
 }
 
-/** The drag's items the patterns accept: strings as text, files as base64 bytes. */
-export async function readItems(transfer: DataTransfer, patterns: readonly string[]): Promise<DropItem[]> {
-  const reads: Promise<DropItem | null>[] = [];
+export interface ReadItemsOptions {
+  /** Carry each file by reference (`file`, and `path` inside a dropped folder) instead of reading it into base64 `data`. */
+  reference?: boolean;
+}
+
+/** The entry behind a dragged item where the browser offers one (`webkitGetAsEntry`), for folders. */
+type EntryItem = Pick<DataTransferItem, 'kind' | 'type' | 'getAsFile' | 'getAsString'> & { webkitGetAsEntry?: () => FileSystemEntry | null };
+
+/**
+ * The drag's items the patterns accept: strings as text, files as base64
+ * bytes (or by reference, `options.reference`). A dropped folder is walked
+ * (`webkitGetAsEntry`, which every browser with drag and drop offers) and
+ * each file in it that the patterns accept comes as an item of its own,
+ * named by its path from the folder, the folder's name first, as the folder
+ * chooser names picked files (hostRequests.ts `folderFiles`).
+ */
+export async function readItems(transfer: DataTransfer, patterns: readonly string[], options: ReadItemsOptions = {}): Promise<DropItem[]> {
+  const reads: Promise<DropItem[]>[] = [];
   const items = Array.from(transfer.items ?? []);
   if (items.length > 0) {
     for (const item of items) {
       if (item.kind === 'file') {
+        // The entry and the file must be taken now, inside the event: the item is empty afterwards.
+        const entry = (item as EntryItem).webkitGetAsEntry?.() ?? null;
+        if (entry?.isDirectory) {
+          reads.push(readDirectory(entry as FileSystemDirectoryEntry, entry.name, patterns, options));
+          continue;
+        }
         const file = item.getAsFile();
         const type = file?.type || 'application/octet-stream';
         if (!file || !acceptsType(patterns, type)) continue;
-        reads.push(readFile(file, type));
+        reads.push(readFile(file, type, undefined, options).then((read) => (read ? [read] : [])));
       } else if (item.kind === 'string' && (item.type === 'text/plain' || item.type === 'text/uri-list') && acceptsType(patterns, item.type)) {
         const type = item.type;
-        reads.push(new Promise((resolve) => item.getAsString((text) => resolve({ type, text }))));
+        reads.push(new Promise((resolve) => item.getAsString((text) => resolve([{ type, text }]))));
       }
     }
   } else {
     // Without `items` (an older browser, a synthetic transfer): the strings only.
     for (const type of ['text/plain', 'text/uri-list']) {
       const text = transfer.getData(type);
-      if (text && acceptsType(patterns, type)) reads.push(Promise.resolve({ type, text }));
+      if (text && acceptsType(patterns, type)) reads.push(Promise.resolve([{ type, text }]));
     }
   }
   const results = await Promise.all(reads);
-  return results.filter((item): item is DropItem => item !== null);
+  return results.flat();
+}
+
+/** Every file under a dropped folder's entry, at any depth, that the patterns accept, named by its path from the folder. */
+async function readDirectory(directory: FileSystemDirectoryEntry, path: string, patterns: readonly string[], options: ReadItemsOptions): Promise<DropItem[]> {
+  const entries = await allEntries(directory);
+  const out: DropItem[][] = await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = `${path}/${entry.name}`;
+      if (entry.isDirectory) return readDirectory(entry as FileSystemDirectoryEntry, entryPath, patterns, options);
+      const file = await new Promise<File | null>((resolve) => (entry as FileSystemFileEntry).file(resolve, () => resolve(null)));
+      const type = file?.type || 'application/octet-stream';
+      if (!file || !acceptsType(patterns, type)) return [];
+      const read = await readFile(file, type, entryPath, options);
+      return read ? [read] : [];
+    }),
+  );
+  return out.flat();
+}
+
+/** A directory entry's children: `readEntries` answers a batch at a time, until an empty one. */
+async function allEntries(directory: FileSystemDirectoryEntry): Promise<FileSystemEntry[]> {
+  const reader = directory.createReader();
+  const all: FileSystemEntry[] = [];
+  for (;;) {
+    const batch = await new Promise<FileSystemEntry[]>((resolve) => reader.readEntries(resolve, () => resolve([])));
+    if (batch.length === 0) return all;
+    all.push(...batch);
+  }
 }
 
-function readFile(file: File, type: string): Promise<DropItem | null> {
+function readFile(file: File, type: string, path: string | undefined, options: ReadItemsOptions): Promise<DropItem | null> {
+  if (options.reference) return Promise.resolve({ type, name: file.name, file, ...(path !== undefined ? { path } : {}) });
   return file
     .arrayBuffer()
-    .then((buffer) => ({ type, name: file.name, data: base64Encode(new Uint8Array(buffer)) }))
+    .then((buffer) => ({ type, name: file.name, data: base64Encode(new Uint8Array(buffer)), ...(path !== undefined ? { path } : {}) }))
     .catch(() => null);
 }

package/src/editorSelection.ts

@@ -11,6 +11,8 @@ import type { TextSelectionRange } from './protocol';
 
 /** The selection each bound editor last reported, or was last moved to. */
 const reported = new WeakMap<HTMLElement, string>();
+/** The text each editor last reported (what the viewer typed): a `text` coming back equal to it is an echo, any other came from outside. */
+const reportedText = new WeakMap<HTMLElement, string>();
 /** A selection the app set while the editor was not focused: where its caret goes when the app focuses it. */
 const pending = new WeakMap<HTMLElement, TextSelectionRange>();
 
@@ -41,14 +43,47 @@ export function wantsDeleteBackward(el: HTMLElement): boolean {
   return el.dataset['sbDeleteBackward'] !== undefined;
 }
 
+/** The editor reported `text` (the viewer typed it). */
+export function noteReportedText(el: HTMLElement, text: string): void {
+  reportedText.set(el, text);
+}
+
+/**
+ * Where a `text` the app sends came from: the echo of what the editor
+ * reported, or outside (another person's edit, the app's own change). The
+ * caret survives an echo on its own; an outside change moves what is under
+ * it, so the caret is moved too (`shiftOffset`), or the app's selection
+ * re-applied even when its numbers did not change.
+ */
+export function textArrived(el: HTMLElement, text: string): 'echo' | 'remote' {
+  return reportedText.get(el) === text ? 'echo' : 'remote';
+}
+
+/**
+ * Where an offset into `before` is in `after`: the same offset before the
+ * change (the common prefix), moved by the change's length after it (the
+ * common suffix), and at the change's end inside it.
+ */
+export function shiftOffset(before: string, after: string, offset: number): number {
+  const shortest = Math.min(before.length, after.length);
+  let prefix = 0;
+  while (prefix < shortest && before.charCodeAt(prefix) === after.charCodeAt(prefix)) prefix += 1;
+  let suffix = 0;
+  while (suffix < shortest - prefix && before.charCodeAt(before.length - 1 - suffix) === after.charCodeAt(after.length - 1 - suffix)) suffix += 1;
+  if (offset <= prefix) return offset;
+  if (offset >= before.length - suffix) return offset + (after.length - before.length);
+  return after.length - suffix;
+}
+
 /**
  * The app sent `range` (or no selection): the range the editor moves to now,
  * when it is focused; otherwise null, the range kept for `takePendingSelection`
  * when the app focuses the editor. Nothing for the selection the editor
- * itself reported, coming back.
+ * itself reported, coming back, unless `force` (the text changed from
+ * outside under it, so the same numbers mean a move).
  */
-export function selectionToApply(el: HTMLElement, range: TextSelectionRange | undefined): TextSelectionRange | null {
-  if (!range || reported.get(el) === key(range)) return null;
+export function selectionToApply(el: HTMLElement, range: TextSelectionRange | undefined, force = false): TextSelectionRange | null {
+  if (!range || (!force && reported.get(el) === key(range))) return null;
   reported.set(el, key(range));
   if (el.ownerDocument.activeElement === el) return range;
   pending.set(el, range);

package/src/files.ts

@@ -48,8 +48,19 @@ export interface FilesHost {
   readonly directories: FileDirectories;
   /** The file's bytes. */
   read(url: string): Promise<Uint8Array>;
-  /** Writes the bytes as the file, replacing one there; its directory must exist. */
-  write(url: string, data: Uint8Array): Promise<void>;
+  /**
+   * The file's bytes from `start` up to `end` (exclusive, clamped to the
+   * file's size): what `read` would answer, sliced, without the rest of the
+   * file in memory where the host can avoid it. Hosts before 0.20 lack it;
+   * `fileManager` then reads the whole file and slices.
+   */
+  readRange?(url: string, start: number, end: number): Promise<Uint8Array>;
+  /**
+   * Writes the bytes as the file, replacing one there; its directory must
+   * exist. A `Blob` (a `File` the viewer picked or dropped) is kept as it
+   * is where the host can, so a large file never passes through memory.
+   */
+  write(url: string, data: Uint8Array | Blob): Promise<void>;
   /** Removes a file, or a directory and everything in it. */
   remove(url: string): Promise<void>;
   /** Makes the directory and the directories above it; one already there is fine. */
@@ -136,13 +147,47 @@ function parentOf(path: string): string {
 // Rows: a home's files by path, in IndexedDB or memory
 // ---------------------------------------------------------------------------
 
+/**
+ * A file's contents: bytes, or a `Blob` kept as the viewer handed it over
+ * (IndexedDB stores one without reading it into memory).
+ */
+export type FileData = Uint8Array | Blob;
+
 /** A file's bytes, or null for a directory, and when it was written and made. */
 export interface FileRow {
-  data: Uint8Array | null;
+  data: FileData | null;
   modified: number | null;
   created: number | null;
 }
 
+function isBlob(data: FileData): data is Blob {
+  return typeof Blob !== 'undefined' && data instanceof Blob;
+}
+
+/** How many bytes a file's data holds. */
+export function dataSize(data: FileData): number {
+  return isBlob(data) ? data.size : data.byteLength;
+}
+
+/** A file's data as bytes. */
+export async function dataBytes(data: FileData): Promise<Uint8Array> {
+  return isBlob(data) ? new Uint8Array(await data.arrayBuffer()) : data;
+}
+
+/** The bytes of a file's data from `start` up to `end`, clamped. */
+export async function dataSlice(data: FileData, start: number, end: number): Promise<Uint8Array> {
+  const size = dataSize(data);
+  const from = Math.min(Math.max(0, Math.floor(start)), size);
+  const to = Math.min(Math.max(from, Math.floor(end)), size);
+  if (isBlob(data)) return new Uint8Array(await data.slice(from, to).arrayBuffer());
+  return data.subarray(from, to);
+}
+
+/** A copy of a file's data a row can keep: a Blob is immutable and kept as it is. */
+function ownData(data: FileData): FileData {
+  return isBlob(data) ? data : data.slice();
+}
+
 /** The rows of one home, by path relative to it (`Documents/notes.txt`). */
 export interface FileRows {
   get(path: string): Promise<FileRow | undefined>;
@@ -157,7 +202,7 @@ export function memoryRows(): FileRows {
   const rows = new Map<string, FileRow>();
   return {
     get: async (path) => rows.get(path),
-    put: async (path, row) => void rows.set(path, { data: row.data === null ? null : row.data.slice(), modified: row.modified, created: row.created }),
+    put: async (path, row) => void rows.set(path, { data: row.data === null ? null : ownData(row.data), modified: row.modified, created: row.created }),
     remove: async (paths) => paths.forEach((path) => rows.delete(path)),
     keys: async () => [...rows.keys()],
   };
@@ -173,14 +218,15 @@ export function indexedDBRows(app: string, factory: IDBFactory = indexedDB): Fil
       const row = (await request((await store('readonly')).get(path))) as EntryRow | undefined;
       if (!row) return undefined;
       return {
-        data: row.directory ? null : new Uint8Array(row.data ?? new Uint8Array()),
+        // A Blob row stays a Blob: the browser hands it over without reading it.
+        data: row.directory ? null : row.data !== undefined && isBlob(row.data) ? row.data : new Uint8Array(row.data ?? new Uint8Array()),
         modified: typeof row.modified === 'number' ? row.modified : null,
         created: typeof row.created === 'number' ? row.created : null,
       };
     },
     async put(path, row) {
       const entries = await store('readwrite');
-      const stored: EntryRow = row.data === null ? { path, directory: true } : { path, data: row.data.slice() };
+      const stored: EntryRow = row.data === null ? { path, directory: true } : { path, data: ownData(row.data) };
       if (row.modified !== null) stored.modified = row.modified;
       if (row.created !== null) stored.created = row.created;
       entries.put(stored);
@@ -350,15 +396,24 @@ export class BrowserFiles implements FilesHost {
     this.objectURLs?.revoke(url);
   }
 
-  async read(url: string): Promise<Uint8Array> {
+  /** The row of a file (not a directory) at the URL. */
+  private async fileRow(url: string): Promise<FileRow & { data: FileData }> {
     const { mount, path } = this.locate(url);
     const row = await this.rowAt(mount, path);
     if (!row) throw new FilesFailure('notFound', `no file at ${url}`);
     if (row.data === null) throw new FilesFailure('isDirectory', `${url} is a directory`);
-    return row.data;
+    return row as FileRow & { data: FileData };
+  }
+
+  async read(url: string): Promise<Uint8Array> {
+    return dataBytes((await this.fileRow(url)).data);
+  }
+
+  async readRange(url: string, start: number, end: number): Promise<Uint8Array> {
+    return dataSlice((await this.fileRow(url)).data, start, end);
   }
 
-  async write(url: string, data: Uint8Array): Promise<void> {
+  async write(url: string, data: FileData): Promise<void> {
     const { mount, path } = this.locate(url);
     if (path === '') throw new FilesFailure('isDirectory', `${url} is a directory`);
     await this.requireDirectory(mount, parentOf(path), url);
@@ -413,7 +468,7 @@ export class BrowserFiles implements FilesHost {
     const row = await this.rowAt(mount, path);
     if (!row) return null;
     const directory = row.data === null;
-    return { size: row.data?.byteLength ?? 0, modified: row.modified, created: row.created, directory, type: directory ? '' : mediaType(path) };
+    return { size: row.data === null ? 0 : dataSize(row.data), modified: row.modified, created: row.created, directory, type: directory ? '' : mediaType(path) };
   }
 
   /** Every row at or below `path`, by path. */
@@ -464,10 +519,10 @@ export class BrowserFiles implements FilesHost {
     const key = `${mount.url}/${path}`;
     const known = this.loaded.get(key);
     if (known !== undefined) return known;
-    const data = await this.read(url);
+    const { data } = await this.fileRow(url);
     const type = mediaType(path);
-    if (!this.objectURLs) return `data:${type};base64,${base64Of(data)}`;
-    const made = this.objectURLs.create(new Blob([data.slice()], { type }));
+    if (!this.objectURLs) return `data:${type};base64,${base64Of(await dataBytes(data))}`;
+    const made = this.objectURLs.create(isBlob(data) ? data.slice(0, data.size, type) : new Blob([data.slice()], { type }));
     this.loaded.set(key, made);
     return made;
   }