@jetcrab/pi-desk 1.1.20-dev → 1.1.21

package/docs/plugins.md

@@ -50,6 +50,8 @@ Node Entry 默认导出普通 `PiDeskPluginDefinition` 对象即可，`definePiD
 
 `registerBrowserEntry()` 最多一次，路径位于包内，文件名为 `entry.js`。无需自有资源时 `setup()` 不必返回清理；创建 Timer、Watcher、连接或子进程时返回 disposer，释放旧实例资源。Host 自动撤销注册；旧异步清理不得写入新实例。
 
+宿主启动时，单个 Node 插件的入口导入、`setup()` 和 Browser 资源检查共用 15 秒上限。超时不代表插件代码已经停止；宿主撤销旧实例，等首轮插件加载、旧加载及其清理结束后，延迟 10 秒自动重试一次。明确加载错误和再次超时不自动重试；手动重载、禁用、卸载或宿主关闭会取消待执行的恢复。加载失败可在插件管理行点击“重新加载”，只重载本机代码。
+
 会话能力在真实原生扩展中绑定，不用 Node Global 冒充 Session：
 
 ```ts
@@ -81,7 +83,7 @@ plugin.addPreviewDirectory(directory, { default: true })
 
 ## Browser Entry 与懒界面
 
-Entry 默认导出普通同步函数即可；在函数返回前完成全部 `registerContribution(kind, name, definition)`。kind 支持 `application`、`composer-panel`、`settings-page`、`session-sidebar-tab`、`message-view`。Entry 只放元数据、loader、轻量页面状态和事件订阅；返回 disposer 清理自有订阅与资源。
+Entry 默认导出普通同步函数即可；在函数返回前完成全部注册。`registerContribution(kind, name, definition)` 支持 `application`、`composer-panel`、`settings-page`、`session-sidebar-tab`、`message-view`；输入区挂件与会话标题项分别使用 `registerWidget()`、`registerSessionHeaderItem()`，不能通过 `registerContribution` 注册。Entry 只放元数据、loader、轻量页面状态和事件订阅；返回 disposer 清理自有订阅与资源。
 
 Entry 不静态引入 React、ReactDOM、UI、CSS 或大型实现，也不等网络或动态 import 后再注册。UI 放在 `load()` 的动态模块，导出 `{ mount({ container, target, host, signal }) }`；Lazy Module 顶层不启动副作用。
 
@@ -107,6 +109,84 @@ Application 使用 `chrome: 'host'` 让宿主负责 Dialog、标题、关闭、
 
 界面继承宿主明暗主题与字号，布局使用 `rem`、合理内边距和自身滚动；窄屏与触控可用，不以裁切或只靠 hover 隐藏必要操作。按钮、表单、加载/错误/重试优先复用 `/react/base`；需要 Markdown 时才加载 `/react/markdown`。
 
