@h-ai/ui 0.1.0-alpha.60 → 0.1.0-alpha.62

package/README.en.md

@@ -248,7 +248,14 @@ For `BareInput` with `type="file"`, read `event.currentTarget.files` in `onchang
 | ------------ | ----------- | ----------------------------------------------- |
 | `PageHeader` | Page header | `title`, `description`; supports `actions` slot |
 
-### Scenes (34)
+### Scenes (36)
+
+#### Guide (2)
+
+| Component | Description | Key props |
+| --- | --- | --- |
+| `GuideHost` | First-use invitations, tours and help dialog host | `guide`, `locale`, `scope`, `autoStart` |
+| `HelpCenter` | Standalone searchable help center | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
 
 #### App (7)
 
@@ -752,8 +759,62 @@ agreements:
 
 AuthPanel accepts public IAM config and actions for password/LDAP/email/SMS login, registration and recovery. config.ui supplies layout, branding and images. LoginForm supports methods, onsendotp, otpLength and resendInterval; password forms accept passwordPolicy. Network and token storage remain in actions. Known IAM authentication errors use the current UI language; custom application messages are preserved.
 
+AuthPanel disables native form controls during SSR and enables input after client mount binds events, preventing early input from being lost during hydration. Applications need no extra readiness code. E2E tests wait for editable controls and cover delayed client scripts.
+
 [完整 IAM 配置 / IAM configuration](../iam/README.en.md)
 
+## Onboarding and help center
+
+Import `createGuide`, `GuideHost` and `HelpCenter` from `@h-ai/ui/guide`. No init/close is required. The tour engine loads when a tour starts; controls follow the current theme and include Chinese/English translations. Business text uses application i18n callbacks.
+
+The same entry exports `resolveGuideText(text?)` to evaluate strings or i18n callbacks; host components resolve text automatically.
+
+Create the controller inside a layout component, register tours with id/title/steps and optional route/version, then mount `<GuideHost {guide} {locale} scope={user.id} autoStart='overview' />`. Add `data-guide` to existing target components. Supply the application's NavAdapter for SPA navigation.
+
+```svelte
+<script lang='ts'>
+  import { createGuide, GuideHost } from '@h-ai/ui/guide'
+
+  const guide = createGuide({
+    nav,
+    persistKey: 'my-app-guide',
+    tours: [{
+      id: 'users',
+      version: 1,
+      route: '/users',
+      title: () => m.guide_users_title(),
+      description: () => m.guide_users_description(),
+      steps: [{
+        target: 'users-create',
+        title: () => m.guide_create_title(),
+        description: () => m.guide_create_description(),
+      }],
+    }],
+    articles: [{
+      id: 'users-help',
+      title: () => m.guide_users_title(),
+      content: () => m.guide_users_markdown(),
+      tourId: 'users',
+    }],
+  })
+</script>
+
+<GuideHost {guide} {locale} scope={user.id} autoStart='users' />
+<Button onclick={() => guide.openHelp()}>{m.help()}</Button>
+<!-- 在目标页面为现有按钮添加锚点，无需额外包装。 -->
+<Button data-guide='users-create' onclick={createUser}>{m.create_user()}</Button>
+```
+
+`start(id)` returns Promise<boolean> and always allows replay; failure returns false and sets error. `startIfNeeded(id)` returns boolean and offers a first-use invitation. `openHelp(articleId?)` opens searchable Markdown help; `stop()` cancels without marking completion; `reset(id)` clears the current user's preference.
+
+The close button, Escape, and overlay clicks cancel pending highlighting and clear `busy` even before the first positioning frame completes. A pending `start()` resolves to false without recording completion.
+
+Persistence supports cookie (default), localStorage and memory, with an in-instance fallback when storage is restricted. Preferences are isolated by user and version. Later delays reminders for one day; Cookie preferences expire after one year. The default full-page navigation uses a short-lived sessionStorage record to start on the destination page.
+
+Use `() => m.key()` for localized content and pass the current locale. Steps render as plain text; help uses the existing safe Markdown renderer with raw HTML disabled. Targets wait up to 3000ms by default; before(signal) prepares tabs or drawers, optional skips nonessential missing targets, and missing required targets stop the tour. Unmounting cancels pending work. Never share controllers across SSR users.
+
+HelpCenter can also render a standalone page using articles, optional tours, locale, selectedId and onstart. The admin-console example and CLI fullstack Web/App/Desktop include first-use invitations, help and profile tours by default. See the [complete integration guide](../cli/templates/skills/hai-ui/guide.md).
+
 ## Other exports
 
 ```ts

package/README.ja.md

@@ -248,7 +248,14 @@ components/
 | -------------- | -------------- | ---------------------------------------------- |
 | `PageHeader`   | ページヘッダー | `title`, `description`、`actions` スロット対応 |
 
