weifuwu 0.94.0 → 0.95.0

package/dist/level5/client/components/Menubar/Menubar.ts

@@ -0,0 +1,164 @@
+/** Menubar：水平菜单栏：←→ 切换 + ↓ 展开（shadcn Menubar）（showcase /components/menubar） */
+import type {Component, VNodeChild} from '../../../../level6/client/vdom/index.ts'
+import { createClientBrowser } from '../../../../level6/client/vdom/index.ts'
+import type { UIContext } from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+
+export interface MenubarItem {
+  key: string
+  label: string
+  icon?: VNodeChild
+  shortcut?: string
+  disabled?: boolean
+  onSelect?: ()=> void
+}
+
+export interface MenubarMenu {
+  key: string
+  label: string
+  items?: MenubarItem[]
+  disabled?: boolean
+}
+
+export interface MenubarProps {
+  menus?: MenubarMenu[]
+  'aria-label'?: string
+}
+
+/** 水平菜单栏（对应 shadcn Menubar）：trigger 点击展开下拉，←→ 切换菜单，Escape 关闭。
+ * 裁剪（CS-05，见 docs/client.md）：hover 展开、子菜单、可拖拽菜单。 */
+export const Menubar: Component<MenubarProps> = (_init, ctx)=> {
+  // 浏览器环境（ctx.browser 优先，测试/无注入环境 fallback createClientBrowser——自研惰性防御）
+  const _browser = ctx.browser ?? createClientBrowser()
+  // ── mount（只一次）──
+  let openMenu: string | null = null
+  const highlight = ctx.ui.useSignal(0)
+  let triggerEls: (HTMLElement | null)[] = []
+
+  // 闭包捕获索引 + Map 缓存稳定（React useCallback 等价物）：不读 dataset（根治顺序依赖）
+  const triggerRefs = new Map<number, (el: HTMLElement | null)=> void>()
+  const triggerRefFor = (i: number)=> {
+    let fn = triggerRefs.get(i)
+    if (!fn) {
+      fn = (el)=> { if (el) triggerEls[i] = el }
+      triggerRefs.set(i, fn)
+    }
+    return fn
+  }
+
+  // menus 由 render 阶段更新（闭包读最新）
+  let menus: MenubarMenu[] = []
+
+  // 命令式弹窗（唯一形态 openPopup）：document 级外部点击/Escape + 面板定位/
+  // 视口 clamp。trigger 点击仍走自定义 toggle（多 trigger 共用一个面板）
+  /** 命令式句柄（唯一形态——openPopup——组件内部同步样板） */
+  let handle: import('../../../../level3/vdom/hooks/popup-manager.ts').PopupHandle | null = null
+  const syncPanel = (panel: import('../../../../level6/client/vdom/index.ts').VNode | null): void => {
+    if (openMenu && panel && !handle)
+      handle = ctx.ui.openPopup({
+        anchor: ()=> {
+          const i = menus.findIndex(m => m.key === openMenu)
+          return i >= 0 ? triggerEls[i] : null
+        },
+        placement: 'bottom',
+        center: false,
+        gap: 4,
+        content: ()=> panel,
+        onClose: ()=> { handle = null; if (openMenu) close() },
+      })
+    else if (!openMenu && handle) { handle.close(); handle = null }
+    else if (handle) handle.update(panel)
+  }
+
+  const close = ()=> {
+    if (openMenu !== null) {
+      openMenu = null
+      ctx.render()
+    }
+  }
+
+  const toggle = (key: string)=> {
+    openMenu = openMenu === key ? null : key
+    highlight.set(0)
+    ctx.render()
+  }
+
+  return (props)=> {
+    const { menus: propMenus = [], 'aria-label': ariaLabel } = props
+    menus = propMenus
+
+    const onKeyDown = (e: any)=> {
+      if (e.key === 'Escape') {
+        close()
+        return
+      }
+      if (e.key !== 'ArrowRight' && e.key !== 'ArrowLeft') return
+      if (openMenu) { close(); return }
+      const current = (_browser?.activeElement() ?? null)
+      const idx = triggerEls.indexOf(current as HTMLElement)
+      if (idx < 0) return
+      e.preventDefault()
+      const next = e.key === 'ArrowRight'
+        ? (idx + 1) % menus.length
+        : (idx - 1 + menus.length) % menus.length
+      triggerEls[next]?.focus()
+    }
+
+    const triggers = menus.map((menu, i)=> {
+      const open = openMenu === menu.key
+      return h('button', {
+        type: 'button',
+        class: [
+          'wf-menubar-trigger',
+          open ? 'wf-menubar-trigger--open' : '',
+          menu.disabled ? 'wf-menubar-trigger--dis' : '',
+        ].filter(Boolean).join(' '),
+        key: menu.key,
+        ref: triggerRefFor(i),
+        'aria-haspopup': 'menu',
+        'aria-expanded': open,
+        onClick: menu.disabled ? undefined : ()=> toggle(menu.key),
+        onKeyDown: (e: any)=> {
+          if (e.key === 'ArrowDown' || e.key === 'Enter') {
+            e.preventDefault()
+            if (!menu.disabled) toggle(menu.key)
+          }
+        },
+      }, menu.label)
+    })
+
+    const openMenuData = menus.find(m => m.key === openMenu)
+
+    // 命令式弹窗（唯一形态 openPopup——openMenuData 驱动）
+    const panel = openMenuData ? h('div', {
+      class: 'wf-menubar-panel',
+      role: 'menu',
+    }, (openMenuData.items ?? []).map((item, i)=>
+      h('button', {
+        type: 'button',
+        class: [
+          'wf-menubar-item',
+          highlight.get() === i ? 'wf-menubar-item--hl' : '',
+          item.disabled ? 'wf-menubar-item--dis' : '',
+        ].filter(Boolean).join(' '),
+        key: item.key,
+        role: 'menuitem',
+        onClick: item.disabled ? undefined : ()=> { item.onSelect?.(); close() },
+        onMouseEnter: ()=> { if (!item.disabled) highlight.set(i) },
+      }, [
+        h('span', { class: 'wf-menubar-item-label' }, item.label),
+        item.shortcut ? h('kbd', { class: 'wf-menubar-shortcut' }, item.shortcut) : null,
+      ].filter(Boolean))
+    )) : null
+
+    // 命令式同步（受控 + 内容更新——每次渲染恒调用）
+    syncPanel(panel)
+
+    return h('div', {
+      class: 'wf-menubar',
+      role: 'menubar',
+      'aria-label': ariaLabel,
+      onKeyDown,
+    }, triggers)
+  }
+}

