dsh-plugin-term-dictionary 1.0.0 → 1.1.0

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,12 @@ const zh = {
 	usageLabel: "用法示例",
 	notesLabel: "备注",
 	domainLabel: "领域",
+	groupLabel: "分组",
+	groupOpen: "进入这个分组",
+	groupGo: "回到「{name}」",
+	groupCount: "{count} 条",
+	groupEmpty: "这一层只有分组，还没有词条。",
+	groupPlaceholder: "留空 = 顶层；用 / 分层，例如 backend/net",
 	termPlaceholder: "例如 event sourcing",
 	glossPlaceholder: "用一两句话说明它的含义",
 	usagePlaceholder: "可选：一句例子或典型用法",
@@ -293,6 +324,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 +381,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 +437,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 +535,12 @@ 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.",
+	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,51 @@ function summarize(state) {
 }
 
 /**
- * The panel's visible list: filter by query, then order pinned first, then most
- * recently seen.
+ * 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.
+ *
+ * @param entries - every live entry.
+ * @param prefix - the path to look inside, `""` for the top level.
+ * @returns `[{ group, name, count }]`, alphabetical.
+ */
+function groupsIn(entries, prefix) {
+	const base = prefix === undefined || prefix === null ? "" : String(prefix);
+	const counts = new Map();
+	for (const entry of Array.isArray(entries) ? entries : []) {
+		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);
+	}
+	return [...counts.entries()]
+		.map(([name, count]) => ({ group: base === "" ? name : `${base}/${name}`, name, count }))
+		.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 +1021,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 +1170,7 @@ module.exports = {
 	tombstonesOf,
 	upsertEntry,
 	editEntry,
+	restoreEntry,
 	recordSighting,
 	removeEntry,
 	reviveEntry,
@@ -1077,6 +1180,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/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;

package/lib/core/settings.js

@@ -23,12 +23,34 @@ const SETTINGS_KEY = "dsh-plugin-term-dictionary:settings:v1";
 /** The most sources the list will hold. A UI bound, not a security one. */
 const MAX_SOURCES = 12;
 
+/**
+ * The source a fresh install starts with: this plugin's own repository, as a static file.
+ *
+ * Why ship one at all: without it the packs page opens on an empty list, and a first-time reader has
+ * to be TOLD a URL before they can see what a term pack even is. The alternative — fetching from a
+ * server we run — is the thing this design refuses to have, so the default is an ordinary source like
+ * any other: visible in the list, removable in one press, and fetched only when the reader asks (the
+ * page refreshes it on first open, which is a request to the source THEY have configured).
+ *
+ * `@main` rather than a tag because a default should follow the packs the repository actually has:
+ * pinned to a tag, a new pack would need a plugin release before anyone could see it.
+ */
+const DEFAULT_PACK_SOURCE = "https://cdn.jsdelivr.net/gh/lakerian/dsh-plugin-term-dictionary@main/packs/index.json";
+
 /**
  * The URL rule, imported rather than restated: the settings store, the page and the host's transport
  * must agree on what a usable source is, and two copies of that rule is how one of them drifts.
  */
 const { refuseUrl } = require("./pack.js");
 
+const ENTRY_COLUMNS = ["auto", "1", "2", "3"];
+
+/** The two row-height readings: equal cards, or each card as tall as its own text. */
+const ENTRY_ROWS = ["uniform", "compact"];
+
+/** The narrowest a column may be when the layout is choosing. Below this a gloss wraps every other word. */
+const MIN_COLUMN_PX = 260;
+
 /**
  * The three switches and their defaults.
  *
@@ -80,6 +102,23 @@ const DEFAULT_SETTINGS = {
 	 * the pointer had gone. Anyone who wants a grace period may have one; nobody gets it by accident.
 	 */
 	hoverOutMs: 0,
+	/**
+	 * How many columns the entry list is laid out in.
+	 *
+	 * `auto` fits as many as the panel is wide enough for, and is the default: a dictionary row is
+	 * short, a single column of them is a very long strip to read, and a narrow panel simply gets one
+	 * column back. The fixed values exist for a reader who wants the layout to stop moving under them.
+	 */
+	entryColumns: "auto",
+	/**
+	 * How tall a row of the entry list is.
+	 *
+	 * `uniform` gives every card in a grid row the height of the tallest, so the cards line up and no
+	 * empty strip is left under the short ones. `compact` lets each keep its own height, which reads
+	 * tighter in a single column and leaves exactly those strips in a grid. Both are defensible, which
+	 * is why it is a preference rather than a constant.
+	 */
+	entryRows: "uniform",
 	/**
 	 * The term-pack sources the user added: https URLs of static `index.json` files.
 	 *
@@ -88,8 +127,13 @@ const DEFAULT_SETTINGS = {
 	 * is not configuration. Validated by the same rule the host applies before it fetches anything
 	 * ({@link module:core/pack.refuseUrl}), so the page and the transport cannot disagree about what a
 	 * usable source is.
+	 *
+	 * The default is not empty: see {@link DEFAULT_PACK_SOURCE}. An ABSENT key means "never touched, use
+	 * the default"; an empty array means "the reader removed them all", which is honoured (§
+	 * `normalizeSettings`) — the two are different statements and a store that conflated them would
+	 * resurrect the default every time somebody cleared the list.
 	 */
-	packSources: []
+	packSources: [DEFAULT_PACK_SOURCE]
 };
 
 /** The accepted minimum term lengths, for the panel's cycling control. */
@@ -195,7 +239,13 @@ function normalizeSettings(raw) {
 		collectCjk: readFlag(value.collectCjk, DEFAULT_SETTINGS.collectCjk),
 		hoverInMs: readDelay(value.hoverInMs, DEFAULT_SETTINGS.hoverInMs),
 		hoverOutMs: readDelay(value.hoverOutMs, DEFAULT_SETTINGS.hoverOutMs),
-		packSources: readSources(value.packSources)
+		entryColumns: readChoice(value.entryColumns, ENTRY_COLUMNS, DEFAULT_SETTINGS.entryColumns),
+		entryRows: readChoice(value.entryRows, ENTRY_ROWS, DEFAULT_SETTINGS.entryRows),
+		// Absent means "never touched" and gets the shipped default; an empty array means the reader
+		// removed every source, and is kept as it is. A fresh array either way: a snapshot is compared by
+		// identity, so handing back the shared default array would make one page's edit appear in
+		// another page's defaults.
+		packSources: value.packSources === undefined ? [...DEFAULT_SETTINGS.packSources] : readSources(value.packSources)
 	};
 }
 
