@cplieger/web-terminal-ui 8.4.0-dev.2 → 8.4.0-dev.3

package/README.md

@@ -14,7 +14,7 @@ web-terminal-ui is built for a shell or a coding agent served by web-terminal-en
 
 - One `createTerminal()` call builds the UI inside an element you provide. Four presets cover a single, a touch and two tabbed layouts.
 - On a touchscreen it adds a key bar with Tab, Esc, arrows, Enter and a sticky Ctrl, a long-press paste menu and iOS soft-keyboard handling.
-- Tabs show activity dots from the program's `OSC 9;4` progress reports and raise browser notifications. Two tabs can sit side by side.
+- Tabs show activity dots from the program's `OSC 9;4` progress reports and raise browser notifications. Two tabs can sit side by side. A full-page terminal gives each tab and each split its own page address, and names the browser tab after the active tab, followed by the page's own title: `fix build · Web Terminal`.
 - Native text selection, IME input and dictation work, and predictive echo hides latency.
 
 Consider [xterm.js](https://github.com/xtermjs/xterm.js) if you want a terminal component for any PTY backend, such as node-pty. It has an optional GPU-accelerated renderer and a set of addons, and VS Code uses it. To build a UI of your own on web-terminal-engine, depend on the engine alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "8.4.0-dev.2",
+  "version": "8.4.0-dev.3",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
   "license": "MPL-2.0",
@@ -33,8 +33,12 @@
     "test": "vitest --run",
     "test:watch": "vitest",
     "test:coverage": "vitest --run --coverage",
+    "test:browsers": "playwright install chromium",
+    "test:mutation": "stryker run",
     "lint:eslint": "eslint .",
     "lint:prettier": "prettier --check .",
+    "lint:css": "stylelint \"css/**/*.css\"",
+    "lint:html": "html-validate scaffold/index.html",
     "lint:fix": "eslint . --fix && prettier --write .",
     "lint:knip": "knip",
     "verify": "bash scripts/verify.sh"
@@ -58,7 +62,7 @@
     "eslint": "10.12.0",
     "fast-check": "4.10.2",
     "html-validate": "11.16.2",
-    "knip": "6.39.0",
+    "knip": "6.40.0",
     "playwright": "1.63.0",
     "prettier": "3.9.9",
     "stylelint": "17.16.0",

package/src/features/tabs/address-bar.ts

@@ -0,0 +1,138 @@
+/** How a fragment reached the page. A deep link (a fresh load, a typed fragment)
+ *  earns a notice when it names a tab that is gone; history and restore, which
+ *  replay entries the page itself wrote, are corrected silently. */
+export type RouteOrigin = "deeplink" | "history" | "restore";
+
+interface AddressBarOptions {
+  /** The fragment for what the page shows now (`#...`, or `""` for none), or null
+   *  while there is nothing to name, which leaves the address bar alone. */
+  readonly read: () => string | null;
+  /** Show what `fragment` names. Writes the page schedules from inside are
+   *  dropped; the address bar canonicalises once it returns. */
+  readonly apply: (fragment: string, origin: RouteOrigin) => void;
+}
+
+export interface AddressBar {
+  /** Write the current fragment after this task: a push adds a history entry, a
+   *  replace rewrites the current one, and a push wins when both are asked for.
+   *  Nothing is written before `start` or while applying, and a fragment already
+   *  the address bar's adds no entry (an unmarked one is only re-marked). */
+  schedule(mode: "push" | "replace"): void;
+  /** Where this page load came from, for the boot's notice decision. */
+  bootOrigin(): RouteOrigin;
+  /** Start answering navigation: replace the current entry with what is shown
+   *  (when `canonicalize`), then follow every fragment change. */
+  start(canonicalize: boolean): void;
+  dispose(): void;
+}
+
+// Marks a history entry this page wrote, so a back or forward onto it is told
+// from a fragment someone typed (whose entry carries no state).
+const ENTRY_MARK = "wtTabs";
+
+function isMarked(state: unknown): boolean {
+  return typeof state === "object" && state !== null && Object.hasOwn(state, ENTRY_MARK);
+}
+
+/** The page address as the tabs feature's: it writes the fragment, never the
+ *  path or the query, and it reacts to the fragment changing under it. */
+export function createAddressBar(win: Window, opts: AddressBarOptions): AddressBar {
+  let started = false;
+  let disposed = false;
+  let applying = 0;
+  let pending: "push" | "replace" | null = null;
+  let timer: number | null = null;
+  // The fragment last applied or written. popstate and hashchange both fire for
+  // one fragment navigation, and the second must not apply it again.
+  let known = win.location.hash;
+
+  function cancel(): void {
+    if (timer !== null) {
+      win.clearTimeout(timer);
+      timer = null;
+    }
+    pending = null;
+  }
+
+  function write(mode: "push" | "replace"): void {
+    const target = opts.read();
+    if (target === null) {
+      return;
+    }
+    const current = win.location.hash;
+    if (target === current && isMarked(win.history.state)) {
+      known = current;
+      return;
+    }
+    const url = new URL(win.location.href);
+    url.hash = target;
+    // An entry for a page with no addressable tab is not one worth going back to.
+    if (mode === "push" && target !== current && target !== "") {
+      win.history.pushState({ [ENTRY_MARK]: 1 }, "", url);
+    } else {
+      const prior: unknown = win.history.state;
+      const state = typeof prior === "object" && prior !== null ? { ...prior } : {};
+      win.history.replaceState({ ...state, [ENTRY_MARK]: 1 }, "", url);
+    }
+    known = win.location.hash;
+  }
+
+  function onNavigate(): void {
+    const fragment = win.location.hash;
+    if (fragment === known) {
+      return;
+    }
+    known = fragment;
+    const origin: RouteOrigin = isMarked(win.history.state) ? "history" : "deeplink";
+    cancel();
+    applying++;
+    try {
+      opts.apply(fragment, origin);
+    } finally {
+      applying--;
+    }
+    write("replace");
+  }
+
+  return {
+    schedule(mode) {
+      if (!started || disposed || applying > 0) {
+        return;
+      }
+      if (pending !== "push") {
+        pending = mode;
+      }
+      timer ??= win.setTimeout(() => {
+        timer = null;
+        const m = pending;
+        pending = null;
+        if (m !== null && !disposed) {
+          write(m);
+        }
+      }, 0);
+    },
+    bootOrigin() {
+      const entry: unknown = win.performance.getEntriesByType("navigation")[0];
+      const type =
+        typeof entry === "object" && entry !== null && "type" in entry ? entry.type : null;
+      return type === "reload" || type === "back_forward" ? "restore" : "deeplink";
+    },
+    start(canonicalize) {
+      if (started || disposed) {
+        return;
+      }
+      started = true;
+      if (canonicalize) {
+        write("replace");
+      }
+      win.addEventListener("popstate", onNavigate);
+      win.addEventListener("hashchange", onNavigate);
+    },
+    dispose() {
+      disposed = true;
+      cancel();
+      win.removeEventListener("popstate", onNavigate);
+      win.removeEventListener("hashchange", onNavigate);
+    },
+  };
+}

package/src/features/tabs/index.ts

@@ -19,6 +19,8 @@ import { createClickSwallow, placeMenuAt } from "../menu-position.js";
 import { snapToDevicePixels } from "./device-snap.js";
 import { centreChipLabels } from "./ink-centre.js";
 import { SWITCH_ANIMATIONS, SWITCH_CLASSES } from "./switch-anim.js";
+import { createAddressBar, type AddressBar, type RouteOrigin } from "./address-bar.js";
+import { formatTabRoute, parseTabAlias, parseTabRoute, type TabAlias } from "./route.js";
 import type { CueStatus, PaneLayout, SessionInfo, StatusRecord, Tab } from "./model.js";
 import {
   CUE_SEEN_KEY,
@@ -95,6 +97,19 @@ const DEFAULT_POLL_MS = 4000;
 // URL and NAVIGATES to it when no handler cancels the drop, so a bare session id
 // loaded /<session-id> on iPadOS. It also keeps the id out of the pasteboard.
 const TAB_DRAG_TYPE = "application/x-web-terminal-tab";
+const STALE_TAB_NOTICE = "That tab is no longer open";
+
+// Whether two records show the same tabs the same way; the handle is a device's
+// preference and does not count.
+function sameShownLayout(a: PaneLayout, b: PaneLayout | null): boolean {
+  return (
+    b !== null &&
+    a.left === b.left &&
+    a.right === b.right &&
+    a.open === b.open &&
+    a.selected === b.selected
+  );
+}
 
 /** The value a peer or a host reads through `ctx.use(tabs(...))`. `create` and
  *  `close` are server round trips and NEITHER rejects: a refusal is toasted and
@@ -781,6 +796,23 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // The record is read once and never written back by a read.
       let applyingRecord = false;
       let warnedLayout = false;
+      // The page address names the shown tabs only when the terminal owns the page.
+      const address: AddressBar | null =
+        ctx.shell.layoutMode === "viewport"
+          ? createAddressBar(win, { read: currentFragment, apply: applyFragment })
+          : null;
+      if (address !== null) {
+        ctx.defer(() => {
+          address.dispose();
+        });
+      }
+      // The page that owns its address is named after its active tab too.
+      const pageTitle = address === null ? null : ctx.shell.claimPageTitle();
+      if (pageTitle !== null) {
+        ctx.defer(() => {
+          pageTitle.release();
+        });
+      }
       // Twin of marotte static-src/tabs-drag.ts; when changing drag behaviour or its
       // constants, check the other app. Both judge a live drag's viewport against the
       // PRESS-time frame, so a move a hold lifted across still ends the drag.
@@ -1244,6 +1276,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // Every list mutation ends in syncChrome, so no path can forget the
         // out-of-page surfaces; the fold is idempotent and the sinks no-op.
         paintAttention();
+        const active = selectedId();
+        pageTitle?.set(tabList.find((t) => t.id === active)?.display ?? null);
       }
 
       // The percentage is deliberately NOT written into the document title: a page
@@ -1391,6 +1425,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
 
         const tab: Tab = {
           id: info.id,
+          alias: parseTabAlias(info.alias) ?? undefined,
           born: ++tabEpoch,
           title: info.title,
           pinnedTitle: info.pinnedTitle,
@@ -1650,6 +1685,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           ctx.shell.select(side);
         }
         scheduleLayoutWrite();
+        address?.schedule("push");
         // Only when the user is about to wait: a revisited tab with a warm store
         // paints from cache in one frame and must not flash a cue at every switch.
         if (
@@ -3066,6 +3102,15 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         if (rec.order !== undefined) {
           t.order = rec.order;
         }
+        // A changed alias renames the tab it already is, so the address it is
+        // shown under is rewritten in place rather than pushed.
+        if (rec.alias !== undefined) {
+          const alias = parseTabAlias(rec.alias) ?? undefined;
+          if (alias !== t.alias) {
+            t.alias = alias;
+            address?.schedule("replace");
+          }
+        }
         paintStatusDot(t.dot, rec.status, reports);
         // Only a PRESENT percentage updates the tab: the polling fallback lists
         // SessionInfo, which carries none, and reading absence as cleared would
@@ -3193,6 +3238,98 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           open: split.open,
         };
       }
+      // Own-field equality over the list, never a keyed object, so an alias such
+      // as `constructor` finds nothing rather than Object.prototype.
+      function tabByAlias(alias: TabAlias | null): Tab | undefined {
+        return alias === null ? undefined : tabList.find((t) => t.alias === alias);
+      }
+      /** The fragment naming what the panes show: `""` when a shown tab has no
+       *  alias, null while no pane shows a tab. */
+      function currentFragment(): string | null {
+        const left = shownIn("left");
+        const right = shownIn("right");
+        if (left === null && right === null) {
+          return null;
+        }
+        const aliasOf = (id: string | null): TabAlias | null | undefined =>
+          id === null ? null : tabList.find((t) => t.id === id)?.alias;
+        const l = aliasOf(left);
+        const r = aliasOf(right);
+        if (l === undefined || r === undefined) {
+          return "";
+        }
+        if (!ctx.shell.split.isOpen()) {
+          const tab = l ?? r;
+          return tab === null ? "" : formatTabRoute({ kind: "single", tab });
+        }
+        return formatTabRoute({ kind: "split", left: l, right: r });
+      }
+      /** Show what a fragment the user navigated to names. Only tabs already open
+       *  are shown: a URL never creates or closes a session, because a history
+       *  entry would otherwise resurrect a tab closed on another device. */
+      function applyFragment(fragment: string, origin: RouteOrigin): void {
+        const route = parseTabRoute(fragment);
+        if (route === null) {
+          return;
+        }
+        const [wantLeft, wantRight] =
+          route.kind === "single" ? [route.tab, null] : [route.left, route.right];
+        const left = tabByAlias(wantLeft);
+        const right = tabByAlias(wantRight);
+        if (
+          origin === "deeplink" &&
+          ((wantLeft !== null && !left) || (wantRight !== null && !right))
+        ) {
+          ctx.toast(STALE_TAB_NOTICE);
+        }
+        const first = left ?? right;
+        if (first === undefined) {
+          return;
+        }
+        const split = ctx.shell.split;
+        let wantSplit = route.kind === "split" && split.enabled;
+        if (wantSplit && !split.isOpen() && !split.canOpen()) {
+          wantSplit = false;
+          ctx.toast("Split view needs a wider window");
+        }
+        if (!wantSplit) {
+          if (split.isOpen()) {
+            // Closing keeps the selected pane's tab, so select the one wanted.
+            const at = sideOf(first.id);
+            if (at !== null) {
+              ctx.shell.select(at);
+            }
+            split.close();
+          }
+          if (sideOf(first.id) === null) {
+            showIn(ctx.shell.selected(), first.id, { keepSelection: true });
+          }
+          return;
+        }
+        if (!split.isOpen() && !split.open()) {
+          return;
+        }
+        const want: Record<PaneSide, Tab | undefined> = { left, right };
+        // The selected side goes first: filling the peer first could empty the
+        // selected pane (a tab moving across), and showIn then moves the
+        // selection to the peer. A moving tab is emptied from its old side by showIn.
+        const kept = ctx.shell.selected();
+        for (const side of [kept, otherSide(kept)]) {
+          const tab = want[side];
+          if (tab !== undefined && shownIn(side) !== tab.id) {
+            showIn(side, tab.id, { keepSelection: true });
+          }
+        }
+        for (const side of ["left", "right"] as const) {
+          if (want[side] === undefined && shownIn(side) !== null) {
+            ctx.shell.pane(side)?.clearActiveSession();
+          }
+        }
+        const sel = ctx.shell.selected();
+        if (shownIn(sel) === null && shownIn(otherSide(sel)) !== null) {
+          ctx.shell.select(otherSide(sel));
+        }
+      }
       async function writeLayout(layout: PaneLayout, retryOnStale: boolean): Promise<void> {
         try {
           await api.setLayout(layout);
@@ -3274,6 +3411,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           syncCatchups();
           syncChrome();
           scheduleLayoutWrite();
+          address?.schedule("push");
         }),
       );
       ctx.defer(ctx.shell.onSelectionChange(syncChrome));
@@ -4173,6 +4311,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // its bootShowedNothing gate), or the SSE snapshot would win this race on
         // every load.
         if (anyShown()) {
+          address?.start(listed.status === "fulfilled");
           return true;
         }
         // The record's sessions where they still exist, else the oldest LIVE tab:
@@ -4197,7 +4336,64 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           return true;
         };
         let shown = false;
