@mp-lb/termkit 0.2.1 → 0.2.3

package/README.md

@@ -1,122 +1,29 @@
 # @mp-lb/termkit
 
-Easily orchestrate terminal sessions in React. Render a `<Terminal />`, and manage
-all your live sessions — including their attention bells — with a small set of
-global hooks.
-
-## Mental model
-
-- A **session** is a long-lived shell (a PTY) living in the **daemon**
-  (`@mp-lb/termkit-server`), addressed by a stable id you choose.
-- A `<Terminal session={id} />` is just a **view** onto a session. Mounting it
-  attaches (reconnecting to the existing shell if there is one, via a replayed
-  screen snapshot); unmounting detaches but leaves the shell running.
-- The `<TermkitProvider>` holds the **global registry** of sessions and polls the
-  daemon for the live list. So there is **no one-to-one** requirement between the
-  terminals on screen and the sessions that are alive — you can have background
-  sessions with no terminal, and you can see/manage them from anywhere.
-
-## Two ways to use a session
-
-- **Local:** drop `<Terminal session="abc" />` somewhere. Rendering it creates or
-  reattaches session `abc`. Its lifecycle reads as component-local — but the
-  session itself outlives the component.
-- **Global:** use the hooks (`useSessions`, `useRingingSessions`,
-  `useTermkitActions`, …) anywhere under the provider to list every session, watch
-  which ones are **belling** for attention, and act on them — whether or not a
-  terminal is mounted for them.
-
-## Setup
+Build React terminal experiences backed by persistent PTY sessions. This workspace package is private while its API is being designed; use it through the workspace dependency `workspace:*`.
 
 ```tsx
-import { TermkitProvider } from "@mp-lb/termkit"
+import { Terminal, TermkitProvider, type TermkitConfig } from "@mp-lb/termkit";
 
-const config = {
-  // Where the byte stream lives. `params` is forwarded to the daemon as session
-  // metadata and drives its resolveCwd.
+const config: TermkitConfig = {
   connectionUrl: ({ sessionId, params }) =>
-    `ws://${location.host}/_terminal?` +
-    new URLSearchParams({ session: sessionId, ...params }),
-  // The control plane: list / kill / clear-bell. Wire to your backend.
+    `wss://example.com/_terminal?${new URLSearchParams({ ...params, session: sessionId })}`,
   transport: {
-    list: () => trpc.terminal.list.query(),
-    kill: (sessionId) => trpc.terminal.kill.mutate({ sessionId }),
-    seen: (sessionId) => trpc.terminal.seen.mutate({ sessionId }),
+    list: () => api.terminal.list(),
+    kill: (sessionId) => api.terminal.kill(sessionId),
+    seen: (sessionId) => api.terminal.seen(sessionId),
   },
