@forgeax/interface 0.4.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+forgeax-interface
+Copyright 2026 ForgeaXGame Contributors
+
+This is part of the ForgeaX project, an open-source AI-native game
+development toolchain (https://github.com/ForgeaXGame).
+
+Licensed under the Apache License, Version 2.0 (the "License");
+see the LICENSE file in this repository or at
+http://www.apache.org/licenses/LICENSE-2.0 for details.

package/README.md

@@ -0,0 +1,111 @@
+# forgeax-interface
+
+forgeax 前端工程（Studio 三栏 UI）。
+
+## 技术栈
+
+- **Bun** runtime · **Vite 6** dev server · **React 19** · **TypeScript**
+- **Zustand** 状态管理
+- **lucide-react** 图标
+- 配色对齐 VAG 海外版 Design System（主色荧光绿 `#D4FF48`）
+
+## 启动
+
+```bash
+cd ForgeaXGame/forgeax-interface
+bun install
+bun dev   # http://localhost:18920
+```
+
+## 结构
+
+```
+src/
+├── main.tsx                    # 入口
+├── App.tsx                     # 三栏 shell
+├── store.ts                    # Zustand: mode / activeSession / activeAgent
+├── styles/
+│   ├── tokens.css              # VAG 配色 token
+│   └── global.css              # 重置 + 滚动条
+├── components/
+│   ├── TopBar/                 # 顶部 + Preview/Page mode switcher
+│   ├── Sidebar/                # 左栏 — AgentSession + Page工具 + 长期记忆
+│   ├── MainArea/               # 中栏 — Preview iframe / Page 编辑器
+│   └── ChatPanel/              # 右栏 — FORGE 卡 + Thought process + Composer
+└── assets/icons/               # 24 个图标（agent-icon.png + status-* + chevron-*）
+```
+
+## 模式切换
+
+顶部胶囊：**Preview** (`⌘1`) / **Page** (`⌘2`) / **Bus** (`⌘3`) — 切换中央 MainArea 内容；左/右栏不变。
+
+---
+
+## 2026-05-15 → 16 Bus surface 网
+
+v3 prompt daemon ~40 commit 后 UI 现状（详见 `forgeax-dev-diary/2026-05-16/UI-FRAMEWORK-PROPOSAL.md` §1 审计）：
+
+### Surface 网（5 处 deep-link 互通）
+
+- **TopBar**：3 mode-tab 各带 count chip（Preview 3 ws-client / Page 11 wb / Bus 19 plugin）· 同色对称
+- **Sidebar**：上半 PAGE 行 11 extension-* 图标（icon 读自 manifest）+ 单击 placeholder 卡（zh/en 描述 / manifest 路径 / 跳 Bus 详情按钮）· 下半 AGENTS 列 7 agent 卡片（role-tribe 6 色 dot · cc-coder `bus →` 可点 deep-link）· 底部 BUS KINDS 6 chip 横排（wb 11 / ag 1 / cli 4 / mb 1 / sk 1 / tl 1 click → BusAdmin kind filter）· header `BusHealthChip` 19 plugin 数字 + 健康灯
+- **MainArea**：
+  - Preview mode → 游戏 iframe（vite proxy 到 engine 15173）+ TEAM role-tribe dot strip
+  - Page mode → 11 extension-* plugin gallery（icon + 名 + 描述 + chip）
+  - Bus mode → BusAdminPanel（kind chip filter + search + 19 行表 · 行展开渲染 provides[] 4 色块 cliProvider/skills/tools/events + 反向 deep-link 回 Sidebar / wb tab）
+- **ChatPanel**：empty state BUS HOST 卡片（19 plugin + 6 kind chip + FORGE 范例 prompt）· TabStrip 加 bus chip · AgentSwitcher 7 marketplace placeholder avatar + role-tribe outer ring · Composer cli dropdown 行带 bus desc + bus → deep-link · 顶部 model-binding teal VIA chip strip · agent → bus mini bar
+- **Dashboard**（overlay）：Overview/Analytics/Runs/Threads 4 子页全 cli-provider Bus 视图收口（双 strip 双维度过滤 provider × status + 表格行 role dot + capability matrix）
+
+### 当前架构现状
+
+- 26 .tsx · 10 .css · 4977 CSS 行 · 51 store action · 263 hook 调用 · 1 个 Zustand store（1460 行单文件）
+- **零依赖**：无 Radix / Headless UI / shadcn / MUI / Tailwind · 无 react-router · 无 dnd-kit / framer-motion
+- **Token 体系**：`src/styles/tokens.css` + `primitive.css`（Figma `*.tokens.json`）· 526+ 处 `var(--*)` · 6 kind 配色家族（lime/violet/blue/teal/amber/orange）
+- **预览布局合并**：`src/styles/forgeax-preview/` 仅布局/结构 · 颜色/图标服从 token + lucide（见 `forgeax-preview/DESIGN-SYSTEM.md`）
+- **可拖拽**：自写 `<ResizeHandle>` 80 行 pointer-capture · `useLocalSize` localStorage 持久化
+
+### 已知架构债（待 P5-P9）
+
+1. **Overlay 原语 0/6** — 6 处 `alert()`/`confirm()` 在生产代码 · 4 个 dropdown 各自手 roll click-outside · 0 处 createPortal · 缺 Modal/Popover/Toast/Tooltip/CommandPalette
+2. **plugin runtime 不存在** — 11 extension-* tab body 全是 `<BusPluginPlaceholder>` 静态卡 · 没有 iframe / panel.esm.js 加载
+3. **3 栏布局硬编码** — 无 dock / collapse / 第二行 split
+4. **无 cmd-k / 全局快捷键** — 只有 Cmd+S + Esc
+5. **store 1460 行单文件** · sendMessage ~400 行 · UI state + fetch + SSE 全在一起
+6. **dark-only 主题** — 0 处 `[data-theme]` / `prefers-color-scheme`
+
+### 路线图
+
+- **P5** UI Primitives 6 件套 self-rolled ~600 LOC（Modal/Popover/DropdownMenu/Tooltip/Toast/CommandPalette）
+- **P6** Command Registry + Cmd-K（~470 LOC）
+- **P7** Theme + LayoutService（5 part dock）
+- **P8** Extension Runtime（`<ExtensionIframeHost>` + native React panels + Page contributions）
+- **P9** 双模态 UI（host + plugin 同构 surface · AG-UI 扩展 · 玩家与 AI 共操作）
+
+### 相关文档
+
+- `src/core/page-platform/`（Page / Panel / Activity contracts）
+- `src/components/ExtensionHost/`（iframe 与 native extension hosts）
+- `forgeax-dev-diary/2026-05-16/UI-FRAMEWORK-PROPOSAL.md`（架构审计 + P5-P8 颗粒图）
+- `forgeax-dev-diary/2026-05-16/DUAL-MODALITY-UI.md`（host = plugin 同构 · UISurface 抽象）
+- `forgeax-dev-diary/2026-05-16/STRATEGY-PLAN-v3.md`（OSS / Desktop / Cloud 三产品定位）
+- `~/.forgeax/auto-dev-progress.md`（daemon 颗粒账本）
+
+---
+
+## 2026-05-17 update · Bus 第一公民 + Workspaces + Settings 浮层
+
+5 路 surface 全部接通 Bus(每个 chip / row / pill 都能 deep-link 反查 plugin):
+
+- **Sidebar** — bus health 灯 + BUS KINDS footer(键盘 ↑↓⏎ 可用 · phase3.50)
+- **TopBar** — bus / skill / tool / agent LED count chip(role-tribe 着色 · P4.20-P4.22)+ ProjectSwitcher(任意目录开 workspace)
+- **Composer** — cli bus pill + `@` button → agent mention popover + `/` slash → skills
+- **Dashboard** — Overview Bus card · ThreadsList/RunsList provider role dot + distribution strip · Agents Hub pane
+- **ChatPanel** — empty-state Bus readout · `CpProvPulse` cli-provider health pill · SKILL gold LED pill
+
+**Settings 浮层** 取代 Bus mode tab(phase4 后期)。sections registry:Plugins / Keys / Models / CLI / Workspace / Account / About。Keys 段直接编辑 `SAFE_ENV_KEYS`。
+
+**Session-Thread-Agents 三合一** —— AgentsPanel / AgentSwitcher 现在是本-session-scoped 视图。SessionSwitcher 重写。ChatPanel 刷新按 `providerOverride` 分流(forgeax → ledger · 其他 → `.forgeax/runs/` AG-UI)。
+
+**布局** —— resizable sidebar / chat / dock panels · ContextMenu primitive · Composer refactor(message-parts/ 抽出)。
+
+完整数据 + 截图:[`../../forgeax-dev-diary/2026-05-18/SUMMARY.html`](../../forgeax-dev-diary/2026-05-18/SUMMARY.html)

package/dist/package/browser/App.css

@@ -0,0 +1,192 @@
+@import '@forgeax/app-shell/resize.css';
+@import '@forgeax/app-shell/panel.css';
+@import '@forgeax/app-shell/detached.css';
+@import '@forgeax/app-shell/surface.css';
+@import '@forgeax/app-shell/dock-tab.css';
+
+.studio-shell {
+  position: relative;
+  width: 100%; height: 100%;
+  min-width: 0;
+  display: flex; flex-direction: column;
+  background: var(--bg-0);
+  overflow: hidden;
+}
+
+/* forgeax-preview scene layer (.scene-fx) stays behind all shell chrome.
+   Whitelist layout-flow children only — overlays (.dash-overlay, .sp-overlay,
+   .pulse-feeds) must keep their own `position: fixed`. */
+.studio-shell > .topbar,
+.studio-shell > .studio-body,
+.studio-shell > .health-status-bar,
+.studio-shell > .global-status-bar {
+  position: relative;
+  z-index: 1;
+}
+
+/* TopBar owns fixed-position dropdowns; keep it above body panes. */
+.studio-shell > .topbar {
+  z-index: var(--z-top);
+  overflow: visible;
+}
+
+.studio-body {
+  flex: 1;
+  display: flex;
+  overflow: hidden;
+  min-width: 0;
+  min-height: 0;
+  /* The darkest canvas layer shows through the 6px gaps we open around the
+     ActivityRail (see .activity-rail margins), so the plugin rail reads as a
+     floating dock cell just like the native inter-group gaps in the dockview
+     grid. Every in-flow child (main col / rail / chat) is opaque, so this only
+     paints in those gaps. */
+  background: var(--color-background-canvas, #0d0d0d);
+}
+
+/* Main (Layout) column: the page-tab strip stacked over the DockShell + AuxBar
+   docks. Sits left of the full-height ActivityRail + chat, so the tab strip's
+   width matches the editor Layout area and stops before the plugin rail. */
+.studio-main-col {
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+.studio-main-dock {
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  display: flex;
+  overflow: hidden;
+}
+
+/* Fixed chat column — chat was pulled out of the dockview so the ActivityRail
+   (its own 64px column) can sit immediately to its left. Width is drag-resizable
+   (inline style from useChatWidth), so flex is fixed-basis:auto. */
+.studio-chat-col {
+  flex: 0 0 auto;
+  max-width: 100%;
+  min-width: 0;
+  height: 100%;
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  border-left: 1px solid var(--color-border-default);
+}
+
+/* Keep the persisted desktop width, but leave room for the activity rail and
+   a usable editor when the shell becomes phone-sized. The inline width from
+   useChatWidth still wins everywhere above this breakpoint. */
+@media (max-width: 640px) {
+  .studio-chat-col {
+    max-width: min(360px, calc(100% - 160px));
+  }
+}
+.studio-chat-col > .fx-panel {
+  flex: 1 1 0;
+  min-height: 0;
+  height: 100%;
+}
+/* Left-edge resize handle (6px). During drag, a full-viewport ::after catcher +
+   iframe pointer-events:none keep the engine/plugin iframes from stealing the
+   pointer mid-drag — same technique as .fx-auxbar-resizer. */
+/* Sit ON the 6px canvas gap between the ActivityRail and the chat column (the
+   rail's margin-right), NOT just inside the chat edge — so the GAP itself is the
+   drag target and lights up lime, exactly like a dockview grid sash. Transparent
+   at rest lets the canvas show through (the visible gap); hover/drag fills it. */
+.fx-chat-resizer {
+  position: absolute;
+  left: -6px;
+  top: 0;
+  bottom: 0;
+  width: 6px;
+  margin: 0;
+  cursor: col-resize;
+  z-index: 10;
+  background: transparent;
+  transition: background 120ms ease;
+}
+.resize-handle.fx-chat-resizer::after { content: none; }
+/* Match dockview's UE sash: a solid lime bar revealed on hover / during drag,
+   so the chat column's left-edge resizer reads the same as the 6px grid gaps
+   sitting right beside it (was a blue bar → clashed with the lime sashes). */
+.fx-chat-resizer:hover,
+body.fx-chat-resizing .fx-chat-resizer {
+  background: var(--lime, #7ee04a);
+}
+body.fx-chat-resizing::after {
+  content: '';
+  position: fixed;
+  inset: 0;
+  z-index: 9;
+  cursor: col-resize;
+}
+body.fx-chat-resizing iframe {
+  pointer-events: none;
+}
+
+.studio-pane {
+  flex-shrink: 0;
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+}
+.studio-pane > * { flex: 1; min-height: 0; width: 100%; }
+
+.studio-shell--preview-skin .studio-pane-right {
+  overflow: visible;
+  z-index: var(--z-overlay);
+}
+
+/* Preview rail: Sidebar sets its own width (60px collapsed / 60+drawer expanded) */
+.studio-pane-left--rail {
+  flex: 0 0 auto;
+  width: auto;
+  min-width: 0;
+}
+/* ──────────────────────────────────────────────────────────────────────
+   Fullscreen ("immersive") mode · driven by Ctrl+Shift+F · store.fullscreen
+   ----------------------------------------------------------------------
+   Hides every chrome surface so MainArea (the canvas / extension) owns the
+   whole viewport. Toggled on/off by .studio-shell[data-fullscreen="1"].
+   Esc also exits (see lib/global-shortcuts.ts Esc cascade).
+
+   Surfaces hidden: TopBar · Sidebar · ChatPanel · GlobalStatusBar.
+   Surfaces kept:   MainArea + any overlay (Settings / Dashboard) so the
+                    user can still open settings while immersive.
+   ────────────────────────────────────────────────────────────────────── */
+.studio-shell[data-fullscreen="1"] > .topbar,
+.studio-shell[data-fullscreen="1"] [data-fx-slot="PageTabs"],
+.studio-shell[data-fullscreen="1"] > .studio-body > .studio-pane-left,
+.studio-shell[data-fullscreen="1"] > .studio-body > .resize-handle-col,
+.studio-shell[data-fullscreen="1"] > .studio-body > .studio-pane-right,
+.studio-shell[data-fullscreen="1"] > .global-status-bar {
+  display: none !important;
+}
+
+/* Subtle hint at top edge so user remembers they're in fullscreen — a 2px
+   lime line they can click to exit (in addition to Esc / Ctrl+Shift+F). */
+.studio-shell[data-fullscreen="1"]::before {
+  content: "全屏模式 · Ctrl+Shift+F 或 Esc 退出";
+  position: fixed;
+  top: 8px; right: 12px;
+  z-index: 2000;
+  font-family: var(--font-mono);
+  font-size: 10.5px;
+  letter-spacing: 0.06em;
+  color: rgba(255, 255, 255, 0.55);
+  background: rgba(20, 24, 26, 0.78);
+  border: 1px solid var(--color-border-default);
+  padding: 3px 9px;
+  border-radius: 99px;
+  pointer-events: none;
+  animation: kc-fs-hint-fade 3s ease-out 2s forwards;
+}
+@keyframes kc-fs-hint-fade {
+  to { opacity: 0.12; }
+}

package/dist/package/browser/App.d.ts

@@ -0,0 +1,11 @@
+import { type ApplicationOnboardingOptions } from './ApplicationShell';
+import { type AppHostBootstrapOverrides } from './application';
+export interface AppProps {
+    /** Studio injects concrete overlay / surface / slot / detached / editor
+     *  extensions here (ADR 0025 M1 — the sole assembly channel; the legacy
+     *  `panelRenderers` escape hatch was removed once studio migrated). */
+    overrides?: AppHostBootstrapOverrides;
+    /** Product-level onboarding policy; setup remains shared across assemblies. */
+    onboarding?: ApplicationOnboardingOptions;
+}
+export declare function App({ overrides, onboarding }?: AppProps): React.ReactElement | null;

package/dist/package/browser/App.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Compatibility entry for existing standalone consumers. Product assemblies
+// should own ApplicationRuntimeRoot and render ApplicationShell directly.
+import { useCallback } from 'react';
+import { ApplicationRuntimeRoot } from '@forgeax/app-shell/application';
+import { ApplicationShell, } from './ApplicationShell';
+import { startInterfaceApplication, } from './application';
+export function App({ overrides, onboarding } = {}) {
+    const start = useCallback(() => startInterfaceApplication(overrides), [overrides]);
+    return (_jsx(ApplicationRuntimeRoot, { start: start, children: (runtime) => _jsx(ApplicationShell, { runtime: runtime, onboarding: onboarding }) }));
+}

package/dist/package/browser/ApplicationDetachedShell.d.ts

@@ -0,0 +1,13 @@
+import { type ComponentType, type ReactElement, type ReactNode } from 'react';
+import type { SurfaceDescriptor } from '@forgeax/app-shell/window';
+import type { InterfaceApplicationRuntime } from './application';
+export interface ApplicationDetachedShellProps {
+    readonly host: InterfaceApplicationRuntime['host'];
+    readonly surface: SurfaceDescriptor;
+    /** A stable product-owned provider rendered inside the shell contexts. */
+    readonly SurfaceProvider?: ComponentType<{
+        children: ReactNode;
+    }>;
+}
+/** Detached presentation only; the caller retains startup, recovery and disposal. */
+export declare function ApplicationDetachedShell({ host, surface, SurfaceProvider, }: ApplicationDetachedShellProps): ReactElement;

package/dist/package/browser/ApplicationDetachedShell.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment } from 'react';
+import { HostProvider } from '@forgeax/app-shell/application';
+import { BrandProvider } from './brand';
+import { DetachedSurface } from './components/DetachedSurface';
+import { PanelRenderersProvider } from './components/DockShell/panelRenderers';
+/** Detached presentation only; the caller retains startup, recovery and disposal. */
+export function ApplicationDetachedShell({ host, surface, SurfaceProvider = Fragment, }) {
+    return (_jsx(BrandProvider, { children: _jsx(HostProvider, { value: host, children: _jsx(PanelRenderersProvider, { value: host.panels, children: _jsx(SurfaceProvider, { children: _jsx(DetachedSurface, { surface: surface }) }) }) }) }));
+}

package/dist/package/browser/ApplicationShell.d.ts

@@ -0,0 +1,19 @@
+import type { InterfaceApplicationRuntime } from './application';
+import './App.css';
+export { ApplicationDetachedShell } from './ApplicationDetachedShell';
+export type { ApplicationDetachedShellProps } from './ApplicationDetachedShell';
+export interface ApplicationOnboardingOptions {
+    /** Whether this product assembly participates in Interface onboarding. */
+    readonly enabled?: boolean;
+    readonly tourEnabled?: boolean;
+}
+export interface ApplicationShellProps {
+    readonly runtime: InterfaceApplicationRuntime;
+    readonly onboarding?: ApplicationOnboardingOptions;
+}
+export declare function isApplicationOnboardingEnabled(onboarding?: ApplicationOnboardingOptions): boolean;
+/**
+ * Renders the shared Interface chrome for a runtime owned by the product root.
+ * Product startup and disposal deliberately stay outside this component.
+ */
+export declare function ApplicationShell({ runtime, onboarding }: ApplicationShellProps): React.ReactElement;

package/dist/package/browser/ApplicationShell.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useMemo, useSyncExternalStore } from 'react';
+import { SlotDebugOverlay, isSlotDebugEnabled } from '@forgeax/app-shell/react';
+import { TopBar } from './components/TopBar/TopBar';
+import { GameDirectoryModalHost } from './components/TopBar/ProjectSwitcher';
+import { GameModalHost } from './components/TopBar/GameSwitcher';
+import { ActivityRail } from './components/ActivityRail/ActivityRail';
+import { PageTabStrip } from './components/PageTabs/PageTabStrip';
+import { DockRegion } from './components/DockShell/DockRegion';
+import { PanelRenderersProvider, DEFAULT_PANEL_RENDERERS } from './components/DockShell/panelRenderers';
+import { SurfaceKeepAliveLayer } from './components/Surfaces/SurfaceKeepAliveLayer';
+import { StripHostView } from './components/StatusBar/StripHostView';
+import { DrawerHostView } from './components/Drawer/DrawerHostView';
+import { ContextMenu } from './components/ContextMenu/ContextMenu';
+import { CommandPalette } from './components/CommandPalette/CommandPalette';
+import { OnboardingController, ConnectModelPrompt } from './components/Onboarding';
+import { useOnboardingPhase } from './components/Onboarding/types';
+import { DialogHost } from './lib/dialog';
+import { PassiveFeedbackHost } from './components/Feedback/PassiveFeedback';
+import { useGlobalShortcuts } from './lib/global-shortcuts';
+import { useShellStore } from './store';
+import { useTranslation } from './i18n';
+import { initNativeMenuBridge } from './lib/native-menu-bridge';
+import { isTauri } from './lib/platform/runtime';
+import './App.css';
+export { ApplicationDetachedShell } from './ApplicationDetachedShell';
+function KeyboardRouter({ runtime }) {
+    useGlobalShortcuts(runtime.host.keybindings);
+    return null;
+}
+export function isApplicationOnboardingEnabled(onboarding) {
+    return onboarding?.enabled !== false;
+}
+/**
+ * Renders the shared Interface chrome for a runtime owned by the product root.
+ * Product startup and disposal deliberately stay outside this component.
+ */
+export function ApplicationShell({ runtime, onboarding }) {
+    const { t } = useTranslation();
+    const fullscreen = useShellStore((state) => state.fullscreen);
+    const sidebarCollapsed = useShellStore((state) => state.sidebarCollapsed);
+    const chatpanelCollapsed = useShellStore((state) => state.chatpanelCollapsed);
+    const onboardingPhase = useOnboardingPhase();
+    const onboardingEnabled = isApplicationOnboardingEnabled(onboarding);
+    const shellHidden = onboardingEnabled && (onboardingPhase === 'welcome' || onboardingPhase === 'project');
+    useEffect(() => {
+        if (!isTauri())
+            return;
+        void initNativeMenuBridge({
+            execute: (id, args) => runtime.host.commands.execute(id, args),
+            translate: t,
+        });
+    }, [runtime, t]);
+    const subscribePanels = useMemo(() => (callback) => runtime.control.onPanelsChange(callback), [runtime]);
+    const renderers = useSyncExternalStore(subscribePanels, () => runtime.host.panels, () => DEFAULT_PANEL_RENDERERS);
+    const Dashboard = renderers.overlays?.Dashboard;
+    const Settings = renderers.overlays?.Settings;
+    if (shellHidden) {
+        return (_jsxs(_Fragment, { children: [_jsx(KeyboardRouter, { runtime: runtime }), _jsx(PanelRenderersProvider, { value: renderers, children: _jsxs("div", { className: "studio-shell studio-shell--preview-skin", children: [_jsx(OnboardingController, { tourEnabled: onboarding?.tourEnabled }), _jsx(DialogHost, {})] }) })] }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(KeyboardRouter, { runtime: runtime }), _jsx(PanelRenderersProvider, { value: renderers, children: _jsxs("div", { className: "studio-shell studio-shell--preview-skin", "data-fullscreen": fullscreen ? '1' : undefined, "data-sidebar-collapsed": sidebarCollapsed ? '1' : undefined, "data-chatpanel-collapsed": chatpanelCollapsed ? '1' : undefined, children: [onboardingEnabled && (_jsx(OnboardingController, { tourEnabled: onboarding?.tourEnabled })), _jsx(ConnectModelPrompt, {}), _jsx(TopBar, {}), _jsx(PassiveFeedbackHost, {}), _jsxs("div", { className: "studio-body", children: [_jsxs("div", { className: "studio-main-col", children: [_jsx(PageTabStrip, {}), _jsxs("div", { className: "studio-main-dock", children: [_jsx(DockRegion, { region: "DockShell" }), _jsx(DockRegion, { region: "AuxBar" })] })] }), _jsx(SurfaceKeepAliveLayer, {}), _jsx(ActivityRail, {}), _jsx(DockRegion, { region: "ChatDock" })] }), _jsx(DrawerHostView, {}), _jsx(StripHostView, {}), Dashboard && _jsx("div", { "data-fx-slot": "Dashboard", style: { display: 'contents' }, children: _jsx(Dashboard, {}) }), Settings && _jsx("div", { "data-fx-slot": "Settings", style: { display: 'contents' }, children: _jsx(Settings, {}) }), _jsx(ContextMenu, {}), _jsx(CommandPalette, {}), _jsx(GameDirectoryModalHost, {}), _jsx(GameModalHost, {}), _jsx(DialogHost, {}), isSlotDebugEnabled() && _jsx(SlotDebugOverlay, {})] }) })] }));
+}

package/dist/package/browser/app-kit.d.ts

@@ -0,0 +1 @@
+export { AppKitError, defineApp, mountComposition, type AppKitErrorInit, type AppManifest, type AppManifestPanel, type DefinedApp, type MountOptions, } from '@forgeax/app-shell/application';

package/dist/package/browser/app-kit.js

@@ -0,0 +1,4 @@
+// Compatibility export while application packages migrate to App Shell.
+// AppKit is product-neutral composition metadata and structured mount errors;
+// Interface no longer owns a second implementation.
+export { AppKitError, defineApp, mountComposition, } from '@forgeax/app-shell/application';