Editor intelligence: hover docs and signature help (Phase 2c) #27

Split from #22. Phase 2c of the textarea editor enhancement track. Optional polish — file after Phase 2b (#26) ships.

Dependency: Phase 2a (#25 — reference data loader) must be merged first. funcDefs (system.functions.syntax and arguments) is loaded there and is the primary data source here.

Goal

Show a hover tooltip or inline parameter hints for SQL functions while typing.

Data sources (from app.state.editorReference, loaded by #25)

• funcDefs: Map<name, {syntax, arguments}> — function signatures and argument lists.
• system.documentation — Markdown description per entity. Not loaded by Editor intelligence: reference data loader and tokenizer dynamic-keyword API (Phase 2a) #25 — decide at implementation whether to load it alongside Editor intelligence: reference data loader and tokenizer dynamic-keyword API (Phase 2a) #25 (increases connect time) or fetch lazily on first hover per entity.

Pointer-events constraint

.sql-pre has pointer-events: none (see styles.css). Hover events cannot be sourced from the syntax <pre> overlay or the search/bracket overlay <pre>. The event source must be one of:

• The textarea mousemove event — compute a character offset from the mouse coords against the <pre> metrics (same font/line-height/padding), then look up the token at that offset via tokenRanges().
• The .sql-area container mousemove — same computation; avoids tying hover to <textarea> internals.

This is an open choice for implementers; the event strategy must be decided before implementation begins. Do not rely on hovering over <pre> elements.

Proposed behavior (subject to design confirmation)

• Hover: mouse over a function token shows a small tooltip with funcDefs.get(name).syntax and, if available, a one-line description from system.documentation.
• Signature help: after typing a function name followed by (, show the argument list inline below the caret — dismisses on ) or Esc.

Open design questions (resolve before implementing)

• system.documentation loading strategy: load upfront alongside Phase 2a (increases connect latency) or fetch on first hover per entity (one network call per unknown entity)?
• Tooltip visual design: floating box, inline annotation above/below cursor, or status-bar style?
• Event source: textarea mousemove or .sql-area container mousemove?
• Should signature help persist after , (moving between args) or only appear on (?

Non-goals

• Anything from Phase 1 (Editor: in-editor search/replace on the textarea (Phase 1a) #23, Editor: bracket matching and auto-close on the textarea (Phase 1b) #24) or 2a/2b (Editor intelligence: reference data loader and tokenizer dynamic-keyword API (Phase 2a) #25, Editor intelligence: autocomplete dropdown (Phase 2b) #26) — all should be done first.
• Live validation or squiggles.