projectkeeper 0.0.0-stage → 1.0.0

package/ui/failures.js

@@ -0,0 +1,82 @@
+// What intake could not take in (CKC-07 AC-10), as the top bar counts it and its list shows it (owner 2026-09-30: "2
+// failed" could not be opened, and it was one file recorded twice). No DOM here: tested with `node --test`
+// (src/ui/failures.test.ts). The server keeps one entry per ref too (src/intake/intake.ts `latestFailures`); this also
+// folds what an older home still holds, and the entries of several scopes.
+//
+// A file over the size intake reads of one file is not a failure (D105; owner: 「超过 2 MB 的上限 这个不要红色的」): it is
+// `Skipped: too large`, listed in Project scope with its size and the limit, and the top bar neither counts it nor
+// shows it in the colour of an error. The server records it apart (`scope.skipped`, src/intake/skipped.ts); a home
+// written before that still holds it among its failures, and it is read as skipped here all the same.
+
+const TOO_LARGE = /^larger than (\d+) bytes$/;
+const tooLargeLimit = (reason) => { const m = TOO_LARGE.exec(String(reason ?? '').trim()); return m ? Number(m[1]) : null; };
+
+/**
+ * One entry per ref across the coverage's scopes: the latest (by `at`; the later listed on a tie), each with the label of
+ * the scope it was recorded under, newest first. Only what really failed: a file too large to read is skipped (`skippedOf`).
+ */
+export function failuresOf(coverage) {
+  const byRef = new Map();
+  for (const s of coverage?.scopes ?? []) {
+    for (const f of s.failed ?? []) {
+      const before = byRef.get(f.ref);
+      if (before && String(before.at) > String(f.at)) continue;
+      byRef.set(f.ref, { ...f, scope: s.label ?? s.id });
+    }
+  }
+  return [...byRef.values()].filter((f) => tooLargeLimit(f.reason) === null).sort((a, b) => String(b.at).localeCompare(String(a.at)));
+}
+
+/**
+ * The files skipped as too large across the coverage's scopes, one entry per file (the latest), newest first: each with
+ * its size when it was skipped (null when an older home did not record it) and the limit, in bytes.
+ */
+export function skippedOf(coverage) {
+  const byRef = new Map();
+  const take = (entry) => {
+    const before = byRef.get(entry.ref);
+    if (before && String(before.at) > String(entry.at)) return;
+    byRef.set(entry.ref, entry);
+  };
+  for (const s of coverage?.scopes ?? []) {
+    for (const k of s.skipped ?? []) take({ ref: k.ref, bytes: k.bytes ?? null, limit: k.limit, at: k.at, scope: s.label ?? s.id });
+    for (const f of s.failed ?? []) {
+      const limit = tooLargeLimit(f.reason);
+      if (limit !== null) take({ ref: f.ref, bytes: null, limit, at: f.at, scope: s.label ?? s.id });
+    }
+  }
+  return [...byRef.values()].sort((a, b) => String(b.at).localeCompare(String(a.at)));
+}
+
+/** A size in words: `2.4 MB (2,400,000 bytes)`; MB as intake counts its limit, a million bytes. */
+export function sizeText(bytes) {
+  const n = Number(bytes);
+  if (bytes === null || bytes === undefined || !Number.isFinite(n)) return 'size not recorded';
+  const mb = n / 1_000_000;
+  return `${Number.isInteger(mb) ? mb : mb.toFixed(1)} MB (${n.toLocaleString('en-US')} bytes)`;
+}
+
+/** One skipped file in words: its size and the limit. */
+export function skippedText(entry) {
+  return `${sizeText(entry.bytes)} · the most intake reads of one file is ${sizeText(entry.limit)}`;
+}
+
+/** The reason in words: a byte limit also in MB, the rest as recorded. */
+export function reasonText(reason) {
+  const m = /^larger than (\d+) bytes$/.exec(String(reason ?? '').trim());
+  if (!m) return String(reason ?? '');
+  const n = Number(m[1]);
+  const mb = n / 1_000_000;
+  return `larger than ${Number.isInteger(mb) ? mb : mb.toFixed(1)} MB (${n.toLocaleString('en-US')} bytes), the most intake reads of one file`;
+}
+
+/** The path shown under a project location it lies in (with forward slashes), else as recorded. */
+export function shortRef(ref, locations = []) {
+  const norm = (p) => String(p).replace(/\\/g, '/').replace(/\/+$/, '');
+  const r = norm(ref);
+  for (const loc of locations) {
+    const l = norm(loc);
+    if (l && r.toLowerCase().startsWith(`${l.toLowerCase()}/`)) return r.slice(l.length + 1);
+  }
+  return String(ref);
+}

