@volter/supercode-terminal 0.2.30

package/CAPABILITIES.md

@@ -0,0 +1,57 @@
+# Terminal capability contract
+
+This package aims for the terminal-client workflows people rely on in iTerm2, not a claim that a
+browser frame is macOS iTerm2. Every row is assigned to one of four owners so browser products can
+compose the package without duplicating or pretending to own behavior.
+
+- **UI** — reusable behavior supplied here.
+- **tmux** — durable terminal behavior supplied by this package's shared substrate and tmux.
+- **host** — browser/extension policy that must be supplied by the embedding product.
+- **excluded** — platform-specific iTerm2 functionality that does not belong in a Volter Harness glue UI.
+
+`verified` means the behavior executes today. `partial` names the remaining residue. `missing`
+means it must not be presented as supported.
+
+| Capability family | Owner | State | Contract / residue |
+| --- | --- | --- | --- |
+| Native Claude `/clear` identity rollover | host substrate | verified | Bounded transcript-edge evidence shared across iTerm and Terminal; ambiguous/claimed successors refused, chain history retained, stale mappings revoked. Controlled native-command tests; arbitrary interior transcript rewrites are not guaranteed. |
+| VT screen, alternate screen, color, mouse reporting, IME | UI/xterm | verified | xterm.js is the emulator; the package does not reinterpret terminal bytes. |
+| Unicode, emoji, CJK and IME input | UI/xterm | verified | Supplied by stable xterm.js behavior. Experimental grapheme clustering is not enabled by default. |
+| Tabs and instant switching | UI | verified | Open viewers stay mounted; switching does not reconnect or replay output. |
+| New, attach, detach, stop, open in local terminal | UI/tmux | verified | Detach never stops tmux. Stop remains explicit and ownership-gated. |
+| Browser-safe shortcuts and discovery | UI | verified | Option/Alt+Shift namespace only; browser Command/Ctrl bindings are never claimed. |
+| Scrollback, selection and copy | UI/xterm | verified | Bounded scrollback and native xterm selection. |
+| Find in one terminal, next/previous match | UI | verified | Search covers the active xterm buffer. Cross-tab search is missing. |
+| URL detection | UI | partial | The stable xterm web-link provider is active; host policy and end-to-end link opening still need a dedicated proof. |
+| Paste and bracketed paste | UI | verified | Multiline or large pastes require confirmation; history is memory-only. Advanced transforms and slow paste are missing. |
+| Save terminal contents | UI | partial | The normal buffer is projected to a bounded plain-text download; the browser download boundary and continuous logging still need dedicated proof. |
+| Bell and background activity | UI | verified | A controlled tmux shell proved active visual bell plus inactive activity/bell tab state. System notifications are host policy. |
+| Dynamic terminal title | UI/tmux | partial | Direct xterm title events are wired, but OSC titles do not currently survive the tmux attachment path. |
+| Durable process survival and reconnect | tmux | verified | The tmux session outlives the viewer; a disconnected viewer can request a fresh grant. |
+| New-session conversation recovery | host/tmux | verified | A bounded ten-minute ledger binds only one unambiguous new native descriptor by harness, workspace, first user prompt, and pre-launch catalog baseline. |
+| Read-only mirroring without terminal reflow | tmux | verified | Observers inherit the pane's live dimensions and cannot send input. |
+| Live PTY resize | UI/tmux | verified | Control attachments refit and send bounded resize frames; an isolated real tmux proof resized the PTY to 113×37. Observers never resize. |
+| Split panes and draggable layout | UI/tmux | missing | tmux may contain panes, but this UI cannot create, address, or arrange them yet. |
+| Window/pane dashboard and rename/reorder | UI/tmux | partial | Sessions are listed and tabs can be selected; windows, panes, rename, and drag reorder are missing. |
+| Workspace/layout restoration | UI/host | missing | tmux preserves jobs, but open tabs, active tab, layout, and scrollback are not restored after the UI is destroyed. |
+| Profiles, themes, fonts, cursor, scrollback settings | UI/host | missing | The default is tokenized, but there is no user profile model or settings surface yet. |
+| Transparent embeddable surface | UI/host | verified | Shell and xterm layers preserve alpha; one tokenized backing layer prevents nested opacity from compounding. |
+| Fit versus simulated viewport | UI/host | partial | The workspace exposes an explicit scale/fit policy and control attachments reflow in fit mode. Embedding hosts must supply the two presentation geometries and prove their boundary. |
+| Font zoom, fullscreen and popout | host | missing | These alter host geometry or profile settings and require explicit embedding-host commands. |
+| Search across tabs / terminal Exposé | UI | missing | Per-terminal search exists; no workspace-wide result navigator exists. |
+| Command history, recent directories, prompt navigation | host/shell integration | missing | Requires a shell-integration event model rather than scraping rendered text. |
+| Smart file/path selection and semantic history | UI/host | missing | URLs work. Files, line numbers, command URLs, and host open policy are not modeled. |
+| Notifications for bell, activity, idle, exit, job completion | host | partial | UI events exist; browser notification permission and agent-status policy belong to the host. |
+| Broadcast input | UI/tmux | missing | Must include an unmistakable armed state and explicit target scope before shipping. |
+| Triggers, captured output, annotations, badges | host | missing | Requires a declarative event/action layer; never infer these from fragile DOM text. |
+| Inline images / sixel / iTerm image protocol | UI/xterm | missing | xterm has an image addon, but it is not loaded or validated here. |
+| Paste history persistence, password manager, secure keyboard entry | host/platform | partial | Paste history is deliberately memory-only. Secrets and secure input require native host policy. |
+| Save/restore arrangements, undo close, instant replay | UI/host | missing | No layout journal or serialized screen timeline exists yet. |
+| Dynamic profiles, Python/AppleScript API, coprocesses | excluded | excluded | These are iTerm2 automation/platform features, not Volter Harness's cross-harness glue role. |
+| Touch Bar, native menu bar, macOS window transparency | excluded | excluded | A browser overlay uses browser/Widget Shell equivalents. |
+| iTerm web browser and AI Chat | excluded | excluded | Vibewaiting already supplies browser context and semantic agent chat; duplicating them in the terminal package is out of scope. |
+
+The next parity gates are ordered by user impact: live resize and pane addressing; restorable
+workspace state; profiles/settings and explicit zoom/popout; cross-tab search and semantic shell
+events; logging/replay and guarded broadcast input. A feature remains `missing` until its real
+boundary is exercised—dependency presence or registry wiring is not proof.

