Develop Icod.DCurses 1.4.0 interaction routing

Icod.DCurses-1.1.0-to-1.4.0-Development-Roadmap.md

@@ -2,101 +2,129 @@
 
 **Project:** `Icod.DCurses`  
 **Scope:** post-1.0 additive core development  
-**Published compatibility floor:** `1.2.0`  
-**Current main source package:** `1.3.0`  
+**Published compatibility floor:** `1.3.0`  
+**Current published package:** `1.3.0`  
 **Assembly version policy:** retain `1.0.0.0` through compatible additive 1.x releases  
-**Current declared runtime dependencies:** `Icod.Terminal 1.11.1`; `Icod.TermInfo 1.11.0`  
-**Planning status:** 1.3 complete, merged, and Release-qualified; 1.4 remains the approved next development release
+**Current declared runtime dependencies:** `Icod.Terminal 1.13.0`; `Icod.TermInfo 1.12.0`  
+**Planning status:** 1.3 is complete/published; 1.4 has completed T1401-T1411 and is in T1412 stable-source qualification
 
 ---
 
 ## Release sequence
 
 ```text
 1.1.0  semantic cell metadata + hyperlinks                  complete/published history
-1.2.0  panels/layers + z-order composition                  complete/published
-1.3.0  layout + resize primitives                           complete/merged; publication pending
-1.4.0  focus/interaction/key gestures/hit testing/pointer   approved future release
+1.2.0  panels/layers + z-order composition                  complete/published history
+1.3.0  layout + resize primitives                           complete/published
+1.4.0  interaction routing/focus/gestures/hit testing       stable-source qualification active
 ```
 
-The sequence is cumulative: 1.1 adds meaning to retained content; 1.2 composes overlapping retained surfaces; 1.3 makes geometry manageable; 1.4 routes semantic input to logical regions.
+The sequence is cumulative: 1.1 adds meaning to retained content; 1.2 composes overlapping retained surfaces; 1.3 makes geometry manageable; 1.4 routes semantic input to logical application regions.
 
 ## Ownership boundary
 
 DCurses consumes Terminal's live-session/input/lifecycle/semantic-output contracts rather than terminal-family protocol details and does not install private protocol writers or a second input owner.
 
-The 1.3 layout work preserves the same ownership principle internally: geometry values are immutable, `CursesLayout` is pure/stateless, and applications explicitly recompute/apply layout rather than delegating control to a background layout owner.
+The 1.3 layout work preserved that ownership principle internally: geometry values are immutable, `CursesLayout` is pure/stateless, and applications explicitly recompute/apply layout rather than delegating control to a background layout owner.
 
-## Published 1.2 floor
+The 1.4 interaction work extends the same principle. DCurses classifies and routes already-normalized input, while `Icod.Terminal` remains authoritative for terminal input decoding, rich-input protocol ownership, pointer-shape transport/lifetime, session lifecycle, and output serialization.
 
-```text
-47 exported types
-356 canonical declared contract lines
-sha256 4810ebb088764acedbb94aca84b231677886b9c1a1f920d9a30f960cbe1dfce7
-```
-
-`CursesPanel` and `CursesPanelTransparency` are the two 1.2 exported additions. The published contract includes retained panel content, deterministic z-order, show/hide, movement/ordering, opaque or blank-transparent composition, clipping, incremental recomposition, semantic-metadata/wide-cell coherence, live refresh/lifecycle integration, and deterministic one-way disposal.
-
-Panel dimensions are fixed in the published 1.2 package; resize/layout belongs to 1.3.
-
-## Release 1.3 — layout and resize primitives
-
-Frozen stable-source contract:
+## Published 1.3 floor
 
 ```text
 51 exported types
 406 canonical declared contract lines
 sha256 a655bd85e3c88f5bf38ad0d43a148e3bd06a9e943bbf3e3aa2e21575ffb07424
 ```
 
-Four exported types are added over 1.2:
+Tagged baseline:
 
 ```text
-CursesRectangle
-CursesInsets
-CursesDockEdge
-CursesLayout
+v1.3.0 -> c10ca043a666b85225f2d3b8955a1ac2075b0d31
 ```
 