package/dist/level5/client/components/MessageBubble/MessageBubble.css

@@ -0,0 +1,33 @@
+/* weifuwu/client/components — MessageBubble（依赖 layout wf-bubble 原语） */
+
+.wf-bubble--error {
+  border: var(--wf-border-width) solid var(--wf-color-error-text);
+  background: var(--wf-color-error-bg);
+  color: var(--wf-color-error-text);
+}
+
+.wf-bubble--streaming {
+  border-right: 3px solid var(--wf-color-primary);
+  border-right-color: var(--wf-color-primary);
+  /* 1s 光标式平缓闪烁（≤1Hz，远低于 3Hz 光敏阈值）；reduced-motion 下基线降为 0.01ms */
+  animation: wf-bubble-blink var(--wf-dur-blink) var(--wf-ease-in-out) infinite;
+}
+
+@keyframes wf-bubble-blink {
+  0%, 100% { border-right-color: var(--wf-color-primary); }
+  50% { border-right-color: var(--wf-color-primary-bg); }
+}
+
+.wf-bubble-body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wf-gap-xs);
+}
+
+.wf-bubble-actions {
+  display: flex;
+  gap: var(--wf-gap-xs);
+  align-items: center;
+}
+/* ── 语义标记类（DOM 钩子——无样式：测试定位/用户扩展——:where 零优先级显式声明） ── */
+:where(.wf-bubble-text) {}

package/dist/level5/client/components/MessageBubble/MessageBubble.d.ts

@@ -0,0 +1,21 @@
+/** MessageBubble：消息气泡：user/assistant + streaming/error 状态 + actions（showcase /components/messagebubble） */
+/**
+ * weifuwu/client/components — MessageBubble
+ *
+ * 独立消息气泡（从 AiChat 气泡层抽取，业务聊天页复用）。
+ * 复用 layout 的 wf-bubble 原语：user → --own，assistant → --ai。
+ * content 支持文本或任意 VNode（可与 Markdown 组合）。
+ * 裁剪（CS-05，见 docs/client.md）：不做打字指示动画（Loading 已有）。
+ */
+import type { Component, VNodeChild } from '../../../../level6/client/vdom/index.ts';
+export type MessageBubbleRole = 'user' | 'assistant';
+export type MessageBubbleStatus = 'complete' | 'streaming' | 'error';
+export interface MessageBubbleProps {
+    content?: VNodeChild;
+    role: MessageBubbleRole;
+    status?: MessageBubbleStatus;
+    /** 气泡尾部操作区（重试/复制按钮等，VNode 或数组） */
+    actions?: VNodeChild;
+    className?: string;
+}
+export declare const MessageBubble: Component<MessageBubbleProps>;