package/LICENSE-SUBSTRATE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 termfleet contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE-SUBSTRATE

@@ -0,0 +1,14 @@
+The terminal substrate in src/substrate/ and its compiled substrate/ outputs
+was originally moved without runtime changes from @termfleet/terminal, authored
+by Volter AI, and is now maintained in this package.
+Original source: https://github.com/volter-ai/termfleet
+Source revision: d6b28d9866a5efee5a8ba698fb47ccf8232b299d
+
+These files remain licensed under Apache License 2.0; see LICENSE-SUBSTRATE.
+The session-roll implementation and its reference invariants were adapted from
+Termfleet core agent-session-roll at 089d58c48e34c609a31dfa8ce8f7111b6dff90c0,
+also authored by Volter AI; subsequent native integration is owned here.
+The containing package's alternative MIT license does not relicense this code.
+
+Existing .termfleet paths, environment variables, tmux ownership markers, and
+public wire names are compatibility contracts and are intentionally retained.

package/README.md

@@ -0,0 +1,190 @@
+# `@volter/supercode-terminal`
+
+## Native Claude rollover evidence
+
+`NativeTerminalSessionHost` (also used by `SupercodeTerminalController`) follows
+Claude `/clear` transcript successors while the process keeps its original argv
+session ID. iTerm and Terminal observations share one ownership batch. Ambiguous
+co-located predecessors and successors claimed by another pane are not adopted;
+later predecessor activity or a missing successor revokes the mapping.
+
+The rollover store defaults to `CLAUDE_CONFIG_DIR`, then `~/.claude`. An explicit
+`nativeHost.home` isolates discovery to that home's `.claude`; an explicit
+`nativeHost.claudeConfigDir` takes precedence. Both rollover evidence and the
+existing PID-only Claude fallback use this same native store.
+
+Embedders can gather the same evidence with `createSessionRollTracker` from the
+existing `./substrate/session-lifecycle.js` export and supply its map as
+`ObserveIo.sessionRolls` (or pass the tracker to `gatherLifecycleObservation`).
+
+Evidence is asynchronous: 16 KiB transcript head/tail reads, a 50-entry head
+inspection bound, 500-entry edge caches, and a 15-second successor-scan cadence.
+Directory enumeration still scales with the native project inventory. No new
+watcher, timer, subprocess, transcript copy, or persistent state is introduced.
+Closed-pane chains are pruned; over-capacity evidence fails closed. These are
+conservative append-oriented observations, not proof of arbitrary interior
+transcript rewrites. Native routing tests use isolated command fixtures, not
+live user terminals.
+
+## Overview
+
+Optional terminal/tmux hosting for Volter Harness frontends. It complements
+Volter Harness's semantic transcript and runtime APIs with the familiar live terminal
+screen; it does not turn terminal bytes into canonical conversation history.
+
+This package owns the shared terminal substrate. `src/substrate/` is its source;
+`substrate/` contains the compiled runtime and declarations. The existing host,
+controller, and browser client consume these modules directly, without a
+the fleet tool package dependency. Advanced hosts and legacy adapters may import
+`/substrate/attach.js`, `/substrate/client.js`, `/substrate/local-terminal.js`,
+`/substrate/native-host.js`, `/substrate/session-lifecycle.js`,
+`/substrate/tmux-stream.js`, and `/substrate/tmux.js`; the two internal helper
+subpaths are exported only for compatibility. Prefer the controller/client APIs
+above this layer for new applications.
+
+The substrate was moved from a retired package without behavioral changes.
+Its existing home paths, environment variables, and tmux ownership markers stay
+compatible. Those files retain Apache-2.0 licensing; see `NOTICE-SUBSTRATE` and
+`LICENSE-SUBSTRATE`.
+
+The server-side `TmuxTerminalHost` can discover existing tmux sessions, create a
+session from a structured command, capture its display, submit input to a
+session it owns, prepare a local `tmux
+attach-session` launch, open that launch through the trusted local-terminal
+adapter, and issue a one-use embedded attachment grant. Existing
+sessions are read-only by default. Control and close are allowed only for
+sessions bearing this host's ownership mark unless the embedding host explicitly
+opts into unowned control.
+
+Most Volter Harness frontends should use `SupercodeTerminalController`, which composes that low-level
+host with the loopback bridge, persistent context recovery, native Claude Code/Codex handoff, and
+harness-aware initial-input delivery. The embedding product supplies allowed browser origins and
+optional display-path formatting; it should not create a second terminal registry or scrape agent
+prompts itself. `TmuxTerminalHost` remains public for applications that deliberately need only the
+lower-level primitive.
+
+An embedding host may pass an opaque `contextKey` when it creates a session.
+The host stores that association in a namespaced tmux user option and returns it
+with future catalog reads, so a semantic conversation can recover its terminal
+after the browser or native bridge restarts. The value is application-defined;
+native harness session ids, tmux targets, sockets, and process handles should
+never be used as context keys.
+
+For a brand-new interactive launch, the native session does not exist when tmux is created.
+`conversationDiscovery` records the pre-launch opaque catalog keys and first user prompt;
+`reconcileConversationBindings` later binds the terminal only when exactly one new descriptor has
+the same harness, workspace, and user prompt. Ambiguous matches remain unbound. This recovery
+state is bounded, expires after ten minutes, and never exposes a tmux target to the product.
+
+Browser and extension hosts can pair it with `TerminalWebSocketBridge`, which binds an ephemeral
+loopback port, requires an exact configured origin on every WebSocket upgrade, and accepts only
+one-use attachment grants. The embedding product supplies its allowed origin and never handles a
+tmux socket or target. `normalizeTerminalUiState` performs the matching untrusted-wire projection
+before state reaches the reusable terminal components.
+
+Browser code imports `@volter/supercode-terminal/client`. It contains only
+the terminal WebSocket client and protocol types; it never imports tmux,
+`node-pty`, filesystem, or process APIs.
+
+Frontends that want the default terminal experience can import the optional
+Preact components from `@volter/supercode-terminal/ui` and its tokenized
+stylesheet from `@volter/supercode-terminal/ui/styles.css`. `TerminalWorkspace`
+is the terminal-app surface: retained live tabs, one-click session attachment,
+keyboard tab switching, direct terminal focus, connection state, and separate detach/open/stop
+actions. `TerminalPanel`, `TerminalViewer`, and `TerminalPath` remain independently reusable for
+constrained hosts. The surfaces take
+callbacks rather than a transport implementation, so a host can map its own
+validated intents without exposing native handles. The heavy xterm runtime is a
+dynamic import and is loaded only when a viewer is actually opened.
+
+The workspace deliberately leaves browser-owned Command/Ctrl shortcuts alone. While it has focus,
+its default namespace is Option/Alt+Shift: `T` opens the session menu, `D` detaches the active tab,
+digits 1–9 select tabs, and brackets rotate between tabs.
+
+Hosts with both a fixed simulated viewport and a responsive viewport can pass `viewportMode` and
+`onViewportModeChange`. The workspace then exposes one compact scale/fit control for writable
+attachments; read-only mirrors never offer a control that could reflow the source pane. The full,
+evidence-scoped parity boundary is recorded in [CAPABILITIES.md](CAPABILITIES.md).
+
+The terminal canvas and internal layout layers are transparent over one
+`--sctui-terminal-background` backing layer (the Volter brand's `surface.media` by default). Embedders
+can set that token to any valid transparent or opaque CSS color without forking the component; the
+color is intentionally applied once so nested alpha does not compound back into an opaque card.
+
+Colours and fonts default to the [Volter brand's roles](https://brand.volter.ai/tokens), read as
+`var(--volter-<role>, <brand value>)`: a host that sets `--volter-*` (the brand's `tokens.css`)
+governs them, and `--sctui-*` or `--scui-*` overrides the one it sets. The terminal is a dark media
+surface in either page scheme, so its inks (the ANSI palette, foreground, cursor and the viewer's
+own controls) use the brand's dark values. `styles.css` is generated from `src/styles.css`, which
+names each role as `brand(<role>)`; `npm run build` resolves them.
+
+Safety properties:
+
+- browser actions use opaque catalog ids rather than tmux targets;
+- embedded attachment grants are random, short-lived, and consumed once;
+- the tmux socket and session target never appear in an embedded grant;
+- detaching disposes the ephemeral PTY/WebSocket resources but cannot stop the
+  durable tmux session;
+- closing is a separate explicit operation and checks the ownership mark;
+- structured commands and argument arrays are passed without shell-string
+  construction.
+
+## Use the xterm UI with a browser runtime
+
+The optional `/stream` and `/react/stream` entries export `TerminalStreamViewer`.
+They use the same search, links, paste controls, download, status, and keyboard
+behavior as `TerminalViewer`, with a caller-supplied connector instead of a
+WebSocket. Import `/ui/styles.css` and `@xterm/xterm/css/xterm.css`; install the
+xterm, fit, search, and web-links peer packages for this surface.
+
+```jsx
+<TerminalStreamViewer
+  attachment={{ id: 'workspace-shell', sessionId: 'workspace', baseUrl: '', mode: 'control' }}
+  connect={(attachment, events, { cols, rows }) => {
+    // Subscribe to process output, report readiness with events.onOpen(),
+    // forward output through events.onOutput(data), and report exit/close.
+    return { write, resize, close: unsubscribe };
+  }}
+  convertEol={true}
+  onReady={({ focus }) => { /* retain focus for the host's terminal tab */ }}
+/>
+```
+
+`connect` returns synchronously and must keep its function identity stable for
+one attachment. Unmount closes the attachment; the host retains ownership of
+process termination. Use `convertEol` for streams without PTY newline processing;
+the default preserves terminal bytes. Theme foreground and cursor through
+`--sctui-terminal-foreground` and `--sctui-terminal-cursor`, and the ANSI palette through
+`--sctui-terminal-black`, `-red`, `-green`, `-yellow`, `-blue`, `-magenta`, `-cyan`, `-white` and
+their `-bright-*` forms (defaults: the brand's `terminal.*` roles). xterm reads the resolved colours
+when the viewer mounts. `/stream` does not
+load the tmux or WebSocket implementation. Existing `TerminalViewer` consumers
+keep the default WebSocket connector, also exported as `/client`'s
+`connectTerminal`.
+
+## Shells over a Docker exec wire
+
+`/docker-exec` exports `dockerExecTerminal`, a controller for an environment that
+offers Docker's Engine API and no session service: a container, a Conduit
+`docker/engine-api` binding, or a browser tab's container. Each New terminal is
+an exec of `sh` with a TTY. The controller holds the exec's stream and a bounded
+buffer of its output, so a view that detaches leaves its shell running and one
+that attaches replays the newest output. `stop` ends a shell or dismisses one
+that exited. Nothing outlives the page: Docker offers no way back into an exec's
+stream once its socket closes, so say so where the shells are listed.
+
+```js
+import { dockerExecTerminal } from '@volter/supercode-terminal/docker-exec';
+
+const shells = dockerExecTerminal({
+  base: 'https://agent.example/v1.51', containerId,
+  headers: { authorization: `Bearer ${token}` },
+  // in a tab, the page's own socket onto the exec's stream
+  socket: (url) => daemon.socket(url),
+});
+// shells.getState() and shells.subscribe() feed TerminalWorkspace;
+// shells.connector is the viewer's `connect`.
+const id = await shells.create();
+```
+
+It loads neither xterm nor a UI framework.

package/client.d.ts

@@ -0,0 +1,17 @@
+export {
+  directTerminalUrlResolver,
+  TerminalClient,
+  webSocketBaseUrl,
+} from './substrate/client.js';
+export type {
+  TerminalClientOptions,
+  TerminalErrorMessage,
+  TerminalExitMessage,
+  TerminalHelloMessage,
+  TerminalInputRejectedMessage,
+  TerminalMessage,
+  TerminalOutputMessage,
+  TerminalUrlResolver,
+} from './substrate/client.js';
+
+export const connectTerminal: import('./ui.js').TerminalConnector;

package/client.mjs

@@ -0,0 +1,32 @@
+export {
+  directTerminalUrlResolver,
+  TerminalClient,
+  webSocketBaseUrl,
+} from './substrate/client.js';
+
+
+import { TerminalClient } from './substrate/client.js';
+
+/** The default connector; local runtimes may supply the same callback contract. */
+export function connectTerminal(attachment, handlers, size) {
+  const client = new TerminalClient({ baseUrl: attachment.baseUrl, terminalId: attachment.id,
+    ...(attachment.mode === 'control' ? size : {}) });
+  const socket = client.connect();
+  socket.onopen = () => handlers.onOpen();
+  socket.onmessage = (event) => {
+    try {
+      const message = client.parse(String(event.data));
+      if (message.type === 'output') handlers.onOutput(message.data);
+      else if (message.type === 'hello') handlers.onResize(message.cols, message.rows);
+      else if (message.type === 'error' || message.type === 'input-rejected') handlers.onError(message.message);
+      else if (message.type === 'exit') handlers.onExit();
+    } catch (error) { handlers.onError(error instanceof Error ? error.message : 'Terminal stream failed'); }
+  };
+  socket.onerror = () => handlers.onError('Terminal connection failed');
+  socket.onclose = () => handlers.onClose();
+  return {
+    write: (data) => client.write(data),
+    resize: (cols, rows) => client.resize(cols, rows),
+    close() { socket.onopen = socket.onmessage = socket.onerror = socket.onclose = null; client.close(); },
+  };
+}