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

package/lib/index.mjs

@@ -0,0 +1,171 @@
+import { getLogger } from "@huaqiu/dsh-plugin-log";
+//#region src/prompt.ts
+/** Unique prompt-section name. */
+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.
+*/
+const EDA_SELECTION_SECTION_ORDER = 590;
+/** Editor display name for the prompt (English: the prompt is model-facing). */
+function editorName(editor) {
+	switch (editor) {
+		case "PCB": return "PCB (pcbnew)";
+		case "SCHEMATIC": return "schematic (eeschema)";
+		default: return "an unidentified editor";
+	}
+}
+/**
+* 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.
+*/
+function edaSelectionSectionText(snapshot) {
+	if (snapshot === null || !snapshot.hasSelection || snapshot.itemCount <= 0) return "";
+	const lines = [
+		"Current EDA selection (Huaqiu EDA host):",
+		`- The focused editor is ${editorName(snapshot.editor)}.`,
+		`- It currently has ${snapshot.itemCount} selected item(s).`
+	];
+	const labels = snapshot.labels.slice(0, 5);
+	if (labels.length > 0) lines.push(`- Selected labels (partial, host-truncated): ${labels.join(", ")}.`);
+	lines.push("- This is a SUMMARY only. The selected items themselves are NOT in this conversation — call the existing selection tools (`get_pcb_selection`, `get_selection_netlist`) when you need the actual entities, nets or netlist. Never claim to know the selected content without calling them.");
+	return lines.join("\n");
+}
+/**
+* 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.
+*/
+function registerEdaSelectionSection(systemPrompt, readSelection) {
+	if (systemPrompt === void 0 || systemPrompt === null || typeof systemPrompt.section !== "function") return;
+	try {
+		const dispose = systemPrompt.section({
+			name: EDA_SELECTION_SECTION,
+			order: 590,
+			text: () => edaSelectionSectionText(readSelection())
+		});
+		return typeof dispose === "function" ? dispose : void 0;
+	} catch {
+		return;
+	}
+}
+//#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/index.ts
+/**
+* `@huaqiu/dsh-eda-selection` — node half.
+*
+* Registers ONE dynamic system-prompt section, `eda:selection`, that reports
+* the focused editor's selection to the agent. Nothing else: no tools, no
+* routes, no I/O.
+*
+* ── Why a section and not a context ─────────────────────────────────────────
+* A *section* is part of the system prompt (stable policy text); a *context* is
+* materialized as a durable user-role snapshot. The selection summary is
+* neither — it is ambient state that changes between turns and must not be
+* persisted into the conversation history as if the user had said it. A
+* section whose provider re-evaluates at each assembly is exactly that.
+*
+* ── Why the provider performs no I/O ────────────────────────────────────────
+* The provider reads `hqEdge.selection.getCurrent()` — an in-memory value the
+* bridge keeps fresh from its own `/runtime/dsh` poll. Prompt assembly happens
+* on the agent's hot path, so an HTTP call here would add latency to every
+* turn and could fail; a stale-but-free read is strictly better than a fresh
+* blocking one. When the value is unknown the section contributes NOTHING.
+*
+* ── What the section must not do ────────────────────────────────────────────
+* It must not imply that selection CONTENT was inserted into the conversation.
+* The summary is a count, an editor identity and a bounded label list — enough
+* to decide whether the existing selection tools are worth calling, never a
+* substitute for calling them.
+*
+* @module @huaqiu/dsh-eda-selection
+*/
+/** Plugin id — matches package.json. */
+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.
+*/
+const inject = ["hqEdge", "systemPrompt"];
+const log = getLogger("dsh-eda-selection");
+/** Host plugin body — register the dynamic selection section. */
+function apply(ctx) {
+	const readSelection = () => {
+		try {
+			const edge = ctx.hqEdge;
+			if (!edge || !edge.selection || typeof edge.selection.getCurrent !== "function") return null;
+			return normalizeSelectionSnapshot(edge.selection.getCurrent());
+		} catch {
+			return null;
+		}
+	};
+	const dispose = registerEdaSelectionSection(ctx.systemPrompt, readSelection);
+	if (dispose === void 0) log.warn("systemPrompt service unavailable — the selection prompt section was not registered");
+	return () => {
+		dispose?.();
+	};
+}
+//#endregion
+export { EDA_SELECTION_SECTION, EDA_SELECTION_SECTION_ORDER, apply, edaSelectionSectionText, inject, name, registerEdaSelectionSection };

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@huaqiu/dsh-eda-selection",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.6",
+  "description": "Ambient 'Current Selection' chip above the DSH composer plus a dynamic system-prompt section describing the focused EDA editor's selection.",
+  "type": "module",
+  "main": "./lib/index.mjs",
+  "types": "./lib/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.mts",
+      "default": "./lib/index.mjs"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.0"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@huaqiu/dsh-plugin-log": "0.5.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "^18.3.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown",
+    "test": "vitest run"
+  }
 }