-### Scenes：用途別コンポーネント（34）
+### Scenes：用途別コンポーネント（36）
+
+#### Guide：案内・ヘルプ（2）
+
+| コンポーネント | 説明 | 主なプロパティ |
+| --- | --- | --- |
+| `GuideHost` | 初回案内・ガイド・ヘルプダイアログ | `guide`, `locale`, `scope`, `autoStart` |
+| `HelpCenter` | 独立して使える検索付きヘルプ | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
 
 #### App：アプリ全体（7）
 
@@ -752,8 +759,62 @@ agreements:
 
 AuthPanel に IAM 公開設定と actions を渡すと、複数方式のログイン、登録、復旧、規約を利用できます。config.ui でレイアウトとブランド画像を指定し、パスワードフォームは passwordPolicy を受け取ります。通信と Token 保存は actions の責務です。既知の IAM 認証エラーは現在の UI 言語で表示し、アプリ独自のメッセージはそのまま保持します。
 
+AuthPanel は SSR 中のフォーム操作を無効にし、クライアントのマウントとイベント登録が完了してから入力を有効にします。ハイドレーションによる入力の消失を防ぎ、アプリ側の追加の準備処理は不要です。E2E では入力可能な状態を待ち、クライアントスクリプトの読み込みが遅れる場合も検証します。
+
 [完整 IAM 配置 / IAM configuration](../iam/README.ja.md)
 
