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

package/src/client/index.ts

@@ -0,0 +1,222 @@
+/**
+ * `@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
+ */
+import { createElement, useEffect, useState, type ReactElement } from 'react'
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+import { SelectionChip } from './SelectionChip.js'
+import { en, zh, type EdaSelectionKey } from './locales.js'
+import {
+  normalizeSelectionSnapshot,
+  type HqEdgeLike,
+  type SelectionSnapshot,
+} from './hq-edge.js'
+
+export const inject = ['slots', 'locale', 'hqEdge'] as const
+
+/** This plugin's dictionary namespace. */
+export const EDA_SELECTION_NS = 'huaqiu:eda-selection'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    'huaqiu:eda-selection': EdaSelectionKey
+  }
+}
+
+/**
+ * Minimal structural client context (the DSH client runtime provides these
+ * faces). Declared structurally, never imported, so the package stays
+ * independently installable — the same pattern as
+ * `@huaqiu/dsh-tool-schematic-gen` and `@huaqiu/dsh-huaqiu-about`.
+ */
+export interface ClientContext {
+  slots?: {
+    inject(key: string, callback: () => () => void): () => void
+    register(
+      spec: {
+        name: string
+        id?: string
+        order?: number
+        label?: () => string
+        locale?: string
+      },
+      component: unknown,
+    ): () => void
+  }
+  locale?: {
+    register(namespace: string, dictionaries: unknown): unknown
+    bind(namespace: string): (key: string, params?: Record<string, unknown>) => string
+  }
+  get<T = unknown>(name: string): T | undefined
+  effect?(fn: () => (() => void) | void, label?: string): void
+}
+
+/** Translation function shape (the locale service's `bind` result). */
+export type Translate = (key: string, params?: Record<string, unknown>) => string
+
+/**
+ * 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: ClientContext): HqEdgeLike | undefined {
+  try {
+    const edge = ctx.get<HqEdgeLike | undefined>('hqEdge')
+    if (!edge || !edge.selection || typeof edge.selection.getCurrent !== 'function') return undefined
+    return edge
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 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: HqEdgeLike | undefined): SelectionSnapshot | null {
+  if (!edge) return null
+  try {
+    return normalizeSelectionSnapshot(edge.selection?.getCurrent())
+  } catch {
+    return null
+  }
+}
+
+export interface SelectionDockProps {
+  /** Bound dictionary, injected by the client entry. */
+  t: Translate
+  /** Lazy bridge accessor — a closure over `ctx`, never a captured value. */
+  getEdge: () => HqEdgeLike | undefined
+}
+
+/**
+ * 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).
+ */
+export function SelectionDock({ t, getEdge }: SelectionDockProps): ReactElement | null {
+  const [snapshot, setSnapshot] = useState<SelectionSnapshot | null>(null)
+
+  useEffect(() => {
+    const edge = getEdge()
+
+    // No bridge (standalone DSH) or a bridge without the selection face
+    // (older edge-bridge): render nothing, permanently. Not an error.
+    if (!edge || typeof edge.selection?.onChanged !== 'function') {
+      setSnapshot(null)
+      return
+    }
+
+    // `onChanged` replays the current state immediately when one is known, so
+    // this read is only needed for the unknown-at-mount case.
+    setSnapshot(readSnapshot(edge))
+
+    let alive = true
+    const dispose = edge.selection.onChanged((next) => {
+      if (!alive) return
+      // Normalize on the way in too: a listener must never be handed a shape
+      // it did not expect, whatever the bridge did.
+      setSnapshot(normalizeSelectionSnapshot(next))
+    })
+
+    return () => {
+      alive = false
+      dispose()
+    }
+  }, [getEdge])
+
+  return 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.
+ */
+export function apply(ctx: ClientContext): void {
+  // Dictionaries first, so the first render already has localized text. The
+  // untyped register form is used because this namespace is declared by this
+  // package (not by DSH), which keeps DSH core untouched.
+  const locale = ctx.locale
+  if (locale && typeof locale.register === 'function') {
+    try {
+      locale.register(EDA_SELECTION_NS, { zh, en })
+    } catch {
+      // A duplicate registration (hot reload, double mount) is not fatal —
+      // the first registration's dictionaries are already live.
+    }
+  }
+
+  const t: Translate =
+    locale && typeof locale.bind === 'function'
+      ? locale.bind(EDA_SELECTION_NS)
+      : (key: string) => key
+
+  const getEdge = (): HqEdgeLike | undefined => 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',
+            // Our own id: a fresh id is added BESIDE the shipped entries
+            // (queue / todo / goal) instead of replacing one of them.
+            id: 'eda-selection',
+            // Ascending among the dock entries. `queue` is 20 and `todo` is 0,
+            // so 5 puts the ambient chip near the top — closest to the composer
+            // it describes — without displacing the todo dock at 0.
+            order: 5,
+            label: () => t('dock.label'),
+            locale: EDA_SELECTION_NS,
+          },
+          () => createElement(SelectionDock, { t, getEdge }),
+        ),
+      ),
+    'huaqiu eda-selection: composer dock chip',
+  )
+}

