@h-ai/ui 0.1.0-alpha.65 → 0.1.0-alpha.67

package/README.en.md

@@ -4,19 +4,29 @@
 
 [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
 
-> A cross-platform Svelte 5 Runes component library with DaisyUI v5 + Tailwind CSS v4 styling and Bits UI v2 headless interactions. Includes built-in i18n (zh-CN / en-US) and 15 curated DaisyUI themes.
+## Introduction
 
-## Installation
+A cross-platform Svelte 5 Runes component library with DaisyUI v5 + Tailwind CSS v4 styling and Bits UI v2 headless interactions. Includes built-in i18n (zh-CN / en-US) and 15 curated DaisyUI themes.
+
+## Core features
+
+- Forms, tables, dialogs, navigation, charts and application components.
+- Authentication, CRUD, AI content, onboarding and a help center.
+- Svelte 5, themes, responsive layouts and Chinese/English component messages.
+
+## Getting started
+
+### Installation
 
 ```bash
-npm install @h-ai/ui
+npm install @h-ai/ui @h-ai/core
 ```
 
-Depends on `@h-ai/core`, installed automatically.
+For a Node server, declare both UI and core as production dependencies so the adapter preserves native logging and runtime dependencies.
 
-## Quick start
+### Quick start
 
-### 1. Configure svelte.config.js
+#### 1. Configure svelte.config.js
 
 ```js
 import { autoImportHaiUi } from '@h-ai/ui/auto-import'
@@ -33,7 +43,7 @@ const config = {
 export default config
 ```
 
-### 2. Configure vite.config.ts
+#### 2. Configure vite.config.ts
 
 ```ts
 import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
@@ -51,11 +61,13 @@ export default defineConfig({
     // 避免首次进入业务路由时触发依赖再优化与整页刷新
     include: [...haiPrebundledDeps],
   },
-  ssr: { noExternal: [/@h-ai\//] },
+  ssr: { noExternal: ['@h-ai/ui', '@h-ai/kit'], external: ['@h-ai/core', 'sm-crypto'] },
 })
 ```
 
-### 3. Configure src/app.css
+When using Crypto or Kit/IAM, include `sm-crypto@0.5.7` in application production dependencies. CLI projects already do this; for manual setup, run `pnpm add sm-crypto@0.5.7`. The external option alone is insufficient: adapter-node also uses direct production dependencies to preserve native package loading.
+
+#### 3. Configure src/app.css
 
 ```css
 @import 'tailwindcss';
@@ -76,7 +88,7 @@ export default defineConfig({
 
 > `@source` makes TailwindCSS scan classes in `@h-ai/ui`; without it, component styles are missing. In nested monorepo apps, dependencies may be hoisted to root `node_modules`, so retain both paths.
 
-### 4. Use components
+#### 4. Use components
 
 ```svelte
 <script>
@@ -108,7 +120,7 @@ import { Button } from '@h-ai/ui/components/primitives/index'
 import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
 ```
 
-### data-\* attribute forwarding
+#### data-\* attribute forwarding
 
 Public Svelte components forward caller-supplied `data-*` attributes to their root or primary interactive element for tests, analytics, and automation. Other unknown attributes are not forwarded.
 
@@ -120,7 +132,7 @@ Public Svelte components forward caller-supplied `data-*` attributes to their ro
 
 No extra button, input, or overlay wrappers are needed just for `data-testid`.
 
-## Component architecture
+### Component architecture
 
 Three layers (primitives → compounds → scenes):
 
@@ -137,9 +149,9 @@ components/
     └── crypto/   # Cryptographic display
 ```
 
-## Component catalog
+### Component catalog
 
-### Primitives (20)
+#### Primitives (20)
 
 | Component        | Description         | Key props                                                                      |
 | ---------------- | ------------------- | ------------------------------------------------------------------------------ |
@@ -166,9 +178,9 @@ components/
 
 For `BareInput` with `type="file"`, read `event.currentTarget.files` in `onchange` and leave the file path `value` unbound. Other input types support `bind:value`.
 
-### Compounds (37)
+#### Compounds (37)
 
-#### Forms
+##### Forms
 
 | Component   | Description    | Key props                                    |
 | ----------- | -------------- | -------------------------------------------- |
@@ -177,7 +189,7 @@ For `BareInput` with `type="file"`, read `event.currentTarget.files` in `onchang
 | `FormLayout` | Form layout | `columns`, `labelPosition`, `labelWidth` |
 | `TagInput`  | Tag input      | `tags`, `maxTags`, `allowDuplicates`, `size` |
 
-#### Form layouts and validation
+##### Form layouts and validation
 
 `Form` and `FormLayout` (for native `<form>` elements) share `columns={1 | 2}`, `labelPosition="top" | "left"` and `labelWidth` (default `8rem`). Defaults are one column and stacked labels. Two columns collapse below a container width of `36rem`; inline labels stack below `28rem`.
 
@@ -206,14 +218,14 @@ Client validation appears on the first blur and updates as invalid input is corr
 </Form>
 ```
 
-#### Feedback
+##### Feedback
 
 | Component        | Description     | Key props                                         |
 | ---------------- | --------------- | ------------------------------------------------- |
 | `Alert`          | Alert           | `variant`, `title`, `dismissible`                 |
 | `ToastContainer` | Toast container | Place globally and use with the `toast` singleton |
 
-#### Overlays
+##### Overlays
 
 | Component | Description         | Key props                                                                    |
 | --------- | ------------------- | ---------------------------------------------------------------------------- |
@@ -222,7 +234,7 @@ Client validation appears on the first blur and updates as invalid input is corr
 | `Confirm` | Confirmation dialog | `open`, `title`, `message`, `variant`, `onconfirm`                           |
 | `Popover` | Popover             | `open`, `position`, `trigger`, `offset`, `portal`                            |
 
-#### Data display
+##### Data display
 
 | Component   | Description    | Key props                                                                                                                                   |
 | ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -231,7 +243,7 @@ Client validation appears on the first blur and updates as invalid input is corr
 | `Accordion` | Accordion      | `items: AccordionItem[]`                                                                                                                    |
 | `Timeline`  | Timeline       | `items: TimelineItem[]`                                                                                                                     |
 
-#### Bits UI headless interactions
+##### Bits UI headless interactions
 
 | Component    | Description                         | Key props                                                   |
 | ------------ | ----------------------------------- | ----------------------------------------------------------- |
@@ -241,7 +253,7 @@ Client validation appears on the first blur and updates as invalid input is corr
 
 > Dates use `DateValue` / `CalendarDate` from `@internationalized/date`.
 
-#### Mobile / enhanced interactions
+##### Mobile / enhanced interactions
 
 | Component        | Description         | Key props                                              |
 | ---------------- | ------------------- | ------------------------------------------------------ |
@@ -253,7 +265,7 @@ Client validation appears on the first blur and updates as invalid input is corr
 | `SafeArea`       | Safe area container | `top`, `bottom`, `left`, `right`                       |
 | `SwipeCell`      | Swipe actions       | `leftActions`, `rightActions`, `threshold`, `onaction` |
 
-#### Navigation
+##### Navigation
 
 | Component    | Description                     | Key props                                                                                                  |
 | ------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -264,7 +276,7 @@ Client validation appears on the first blur and updates as invalid input is corr
 | `Dropdown`   | Dropdown menu                   | `items`, `trigger`, `triggerClass`, `position`                                                             |
 | `Tooltip`    | Tooltip                         | `content`, `position`, `delay`                                                                             |
 
-#### State placeholders
+##### State placeholders
 
 | Component  | Description | Key props                             |
 | ---------- | ----------- | ------------------------------------- |
@@ -272,22 +284,22 @@ Client validation appears on the first blur and updates as invalid input is corr
 | `Empty`    | Empty state | `title`, `description`, `icon`        |
 | `Result`   | Result page | `status`, `title`, `description`      |
 
-#### Page-level
+##### Page-level
 
 | Component    | Description | Key props                                       |
 | ------------ | ----------- | ----------------------------------------------- |
 | `PageHeader` | Page header | `title`, `description`; supports `actions` slot |
 
-### Scenes (36)
+#### Scenes (36)
 
-#### Guide (2)
+##### 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)
+##### App (7)
 
 | Component          | Description                                    | Key props                                                |
 | ------------------ | ---------------------------------------------- | -------------------------------------------------------- |
@@ -299,7 +311,7 @@ Client validation appears on the first blur and updates as invalid input is corr
 | `ThemeSelector`    | Full theme selector                            | No props required                                        |
 | `ThemeToggle`      | Light/dark toggle                              | No props required                                        |
 
-#### IAM authentication (10)
+##### IAM authentication (10)
 
 | Component            | Description                                      | Key props                                                                                              |
 | -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
@@ -314,7 +326,7 @@ Client validation appears on the first blur and updates as invalid input is corr
 | `PermGuard`          | Permission guard                                 | `permissions`, `mode`, `fallback`                                                                      |
 | `UserProfile`        | User profile                                     | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint`, `onsubmit` |
 
-#### Storage (4)
+##### Storage (4)
 
 | Component      | Description   | Key props                                                    |
 | -------------- | ------------- | ------------------------------------------------------------ |
@@ -325,7 +337,7 @@ Client validation appears on the first blur and updates as invalid input is corr
 
 Upload components do not embed presigning, headers, or PUT/POST protocols. Applications call their service through `uploadHandler(file, { signal, onProgress })` and return `{ url?, response? }`. Image/avatar uploads require a displayable `url`. Without a handler, `FileUpload` only selects files, and image/avatar components generate local previews only.
 
-#### Crypto display (3)
+##### Crypto display (3)
 
 Input changes immediately clear `encryptedValue`; only successful results for current input are restored. Clearing, callback replacement, and unmounting invalidate old requests. Failures show built-in errors and leave ciphertext empty. Submit encrypted inputs only when current ciphertext is nonempty.
 
@@ -339,7 +351,7 @@ Callers must connect `EncryptedInput` to a real encryption service through `onen
 
 Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and `SM2` for signatures.
 
-#### AI documents and spreadsheets (4)
+##### AI documents and spreadsheets (4)
 
 | Component                | Description            | Key props / capabilities                                                                                   |
 | ------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -370,7 +382,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
 />
 ```
 
-#### Charts
+##### Charts
 
 `Chart type='line'` uses LayerChart's native line chart by default. For monitoring dashboards with segmented lines, points, nearest-point hover, and vertical reference lines, use `lineVariant='segmented-point'`:
 
@@ -389,7 +401,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
 />
 ```
 
-#### CRUD scenes (5)
+##### CRUD scenes (5)
 
 | Component           | Description                                     | Key props / capabilities                                                                                                                                                                                                                                                    |
 | ------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -405,7 +417,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
 >
 > Columns first shrink to 7rem and truncate long text; horizontal scrolling appears only if total width still exceeds the container. The action column stays fixed on the right.
 
-#### Error pages (1)
+##### Error pages (1)
 
 | Component   | Description                                         | Key props / capabilities                                                |
 | ----------- | --------------------------------------------------- | ----------------------------------------------------------------------- |
@@ -436,9 +448,9 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
 >
 > `Tabs` supports lazy content. With `lazy`, never-activated panes are not rendered (`children` receives `isActivated(key)`); `onactivate(key)` runs once on first activation. Combine with `createCrudController({ autoLoad: false })` to load only when first visible.
 
-## Examples
+### Examples
 
-### Toast notifications
+#### Toast notifications
 
 ```svelte
 <script>
@@ -458,7 +470,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
 
 > Built-in `notifySuccess` / `notifyError` / `notifyInfo` / `notifyWarning` remove the need for application toast wrappers. `notifyError(err, fallback?)` accepts `Error` or strings with a fallback message. Success lasts 3s and errors 5s by default.
 
-### Message feedback
+#### Message feedback
 
 ```svelte
 <script>
@@ -476,7 +488,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
 <MessageContainer />
 ```
 
-### Typical CRUD page
+#### Typical CRUD page
 
 ```svelte
 <script>
@@ -546,7 +558,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
 
 `Modal` retains the top-right close button without a `title` / `header`, but does not render a full header row. Use `radius="1.4rem"` for rounded corners and `bodyOverflow="visible"` when internal dropdowns/overlays need to extend outside.
 
-### Declarative CRUD page (CrudPage)
+#### Declarative CRUD page (CrudPage)
 
 ```svelte
 <script lang='ts'>
@@ -572,7 +584,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
 
 > Use `form={{ variant: 'drawer', drawerWidth: '40rem' }}` for drawers. User resizing overrides the initial width and is remembered per resource.
 
-### Login page
+#### Login page
 
 ```svelte
 <script>
@@ -598,7 +610,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
 <LoginForm {loading} {errors} onsubmit={handleLogin} showRegisterLink />
 ```
 
-### Controlled PasswordInput
+#### Controlled PasswordInput
 
 ```svelte
 <script>
@@ -615,7 +627,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
 />
 ```
 
-## Style dependencies
+### Style dependencies
 
 Components use TailwindCSS v4 + DaisyUI. Configure application `app.css` as follows:
 
@@ -654,7 +666,7 @@ On mobile pages, match `BottomNav` width to the page shell to avoid spanning the
 </div>
 ```
 
-### Icons
+#### Icons
 
 Components use Iconify (Tabler Icons):
 
@@ -669,7 +681,7 @@ npm install -D @iconify/tailwind4 @iconify-json/tabler
 }
 ```
 
-### Theme switching
+#### Theme switching
 
 Manage 15 curated DaisyUI themes through built-in utilities:
 
@@ -713,7 +725,7 @@ const themeBootstrapScript = createThemeBootstrapScript({
 transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstrapScript)
 ```
 
