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

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
 	/**
@@ -109,10 +331,13 @@
 	* SSE agents were removed with the package). The chip identity, the `@`
 	* trigger, the clipboard projection and the menu row are preserved verbatim so
 	* existing drafts and the composer UX keep working. The one deliberate change:
-	* the chip's model text now pins the bundled `kicad-schematic-design` skill
-	* instead of the deleted online tools (`generate_schematic_from_description` /
-	* `generate_system_module_graph`), because the design skill is the new local
-	* entry point the agent must follow.
+	* the chip's model text is now the bare clipboard token — the semantics that
+	* used to ride in the payload (pin the `kicad-schematic-design` skill instead
+	* of the deleted online tools `generate_schematic_from_description` /
+	* `generate_system_module_graph`, forbid hand-written KiCad files, defer to
+	* the user's words) moved to the node half's `huaqiu:schematic-gen`
+	* system-prompt section; see {@link SCHEMATIC_GEN_SERIALIZED} and
+	* `src/prompt.ts`.
 	*
 	* One module owns the identity of the chip, its menu row, and the model text
 	* the chip expands to at submit time. Registering the source is MANDATORY, not
@@ -122,6 +347,12 @@
 	* source"). A chip inserted without a registered source would therefore block
 	* the user's message instead of degrading quietly.
 	*
+	* The registration is also ORDER-sensitive: the trigger service is provided by
+	* a plugin whose own dependency chain is longer than ours, so reading it once
+	* at `apply()` time can find nothing. The entry therefore declares
+	* `inputTriggers` in its `inject` (cordis parks the plugin until the provider
+	* exists) and retries briefly if it still arrives late.
+	*
 	* Registering it also buys the typed path for free: the user can type `@` and
 	* pick *Generate schematic* (生成原理图 under a Chinese UI) from a group beside
 	* *Files & folders* / *Sessions*.
@@ -145,11 +376,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 +393,7 @@
 	*/
 	function schematicGenLabel(lang = detectHostLocale()) {
 		const label = lang === "en" ? "Generate schematic" : "生成原理图";
-		trace("label", {
+		trace$1("label", {
 			hostLang: lang ?? null,
 			htmlLang: readHtmlLang(),
 			label
@@ -185,20 +416,27 @@
 	}
 	/**
 	* Model form of the chip: what the agent actually reads at the chip's position
-	* in the user message.
-	*
-	* Deliberately an *intent*, never a fabricated design description — the user's
-	* own words stay the only source of requirements, and the plugin being loaded
-	* is never by itself a reason to generate.
-	*
-	* The retired plugin pinned the online tools here
-	* (`generate_schematic_from_description` / `generate_system_module_graph`).
-	* The migrated chip pins the bundled `kicad-schematic-design` skill instead:
-	* the skill owns the module search / part import / editable-project flow, and
-	* starts from the hardware design brief when no plan exists yet. Hand-written
-	* KiCad files stay forbidden in both worlds.
+	* in the user message — the clipboard token itself, nothing more.
+	*
+	* This is the idiomatic mention pattern (DSH's own draft tests serialize a
+	* reference to its ref), and it is deliberate on two counts:
+	*
+	* 1. **Whatever `serialize` returns lands in the USER message** — the submit
+	*    plane splices it over the chip's clipboard range — so a long payload is
+	*    noise the user reads back in their own transcript on every send.
+	* 2. **The token has no semantics of its own**, so the semantics cannot live
+	*    here; they live in the node half's `huaqiu:schematic-gen` system-prompt
+	*    section (see `src/prompt.ts`), which defines the token, pins the
+	*    `kicad-schematic-design` skill, and carries the guardrails.
+	*
+	* History: the chip first shipped a 6-line `<schematic-gen intent=…>` block,
+	* then a 3-line trimmed form, and now delegates entirely to the section. The
+	* retired plugin pinned deleted online tools here
+	* (`generate_schematic_from_description` / `generate_system_module_graph`);
+	* nothing in this constant may ever name a tool again — the skill pin is the
+	* section's job.
 	*/
-	const SCHEMATIC_GEN_SERIALIZED = "<schematic-gen intent=\"kicad-schematic-design\">\nThe user explicitly chose Schematic Gen for this request. Produce the design with the `kicad-schematic-design` skill; when the hardware design brief is missing or incomplete, the skill starts by preparing it before the schematic work.\nNever hand-write .kicad_sch files or KiCad project files yourself — always go through the skill and its tools.\nUse the user's own words as the design description. If they have not described the circuit yet, ask for the requirements instead of assuming them.\n</schematic-gen>";
+	const SCHEMATIC_GEN_SERIALIZED = SCHEMATIC_GEN_CLIPBOARD;
 	/**
 	* The `ReferenceInsert` this source produces on pick (and on button click).
 	*
@@ -212,7 +450,7 @@
 			label: schematicGenLabel(lang),
 			clipboardText: SCHEMATIC_GEN_CLIPBOARD
 		};
-		trace("insert", insert);
+		trace$1("insert", insert);
 		return insert;
 	}
 	/**
@@ -239,12 +477,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: {
@@ -254,24 +492,569 @@
 		};
 	}
 	/**
-	* Register the source and return its disposer.
+	* One registration attempt, reported instead of swallowed.
+	*
+	* {@link registerSchematicGenSource} is the disposer-only view for callers that
+	* do not care; this is the same attempt with the outcome visible, which is what
+	* a caller needs to decide whether a chip may be inserted at all — an
+	* unregistered source makes every send fail (see the module header).
 	*
-	* Never throws: a missing service, a duplicate registration (a second live
-	* copy of this plugin) or a throwing registry must not take the whole client
-	* half down. Without a registered source the sidebar button degrades to
-	* inserting nothing rather than producing a chip that would block submission.
 	* @param registry - `ctx.get('inputTriggers')`, or undefined.
-	* @returns disposer (a no-op when registration did not happen).
+	* @returns whether the registration landed, plus its disposer.
 	*/
-	function registerSchematicGenSource(registry) {
-		if (registry === void 0 || registry === null || typeof registry.registerSource !== "function") return () => {};
+	function registerSchematicGenSourceTracked(registry) {
+		if (registry === void 0 || registry === null || typeof registry.registerSource !== "function") return {
+			registered: false,
+			dispose: () => {}
+		};
 		try {
 			const dispose = registry.registerSource(createSchematicGenSource());
-			return typeof dispose === "function" ? dispose : () => {};
+			return {
+				registered: true,
+				dispose: typeof dispose === "function" ? dispose : () => {}
+			};
 		} catch {
-			return () => {};
+			return {
+				registered: true,
+				dispose: () => {}
+			};
 		}
 	}
+	/**
+	* Host timer, or undefined where there is none.
+	*
+	* The retry is browser-only machinery, and the built bundle is also evaluated
+	* in bare hosts (the vm-based card test, a non-DOM worker) where `setInterval`
+	* does not exist. Those must degrade to "not registered yet" — a throw here
+	* would take the whole client half down, which is the failure mode this module
+	* exists to prevent.
+	*/
+	function hostTimer() {
+		if (typeof setInterval !== "function" || typeof clearInterval !== "function") return void 0;
+		return {
+			set: (fn, ms) => setInterval(fn, ms),
+			clear: (handle) => clearInterval(handle)
+		};
+	}
+	/**
+	* Register the source, polling while the trigger service has not activated yet.
+	*
+	* Why this exists: activation is service-availability driven, and
+	* `inputTriggers` is provided by a plugin (`dsh-client-ui-input-trigger`) whose
+	* own dependency chain is far longer than ours. A plugin that reads the service
+	* exactly once at `apply()` time and finds it absent registers NOTHING —
+	* silently. The chip then lands in the composer (insertion only needs
+	* `conversation`) and the send dies on
+	* `slash: no serializer for reference source "schematic-gen"`, because the
+	* controller routes every chip to its owner's codec. Declaring `inputTriggers`
+	* in the plugin's `inject` is the primary fix (cordis then parks this plugin
+	* until the provider exists); this poll is the belt-and-braces path for a
+	* provider that arrives later than that declaration could promise.
+	*
+	* @param getRegistry - returns the current `ctx.get('inputTriggers')` value.
+	* @param hooks - scheduler/trace seams.
+	* @returns a live binding whose `registered()` the caller may consult.
+	*/
+	function registerSchematicGenSourceWhenReady(getRegistry, hooks = {}) {
+		const intervalMs = hooks.intervalMs ?? 250;
+		const maxAttempts = hooks.maxAttempts ?? 80;
+		const traceFn = hooks.trace ?? trace$1;
+		const timer = hooks.setTimer !== void 0 && hooks.clearTimer !== void 0 ? {
+			set: hooks.setTimer,
+			clear: hooks.clearTimer
+		} : hostTimer();
+		let current = registerSchematicGenSourceTracked(getRegistry());
+		let handle;
+		let attempts = 0;
+		let stopped = false;
+		const stopTimer = () => {
+			if (handle === void 0 || timer === void 0) return;
+			timer.clear(handle);
+			handle = void 0;
+		};
+		const dispose = () => {
+			stopped = true;
+			stopTimer();
+			current.dispose();
+		};
+		if (current.registered) return {
+			registered: () => true,
+			dispose
+		};
+		if (timer === void 0) {
+			traceFn("no timer host — source registration not retried");
+			return {
+				registered: () => false,
+				dispose
+			};
+		}
+		traceFn("waiting for inputTriggers", {
+			intervalMs,
+			maxAttempts
+		});
+		handle = timer.set(() => {
+			if (stopped) return;
+			attempts += 1;
+			const next = registerSchematicGenSourceTracked(getRegistry());
+			if (next.registered) {
+				current = next;
+				stopTimer();
+				traceFn("registered (late)", { attempts });
+				return;
+			}
+			if (attempts >= maxAttempts) {
+				stopTimer();
+				traceFn("source registration gave up", { attempts });
+			}
+		}, intervalMs);
+		return {
+			registered: () => current.registered,
+			dispose
+		};
+	}
+	//#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. */
@@ -461,22 +1244,80 @@
 				}, busy ? "处理中…" : "放置到编辑器") : null, h("span", { style: { fontSize: 12 } }, `${result.fileCount} 个工程和库文件`)), result.status !== "ok" ? h("p", null, "存在未渲染页面或预览警告，请结合工具结果检查。") : null, message ? h("p", { role: "alert" }, message) : null);
 			}
 			return {
-				inject: ["slots"],
+				inject: ["slots", "inputTriggers"],
 				apply: (ctx) => {
 					getHost = () => ctx.get?.("hqEdge");
 					const stopVisibility = keepDeliveryVisible();
-					const stopRefs = registerSchematicGenSource(ctx.get?.("inputTriggers"));
+					const source = registerSchematicGenSourceWhenReady(() => ctx.get?.("inputTriggers"));
+					try {
+						console.debug("[schematic-gen:client] apply", {
+							inputTriggers: source.registered(),
+							slots: typeof ctx.slots?.inject === "function"
+						});
+					} catch {}
+					const chipDeps = {
+						getConversation: () => ctx.get?.("conversation"),
+						getSessions: () => ctx.get?.("sessions")
+					};
+					const stopEntry = mountSchematicGenSidebarEntry({
+						onToggle: () => {
+							if (!source.registered()) {
+								try {
+									console.debug("[schematic-gen:chip] click", {
+										ok: false,
+										reason: "source-unregistered"
+									});
+								} catch {}
+								notifyComposer(ctx, "source-unregistered");
+								return;
+							}
+							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"
 					}, Card));
 					ctx.effect?.(() => () => {
 						stopVisibility();
-						stopRefs();
+						source.dispose();
+						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.";
+					case "source-unregistered": return "Schematic Gen is still starting up — click again in a moment.";
+					default: return "Schematic Gen is unavailable in this session.";
+				}
+			}
 		}
 	});
 	//#endregion