@snap-rail/framework-shadcn 0.0.0-stage → 0.2.2

package/lib/semantic.js

@@ -0,0 +1,104 @@
+import "@snap-rail/cordis";
+//#region lib/types/slots.js
+/** Stable semantic slot names shared by every layout implementation. */
+const UI_SLOT_IDS = {
+	layout: "shell.layout",
+	titlebar: "shell.titlebar",
+	titlebarActions: "shell.titlebar.actions",
+	menu: "shell.menu",
+	sidebar: "shell.sidebar",
+	main: "shell.main",
+	view: "shell.view",
+	statusbar: "shell.statusbar",
+	overlay: "shell.overlay",
+	/**
+	* The floating ball (`shell.ball`): the auxiliary-surface face. A package
+	* that ships a `ball` client bundle occupies it; when nobody does, the
+	* surface renders the framework's default (an orb that summons the operator
+	* window). `single`, like every other "one tenant paints this window" slot.
+	*/
+	ball: "shell.ball"
+};
+/** Runtime set used by manifest/semantic validation as well as TypeScript. */
+const STANDARD_UI_SLOT_IDS = new Set(Object.values(UI_SLOT_IDS));
+/** A custom slot is owned by a publisher and a local slot name. */
+const CUSTOM_UI_SLOT_PATTERN = /^custom:[a-z0-9][a-z0-9-]*\.[a-z0-9][a-z0-9-]*$/;
+/** Check the public slot naming contract at runtime. */
+function isValidUiSlotId(value) {
+	return STANDARD_UI_SLOT_IDS.has(value) || CUSTOM_UI_SLOT_PATTERN.test(value);
+}
+/**
+* The mode table for the standard slots — the framework owns it.
+*
+* `titlebar` and `main` are `single`: exactly one tenant renders (a skin or
+* replacement displaces the default and falls back on unload). `layout`
+* stays `stack` on purpose — the settings dialog is a permanent overlay
+* occupant beside the active layout, and the fallback shell yields by
+* counting; every other slot collects contributions.
+*/
+const UI_SLOT_MODES = {
+	[UI_SLOT_IDS.layout]: "stack",
+	[UI_SLOT_IDS.titlebar]: "single",
+	[UI_SLOT_IDS.titlebarActions]: "stack",
+	[UI_SLOT_IDS.menu]: "stack",
+	[UI_SLOT_IDS.sidebar]: "stack",
+	[UI_SLOT_IDS.main]: "single",
+	[UI_SLOT_IDS.view]: "stack",
+	[UI_SLOT_IDS.statusbar]: "stack",
+	[UI_SLOT_IDS.overlay]: "stack",
+	[UI_SLOT_IDS.ball]: "single"
+};
+new Map(Object.entries(UI_SLOT_MODES));
+//#endregion
+//#region lib/types/semantic.js
+/** Mount the semantic contribution registry on top of the slot registry. */
+const semanticPlugin = {
+	name: "framework semantic ui contract",
+	inject: ["uiSlots"],
+	apply(ctx) {
+		const slots = ctx.uiSlots;
+		const views = /* @__PURE__ */ new Map();
+		const layouts = /* @__PURE__ */ new Map();
+		const navigation = /* @__PURE__ */ new Map();
+		let sequence = 0;
+		const ordered = (values) => [...values].sort((a, b) => a.value.order - b.value.order || a.seq - b.seq).map((item) => item.value);
+		const register = (table, caller, id, value, disposeSlot) => {
+			table.set(id, {
+				value,
+				seq: sequence++
+			});
+			const kind = table === views ? "view" : table === layouts ? "layout" : "navigation";
+			ctx.emit("ui/semantic-changed", kind);
+			const remove = () => {
+				if (!table.delete(id)) return;
+				disposeSlot?.();
+				ctx.emit("ui/semantic-changed", kind);
+			};
+			caller.effect(() => remove);
+			return remove;
+		};
+		const validateSlot = (kind, id, slot) => {
+			if (!isValidUiSlotId(slot)) ctx.emit("ui/semantic-invalid", kind, id, slot);
+		};
+		ctx.provide("uiContract", {
+			registerView(caller, contribution) {
+				validateSlot("view", contribution.id, contribution.slot);
+				const disposeSlot = slots.register(caller, contribution.slot, contribution);
+				return register(views, caller, contribution.id, contribution, disposeSlot);
+			},
+			registerLayout(caller, contribution) {
+				for (const slot of contribution.slots) validateSlot("layout", contribution.id, slot);
+				const disposeSlot = slots.register(caller, UI_SLOT_IDS.layout, contribution);
+				return register(layouts, caller, contribution.id, contribution, disposeSlot);
+			},
+			registerNavigation(caller, contribution) {
+				return register(navigation, caller, contribution.id, contribution);
+			},
+			listViews: () => ordered(views.values()),
+			listLayouts: () => ordered(layouts.values()),
+			listNavigation: () => ordered(navigation.values())
+		});
+	}
+};
+//#endregion
+export { semanticPlugin as default };