package/src/client/SelectionChip.tsx

@@ -0,0 +1,95 @@
+/**
+ * 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
+ */
+import { createElement, type CSSProperties, type ReactElement } from 'react'
+import type { SelectionSnapshot } from './hq-edge.js'
+import {
+  formatSelectionChip,
+  selectionChipAriaLabel,
+  type Translate,
+} from './chip-text.js'
+
+const ROOT: CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 6,
+  // The dock is full-width; the chip itself is only as wide as its text so it
+  // reads as an ambient tag rather than a toolbar.
+  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: CSSProperties = {
+  width: 6,
+  height: 6,
+  borderRadius: '50%',
+  flex: '0 0 auto',
+  background: 'var(--dsw-alias-state-success, #34c759)',
+}
+
+const TEXT: CSSProperties = {
+  // One line, ellipsised. The label list is host-bounded and already short.
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+}
+
+export interface SelectionChipProps {
+  /** The latest snapshot, or `null` when the state is unknown. */
+  snapshot: SelectionSnapshot | null
+  /** Bound dictionary (the entry's locale seat). */
+  t: Translate
+}
+
+/**
+ * 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.
+ */
+export function SelectionChip({ snapshot, t }: SelectionChipProps): ReactElement | null {
+  const text = formatSelectionChip(snapshot, t)
+
+  if (text.length === 0) return null
+
+  const aria = selectionChipAriaLabel(snapshot, t)
+
+  return createElement(
+    'div',
+    {
+      style: ROOT,
+      // `data-*` markers so the entry can be identified in tests and by the
+      // host's own diagnostics without depending on the copy.
+      '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 : undefined,
+    },
+    createElement('span', { style: DOT, 'aria-hidden': true }),
+    createElement('span', { style: TEXT }, text),
+  )
+}

package/src/client/chip-text.ts

