@heycys/gallery 0.0.0-stage → 0.1.0

package/browser/editor/page/overlays.mjs

@@ -0,0 +1,205 @@
+// What the editor draws over the page (docs/editor.md, "Overlays"): a selected block's fill, the
+// handle and a section's bar, the dashed frame of the text being edited, a drag's line, tint and
+// the blocks' faded copy, a box selection, a resize's lines. Each such node is registered with what it stands for
+// (own: a block, or the gesture it belongs to) and a test of whether it still does (alive). The
+// editor's frames audit them against that: one standing for nothing (a block no longer selected or
+// on the page, a gesture over) is a bug, said once with what led to it, and the node goes, so no
+// overlay is ever left behind on the screen. window.__galleryOverlays() describes them all, with
+// their owners, where each is against where it should be, the frames and the recent events: what
+// to look at (and copy) when something drawn looks wrong.
+
+// own() marks each overlay node with this attribute: the audit and the snapshot go through the marked
+// nodes on the page, so whatever is registered is audited, whoever draws it. The audit keeps the
+// marked nodes it found (and those marked since) and goes through them: looking them up in the whole
+// page after every frame took 0.2ms a frame on a long report. It looks through the page again
+// whenever a node it does not hold may have come onto it (put in by anyone: a copy of an overlay, one
+// taken off and put back), which an observer of what is added says (`arrivals`).
+const MARK = "data-ge-overlay";
+
+const owners = new WeakMap(); // node -> { kind, owner, alive, expected }
+const owned = new Set(); // the marked nodes the audit goes through
+let unknown = true; // a node `owned` does not hold may be on the page: the next audit looks through it
+
+// Watched from an audit to the first node added that `owned` does not hold (or that holds a marked
+// node), then not until the next audit: nothing to pay for while the page is built or typed in. Made
+// at the first audit (this module is read without a page too: the unit tests).
+let arrivals = null;
+function arrived(records) {
+  for (const record of records) {
+    for (const node of record.addedNodes) {
+      if (node.nodeType === 1 && (!owned.has(node) || node.querySelector(`[${MARK}]`))) return true;
+    }
+  }
+  return false;
+}
+function stopWatching() {
+  unknown = true;
+  arrivals?.disconnect();
+}
+const settlers = new Set(); // what each part drops at once after a structural change
+const providers = new Map(); // name -> () => state, for the snapshot
+const events = []; // the last things that changed what is drawn: { t, type, detail }
+const said = new Map(); // scope -> { message, time }: errors said, not said again within 5s
+const errors = []; // the last errors said: { t, scope, message }
+let lastStray = "";
+
+/**
+ * Register `node` as an overlay of `kind` standing for `owner` (a block, or null for a gesture);
+ * alive(): whether it still stands for something (the block selected and on the page, the gesture
+ * under way); expected(): where it should be now (client coordinates), when that can be told.
+ */
+export function own(node, kind, { owner = null, alive = () => true, expected = null } = {}) {
+  owners.set(node, { kind, owner, alive, expected });
+  if (node.getAttribute(MARK) !== kind) node.setAttribute(MARK, kind); // the block tools own theirs again on every frame they draw
+  owned.add(node);
+  return node;
+}
+
+/**
+ * settle(): after a structural change (history.mjs: a change, undo, redo), at once, not on a later
+ * frame, each part drops what stands for something no longer on the page (the selection its gone
+ * blocks, the handle the block it stood beside, the frame the text it framed). onSettle(fn): a part's.
+ */
+export function onSettle(fn) {
+  settlers.add(fn);
+}
+
+export function settle() {
+  for (const fn of settlers) {
+    try {
+      fn();
+    } catch (error) {
+      report("settling after a change", error);
+    }
+  }
+}
+
+/** Something that changes what is drawn happened (selection, history, a gesture). */
+export function note(type, detail = "") {
+  events.push({ t: Math.round(performance.now()), type, detail: String(detail).slice(0, 160) });
+  if (events.length > 30) events.shift();
+}
+
+/** A part of the editor's state for the snapshot (the frames, the block tools). */
+export function provide(name, state) {
+  providers.set(name, state);
+}
+
+/**
+ * An error in drawing or in a gesture: said on the console (the same one at most every 5 seconds
+ * per scope, never on every frame) and kept for the snapshot.
+ */
+export function report(scope, error) {
+  const message = error?.message ?? String(error);
+  const now = performance.now();
+  const last = said.get(scope);
+  if (last && last.message === message && now - last.time < 5000) return;
+  said.set(scope, { message, time: now });
+  errors.push({ t: Math.round(now), scope, message });
+  if (errors.length > 10) errors.shift();
+  note("error", `${scope}: ${message}`);
+  console.error(`[gallery] ${scope} failed:`, error);
+}
+
+// A short description of a block or node: tag, id, the start of its text.
+export function describe(node) {
+  if (!node) return null;
+  if (!node.localName) return String(node);
+  const id = node.getAttribute?.("data-block-id");
+  const text = (node.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 24);
+  return `${node.localName}${id ? `#${id}` : ""}${text ? ` "${text}"` : ""}`;
+}
+
+const rounded = (rect) => rect && { left: Math.round(rect.left), top: Math.round(rect.top), right: Math.round(rect.right), bottom: Math.round(rect.bottom) };
+
+// How far a node's rectangle is from where it should be (the largest difference of an edge), or null.
+function offBy(rect, expected) {
+  if (!rect || !expected) return null;
+  return Math.max(...["left", "top", "right", "bottom"].map((side) => Math.abs(rect[side] - expected[side])));
+}
+
+/** Everything drawn and what it stands for, the frames and the recent events (plain data). */
+export function snapshot() {
+  const overlays = [];
+  for (const node of document.querySelectorAll(`[${MARK}]`)) {
+    const entry = owners.get(node);
+    const rect = node.getBoundingClientRect();
+    const shown = !node.hidden && rect.width > 0 && rect.height > 0;
+    let expected = null;
+    try {
+      expected = entry?.expected?.() ?? null;
+    } catch {}
+    let alive = null;
+    try {
+      alive = entry ? Boolean(entry.alive()) : null;
+    } catch {}
+    overlays.push({
+      class: node.className,
+      kind: entry?.kind ?? null,
+      shown,
+      rect: rounded(rect),
+      owner: describe(entry?.owner),
+      ownerOnPage: entry?.owner ? Boolean(entry.owner.isConnected) : null,
+      alive,
+      expected: rounded(expected),
+      offBy: shown ? offBy(rect, expected) : null,
+    });
+  }
+  const state = {};
+  for (const [name, provider] of providers) {
+    try {
+      state[name] = provider();
+    } catch (error) {
+      state[name] = `unavailable: ${error.message}`;
+    }
+  }
+  return { time: Math.round(performance.now()), scroll: { x: Math.round(scrollX), y: Math.round(scrollY) }, overlays, ...state, errors: [...errors], events: [...events] };
+}
+
+/**
+ * The overlays standing for nothing, removed (a bug: said once, with the snapshot). Returns how
+ * many there were.
+ */
+export function audit() {
+  if (!unknown && arrived(arrivals.takeRecords())) stopWatching();
+  if (unknown) {
+    owned.clear();
+    for (const node of document.querySelectorAll(`[${MARK}]`)) owned.add(node);
+    unknown = false;
+    arrivals ??= new MutationObserver((records) => {
+      if (arrived(records)) stopWatching();
+    });
+    arrivals.observe(document.documentElement, { childList: true, subtree: true });
+  }
+  const strays = [...owned].filter((node) => {
+    // Off the page (what puts it back is an arrival), or no longer marked (annotate/ unmarks its
+    // markers as they fade out, standing for nothing): not the audit's.
+    if (!node.isConnected || !node.hasAttribute(MARK)) {
+      owned.delete(node);
+      return false;
+    }
+    const entry = owners.get(node);
+    try {
+      return !entry || !entry.alive();
+    } catch {
+      return true;
+    }
+  });
+  if (strays.length === 0) {
+    lastStray = "";
+    return 0;
+  }
+  const key = strays.map((node) => `${node.className}:${describe(owners.get(node)?.owner)}`).join(" | ");
+  if (key !== lastStray) {
+    lastStray = key;
+    note("stray", key);
+    console.error("[gallery] overlay standing for nothing (removed):", key, snapshot());
+  }
+  strays.forEach((node) => {
+    node.remove();
+    owned.delete(node);
+  });
+  return strays.length;
+}
+
+globalThis.__galleryOverlays = snapshot;

