@monotykamary/dsh-client-web 0.1.0-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/web/README.md
+README.md: 5eab78dc506873652dbb2559df922e9a24f5518e
+README.zh.md: d143c6e7ed22c9bedf89ac5724b4e6eb0ffd43dc

package/README.md

@@ -0,0 +1,25 @@
+# @monotykamary/dsh-client-web
+
+English | [中文](README.zh.md)
+
+Web boot kernel: `new AppWebEntry(el, seams?).run()` mounts the client through two stages. The module stage calls the Host-installed `window.__ModuleLoader__.create()` with `window.__DSH_BOOT__`, the shell's static modules, and any test transport override; the facade returns the constructed module system and parsed manifest after adopting parser-preloaded registrations. This package then prefetches the `immediately` tier. The plugin stage mounts the vendored Cordis Loader, injects that module system through the Loader's `internal` interface, creates every graph entry uniformly, and waits for every fiber to become ACTIVE. It then hands the marked boot DOM to the dynamic UI renderer's `ctx.uiRenderer.mount(el)` operation; the renderer hydrates that DOM before switching to the complete UI. The Host owns the graph, parser preloads, and facade; AppWebEntry does not know the bootstrap package id or parse the wire format.
+
+The boot page uses plain DOM and local CSS, so client-bundle and plugin-activation failures remain visible. Its fallback fonts and colors match the theme tokens that arrive during loading. Fiber updates retain one spinner node and grow its CSS arc as entries first become active; hydration preserves that node and its animation phase until the application commit. React mounting, slot rendering, application assembly, and browser-title projection live in [`ui-renderer`](../ui-renderer/README.md). The modules bundle caches its own materialized exports and provides the closed-over system when its ordinary graph entry activates; Cordis service waiting makes graph-row creation order independent from that activation.
+
+`PLATFORM_MODULES` (src/platform.ts) is the single source of truth for shell-seeded shared modules. Together with `PRELOADED_CLIENT_EXTERNALS`, it defines the implicit external baseline for every dynamic bundle; `dsh.client.external` adds only exact non-baseline requests.
+
+The optional override parameter `seams` forwards the module system's `loadBundle` transport override (`BootSeams`) for environments where external `<script>` execution cannot reach the page context; ordinary browser callers omit it.
+
+The shell owns browser-title projection. With a selected session carrying a durable title, it renders `<session title> — <existing HTML title>` and reacts to later title revisions; no selection or a selected untitled session preserves the existing title, and shell unmount restores it. The existing HTML title remains the configurable product suffix. The non-reloadable kernel observes its shell-owned `#root` child list and document visibility: when a visible root loses its required AppRoot child, it reloads the complete document immediately; a root emptied while hidden reloads when the document becomes visible, while a mounted child never triggers recovery.
+
+## Model Experience
+
+None, as the entry shell boots the browser plugin tree; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **The application waits for the full roster** — one failed entry keeps the framework-free boot page visible with a per-entry report; partial UI availability is not supported.

package/README.zh.md

@@ -0,0 +1,25 @@
+# @monotykamary/dsh-client-web
+
+[English](README.md) | 中文
+
+Web 启动内核：`new AppWebEntry(el, seams?).run()` 分两个阶段挂载客户端。模块阶段调用 Host 安装的 `window.__ModuleLoader__.create()`，传入 `window.__DSH_BOOT__`、外壳静态模块以及可选测试传输覆盖；facade 接纳 parser 预载的 registration 后返回构造好的模块系统与已解析 manifest。本包随后预取 `immediately` 层级。插件阶段挂载仓库内置的 Cordis Loader，通过 Loader 的 `internal` 接口注入该模块系统，统一创建全部图 entry，并等待每个 fiber 进入 ACTIVE。随后它把带标记的启动 DOM 交给动态 UI 渲染器的 `ctx.uiRenderer.mount(el)` 操作；渲染器先 hydrate 该 DOM，再切换到完整 UI。Graph、parser preload 与 facade 归 Host 所有；AppWebEntry 不感知 bootstrap package id，也不解析 wire 格式。
+
+启动页只使用原生 DOM 与本地 CSS，因此客户端 bundle 或插件激活失败时仍能显示。其回退字体和颜色与加载期间到达的主题 token 一致。fiber 更新会保留同一个 spinner 节点，并在 entry 首次进入 active 时增长其 CSS 圆弧；hydrate 会继续保留该节点及其动画相位，直到应用提交。React 挂载、slot 渲染、应用组装和浏览器标题投影位于 [`ui-renderer`](../ui-renderer/README.md)。Modules bundle 会缓存自身已物化导出，并在其普通图 entry 激活时提供闭包中的系统；Cordis service 等待使图 row 创建顺序不依赖该激活时点。
+
+`PLATFORM_MODULES`（src/platform.ts）是外壳播种共享模块的唯一事实来源。它与 `PRELOADED_CLIENT_EXTERNALS` 一起定义全部动态 bundle 的隐式 external 基座；`dsh.client.external` 只添加基座之外的精确请求。
+
+可选的覆盖参数 `seams` 会为外部 `<script>` 执行无法到达页面上下文的环境转发模块系统的 `loadBundle` 传输覆盖（`BootSeams`）；普通浏览器调用方省略此参数。
+
+外壳拥有浏览器标题投影。选中带有持久标题的会话时，它会渲染 `<session title> — <existing HTML title>` 并响应后续标题修订；未选择会话或选中无标题会话时，会保留现有标题；外壳卸载时恢复标题。现有 HTML 标题仍是可配置的产品后缀。不可 reload 的 kernel 会观察外壳自有 `#root` 的子项列表与 document visibility：当可见 root 丢失其必需 AppRoot 子项时，它会立即 reload 完整 document；隐藏时变空的 root 会在 document 变为可见时 reload，仍挂载的子项不会触发恢复。
+
+## 模型体验
+
+无。入口外壳负责启动浏览器插件树；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **应用会等待完整名册**：只要一个 entry 失败，不依赖框架的启动页就会保留并逐项报告；不支持部分 UI 可用。