-## Internationalization (i18n)
+### Internationalization (i18n)
 
 @h-ai/ui uses **built-in component translations**:
 
@@ -722,7 +734,7 @@ transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstr
 - Applications handle **page text** only; @h-ai/ui manages internal component text.
 - Override specific text with props such as `submitText` or `labels`.
 
-### createLocaleStore
+#### createLocaleStore
 
 Client locale state management, automatically synchronized with the `@h-ai/core` global locale manager:
 
@@ -746,7 +758,7 @@ Client locale state management, automatically synchronized with the `@h-ai/core`
 </select>
 ```
 
-### Exported i18n utilities
+#### Exported i18n utilities
 
 ```ts
 import {
@@ -762,7 +774,7 @@ import {
 } from '@h-ai/ui/i18n'
 ```
 
-## Configuration driven authentication
+### Configuration driven authentication
 
 Agreement content can be configured as `agreements.userAgreementMarkdown` and `privacyPolicyMarkdown` using YAML `|`. The modal safely renders configured Markdown and prefers it over the URL of the same agreement. URL-only content stays in a sandboxed iframe.
 
@@ -791,9 +803,11 @@ AuthPanel accepts public IAM config and actions for password/LDAP/email/SMS logi
 
 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.
 
+When an authentication link points to the current complete URL, AuthPanel switches scenes without navigating again, so input entered after returning to login is preserved. Links with a different path, query, or hash use application routing. Modified clicks such as Ctrl/Cmd retain browser behavior.
+
 [完整 IAM 配置 / IAM configuration](../iam/README.en.md)
 
-## Onboarding and help center
+### 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.
 
@@ -845,7 +859,7 @@ Use `() => m.key()` for localized content and pass the current locale. Steps ren
 
 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
+### Other exports
 
 ```ts
 // 类型
@@ -875,3 +889,16 @@ Agreements open in a Modal and preserve form input. Pages must allow iframe embe
   {/snippet}
 </AuthPanel>
 ```
+
+## Development and testing
+
+```sh
+pnpm --filter @h-ai/ui typecheck
+pnpm --filter @h-ai/ui lint
+pnpm --filter @h-ai/ui build
+pnpm --filter @h-ai/ui test
+```
+
+## License
+
+Apache-2.0

package/README.ja.md

@@ -4,19 +4,29 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
 
-> Svelte 5 Runes のクロスプラットフォーム UI ライブラリーです。DaisyUI v5 + Tailwind CSS v4 のスタイル、Bits UI v2 のヘッドレス UI、内蔵 i18n（zh-CN / en-US）、15 種類の厳選テーマを提供します。
+## 概要
 
-## インストール
+Svelte 5 Runes のクロスプラットフォーム UI ライブラリーです。DaisyUI v5 + Tailwind CSS v4 のスタイル、Bits UI v2 のヘッドレス UI、内蔵 i18n（zh-CN / en-US）、15 種類の厳選テーマを提供します。
+
+## 主な機能
+
+- フォーム、テーブル、ダイアログ、ナビゲーション、チャートなどの部品。
+- 認証、CRUD、AI コンテンツ、操作ガイド、ヘルプセンター。
+- Svelte 5、テーマ、レスポンシブ表示、中国語・英語のコンポーネント文言。
+
+## 使い始める
+
+### インストール
 
 ```bash
-npm install @h-ai/ui
+npm install @h-ai/ui @h-ai/core
 ```
 
-`@h-ai/core` に依存し、自動的にインストールされます。
+Node サーバーでは UI と core の両方を本番依存に含め、ログなどのネイティブ依存を通常どおり読み込めるようにします。
 
-## クイックスタート
+### クイックスタート
 
-### 1. svelte.config.js の設定
+#### 1. svelte.config.js の設定
 
 ```js
 import { autoImportHaiUi } from '@h-ai/ui/auto-import'
@@ -33,7 +43,7 @@ const config = {
 export default config
 ```
 
-### 2. vite.config.ts の設定
+#### 2. vite.config.ts の設定
 
 ```ts
 import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
@@ -51,11 +61,13 @@ export default defineConfig({
     // 避免首次进入业务路由时触发依赖再优化与整页刷新
     include: [...haiPrebundledDeps],
   },
-  ssr: { noExternal: [/@h-ai\//] },
+  ssr: { noExternal: ['@h-ai/ui', '@h-ai/kit'], external: ['@h-ai/core', 'sm-crypto'] },
 })
 ```
 
-### 3. src/app.css の設定
+Crypto または Kit/IAM を使う場合、アプリの本番依存に `sm-crypto@0.5.7` を含めます。CLI 生成済みのプロジェクトでは設定済みです。手動導入は `pnpm add sm-crypto@0.5.7` を実行してください。adapter-node は直接の本番依存も参照するため、external 指定だけでは不十分です。
+
+#### 3. src/app.css の設定
 
 ```css
 @import 'tailwindcss';
@@ -76,7 +88,7 @@ export default defineConfig({
 
 > `@source` で TailwindCSS に `@h-ai/ui` の class を走査させます。ない場合はスタイルが欠落します。monorepo 内のアプリでは依存がルート `node_modules` に置かれる場合があるため、両方のパスを残すことを推奨します。
 
-### 4. コンポーネントの使用
+#### 4. コンポーネントの使用
 
 ```svelte
 <script>
@@ -108,7 +120,7 @@ import { Button } from '@h-ai/ui/components/primitives/index'
 import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
 ```
 
-### data-\* 属性の転送
+#### data-\* 属性の転送
 
 公開 Svelte コンポーネントは `data-*` をルート・主操作要素へ転送し、テスト・計測・自動化に使えます。通常の未知属性は転送しません。
 
@@ -120,7 +132,7 @@ import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
 
 `data-testid` のためだけにボタン・入力・ポップアップをラップする必要はありません。
 
-## コンポーネント構成
+### コンポーネント構成
 
 3 層で構成します（primitives → compounds → scenes）：
 
@@ -137,9 +149,9 @@ components/
     └── crypto/   # 暗号表示
 ```
 
-## コンポーネント一覧
+### コンポーネント一覧
 
-### Primitives：基本コンポーネント（20）
+#### Primitives：基本コンポーネント（20）
 
 | コンポーネント   | 説明                   | 主なプロパティ                                                                 |
 | ---------------- | ---------------------- | ------------------------------------------------------------------------------ |
@@ -166,9 +178,9 @@ components/
 
 `BareInput` の `type="file"` では `onchange` の `event.currentTarget.files` を読み取り、ファイルパスの `value` はバインドしません。他の入力型では `bind:value` を使用できます。
 
-### Compounds：複合コンポーネント（37）
+#### Compounds：複合コンポーネント（37）
 
-#### フォーム
+##### フォーム
 
 | コンポーネント | 説明               | 主なプロパティ                               |
 | -------------- | ------------------ | -------------------------------------------- |
@@ -177,7 +189,7 @@ components/
 | `FormLayout` | フォーム配置 | `columns`, `labelPosition`, `labelWidth` |
 | `TagInput`     | タグ入力           | `tags`, `maxTags`, `allowDuplicates`, `size` |
 
-#### フォームのレイアウトと検証
+##### フォームのレイアウトと検証
 
 `Form` とネイティブ `<form>` 内で使う `FormLayout` は、`columns={1 | 2}`、`labelPosition="top" | "left"`、`labelWidth`（既定 `8rem`）を共有します。既定は1列・ラベルを上に配置します。コンテナー幅が `36rem` 未満では1列、`28rem` 未満では横並びラベルも縦並びになります。
 
@@ -206,14 +218,14 @@ components/
 </Form>
 ```
 
-#### フィードバック
+##### フィードバック
 
 | コンポーネント   | 説明           | 主なプロパティ                           |
 | ---------------- | -------------- | ---------------------------------------- |
 | `Alert`          | アラート       | `variant`, `title`, `dismissible`        |
 | `ToastContainer` | 通知コンテナー | 全体に配置し、`toast` シングルトンと併用 |
 
-#### オーバーレイ
+##### オーバーレイ
 
 | コンポーネント | 説明           | 主なプロパティ                                                               |
 | -------------- | -------------- | ---------------------------------------------------------------------------- |
@@ -222,7 +234,7 @@ components/
 | `Confirm`      | 確認ダイアログ | `open`, `title`, `message`, `variant`, `onconfirm`                           |
 | `Popover`      | ポップオーバー | `open`, `position`, `trigger`, `offset`, `portal`                            |
 
-#### データ表示
+##### データ表示
 
 | コンポーネント | 説明             | 主なプロパティ                                                                                                                        |
 | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
@@ -231,7 +243,7 @@ components/
 | `Accordion`    | アコーディオン   | `items: AccordionItem[]`                                                                                                              |
 | `Timeline`     | タイムライン     | `items: TimelineItem[]`                                                                                                               |
 
-#### Bits UI によるヘッドレス UI
+##### Bits UI によるヘッドレス UI
 
 | コンポーネント | 説明                       | 主なプロパティ                                              |
 | -------------- | -------------------------- | ----------------------------------------------------------- |
@@ -241,7 +253,7 @@ components/
 
 > 日付値には `@internationalized/date` の `DateValue` / `CalendarDate` を使います。
 
-#### モバイル・拡張操作
+##### モバイル・拡張操作
 
 | コンポーネント   | 説明                   | 主なプロパティ                                         |
 | ---------------- | ---------------------- | ------------------------------------------------------ |
@@ -253,7 +265,7 @@ components/
 | `SafeArea`       | セーフエリアコンテナー | `top`, `bottom`, `left`, `right`                       |
 | `SwipeCell`      | スワイプ操作           | `leftActions`, `rightActions`, `threshold`, `onaction` |
 
-#### ナビゲーション
+##### ナビゲーション
 
 | コンポーネント | 説明                              | 主なプロパティ                                                                                             |
 | -------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -264,7 +276,7 @@ components/
 | `Dropdown`     | ドロップダウンメニュー            | `items`, `trigger`, `triggerClass`, `position`                                                             |
 | `Tooltip`      | ツールチップ                      | `content`, `position`, `delay`                                                                             |
 
-#### 状態表示
+##### 状態表示
 
 | コンポーネント | 説明       | 主なプロパティ                        |
 | -------------- | ---------- | ------------------------------------- |
@@ -272,22 +284,22 @@ components/
 | `Empty`        | 空状態     | `title`, `description`, `icon`        |
 | `Result`       | 結果ページ | `status`, `title`, `description`      |
 
-#### ページ単位
+##### ページ単位
 
 | コンポーネント | 説明           | 主なプロパティ                                 |
 | -------------- | -------------- | ---------------------------------------------- |
 | `PageHeader`   | ページヘッダー | `title`, `description`、`actions` スロット対応 |
 
-### Scenes：用途別コンポーネント（36）
+#### Scenes：用途別コンポーネント（36）
 
-#### Guide：案内・ヘルプ（2）
+##### Guide：案内・ヘルプ（2）
 
 | コンポーネント | 説明 | 主なプロパティ |
 | --- | --- | --- |
 | `GuideHost` | 初回案内・ガイド・ヘルプダイアログ | `guide`, `locale`, `scope`, `autoStart` |
 | `HelpCenter` | 独立して使える検索付きヘルプ | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
 
-#### App：アプリ全体（7）
+##### App：アプリ全体（7）
 
 | コンポーネント     | 説明                                        | 主なプロパティ                                           |
 | ------------------ | ------------------------------------------- | -------------------------------------------------------- |
@@ -299,7 +311,7 @@ components/
 | `ThemeSelector`    | テーマ選択パネル                            | プロパティ不要                                           |
 | `ThemeToggle`      | ライト・ダーク切り替え                      | プロパティ不要                                           |
 
-#### IAM：認証（10）
+##### IAM：認証（10）
 
 | コンポーネント       | 説明                                    | 主なプロパティ                                                                                         |
 | -------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------ |
@@ -314,7 +326,7 @@ components/
 | `PermGuard`          | 権限ガード                              | `permissions`, `mode`, `fallback`                                                                      |
 | `UserProfile`        | ユーザープロフィール                    | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint`, `onsubmit` |
 
-#### Storage：ストレージ（4）
+##### Storage：ストレージ（4）
 
 | コンポーネント | 説明                 | 主なプロパティ                                               |
 | -------------- | -------------------- | ------------------------------------------------------------ |
@@ -325,7 +337,7 @@ components/
 
 アップロード部品は presign・ヘッダー・PUT/POST を内蔵しません。アプリは `uploadHandler(file, { signal, onProgress })` からサービスを呼び、`{ url?, response? }` を返します。画像・アバターには表示可能な `url` が必要です。handler がなければ `FileUpload` は選択のみ、画像・アバターはローカルのプレビューのみを作成します。
 
-#### Crypto：暗号表示（3）
+##### Crypto：暗号表示（3）
 
 入力変更で `encryptedValue` を即座に消去し、現在の入力の成功結果のみを反映します。消去・コールバック置換・破棄で旧リクエストを無効化します。失敗時は組み込みエラーを表示し暗号文は空です。暗号化対象の送信は現在の暗号文が空でない場合に限ってください。
 
@@ -339,7 +351,7 @@ components/
 
 既定は `@h-ai/crypto` と共通で、暗号化入力は `SM4`、ハッシュは `SM3`、署名は `SM2` です。
 
-#### AI：文書・表計算（4）
+##### AI：文書・表計算（4）
 
 | コンポーネント           | 説明                     | 主なプロパティ・機能                                                                                       |
 | ------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
@@ -370,7 +382,7 @@ components/
 />
 ```
 
-#### Charts：グラフ
+##### Charts：グラフ
 
 `Chart type='line'` は既定で LayerChart の折れ線を使います。監視画面で分割線・点・最寄りの点への hover・縦基準線が必要な場合は `lineVariant='segmented-point'` を使います：
 
@@ -389,7 +401,7 @@ components/
 />
 ```
 
-#### CRUD：一覧操作（5）
+##### CRUD：一覧操作（5）
 
 | コンポーネント      | 説明                                                   | 主なプロパティ・機能                                                                                                                                                                                                                                                        |
 | ------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -405,7 +417,7 @@ components/
 >
 > 列は先に 7rem まで縮小し長文を切り詰め、総幅が容器を超える場合のみ横スクロールを出します。操作列は右に固定し、横スクロール中も表示します。
 
-#### エラーページ（1）
+##### エラーページ（1）
 
 | コンポーネント | 説明                                               | 主なプロパティ・機能                                                    |
 | -------------- | -------------------------------------------------- | ----------------------------------------------------------------------- |
@@ -436,9 +448,9 @@ components/
 >
 > `Tabs` は遅延表示に対応し、`lazy` では未使用タブの内容を描画しません（`children` の `isActivated(key)` で判定）。`onactivate(key)` は初回のみ実行し、`createCrudController({ autoLoad: false })` と組み合わせて最初に表示されたときに読み込めます。
 
-## 使用例
+### 使用例
 
-### Toast 通知
+#### Toast 通知
 
 ```svelte
 <script>
@@ -458,7 +470,7 @@ components/
 
 > `notifySuccess` / `notifyError` / `notifyInfo` / `notifyWarning` を内蔵し、アプリ独自の toast ツールは不要です。`notifyError(err, fallback?)` は `Error`・文字列と代替文言を受け付け、既定は成功 3 秒・失敗 5 秒です。
 
-### Message 表示
+#### Message 表示
 
 ```svelte
 <script>
@@ -476,7 +488,7 @@ components/
 <MessageContainer />
 ```
 
-### 標準的な CRUD ページ
+#### 標準的な CRUD ページ
 
 ```svelte
 <script>
@@ -546,7 +558,7 @@ components/
 
 `Modal` は `title` / `header` がなくても右上の閉じるボタンを表示し、ヘッダー全体は追加しません。角丸は `radius="1.4rem"`、内部ドロップダウンなどを外に表示する場合は `bodyOverflow="visible"` を指定できます。
 
-### 宣言的な CRUD ページ（CrudPage）
+#### 宣言的な CRUD ページ（CrudPage）
 
 ```svelte
 <script lang='ts'>
@@ -572,7 +584,7 @@ components/
 
 > ドロワーは `form={{ variant: 'drawer', drawerWidth: '40rem' }}` に変更できます。ユーザーが変更した幅が初期幅より優先され、リソースごとに記憶されます。
 
-### ログインページ
+#### ログインページ
 
 ```svelte
 <script>
@@ -598,7 +610,7 @@ components/
 <LoginForm {loading} {errors} onsubmit={handleLogin} showRegisterLink />
 ```
 
-### PasswordInput の制御モード
+#### PasswordInput の制御モード
 
 ```svelte
 <script>
@@ -615,7 +627,7 @@ components/
 />
 ```
 
-## スタイルの依存関係
+### スタイルの依存関係
 
 コンポーネントは TailwindCSS v4 + DaisyUI を使います。アプリの `app.css` に次を設定します：
 
@@ -654,7 +666,7 @@ components/
 </div>
 ```
 
-### アイコン
+#### アイコン
 
 Iconify（Tabler Icons）を使用します：
 
@@ -669,7 +681,7 @@ npm install -D @iconify/tailwind4 @iconify-json/tabler
 }
 ```
 
-### テーマ切り替え
+#### テーマ切り替え
 
 内蔵ツールで 15 種類の厳選 DaisyUI テーマを管理します：
 
@@ -713,7 +725,7 @@ const themeBootstrapScript = createThemeBootstrapScript({
 transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstrapScript)
 ```
 
-## 国際化（i18n）
+### 国際化（i18n）
 
 @h-ai/ui は**コンポーネント内蔵翻訳**を使います：
 
@@ -722,7 +734,7 @@ transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstr
 - アプリは**ページ単位の文言**のみを扱い、内部テキストは @h-ai/ui が管理します。
 - 個別文言の変更は `submitText`・`labels` などの props で指定。
 
-### createLocaleStore
+#### createLocaleStore
 
 クライアントの locale 状態を管理し、`@h-ai/core` の全体管理器へ自動同期します：
 
@@ -746,7 +758,7 @@ transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstr
 </select>
 ```
 
-### エクスポートされる i18n ツール
+#### エクスポートされる i18n ツール
 
 ```ts
 import {
@@ -762,7 +774,7 @@ import {
 } from '@h-ai/ui/i18n'
 ```
 
-## 設定による認証画面
+### 設定による認証画面
 
 YAML の `|` で `agreements.userAgreementMarkdown` と `privacyPolicyMarkdown` を設定できます。Modal は本文を安全に描画し、同じ規約の URL より本文を優先します。URL のみの場合は隔離 iframe を使用します。
 
@@ -791,9 +803,11 @@ AuthPanel に IAM 公開設定と actions を渡すと、複数方式のログ
 
 AuthPanel は SSR 中のフォーム操作を無効にし、クライアントのマウントとイベント登録が完了してから入力を有効にします。ハイドレーションによる入力の消失を防ぎ、アプリ側の追加の準備処理は不要です。E2E では入力可能な状態を待ち、クライアントスクリプトの読み込みが遅れる場合も検証します。
 
+認証リンクが現在の完全な URL を指す場合、AuthPanel は再ナビゲーションせずに画面だけを切り替え、ログインに戻った直後の入力を保持します。パス、クエリー、hash が異なる場合はアプリのルーターに任せます。Ctrl/Cmd などの修飾キーを使ったクリックはブラウザーの動作を維持します。
+
 [完整 IAM 配置 / IAM configuration](../iam/README.ja.md)
 
-## 初回ガイドとヘルプセンター
+### 初回ガイドとヘルプセンター
 
 `@h-ai/ui/guide` から `createGuide`、`GuideHost`、`HelpCenter` をインポートします。init/close は不要です。ガイド開始時にエンジンを読み込み、既存テーマと中国語・英語の共通文言を使用します。業務内容はアプリの翻訳関数を使います。
 
@@ -845,7 +859,7 @@ start(id) は Promise<boolean> を返し、手動で再表示できます。失
 
 HelpCenter は articles、任意の tours、locale、selectedId、onstart で独立ページにも配置できます。admin-console と CLI fullstack Web/App/Desktop は初回案内、ヘルプ、プロフィールガイドを標準搭載します。[詳細ガイド](../cli/templates/skills/hai-ui/guide.md)を参照してください。
 
-## その他のエクスポート
+### その他のエクスポート
 
 ```ts
 // 类型
@@ -875,3 +889,16 @@ import { toast } from '@h-ai/ui'
   {/snippet}
 </AuthPanel>
 ```
+
+## 開発とテスト
+
+```sh
+pnpm --filter @h-ai/ui typecheck
+pnpm --filter @h-ai/ui lint
+pnpm --filter @h-ai/ui build
+pnpm --filter @h-ai/ui test
+```
+
+## ライセンス
+
+Apache-2.0

package/README.md

@@ -4,19 +4,29 @@
 
 [框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
 
-> 基于 Svelte 5 Runes 的多端 UI 组件库，采用 DaisyUI v5 + Tailwind CSS v4 样式 + Bits UI v2 headless 交互，内置 i18n（zh-CN / en-US），内置 15 个精选 DaisyUI 主题。
+## 简介
 
-## 安装
+基于 Svelte 5 Runes 的多端 UI 组件库，采用 DaisyUI v5 + Tailwind CSS v4 样式 + Bits UI v2 headless 交互，内置 i18n（zh-CN / en-US），内置 15 个精选 DaisyUI 主题。
+
+## 核心功能清单
+
+- 表单、表格、弹窗、导航、图表与业务场景组件。
+- 认证、CRUD、AI 内容展示、新手引导和帮助中心。
+- Svelte 5、主题切换、响应式布局及中英文组件文案。
+
+## 使用入门
+
+### 安装
 
 ```bash
-npm install @h-ai/ui
+npm install @h-ai/ui @h-ai/core
 ```
 
-依赖 `@h-ai/core`（会自动安装）。
+Node 服务端工程将 UI 与 core 都列为生产依赖，确保适配器保留 core 的日志和原生依赖加载。
 
-## 快速开始
+### 快速开始
 
-### 1. 配置 svelte.config.js
+#### 1. 配置 svelte.config.js
 
 ```js
 import { autoImportHaiUi } from '@h-ai/ui/auto-import'
@@ -33,7 +43,7 @@ const config = {
 export default config
 ```
 
-### 2. 配置 vite.config.ts
+#### 2. 配置 vite.config.ts
 
 ```ts
 import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
@@ -51,11 +61,13 @@ export default defineConfig({
     // 避免首次进入业务路由时触发依赖再优化与整页刷新
     include: [...haiPrebundledDeps],
   },
-  ssr: { noExternal: [/@h-ai\//] },
+  ssr: { noExternal: ['@h-ai/ui', '@h-ai/kit'], external: ['@h-ai/core', 'sm-crypto'] },
 })
 ```
 
-### 3. 配置 src/app.css
+使用 Crypto 或依赖它的 Kit/IAM 时，应用生产依赖需包含 `sm-crypto@0.5.7`。CLI 已配好这一项；手工接入时运行 `pnpm add sm-crypto@0.5.7`。仅设置 external 不够，adapter-node 还需要这项直接依赖声明才能保留原包加载。
+
+#### 3. 配置 src/app.css
 
 ```css
 @import 'tailwindcss';
@@ -76,7 +88,7 @@ export default defineConfig({
 
 > `@source` 让 TailwindCSS 扫描 `@h-ai/ui` 组件中使用的 class 名，否则组件样式会丢失。嵌套应用位于 monorepo 中时，依赖包可能被提升到工作区根 `node_modules`，所以建议同时保留两条路径。
 
-### 4. 使用组件
+#### 4. 使用组件
 
 ```svelte
 <script>
@@ -108,7 +120,7 @@ import { Button } from '@h-ai/ui/components/primitives/index'
 import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
 ```
 
-### data-* 属性透传
+#### data-* 属性透传
 
 公开 Svelte 组件支持把调用方传入的 `data-*` 属性透传到组件根节点或主交互节点，便于测试选择器、埋点和自动化标记。普通未知属性不会被透传。
 
@@ -120,7 +132,7 @@ import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
 
 无需再为了 `data-testid` 单独封装按钮、输入框或弹层组件。
 
-## 组件架构
+### 组件架构
 
 组件按三层划分（primitives → compounds → scenes）：
 
@@ -137,9 +149,9 @@ components/
     └── crypto/   # 加密展示
 ```
 
-## 组件清单
+### 组件清单
 
-### 原子组件 Primitives（20 个）
+#### 原子组件 Primitives（20 个）
 
 | 组件             | 描述         | 主要属性                                                           |
 | ---------------- | ------------ | ------------------------------------------------------------------ |
@@ -166,9 +178,9 @@ components/
 
 `BareInput` 的 `file` 类型通过 `onchange` 读取 `event.currentTarget.files`，不绑定文件路径 `value`；其他输入类型可使用 `bind:value`。
 
-### 组合组件 Compounds（37 个）
+#### 组合组件 Compounds（37 个）
 
-#### 表单
+##### 表单
 
 | 组件        | 描述     | 主要属性                                     |
 | ----------- | -------- | -------------------------------------------- |
@@ -177,7 +189,7 @@ components/
 | `FormLayout` | 表单布局 | `columns`, `labelPosition`, `labelWidth` |
 | `TagInput`  | 标签输入 | `tags`, `maxTags`, `allowDuplicates`, `size` |
 
-#### 表单布局与校验
+##### 表单布局与校验
 
 `Form` 和可嵌入原生 `<form>` 的 `FormLayout` 共用 `columns={1 | 2}`、`labelPosition="top" | "left"`、`labelWidth`（默认 `8rem`）。默认单列、标签独立成行；双列在容器不足 `36rem` 时收为单列，同行标签在容器不足 `28rem` 时改为上下排列。
 
@@ -206,14 +218,14 @@ components/
 </Form>
 ```
 
-#### 反馈
+##### 反馈
 
 | 组件             | 描述     | 主要属性                          |
 | ---------------- | -------- | --------------------------------- |
 | `Alert`          | 警告框   | `variant`, `title`, `dismissible` |
 | `ToastContainer` | 通知容器 | 全局放置，配合 `toast` 单例使用   |
 
-#### 弹层
+##### 弹层
 
 | 组件      | 描述   | 主要属性                                                |
 | --------- | ------ | ------------------------------------------------------- |
@@ -222,7 +234,7 @@ components/
 | `Confirm` | 确认框 | `open`, `title`, `message`, `variant`, `onconfirm`      |
 | `Popover` | 弹出层 | `open`, `position`, `trigger`, `offset`, `portal`       |
 
-#### 数据展示
+##### 数据展示
 
 | 组件        | 描述     | 主要属性                                 |
 | ----------- | -------- | ---------------------------------------- |
@@ -231,7 +243,7 @@ components/
 | `Accordion` | 手风琴   | `items: AccordionItem[]`                 |
 | `Timeline`  | 时间线   | `items: TimelineItem[]`                  |
 
-#### Bits UI headless 交互
+##### Bits UI headless 交互
 
 | 组件         | 描述                        | 主要属性                                                    |
 | ------------ | --------------------------- | ----------------------------------------------------------- |
@@ -241,7 +253,7 @@ components/
 
 > 日期值使用 `@internationalized/date` 的 `DateValue` / `CalendarDate` 类型。
 
-#### 移动端 / 增强交互
+##### 移动端 / 增强交互
 
 | 组件             | 描述         | 主要属性                                            |
 | ---------------- | ------------ | --------------------------------------------------- |
@@ -253,7 +265,7 @@ components/
 | `SafeArea`       | 安全区域容器 | `top`, `bottom`, `left`, `right`                    |
 | `SwipeCell`      | 滑动操作单元 | `leftActions`, `rightActions`, `threshold`, `onaction` |
 
-#### 导航
+##### 导航
 
 | 组件         | 描述     | 主要属性                                     |
 | ------------ | -------- | -------------------------------------------- |
@@ -264,7 +276,7 @@ components/
 | `Dropdown`   | 下拉菜单 | `items`, `trigger`, `triggerClass`, `position` |
 | `Tooltip`    | 提示     | `content`, `position`, `delay`               |
 
-#### 状态占位
+##### 状态占位
 
 | 组件       | 描述   | 主要属性                              |
 | ---------- | ------ | ------------------------------------- |
@@ -272,22 +284,22 @@ components/
 | `Empty`    | 空状态 | `title`, `description`, `icon`        |
 | `Result`   | 结果页 | `status`, `title`, `description`      |
 
-#### 页面级
+##### 页面级
 
 | 组件         | 描述     | 主要属性                                    |
 | ------------ | -------- | ------------------------------------------- |
 | `PageHeader` | 页面头部 | `title`, `description`，支持 `actions` 插槽 |
 
-### 场景组件 Scenes（36 个）
+#### 场景组件 Scenes（36 个）
 
-#### Guide 引导与帮助（2 个）
+##### Guide 引导与帮助（2 个）
 
 | 组件 | 描述 | 主要属性 |
 | --- | --- | --- |
 | `GuideHost` | 首次邀请、页面导览与帮助弹窗宿主 | `guide`, `locale`, `scope`, `autoStart` |
 | `HelpCenter` | 可独立使用的帮助中心 | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
 
-#### App 应用级（7 个）
+##### App 应用级（7 个）
 
 | 组件             | 描述             | 主要属性           |
 | ---------------- | ---------------- | ------------------ |
@@ -299,7 +311,7 @@ components/
 | `ThemeSelector`  | 完整主题选择面板 | 无需 Props         |
 | `ThemeToggle`    | 明/暗主题切换    | 无需 Props         |
 
-#### IAM 身份认证（10 个）
+##### IAM 身份认证（10 个）
 
 | 组件                 | 描述       | 主要属性                                              |
 | -------------------- | ---------- | ----------------------------------------------------- |
@@ -314,7 +326,7 @@ components/
 | `PermGuard`          | 权限守卫   | `permissions`, `mode`, `fallback`                     |
 | `UserProfile`        | 用户资料   | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint`, `onsubmit` |
 
-#### Storage 存储（4 个）
+##### Storage 存储（4 个）
 
 | 组件           | 描述     | 主要属性                                                 |
 | -------------- | -------- | -------------------------------------------------------- |
@@ -325,7 +337,7 @@ components/
 
 上传组件不内置 presign、请求头或 PUT/POST 协议。应用层通过 `uploadHandler(file, { signal, onProgress })` 调用自己的 service，并返回 `{ url?, response? }`；图片和头像上传需要返回可展示的 `url`。未提供 handler 时，`FileUpload` 只选择文件，图片/头像组件只生成本地预览。
 
-#### Crypto 加密展示（3 个）
+##### Crypto 加密展示（3 个）
 
 输入变化立即清空 `encryptedValue`，只有当前输入的成功结果会回填；清空、回调替换和卸载均使旧请求失效。失败显示内置错误提示且密文保持为空；表单应仅在当前密文非空时提交需要加密的输入。
 
@@ -339,7 +351,7 @@ components/
 
 默认算法与 `@h-ai/crypto` 对齐：加密输入使用 `SM4`，哈希展示使用 `SM3`，签名展示使用 `SM2`。
 
-#### AI 文档与表格（4 个）
+##### AI 文档与表格（4 个）
 
 | 组件                     | 描述             | 主要属性 / 能力 |
 | ------------------------ | ---------------- | ---------------- |
@@ -369,7 +381,7 @@ components/
 />
 ```
 
-#### Charts 图表
+##### Charts 图表
 
 `Chart type='line'` 默认透传 LayerChart 原生折线图；需要监控看板常见的“分段线 + 圆点 + 最近点 hover + 竖向参考线”时，使用 `lineVariant='segmented-point'`：
 
@@ -388,7 +400,7 @@ components/
 />
 ```
 
-#### CRUD 场景（5 个）
+##### CRUD 场景（5 个）
 
 | 组件                 | 描述         | 主要属性 / 能力 |
 | -------------------- | ------------ | ---------------- |
@@ -404,7 +416,7 @@ components/
 >
 > 表格列会优先压缩到 7rem 并截断超长文本；列总宽度仍超过容器时才显示横向滚动条。操作列固定在右侧，横向滚动时保持可见。
 
-#### 错误页场景（1 个）
+##### 错误页场景（1 个）
 
 | 组件        | 描述         | 主要属性 / 能力 |
 | ----------- | ------------ | ---------------- |
@@ -435,9 +447,9 @@ components/
 >
 > `Tabs` 支持惰性页签：`lazy` 开启后未激活过的页签内容不渲染（`children` 提供 `isActivated(key)` 判断），`onactivate(key)` 在页签首次激活时触发一次，适合配合 `createCrudController({ autoLoad: false })` 在首次可见时才加载。
 
-## 使用示例
+### 使用示例
 
-### Toast 通知
+#### Toast 通知
 
 ```svelte
 <script>
@@ -457,7 +469,7 @@ components/
 
 > 已内置 `notifySuccess` / `notifyError` / `notifyInfo` / `notifyWarning` 封装，业务应用无需自建 toast 工具文件：`notifyError(err, fallback?)` 接受 `Error` 或字符串并内置兑底文案，默认成功 3s / 失败 5s。
 
-### Message 消息提示
+#### Message 消息提示
 
 ```svelte
 <script>
@@ -475,7 +487,7 @@ components/
 <MessageContainer />
 ```
 
-### 典型 CRUD 页面
+#### 典型 CRUD 页面
 
 ```svelte
 <script>
@@ -545,7 +557,7 @@ components/
 
 `Modal` 不传 `title` / `header` 时会保留右上角关闭按钮，但不额外渲染整条头部。需要调整圆角时可传 `radius="1.4rem"`，内部下拉等浮层需要越界显示时可传 `bodyOverflow="visible"`。
 
-### 声明式 CRUD 页面（CrudPage）
+#### 声明式 CRUD 页面（CrudPage）
 
 ```svelte
 <script lang='ts'>
@@ -571,7 +583,7 @@ components/
 
 > 抽屉形式可改用 `form={{ variant: 'drawer', drawerWidth: '40rem' }}`；用户拖动后的宽度会覆盖初始宽度并按资源记忆。
 
-### 登录页面
+#### 登录页面
 
 ```svelte
 <script>
@@ -597,7 +609,7 @@ components/
 <LoginForm {loading} {errors} onsubmit={handleLogin} showRegisterLink />
 ```
 
-### PasswordInput 受控模式
+#### PasswordInput 受控模式
 
 ```svelte
 <script>
@@ -614,7 +626,7 @@ components/
 />
 ```
 
-## 样式依赖
+### 样式依赖
 
 组件基于 TailwindCSS v4 + DaisyUI。应用层 `app.css` 需要以下配置：
 
@@ -653,7 +665,7 @@ components/
 </div>
 ```
 
-### 图标
+#### 图标
 
 组件使用 Iconify (Tabler Icons)：
 
@@ -668,7 +680,7 @@ npm install -D @iconify/tailwind4 @iconify-json/tabler
 }
 ```
 
-### 主题切换
+#### 主题切换
 
 使用内置的主题工具函数管理 15 个精选 DaisyUI 主题：
 
@@ -712,7 +724,7 @@ const themeBootstrapScript = createThemeBootstrapScript({
 transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstrapScript)
 ```
 
-## 国际化 (i18n)
+### 国际化 (i18n)
 
 @h-ai/ui 采用**组件内置翻译**模式：
 
@@ -721,7 +733,7 @@ transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstr
 - 应用层只需处理**页面级文本**，组件内部文本由 @h-ai/ui 统一管理
 - 如需覆盖特定文本，通过 `submitText`、`labels` 等 props 传入
 
-## 配置驱动认证页面
+### 配置驱动认证页面
 
 协议支持 `agreements.userAgreementMarkdown` 与 `privacyPolicyMarkdown` 直接从配置加载；YAML 的 `|` 保留 Markdown 段落和换行。弹窗复用安全 MarkdownRenderer，关闭原始 HTML、脚本和代码复制工具。同主题同时提供正文与 URL 时优先正文，URL 可作为额外查看入口；只有 URL 时使用隔离 iframe。
 
@@ -750,9 +762,11 @@ AuthPanel 直接接收 IAM 白名单配置和 actions，内置登录（密码/LD
 
 AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事件后自动开放输入，避免接管时丢失早到的输入。应用无需额外的就绪适配；E2E 等待控件可编辑，并覆盖客户端脚本延迟加载的场景。
 
+认证链接指向当前完整 URL 时，AuthPanel 只切换场景并阻止重复导航，返回登录后可立即输入。路径、查询串或 hash 不同时交给应用路由处理；Ctrl/Cmd 等修改键点击保留浏览器行为。
+
 [完整 IAM 配置 / IAM configuration](../iam/README.md)
 
-### createLocaleStore
+#### createLocaleStore
 
 用于客户端 locale 状态管理，自动同步到 `@h-ai/core` 全局 locale 管理器：
 
@@ -776,7 +790,7 @@ AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事
 </select>
 ```
 
-### 导出的 i18n 工具
+#### 导出的 i18n 工具
 
 ```ts
 import {
@@ -809,8 +823,7 @@ import {
 
 上例的 subscribe 为应用自身的 $state，应用包装 register 动作校验/提交扩展业务数据；如需单独组合表单，使用 `<RegisterForm> {#snippet extraFields()}...{/snippet} </RegisterForm>`。扩展里的按钮须为 `type="button"`，避免误提交。
 
-
-## 新手引导与帮助中心
+### 新手引导与帮助中心
 
 `@h-ai/ui/guide` 提供 `createGuide`、`GuideHost`、`HelpCenter` 和相关类型。无需 init/close；引擎在开始导览时按需加载，浮层复用当前主题。组件内置中英文按钮、进度和错误提示，业务内容使用应用 i18n。
 
@@ -863,7 +876,7 @@ import {
 
 admin-console 示例和 CLI fullstack Web/App/Desktop 默认包含帮助入口、首次邀请及个人资料导览。完整配置和验证场景见 [引导指南](../cli/templates/skills/hai-ui/guide.md)。
 
-## 其他导出
+### 其他导出
 
 ```ts
 // 类型
@@ -879,3 +892,16 @@ import { cn, generateId, getSizeClass, getVariantClass } from '@h-ai/ui'
 // Toast 单例
 import { toast } from '@h-ai/ui'
 ```
+
+## 开发测试
+
+```sh
+pnpm --filter @h-ai/ui typecheck
+pnpm --filter @h-ai/ui lint
+pnpm --filter @h-ai/ui build
+pnpm --filter @h-ai/ui test
+```
+
+## 许可证
+
+Apache-2.0

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

@@ -73,12 +73,18 @@
 
 {#snippet link(next: AuthPanelMode, label: string, href?: string)}
   {#if href}<a {href} class='link link-primary text-sm' aria-disabled={loading} onclick={(event) => {
-    if (loading)
+    if (loading) {
+      event.preventDefault()
+      return
+    }
+    if (event.defaultPrevented || event.button !== 0 || event.ctrlKey || event.metaKey || event.shiftKey || event.altKey)
+      return
+    // 当前完整 URL 只切换场景，阻止重复导航重建表单并清空刚输入的内容。
+    // 跨路径、查询或 hash 的链接由路由接管；修改键点击保留浏览器的新窗口行为。
+    if (event.currentTarget.href === window.location.href) {
       event.preventDefault()
-    // 跨路径或哈希路由由路由创建新表单；提前切换会让输入被随后导航清空。
-    // 当前路由只更新场景，支持登录页内的找回密码和返回登录。
-    else if (event.currentTarget.origin === window.location.origin && event.currentTarget.pathname === window.location.pathname && event.currentTarget.hash === window.location.hash)
       switchMode(next)
+    }
   }}>{label}</a>
   {:else}<BareButton type='button' class='link link-primary text-sm' disabled={loading} onclick={() => switchMode(next)}>{label}</BareButton>{/if}
 {/snippet}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/ui",
   "type": "module",
-  "version": "0.1.0-alpha.65",
+  "version": "0.1.0-alpha.67",
   "description": "Hai Framework UI component library for Svelte 5 Runes.",
   "license": "Apache-2.0",
   "svelte": "./dist/index.js",
@@ -59,7 +59,7 @@
     "svelte": "^5.57.2"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.65",
+    "@h-ai/core": "0.1.0-alpha.67",
     "@internationalized/date": "^3.12.4",
     "@shikijs/langs": "^4.5.0",
     "bits-ui": "^2.19.5",