package/browser/editor/page/own.mjs

@@ -0,0 +1,28 @@
+import { isInkClass } from "./marks.mjs";
+import { TAB } from "../components/paragraph/index.mjs";
+
+// Inline elements of the report's own (docs/editor.md, "In-place text editing"): a phrasing element
+// the editor has no format for (a span with a class, style or attribute of the report's own: a
+// number badge in a heading, a citation in a cell; a cite, a small, an abbr…), and a format bar's tag
+// that carries attributes of its own and holds no words (a drawn arrow, <i class="arr-r"></i>). In a
+// text block it is an atom, as an inline formula is: shown and written back as the file has it, its
+// words not edited, the words around it editable. Judged from an element's tag, its attributes as the
+// file writes them and whether it holds words, so that the scanner's parse5 nodes (source/blocks.mjs)
+// and the page's elements (core.mjs) are judged alike. Not the editor's own: a text color or
+// highlight (the kit's classes alone), small text's end part, a formula, a link.
+
+const PHRASING = new Set([
+  "span", "abbr", "cite", "dfn", "small", "mark", "q", "time", "data", "bdi", "bdo", "kbd", "samp", "var",
+  "ins", "del", "strike", "font", "big", "tt", "nobr", "acronym",
+]);
+const FORMATS = new Set(["strong", "em", "b", "i", "u", "s", "code", "sup", "sub"]);
+
+/** `attributes`: [{ name, value }] as the file writes them; `words`: whether it holds any. */
+export function ownInline(tag, attributes, words) {
+  if (FORMATS.has(tag)) return attributes.length > 0 && !words;
+  if (!PHRASING.has(tag)) return false;
+  if (tag !== "span") return true;
+  const classes = attributes.length === 1 && attributes[0].name === "class" ? attributes[0].value.trim().split(/\s+/).filter(Boolean) : null;
+  if (classes?.length > 0 && (classes.every(isInkClass) || classes.join(" ") === TAB)) return false;
+  return !attributes.some(({ name, value }) => name === "class" && value.split(/\s+/).includes("doc-math-inline"));
+}