package/lib/session.js

@@ -0,0 +1,48 @@
+import { SESSION_OPERATOR_KEY, settingsChangedSchema } from "@snap-rail/station-rpc/contract";
+import "@snap-rail/cordis";
+import { subscribeFrame } from "@snap-rail/connection";
+//#region lib/types/session.js
+/** Mounts the `ctx.session` mirror; state lives in the apply closure. */
+const sessionPlugin = {
+	name: "client-session",
+	inject: ["client"],
+	apply(ctx) {
+		const { link } = ctx.client;
+		let operator = null;
+		let restored = false;
+		const sync = (next) => {
+			operator = next;
+			ctx.emit("session/changed", operator);
+		};
+		link.call("session.current", {}).then((result) => {
+			if (result.ok) sync(result.value.operator);
+		}).catch(() => {}).finally(() => {
+			restored = true;
+			ctx.emit("session/restored");
+		});
+		ctx.effect(() => subscribeFrame(link, "settings/changed", settingsChangedSchema, (change) => {
+			if (change.key !== SESSION_OPERATOR_KEY) return;
+			link.call("session.current", {}).then((result) => {
+				if (result.ok && result.value.operator !== operator) sync(result.value.operator);
+			}).catch(() => {});
+		}));
+		ctx.provide("session", {
+			current: () => operator,
+			restored: () => restored,
+			async login(raw) {
+				const trimmed = raw.trim();
+				if (trimmed === "") throw new Error("工号不能为空");
+				const result = await link.call("session.login", { operator: trimmed });
+				if (!result.ok) throw new Error(`登录失败（${result.error.code}）`);
+				sync(trimmed);
+			},
+			async logout() {
+				const result = await link.call("session.logout", {});
+				if (!result.ok) throw new Error(`退出失败（${result.error.code}）`);
+				sync(null);
+			}
+		});
+	}
+};
+//#endregion
+export { sessionPlugin as default };

package/lib/settings-pages.js

@@ -0,0 +1,68 @@
+import "@snap-rail/cordis";
+//#region lib/types/settings-pages.js
+/**
+* Mounts the `ctx.settingsPages` registry. All state lives in
+* construction-time closures: traceable context proxies rebind `this` on
+* every method access, so `this`-reached state cannot back a service here
+* (the uiSlots lesson).
+*/
+const settingsPlugin = {
+	name: "client-settings",
+	apply(ctx) {
+		const pages = /* @__PURE__ */ new Map();
+		let nextSeq = 0;
+		let open = false;
+		let requestedId;
+		const firstId = () => [...pages.values()].sort((a, b) => a.def.order - b.def.order || a.seq - b.seq)[0]?.def.id;
+		const activeId = () => {
+			if (!open) return void 0;
+			if (requestedId !== void 0 && pages.has(requestedId)) return requestedId;
+			return firstId();
+		};
+		const openDialog = (id) => {
+			if (id !== void 0) requestedId = id;
+			if (open && id === void 0) return;
+			open = true;
+			ctx.emit("settings/open-changed");
+		};
+		const closeDialog = () => {
+			if (!open) return;
+			open = false;
+			ctx.emit("settings/open-changed");
+		};
+		ctx.provide("settingsPages", {
+			list() {
+				const current = activeId();
+				return [...pages.values()].sort((a, b) => a.def.order - b.def.order || a.seq - b.seq).map(({ def }) => ({
+					...def,
+					active: def.id === current
+				}));
+			},
+			register(caller, def) {
+				const replaced = pages.has(def.id);
+				pages.set(def.id, {
+					def,
+					seq: nextSeq++
+				});
+				ctx.emit(replaced ? "settings/open-changed" : "settings/pages-changed");
+				const remove = () => {
+					if (pages.delete(def.id)) ctx.emit("settings/pages-changed");
+				};
+				caller.effect(() => remove);
+				return remove;
+			},
+			open: openDialog,
+			close: closeDialog,
+			toggle() {
+				if (open) closeDialog();
+				else openDialog();
+			},
+			isOpen() {
+				return open;
+			},
+			active: activeId
+		});
+	}
+};
+//#endregion
+export { settingsPlugin as default };

