@huaqiu/dsh-tool-kicad-schematic-gen 0.6.3 → 0.6.4

package/lib/client.js

@@ -84,6 +84,190 @@
 	}
 	//#endregion
 	//#region ../dsh-sidebar-entry/lib/index.mjs
+	/** Find the sidebar shell root element, or undefined while not yet mounted. */
+	function sidebarRoot() {
+		const column = document.querySelector("[data-pane=\"sidebar\"], [class*=\"sidebarCol\"]");
+		if (column === null) return void 0;
+		return column.querySelector("[class*=\"logoRow\"]")?.parentElement ?? column.firstElementChild;
+	}
+	/** The New Session button: nested in the logo row on current shells, a direct child on legacy shells. */
+	function newSessionButton(root) {
+		const nested = root.querySelector("button[class*=\"newSession\"]");
+		if (nested !== null) return nested;
+		for (const child of root.children) if (child.tagName === "BUTTON") return child;
+	}
+	/** Build the entry row (a detached button; insert once the shell is up). */
+	function createEntry(options) {
+		const entry = document.createElement("button");
+		entry.type = "button";
+		entry.setAttribute(options.rowAttribute, "");
+		if (options.plugin !== void 0) {
+			entry.setAttribute("data-dsh-plugin", options.plugin);
+			entry.setAttribute("data-dsh-part", "sidebar-entry");
+		}
+		entry.className = options.css["entry"] ?? "";
+		const labelSpan = document.createElement("span");
+		labelSpan.className = options.css["entryLabel"] ?? "";
+		const iconSpan = document.createElement("span");
+		iconSpan.className = options.css["entryIcon"] ?? "";
+		iconSpan.innerHTML = options.icon;
+		entry.append(iconSpan, labelSpan);
+		let badgeSpan = null;
+		const applyBadge = () => {
+			if (options.badge === void 0) return;
+			const count = options.badge.count();
+			if (count <= 0) {
+				badgeSpan?.remove();
+				badgeSpan = null;
+				return;
+			}
+			if (badgeSpan === null) {
+				badgeSpan = document.createElement("span");
+				badgeSpan.className = options.css["entryBadge"] ?? "";
+				entry.append(badgeSpan);
+			}
+			badgeSpan.textContent = String(count);
+			entry.setAttribute("data-has-badge", "");
+		};
+		const applyLabel = () => {
+			entry.setAttribute("aria-label", options.label());
+			if (options.tooltip !== void 0) entry.setAttribute("title", options.tooltip());
+			labelSpan.textContent = options.label();
+		};
+		applyLabel();
+		applyBadge();
+		entry.addEventListener("click", options.onToggle);
+		return {
+			entry,
+			applyLabel,
+			applyBadge
+		};
+	}
+	/**
+	* Re-insert the entry after the New Session row, in the family's intended
+	* order.
+	*
+	* The `familySelectors` array order is the single source of truth for visual
+	* order, so the rendered order is stable regardless of which plugin mounts
+	* first or of observer callback order — a re-render can never swap two rows.
+	* (Earlier builds used the `position: 'before' | 'after'` convention, which
+	* clustered rows by mount order and let a late-mounting `before` row steal the
+	* lead. The array order supersedes it; `position` remains only as a fallback
+	* for a row whose selector is absent from the family list.)
+	*/
+	function placeEntry(root, entry, options) {
+		const button = newSessionButton(root);
+		if (button === void 0) return false;
+		if (entry.parentElement !== root) {
+			const row = button.closest("[class*=\"logoRow\"]");
+			const base = row !== null && row.parentElement === root ? row : button;
+			const order = options.familySelectors;
+			const present = Array.from(root.children).filter((el) => el instanceof HTMLElement && el.matches(order.join(", "))).map((el) => ({
+				el,
+				idx: order.findIndex((sel) => el.matches(sel))
+			}));
+			const selfIndex = order.indexOf(options.rowSelector);
+			let anchor;
+			if (selfIndex === -1) anchor = options.position === "before" ? present.length > 0 ? present[0].el : base.nextElementSibling : present.length > 0 ? present[present.length - 1].el.nextElementSibling : base.nextElementSibling;
+			else {
+				const later = present.find((member) => member.idx > selfIndex);
+				if (later !== void 0) anchor = later.el;
+				else {
+					const earlier = [...present].reverse().find((member) => member.idx < selfIndex);
+					anchor = earlier !== void 0 ? earlier.el.nextElementSibling : base.nextElementSibling;
+				}
+			}
+			root.insertBefore(entry, anchor ?? null);
+		}
+		return true;
+	}
+	/**
+	* Mount the sidebar entry, waiting for the shell to render and self-healing
+	* on later React re-renders.
+	* @param options - the row's attribute/icon/copy/action/ordering configuration.
+	* @returns disposer removing the entry and its observers.
+	*/
+	function mountSidebarEntry(options) {
+		if (typeof document !== "undefined" && document.querySelector(options.rowSelector) !== null) return () => {};
+		const { entry, applyLabel, applyBadge } = createEntry(options);
+		let root;
+		let placed = false;
+		let unsubscribeRefresh;
+		if (options.refresh !== void 0) try {
+			unsubscribeRefresh = options.refresh.subscribe(applyLabel);
+		} catch {}
+		let unsubscribeBadge;
+		if (options.badge !== void 0) try {
+			unsubscribeBadge = options.badge.subscribe(applyBadge);
+		} catch {}
+		const tryPlace = () => {
+			if (root !== void 0 && !root.isConnected) {
+				rootObserver.disconnect();
+				root = void 0;
+				placed = false;
+			}
+			if (placed) {
+				if (document.body.contains(entry)) return;
+				rootObserver.disconnect();
+				root = void 0;
+				placed = false;
+			}
+			root ??= sidebarRoot();
+			if (root === void 0) return;
+			placed = placeEntry(root, entry, options);
+			if (placed) rootObserver.observe(root, {
+				childList: true,
+				subtree: true
+			});
+		};
+		const waitObserver = new MutationObserver(() => {
+			tryPlace();
+		});
+		waitObserver.observe(document.body, {
+			childList: true,
+			subtree: true
+		});
+		const rootObserver = new MutationObserver(() => {
+			if (root === void 0 || !root.isConnected) {
+				placed = false;
+				tryPlace();
+				return;
+			}
+			if (!root.contains(entry)) placed = placeEntry(root, entry, options);
+		});
+		options.active === void 0 || (() => {
+			const syncActive = () => {
+				if (options.active.isOpen()) entry.dataset.active = "true";
+				else delete entry.dataset.active;
+			};
+			const unsubscribe = options.active.subscribe(syncActive);
+			syncActive();
+			return unsubscribe;
+		})();
+		tryPlace();
+		return () => {
+			waitObserver.disconnect();
+			rootObserver.disconnect();
+			unsubscribeRefresh?.();
+			unsubscribeBadge?.();
+			entry.remove();
+		};
+	}
+	/**
+	* Every row selector in the Huaqiu sidebar family, in intended visual order.
+	*
+	* Family ordering is only stable when every participating plugin passes the
+	* SAME list to {@link mountSidebarEntry} — the core positions a row relative to
+	* the family block, never relative to transient shell geometry. Adding a new
+	* family row means adding its selector here (and to no plugin-local list).
+	*/
+	const HUAQIU_SIDEBAR_ENTRY_FAMILY = [
+		"[data-hq-plugin-update-entry]",
+		"[data-hqcg-footprint-entry]",
+		"[data-hqcg-symbol-entry]",
+		"[data-hqcg-schematic-entry]",
+		"[data-hq-dummy-entry]"
+	];
 	/**
 	* Read the host UI language from `<html lang>`.
 	*
@@ -100,6 +284,44 @@
 		const primary = tag.toLowerCase().split("-")[0];
 		return primary === "zh" || primary === "en" ? primary : void 0;
 	}
+	/**
+	* Watch `<html lang>` and report every resolved change.
+	*
+	* Idempotent-safe: repeated calls share one observer and each caller gets its
+	* own disposer; the observer disconnects when the last listener leaves.
+	* @param listener - called with the newly resolved language.
+	* @returns disposer removing this listener.
+	*/
+	/** Shared observer/listener set backing {@link observeHostLocale}. */
+	const localeListeners = /* @__PURE__ */ new Set();
+	let localeObserver = null;
+	function observeHostLocale(listener) {
+		if (typeof document === "undefined" || typeof MutationObserver === "undefined" || document.documentElement === null) return () => {};
+		let current = detectHostLocale();
+		const listeners = localeListeners;
+		listeners.add(listener);
+		if (localeObserver === null) {
+			localeObserver = new MutationObserver(() => {
+				const next = detectHostLocale();
+				if (next === current) return;
+				current = next;
+				for (const fn of [...listeners]) try {
+					fn(next);
+				} catch {}
+			});
+			localeObserver.observe(document.documentElement, {
+				attributes: true,
+				attributeFilter: ["lang"]
+			});
+		}
+		return () => {
+			listeners.delete(listener);
+			if (listeners.size === 0 && localeObserver !== null) {
+				localeObserver.disconnect();
+				localeObserver = null;
+			}
+		};
+	}
 	//#endregion
 	//#region src/client/schematic-ref.ts
 	/**
@@ -145,11 +367,11 @@
 	* Every line is `console.debug` and every helper is wrapped, so a host without
 	* a console (or one that rejects the payload) can never break the plugin.
 	*/