package/dist/level5/client/components/MessageBubble/MessageBubble.ts

@@ -0,0 +1,49 @@
+/** MessageBubble：消息气泡：user/assistant + streaming/error 状态 + actions（showcase /components/messagebubble） */
+/**
+ * weifuwu/client/components — MessageBubble
+ *
+ * 独立消息气泡（从 AiChat 气泡层抽取，业务聊天页复用）。
+ * 复用 layout 的 wf-bubble 原语：user → --own，assistant → --ai。
+ * content 支持文本或任意 VNode（可与 Markdown 组合）。
+ * 裁剪（CS-05，见 docs/client.md）：不做打字指示动画（Loading 已有）。
+ */
+
+import type {Component, VNodeChild} from '../../../../level6/client/vdom/index.ts'
+import type { UIContext } from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+
+export type MessageBubbleRole = 'user' | 'assistant'
+export type MessageBubbleStatus = 'complete' | 'streaming' | 'error'
+
+export interface MessageBubbleProps {
+  content?: VNodeChild
+  role: MessageBubbleRole
+  status?: MessageBubbleStatus
+  /** 气泡尾部操作区（重试/复制按钮等，VNode 或数组） */
+  actions?: VNodeChild
+  className?: string
+}
+
+export const MessageBubble: Component<MessageBubbleProps> = (_init, _ctx)=>
+  (props)=> {
+    const { content, role, status = 'complete', actions, className } = props
+
+    const roleClass = role === 'user' ? 'wf-bubble--own' : 'wf-bubble--ai'
+    const statusClass = status === 'error'
+      ? ' wf-bubble--error'
+      : status === 'streaming'
+        ? ' wf-bubble--streaming'
+        : ''
+
+    const body = actions
+      ? h('div', { class: 'wf-bubble-body' }, [
+          h('div', { class: 'wf-bubble-text' }, content),
+          h('div', { class: 'wf-bubble-actions' }, actions),
+        ])
+      : content
+
+    return h('div', {
+      class: `wf-bubble ${roleClass}${statusClass}${className ? ` ${className}` : ''}`,
+      role: status === 'error' ? 'alert' : undefined,
+    }, body)
+  }

package/dist/level5/client/components/Modal/Modal.css

