@heycys/gallery 0.0.0-stage → 0.1.0

package/browser/editor/components/installed/index.mjs

@@ -0,0 +1,133 @@
+import { escapeText } from "../../../shared/escape.mjs";
+import { ATTRIBUTE, FALLBACK, INSTANCE, PACKAGE_ID, instanceMatch, refusedInCopy } from "../../../shared/components/installed.mjs";
+import { wordsIn } from "../../page/clipboard/own/writers.mjs";
+import { svg } from "../icons.mjs";
+import { t } from "../../../shared/i18n/index.mjs";
+
+// 组件: the one kind of block every component package is to the engines, the host of a package's
+// instances (src/shared/components/installed.mjs). It uses only what a definition offers any block:
+// the engines know no package and no part of one. An instance is one block, moved, copied and
+// deleted whole, no container, nothing going in or out; its parts edited as text are text blocks of
+// this kind (file.mjs finds them, as its manifest says), and everything else in it is the component's
+// (page.mjs). A press on its outer frame or on the handle is Gallery's, as for any block.
+//
+// Where the engines reach it (src/editor/page/ unless named): ../source/ (the scan stops at one,
+// natural.mjs and old names pass it by: `isInstance`, src/shared/components/), hints/ (`readOnly`), clipboard/own/
+// (`clipboard`, copied as itself), caret.mjs (`sealed`: `editable`, where most of the page's events
+// start from), text-select/, editor.mjs's entries and the tools that go by a kit's class (`keepsKeys`,
+// page.mjs), formula/, the "/" menu, the format bar and clipboard/ (`formula`). The "/" menu and 在下方新建
+// offer each package (`menuVariants`, notion-lite's, on the page object: the catalog reaches the page
+// alone), and a new one is written from its manifest (file.mjs `source`). Its parts edited as data
+// are written as a table's rows are (page/core.mjs dataChanges, on `dataOf` of the page object,
+// source/apply.mjs and file.mjs `rewrite`), an undo step of `source` (page/history.mjs).
+
+// An instance as Markdown, the words of the file and none of what a component draws: as its package's
+// manifest says (`markdown`), each part in the file's order with `parts`, a table a table, one edited
+// as text a paragraph and any other its words and pictures, or with `text`, and where no package says,
+// its words as any whole block's.
+function instanceParts(unit, how) {
+  const found = how.packageOf(unit.getAttribute(ATTRIBUTE));
+  if (found?.markdown !== "parts") return [how.words(unit)];
+  return saidParts(unit, found.parts).flatMap(({ part, edit }) => {
+    if (part.matches("table")) return [how.writtenAs("table", part)];
+    return (edit === "text" ? [how.own(part)] : [how.wordsIn(part).join(" · "), ...how.picturesIn(part)]).map((line) => [line]);
+  }).filter(([first, ...more]) => first || more.length > 0);
+}
+
+// The parts of an instance that say something, each once and none inside another, in the file's order.
+function saidParts(unit, parts) {
+  const said = Object.values(parts).flatMap(({ at, edit }) => [...unit.querySelectorAll(at)].map((part) => ({ part, edit })))
+    .filter(({ part }) => !part.matches(`${INSTANCE}, script, style, template`) && part.parentElement.closest(INSTANCE) === unit);
+  const found = [...new Map(said.map((each) => [each.part, each])).values()];
+  return found.filter(({ part }) => !found.some((other) => other.part !== part && other.part.contains(part)))
+    .sort((a, b) => (a.part.compareDocumentPosition(b.part) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1));
+}
+
+// A copy of an instance as blocks, what other programs and a field of plain text read of it: as its
+// package says, as a page export writes it (instanceParts), but for pictures, which are no words. Its
+// words are paragraphs, as `markdown: "parts"` has them; a text part that is a heading says so for the
+// clipboard's HTML (`as`: the type it is written as there, the parts writer's).
+function copiedParts(copy, found, { serializeInner, clipboardOf, copiedType }) {
+  if (found?.markdown !== "parts" || !found.parts) return [{ type: "paragraph", html: escapeText(wordsIn(copy).join(" · ")) }].filter(({ html }) => html);
+  return saidParts(copy, found.parts).flatMap(({ part, edit }) => {
+    if (part.matches("table")) return [clipboardOf("table").data(part, { serializeInner })].filter(Boolean);
+    const html = edit === "text" ? serializeInner(part) : escapeText(wordsIn(part).join(" · "));
+    const own = edit === "text" ? copiedType(part) : null;
+    return html ? [{ type: "paragraph", html, ...(own && clipboardOf(own)?.kind === "heading" ? { as: own } : {}) }] : [];
+  });
+}
+
+// All an element holds, what a <template> keeps apart among it, itself first.
+const allIn = (root) => [root, ...root.querySelectorAll("*")].flatMap((node) => (node.localName === "template" ? [node, ...[...node.content.children].flatMap(allIn)] : [node]));
+// Whether any of that may not come onto a page by a clipboard.
+const refused = (root) => allIn(root).some((node) => refusedInCopy(node.localName, [...node.attributes]));
+// The one element a copy's markup is, or null. An element's outerHTML reads back as itself, which
+// markup that leans on the parser does not (an end tag left out, a comment left open, an end tag of
+// nothing): what is put right here a file reads otherwise.
+function elementOf(html, doc = globalThis.document) {
+  const template = doc.createElement("template");
+  template.innerHTML = html;
+  const [root, ...more] = template.content.childNodes;
+  return template.innerHTML === html && root?.nodeType === 1 && more.length === 0 ? root : null;
+}
+// The most a description carries of one piece of markup (blocks.mjs `string`).
+const CARRIED = 1e6;
+
+// A block of four corners and a notch, a piece that fits something else.
+export const ICON = svg('<path d="M4 6.75A1.75 1.75 0 0 1 5.75 5H8a2 2 0 0 1 4 0h2.25A1.75 1.75 0 0 1 16 6.75V9a2 2 0 0 1 0 4v1.25A1.75 1.75 0 0 1 14.25 16H5.75A1.75 1.75 0 0 1 4 14.25z"/>');
+
+export default {
+  name: "installed",
+  // Ahead of every rule of the page's: all that stands in an instance is the component's, its
+  // controls too, and one of no package, or whose component failed, says why nothing there answers.
+  readOnly: [
+    { rank: 1, at: `[${FALLBACK}] *`, says: t("这个组件没有运行：内容只能看，可以整块移动、复制和删除。") },
+    { rank: 2, at: `[${ATTRIBUTE}] *`, says: null },
+  ],
+  attributes: [ATTRIBUTE],
+  sealed: INSTANCE,
+  units: {
+    installed: {
+      name: t("组件@block"),
+      icon: ICON,
+      match: [{ rank: 0, tag: ["div", "section"], attr: ATTRIBUTE }],
+      boxed: true,
+      chapter: true,
+      copy: "itself",
+    },
+  },
+  hosts: {
+    // A part a manifest edits as text: words as in a paragraph, emptied but never split, joined or
+    // taken out on its own, as a media block's caption is. No formula: the kit draws none in an
+    // instance, so one would read as its TeX from the next load on.
+    installed: { name: t("组件里的文字"), caps: () => ["empty", "links"], formula: false, placeholder: t("输入文字…") },
+  },
+  types: {
+    // An instance made on the page, in no menu of types: its package's rows are `menuVariants`, and its
+    // markup the file's, written from its manifest, or from what a clipboard carried where a copy has
+    // no unit to be made from (`data-ge-copy`).
+    installed: {
+      tag: "div", kind: "installed", bare: true,
+      extras: (element) => ({ package: element.getAttribute(ATTRIBUTE), ...(element.hasAttribute("data-ge-copy") ? { html: element.getAttribute("data-ge-copy") } : {}) }),
+      clipboard: {
+        kind: "parts", read: instanceParts,
+        // What carries it where its unit is not (cut, another document): its markup as the kit would
+        // start it, with the ids it names itself, and what it says to whoever reads no blocks. One
+        // whose markup no clipboard may bring anywhere (a handler, a script) has none, and stays a
+        // copy within its document.
+        data(node, { serializeInner, copyOf, clipboardOf, copiedType, page }) {
+          const copy = copyOf(node, { named: true });
+          const html = copy.outerHTML;
+          if (html.length > CARRIED || refused(copy) || !elementOf(html, node.ownerDocument)) return null;
+          const id = node.getAttribute(ATTRIBUTE);
+          return { type: "installed", package: id, html, blocks: copiedParts(copy, page("installed")?.packageOf(id), { serializeInner, clipboardOf, copiedType }) };
+        },
+        check(block, { string, valid }) {
+          if (!string(block.package, 200) || !PACKAGE_ID.test(block.package) || !string(block.html, CARRIED) || !Array.isArray(block.blocks) || !block.blocks.every((inner) => valid(inner))) return false;
+          const root = elementOf(block.html);
+          return Boolean(root?.matches(instanceMatch(block.package))) && !refused(root);
+        },
+      },
+    },
+  },
+};

