dsh-plugin-term-dictionary 1.0.0 → 1.1.1

package/lib/core/copy.js

@@ -23,6 +23,16 @@ const zh = {
 	explainLang_en: "英文",
 	explainDepthName: "详细程度",
 	explainDepthHint: "解释写多详细",
+	entryColumnsName: "词条排列",
+	entryColumnsHint: "一列排下去很长；「自动」按面板宽度铺成多列，窄了就回到一列。",
+	entryColumns_auto: "自动",
+	entryColumns_1: "1 列",
+	entryColumns_2: "2 列",
+	entryColumns_3: "3 列",
+	entryRowsName: "词条行高",
+	entryRowsHint: "多列排版时，同一行的卡片要不要一样高。统一高度不会在矮卡片下面留出空条；各按各自更紧凑。",
+	entryRows_uniform: "统一高度",
+	entryRows_compact: "各按各自",
 	explainDepth_brief: "一句话",
 	explainDepth_normal: "标准",
 	explainDepth_detailed: "详细",
@@ -55,6 +65,20 @@ const zh = {
 	transferImportHint: "选择一个 JSON 文件。已存在的词条会原样保留；你删除过的词条默认不复活；导入完成后会报告各自的条数。",
 	transferIncludeDeleted: "导入我删除过的词条",
 	transferIncludeDeletedHint: "勾选后，文件里那些你删除过的词条会被导入，并从「已删除」里撤回。不勾选则它们留在删除列表里。",
+	transferConfirmTitle: "「{name}」里有什么",
+	transferWillImport: "将导入 {count} 条",
+	transferWillSkipExisting: "已有 {count} 条（跳过）",
+	transferWillSkipDeleted: "你删过 {count} 条（默认跳过）",
+	transferConfirm: "确认导入",
+	transferShown: "已切到「全部」并清空搜索，好让刚导入的词条就在眼前。",
+	transferFolderTitle: "导入文件夹",
+	transferFolderHint: "选一个文件夹，把里面的 .json 全部读一遍（导出的词典、下载的包文件都认）。不是 JSON 的文件直接忽略；读不了的会点名列出。",
+	transferFolderAsGroup: "按文件夹建立分组（文件夹名就是组名）",
+	transferFolderLabel: "文件夹里的 {count} 个文件",
+	transferFolderFound: "文件夹里 {files} 个 .json，用上 {used} 个",
+	transferFolderSkipped: "跳过 {count} 个：",
+	transferFolderAllSkipped: "这个文件夹里 {count} 个 .json 都读不了",
+	transferNoJson: "这个文件夹里没有 .json 文件",
 	transferReport: "导入 {imported} 条；跳过：已存在 {existing} 条、你删除过 {deleted} 条、重复或无效 {duplicates} 条。",
 	transferFailed: "操作失败：{message}",
 	settingsBack: "返回词条列表",
@@ -146,6 +170,7 @@ const zh = {
 	packSourcesTitle: "源",
 	packSourcesHint: "源就是别人托管的一个静态 index.json。只接受 https（http、file、带账号密码的 URL 都会被拒）。",
 	packNoSources: "还没有添加源",
+	packBuiltInSource: "内置",
 	packRemoveSource: "移除",
 	packAddSourceLabel: "添加源",
 	packAddSourcePlaceholder: "https://cdn.jsdelivr.net/gh/…/index.json",
@@ -208,6 +233,25 @@ const zh = {
 	usageLabel: "用法示例",
 	notesLabel: "备注",
 	domainLabel: "领域",
+	groupLabel: "分组",
+	groupOpen: "进入这个分组",
+	groupGo: "回到「{name}」",
+	groupCount: "{count} 条",
+	groupEmpty: "这一层只有分组，还没有词条。",
+	groupSampleJoin: "、",
+	groupSampleMore: " 等 {count} 条",
+	groupRename: "重命名或移动",
+	groupRenameTo: "改到：",
+	groupRenameApply: "改名 / 移动",
+	groupDelete: "删除分组",
+	groupRenamed: "已移动 {count} 条词条。",
+	groupDeleted: "已删除 {count} 条词条，它们都在「已删除」里，可以撤回。",
+	groupDeleteConfirm: "删除分组「{name}」里的 {count} 条词条？它们会进入「已删除」，之后可以逐条撤回。",
+	"groupError_no-group": "那个分组不存在。",
+	"groupError_no-name": "分组名不能为空。",
+	"groupError_same": "新旧名字一样，没有需要动的地方。",
+	"groupError_into-itself": "不能把分组移动到它自己里面。",
+	groupPlaceholder: "留空 = 顶层；用 / 分层，例如 backend/net",
 	termPlaceholder: "例如 event sourcing",
 	glossPlaceholder: "用一两句话说明它的含义",
 	usagePlaceholder: "可选：一句例子或典型用法",
@@ -293,6 +337,16 @@ const en = {
 	explainLang_en: "English",
 	explainDepthName: "Explanation depth",
 	explainDepthHint: "How much the explanation says",
+	entryColumnsName: "Entry layout",
+	entryColumnsHint: "One column makes a very long strip; 自动 fills the panel width with as many columns as fit, and falls back to one when it is narrow.",
+	entryColumns_auto: "Auto",
+	entryColumns_1: "1 column",
+	entryColumns_2: "2 columns",
+	entryColumns_3: "3 columns",
+	entryRowsName: "Row height",
+	entryRowsHint: "In a multi-column layout, whether the cards in one row share a height. Uniform leaves no empty strip under the short ones; compact keeps each card tight.",
+	entryRows_uniform: "Uniform",
+	entryRows_compact: "Compact",
 	explainDepth_brief: "One line",
 	explainDepth_normal: "Normal",
 	explainDepth_detailed: "Detailed",
@@ -340,6 +394,7 @@ const en = {
 	packSourcesTitle: "Sources",
 	packSourcesHint: "A source is somebody's static index.json. Only https is accepted (http, file and URLs carrying credentials are refused).",
 	packNoSources: "No sources yet",
+	packBuiltInSource: "built in",
 	packRemoveSource: "Remove",
 	packAddSourceLabel: "Add a source",
 	packAddSourcePlaceholder: "https://cdn.jsdelivr.net/gh/…/index.json",
@@ -395,6 +450,20 @@ const en = {
 	transferImportHint: "Choose a JSON file. Entries you already have are left as they are, and entries you deleted stay deleted unless you say otherwise below; the counts are reported when it finishes.",
 	transferIncludeDeleted: "Import entries I deleted",
 	transferIncludeDeletedHint: "When ticked, entries in the file that you had deleted are imported and retracted from the deleted list. Unticked, they stay there.",
+	transferConfirmTitle: "What “{name}” holds",
+	transferWillImport: "{count} entries will be imported",
+	transferWillSkipExisting: "{count} already here (skipped)",
+	transferWillSkipDeleted: "{count} you deleted (skipped by default)",
+	transferConfirm: "Import them",
+	transferShown: "Moved to All and cleared the search, so what was imported is in front of you.",
+	transferFolderTitle: "Import a folder",
+	transferFolderHint: "Pick a folder and every .json inside it is read: exported dictionaries and downloaded pack files both. Files that are not JSON are ignored, and any that cannot be read are named.",
+	transferFolderAsGroup: "Build groups from the folders (the folder name is the group)",
+	transferFolderLabel: "{count} files in the folder",
+	transferFolderFound: "{files} .json files in the folder, {used} of them usable",
+	transferFolderSkipped: "{count} skipped:",
+	transferFolderAllSkipped: "none of the {count} .json files in that folder could be read",
+	transferNoJson: "that folder holds no .json files",
 	transferReport: "Imported {imported}; skipped {existing} already here, {deleted} you deleted, {duplicates} duplicate or unusable.",
 	transferFailed: "That did not work: {message}",
 	settingsBack: "Back to the entries",
@@ -479,6 +548,25 @@ const en = {
 	usageLabel: "Usage",
 	notesLabel: "Notes",
 	domainLabel: "Domain",
+	groupLabel: "Group",
+	groupOpen: "Open this group",
+	groupGo: "Go back to {name}",
+	groupCount: "{count} entries",
+	groupEmpty: "This level holds only groups so far.",
+	groupSampleJoin: ", ",
+	groupSampleMore: " and {count} more",
+	groupRename: "Rename or move",
+	groupRenameTo: "Move to:",
+	groupRenameApply: "Rename / move",
+	groupDelete: "Delete group",
+	groupRenamed: "Moved {count} entries.",
+	groupDeleted: "Deleted {count} entries. They are on the deleted list and can be restored one by one.",
+	groupDeleteConfirm: "Delete the {count} entries in “{name}”? They go to the deleted list, where each can be restored.",
+	"groupError_no-group": "There is no such group.",
+	"groupError_no-name": "A group needs a name.",
+	"groupError_same": "The name is unchanged, so there is nothing to move.",
+	"groupError_into-itself": "A group cannot be moved inside itself.",
+	groupPlaceholder: "empty = top level; use / to nest, e.g. backend/net",
 	termPlaceholder: "e.g. event sourcing",
 	glossPlaceholder: "Say what it means in one or two sentences",
 	usagePlaceholder: "Optional: an example or typical use",

package/lib/core/dictionary.js

@@ -285,6 +285,9 @@ function mergeRecords(record, notice, options) {
 		//
 		// So the comparison uses the newest time a record the USER asked for carries, and
 		// being strictly newer is what revives. Time alone is not intent; provenance is.
+		// A NAMED restoration first: `restoreEntry` records that the user asked for this term back, which
+		// is not an inference from a clock. The comparison below stays for the paths that revive by editing.
+		if ((record.restoredAt ?? 0) > notice.deletedAt) return { ...record, deletedAt: 0 };
 		if ((options?.craftedAt ?? 0) > notice.deletedAt) return { ...record, deletedAt: 0 };
 		const alreadyDeleted = record.deletedAt ?? 0;
 		return { ...record, deletedAt: Math.max(alreadyDeleted, notice.deletedAt) };
@@ -567,6 +570,10 @@ function editEntry(state, term, patch, options) {
 	const feedbackStamp = mentionsFeedback ? Math.max(stamp, (base.feedbackAt ?? 0) + 1) : base.feedbackAt ?? 0;
 	const untrustedPatch = typeof patch?.untrusted === "boolean" ? patch.untrusted : null;
 	const untrustedStamp = untrustedPatch === null ? base.untrustedAt ?? 0 : Math.max(stamp, (base.untrustedAt ?? 0) + 1);
+	// A move is a decision like a pin or a remark, and it is stamped strictly past the last one so that two
+	// moves inside the same millisecond still have an order.
+	const mentionsGroup = patch !== null && patch !== undefined && Object.prototype.hasOwnProperty.call(patch, "group");
+	const groupStamp = mentionsGroup ? Math.max(stamp, (base.groupAt ?? 0) + 1) : base.groupAt ?? 0;
 	const candidate = normalizeEntry(
 		{
 			...base,
@@ -575,6 +582,11 @@ function editEntry(state, term, patch, options) {
 			deletedAt: 0,
 			aliases: patch?.aliases ?? base.aliases,
 			domain: patch?.domain ?? base.domain,
+			// `patch.group` may legitimately be `""` — that is how an entry is moved back to the top level —
+			// so this reads with `hasOwnProperty` rather than with `??`: a patch that says nothing about the
+			// group must leave it, and its stamp, exactly where they were.
+			group: mentionsGroup ? patch.group : base.group,
+			groupAt: groupStamp,
 			definition: { ...base.definition, ...(patch?.definition ?? {}) },
 			source: "user",
 			confidence: 1,
@@ -592,6 +604,60 @@ function editEntry(state, term, patch, options) {
 	return upsertEntry(state, { ...candidate, source: "user", deletedAt: 0 }, { now: stamp });
 }
 
+/**
+ * Bring a deleted term back, as an explicit act rather than as a side effect of an edit.
+ *
+ * This exists because "restore this deleted term" is a decision, and until now it was expressed as "write
+ * an edit and hope the merge weighs it right": `editEntry` produced a crafted timestamp, and a merge
+ * revived the record when that timestamp beat the tombstone's. That works — there is a check for it — but
+ * it means the import path, the editor, a sighting and a second window all revive through one inferred
+ * comparison, and a term the user had collected and deleted came back as "nothing happened".
+ *
+ * So a restoration is its own thing:
+ *
+ *  - `restoredAt` is the evidence, weighed against `notice.deletedAt` like `pinnedAt` is weighed against
+ *    silence. It is what the merge reads, and it exists even when the tombstone's clock ran ahead;
+ *  - the tombstone is WITHDRAWN from the document this returns — the key leaves `deletedKeys` and the
+ *    record leaves `backing` — so a reader of this document is not told the term is deleted at all. Being
+ *    merely outvoted is what let a later merge put the deletion back;
+ *  - the text is kept: restoring is not the same as rewriting, so the patch is applied on top of whatever
+ *    the tombstone still remembers.
+ *
+ * @param state - the current document.
+ * @param idOrTerm - the entry id, term or alias.
+ * @param patch - `definition`, `domain`, `group`, `aliases`, `pinned`.
+ * @param options - `now` overrides the restoration time.
+ * @returns `{ state, entry, restored }`; `restored` is false when the term was not deleted.
+ */
+function restoreEntry(state, idOrTerm, patch, options) {
+	const found = findEntryIncludingDeleted(state, idOrTerm);
+	if (found === undefined) {
+		// Nothing to restore: the caller wanted a new entry, and `editEntry` is the path for that.
+		const created = editEntry(state, typeof idOrTerm === "string" ? idOrTerm : "", patch, options);
+		return { ...created, restored: false };
+	}
+	if ((found.deletedAt ?? 0) === 0) {
+		// Already live: a restoration must not disturb it, and saying "restored" would be a lie the caller
+		// might act on (the import reports it).
+		return { state, entry: found, restored: false };
+	}
+	// The stamp is strictly past the deletion for the same reason `editEntry`'s is: a clock that ran ahead
+	// must not let the tombstone win a comparison it lost the argument for.
+	const now = options?.now ?? Date.now();
+	const stamp = Math.max(now, (found.deletedAt ?? 0) + 1);
+	const edited = editEntry(state, found.term, { ...patch, definition: { ...found.definition, ...(patch?.definition ?? {}) } }, { now: stamp });
+	const key = found.key;
+	// The withdrawal, in the document itself: the record is rewritten live and the whole thing is re-sealed,
+	// so `deletedKeys` and `backing` are derived fresh and no longer announce the deletion. (An earlier
+	// version also filtered them by hand first, which the re-seal made redundant — a mutation proved it by
+	// not biting, so the dead work is gone.)
+	const records = recordsOf(edited.state).map((entry) =>
+		entry.id === found.id || entry.key === key ? { ...entry, deletedAt: 0, restoredAt: stamp, source: "user", updatedAt: stamp, lastSeenAt: stamp } : entry
+	);
+	const next = sealRecords(records, { now: stamp });
+	return { state: next, entry: next.entries.find((entry) => entry.key === key) ?? edited.entry, restored: true };
+}
+
 /**
  * Record one sighting of a term without replacing its meaning: the counters move
  * and a missing definition is filled from the glossary, but a curated definition
@@ -901,16 +967,139 @@ function summarize(state) {
 }
 
 /**
- * The panel's visible list: filter by query, then order pinned first, then most
- * recently seen.
+ * Move a group — and everything under it — to another path.
+ *
+ * Renaming and moving are the same act, because a group IS a path: renaming `backend` to `服务端` and moving
+ * `net` out of `backend` into `infra` are both "these entries live somewhere else now". One primitive, two
+ * names in the UI, so the two cannot drift apart.
+ *
+ * Each entry is moved through {@link editEntry}, so each carries the stamped decision (`groupAt`) a merge
+ * weighs — a bulk move is not an exception to "a move is a decision".
+ *
+ * Refused: an empty target, a target inside the group being moved (which would put it inside itself), and a
+ * target that leaves everything where it is. Renaming ONTO an existing group is allowed and merges the two,
+ * which is what a reader asking for it means.
+ *
+ * @param state - the current document.
+ * @param from - the path to move.
+ * @param to - the path to move it to.
+ * @param options - `now` overrides the timestamps.
+ * @returns `{ state, moved, error }`.
+ */
+function renameGroup(state, from, to, options) {
+	const source = typeof from === "string" ? from.replace(/^\/+|\/+$/g, "") : "";
+	const target = typeof to === "string" ? to.replace(/^\/+|\/+$/g, "") : "";
+	if (source === "") return { state, moved: 0, error: "no-group" };
+	if (target === "") return { state, moved: 0, error: "no-name" };
+	if (target === source) return { state, moved: 0, error: "same" };
+	if (target.startsWith(`${source}/`)) return { state, moved: 0, error: "into-itself" };
+	const now = options?.now ?? Date.now();
+	let next = state;
+	let moved = 0;
+	let stamp = now;
+	for (const entry of state.entries.filter((each) => each.deletedAt === 0 && (each.group === source || each.group.startsWith(`${source}/`)))) {
+		stamp += 1;
+		const rest = entry.group === source ? "" : entry.group.slice(source.length + 1);
+		next = editEntry(next, entry.term, { group: rest === "" ? target : `${target}/${rest}` }, { now: stamp }).state;
+		moved += 1;
+	}
+	return { state: next, moved, error: null };
+}
+
+/**
+ * Delete a group: every entry under it goes to the deleted list.
+ *
+ * Soft, like every other deletion here — the tombstones make it reversible from 「已删除」, and they are also
+ * what stops a passing pack from putting the terms straight back. A group therefore disappears when the last
+ * entry in it does, which is the same rule that made it appear.
+ *
+ * @param state - the current document.
+ * @param from - the path to empty.
+ * @param options - `now` overrides the timestamps.
+ * @returns `{ state, removed, error }`.
+ */
+function deleteGroup(state, from, options) {
+	const source = typeof from === "string" ? from.replace(/^\/+|\/+$/g, "") : "";
+	if (source === "") return { state, removed: 0, error: "no-group" };
+	const now = options?.now ?? Date.now();
+	let next = state;
+	let removed = 0;
+	let stamp = now;
+	for (const entry of state.entries.filter((each) => each.deletedAt === 0 && (each.group === source || each.group.startsWith(`${source}/`)))) {
+		stamp += 1;
+		next = removeEntry(next, entry.id, { now: stamp }).state;
+		removed += 1;
+	}
+	return { state: next, removed, error: null };
+}
+
+/**
+ * The groups immediately inside one path, with how many entries each holds.
+ *
+ * Only the immediate children: the list shows one level at a time, and a count covers everything under
+ * that child, however deep. A group exists as long as something is in it — there is no separate list of
+ * empty groups to keep in step with the entries, which is the trade this makes deliberately.
+ *
+ * Each group also carries a SAMPLE of the terms inside it. A folder row with only a name and a count is a
+ * row of empty space next to entries full of text — and a preview answers the question the row raises
+ * without making the reader open it to find out.
+ *
+ * @param entries - every live entry.
+ * @param prefix - the path to look inside, `""` for the top level.
+ * @returns `[{ group, name, count, sample }]`, alphabetical.
+ */
+/**
+ * How many terms a group's preview names before it stops.
+ *
+ * Three: enough to say what kind of thing is in there, few enough that the line stays one line in a
+ * multi-column layout.
+ */
+const GROUP_SAMPLE = 3;
+
+function groupsIn(entries, prefix) {
+	const base = prefix === undefined || prefix === null ? "" : String(prefix);
+	const counts = new Map();
+	const samples = new Map();
+	// Newest first, the order the list itself uses, so the preview is the top of what you would see inside.
+	const ordered = (Array.isArray(entries) ? entries : [])
+		.filter((entry) => (entry?.deletedAt ?? 0) === 0 && typeof entry?.term === "string" && entry.term !== "")
+		.slice()
+		.sort((left, right) => (right.createdAt ?? 0) - (left.createdAt ?? 0) || left.term.localeCompare(right.term));
+	for (const entry of ordered) {
+		if ((entry?.deletedAt ?? 0) !== 0) continue;
+		const group = typeof entry?.group === "string" ? entry.group : "";
+		if (group === "" || group === base) continue;
+		let inside = null;
+		if (base === "") inside = group;
+		else if (group.startsWith(`${base}/`)) inside = group.slice(base.length + 1);
+		if (inside === null || inside === "") continue;
+		const name = inside.split("/")[0];
+		counts.set(name, (counts.get(name) ?? 0) + 1);
+		const sample = samples.get(name) ?? [];
+		if (sample.length < GROUP_SAMPLE) sample.push(entry.term);
+		samples.set(name, sample);
+	}
+	return [...counts.entries()]
+		.map(([name, count]) => ({ group: base === "" ? name : `${base}/${name}`, name, count, sample: samples.get(name) ?? [] }))
+		.sort((left, right) => left.name.localeCompare(right.name));
+}
+
+/**
+ * The panel's visible list: one level of the group tree, filtered by query, then ordered by when each
+ * term was last seen.
  * @param state - the document.
  * @param query - search text.
  * @param filter - `all`, `unexplained`, `pinned` or `flagged`.
+ * @param group - the group path to look inside, `""` for the top level.
  * @returns the ordered entries.
  */
-function listEntries(state, query, filter) {
+function listEntries(state, query, filter, group) {
+	const base = group === undefined || group === null ? "" : String(group);
 	const matched = state.entries.filter((entry) => {
 		if (entry.deletedAt !== 0) return false;
+		// The list shows the level you are standing in, not everything below it: a group is a directory,
+		// and what is inside it is what you see after entering it.
+		if ((typeof entry.group === "string" ? entry.group : "") !== base) return false;
 		if (!matchesQuery(entry, query)) return false;
 		if (filter === "unexplained") return isUnexplained(entry);
 		if (filter === "pinned") return entry.pinned;
@@ -920,13 +1109,14 @@ function listEntries(state, query, filter) {
 		if (filter === "flagged") return isFlagged(entry);
 		return true;
 	});
-	return matched.sort(
-		(left, right) =>
-			Number(right.pinned) - Number(left.pinned) ||
-			Number(isUnexplained(left)) - Number(isUnexplained(right)) ||
-			right.lastSeenAt - left.lastSeenAt ||
-			left.term.localeCompare(right.term)
-	);
+	// Newest term first, and NOTHING ELSE.
+	//
+	// It used to sort pinned first and unexplained first, and it then sorted by when each term was last
+	// SEEN — every one of which moves a row under the reader's hand: pin a term and it jumped to the top,
+	// answer a prompt and it jumped, and the transcript merely mentioning a term again shuffled the list.
+	// Creation time is the one thing no action changes, so the list is still while the reader reads it.
+	// The pin is shown on the row itself and 「已钉选」 gathers the pinned ones, so ordering has no job left.
+	return matched.sort((left, right) => (right.createdAt ?? 0) - (left.createdAt ?? 0) || left.term.localeCompare(right.term));
 }
 
 /**
@@ -1068,6 +1258,9 @@ module.exports = {
 	tombstonesOf,
 	upsertEntry,
 	editEntry,
+	restoreEntry,
+	renameGroup,
+	deleteGroup,
 	recordSighting,
 	removeEntry,
 	reviveEntry,
@@ -1077,6 +1270,7 @@ module.exports = {
 	mergeState,
 	summarize,
 	listEntries,
+	groupsIn,
 	listDeleted,
 	createFileStore,
 	createBrowserStore

package/lib/core/entries.js

@@ -32,6 +32,15 @@ const MAX_CONTEXT_CHARS = 400;
 /** Upper bound on a feedback note, which is a remark rather than an explanation. */
 const MAX_NOTE_CHARS = 200;
 
+/**
+ * Upper bound on an entry's group path.
+ *
+ * A path rather than a name: a group can hold groups, because that is what a directory does and what a
+ * folder import produces. One string covers any depth, which is why nothing else had to be added to the
+ * document to get nesting.
+ */
+const MAX_GROUP_CHARS = 120;
+
 /**
  * What a user can say is wrong with an entry.
  *
@@ -121,6 +130,25 @@ function normalizeEntry(value, options) {
 			notes: clampText(definition.notes, MAX_DEFINITION_CHARS)
 		},
 		domain: clampText(value.domain, 24),
+		/**
+		 * The group (folder) this entry lives in: `""` for the top level, or a `/`-separated path.
+		 *
+		 * A CONTAINER, not a topic: `domain` is a semantic label the reader assigns, while this is where
+		 * the entry was put. It needs its own stamp (§ `groupAt`) because a move is a decision — the first
+		 * attempt let it ride on the content merge, and a merge of one entry from two windows then wiped
+		 * the group order-dependently.
+		 */
+		group: clampText(value.group, MAX_GROUP_CHARS),
+		// When the group was last decided, epoch milliseconds, 0 for "never moved".
+		//
+		// The third use of this pattern, and for the reason the other two exist: a decision the user can
+		// make and unmake cannot be carried by content-merging rules.
+		// When the user restored this term, epoch milliseconds, 0 for never.
+		//
+		// The named evidence a merge weighs against a deletion, so a restoration does not have to win a
+		// contest over a clock — see `restoreEntry`.
+		restoredAt: typeof value.restoredAt === "number" && Number.isFinite(value.restoredAt) && value.restoredAt > 0 ? Math.floor(value.restoredAt) : 0,
+		groupAt: typeof value.groupAt === "number" && Number.isFinite(value.groupAt) && value.groupAt > 0 ? Math.floor(value.groupAt) : 0,
 		source: SOURCES.includes(value.source) ? value.source : "auto",
 		confidence: typeof value.confidence === "number" && value.confidence >= 0 && value.confidence <= 1 ? value.confidence : 0.5,
 		createdAt: typeof value.createdAt === "number" && value.createdAt > 0 ? value.createdAt : now,
@@ -302,6 +330,12 @@ function mergeEntry(current, incoming, options) {
 		aliases: [...new Set([...current.aliases, ...incoming.aliases])].slice(0, 8),
 		definition: takeDefinition ? incoming.definition : current.definition,
 		domain: takeDefinition && incoming.domain !== "" ? incoming.domain : current.domain,
+		// Unlike the domain, an empty incoming group is taken when the content changed: moving an entry back
+		// to the top level is a move, and the old rule ("an empty value never overwrites") would make the
+		// top level unreachable for anything that had ever been filed.
+		group: (incoming.groupAt ?? 0) > (current.groupAt ?? 0) ? incoming.group : current.group,
+		groupAt: Math.max(incoming.groupAt ?? 0, current.groupAt ?? 0),
+		restoredAt: Math.max(incoming.restoredAt ?? 0, current.restoredAt ?? 0),
 		// The STRONGEST provenance survives, not the arriving one. Taking the arriving
 		// source let a later automatic copy of an already-curated term downgrade it to
 		// `auto`, which then denied that term its own revival — and let its source be
@@ -405,6 +439,7 @@ module.exports = {
 	MAX_DEFINITION_CHARS,
 	MAX_CONTEXT_CHARS,
 	MAX_NOTE_CHARS,
+	MAX_GROUP_CHARS,
 	normalizeEntry,
 	normalizeFeedback,
 	entryAsText,

package/lib/core/hover.js

@@ -199,6 +199,45 @@ function createHoverLayer(options) {
 		return null;
 	}
 
+	/**
+	 * How far left of the caret a pointer may still count as being on the text.
+	 *
+	 * The space before a word is enough: landing in it resolves the caret to the word's own start, and a
+	 * reader aiming at the first letter often lands there. A paragraph's left margin is tens of pixels, which
+	 * is what this has to reject.
+	 */
+	const LEFT_TOLERANCE_PX = 8;
+
+	/**
+	 * Whether the caret a point resolved to actually sits at that point.
+	 *
+	 * `caretRangeFromPoint` CLAMPS horizontally: a point in the left margin of a line resolves to the line's
+	 * start, offset 0. When a term begins that line, offset 0 IS that term — so every point from the panel's
+	 * left edge to the first character read as "on the term", and the card opened from anywhere in the margin,
+	 * with a click to match. That is how this was reported.
+	 *
+	 * The caret's own rectangle is the live proof of where the text is: it is measured from the document at
+	 * this instant, so unlike a block snapshot it cannot go stale. One measurement per event, and only once a
+	 * caret has been found at all.
+	 *
+	 * @param x - viewport x of the pointer.
+	 * @param caret - the Range the point resolved to.
+	 * @returns true when the caret is at the pointer rather than clamped to the start of a line.
+	 */
+	function caretIsAt(x, caret) {
+		let rect = null;
+		try {
+			rect = typeof caret?.getBoundingClientRect === "function" ? caret.getBoundingClientRect() : null;
+		} catch (error) {
+			rect = null;
+		}
+		// A browser (or a fixture) that cannot answer is trusted: refusing every hover because one optional
+		// measurement is missing would be a worse failure than the one being fixed. An all-zero rectangle says
+		// the same thing in another shape — a detached or not-yet-laid-out range.
+		if (rect === null || (rect.left === 0 && rect.top === 0 && rect.width === 0 && rect.height === 0)) return true;
+		return rect.left <= x + LEFT_TOLERANCE_PX;
+	}
+
 	/**
 	 * The marked occurrence under a point.
 	 *
@@ -213,6 +252,7 @@ function createHoverLayer(options) {
 	function matchAt(x, y) {
 		const caret = caretAt(x, y);
 		if (caret === null) return null;
+		if (!caretIsAt(x, caret)) return null;
 		const at = resolveCaret(caret, doc);
 		if (at === null) return null;
 		let best = null;

package/lib/core/pack.js

@@ -160,28 +160,41 @@ function buildPack(entries, options) {
 }
 
 /**
- * Read a pack from whatever arrived: a fetched file, or a decoded share code.
+ * Read a pack from whatever arrived: a fetched file, a decoded share code, or the text of either.
  *
  * Tolerant about unknown keys in the envelope, strict about the two things that make it a pack: its
  * marker and at least one usable entry. Every record goes through the same validator an imported file
  * does, so a record that cannot be imported is a record this refuses.
  *
- * @param raw - the parsed value.
+ * Accepts TEXT as well as a parsed object, because text is what actually arrives: the host fetches the
+ * file and passes the body on. Accepting only an object made every source and every pack answer
+ * `not-an-object` — a feature that refuses everything, in the shape of a bad URL.
+ *
+ * @param raw - the fetched body, the decoded text, or the parsed value.
  * @returns `{ ok: true, pack }`, or `{ ok: false, error }`.
  */
 function parsePack(raw) {
-	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return { ok: false, error: "not-an-object" };
-	if (raw.kind !== PACK_KIND) return { ok: false, error: "not-a-pack" };
-	if (raw.version !== PACK_VERSION) return { ok: false, error: "unsupported-version" };
-	if (!Array.isArray(raw.entries)) return { ok: false, error: "no-entries" };
-	if (raw.entries.length > MAX_PACK_ENTRIES) return { ok: false, error: "too-many" };
+	let value = raw;
+	if (typeof raw === "string") {
+		try {
+			value = JSON.parse(raw);
+		} catch (error) {
+			return { ok: false, error: "not-json" };
+		}
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return { ok: false, error: "not-an-object" };
+	const raw2 = value;
+	if (raw2.kind !== PACK_KIND) return { ok: false, error: "not-a-pack" };
+	if (raw2.version !== PACK_VERSION) return { ok: false, error: "unsupported-version" };
+	if (!Array.isArray(raw2.entries)) return { ok: false, error: "no-entries" };
+	if (raw2.entries.length > MAX_PACK_ENTRIES) return { ok: false, error: "too-many" };
 	const entries = [];
-	for (const record of raw.entries) {
+	for (const record of raw2.entries) {
 		const entry = transfer.toEntry(record);
 		if (entry !== null) entries.push(record);
 	}
 	if (entries.length === 0) return { ok: false, error: "no-usable-entries" };
-	const scope = raw.scope !== null && typeof raw.scope === "object" && raw.scope.kind === "domains" ? "domains" : "all";
+	const scope = raw2.scope !== null && typeof raw2.scope === "object" && raw2.scope.kind === "domains" ? "domains" : "all";
 	return {
 		ok: true,
 		pack: {
@@ -280,17 +293,31 @@ function buildIndex(packs, options) {
  * in somebody's index must not hide the other forty packs. An index with nothing usable left is a
  * refusal, because a source that offers nothing is a source that is misconfigured or moved.
  *
- * @param raw - the parsed value.
+ * Takes TEXT or a parsed object, like {@link parsePack} — and the text form is the one production uses:
+ * the host fetches the source and hands the body straight over. Requiring an object here while the host
+ * sends text meant every source answered `not-an-object`, which is a whole feature answering "no" in a
+ * way that looks like the user's URL was wrong.
+ *
+ * @param raw - the fetched body, or the parsed value.
  * @returns `{ ok: true, index, dropped }`, or `{ ok: false, error }`.
  */
 function parseIndex(raw) {
-	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return { ok: false, error: "not-an-object" };
-	if (raw.kind !== INDEX_KIND) return { ok: false, error: "not-an-index" };
-	if (raw.version !== INDEX_VERSION) return { ok: false, error: "unsupported-version" };
-	if (!Array.isArray(raw.packs)) return { ok: false, error: "no-packs" };
+	let value = raw;
+	if (typeof raw === "string") {
+		try {
+			value = JSON.parse(raw);
+		} catch (error) {
+			return { ok: false, error: "not-json" };
+		}
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return { ok: false, error: "not-an-object" };
+	const raw2 = value;
+	if (raw2.kind !== INDEX_KIND) return { ok: false, error: "not-an-index" };
+	if (raw2.version !== INDEX_VERSION) return { ok: false, error: "unsupported-version" };
+	if (!Array.isArray(raw2.packs)) return { ok: false, error: "no-packs" };
 	const packs = [];
 	let dropped = 0;
-	for (const pack of raw.packs) {
+	for (const pack of raw2.packs) {
 		if (pack === null || typeof pack !== "object") {
 			dropped++;
 			continue;