@@ -0,0 +1,121 @@
+/* weifuwu/client/components — Modal */
+
+.wf-modal {
+  position: fixed;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: var(--wf-z-modal);
+}
+
+.wf-modal--enter .wf-modal-overlay {
+  animation: wf-modal-overlay-fadein var(--wf-dur-base) var(--wf-ease-out);
+}
+
+.wf-modal--exit .wf-modal-overlay {
+  animation: wf-modal-overlay-fadeout var(--wf-dur-base) var(--wf-ease-in) forwards;
+}
+
+@keyframes wf-modal-overlay-fadein {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+
+@keyframes wf-modal-overlay-fadeout {
+  from { opacity: 1; }
+  to   { opacity: 0; }
+}
+
+/* 内容独立动画（不随遮罩 opacity，避免父级 opacity 过渡延迟 backdrop-filter） */
+.wf-modal--enter .wf-modal-content {
+  animation: wf-modal-pop var(--wf-dur-base) var(--wf-ease-out);
+}
+
+.wf-modal--exit .wf-modal-content {
+  animation: wf-modal-unpop var(--wf-dur-base) var(--wf-ease-in) forwards;
+}
+
+@keyframes wf-modal-pop {
+  from { opacity: 0; transform: scale(0.96); }
+  to   { opacity: 1; transform: scale(1); }
+}
+
+@keyframes wf-modal-unpop {
+  from { opacity: 1; transform: scale(1); }
+  to   { opacity: 0; transform: scale(0.96); }
+}
+
+.wf-modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: var(--wf-overlay);
+  backdrop-filter: blur(var(--wf-overlay-blur));
+  -webkit-backdrop-filter: blur(var(--wf-overlay-blur));
+  z-index: -1;
+}
+
+.wf-modal-content {
+  background: var(--wf-color-bg-elevated);
+  border-radius: var(--wf-modal-radius,  var(--wf-radius-lg)); /* 浮层圆角矩阵：Modal 12（抬升语义） */
+  box-shadow: var(--wf-modal-shadow,  var(--wf-shadow-lg));
+  min-width: var(--wf-modal-width,  400px);
+  max-width: 90vw;
+  max-height: 80vh;
+  display: flex;
+  flex-direction: column;
+  z-index: 1;
+  transform-origin: center;
+width: 100%;
+    max-width: 100vw;
+    max-height: 85vh;
+    border-radius: var(--wf-radius-lg) var(--wf-radius-lg) 0 0;
+  min-width: min(var(--wf-modal-width,  400px), calc(100vw - 32px));
+    padding-bottom: env(safe-area-inset-bottom);
+}
+
+.wf-modal-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--wf-space-md) var(--wf-space-lg);
+  border-bottom: var(--wf-border-width) solid var(--wf-color-border);
+  font-size: var(--wf-font-size-lg);
+  font-weight: var(--wf-font-weight-semibold);
+}
+
+.wf-modal-close {
+  background: none;
+  border: none;
+  font-size: var(--wf-font-size-lg);
+  cursor: pointer;
+  color: var(--wf-color-text-secondary);
+  padding: var(--wf-space-xs);
+  line-height: 1;
+}
+.wf-modal-close:hover {
+  color: var(--wf-color-text);
+}
+
+.wf-modal-body {
+  padding: var(--wf-space-lg);
+  overflow-y: auto;
+  flex: 1;
+}
+
+.wf-modal-footer {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--wf-gap-sm);
+  padding: var(--wf-space-md) var(--wf-space-lg);
+  border-top: var(--wf-border-width) solid var(--wf-color-border);
+}
+
+/* ── 移动端适配（P2）：min-width 视口 clamp（修 375px 屏 400px 溢出）+ 小屏 bottom-sheet ── */
+
+
+@media (max-width: 639.98px) { /* 断点单源：--wf-bp-sm(640) - 0.02——与 min-width:640px 无缝对接（LAYOUT-PLAN W3·L10 哨兵） */
+  .wf-modal {
+    align-items: flex-end; /* bottom-sheet 形态 */
+  }
+}

package/dist/level5/client/components/Modal/Modal.d.ts

@@ -0,0 +1,23 @@
+/** Modal：自定义宽度 + closable 控制关闭按钮（showcase /components/modal） */
+/**
+ * weifuwu/client/components — Modal
+ *
+ * 行为面（2027-09 分层抽象 W2）：openPopup 生命周期/焦点 trap/滚动锁/Esc/
+ * 遮罩点击 → useOverlay 契约（手搓面消除——行为正确性结构性保证）。
+ * 组件只写皮：overlay（遮罩）+ content（面板）+ 关闭按钮/标题/footer。
+ */
+import type { Component, VNodeChild } from '../../../../level6/client/vdom/index.ts';
+export interface ModalProps {
+    open?: boolean;
+    title?: string;
+    onClose?: () => void;
+    children?: VNodeChild;
+    footer?: VNodeChild;
+    /** 自定义宽度，如 '500px'、'80%'，默认 400px */
+    width?: string;
+    /** 是否显示关闭按钮，默认 true */
+    closable?: boolean;
+    /** 点击遮罩是否关闭，默认 true（危险确认应设 false） */
+    maskClosable?: boolean;
+}
+export declare const Modal: Component<ModalProps>;

package/dist/level5/client/components/Modal/Modal.ts

