@cplieger/web-terminal-ui 7.2.2 → 7.3.1

package/src/kernel/style-contract.ts

@@ -1,36 +1,38 @@
-// The names that cross this package's boundary as STRINGS, published as data.
-//
-// Two surfaces of this library are addressed by name rather than by type, so no
-// compiler on either side of the boundary checks them:
-//
-//   - `theme` is `Readonly<Record<string, string>>`. The kernel copies every key
-//     onto the terminal root verbatim, so a consumer that names a token this
-//     library renamed or retired gets a live declaration nothing reads: no
-//     error, no warning, just the library's own defaults where the consumer's
-//     brand was meant to be.
-//   - The loading overlay is the CONSUMER's element (it must paint before this
-//     module loads), styled by `css/page.css` purely because the markup opts in
-//     by class. Those classes are usually hardcoded in a static HTML file no
-//     compiler reads at all.
-//
-// Both were previously prose — a doc comment on the option, a sentence in the
-// README — which a consumer could only agree with by remembering. Published as
-// data they can be ASSERTED against instead: web-terminal-kiro's app.test.ts
-// checks its theme keys and its overlay markup against these exports the same
-// way it already checks its bootstrap watchdog's wording against
-// STARTUP_FAILURE_COPY. Same reason, same shape: this file imports nothing and
-// touches no DOM, so a test or a Node build script can read it without loading
-// the kernel.
-//
-// These lists are HAND-WRITTEN on purpose. They are the public contract — a
-// decision about what this library promises to support — not a fact derived
-// from the stylesheets. What IS derived from the stylesheets is the
-// verification that the promise holds: `src/css-contract.node.test.ts` generates the
-// declared/referenced token inventory from the CSS itself and fails if any
-// token named here is not both DECLARED and READ by a rule. A token that is
-// declared but never read is the silent-no-op case above, reached from the
-// library's side instead of the consumer's, and no hand-maintained list can
-// catch it.
+/**
+ * The names that cross this package's boundary as STRINGS, published as data.
+ *
+ * Two surfaces of this library are addressed by name rather than by type, so no
+ * compiler on either side of the boundary checks them:
+ *
+ *   - `theme` is `Readonly<Record<string, string>>`. The kernel copies every key
+ *     onto the terminal root verbatim, so a consumer that names a token this
+ *     library renamed or retired gets a live declaration nothing reads: no
+ *     error, no warning, just the library's own defaults where the consumer's
+ *     brand was meant to be.
+ *   - The loading overlay is the CONSUMER's element (it must paint before this
+ *     module loads), styled by `css/page.css` purely because the markup opts in
+ *     by class. Those classes are usually hardcoded in a static HTML file no
+ *     compiler reads at all.
+ *
+ * Both are published as data, so they can be ASSERTED against: a consumer can
+ * check its own theme keys and its own overlay markup against these exports in
+ * its own test, the same way it can check its bootstrap watchdog's wording
+ * against `STARTUP_FAILURE_COPY` on the `./startup-copy` entrypoint. This file
+ * imports nothing and touches no DOM, so a test or a Node build script can read
+ * it without loading the kernel.
+ *
+ * These lists are HAND-WRITTEN on purpose. They are the public contract — a
+ * decision about what this library promises to support — not a fact derived
+ * from the stylesheets. What IS derived from the stylesheets is the
+ * verification that the promise holds: an internal test generates the
+ * declared/referenced token inventory from the CSS itself and fails if any
+ * token named here is not both DECLARED and READ by a rule. A token that is
+ * declared but never read is the silent-no-op case above, reached from the
+ * library's side instead of the consumer's, and no hand-maintained list can
+ * catch it.
+ *
+ * @module
+ */
 
 /** CSS custom properties a consumer may set through `CreateTerminalOptions.theme`.
  *

package/src/presets/agent-tabbed.ts

@@ -1,20 +1,23 @@
-// presetAgentTabbed: the tabbed composition tuned for an agent shell.
+/**
+ * presetAgentTabbed: the tabbed composition tuned for an agent shell.
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 import { type TabbedPresetOptions, buildTabbed } from "./tabbed.js";
 
-/** Tabbed UI for an agent shell (web-terminal-kiro). Same features as
- *  presetTabbed, tuned for sessions that ARE agents:
+/** Tabbed UI for an agent shell. Same features as presetTabbed, tuned for
+ *  sessions that ARE agents:
  *  - `presumeReports`: every session's program is an agent that WILL report
  *    OSC 9;4 progress, so the idle activity dot shows from tab creation
  *    instead of popping in seconds later when the agent has booted far enough
  *    to first report; the server's sticky reportsActivity flag then merely
  *    confirms. (presetTabbed keeps the evidence-driven reveal instead: a
  *    plain shell never grows a meaningless dot.)
- *  Two agent-vs-generic distinctions live SERVER-side rather than here: the
- *  status classifier that maps OSC 9 notifications to done/needs-input, and the
- *  input-derived session name (terminal.WithInputTitle), which the agent host
- *  enables because its program's own window title is not worth showing. */
+ *  One agent-vs-generic distinction lives SERVER-side rather than here: the
+ *  status classifier that maps OSC 9 notifications to done/needs-input. Tab
+ *  names are server-side too but are not agent-specific — see buildTabbed. */
 export function presetAgentTabbed(opts: TabbedPresetOptions = {}): TerminalFeature<unknown>[] {
   return buildTabbed(true, opts);
 }