-        if (layout?.open === true) {
+        // The address outranks the record when it names an open tab: it is the
+        // explicit instruction for this load. Read only with the server's list in
+        // hand, so a failed list never declares a tab gone.
+        const route =
+          address !== null && listed.status === "fulfilled"
+            ? parseTabRoute(win.location.hash)
+            : null;
+        if (route !== null && address !== null) {
+          const [wantLeft, wantRight] =
+            route.kind === "single" ? [route.tab, null] : [route.left, route.right];
+          const fromRoute = (alias: TabAlias | null): Tab | undefined => {
+            const tab = tabByAlias(alias);
+            return tab === undefined ? undefined : saved(tab.id);
+          };
+          const sides: Record<PaneSide, Tab | undefined> = {
+            left: fromRoute(wantLeft),
+            right: fromRoute(wantRight),
+          };
+          // Gone means absent from the list: an ended tab still in the row is
+          // refused here only because a boot never lands on a corpse.
+          const gone = (alias: TabAlias | null): boolean =>
+            alias !== null && tabByAlias(alias) === undefined;
+          if ((gone(wantLeft) || gone(wantRight)) && address.bootOrigin() === "deeplink") {
+            ctx.toast(STALE_TAB_NOTICE);
+          }
+          applyingRecord = true;
+          try {
+            if (route.kind === "split" && (sides.left || sides.right)) {
+              const record =
+                layout?.open === true &&
+                layout.left === (sides.left?.id ?? null) &&
+                layout.right === (sides.right?.id ?? null)
+                  ? layout.selected
+                  : null;
+              const selected: PaneSide =
+                record !== null && sides[record] ? record : sides.left ? "left" : "right";
+              if (ctx.shell.restoreSplit(layout?.handle ?? 0.5, selected)) {
+                for (const side of ["left", "right"] as const) {
+                  const tab = sides[side];
+                  if (tab) {
+                    shown = showAtBoot(side, tab) || shown;
+                  }
+                }
+              }
+            }
+            const only = sides.left ?? sides.right;
+            if (!shown && only) {
+              shown = showAtBoot(ctx.shell.targetFor(only.id), only);
+            }
+          } finally {
+            applyingRecord = false;
+          }
+          // The shared record follows the address this load was opened at.
+          if (shown && layout !== null && !sameShownLayout(layout, currentLayout())) {
+            scheduleLayoutWrite();
+          }
+        }
+        if (!shown && layout?.open === true) {
           const sides: Record<PaneSide, Tab | undefined> = {
             left: saved(layout.left),
             right: saved(layout.right),
@@ -4233,10 +4429,12 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         }
         if (!shown) {
           bootShowedNothing = true;
+          address?.start(false);
           return false;
         }
         syncChrome();
         focusInput();
+        address?.start(listed.status === "fulfilled");
         return true;
       };
       live = { resolveInitialLayout, shownIn, showIn };

package/src/features/tabs/model.ts

@@ -4,14 +4,18 @@ import type { LineStore } from "@cplieger/web-terminal-engine";
 import type { SessionInfo } from "@cplieger/web-terminal-engine";
 import type { ViewMemory } from "@cplieger/web-terminal-engine";
 import type { PaneSide, TabHandle } from "../../kernel/types.js";
+import type { TabAlias } from "./route.js";
 
 export type { SessionInfo };
 
 /** A status record as the tabs feature consumes it: the REST wire shape plus the
  *  percentage that exists only on the status STREAM. The polling fallback lists
- *  no percentage at all, which means "no information", not "cleared". */
+ *  no percentage at all, which means "no information", not "cleared". `alias` is
+ *  read as `unknown` because `parseTabAlias` validates it where it enters, and an
+ *  engine before 6.2 sends none. */
 export type StatusRecord = SessionInfo & {
   readonly progressValue?: number;
+  readonly alias?: unknown;
 };
 
 // The status vocabulary is module-private so a status's MEANING has one home:
@@ -392,6 +396,10 @@ export function orderedInsertIndex(current: readonly TabOrderKey[], incoming: Ta
 
 export interface Tab {
   id: string;
+  /** The session's public URL name from the server, or undefined when it sent
+   *  none (a server before engine 6.2) or one outside the alias grammar; such a
+   *  tab has no address of its own. */
+  alias: TabAlias | undefined;
   /** The local mutation epoch at which this tab was adopted. The list reconcile
    *  snapshots the counter BEFORE its GET and drops an unlisted tab only when
    *  the tab predates the snapshot: a tab born while the list was in flight is

package/src/features/tabs/route.ts

@@ -0,0 +1,65 @@
+/** A session alias that has passed `parseTabAlias`: 1 to 64 characters of
+ *  `[A-Za-z0-9_-]`, the grammar the engine's `SessionInfo.alias` documents. */
+export type TabAlias = string & {
+  // deadset:ignore DS1003 -- the brand only makes TabAlias nominal; nothing reads it
+  readonly __brand: "TabAlias";
+};
+
+// A fragment rather than a path: only a fragment edit navigates without a reload,
+// and a library mounted in someone else's page must not claim its path.
+/** What a fragment shows: one tab, or the split with a tab (or nothing) in each
+ *  pane. A split route names at least one side, and never one alias twice. */
+export type TabRoute =
+  | { readonly kind: "single"; readonly tab: TabAlias }
+  | { readonly kind: "split"; readonly left: TabAlias | null; readonly right: TabAlias | null };
+
+const ALIAS = /^[A-Za-z0-9_-]{1,64}$/;
+// Two maximal aliases and the separator.
+const MAX_ROUTE_LENGTH = 129;
+
+/** The value as an alias, or null for anything outside the grammar, including a
+ *  non-string. */
+export function parseTabAlias(raw: unknown): TabAlias | null {
+  return typeof raw === "string" && ALIAS.test(raw) ? (raw as TabAlias) : null;
+}
+
+/** Parse `location.hash` (with or without its `#`): `#<alias>` is one tab and
+ *  `#<left>,<right>` the split, either side possibly empty. Null for no fragment
+ *  and for any malformed one. Nothing is percent-decoded: the alias alphabet
+ *  needs no escaping, so an escape is malformed. */
+export function parseTabRoute(hash: string): TabRoute | null {
+  const body = hash.startsWith("#") ? hash.slice(1) : hash;
+  if (body === "" || body.length > MAX_ROUTE_LENGTH) {
+    return null;
+  }
+  const parts = body.split(",");
+  if (parts.length === 1) {
+    const tab = parseTabAlias(body);
+    return tab === null ? null : { kind: "single", tab };
+  }
+  if (parts.length !== 2) {
+    return null;
+  }
+  const [rawLeft = "", rawRight = ""] = parts;
+  const left = rawLeft === "" ? null : parseTabAlias(rawLeft);
+  const right = rawRight === "" ? null : parseTabAlias(rawRight);
+  if ((rawLeft !== "" && left === null) || (rawRight !== "" && right === null)) {
+    return null;
+  }
+  if ((left === null && right === null) || left === right) {
+    return null;
+  }
+  return { kind: "split", left, right };
+}
+
+/** The fragment for `route`, `#` included, or `""` (no fragment) for null. The
+ *  inverse of `parseTabRoute`. */
+export function formatTabRoute(route: TabRoute | null): string {
+  if (route === null) {
+    return "";
+  }
+  if (route.kind === "single") {
+    return `#${route.tab}`;
+  }
+  return `#${route.left ?? ""},${route.right ?? ""}`;
+}

package/src/kernel/shell.ts

@@ -394,18 +394,41 @@ function createShellInto(
   }
 
   let titleMark = "";
+  // The base a feature claimed through claimPageTitle; null text is the served title.
+  let claimedTitle: { text: string | null } | null = null;
+  // Suffixed from servedTitle, never from doc.title, so a repaint cannot stack it.
+  function claimedBase(text: string | null): string {
+    if (text === null || text === "") {
+      return servedTitle;
+    }
+    return servedTitle === "" ? text : `${text} · ${servedTitle}`;
+  }
+  let titleWritten = false;
   function paintTitle(): void {
-    const next =
-      titleMark + (slotAt(selectedSide)?.baseTitle ?? slots[0]?.baseTitle ?? servedTitle);
+    if (destroyed) {
+      return;
+    }
+    const base =
+      claimedTitle !== null
+        ? claimedBase(claimedTitle.text)
+        : (slotAt(selectedSide)?.baseTitle ?? slots[0]?.baseTitle ?? servedTitle);
+    const next = titleMark + base;
     // The title doubles as the browser-tab label and the bookmark name, and this
     // runs on every status sweep, so an unchanged assignment must not churn it.
     if (doc.title !== next) {
       doc.title = next;
+      titleWritten = true;
     }
   }
+  // Hands back the served title the terminal overwrote; paintTitle's destroyed
+  // guard stops teardown from repainting over it.
+  held.push(() => {
+    if (titleWritten) {
+      doc.title = servedTitle;
+    }
+  });
   const attentionSurfaces = new Set<AttentionSurface>();
-  // The badge is OS-level and the icon links outlive the terminal; the base
-  // title belongs to the document.
+  // The badge is OS-level and the icon links outlive the terminal.
   held.push(() => {
     for (const surface of attentionSurfaces) {
       surface.dispose();
@@ -816,6 +839,7 @@ function createShellInto(
     : disabledSplit();
   const shellContext: ShellContext = {
     root: shellRoot,
+    layoutMode,
     keyboard: {
       hardwareSeen: () => keyboardPresence.hardwareSeen(),
       likely: () => keyboardPresence.likely(),
@@ -851,6 +875,25 @@ function createShellInto(
     split,
     restoreSplit: (committed, selected) =>
       splitEnabled && isPaneSide(selected) && openSplitAt(committed, selected),
+    claimPageTitle() {
+      const claim: { text: string | null } = { text: null };
+      claimedTitle = claim;
+      paintTitle();
+      return {
+        set(text) {
+          claim.text = text;
+          if (claimedTitle === claim) {
+            paintTitle();
+          }
+        },
+        release() {
+          if (claimedTitle === claim) {
+            claimedTitle = null;
+            paintTitle();
+          }
+        },
+      };
+    },
   };
   // One row controller over every pane's tabpanel: a chip names the panel of the
   // pane showing it, or the one a click would fill.

package/src/kernel/types.ts

@@ -293,6 +293,9 @@ export interface KeyboardPresence {
 export interface ShellContext {
   /** The shell root; the pane root in the direct-root topology. */
   readonly root: HTMLElement;
+  /** The resolved `layout` option. Only a `"viewport"` terminal owns the page, so
+   *  only it may write the address bar. */
+  readonly layoutMode: "viewport" | "container";
   readonly keyboard: KeyboardPresence;
   /** Null while that side has no built kernel. */
   pane(side: PaneSide): PaneHandle | null;
@@ -322,9 +325,10 @@ export interface ShellContext {
   /** Bind the page's attention surfaces (the document-title prefix, the app
    *  badge, the icon links) and get the reporter that drives them. The terminal
    *  is the only writer of `document.title`: a program's OSC 0/2 title replaces
-   *  the base and keeps the prefix. The surfaces are restored when the page hides
-   *  and on destroy, and repainted on a back-forward cache restore. Keep the
-   *  report an AGGREGATE, since a page has one title over many sessions. */
+   *  the base (unless a feature holds `claimPageTitle`) and keeps the prefix.
+   *  The surfaces are restored when the page hides and on destroy (which also
+   *  restores the served title), and repainted on a back-forward cache restore.
+   *  Keep the report an AGGREGATE, since a page has one title over many sessions. */
   attention(opts: AttentionOptions): AttentionReporter;
   /** Subscribe to the server's session status stream at `path`. The terminal
    *  holds ONE stream per path for the page and fans it out, because the server
@@ -346,6 +350,12 @@ export interface ShellContext {
    *  shows a tab. False when the split is open already, `committedRatio` is not a
    *  share of 0 to 1, or `selected` is not a side. */
   restoreSplit(committedRatio: number, selected: PaneSide): boolean;
+  /** Take the document title's base over from the selected pane's program title.
+   *  `set(text)` names the page `<text> · <served title>` (the text alone when
+   *  the page was served untitled), `set(null)` or `set("")` shows the served
+   *  title, and `release()` hands the base back. The attention prefix is kept,
+   *  and a later claim replaces an earlier one. */
+  claimPageTitle(): { set(text: string | null): void; release(): void };
 }
 
 /** The inbound-wire + lifecycle events features can subscribe to via ctx.on.