dsh-quick-actions 0.1.0-rc.3

package/lib/index.js

@@ -0,0 +1,737 @@
+import Schema from "@deepseek-ai/schemastery";
+//#region src/model/types.ts
+/** Every layout value, in the order the management panel offers them. */
+const QUICK_ACTION_LAYOUTS = [
+	"ribbon",
+	"bar",
+	"launcher"
+];
+/**
+* The identity of a reference as one comparable string. Source and id together
+* are the identity: the same id under a different source is a different action.
+*/
+function quickActionRefKey(ref) {
+	return `${ref.source}:${ref.id}`;
+}
+//#endregion
+//#region src/model/json.ts
+/**
+* JSON structural comparison shared by the mutation planner and the Host's
+* canonical rewrite.
+*
+* Structural, not canonical-JSON: object key order carries no meaning here.
+* A stored section round-tripped through YAML, and a tombstone written by a
+* higher version, both come back with whatever key order their writer chose —
+* comparing serialized text would report a difference that is not one, and the
+* rewrite would then write on every start instead of being idempotent.
+*/
+function deepEqualJson(left, right) {
+	if (left === right) return true;
+	if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false;
+	if (Array.isArray(left) || Array.isArray(right)) {
+		if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+		return left.every((item, index) => deepEqualJson(item, right[index]));
+	}
+	const leftKeys = Object.keys(left);
+	const rightKeys = Object.keys(right);
+	if (leftKeys.length !== rightKeys.length) return false;
+	return leftKeys.every((key) => Object.hasOwn(right, key) && deepEqualJson(left[key], right[key]));
+}
+//#endregion
+//#region src/model/text.ts
+/**
+* Unicode primitives shared by every Quick Action entry point (spec 4.3).
+* Config loading, the management form, migration and Settings mutations must all
+* measure and trim text through these functions so one rule cannot drift from another.
+*/
+/**
+* Reference placeholder code points DSH reserves and strips inside `setDraft`:
+* the reference marker block plus the legacy object replacement character.
+* Static text carrying one of them would submit something other than what the
+* user configured, so the model rejects it as a field error (spec 4.3).
+*
+* Source: `REFERENCE_PLACEHOLDER_RE` in `@deepseek-ai/dsh-client-ui-conversation`
+* (`lib/client.js`, input machine), applied by `setDraft` before it rebuilds the
+* draft. Verified identical in 0.1.1-rc.2, 0.1.2-rc.1 and 0.1.5-rc.1 — the release
+* that renamed `imageIds` left this range untouched (ticket 29). Its tail is
+* published as a named constant, which 0.1.5-rc.1 moved and renamed:
+* `PLACEHOLDER = "\uFFFC"` in `lib/types/client/input/machine.d.ts` became
+* `ATOMIC_CHAR = "\uFFFC"` in `lib/types/client/input/editor/projection.d.ts`.
+* Re-check this range when the supported DSH range moves.
+*/
+const RESERVED_REFERENCE_PLACEHOLDER = /[\u{E100}-\u{E11D}\u{FFFC}]/u;
+/** Unicode code point length — the counting unit for every length limit (spec 4.3). */
+function countCodePoints(value) {
+	let count = 0;
+	for (const _ of value) count += 1;
+	return count;
+}
+/** Whether a text holds no character outside ECMAScript `trim()` whitespace (spec 4.3). */
+function isBlankQuickActionText(text) {
+	return text.trim().length === 0;
+}
+/** Whether a text carries a DSH-reserved reference placeholder code point (spec 4.3). */
+function containsReservedReferencePlaceholder(text) {
+	return RESERVED_REFERENCE_PLACEHOLDER.test(text);
+}
+/** Code points allowed to appear inside an emoji grapheme cluster. */
+const EMOJI_CLUSTER_MEMBER = /^[\p{Extended_Pictographic}\p{Emoji_Component}\p{Emoji_Modifier}\u{FE0E}\u{FE0F}\u{200D}]+$/u;
+/** A keycap sequence carries no pictographic code point of its own. */
+const KEYCAP_CLUSTER = /^[0-9#*]\u{FE0F}?\u{20E3}$/u;
+/** A flag is a pair of regional indicators, also without a pictographic code point. */
+const FLAG_CLUSTER = /^\p{Regional_Indicator}{2}$/u;
+const graphemeSegmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
+function isEmojiCluster(cluster) {
+	if (!EMOJI_CLUSTER_MEMBER.test(cluster)) return false;
+	return /\p{Extended_Pictographic}/u.test(cluster) || KEYCAP_CLUSTER.test(cluster) || FLAG_CLUSTER.test(cluster);
+}
+/**
+* Segment an icon candidate into grapheme clusters and report whether each one
+* is an emoji cluster, so validation can tell `too-long` from `not-emoji`.
+*/
+function scanEmojiClusters(icon) {
+	let clusters = 0;
+	let emojiOnly = true;
+	for (const { segment } of graphemeSegmenter.segment(icon)) {
+		clusters += 1;
+		if (!isEmojiCluster(segment)) emojiOnly = false;
+	}
+	return {
+		clusters,
+		emojiOnly
+	};
+}
+/** Trimmed label, or the reason it cannot be stored. */
+function labelIssue(label) {
+	const trimmed = label.trim();
+	if (trimmed.length === 0) return {
+		field: "label",
+		reason: "blank"
+	};
+	if (countCodePoints(trimmed) > 40) return {
+		field: "label",
+		reason: "too-long"
+	};
+}
+/** The reason a static text cannot be stored, if any. */
+function textIssue(text) {
+	if (isBlankQuickActionText(text)) return {
+		field: "text",
+		reason: "blank"
+	};
+	if (countCodePoints(text) > 4e3) return {
+		field: "text",
+		reason: "too-long"
+	};
+	if (containsReservedReferencePlaceholder(text)) return {
+		field: "text",
+		reason: "reserved-placeholder"
+	};
+}
+/** The reason a non-empty icon cannot be stored, if any. */
+function iconIssue(icon) {
+	const { clusters, emojiOnly } = scanEmojiClusters(icon);
+	if (!emojiOnly) return {
+		field: "icon",
+		reason: "not-emoji"
+	};
+	if (clusters > 4) return {
+		field: "icon",
+		reason: "too-long"
+	};
+}
+const FNV_OFFSET_BASIS = 144066263297769815596495629667062367629n;
+const FNV_PRIME = 309485009821345068724781371n;
+const FNV_MASK = (1n << 128n) - 1n;
+function fnv1a128(value) {
+	let hash = FNV_OFFSET_BASIS;
+	for (const byte of new TextEncoder().encode(value)) hash = (hash ^ BigInt(byte)) * FNV_PRIME & FNV_MASK;
+	return hash.toString(16).padStart(32, "0");
+}
+/**
+* Hash the whole catalog projection, field by field and in order, so that any
+* change a client could observe — including a pure reordering — moves the
+* revision, and an unchanged catalog never does (spec 6.2).
+*/
+function revisionOf(presets) {
+	return fnv1a128(JSON.stringify([1, presets.map((preset) => [
+		preset.id,
+		preset.kind,
+		preset.label,
+		preset.text,
+		preset.icon ?? null,
+		preset.confirm
+	])]));
+}
+function fieldIssue(field, reason) {
+	return {
+		field,
+		reason
+	};
+}
+function readId(entry) {
+	const { id } = entry;
+	if (id === void 0) return { issue: fieldIssue("id", "missing") };
+	if (typeof id !== "string") return { issue: fieldIssue("id", "invalid-type") };
+	if (id.trim().length === 0) return { issue: fieldIssue("id", "blank") };
+	return { id };
+}
+function readPreset(entry, id) {
+	if (entry.kind !== void 0 && entry.kind !== "send") return { issue: fieldIssue("kind", "unsupported") };
+	const { label, text, icon, confirm } = entry;
+	if (typeof label !== "string") return { issue: fieldIssue("label", label === void 0 ? "missing" : "invalid-type") };
+	const labelProblem = labelIssue(label);
+	if (labelProblem !== void 0) return { issue: labelProblem };
+	if (typeof text !== "string") return { issue: fieldIssue("text", text === void 0 ? "missing" : "invalid-type") };
+	const textProblem = textIssue(text);
+	if (textProblem !== void 0) return { issue: textProblem };
+	if (icon !== void 0 && typeof icon !== "string") return { issue: fieldIssue("icon", "invalid-type") };
+	if (icon === "") return { issue: fieldIssue("icon", "blank") };
+	if (icon !== void 0) {
+		const iconProblem = iconIssue(icon);
+		if (iconProblem !== void 0) return { issue: iconProblem };
+	}
+	if (confirm !== void 0 && typeof confirm !== "boolean") return { issue: fieldIssue("confirm", "invalid-type") };
+	return { preset: {
+		id,
+		kind: "send",
+		label: label.trim(),
+		text,
+		...icon === void 0 ? {} : { icon },
+		confirm: confirm ?? true
+	} };
+}
+/**
+* Merge and validate the built-in manifest with the Host composition's presets.
+* Nothing is repaired or dropped: the first release refuses to load a catalog an
+* author got wrong, so the mistake surfaces at startup rather than at send time.
+*/
+function buildPresetCatalog(input) {
+	const issues = [];
+	const presets = [];
+	const seen = /* @__PURE__ */ new Set();
+	const sources = [["builtin", input.builtins], ["config", input.configured]];
+	for (const [source, entries] of sources) for (const [index, entry] of entries.entries()) {
+		const at = (issue, id) => ({
+			scope: "preset",
+			source,
+			index,
+			id,
+			field: issue.field,
+			reason: issue.reason
+		});
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+			issues.push(at(fieldIssue("id", "invalid-type"), void 0));
+			continue;
+		}
+		const record = entry;
+		const identity = readId(record);
+		if ("issue" in identity) {
+			issues.push(at(identity.issue, void 0));
+			continue;
+		}
+		if (seen.has(identity.id)) {
+			issues.push(at(fieldIssue("id", "duplicate"), identity.id));
+			continue;
+		}
+		const read = readPreset(record, identity.id);
+		if ("issue" in read) {
+			issues.push(at(read.issue, identity.id));
+			continue;
+		}
+		seen.add(identity.id);
+		presets.push(read.preset);
+	}
+	const count = input.builtins.length + input.configured.length;
+	if (count > 50) issues.push({
+		scope: "catalog",
+		reason: "too-many",
+		count,
+		limit: 50
+	});
+	if (issues.length > 0) return {
+		ok: false,
+		issues
+	};
+	return {
+		ok: true,
+		catalog: {
+			schemaVersion: 1,
+			revision: revisionOf(presets),
+			presets
+		}
+	};
+}
+//#endregion
+//#region src/model/settings.ts
+/**
+* Settings V1 decoding (spec 4.2, 6.3). Decoding is defensive and lossless: it
+* coerces shapes it recognises, falls back to documented defaults, and preserves
+* anything it cannot render as a tombstone rather than repairing or dropping it.
+* Catalog-aware canonicalization lives in `normalize.ts`.
+*/
+/**
+* The one namespace holding user data (spec 4.2); renaming it orphans every
+* stored section. It lives in the shared model because both faces address it:
+* the Host registers it, the Client binds the same name.
+*/
+const QUICK_ACTIONS_SETTINGS_NAMESPACE = "composer-quick-actions";
+/**
+* The read-only namespace carrying the Preset Catalog to Clients (spec 17.2).
+* The plugin never writes its user layer, so it holds no persisted section —
+* `composer-quick-actions` remains the only persisted namespace (spec 4.2).
+*/
+const QUICK_ACTIONS_CATALOG_NAMESPACE = "composer-quick-actions-catalog";
+/** The state a fresh install starts from (spec 4.2). */
+const DEFAULT_QUICK_ACTION_SETTINGS = Object.freeze({
+	schemaVersion: 1,
+	layout: "ribbon",
+	userActionsById: Object.freeze({}),
+	actionOrder: Object.freeze([]),
+	presetStateById: Object.freeze({})
+});
+function asRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	return value;
+}
+/**
+* Whether a stored entry is a live Send Action this release can render.
+* Everything else is a tombstone: a higher version's `kind`, or a value whose
+* label/text are not readable strings.
+*/
+function isLiveQuickAction(value) {
+	return value.kind === "send" && typeof value.label === "string" && typeof value.text === "string";
+}
+function decodeLayout(value) {
+	return QUICK_ACTION_LAYOUTS.find((layout) => layout === value) ?? DEFAULT_QUICK_ACTION_SETTINGS.layout;
+}
+/**
+* Read one stored custom action into canonical form. A missing `kind` reads as
+* `'send'` because V1 always writes the tag; anything else marks a tombstone and
+* is handed straight back by identity, so a value written by a higher version
+* survives the round trip intact.
+*
+* A live result always carries `kind`, `confirm` and `enabled` explicitly, which
+* is what spec 4.3 requires of every normalized action. `confirm` is only
+* defaulted when it is absent — never derived from the text.
+*/
+function decodeStoredQuickAction(value) {
+	const entry = asRecord(value);
+	if (entry === void 0) return void 0;
+	if ((entry.kind ?? "send") !== "send" || typeof entry.label !== "string" || typeof entry.text !== "string") return entry;
+	const { icon, confirm, enabled, clonedFromPresetId } = entry;
+	return {
+		kind: "send",
+		label: entry.label,
+		text: entry.text,
+		...typeof icon === "string" && icon !== "" ? { icon } : {},
+		confirm: typeof confirm === "boolean" ? confirm : true,
+		enabled: typeof enabled === "boolean" ? enabled : true,
+		...typeof clonedFromPresetId === "string" ? { clonedFromPresetId } : {}
+	};
+}
+function decodeUserActions(value) {
+	const entries = asRecord(value);
+	if (entries === void 0) return {};
+	const decoded = {};
+	for (const [id, raw] of Object.entries(entries)) {
+		const action = decodeStoredQuickAction(raw);
+		if (action !== void 0) decoded[id] = action;
+	}
+	return decoded;
+}
+function decodeRef(value) {
+	const entry = asRecord(value);
+	if (entry === void 0) return void 0;
+	if (typeof entry.id !== "string" || entry.id === "") return void 0;
+	if (entry.source === "preset") return {
+		source: "preset",
+		id: entry.id
+	};
+	if (entry.source === "custom") return {
+		source: "custom",
+		id: entry.id
+	};
+}
+function decodeOrder(value) {
+	if (!Array.isArray(value)) return [];
+	return value.map(decodeRef).filter((ref) => ref !== void 0);
+}
+/**
+* Canonicalize one preset state: `hidden` becomes an explicit boolean or
+* disappears, and every other field is carried through so a higher version's own
+* preference survives a downgrade (spec 5.3).
+*/
+function canonicalPresetState(state) {
+	const rest = { ...state };
+	delete rest.hidden;
+	return state.hidden === true ? {
+		...rest,
+		hidden: true
+	} : rest;
+}
+/** Whether a canonical preset state carries no user preference at all. */
+function isEmptyPresetState(state) {
+	return Object.keys(state).length === 0;
+}
+function decodePresetState(value) {
+	const entries = asRecord(value);
+	if (entries === void 0) return {};
+	const decoded = {};
+	for (const [id, raw] of Object.entries(entries)) {
+		const state = asRecord(raw);
+		if (state === void 0) continue;
+		decoded[id] = canonicalPresetState(state);
+	}
+	return decoded;
+}
+/**
+* Decode any published snapshot into V1. The stored `schemaVersion` is not a
+* gate: a snapshot written by a higher version still yields every field this
+* release understands, which is what makes a downgrade round trip lossless.
+*/
+function decodeQuickActionSettings(raw) {
+	const stored = asRecord(raw);
+	if (stored === void 0) return DEFAULT_QUICK_ACTION_SETTINGS;
+	return {
+		schemaVersion: 1,
+		layout: decodeLayout(stored.layout),
+		userActionsById: decodeUserActions(stored.userActionsById),
+		actionOrder: decodeOrder(stored.actionOrder),
+		presetStateById: decodePresetState(stored.presetStateById)
+	};
+}
+//#endregion
+//#region src/model/normalize.ts
+/**
+* Deterministic, idempotent canonicalization of decoded Settings against the
+* current Preset Catalog (spec 5.3). The same input and catalog always produce
+* the same result, and normalizing twice changes nothing — which is what lets the
+* Host rewrite behind a revision fence without fighting its own writes.
+*
+* Normalization repairs references and re-states the discriminant, never content.
+* In particular it never derives `confirm` from the text: that default is
+* initialized when an action is created or cloned, so rewriting it here would undo
+* the user's choice on every load and break idempotence.
+*/
+/**
+* Canonicalize one decoded snapshot against a catalog.
+*
+* Order: existing references keep their positions, minus repeats and minus
+* references to custom actions that are gone; references to presets this catalog
+* no longer carries stay put, because the same Preset Action ID coming back must
+* restore the user's preference. Known actions with no reference are appended —
+* presets in catalog order, then custom actions in stored order. Tombstones are
+* never given a new reference, so a downgrade round trip returns their exact order.
+*/
+function normalizeQuickActionSettings(settings, catalog) {
+	const knownPresetIds = new Set(catalog.presets.map((preset) => preset.id));
+	const placed = /* @__PURE__ */ new Set();
+	const actionOrder = [];
+	const place = (ref) => {
+		const key = quickActionRefKey(ref);
+		if (placed.has(key)) return;
+		placed.add(key);
+		actionOrder.push(ref);
+	};
+	const userActionsById = {};
+	for (const [id, stored] of Object.entries(settings.userActionsById)) {
+		const value = decodeStoredQuickAction(stored);
+		if (value !== void 0) userActionsById[id] = value;
+	}
+	for (const ref of settings.actionOrder) {
+		if (ref.source === "custom" && userActionsById[ref.id] === void 0) continue;
+		place(ref);
+	}
+	for (const preset of catalog.presets) place({
+		source: "preset",
+		id: preset.id
+	});
+	for (const [id, value] of Object.entries(userActionsById)) if (isLiveQuickAction(value)) place({
+		source: "custom",
+		id
+	});
+	const presetStateById = {};
+	for (const [id, stored] of Object.entries(settings.presetStateById)) {
+		const state = canonicalPresetState(stored);
+		if (!knownPresetIds.has(id)) presetStateById[id] = state;
+		else if (!isEmptyPresetState(state)) presetStateById[id] = state;
+	}
+	return {
+		schemaVersion: 1,
+		layout: settings.layout,
+		userActionsById,
+		actionOrder,
+		presetStateById
+	};
+}
+//#endregion
+//#region src/host/presets.ts
+/**
+* The package's built-in Preset Quick Action manifest — component 1 of the
+* Preset Catalog (spec 5.1), declared ahead of the Host composition's
+* `Config.presets`.
+*
+* These are author-facing product copy in one language; changing a label or a
+* text is a product decision, not an implementation one.
+*
+* Two rules bind any edit here:
+*
+* - A Preset Action ID is permanent. Label, icon and text may change under the
+*   same id, but `kind` and `confirm` are the immutable safety behaviour
+*   signature — changing either needs a new id (spec 5.1). Editing a text so it
+*   crosses the Command Send Action boundary counts as crossing that signature.
+* - Adding an entry is additive: a new id appends to the end of every existing
+*   user's order and rewrites no stored data (spec 5.3).
+*
+* `summarize` and `explain` carry new ids rather than reusing
+* `summarize-thread` and `explain-last-change`: those two shipped on the
+* default `confirm: true`, and turning confirmation off is exactly the
+* signature change the first rule reserves a new id for. The old ids simply
+* leave the catalog, which the model already handles — a stored preference for
+* an id no longer in the catalog is kept as a tombstone, neither shown nor
+* counted (spec 5.3).
+*/
+const BUILT_IN_PRESETS = Object.freeze([
+	Object.freeze({
+		id: "approve",
+		label: "确认",
+		text: "确认，按你刚才说的做。",
+		icon: "✅",
+		confirm: false
+	}),
+	Object.freeze({
+		id: "continue",
+		label: "继续",
+		text: "继续。",
+		icon: "▶️",
+		confirm: false
+	}),
+	Object.freeze({
+		id: "summarize",
+		label: "总结",
+		text: "总结当前对话：已确定的结论、仍未决的问题、下一步要做的事。",
+		icon: "📝",
+		confirm: false
+	}),
+	Object.freeze({
+		id: "explain",
+		label: "解释",
+		text: "解释你刚才的改动：为什么这样做，考虑过哪些替代方案，取舍是什么。",
+		icon: "🔍",
+		confirm: false
+	}),
+	Object.freeze({
+		id: "compact-context",
+		label: "压缩",
+		text: "/compact",
+		icon: "🧹"
+	})
+]);
+//#endregion
+//#region src/host/config.ts
+/**
+* Host composition config: the author-facing `presets` list, merged behind the
+* package's built-in manifest into the authoritative Preset Catalog (spec 5.1).
+*
+* The Host owns the catalog, so this fails loudly. An invalid preset, a
+* duplicate Preset Action ID, a `kind` this release cannot run, or a catalog
+* over fifty entries makes plugin config loading fail with a message naming
+* every problem at once — never a silent truncation or a last-one-wins merge.
+*/
+function describeIssue(issue) {
+	if (issue.scope === "catalog") return `the preset catalog holds ${String(issue.count)} presets, above the limit of ${String(issue.limit)}`;
+	const at = issue.source === "builtin" ? `built-in presets[${String(issue.index)}]` : `presets[${String(issue.index)}]`;
+	return `${issue.id === void 0 ? at : `${at} ("${issue.id}")`}: ${issue.field} is ${issue.reason}`;
+}
+/**
+* Read one Host composition config into the authoritative catalog.
+* @param config - the composition entry's config, absent when nothing was declared.
+*/
+function readComposerQuickActionsConfig(config) {
+	const declared = config?.presets;
+	if (declared !== void 0 && !Array.isArray(declared)) return {
+		ok: false,
+		message: "composer-quick-actions: `presets` must be a list of preset quick actions"
+	};
+	const result = buildPresetCatalog({
+		builtins: BUILT_IN_PRESETS,
+		configured: declared ?? []
+	});
+	if (result.ok) return {
+		ok: true,
+		catalog: result.catalog
+	};
+	return {
+		ok: false,
+		message: `composer-quick-actions: invalid preset configuration\n${result.issues.map((issue) => `  - ${describeIssue(issue)}`).join("\n")}`
+	};
+}
+//#endregion
+//#region src/host/settings.ts
+/**
+* The single persisted Settings namespace and the Host's canonical rewrite
+* (spec 4.2, 6.1, 6.3).
+*
+* The Host is the sole validation and migration authority, so the registered
+* schema is deliberately permissive: it fixes the shape of the section and its
+* defaults, and nothing else. A strict schema would refuse registration for a
+* section a higher version wrote — which is exactly the data spec 5.3 requires
+* to survive a downgrade untouched. The shared model decodes and normalizes what
+* the schema lets through, and it never rewrites content it cannot render.
+*/
+/**
+* Shape and defaults of the persisted section (spec 4.2). The three collections
+* stay unconstrained on purpose: a stricter schema would refuse registration for
+* a section this release cannot render, and refusing registration is how stored
+* data gets lost. The shared model is the validation gate — see the module note.
+*/
+const quickActionSettingsSchema = Schema.object({
+	schemaVersion: Schema.number().default(1),
+	layout: Schema.string().default("ribbon"),
+	userActionsById: Schema.any().default({}),
+	actionOrder: Schema.any().default([]),
+	presetStateById: Schema.any().default({})
+});
+/**
+* Shape of the catalog namespace. Its authoritative content is the composition
+* `base` layer the Host declares; a user layer is never written and, if one were
+* hand-written into the document, Clients would still read `base` (spec 17.2).
+*/
+const quickActionCatalogSchema = Schema.object({
+	schemaVersion: Schema.number().default(1),
+	revision: Schema.string().default(""),
+	presets: Schema.any().default([])
+});
+/** Recognize a revision conflict by its stable code, never by prototype (realm copies). */
+function isConflict(error) {
+	return typeof error === "object" && error !== null && error.code === "SETTINGS_CONFLICT";
+}
+/** How many times a conflicting rewrite refreshes and tries again before giving up. */
+const REWRITE_ATTEMPTS = 3;
+/**
+* Read the stored section, canonicalize it against the current catalog, and
+* persist it behind the revision it was read at (spec 6.3).
+*
+* Nothing is written when nothing is stored: materializing the defaults into the
+* user layer would shadow the composition `base` and destroy what `replace({})`
+* resets to. Nothing is written for a higher `schemaVersion` either — that data
+* belongs to the version that wrote it.
+*
+* A conflict means another writer won the race, so the rewrite refreshes the
+* authoritative snapshot and recomputes rather than replaying its own stale
+* section; after a bounded number of attempts it reports the conflict instead of
+* overwriting the concurrent write.
+*/
+async function rewriteCanonicalSettings(settings, catalog) {
+	if (!settings.writable) return { status: "read-only" };
+	for (let attempt = 1; attempt <= REWRITE_ATTEMPTS; attempt += 1) {
+		const descriptor = settings.describe().find((candidate) => candidate.ns === QUICK_ACTIONS_SETTINGS_NAMESPACE);
+		if (descriptor === void 0) return { status: "unregistered" };
+		const stored = descriptor.user;
+		if (stored === void 0) return { status: "nothing-stored" };
+		const storedVersion = storedSchemaVersion(stored);
+		if (storedVersion > 1) return {
+			status: "newer-version",
+			schemaVersion: storedVersion
+		};
+		const canonical = canonicalSettings(stored, catalog);
+		if (deepEqualJson(stored, canonical)) return { status: "unchanged" };
+		try {
+			await settings.replace(QUICK_ACTIONS_SETTINGS_NAMESPACE, canonical, descriptor.revision);
+			return {
+				status: "rewritten",
+				revision: descriptor.revision
+			};
+		} catch (error) {
+			if (!isConflict(error)) throw error;
+		}
+	}
+	return {
+		status: "conflict",
+		attempts: REWRITE_ATTEMPTS
+	};
+}
+/** The `schemaVersion` a stored section declares; anything unreadable counts as this release's. */
+function storedSchemaVersion(stored) {
+	const declared = stored?.schemaVersion;
+	return typeof declared === "number" && Number.isFinite(declared) ? declared : 1;
+}
+/** Decode one raw stored section and canonicalize it against the catalog. */
+function canonicalSettings(stored, catalog) {
+	return normalizeQuickActionSettings(decodeQuickActionSettings(stored), catalog);
+}
+//#endregion
+//#region src/host/index.ts
+/**
+* Host ownership of the Quick Action state (spec 6.1, 17.2): it merges and
+* validates the Preset Catalog, registers the user-state Settings namespace and
+* the read-only catalog namespace, canonicalizes the stored section behind a
+* revision fence, and serves the authoritative catalog snapshot.
+*
+* The Host never reaches past Settings to a file or a storage backend, and it
+* never substitutes its own storage when the provider is missing — the plugin
+* declares `settings` as a hard dependency and waits.
+*/
+/** A copy nothing can reach the authoritative catalog through. */
+function detachedCatalog(catalog) {
+	return JSON.parse(JSON.stringify(catalog));
+}
+/**
+* Load the catalog, register both namespaces and canonicalize the stored section.
+*
+* An invalid preset configuration throws before anything is registered: the
+* catalog is author-owned, so a mistake fails plugin loading rather than
+* silently shipping a partial catalog (spec 5.1).
+*
+* @param settings - the Host settings provider.
+* @param config - the Host composition entry's config.
+*/
+function startQuickActionsHost(settings, config) {
+	const loaded = readComposerQuickActionsConfig(config);
+	if (!loaded.ok) throw new Error(loaded.message);
+	const { catalog } = loaded;
+	settings.register(QUICK_ACTIONS_SETTINGS_NAMESPACE, quickActionSettingsSchema, { applies: "live" });
+	settings.register(QUICK_ACTIONS_CATALOG_NAMESPACE, quickActionCatalogSchema, {
+		base: detachedCatalog(catalog),
+		applies: "restart"
+	});
+	return {
+		ready: rewriteCanonicalSettings(settings, catalog),
+		describeCatalog: async () => detachedCatalog(catalog)
+	};
+}
+//#endregion
+//#region src/index.ts
+const name = "composer-quick-actions";
+const inject = ["settings"];
+/**
+* Load the Preset Catalog, register the Settings namespace and canonicalize the
+* stored section. An invalid preset configuration throws here, failing plugin
+* loading loudly rather than shipping a partial catalog (spec 5.1).
+*
+* @returns the running Host, so a composition that embeds this plugin directly
+* can reach the catalog projection; the cordis loader ignores the value.
+*/
+function apply(ctx, config) {
+	const settings = ctx.settings;
+	const host = startQuickActionsHost(settings, config);
+	const logger = ctx.logger("composer-quick-actions");
+	ctx.effect(() => {
+		let owned = true;
+		host.ready.then((outcome) => {
+			if (!owned) return;
+			if (outcome.status === "conflict") logger.warn("settings kept moving during the canonical rewrite after %d attempts; leaving the stored section as the concurrent writer left it", outcome.attempts);
+			else if (outcome.status === "read-only") logger.warn("settings are read-only; the stored section was left untouched");
+			else if (outcome.status === "newer-version") logger.warn("the stored section declares schemaVersion %d; leaving it untouched so downgrading loses nothing", outcome.schemaVersion);
+		}, (error) => {
+			if (owned) logger.error(error);
+		});
+		return () => {
+			owned = false;
+		};
+	}, "composer-quick-actions: canonical settings rewrite");
+	return host;
+}
+//#endregion
+export { apply, inject, name };