+### 输入框上下方挂件
+
+在 Browser Entry 注册，不调用原生 `ctx.ui.setWidget()`：
+
+```js
+plugin.registerWidget('session-info', {
+  placement: 'aboveEditor',
+  load: () => import('./session-info.js').then((module) => module.default)
+})
+```
+
+同目录 `session-info.js` 是最小 Lazy View：
+
+```js
+export default {
+  mount({ container, target }) {
+    const element = document.createElement('p')
+    element.textContent = `当前会话：${target.source.sessionId}`
+    element.style.cssText = 'margin:0;overflow-wrap:anywhere'
+    container.append(element)
+    return () => element.remove()
+  }
+}
+```
+
+`placement` 只允许 `aboveEditor / belowEditor`，省略时是上方。Target 为 `{ kind: 'widget', source }`。挂件在对应聊天区可见时挂载，自然高度；没有内容时不预留空白。多个挂件按插件名和注册名稳定排列，不进入标题栏更多浮层。关闭或隐藏聊天区、Source 变化和插件重载会 Abort/dispose；重新挂载时按现有 Method/Push 建立数据基线。
+
+### 锚定浮层
+
+Lazy View 可从 `@jetcrab/pi-desk-sdk/react/base` 使用受控 `PluginPopover`。`trigger` 接收 React Element，其他内容作为 children；宿主组件负责 Portal、锚定、视口约束和焦点，打开不会抢走输入焦点。悬停、短暂提示和业务状态由插件控制，不自行定位到宿主 DOM。
+
+```tsx
+const [open, setOpen] = useState(false)
+
+<PluginPopover
+  open={open}
+  onOpenChange={setOpen}
+  side="top"
+  trigger={<PluginButton>查看详情</PluginButton>}
+>
+  <div style={{ padding: '0.75rem' }}>当前内容</div>
+</PluginPopover>
+```
+
+`side` 默认 `bottom`，`align` 默认 `start`，`className` 用于自身浮层的布局。浮层维持指定方向并限制可用高度；长内容自行使用 `PluginScroll`。调用方关闭或卸载时清理自己的计时器、Observer 和订阅。此组件需要支持该导出的宿主 Host Runtime，不能只更新插件依赖后向旧宿主请求。
+
+### 会话标题右侧条目
+
+`inline` 和 `overflow` 必须分别声明，可以独立选择普通按钮或自定义视图：
+
+```js
+const showSession = {
+  type: 'action',
+  icon: { type: 'builtin', name: 'file' },
+  label: '会话信息',
+  onSelect({ source, host }) {
+    host.notify({ level: 'info', title: '当前会话', description: source.sessionId })
+  }
+}
+
+plugin.registerSessionHeaderItem('session-info', {
+  inline: {
+    type: 'custom',
+    minWidthRem: 6,
+    load: () => import('./session-info.js').then((module) => module.default)
+  },
+  overflow: showSession
+})
+```
+
+- `action` 只接受固定 `icon`、`label`、`onSelect({ source, host, signal })`，不提供动态图标、文字或状态订阅。宿主显示图标加文字，异步操作期间防止重复点击；失败记录局部错误，失效后的回调不得继续使用旧 Host。信号属于该展示生命周期，不会回滚服务端已经产生的副作用。
+- `custom` 只提供 `load()`，宿主不包装点击回调。inline custom 必须额外声明正数 `minWidthRem`，单位为 `rem`；宿主按此预留可用宽度，不通过重复挂载业务视图测量。自定义内容应适应获得的容器，不能靠超宽 DOM 挤占标题。overflow custom 不声明宽度。
+- 自定义 Target 为 `{ kind: 'session-header-item', source, presentation: 'inline' | 'overflow' }`。两种表现可以使用不同模块，也可以复用同一个 `{ mount }`；loader 分别按表现缓存和重试。可复用上面的 `session-info.js`，或使用公共 React/UI 构建交互视图。
+- 标题项按插件名和注册名稳定排列；宽度不足时从末尾收进更多，宿主保留标题及必要操作。普通按钮选择后关闭更多；自定义区域内点击不会被转发，也不会自动关闭更多。Escape 或外部点击关闭浮层，键盘与触控均可操作。
+- 收纳会卸载 inline 自定义视图；只有更多打开时才挂载 overflow 自定义视图，关闭后释放。动态状态与运行/停止等复杂交互由自定义视图自行实现；业务状态归插件运行态，不归 mount，也不能只存于会被卸载的组件局部状态。卸载只清理视图资源，不停止项目进程。
+
+两种注册均限定 Browser Entry 同步阶段，名称规则与其他贡献相同。它们需要支持对应方法的宿主和 SDK；旧宿主缺少能力时禁用这项入口，不使用 `registerContribution` 别名或访问宿主 DOM 代替。现有 `composer-panel` 仍是人工打开的会话弹窗，不是上下方挂件。
+
 ### 侧栏顶部操作
 
 `session-sidebar-tab` 的 Lazy `mount({ target, host })` 内可为当前 Tab 设置顶部右侧按钮：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetcrab/pi-desk",