-	const TRACE = "[schematic-gen:ref]";
+	const TRACE$1 = "[schematic-gen:ref]";
 	/** Emit one trace line. Never throws. */
-	function trace(event, payload) {
+	function trace$1(event, payload) {
 		try {
-			console.debug(TRACE, event, payload ?? "");
+			console.debug(TRACE$1, event, payload ?? "");
 		} catch {}
 	}
 	/**
@@ -162,7 +384,7 @@
 	*/
 	function schematicGenLabel(lang = detectHostLocale()) {
 		const label = lang === "en" ? "Generate schematic" : "生成原理图";
-		trace("label", {
+		trace$1("label", {
 			hostLang: lang ?? null,
 			htmlLang: readHtmlLang(),
 			label
@@ -212,7 +434,7 @@
 			label: schematicGenLabel(lang),
 			clipboardText: SCHEMATIC_GEN_CLIPBOARD
 		};
-		trace("insert", insert);
+		trace$1("insert", insert);
 		return insert;
 	}
 	/**
@@ -239,12 +461,12 @@
 					name: schematicGenLabel(lang),
 					description: schematicGenDescription(lang)
 				}];
-				trace("candidates", rows);
+				trace$1("candidates", rows);
 				return Promise.resolve(rows);
 			},
 			onPick: () => {
 				const insert = schematicGenInsert(getLang());
-				trace("onPick", insert);
+				trace$1("onPick", insert);
 				return { insert };
 			},
 			codec: {
@@ -273,6 +495,449 @@
 		}
 	}
 	//#endregion
+	//#region src/client/sidebar-entry.ts
+	/**
+	* `@huaqiu/dsh-tool-kicad-schematic-gen` — the `Schematic Gen` sidebar toolbutton.
+	*
+	* Migrated from the retired `@huaqiu/dsh-tool-schematic-gen` plugin: the
+	* migration deleted the whole old package and this row went with it, which is
+	* why the sidebar showed only Plugin Updates / Footprint Gen / Symbol Gen while
+	* the plugin itself stayed installed and registered. The row, its ordering, its
+	* icon and its localization are restored verbatim.
+	*
+	* Mounts one row through the shared family helper
+	* (`@huaqiu/dsh-sidebar-entry`), in the same block and with the same look as
+	* the component-gen rows (封装生成 / Symbol 生成). Unlike those, clicking this
+	* row does NOT open a workspace: it inserts a `Generate schematic` reference
+	* chip into the current session's composer.
+	*
+	* The row is plain DOM; the chip it inserts is real DSH composer state.
+	*
+	* @module
+	*/
+	/** Stable data attribute identifying the injected row. */
+	const SCHEMATIC_ENTRY_SELECTOR = "[data-hqcg-schematic-entry]";
+	/** Full attribute name (the helper's idempotency key). */
+	const SCHEMATIC_ENTRY_ATTRIBUTE = "data-hqcg-schematic-entry";
+	/** L2 semantic plugin id: rows carry data-dsh-plugin + data-dsh-part. */
+	const PLUGIN_ID = "huaqiu-schematic-gen";
+	/** Row class names (defined by {@link ENTRY_CSS_TEXT}). */
+	const ENTRY_CSS = {
+		entry: "hqcg-schematic-sidebar-entry",
+		entryIcon: "hqcg-schematic-sidebar-entry__icon",
+		entryLabel: "hqcg-schematic-sidebar-entry__label"
+	};
+	/** Localized row copy: zh is the fallback, matching the HIT card. */
+	const COPY = {
+		zh: {
+			label: "原理图生成",
+			tooltip: "在输入框插入「生成原理图」引用"
+		},
+		en: {
+			label: "Schematic Gen",
+			tooltip: "Insert a \"Generate schematic\" reference into the composer"
+		}
+	};
+	/**
+	* Resolve the row copy for one language.
+	* @param lang - resolved host language; undefined falls back to zh.
+	* @returns the label/tooltip pair.
+	*/
+	function schematicEntryCopy(lang) {
+		return lang === "en" ? COPY.en : COPY.zh;
+	}
+	/**
+	* Inline schematic glyph — cropped to the artwork's ink, `currentColor` so it
+	* inherits the sidebar text/theme colour, 16×16 like the shell's nav glyphs
+	* (18×18 on the collapsed rail).
+	*/
+	const SCHEMATIC_ICON = `
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <!-- Schematic Sheet Frame -->
+  <rect x="3" y="3" width="18" height="18" rx="2" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+
+  <!-- Circuit Wires & Connection Nodes -->
+  <path d="M7 8H10M14 8H17" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
+  <path d="M10 16H14" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
+  <path d="M10 8V16" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
+
+  <!-- Component Symbol (Resistor / Block representation) -->
+  <path d="M10 10L11 11L12 9L13 11L14 10" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+
+  <!-- Junction Nodes / Pins -->
+  <circle cx="7" cy="8" r="1.5" fill="currentColor"/>
+  <circle cx="17" cy="8" r="1.5" fill="currentColor"/>
+  <circle cx="10" cy="16" r="1.5" fill="currentColor"/>
+  <circle cx="14" cy="16" r="1.5" fill="currentColor"/>
+</svg>
+`;
+	/**
+	* Row styles — matched to the shipped `sidebar.panellist` rows and to the
+	* component-gen rows, so the family block sits flush with the shell's own
+	* entries.
+	*/
+	const ENTRY_CSS_TEXT = `
+.hqcg-schematic-sidebar-entry {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  margin: 0 2px;
+  min-height: 36px;
+  padding: 7px 8px;
+  background: transparent;
+  border: none;
+  border-radius: 12px;
+  color: var(--dsw-alias-label-primary);
+  cursor: pointer;
+  font: inherit;
+  line-height: 22px;
+  text-align: left;
+  white-space: nowrap;
+}
+.hqcg-schematic-sidebar-entry:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+.hqcg-schematic-sidebar-entry[data-active] {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-primary);
+}
+.hqcg-schematic-sidebar-entry__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+}
+.hqcg-schematic-sidebar-entry__icon svg {
+  display: block;
+  width: 16px;
+  height: 16px;
+}
+.hqcg-schematic-sidebar-entry__label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+/* Collapsed rail: icon-only, centered — the same 36px square the shell uses. */
+[data-dsh-frame][data-sidebar-collapsed] .hqcg-schematic-sidebar-entry,
+[data-sidebar-collapsed] .hqcg-schematic-sidebar-entry {
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  margin: 0;
+  padding: 0;
+}
+[data-dsh-frame][data-sidebar-collapsed] .hqcg-schematic-sidebar-entry__icon svg,
+[data-sidebar-collapsed] .hqcg-schematic-sidebar-entry__icon svg {
+  width: 18px;
+  height: 18px;
+}
+[data-dsh-frame][data-sidebar-collapsed] .hqcg-schematic-sidebar-entry__label,
+[data-sidebar-collapsed] .hqcg-schematic-sidebar-entry__label {
+  display: none;
+}
+`;
+	/** Style tag id used for idempotent style injection. */
+	const STYLE_TAG_ID = "data-plugin-css=\"huaqiu-schematic-gen-sidebar\"";
+	/** Inject the row stylesheet once (idempotent). */
+	function injectSchematicEntryStyles() {
+		if (typeof document === "undefined") return;
+		if (document.querySelector(`style[${STYLE_TAG_ID}]`) !== null) return;
+		const tag = document.createElement("style");
+		tag.dataset.pluginCss = "huaqiu-schematic-gen-sidebar";
+		tag.textContent = ENTRY_CSS_TEXT;
+		document.head.appendChild(tag);
+	}
+	/**
+	* Mount the `Schematic Gen` sidebar row.
+	*
+	* Localization follows the host UI language through `<html lang>`
+	* (`dsh-client-locale` rewrites it on every language change and HQ Edge mirrors
+	* it), so the row re-labels itself without a `locale` service dependency.
+	*
+	* @param options - click action and family-block position.
+	* @returns disposer removing the row, its observers and its locale listener.
+	*/
+	function mountSchematicGenSidebarEntry(options) {
+		if (typeof document === "undefined") return () => {};
+		injectSchematicEntryStyles();
+		const listeners = /* @__PURE__ */ new Set();
+		const announce = () => {
+			for (const fn of [...listeners]) try {
+				fn();
+			} catch {}
+		};
+		let lang = detectHostLocale();
+		const stopLocale = observeHostLocale((next) => {
+			lang = next;
+			announce();
+		});
+		const dispose = mountSidebarEntry({
+			rowAttribute: SCHEMATIC_ENTRY_ATTRIBUTE,
+			rowSelector: SCHEMATIC_ENTRY_SELECTOR,
+			plugin: PLUGIN_ID,
+			icon: SCHEMATIC_ICON,
+			css: ENTRY_CSS,
+			label: () => schematicEntryCopy(lang).label,
+			tooltip: () => schematicEntryCopy(lang).tooltip,
+			refresh: { subscribe: (fn) => {
+				listeners.add(fn);
+				return () => {
+					listeners.delete(fn);
+				};
+			} },
+			onToggle: options.onToggle,
+			position: options.position ?? "after",
+			familySelectors: HUAQIU_SIDEBAR_ENTRY_FAMILY
+		});
+		return () => {
+			dispose();
+			stopLocale();
+			listeners.clear();
+		};
+	}
+	//#endregion
+	//#region src/client/composer-chip.ts
+	/**
+	* `@huaqiu/dsh-tool-kicad-schematic-gen` — programmatic composer chip insertion.
+	*
+	* Migrated from the retired `@huaqiu/dsh-tool-schematic-gen` plugin, whose
+	* sidebar row was lost with the package. The row is restored together with the
+	* path that makes it do something: inserting the `@ Generate schematic` chip
+	* into the live composer.
+	*
+	* The public path is `ctx.conversation.input.for(actx).insertReference(ref,
+	* span)` — a verb on DSH's frozen `SessionInput` face, reached through two
+	* public services (`conversation`, `sessions`). No DOM forgery, no new public
+	* API, no DSH source change.
+	*
+	* Two coordinate systems are in play and mixing them silently misplaces the
+	* chip:
+	*
+	* - `InputState.draft` and `Occurrence.offset|length` are CLIPBOARD
+	*   coordinates — a chip occupies its whole `clipboardText`.
+	* - `TokenSpan` is DETECT coordinates — a chip is exactly one `U+FFFC`.
+	*
+	* `insertReference` is span-CAS'd (`span.draftRev !== this.rev → false`) and
+	* refuses busy phases, so every call reads a fresh snapshot and retries once.
+	*
+	* @module
+	*/
+	/** Browser-console tag for the insertion path (see schematic-ref.ts). */
+	const TRACE = "[schematic-gen:chip]";
+	/** Emit one trace line. Never throws. */
+	function trace(event, payload) {
+		try {
+			console.debug(TRACE, event, payload ?? "");
+		} catch {}
+	}
+	/**
+	* The Session whose composer the user is looking at.
+	*
+	* `SessionListState` has no `current` field — reading one silently yields
+	* undefined and the insertion aborts before touching the draft. The main view
+	* is whichever row `retainedBy.mainView` counts, so that is the primary
+	* answer; host list order and then any known row are the fallbacks.
+	*
+	* @param sessions - `ctx.get('sessions')`, or undefined.
+	* @returns the Session id, or undefined when the host has none yet.
+	*/
+	function currentSessionId(sessions) {
+		let list;
+		try {
+			list = sessions?.list?.getSnapshot();
+		} catch {
+			list = void 0;
+		}
+		if (list === void 0 || list === null) return void 0;
+		const ids = Array.isArray(list.ids) ? list.ids : [];
+		for (const id of ids) if ((list.byId?.[id]?.retainedBy?.mainView ?? 0) > 0) return id;
+		if (ids.length > 0) return ids[0];
+		return Object.keys(list.byId ?? {})[0];
+	}
+	/** How many Sessions the host knows about — the only context a `no-session` trace needs. */
+	function countSessions(sessions) {
+		try {
+			const list = sessions?.list?.getSnapshot();
+			const ids = Array.isArray(list?.ids) ? list?.ids.length ?? 0 : 0;
+			return ids > 0 ? ids : Object.keys(list?.byId ?? {}).length;
+		} catch {
+			return 0;
+		}
+	}
+	/**
+	* Resolve one Session's scope context — the value `conversation.input.for()`
+	* needs.
+	*
+	* `binding(id).ctx` is the ONLY guard-safe path: DSH's dynamic-plugin facade
+	* rejects every service call whose result is a cordis Context
+	* (`sessions.scope()` → "service \"sessions\" returned a cordis Context, which
+	* the dynamic facade does not expose"), and that rejection THROWS. `binding()`
+	* returns a plain object, so its `ctx` field is reachable without going back
+	* through the facade. `scope()` stays as a last resort for a host whose
+	* binding carries no ctx.
+	*
+	* @param sessions - `ctx.get('sessions')`, or undefined.
+	* @param sessionId - target Session.
+	* @returns the scope context, or undefined.
+	*/
+	function resolveSessionScope(sessions, sessionId) {
+		let binding;
+		try {
+			binding = sessions?.binding?.(sessionId);
+		} catch {
+			binding = void 0;
+		}
+		const ctx = binding?.ctx;
+		if (ctx !== void 0 && ctx !== null) return ctx;
+		try {
+			return sessions?.scope?.(sessionId);
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Translate a clipboard-projected draft length into DETECT coordinates.
+	*
+	* Every existing chip shrinks from `length` clipboard characters to one detect
+	* character, so the detect length is the clipboard length minus the sum of
+	* `length - 1` over all occurrences. A draft with no chips is unchanged.
+	*
+	* @param state - the fresh input snapshot.
+	* @returns the detect-coordinate length of the whole draft.
+	*/
+	function detectLengthOf(state) {
+		const draft = typeof state.draft === "string" ? state.draft : "";
+		const occurrences = Array.isArray(state.occurrences) ? state.occurrences : [];
+		let shrink = 0;
+		for (const occurrence of occurrences) {
+			const length = typeof occurrence.length === "number" ? occurrence.length : 0;
+			if (length > 1) shrink += length - 1;
+		}
+		return Math.max(0, draft.length - shrink);
+	}
+	/** Whether the draft already carries our chip. */
+	function hasSchematicChip(state) {
+		return (Array.isArray(state.occurrences) ? state.occurrences : []).some((o) => o.source === "schematic-gen" && o.ref === "generate");
+	}
+	/** Phases in which `insertReference` refuses to edit. */
+	const BUSY_PHASES = ["adjudicating", "submitting"];
+	/**
+	* Insert the `Generate schematic` chip at the end of the current draft.
+	*
+	* Never throws and never partially edits: every failure leaves the draft
+	* exactly as it was.
+	*
+	* @param deps - lazy service accessors (resolved per call, never captured).
+	* @param insert - the reference to insert (defaults to the schematic-gen one,
+	*                 whose label is resolved against the host language at call
+	*                 time — so the chip matches the UI language, not a frozen
+	*                 English literal).
+	* @returns whether a chip landed, and why not when it did not.
+	*/
+	function insertSchematicChip(deps, insert = schematicGenInsert()) {
+		const sessions = deps.getSessions();
+		const conversation = deps.getConversation();
+		if (sessions === void 0 || conversation === void 0 || conversation.input === void 0) {
+			trace("unavailable", {
+				hasSessions: sessions !== void 0,
+				hasConversation: conversation !== void 0
+			});
+			return {
+				ok: false,
+				reason: "unavailable"
+			};
+		}
+		const sessionId = currentSessionId(sessions);
+		if (sessionId === void 0 || sessionId === null || sessionId === "") {
+			trace("no-session", { known: countSessions(sessions) });
+			return {
+				ok: false,
+				reason: "no-session"
+			};
+		}
+		const actx = resolveSessionScope(sessions, sessionId);
+		if (actx === void 0 || actx === null) {
+			trace("no-scope", { sessionId });
+			return {
+				ok: false,
+				reason: "no-session"
+			};
+		}
+		let input;
+		try {
+			input = conversation.input.for(actx);
+		} catch (err) {
+			trace("for() threw", err instanceof Error ? err.message : err);
+			input = void 0;
+		}
+		if (input === void 0 || input === null || typeof input.insertReference !== "function") {
+			trace("unavailable", { hasInput: input !== void 0 && input !== null });
+			return {
+				ok: false,
+				reason: "unavailable"
+			};
+		}
+		trace("inserting", {
+			label: insert.label,
+			clipboardText: insert.clipboardText
+		});
+		for (let attempt = 0; attempt < 2; attempt += 1) {
+			const state = input.state?.getSnapshot() ?? {};
+			if (hasSchematicChip(state)) {
+				trace("already-present");
+				return {
+					ok: false,
+					reason: "already-present"
+				};
+			}
+			const phase = state.phase ?? "plain";
+			if (BUSY_PHASES.includes(phase)) {
+				trace("busy", { phase });
+				return {
+					ok: false,
+					reason: "busy"
+				};
+			}
+			const draftRev = typeof state.draftRev === "number" ? state.draftRev : 0;
+			const end = detectLengthOf(state);
+			let applied = false;
+			try {
+				applied = input.insertReference(insert, {
+					start: end,
+					end,
+					draftRev
+				});
+			} catch (err) {
+				trace("insertReference threw", err instanceof Error ? err.message : err);
+				applied = false;
+			}
+			if (applied) {
+				trace("inserted", {
+					label: insert.label,
+					span: {
+						start: end,
+						end,
+						draftRev
+					}
+				});
+				try {
+					input.focus?.();
+				} catch (err) {
+					trace("focus threw", err instanceof Error ? err.message : err);
+				}
+				return { ok: true };
+			}
+			trace("cas-miss", { attempt });
+		}
+		trace("conflict");
+		return {
+			ok: false,
+			reason: "conflict"
+		};
+	}
+	//#endregion
 	//#region src/client/index.ts
 	/** Harness compacts finished tool calls; keep only our delivery card visible. */
 	function keepDeliveryVisible() {
@@ -465,7 +1130,32 @@
 				apply: (ctx) => {
 					getHost = () => ctx.get?.("hqEdge");
 					const stopVisibility = keepDeliveryVisible();
-					const stopRefs = registerSchematicGenSource(ctx.get?.("inputTriggers"));
+					const triggers = ctx.get?.("inputTriggers");
+					try {
+						console.debug("[schematic-gen:client] apply", {
+							inputTriggers: triggers !== void 0 && triggers !== null,
+							slots: typeof ctx.slots?.inject === "function"
+						});
+					} catch {}
+					const stopRefs = registerSchematicGenSource(triggers);
+					const chipDeps = {
+						getConversation: () => ctx.get?.("conversation"),
+						getSessions: () => ctx.get?.("sessions")
+					};
+					const stopEntry = mountSchematicGenSidebarEntry({
+						onToggle: () => {
+							const result = insertSchematicChip(chipDeps);
+							try {
+								console.debug("[schematic-gen:chip] click", result);
+							} catch {}
+							if (result.ok || result.reason === "already-present") return;
+							notifyComposer(ctx, result.reason);
+						},
+						position: "after"
+					});
+					try {
+						console.debug("[schematic-gen:client] sidebar row", { rows: document.querySelectorAll("[data-hqcg-schematic-entry]").length });
+					} catch {}
 					const dispose = ctx.slots.inject("tool.call.toolview", () => ctx.slots.register({
 						name: "tool.call.toolview",
 						key: "render_kicad_module_preview"
@@ -473,10 +1163,33 @@
 					ctx.effect?.(() => () => {
 						stopVisibility();
 						stopRefs();
+						stopEntry();
 						if (typeof dispose === "function") dispose();
 					});
 				}
 			};
+			/** Surface why a chip insertion did not happen, through the composer's own notice channel. Best-effort by design. */
+			function notifyComposer(context, reason) {
+				try {
+					const sessions = context.get?.("sessions");
+					const conversation = context.get?.("conversation");
+					if (sessions === void 0 || conversation?.input === void 0) return;
+					const sessionId = currentSessionId(sessions);
+					if (!sessionId) return;
+					const actx = resolveSessionScope(sessions, sessionId);
+					if (actx === void 0 || actx === null) return;
+					conversation.input.for(actx)?.notify?.("info", noticeFor(reason));
+				} catch {}
+			}
+			/** Human-readable notice text for one insertion failure reason. */
+			function noticeFor(reason) {
+				switch (reason) {
+					case "no-session": return "Open a conversation first, then click Schematic Gen again.";
+					case "busy": return "The composer is busy — try again once the current message settles.";
+					case "conflict": return "The composer changed while inserting — click Schematic Gen again.";
+					default: return "Schematic Gen is unavailable in this session.";
+				}
+			}
 		}
 	});
 	//#endregion