package/lib/slots.js

@@ -0,0 +1,103 @@
+import "@snap-rail/cordis";
+//#region lib/types/slots.js
+/** Stable semantic slot names shared by every layout implementation. */
+const UI_SLOT_IDS = {
+	layout: "shell.layout",
+	titlebar: "shell.titlebar",
+	titlebarActions: "shell.titlebar.actions",
+	menu: "shell.menu",
+	sidebar: "shell.sidebar",
+	main: "shell.main",
+	view: "shell.view",
+	statusbar: "shell.statusbar",
+	overlay: "shell.overlay",
+	/**
+	* The floating ball (`shell.ball`): the auxiliary-surface face. A package
+	* that ships a `ball` client bundle occupies it; when nobody does, the
+	* surface renders the framework's default (an orb that summons the operator
+	* window). `single`, like every other "one tenant paints this window" slot.
+	*/
+	ball: "shell.ball"
+};
+/** Runtime set used by manifest/semantic validation as well as TypeScript. */
+const STANDARD_UI_SLOT_IDS = new Set(Object.values(UI_SLOT_IDS));
+/** A custom slot is owned by a publisher and a local slot name. */
+const CUSTOM_UI_SLOT_PATTERN = /^custom:[a-z0-9][a-z0-9-]*\.[a-z0-9][a-z0-9-]*$/;
+/** Check the public slot naming contract at runtime. */
+function isValidUiSlotId(value) {
+	return STANDARD_UI_SLOT_IDS.has(value) || CUSTOM_UI_SLOT_PATTERN.test(value);
+}
+/**
+* The mode table for the standard slots — the framework owns it.
+*
+* `titlebar` and `main` are `single`: exactly one tenant renders (a skin or
+* replacement displaces the default and falls back on unload). `layout`
+* stays `stack` on purpose — the settings dialog is a permanent overlay
+* occupant beside the active layout, and the fallback shell yields by
+* counting; every other slot collects contributions.
+*/
+const UI_SLOT_MODES = {
+	[UI_SLOT_IDS.layout]: "stack",
+	[UI_SLOT_IDS.titlebar]: "single",
+	[UI_SLOT_IDS.titlebarActions]: "stack",
+	[UI_SLOT_IDS.menu]: "stack",
+	[UI_SLOT_IDS.sidebar]: "stack",
+	[UI_SLOT_IDS.main]: "single",
+	[UI_SLOT_IDS.view]: "stack",
+	[UI_SLOT_IDS.statusbar]: "stack",
+	[UI_SLOT_IDS.overlay]: "stack",
+	[UI_SLOT_IDS.ball]: "single"
+};
+const STANDARD_SLOT_MODES = new Map(Object.entries(UI_SLOT_MODES));
+/** The occupancy mode of a slot; `custom:*` slots are `stack`. */
+function slotModeOf(slot) {
+	return STANDARD_SLOT_MODES.get(slot) ?? "stack";
+}
+/** Mounts the `ctx.uiSlots` registry.
+*
+* The facade binds everything to construction-time closures: traceable
+* context proxies rebind `this` on every method access, so `this`-reached
+* state cannot back a service here (mirrors the field seam's external core).
+*/
+const slotsPlugin = {
+	name: "framework slots",
+	apply(ctx) {
+		const slots = /* @__PURE__ */ new Map();
+		const entryOf = (slot) => {
+			let entry = slots.get(slot);
+			if (entry === void 0) {
+				entry = {
+					occupants: /* @__PURE__ */ new Map(),
+					nextSeq: 0
+				};
+				slots.set(slot, entry);
+			}
+			return entry;
+		};
+		ctx.provide("uiSlots", {
+			list(slot) {
+				const ranked = [...entryOf(slot).occupants.values()].sort((a, b) => a.occupant.order - b.occupant.order || a.seq - b.seq);
+				if (slotModeOf(slot) === "single" && ranked.length > 0) return [ranked.reduce((best, item) => {
+					const byPrecedence = (item.occupant.precedence ?? 0) - (best.occupant.precedence ?? 0);
+					return byPrecedence > 0 || byPrecedence === 0 && item.seq > best.seq ? item : best;
+				}).occupant];
+				return ranked.map((item) => item.occupant);
+			},
+			register(caller, slot, occupant) {
+				const entry = entryOf(slot);
+				entry.occupants.set(occupant.id, {
+					occupant,
+					seq: entry.nextSeq++
+				});
+				ctx.emit("ui/slot-changed", slot);
+				const remove = () => {
+					if (entry.occupants.delete(occupant.id)) ctx.emit("ui/slot-changed", slot);
+				};
+				caller.effect(() => remove);
+				return remove;
+			}
+		});
+	}
+};
+//#endregion
+export { CUSTOM_UI_SLOT_PATTERN, STANDARD_UI_SLOT_IDS, UI_SLOT_IDS, UI_SLOT_MODES, slotsPlugin as default, isValidUiSlotId, slotModeOf };