-  "version": "1.1.20-dev",
+  "version": "1.1.21",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -70,7 +70,7 @@
     "viewerjs": "^1.11.8",
     "ws": "^8.21.3",
     "zod": "^4.4.3",
-    "@jetcrab/pi-desk-sdk": "^1.1.7-dev"
+    "@jetcrab/pi-desk-sdk": "^1.1.8"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "1.2.0",
@@ -112,7 +112,7 @@
     "build:plugin-host-runtime": "pnpm --filter @jetcrab/pi-desk-sdk build",
     "start": "node bin/pi-desk.js --no-open",
     "test:package": "node --test tests/l4-pi-desk-package.test.mjs",
-    "test:pidesk": "node --import tsx --test tests/l4-pidesk-command.test.ts tests/l2-plugin-commands.test.ts tests/l4-pidesk-session-reload.test.ts tests/l4-pidesk-runtime.test.ts tests/l4-pidesk-runtime-bundle.test.mjs tests/l4-pidesk-docs.test.mjs tests/l4-pidesk-installed-runners.test.mjs tests/l4-pidesk-package-maintenance.test.ts tests/l4-pidesk-release-gate.test.mjs tests/l4-pi-desk-process-tree.test.mjs tests/l4-pi-runner-process.test.ts tests/l4-pi-global-runtime.test.mjs tests/l4-pi-desk-supervisor-cli.test.mjs",
+    "test:pidesk": "node --import tsx --test --test-concurrency=1 tests/l4-pidesk-command.test.ts tests/l2-plugin-commands.test.ts tests/l4-pidesk-session-reload.test.ts tests/l4-pidesk-runtime.test.ts tests/l4-pidesk-runtime-bundle.test.mjs tests/l4-pidesk-docs.test.mjs tests/l4-pidesk-installed-runners.test.mjs tests/l4-pidesk-package-maintenance.test.ts tests/l4-pidesk-release-gate.test.mjs tests/l4-pi-desk-process-tree.test.mjs tests/l4-pi-runner-process.test.ts tests/l4-pi-global-runtime.test.mjs tests/l4-pi-desk-supervisor-cli.test.mjs",
     "test:app-websocket": "pnpm build && node --import tsx --test tests/l2-chat-state.test.ts tests/l2-workbench-chat-repository.test.ts tests/l2-workbench-chat.test.ts tests/l2-workbench-layout.test.ts tests/l2-work-session-column-layout.test.ts tests/l2-work-session-update.test.ts tests/l1-app-websocket.test.mjs",
     "lint": "eslint .",
     "lint:production": "eslint . --ignore-pattern \"apps/desktop/**\" --ignore-pattern \"**/tests/**\" --ignore-pattern \"**/__tests__/**\" --ignore-pattern \"**/*.test.*\" --ignore-pattern \"**/*.spec.*\"",

package/src/app/page.tsx

@@ -1,5 +1,10 @@
 import { L1HomePage } from '@client/l1_entry/pages/l1-home-page'
+import { L1AppRuntimeProvider } from '@client/l1_entry/providers/l1-app-runtime-provider'
 
 export default function Home(): React.JSX.Element {
-  return <L1HomePage />
+  return (
+    <L1AppRuntimeProvider>
+      <L1HomePage />
+    </L1AppRuntimeProvider>
+  )
 }

package/src/app/project-preview/page.tsx

@@ -0,0 +1,10 @@
+import { Suspense } from 'react'
+import { L1ProjectPreviewPage } from '@client/l1_entry/pages/l1-project-preview-page'
+
+export default function ProjectPreview(): React.JSX.Element {
+  return (
+    <Suspense>
+      <L1ProjectPreviewPage />
+    </Suspense>
+  )
+}

package/src/client/l1_entry/pages/l1-home-page.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import { useCallback, useEffect, useMemo, type ComponentProps } from 'react'
+import { buildL2ProjectPreviewHref } from '@common/l2_biz/project-preview/l2-project-preview-navigation'
 import { L2TerminalBiz } from '@client/l2_biz/terminal/l2-terminal-biz'
 import { L2TerminalWorkspace } from '@client/l2_biz/terminal/l2-terminal-workspace'
 import { useL4PluginHost } from '@client/l4_foundation/plugin-host/l4-plugin-host-context'