@@ -0,0 +1,80 @@
+/** Modal：自定义宽度 + closable 控制关闭按钮（showcase /components/modal） */
+/**
+ * weifuwu/client/components — Modal
+ *
+ * 行为面（2027-09 分层抽象 W2）：openPopup 生命周期/焦点 trap/滚动锁/Esc/
+ * 遮罩点击 → useOverlay 契约（手搓面消除——行为正确性结构性保证）。
+ * 组件只写皮：overlay（遮罩）+ content（面板）+ 关闭按钮/标题/footer。
+ */
+
+import type {Component, VNodeChild} from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+import { Icon } from '../Icon/Icon.ts'
+
+export interface ModalProps {
+  open?: boolean
+  title?: string
+  onClose?: ()=> void
+  children?: VNodeChild
+  footer?: VNodeChild
+  /** 自定义宽度，如 '500px'、'80%'，默认 400px */
+  width?: string
+  /** 是否显示关闭按钮，默认 true */
+  closable?: boolean
+  /** 点击遮罩是否关闭，默认 true（危险确认应设 false） */
+  maskClosable?: boolean
+}
+
+export const Modal: Component<ModalProps> = (_props, ctx)=> {
+  // 行为契约（mount 期闭包——maskProps/panelProps/close/sync）
+  // positioning 'none'：.wf-modal 自己 inset:0 居中（CSS flex——不依赖锚点坐标）
+  const ov = ctx.ui.useOverlay({ role: 'dialog' })
+
+  return (props: ModalProps)=> {
+    const { open, title, onClose, children, footer, width, closable = true, maskClosable = true } = props
+    const ML = ctx?.i18n?.components?.Modal ?? {}
+
+    const overlay = h('div', {
+      ...ov.maskProps,
+      class: 'wf-modal-overlay',
+    })
+
+    const closeBtn = closable ? h('button', {
+      class: 'wf-modal-close',
+      onClick: onClose,
+      type: 'button',
+      'aria-label': ML.closeAria ?? '关闭',
+    }, h(Icon, { name: 'close' })) : null
+
+    const titleEl = title
+      ? h('div', { class: 'wf-modal-header' }, [title, closeBtn].filter(Boolean))
+      : null
+
+    const bodyEl = h('div', { class: 'wf-modal-body' }, children)
+    const footerEl = footer
+      ? h('div', { class: 'wf-modal-footer' }, footer)
+      : null
+
+    const content = h('div', {
+      class: 'wf-modal-content',
+      onClick: (e: Event)=> e.stopPropagation(),
+      style: width ? { minWidth: `min(${width}, calc(100vw - 32px))`, maxWidth: `min(${width}, calc(100vw - 32px))` } : undefined,
+    }, [titleEl, bodyEl, footerEl].filter(Boolean))
+
+    const root = h('div', {
+      ...ov.panelProps,
+      class: `wf-modal ${open ? 'wf-modal--enter' : 'wf-modal--exit'}`,
+      'aria-label': title ?? (ML.ariaLabel ?? '弹窗'),
+    }, [overlay, content])
+
+    // 渲染期同步（openPopup 生命周期——受控 + 内容更新——每次渲染恒调用）
+    ov.sync(()=> root, {
+      open: !!open,
+      onOpenChange: (v)=> { if (!v) onClose?.() },
+      maskClosable,
+      presence: true,
+    })
+
+    return null
+  }
+}

package/dist/level5/client/components/NavBar/NavBar.css