@@ -303,6 +353,10 @@ module.exports = {
 	DEFAULT_SETTINGS,
 	normalizeSettings,
 	MAX_SOURCES,
+	DEFAULT_PACK_SOURCE,
+	ENTRY_COLUMNS,
+	ENTRY_ROWS,
+	MIN_COLUMN_PX,
 	EXPLAIN_LANGS,
 	EXPLAIN_DEPTHS,
 	COLLECT_LENGTHS,

package/lib/core/store.js

@@ -201,6 +201,21 @@ function createDictionaryStore(options) {
 			return result.entry;
 		},
 
+		/**
+		 * Bring a deleted term back, as an explicit act.
+		 *
+		 * See `restoreEntry` in the core: a restoration is a decision with its own evidence and it
+		 * withdraws the tombstone, rather than an edit that has to win a comparison on the way to the host.
+		 * @param idOrTerm - the entry id, term or alias.
+		 * @param patch - the text to restore it with, if any.
+		 * @returns a promise resolving to `{ entry, restored }`.
+		 */
+		async restoreEntry(idOrTerm, patch) {
+			const result = dictionary.restoreEntry(state, idOrTerm, patch, { now: now() });
+			if (result.restored) await commit(result.state);
+			return { entry: result.entry, restored: result.restored };
+		},
+
 		/**
 		 * Record that a term appeared in a message, without overwriting a definition
 		 * the user wrote.
@@ -327,17 +342,29 @@ function createDictionaryStore(options) {
 			return this.saveEntry(found.term, patch);
 		},
 
+		/**
+		 * The groups directly inside one path, each with how many entries it holds.
+		 * @param prefix - the path to look inside, `""` for the top level.
+		 * @returns `[{ group, name, count }]`.
+		 */
+		groups(prefix) {
+			return dictionary.groupsIn(state.entries, prefix);
+		},
+
 		/**
 		 * The visible list for the panel.
 		 * @param query - search text.
 		 * @param filter - `all`, `unexplained`, `pinned`, `deleted` or `flagged`.
+		 * @param group - the group path to look inside, `""` for the top level.
 		 * @returns the ordered entries. For `deleted`, the tombstones.
 		 */
-		list(query, filter) {
+		list(query, filter, group) {
+			const at = group === undefined || group === null ? "" : String(group);
 			// The deleted view is a different LIST rather than a different filter: tombstones live in
-			// `backing`, not in `entries`, so no predicate over the live list could ever show one.
-			if (filter === "deleted") return dictionary.listDeleted(state, query);
-			return listEntries(state, query, filter);
+			// `backing`, not in `entries`, so no predicate over the live list could ever show one. The group
+			// still applies — standing in a folder and asking what was deleted there means that folder.
+			if (filter === "deleted") return dictionary.listDeleted(state, query).filter((entry) => (typeof entry.group === "string" ? entry.group : "") === at);
+			return listEntries(state, query, filter, at);
 		},
 
 		/**

package/lib/core/styles.js

@@ -124,6 +124,23 @@ const applyStyles = {
 		boxShadow: "0 0 0 1px var(--dsw-alias-brand-primary, #4d6bfe)"
 	},
 	rowHead: { display: "flex", alignItems: "center", gap: "6px", flexWrap: "wrap" },
+	/** Where you are, and the way back up: a directory you can only enter is a trap. */
+	breadcrumb: { display: "flex", alignItems: "center", gap: "2px", flexWrap: "wrap", padding: "2px 0 6px", fontSize: "12px" },
+	breadcrumbPart: { display: "inline-flex", alignItems: "center", gap: "2px" },
+	breadcrumbSep: { color: "var(--dsw-alias-label-tertiary)", margin: "0 2px" },
+	breadcrumbButton: { appearance: "none", border: "none", background: "none", padding: "2px 4px", font: "inherit", fontSize: "12px", color: "var(--dsw-alias-brand-primary, #4d6bfe)", cursor: "pointer" },
+	breadcrumbHere: { appearance: "none", border: "none", background: "none", padding: "2px 4px", font: "inherit", fontSize: "12px", color: "var(--dsw-alias-label-secondary)", cursor: "default" },
+	/** The group row's own bits: the mark that says "not an entry", and the chevron that says "opens". */
+	groupIcon: { display: "inline-flex", alignItems: "center", color: "var(--dsw-alias-label-secondary)" },
+	groupEnter: { color: "var(--dsw-alias-label-tertiary)", fontSize: "14px", lineHeight: 1 },
+	/**
+	 * The row's action toolbar: the second line, always.
+	 *
+	 * On the title line the controls moved from row to row with the length of the term and the number of
+	 * badges; a line of their own puts every row's controls in the same place and keeps them out of the
+	 * way of the text they act on.
+	 */
+	rowActions: { display: "flex", alignItems: "center", gap: "6px", marginTop: "2px" },
 	termButton: {
 		appearance: "none",
 		background: "transparent",