package/ui/flyout.js

@@ -0,0 +1,120 @@
+// A floating panel that belongs to one button of a view's control row: the `Filter` expansion and the panel behind the
+// readability mark (Spec §6.3 "控件放在哪", "可读性自检 · 在哪里说"; CKC-09 AC-37). It floats — nothing under it is pushed
+// down — and it lies wholly inside the main view's visible area, which is narrower while the Keeper is docked: where it
+// goes is worked out by the same rule as the details popover (popover-place.js), under its button when there is room.
+// Esc or a press elsewhere closes it and focus goes back to the button; Tab walks its items and stays inside it. One
+// panel is open at a time. What is shown inside comes from the caller.
+import { placePopover } from './popover-place.js';
+
+const FOCUSABLE = 'button:not([disabled]), a[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), summary, [tabindex]:not([tabindex="-1"])';
+
+/**
+ * @param {{ bounds: () => {left:number,top:number,right:number,bottom:number}, avoid?: () => Array<{left:number,top:number,right:number,bottom:number}> }} o
+ *   `bounds` is the main view's visible area; `avoid` names rectangles not to lie on when that can be helped (the pill).
+ */
+export function createFlyout({ bounds, avoid = () => [] }) {
+  const el = document.createElement('section');
+  el.className = 'flyout';
+  el.hidden = true;
+  el.tabIndex = -1;
+  el.setAttribute('role', 'dialog');
+  document.body.append(el);
+
+  /** @type {null | { button: HTMLElement, render: (api: object) => Array<Node|null>, className: string }} */
+  let current = null;
+  let frame = 0;
+  let watch = null;
+  const focusables = () => [...el.querySelectorAll(FOCUSABLE)].filter((n) => n.getClientRects().length > 0);
+
+  function place() {
+    if (!current) return;
+    if (!current.button.isConnected) { close(); return; }   // the row it belonged to was rebuilt
+    const scrollTop = el.scrollTop;
+    el.style.maxHeight = '';
+    el.style.width = '';
+    const size = { width: el.offsetWidth, height: el.offsetHeight };
+    const r = current.button.getBoundingClientRect();
+    const p = placePopover({ anchor: { left: r.left, top: r.top, right: r.right, bottom: r.bottom }, size, bounds: bounds(), gap: 6, prefer: ['bottom', 'top', 'right', 'left'], avoid: avoid() });
+    el.style.left = `${p.left}px`;
+    el.style.top = `${p.top}px`;
+    el.style.width = p.width < size.width ? `${p.width}px` : '';
+    el.style.maxHeight = p.height < size.height ? `${p.height}px` : '';
+    el.dataset.side = p.side;
+    el.scrollTop = scrollTop;
+  }
+  function reposition() {
+    if (!current || frame) return;
+    frame = requestAnimationFrame(() => { frame = 0; place(); });
+  }
+  function draw({ focus = false } = {}) {
+    if (!current) return;
+    const at = el.contains(document.activeElement) ? focusables().indexOf(document.activeElement) : -1;
+    const nodes = current.render(api).flat(Infinity).filter((n) => n !== null && n !== undefined && n !== false);
+    el.replaceChildren(...nodes);
+    el.hidden = false;
+    place();
+    if (focus) (focusables()[0] ?? el).focus({ preventScroll: true });
+    else if (at >= 0) (focusables()[at] ?? el).focus({ preventScroll: true });
+  }
+  function close({ focus = false } = {}) {
+    if (!current) return;
+    const was = current;
+    current = null;
+    watch?.disconnect();
+    watch = null;
+    el.hidden = true;
+    el.replaceChildren();
+    was.button.setAttribute('aria-expanded', 'false');
+    if (focus && was.button.isConnected) was.button.focus({ preventScroll: true });
+  }
+
+  const api = {
+    el,
+    isOpen: (button) => Boolean(current) && (button === undefined || current.button === button),
+    /** Open the panel of a button; pressed again while it is open, the button puts it away. */
+    toggle({ button, label, render, className = '' }) {
+      if (current?.button === button) { close({ focus: true }); return false; }
+      close();
+      current = { button, render, className };
+      el.className = `flyout ${className}`.trim();
+      el.setAttribute('aria-label', label);
+      button.setAttribute('aria-expanded', 'true');
+      // The main view changes width when the Keeper docks or is resized: the panel follows it.
+      const main = document.getElementById('main');
+      if (main && 'ResizeObserver' in window) { watch = new ResizeObserver(() => reposition()); watch.observe(main); }
+      draw({ focus: true });
+      return true;
+    },
+    /** What the panel shows changed (a filter was set, the check ran again): drawn again in place, focus where it was. */
+    refresh(button) { if (current && (button === undefined || current.button === button)) draw(); },
+    close,
+    reposition,
+  };
+
+  // One Escape closes one thing: a dialog on top takes it first; otherwise this panel, and nothing else hears it.
+  document.addEventListener('keydown', (e) => {
+    if (!current) return;
+    if (e.key === 'Escape') {
+      if (document.querySelector('dialog[open]')) return;
+      e.preventDefault();
+      e.stopPropagation();
+      close({ focus: true });
+      return;
+    }
+    if (e.key !== 'Tab' || !el.contains(document.activeElement)) return;
+    const items = focusables();
+    if (!items.length) { e.preventDefault(); return; }
+    const at = items.indexOf(document.activeElement);
+    if (e.shiftKey && at <= 0) { e.preventDefault(); items[items.length - 1].focus(); }
+    else if (!e.shiftKey && at === items.length - 1) { e.preventDefault(); items[0].focus(); }
+  }, true);
+  // A press elsewhere closes it. A press on its own button is that button's business (it toggles).
+  document.addEventListener('pointerdown', (e) => {
+    if (!current || !(e.target instanceof Element)) return;
+    if (el.contains(e.target) || current.button.contains(e.target) || e.target.closest('dialog, #toast')) return;
+    close();
+  }, true);
+  addEventListener('resize', () => reposition());
+
+  return api;
+}

