@huaqiu/dsh-eda-selection 0.0.0-stage → 0.5.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 深圳华秋智联股份有限公司
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# DSH bundle patch: inserts the ambient selection plugin.
+#
+# The browser half registers a `conversation.input.dock` entry and the node
+# half registers a `systemPrompt` section, so the entry inject must hold the
+# plugin until both surfaces exist.
+- insert:
+    - id: huaqiu-eda-selection
+      name: '@huaqiu/dsh-eda-selection'
+      inject: ['hqEdge', 'systemPrompt']

package/lib/client.js

@@ -0,0 +1,357 @@
+window.__ModuleLoader__.load({
+	id: "@huaqiu/dsh-eda-selection",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react = require("react");
+		//#region src/client/chip-text.ts
+		/** Fallback translator: the key itself, so a missing dictionary is never blank. */
+		const identityTranslate = (key) => key;
+		/** Editor display name for one editor identity. */
+		function editorLabel(editor, t = identityTranslate) {
+			switch (editor) {
+				case "PCB": return t("editor.pcb");
+				case "SCHEMATIC": return t("editor.schematic");
+				default: return t("editor.unspecified");
+			}
+		}
+		/**
+		* `"{count} items"` with the singular form honoured for one item.
+		*
+		* Both languages ship a dedicated singular key, so English reads "1 item"
+		* rather than "1 items".
+		*/
+		function itemCountLabel(count, t = identityTranslate) {
+			return count === 1 ? t("chip.item") : t("chip.items", { count });
+		}
+		/**
+		* The bounded, comma-joined label suffix, or `''` when there is nothing to show.
+		*
+		* The separator is a plain comma plus a space rather than a locale-specific
+		* list separator: the chip is a compact ambient indicator, and the host's
+		* labels are identifiers (R1, U3, …) that read the same in both languages.
+		*/
+		function labelSuffix(labels) {
+			return labels.slice(0, 3).join(", ");
+		}
+		/**
+		* The full chip text, e.g. `Current selection · 3 items (PCB): R1, R2, R3`.
+		*
+		* Returns `''` for anything that must NOT be rendered — an unknown state
+		* (`null`) or a known-empty selection. One gate for both, so the chip and the
+		* prompt section can never disagree about when the selection exists.
+		*/
+		function formatSelectionChip(snapshot, t = identityTranslate) {
+			if (snapshot === null || !snapshot.hasSelection || snapshot.itemCount <= 0) return "";
+			const parts = [
+				t("chip.label"),
+				t("chip.sep"),
+				itemCountLabel(snapshot.itemCount, t)
+			];
+			if (snapshot.editor !== "UNSPECIFIED") parts.push(`(${editorLabel(snapshot.editor, t)})`);
+			const labels = labelSuffix(snapshot.labels);
+			return labels.length > 0 ? `${parts.join(" ")}${t("chip.labels", { labels })}` : parts.join(" ");
+		}
+		/** Screen-reader label for the chip. */
+		function selectionChipAriaLabel(snapshot, t = identityTranslate) {
+			if (snapshot === null || !snapshot.hasSelection || snapshot.itemCount <= 0) return "";
+			return t("chip.aria", { count: snapshot.itemCount });
+		}
+		//#endregion
+		//#region src/client/SelectionChip.tsx
+		/**
+		* The ambient `Current selection` chip — the browser half's only visible
+		* surface.
+		*
+		* It is a passive indicator: it renders what the host published and nothing
+		* else. There is no click action (the agent reaches the real selection through
+		* the existing EDA tools), no expand affordance, and no per-item type claim.
+		*
+		* ── When it renders ─────────────────────────────────────────────────────────
+		* Only for a snapshot with `hasSelection && itemCount > 0`. Both UNKNOWN
+		* (`null` — nothing published yet, or the sync failed) and KNOWN-EMPTY
+		* (`hasSelection: false` with a real revision) render NOTHING. Rendering
+		* either of them would put a chip on screen that the host does not back.
+		*
+		* @module
+		*/
+		const ROOT = {
+			display: "inline-flex",
+			alignItems: "center",
+			gap: 6,
+			alignSelf: "flex-start",
+			maxWidth: "100%",
+			padding: "3px 10px",
+			borderRadius: 999,
+			boxSizing: "border-box",
+			fontSize: 12,
+			lineHeight: "18px",
+			color: "var(--dsw-alias-label-secondary)",
+			background: "color-mix(in srgb, var(--dsw-alias-label-primary) 5%, transparent)",
+			border: "1px solid color-mix(in srgb, var(--dsw-alias-label-primary) 14%, transparent)"
+		};
+		/** The leading dot — the only ornament, and it carries no meaning. */
+		const DOT = {
+			width: 6,
+			height: 6,
+			borderRadius: "50%",
+			flex: "0 0 auto",
+			background: "var(--dsw-alias-state-success, #34c759)"
+		};
+		const TEXT = {
+			overflow: "hidden",
+			textOverflow: "ellipsis",
+			whiteSpace: "nowrap"
+		};
+		/**
+		* Render the chip, or `null` when there is nothing grounded to show.
+		*
+		* Returning `null` (rather than an empty fragment) lets the dock skip the row
+		* entirely, so an absent selection costs no vertical space in the composer.
+		*/
+		function SelectionChip({ snapshot, t }) {
+			const text = formatSelectionChip(snapshot, t);
+			if (text.length === 0) return null;
+			const aria = selectionChipAriaLabel(snapshot, t);
+			return (0, react.createElement)("div", {
+				style: ROOT,
+				"data-dsh-plugin": "huaqiu-eda-selection",
+				"data-dsh-part": "selection-chip",
+				"data-editor": snapshot?.editor ?? "UNSPECIFIED",
+				"data-revision": snapshot?.revision ?? "",
+				role: "status",
+				"aria-label": aria.length > 0 ? aria : void 0
+			}, (0, react.createElement)("span", {
+				style: DOT,
+				"aria-hidden": true
+			}), (0, react.createElement)("span", { style: TEXT }, text));
+		}
+		//#endregion
+		//#region src/client/locales.ts
+		/**
+		* zh / en copy for the ambient `Current selection` dock entry.
+		*
+		* Chinese is the source of truth: `EdaSelectionKey` is derived from it and
+		* `en` is typed against it, so a key added to one language without the other
+		* is a COMPILE error rather than a silent Chinese fallback at runtime.
+		*
+		* Kept in its own module (rather than inlined in the component) so the copy is
+		* reviewable on its own and the test file can assert bilingual balance
+		* directly, mirroring `@huaqiu/dsh-auth` / `@huaqiu/dsh-tool-schematic-gen`.
+		*/
+		const zh = {
+			/** Dock-entry label shown wherever the owner projects one. */
+			"dock.label": "当前选中",
+			/** The chip itself: "Current selection · 3 items (PCB)". */
+			"chip.label": "当前选中",
+			"chip.sep": "·",
+			/** Editor names, spelled for a human reader. */
+			"editor.pcb": "PCB",
+			"editor.schematic": "原理图",
+			"editor.unspecified": "编辑器",
+			/** "{count} items" / "{count} 项". */
+			"chip.items": "{count} 项",
+			/** One item — English needs the singular form. */
+			"chip.item": "1 项",
+			/** Screen-reader label for the chip. */
+			"chip.aria": "当前编辑器选中 {count} 项",
+			/** Bounded label list, shown after the count when the host supplied any. */
+			"chip.labels": "：{labels}"
+		};
+		const en = {
+			"dock.label": "Current selection",
+			"chip.label": "Current selection",
+			"chip.sep": "·",
+			"editor.pcb": "PCB",
+			"editor.schematic": "Schematic",
+			"editor.unspecified": "editor",
+			"chip.items": "{count} items",
+			"chip.item": "1 item",
+			"chip.aria": "Current editor selection: {count} items",
+			"chip.labels": ": {labels}"
+		};
+		//#endregion
+		//#region src/client/hq-edge.ts
+		/**
+		* Normalize one raw summary into {@link SelectionSnapshot}, or `null` when it
+		* carries no usable state.
+		*
+		* The bridge already normalizes, but this plugin can be pointed at a host
+		* service that predates the selection face (or at a hand-rolled test double),
+		* so the same defensive rules are applied again here:
+		*
+		*   - null / undefined / non-object → `null` (unknown)
+		*   - `hasSelection` not a boolean → `null` (cannot tell selected from not)
+		*   - unknown editor name → `UNSPECIFIED`
+		*   - non-string labels are dropped; the array is copied
+		*
+		* A well-formed `hasSelection: false` is KEPT: that is a known-empty state,
+		* and dropping it would erase the distinction the whole design rests on.
+		*
+		* @param raw - value read from `hqEdge.selection.getCurrent()`.
+		* @returns the normalized snapshot, or `null` for unknown/malformed.
+		*/
+		function normalizeSelectionSnapshot(raw) {
+			if (raw === null || raw === void 0) return null;
+			if (typeof raw !== "object" || Array.isArray(raw)) return null;
+			const record = raw;
+			if (typeof record.hasSelection !== "boolean") return null;
+			const itemCount = typeof record.itemCount === "number" && Number.isFinite(record.itemCount) && record.itemCount > 0 ? Math.floor(record.itemCount) : 0;
+			const editor = record.editor;
+			const knownEditor = editor === "SCHEMATIC" || editor === "PCB" ? editor : "UNSPECIFIED";
+			const labels = Array.isArray(record.labels) ? record.labels.filter((label) => typeof label === "string") : [];
+			const revision = typeof record.revision === "string" ? record.revision : typeof record.revision === "number" && Number.isFinite(record.revision) ? String(record.revision) : "";
+			return {
+				hasSelection: record.hasSelection,
+				itemCount,
+				editor: knownEditor,
+				labels,
+				revision
+			};
+		}
+		//#endregion
+		//#region src/client/index.ts
+		/**
+		* `@huaqiu/dsh-eda-selection` — browser half.
+		*
+		* Contributes ONE entry to the public `conversation.input.dock` slot: an
+		* ambient `Current selection · N items (editor)` chip that appears above the
+		* composer whenever the FOCUSED KiCad editor has a selection, and disappears
+		* the moment it does not.
+		*
+		* ── Where the state comes from ──────────────────────────────────────────────
+		* The `hqEdge` host service provided by `@hqedge/dsh-edge-bridge`. Its
+		* `selection` face is fed by the bridge's OWN `/runtime/dsh` poll, so this
+		* plugin adds NO second polling loop and never talks to HQ Edge itself.
+		*
+		* `inject` declares `hqEdge`, so DSH holds this plugin's activation until the
+		* bridge has provided it — `ctx.get('hqEdge')` inside `apply()` therefore
+		* resolves. The accessor is still built lazily (a closure, not a captured
+		* value) because the service object is created once but its `selection` face
+		* is read on every subscription.
+		*
+		* The bridge's `onChanged` replays the current state immediately when one is
+		* already known, so a chip mounted after the first summary does not wait for a
+		* change; and it returns a disposer, which is what the slot's own lifecycle
+		* expects.
+		*
+		* ── Unknown vs known-empty ──────────────────────────────────────────────────
+		* `hqEdge.selection.getCurrent()` returns `null` when the state is UNKNOWN
+		* (nothing published yet, or the sync failed). That is NOT a selection, and
+		* the chip renders nothing for it — a chip must never appear on screen that
+		* the host does not currently back.
+		*
+		* ── No second composer ──────────────────────────────────────────────────────
+		* This entry never touches the draft, the input state, or the reference
+		* pipeline. It is a read-only projection of host state; the agent reaches the
+		* real selection through the existing EDA selection tools.
+		*
+		* @module @huaqiu/dsh-eda-selection/client
+		*/
+		const inject = [
+			"slots",
+			"locale",
+			"hqEdge"
+		];
+		/** This plugin's dictionary namespace. */
+		const EDA_SELECTION_NS = "huaqiu:eda-selection";
+		/**
+		* Resolve the `hqEdge` service defensively.
+		*
+		* `inject` already guarantees it exists by `apply()` time; the try/catch and
+		* the shape checks keep a standalone DSH (no edge-bridge) from taking the
+		* plugin down. In that case the chip simply never renders.
+		*/
+		function getHqEdge(ctx) {
+			try {
+				const edge = ctx.get("hqEdge");
+				if (!edge || !edge.selection || typeof edge.selection.getCurrent !== "function") return void 0;
+				return edge;
+			} catch {
+				return;
+			}
+		}
+		/**
+		* Read and normalize the current snapshot from the bridge.
+		*
+		* The bridge already normalizes; re-normalizing here keeps this plugin honest
+		* when pointed at an older bridge (or a test double) that does not.
+		*/
+		function readSnapshot(edge) {
+			if (!edge) return null;
+			try {
+				return normalizeSelectionSnapshot(edge.selection?.getCurrent());
+			} catch {
+				return null;
+			}
+		}
+		/**
+		* The dock component: subscribes to the bridge and renders the chip.
+		*
+		* A hook rather than a plain read, because the snapshot arrives asynchronously
+		* (the bridge's first poll lands after this component mounts).
+		*/
+		function SelectionDock({ t, getEdge }) {
+			const [snapshot, setSnapshot] = (0, react.useState)(null);
+			(0, react.useEffect)(() => {
+				const edge = getEdge();
+				if (!edge || typeof edge.selection?.onChanged !== "function") {
+					setSnapshot(null);
+					return;
+				}
+				setSnapshot(readSnapshot(edge));
+				let alive = true;
+				const dispose = edge.selection.onChanged((next) => {
+					if (!alive) return;
+					setSnapshot(normalizeSelectionSnapshot(next));
+				});
+				return () => {
+					alive = false;
+					dispose();
+				};
+			}, [getEdge]);
+			return (0, react.createElement)(SelectionChip, {
+				snapshot,
+				t
+			});
+		}
+		/**
+		* Install the dock entry on the running client context.
+		*
+		* Never throws: a deployment without the slot service, the locale service, or
+		* the `hqEdge` bridge must still load — it simply shows no chip.
+		*/
+		function apply(ctx) {
+			const locale = ctx.locale;
+			if (locale && typeof locale.register === "function") try {
+				locale.register(EDA_SELECTION_NS, {
+					zh,
+					en
+				});
+			} catch {}
+			const t = locale && typeof locale.bind === "function" ? locale.bind(EDA_SELECTION_NS) : (key) => key;
+			const getEdge = () => getHqEdge(ctx);
+			const slots = ctx.slots;
+			if (!slots || typeof slots.inject !== "function" || typeof slots.register !== "function") return;
+			ctx.effect?.(() => slots.inject("conversation.input.dock", () => slots.register({
+				name: "conversation.input.dock",
+				id: "eda-selection",
+				order: 5,
+				label: () => t("dock.label"),
+				locale: EDA_SELECTION_NS
+			}, () => (0, react.createElement)(SelectionDock, {
+				t,
+				getEdge
+			}))), "huaqiu eda-selection: composer dock chip");
+		}
+		//#endregion
+		exports.EDA_SELECTION_NS = EDA_SELECTION_NS;
+		exports.SelectionDock = SelectionDock;
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":["createElement","useState","createElement"],"sources":["../src/client/chip-text.ts","../src/client/SelectionChip.tsx","../src/client/locales.ts","../src/client/hq-edge.ts","../src/client/index.ts"],"sourcesContent":["/**\n * Pure label formatting for the ambient `Current selection` chip.\n *\n * Deliberately free of React and of the cordis context so the text the user\n * reads is unit-testable on its own — the same call\n * `@huaqiu/dsh-tool-symbol-footprint` makes for its sidebar copy.\n *\n * ── Grounding rule ──────────────────────────────────────────────────────────\n * The chip may only state what the host actually reported:\n *\n *   - the item COUNT (`item_count`) — never inferred from `labels.length`,\n *     because the host truncates the label list to a small bound;\n *   - the editor identity (`editor`), and only when it is one we model;\n *   - a BOUNDED label list, explicitly introduced as a partial view.\n *\n * Anything else — \"the selected footprint\", \"net N$12\", a guessed type — would\n * be a claim the summary does not support, and the agent has the real entity\n * ids one tool call away.\n *\n * @module\n */\nimport type { SelectionEditorName, SelectionSnapshot } from './hq-edge.js'\n\n/** Translation function shape (the locale service's `bind` result). */\nexport type Translate = (key: string, params?: Record<string, unknown>) => string\n\n/** Fallback translator: the key itself, so a missing dictionary is never blank. */\nexport const identityTranslate: Translate = (key) => key\n\n/** Editor display name for one editor identity. */\nexport function editorLabel(\n  editor: SelectionEditorName,\n  t: Translate = identityTranslate,\n): string {\n  switch (editor) {\n    case 'PCB':\n      return t('editor.pcb')\n    case 'SCHEMATIC':\n      return t('editor.schematic')\n    default:\n      return t('editor.unspecified')\n  }\n}\n\n/**\n * `\"{count} items\"` with the singular form honoured for one item.\n *\n * Both languages ship a dedicated singular key, so English reads \"1 item\"\n * rather than \"1 items\".\n */\nexport function itemCountLabel(count: number, t: Translate = identityTranslate): string {\n  return count === 1 ? t('chip.item') : t('chip.items', { count })\n}\n\n/**\n * How many labels the chip may append after the count.\n *\n * The host already bounds the list (8 entries × 64 chars), but the chip is one\n * line of ambient UI, so it shows fewer than the host is willing to send.\n */\nexport const MAX_CHIP_LABELS = 3\n\n/**\n * The bounded, comma-joined label suffix, or `''` when there is nothing to show.\n *\n * The separator is a plain comma plus a space rather than a locale-specific\n * list separator: the chip is a compact ambient indicator, and the host's\n * labels are identifiers (R1, U3, …) that read the same in both languages.\n */\nexport function labelSuffix(labels: readonly string[]): string {\n  return labels.slice(0, MAX_CHIP_LABELS).join(', ')\n}\n\n/**\n * The full chip text, e.g. `Current selection · 3 items (PCB): R1, R2, R3`.\n *\n * Returns `''` for anything that must NOT be rendered — an unknown state\n * (`null`) or a known-empty selection. One gate for both, so the chip and the\n * prompt section can never disagree about when the selection exists.\n */\nexport function formatSelectionChip(\n  snapshot: SelectionSnapshot | null,\n  t: Translate = identityTranslate,\n): string {\n  if (snapshot === null || !snapshot.hasSelection || snapshot.itemCount <= 0) return ''\n\n  const parts: string[] = [t('chip.label'), t('chip.sep'), itemCountLabel(snapshot.itemCount, t)]\n\n  // The editor is parenthesised only when it is one we model; UNSPECIFIED\n  // means the host has not identified a focused editor, and \"(editor)\" would\n  // be noise.\n  if (snapshot.editor !== 'UNSPECIFIED') {\n    parts.push(`(${editorLabel(snapshot.editor, t)})`)\n  }\n\n  const labels = labelSuffix(snapshot.labels)\n\n  // Appended WITHOUT a joining space: the separator lives inside the localized\n  // string (`': {labels}'`), and a space before a colon reads wrong in both\n  // languages.\n  return labels.length > 0 ? `${parts.join(' ')}${t('chip.labels', { labels })}` : parts.join(' ')\n}\n\n/** Screen-reader label for the chip. */\nexport function selectionChipAriaLabel(\n  snapshot: SelectionSnapshot | null,\n  t: Translate = identityTranslate,\n): string {\n  if (snapshot === null || !snapshot.hasSelection || snapshot.itemCount <= 0) return ''\n  return t('chip.aria', { count: snapshot.itemCount })\n}\n","/**\n * The ambient `Current selection` chip — the browser half's only visible\n * surface.\n *\n * It is a passive indicator: it renders what the host published and nothing\n * else. There is no click action (the agent reaches the real selection through\n * the existing EDA tools), no expand affordance, and no per-item type claim.\n *\n * ── When it renders ─────────────────────────────────────────────────────────\n * Only for a snapshot with `hasSelection && itemCount > 0`. Both UNKNOWN\n * (`null` — nothing published yet, or the sync failed) and KNOWN-EMPTY\n * (`hasSelection: false` with a real revision) render NOTHING. Rendering\n * either of them would put a chip on screen that the host does not back.\n *\n * @module\n */\nimport { createElement, type CSSProperties, type ReactElement } from 'react'\nimport type { SelectionSnapshot } from './hq-edge.js'\nimport {\n  formatSelectionChip,\n  selectionChipAriaLabel,\n  type Translate,\n} from './chip-text.js'\n\nconst ROOT: CSSProperties = {\n  display: 'inline-flex',\n  alignItems: 'center',\n  gap: 6,\n  // The dock is full-width; the chip itself is only as wide as its text so it\n  // reads as an ambient tag rather than a toolbar.\n  alignSelf: 'flex-start',\n  maxWidth: '100%',\n  padding: '3px 10px',\n  borderRadius: 999,\n  boxSizing: 'border-box',\n  fontSize: 12,\n  lineHeight: '18px',\n  color: 'var(--dsw-alias-label-secondary)',\n  background: 'color-mix(in srgb, var(--dsw-alias-label-primary) 5%, transparent)',\n  border: '1px solid color-mix(in srgb, var(--dsw-alias-label-primary) 14%, transparent)',\n}\n\n/** The leading dot — the only ornament, and it carries no meaning. */\nconst DOT: CSSProperties = {\n  width: 6,\n  height: 6,\n  borderRadius: '50%',\n  flex: '0 0 auto',\n  background: 'var(--dsw-alias-state-success, #34c759)',\n}\n\nconst TEXT: CSSProperties = {\n  // One line, ellipsised. The label list is host-bounded and already short.\n  overflow: 'hidden',\n  textOverflow: 'ellipsis',\n  whiteSpace: 'nowrap',\n}\n\nexport interface SelectionChipProps {\n  /** The latest snapshot, or `null` when the state is unknown. */\n  snapshot: SelectionSnapshot | null\n  /** Bound dictionary (the entry's locale seat). */\n  t: Translate\n}\n\n/**\n * Render the chip, or `null` when there is nothing grounded to show.\n *\n * Returning `null` (rather than an empty fragment) lets the dock skip the row\n * entirely, so an absent selection costs no vertical space in the composer.\n */\nexport function SelectionChip({ snapshot, t }: SelectionChipProps): ReactElement | null {\n  const text = formatSelectionChip(snapshot, t)\n\n  if (text.length === 0) return null\n\n  const aria = selectionChipAriaLabel(snapshot, t)\n\n  return createElement(\n    'div',\n    {\n      style: ROOT,\n      // `data-*` markers so the entry can be identified in tests and by the\n      // host's own diagnostics without depending on the copy.\n      'data-dsh-plugin': 'huaqiu-eda-selection',\n      'data-dsh-part': 'selection-chip',\n      'data-editor': snapshot?.editor ?? 'UNSPECIFIED',\n      'data-revision': snapshot?.revision ?? '',\n      role: 'status',\n      'aria-label': aria.length > 0 ? aria : undefined,\n    },\n    createElement('span', { style: DOT, 'aria-hidden': true }),\n    createElement('span', { style: TEXT }, text),\n  )\n}\n","/**\n * zh / en copy for the ambient `Current selection` dock entry.\n *\n * Chinese is the source of truth: `EdaSelectionKey` is derived from it and\n * `en` is typed against it, so a key added to one language without the other\n * is a COMPILE error rather than a silent Chinese fallback at runtime.\n *\n * Kept in its own module (rather than inlined in the component) so the copy is\n * reviewable on its own and the test file can assert bilingual balance\n * directly, mirroring `@huaqiu/dsh-auth` / `@huaqiu/dsh-tool-schematic-gen`.\n */\n\nexport const zh = {\n  /** Dock-entry label shown wherever the owner projects one. */\n  'dock.label': '当前选中',\n  /** The chip itself: \"Current selection · 3 items (PCB)\". */\n  'chip.label': '当前选中',\n  'chip.sep': '·',\n  /** Editor names, spelled for a human reader. */\n  'editor.pcb': 'PCB',\n  'editor.schematic': '原理图',\n  'editor.unspecified': '编辑器',\n  /** \"{count} items\" / \"{count} 项\". */\n  'chip.items': '{count} 项',\n  /** One item — English needs the singular form. */\n  'chip.item': '1 项',\n  /** Screen-reader label for the chip. */\n  'chip.aria': '当前编辑器选中 {count} 项',\n  /** Bounded label list, shown after the count when the host supplied any. */\n  'chip.labels': '：{labels}',\n} as const\n\nexport type EdaSelectionKey = keyof typeof zh\n\nexport const en: Record<EdaSelectionKey, string> = {\n  'dock.label': 'Current selection',\n  'chip.label': 'Current selection',\n  'chip.sep': '·',\n  'editor.pcb': 'PCB',\n  'editor.schematic': 'Schematic',\n  'editor.unspecified': 'editor',\n  'chip.items': '{count} items',\n  'chip.item': '1 item',\n  'chip.aria': 'Current editor selection: {count} items',\n  'chip.labels': ': {labels}',\n}\n","/**\n * Structural view of the `hqEdge` host service's `selection` face.\n *\n * Declared structurally and NEVER imported from `@hqedge/dsh-edge-bridge`:\n * that package is a DSH host plugin (its root export is a cordis entry), so\n * importing it here would pull a plugin into a plugin. The contract is instead\n * pinned by the edge-bridge's own unit tests, which assert the exact same\n * field names and semantics this interface describes.\n *\n * Both halves of the bridge publish this shape, and both normalise it through\n * the same `normalizeSelectionSnapshot` rules — so a browser-side chip and a\n * node-side prompt provider reading the same snapshot always agree.\n *\n * @module\n */\n\n/** Editor identity, as an enum NAME (never the wire number). */\nexport type SelectionEditorName = 'UNSPECIFIED' | 'SCHEMATIC' | 'PCB'\n\n/**\n * One selection summary.\n *\n * `revision` is a STRING: protobuf uint64 crosses the HTTP boundary as bigint,\n * and `JSON.stringify` throws on bigint, so hq-edge serialises it as a string.\n */\nexport interface SelectionSnapshot {\n  /** Whether the FOCUSED editor currently has a selection. */\n  hasSelection: boolean\n  /** Number of selected items. Zero when `hasSelection` is false. */\n  itemCount: number\n  /** Which editor the selection belongs to. */\n  editor: SelectionEditorName\n  /**\n   * Bounded, display-only labels (reference designators, symbol names, …).\n   *\n   * Host-truncated to a small fixed count and per-label length. Treat as a\n   * PARTIAL view: never infer `itemCount` from `labels.length`, and never\n   * claim these are all the selected items.\n   */\n  labels: string[]\n  /** Monotonic per-host revision. Empty before the first published summary. */\n  revision: string\n}\n\n/** The `selection` face of the `hqEdge` host service. */\nexport interface HqEdgeSelection {\n  /**\n   * The latest known selection summary, or `null` when UNKNOWN.\n   *\n   * `null` means \"nothing has been published yet, or the sync failed\" — which\n   * is deliberately NOT the same thing as a known-empty selection. A consumer\n   * must render nothing for either, but must never treat `null` as\n   * \"definitely nothing selected\".\n   */\n  getCurrent(): SelectionSnapshot | null\n  /**\n   * Subscribe to selection changes. Fires immediately with the current state\n   * when one is already known.\n   * @returns a disposer removing exactly this listener.\n   */\n  onChanged(listener: (selection: SelectionSnapshot | null) => void): () => void\n}\n\n/** The slice of the `hqEdge` service this plugin consumes. */\nexport interface HqEdgeLike {\n  selection?: HqEdgeSelection\n}\n\n/**\n * Normalize one raw summary into {@link SelectionSnapshot}, or `null` when it\n * carries no usable state.\n *\n * The bridge already normalizes, but this plugin can be pointed at a host\n * service that predates the selection face (or at a hand-rolled test double),\n * so the same defensive rules are applied again here:\n *\n *   - null / undefined / non-object → `null` (unknown)\n *   - `hasSelection` not a boolean → `null` (cannot tell selected from not)\n *   - unknown editor name → `UNSPECIFIED`\n *   - non-string labels are dropped; the array is copied\n *\n * A well-formed `hasSelection: false` is KEPT: that is a known-empty state,\n * and dropping it would erase the distinction the whole design rests on.\n *\n * @param raw - value read from `hqEdge.selection.getCurrent()`.\n * @returns the normalized snapshot, or `null` for unknown/malformed.\n */\nexport function normalizeSelectionSnapshot(raw: unknown): SelectionSnapshot | null {\n  if (raw === null || raw === undefined) return null\n  if (typeof raw !== 'object' || Array.isArray(raw)) return null\n\n  const record = raw as Record<string, unknown>\n\n  if (typeof record.hasSelection !== 'boolean') return null\n\n  const itemCount =\n    typeof record.itemCount === 'number' && Number.isFinite(record.itemCount) && record.itemCount > 0\n      ? Math.floor(record.itemCount)\n      : 0\n\n  const editor = record.editor\n  const knownEditor: SelectionEditorName =\n    editor === 'SCHEMATIC' || editor === 'PCB' ? editor : 'UNSPECIFIED'\n\n  const labels = Array.isArray(record.labels)\n    ? record.labels.filter((label): label is string => typeof label === 'string')\n    : []\n\n  const revision =\n    typeof record.revision === 'string'\n      ? record.revision\n      : typeof record.revision === 'number' && Number.isFinite(record.revision)\n        ? String(record.revision)\n        : ''\n\n  return { hasSelection: record.hasSelection, itemCount, editor: knownEditor, labels, revision }\n}\n\n/**\n * Whether a snapshot is worth surfacing at all.\n *\n * Both the chip and the prompt section use this single gate, so the two can\n * never disagree about when the selection \"exists\". Unknown (`null`) and\n * known-empty both answer \"no\" — but for different reasons, and the chip keeps\n * them apart internally so a later transition is not swallowed.\n */\nexport function hasVisibleSelection(snapshot: SelectionSnapshot | null): boolean {\n  return snapshot !== null && snapshot.hasSelection && snapshot.itemCount > 0\n}\n","/**\n * `@huaqiu/dsh-eda-selection` — browser half.\n *\n * Contributes ONE entry to the public `conversation.input.dock` slot: an\n * ambient `Current selection · N items (editor)` chip that appears above the\n * composer whenever the FOCUSED KiCad editor has a selection, and disappears\n * the moment it does not.\n *\n * ── Where the state comes from ──────────────────────────────────────────────\n * The `hqEdge` host service provided by `@hqedge/dsh-edge-bridge`. Its\n * `selection` face is fed by the bridge's OWN `/runtime/dsh` poll, so this\n * plugin adds NO second polling loop and never talks to HQ Edge itself.\n *\n * `inject` declares `hqEdge`, so DSH holds this plugin's activation until the\n * bridge has provided it — `ctx.get('hqEdge')` inside `apply()` therefore\n * resolves. The accessor is still built lazily (a closure, not a captured\n * value) because the service object is created once but its `selection` face\n * is read on every subscription.\n *\n * The bridge's `onChanged` replays the current state immediately when one is\n * already known, so a chip mounted after the first summary does not wait for a\n * change; and it returns a disposer, which is what the slot's own lifecycle\n * expects.\n *\n * ── Unknown vs known-empty ──────────────────────────────────────────────────\n * `hqEdge.selection.getCurrent()` returns `null` when the state is UNKNOWN\n * (nothing published yet, or the sync failed). That is NOT a selection, and\n * the chip renders nothing for it — a chip must never appear on screen that\n * the host does not currently back.\n *\n * ── No second composer ──────────────────────────────────────────────────────\n * This entry never touches the draft, the input state, or the reference\n * pipeline. It is a read-only projection of host state; the agent reaches the\n * real selection through the existing EDA selection tools.\n *\n * @module @huaqiu/dsh-eda-selection/client\n */\nimport { createElement, useEffect, useState, type ReactElement } from 'react'\nimport type {} from '@deepseek-ai/dsh-client-ui-slots'\nimport { SelectionChip } from './SelectionChip.js'\nimport { en, zh, type EdaSelectionKey } from './locales.js'\nimport {\n  normalizeSelectionSnapshot,\n  type HqEdgeLike,\n  type SelectionSnapshot,\n} from './hq-edge.js'\n\nexport const inject = ['slots', 'locale', 'hqEdge'] as const\n\n/** This plugin's dictionary namespace. */\nexport const EDA_SELECTION_NS = 'huaqiu:eda-selection'\n\ndeclare module '@deepseek-ai/dsh-client-ui-slots' {\n  interface LocaleNamespaceMap {\n    'huaqiu:eda-selection': EdaSelectionKey\n  }\n}\n\n/**\n * Minimal structural client context (the DSH client runtime provides these\n * faces). Declared structurally, never imported, so the package stays\n * independently installable — the same pattern as\n * `@huaqiu/dsh-tool-schematic-gen` and `@huaqiu/dsh-huaqiu-about`.\n */\nexport interface ClientContext {\n  slots?: {\n    inject(key: string, callback: () => () => void): () => void\n    register(\n      spec: {\n        name: string\n        id?: string\n        order?: number\n        label?: () => string\n        locale?: string\n      },\n      component: unknown,\n    ): () => void\n  }\n  locale?: {\n    register(namespace: string, dictionaries: unknown): unknown\n    bind(namespace: string): (key: string, params?: Record<string, unknown>) => string\n  }\n  get<T = unknown>(name: string): T | undefined\n  effect?(fn: () => (() => void) | void, label?: string): void\n}\n\n/** Translation function shape (the locale service's `bind` result). */\nexport type Translate = (key: string, params?: Record<string, unknown>) => string\n\n/**\n * Resolve the `hqEdge` service defensively.\n *\n * `inject` already guarantees it exists by `apply()` time; the try/catch and\n * the shape checks keep a standalone DSH (no edge-bridge) from taking the\n * plugin down. In that case the chip simply never renders.\n */\nfunction getHqEdge(ctx: ClientContext): HqEdgeLike | undefined {\n  try {\n    const edge = ctx.get<HqEdgeLike | undefined>('hqEdge')\n    if (!edge || !edge.selection || typeof edge.selection.getCurrent !== 'function') return undefined\n    return edge\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Read and normalize the current snapshot from the bridge.\n *\n * The bridge already normalizes; re-normalizing here keeps this plugin honest\n * when pointed at an older bridge (or a test double) that does not.\n */\nfunction readSnapshot(edge: HqEdgeLike | undefined): SelectionSnapshot | null {\n  if (!edge) return null\n  try {\n    return normalizeSelectionSnapshot(edge.selection?.getCurrent())\n  } catch {\n    return null\n  }\n}\n\nexport interface SelectionDockProps {\n  /** Bound dictionary, injected by the client entry. */\n  t: Translate\n  /** Lazy bridge accessor — a closure over `ctx`, never a captured value. */\n  getEdge: () => HqEdgeLike | undefined\n}\n\n/**\n * The dock component: subscribes to the bridge and renders the chip.\n *\n * A hook rather than a plain read, because the snapshot arrives asynchronously\n * (the bridge's first poll lands after this component mounts).\n */\nexport function SelectionDock({ t, getEdge }: SelectionDockProps): ReactElement | null {\n  const [snapshot, setSnapshot] = useState<SelectionSnapshot | null>(null)\n\n  useEffect(() => {\n    const edge = getEdge()\n\n    // No bridge (standalone DSH) or a bridge without the selection face\n    // (older edge-bridge): render nothing, permanently. Not an error.\n    if (!edge || typeof edge.selection?.onChanged !== 'function') {\n      setSnapshot(null)\n      return\n    }\n\n    // `onChanged` replays the current state immediately when one is known, so\n    // this read is only needed for the unknown-at-mount case.\n    setSnapshot(readSnapshot(edge))\n\n    let alive = true\n    const dispose = edge.selection.onChanged((next) => {\n      if (!alive) return\n      // Normalize on the way in too: a listener must never be handed a shape\n      // it did not expect, whatever the bridge did.\n      setSnapshot(normalizeSelectionSnapshot(next))\n    })\n\n    return () => {\n      alive = false\n      dispose()\n    }\n  }, [getEdge])\n\n  return createElement(SelectionChip, { snapshot, t })\n}\n\n/**\n * Install the dock entry on the running client context.\n *\n * Never throws: a deployment without the slot service, the locale service, or\n * the `hqEdge` bridge must still load — it simply shows no chip.\n */\nexport function apply(ctx: ClientContext): void {\n  // Dictionaries first, so the first render already has localized text. The\n  // untyped register form is used because this namespace is declared by this\n  // package (not by DSH), which keeps DSH core untouched.\n  const locale = ctx.locale\n  if (locale && typeof locale.register === 'function') {\n    try {\n      locale.register(EDA_SELECTION_NS, { zh, en })\n    } catch {\n      // A duplicate registration (hot reload, double mount) is not fatal —\n      // the first registration's dictionaries are already live.\n    }\n  }\n\n  const t: Translate =\n    locale && typeof locale.bind === 'function'\n      ? locale.bind(EDA_SELECTION_NS)\n      : (key: string) => key\n\n  const getEdge = (): HqEdgeLike | undefined => getHqEdge(ctx)\n\n  const slots = ctx.slots\n  if (!slots || typeof slots.inject !== 'function' || typeof slots.register !== 'function') {\n    return\n  }\n\n  ctx.effect?.(\n    () =>\n      slots.inject('conversation.input.dock', () =>\n        slots.register(\n          {\n            name: 'conversation.input.dock',\n            // Our own id: a fresh id is added BESIDE the shipped entries\n            // (queue / todo / goal) instead of replacing one of them.\n            id: 'eda-selection',\n            // Ascending among the dock entries. `queue` is 20 and `todo` is 0,\n            // so 5 puts the ambient chip near the top — closest to the composer\n            // it describes — without displacing the todo dock at 0.\n            order: 5,\n            label: () => t('dock.label'),\n            locale: EDA_SELECTION_NS,\n          },\n          () => createElement(SelectionDock, { t, getEdge }),\n        ),\n      ),\n    'huaqiu eda-selection: composer dock chip',\n  )\n}\n"],"mappings":"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"}

package/lib/index.d.mts

@@ -0,0 +1,137 @@
+//#region src/client/hq-edge.d.ts
+/**
+ * Structural view of the `hqEdge` host service's `selection` face.
+ *
+ * Declared structurally and NEVER imported from `@hqedge/dsh-edge-bridge`:
+ * that package is a DSH host plugin (its root export is a cordis entry), so
+ * importing it here would pull a plugin into a plugin. The contract is instead
+ * pinned by the edge-bridge's own unit tests, which assert the exact same
+ * field names and semantics this interface describes.
+ *
+ * Both halves of the bridge publish this shape, and both normalise it through
+ * the same `normalizeSelectionSnapshot` rules — so a browser-side chip and a
+ * node-side prompt provider reading the same snapshot always agree.
+ *
+ * @module
+ */
+/** Editor identity, as an enum NAME (never the wire number). */
+type SelectionEditorName = 'UNSPECIFIED' | 'SCHEMATIC' | 'PCB';
+/**
+ * One selection summary.
+ *
+ * `revision` is a STRING: protobuf uint64 crosses the HTTP boundary as bigint,
+ * and `JSON.stringify` throws on bigint, so hq-edge serialises it as a string.
+ */
+interface SelectionSnapshot {
+  /** Whether the FOCUSED editor currently has a selection. */
+  hasSelection: boolean;
+  /** Number of selected items. Zero when `hasSelection` is false. */
+  itemCount: number;
+  /** Which editor the selection belongs to. */
+  editor: SelectionEditorName;
+  /**
+   * Bounded, display-only labels (reference designators, symbol names, …).
+   *
+   * Host-truncated to a small fixed count and per-label length. Treat as a
+   * PARTIAL view: never infer `itemCount` from `labels.length`, and never
+   * claim these are all the selected items.
+   */
+  labels: string[];
+  /** Monotonic per-host revision. Empty before the first published summary. */
+  revision: string;
+}
+/** The `selection` face of the `hqEdge` host service. */
+interface HqEdgeSelection {
+  /**
+   * The latest known selection summary, or `null` when UNKNOWN.
+   *
+   * `null` means "nothing has been published yet, or the sync failed" — which
+   * is deliberately NOT the same thing as a known-empty selection. A consumer
+   * must render nothing for either, but must never treat `null` as
+   * "definitely nothing selected".
+   */
+  getCurrent(): SelectionSnapshot | null;
+  /**
+   * Subscribe to selection changes. Fires immediately with the current state
+   * when one is already known.
+   * @returns a disposer removing exactly this listener.
+   */
+  onChanged(listener: (selection: SelectionSnapshot | null) => void): () => void;
+}
+/** The slice of the `hqEdge` service this plugin consumes. */
+interface HqEdgeLike {
+  selection?: HqEdgeSelection;
+}
+//#endregion
+//#region src/prompt.d.ts
+/** Unique prompt-section name. */
+declare const EDA_SELECTION_SECTION = "eda:selection";
+/**
+ * Centrally allocated placement: 590, between DSH's `PLAN_POLICY` (500) and
+ * `TEAM_POLICY` (600).
+ *
+ * That is where the sibling Huaqiu tool-policy section
+ * (`huaqiu:schematic-gen`) already sits, so both Huaqiu policy blocks are
+ * adjacent and both precede the tool-list sections (`TOOL_*` at 1000+) they
+ * refer to. `ctx.systemPrompt.getSectionOrder()` only resolves DSH's own named
+ * positions, so the number is pinned here and asserted by a test.
+ */
+declare const EDA_SELECTION_SECTION_ORDER = 590;
+/**
+ * Structural view of `ctx.systemPrompt` — only the face we use.
+ *
+ * `text` accepts a provider, which the registry re-evaluates at every
+ * assembly with that assembly's `AssembleContext`. Returning `''` contributes
+ * nothing: `renderPrompt` filters empty sections out before joining.
+ */
+interface SystemPromptLike {
+  section(section: {
+    name: string;
+    order: number;
+    text: string | ((context: unknown) => string);
+  }): () => void;
+}
+/**
+ * Build the section text for one snapshot.
+ *
+ * Returns `''` for every "contribute nothing" case — an unknown state
+ * (`null`) or a known-empty selection. One gate for both, so the section and
+ * the browser chip can never disagree about when the selection exists.
+ *
+ * @param snapshot - the current summary, or `null` when unknown.
+ * @returns the section text, or `''` when it must contribute nothing.
+ */
+declare function edaSelectionSectionText(snapshot: SelectionSnapshot | null): string;
+/**
+ * Register the dynamic selection section.
+ *
+ * Never throws: a DSH deployment without the prompt service, or one where a
+ * duplicate registration races, must still load. A duplicate is the expected
+ * hot-reload case, so it is swallowed rather than surfaced.
+ *
+ * @param systemPrompt - `ctx.systemPrompt`, or undefined.
+ * @param readSelection - reads the current summary. Must not perform I/O.
+ * @returns the section's disposer, or `undefined` when nothing was registered.
+ */
+declare function registerEdaSelectionSection(systemPrompt: unknown, readSelection: () => SelectionSnapshot | null): (() => void) | undefined;
+//#endregion
+//#region src/index.d.ts
+/** Plugin id — matches package.json. */
+declare const name = "@huaqiu/dsh-eda-selection";
+/**
+ * Cordis services this half depends on.
+ *
+ * `hqEdge` is the bridge's node-side twin. It is declared here so DSH holds
+ * this plugin until the bridge has provided it, and every read is still
+ * guarded: a standalone DSH deployment without the bridge must not fail.
+ *
+ * `systemPrompt` carries the section. Declared for the same reason.
+ */
+declare const inject: readonly ["hqEdge", "systemPrompt"];
+/** Host plugin body — register the dynamic selection section. */
+declare function apply(ctx: {
+  hqEdge?: HqEdgeLike;
+  systemPrompt?: SystemPromptLike;
+}): () => void;
+//#endregion
+export { EDA_SELECTION_SECTION, EDA_SELECTION_SECTION_ORDER, type SystemPromptLike, apply, edaSelectionSectionText, inject, name, registerEdaSelectionSection };