@termwright/probe-tview 0.2.0 → 0.3.0

package/README.md

@@ -1,116 +1,126 @@
 # @termwright/probe-tview
 
-Semantics from a [tview](https://github.com/rivo/tview) application that
-**imports nothing of ours**.
+Capability-driven semantic probing for
+[tview](https://github.com/rivo/tview), without editing or copying upstream
+source files.
 
-The application is built through an ephemeral Go workspace that redirects
-`github.com/rivo/tview` to an instrumented copy. Nothing is written into the
-project: its `go.mod`, its `go.sum` and any `go.work` of its own come out of the
-build byte-identical.
+Termwright controls the Go build and uses the official `-toolexec` hook to add
+owned compilation units to the tview package and, on Windows, tcell. The
+compiler checks every private-field assumption. A new upstream version is
+accepted by compilation plus behavioral conformance, not by matching a source
+digest.
 
-## Install
+## Install and use
 
 ```sh
 npm install --save-dev @termwright/probe-tview
 ```
 
-Requires the Go toolchain and `git` (which the toolchain needs anyway). Node >= 22.
+The application opts in with one line immediately before `Run`:
 
-## Usage
-
-One call prepares the build; the launcher owns everything else.
-
-```ts
-import {prepareInstrumentedBuild} from '@termwright/probe-tview';
-
-const build = await prepareInstrumentedBuild({moduleDir: 'path/to/app'});
-
-// build.env carries GOWORK; the project's own files are untouched.
-await execFile('go', ['build', '-o', 'app-binary', '.'], {cwd: 'path/to/app', env: build.env});
+```go
+import "github.com/gorce-ai/termwright/clients/go/tviewprobe"
 
-await launchTerminal({command: ['./app-binary']});
+app.SetRoot(root, true)
+defer tviewprobe.Attach(app, root)()
+if err := app.Run(); err != nil {
+	panic(err)
+}
 ```
 
-The framework version is read from the module, the instrumented copy is cached,
-and a second call with the same inputs reuses it.
-
-## What it gives you
-
-Being inside the package is the point. A `tview.Grid` exposes no accessor for
-its children at all, so an out-of-package adapter has to be handed a callback;
-here it is a field read that also carries whether the item was drawn. A widget
-on a `Pages` page that is not shown reports as **hidden** rather than going
-missing, so a test can tell "not on screen" from "not there".
+Prepare the controlled build and pass the returned Go arguments to the build
+or test command:
 
-Identity is the primitive's pointer: tview retains its widget tree, so the same
-`*Button` is the same button across frames. The handshake therefore reports
-`identityKind: 'stable'` and only the probe capabilities it earns:
-`stable-identity` and `annotations`. Its `frameworkVersion` is the exact
-version selected by the verified patch set, not the Go runtime version.
-
-## Describing what the probe cannot see
+```ts
+import { execFile } from 'node:child_process';
+import { prepareInstrumentedBuild } from '@termwright/probe-tview';
+
+const build = await prepareInstrumentedBuild({ moduleDir: 'path/to/app' });
+await execFile('go', ['build', ...build.goArgs, '-o', 'app-binary', '.'], {
+  cwd: build.moduleDir,
+  env: build.env,
+});
+```
 
-Zero-config means the probe reads facts. It cannot read intent — which button
-is the destructive one, which list is the inbox, what "overdue" means here. For
-that, and only for that, an application may import
-`github.com/gorce-ai/termwright/clients/go/annotate`:
+The mechanism works with ordinary module-cache dependencies, local
+replacements, workspaces and vendored applications. It does not modify the
+application's `go.mod`, `go.sum`, `go.work`, vendor tree, or upstream module
+bytes.
+
+## Intervention tiers
+
+- T0 public tview/tcell APIs provide most widget hierarchy, state, geometry
+  and the `Screen.Show` output boundary.
+- A T1 add-only tview unit exposes sealed root, Grid, Modal, DropDown and other
+  rendered state. Private-field drift is a compile error.
+- On Windows a second T1 tcell unit writes the authenticated frame marker
+  through the console handle used by `Show`. Unix uses the public `Tty()`
+  writer.
+
+The application screen is decorated before `Run`, and its existing public
+before/after-draw hooks are chained. Those hooks arm exactly tview's final
+`Show`; intermediate `Show` calls made by custom primitives or application
+hooks still flush normally but cannot publish a partial semantic frame. After
+the armed underlying `Show` completes, the probe reads the current
+`Application.root`, admits one complete snapshot to the bounded publication
+queue and writes its marker through the same screen sink. This also covers
+tview's before-draw short-circuit and roots changed through `SetRoot`. It never
+calls `Show` itself, never holds a process-global render mutex and never
+performs socket I/O on the render goroutine. Runtime displacement of either
+composed hook fails semantics closed.
+
+A queue refusal, re-entrant `Show`, missing writer, partial marker, worker
+failure or missing injected unit closes semantic publication with a typed
+diagnostic. It is never hidden by a timeout increase, retry, quiet window or
+stale-tree fallback.
+
+## Optional semantics
+
+The automatic tree does not require wrappers or per-widget annotations. An
+application may add intent with the framework-neutral Go SDK:
 
 ```go
-import (
-	"github.com/gorce-ai/termwright/clients/go/annotate"
-	"github.com/gorce-ai/termwright/clients/go/protocol"
-)
-
-annotate.Tag(label, annotate.Semantics{Key: "unread-label"})
 annotate.Tag(unreadBadge, annotate.Semantics{
-	Role: "status", Name: "Unread messages", TestID: "unread-badge",
-	Actions: []protocol.Action{protocol.ActionFocus, protocol.ActionActivate},
-	LabelledBy: []annotate.SemanticKey{"unread-label"},
+	Key:     "unread-badge",
+	Role:    "status",
+	Name:    "Unread messages",
+	TestID:  "unread-badge",
+	Actions: []protocol.Action{protocol.ActionFocus},
 })
 ```
 
-The probe merges this with what it observed: the wording is the author's, the
-bounds and the focus stay the probe's. `Semantics` has no field for bounds,
-focus, visibility, value, rendered text or framework state — not by convention
-but structurally, so an annotation cannot go stale against the screen. Actions
-come from the protocol's closed descriptive set and never install callbacks.
-Tagging retains nothing; the entry is released with the widget.
-
-`LabelledBy` and `DescribedBy` use framework-neutral `SemanticKey` strings, so
-one annotation does not retain its targets. The probe resolves them after the
-whole tree has been walked. Missing or duplicate keys are omitted instead of
-becoming dangling or arbitrary node references. Pointer identity remains the
-stable node id; a key is only the relation target for tview. Primary framework
-provenance is reported in `p`, with recognizer and annotation exceptions in
-`px`.
-
-This is the one import that makes an application no longer zero-config, which
-is why it is optional and why the two example fixtures in this package are kept
-apart.
-
-## Dormant without instrumentation
-
-Without `TERMWRIGHT_ENDPOINT` and `TERMWRIGHT_TOKEN` the instrumented copy opens
-no socket, writes no marker and renders exactly what upstream renders. That is
-measured, not asserted: the test suite builds the same application twice, once
-against untouched tview and once against the copy, and requires the two screens
-to be byte-identical.
-
-## When it refuses
-
-- `-mod=vendor` in `GOFLAGS` is reported by name rather than overridden;
-  workspace mode is incompatible with it, and overriding would change what
-  compiles.
-- A framework version with no patch set is named as such — "this is not
-  tview v0.42.0" — instead of failing somewhere inside a diff.
+Annotations can describe roles, names, ids, relationships and closed actions.
+They cannot override geometry, focus, visibility, value, rendered text or
+framework state. They are held in a side table and do not require replacing
+tview constructors or fluent widget types.
+
+## Dormant and unsupported modes
+
+Without both `TERMWRIGHT_ENDPOINT` and `TERMWRIGHT_TOKEN`, `Attach` returns
+before creating a client, channel, goroutine, socket or framework hook. The
+instrumented and ordinary builds are required to render byte-identical output
+in this mode.
+
+A prebuilt binary cannot receive T1 units and therefore runs as explicitly
+reported raw PTY. A controlled build whose capability unit fails to compile is
+rejected loudly; Termwright does not create an exact-version patch profile or
+silently downgrade its semantic tree.
+
+Known declared limitations are clipped geometry for some tview containers and
+enumeration of application-defined custom container children. Such nodes stay
+visible as generic/opaque nodes and the reduced capability is present in run
+metadata.
 
 ## Development
 
 ```sh
-pnpm build && pnpm typecheck && pnpm test
+pnpm build
+pnpm typecheck
+pnpm test
+cd ../../clients/go && go test -race -count=1 ./...
 ```
 
-The suites that need Go or a pseudo-terminal skip themselves where either is
-missing, and say so in a test named for it. `TERMWRIGHT_SKIP_GO=1` and
-`TERMWRIGHT_SKIP_PTY=1` force it. Implementation notes, including the traps
-that cost time, are in [`NOTES.md`](NOTES.md).
+The native Linux and Windows certification rows require the relevant
+toolchain and real PTY/ConPTY rather than treating their absence as a green
+adapter result. Implementation invariants are recorded in
+[`NOTES.md`](NOTES.md).

package/assets/tcell_marker_windows.go.txt

@@ -0,0 +1,80 @@
+//go:build windows
+
+package tcell
+
+// This add-only companion joins the tcell package only for a Windows-targeted
+// Termwright build. Windows' cScreen has no Tty(), but it owns the console
+// handle that Show uses synchronously. Exposing one narrow marker operation
+// preserves the same-handle commit boundary without modifying tcell's renderer.
+
+import (
+	"errors"
+	"io"
+	"syscall"
+	"unicode/utf16"
+	"unsafe"
+)
+
+var (
+	termwrightKernel32       = syscall.NewLazyDLL("kernel32.dll")
+	termwrightGetConsoleMode = termwrightKernel32.NewProc("GetConsoleMode")
+	termwrightSetConsoleMode = termwrightKernel32.NewProc("SetConsoleMode")
+)
+
+const termwrightMarkerOutputMode = uint32(0x0001 | 0x0004) // processed output + VT processing
+
+// TermwrightWriteMarker is defined on baseScreen because NewConsoleScreen
+// returns *baseScreen, whose embedded screenImpl interface otherwise hides
+// methods implemented only by the concrete *cScreen.
+func (b *baseScreen) TermwrightWriteMarker(marker string) (resultErr error) {
+	s, ok := b.screenImpl.(*cScreen)
+	if !ok {
+		return errors.New("tcell: screen is not the Windows console implementation")
+	}
+	s.Lock()
+	defer s.Unlock()
+	if s.fini {
+		return errors.New("tcell: screen is finalized")
+	}
+	encoded := utf16.Encode([]rune(marker))
+	if len(encoded) == 0 {
+		return nil
+	}
+	var originalMode uint32
+	if ok, _, err := termwrightGetConsoleMode.Call(uintptr(s.out), uintptr(unsafe.Pointer(&originalMode))); ok == 0 {
+		return err
+	}
+	// Inspect the real writer capability instead of tcell's historical `vten`
+	// implementation field. tcell <= 2.11 used that field to select a legacy
+	// renderer, while >= 2.12 requires VT during screen initialization and no
+	// longer declares it. Vendored ordered-passthrough ConPTY serializes both
+	// legacy Console API output and VT on this handle, so a legacy frame can be
+	// followed by a temporarily VT-enabled marker without weakening ordering.
+	if originalMode&termwrightMarkerOutputMode != termwrightMarkerOutputMode {
+		if ok, _, err := termwrightSetConsoleMode.Call(uintptr(s.out), uintptr(originalMode|termwrightMarkerOutputMode)); ok == 0 {
+			return err
+		}
+		defer func() {
+			restored, _, restoreErr := termwrightSetConsoleMode.Call(uintptr(s.out), uintptr(originalMode))
+			if restored == 0 && resultErr == nil {
+				resultErr = restoreErr
+			}
+		}()
+		var activeMode uint32
+		if ok, _, err := termwrightGetConsoleMode.Call(uintptr(s.out), uintptr(unsafe.Pointer(&activeMode))); ok == 0 {
+			return err
+		}
+		if activeMode&termwrightMarkerOutputMode != termwrightMarkerOutputMode {
+			return errors.New("tcell: active Windows console output could not enable VT processing")
+		}
+	}
+	var written uint32
+	writeErr := syscall.WriteConsole(s.out, &encoded[0], uint32(len(encoded)), &written, nil)
+	if writeErr != nil {
+		return writeErr
+	}
+	if written != uint32(len(encoded)) {
+		return io.ErrShortWrite
+	}
+	return nil
+}