package/browser/editor/components/installed/page.mjs

@@ -0,0 +1,422 @@
+import { ARRIVING, ATTRIBUTE, DATA_MOST, DATA_SHOWN, FALLBACK, FIELDS, INSTANCE, NO_TEXT, PACKAGE_MARK, SCHEMA, fitsDataScript, instanceMatch, isDataScript, noDataPart, refusedInData, schemaAhead } from "../../../shared/components/installed.mjs";
+import { referencedIds } from "../../../shared/copy-ids.mjs";
+import { language } from "../../../shared/i18n/index.mjs";
+import { caretAt, editable } from "../../page/caret.mjs";
+import { copyOf } from "../../page/clipboard/own/describe.mjs";
+import { ownIds } from "../../page/clipboard/own/ids.mjs";
+import { unitElement } from "../../page/core.mjs";
+import { accepts, capsFor } from "../registry.mjs";
+import { ICON } from "./index.mjs";
+import { followCatalog, followSettings, isBehind } from "./served.mjs";
+
+// 组件 on the page: events go by region, one rule. What comes down inside an instance and in no text
+// block of it is the component's, and the editor lets go (`keepsKeys`, the same rule as notion-lite's
+// block-keys and clipboard, `e.target.closest('input, textarea')`: a field of a block keeps its keys,
+// here all that stands in an instance, its buttons and what it draws, but undo and redo on what is no
+// field, which has none of its own). Its text parts are the editor's: Enter, Backspace, Ctrl+Z and a
+// selection as in any words. Its outer frame and its handle are Gallery's: moving, copying and deleting
+// it whole, as for any block. What a press does here, the block tools clearing, menus closing and the
+// format bar going, stays: no event is stopped, and a press in a component is only no press the editor
+// answers (`readOnly` in index.mjs says nothing of it, and the format bar comes back over no selection).
+//
+// The page holds the catalog as the server gave it (its map's `components`): a page with no instance
+// of a package that changes is told so and stays as it is, as being shown again would cost its undo
+// steps, so it reads the new list from its own address, which is what a load of the page would have
+// read (`doc-catalog-changed`, src/server/routes.mjs). An instance is made from a template or from
+// what a clipboard carried, here as what the kit would start: its text parts text blocks at once, the
+// caret among them. The first instance of a package on a page served without it, by whatever way it
+// came, brings it: the tags of the map, once, where the server would have put them.
+//
+// A part its manifest edits as data is the component's and nothing of the editor's goes in. What
+// writes it is `context.edit`, which the kit asks of the page (`doc-component-edit`): the page gives the
+// component a draft of each part it names, off the page, and copies of what it made of them go in, one
+// `source` step of undo, or, should it throw, write the part on the page or make what the file could
+// not hold, nothing has happened. The commits find what changed as they find a table's (`dataOf`,
+// core.mjs dataChanges), each part as the kit's dehydrate leaves it, so that what the component leaves
+// on it by its manifest's `runtime` is no change, and they write what differs and nothing else. An
+// instance written whole, made or put back, holds what the file says (`dataIn`), read the same way. What
+// the reader writes over someone else's change of a part (仍然调整) is a step of its own from theirs
+// (`overwrite`), so that one undo gives the file's back.
+// One past its manifest's `schema` is read-only, its words and all.
+
+let held = null; // the map, what makes a block with no editor (the transfer worker) finds none of
+
+// A package as the page knows it. One hidden is one like any other but in a menu: its instances run, copy
+// and go by its name. One turned off is none from the moment the page hears, whatever its list still
+// says: what a clipboard brings would load it, and only a list that came would say otherwise.
+const entryOf = (id) => held?.components?.find((entry) => entry.id === id && entry.state !== "disabled") ?? null;
+
+// What the page runs of each package, by id: the stamp it came with and that of its manifest.
+const brought = new Map();
+
+// On an instance its component wrote: the stamp of the manifest that component ran by, which the write
+// goes by wherever it is sent from, a page taking up what one that is gone left (autosave.mjs recover)
+// running the manifest there is now.
+const WRITTEN_BY = "data-ge-definition";
+
+// Whether the page runs an older version of a package than `entry` says, which only a load mends.
+const overtaken = ({ id, stamp }) => brought.has(id) && brought.get(id).stamp !== stamp;
+
+// On an instance, the parts of it one edit wrote together, as lists of names (JSON): they go to the file
+// together, or wait together for the reader where someone else changed one of them, as the edit's one
+// undo step takes them together. On the instance, as its stamp is, so that a page taking up what one that
+// is gone left (its body, autosave.mjs recover) sends them so too.
+const WRITTEN_TOGETHER = "data-ge-together";
+const writtenTogether = (instance) => {
+  try {
+    const groups = JSON.parse(instance.getAttribute(WRITTEN_TOGETHER) ?? "[]");
+    return Array.isArray(groups) ? groups.filter(Array.isArray) : [];
+  } catch {
+    return [];
+  }
+};
+
+// A tag of a package's as an element that will run: what a template's content holds never does.
+function tagFrom(html) {
+  const template = document.createElement("template");
+  template.innerHTML = html;
+  const written = template.content.firstElementChild;
+  const tag = document.createElement(written.localName);
+  for (const { name, value } of written.attributes) tag.setAttribute(name, value);
+  tag.textContent = written.textContent;
+  if (written.localName === "script") tag.async = false; // in the order they are put in
+  return tag;
+}
+
+// Right after the last of the kit's and the packages' of its kind, as a page is served (render/assets.mjs afterKitTags).
+function put(tag) {
+  const kind = tag.localName;
+  const last = [...document.querySelectorAll(`${kind}[data-doc-kit], ${kind}[data-doc-vendor], ${kind}[${PACKAGE_MARK}]`)].at(-1);
+  if (last) last.after(tag);
+  else (kind === "link" ? document.head : document.body).append(tag);
+}
+
+// The kit's file a tag loads is on the page already (by another package, or as the page was served).
+const onPage = (tag) => ["data-doc-kit", "data-doc-vendor"].some((mark) => tag.hasAttribute(mark) && document.querySelector(`[${mark}="${tag.getAttribute(mark)}"]`));
+
+// The instances of a package start, or show why they do not, now that its files are in.
+const started = (id) => document.querySelectorAll(instanceMatch(id)).forEach((host) => globalThis.DocKit?.mount(host));
+
+// A package on a page served without it: its tags in order, styles then scripts, the kit's files it
+// asks for first. Its description is told at once, its script's own turn comes as it loads.
+function bring({ id, stamp, definition, kit = [], tags }) {
+  if (brought.has(id)) return;
+  brought.set(id, { stamp, definition });
+  const all = [...kit, ...tags.styles, ...tags.scripts].map(tagFrom).filter((tag) => !onPage(tag));
+  const script = all.find((tag) => tag.localName === "script" && tag.src && tag.hasAttribute(PACKAGE_MARK));
+  const done = () => {
+    script?.removeAttribute(ARRIVING);
+    started(id);
+  };
+  script?.setAttribute(ARRIVING, id);
+  script?.addEventListener("load", done, { once: true });
+  script?.addEventListener("error", done, { once: true });
+  all.forEach(put);
+  if (!script) done();
+}
+
+// An instance's parts as its manifest says them, as the kit was told. None before its description has come.
+const partsOf = (instance) => Object.entries(globalThis.DocKit?.description(instance.getAttribute(ATTRIBUTE))?.parts ?? {});
+// Whether an instance holds its content in a shape its manifest does not reach, as the kit was told it.
+const ahead = (instance) => schemaAhead(instance.getAttribute(SCHEMA), globalThis.DocKit?.description(instance.getAttribute(ATTRIBUTE))?.schema);
+// The elements of a part an instance holds, none of an instance in it nor of what the kit draws of a
+// script of data there, which is no element of the file's.
+const elementsOf = (instance, at) => [...instance.querySelectorAll(at)].filter((part) => !part.matches(INSTANCE) && part.parentElement.closest(INSTANCE) === instance && !part.closest(`.${DATA_SHOWN}`));
+
+// The elements of an instance its component writes, [[name, element]], as the server finds them
+// (file.mjs dataParts): of each part edited as data the first it holds, as context.part does. One in
+// another is written with that one, and an element two parts name is the first's.
+function dataParts(instance) {
+  const first = partsOf(instance).filter(([, { edit }]) => edit === "data").map(([name, { at }]) => [name, elementsOf(instance, at)[0]]).filter(([, part]) => part);
+  return first.filter(([, part], index) => !first.some(([, other], at) => (other !== part && other.contains(part)) || (other === part && at < index)));
+}
+const dataOf = (instance) => Object.fromEntries(dataParts(instance).map(([name, part]) => [name, part.innerHTML]));
+
+// The elements of an instance its package edits as text, as the server's scan finds them
+// (file.mjs textParts), in the file's order: what stands in a data part or holds one is the component's,
+// and one past its manifest has none.
+function textParts(instance) {
+  if (ahead(instance)) return [];
+  const said = partsOf(instance).filter(([, { edit }]) => edit === "text");
+  const data = dataParts(instance).map(([, part]) => part);
+  const parts = [...new Set(said.flatMap(([, { at }]) => elementsOf(instance, at)))].filter((part) => !NO_TEXT.has(part.localName) && !data.some((other) => other.contains(part) || part.contains(other)));
+  return parts.filter((part) => !parts.some((other) => other !== part && other.contains(part))).sort((a, b) => (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1));
+}
+
+// All an element holds, what a <template> keeps apart among it.
+const allIn = (root) => [...root.querySelectorAll("*")].flatMap((node) => (node.localName === "template" ? [node, ...allIn(node.content)] : [node]));
+
+// Why what a component made of a draft of `part` cannot go in, as the server would say (file.mjs
+// `rewrite`), for who writes the component, or null.
+function draftProblem(part, draft) {
+  if (draft.cloneNode(false).outerHTML !== part.cloneNode(false).outerHTML) return "a part's own tag and attributes are the file's: a change writes what it holds";
+  const html = draft.innerHTML;
+  if (new TextEncoder().encode(html).length > DATA_MOST) return `it holds more than the ${DATA_MOST} bytes one commit writes`;
+  const attributes = [...part.attributes];
+  if (part.localName === "script") return isDataScript(part.localName, attributes) && fitsDataScript(html) ? null : "a script of data holds JSON, with nothing in it that ends a script: write < as \\u003c";
+  if (noDataPart(part.localName)) return `a <${part.localName}> is no part a component can write`;
+  const read = part.cloneNode(false);
+  read.innerHTML = html;
+  if (read.innerHTML !== html) return "what it holds does not read back as itself (a row with no tbody, a block in a paragraph): a file would hold something else";
+  const refused = allIn(draft).find((node) => refusedInData(node.localName, [...node.attributes]));
+  return refused ? `a data part holds no <${refused.localName}> of that kind: no script, handler, frame, address of code, data-block-id or data-ge-*` : null;
+}
+
+// What the text blocks of an instance are to contenteditable: an instance the kit shows as it stands,
+// its component failed or its script started nothing, takes no word, as one of no package does.
+const openness = (instance) => (instance.hasAttribute(FALLBACK) ? "false" : "true");
+
+// Its text blocks as it stands now, for as long as it stands so: a later mount opens them again.
+function followFallback(instance) {
+  const value = openness(instance);
+  for (const part of instance.querySelectorAll('[data-ge-kind="installed"]')) {
+    if (part.parentElement.closest(INSTANCE) === instance && part.getAttribute("contenteditable") !== value) part.setAttribute("contenteditable", value);
+  }
+}
+
+// Its text parts text blocks now: `data-ge-part`, holding what each said, until the commit that writes
+// the instance names them. What the file then says is what they start from: words typed before that
+// go with the next commit, an untouched one shows the file's, and one the file takes for no text
+// block (more than words in it: `notText`) is read-only from then on.
+function editableParts(instance) {
+  const parts = textParts(instance);
+  for (const part of parts) for (const [name, value] of [["contenteditable", openness(instance)], ["data-ge-part", part.innerHTML], ["data-ge-kind", "installed"], ["data-ge-caps", capsFor("installed")], ["data-ge-framed", ""]]) part.setAttribute(name, value);
+  return parts;
+}
+
+/** A new instance from its markup, marked as made on the page, not on it yet. Ids it does not name itself go, as from a copy. */
+function newInstance(doc, html) {
+  const template = doc.createElement("template");
+  template.innerHTML = html;
+  const instance = doc.importNode(template.content.firstElementChild, true);
+  const all = [instance, ...instance.querySelectorAll("*")];
+  const named = referencedIds(all.flatMap((node) => [...node.attributes]));
+  for (const node of all) if (node.id && !named.has(node.id)) node.removeAttribute("id");
+  for (const [name, value] of [["data-ge-new", ""], ["data-ge-type", "installed"], ["data-ge-unit-kind", "installed"], ["data-ge-frame", ""], ["contenteditable", "false"]]) instance.setAttribute(name, value);
+  return instance;
+}
+
+/** An instance from what a clipboard carried (`data`): the file is written from that markup, which the commit sends. */
+export function build({ doc, block }) {
+  const entry = entryOf(block.package);
+  if (entry) bring(entry);
+  const instance = newInstance(doc, block.html);
+  instance.setAttribute("data-ge-copy", block.html);
+  editableParts(instance);
+  return instance;
+}
+
+let listed = true; // whether the list says what the server last did: no read of it on its way, none that failed
+let reads = 0; // the reads of the list begun
+
+// The list as a load of the page would give it, read from the page's own address: nothing of the page
+// changes. Reads may cross: the last one begun is what the server last did, whichever answers last.
+async function readList() {
+  const read = ++reads;
+  listed = false;
+  const answer = await fetch(location.href, { cache: "no-store" }).catch(() => null);
+  const text = answer?.ok ? await answer.text().catch(() => null) : null;
+  const map = text && new DOMParser().parseFromString(text, "text/html").getElementById("doc-edit-map");
+  if (read !== reads || !map) return;
+  held.components = JSON.parse(map.textContent).components ?? [];
+  listed = true;
+}
+
+// Whether an instance of a package can come onto the page as it is (`entry`, as entryOf finds it): the
+// list says what the package is now, and the page runs that or nothing of it, so that the instance brings it.
+const inStep = (entry) => listed && entry !== null && !overtaken(entry);
+
+/**
+ * An instance on the page, a page's new one: of a package the page is behind on that cannot come as it
+ * is, what a page holding one when it changed has had; else its package brought, what it holds as text
+ * blocks where it came with none.
+ */
+function arrive(instance) {
+  if (!instance.isConnected || instance.parentElement?.closest(INSTANCE)) return;
+  const id = instance.getAttribute(ATTRIBUTE);
+  const entry = entryOf(id);
+  if (isBehind(id) && !inStep(entry)) return void window.dispatchEvent(new CustomEvent("doc-components-changed"));
+  if (!entry) return;
+  bring(entry);
+  started(id);
+  if (!instance.querySelector("[data-ge-block], [data-ge-part]")) editableParts(instance);
+}
+
+// A package's picture where a menu shows a mark.
+const pictureOf = ({ preview }) => (preview ? `<img src="${preview}" alt="">` : null);
+
+/** An instance on the page: what its events are, what Enter does in its words, and what the menus make of its package. */
+export function create({ map, newParagraph, active, sourceStep }) {
+  held = map;
+  // Whether a key in an instance, on no field of it, is undo or redo: a button or what a component draws
+  // has no undo of its own, and a press on one that wrote leaves the focus there, from where the page's
+  // undo goes on through every step, as notion-lite's does from anywhere (onHistoryKey). A field keeps
+  // its own.
+  const pageUndo = (node, event) => {
+    const key = event?.key?.toLowerCase();
+    return Boolean(event?.ctrlKey || event?.metaKey) && !event.altKey && (key === "z" || key === "y") && !node.matches(FIELDS);
+  };
+  // What a component asks to write (`detail` of doc-component-edit, the kit's: the parts it names, and
+  // `run`, its change, given a draft of each by name): whether it was taken. What was written goes in as
+  // copies, so that a draft the component keeps reaches nothing on the page; a change that wrote the part
+  // on the page instead is undone and refused, as its step would undo the change it left out.
+  function write({ parts, run }, instance) {
+    if (!active()) return false;
+    const id = instance.getAttribute(ATTRIBUTE);
+    const refuse = (problem) => {
+      console.error(`[DocKit] ${id}: context.edit: ${problem}`);
+      return false;
+    };
+    const before = parts.map(({ part }) => part.innerHTML);
+    const drafts = parts.map(({ part }) => part.cloneNode(true));
+    const ran = run(Object.fromEntries(parts.map(({ name }, index) => [name, drafts[index]])));
+    const live = parts.findIndex(({ part }, index) => part.innerHTML !== before[index]);
+    if (live >= 0) {
+      parts.forEach(({ part }, index) => { if (part.innerHTML !== before[index]) part.innerHTML = before[index]; });
+      return refuse(`it wrote the part ${parts[live].name} on the page: a change writes the draft it is handed, which goes onto the page when it returns`);
+    }
+    if (!ran) return false;
+    for (const [index, { name, part }] of parts.entries()) {
+      const problem = draftProblem(part, drafts[index]);
+      if (problem) return refuse(parts.length > 1 ? `${name}: ${problem}` : problem);
+    }
+    const changed = parts.map(({ name, part }, index) => [part, before[index], drafts[index], name]).filter(([, was, draft]) => draft.innerHTML !== was);
+    if (changed.length === 0) return true;
+    for (const [part, , draft] of changed) part.replaceChildren(...draft.cloneNode(true).childNodes);
+    instance.setAttribute(WRITTEN_BY, brought.get(id)?.definition ?? "");
+    if (changed.length > 1) {
+      const names = new Set(changed.map(([, , , name]) => name));
+      const groups = writtenTogether(instance);
+      const joined = groups.filter((group) => group.some((name) => names.has(name)));
+      instance.setAttribute(WRITTEN_TOGETHER, JSON.stringify([...groups.filter((group) => !joined.includes(group)), [...new Set([...names, ...joined.flat()])]]));
+    }
+    sourceStep(changed.map(([part, was]) => [part, was]));
+    return true;
+  }
+  return {
+    keepsKeys: (node, event) => node?.nodeType === 1 && Boolean(node.parentElement?.closest(INSTANCE)) && !editable(node) && !pageUndo(node, event),
+    undoHere: (node) => Boolean(node.parentElement?.closest(INSTANCE)) && !editable(node),
+    keys: {
+      // notion-lite's captionEnter: words of a block that are not the block's own line do not split,
+      // Enter there is a text block after the block, the caret in it.
+      enter({ host }) {
+        const unit = unitElement(host);
+        const box = unit?.parentElement;
+        if (!box || !accepts(box.getAttribute("data-ge-box-kind") ?? "flow", "paragraph")) return false;
+        newParagraph(box, unit);
+        return true;
+      },
+    },
+    // Each package with a template that is offered (its `state`, as `isHidden` of page/offered.mjs goes
+    // by block types), by its id, as notion-lite's variants: a row of the menus, found by its name in
+    // either language and its words, and what makes one (notion-lite's
+    // insertTypedBlock: the caret in its first text part; with none, in an empty paragraph after it, as
+    // for a divider).
+    menuVariants: () => Object.fromEntries((map.components ?? []).filter(({ template, state }) => template && state === "normal").map((entry) => [entry.id, {
+      label: entry.name[language],
+      icon: pictureOf(entry) ?? ICON,
+      words: `${entry.name.zh} ${entry.name.en} ${entry.id} ${entry.words}`.toLowerCase(),
+      sample: true,
+      preview: { src: entry.preview, says: entry.description[language] },
+      create({ doc, put: place, paragraph }) {
+        bring(entry);
+        const instance = newInstance(doc, entry.template);
+        ownIds(doc, [instance]);
+        place(instance);
+        return editableParts(instance)[0] ?? place(paragraph());
+      },
+    }])),
+    /** What the reader calls a block of it: its package's name, where the page knows its package. */
+    nameOf: (unit) => entryOf(unit.getAttribute(ATTRIBUTE))?.name[language] ?? null,
+    /**
+     * One the file dropped that the page still shows, a reader's to keep: it goes from now on as what a
+     * clipboard carried does, its markup as the kit would start it. Its template would not hold what
+     * the reader has.
+     */
+    renew(instance) {
+      if (!instance.hasAttribute("data-ge-copy")) instance.setAttribute("data-ge-copy", copyOf(instance, { named: true }).outerHTML);
+      instance.setAttribute("data-ge-type", "installed");
+      return true;
+    },
+    /** A text part the file takes for no text block: as it stood, read-only, the caret on to the next one that is. */
+    notText(part) {
+      const selection = getSelection();
+      const next = selection.rangeCount > 0 && part.contains(selection.anchorNode) ? textParts(part.parentElement.closest(INSTANCE)).find((other) => other !== part && other.isContentEditable) ?? null : undefined;
+      part.innerHTML = part.getAttribute("data-ge-part");
+      for (const name of ["contenteditable", "data-ge-part", "data-ge-kind", "data-ge-framed", "data-ge-caps"]) part.removeAttribute(name);
+      if (next) caretAt(next, "start");
+      else if (next === null) selection.removeAllRanges();
+    },
+    /** Its package's picture, or the mark of any component. */
+    iconOf: (unit) => {
+      const entry = entryOf(unit.getAttribute(ATTRIBUTE));
+      return (entry && pictureOf(entry)) ?? ICON;
+    },
+    /**
+     * What of an instance its component writes, part by part, as the file is to hold it (null: nothing
+     * here does): its parts as the kit's dehydrate leaves them, what it and its component leave on them
+     * being no change.
+     */
+    dataOf: (instance) => (dataParts(instance).length > 0 ? dataOf(globalThis.DocKit.dehydrate(instance.cloneNode(true))) : null),
+    /** What of an instance the file's markup of it (`html`) holds that its component writes, read as dataOf reads one on the page. */
+    dataIn(html) {
+      const template = document.createElement("template");
+      template.innerHTML = html;
+      const instance = template.content.firstElementChild;
+      return instance?.matches(INSTANCE) && dataParts(instance).length > 0 ? dataOf(globalThis.DocKit.dehydrate(instance)) : null;
+    },
+    /** The most one commit carries of what components write, in bytes. */
+    dataMost: DATA_MOST,
+    /** Of the parts of an instance named (`names`), those one edit of this page wrote together, as lists of two or more. */
+    together: (instance, names) => writtenTogether(instance).map((group) => names.filter((name) => group.includes(name))).filter((group) => group.length > 1),
+    /**
+     * The reader writes what an instance holds over what someone else wrote to its parts (`theirs`, by
+     * name, as the file held them and the reader was shown them: 仍然调整): one `source` step from theirs to
+     * what the page holds, the page as it is, so that one undo gives back what the file held and writes it
+     * again. Returns the step, or null where the page holds theirs.
+     */
+    overwrite(instance, theirs) {
+      const parts = dataParts(instance).filter(([name, part]) => typeof theirs[name] === "string" && part.innerHTML !== theirs[name]);
+      return parts.length > 0 ? sourceStep(parts.map(([name, part]) => [part, theirs[name]])) : null;
+    },
+    /**
+     * An instance as it stood with what its component wrote (`parts`, by name, as a commit carried them)
+     * in place of what it holds: a copy off the page, a block to copy where the file did not take that
+     * write (the list of what a page left, editor.mjs showLost). Null where it holds none of those parts.
+     */
+    withData(instance, parts) {
+      const copy = instance.cloneNode(true);
+      const written = dataParts(copy).filter(([name]) => typeof parts?.[name] === "string");
+      for (const [name, part] of written) part.innerHTML = parts[name];
+      return written.length > 0 ? copy : null;
+    },
+    /** The stamp of the manifest an instance's component wrote it by, or the page runs it by. */
+    definitionOf: (instance) => (instance.hasAttribute(WRITTEN_BY) ? instance.getAttribute(WRITTEN_BY) || undefined : brought.get(instance.getAttribute(ATTRIBUTE))?.definition),
+    /** What a package's manifest says of how its instances are read: `parts` as the kit knows them, `markdown`. */
+    packageOf: (id) => ({ markdown: entryOf(id)?.markdown, parts: globalThis.DocKit?.description(id)?.parts }),
+    install() {
+      for (const tag of document.querySelectorAll(`script[${PACKAGE_MARK}]`)) {
+        const id = tag.getAttribute(PACKAGE_MARK);
+        brought.set(id, { stamp: entryOf(id)?.stamp ?? null, definition: entryOf(id)?.definition });
+      }
+      document.addEventListener("doc-component-edit", (event) => { if (write(event.detail, event.target)) event.preventDefault(); });
+      new MutationObserver((records) => {
+        for (const { type, target, addedNodes } of records) {
+          if (type === "attributes") followFallback(target);
+          for (const node of addedNodes) {
+            if (node.nodeType !== 1 || node.hasAttribute("data-doc-dev")) continue;
+            [...(node.matches(INSTANCE) ? [node] : []), ...node.querySelectorAll(INSTANCE)].forEach(arrive);
+          }
+        }
+      }).observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: [FALLBACK] });
+      window.addEventListener("doc-catalog-changed", readList);
+      window.addEventListener("doc-settings-changed", ({ detail }) => followSettings(held.components, detail));
+      followCatalog();
+    },
+    /** The page edits now: what the kit showed as it stands before its text blocks were made is shut, and a component can write. */
+    entered() {
+      document.querySelectorAll(`[${FALLBACK}]`).forEach(followFallback);
+      dispatchEvent(new Event("doc-editable"));
+    },
+  };
+}