package/lib/types/Shell.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The slot-driven shell: renders every registered layout occupant, or the
+ * degradation notice when none did. Any `ui/slot-changed` emission re-renders
+ * the whole shell — occupants stay tiny; reconciliation is React's problem.
+ *
+ * @module @snap-rail/framework-shadcn/runtime/Shell
+ */
+import type { Context } from '@snap-rail/cordis';
+import { type ReactNode } from 'react';
+/** Shell root; mounted once by {@link ../index.tsx | createClientRuntime}. */
+export declare function Shell(props: {
+    ctx: Context;
+}): ReactNode;

package/lib/types/Shell.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment, useEffect, useState } from 'react';
+import { UI_SLOT_IDS } from "./slots.js";
+/** Shell root; mounted once by {@link ../index.tsx | createClientRuntime}. */
+export function Shell(props) {
+    const [tick, setTick] = useState(0);
+    useEffect(() => {
+        const detach = props.ctx.on('ui/slot-changed', () => setTick(value => value + 1));
+        return () => { detach(); };
+    }, [props.ctx]);
+    const layouts = props.ctx.uiSlots.list(UI_SLOT_IDS.layout);
+    const content = layouts.length > 0
+        ? layouts.map(occupant => _jsx(Fragment, { children: occupant.render() }, occupant.id))
+        : _jsx("div", { className: "m-auto text-muted-foreground", children: "\u6CA1\u6709\u5DF2\u52A0\u8F7D\u7684\u5E03\u5C40\u63D2\u4EF6\u3002" });
+    // `tick` participates so slot changes re-run the render.
+    return _jsx("div", { className: "flex h-full flex-col", "data-tick": tick, children: content });
+}

package/lib/types/client.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The framework's installable client face: one bundle carrying every face —
+ * the runtime, the slot registry, the shared primitives, the client
+ * services, and the fallback layout — re-exported as the contributed-seed
+ * map. The shell requires this face once and seeds each
+ * `@snap-rail/framework-shadcn/<key>` id from the map, so every installed
+ * component shares these exact instances (one slots registry, one primitives
+ * set, one runtime entry).
+ *
+ * @module @snap-rail/framework-shadcn/client
+ */
+import * as fallback from './fallback.tsx';
+import * as runtime from './runtime.tsx';
+import * as session from './session.ts';
+import * as settingsPages from './settings-pages.ts';
+import * as slots from './slots.tsx';
+import * as semantic from './semantic.tsx';
+import * as ui from './ui/index.ts';
+import * as variables from './variables.ts';
+import * as workflows from './workflows.ts';
+/** The faces this framework contributes as shared seeds. */
+export interface FrameworkSeedFaces {
+    ui: typeof ui;
+    slots: typeof slots;
+    semantic: typeof semantic;
+    'settings-pages': typeof settingsPages;
+    session: typeof session;
+    variables: typeof variables;
+    workflows: typeof workflows;
+    runtime: typeof runtime;
+    fallback: typeof fallback;
+}
+/**
+ * The client-face default export: the contributed-seed map. No plugin
+ * object rides along — the framework mounts nothing into an occupant seat;
+ * the runtime face's `createClientRuntime` is the integration point.
+ */
+declare const frameworkClientFace: {
+    seeds: FrameworkSeedFaces;
+};
+export default frameworkClientFace;

package/lib/types/client.js

