@snap-rail/framework-shadcn 0.2.0 → 0.2.2

package/README.md

@@ -2,9 +2,10 @@
 
 界面框架插件（clientOnly、单活 `snapRail.exclusive: 'framework'`）：槽位词汇、
 renderer runtime + Shell、shadcn 风格共享原语、主题令牌（预编译 tailwind 输出
-随 zip 内联）、settings/session/variables/workflows 服务与 fallback 布局。
+随 zip 内联）、settings/session/variables/workflows 服务、fallback 布局与辅助
+surface 壳（`surface-shell.tsx` 渲染 `ball` 悬浮球面）。
 
-组件插件经 `requires: ['@snap-rail/framework-shadcn@^0.1']` 绑定本框架（绑定即依赖）；框架不匹配装不上。
+组件插件经 `requires: ['@snap-rail/framework-shadcn@^0.2']` 绑定本框架（绑定即依赖）；框架不匹配装不上。
 构建链：tsc（lib/types）→ tailwind（lib-client/theme.css）→ tsdown（lib 面 +
 clientBundle 工厂包）。
 

package/lib/fallback.js

@@ -27,7 +27,14 @@ const UI_SLOT_IDS = {
 	main: "shell.main",
 	view: "shell.view",
 	statusbar: "shell.statusbar",
-	overlay: "shell.overlay"
+	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"
 };
 new Set(Object.values(UI_SLOT_IDS));
 /**
@@ -48,7 +55,8 @@ const UI_SLOT_MODES = {
 	[UI_SLOT_IDS.main]: "single",
 	[UI_SLOT_IDS.view]: "stack",
 	[UI_SLOT_IDS.statusbar]: "stack",
-	[UI_SLOT_IDS.overlay]: "stack"
+	[UI_SLOT_IDS.overlay]: "stack",
+	[UI_SLOT_IDS.ball]: "single"
 };
 new Map(Object.entries(UI_SLOT_MODES));
 //#endregion

package/lib/index.js

@@ -22,6 +22,7 @@ import { SESSION_OPERATOR_KEY, settingsChangedSchema } from "@snap-rail/station-
 import { PLUGINS_FEED_URLS_KEY, UPDATE_AUTO_CHECK_KEY, UPDATE_FEED_URL_KEY, pluginUpdatesChangedSchema, updateStatusSchema } from "@snap-rail/app-boot/contract";
 import { equipmentFrameSchemas, pointKey } from "@snap-rail/equipment/contract";
 import { createRoot } from "react-dom/client";
+import { SurfaceFallback } from "@snap-rail/client-kernel";
 //#region lib/types/settings-pages.js
 /**
 * Mounts the `ctx.settingsPages` registry. All state lives in
@@ -99,7 +100,14 @@ const UI_SLOT_IDS = {
 	main: "shell.main",
 	view: "shell.view",
 	statusbar: "shell.statusbar",
-	overlay: "shell.overlay"
+	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));
@@ -127,7 +135,8 @@ const UI_SLOT_MODES = {
 	[UI_SLOT_IDS.main]: "single",
 	[UI_SLOT_IDS.view]: "stack",
 	[UI_SLOT_IDS.statusbar]: "stack",
-	[UI_SLOT_IDS.overlay]: "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`. */
@@ -2988,6 +2997,28 @@ function Shell(props) {
 	});
 }
 //#endregion