package/src/presets/single.ts

@@ -1,8 +1,12 @@
-// presetSingle: the single-pane desktop composition. Its own entry module so a
-// consumer importing "@cplieger/web-terminal-ui/presets/single" pulls in ONLY
-// this feature graph — none of the toolbar/tabs modules (the ./presets barrel
-// statically reaches everything; these per-preset entries are the
-// graph-minimal imports).
+/**
+ * presetSingle: the single-pane desktop composition. Its own entry module so a
+ * consumer importing "@cplieger/web-terminal-ui/presets/single" pulls in ONLY
+ * this feature graph — none of the toolbar/tabs modules (the ./presets barrel
+ * statically reaches everything; these per-preset entries are the
+ * graph-minimal imports).
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 import { clipboard } from "../features/clipboard.js";

package/src/presets/tabbed.ts

@@ -1,7 +1,11 @@
-// presetTabbed (and the shared tabbed composition builder): the full
-// multi-session UI. Requires a server that speaks the session API
-// (`/api/sessions`, `/ws?session=`, and the status SSE `/api/sessions/events`),
-// such as `web-terminal-server` or `web-terminal-kiro`.
+/**
+ * presetTabbed (and the shared tabbed composition builder): the full
+ * multi-session UI. Requires a server that speaks the session API
+ * (`/api/sessions`, `/ws?session=`, and the status SSE `/api/sessions/events`),
+ * such as `web-terminal-server` or `web-terminal-kiro`.
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 import { mobileToolbar } from "../features/mobile-toolbar.js";
@@ -18,7 +22,7 @@ export interface TabbedPresetOptions {
   /** Swap the page's icon links to a status variant while a background session
    *  wants the user. Off by default, and enabling it is a promise that the
    *  variant assets are served — see TabsOptions.attentionIcons for the naming
-   *  contract and .kiro/scripts/gen-attention-icons.py, which writes them. */
+   *  contract those files must satisfy. */
   attentionIcons?: boolean;
 }
 