-}
-
-<TermkitProvider config={config}>
-  <App />
-</TermkitProvider>
-```
-
-## Rendering a terminal
-
-```tsx
-import { Terminal } from "@mp-lb/termkit"
-
-<Terminal session="global" autoFocus />
-<Terminal session={tab.id} params={{ slug: "myproject" }} />
-```
-
-Props: `session` (required, stable id), `params`, `autoFocus`, `dismissOnView`
-(default `true` — clear this session's bell when you view it), `pendingCommand`
-(auto-typed once after the prompt settles), `onExitFocus` (called on
-Ctrl+Shift+Enter, after termkit blurs the terminal), `background`, `className`,
-`style`.
-
-## Bells & session hooks
-
-```tsx
-const sessions = useSessions()             // LiveSession[] — the global list
-const ringing = useRingingSessions()       // Set<string> of ids belling for attention
-const isRinging = useIsRinging(id)          // one session
-const status = useSessionStatus(id)         // connecting | ready | disconnected | dead
-const { focus, kill, dismissBell, dismissAllBells, setPendingCommand } =
-  useTermkitActions()
+};
+
+export const Shell = () => (
+  <TermkitProvider config={config}>
+    <div style={{ height: 400 }}>
+      <Terminal session="workspace" autoFocus />
+    </div>
+  </TermkitProvider>
+);
 ```
 
-Bells clear automatically when you view a session (`dismissOnView`), or explicitly
-via `dismissBell(id)` / `dismissAllBells()`.
-
-## Theming
-
-`<Terminal>` renders xterm on a transparent surface inside a full-size wrapper.
-Set the wrapper background with Tailwind/classes, an explicit colour, a CSS
-variable, or a provider default:
-
-```tsx
-<Terminal session="global" className="bg-zinc-950" />
-<Terminal session="global" background="var(--background)" />
-<Terminal session="global" style={{ backgroundColor: theme.terminal }} />
-
-const config = {
-  ...baseConfig,
-  terminalOptions: { background: "var(--termkit-bg)" },
-}
-```
-
-Because the terminal itself is transparent, any leftover space that cannot fit a
-full row or column uses the same background as the terminal.
-
-## Migrating dash onto termkit
-
-termkit is a superset of what `dash` does today; the mapping is mechanical:
-
-| dash | termkit |
-| --- | --- |
-| `<Terminal slot=… slug=… instanceId=… />` | `<Terminal session=… params={{ slug, instanceId }} />` |
-| `useTerminalStore` (zustand) | the provider store + `useTermkitActions` |
-| `live-sessions.ts` poller + `useLiveSessions` | built into `<TermkitProvider>` + `useSessions` |
-| `useRingingSessionIds` | `useRingingSessions` |
-| `markTerminalSeen` on focus/view | `dismissOnView` (default on) + `dismissBell` |
-| `LiveSession.slug` / `.instanceId` | `LiveSession.meta.slug` / `.meta.instanceId` |
-| exit-chord → focus `[data-session-tab]` | `onExitFocus` callback |
-| `useKnownSessionIds` / `useSessionSummaries` | **stay in dash** — built on `useSessions()` (project/slug grouping is dash domain) |
-| daemon (`server/terminal-daemon.ts`) | `createTerminalDaemon({ resolveCwd })` from `@mp-lb/termkit-server` |
-| tRPC `terminal` router | `createTerminalRouter(client)` from `@mp-lb/termkit-trpc`, or keep dash's |
+`api` represents your host application's control-plane adapter. Keep the provider configuration stable. Unmounting a terminal detaches the view; the shell keeps running in the daemon. Remounting the same session ID reattaches to its current screen.
 
-The dash-specific seams — the `~/Code` working-directory resolution and the
-project/instance groupings — are deliberately **not** baked in: the daemon takes a
-`resolveCwd` callback, and per-project rollups stay in dash, layered over the
-generic `useSessions()` list.
+See the [guide](../../docs/public/index.mdx) and [generated reference](../../docs/public/api/index.mdx). The Node daemon and optional tRPC adapter live in sibling packages and are kept out of the browser entrypoint.

package/dist/Terminal.d.ts

@@ -1,5 +1,7 @@
 import { type CSSProperties } from "react";
+import { type ITheme } from "@xterm/xterm";
 import "@xterm/xterm/css/xterm.css";
+import { type TerminalColors } from "./terminalColors.js";
 export interface TerminalProps {
     session: string;
     params?: Record<string, string>;
@@ -7,9 +9,13 @@ export interface TerminalProps {
     dismissOnView?: boolean;
     pendingCommand?: string;
     onExitFocus?: () => void;
+    exitFocusChord?: "ctrl-enter" | "ctrl-shift-enter";
     background?: string;
+    colors?: TerminalColors;
+    theme?: ITheme;
+    visible?: boolean;
     className?: string;
     style?: CSSProperties;
 }
-export declare function Terminal({ session, params, autoFocus, dismissOnView, pendingCommand, onExitFocus, background, className, style, }: TerminalProps): import("react/jsx-runtime").JSX.Element;
+export declare function Terminal({ session, params, autoFocus, dismissOnView, pendingCommand, onExitFocus, exitFocusChord, background, colors, theme, visible, className, style, }: TerminalProps): import("react").JSX.Element;
 //# sourceMappingURL=Terminal.d.ts.map

package/dist/Terminal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Terminal.d.ts","sourceRoot":"","sources":["../src/Terminal.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,OAAO,CAAA;AAG7D,OAAO,4BAA4B,CAAA;AAWnC,MAAM,WAAW,aAAa;IAK5B,OAAO,EAAE,MAAM,CAAA;IAIf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE/B,SAAS,CAAC,EAAE,OAAO,CAAA;IAKnB,aAAa,CAAC,EAAE,OAAO,CAAA;IAGvB,cAAc,CAAC,EAAE,MAAM,CAAA;IAIvB,WAAW,CAAC,EAAE,MAAM,IAAI,CAAA;IAIxB,UAAU,CAAC,EAAE,MAAM,CAAA;IAGnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAED,wBAAgB,QAAQ,CAAC,EACvB,OAAO,EACP,MAAM,EACN,SAAiB,EACjB,aAAoB,EACpB,cAAc,EACd,WAAW,EACX,UAAU,EACV,SAAS,EACT,KAAK,GACN,EAAE,aAAa,2CA2Sf"}
+{"version":3,"file":"Terminal.d.ts","sourceRoot":"","sources":["../src/Terminal.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EAAqB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,4BAA4B,CAAC;AAUpC,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,aAAa;IAK5B,OAAO,EAAE,MAAM,CAAC;IAIhB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhC,SAAS,CAAC,EAAE,OAAO,CAAC;IAKpB,aAAa,CAAC,EAAE,OAAO,CAAC;IAGxB,cAAc,CAAC,EAAE,MAAM,CAAC;IAIxB,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IAGzB,cAAc,CAAC,EAAE,YAAY,GAAG,kBAAkB,CAAC;IAInD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,MAAM,CAAC,EAAE,cAAc,CAAC;IAIxB,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,OAAO,CAAC,EAAE,OAAO,CAAC;IAGlB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,wBAAgB,QAAQ,CAAC,EACvB,OAAO,EACP,MAAM,EACN,SAAiB,EACjB,aAAoB,EACpB,cAAc,EACd,WAAW,EACX,cAAmC,EACnC,UAAU,EACV,MAAM,EACN,KAAK,EACL,OAAc,EACd,SAAS,EACT,KAAK,GACN,EAAE,aAAa,+BAscf"}

package/dist/Terminal.js

@@ -4,12 +4,14 @@ import { Terminal as XTerm } from "@xterm/xterm";
 import { FitAddon } from "@xterm/addon-fit";
 import "@xterm/xterm/css/xterm.css";
 import { CLOSE_SESSION_GONE, HEARTBEAT_INTERVAL_MS, HEARTBEAT_PONG_GRACE_MS, } from "@mp-lb/termkit-core";
-import { useTermkitContext } from "./context.js";
+import { useTermkitContext } from "./useTermkitContext.js";
 import { createTerminalWriteQueue } from "./createTerminalWriteQueue.js";
 import { fitTerminal } from "./fitTerminal.js";
-export function Terminal({ session, params, autoFocus = false, dismissOnView = true, pendingCommand, onExitFocus, background, className, style, }) {
+import { resolveTerminalColors, } from "./terminalColors.js";
+export function Terminal({ session, params, autoFocus = false, dismissOnView = true, pendingCommand, onExitFocus, exitFocusChord = "ctrl-shift-enter", background, colors, theme, visible = true, className, style, }) {
     const { store, config } = useTermkitContext();
     const containerRef = useRef(null);
+    const refreshLayoutBurstRef = useRef(() => { });
     const containerStyle = {
         width: "100%",
         height: "100%",
@@ -18,7 +20,7 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
     };
     useEffect(() => {
         const sessionId = session;
-        const { attach, detach, focus, blur, setStatus, setPendingCommand, consumePendingCommand } = store.getState();
+        const { attach, detach, focus, blur, setStatus, setPendingCommand, consumePendingCommand, } = store.getState();
         attach(sessionId);
         if (pendingCommand !== undefined)
             setPendingCommand(sessionId, pendingCommand);
@@ -32,18 +34,40 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
         // if the ref is repointed before teardown runs.
         const container = containerRef.current;
         const opts = config.terminalOptions ?? {};
+        const terminalTheme = {
+            ...resolveTerminalColors(opts.colors),
+            ...opts.theme,
+            ...resolveTerminalColors(colors),
+            ...theme,
+            background: theme?.background ??
+                (typeof colors === "object" ? colors.background : undefined) ??
+                opts.theme?.background ??
+                (typeof opts.colors === "object"
+                    ? opts.colors.background
+                    : undefined) ??
+                background ??
+                opts.background,
+        };
         const term = new XTerm({
             fontFamily: opts.fontFamily ?? '"IBM Plex Mono", monospace',
             fontSize: opts.fontSize ?? 13,
             cursorBlink: opts.cursorBlink ?? true,
-            theme: { background: "transparent" },
+            theme: terminalTheme,
         });
         const fitAddon = new FitAddon();
         term.loadAddon(fitAddon);
         term.open(container);
+        for (const selector of [
+            ".xterm-viewport",
+            ".xterm-scrollable-element",
+            ".xterm-screen",
+        ]) {
+            container
+                .querySelector(selector)
+                ?.style.setProperty("background-color", "transparent", "important");
+        }
         let lastFitSize = fitTerminal(container, term, fitAddon, null);
         let lastSentSize = null;
-        const terminalWriteQueue = createTerminalWriteQueue(term);
         // If a bell lands while you're actively looking at this session — its terminal
         // is visible and the window has focus — it's already "seen", so clear it now
         // instead of making you switch away and back. Bells that arrive while you're
@@ -59,6 +83,7 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
         else if (term.textarea) {
             term.textarea.tabIndex = -1;
         }
+        let scheduleLayoutRefreshBurst = () => { };
         // Subscribe to store focus changes so external callers (focus/blur actions) work.
         const unsubFocus = store.subscribe((state, prev) => {
             const isFocused = state.focusedSlot === sessionId;
@@ -68,6 +93,7 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
                 if (term.textarea)
                     term.textarea.tabIndex = 0;
                 term.focus();
+                scheduleLayoutRefreshBurst();
             }
             else {
                 term.blur();
@@ -80,15 +106,21 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
         const onFocus = () => {
             focus(sessionId);
             markSeen();
+            scheduleLayoutRefreshBurst();
         };
         const onBlur = () => blur(sessionId);
         term.textarea?.addEventListener("focus", onFocus);
         term.textarea?.addEventListener("blur", onBlur);
-        // Ctrl+Shift+Enter exits terminal focus. Handled here (capture on the container,
+        // The configured chord exits terminal focus. Handled here (capture on the container,
         // before xterm sees it) because global capture listeners don't reliably fire for
         // Enter when xterm has focus. We blur and hand control back to the host.
         const onExitChord = (e) => {
-            if (e.key === "Enter" && e.shiftKey && e.ctrlKey) {
+            const isExitChord = e.key === "Enter" &&
+                e.ctrlKey &&
+                !e.altKey &&
+                !e.metaKey &&
+                (exitFocusChord === "ctrl-shift-enter" ? e.shiftKey : !e.shiftKey);
+            if (isExitChord) {
                 e.preventDefault();
                 e.stopPropagation();
                 blur(sessionId);
@@ -104,6 +136,7 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
         let socket = null;
         let reconnectTimer = null;
         let refreshFrame = null;
+        const refreshTimers = new Set();
         let disposed = false;
         let attachedBefore = false;
         // App-level heartbeat. A half-open socket (laptop sleep/wake, Wi-Fi change, a
@@ -138,7 +171,9 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
                         try {
                             socket?.close();
                         }
-                        catch { /* already closing */ }
+                        catch {
+                            /* already closing */
+                        }
                     }, HEARTBEAT_PONG_GRACE_MS);
                 }
             }, HEARTBEAT_INTERVAL_MS);
@@ -198,7 +233,10 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
             if (nextSize === null)
                 return;
             lastFitSize = nextSize;
-            if (lastSentSize?.cols === nextSize.cols && lastSentSize.rows === nextSize.rows)
+            if (lastSentSize?.cols === nextSize.cols &&
+                lastSentSize.rows === nextSize.rows)
+                return;
+            if (socket?.readyState !== WebSocket.OPEN)
                 return;
             lastSentSize = nextSize;
             send({ type: "resize", cols: nextSize.cols, rows: nextSize.rows });
@@ -216,10 +254,28 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
                 return;
             refreshFrame = requestAnimationFrame(refreshVisibleRows);
         };
+        const refreshAfterDelay = (ms) => {
+            const timer = setTimeout(() => {
+                refreshTimers.delete(timer);
+                refreshAfterLayout();
+            }, ms);
+            refreshTimers.add(timer);
+        };
+        const refreshLayoutBurst = () => {
+            refreshAfterLayout();
+            refreshAfterDelay(50);
+            refreshAfterDelay(150);
+            refreshAfterDelay(500);
+            refreshAfterDelay(1000);
+            refreshAfterDelay(2000);
+        };
+        scheduleLayoutRefreshBurst = refreshLayoutBurst;
+        refreshLayoutBurstRef.current = refreshLayoutBurst;
         const refreshWhenVisible = () => {
             if (document.visibilityState === "visible")
-                refreshAfterLayout();
+                refreshLayoutBurst();
         };
+        const terminalWriteQueue = createTerminalWriteQueue(term, refreshAfterLayout);
         const connect = () => {
             if (disposed)
                 return;
@@ -240,6 +296,7 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
                 attachedBefore = true;
                 setStatus(sessionId, "ready");
                 fitAndSendResize();
+                refreshLayoutBurst();
                 // Run the queued command once, on the very first attach. Wait for the prompt
                 // to finish painting (see noteOutput/flushPendingCmd) so it lands on the real
                 // prompt instead of racing shell startup. The cap timer is a backstop.
@@ -262,7 +319,9 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
                             if (msg.type === "pong")
                                 onPong();
                         }
-                        catch { /* unknown control frame — ignore */ }
+                        catch {
+                            /* unknown control frame — ignore */
+                        }
                     }
                     return;
                 }
@@ -288,20 +347,30 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
             };
         };
         connect();
-        term.onData((data) => send({ type: "input", data }));
+        term.onData((data) => {
+            fitAndSendResize();
+            send({ type: "input", data });
+        });
         const observer = new ResizeObserver(refreshAfterLayout);
         observer.observe(container);
         container.addEventListener("pointerdown", refreshAfterLayout, true);
-        container.addEventListener("wheel", refreshAfterLayout, { capture: true, passive: true });
+        container.addEventListener("wheel", refreshAfterLayout, {
+            capture: true,
+            passive: true,
+        });
         window.addEventListener("focus", refreshAfterLayout);
         window.addEventListener("pageshow", refreshAfterLayout);
         document.addEventListener("visibilitychange", refreshWhenVisible);
+        document.fonts?.ready.then(refreshLayoutBurst).catch(() => { });
         return () => {
             disposed = true;
             if (reconnectTimer !== null)
                 clearTimeout(reconnectTimer);
             if (refreshFrame !== null)
                 cancelAnimationFrame(refreshFrame);
+            for (const timer of refreshTimers)
+                clearTimeout(timer);
+            refreshTimers.clear();
             stopHeartbeat();
             clearAutoType();
             blur(sessionId);
@@ -323,8 +392,12 @@ export function Terminal({ session, params, autoFocus = false, dismissOnView = t
             term.textarea?.removeEventListener("blur", onBlur);
             terminalWriteQueue.dispose();
             term.dispose();
+            refreshLayoutBurstRef.current = () => { };
         };
     }, [session]); // eslint-disable-line react-hooks/exhaustive-deps
-    return _jsx("div", { ref: containerRef, className: className, style: containerStyle });
+    useEffect(() => {
+        if (visible)
+            refreshLayoutBurstRef.current();
+    }, [visible]);
+    return (_jsx("div", { ref: containerRef, className: className, style: containerStyle }));
 }
-//# sourceMappingURL=Terminal.js.map

package/dist/TermkitContext.d.ts

@@ -0,0 +1,8 @@
+import type { TermkitStore } from "./createTermkitStore.js";
+import type { TermkitConfig } from "./types.js";
+export interface TermkitContextValue {
+    store: TermkitStore;
+    config: TermkitConfig;
+}
+export declare const TermkitContext: import("react").Context<TermkitContextValue | null>;
+//# sourceMappingURL=TermkitContext.d.ts.map

package/dist/TermkitContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TermkitContext.d.ts","sourceRoot":"","sources":["../src/TermkitContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,eAAO,MAAM,cAAc,qDAAkD,CAAC"}

package/dist/TermkitContext.js

@@ -0,0 +1,2 @@
+import { createContext } from "react";
+export const TermkitContext = createContext(null);

package/dist/TermkitProvider.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from "react";
+import type { TermkitConfig } from "./types.js";
+export interface TermkitProviderProps {
+    config: TermkitConfig;
+    children: ReactNode;
+}
+export declare const TermkitProvider: ({ config, children }: TermkitProviderProps) => import("react").JSX.Element;
+//# sourceMappingURL=TermkitProvider.d.ts.map

package/dist/TermkitProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TermkitProvider.d.ts","sourceRoot":"","sources":["../src/TermkitProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAG5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAOD,eAAO,MAAM,eAAe,GAAI,sBAAsB,oBAAoB,gCAuCzE,CAAC"}

package/dist/{context.js → TermkitProvider.js}

@@ -1,20 +1,20 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useRef } from "react";
-import { createTermkitStore } from "./store.js";
-const TermkitContext = createContext(null);
+import { useEffect, useState } from "react";
+import { createTermkitStore } from "./createTermkitStore.js";
+import { TermkitContext } from "./TermkitContext.js";
 // Holds the global session registry and config for everything below it. Mount it
 // once near your app root. The registry lives here (not in each <Terminal>), which
 // is what makes sessions outlive the terminals that render them: a <Terminal> is
 // just a view onto a session, and the provider's poller keeps the live list fresh
 // whether or not any terminal is currently mounted for it.
-export function TermkitProvider({ config, children }) {
+export const TermkitProvider = ({ config, children }) => {
     // Create the store once. Config is captured at first render; treat it as stable
     // (define it outside render or memoize it host-side, like any context value).
-    const valueRef = useRef(null);
-    if (valueRef.current === null) {
-        valueRef.current = { store: createTermkitStore(config.transport), config };
-    }
-    const { store } = valueRef.current;
+    const [value] = useState(() => ({
+        store: createTermkitStore(config.transport),
+        config,
+    }));
+    const { store } = value;
     // The single poller: one fetch loop publishes the live snapshot every consumer
     // reads. Cheap on the daemon (an in-memory map read), so a couple of seconds
     // keeps bells and counts responsive without being chatty.
@@ -39,12 +39,5 @@ export function TermkitProvider({ config, children }) {
         };
         // config.transport is captured once with the store; re-poll only if cadence changes.
     }, [intervalMs, store, config.transport]);
-    return _jsx(TermkitContext.Provider, { value: valueRef.current, children: children });
-}
-export function useTermkitContext() {
-    const ctx = useContext(TermkitContext);
-    if (!ctx)
-        throw new Error("useTermkit must be used within a <TermkitProvider>");
-    return ctx;
-}
-//# sourceMappingURL=context.js.map
+    return (_jsx(TermkitContext.Provider, { value: value, children: children }));
+};

package/dist/createTerminalWriteQueue.d.ts

@@ -1,7 +1,7 @@
 interface WritableTerminal {
     write: (data: string, callback?: () => void) => void;
 }
-export declare const createTerminalWriteQueue: (term: WritableTerminal) => {
+export declare const createTerminalWriteQueue: (term: WritableTerminal, afterWrite?: () => void) => {
     write(data: string): void;
     clear(): void;
     dispose(): void;

package/dist/createTerminalWriteQueue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createTerminalWriteQueue.d.ts","sourceRoot":"","sources":["../src/createTerminalWriteQueue.ts"],"names":[],"mappings":"AAAA,UAAU,gBAAgB;IACxB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;CACrD;AAED,eAAO,MAAM,wBAAwB,GAAI,MAAM,gBAAgB;gBAkB/C,MAAM;;;CAarB,CAAA"}
+{"version":3,"file":"createTerminalWriteQueue.d.ts","sourceRoot":"","sources":["../src/createTerminalWriteQueue.ts"],"names":[],"mappings":"AAAA,UAAU,gBAAgB;IACxB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACtD;AAED,eAAO,MAAM,wBAAwB,GACnC,MAAM,gBAAgB,EACtB,aAAa,MAAM,IAAI;gBAoBT,MAAM;;;CAarB,CAAC"}

package/dist/createTerminalWriteQueue.js

@@ -1,4 +1,4 @@
-export const createTerminalWriteQueue = (term) => {
+export const createTerminalWriteQueue = (term, afterWrite) => {
     let chunks = [];
     let isWriting = false;
     let isDisposed = false;
@@ -10,6 +10,7 @@ export const createTerminalWriteQueue = (term) => {
         isWriting = true;
         term.write(data, () => {
             isWriting = false;
+            afterWrite?.();
             drain();
         });
     };
@@ -29,4 +30,3 @@ export const createTerminalWriteQueue = (term) => {
         },
     };
 };
-//# sourceMappingURL=createTerminalWriteQueue.js.map

package/dist/{store.d.ts → createTermkitStore.d.ts}

@@ -23,4 +23,4 @@ export interface TermkitState {
 }
 export type TermkitStore = StoreApi<TermkitState>;
 export declare function createTermkitStore(transport: TermkitTransport): TermkitStore;
-//# sourceMappingURL=store.d.ts.map
+//# sourceMappingURL=createTermkitStore.d.ts.map

package/dist/createTermkitStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTermkitStore.d.ts","sourceRoot":"","sources":["../src/createTermkitStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAOlE,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAE3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAEpC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAI3B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAIxC,IAAI,EAAE,WAAW,EAAE,CAAC;IAGpB,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,SAAS,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAG9D,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAGlC,iBAAiB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChE,qBAAqB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAG5D,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAGzC,OAAO,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;AAElD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,gBAAgB,GAAG,YAAY,CAkG5E"}

package/dist/{store.js → createTermkitStore.js}

@@ -19,7 +19,10 @@ export function createTermkitStore(transport) {
                     return s;
                 const slots = { ...s.slots };
                 delete slots[sessionId];
-                return { slots, focusedSlot: s.focusedSlot === sessionId ? null : s.focusedSlot };
+                return {
+                    slots,
+                    focusedSlot: s.focusedSlot === sessionId ? null : s.focusedSlot,
+                };
             });
         },
         setStatus(sessionId, status) {
@@ -34,10 +37,14 @@ export function createTermkitStore(transport) {
             set({ focusedSlot: sessionId });
         },
         blur(sessionId) {
-            set((s) => ({ focusedSlot: s.focusedSlot === sessionId ? null : s.focusedSlot }));
+            set((s) => ({
+                focusedSlot: s.focusedSlot === sessionId ? null : s.focusedSlot,
+            }));
         },
         setPendingCommand(sessionId, command) {
-            set((s) => ({ pendingCommands: { ...s.pendingCommands, [sessionId]: command } }));
+            set((s) => ({
+                pendingCommands: { ...s.pendingCommands, [sessionId]: command },
+            }));
         },
         consumePendingCommand(sessionId) {
             const command = get().pendingCommands[sessionId];
@@ -74,7 +81,7 @@ export function createTermkitStore(transport) {
             // Optimistically clear attention so the badge goes away immediately; the
             // next poll confirms it.
             set((s) => ({
-                live: s.live.map((l) => (l.sessionId === sessionId ? { ...l, attention: false } : l)),
+                live: s.live.map((l) => l.sessionId === sessionId ? { ...l, attention: false } : l),
             }));
         },
         setLive(live) {
@@ -82,4 +89,3 @@ export function createTermkitStore(transport) {
         },
     }));
 }
-//# sourceMappingURL=store.js.map

package/dist/fitTerminal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fitTerminal.d.ts","sourceRoot":"","sources":["../src/fitTerminal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAChD,OAAO,KAAK,EAAE,QAAQ,IAAI,KAAK,EAAE,MAAM,cAAc,CAAA;AAErD,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED,eAAO,MAAM,WAAW,GACtB,WAAW,WAAW,EACtB,MAAM,KAAK,EACX,UAAU,QAAQ,EAClB,UAAU,YAAY,GAAG,IAAI,KAC5B,YAAY,GAAG,IASjB,CAAA"}
+{"version":3,"file":"fitTerminal.d.ts","sourceRoot":"","sources":["../src/fitTerminal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,IAAI,KAAK,EAAE,MAAM,cAAc,CAAC;AAEtD,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAiDD,eAAO,MAAM,WAAW,GACtB,WAAW,WAAW,EACtB,MAAM,KAAK,EACX,UAAU,QAAQ,EAClB,UAAU,YAAY,GAAG,IAAI,KAC5B,YAAY,GAAG,IAiBjB,CAAC"}

package/dist/fitTerminal.js

@@ -1,10 +1,42 @@
+function parsePixels(value) {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function fallbackDimensions(container) {
+    if (typeof container.querySelector !== "function")
+        return null;
+    const terminal = container.querySelector(".xterm");
+    const measure = container.querySelector(".xterm-helper-textarea");
+    if (!terminal || !measure)
+        return null;
+    const terminalStyle = window.getComputedStyle(terminal);
+    const cell = measure.getBoundingClientRect();
+    if (cell.width <= 0 || cell.height <= 0)
+        return null;
+    const paddingX = parsePixels(terminalStyle.paddingLeft) +
+        parsePixels(terminalStyle.paddingRight);
+    const paddingY = parsePixels(terminalStyle.paddingTop) +
+        parsePixels(terminalStyle.paddingBottom);
+    const scrollbarWidth = 14;
+    const availableWidth = Math.max(0, container.clientWidth - paddingX - scrollbarWidth);
+    const availableHeight = Math.max(0, container.clientHeight - paddingY);
+    return {
+        cols: Math.max(2, Math.floor(availableWidth / cell.width)),
+        rows: Math.max(1, Math.floor(availableHeight / cell.height)),
+    };
+}
 export const fitTerminal = (container, term, fitAddon, lastSize) => {
     if (container.clientWidth === 0 || container.clientHeight === 0)
         return lastSize;
-    fitAddon.fit();
-    const nextSize = { cols: term.cols, rows: term.rows };
+    const fallback = fallbackDimensions(container);
+    const proposed = fitAddon.proposeDimensions();
+    const nextSize = fallback ?? proposed;
+    if (!nextSize)
+        return lastSize;
+    if (term.cols !== nextSize.cols || term.rows !== nextSize.rows) {
+        term.resize(nextSize.cols, nextSize.rows);
+    }
     if (lastSize?.cols === nextSize.cols && lastSize.rows === nextSize.rows)
         return lastSize;
     return nextSize;
 };
-//# sourceMappingURL=fitTerminal.js.map