@@ -0,0 +1,39 @@
+/**
+ * The framework's installable client face: one bundle carrying every face —
+ * the runtime, the slot registry, the shared primitives, the client
+ * services, and the fallback layout — re-exported as the contributed-seed
+ * map. The shell requires this face once and seeds each
+ * `@snap-rail/framework-shadcn/<key>` id from the map, so every installed
+ * component shares these exact instances (one slots registry, one primitives
+ * set, one runtime entry).
+ *
+ * @module @snap-rail/framework-shadcn/client
+ */
+import * as fallback from "./fallback.js";
+import * as runtime from "./runtime.js";
+import * as session from "./session.js";
+import * as settingsPages from "./settings-pages.js";
+import * as slots from "./slots.js";
+import * as semantic from "./semantic.js";
+import * as ui from "./ui/index.js";
+import * as variables from "./variables.js";
+import * as workflows from "./workflows.js";
+/**
+ * The client-face default export: the contributed-seed map. No plugin
+ * object rides along — the framework mounts nothing into an occupant seat;
+ * the runtime face's `createClientRuntime` is the integration point.
+ */
+const frameworkClientFace = {
+    seeds: {
+        ui,
+        slots,
+        semantic,
+        'settings-pages': settingsPages,
+        session,
+        variables,
+        workflows,
+        runtime,
+        fallback,
+    },
+};
+export default frameworkClientFace;