@@ -33,10 +37,9 @@ export interface TabbedPresetOptions {
  *  via ctx.use. Shared by presetTabbed and presetAgentTabbed (agent-tabbed.ts),
  *  which now differ only in presumed activity reporting (presumeReports).
  *
- *  Titles are no longer a preset concern. The ENGINE resolves a session's name —
- *  its pinned name, an input-derived name when the host asked for one
- *  (terminal.WithInputTitle), the program's OSC window title, or its own
- *  foreground-process/cwd inference — and both presets render what it reports. A
+ *  Titles are not a preset concern. The ENGINE resolves a session's name — its
+ *  pinned name, a title its host pushed, the program's OSC window title, or its
+ *  own foreground-process/cwd inference — and both presets render what it reports. A
  *  browser that re-derived any of that could only disagree with the server and
  *  with every other client attached to the same session. */
 export function buildTabbed(

package/src/presets/touch.ts

@@ -1,7 +1,11 @@
-// presetTouch: the touch-first composition (single + the on-screen key
-// toolbar). Its own entry module so a touch consumer's delivered import graph
-// excludes the tabs/activity/animations modules entirely (vibekit's embedded
-// panel imports exactly this).
+/**
+ * presetTouch: the touch-first composition (single + the on-screen key
+ * toolbar). Its own entry module so a touch consumer's delivered import graph
+ * excludes the tabs/activity/animations modules entirely (an embedded panel
+ * imports exactly this).
+ *
+ * @module
+ */
 
 import type { TerminalFeature } from "../kernel/types.js";
 import { mobileToolbar } from "../features/mobile-toolbar.js";

package/src/presets.ts

@@ -1,20 +1,26 @@
-// Feature presets: the barrel. Presets are plain feature-array factories, so
-// they are spreadable and editable: a consumer can drop or add a feature with a
-// filter/spread. This barrel statically imports EVERY preset (and therefore
-// every feature); a consumer that wants the minimal delivered import graph for
-// its composition imports the per-preset entry module instead —
-// "@cplieger/web-terminal-ui/presets/single" | "/presets/touch" |
-// "/presets/tabbed" | "/presets/agent-tabbed" — or hand-picks individual
-// features from "@cplieger/web-terminal-ui/features/<name>".
-//
-// The tabbed presets (presetTabbed / presetAgentTabbed) share the same feature
-// set (both include the activity monitor, whose per-tab dot reveals itself only
-// on OSC 9;4 progress, so a plain shell never shows one). They differ in the
-// title source: presetAgentTabbed sets preferInputTitle (the agent's program
-// emits a useless OSC title, so the label follows the latest submitted line),
-// while presetTabbed is OSC-first. The generic-vs-agent STATUS distinction stays
-// server-side — an agent server sets a classifier mapping OSC 9 notifications to
-// done/needs-input.
+/**
+ * Feature presets: the barrel. Presets are plain feature-array factories, so
+ * they are spreadable and editable: a consumer can drop or add a feature with a
+ * filter/spread. This barrel statically imports EVERY preset (and therefore
+ * every feature); a consumer that wants the minimal delivered import graph for
+ * its composition imports the per-preset entry module instead —
+ * "@cplieger/web-terminal-ui/presets/single" | "/presets/touch" |
+ * "/presets/tabbed" | "/presets/agent-tabbed" — or hand-picks individual
+ * features from "@cplieger/web-terminal-ui/features/<name>".
+ *
+ * The tabbed presets (presetTabbed / presetAgentTabbed) share the same feature
+ * set (both include the activity monitor, which drives the per-tab activity
+ * dot). They differ in one flag, `presumeReports`: presetAgentTabbed presumes
+ * every session's program is an agent that WILL report OSC 9;4 progress, so the
+ * idle dot shows from tab creation instead of appearing seconds later on the
+ * first report, while presetTabbed keeps the evidence-driven reveal so a plain
+ * shell never grows a meaningless dot. Session NAMES are not a preset concern:
+ * the engine resolves them, including a title its host pushes.
+ * The generic-vs-agent STATUS distinction stays server-side — an agent server
+ * sets a classifier mapping OSC 9 notifications to done/needs-input.
+ *
+ * @module
+ */
 
 export { presetSingle } from "./presets/single.js";
 export { presetTouch } from "./presets/touch.js";