package/browser/editor/page/pads.mjs

@@ -0,0 +1,71 @@
+import { select } from "./caret.mjs";
+import { holdsNothing } from "./marks.mjs";
+import { ZWSP } from "../../shared/inline-spacing.mjs";
+
+// Zero-width pads: a text node holding nothing but a zero-width space where the browser would not
+// keep the caret, so that what is typed there lands on the side the reader chose: after a mark a
+// Markdown shortcut made (typed text would go into it, markdown/), outside after inline code or
+// inside at its start (typing/code-edges.mjs). Text typed into a pad stays there and the space
+// goes (settlePads); a pad the caret left empty goes. A text node holding nothing but the space is
+// never saved (core.mjs serializeNode).
+
+const pads = new Set();
+
+/** Whether `node` is a text node holding nothing but the zero-width space. */
+export const isPad = (node) => node?.nodeType === 3 && node.data === ZWSP;
+
+/**
+ * The caret in a pad `where` `node` is ("after" or "before" it, or "start": inside it, first),
+ * after its space; one already there is used again.
+ */
+export function padCaret(node, where) {
+  let pad = where === "start" ? node.firstChild : where === "after" ? node.nextSibling : node.previousSibling;
+  if (!isPad(pad)) {
+    pad = node.ownerDocument.createTextNode(ZWSP);
+    if (where === "start") node.prepend(pad);
+    else if (where === "after") node.after(pad);
+    else node.before(pad);
+  }
+  pads.add(pad);
+  const caret = node.ownerDocument.createRange();
+  caret.setStart(pad, 1);
+  caret.collapse(true);
+  select(caret);
+  return pad;
+}
+
+/**
+ * Text arrived in a pad: the space goes, the caret staying after the text. `left` (the selection
+ * moved): a pad still empty goes unless the caret is in it.
+ */
+export function settlePads(left = false) {
+  const selection = getSelection();
+  for (const pad of [...pads]) {
+    if (!pad.isConnected) {
+      pads.delete(pad);
+      continue;
+    }
+    const inside = selection.rangeCount > 0 && selection.anchorNode === pad;
+    if (pad.data === ZWSP) {
+      if (left && !inside) {
+        pads.delete(pad);
+        const parent = pad.parentElement;
+        pad.remove();
+        // Inline code that held nothing but the pad (its text deleted, the caret gone) goes too: it
+        // would stay drawn as an empty box.
+        if (parent?.tagName === "CODE" && holdsNothing(parent)) parent.remove();
+      }
+      continue;
+    }
+    pads.delete(pad);
+    const at = pad.data.indexOf(ZWSP);
+    if (at < 0) continue;
+    const offset = inside ? selection.anchorOffset : null;
+    pad.deleteData(at, 1);
+    if (offset !== null) {
+      const caret = pad.ownerDocument.createRange();
+      caret.setStart(pad, Math.max(0, offset - (offset > at ? 1 : 0)));
+      select(caret);
+    }
+  }
+}