+## 初回ガイドとヘルプセンター
+
+`@h-ai/ui/guide` から `createGuide`、`GuideHost`、`HelpCenter` をインポートします。init/close は不要です。ガイド開始時にエンジンを読み込み、既存テーマと中国語・英語の共通文言を使用します。業務内容はアプリの翻訳関数を使います。
+
+同じ入口の `resolveGuideText(text?)` は文字列や i18n コールバックを評価します。ホストコンポーネントは文言を自動で解析します。
+
+レイアウト内でコントローラーを作成し、id/title/steps と任意の route/version を登録します。`<GuideHost {guide} {locale} scope={user.id} autoStart='overview' />` を配置し、対象コンポーネントに data-guide を付けます。SPA は既存の NavAdapter を提供してください。
+
+```svelte
+<script lang='ts'>
+  import { createGuide, GuideHost } from '@h-ai/ui/guide'
+
+  const guide = createGuide({
+    nav,
+    persistKey: 'my-app-guide',
+    tours: [{
+      id: 'users',
+      version: 1,
+      route: '/users',
+      title: () => m.guide_users_title(),
+      description: () => m.guide_users_description(),
+      steps: [{
+        target: 'users-create',
+        title: () => m.guide_create_title(),
+        description: () => m.guide_create_description(),
+      }],
+    }],
+    articles: [{
+      id: 'users-help',
+      title: () => m.guide_users_title(),
+      content: () => m.guide_users_markdown(),
+      tourId: 'users',
+    }],
+  })
+</script>
+
+<GuideHost {guide} {locale} scope={user.id} autoStart='users' />
+<Button onclick={() => guide.openHelp()}>{m.help()}</Button>
+<!-- 在目标页面为现有按钮添加锚点，无需额外包装。 -->
+<Button data-guide='users-create' onclick={createUser}>{m.create_user()}</Button>
+```
+
+start(id) は Promise<boolean> を返し、手動で再表示できます。失敗時は false と error を設定します。startIfNeeded(id) は初回案内の有無を boolean で返します。openHelp(articleId?) は検索付き Markdown ヘルプを開き、stop() は完了として記録せず終了し、reset(id) は現在のユーザーの状態を削除します。
+
+閉じるボタン、Escape、オーバーレイのクリックは、最初の位置決めフレームが完了する前でも待機と `busy` 状態を解除します。開始中の `start()` は false を返し、完了として記録しません。
+
+保存先は cookie（既定）、localStorage、memory です。保存が制限された環境ではインスタンス内のメモリーに戻ります。ユーザーとバージョンごとに状態を分け、後で表示は一日延期、Cookie は一年保存します。既定のページ遷移は短期 sessionStorage 記録で移動先から開始します。
+
+文言は `() => m.key()` で遅延評価し、現在の locale を渡します。説明はプレーンテキスト、ヘルプは安全な MarkdownRenderer を使用し、生 HTML を無効にします。要素の待機は既定で 3000ms。before(signal) でタブ等を準備し、optional の要素のみ省略できます。必要な要素がなければ終了し、アンマウント時に処理を解除します。SSR ユーザー間でコントローラーを共有しないでください。
+
+HelpCenter は articles、任意の tours、locale、selectedId、onstart で独立ページにも配置できます。admin-console と CLI fullstack Web/App/Desktop は初回案内、ヘルプ、プロフィールガイドを標準搭載します。[詳細ガイド](../cli/templates/skills/hai-ui/guide.md)を参照してください。
+
 ## その他のエクスポート
 
 ```ts

package/README.md

@@ -248,7 +248,14 @@ components/
 | ------------ | -------- | ------------------------------------------- |
 | `PageHeader` | 页面头部 | `title`, `description`，支持 `actions` 插槽 |
 
-### 场景组件 Scenes（34 个）
+### 场景组件 Scenes（36 个）
+
+#### Guide 引导与帮助（2 个）
+
+| 组件 | 描述 | 主要属性 |
+| --- | --- | --- |
+| `GuideHost` | 首次邀请、页面导览与帮助弹窗宿主 | `guide`, `locale`, `scope`, `autoStart` |
+| `HelpCenter` | 可独立使用的帮助中心 | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
 
 #### App 应用级（7 个）
 
@@ -711,6 +718,8 @@ agreements:
 
 AuthPanel 直接接收 IAM 白名单配置和 actions，内置登录（密码/LDAP/邮件/短信）、注册、找回、重置及协议展示。使用 `config.ui` 配置卡片/分栏、标题、品牌、Logo 和配图。`LoginForm` 提供 methods、onsendotp、otpLength、resendInterval；密码表单接受 passwordPolicy。组件只渲染与交互，网络和 Token 存储通过 actions 注入。认证场景按公开 IAM 错误码显示当前 UI 语言的提示，应用自定义错误保留原文。
 
+AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事件后自动开放输入，避免接管时丢失早到的输入。应用无需额外的就绪适配；E2E 等待控件可编辑，并覆盖客户端脚本延迟加载的场景。
+
 [完整 IAM 配置 / IAM configuration](../iam/README.md)
 
 ### createLocaleStore
@@ -771,6 +780,59 @@ import {
 上例的 subscribe 为应用自身的 $state，应用包装 register 动作校验/提交扩展业务数据；如需单独组合表单，使用 `<RegisterForm> {#snippet extraFields()}...{/snippet} </RegisterForm>`。扩展里的按钮须为 `type="button"`，避免误提交。
 
 
+## 新手引导与帮助中心
+
+`@h-ai/ui/guide` 提供 `createGuide`、`GuideHost`、`HelpCenter` 和相关类型。无需 init/close；引擎在开始导览时按需加载，浮层复用当前主题。组件内置中英文按钮、进度和错误提示，业务内容使用应用 i18n。
+
+同一入口的 `resolveGuideText(text?)` 可解析字符串或 i18n 回调；宿主组件已自动解析文案。
+
+下例放在应用布局中；`nav` 是应用现有 NavAdapter，`locale`、`user` 与翻译函数 `m` 来自应用，翻译 key 需在应用消息中定义。目标按钮放在 `/users` 页面。
+
+```svelte
+<script lang='ts'>
+  import { createGuide, GuideHost } from '@h-ai/ui/guide'
+
+  const guide = createGuide({
+    nav,
+    persistKey: 'my-app-guide',
+    tours: [{
+      id: 'users',
+      version: 1,
+      route: '/users',
+      title: () => m.guide_users_title(),
+      description: () => m.guide_users_description(),
+      steps: [{
+        target: 'users-create',
+        title: () => m.guide_create_title(),
+        description: () => m.guide_create_description(),
+      }],
+    }],
+    articles: [{
+      id: 'users-help',
+      title: () => m.guide_users_title(),
+      content: () => m.guide_users_markdown(),
+      tourId: 'users',
+    }],
+  })
+</script>
+
+<GuideHost {guide} {locale} scope={user.id} autoStart='users' />
+<Button onclick={() => guide.openHelp()}>{m.help()}</Button>
+<!-- 在目标页面为现有按钮添加锚点，无需额外包装。 -->
+<Button data-guide='users-create' onclick={createUser}>{m.create_user()}</Button>
+```
+
+- `start(id)` 返回 `Promise<boolean>`，允许手动重看；失败返回 false 并设置 `error`。`startIfNeeded(id)` 返回 boolean 并显示首次邀请，通常由 autoStart 处理。
+- `openHelp(articleId?)` 打开帮助，`stop()` 取消导览，`reset(id)` 删除当前用户的偏好。完成、稍后和不再提醒分别记录；稍后暂缓一天，Cookie 默认保存一年。
+- 关闭按钮、Escape 和遮罩点击在首帧定位期间也会取消等待、清除 `busy`；启动中的 `start()` 返回 false，不记录完成。
+- `persistence` 支持 cookie（默认）、localStorage、memory；受限存储回退到实例内存。scope 使用非敏感用户标识，version 变化会重新提示。
+- 通过已有 NavAdapter 接入 SvelteKit、SPA 或原生 WebView；默认完整导航使用 sessionStorage 保存短期启动记录。宿主只在浏览器挂载后读取记录，SSR 实例不得跨用户共享。
+- 目标等待默认 3000ms，可用 waitTimeout 调整。before(signal) 可展开页签/抽屉；必要元素缺失停止，可选步骤使用 optional 跳过。引导不会自动提交业务表单。
+- 业务文案用函数延迟求值，并传入当前 locale。步骤内容按纯文本显示；帮助正文复用安全 MarkdownRenderer，原始 HTML 关闭。
+- HelpCenter 可独立放入帮助页面，props 为 articles、tours（可选）、locale、selectedId 和 onstart；支持类别标签、标题/正文搜索和关联导览。
+
+admin-console 示例和 CLI fullstack Web/App/Desktop 默认包含帮助入口、首次邀请及个人资料导览。完整配置和验证场景见 [引导指南](../cli/templates/skills/hai-ui/guide.md)。
+
 ## 其他导出
 
 ```ts

package/auto-import.d.ts

@@ -16,6 +16,8 @@ type AutoImportHaiUiPreprocessor = {
 export function autoImportHaiUi(): AutoImportHaiUiPreprocessor
 
 declare global {
+  const GuideHost: typeof import('@h-ai/ui')['GuideHost']
+  const HelpCenter: typeof import('@h-ai/ui')['HelpCenter']
   // primitives
   const Avatar: typeof import('@h-ai/ui')['Avatar']
   const Badge: typeof import('@h-ai/ui')['Badge']

package/auto-import.js

@@ -77,6 +77,8 @@ const UI_COMPONENTS = new Set([
   'ThemeColorPicker',
   'ThemeSelector',
   'ThemeToggle',
+  'GuideHost',
+  'HelpCenter',
   // scenes - iam
   'AuthShell',
   'AuthPanel',

package/dist/components/scenes/guide/GuideHost.svelte

@@ -0,0 +1,111 @@
+<script lang='ts'>
+  import type { GuideController } from '../../../guide-types.js'
+  import type { DataAttributes } from '../../../types.js'
+  import { onMount, untrack } from 'svelte'
+  import { resolveGuideText } from '../../../guide.svelte.js'
+  import { getUILocale, uiM } from '../../../messages.js'
+  import { getDataAttributes } from '../../../utils.js'
+  import Alert from '../../compounds/Alert.svelte'
+  import Modal from '../../compounds/Modal.svelte'
+  import Button from '../../primitives/Button.svelte'
+  import HelpCenter from './HelpCenter.svelte'
+  import 'driver.js/dist/driver.css'
+  import '../../../styles/guide.css'
+
+  interface Props {
+    guide: GuideController
+    locale?: string
+    /** 非敏感的用户标识，账号切换后独立记录引导偏好。 */
+    scope?: string
+    /** 挂载后提示首次使用者，不会直接打断操作或自动跳转。 */
+    autoStart?: string
+  }
+
+  const { guide, locale = getUILocale(), scope = 'anonymous', autoStart, ...restProps }: Props & DataAttributes = $props()
+  const dataAttributes = $derived(getDataAttributes(restProps))
+  let ready = $state(false)
+  const offered = $derived.by(() => {
+    void locale
+    const tour = guide.offeredTour
+    return tour ? { id: tour.id, title: resolveGuideText(tour.title), description: resolveGuideText(tour.description) } : null
+  })
+  const text = $derived.by(() => ({
+    welcome: uiM('guide_welcome', undefined, locale),
+    start: uiM('guide_start', undefined, locale),
+    later: uiM('guide_later', undefined, locale),
+    dismiss: uiM('guide_dismiss', undefined, locale),
+    help: uiM('guide_help', undefined, locale),
+    close: uiM('guide_close', undefined, locale),
+    loading: uiM('guide_loading', undefined, locale),
+  }))
+
+  $effect(() => {
+    const currentLocale = locale
+    untrack(() => guide.setLocale(currentLocale))
+  })
+  $effect(() => {
+    const currentScope = scope
+    const tourId = autoStart
+    if (ready) {
+      untrack(() => {
+        guide.setScope(currentScope)
+        if (tourId)
+          guide.startIfNeeded(tourId)
+      })
+    }
+  })
+  $effect(() => {
+    const pathname = guide.pathname
+    untrack(() => guide.handleNavigation(pathname))
+  })
+  onMount(() => {
+    let alive = true
+    guide.setScope(scope)
+    guide.setLocale(locale)
+    void guide.resume().then(() => {
+      if (alive)
+        ready = true
+    })
+    return () => {
+      alive = false
+      guide.stop()
+    }
+  })
+</script>
+
+<div {...dataAttributes} class='contents'>
+
+  {#if offered}
+    <aside class='hai-guide-offer fixed bottom-4 right-4 z-[1150] w-96 max-w-[calc(100vw-2rem)] rounded-2xl border border-base-content/10 bg-base-100 p-5 text-base-content shadow-(--shadow-overlay)' aria-label={text.welcome} data-testid='guide-offer'>
+      <p class='text-xs font-medium text-primary'>{text.welcome}</p>
+      <h2 class='mt-2 text-base font-semibold'>{offered.title}</h2>
+      <p class='mt-2 text-sm leading-6 text-base-content/65'>{offered.description}</p>
+      <div class='mt-4 flex flex-wrap gap-2'>
+        <Button variant='primary' size='sm' onclick={() => offered && void guide.start(offered.id)} data-testid='guide-start'>{text.start}</Button>
+        <Button variant='ghost' size='sm' onclick={() => guide.defer()} data-testid='guide-later'>{text.later}</Button>
+        <Button variant='ghost' size='sm' onclick={() => guide.dismiss()} data-testid='guide-dismiss'>{text.dismiss}</Button>
+      </div>
+    </aside>
+  {/if}
+
+  {#if guide.busy}
+    <div class='hai-guide-loading fixed bottom-4 left-1/2 z-[1000000001] flex max-w-[calc(100vw-2rem)] -translate-x-1/2 items-center gap-3 rounded-xl border border-base-content/10 bg-base-100 px-4 py-2 text-sm text-base-content shadow-lg' role='status' data-testid='guide-loading'>
+      <span class='loading loading-spinner loading-xs'></span>{text.loading}
+      <Button size='sm' variant='ghost' onclick={() => guide.stop()} data-testid='guide-cancel'>{text.close}</Button>
+    </div>
+  {/if}
+
+  {#if guide.error}
+    <div class='fixed bottom-4 right-4 z-[1500] max-w-[calc(100vw-2rem)]' data-testid='guide-error'>
+      <Alert variant='warning'>
+        <div class='flex items-center gap-3'><span>{guide.error}</span><Button size='sm' variant='ghost' onclick={() => guide.clearError()}>{text.close}</Button></div>
+      </Alert>
+    </div>
+  {/if}
+
+  {#if guide.helpOpen}
+    <Modal open title={text.help} size='4xl' height='min(80dvh, 48rem)' bodyClass='p-0' onclose={() => guide.closeHelp()} data-testid='guide-help'>
+      <HelpCenter articles={guide.articles} tours={guide.tours} selectedId={guide.articleId} {locale} onstart={id => void guide.start(id)} />
+    </Modal>
+  {/if}
+</div>

package/dist/components/scenes/guide/GuideHost.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { GuideController } from '../../../guide-types.js';
+import type { DataAttributes } from '../../../types.js';
+import 'driver.js/dist/driver.css';
+import '../../../styles/guide.css';
+interface Props {
+    guide: GuideController;
+    locale?: string;
+    /** 非敏感的用户标识，账号切换后独立记录引导偏好。 */
+    scope?: string;
+    /** 挂载后提示首次使用者，不会直接打断操作或自动跳转。 */
+    autoStart?: string;
+}
+type $$ComponentProps = Props & DataAttributes;
+declare const GuideHost: import("svelte").Component<$$ComponentProps, {}, "">;
+type GuideHost = ReturnType<typeof GuideHost>;
+export default GuideHost;

package/dist/components/scenes/guide/HelpCenter.svelte

@@ -0,0 +1,94 @@
+<script lang='ts'>
+  import type { GuideArticle, GuideTour } from '../../../guide-types.js'
+  import type { DataAttributes } from '../../../types.js'
+  import { resolveGuideText } from '../../../guide.svelte.js'
+  import { getUILocale, uiM } from '../../../messages.js'
+  import { getDataAttributes } from '../../../utils.js'
+  import BareButton from '../../primitives/BareButton.svelte'
+  import Button from '../../primitives/Button.svelte'
+  import Input from '../../primitives/Input.svelte'
+
+  interface Props {
+    articles: readonly GuideArticle[]
+    tours?: readonly GuideTour[]
+    locale?: string
+    selectedId?: string | null
+    onstart?: (tourId: string) => void
+  }
+  const { articles, tours = [], locale = getUILocale(), selectedId = null, onstart, ...restProps }: Props & DataAttributes = $props()
+  const dataAttributes = $derived(getDataAttributes(restProps))
+  let search = $state('')
+  const searchId = $props.id()
+  let currentId = $derived(selectedId)
+  // 显式依赖宿主语言，确保回调返回的业务翻译也重新求值。
+  const localized = $derived.by(() => {
+    void locale
+    return articles.filter(article => !article.enabled || article.enabled()).map(article => ({
+      ...article,
+      title: resolveGuideText(article.title),
+      description: resolveGuideText(article.description),
+      category: resolveGuideText(article.category),
+      content: resolveGuideText(article.content),
+    }))
+  })
+  const availableTours = $derived.by(() => {
+    void locale
+    return tours.filter(tour => !tour.enabled || tour.enabled()).map(tour => ({ id: tour.id, title: resolveGuideText(tour.title) }))
+  })
+  const visible = $derived(localized.filter(article => (`${article.title} ${article.description} ${article.category} ${article.content}`).toLowerCase().includes(search.trim().toLowerCase())))
+  const selected = $derived(visible.find(article => article.id === currentId) ?? visible[0])
+  const markdown = $derived(selected ? import('../ai/MarkdownRenderer.svelte') : null)
+  const text = $derived.by(() => ({
+    search: uiM('guide_search', undefined, locale),
+    empty: uiM('guide_empty', undefined, locale),
+    tours: uiM('guide_tours', undefined, locale),
+    start: uiM('guide_start', undefined, locale),
+    loading: uiM('guide_loading', undefined, locale),
+    failed: uiM('guide_startFailed', undefined, locale),
+  }))
+</script>
+
+<div data-testid='help-center' {...dataAttributes} class='flex min-h-0 flex-col text-base-content md:flex-row'>
+  <nav class='shrink-0 border-b border-base-content/8 p-4 md:w-64 md:border-b-0 md:border-r' aria-label={text.search}>
+    <label class='sr-only' for={searchId}>{text.search}</label>
+    <Input id={searchId} bind:value={search} placeholder={text.search} data-testid='guide-search' />
+    <div class='mt-3 max-h-40 space-y-1 overflow-y-auto md:max-h-[50dvh]'>
+      {#each visible as article (article.id)}
+        <BareButton class={`w-full rounded-lg px-3 py-2 text-left text-sm hover:bg-base-content/5 ${selected?.id === article.id ? 'bg-primary/10 font-semibold text-primary' : ''}`} onclick={() => currentId = article.id} data-testid={`guide-article-${article.id}`}>
+          {#if article.category}<span class='mb-1 block text-xs text-base-content/50'>{article.category}</span>{/if}
+          <span class='block'>{article.title}</span>
+        </BareButton>
+      {/each}
+    </div>
+    {#if onstart && availableTours.length}
+      <p class='mt-5 text-xs font-medium text-base-content/50'>{text.tours}</p>
+      <div class='mt-2 flex flex-wrap gap-2 md:flex-col'>
+        {#each availableTours as tour (tour.id)}
+          <Button variant='ghost' size='sm' onclick={() => onstart?.(tour.id)} data-testid={`guide-tour-${tour.id}`}>{tour.title}</Button>
+        {/each}
+      </div>
+    {/if}
+  </nav>
+  <article class='min-w-0 flex-1 p-5 md:p-7' data-testid='guide-article-content'>
+    {#if selected}
+      <h2 class='text-xl font-semibold'>{selected.title}</h2>
+      {#if selected.description}<p class='mt-2 text-sm text-base-content/60'>{selected.description}</p>{/if}
+      {#if selected.tourId && availableTours.some(tour => tour.id === selected.tourId) && onstart}
+        <Button variant='primary' size='sm' class='mt-4' onclick={() => onstart?.(selected!.tourId!)} data-testid='guide-article-start'>{text.start}</Button>
+      {/if}
+      <div class='mt-5'>
+        {#await markdown}
+          <p class='text-sm text-base-content/50' role='status'>{text.loading}</p>
+        {:then component}
+          {#if component}
+            <component.default content={selected.content} allowHtmlTags={false} showCopyButton={false} />
+          {/if}
+        {:catch}
+          <p class='text-sm text-error' role='alert'>{text.failed}</p>
+        {/await}
+      </div>
+    {:else}
+      <p class='py-8 text-center text-sm text-base-content/50'>{text.empty}</p>
+    {/if}
+  </article>
+</div>

package/dist/components/scenes/guide/HelpCenter.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { GuideArticle, GuideTour } from '../../../guide-types.js';
+import type { DataAttributes } from '../../../types.js';
+interface Props {
+    articles: readonly GuideArticle[];
+    tours?: readonly GuideTour[];
+    locale?: string;
+    selectedId?: string | null;
+    onstart?: (tourId: string) => void;
+}
+type $$ComponentProps = Props & DataAttributes;
+declare const HelpCenter: import("svelte").Component<$$ComponentProps, {}, "">;
+type HelpCenter = ReturnType<typeof HelpCenter>;
+export default HelpCenter;

package/dist/components/scenes/guide/index.d.ts

@@ -0,0 +1,2 @@
+export { default as GuideHost } from './GuideHost.svelte';
+export { default as HelpCenter } from './HelpCenter.svelte';

package/dist/components/scenes/guide/index.js

@@ -0,0 +1,2 @@
+export { default as GuideHost } from './GuideHost.svelte';
+export { default as HelpCenter } from './HelpCenter.svelte';

package/dist/components/scenes/iam/AuthPanel.svelte

@@ -2,7 +2,7 @@
 <script lang='ts'>
   import type { HaiResult } from '@h-ai/core'
   import type { AuthLoginMethod, AuthPanelMode, AuthPanelProps } from '../types.js'
-  import { untrack } from 'svelte'
+  import { onMount, untrack } from 'svelte'
   import { uiM } from '../../../messages.js'
   import { getDataAttributes } from '../../../utils.js'
   import Alert from '../../compounds/Alert.svelte'
@@ -22,6 +22,11 @@
   let loading = $state(false)
   let errors = $state<Record<string, string>>({})
   let notice = $state('')
+  // SSR 表单先显示但不可编辑；客户端绑定事件后开放输入，避免接管时丢失早到的输入。
+  let interactive = $state(false)
+  onMount(() => {
+    interactive = true
+  })
   const methods = $derived(config ? (['password', 'ldap', 'email', 'sms'] as AuthLoginMethod[]).filter(method => config.login[method]) : [])
   const title = $derived(mode === 'register' ? uiM('register_title') : mode === 'forgot' ? uiM('forgot_password_title') : mode === 'reset' ? uiM('reset_password_title') : uiM('login_title'))
   const available = $derived(config && (mode === 'login' || (mode === 'register' ? config.register.enabled : config.passwordReset.enabled)))
@@ -74,43 +79,45 @@
 {/snippet}
 
 <AuthShell {...dataAttributes} {...config?.ui} title={config?.ui.title || title} brandTitle={config?.ui.brandTitle || uiM('auth_brand')}>
-  {#if error}
-    <Alert variant='error'>{error}</Alert>
-    {#if onretry}<Button class='mt-4 w-full' onclick={onretry}>{uiM('crud_retry')}</Button>{/if}
-  {:else if !config}
-    <div class='flex justify-center' role='status'><Spinner /></div>
-  {:else if !available}
-    <Alert variant='warning'>{uiM('auth_unavailable')}</Alert>
-    <div class='mt-4 text-center'>{@render link('login', uiM('login_submit'), loginUrl)}</div>
-  {:else}
-    {#if notice}<Alert variant='success' class='mb-4'>{notice}</Alert>{/if}
-    {#if mode === 'login'}
-      <LoginForm {methods} {loading} {errors} header={loginHeader} extraFields={loginFields} showRememberMe={false} showForgotPassword={config.passwordReset.enabled} {forgotPasswordUrl}
-                 onforgotpassword={forgotPasswordUrl ? undefined : () => switchMode('forgot')}
-                 otpLength={config.otp.length} resendInterval={config.otp.resendInterval} onsendotp={actions.sendOtp}
-                 agreements={config.agreements.showOnLogin ? config.agreements : undefined}
-                 onsubmit={data => run(() => actions.login({ identifier: data.username, password: data.password, method: data.method, code: data.code }), true)}>
-        {#snippet footer()}
-          {#if loginFooter}{@render loginFooter()}{/if}
-          {#if config?.register.enabled}<div class='text-center text-sm'>{uiM('login_no_account')} {@render link('register', uiM('login_register_now'), registerUrl)}</div>{/if}
-        {/snippet}
-      </LoginForm>
-    {:else if mode === 'register'}
-      <RegisterForm {loading} {errors} header={registerHeader} extraFields={registerFields} fields={config.passwordReset.mode === 'phone' ? ['username', 'phone', 'password'] : ['username', 'email', 'password']} passwordPolicy={config.password} minPasswordLength={config.password.minLength}
-                    agreements={config.agreements.showOnRegister ? config.agreements : undefined} onsubmit={data => run(() => actions.register({ username: data.username || '', password: data.password, email: data.email, phone: data.phone, displayName: data.nickname }), true)}>
-        {#snippet footer()}
-          {#if registerFooter}{@render registerFooter()}{/if}
-          <div class='text-center'>{@render link('login', uiM('register_login_now'), loginUrl)}</div>
-        {/snippet}
-      </RegisterForm>
-    {:else if mode === 'forgot'}
-      <ForgotPasswordForm {loading} {errors} mode={config.passwordReset.mode ?? 'email'} onsubmit={data => run(() => actions.requestPasswordReset(data.email || data.phone || ''), false, uiM('auth_reset_sent'))}>
-        {#snippet footer()}<div class='flex justify-between gap-3'>{@render link('login', uiM('login_submit'), loginUrl)}{@render link('reset', uiM('auth_have_token'))}</div>{/snippet}
-      </ForgotPasswordForm>
-    {:else}
-      <ResetPasswordForm {loading} {errors} showCode={!resetToken} passwordPolicy={config.password} minPasswordLength={config.password.minLength}
-                         onsubmit={data => run(() => actions.confirmPasswordReset(resetToken || data.code || '', data.newPassword), false, uiM('auth_reset_done'))} />
+  <fieldset class='m-0 min-w-0 border-0 p-0' disabled={!interactive}>
+    {#if error}
+      <Alert variant='error'>{error}</Alert>
+      {#if onretry}<Button class='mt-4 w-full' onclick={onretry}>{uiM('crud_retry')}</Button>{/if}
+    {:else if !config}
+      <div class='flex justify-center' role='status'><Spinner /></div>
+    {:else if !available}
+      <Alert variant='warning'>{uiM('auth_unavailable')}</Alert>
       <div class='mt-4 text-center'>{@render link('login', uiM('login_submit'), loginUrl)}</div>
+    {:else}
+      {#if notice}<Alert variant='success' class='mb-4'>{notice}</Alert>{/if}
+      {#if mode === 'login'}
+        <LoginForm {methods} {loading} {errors} header={loginHeader} extraFields={loginFields} showRememberMe={false} showForgotPassword={config.passwordReset.enabled} {forgotPasswordUrl}
+                   onforgotpassword={forgotPasswordUrl ? undefined : () => switchMode('forgot')}
+                   otpLength={config.otp.length} resendInterval={config.otp.resendInterval} onsendotp={actions.sendOtp}
+                   agreements={config.agreements.showOnLogin ? config.agreements : undefined}
+                   onsubmit={data => run(() => actions.login({ identifier: data.username, password: data.password, method: data.method, code: data.code }), true)}>
+          {#snippet footer()}
+            {#if loginFooter}{@render loginFooter()}{/if}
+            {#if config?.register.enabled}<div class='text-center text-sm'>{uiM('login_no_account')} {@render link('register', uiM('login_register_now'), registerUrl)}</div>{/if}
+          {/snippet}
+        </LoginForm>
+      {:else if mode === 'register'}
+        <RegisterForm {loading} {errors} header={registerHeader} extraFields={registerFields} fields={config.passwordReset.mode === 'phone' ? ['username', 'phone', 'password'] : ['username', 'email', 'password']} passwordPolicy={config.password} minPasswordLength={config.password.minLength}
+                      agreements={config.agreements.showOnRegister ? config.agreements : undefined} onsubmit={data => run(() => actions.register({ username: data.username || '', password: data.password, email: data.email, phone: data.phone, displayName: data.nickname }), true)}>
+          {#snippet footer()}
+            {#if registerFooter}{@render registerFooter()}{/if}
+            <div class='text-center'>{@render link('login', uiM('register_login_now'), loginUrl)}</div>
+          {/snippet}
+        </RegisterForm>
+      {:else if mode === 'forgot'}
+        <ForgotPasswordForm {loading} {errors} mode={config.passwordReset.mode ?? 'email'} onsubmit={data => run(() => actions.requestPasswordReset(data.email || data.phone || ''), false, uiM('auth_reset_sent'))}>
+          {#snippet footer()}<div class='flex justify-between gap-3'>{@render link('login', uiM('login_submit'), loginUrl)}{@render link('reset', uiM('auth_have_token'))}</div>{/snippet}
+        </ForgotPasswordForm>
+      {:else}
+        <ResetPasswordForm {loading} {errors} showCode={!resetToken} passwordPolicy={config.password} minPasswordLength={config.password.minLength}
+                           onsubmit={data => run(() => actions.confirmPasswordReset(resetToken || data.code || '', data.newPassword), false, uiM('auth_reset_done'))} />
+        <div class='mt-4 text-center'>{@render link('login', uiM('login_submit'), loginUrl)}</div>
+      {/if}
     {/if}
-  {/if}
+  </fieldset>
 </AuthShell>

package/dist/components/scenes/iam/auth-error-message.d.ts

@@ -1,4 +1,2 @@
-export declare function authErrorMessage(error: {
-    code: string;
-    message: string;
-}): string;
+import type { HaiError } from '@h-ai/core';
+export declare function authErrorMessage(error: Pick<HaiError, 'code' | 'message'>): string;

package/dist/components/scenes/index.d.ts

@@ -10,6 +10,7 @@ export * from './charts/index.js';
 export * from './crud/index.js';
 export * from './crypto/index.js';
 export * from './error/index.js';
+export * from './guide/index.js';
 export * from './iam/index.js';
 export * from './storage/index.js';
 export * from './types.js';

package/dist/components/scenes/index.js

@@ -16,6 +16,7 @@ export * from './crud/index.js';
 export * from './crypto/index.js';
 // 错误页场景组件
 export * from './error/index.js';
+export * from './guide/index.js';
 // IAM 场景组件
 export * from './iam/index.js';
 // Storage 场景组件