package/ui/folder-chooser.js

@@ -0,0 +1,264 @@
+// The folder chooser: where a location is typed (Add project's `Locations`, a scope item's `Path`), `Browse…` opens this
+// panel inside the dialog and the owner walks to the folder instead of typing its path (owner 2026-10-06:
+// 「add这个locations帮我换成可以有对话框自己选一下」). The field it stands under stays as it was: typing and pasting a path
+// work as before, and what is chosen here is written into that field as text.
+//
+// It is the program's own panel, not the system's dialog and not the browser's directory picker: a page cannot learn a
+// folder's whole path from the browser, and a dialog opened by a local server comes up behind the browser. The folders
+// come from `GET /api/folders` (src/server/folders-api.ts), which answers the workbench's own pages only.
+//
+// Nothing here knows the system it runs on: the separator, the quick starts (the home directory; the drives on Windows,
+// `/` elsewhere) and every path are the server's. The first half of this file is what the panel says and decides, with
+// no DOM in it (src/ui/folder-chooser.test.ts); the second half draws it with the page's own `h` and `api`.
+
+/** The locations typed in a field, one a line: trimmed, empty lines dropped. */
+export const locationLines = (text) => String(text ?? '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+
+/** `text` with `path` as a new last line; unchanged when a line already says exactly that. What was typed is kept as typed. */
+export function withLocation(text, path) {
+  const now = String(text ?? '');
+  if (locationLines(now).includes(path)) return now;
+  const kept = now.replace(/\s+$/, '');
+  return kept ? `${kept}\n${path}` : path;
+}
+
+/** The request for one directory. `added` are the paths the field already holds (at most 50 are sent). */
+export function foldersUrl({ path = '', hidden = false, added = [] } = {}) {
+  const q = new URLSearchParams();
+  if (path) q.set('path', path);
+  if (hidden) q.set('hidden', '1');
+  for (const a of added.slice(0, 50)) q.append('added', a);
+  const s = q.toString();
+  return s ? `/api/folders?${s}` : '/api/folders';
+}
+
+/** The marks beside a folder's name: `{ text, tone, title }`, in the order shown. */
+export function folderMarks(folder, addedWord = 'added') {
+  const marks = [];
+  if (folder.repository) marks.push({ text: 'git', tone: 'blue', title: 'A git repository or a worktree of one' });
+  if (folder.link) marks.push({ text: 'link', tone: '', title: 'A link: it opens the folder it leads to' });
+  if (folder.added) marks.push({ text: addedWord, tone: 'green', title: `Already ${addedWord}` });
+  return marks;
+}
+
+/** The line under the list: how many folders are not shown, and how to reach one. Empty when all are shown. */
+export function moreLine(listing) {
+  if (!listing || !listing.more) return '';
+  return `${listing.more.toLocaleString('en')} more ${listing.more === 1 ? 'folder is' : 'folders are'} not shown. Type a path above to go to one.`;
+}
+
+/** What the list says when it has no row. */
+export function emptyLine(listing, showHidden) {
+  if (listing.error) return listing.error;
+  if (listing.hidden > 0 && !showHidden) return `No folders here, apart from ${listing.hidden} hidden.`;
+  return 'No folders here.';
+}
+
+/** The label of the hidden-folders switch. */
+export const hiddenLabel = (listing) => (listing && listing.hidden > 0 ? `Show hidden (${listing.hidden})` : 'Show hidden');
+
+/**
+ * What a key does in the panel, or null when it is left to the browser.
+ *   Escape                  → 'close'   (the panel, never the dialog it is in)
+ *   Alt+ArrowUp             → 'up'      (anywhere in the panel)
+ *   Backspace               → 'up'      (not while typing: in the path line it deletes a character)
+ *   ArrowDown / ArrowUp     → 'next' / 'previous' row (from the path line, ArrowDown enters the list)
+ *   Home / End              → 'first' / 'last' row (in the list)
+ * Enter needs no entry: on a row it is the button's own click (go in); in the path line it goes to the typed path.
+ * @param {{ key: string, altKey?: boolean, ctrlKey?: boolean, metaKey?: boolean }} e
+ * @param {'row' | 'path' | 'other'} where what has the focus
+ */
+export function chooserKey(e, where) {
+  if (e.ctrlKey || e.metaKey) return null;
+  if (e.key === 'Escape') return 'close';
+  if (e.key === 'ArrowUp' && e.altKey) return 'up';
+  if (e.altKey) return null;
+  if (e.key === 'Backspace') return where === 'path' ? null : 'up';
+  if (e.key === 'ArrowDown') return where === 'other' ? null : 'next';
+  if (e.key === 'ArrowUp') return where === 'row' ? 'previous' : null;
+  if (where === 'row' && e.key === 'Home') return 'first';
+  if (where === 'row' && e.key === 'End') return 'last';
+  return null;
+}
+
+// ───────────────────────── the panel ─────────────────────────
+
+const FOLDER_ICON = "<svg viewBox='0 0 20 20' width='15' height='15' fill='none' stroke='currentColor' stroke-width='1.5' stroke-linejoin='round' aria-hidden='true'><path d='M2.5 5.5a1 1 0 0 1 1-1h4l1.6 1.8h7.4a1 1 0 0 1 1 1v7.7a1 1 0 0 1-1 1h-13a1 1 0 0 1-1-1z'/></svg>";
+
+/** Where the last chooser was left, so the next one opens there: this page only, never stored. */
+let lastPlace = '';
+
+/**
+ * @param {{
+ *   h: Function, api: (path: string) => Promise<any>,
+ *   added: () => string[],          the paths the field holds now
+ *   onAdd: (path: string) => void,  write the chosen folder into the field
+ *   start?: () => string,           where to open; empty: where the last chooser was left, else the home directory
+ *   addLabel?: string,              the button that takes the folder shown ('Add this folder')
+ *   addedWord?: string,             the mark of a folder the field already holds ('added')
+ *   single?: boolean,               one folder is wanted: choosing it closes the panel
+ *   chooseAdded?: boolean,          a folder the field's owner already holds can be chosen again (it is only marked)
+ * }} o
+ * @returns {{ button: HTMLElement, panel: HTMLElement, open: () => Promise<void>, close: () => void, isOpen: () => boolean }}
+ */
+export function createFolderChooser(o) {
+  const { h, api } = o;
+  const addLabel = o.addLabel ?? 'Add this folder';
+  const addedWord = o.addedWord ?? 'added';
+  let listing = null;       // the last answer shown
+  let showHidden = false;
+  let asked = 0;            // the newest request; an older answer that arrives late is dropped
+  let host = null;          // the dialog the panel is in, while it listens there
+  let byKeys = false;       // the last thing done in the panel was a key, not the mouse: the folder in focus is shown as such
+
+  const path = h('input', { class: 'input mono fc-path', 'aria-label': 'Folder path', autocomplete: 'off', spellcheck: 'false', title: 'The folder shown. Type or paste a path and press Enter to go there.' });
+  const up = h('button', { class: 'btn small fc-up', type: 'button', title: 'Up one level (Alt+↑, or Backspace in the list)', onClick: () => goUp() }, '↑ Up');
+  const go = h('button', { class: 'btn small', type: 'button', title: 'Go to the path typed', onClick: () => load(path.value, { focus: 'list' }) }, 'Go');
+  const starts = h('div', { class: 'fc-starts' });
+  const hiddenBox = h('input', { type: 'checkbox', onChange: () => { showHidden = hiddenBox.checked; void load(listing?.path ?? path.value, { focus: 'keep' }); } });
+  const hiddenText = h('span', {}, 'Show hidden');
+  const list = h('div', { class: 'fc-list', role: 'group', 'aria-label': 'Folders' });
+  const more = h('small', { class: 'fc-more faint', 'aria-live': 'polite' });
+  const here = h('span', { class: 'fc-here muted' });
+  const add = h('button', { class: 'btn', type: 'button', onClick: () => choose() }, addLabel);
+  const done = h('button', { class: 'btn', type: 'button', title: 'Close the folder list (Esc)', onClick: () => close() }, o.single ? 'Cancel' : 'Done');
+  const panel = h('div', { class: 'fc', hidden: true },
+    h('div', { class: 'fc-bar' }, up, path, go),
+    h('div', { class: 'fc-bar fc-sub' }, starts, h('label', { class: 'fc-hidden' }, hiddenBox, hiddenText)),
+    list, more,
+    h('div', { class: 'fc-foot' }, here, add, done));
+  const button = h('button', { class: 'btn small fc-browse', type: 'button', 'aria-expanded': 'false', title: 'Choose the folder from a list instead of typing its path', onClick: () => (isOpen() ? close() : void open()) }, 'Browse…');
+
+  panel.addEventListener('pointerdown', () => { byKeys = false; }, true);
+  const rows = () => [...list.querySelectorAll('.fc-row')];
+  const isOpen = () => !panel.hidden;
+
+  function say(text) {
+    list.replaceChildren(h('div', { class: 'fc-empty muted' }, text));
+  }
+
+  function draw(focus) {
+    const l = listing;
+    path.value = l.path;
+    up.disabled = l.parent === null;
+    starts.replaceChildren(...l.starts.map((s) => h('button', { class: 'btn small', type: 'button', title: s.path, onClick: () => load(s.path, { focus: 'list' }) }, s.label)));
+    hiddenText.textContent = hiddenLabel(l);
+    if (l.folders.length === 0) say(emptyLine(l, showHidden));
+    else {
+      list.replaceChildren(...l.folders.map((f) => h('button', { class: `fc-row${f.hidden ? ' dim' : ''}`, type: 'button', dataset: { path: f.path }, title: f.path, onClick: () => load(f.path, { focus: 'list' }) },
+        h('span', { class: 'fc-icon', html: FOLDER_ICON }),
+        h('span', { class: 'fc-name' }, f.name),
+        ...folderMarks(f, addedWord).map((m) => h('span', { class: `tag ${m.tone}`.trim(), title: m.title }, m.text)))));
+    }
+    list.scrollTop = 0;
+    more.textContent = moreLine(l);
+    const marks = folderMarks({ repository: l.repository, link: false, added: l.added }, addedWord);
+    here.replaceChildren(h('span', { class: 'fc-here-name', title: l.path }, l.name), ...marks.map((m) => h('span', { class: `tag ${m.tone}`.trim(), title: m.title }, m.text)));
+    const taken = l.added && !o.chooseAdded;
+    add.disabled = Boolean(l.error) || taken;
+    add.title = l.error ? 'This folder cannot be chosen' : taken ? `This folder is already ${addedWord}` : l.path;
+    if (focus === 'keep') return;
+    // Coming up, the folder that was left is the one in focus; going in, the first; with no row, the way on.
+    const from = typeof focus === 'object' && focus ? rows().find((r) => r.dataset.path === focus.from) : null;
+    const target = from ?? rows()[0] ?? (add.disabled ? (up.disabled ? path : up) : add);
+    // A key held with Alt does not make the browser draw the focus by itself, so it is asked to.
+    target.focus({ preventScroll: true, focusVisible: byKeys });
+    target.scrollIntoView?.({ block: 'nearest' });
+  }
+
+  async function load(to, { focus = 'list' } = {}) {
+    const mine = ++asked;
+    const slow = setTimeout(() => { if (mine === asked) say('Reading…'); }, 250);
+    try {
+      const answer = await api(foldersUrl({ path: String(to ?? '').trim(), hidden: showHidden, added: o.added() }));
+      if (mine !== asked) return;
+      listing = answer;
+      lastPlace = answer.error ? lastPlace : answer.path;
+      draw(focus);
+    } catch (e) {
+      if (mine !== asked) return;
+      // Not a whole path, or the workbench did not answer: said where the list is; the path line keeps what was typed.
+      say(e.message);
+      more.textContent = '';
+    } finally { clearTimeout(slow); }
+  }
+
+  function goUp() {
+    if (!listing || listing.parent === null) return;
+    void load(listing.parent, { focus: { from: listing.path } });
+  }
+
+  function choose() {
+    if (!listing || listing.error || (listing.added && !o.chooseAdded)) return;
+    o.onAdd(listing.path);
+    if (o.single) { close(); return; }
+    // Still open: a project often has more than one location. The folder now shows as added, here and in the list above it.
+    void load(listing.path, { focus: 'keep' });
+    done.focus({ preventScroll: true });
+  }
+
+  function onKey(e) {
+    if (!panel.isConnected) { detach(); return; }   // the dialog went on to other content with the panel open
+    if (!isOpen() || e.isComposing) return;   // a key that belongs to an input method composing a name is not the panel's
+    byKeys = true;
+    const inPanel = panel.contains(e.target);
+    const where = e.target === path ? 'path' : inPanel && e.target.classList?.contains('fc-row') ? 'row' : 'other';
+    // Escape closes the panel wherever the focus is in the dialog; every other key is the panel's only inside it.
+    if (e.key === 'Enter' && where === 'path') { e.preventDefault(); void load(path.value, { focus: 'list' }); return; }
+    const action = chooserKey(e, where);
+    if (!action || (action !== 'close' && !inPanel)) return;
+    e.preventDefault();
+    e.stopPropagation();
+    if (action === 'close') { close(); return; }
+    if (action === 'up') { goUp(); return; }
+    const all = rows();
+    if (all.length === 0) return;
+    const at = all.indexOf(e.target);
+    const next = action === 'first' ? 0 : action === 'last' ? all.length - 1 : action === 'next' ? Math.min(all.length - 1, at + 1) : Math.max(0, at - 1);
+    all[next].focus({ preventScroll: true, focusVisible: true });
+    all[next].scrollIntoView({ block: 'nearest' });
+  }
+  /** The dialog's own answer to Escape (it would close): the panel closes instead. */
+  function onCancel(e) {
+    if (!panel.isConnected) { detach(); return; }
+    if (!isOpen()) return;
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    close();
+  }
+  function detach() {
+    host?.removeEventListener('keydown', onKey, true);
+    host?.removeEventListener('cancel', onCancel, true);
+    host?.removeEventListener('close', detach);
+    host = null;
+  }
+
+  async function open() {
+    if (isOpen()) return;
+    panel.hidden = false;
+    button.setAttribute('aria-expanded', 'true');
+    button.classList.add('active');
+    host = panel.closest('dialog') ?? panel.ownerDocument;
+    host.addEventListener('keydown', onKey, true);
+    host.addEventListener('cancel', onCancel, true);
+    host.addEventListener('close', detach);   // the dialog closed with the panel open: nothing of it stays behind
+    say('Reading…');
+    listing = null;
+    const first = o.start?.() || lastPlace || '';
+    await load(first, { focus: 'list' });
+    // What the field holds may be no whole path (a name half typed): the panel then opens at the home directory.
+    if (listing === null && first && isOpen()) await load('', { focus: 'list' });
+  }
+
+  function close() {
+    if (!isOpen()) return;
+    asked++;
+    panel.hidden = true;
+    button.setAttribute('aria-expanded', 'false');
+    button.classList.remove('active');
+    detach();
+    if (button.isConnected) button.focus({ preventScroll: true });
+  }
+
+  return { button, panel, open, close, isOpen };
+}