package/browser/editor/page/page-objects.mjs

@@ -0,0 +1,105 @@
+import { HOST_COMPONENT, TYPE_COMPONENT, TYPE_INFO, UNIT_COMPONENT, canHaveChildren, ownerOf, textFilters } from "../components/registry.mjs";
+
+// The components' page objects (components/pages.mjs) for the engines that are handed no `ctx` of
+// their own: the editor gives them here once it has made them, and what a type needs of the page is
+// asked of its component.
+let pages = {};
+
+/** Hand the engines the page objects. */
+export function connectPages(given) {
+  pages = given;
+}
+
+/** Whether what happens on `node` is a component's own, the editor letting go of it (`keepsKeys`: its keys, the clipboard, a press that would draw a selection). `event`: the key, where one is asked about. */
+export const keptByComponent = (node, event = null) => pageObjects().some((page) => page.keepsKeys?.(node, event));
+
+/** The page object of the component a block type is of, if it has one. */
+export const pageOfType = (type) => pages[TYPE_COMPONENT[type]];
+
+/**
+ * A key of a menu of blocks (notion-lite's menuEntry): a type, or "type:variant", another entry of the
+ * type a page object says (`menuVariants`: { label, icon, words, preview?, sample?, create(what) },
+ * `sample` where the words a new one holds are there to be typed over): { type, variant (null when it
+ * names none, or none there is), named }.
+ */
+export function menuEntry(key) {
+  const [type, ...rest] = String(key).split(":");
+  const name = rest.join(":");
+  return { type, variant: name ? pageOfType(type)?.menuVariants?.()[name] ?? null : null, named: Boolean(name) };
+}
+
+/** The row of a key of a menu of blocks: its type's, or its variant's; null for neither. */
+export const menuRow = (key) => TYPE_INFO[key] ?? menuEntry(key).variant;
+
+/** The keys of every variant there is now. */
+export const variantKeys = () => Object.keys(TYPE_COMPONENT).flatMap((type) => Object.keys(pageOfType(type)?.menuVariants?.() ?? {}).map((name) => `${type}:${name}`));
+
+/** The page objects, in the order they are made. */
+export const pageObjects = () => Object.values(pages);
+
+/** The page object with an editor open over the page (`panel`), if any. */
+export const panelOpen = () => pageObjects().find((page) => page.panel) ?? null;
+
+/** The text field outside the page's text blocks being edited (`field`: a tab's name), or null. */
+export const fieldOpen = () => pageObjects().map((page) => page.field).find(Boolean) ?? null;
+
+/** What the block tools do with rows of columns (`columnOps`, notion-lite's), of whichever page object says, or null. */
+export const columnOps = () => pageObjects().find((page) => page.columnOps)?.columnOps ?? null;
+
+/** What the block tools do with sections (`sectionOps`), of whichever page object says, or null. */
+export const sectionOps = () => pageObjects().find((page) => page.sectionOps)?.sectionOps ?? null;
+
+/** What the gaps between blocks in a row resize (`rowOps`), of whichever page object says, or null. */
+export const rowOps = () => pageObjects().find((page) => page.rowOps)?.rowOps ?? null;
+
+// With no component that says `modalOps`, nothing stands over the page.
+const NO_MODALS = { open: () => [], listen() {}, closeTop: () => false, show: () => null, kept: () => [], reopen() {} };
+
+/** What stands open over the page as a modal (`modalOps`), of whichever page object says. */
+export const modalOps = () => pageObjects().find((page) => page.modalOps)?.modalOps ?? NO_MODALS;
+
+/** The page's own icon, as the page shows it (`pageIcon`), or null. */
+export const pageIcon = () => pageObjects().map((page) => page.pageIcon?.()).find(Boolean) ?? null;
+
+/** The page object of the component that defines a kind of text block. */
+export const pageOfHost = (kind) => pages[HOST_COMPONENT[kind]];
+
+/** The page object of the component a kind of unit is of, if it has one. */
+export const pageOfKind = (kind) => pages[UNIT_COMPONENT[kind]];
+
+/** The page object of the component a block is of, by the kind of unit it is (`menuItems`, `menu`), if it has one. */
+export const pageOfUnit = (unit) => pageOfKind(unit.getAttribute("data-ge-unit-kind"));
+
+/** The row of the block menu a page object has for a block of another component (`rowBeside`), the first that has one, or null. */
+export const rowBeside = (target) => pageObjects().map((page) => page.rowBeside?.(target)).find(Boolean) ?? null;
+
+/** The page object of the component a text block is of, or none (`keys`). */
+export const pageOf = (host) => pages[ownerOf(host)];
+
+/**
+ * What stands around a text block, nearest first, each once and its own component none of them: the
+ * block before it where that says `canHaveChildren`, then what it stands in, from where it stands out.
+ */
+export function pagesAround(host) {
+  const before = host.previousElementSibling;
+  const around = before && canHaveChildren(before) ? [before] : [];
+  for (let node = host.parentElement; node; node = node.parentElement) around.push(node);
+  const own = pageOf(host);
+  return [...new Set(around.map(pageOf))].filter((page) => page && page !== own);
+}
+
+/** The page object of what a press or a click came down on: of the component of the nearest element around it that is of one. */
+export function pageAt(target) {
+  for (let node = target; node?.nodeType === 1; node = node.parentElement) {
+    const owner = ownerOf(node);
+    if (owner) return pages[owner];
+  }
+  return undefined;
+}
+
+/** Text put in a text block that takes it as it is (`textFilters`), by its component's `type`. Whether it took it. */
+export function typedAsIs(host, text) {
+  const page = textFilters(host) ? null : pageOf(host);
+  page?.type?.(host, text);
+  return Boolean(page?.type);
+}

