@xmoon76/dsh-pi-tui 0.1.8 → 0.2.1

package/dist/builtins.mjs

@@ -0,0 +1,75 @@
+import { TUI_STARTUP_SERVICE } from "./startup.mjs";
+import { M as PI_TUI_EXTENSIONS_SERVICE } from "./src-C_RdKmcj.mjs";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/builtins.ts
+/** Stable Cordis plugin name for the builtins row. */
+const name = "pi-tui-builtins";
+/** The builtins mount only when the TUI startup flags were parsed. */
+const inject = [TUI_STARTUP_SERVICE, PI_TUI_EXTENSIONS_SERVICE];
+/** The `@xmoon76/dsh-pi-tui` package version (dist/extensions.mjs → ../package.json). */
+function packageVersion() {
+	try {
+		return JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")).version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+/**
+* Register the first-party chrome contributions. The turn/step footer
+* segment subscribes to the surface state and re-bakes via handle.replace
+* on every state change (the async-producer → cache → invalidate pattern
+* from the plan §8.4, with replace() as the cache commit).
+* @param ctx - the builtins plugin context (the extension service resolves
+*   through it; the registration is owned by THIS fiber).
+*/
+function apply(ctx) {
+	if (ctx.get("tuiStartup") === void 0) return;
+	const service = ctx.get(PI_TUI_EXTENSIONS_SERVICE);
+	if (service === void 0) return;
+	service.register("chrome.header.badge", {
+		id: "builtin-version",
+		order: 1e3,
+		description: "The bundle version (first-party builtin)."
+	}, {
+		text: `v${packageVersion()}`,
+		tone: "info"
+	});
+	const counters = service.register("chrome.footer.status", {
+		id: "builtin-turns-steps",
+		order: 1e3,
+		description: "Completed turns/steps counters (first-party builtin)."
+	}, { spans: [] });
+	const renderCounters = (state) => {
+		const spans = [{ text: `t${state.session.turns}/s${state.session.steps}` }];
+		counters.replace({ spans });
+	};
+	service.subscribeState((state) => {
+		renderCounters(state);
+	});
+	const todoDock = service.register("input.dock.item", {
+		id: "builtin-todo-summary",
+		order: 1e3,
+		description: "The todo summary line (first-party builtin)."
+	}, { label: [] });
+	const renderTodoDock = (state) => {
+		const summary = state.activity.todoSummary;
+		if (summary === void 0 || summary === "") {
+			todoDock.replace({ label: [] });
+			return;
+		}
+		const label = [{
+			text: "☑  ",
+			tone: "textDim"
+		}, {
+			text: summary,
+			tone: "textDim"
+		}];
+		todoDock.replace({ label });
+	};
+	service.subscribeState((state) => {
+		renderTodoDock(state);
+	});
+}
+//#endregion
+export { apply, inject, name };

package/dist/extension/advanced.d.mts

@@ -0,0 +1,372 @@
+import { E as PiTuiApiInfo, T as NormalizedKey, _ as ExtensionTier, at as TuiOverlayOptions, h as EditorSnapshot, v as ExtensionView } from "../public-types-2omeXG8d.mjs";
+
+//#region src/extension/advanced-types.d.ts
+/** API level of the advanced tier. Bumped only on advanced breaking changes. */
+declare const ADVANCED_API_LEVEL: 1;
+/**
+ * A normalized input event — the ONLY input shape an advanced plugin ever
+ * sees. The Host has already decoded the terminal protocol (legacy + Kitty
+ * CSI-u + modifyOtherKeys encodings, bracketed paste, key release/repeat
+ * filtering), so an advanced plugin behaves identically on every terminal.
+ */
+type AdvancedInputEvent = /** One key press, normalized to the semantic identity. */{
+  readonly kind: 'key';
+  readonly key: NormalizedKey;
+} /** One plain printable character run (ordinary typing). */ | {
+  readonly kind: 'text';
+  readonly text: string;
+} /** A paste burst (bracketed-paste or the host's paste heuristic). */ | {
+  readonly kind: 'paste';
+  readonly text: string;
+};
+/** The capture modes of a normalized input capture (plan §5). */
+type AdvancedInputCaptureMode = 'observe' | 'capture' | 'exclusive';
+/**
+ * One normalized input capture registration (plan §5). The capture is
+ * consulted by the Host AFTER its own capturing flows (questions, approvals,
+ * overlays) and reserved lifecycle keys, and BEFORE the editor and the
+ * Stable keybindings — so an advanced plugin can preempt ordinary editor and
+ * panel input, but never a Host question/approval, a Host overlay, or a
+ * Host fatal-recovery shortcut (session safety stays Host-owned).
+ *
+ * Modes:
+ * - `observe` — never consumes; the handler is a pure observer.
+ * - `capture` — may consume the event (return true).
+ * - `exclusive` — the SOLE capture consumer while live: capture-mode
+ *   captures are not consulted (observers still run). A second exclusive
+ *   registration is an explicit error, never a load-order winner.
+ *
+ * Ordering is deterministic: `priority` ASC, then `id` ASC. A throwing
+ * handler is isolated (health ledger) and FAILS OPEN — the event continues
+ * down the Host ladder, so a broken capture can never stall the TUI.
+ */
+interface AdvancedInputCaptureSpec {
+  /** Stable diagnostic identity, unique per owner. */
+  readonly id: string;
+  /** Deterministic ordering: priority ASC, then id ASC. */
+  readonly priority?: number;
+  /** observe | capture | exclusive (default: capture). */
+  readonly mode?: AdvancedInputCaptureMode;
+  /** Optional gate: the capture is consulted only while this returns true.
+   * A throwing gate is treated as false (the capture is skipped). */
+  readonly when?: () => boolean;
+  /**
+   * The event handler. Return true to CONSUME the event (the Host does
+   * nothing further with it); return false/undefined to pass it on.
+   * A throwing handler is isolated and fails open.
+   */
+  handle(event: AdvancedInputEvent): boolean | void;
+}
+/** A live handle on one normalized input capture. */
+interface AdvancedInputCaptureHandle {
+  readonly id: string;
+  /** Remove the capture. Idempotent; owner unload also disposes it. */
+  dispose(): void;
+}
+/**
+ * The render context handed to an interactive component's render() (plan
+ * §6). The plugin owns its state; the Host compiles the returned
+ * ExtensionView and owns layout, ANSI, width/wrapping and error isolation.
+ */
+interface AdvancedRenderContext {
+  readonly surfaceId: string;
+  readonly generation: number;
+  /** The current terminal width in cells (re-read at every compile). */
+  readonly width: number;
+  /** The current terminal height in rows. */
+  readonly height: number;
+  /** Whether this component currently owns keyboard focus. */
+  readonly focused: boolean;
+}
+/**
+ * A focused interactive component (plan §6): plugin-owned interactive
+ * state rendered through the Host's component kit. The Host compiles
+ * render() output, normalizes input, leases focus and isolates every
+ * callback — the plugin never touches a private component, screen or
+ * terminal.
+ */
+interface AdvancedInteractiveComponent {
+  /** Render the current state as a structured view (Host-compiled). */
+  render(ctx: AdvancedRenderContext): ExtensionView;
+  /**
+   * Receive a normalized input event while this component owns focus.
+   * Return true to consume; false/undefined passes the event on (the Host
+   * drops it — the focused component owns the seat). A throwing handler
+   * is isolated.
+   */
+  handleInput?(event: AdvancedInputEvent): boolean | void;
+  /** The component gained keyboard focus. */
+  onFocus?(): void;
+  /** The component lost keyboard focus. */
+  onBlur?(): void;
+  /** The component was disposed (overlay closed / surface died). */
+  dispose?(): void;
+}
+/**
+ * A Host-owned focus lease (plan §7). In Phase 2 the lease is delivered
+ * through the interactive overlay lease (the overlay IS the focused
+ * interactive surface); a stale lease (surface disposed, owner unloaded)
+ * is inert.
+ */
+interface AdvancedFocusHandle {
+  /** Whether this lease currently holds focus. */
+  readonly active: boolean;
+  /** Request focus for the leased surface. */
+  focus(): void;
+  /** Release focus. */
+  blur(): void;
+  /** Release the lease (idempotent; owner unload also releases it). */
+  dispose(): void;
+}
+/**
+ * A live lease on one interactive managed overlay (plan §8). The plugin
+ * owns the component's state; the Host owns the physical screen mount,
+ * the overlay stack, focus, fullscreen migration and final teardown. The
+ * lease is caller-fiber-owned: owner unload closes the overlay, and a
+ * stale lease (surface disposed) is inert.
+ */
+interface AdvancedOverlayLease {
+  /** The lease identity (stable diagnostic id). */
+  readonly id: string;
+  /** Whether the overlay is still mounted (false after close/dispose). */
+  readonly active: boolean;
+  /** Whether the overlay currently owns keyboard focus. */
+  readonly focused: boolean;
+  /** Request focus for the overlay (also shows it if hidden). */
+  focus(): void;
+  /** Release focus. */
+  blur(): void;
+  /** Recompile the component's render() output and repaint. */
+  invalidate(): void;
+  /** Close the overlay (idempotent; the surface's dispose also closes it). */
+  close(): void;
+  /** Temporarily hide (the lease stays live). */
+  hide(): void;
+  /** Show again after hide(). */
+  show(): void;
+}
+/**
+ * The advanced editor controls (plan §9): direct semantic editor actions
+ * through the Host's editor seat. The Host owns submission/session safety
+ * (dispatch('submit') stays the explicit action path); these controls only
+ * carry text/cursor/focus. A stale controls object (surface disposed) is
+ * inert.
+ */
+interface AdvancedEditorControls {
+  /** The current immutable editor snapshot (text/cursor/focus). */
+  getEditorState(): EditorSnapshot;
+  /** Replace the draft wholesale. */
+  setEditorText(text: string): void;
+  /** Move the cursor to a flat offset within the draft. */
+  setEditorCursor(offset: number): void;
+  /** Insert text at the cursor (or at an explicit offset). */
+  insertEditorText(text: string, at?: number): void;
+  /** Paste text at the cursor (same insertion semantics as
+   * insertEditorText at the cursor — the Host owns paste protection). */
+  pasteToEditor(text: string): void;
+  /** Request keyboard focus for the editor seat. */
+  requestEditorFocus(): void;
+}
+/** The advanced input facade (plan §5). */
+interface AdvancedInputFacade {
+  /**
+   * Register a normalized input capture. Caller-fiber-owned: owner unload
+   * removes it. A duplicate id or a second exclusive capture is an explicit
+   * error.
+   */
+  capture(spec: AdvancedInputCaptureSpec): AdvancedInputCaptureHandle;
+}
+/** One selectable row in the imperative select broker. */
+interface AdvancedSelectItem {
+  readonly value: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly group?: string;
+}
+/** Options for {@link AdvancedUiFacade.select}. */
+interface AdvancedSelectOptions {
+  readonly items: readonly AdvancedSelectItem[];
+  readonly header?: string;
+  readonly enableSearch?: boolean;
+  readonly width?: number;
+  readonly maxHeight?: number;
+  /** Abort the prompt (the promise resolves undefined). */
+  readonly signal?: AbortSignal;
+}
+/** Options for {@link AdvancedUiFacade.confirm}. */
+interface AdvancedConfirmOptions {
+  readonly question: string;
+  readonly detail?: string;
+  /** The approve option label (default 'Yes'). */
+  readonly approveLabel?: string;
+  /** The reject option label (default 'No'). */
+  readonly rejectLabel?: string;
+  /** Abort the prompt (the promise resolves false). */
+  readonly signal?: AbortSignal;
+}
+/** Options for {@link AdvancedUiFacade.input}. */
+interface AdvancedInputOptions {
+  readonly question: string;
+  readonly detail?: string;
+  /** Abort the prompt (the promise resolves undefined). */
+  readonly signal?: AbortSignal;
+}
+/** Options for {@link AdvancedUiFacade.notify}. */
+interface AdvancedNotifyOptions {
+  readonly type?: 'info' | 'error';
+}
+/**
+ * The public host facade handed to a {@link AdvancedUiFacade.custom}
+ * factory (plan §4B). The plugin builds an interactive component against
+ * this facade — never a private TUI object — and completes the custom()
+ * promise through `done`/`close`.
+ */
+interface AdvancedCustomHost {
+  readonly surfaceId: string;
+  readonly generation: number;
+  readonly width: number;
+  readonly height: number;
+  /** Complete the custom() promise with a result (closes the surface). */
+  done(result?: unknown): void;
+  /** Cancel the custom() promise (resolves undefined; closes the surface). */
+  close(): void;
+}
+/** The advanced UI facade (plan §6/§8 + Phase 4 §4A/§4B). */
+interface AdvancedUiFacade {
+  /**
+   * Open an interactive managed overlay hosting a focused interactive
+   * component. The Host mounts it through its overlay broker (modal
+   * stacking, focus, fullscreen migration, teardown) and returns a
+   * caller-fiber-owned lease. A throwing render/input/focus callback is
+   * isolated (health ledger).
+   */
+  showInteractiveOverlay(component: AdvancedInteractiveComponent, options?: TuiOverlayOptions): AdvancedOverlayLease;
+  /**
+   * Imperative selection (plan §4A): show a picker and resolve with the
+   * selected value, or undefined on cancel/abort. Caller-fiber-owned:
+   * owner unload aborts the prompt. Reuses the Host's picker overlay —
+   * no second modal manager.
+   */
+  select(options: AdvancedSelectOptions): Promise<string | undefined>;
+  /**
+   * Imperative confirmation (plan §4A): show a yes/no question and
+   * resolve with the choice; cancel/abort resolves false. Caller-fiber-
+   * owned: owner unload aborts the prompt. Reuses the Host's question
+   * flow.
+   */
+  confirm(options: AdvancedConfirmOptions): Promise<boolean>;
+  /**
+   * Imperative free-text input (plan §4A): show a question with a
+   * free-text row and resolve with the text, or undefined on
+   * cancel/abort. Caller-fiber-owned: owner unload aborts the prompt.
+   * Reuses the Host's question flow.
+   */
+  input(options: AdvancedInputOptions): Promise<string | undefined>;
+  /**
+   * Imperative notification (plan §4A): show a transient notice. Bounded,
+   * no raw ANSI, surface-detach safe, plugin-unload safe.
+   */
+  notify(message: string, options?: AdvancedNotifyOptions): void;
+  /**
+   * Custom interactive UI (plan §4B): mount a factory-built interactive
+   * component (fullscreen/panel/overlay) and resolve with the result the
+   * component reports through {@link AdvancedCustomHost.done}, or
+   * undefined on close/cancel. The factory receives ONLY the public host
+   * facade — never a private TUI object. Caller-fiber-owned: owner
+   * unload closes the surface and settles the promise.
+   */
+  custom(factory: (host: AdvancedCustomHost) => AdvancedInteractiveComponent, options?: TuiOverlayOptions): Promise<unknown>;
+}
+/**
+ * The advanced host-state facade (plan §4D): semantic Host UI state
+ * control — theme query/select, title override, working-indicator
+ * override and tool-expansion preference. The Host owns persistence and
+ * repaint; these are live overrides (a stale facade is inert).
+ */
+interface AdvancedHostState {
+  /** The current theme id ('dark' | 'light' | 'custom'). */
+  getTheme(): string;
+  /** Apply a theme by id ('dark'/'light' or a registered plugin theme
+   * name). Unknown names are a no-op. */
+  setTheme(name: string): void;
+  /** Override the session title shown in the header (undefined clears). */
+  setTitle(title: string | undefined): void;
+  /** Override the working-indicator message (undefined clears). */
+  setWorkingMessage(message: string | undefined): void;
+  /** Set the tool-output expansion master switch. */
+  setToolsExpanded(expanded: boolean): void;
+}
+/** The full advanced facade (plan §4: `advanced(service)`). */
+interface AdvancedFacade {
+  /** Normalized input capture. */
+  readonly input: AdvancedInputFacade;
+  /** Focused interactive surfaces (interactive overlays) + the Phase-4
+   * imperative UI broker (select/confirm/input/notify/custom). */
+  readonly ui: AdvancedUiFacade;
+  /** The CURRENT surface's advanced editor controls (a getter — the
+   * controls follow the live surface attachment). */
+  readonly editor: AdvancedEditorControls;
+  /** The Phase-4 host-state facade (theme/title/working/tools-expanded). */
+  readonly host: AdvancedHostState;
+}
+/**
+ * The minimal service surface the advanced facade consumes (plan §4:
+ * `advanced(service)`). STRUCTURAL and defined here so the packed
+ * advanced declarations never reference the internal service module —
+ * the concrete `piTuiExtensions` service implements these members, but
+ * the public `PiTuiExtensionService` interface does not declare them.
+ *
+ * `api` is the structural anchor: a plain `PiTuiExtensionService` value
+ * satisfies the facade's parameter (the seam members are optional in the
+ * type), and the facade throws loudly when the host does not implement
+ * the seam (a host/plugin version mismatch) instead of failing later
+ * with an obscure "not a function".
+ */
+interface AdvancedServiceHost {
+  /** The public api() surface (the structural anchor — the facade does
+   * not consume it; it makes a plain `PiTuiExtensionService` value
+   * assignable to the parameter). */
+  readonly api: () => PiTuiApiInfo;
+  /** The service's internal advanced seam: register a normalized input
+   * capture (caller-fiber-owned). */
+  _advancedCaptureInput?(spec: AdvancedInputCaptureSpec): AdvancedInputCaptureHandle;
+  /** The service's internal advanced seam: open an interactive managed
+   * overlay (caller-fiber-owned lease). */
+  _advancedShowInteractiveOverlay?(component: AdvancedInteractiveComponent, options?: TuiOverlayOptions): AdvancedOverlayLease;
+  /** The service's internal advanced seam: the current surface's advanced
+   * editor controls (inert when stale). */
+  _advancedEditorControls?(): AdvancedEditorControls;
+  /** The service's internal advanced seam (Phase 4): the imperative UI
+   * broker (select/confirm/input/notify/custom). */
+  _advancedUiSelect?(options: AdvancedSelectOptions): Promise<string | undefined>;
+  _advancedUiConfirm?(options: AdvancedConfirmOptions): Promise<boolean>;
+  _advancedUiInput?(options: AdvancedInputOptions): Promise<string | undefined>;
+  _advancedUiNotify?(message: string, options?: AdvancedNotifyOptions): void;
+  _advancedUiCustom?(factory: (host: AdvancedCustomHost) => AdvancedInteractiveComponent, options?: TuiOverlayOptions): Promise<unknown>;
+  /** The service's internal advanced seam (Phase 4): the host-state
+   * facade (theme/title/working/tools-expanded). */
+  _advancedHostState?(): AdvancedHostState;
+}
+//#endregion
+//#region src/extension/advanced.d.ts
+/**
+ * Build the ADVANCED facade over the shared `piTuiExtensions` service
+ * (plan §4). The facade is a thin capability view: every resource it
+ * creates is caller-fiber-owned and surface-generation-scoped through the
+ * service's shared Extension Runtime — never a second plugin system.
+ *
+ * The facade is safe to call before any surface exists: registrations
+ * (input captures) are service-lifetime and attach later; leases
+ * (interactive overlays) and the editor controls are inert until a
+ * surface is live.
+ *
+ * The parameter is the structural {@link AdvancedServiceHost}: a plain
+ * `PiTuiExtensionService` value is accepted (the seam members are optional
+ * in the type), and the facade throws loudly when the host does not
+ * implement the seam (a host/plugin version mismatch).
+ * @param service - the `piTuiExtensions` service (from `ctx.get(...)`).
+ * @returns the Advanced facade.
+ */
+declare function advanced(service: AdvancedServiceHost): AdvancedFacade;
+//#endregion
+export { ADVANCED_API_LEVEL, type AdvancedConfirmOptions, type AdvancedCustomHost, type AdvancedEditorControls, type AdvancedFacade, type AdvancedFocusHandle, type AdvancedHostState, type AdvancedInputCaptureHandle, type AdvancedInputCaptureMode, type AdvancedInputCaptureSpec, type AdvancedInputEvent, type AdvancedInputFacade, type AdvancedInputOptions, type AdvancedInteractiveComponent, type AdvancedNotifyOptions, type AdvancedOverlayLease, type AdvancedRenderContext, type AdvancedSelectItem, type AdvancedSelectOptions, type AdvancedServiceHost, type AdvancedUiFacade, type ExtensionTier, advanced };

package/dist/extension/advanced.mjs

@@ -0,0 +1,46 @@
+//#region src/extension/advanced-types.ts
+/** API level of the advanced tier. Bumped only on advanced breaking changes. */
+const ADVANCED_API_LEVEL = 1;
+//#endregion
+//#region src/extension/advanced.ts
+/**
+* Build the ADVANCED facade over the shared `piTuiExtensions` service
+* (plan §4). The facade is a thin capability view: every resource it
+* creates is caller-fiber-owned and surface-generation-scoped through the
+* service's shared Extension Runtime — never a second plugin system.
+*
+* The facade is safe to call before any surface exists: registrations
+* (input captures) are service-lifetime and attach later; leases
+* (interactive overlays) and the editor controls are inert until a
+* surface is live.
+*
+* The parameter is the structural {@link AdvancedServiceHost}: a plain
+* `PiTuiExtensionService` value is accepted (the seam members are optional
+* in the type), and the facade throws loudly when the host does not
+* implement the seam (a host/plugin version mismatch).
+* @param service - the `piTuiExtensions` service (from `ctx.get(...)`).
+* @returns the Advanced facade.
+*/
+function advanced(service) {
+	const host = service;
+	if (host._advancedCaptureInput === void 0 || host._advancedShowInteractiveOverlay === void 0 || host._advancedEditorControls === void 0 || host._advancedUiSelect === void 0 || host._advancedUiConfirm === void 0 || host._advancedUiInput === void 0 || host._advancedUiNotify === void 0 || host._advancedUiCustom === void 0 || host._advancedHostState === void 0) throw new Error("this piTuiExtensions host does not implement the advanced seam (host/plugin version mismatch? upgrade the host bundle)");
+	return {
+		input: { capture: (spec) => host._advancedCaptureInput(spec) },
+		ui: {
+			showInteractiveOverlay: (component, options) => host._advancedShowInteractiveOverlay(component, options),
+			select: (options) => host._advancedUiSelect(options),
+			confirm: (options) => host._advancedUiConfirm(options),
+			input: (options) => host._advancedUiInput(options),
+			notify: (message, options) => host._advancedUiNotify(message, options),
+			custom: (factory, options) => host._advancedUiCustom(factory, options)
+		},
+		get editor() {
+			return host._advancedEditorControls();
+		},
+		get host() {
+			return host._advancedHostState();
+		}
+	};
+}
+//#endregion
+export { ADVANCED_API_LEVEL, advanced };