@@ -0,0 +1,111 @@
+/**
+ * Pure label formatting for the ambient `Current selection` chip.
+ *
+ * Deliberately free of React and of the cordis context so the text the user
+ * reads is unit-testable on its own — the same call
+ * `@huaqiu/dsh-tool-symbol-footprint` makes for its sidebar copy.
+ *
+ * ── Grounding rule ──────────────────────────────────────────────────────────
+ * The chip may only state what the host actually reported:
+ *
+ *   - the item COUNT (`item_count`) — never inferred from `labels.length`,
+ *     because the host truncates the label list to a small bound;
+ *   - the editor identity (`editor`), and only when it is one we model;
+ *   - a BOUNDED label list, explicitly introduced as a partial view.
+ *
+ * Anything else — "the selected footprint", "net N$12", a guessed type — would
+ * be a claim the summary does not support, and the agent has the real entity
+ * ids one tool call away.
+ *
+ * @module
+ */
+import type { SelectionEditorName, SelectionSnapshot } from './hq-edge.js'
+
+/** Translation function shape (the locale service's `bind` result). */
+export type Translate = (key: string, params?: Record<string, unknown>) => string
+
+/** Fallback translator: the key itself, so a missing dictionary is never blank. */
+export const identityTranslate: Translate = (key) => key
+
+/** Editor display name for one editor identity. */
+export function editorLabel(
+  editor: SelectionEditorName,
+  t: Translate = identityTranslate,
+): string {
+  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".
+ */
+export function itemCountLabel(count: number, t: Translate = identityTranslate): string {
+  return count === 1 ? t('chip.item') : t('chip.items', { count })
+}
+
+/**
+ * How many labels the chip may append after the count.
+ *
+ * The host already bounds the list (8 entries × 64 chars), but the chip is one
+ * line of ambient UI, so it shows fewer than the host is willing to send.
+ */
+export const MAX_CHIP_LABELS = 3
+
+/**
+ * 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.
+ */
+export function labelSuffix(labels: readonly string[]): string {
+  return labels.slice(0, MAX_CHIP_LABELS).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.
+ */
+export function formatSelectionChip(
+  snapshot: SelectionSnapshot | null,
+  t: Translate = identityTranslate,
+): string {
+  if (snapshot === null || !snapshot.hasSelection || snapshot.itemCount <= 0) return ''
+
+  const parts: string[] = [t('chip.label'), t('chip.sep'), itemCountLabel(snapshot.itemCount, t)]
+
+  // The editor is parenthesised only when it is one we model; UNSPECIFIED
+  // means the host has not identified a focused editor, and "(editor)" would
+  // be noise.
+  if (snapshot.editor !== 'UNSPECIFIED') {
+    parts.push(`(${editorLabel(snapshot.editor, t)})`)
+  }
+
+  const labels = labelSuffix(snapshot.labels)
+
+  // Appended WITHOUT a joining space: the separator lives inside the localized
+  // string (`': {labels}'`), and a space before a colon reads wrong in both
+  // languages.
+  return labels.length > 0 ? `${parts.join(' ')}${t('chip.labels', { labels })}` : parts.join(' ')
+}
+
+/** Screen-reader label for the chip. */
+export function selectionChipAriaLabel(
+  snapshot: SelectionSnapshot | null,
+  t: Translate = identityTranslate,
+): string {
+  if (snapshot === null || !snapshot.hasSelection || snapshot.itemCount <= 0) return ''
+  return t('chip.aria', { count: snapshot.itemCount })
+}

package/src/client/hq-edge.ts

@@ -0,0 +1,129 @@
+/**
+ * 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). */
+export 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.
+ */
+export 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. */
+export 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. */
+export interface HqEdgeLike {
+  selection?: HqEdgeSelection
+}
+
+/**
+ * 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.
+ */
+export function normalizeSelectionSnapshot(raw: unknown): SelectionSnapshot | null {
+  if (raw === null || raw === undefined) return null
+  if (typeof raw !== 'object' || Array.isArray(raw)) return null
+
+  const record = raw as Record<string, unknown>
+
+  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: SelectionEditorName =
+    editor === 'SCHEMATIC' || editor === 'PCB' ? editor : 'UNSPECIFIED'
+
+  const labels = Array.isArray(record.labels)
+    ? record.labels.filter((label): label is string => 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 }
+}
+
+/**
+ * Whether a snapshot is worth surfacing at all.
+ *
+ * Both the chip and the prompt section use this single gate, so the two can
+ * never disagree about when the selection "exists". Unknown (`null`) and
+ * known-empty both answer "no" — but for different reasons, and the chip keeps
+ * them apart internally so a later transition is not swallowed.
+ */
+export function hasVisibleSelection(snapshot: SelectionSnapshot | null): boolean {
+  return snapshot !== null && snapshot.hasSelection && snapshot.itemCount > 0
+}