package/browser/editor/page/panel.mjs

@@ -0,0 +1,64 @@
+import { Z } from "../../shared/layers.mjs";
+
+// The editor's one bottom panel: the conflicts' (conflicts.mjs, left) and the lost texts' (notices.mjs,
+// right) are the same card: a small muted head with a red dot, items under it, the reader's words as
+// a quote, one filled primary button, the rest outlined or, looking only, quiet text. No notice covers
+// one: while one stands, the toast stands above it (notices.mjs, and the workbench's, told the room).
+
+const PANELS = ".ge-conflicts:not([hidden]), .ge-panel";
+
+/**
+ * How far from the window's bottom the highest bottom panel shown reaches, 0 with none shown: what a
+ * notice stands above.
+ */
+export function panelRoom() {
+  let room = 0;
+  for (const panel of document.querySelectorAll(PANELS)) {
+    const { top, height } = panel.getBoundingClientRect();
+    if (height > 0) room = Math.max(room, Math.round(innerHeight - top));
+  }
+  return room;
+}
+
+// Who hears that the room the panels take may have changed: as a panel comes, changes size (cards
+// added or answered), is hidden (收起) and goes.
+const hearing = new Set();
+const told = () => hearing.forEach((listener) => listener());
+const sizes = typeof ResizeObserver === "function" ? new ResizeObserver(told) : null;
+
+/** `listener` told whenever the room the bottom panels take may have changed. */
+export const onPanels = (listener) => hearing.add(listener);
+
+/** A bottom panel put on the page. */
+export function panelShown(panel) {
+  sizes?.observe(panel);
+  told();
+}
+
+/** A bottom panel taken off the page. */
+export function panelGone(panel) {
+  sizes?.unobserve(panel);
+  told();
+}
+export const PANEL_STYLE = `
+  :is(.ge-conflicts, .ge-panel) { position: fixed; bottom: 16px; z-index: ${Z.panel}; box-sizing: border-box; width: min(400px, calc(100vw - 32px)); max-height: min(70vh, 600px); overflow: auto; border-radius: 10px; background: var(--ge-bg); color: var(--ge-tx); box-shadow: var(--ge-shadow); font: 13px/1.55 var(--doc-font, system-ui, sans-serif); }
+  .ge-conflicts { left: 16px; }
+  .ge-panel { right: 16px; }
+  .ge-conflicts[hidden] { display: none; }
+  :is(.ge-conflicts-head, .ge-panel-head) { position: sticky; top: 0; z-index: 1; display: flex; align-items: center; gap: 8px; padding: 10px 10px 4px 14px; background: var(--ge-bg); color: var(--ge-tx2); font-size: 12px; font-weight: 500; }
+  :is(.ge-conflicts-head, .ge-panel-head)::before { content: ""; flex: none; width: 6px; height: 6px; border-radius: 50%; background: var(--ge-red); }
+  :is(.ge-conflicts-head, .ge-panel-head) span { flex: 1; }
+  :is(.ge-conflict, .ge-panel-item) { padding: 10px 14px 12px; }
+  :is(.ge-conflict, .ge-panel-item) + :is(.ge-conflict, .ge-panel-item) { border-top: 1px solid var(--ge-edge); }
+  :is(.ge-conflict, .ge-panel-item) p { margin: 0; font-weight: 500; }
+  :is(.ge-conflict, .ge-panel-item) p + .ge-version { margin-top: 6px; }
+  :is(.ge-conflicts, .ge-panel) .ge-version { margin: 0; padding: 0 0 0 10px; border-left: 2px solid var(--ge-quote); overflow-wrap: anywhere; }
+  :is(.ge-conflicts, .ge-panel) .ge-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; margin-top: 12px; }
+  :is(.ge-conflicts, .ge-panel) button { height: 28px; padding: 0 10px; border: 1px solid var(--ge-edge); border-radius: 6px; background: transparent; color: inherit; font: inherit; font-weight: 500; white-space: nowrap; cursor: pointer; }
+  :is(.ge-conflicts, .ge-panel) button:hover:not(:disabled) { background: var(--ge-hover); }
+  :is(.ge-conflicts, .ge-panel) button[data-primary] { border-color: transparent; background: var(--ge-accent); color: #fff; }
+  :is(.ge-conflicts, .ge-panel) button[data-primary]:hover:not(:disabled) { background: var(--ge-accent-hover); }
+  :is(.ge-conflicts, .ge-panel) button[data-quiet] { height: 24px; padding: 0 6px; border-color: transparent; color: var(--ge-tx2); font-weight: 400; }
+  :is(.ge-conflicts, .ge-panel) button[data-quiet]:hover:not(:disabled) { color: var(--ge-tx); background: transparent; }
+  :is(.ge-conflicts, .ge-panel) button:disabled { opacity: .45; cursor: default; }
+`;