package/lib/types/fallback.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The fallback shell (兜底壳): the built-in minimal layout that shows when
+ * no business suite is active — a bare titlebar (window controls + the
+ * settings entry, so a fresh install can always reach the plugin manager)
+ * and an empty state pointing there. It yields the moment a suite layout
+ * registers: it renders only while it is the sole full-screen layout
+ * occupant (the settings dialog's own occupant is a portal, not a layout).
+ *
+ * @module @snap-rail/framework-shadcn/fallback
+ */
+import { type Plugin } from '@snap-rail/cordis';
+import './settings-pages.ts';
+/** The fallback shell occupant. */
+declare const fallbackShellPlugin: Plugin.Object<void>;
+export default fallbackShellPlugin;

package/lib/types/fallback.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The fallback shell (兜底壳): the built-in minimal layout that shows when
+ * no business suite is active — a bare titlebar (window controls + the
+ * settings entry, so a fresh install can always reach the plugin manager)
+ * and an empty state pointing there. It yields the moment a suite layout
+ * registers: it renders only while it is the sole full-screen layout
+ * occupant (the settings dialog's own occupant is a portal, not a layout).
+ *
+ * @module @snap-rail/framework-shadcn/fallback
+ */
+import { Context } from '@snap-rail/cordis';
+import "./settings-pages.js";
+import { UI_SLOT_IDS } from "./slots.js";
+import { Button, useRefresh } from "./ui/index.js";
+import { Fragment } from 'react';
+/** The settings dialog's occupant id (a Dialog portal, not a layout). */
+const SETTINGS_OCCUPANT_ID = 'settings-dialog';
+/** Window-control glyphs; inline so the shell needs no icon dependency. */
+function ControlIcons(props) {
+    const base = 'flex h-10 w-10 items-center justify-center text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground';
+    return (_jsxs("div", { className: "flex items-center", children: [_jsx("button", { type: "button", "aria-label": "\u6700\u5C0F\u5316", className: base, onClick: props.onMinimize, children: _jsx("svg", { viewBox: "0 0 12 12", className: "h-3 w-3", fill: "none", children: _jsx("path", { d: "M2 6h8", stroke: "currentColor", strokeWidth: "1.4" }) }) }), _jsx("button", { type: "button", "aria-label": "\u6700\u5927\u5316", className: base, onClick: props.onToggleMaximize, children: _jsx("svg", { viewBox: "0 0 12 12", className: "h-3 w-3", fill: "none", children: _jsx("rect", { x: "2.5", y: "2.5", width: "7", height: "7", stroke: "currentColor", strokeWidth: "1.2" }) }) }), _jsx("button", { type: "button", "aria-label": "\u5173\u95ED", className: `${base} hover:bg-destructive hover:text-white`, onClick: props.onClose, children: _jsx("svg", { viewBox: "0 0 12 12", className: "h-3 w-3", fill: "none", children: _jsx("path", { d: "m3 3 6 6M9 3l-6 6", stroke: "currentColor", strokeWidth: "1.4" }) }) })] }));
+}
+/** The fallback body: minimal titlebar + install guidance. */
+function FallbackShell(props) {
+    useRefresh(props.ctx, ['ui/slot-changed', 'settings/open-changed']);
+    const layouts = props.ctx.uiSlots.list(UI_SLOT_IDS.layout);
+    const fullScreen = layouts.filter(occupant => occupant.id !== SETTINGS_OCCUPANT_ID);
+    // A suite layout took over: render nothing.
+    if (fullScreen.length > 1)
+        return null;
+    const windowControl = (action) => {
+        void props.link.call('window.control', { action }).catch(() => undefined);
+    };
+    return (_jsxs("div", { className: "flex h-full flex-col", "data-region": "fallback-shell", children: [_jsxs("div", { className: "flex h-10 shrink-0 items-center justify-between border-b border-border pl-4 select-none", style: { WebkitAppRegion: 'drag' }, children: [_jsx("span", { className: "text-sm text-muted-foreground", children: "snap-rail" }), _jsxs("div", { className: "flex items-center", style: { WebkitAppRegion: 'no-drag' }, children: [props.ctx.uiSlots.list(UI_SLOT_IDS.titlebarActions).map(occupant => (_jsx(Fragment, { children: occupant.render() }, occupant.id))), _jsx("button", { type: "button", "aria-label": "\u8BBE\u7F6E", className: "flex h-10 w-10 items-center justify-center text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground", onClick: () => props.ctx.settingsPages.open(), children: _jsxs("svg", { viewBox: "0 0 24 24", className: "h-5 w-5", fill: "none", stroke: "currentColor", strokeWidth: "1.6", children: [_jsx("circle", { cx: "12", cy: "12", r: "3.2" }), _jsx("path", { d: "M19.4 15a1.7 1.7 0 0 0 .34 1.87l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.7 1.7 0 0 0-1.87-.34 1.7 1.7 0 0 0-1 1.55V21a2 2 0 1 1-4 0v-.09a1.7 1.7 0 0 0-1-1.55 1.7 1.7 0 0 0-1.87.34l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.7 1.7 0 0 0 .34-1.87 1.7 1.7 0 0 0-1.55-1H3a2 2 0 1 1 0-4h.09a1.7 1.7 0 0 0 1.55-1 1.7 1.7 0 0 0-.34-1.87l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.7 1.7 0 0 0 1.87.34h0a1.7 1.7 0 0 0 1-1.55V3a2 2 0 1 1 4 0v.09a1.7 1.7 0 0 0 1 1.55h0a1.7 1.7 0 0 0 1.87-.34l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.7 1.7 0 0 0-.34 1.87v0a1.7 1.7 0 0 0 1.55 1H21a2 2 0 1 1 0 4h-.09a1.7 1.7 0 0 0-1.55 1Z" })] }) }), _jsx(ControlIcons, { onMinimize: () => windowControl('minimize'), onToggleMaximize: () => windowControl('toggle-maximize'), onClose: () => windowControl('close') })] })] }), _jsx("div", { className: "flex min-h-0 flex-1 items-center justify-center p-6", children: _jsxs("div", { className: "grid max-w-md gap-4 text-center", children: [_jsx("div", { className: "text-xl font-medium text-foreground", children: "\u5C1A\u672A\u6FC0\u6D3B\u4E1A\u52A1\u5957\u4EF6" }), _jsx("p", { className: "text-sm text-muted-foreground", children: "\u6253\u5F00\u8BBE\u7F6E\u7684\u300C\u63D2\u4EF6\u7BA1\u7406\u300D\u9875\uFF0C\u5B89\u88C5\u5E76\u6FC0\u6D3B\u4E00\u4E2A\u4E1A\u52A1\u5957\u4EF6\uFF1B\u901A\u8BAF\u9A71\u52A8\u4E5F\u5728\u540C\u4E00\u5904\u5B89\u88C5\u3002" }), _jsx("div", { children: _jsx(Button, { "data-fallback-open-settings": true, onClick: () => props.ctx.settingsPages.open(), children: "\u6253\u5F00\u8BBE\u7F6E" }) })] }) })] }));
+}
+/** The fallback shell occupant. */
+const fallbackShellPlugin = {
+    name: 'framework fallback',
+    inject: ['uiSlots', 'settingsPages'],
+    apply(ctx) {
+        const client = ctx.get('client');
+        ctx.uiSlots.register(ctx, UI_SLOT_IDS.layout, {
+            id: 'fallback-shell',
+            order: 200,
+            render() {
+                return _jsx(FallbackShell, { ctx: ctx, link: client.link });
+            },
+        });
+    },
+};
+export default fallbackShellPlugin;

package/lib/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The framework root barrel: one import site for the whole UI substrate —
+ * the renderer runtime, the slot registry, the shared shadcn-style
+ * primitives, the theme tokens, and the settings/session/variables/workflows
+ * services. Component plugins bind to this package through
+ * `snapRail.framework`; replacing it is an ecosystem switch, not a hot swap.
+ *
+ * @module @snap-rail/framework-shadcn
+ */
+export * from './runtime.tsx';
+export * from './slots.tsx';
+export * from './semantic.tsx';
+export * from './settings-pages.ts';
+export * from './session.ts';
+export * from './variables.ts';
+export * from './workflows.ts';
+export * from './fallback.tsx';

package/lib/types/index.js

@@ -0,0 +1,17 @@
+/**
+ * The framework root barrel: one import site for the whole UI substrate —
+ * the renderer runtime, the slot registry, the shared shadcn-style
+ * primitives, the theme tokens, and the settings/session/variables/workflows
+ * services. Component plugins bind to this package through
+ * `snapRail.framework`; replacing it is an ecosystem switch, not a hot swap.
+ *
+ * @module @snap-rail/framework-shadcn
+ */
+export * from "./runtime.js";
+export * from "./slots.js";
+export * from "./semantic.js";
+export * from "./settings-pages.js";
+export * from "./session.js";
+export * from "./variables.js";
+export * from "./workflows.js";
+export * from "./fallback.js";

package/lib/types/runtime.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The client renderer host: takes over the React root from the kernel,
+ * mounts the phase-1 occupant plugins into one client Cordis context, and
+ * renders the slot-driven shell that re-renders whenever any occupied slot
+ * changes. When no layout plugin registered, the shell degrades to a notice
+ * instead of an empty window.
+ *
+ * @module @snap-rail/framework-shadcn/runtime
+ */
+import { Context, type Plugin } from '@snap-rail/cordis';
+import type { ClientHandle } from '@snap-rail/client-kernel';
+import type { HostLink } from '@snap-rail/connection';
+import type { SurfaceId } from '@snap-rail/protocol';
+export type { ClientHandle } from '@snap-rail/client-kernel';
+declare module '@snap-rail/cordis' {
+    interface Context {
+        /** Shared client-side services every occupant may consume. */
+        client: ClientServices;
+    }
+}
+/** Services mounted once for all occupant plugins. */
+export interface ClientServices {
+    /** The typed host link shared by every occupant. */
+    link: HostLink;
+    /**
+     * Which window this client tree serves (`main` or `ball`). A face bound to
+     * the auxiliary surface reads it to pick its compact layout, and a face
+     * that only makes sense on `main` can refuse to mount there.
+     */
+    surface: SurfaceId;
+}
+/** One occupant seat: the plugin plus the config carved from its plugins.yml row. */
+export interface OccupantSpec {
+    /** The occupant plugin (layout, chrome, process pages). */
+    plugin: Plugin;
+    /** The occupant's config when its user-layer row carries one. */
+    config?: unknown;
+}
+/** Options for {@link createClientRuntime}. */
+export interface RuntimeOptions {
+    /**
+     * Occupant plugins (layout, chrome, process pages) — a bare plugin or one
+     * paired with config. Phase 1 ships them from an in-app list; the
+     * boot-graph-driven loader replaces this seat when plugin directories ship
+     * outside the bundle.
+     */
+    plugins: readonly (Plugin | OccupantSpec)[];
+    /**
+     * The window this runtime serves; defaults to `main`. The auxiliary surface
+     * gets the same spine services but its own shell: one slot paints the whole
+     * window (`shell.ball`), and the operator shell — layouts, titlebar,
+     * views — is never mounted into a 128px orb.
+     */
+    surface?: SurfaceId | undefined;
+}
+export interface RuntimeHandle {
+    ctx: Context;
+    dispose(): Promise<void>;
+}
+/**
+ * Take over the booted root: stop the startup page, mount the client plugin
+ * tree, render the shell.
+ *
+ * @param handle - the kernel's boot result.
+ * @param options - see {@link RuntimeOptions}.
+ */
+export declare function createClientRuntime(handle: ClientHandle, options: RuntimeOptions): Promise<RuntimeHandle>;