@h-ai/ui 0.1.0-alpha.61 → 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)
 
@@ -756,6 +763,58 @@ AuthPanel disables native form controls during SSR and enables input after clien
 
 [完整 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）
 
@@ -756,6 +763,58 @@ AuthPanel は SSR 中のフォーム操作を無効にし、クライアント
 
 [完整 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 个）
 
@@ -773,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/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 场景组件

package/dist/guide-storage.d.ts

@@ -0,0 +1,6 @@
+import type { GuideOptions, GuideProgress } from './guide-types.js';
+/** 存储受限时使用会话内存；只保存非敏感的引导偏好。 */
+export declare function createGuideStorage(options: GuideOptions): {
+    get(key: string): GuideProgress | null;
+    set(key: string, progress: GuideProgress | null): void;
+};

package/dist/guide-storage.js

@@ -0,0 +1,67 @@
+import { readStoredValue, writeStoredValue } from './internal/browser-safety.js';
+/** 存储受限时使用会话内存；只保存非敏感的引导偏好。 */
+export function createGuideStorage(options) {
+    const memory = new Map();
+    const persistence = options.persistence ?? 'cookie';
+    function read(key) {
+        if (memory.has(key))
+            return memory.get(key) ?? null;
+        try {
+            if (persistence === 'localStorage')
+                return readStoredValue(key) ?? memory.get(key) ?? null;
+            if (persistence === 'cookie' && typeof document !== 'undefined') {
+                const prefix = `${encodeURIComponent(key)}=`;
+                const value = document.cookie.split('; ').find(item => item.startsWith(prefix));
+                return value ? decodeURIComponent(value.slice(prefix.length)) : memory.get(key) ?? null;
+            }
+        }
+        catch {
+            // Cookie 禁用或内容损坏时不影响正常使用。
+        }
+        return memory.get(key) ?? null;
+    }
+    function write(key, value) {
+        memory.set(key, value);
+        try {
+            if (persistence === 'localStorage') {
+                if (value === null) {
+                    if (typeof localStorage !== 'undefined')
+                        localStorage.removeItem(key);
+                }
+                else {
+                    writeStoredValue(key, value);
+                }
+            }
+            else if (persistence === 'cookie' && typeof document !== 'undefined') {
+                const secure = globalThis.location?.protocol === 'https:' ? '; Secure' : '';
+                document.cookie = `${encodeURIComponent(key)}=${encodeURIComponent(value ?? '')}; Path=/; SameSite=Lax; Max-Age=${value === null ? '0' : '31536000'}${secure}`;
+            }
+        }
+        catch {
+            // WebView 或隐私模式下保留内存态。
+        }
+    }
+    return {
+        get(key) {
+            try {
+                const raw = read(key);
+                if (!raw)
+                    return null;
+                const value = JSON.parse(raw);
+                if (value && typeof value === 'object'
+                    && 'version' in value && typeof value.version === 'number' && Number.isFinite(value.version)
+                    && 'updatedAt' in value && typeof value.updatedAt === 'number' && Number.isFinite(value.updatedAt)
+                    && 'status' in value && (value.status === 'completed' || value.status === 'dismissed' || value.status === 'deferred')) {
+                    return { version: value.version, updatedAt: value.updatedAt, status: value.status };
+                }
+            }
+            catch {
+                // 损坏的偏好作为未看过处理。
+            }
+            return null;
+        },
+        set(key, progress) {
+            write(key, progress ? JSON.stringify(progress) : null);
+        },
+    };
+}