package/browser/editor/components/installed/served.mjs

@@ -0,0 +1,35 @@
+import { settingState } from "../../../shared/components/installed.mjs";
+
+// What a page runs of a package is what it was served with. A page holding an instance of one that
+// changes is shown again; one holding none stays, as being shown again would cost its undo steps
+// (src/server/routes.mjs), and is behind on that package from then on, which nothing reads until an
+// instance of it comes onto the page: a menu, an undo, a paste, whatever else puts one there. One the
+// page's new list has, of a package the page runs nothing of or runs as it now is, brings it (./page.mjs
+// `bring`). Any other would run as the page was served, a package off still going, a changed one
+// as it was, against what the file now is, and words typed in it would be refused. So the page keeps
+// which packages it is behind on, and the first such instance to arrive asks for what a page holding
+// one has already had (`doc-components-changed`): shown again once nothing waits.
+
+const behind = new Set(); // the ids of the packages that changed since the page was served
+let any = false; // the server could not say which: the page connected a moment after a change
+
+/** Whether the package `id` may have changed since the page was served. */
+export const isBehind = (id) => any || behind.has(id);
+
+/**
+ * `components`, the list a page holds, as the reader's settings now say: the state each package says,
+ * which a menu reads, at once and with nothing shown again (`doc-settings-changed`). A package that
+ * comes on is in none of that yet: it comes with the list the page reads as the catalog changes, as
+ * one added does (`doc-catalog-changed`, ./page.mjs).
+ */
+export function followSettings(components, settings) {
+  for (const entry of components) entry.state = settingState(entry.id, settings);
+}
+
+/** Hears what changed of the catalog while the page held no instance of it. */
+export function followCatalog() {
+  window.addEventListener("doc-catalog-changed", ({ detail: { ids } }) => {
+    if (ids) ids.forEach((id) => behind.add(id));
+    else any = true;
+  });
+}