@@ -12,6 +13,8 @@ import { L2PluginManagement } from '@client/l2_biz/plugin-host/l2-plugin-managem
 import { createL2PluginManagementBiz } from '@client/l2_biz/plugin-host/l2-plugin-management-biz'
 import { L2PluginSessionSidebarTab } from '@client/l2_biz/plugin-host/l2-plugin-session-sidebar-tab'
 import { L2PluginSettingsPage } from '@client/l2_biz/plugin-host/l2-plugin-settings-page'
+import { L2PluginWidgets } from '@client/l2_biz/plugin-host/l2-plugin-widgets'
+import { L2PluginSessionHeader } from '@client/l2_biz/plugin-host/l2-plugin-session-header'
 import { L2Settings } from '@client/l2_biz/settings/l2-settings'
 import { L2PiSettings } from '@client/l2_biz/pi-settings/l2-pi-settings'
 import { createL2TaskCenterBiz } from '@client/l2_biz/task-center/l2-task-center-biz'
@@ -61,6 +64,28 @@ function renderPluginComposerPanel(
   )
 }
 
+function renderPluginWidgets(
+  input: Parameters<WorkbenchProps['renderPluginWidgets']>[0]
+): React.JSX.Element {
+  return (
+    <L2PluginWidgets
+      key={`${input.source.workId}:${input.source.sessionId}:${input.source.branchId}:${input.placement}`}
+      {...input}
+    />
+  )
+}
+
+function renderPluginSessionHeader(
+  input: Parameters<WorkbenchProps['renderPluginSessionHeader']>[0]
+): React.JSX.Element {
+  return (
+    <L2PluginSessionHeader
+      key={`${input.source.workId}:${input.source.sessionId}:${input.source.branchId}`}
+      {...input}
+    />
+  )
+}
+
 function renderPluginSettingsPage(
   input: Parameters<SettingsProps['renderPluginSettingsPage']>[0]
 ): React.JSX.Element {
@@ -158,6 +183,9 @@ export function L1HomePage(): React.JSX.Element {
       onTerminalReady={terminalBiz.connected}
       onTerminalDisconnected={terminalBiz.disconnected}
       onOpenTerminal={terminalBiz.open}
+      onOpenProjectPreviewWindow={(cwd) => {
+        window.open(buildL2ProjectPreviewHref(cwd), '_blank', 'noopener,noreferrer')
+      }}
       renderTerminalWorkspace={renderTerminalWorkspace}
       listPluginManagement={pluginManagementBiz.list}
       subscribePluginManagementChanges={pluginManagementBiz.subscribeChanges}
@@ -169,6 +197,8 @@ export function L1HomePage(): React.JSX.Element {
       renderPluginApplication={renderPluginApplication}
       renderPluginSessionSidebarTab={renderPluginSessionSidebarTab}
       renderPluginComposerPanel={renderPluginComposerPanel}
+      renderPluginWidgets={renderPluginWidgets}
+      renderPluginSessionHeader={renderPluginSessionHeader}
       renderSettings={renderSettings}
       renderTaskSummary={renderTaskSummary}
       renderTaskMenu={renderTaskMenu}

package/src/client/l1_entry/pages/l1-project-preview-page.tsx

@@ -0,0 +1,33 @@
+'use client'
+
+import { useCallback, useEffect, useRef } from 'react'
+import { useRouter, useSearchParams } from 'next/navigation'
+import { L2BuildLoginHref } from '@common/l2_biz/auth/l2-auth-return-to'
+import { buildL2ProjectPreviewHref } from '@common/l2_biz/project-preview/l2-project-preview-navigation'
+import { useL4ClientId } from '@client/l4_foundation/lib/l4-client-id'
+import { L2ProjectPreviewPage } from '@client/l2_biz/project-preview/l2-project-preview-page'
+
+export function L1ProjectPreviewPage(): React.JSX.Element {
+  const clientId = useL4ClientId()
+  const params = useSearchParams()
+  const router = useRouter()
+  const cwd = params.get('cwd')?.trim() || null
+  const redirecting = useRef(false)
+  const onUnauthorized = useCallback((): void => {
+    if (redirecting.current) return
+    redirecting.current = true
+    window.location.assign(L2BuildLoginHref(window.location.pathname + window.location.search))
+  }, [])
+  useEffect(() => {
+    const name = cwd?.replaceAll('\\', '/').split('/').filter(Boolean).at(-1)
+    document.title = name ? `${name} · Pi Desk` : 'Pi Desk'
+  }, [cwd])
+  return (
+    <L2ProjectPreviewPage
+      clientId={clientId}
+      cwd={cwd}
+      onUnauthorized={onUnauthorized}
+      onSelect={(directory) => router.push(buildL2ProjectPreviewHref(directory))}
+    />
+  )
+}

package/src/client/l1_entry/providers/l1-app-providers.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import type { ReactNode } from 'react'
+import { useState, type ReactNode } from 'react'
 import type { HostSettingsSnapshot } from '@jetcrab/pi-desk-sdk/settings'
 import { L2_AUTH_MESSAGES } from '@common/l2_biz/auth/l2-auth-messages'
 import { L2_CAPABILITY_MODE_MESSAGES } from '@common/l2_biz/capability-modes/l2-capability-mode-messages'
@@ -22,7 +22,8 @@ import { L4RegionProvider } from '@client/l4_foundation/locale/l4-region-provide
 import { L4RegionNotice } from '@client/l4_foundation/locale/l4-region-notice'
 import { L4AppToastProvider } from '@client/l4_foundation/ui/l4-app-toast'
 import { TooltipProvider } from '@client/l4_foundation/ui/shadcn/tooltip'
-import { L1AppRuntimeProvider } from './l1-app-runtime-provider'
+import { createL4BrowserUuid } from '@client/l4_foundation/lib/l4-browser-uuid'
+import { L4ClientIdContext } from '@client/l4_foundation/lib/l4-client-id'
 
 const resources = {
   en: {
@@ -66,20 +67,22 @@ export function L1AppProviders({
   children,
   initialSettings
 }: L1AppProvidersProps): React.JSX.Element {
+  const [clientId] = useState(createL4BrowserUuid)
+
   return (
-    <L4ThemeProvider>
-      <L4DisplaySizeProvider>
-        <L4CodePreferencesProvider>
-          <L4RegionProvider resources={resources} initialSettings={initialSettings}>
-            <L4AppToastProvider>
-              <L4RegionNotice />
-              <L1AppRuntimeProvider>
+    <L4ClientIdContext.Provider value={clientId}>
+      <L4ThemeProvider>
+        <L4DisplaySizeProvider>
+          <L4CodePreferencesProvider>
+            <L4RegionProvider resources={resources} initialSettings={initialSettings}>
+              <L4AppToastProvider>
+                <L4RegionNotice />
                 <TooltipProvider>{children}</TooltipProvider>
-              </L1AppRuntimeProvider>
-            </L4AppToastProvider>
-          </L4RegionProvider>
-        </L4CodePreferencesProvider>
-      </L4DisplaySizeProvider>
-    </L4ThemeProvider>
+              </L4AppToastProvider>
+            </L4RegionProvider>
+          </L4CodePreferencesProvider>
+        </L4DisplaySizeProvider>
+      </L4ThemeProvider>
+    </L4ClientIdContext.Provider>
   )
 }

package/src/client/l1_entry/providers/l1-app-runtime-provider.tsx

@@ -3,7 +3,7 @@
 import { useEffect, useRef, useState, type PropsWithChildren } from 'react'
 import { createL2PluginHostRuntime } from '@client/l2_biz/plugin-host/l2-plugin-host-runtime'
 import { L2ProjectPreviewDialog } from '@client/l2_biz/project-preview/l2-project-preview-dialog'
-import { createL4BrowserUuid } from '@client/l4_foundation/lib/l4-browser-uuid'
+import { useL4ClientId } from '@client/l4_foundation/lib/l4-client-id'
 import { L4PluginHostContext } from '@client/l4_foundation/plugin-host/l4-plugin-host-context'
 import type { L4PluginHostRuntime } from '@client/l4_foundation/plugin-host/l4-plugin-host-runtime'
 import { useL4AppToast } from '@client/l4_foundation/ui/l4-app-toast'
@@ -22,8 +22,8 @@ interface L1AppRuntimeOwner {
 
 export function L1AppRuntimeProvider({ children }: PropsWithChildren): React.JSX.Element {
   const toast = useL4AppToast()
+  const clientId = useL4ClientId()
   const [runtime] = useState<L1AppRuntimeOwner>(() => {
-    const clientId = createL4BrowserUuid()
     const owner = createL4AppSocketClient(clientId)
     return {
       clientId,

package/src/client/l2_biz/auth/l2-login-biz.ts

@@ -1,4 +1,5 @@
 import type { L4ApiResponse } from '@common/l4_foundation/http/l4-api-response-contract'
+import { L2ResolveAuthReturnTo } from '@common/l2_biz/auth/l2-auth-return-to'
 import { l4LocalizedErrorMessage } from '@client/l4_foundation/locale/l4-localized-error'
 import {
   L2AuthLoginRequestSchema,
@@ -44,4 +45,6 @@ export async function loginL2Auth(clientId: string, input: L2AuthLoginRequest):
     )
   }
   L2AuthLoginResponseSchema.parse(envelope.data)
+  const returnTo = new URLSearchParams(window.location.search).get('returnTo')
+  window.location.replace(L2ResolveAuthReturnTo(returnTo))
 }

package/src/client/l2_biz/auth/l2-login.tsx

@@ -3,7 +3,7 @@
 import { ArrowRightIcon, LanguagesIcon, LoaderCircleIcon } from 'lucide-react'
 import { useEffect, useRef, useState, type FormEvent } from 'react'
 import { useTranslation } from 'react-i18next'
-import { useL4AppSocket } from '@client/l4_foundation/realtime/app-socket/l4-app-socket'
+import { useL4ClientId } from '@client/l4_foundation/lib/l4-client-id'
 import { useL4Region } from '@client/l4_foundation/locale/l4-region-provider'
 import { setL4RegionDisplayLocale } from '@client/l4_foundation/locale/l4-region-store'
 import { Button } from '@client/l4_foundation/ui/shadcn/button'
@@ -23,7 +23,7 @@ import styles from './l2-login.module.css'
 export function L2Login(): React.JSX.Element {
   const { t } = useTranslation('auth')
   const region = useL4Region()
-  const { clientId } = useL4AppSocket()
+  const clientId = useL4ClientId()
   const [password, setPassword] = useState('')
   const [error, setError] = useState<string | null>(null)
   const [submitting, setSubmitting] = useState(false)
@@ -43,7 +43,6 @@ export function L2Login(): React.JSX.Element {
     setSubmitting(true)
     try {
       await loginL2Auth(clientId, { password })
-      window.location.replace('/')
     } catch (cause) {
       submittingRef.current = false
       setError(cause instanceof Error ? cause.message : t('loginFailed'))

package/src/client/l2_biz/plugin-host/l2-plugin-capability-details.tsx

@@ -72,7 +72,9 @@ const CONTRIBUTION_LABELS: Readonly<Record<L4PluginBrowserContributionDescriptor
     'composer-panel': 'contributionComposer',
     'settings-page': 'contributionSettings',
     'message-view': 'contributionMessage',
-    'session-sidebar-tab': 'contributionSidebar'
+    'session-sidebar-tab': 'contributionSidebar',
+    widget: 'contributionWidget',
+    'session-header-item': 'contributionSessionHeader'
   }
 
 export type L2PluginCapabilityTagTone = 'neutral' | 'prompt' | 'dynamic' | 'override'
@@ -567,6 +569,9 @@ function PromptResources({
 function contributionDescription(descriptor: L4PluginBrowserContributionDescriptor): string {
   if (descriptor.kind === 'message-view') return descriptor.viewKey
   if (descriptor.kind === 'application') return descriptor.title
+  if (descriptor.kind === 'widget' || descriptor.kind === 'session-header-item') {
+    return descriptor.contributionName
+  }
   return descriptor.label
 }
 

package/src/client/l2_biz/plugin-host/l2-plugin-contribution-host.tsx

@@ -8,7 +8,9 @@ import type {
   BrowserComposerPanelTarget,
   BrowserMessageViewTarget,
   BrowserSessionSidebarTabTarget,
+  BrowserSessionHeaderItemTarget,
   BrowserSettingsPageTarget,
+  BrowserWidgetTarget,
   PluginDisposer
 } from '@jetcrab/pi-desk-sdk/browser'
 import {
@@ -16,11 +18,17 @@ import {
   useL4PluginRegistry
 } from '@client/l4_foundation/plugin-host/l4-plugin-host-context'
 import { Button } from '@client/l4_foundation/ui/shadcn/button'
+import {
+  Popover,
+  PopoverContent,
+  PopoverTitle,
+  PopoverTrigger
+} from '@client/l4_foundation/ui/shadcn/popover'
 import { L4ErrorDetails } from '@client/l4_foundation/ui/l4-error-details'
 import { cn } from '@client/l4_foundation/lib/l4-utils'
 import type { L4PluginContributionKind } from '@client/l4_foundation/plugin-host/l4-plugin-host-runtime'
 
-type L2PluginContributionLayout = 'fill' | 'intrinsic'
+type L2PluginContributionLayout = 'fill' | 'intrinsic' | 'inline'
 
 interface L2PluginContributionHostProps {
   pluginName: string
@@ -32,6 +40,8 @@ interface L2PluginContributionHostProps {
     | BrowserSettingsPageTarget
     | BrowserMessageViewTarget
     | BrowserSessionSidebarTabTarget
+    | BrowserWidgetTarget
+    | BrowserSessionHeaderItemTarget
   targetKey?: string
   className?: string
   layout?: L2PluginContributionLayout
@@ -57,6 +67,7 @@ export function L2PluginContributionHost({
   const containerRef = useRef<HTMLDivElement | null>(null)
   const targetRef = useRef(target)
   const mountIdentity = targetKey ?? target
+  const presentation = target.kind === 'session-header-item' ? target.presentation : undefined
   const [attempt, setAttempt] = useState(0)
   const [state, setState] = useState<MountState>({ status: 'loading' })
 
@@ -86,7 +97,9 @@ export function L2PluginContributionHost({
       mountContainer.className =
         layout === 'intrinsic'
           ? 'inline-block min-h-0 min-w-0 align-top'
-          : 'h-full min-h-0 w-full min-w-0'
+          : layout === 'inline'
+            ? 'min-w-0 w-full'
+            : 'h-full min-h-0 w-full min-w-0'
       hostContainer.append(mountContainer)
       return runtime.mountContribution({
         pluginName,
@@ -163,13 +176,18 @@ export function L2PluginContributionHost({
       })
       return
     }
-    const loadState = runtime.getContributionLoadState(pluginName, kind, contributionName)
+    const loadState = runtime.getContributionLoadState(
+      pluginName,
+      kind,
+      contributionName,
+      presentation
+    )
     if (loadState.status !== 'failed') {
       setAttempt((current) => current + 1)
       return
     }
     setState({ status: 'loading' })
-    void runtime.retryContribution(pluginName, kind, contributionName).then(
+    void runtime.retryContribution(pluginName, kind, contributionName, presentation).then(
       () => {
         if (runtime.getEntryState(pluginName) === entryState) setAttempt((current) => current + 1)
       },
@@ -199,7 +217,9 @@ export function L2PluginContributionHost({
               'max-h-[calc(100dvh-7rem)] max-w-[calc(100dvw-3rem)] overflow-auto max-sm:max-h-[calc(100dvh-5rem)] max-sm:max-w-[calc(100dvw-2rem)]',
               intrinsicFallbackClass
             )
-          : 'h-full w-full',
+          : layout === 'inline'
+            ? 'w-full'
+            : 'h-full w-full',
         className
       )}
     >
@@ -211,17 +231,58 @@ export function L2PluginContributionHost({
         className={cn(
           layout === 'intrinsic'
             ? 'inline-block min-h-0 min-w-0 align-top'
-            : 'h-full min-h-0 w-full min-w-0',
+            : layout === 'inline'
+              ? 'w-full min-w-0'
+              : 'h-full min-h-0 w-full min-w-0',
           state.status === 'error' && 'hidden'
         )}
       />
       {state.status === 'loading' ? (
-        <div className="absolute inset-0 flex items-center justify-center bg-popover p-6 text-sm text-muted-foreground">
-          <LoaderCircleIcon className="mr-2 size-4 animate-spin" />
-          {t('viewLoading')}
+        <div
+          role="status"
+          className={cn(
+            'flex items-center text-sm text-muted-foreground',
+            layout === 'inline'
+              ? 'min-h-7 gap-1 py-1'
+              : 'absolute inset-0 justify-center bg-popover p-6'
+          )}
+        >
+          <LoaderCircleIcon className="mr-2 size-4 shrink-0 animate-spin" />
+          <span className="min-w-0 truncate">{t('viewLoading')}</span>
         </div>
       ) : null}
-      {state.status === 'error' ? (
+      {state.status === 'error' && layout === 'inline' ? (
+        <div role="alert" className="min-w-0">
+          <Popover>
+            <PopoverTrigger
+              render={
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon-sm"
+                  aria-label={t('viewFailed')}
+                  title={t('viewFailed')}
+                  className="text-destructive"
+                />
+              }
+            >
+              <AlertTriangleIcon className="size-4" />
+            </PopoverTrigger>
+            <PopoverContent align="start" finalFocus>
+              <PopoverTitle>{t('viewFailed')}</PopoverTitle>
+              <L4ErrorDetails error={state.error}>
+                <p className="text-xs text-muted-foreground [overflow-wrap:anywhere]">
+                  {pluginName} · {kind} · {contributionName}
+                </p>
+              </L4ErrorDetails>
+              <Button type="button" variant="outline" size="sm" onClick={retry}>
+                <RefreshCwIcon />
+                {t('retry')}
+              </Button>
+            </PopoverContent>
+          </Popover>
+        </div>
+      ) : state.status === 'error' ? (
         <div
           role="alert"
           className={cn(

package/src/client/l2_biz/plugin-host/l2-plugin-management-controls.tsx

@@ -57,6 +57,15 @@ export function L2PluginManagementControls({
         >
           {t('retry')}
         </Button>
+      ) : plugin.status === 'failed' ? (
+        <Button
+          size="sm"
+          variant="outline"
+          disabled={disabled || pending}
+          onClick={() => onAction('reload')}
+        >
+          {t('reloadOne')}
+        </Button>
       ) : browserError && plugin.pluginName ? (
         <Button
           size="sm"

package/src/client/l2_biz/plugin-host/l2-plugin-session-header-layout.ts

@@ -0,0 +1,18 @@
+export function calculateL2PluginSessionHeaderInlineCount(
+  widths: readonly number[],
+  availableWidth: number,
+  moreWidth: number,
+  gap: number
+): number {
+  const total = widths.reduce((sum, width) => sum + width, 0) + Math.max(0, widths.length - 1) * gap
+  if (total <= availableWidth) return widths.length
+
+  let used = moreWidth
+  let count = 0
+  for (const width of widths) {
+    if (used + gap + width > availableWidth) break
+    used += gap + width
+    count += 1
+  }
+  return count
+}