-Additive members on existing types provide screen/window/panel bounds, atomic rectangle application, and retained panel resizing.
+Current 1.4 interaction fingerprint:
+
+```text
+62 exported types
+491 canonical declared contract lines
+sha256 8afe72deaa5354ee072de8ae17b04d8a1a0a8f730d5e3a737b4a47a539379147
+```
+
+Version 1.3 contributes the reusable `CursesRectangle` coordinate substrate, screen/window/panel bounds, explicit rectangle application, retained panel resizing, and lifecycle-driven application relayout model which 1.4 consumes rather than replaces.
+
+## Release 1.4 — deterministic interaction routing
 
-The accepted 1.3 design provides:
+Version 1.4 turns the existing semantic input and geometry foundations into an application-facing interaction substrate without introducing widgets or a hidden event loop.
 
-- immutable terminal-cell rectangles and insets;
-- deterministic containment/intersection/inset semantics;
-- fixed top/bottom/left/right allocation;
-- proportional row/column allocation;
-- Top/Right/Bottom/Left docking;
-- clipping and explicit empty geometry;
-- `CursesScreen.Bounds`;
-- parent-relative nested `CursesWindow.Bounds` plus atomic `SetBounds`;
-- screen-relative `CursesPanel.Bounds`, retained `Resize`, and atomic `SetBounds`;
-- surviving upper-left content/metadata preservation on panel resize;
-- width-two footprint repair at shrink boundaries;
-- explicit lifecycle-driven recomputation from `session.Screen.Bounds`;
-- a dedicated interactive layout sample;
-- Unicode/metadata/repeated-resize hardening;
-- application/performance/allocation acceptance with no retained layout state;
-- fresh NuGet-only package consumption of the full 1.3 surface.
+The implemented surface provides:
 
-T1310 qualified exact head `c8d6a6313b9f6ca124a255c12b912f8ed89ffda7` in workflow #681 / `34694609178`, all seven jobs green. The API regret audit found no naming, mutability, ambiguity, ownership, or 1.4-reuse correction requiring an API break.
+- bounded screen-bound interaction-region registration;
+- screen-relative and panel-associated hit targets;
+- deterministic overlap resolution using panel z-order plus region precedence;
+- region-local coordinate translation;
+- logical focus independent of terminal/window-manager focus;
+- explicit focus/clear plus forward/backward traversal;
+- deterministic focus repair when regions become ineligible;
+- immutable semantic keyboard gestures over the existing `CursesKey`, modifiers, characters, and event phases;
+- region-local and router-global command bindings;
+- structured routing results rather than callback invocation;
+- pointer-shape preferences and a DCurses-shaped wrapper over Terminal-owned pointer leases;
+- resize/panel visibility/reorder/disposal coherence;
+- an application sample proving keyboard, mouse, panel, pointer, and live-resize composition;
+- allocation/performance/adversarial qualification before stable promotion.
 
-The unchanged implementation/API was promoted to `1.3.0-rc.1`; exact RC head `2ab949a64f63759ad9cf4e93e45a368c50ab6e49` passed workflow #689 / `34694881296` across all seven jobs. The declared dependencies were then advanced to `Icod.Terminal 1.11.1` and `Icod.TermInfo 1.11.0` without changing the frozen public API. Final stable-source head `b90b444556291434bddb9f56d031f09ac1aabfbf` passed workflow #719 / `34708925529` across all seven jobs. PR #27 was merged as `18255d59136922b9e246f4113dc6fdb6a9ea24a3`, and main Release workflow #17 / `34709142076` passed.
+The detailed authorities are:
 
-## Planned 1.4 focus and interaction mechanics
+- `Icod.DCurses-1.4.0-Development-Roadmap.md`
+- `docs/superpowers/specs/2026-09-12-icod-dcurses-1.4-interaction-routing-design.md`
+- `docs/Public-API-Fingerprint-1.4.json`
+- `docs/T1409-Interaction-Acceptance-Sample.md`
+- `docs/T1410-Interaction-Performance-Allocation-and-Adversarial-Hardening.md`
+- `docs/T1411-Public-API-Package-Documentation-and-Regret-Gate.md`
+- `docs/T1412-RC-and-Stable-1.4.0-Closure.md`
 