package/src/client/locales.ts

@@ -0,0 +1,46 @@
+/**
+ * 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`.
+ */
+
+export 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}',
+} as const
+
+export type EdaSelectionKey = keyof typeof zh
+
+export const en: Record<EdaSelectionKey, string> = {
+  '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}',
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * `@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
+ */
+import {
+  EDA_SELECTION_SECTION,
+  EDA_SELECTION_SECTION_ORDER,
+  edaSelectionSectionText,
+  registerEdaSelectionSection,
+  type SystemPromptLike,
+} from './prompt.js'
+import { normalizeSelectionSnapshot, type HqEdgeLike } from './client/hq-edge.js'
+import { getLogger } from '@huaqiu/dsh-plugin-log'
+
+/** Plugin id — matches package.json. */
+export 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.
+ */
+export const inject = ['hqEdge', 'systemPrompt'] as const
+
+/** Shared component name for the unified DSH-plugin log. */
+const COMPONENT = 'dsh-eda-selection'
+const log = getLogger(COMPONENT)
+
+/** Host plugin body — register the dynamic selection section. */
+export function apply(ctx: {
+  hqEdge?: HqEdgeLike
+  systemPrompt?: SystemPromptLike
+}): () => void {
+  // Lazy, never captured once: the bridge's `selection` face is a live object,
+  // but reading it lazily keeps this plugin working if the service is swapped.
+  const readSelection = (): ReturnType<typeof normalizeSelectionSnapshot> => {
+    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 === undefined) {
+    log.warn('systemPrompt service unavailable — the selection prompt section was not registered')
+  }
+
+  return () => {
+    dispose?.()
+  }
+}
+
+export {
+  EDA_SELECTION_SECTION,
+  EDA_SELECTION_SECTION_ORDER,
+  edaSelectionSectionText,
+  registerEdaSelectionSection,
+  type SystemPromptLike,
+}

package/src/prompt.ts

@@ -0,0 +1,127 @@
+/**
+ * The `eda:selection` system-prompt section.
+ *
+ * Split out from `src/index.ts` so the text builder is unit-testable without a
+ * cordis context, a bridge, or a prompt registry — the same call
+ * `@huaqiu/dsh-tool-schematic-gen` makes for its `prompt.ts`.
+ *
+ * @module
+ */
+import type { SelectionSnapshot } from './client/hq-edge.js'
+
+/** Unique prompt-section name. */
+export 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.
+ */
+export 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.
+ */
+export interface SystemPromptLike {
+  section(section: {
+    name: string
+    order: number
+    text: string | ((context: unknown) => string)
+  }): () => void
+}
+
+/** Editor display name for the prompt (English: the prompt is model-facing). */
+function editorName(editor: SelectionSnapshot['editor']): string {
+  switch (editor) {
+    case 'PCB':
+      return 'PCB (pcbnew)'
+    case 'SCHEMATIC':
+      return 'schematic (eeschema)'
+    default:
+      return 'an unidentified editor'
+  }
+}
+
+/** How many labels the section may quote. The host already bounds the list. */
+export const MAX_SECTION_LABELS = 5
+
+/**
+ * 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.
+ */
+export function edaSelectionSectionText(snapshot: SelectionSnapshot | null): string {
+  if (snapshot === null || !snapshot.hasSelection || snapshot.itemCount <= 0) return ''
+
+  const lines: string[] = [
+    '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, MAX_SECTION_LABELS)
+  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.
+ */
+export function registerEdaSelectionSection(
+  systemPrompt: unknown,
+  readSelection: () => SelectionSnapshot | null,
+): (() => void) | undefined {
+  if (
+    systemPrompt === undefined || systemPrompt === null ||
+    typeof (systemPrompt as SystemPromptLike).section !== 'function'
+  ) {
+    return undefined
+  }
+
+  try {
+    const dispose = (systemPrompt as SystemPromptLike).section({
+      name: EDA_SELECTION_SECTION,
+      order: EDA_SELECTION_SECTION_ORDER,
+      // A provider, not a constant: the selection changes between turns and the
+      // registry re-evaluates this at every assembly. It performs NO I/O — it
+      // reads the bridge's in-memory cache.
+      text: () => edaSelectionSectionText(readSelection()),
+    })
+    return typeof dispose === 'function' ? dispose : undefined
+  } catch {
+    // Duplicate registration (hot reload) — the first one is still live.
+    return undefined
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.