package/browser/editor/page/placement.mjs

@@ -0,0 +1,58 @@
+// Where a card or panel that stands by something stands: notion-lite's ui/popup.js rule (an origin, a
+// side, an alignment and a gap; put on the other side where it does not fit; kept inside the window),
+// the one placement every such card here takes: the link card, the formula editor, the cell bar, the
+// format bar, the tooltips and the icon picker's popups (emoji-picker/support.mjs). The block menu
+// (menu.mjs place) and what follows the pointer (hints, the size label of resize/) have rules of
+// their own. What stands for text (the format bar, a pasted address's 选择视图) stands by its last
+// character: textAnchor, besideText.
+
+const TEXT_GAP_X = 4; // its corner this far right of the text's last character
+const TEXT_GAP_Y = 8; // and this far below its line (or above the text)
+const TEXT_MARGIN = 12; // this far inside the window at the most
+
+/**
+ * The left and top (window px, not rounded) of a box of `size` ({ width, height }) by `origin` (a
+ * rect), `margin` px inside the window at the most. placement: "bottom" or "top" (below or above
+ * the origin), "right" or "left" (beside it); a box that does not fit on the side asked for goes to
+ * the opposite one if it fits there (if it fits on neither, it stays on the one asked for), inside the
+ * window less its scrollbars. align:
+ * along that side, the box's "start", "center" or "end" with the origin's. gap: px between them. x:
+ * for "bottom" and "top", where the box's left edge is wanted in place of the alignment's (the format
+ * bar stands at the selection's last character).
+ */
+export function placeBox(origin, { width, height }, { placement = "bottom", align = "start", gap = 0, margin = 8, x } = {}) {
+  // The window less its scrollbars (a box kept inside innerWidth would run under the page's scrollbar).
+  const root = globalThis.document?.documentElement;
+  const innerWidth = root?.clientWidth || globalThis.innerWidth;
+  const innerHeight = root?.clientHeight || globalThis.innerHeight;
+  const clamp = (value, space) => Math.max(margin, Math.min(value, space - margin));
+  const alignX = () => x ?? (align === "center" ? origin.left + origin.width / 2 - width / 2 : align === "end" ? origin.right - width : origin.left);
+  const alignY = () => (align === "center" ? origin.top + origin.height / 2 - height / 2 : align === "end" ? origin.bottom - height : origin.top);
+  if (placement === "bottom" || placement === "top") {
+    const below = origin.bottom + gap;
+    const above = origin.top - gap - height;
+    const fitsBelow = below + height <= innerHeight - margin;
+    const fitsAbove = above >= margin;
+    const top = placement === "bottom" ? (fitsBelow || !fitsAbove ? below : above) : (fitsAbove || !fitsBelow ? above : below);
+    return { left: clamp(alignX(), innerWidth - width), top: clamp(top, innerHeight - height) };
+  }
+  const right = origin.right + gap;
+  const beyond = origin.left - gap - width;
+  const fitsRight = right + width <= innerWidth - margin;
+  const fitsLeft = beyond >= margin;
+  const left = placement === "right" ? (fitsRight || !fitsLeft ? right : beyond) : (fitsLeft || !fitsRight ? beyond : right);
+  return { left: clamp(left, innerWidth - width), top: clamp(alignY(), innerHeight - height) };
+}
+
+/**
+ * Where text (a range) is to what stands for it: its last character (its last piece of a line), not
+ * the right edge of its widest line, and the top of its first line, for when there is no room below.
+ */
+export function textAnchor(range) {
+  const box = range.getBoundingClientRect();
+  const end = [...range.getClientRects()].filter((rect) => rect.width > 0 && rect.height > 0).at(-1) ?? box;
+  return { right: end.right, bottom: end.bottom, top: box.top };
+}
+
+/** The left and top of a box of `size` standing for text (`anchor`: textAnchor): below and right of its last character, above its first line when it does not fit below. */
+export const besideText = (anchor, size) => placeBox(anchor, size, { x: anchor.right + TEXT_GAP_X, gap: TEXT_GAP_Y, margin: TEXT_MARGIN });