-Version 1.4 is planned to add focusable regions, focus traversal, keyboard gestures/commands, mouse hit testing, interaction regions, pointer-shape requests, focus repair, resize-aware hit testing, and deterministic overlap precedence. Terminal remains the authoritative input/protocol owner.
+## 1.4 key policy decisions
 
-The key 1.3-to-1.4 bridge is `CursesRectangle`: 1.4 can reuse the same immutable terminal-cell coordinate substrate for focus and hit-test regions without inventing a second geometry model or changing 1.3 layout ownership.
+The approved direction deliberately keeps rendering and interaction separate.
 
-Version 1.4 is not being pulled backward into 1.3. No focus router, gesture registry, hit-test tree, pointer policy, widget framework, raster placement, animation system, or general constraint solver belongs in the 1.3 release.
+Interaction regions are not windows, panels, widgets, event handlers, or callbacks. They identify logical application targets and routing metadata. Ordinary regions are screen-relative. Panel-associated regions derive effective screen position and eligibility from their owning panel while preserving panel z-order as the first overlap discriminator.
+
+Logical focus is application focus and is therefore distinct from `CursesFocusEvent`, which represents actual terminal focus reports. Terminal focus loss does not erase which application region is logically focused.
+
+Mouse routing is hit testing, not automatic application policy. A click may identify a focusable target, but the router does not automatically focus it. Visual panel transparency does not automatically create mouse click-through semantics.
+
+Keyboard command routing is semantic rather than escape-sequence based. Focused-region bindings take precedence over router-global bindings, and duplicate gestures within one binding scope are rejected instead of silently depending on registration order.
+
+Pointer-shape preferences are routing data. Synchronous hit testing never performs asynchronous terminal output. The application/session layer explicitly applies the desired shape through DCurses-owned semantics which delegate transport and lifetime to `Icod.Terminal`.
+
+## 1.4 tranche sequence
+
+```text
+T1401  contract/design/public-surface candidate freeze       complete
+T1402  interaction-region registry                           complete
+T1403  hit testing / clipping / panel precedence             complete
+T1404  logical focus / traversal / repair                    complete
+T1405  keyboard gestures                                     complete
+T1406  command bindings / routing result                     complete
+T1407  pointer shape integration                             complete
+T1408  resize / panel / lifecycle coherence                  complete
+T1409  application acceptance sample                         complete
+T1410  performance / allocation / hardening                  complete
+T1411  API / package / docs / licensing / dependency gate    complete
+T1412  RC / stable-source closure                            active
+```
 
 ## Cross-release rules
 
 Compatible 1.x releases retain additive API by default, exact compiler-derived fingerprints, Terminal/TermInfo ownership boundaries, Unicode/wide-cell/metadata semantics, conservative lifecycle recovery, package-only consumer validation, Windows/Linux/macOS x64/ARM64 validation, and documentation/sample/package audits before stable promotion.
 
 Historical release documents remain historical authorities and are not rewritten simply to reflect newer package/dependency state.
 
+## Deliberate 1.4 exclusions
+
+Version 1.4 does not add a widget/control library, retained widget hierarchy, event capture/bubbling tree, automatic focus-on-click policy, generalized drag/drop framework, flex/grid/constraint layout, automatic layout ownership, accessibility tree, raster scene graph, animation framework, PTY/process hosting, or raw terminal protocol escape hatches.
+
 ## Immediate next step
 
-Repository-side 1.3 development is complete. Public `v1.3.0` tagging/GitHub Release/NuGet publication remain explicit release actions. The next approved development track is 1.4.0.
+T1412 is the active release gate. The final `1.4.0-rc.1` head has passed the full seven-job package/runtime matrix and the unchanged accepted implementation/API has been promoted to stable-source `1.4.0`. Qualify the stable-source exact head through the same matrix, then present PR #29 for explicit merge approval. After merge, qualify the resulting `main` Release workflow before tagging, GitHub Release creation, or NuGet publication.