+//#region lib/types/surface-shell.js
+/** Shell root for the auxiliary window; mounted by `createClientRuntime`. */
+function SurfaceShell(props) {
+	const [tick, setTick] = useState(0);
+	useEffect(() => {
+		const detach = props.ctx.on("ui/slot-changed", () => setTick((value) => value + 1));
+		return () => {
+			detach();
+		};
+	}, [props.ctx]);
+	const occupant = props.ctx.uiSlots.list(UI_SLOT_IDS.ball)[0];
+	return jsx("div", {
+		className: "h-full w-full",
+		"data-tick": tick,
+		"data-surface": props.surface,
+		children: occupant === void 0 ? jsx(SurfaceFallback, {
+			link: props.ctx.client.link,
+			surface: props.surface
+		}) : occupant.render()
+	});
+}
+//#endregion
 //#region lib/types/runtime.js
 /**
 * The client renderer host: takes over the React root from the kernel,
@@ -3006,8 +3037,12 @@ function Shell(props) {
 * @param options - see {@link RuntimeOptions}.
 */
 async function createClientRuntime(handle, options) {
+	const surface = options.surface ?? "main";
 	const ctx = new Context();
-	ctx.provide("client", { link: handle.link });
+	ctx.provide("client", {
+		link: handle.link,
+		surface
+	});
 	await ctx.plugin(TimerService);
 	await ctx.plugin(slotsPlugin);
 	await ctx.plugin(semanticPlugin);
@@ -3021,10 +3056,13 @@ async function createClientRuntime(handle, options) {
 		const plugin = spec.plugin;
 		await ctx.plugin(plugin, spec.config === void 0 ? {} : spec.config);
 	}
-	await ctx.plugin(fallbackShellPlugin);
+	if (surface === "main") await ctx.plugin(fallbackShellPlugin);
 	handle.root.unmount();
 	const shellRoot = createRoot(handle.element);
-	shellRoot.render(jsx(Shell, { ctx }));
+	shellRoot.render(surface === "main" ? jsx(Shell, { ctx }) : jsx(SurfaceShell, {
+		ctx,
+		surface
+	}));
 	return {
 		ctx,
 		dispose: () => ctx.fiber.dispose().then(() => {

package/lib/runtime.js

@@ -22,6 +22,7 @@ import { SESSION_OPERATOR_KEY, settingsChangedSchema } from "@snap-rail/station-
 import { PLUGINS_FEED_URLS_KEY, UPDATE_AUTO_CHECK_KEY, UPDATE_FEED_URL_KEY, pluginUpdatesChangedSchema, updateStatusSchema } from "@snap-rail/app-boot/contract";
 import { pointKey } from "@snap-rail/equipment/contract";
 import { createRoot } from "react-dom/client";
+import { SurfaceFallback } from "@snap-rail/client-kernel";
 //#region lib/types/settings-pages.js
 /**
 * Mounts the `ctx.settingsPages` registry. All state lives in
@@ -99,7 +100,14 @@ const UI_SLOT_IDS = {
 	main: "shell.main",
 	view: "shell.view",
 	statusbar: "shell.statusbar",
-	overlay: "shell.overlay"
+	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));
@@ -127,7 +135,8 @@ const UI_SLOT_MODES = {
 	[UI_SLOT_IDS.main]: "single",
 	[UI_SLOT_IDS.view]: "stack",
 	[UI_SLOT_IDS.statusbar]: "stack",
-	[UI_SLOT_IDS.overlay]: "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`. */
@@ -2779,6 +2788,28 @@ function Shell(props) {
 	});
 }
 //#endregion
+//#region lib/types/surface-shell.js
+/** Shell root for the auxiliary window; mounted by `createClientRuntime`. */
+function SurfaceShell(props) {
+	const [tick, setTick] = useState(0);
+	useEffect(() => {
+		const detach = props.ctx.on("ui/slot-changed", () => setTick((value) => value + 1));
+		return () => {
+			detach();
+		};
+	}, [props.ctx]);
+	const occupant = props.ctx.uiSlots.list(UI_SLOT_IDS.ball)[0];
+	return jsx("div", {
+		className: "h-full w-full",
+		"data-tick": tick,
+		"data-surface": props.surface,
+		children: occupant === void 0 ? jsx(SurfaceFallback, {
+			link: props.ctx.client.link,
+			surface: props.surface
+		}) : occupant.render()
+	});
+}
+//#endregion
 //#region lib/types/runtime.js
 /**
 * The client renderer host: takes over the React root from the kernel,
@@ -2797,8 +2828,12 @@ function Shell(props) {
 * @param options - see {@link RuntimeOptions}.
 */
 async function createClientRuntime(handle, options) {
+	const surface = options.surface ?? "main";
 	const ctx = new Context();
-	ctx.provide("client", { link: handle.link });
+	ctx.provide("client", {
+		link: handle.link,
+		surface
+	});
 	await ctx.plugin(TimerService);
 	await ctx.plugin(slotsPlugin);
 	await ctx.plugin(semanticPlugin);
@@ -2812,10 +2847,13 @@ async function createClientRuntime(handle, options) {
 		const plugin = spec.plugin;
 		await ctx.plugin(plugin, spec.config === void 0 ? {} : spec.config);
 	}
-	await ctx.plugin(fallbackShellPlugin);
+	if (surface === "main") await ctx.plugin(fallbackShellPlugin);
 	handle.root.unmount();
 	const shellRoot = createRoot(handle.element);
-	shellRoot.render(jsx(Shell, { ctx }));
+	shellRoot.render(surface === "main" ? jsx(Shell, { ctx }) : jsx(SurfaceShell, {
+		ctx,
+		surface
+	}));
 	return {
 		ctx,
 		dispose: () => ctx.fiber.dispose().then(() => {

package/lib/semantic.js

@@ -10,7 +10,14 @@ const UI_SLOT_IDS = {
 	main: "shell.main",
 	view: "shell.view",
 	statusbar: "shell.statusbar",
-	overlay: "shell.overlay"
+	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));
@@ -38,7 +45,8 @@ const UI_SLOT_MODES = {
 	[UI_SLOT_IDS.main]: "single",
 	[UI_SLOT_IDS.view]: "stack",
 	[UI_SLOT_IDS.statusbar]: "stack",
-	[UI_SLOT_IDS.overlay]: "stack"
+	[UI_SLOT_IDS.overlay]: "stack",
+	[UI_SLOT_IDS.ball]: "single"
 };
 new Map(Object.entries(UI_SLOT_MODES));
 //#endregion

package/lib/slots.js

@@ -10,7 +10,14 @@ const UI_SLOT_IDS = {
 	main: "shell.main",
 	view: "shell.view",
 	statusbar: "shell.statusbar",
-	overlay: "shell.overlay"
+	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));
@@ -38,7 +45,8 @@ const UI_SLOT_MODES = {
 	[UI_SLOT_IDS.main]: "single",
 	[UI_SLOT_IDS.view]: "stack",
 	[UI_SLOT_IDS.statusbar]: "stack",
-	[UI_SLOT_IDS.overlay]: "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`. */

package/lib/types/runtime.d.ts

@@ -10,6 +10,7 @@
 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 {
@@ -21,6 +22,12 @@ declare module '@snap-rail/cordis' {
 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 {
@@ -38,6 +45,13 @@ export interface RuntimeOptions {
      * 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;

package/lib/types/runtime.js

@@ -26,6 +26,7 @@ import variablesPlugin from "./variables.js";
 import workflowsPlugin from "./workflows.js";
 import { createRoot } from 'react-dom/client';
 import { Shell } from "./Shell.js";
+import { SurfaceShell } from "./surface-shell.js";
 /**
  * Take over the booted root: stop the startup page, mount the client plugin
  * tree, render the shell.
@@ -34,10 +35,11 @@ import { Shell } from "./Shell.js";
  * @param options - see {@link RuntimeOptions}.
  */
 export async function createClientRuntime(handle, options) {
+    const surface = options.surface ?? 'main';
     const ctx = new Context();
-    ctx.provide('client', { link: handle.link });
+    ctx.provide('client', { link: handle.link, surface });
     // Spine services first: timer gives occupants disposable intervals, slots
-    // carries the panel seam, session and workflows sit under every occupant,
+    // carries the occupant seam, session and workflows sit under every occupant,
     // and settingsPages/variables are the seams dialog pages and demand
     // plugins consume. The settings shell rides right after its seam — the
     // dialog, the theme adopter, and the first-party plugin/theme/update
@@ -60,12 +62,16 @@ export async function createClientRuntime(handle, options) {
     }
     // The framework's own fallback layout rides last: it renders only while it
     // is the sole full-screen layout occupant and yields the moment a suite
-    // layout registers.
-    await ctx.plugin(fallbackPlugin);
+    // layout registers. It is an operator-window concern — an auxiliary surface
+    // paints its own slot and has no layout to fall back from.
+    if (surface === 'main')
+        await ctx.plugin(fallbackPlugin);
     // Take over the element: the startup root unmounts, a fresh shell roots.
     handle.root.unmount();
     const shellRoot = createRoot(handle.element);
-    shellRoot.render(_jsx(Shell, { ctx: ctx }));
+    shellRoot.render(surface === 'main'
+        ? _jsx(Shell, { ctx: ctx })
+        : _jsx(SurfaceShell, { ctx: ctx, surface: surface }));
     return {
         ctx,
         dispose: () => ctx.fiber.dispose().then(() => {

package/lib/types/slots.d.ts

@@ -30,6 +30,13 @@ export declare const UI_SLOT_IDS: {
     readonly view: "shell.view";
     readonly statusbar: "shell.statusbar";
     readonly 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.
+     */
+    readonly ball: "shell.ball";
 };
 /** Runtime set used by manifest/semantic validation as well as TypeScript. */
 export declare const STANDARD_UI_SLOT_IDS: ReadonlySet<string>;
@@ -60,6 +67,7 @@ export declare const UI_SLOT_MODES: {
     readonly "shell.view": "stack";
     readonly "shell.statusbar": "stack";
     readonly "shell.overlay": "stack";
+    readonly "shell.ball": "single";
 };
 /** The occupancy mode of a slot; `custom:*` slots are `stack`. */
 export declare function slotModeOf(slot: SlotId): UiSlotMode;

package/lib/types/slots.js

@@ -29,6 +29,13 @@ export const UI_SLOT_IDS = {
     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. */
 export const STANDARD_UI_SLOT_IDS = new Set(Object.values(UI_SLOT_IDS));
@@ -57,6 +64,7 @@ export const UI_SLOT_MODES = {
     [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`. */

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

@@ -0,0 +1,21 @@
+/**
+ * The auxiliary-surface shell: what the ball window renders instead of the
+ * operator shell. A 128px transparent window has no room for a titlebar,
+ * a sidebar, or a view port — mounting the operator shell there would paint a
+ * miniature copy of the terminal into a floating orb.
+ *
+ * One slot (`shell.ball`) and the elected occupant paints the whole window;
+ * with no occupant the framework's default takes over — the kernel's
+ * fallback, which is already the right shape for this window (a draggable orb
+ * that summons the operator window). The default is never destroyed, only
+ * shadowed, so unloading a suite falls back automatically.
+ *
+ * @module @snap-rail/framework-shadcn/surface-shell
+ */
+import type { Context } from '@snap-rail/cordis';
+import { type ReactNode } from 'react';
+/** Shell root for the auxiliary window; mounted by `createClientRuntime`. */
+export declare function SurfaceShell(props: {
+    ctx: Context;
+    surface: 'ball';
+}): ReactNode;

package/lib/types/surface-shell.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { SurfaceFallback } from '@snap-rail/client-kernel';
+import { UI_SLOT_IDS } from "./slots.js";
+/** Shell root for the auxiliary window; mounted by `createClientRuntime`. */
+export function SurfaceShell(props) {
+    const [tick, setTick] = useState(0);
+    useEffect(() => {
+        const detach = props.ctx.on('ui/slot-changed', () => setTick(value => value + 1));
+        return () => { detach(); };
+    }, [props.ctx]);
+    // `single` slots answer with the elected winner only, so index 0 is the tenant.
+    const occupant = props.ctx.uiSlots.list(UI_SLOT_IDS.ball)[0];
+    return (_jsx("div", { className: "h-full w-full", "data-tick": tick, "data-surface": props.surface, children: occupant === undefined
+            ? _jsx(SurfaceFallback, { link: props.ctx.client.link, surface: props.surface })
+            : occupant.render() }));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@snap-rail/framework-shadcn",
   "description": "The UI framework (single-active): slot vocabulary, renderer runtime + shell, shadcn-style shared primitives, theme tokens, settings/session/variables/workflows services, the settings dialog shell with its first-party plugin/theme/update pages, and the fallback layout",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -78,7 +78,7 @@
   "peerDependencies": {
     "@snap-rail/cordis": "^4.0.1",
     "@snap-rail/equipment": "^0.1.0",
-    "@snap-rail/protocol": "^0.1.1",
+    "@snap-rail/protocol": "^0.1.3",
     "react": ">=19",
     "react-dom": ">=19"
   },
@@ -96,20 +96,20 @@
     "tsdown": "^0.22.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8",
-    "@snap-rail/app-boot": "0.1.2",
-    "@snap-rail/audit": "0.1.0",
-    "@snap-rail/client-kernel": "0.1.1",
-    "@snap-rail/connection": "0.1.0",
+    "@snap-rail/app-boot": "0.1.3",
+    "@snap-rail/client-kernel": "0.1.2",
     "@snap-rail/cordis": "4.0.3",
     "@snap-rail/cordis-plugin-timer": "1.1.3",
+    "@snap-rail/audit": "0.1.0",
     "@snap-rail/equipment": "0.1.4",
     "@snap-rail/gateway": "0.1.1",
-    "@snap-rail/plugin-kit": "0.2.1",
-    "@snap-rail/plugin-sdk": "0.2.2",
-    "@snap-rail/protocol": "0.1.1",
+    "@snap-rail/plugin-kit": "0.2.2",
+    "@snap-rail/plugin-sdk": "0.2.3",
     "@snap-rail/settings": "0.1.0",
     "@snap-rail/station-rpc": "0.1.0",
-    "@snap-rail/store-sqlite": "0.1.1"
+    "@snap-rail/store-sqlite": "0.1.1",
+    "@snap-rail/protocol": "0.1.3",
+    "@snap-rail/connection": "0.1.0"
   },
   "snapRail": {
     "kind": "framework",