package/browser/editor/page/post.mjs

@@ -0,0 +1,41 @@
+import { t, told } from "../../shared/i18n/index.mjs";
+// The page's one way to talk to the preview server: a POST of JSON with the report's token
+// (postJson: the request, a network error rejecting as fetch does; postAnswer: its answer read, a
+// failure an answer too, what the editor's requests use), and what goes over it: what a refusal
+// says (failure) and how an upload carries a file (blobBase64).
+
+/** POST `body` as JSON to `route` with `token` (the map's); resolves with the Response. */
+export const postJson = (route, token, body, { keepalive = false } = {}) => fetch(route, {
+  method: "POST",
+  headers: { "Content-Type": "application/json", "X-Gallery-Token": token },
+  body: JSON.stringify(body),
+  keepalive,
+});
+
+/**
+ * POST `body` as JSON to `route` and read the answer, never throwing: a server that cannot be
+ * reached answers `{ ok: false, reason: "offline" }`, one that answers with no JSON `{ ok: false }`.
+ */
+export async function postAnswer(route, token, body) {
+  let response;
+  try {
+    response = await postJson(route, token, body);
+  } catch {
+    return { ok: false, reason: "offline" };
+  }
+  return response.json().catch(() => ({ ok: false }));
+}
+
+/**
+ * What a refused request says: the server's own words in the UI's language (told: its template with its
+ * values, or its whole message), else that it could not be reached, else `fallback`.
+ */
+export const failure = (answer, fallback) => told(answer) ?? (answer.reason === "offline" ? t("连不上本地服务") : fallback);
+
+/** A blob's bytes as base64, how an upload carries them. */
+export const blobBase64 = (blob) => new Promise((resolve, reject) => {
+  const reader = new FileReader();
+  reader.onload = () => resolve(String(reader.result).split(",")[1]);
+  reader.onerror = () => reject(reader.error);
+  reader.readAsDataURL(blob);
+});