package/lib/AppRoot.module.css

@@ -0,0 +1,66 @@
+/* Boot page styles are self-contained: the theme base stylesheets are linked
+   by the shell, but the loading page must render acceptably even before/without
+   them, so this file uses tokens with neutral fallbacks (the one sanctioned
+   fallback site — plugin packages must not do this). */
+
+.boot {
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: var(--dsw-alias-bg-base, #f9fafb);
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+}
+
+.wordmark {
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  color: var(--dsw-alias-label-primary, #0f1115);
+}
+
+.hint {
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-tertiary, #81858c);
+}
+
+.spinner {
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  border: 2px solid var(--dsw-alias-border-l2, rgb(0 0 0 / 10%));
+  border-top-color: var(--dsw-alias-brand-primary, #3964fe);
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+.failed {
+  max-width: 480px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.failedTitle {
+  font-size: 14px;
+  line-height: 22px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary, #0f1115);
+}
+
+.failedItem {
+  font-family: var(--ds-font-family-code, ui-monospace, 'SF Mono', Menlo, Consolas, 'Courier New');
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-secondary, #61666b);
+}

package/lib/base.css

@@ -0,0 +1,41 @@
+/* Shell-owned mount defaults. Theme tokens arrive with the ui-theme client
+ * plugin before the loader roster activates. */
+
+html,
+body,
+#root {
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  font-family: var(
+    --dsw-font-family,
+    -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    'PingFang SC',
+    'Hiragino Sans GB',
+    'Microsoft YaHei',
+    'Helvetica Neue',
+    Helvetica,
+    Arial,
+    sans-serif
+  );
+  /* Grayscale antialiasing over subpixel rendering: WebKit/Blink and the
+     Firefox macOS equivalent; other engines ignore both lines. */
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  color: var(--dsw-alias-label-primary, #0f1115);
+  background: var(--dsw-alias-bg-base, #fff);
+}
+
+/* Form controls don't inherit the body font (UA sheets pin their families —
+   Chrome buttons fall back to Arial, textareas to monospace), so the app
+   stack is re-applied to them explicitly, as upstream's global reset does. */
+button,
+input,
+select,
+textarea {
+  font-family: inherit;
+}

package/lib/index.js

@@ -0,0 +1,454 @@
+import * as ReactJsxRuntime from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import * as Cordis from "@monotykamary/cordis";
+import { Context } from "@monotykamary/cordis";
+import Loader from "@monotykamary/cordis-plugin-loader";
+import * as ReactDomClient from "react-dom/client";
+import { createRoot } from "react-dom/client";
+import * as ModulesClient from "@monotykamary/dsh-client-modules/client";
+import { ClientModuleSystem, parseBootManifest } from "@monotykamary/dsh-client-modules/client";
+import { bindSnapshotSelector, createSlotRenderer } from "@monotykamary/dsh-client-web-react";
+import * as React from "react";
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import css from "./AppRoot.module.css";
+import * as ReactDom from "react-dom";
+import * as UiSlots from "@monotykamary/dsh-client-ui-slots";
+import * as UiPrimitives from "@monotykamary/dsh-client-ui-primitives";
+import "./base.css";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region lib/types/DocumentTitle.js
+/**
+* Project the selected durable session title into the browser title and
+* restore the shell's original product title when unmounted.
+* @param props - selected session title projection.
+* @returns no rendered content.
+*/
+function DocumentTitle({ title }) {
+	const original = useRef(document.title);
+	useEffect(() => {
+		document.title = title === void 0 ? original.current : `${title} — ${original.current}`;
+		return () => {
+			document.title = original.current;
+		};
+	}, [title]);
+	return null;
+}
+//#endregion
+//#region lib/types/app.js
+/**
+* Build the renderApp factory the app-shell plugin provides to AppRoot.
+* @param deps - assembly inputs.
+* @returns factory producing the real UI tree (called once per AppRoot render after settled).
+*/
+function buildRenderApp(deps) {
+	const { ctx } = deps;
+	const sessions = ctx.get("sessions");
+	if (sessions === void 0) throw new Error("shell assembly: sessions service unavailable");
+	const useSessions = bindSnapshotSelector(sessions.list);
+	const SessionDocumentTitle = () => {
+		const title = useSessions((state) => {
+			const id = state.current;
+			return id === void 0 ? void 0 : state.byId[id]?.title;
+		});
+		return jsx(DocumentTitle, { ...title === void 0 ? {} : { title } });
+	};
+	return () => jsxs(Fragment, { children: [jsx(SessionDocumentTitle, {}), ctx.slots.renderSlot("root", {})] });
+}
+//#endregion
+//#region lib/types/app-shell.js
+var app_shell_exports = /* @__PURE__ */ __exportAll({
+	APP_SHELL_ID: () => APP_SHELL_ID,
+	apply: () => apply,
+	inject: () => inject,
+	name: () => name
+});
+/** Shell-owned pseudo entry id under which the host graph mounts this plugin. */
+const APP_SHELL_ID = "@monotykamary/dsh-client-app-shell";
+/** Cordis plugin name. */
+const name = "app-shell";
+/** Services required before shell assembly. */
+const inject = [
+	"slots",
+	"sessions",
+	"layout"
+];
+/** Installs the React renderer and exposes the assembled application.
+* @param ctx - Plugin context.
+*/
+function apply(ctx) {
+	ctx.slots.install(createSlotRenderer());
+	let renderApp;
+	ctx.reflect.provide("appShell", { renderApp: () => {
+		renderApp ??= buildRenderApp({ ctx });
+		return renderApp();
+	} });
+}
+//#endregion
+//#region lib/types/AppRoot.js
+/**
+* Shell root: boot loading page → (boot settled) → real UI in one switch.
+* Pure kernel component with zero plugin dependencies — before settled it may
+* only rely on itself (the fail-loud presentation must not depend on the
+* system whose failure it reports; the status/signal stores are kernel-own,
+* shell self-sufficiency rule); the real UI is produced by the
+* app-shell entry once every entry is active. A failed boot keeps the
+* loading page, lists the per-entry fiber states and the sweep report (fail
+* loud, no partial UI).
+*/
+/** Boot gate: loading page until the boot settles; failures stay here. */
+function AppRoot(props) {
+	const settled = useSyncExternalStore(props.settled.subscribe, props.settled.getSnapshot);
+	const status = useSyncExternalStore(props.status.subscribe, props.status.getSnapshot);
+	const error = useSyncExternalStore(props.error.subscribe, props.error.getSnapshot);
+	const failed = Object.entries(status).filter(([, s]) => s === "failed");
+	if (settled) return jsx(Fragment, { children: props.renderApp() });
+	const loud = error !== void 0 || failed.length > 0;
+	return jsx("div", {
+		className: css.boot,
+		children: jsxs("div", {
+			className: css.card,
+			children: [jsx("div", {
+				className: css.wordmark,
+				children: "HARNESS"
+			}), !loud ? jsxs(Fragment, { children: [jsx("div", { className: css.spinner }), jsx("div", {
+				className: css.hint,
+				children: "Loading plugins…"
+			})] }) : jsxs("div", {
+				className: css.failed,
+				children: [
+					jsx("div", {
+						className: css.failedTitle,
+						children: "Failed to load plugins"
+					}),
+					failed.map(([id]) => jsx("div", {
+						className: css.failedItem,
+						children: id
+					}, id)),
+					error !== void 0 && jsx("div", {
+						className: css.failedItem,
+						children: error
+					})
+				]
+			})]
+		})
+	});
+}
+//#endregion
+//#region lib/types/seed.js
+/**
+* Platform-singleton module-table. These are the ONLY entities the shell
+* shares into the frozen module table — fetch bundles resolve their externals
+* against exactly this set through the loader's require. Keys come from the
+* platform constant module ({@link ./platform.ts}, the single source
+* of truth with the tsdown client externals); values stay shell-static
+* imports so every bundle sees the same instance.
+*/
+/**
+* Build the static table handed to the module loader at boot.
+* @returns module specifier → exported entity (one entry per platform word).
+*/
+function getStaticModules() {
+	return {
+		"react": React,
+		"react/jsx-runtime": ReactJsxRuntime,
+		"react-dom": ReactDom,
+		"react-dom/client": ReactDomClient,
+		"@monotykamary/cordis": Cordis,
+		"@monotykamary/dsh-client-ui-slots": UiSlots,
+		"@monotykamary/dsh-client-ui-primitives": UiPrimitives
+	};
+}
+//#endregion
+//#region lib/types/loader-status.js
+/**
+* Value mirror of cordis's `FiberState` const enum: a const enum has no
+* runtime object to import (and esbuild-based pipelines cannot inline it
+* across modules), so these values mirror the pinned vendored definition
+* while retaining its type (same rationale as dsh-tool-cordis's mirror).
+*/
+const FIBER_STATE = {
+	PENDING: 0,
+	LOADING: 1,
+	ACTIVE: 2,
+	FAILED: 3,
+	DISPOSED: 4,
+	UNLOADING: 5
+};
+/** Label for each fiber state, keyed by member (inlining-safe — no reverse mapping). */
+const STATE_LABELS = {
+	[FIBER_STATE.PENDING]: "pending",
+	[FIBER_STATE.LOADING]: "loading",
+	[FIBER_STATE.ACTIVE]: "active",
+	[FIBER_STATE.FAILED]: "failed",
+	[FIBER_STATE.DISPOSED]: "disposed",
+	[FIBER_STATE.UNLOADING]: "unloading"
+};
+/**
+* Create a writable kernel signal.
+* @param init - initial value.
+* @returns the signal.
+*/
+function createSignal(init) {
+	let value = init;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		getSnapshot: () => value,
+		subscribe: (fn) => {
+			listeners.add(fn);
+			return () => {
+				listeners.delete(fn);
+			};
+		},
+		set: (next) => {
+			value = next;
+			for (const fn of [...listeners]) fn();
+		}
+	};
+}
+/**
+* Create the boot status store.
+* @returns the store (empty until the boot chain projects rows).
+*/
+function createLoaderStatusStore() {
+	let value = {};
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		getSnapshot: () => value,
+		subscribe: (fn) => {
+			listeners.add(fn);
+			return () => {
+				listeners.delete(fn);
+			};
+		},
+		set: (id, state) => {
+			value = {
+				...value,
+				[id]: state
+			};
+			for (const fn of [...listeners]) fn();
+		}
+	};
+}
+//#endregion
+//#region lib/types/boot.js
+/**
+* Web shell boot kernel — the face consumed by the apps/web entry. Everything
+* here is machinery that cannot itself be a loader entry, and none of it
+* value-imports a plugin package (shell self-sufficiency rule: the
+* loading page must work while — especially when — plugins fail). The one
+* sanctioned exception is the modules package (bootstrap
+* identity): the module system cannot arrive through itself, so its class
+* and its client-half wrapper are shell-bundled and the kernel adopts its
+* plugin entry once cordis is up.
+*
+* AppWebEntry.run(), module face first, then plugin face: parse
+* `window.__DSH_BOOT__` into the two-view BootManifest (wire boundary)
+* → build the module system over the module-view rows → render the loading
+* page → prefetch every `immediately` row in parallel with mounting the
+* vendored cordis Loader (`internal` contract injection BEFORE any entry exists —
+* the bare-import fallback in tree.import must never run in a browser) →
+* await the prefetch tier, THEN adopt the modules entry and create one
+* loader entry per plugin-view row plus the shell-own app-shell assembly
+* entry → loader.await() + a full fiber sweep (all ACTIVE, else fail
+* listing who/what/which service) → flip the settled signal so AppRoot
+* switches to the real UI in one pass.
+*
+* Entry creation waits for the whole immediately tier: materialization runs
+* synchronous cross-package require edges (e.g. locale → runtime/client) that
+* fiber inject waiting cannot protect — a bundle's factory must be
+* registered before any dependent entry materializes. Per-row prefetch
+* failures still resolve silently (the create-side import reloads and
+* owns the loud failure), so the barrier never turns one bad bundle into a
+* boot-wide fail-fast.
+*
+* Composition lives in the host graph; the shell makes zero composition
+* decisions (the app-shell assembly is itself a graph entry, the only
+* shell-own module registered with the module system).
+*/
+/**
+* Reload a visible document whose shell-owned React mount point has become empty.
+* @param element - shell mount point that must retain one AppRoot child after render.
+* @param reload - document reload action, replaceable by browser tests.
+* @returns disposer for the visibility listener.
+*/
+function installBlankRootRecovery(element, reload = () => {
+	globalThis.location.reload();
+}) {
+	const recover = () => {
+		if (document.visibilityState === "visible" && element.childElementCount === 0) reload();
+	};
+	const observer = new MutationObserver(recover);
+	observer.observe(element, { childList: true });
+	document.addEventListener("visibilitychange", recover);
+	return () => {
+		observer.disconnect();
+		document.removeEventListener("visibilitychange", recover);
+	};
+}
+/**
+* The modules package's own graph row id. The kernel adopts that entry
+* itself (its wrapper is statically registered — shell-bundled code, never
+* fetched), so the plugin-row loop must skip it: the vendored Group.create
+* does not deduplicate by name, and a second fiber would provide 'modules'
+* twice.
+*/
+const MODULES_ID = "@monotykamary/dsh-client-modules";
+/**
+* The web shell kernel: mounts the loading page into a DOM element and runs
+* the two-stage boot over the host graph. Fields hold only what must exist
+* before cordis does — the parsed manifest, the module system, and the
+* loading-page UI handles; everything else lives in plugins.
+*/
+var AppWebEntry = class {
+	el;
+	seams;
+	status = createLoaderStatusStore();
+	settled = createSignal(false);
+	error = createSignal(void 0);
+	ctx;
+	modules;
+	manifest;
+	root;
+	disposeBlankRootRecovery;
+	/**
+	* Hold the mount point; all work happens in {@link run}.
+	* @param el - mount point (the app's #root).
+	* @param seams - Optional module transport overrides for test environments.
+	*/
+	constructor(el, seams) {
+		this.el = el;
+		this.seams = seams;
+	}
+	/**
+	* Run the boot chain to settlement. Boot-chain failures resolve (not
+	* reject): the loading page stays up and renders the failure report (the
+	* fail-loud surface the kernel owns). Rejects only when the boot manifest
+	* is missing or malformed — there is nothing to boot against.
+	* @returns resolves once the UI settled or the failure report rendered.
+	*/
+	async run() {
+		this.manifest = parseBootManifest(globalThis.__DSH_BOOT__);
+		this.modules = new ClientModuleSystem({
+			modules: this.manifest.modules,
+			staticModules: getStaticModules(),
+			...this.seams
+		});
+		this.modules.registerStatic(APP_SHELL_ID, app_shell_exports);
+		this.modules.registerStatic(MODULES_ID, ModulesClient);
+		globalThis.__DSH_MODULES__ = this.modules;
+		this.root = createRoot(this.el);
+		this.root.render(jsx(AppRoot, {
+			settled: this.settled,
+			status: this.status,
+			error: this.error,
+			renderApp: () => {
+				const shell = this.ctx.get("appShell");
+				if (shell === void 0) throw new Error("web boot: appShell service missing after settled");
+				return shell.renderApp();
+			}
+		}));
+		this.disposeBlankRootRecovery = installBlankRootRecovery(this.el);
+		const prefetching = this.prefetchImmediateTier();
+		this.ctx = new Context();
+		try {
+			await this.runPluginBoot(prefetching);
+			this.settled.set(true);
+		} catch (reason) {
+			console.error(reason);
+			this.error.set(reason instanceof Error ? reason.message : String(reason));
+		}
+	}
+	/** Unmount the shell (loading page or settled UI). */
+	dispose() {
+		this.disposeBlankRootRecovery?.();
+		this.disposeBlankRootRecovery = void 0;
+		this.root?.unmount();
+	}
+	/** Prefetch the immediately tier (factory registration only; failures defer to the import path). */
+	async prefetchImmediateTier() {
+		await Promise.all(this.manifest.plugins.filter((row) => row.immediately).map((row) => this.modules.prefetch(row.id).catch(() => {})));
+	}
+	/** Plugin face: mount the Loader, inject the `internal` contract, adopt modules, create the graph entries, settle, sweep. */
+	async runPluginBoot(prefetching) {
+		const ctx = this.ctx;
+		await ctx.plugin(Loader);
+		const loader = ctx.loader;
+		loader.internal = this.modules;
+		ctx.on("internal/status", (fiber) => {
+			const entry = fiber.entry;
+			if (entry === void 0 || entry.fiber === void 0) return;
+			this.status.set(entry.options.name, STATE_LABELS[entry.fiber.state]);
+		});
+		await prefetching;
+		const rows = [
+			MODULES_ID,
+			...this.manifest.plugins.map((row) => row.id).filter((id) => id !== MODULES_ID),
+			APP_SHELL_ID
+		];
+		await Promise.all(rows.map(async (name) => {
+			this.status.set(name, "loading");
+			const id = await loader.create({ name });
+			if (loader.resolve(id).fiber === void 0) this.status.set(name, "failed");
+		}));
+		await loader.await();
+		this.assertEntriesActive();
+	}
+	/**
+	* Sweep every loader entry after the tree quiesced: an entry without a
+	* fiber failed its import; a fiber not ACTIVE is FAILED (apply threw) or
+	* PENDING (a required service never arrived — cordis inject waiting has no
+	* timeout, so this sweep is the fail-loud compensation).
+	*/
+	assertEntriesActive() {
+		const ctx = this.ctx;
+		const failures = [];
+		for (const entry of ctx.loader.entries()) {
+			const name = entry.options.name;
+			if (entry.fiber === void 0) {
+				failures.push(`${name}: import failed (see console for the import error)`);
+				continue;
+			}
+			const state = STATE_LABELS[entry.fiber.state];
+			if (state === "active") continue;
+			if (state === "pending") {
+				const missing = Object.keys(entry.fiber.inject).filter((service) => ctx.get(service) === void 0);
+				failures.push(`${name}: pending (waiting for service${missing.length === 1 ? "" : "s"}: ${missing.join(", ") || "unknown"})`);
+			} else failures.push(`${name}: ${state}`);
+		}
+		if (failures.length > 0) throw new Error(`web boot: ${String(failures.length)} entr${failures.length === 1 ? "y" : "ies"} did not activate\n${failures.join("\n")}`);
+	}
+};
+//#endregion
+//#region lib/types/platform.js
+/**
+* Shared browser platform modules. Seeding, bundling externals, and Vite
+* aliases consume this list so their module identities cannot drift.
+* @module @monotykamary/dsh-client-web/src/platform
+*/
+/** The module specifiers the shell shares into the frozen module table. */
+const PLATFORM_MODULES = [
+	"react",
+	"react/jsx-runtime",
+	"react-dom",
+	"react-dom/client",
+	"@monotykamary/cordis",
+	"@monotykamary/dsh-client-ui-slots",
+	"@monotykamary/dsh-client-ui-primitives"
+];
+/** Client-bundle specifiers whose factories the parser preloads before the shell starts. */
+const PRELOADED_CLIENT_EXTERNALS = ["@monotykamary/dsh-client-runtime/client"];
+//#endregion
+export { AppWebEntry, PLATFORM_MODULES, PRELOADED_CLIENT_EXTERNALS, getStaticModules };
+
+//# sourceMappingURL=index.js.map

package/lib/invariant.js

@@ -0,0 +1,27 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@monotykamary/dsh-client-web`.
+* @module @monotykamary/dsh-client-web/invariant
+*/
+const PACKAGE_NAME = "@monotykamary/dsh-client-web";
+/** Cordis companion plugin name. */
+const name = "client-web-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the vite entry shell — boot glue and module-table
+* seeding with no cordis events and no cross-plugin mutable state; the boot
+* chain (loading page → settled → one-flip UI) is asserted by the web smoke
+* e2e against the real carrier.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };
+
+//# sourceMappingURL=invariant.js.map

package/lib/types/AppRoot.d.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+import type { KernelSignal, LoaderStatus } from './loader-status.ts';
+/** AppRoot props: settled signal, fiber-state projection feed, boot failure report, deferred real-UI factory. */
+export interface AppRootProps {
+    /** True once the boot chain settled (loader quiesced + all entries ACTIVE); the boot closure flips it. */
+    settled: KernelSignal<boolean>;
+    /** Per-entry fiber-state projection store (drives loading/failed rendering). */
+    status: KernelSignal<LoaderStatus>;
+    /** Boot failure report (the settle rejection message); undefined while loading or after success. */
+    error: KernelSignal<string | undefined>;
+    /** Builds the real UI; called only after settled. */
+    renderApp: () => ReactNode;
+}
+/** Boot gate: loading page until the boot settles; failures stay here. */
+export declare function AppRoot(props: AppRootProps): import("react").JSX.Element;
+//# sourceMappingURL=AppRoot.d.ts.map

package/lib/types/DocumentTitle.d.ts

@@ -0,0 +1,13 @@
+/** Props for the shell-owned browser title projection. */
+export interface DocumentTitleProps {
+    /** Durable title of the selected session, or undefined for the product title. */
+    title?: string;
+}
+/**
+ * Project the selected durable session title into the browser title and
+ * restore the shell's original product title when unmounted.
+ * @param props - selected session title projection.
+ * @returns no rendered content.
+ */
+export declare function DocumentTitle({ title }: DocumentTitleProps): null;
+//# sourceMappingURL=DocumentTitle.d.ts.map

package/lib/types/app-shell.d.ts

@@ -0,0 +1,28 @@
+/**
+ * App-shell assembly plugin. Its pseudo package id exists only in the host
+ * graph and shell registry; there is no npm package behind it.
+ */
+import type { ReactNode } from 'react';
+import type { Context } from '@monotykamary/cordis';
+/** Shell-owned pseudo entry id under which the host graph mounts this plugin. */
+export declare const APP_SHELL_ID = "@monotykamary/dsh-client-app-shell";
+/** The assembled-UI face AppRoot renders once the boot settles. */
+export interface AppShellService {
+    /** Build (once) and render the real UI tree. */
+    renderApp: () => ReactNode;
+}
+declare module '@monotykamary/cordis' {
+    interface Context {
+        /** The shell assembly face, provided by the app-shell entry once its inject set is active. */
+        appShell: AppShellService;
+    }
+}
+/** Cordis plugin name. */
+export declare const name = "app-shell";
+/** Services required before shell assembly. */
+export declare const inject: string[];
+/** Installs the React renderer and exposes the assembled application.
+ * @param ctx - Plugin context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=app-shell.d.ts.map

package/lib/types/app.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Real-UI assembly closure, invoked by the app-shell plugin once its inject
+ * set is active: the whole layout tree hangs off the built-in 'root' slot
+ * (ui-layout registers AppFrame there and renders the child slots
+ * internally) — the shell's render is the one ctx-level renderSlot call in
+ * the program.
+ */
+import type { ReactNode } from 'react';
+import type { Context } from '@monotykamary/cordis';
+/** Assembly inputs: the active app-shell plugin ctx (slots/sessions/layout services provided). */
+export interface AssemblyDeps {
+    /** Client context with the assembly's inject set active. */
+    ctx: Context;
+}
+/**
+ * Build the renderApp factory the app-shell plugin provides to AppRoot.
+ * @param deps - assembly inputs.
+ * @returns factory producing the real UI tree (called once per AppRoot render after settled).
+ */
+export declare function buildRenderApp(deps: AssemblyDeps): () => ReactNode;
+//# sourceMappingURL=app.d.ts.map

package/lib/types/boot-page.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Framework-free boot page and failure report. It remains available when a
+ * client plugin fails because React arrives only with the UI renderer.
+ * @module @monotykamary/dsh-client-web/src/boot-page
+ */
+import type { LoaderEntryState } from './loader-status.ts';
+/** Kernel-owned page mounted below the application's root element. */
+export declare class BootPage {
+    private readonly root;
+    private readonly card;
+    private readonly wordmark;
+    private readonly spinner;
+    private readonly hint;
+    private readonly states;
+    private readonly active;
+    private total;
+    private failure;
+    /**
+     * Build and attach the boot page.
+     * @param container - Application mount point.
+     */
+    constructor(container: HTMLElement);
+    /**
+     * Set the number of loader entries represented by the progress arc.
+     * @param total - Complete boot roster size.
+     */
+    setTotal(total: number): void;
+    /**
+     * Project one loader entry's fiber state.
+     * @param id - Loader entry name.
+     * @param state - Projected fiber state.
+     */
+    setState(id: string, state: LoaderEntryState): void;
+    /**
+     * Display the boot failure report.
+     * @param message - Failure report text.
+     */
+    fail(message: string): void;
+    /** Detach the page before or after the UI renderer takes the mount point. */
+    dispose(): void;
+    /** Redraw the state-dependent content below the wordmark. */
+    private render;
+    /** Grow the rotating arc monotonically as loader entries activate. */
+    private updateProgress;
+}
+//# sourceMappingURL=boot-page.d.ts.map

package/lib/types/boot.d.ts

@@ -0,0 +1,57 @@
+import { type ClientModuleSystemOptions } from '@monotykamary/dsh-client-modules/client';
+import './base.css';
+/** Module transport hook the shell passes through (jsdom tests replace the <script> path). */
+export type BootSeams = Pick<ClientModuleSystemOptions, 'loadBundle'>;
+/**
+ * Reload a visible document whose shell-owned React mount point has become empty.
+ * @param element - shell mount point that must retain one AppRoot child after render.
+ * @param reload - document reload action, replaceable by browser tests.
+ * @returns disposer for the visibility listener.
+ */
+export declare function installBlankRootRecovery(element: HTMLElement, reload?: () => void): () => void;
+/**
+ * The web shell kernel: mounts the loading page into a DOM element and runs
+ * the two-stage boot over the host graph. Fields hold only what must exist
+ * before cordis does — the parsed manifest, the module system, and the
+ * loading-page UI handles; everything else lives in plugins.
+ */
+export declare class AppWebEntry {
+    private readonly el;
+    private readonly seams;
+    private readonly status;
+    private readonly settled;
+    private readonly error;
+    private ctx;
+    private modules;
+    private manifest;
+    private root;
+    private disposeBlankRootRecovery;
+    /**
+     * Hold the mount point; all work happens in {@link run}.
+     * @param el - mount point (the app's #root).
+     * @param seams - Optional module transport overrides for test environments.
+     */
+    constructor(el: HTMLElement, seams?: BootSeams);
+    /**
+     * Run the boot chain to settlement. Boot-chain failures resolve (not
+     * reject): the loading page stays up and renders the failure report (the
+     * fail-loud surface the kernel owns). Rejects only when the boot manifest
+     * is missing or malformed — there is nothing to boot against.
+     * @returns resolves once the UI settled or the failure report rendered.
+     */
+    run(): Promise<void>;
+    /** Unmount the shell (loading page or settled UI). */
+    dispose(): void;
+    /** Prefetch the immediately tier (factory registration only; failures defer to the import path). */
+    private prefetchImmediateTier;
+    /** Plugin face: mount the Loader, inject the `internal` contract, adopt modules, create the graph entries, settle, sweep. */
+    private runPluginBoot;
+    /**
+     * Sweep every loader entry after the tree quiesced: an entry without a
+     * fiber failed its import; a fiber not ACTIVE is FAILED (apply threw) or
+     * PENDING (a required service never arrived — cordis inject waiting has no
+     * timeout, so this sweep is the fail-loud compensation).
+     */
+    private assertEntriesActive;
+}
+//# sourceMappingURL=boot.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Web shell library entry. The shell's product is {@link AppWebEntry} —
+ * apps/web's Vite entry runs it against #root. The boot page and fiber-state
+ * projection remain internal; the static module table and its platform words
+ * form the package's build-time contract.
+ * @module @monotykamary/dsh-client-web
+ */
+export { AppWebEntry, type BootSeams } from './boot.ts';
+export { getStaticModules } from './seed.ts';
+export { PLATFORM_MODULES, PRELOADED_CLIENT_EXTERNALS, type PlatformModule } from './platform.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@monotykamary/dsh-client-web`.
+ * @module @monotykamary/dsh-client-web/invariant
+ */
+import type { Context } from '@monotykamary/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-web-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/loader-status.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Fiber-state projection vocabulary and the kernel-owned status store for the
+ * boot loading page. The status AppRoot renders is a projection of the real
+ * cordis fiber states (display the truth, not a retelling) — the boot chain
+ * subscribes `internal/status` and recomputes one row per loader entry.
+ *
+ * The store is hand-rolled here because of the shell self-sufficiency rule:
+ * the snapshot-store machinery lives in the runtime PLUGIN
+ * package, and the shell kernel must not value-import any plugin package —
+ * the loading page has to work while (and especially when) plugins fail.
+ * @module @monotykamary/dsh-client-web/src/loader-status
+ */
+import type { FiberState } from '@monotykamary/cordis';
+/**
+ * Value mirror of cordis's `FiberState` const enum: a const enum has no
+ * runtime object to import (and esbuild-based pipelines cannot inline it
+ * across modules), so these values mirror the pinned vendored definition
+ * while retaining its type (same rationale as dsh-tool-cordis's mirror).
+ */
+export declare const FIBER_STATE: {
+    readonly PENDING: FiberState.PENDING;
+    readonly LOADING: FiberState.LOADING;
+    readonly ACTIVE: FiberState.ACTIVE;
+    readonly FAILED: FiberState.FAILED;
+    readonly DISPOSED: FiberState.DISPOSED;
+    readonly UNLOADING: FiberState.UNLOADING;
+};
+/** One entry's projected state label (lower-case face of {@link FiberState}). */
+export type LoaderEntryState = 'pending' | 'loading' | 'active' | 'failed' | 'disposed' | 'unloading';
+/** Label for each fiber state, keyed by member (inlining-safe — no reverse mapping). */
+export declare const STATE_LABELS: Record<FiberState, LoaderEntryState>;
+/** Per-entry state projection (AppRoot's status feed), keyed by entry name. */
+export type LoaderStatus = Record<string, LoaderEntryState>;
+/** Minimal observable snapshot the kernel components consume (useSyncExternalStore shape). */
+export interface KernelSignal<T> {
+    /** Current value (stable reference between changes). */
+    getSnapshot: () => T;
+    /**
+     * Subscribe to changes.
+     * @param fn - change listener.
+     * @returns the unsubscribe disposer.
+     */
+    subscribe: (fn: () => void) => () => void;
+}
+/** Writable one-value signal (settled flag, boot failure report). */
+export interface KernelValueSignal<T> extends KernelSignal<T> {
+    /**
+     * Publish a new value and notify subscribers.
+     * @param next - the new value.
+     */
+    set: (next: T) => void;
+}
+/**
+ * Create a writable kernel signal.
+ * @param init - initial value.
+ * @returns the signal.
+ */
+export declare function createSignal<T>(init: T): KernelValueSignal<T>;
+/** The boot status store: per-entry rows over a {@link KernelSignal} face. */
+export interface LoaderStatusStore extends KernelSignal<LoaderStatus> {
+    /**
+     * Project one entry's state (copy-on-write so getSnapshot references only
+     * change on writes — useSyncExternalStore contract).
+     * @param id - entry name.
+     * @param state - projected fiber state.
+     */
+    set: (id: string, state: LoaderEntryState) => void;
+}
+/**
+ * Create the boot status store.
+ * @returns the store (empty until the boot chain projects rows).
+ */
+export declare function createLoaderStatusStore(): LoaderStatusStore;
+//# sourceMappingURL=loader-status.d.ts.map

package/lib/types/platform.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared browser platform modules. Seeding, bundling externals, and Vite
+ * aliases consume this list so their module identities cannot drift.
+ * @module @monotykamary/dsh-client-web/src/platform
+ */
+/** The module specifiers the shell shares into the frozen module table. */
+export declare const PLATFORM_MODULES: readonly ["react", "react/jsx-runtime", "react-dom", "react-dom/client", "@monotykamary/cordis", "@monotykamary/dsh-client-ui-slots", "@monotykamary/dsh-client-ui-primitives"];
+/** Client-bundle specifiers whose factories the parser preloads before the shell starts. */
+export declare const PRELOADED_CLIENT_EXTERNALS: readonly ["@monotykamary/dsh-client-runtime/client"];
+/** One platform module specifier (a seed-table key). */
+export type PlatformModule = (typeof PLATFORM_MODULES)[number];
+//# sourceMappingURL=platform.d.ts.map

package/lib/types/seed.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Build the static table handed to the module loader at boot.
+ * @returns module specifier → exported entity (one entry per platform word).
+ */
+export declare function getStaticModules(): Record<string, unknown>;
+//# sourceMappingURL=seed.d.ts.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@monotykamary/dsh-client-web",
+  "description": "Web shell kernel: bootWebShell (module system holding + seed table + two-stage boot + AppRoot gate + app-shell assembly entry), consumed by the apps/web vite entry",
+  "version": "0.1.0-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/web"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^6.0.3",
+    "@monotykamary/cordis-plugin-loader": "^1.0.2",
+    "@monotykamary/dsh-client-ui-primitives": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-ui-slots": "^0.1.0-rc.10",
+    "@monotykamary/dsh-invariants": "^0.1.0-rc.10",
+    "@monotykamary/cordis": "^4.0.1",
+    "@monotykamary/dsh-client-test-runtime": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-runtime": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-modules": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-ui-renderer": "^0.1.0-rc.10"
+  },
+  "peerDependencies": {
+    "@monotykamary/dsh-invariants": "^0.1.0-rc.10",
+    "@monotykamary/cordis": "^4.0.1",
+    "@monotykamary/cordis-plugin-loader": "^1.0.2"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/**/*.css",
+    "lib/types/**/*.d.ts"
+  ],
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@monotykamary/dsh-client-ui-primitives": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-ui-attachment": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-ui-slots": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-ui-theme": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-modules": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-schema-form": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-web-react": "^0.1.0-rc.10"
+  }
+}