@@ -0,0 +1,43 @@
+/* weifuwu/client/components — NavBar 移动端顶栏（antd-mobile NavBar 对位） */
+
+.wf-nav-bar {
+  display: flex;
+  align-items: center;
+  gap: var(--wf-gap-xs);
+  min-height: 48px;
+  padding: var(--wf-space-xs) var(--wf-space-sm);
+  background: var(--wf-color-bg-secondary);
+  border-bottom: var(--wf-border-width) solid var(--wf-color-border);
+}
+
+/* sticky 常驻：滚动不丢导航入口（ap-topbar 实证）+ 刘海屏避让 */
+.wf-nav-bar--fixed {
+  position: sticky;
+  top: 0;
+  z-index: var(--wf-z-sticky);
+  padding-top: calc(4px + env(safe-area-inset-top, 0px));
+}
+
+.wf-nav-bar-side {
+  display: flex;
+  align-items: center;
+  gap: var(--wf-gap-xs);
+  min-width: 0;
+  flex-shrink: 0;
+  white-space: nowrap;
+}
+
+.wf-nav-bar-title {
+  flex: 1;
+  min-width: 0;
+  text-align: center;
+  font-size: var(--wf-font-size-base);
+  font-weight: var(--wf-font-weight-semibold);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.wf-nav-bar-title--left {
+  text-align: left;
+}

package/dist/level5/client/components/NavBar/NavBar.d.ts

@@ -0,0 +1,33 @@
+/** NavBar：移动端顶栏——left 槽（返回/菜单）+ 标题截断 + right 槽（antd-mobile NavBar 对位）（showcase /components/navbar） */
+/**
+ * weifuwu/client/components — NavBar 移动端顶栏（antd-mobile NavBar / MUI AppBar 对位）
+ *
+ * 移动端 App 应用外壳顶栏：left 槽（返回/菜单按钮）+ 标题（单行截断）+ right 槽
+ * （操作按钮）——消费侧手搓实证 agent-platform `ap-topbar`
+ * （apps/agent-platform/ui/components/AppLayout.tsx:142——汉堡 + 品牌 + 设置）。
+ *
+ * 与近义组件区分（易混对照——components-map）：
+ * - PageHeader = 桌面**页内容**标题 + 操作区（页面内）；NavBar = 移动端**外壳**顶栏
+ * - AppShell/Layout = 整壳（侧栏+内容）；NavBar 独立组件——应用层组合
+ *   （与 TabBar 独立同构——顶部对位）
+ *
+ * 纪律：
+ * - 纯展示壳——无内部状态（交互全在调用方 VNode——组合式）
+ * - fixed = position:sticky（滚动常驻——ap-topbar 实证）+ safe-area-inset-top 避让
+ * - 标题对齐：align='center'（iOS 语义——默认）/ 'left'（品牌左对齐——ap-topbar 实证）
+ */
+import type { Component } from '../../../../level6/client/vdom/index.ts';
+export interface NavBarProps {
+    /** 标题（单行截断——不传 = 纯工具栏） */
+    title?: string;
+    /** 左区任意 VNode（返回/菜单按钮——组合式） */
+    left?: any;
+    /** 右区任意 VNode（操作按钮） */
+    right?: any;
+    /** 标题对齐（默认 'center'——iOS 语义；'left'——品牌左对齐） */
+    align?: 'left' | 'center';
+    /** sticky 常驻（position:sticky top:0 + safe-area-inset-top——移动端 App 顶栏） */
+    fixed?: boolean;
+    className?: string;
+}
+export declare const NavBar: Component<NavBarProps>;

package/dist/level5/client/components/NavBar/NavBar.ts

@@ -0,0 +1,47 @@
+/** NavBar：移动端顶栏——left 槽（返回/菜单）+ 标题截断 + right 槽（antd-mobile NavBar 对位）（showcase /components/navbar） */
+/**
+ * weifuwu/client/components — NavBar 移动端顶栏（antd-mobile NavBar / MUI AppBar 对位）
+ *
+ * 移动端 App 应用外壳顶栏：left 槽（返回/菜单按钮）+ 标题（单行截断）+ right 槽
+ * （操作按钮）——消费侧手搓实证 agent-platform `ap-topbar`
+ * （apps/agent-platform/ui/components/AppLayout.tsx:142——汉堡 + 品牌 + 设置）。
+ *
+ * 与近义组件区分（易混对照——components-map）：
+ * - PageHeader = 桌面**页内容**标题 + 操作区（页面内）；NavBar = 移动端**外壳**顶栏
+ * - AppShell/Layout = 整壳（侧栏+内容）；NavBar 独立组件——应用层组合
+ *   （与 TabBar 独立同构——顶部对位）
+ *
+ * 纪律：
+ * - 纯展示壳——无内部状态（交互全在调用方 VNode——组合式）
+ * - fixed = position:sticky（滚动常驻——ap-topbar 实证）+ safe-area-inset-top 避让
+ * - 标题对齐：align='center'（iOS 语义——默认）/ 'left'（品牌左对齐——ap-topbar 实证）
+ */
+import type { Component } from '../../../../level6/client/vdom/index.ts'
+import { h } from '../../../../level6/client/vdom/index.ts'
+
+export interface NavBarProps {
+  /** 标题（单行截断——不传 = 纯工具栏） */
+  title?: string
+  /** 左区任意 VNode（返回/菜单按钮——组合式） */
+  left?: any
+  /** 右区任意 VNode（操作按钮） */
+  right?: any
+  /** 标题对齐（默认 'center'——iOS 语义；'left'——品牌左对齐） */
+  align?: 'left' | 'center'
+  /** sticky 常驻（position:sticky top:0 + safe-area-inset-top——移动端 App 顶栏） */
+  fixed?: boolean
+  className?: string
+}
+
+export const NavBar: Component<NavBarProps> = (_init, _ctx)=> (props)=> {
+  const { title, left, right, align = 'center', fixed, className } = props
+  return h('header', {
+    class: ['wf-nav-bar', fixed ? 'wf-nav-bar--fixed' : '', className ?? ''].filter(Boolean).join(' '),
+  }, [
+    left ? h('div', { class: 'wf-nav-bar-side' }, left) : null,
+    title !== undefined && title !== null
+      ? h('div', { class: `wf-nav-bar-title${align === 'left' ? ' wf-nav-bar-title--left' : ''}` }, title)
+      : null,
+    right ? h('div', { class: 'wf-nav-bar-side' }, right) : null,
+  ].filter(Boolean))
+}