package/browser/editor/page/present-links.mjs

@@ -0,0 +1,50 @@
+import { t } from "../../shared/i18n/index.mjs";
+import { addressOn, elsewhere, fromFile, isPageAddress, mayBePage, pageAddress, workbenchHash } from "../../shared/page-address.mjs";
+import { inTrash, linkedPages, pageLinks } from "../../shared/page-links.mjs";
+import { PROTOCOL, VERSION } from "../../shared/session.mjs";
+
+// The links of a page shown in 演示视图 (?present: src/server/routes.mjs), which has no editor and whose
+// frame the presentation holds (src/workbench/app/features/present/). A link to a document or a block
+// of one goes there in the frame and stays a reader's: its page with ?present, the block found by the
+// kit (kit/runtime/reveal.js); followed as it stands it would come to the document's page with the
+// editor on it, and a web address would take the frame away from the presentation, so that goes to
+// a new tab. An address of this computer is asked of the list as the click is taken, for only the
+// list knows the titles and what is gone: a document that is not there leaves the presentation where
+// it is, with a word through it (the workbench's notice), and on another port what the list does not
+// hold (addressOn) is another program's, a web address like any. What the kit or the browser does with
+// a click stays theirs: an anchor, a link to save, a link of a target of its own, any click with a key
+// held.
+
+const own = pageAddress(location.href)?.slug ?? null;
+const openTab = (address) => window.open(address, "_blank", "noopener");
+const read = (route) => fetch(`/__gallery/workspace/${route}`).then((answer) => answer.json()).catch(() => null);
+
+function go({ slug, block }) {
+  const fragment = block ? `#${encodeURIComponent(block)}` : "";
+  if (slug !== own) location.assign(`/generated/${slug}.html?present${fragment}`);
+  else if (block) dispatchEvent(new CustomEvent("doc-jump-request", { detail: { hash: fragment } })); // the kit's jump, a step of the history as a link #<block id> is
+}
+
+function sayGone(name, { trash = [] } = {}) {
+  const text = inTrash(trash, name) ? t("这个页面已删除。") : t("没有找到这个页面。");
+  window.parent.postMessage({ protocol: PROTOCOL, v: VERSION, type: "notice", slug: own, text }, location.origin);
+}
+
+async function follow(address) {
+  if (!mayBePage(address)) return void openTab(address);
+  const listed = await read("outline");
+  const place = addressOn(address, listed?.reports ? pageLinks(linkedPages(listed.reports)) : null, location.origin);
+  if (place) go(place);
+  else if (isPageAddress(address) && !elsewhere(address, location.origin)) sayGone(pageAddress(address)?.slug ?? workbenchHash(address), listed ?? undefined);
+  else openTab(address);
+}
+
+document.addEventListener("click", (event) => {
+  if (event.defaultPrevented || event.button !== 0 || event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;
+  const link = event.target.closest?.("a[*|href]");
+  if (!link || link.matches("[download], [target], [*|href^='#']")) return;
+  const address = fromFile(link.href.baseVal ?? link.getAttribute("href"), own, location.origin);
+  if (!address || !/^https?:/.test(address)) return;
+  event.preventDefault();
+  follow(address);
+});