@jayyuen66/dsh-plugin-shared 0.2.4 → 0.2.5

package/README.md

@@ -12,7 +12,7 @@
   <a href="https://github.com/JayYuen666/dsh-plugin-shared/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/JayYuen666/dsh-plugin-shared/ci.yml?branch=main&style=flat-square&label=ci" alt="ci" /></a>
   <img src="https://img.shields.io/badge/license-MIT-4c1?style=flat-square" alt="MIT" />
   <img src="https://img.shields.io/badge/node-%3E%3D24.9-4c1?style=flat-square&logo=nodedotjs&logoColor=white" alt="node" />
-  <img src="https://img.shields.io/badge/dsh-%5E0.2.1--rc.5-658EFF?style=flat-square" alt="dsh" />
+  <img src="https://img.shields.io/badge/dsh-%5E0.2.2--rc.1-658EFF?style=flat-square" alt="dsh" />
   <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/powered_by_dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white" alt="powered by dsh" /></a>
 </p>
 
@@ -31,18 +31,23 @@
 
 ## <img src="https://api.iconify.design/lucide/file-text.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> Contents
 
-- [What it does](#what-it-does)
-- [Install](#install)
-- [Verify it is live](#verify-it-is-live)
-- [What it does not provide](#what-it-does-not-provide)
-- [Modules](#modules)
-- [The config exports](#the-config-exports)
-- [Known boundaries](#known-boundaries)
-- [Data and privacy](#data-and-privacy)
-- [Versioning and compatibility](#versioning-and-compatibility)
-- [FAQ](#faq)
-- [Development](#development)
-- [License](#license)
+- [ Contents](#-contents)
+- [ What it does](#-what-it-does)
+  - [What belongs here](#what-belongs-here)
+- [ Install](#-install)
+  - [Dependency requirements](#dependency-requirements)
+  - [Shared version floor](#shared-version-floor)
+  - [What ships](#what-ships)
+- [ Verify it is live](#-verify-it-is-live)
+- [ What it does not provide](#-what-it-does-not-provide)
+- [ Modules](#-modules)
+- [ The config exports](#-the-config-exports)
+- [ Known boundaries](#-known-boundaries)
+- [ Data and privacy](#-data-and-privacy)
+- [ Versioning and compatibility](#-versioning-and-compatibility)
+- [ FAQ](#-faq)
+- [ Development](#-development)
+- [ License](#-license)
 
 ## <img src="https://api.iconify.design/lucide/shield.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> What it does
 
@@ -79,7 +84,7 @@ End users do not install or enable it separately: any consumer package pulls it
 | Requirement | Value |
 | --- | --- |
 | Node.js | `>=24.9.0` — the publish-side floor the plugin family shares, so a package declaring the same `engines.node` never rejects this library |
-| dsh | `^0.2.1-rc.5 || ^0.2.2-alpha.3`, declared as an **optional** peer (importing this package does not need a host) |
+| dsh | `^0.2.2-rc.1`, declared as an **optional** peer (importing this package does not need a host) |
 | Module format | ESM only. `require()` works only where Node supports `require(esm)` |
 | Tree shaking | `"sideEffects": false` |
 
@@ -92,8 +97,8 @@ End users do not install or enable it separately: any consumer package pulls it
 - **`@deepseek-ai/dsh-fs-patch` is the one allowed runtime dependency.** It is a stateless pure parser: it holds no service instance or module-level identity, so a duplicate copy cannot split a `Symbol`. Shipping it makes `apply_patch` syntax resolvable on every host in the supported window. Every other host package stays in peer/dev.
 - **A host package under `dependencies` disables the consumer's host.** Profiles install with `nodeLinker: hoisted` and `autoInstallPeers: false`, so a listed host package is materialized as a real directory next to the copy the host process already loaded. `@deepseek-ai/dsh-tools` keys its tool-runtime scheduler with a plain `Symbol` (not `Symbol.for`), so symbol identity is per module instance: the host reads the scheduler from the duplicate and gets `undefined`, and every native tool call throws. Build, typecheck and tests pass up to that point; the invariant has to be stated in the manifest.
 - **`@deepseek-ai/dsh-output-retention` is the one required peer.** It is a value import (`truncateEnd`), provided by the host at runtime, and marked `"optional": false` in `peerDependenciesMeta` rather than left implicit — a peer left out of that table is a hard requirement for npm 7+.
-- **The remaining peers are optional.** Except for the bare `@deepseek-ai/dsh` peer, which only declares the host line, they carry type declarations only. `devDependencies` holds the exact development line, including `@deepseek-ai/dsh-llm` and `@deepseek-ai/dsh-util-values`, whose types the local PTC declarations name, and `@deepseek-ai/dsh-tool-executor-ptc`, whose types only the parity check reads. Profiles never install peers, so no duplicate appears.
-- **Version requirements separate the install gate from the build baseline.** Every `@deepseek-ai/dsh-*` peer carries the same window as `engines.dsh`, and that window names two host lines: a caret's prerelease comparison only covers its own patch tuple, so a single `^0.2.1-rc.5` does not admit `0.2.2-alpha.*` — measured with this workspace's semver, `satisfies('0.2.2-alpha.3','^0.2.1-rc.5')` is false and `{includePrerelease:true}` turns it true, and that flag is exactly what the host's own comparison passes. The cost is measured and belongs here: npm resolves each peer on its own, while the host family pins its own line inside every member (any member of the `0.2.1-rc` line asks cordis `~4.0.5`, the `0.2.2-alpha.2` host asks `~4.0.6-alpha.1`, `0.2.2-alpha.3` asks `~4.0.6-alpha.2`, and `0.2.2-rc.1` asks `~4.1.0`), so a consumer that pins the older host line can still stop at `ERESOLVE`, while the same tree resolves on the newest line. The union also admits later prereleases in the same `0.2.2` tuple, such as `0.2.2-rc.1`; that is range semantics, not a compatibility certification. The verified baseline for this release is `0.2.2-rc.1`; the dev pins and host parity check have moved to that line. pnpm — the installer this workspace supports, and the one behind the host's `dsh plugin add` — resolves both shapes and only prints a peer warning. The loading gate is unaffected either way, because the host compares `engines.dsh` with `includePrerelease: true`. `devDependencies` pin the exact line this repository compiles and tests against (`0.2.2-rc.1`) and must stay uniform: one `dsh-session` version per tree keeps the nominal types recognizable. `@deepseek-ai/cordis` stays exact in `devDependencies` (`4.1.0`) and its peer range `^4.0.5||^4.0.6-alpha.1` covers both host lines, because one package cannot mix lines the way the host family does: alpha.2 requires `~4.0.6-alpha.1`, alpha.3 requires `~4.0.6-alpha.2`, and the range also admits `4.1.0`. The cordis union carries no spaces around `||`; the install-matrix probe reads one specifier per line now, while the dsh-family window keeps spaces. `test/publish-manifest.test.ts` checks each of these separately.
+- **The remaining peers are optional.** Except for the bare `@deepseek-ai/dsh` peer, which only declares the host line, most carry type declarations only. Two subpath-scoped value peers are the exceptions: `react` is value-imported by `./lib/card-ui`, and `@deepseek-ai/dsh-typert-protocol` by `./lib/remote-marker`; both stay optional, so only a consumer of that subpath needs the package present. `devDependencies` holds the exact development line, including `@deepseek-ai/dsh-llm` and `@deepseek-ai/dsh-util-values`, whose types the local PTC declarations name, and `@deepseek-ai/dsh-tool-executor-ptc`, whose types only the parity check reads. Profiles never install peers, so no duplicate appears.
+- **Version requirements separate the install gate from the build baseline.** Every `@deepseek-ai/dsh-*` peer carries the same window as `engines.dsh` — `^0.2.2-rc.1`, a single host line. A caret's prerelease comparison only covers its own patch tuple, so `^0.2.2-rc.1` admits `0.2.2-rc.1`, later `0.2.2` prereleases and `0.2.2`/`0.2.x`, but not the older `0.2.1` line or `0.2.2-alpha.*`; the host's own comparison passes `{includePrerelease:true}`, which is what lets same-tuple prereleases participate. The cost is measured and belongs here: npm resolves each peer on its own, while the host family pins its own line inside every member (`0.2.2-rc.1` asks cordis `~4.1.0` and schemastery `~3.19.0`), so a consumer that pins an older host line can still stop at `ERESOLVE`, while the same tree resolves on the supported line. pnpm — the installer this workspace supports, and the one behind the host's `dsh plugin add` — resolves both shapes and only prints a peer warning. The loading gate is unaffected either way, because the host compares `engines.dsh` with `includePrerelease: true`. `devDependencies` pin the exact line this repository compiles and tests against (`0.2.2-rc.2`) and must stay uniform: one `dsh-session` version per tree keeps the nominal types recognizable. `@deepseek-ai/cordis` stays exact in `devDependencies` (`4.1.0`); its peer range `^4.0.5||^4.0.6-alpha.1` is retained unchanged and admits `4.1.0`. The cordis union carries no spaces around `||`; the install-matrix probe reads one specifier per line now. `test/publish-manifest.test.ts` checks each of these separately.
 - Known upstream limitation: `@deepseek-ai/dsh-llm`'s declarations import `@deepseek-ai/dsh-attachment`, which that package does not declare. It is reached through `dsh-session`, so a consumer running with `skipLibCheck: false` sees `TS2307` from that package, not from this one. The published `./lib/tool-events` declaration also names `@deepseek-ai/dsh-util-values`, which is reached through `dsh-session` / `dsh-tools`; a consumer running with `skipLibCheck: false` must have that package resolvable as well.
 
 ### Shared version floor
@@ -107,12 +112,12 @@ A consumer profile can lock this package with a pnpm `overrides` entry. Lock it
 - `publishConfig` carries `access` and `registry` and nothing else. Entry fields there are a trap: pnpm merges them onto the top level when publishing and npm does not, so one publisher would ship a package whose entry points name files that are not in the tarball.
 - `build` deletes `dist/` first, then emits the runtime artifacts, the config artifacts, the type declarations and the generated barrel declaration. Both builders minify; `test/dist-size.test.ts` keeps the runtime and config artifacts inside their budgets.
 - `prepare` runs `build`. It does not run when a consumer installs from the registry; it exists so packing, publishing and workspace links always ship a fresh `dist/`.
-- Adding a module means touching five places: the barrel in `lib/index.ts`, `exports`, the `facets` array in `build-host.mjs`, `include` in `tsconfig.build.json`, and a `test/<module>.test.ts`. The consistency checks in Development fail if one is missed.
+- Adding a runtime module means touching the barrel in `lib/index.ts`, `exports`, the `facets` array in `build-host.mjs`, `include` in `tsconfig.build.json`, and a `test/<module>.test.ts`. A subpath-only runtime module (like `remote-marker` or `card-ui`) is registered in `entries` and marked barrel-exempt instead; a build-time module (like `decorator-lowering`) goes into `buildFacets`. The consistency checks in Development fail if one is missed.
 
 ## <img src="https://api.iconify.design/lucide/circle-check.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> Verify it is live
 
 1. **A subpath resolves.** From the consuming package, `node -e 'import("@jayyuen66/dsh-plugin-shared/lib/record").then((m) => console.log(typeof m.isRecord))'` prints `function`. `ERR_MODULE_NOT_FOUND` means the dependency is not installed; `does not provide an export named ...` means the installed copy is older than the subpath you import.
-2. **The barrel resolves.** The same check against the bare package name returns the runtime modules. `canonicalize-region-paths` is the one module deliberately absent from the barrel; import it by subpath when a build script needs it.
+2. **The barrel resolves.** The same check against the bare package name returns the runtime modules. `canonicalize-region-paths` (build-time), `remote-marker` (value-imports typert), and `card-ui` (client-only) are deliberately absent from the barrel; import them by subpath.
 3. **A consumer host boots.** Start the profile that declares the plugin. A boot log containing `N entries did not activate` and `does not provide an export named ...` means the profile's `overrides` version is below the version that contains the subpath the consumer imports — raise the version, do not patch the plugin.
 4. **Local source edits reach the consumer.** Consumers load `dist/`, not `lib/`. Run `pnpm run build` after editing; `test/build-host.test.ts` compares the runtime artifacts on disk against an in-memory build and fails when they are stale. "The code changed but nothing happened" is almost always a stale artifact, not a caching bug.
 
@@ -130,11 +135,11 @@ The subpath column is the in-package specifier; value imports prefix it with the
 
 | Subpath | Provides |
 | --- | --- |
-| `.` | Barrel over the runtime modules below, served from `dist/plugin.js`: the same names plus `name` and a no-op `apply`, so the host loader can also take this package as a row. `canonicalize-region-paths` deliberately stays out, so a runtime consumer does not add an import for it; the client-only `card-ui` stays out for the same reason plus one more: the root barrel must not bring `react` into every consumer. |
+| `.` | Barrel over the runtime modules below, served from `dist/plugin.js`: the same names plus `name` and a no-op `apply`, so the host loader can also take this package as a row. `canonicalize-region-paths` (build-time), `remote-marker` (value-imports typert), and `card-ui` (client-only) deliberately stay out; the root barrel must not pull an unused package into every consumer. |
 | `./lib/tool-events` | `scanToolEvents` returns the `calls` / `results` tables, PTC sub-calls included; `toolEventRowsOf` handles a single event and already carries normalized `arguments` and `badArguments`. `editPathOf` returns a `kind`-discriminated `EditTarget` with only `write` / `read-view`; the path is `undefined` when it cannot be read. `applyPatchTargetsOf` parses the ordered operations of an `apply_patch` input with the official `dsh-fs-patch`; `editPathsOf` expands every write target, including both sides of a move. Record fields are `readonly`. Re-exports the official `SessionEvent`; `PtcDispatchStartEventData` / `PtcDispatchEventData` are declared in this package and augment `SessionEventMap` locally, because the host moved that augmentation between packages inside the supported window. |
 | `./lib/card-apply` | `claimApply` + `CardApplyCtx`: an apply idempotency guard built on an **own** flag on `globalThis` (a symbol, or `true` written by an outside holder) with `ctx.effect` cleanup. The flag is process-wide, so a second context on the same page is rejected by design. |
 | `./lib/card-diff` | `diffTouched`: which touched fields really differ from the snapshot, compared by form value. `undefined`, `null` and an absent key are one value; arrays and objects compare element by element; cycles terminate. |
-| `./lib/card-ui` | Client-only settings-card kit: `CardForm`, `Section`, `FieldGrid`, `StatusBar`, `Field`, `FieldLabel`, `InfoTip`, `ToggleField`, `NumberField`, `TextField`, `ListField`, `SelectField`, `SaveBar`, `splitHint` and the `CARD_UI_CSS` string. Built with `createElement` only; `react` is an optional peer and the subpath never enters the root barrel. React 18 runtime APIs only (`useId`, `useState`, `useEffect`, refs). |
+| `./lib/card-ui` | Client-only settings-card kit: `CardForm`, `Section`, `FieldGrid`, `StatusBar`, `Field`, `FieldLabel`, `InfoTip`, `ToggleField`, `NumberField`, `TextField`, `ListField`, `SelectField`, `SaveBar`, `splitHint` and the `CARD_UI_CSS` string. Built with `createElement` only; `react` is an optional peer and the subpath never enters the root barrel. The declared peer floor is `^19.3.0`; the kit uses only APIs that already existed in React 18 (`useId`, `useState`, `useEffect`, refs). |
 | `./client` | Browser client row: the `__ModuleLoader__` bundle the host module graph serves once. Consumers externalize this specifier and enable the row from their own patch with an id-less entry. |
 | `./client-node` | Node/ESM face of the same client surface, used by tests and type-aware Node consumers. |
 | `./lib/project-key` | `deriveProjectKey` + `ProjectKeyOptions`: cwd → `last-segment-<first 8 hex of sha256(norm)>`, with `default` for a non-string, an empty string or a normalized root. `realpathSync` resolves symlinks; a failure falls back to the resolved path. Windows `\` and `/` produce the same key. |
@@ -145,9 +150,11 @@ The subpath column is the in-package specifier; value imports prefix it with the
 | `./lib/errors` | `errorText` follows the official `@deepseek-ai/dsh-llm` `errorChain` semantics (cause chain, `AggregateError` members, empty message → `name`, cross-realm `message`, malicious getters render as a placeholder) in a zero-dependency local implementation. `isSettingsConflict` recognizes the host's settings-conflict pattern from `code` / `name`, so a cross-realm error is still recognized. |
 | `./lib/jsonl` | `shrinkJsonlTail`: pure decision logic for JSONL tail shrinking. The trigger policy and error handling stay with the caller; the byte budget is the caller's responsibility to keep finite. |
 | `./lib/job-outcome` | `jobOutcomeOf` + `SettledProcess` + `JobOutcome` map a finished subprocess onto the official job registry's outcome; `killProc` + `KillableProcess` release a child handle and ignore a `kill()` that throws or rejects (for example, on an already-reaped process). |
+| `./lib/remote-marker` | `markRemote(prototype, methodName)`: the programmatic equivalent of the official `@Remote` method decorator. It applies the same decorator function to a hand-built TC39 context, so a source file can avoid decorator syntax and needs no lowering pipeline. It value-imports `@deepseek-ai/dsh-typert-protocol` (an optional peer) and stays out of the root barrel. |
+| `./lib/decorator-lowering` | Build/test helper for standard decorators: `needsDecoratorLowering`, `lowerStandardDecorators`, `rolldownDecorators`, `viteDecorators`. It runs the caller-injected `tsc` entry on one file with `--noResolve`, preserves module specifiers, returns code plus a source map, and (on the Vite side) prunes injected plumbing from coverage mappings. Build-time only, never in the runtime barrel. |
 | `./lib/canonicalize-region-paths` | Build-time string helper that rewrites rolldown's `//#region <path>` markers into a `process.cwd()`-independent form. Exported as a subpath so build scripts can import it without putting it in the runtime barrel. |
 
-`card-ui` is the one runtime module that is deliberately subpath-only: adding it to the barrel would make every host-side importer resolve `react`.
+`card-ui` (value-imports `react`) and `remote-marker` (value-imports `@deepseek-ai/dsh-typert-protocol`) are the runtime modules that are deliberately subpath-only: putting them in the barrel would make every host-side importer resolve a package it does not use.
 
 The client row is enabled by the consuming plugin, not by installing this package alone. The consumer writes `- name: "@jayyuen66/dsh-plugin-shared"` without an `id`; the host still loads it, while the plugin page does not expose it as a separately disableable component. An `id` would add that switch, and switching it off would break every settings card that requires the row's components.
 
@@ -211,7 +218,7 @@ The package is imported into a host process; the table describes run time.
 | Should I `dsh plugin add` it? | No. It declares `dsh.client` for the row consumers enable, but carries no `dsh.bundle.patch`, so adding it as a plugin installs no profile layer and enables nothing by itself. Declare it as a dependency of the plugin package, and insert the id-less row in your own `cordis.patch.yml`. |
 | A consumer boots with `does not provide an export named ...` and `N entries did not activate`. | The profile is serving an older copy of this package than the consumer imports. Raise the profile's `overrides` entry to a version that contains the subpath the consumer imports; check this package's `exports` and CHANGELOG. No per-repository CI run can see this state. |
 | I changed `lib/*.ts` and the consumer still runs the old behavior. | Consumers load `dist/`. Run `pnpm run build`; `test/build-host.test.ts` fails if the runtime artifact is stale. A workspace link does not bypass the artifact. |
-| Why is `@deepseek-ai/dsh-output-retention` a required peer while the rest are optional? | It is the only host package imported for value (`truncateEnd`). The rest are type-only, except the bare `@deepseek-ai/dsh` peer, which only declares the host line. |
+| Why is `@deepseek-ai/dsh-output-retention` a required peer while the rest are optional? | It is the only **required** host package imported for value (`truncateEnd`). `@deepseek-ai/dsh-typert-protocol` is also value-imported, but only by `./lib/remote-marker`, so it stays optional; the remaining dsh peers are type-only. The bare `@deepseek-ai/dsh` peer only declares the host line, and `react` is a value peer for `./lib/card-ui`. |
 | Why isn't `oxlint` a `peerDependency`? | npm 7+ would try to satisfy it, and `oxlint`'s optional `vite-plus` peer locks `vitest` outside the range this baseline needs, producing `ERESOLVE` for a plain install. The requirement is documented instead. |
 | Want a helper added here? | First confirm the body repeats verbatim in two or more packages. Domain judgement stays in the plugins. |
 
@@ -232,7 +239,7 @@ pnpm run build   # runtime artifacts, config artifacts, declarations, client row
   - **Log records**: `test/setup-logs.ts` takes over `console.*`; every `[shared/*]` line must match `test/log-templates.ts` or the run fails. `test/log-templates.test.ts` checks both directions, so adding or deleting a log without updating the record list fails.
   - **Published shape**: `test/publish-manifest.test.ts` requires every export target to be inside `files`, entry points to be artifacts rather than source, `publishConfig` to carry no entry fields, every peer to be stated in `peerDependenciesMeta`, every `dsh-*` development pin to be exact and uniform, every dsh peer range to equal `engines.dsh`, and the source, docs and artifacts to carry no dates, absolute paths, home-directory references or collaboration-only wording.
 - Coverage thresholds are **100%** across lines, statements, functions and branches, so a new branch needs a case that reaches it. `test/vitest-base.test.ts` refuses an empty `coverageInclude` because that would make the four thresholds pass over nothing.
-- CI runs the checks on Linux, Windows and macOS across a Node 22/24 matrix, with a weekly scheduled run to catch upstream changes. The install matrix packs with both npm and pnpm, installs into a clean directory without peer-resolution flags, imports every subpath and type-checks a small consumer import under both `skipLibCheck` settings.
+- CI runs the checks on Linux, Windows and macOS on Node 24.9, with a weekly scheduled run to catch upstream changes. The install matrix packs with both npm and pnpm, installs into a clean directory without peer-resolution flags, imports every subpath and type-checks a small consumer import under both `skipLibCheck` settings.
 
 ## <img src="https://api.iconify.design/lucide/scale.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> License
 

package/README.zh-CN.md

@@ -12,7 +12,7 @@
   <a href="https://github.com/JayYuen666/dsh-plugin-shared/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/JayYuen666/dsh-plugin-shared/ci.yml?branch=main&style=flat-square&label=ci" alt="ci" /></a>
   <img src="https://img.shields.io/badge/license-MIT-4c1?style=flat-square" alt="MIT" />
   <img src="https://img.shields.io/badge/node-%3E%3D24.9-4c1?style=flat-square&logo=nodedotjs&logoColor=white" alt="node" />
-  <img src="https://img.shields.io/badge/dsh-%5E0.2.1--rc.5-658EFF?style=flat-square" alt="dsh" />
+  <img src="https://img.shields.io/badge/dsh-%5E0.2.2--rc.1-658EFF?style=flat-square" alt="dsh" />
   <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/powered_by_dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white" alt="powered by dsh" /></a>
 </p>
 
@@ -31,18 +31,23 @@
 
 ## <img src="https://api.iconify.design/lucide/file-text.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> 目录
 
-- [它做什么](#它做什么)
-- [安装](#安装)
-- [确认它在正常工作](#确认它在正常工作)
-- [它不提供什么](#它不提供什么)
-- [模块清单](#模块清单)
-- [config 导出](#config-导出)
-- [已知边界](#已知边界)
-- [数据与隐私](#数据与隐私)
-- [版本与兼容](#版本与兼容)
-- [常见问题](#常见问题)
-- [开发](#开发)
-- [许可](#许可)
+- [ 目录](#-目录)
+- [ 它做什么](#-它做什么)
+  - [收录边界](#收录边界)
+- [ 安装](#-安装)
+  - [依赖要求](#依赖要求)
+  - [shared 的版本下限](#shared-的版本下限)
+  - [随包发什么](#随包发什么)
+- [ 确认它在正常工作](#-确认它在正常工作)
+- [ 它不提供什么](#-它不提供什么)
+- [ 模块清单](#-模块清单)
+- [ config 导出](#-config-导出)
+- [ 已知边界](#-已知边界)
+- [ 数据与隐私](#-数据与隐私)
+- [ 版本与兼容](#-版本与兼容)
+- [ 常见问题](#-常见问题)
+- [ 开发](#-开发)
+- [ 许可](#-许可)
 
 ## <img src="https://api.iconify.design/lucide/shield.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> 它做什么
 
@@ -74,12 +79,12 @@ pnpm add @jayyuen66/dsh-plugin-shared
 import { isRecord, fieldOf } from "@jayyuen66/dsh-plugin-shared/lib/record";
 ```
 
-终端用户不需要单独安装或启用它：任一消费包安装时都会自动包含它。它缺失时的失败是 `ERR_MODULE_NOT_FOUND`（说明符指向 `@jayyuen66/dsh-plugin-shared/...`），不会静默变成其他行为。本包没有 default 导出；请从 barrel 或子路径使用具名导入。
+终端用户不需要单独安装或启用它：任一消费包安装时都会自动包含它。它缺失时的失败是 `ERR_MODULE_NOT_FOUND`（那条说明符指向 `@jayyuen66/dsh-plugin-shared/...`），不会静默变成其他行为。本包没有 default 导出；请从 barrel 或子路径使用具名导入。
 
 | 要求 | 值 |
 | --- | --- |
 | Node.js | `>=24.9.0`——插件家族共用的发布侧下限，声明同一个 `engines.node` 的包不会因为这个库而被拒 |
-| dsh | `^0.2.1-rc.5 || ^0.2.2-alpha.3`，声明为 **optional** peer（import 本包不需要宿主存在） |
+| dsh | `^0.2.2-rc.1`，声明为 **optional** peer（import 本包不需要宿主存在） |
 | 模块形态 | 仅 ESM。`require()` 只在支持 `require(esm)` 的 Node 上可用 |
 | Tree shaking | `"sideEffects": false` |
 
@@ -92,13 +97,13 @@ import { isRecord, fieldOf } from "@jayyuen66/dsh-plugin-shared/lib/record";
 - **`@deepseek-ai/dsh-fs-patch` 是唯一允许的普通依赖。** 它是无状态纯解析器，不承载服务实例或模块级身份，多一份不会分裂 `Symbol`；随包安装是为了让宿主窗口内没有该包的版本也能解析 `apply_patch` 语法。其余宿主包仍然必须留在 peer/dev。
 - **宿主包写进 `dependencies` 会让消费方的宿主无法工作。** profile 用 `nodeLinker: hoisted` 与 `autoInstallPeers: false` 安装，于是列在 `dependencies` 里的宿主包会被安装成真实目录，与宿主进程已加载的那份并存。`@deepseek-ai/dsh-tools` 的工具运行期调度键是普通 `Symbol`（不是 `Symbol.for`），符号身份按模块实例计算：宿主从副本上读那个键得到 `undefined`，于是每一次原生工具调用都抛错。构建、类型检查与测试在此之前全部通过；这条不变式只能写在 manifest 上。
 - **`@deepseek-ai/dsh-output-retention` 是唯一必需 peer。** 它是值导入（`truncateEnd`），运行期由宿主提供；在 `peerDependenciesMeta` 里明写成 `"optional": false`，不靠"没写就等于必需"，因为没写进那张表对 npm 7+ 就是硬要求。
-- **其余 peer 都是 optional。** 除裸 `@deepseek-ai/dsh`（只声明宿主版本线）外，它们只承载类型声明。`devDependencies` 保存精确的开发线，其中包括本包 PTC 声明所引用的 `@deepseek-ai/dsh-llm` 与 `@deepseek-ai/dsh-util-values`，以及只有对照断言会读其类型的 `@deepseek-ai/dsh-tool-executor-ptc`。profile 不装 peer，所以不会产生副本。
-- **版本要求把装载门与构建基线分开。** 每条 `@deepseek-ai/dsh-*` peer 与 `engines.dsh` 写同一条窗口，而这条窗口点明两条宿主线：caret 的预发布比较只吃自己那条 patch 元组，单写 `^0.2.1-rc.5` 收不进 `0.2.2-alpha.*`——用本工作区的 semver 实测 `satisfies('0.2.2-alpha.3','^0.2.1-rc.5')` 为 false，带 `{includePrerelease:true}` 才为 true，而宿主自己那道比较正是带这一档。代价是量出来写在这里的：npm 逐条 peer 独立解析，宿主家族每一枚包内部又把自己的那条线精确钉住（`0.2.1-rc` 线上任一成员要求 cordis `~4.0.5`，`0.2.2-alpha.2` 宿主要求 `~4.0.6-alpha.1`，`0.2.2-alpha.3` 要求 `~4.0.6-alpha.2`，`0.2.2-rc.1` 要求 `~4.1.0`），所以消费者把宿主钉在旧那条线时仍可能止步 `ERESOLVE`，同一条树落在最新线上则可解。并集窗口也收得进同一 `0.2.2` 元组里更晚的预发布，例如 `0.2.2-rc.1`；那只是范围语义，不是兼容性取证。本版实际取证的基线是 `0.2.2-rc.1`；dev 钉版与宿主对照断言已同步到这一线。pnpm——本工作区支持、也是宿主 `dsh plugin add` 在用的安装器——两种形状都解得出，只打一条 peer 告警。装载门两边都不受影响。`devDependencies` 精确锁定本仓编译与测试用的那一线（`0.2.2-rc.1`），且必须统一：一棵树里只有一份 `dsh-session`，nominal 类型才互相认得。`@deepseek-ai/cordis` 在 `devDependencies` 里精确锁定 `4.1.0`，peer 范围 `^4.0.5||^4.0.6-alpha.1` 同时覆盖 rc 线与 alpha 线——单独一枚包不存在宿主家族那种混线问题：alpha.2 要求 `~4.0.6-alpha.1`，alpha.3 要求 `~4.0.6-alpha.2`，该范围也收得下 `4.1.0`。cordis 这条并集在 `||` 两侧不带空格；类型面 peer 安装现已按行逐枚读取，dsh 家族窗口保留空格。`test/publish-manifest.test.ts` 分别检查这三件事。
+- **其余 peer 都是 optional。** 除裸 `@deepseek-ai/dsh`（只声明宿主版本线）外，它们大多只承载类型声明；两个按子路径收窄的值导入 peer 是例外：`react` 被 `./lib/card-ui` 按值导入，`@deepseek-ai/dsh-typert-protocol` 被 `./lib/remote-marker` 按值导入。两者仍是 optional，只有取用对应子路径的消费方才需要它们在场。`devDependencies` 保存精确的开发线，其中包括本包 PTC 声明所引用的 `@deepseek-ai/dsh-llm` 与 `@deepseek-ai/dsh-util-values`，以及只有对照断言会读其类型的 `@deepseek-ai/dsh-tool-executor-ptc`。profile 不装 peer，所以不会产生副本。
+- **版本要求把装载门与构建基线分开。** 每条 `@deepseek-ai/dsh-*` peer 与 `engines.dsh` 写同一条窗口——`^0.2.2-rc.1`，单条宿主线。caret 的预发布比较只吃自己那条 patch 元组，所以 `^0.2.2-rc.1` 收得进 `0.2.2-rc.1`、同元组更晚的预发布以及 `0.2.2`/`0.2.x`，收不进更旧的 `0.2.1` 线或 `0.2.2-alpha.*`；宿主自己那道比较带 `{includePrerelease:true}`，正是这一档让同元组预发布参与。代价是量出来写在这里的：npm 逐条 peer 独立解析，宿主家族每一枚包内部又把自己的那条线精确钉住（`0.2.2-rc.1` 要求 cordis `~4.1.0`、schemastery `~3.19.0`），所以消费者把宿主钉在旧线时仍可能止步 `ERESOLVE`，同一条树落在受支持的线上则可解。pnpm——本工作区支持、也是宿主 `dsh plugin add` 在用的安装器——两种形状都解得出，只打一条 peer 告警。装载门两边都不受影响，因为宿主比较 `engines.dsh` 时带 `includePrerelease: true`。`devDependencies` 精确锁定本仓编译与测试用的那一线（`0.2.2-rc.2`），且必须统一：一棵树里只有一份 `dsh-session`，nominal 类型才互相认得。`@deepseek-ai/cordis` 在 `devDependencies` 里精确锁定 `4.1.0`；peer 范围 `^4.0.5||^4.0.6-alpha.1` 保持不变，收得下 `4.1.0`。cordis 这条并集在 `||` 两侧不带空格；install-matrix 探针现已按行逐枚读取。`test/publish-manifest.test.ts` 分别检查这几件事。
 - 已知上游限制：`@deepseek-ai/dsh-llm` 的声明文件引用了它自己没声明的 `@deepseek-ai/dsh-attachment`。它经 `dsh-session` 传递进来，所以开 `skipLibCheck: false` 的消费方会看到来自那个包的 `TS2307`，不是来自本包。发布出去的 `./lib/tool-events` 声明还引用了 `@deepseek-ai/dsh-util-values`，它经 `dsh-session` / `dsh-tools` 传递进来；开 `skipLibCheck: false` 的消费方同样必须能解析到这个包。
 
 ### shared 的版本下限
 
-消费者的 profile 可以用 pnpm `overrides` 把本包固定在某个版本。固定得低于某个 `./lib/...` 子路径首次出现的版本，宿主启动时就会报 `N entries did not activate` 与 `does not provide an export named ...`：包装得上、永远不加载，而任何单仓 CI 都看不见。要固定版本请先对照本包的 `exports` 与 CHANGELOG。
+消费者的 profile 可以用 pnpm `overrides` 把本包钉在某个版本。钉得低于某个 `./lib/...` 子路径首次出现的版本，宿主启动时就会报 `N entries did not activate` 与 `does not provide an export named ...`：包装得上、永远不加载，而任何单仓 CI 都看不见。要钉版本请先对照本包的 `exports` 与 CHANGELOG。
 
 ### 随包发什么
 
@@ -107,12 +112,12 @@ import { isRecord, fieldOf } from "@jayyuen66/dsh-plugin-shared/lib/record";
 - `publishConfig` 只带 `access` 与 `registry`。把入口字段放在那里容易出错：pnpm 发布时会把它合并到顶层，npm 不会——换一个发布器就会发出一个入口指向 tarball 里不存在文件的包。
 - `build` 先删除 `dist/`，再产出运行期产物、配置产物、类型声明与生成的 barrel 声明。两个构建脚本都压缩；`test/dist-size.test.ts` 把运行期产物与配置产物各自限制在预算内。
 - `prepare` 指向 `build`。消费方从 registry 安装时它不执行；它存在是为了让打包、发布与 workspace link 拿到的都是新鲜 `dist/`。
-- 新增模块要同时改五处：`lib/index.ts` 的 barrel、`exports`、`build-host.mjs` 的 `facets` 数组、`tsconfig.build.json` 的 `include`，外加一份 `test/<模块>.test.ts`。漏一处会被「开发」一节的一致性检查判定失败。
+- 新增运行期模块要同时改：`lib/index.ts` 的 barrel、`exports`、`build-host.mjs` 的 `facets` 数组、`tsconfig.build.json` 的 `include`，外加一份 `test/<模块>.test.ts`。只走子路径的运行期模块（如 `remote-marker`、`card-ui`）改登记进 `entries` 并在 barrel 检查里豁免；构建期模块（如 `decorator-lowering`）进 `buildFacets`。漏一处会被「开发」一节的一致性检查判定失败。
 
 ## <img src="https://api.iconify.design/lucide/circle-check.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> 确认它在正常工作
 
 1. **子路径能解析。** 在消费包里运行 `node -e 'import("@jayyuen66/dsh-plugin-shared/lib/record").then((m) => console.log(typeof m.isRecord))'`，输出 `function`。`ERR_MODULE_NOT_FOUND` 表示依赖没装上；`does not provide an export named ...` 表示装到的那份比你 import 的子路径旧。
-2. **barrel 能解析。** 换成裸包名做同一件事，应能取到运行期模块。`canonicalize-region-paths` 是唯一刻意不在 barrel 里的模块；构建脚本需要时按子路径取。
+2. **barrel 能解析。** 换成裸包名做同一件事，应能取到运行期模块。`canonicalize-region-paths`（构建期）、`remote-marker`（值导入 typert）与 `card-ui`（客户端专用）刻意不在 barrel 里；需要时按子路径取。
 3. **消费方宿主能启动。** 启动声明该插件的 profile。若启动日志出现 `N entries did not activate` 与 `does not provide an export named ...`，说明 profile 的 `overrides` 固定得比包含该子路径的版本低——调高固定版本，不要改插件。
 4. **本地源码改动能反映到消费方。** 消费方载入的是 `dist/`，不是 `lib/`。改完先运行 `pnpm run build`；`test/build-host.test.ts` 会把磁盘上的运行期产物与内存构建逐字节比对，产物过期即报错。"代码改了却没生效"多半是产物过期，不是缓存问题。
 
@@ -130,13 +135,13 @@ import { isRecord, fieldOf } from "@jayyuen66/dsh-plugin-shared/lib/record";
 
 | 子路径 | 提供什么 |
 | --- | --- |
-| `.` | 下面列出的运行期模块的 barrel，由 `dist/plugin.js` 提供：同样的导出名，再加 `name` 与一条空操作的 `apply`，宿主 Loader 因此也能把本包当作一行载入。`canonicalize-region-paths` 刻意不进，运行期消费方不必为它增加一次导入；客户端专用的 `card-ui` 同样不进，理由还多一条：根 barrel 不得把 `react` 带进每个消费方 |
+| `.` | 下面列出的运行期模块的 barrel，由 `dist/plugin.js` 提供：同样的导出名，再加 `name` 与一条空操作的 `apply`，宿主 Loader 因此也能把本包当作一行载入。`canonicalize-region-paths`（构建期）、`remote-marker`（值导入 typert）与 `card-ui`（客户端专用）刻意不进；根 barrel 不得把用不到的包带进每个消费方 |
 | `./lib/tool-events` | `scanToolEvents` 返回 `calls` / `results` 两张表，PTC 子调用一并合并；`toolEventRowsOf` 处理单个事件，交回的记录已带归一后的 `arguments` 与 `badArguments`。`editPathOf` 返回按 `kind` 判别的 `EditTarget`，只有 `write` / `read-view` 两个分支；路径取不到时为 `undefined`。`applyPatchTargetsOf` 用官方 `dsh-fs-patch` 解析 `apply_patch` 的有序操作；`editPathsOf` 展开全部写目标（move 的源与目的都算）。记录字段一律 `readonly`。同时再导出官方 `SessionEvent`；`PtcDispatchStartEventData` / `PtcDispatchEventData` 在本包内声明并自行增强 `SessionEventMap`，因为宿主在支持窗口内换过承载这份增强的包 |
 | `./lib/card-apply` | `claimApply` + `CardApplyCtx`：保证 apply 幂等的保护逻辑，建立在 `globalThis` 上的**自有**标记（symbol，或外部写入的 `true`）加 `ctx.effect` 清理。标记是进程级的，所以同一页面的第二个 ctx 会被拒绝——这是有意的设计 |
 | `./lib/card-diff` | `diffTouched`：touched 层里哪些字段真的与快照不同，按表单值比较。`undefined`、`null` 与键缺失是同一种值；数组与对象逐元素比较；循环引用也能正常结束 |
-| `./lib/card-ui` | 客户端专用设置卡组件：`CardForm`、`Section`、`FieldGrid`、`StatusBar`、`Field`、`FieldLabel`、`InfoTip`、`ToggleField`、`NumberField`、`TextField`、`ListField`、`SelectField`、`SaveBar`、`splitHint` 与样式字符串 `CARD_UI_CSS`。只用 `createElement`；`react` 是 optional peer，该子路径永不进根 barrel。只用 React 18 运行时 API（`useId`、`useState`、`useEffect`、refs） |
+| `./lib/card-ui` | 客户端专用设置卡组件：`CardForm`、`Section`、`FieldGrid`、`StatusBar`、`Field`、`FieldLabel`、`InfoTip`、`ToggleField`、`NumberField`、`TextField`、`ListField`、`SelectField`、`SaveBar`、`splitHint` 与样式字符串 `CARD_UI_CSS`。只用 `createElement`；`react` 是 optional peer，该子路径永不进根 barrel。声明的 peer 下限是 `^19.3.0`；组件只用 React 18 就已存在的 API（`useId`、`useState`、`useEffect`、refs） |
 | `./client` | 浏览器客户端行：宿主模块图只提供一份的 `__ModuleLoader__` bundle。消费者外置这个说明符，并在自己的 patch 里以无 id 条目启用这一行 |
-| `./client-node` | 同一客户端面的 Node/ESM 形态，供测试与类型感知的 Node 消费方使用 |
+| `./client-node` | 同一份客户端接口的 Node/ESM 形态，供测试与类型感知的 Node 消费方使用 |
 | `./lib/project-key` | `deriveProjectKey` + `ProjectKeyOptions`：cwd → `尾目录名-<sha256(norm) 前 8 位 hex>`；非字符串、空串或归一后的根目录归入 `default`。`realpathSync` 会解析软链接，失败则退回解析后的路径。Windows 的 `\` 与 `/` 产生同一个键 |
 | `./lib/locale` | `Locale`（官方 `BuiltInLocaleId` 的别名）、`DEFAULT_LOCALE`、`resolveLocale`、`resolveLocalePreference`、`messagesFor`、`MessagesCatalog`，加 `LOCALE_SETTINGS_NAMESPACE` 与 `LOCALE_PREFERENCE_FIELD`。只负责宿主侧字典；客户端用官方 locale 包 |
 | `./lib/lesson-bus` | `settleLessonCall`：同步抛错与异步 rejection 归到同一个 `onFailure` 出口。函数型 thenable 也算可等待；`onFailure` 自己抛错或拒绝时被统一处理，不会分成"抛给调用方"或"未处理拒绝"两种结果 |
@@ -145,9 +150,11 @@ import { isRecord, fieldOf } from "@jayyuen66/dsh-plugin-shared/lib/record";
 | `./lib/errors` | `errorText` 对齐官方 `@deepseek-ai/dsh-llm` 的 `errorChain` 语义（cause 链、`AggregateError` 成员、空 message 回退 `name`、跨 realm 取 `message`、恶意 getter 改用占位文本），本地零依赖实现。`isSettingsConflict` 由 `code` / `name` 识别宿主的设置冲突特征，跨 realm 抛来的错误也能识别 |
 | `./lib/jsonl` | `shrinkJsonlTail`：JSONL 尾部裁剪的纯逻辑模块。触发策略与错误处理留给调用方；字节预算是否有限由调用方保证 |
 | `./lib/job-outcome` | `jobOutcomeOf` + `SettledProcess` + `JobOutcome` 把已结束的子进程映射成官方作业注册表的结局；`killProc` + `KillableProcess` 释放子进程句柄，对抛错或拒绝的 `kill()` 一律忽略（例如进程已被回收） |
+| `./lib/remote-marker` | `markRemote(prototype, methodName)`：官方 `@Remote` 方法装饰器的程序化等价物。它把同一个装饰器函数作用在手写的 TC39 context 上，源码因此不必写装饰器语法，也不需要降级流水线。按值导入 `@deepseek-ai/dsh-typert-protocol`（optional peer），且不进根 barrel |
+| `./lib/decorator-lowering` | 标准装饰器的构建/测试辅助：`needsDecoratorLowering`、`lowerStandardDecorators`、`rolldownDecorators`、`viteDecorators`。它用调用方注入的 `tsc` 入口单文件编译（`--noResolve`，模块说明符逐字保留），交回代码与源映射；Vite 侧还会把注入样板从覆盖率映射里摘掉。仅构建期使用，绝不进运行期 barrel |
 | `./lib/canonicalize-region-paths` | 构建期字符串处理：把 rolldown 写下的 `//#region <路径>` 改写成与 `process.cwd()` 无关的形态。只提供子路径，是为了让构建脚本取得到它，同时不把运行期 barrel 增大 |
 
-`card-ui` 是唯一刻意只走子路径的运行期模块：把它加进 barrel 会让每个 host 侧 importer 都去解析 `react`。
+`card-ui`（值导入 `react`）与 `remote-marker`（值导入 `@deepseek-ai/dsh-typert-protocol`）是刻意只走子路径的运行期模块：放进 barrel 会让每个 host 侧 importer 都去解析一枚它用不到的包。
 
 客户端行由消费插件启用，不由单独安装本包启用。消费者写 `- name: "@jayyuen66/dsh-plugin-shared"` 且**不写 id**；宿主照常装载它，插件页不会把它暴露成可单独停用的组件。写 id 会多出那个开关，关闭后所有需要该行组件的设置卡都会失效。
 
@@ -211,7 +218,7 @@ import { isRecord, fieldOf } from "@jayyuen66/dsh-plugin-shared/lib/record";
 | 要不要 `dsh plugin add` 它？ | 不要。它声明的是 `dsh.client`（消费者要启用的那一行），但没有 `dsh.bundle.patch`，单独添加不会装出配置层，也启用不了任何东西。正确做法是声明成插件包的依赖，再在自己的 `cordis.patch.yml` 里插入那条不带 id 的行。 |
 | 消费方启动时报 `does not provide an export named ...` 与 `N entries did not activate`。 | profile 提供的那份本包比消费方 import 的版本旧。把 profile 的 `overrides` 版本调高到包含该子路径的版本；对照本包的 `exports` 与 CHANGELOG。任何单仓 CI 都看不见这个状态。 |
 | 改了 `lib/*.ts`，消费方还是旧行为。 | 消费方载入的是 `dist/`。先运行 `pnpm run build`；`test/build-host.test.ts` 会在运行期产物过期时判定失败。workspace link 不会绕过产物。 |
-| 为什么 `@deepseek-ai/dsh-output-retention` 是必需 peer，其余都是 optional？ | 它是唯一按值导入的宿主包（`truncateEnd`）。其余都是类型声明，唯一的例外是裸 `@deepseek-ai/dsh` peer——它只声明宿主版本线。 |
+| 为什么 `@deepseek-ai/dsh-output-retention` 是必需 peer，其余都是 optional？ | 它是唯一**必需**且按值导入的宿主包（`truncateEnd`）。`@deepseek-ai/dsh-typert-protocol` 也按值导入，但只被 `./lib/remote-marker` 取用，所以仍是 optional；其余 dsh peer 只承载类型。裸 `@deepseek-ai/dsh` peer 只声明宿主版本线，`react` 则是 `./lib/card-ui` 的值导入 peer。 |
 | 为什么 `oxlint` 不写成 `peerDependency`？ | npm 7+ 会去满足它，而 `oxlint` 的 optional `vite-plus` peer 把 `vitest` 锁定在基线所需范围之外，普通安装会得到 `ERESOLVE`。这条要求因此写在文档里。 |
 | 想把某个 helper 收录进来？ | 先确认那份函数体在两个以上包里逐字重复。带领域判断的部分留在插件里。 |
 
@@ -232,7 +239,7 @@ pnpm run build   # 运行期产物、配置产物、声明文件、客户端行
   - **日志记录**：`test/setup-logs.ts` 接管 `console.*`；每条 `[shared/*]` 日志都要匹配 `test/log-templates.ts` 里的模板片段，否则测试立即失败。`test/log-templates.test.ts` 双向校验，增删日志却不改记录清单都会失败。
   - **发布形态**：`test/publish-manifest.test.ts` 要求入口目标都在 `files` 覆盖内、入口指向产物而不是源码、`publishConfig` 不带入口字段、每条 peer 都在 `peerDependenciesMeta` 里明确标注、`dsh-*` 开发钉版精确且统一、dsh peer 范围与 `engines.dsh` 相同，并要求源码、文档与产物里没有日期、绝对路径、家目录指涉或只在协作当时成立的措辞。
 - 覆盖率四项阈值都是 **100%**（lines / statements / functions / branches），所以新增分支必须有能走到它的用例。`test/vitest-base.test.ts` 拒绝空 `coverageInclude`，因为那会让四项阈值在空统计范围上全部通过。
-- CI 在 Linux、Windows 与 macOS 上运行同一组检查，Node 版本矩阵覆盖 22 与 24，并有一周一次的定时运行来发现上游变化。安装矩阵会分别用 npm 与 pnpm 打包，在干净目录里不带 peer 解析选项安装，逐子路径 import，并在两种 `skipLibCheck` 设置下对一小段消费方导入代码做类型检查。
+- CI 在 Linux、Windows 与 macOS 上以 Node 24.9 运行同一组检查，并有一周一次的定时运行来发现上游变化。安装矩阵会分别用 npm 与 pnpm 打包，在干净目录里不带 peer 解析选项安装，逐子路径 import，并在两种 `skipLibCheck` 设置下对一小段消费方导入代码做类型检查。
 
 ## <img src="https://api.iconify.design/lucide/scale.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> 许可
 

package/dist/build/build-artifacts.js

@@ -1 +1,8 @@
-import{randomUUID as e}from"node:crypto";import{realpathSync as t}from"node:fs";import{mkdir as n,readFile as r,rename as i,rm as a,writeFile as o}from"node:fs/promises";import{setTimeout as s}from"node:timers/promises";import c from"node:path";function l(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function u(e){return l(e)?e:{}}async function d(e){let t=c.join(e,`package.json`);try{return JSON.parse(await r(t,`utf8`))}catch(e){throw Error(`读 ${t} 失败：${String(e)}`,{cause:e})}}function f(e){let t=e.indexOf(`/`);if(!e.startsWith(`@`))return t===-1?e:e.slice(0,t);let n=t===-1?-1:e.indexOf(`/`,t+1);return n===-1?e:e.slice(0,n)}function p(e){return e?.type===`chunk`&&e.isEntry===!0&&typeof e.code==`string`&&e.code.trim()!==``}function m(e,t){if(e.length!==1){let n=e.map(e=>`${e.type}:${e.fileName}`).join(`, `);throw Error(`rolldown 为 ${t} 产出了 ${e.length} 项输出（期望恰好一个 entry chunk）：${n}`)}let n=e.at(0);if(!p(n))throw Error(`rolldown 为 ${t} 产出的不是单个带正文的 entry chunk`);return n}const h=/* @__PURE__ */ new Set([`EPERM`,`EBUSY`,`EACCES`]),g=[50,100,200];async function _(e,t,n=0){try{await i(e,t)}catch(r){let i=typeof r==`object`&&r&&`code`in r?r.code:void 0;if(typeof i!=`string`||!h.has(i))throw r;let a=g.at(n);if(a===void 0)throw r;await s(a),await _(e,t,n+1)}}async function v(t,r){let i=c.join(c.dirname(t),`.tmp`);await n(i,{recursive:!0});let s=c.join(i,`${c.basename(t)}.${process.pid}.${e()}.tmp`);try{await o(s,r,`utf8`),await _(s,t)}catch(e){try{await a(s,{force:!0})}catch{}throw Error(`写产物失败：${t}（草稿 ${s}）：${String(e)}`,{cause:e})}}async function y(e){try{await e.close()}catch(e){console.error(`释放 rolldown bundle 失败（不影响上面那条构建错因）:`,e)}}function b(e){let n=process.argv.at(1);if(n===void 0||n.length===0||c.basename(n)!==c.basename(e))return!1;try{return t(n)===t(e)}catch(e){throw Error(`无法解析本脚本自身的路径（argv[1]=${n}）：构建未发生，不要当成成功。`,{cause:e})}}export{u as asRecord,y as closeQuietly,b as invokedDirectly,l as isRecord,f as packageNameOf,d as readManifest,m as singleEntryChunk,v as writeArtifact};
+import{randomUUID as e}from"node:crypto";import{realpathSync as t}from"node:fs";import{mkdir as n,readFile as r,rename as i,rm as a,writeFile as o}from"node:fs/promises";import{setTimeout as s}from"node:timers/promises";import c from"node:path";function l(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function u(e){return l(e)?e:{}}async function d(e){let t=c.join(e,`package.json`);try{return JSON.parse(await r(t,`utf8`))}catch(e){throw Error(`读 ${t} 失败：${String(e)}`,{cause:e})}}function f(e){let t=e.indexOf(`/`);if(!e.startsWith(`@`))return t===-1?e:e.slice(0,t);let n=t===-1?-1:e.indexOf(`/`,t+1);return n===-1?e:e.slice(0,n)}function p(e){return e?.type===`chunk`&&e.isEntry===!0&&typeof e.code==`string`&&e.code.trim()!==``}function m(e,t){if(e.length!==1){let n=e.map(e=>`${e.type}:${e.fileName}`).join(`, `);throw Error(`rolldown 为 ${t} 产出了 ${e.length} 项输出（期望恰好一个 entry chunk）：${n}`)}let n=e.at(0);if(!p(n))throw Error(`rolldown 为 ${t} 产出的不是单个带正文的 entry chunk`);return n}const h=/* @__PURE__ */ new Set([`EPERM`,`EBUSY`,`EACCES`]),g=[50,100,200];async function _(e,t,n=0){try{await i(e,t)}catch(r){let i=typeof r==`object`&&r&&`code`in r?r.code:void 0;if(typeof i!=`string`||!h.has(i))throw r;let a=g.at(n);if(a===void 0)throw r;await s(a),await _(e,t,n+1)}}async function v(t,r){let i=c.join(c.dirname(t),`.tmp`);await n(i,{recursive:!0});let s=c.join(i,`${c.basename(t)}.${process.pid}.${e()}.tmp`);try{await o(s,r,`utf8`),await _(s,t)}catch(e){try{await a(s,{force:!0})}catch{}throw Error(`写产物失败：${t}（草稿 ${s}）：${String(e)}`,{cause:e})}}function y(e,t,n){let r=e.charAt(t);n.push(r);let i=t+1;for(;i<e.length;){let t=e.charAt(i);if(t===`\\`)n.push(e.charAt(i+1)===`
+`?` 
+`:`  `),i+=2;else if(t===r)return n.push(t),i+1;else n.push(t===`
+`?`
+`:` `),i+=1}return i}function b(e){let t=[],n=0,r=(n,r)=>{for(let i=n;i<r;i+=1)t.push(e.charAt(i)===`
+`?`
+`:` `)};for(;n<e.length;){let i=e.charAt(n);if(i===`"`||i===`'`||i==="`")n=y(e,n,t);else if(e.startsWith(`//`,n)){let t=e.indexOf(`
+`,n),i=t===-1?e.length:t;r(n,i),n=i}else if(e.startsWith(`/*`,n)){let t=e.indexOf(`*/`,n+2),i=t===-1?e.length:t+2;r(n,i),n=i}else t.push(i),n+=1}return t.join(``)}async function x(e){try{await e.close()}catch(e){console.error(`释放 rolldown bundle 失败（不影响上面那条构建错因）:`,e)}}function S(e){let n=process.argv.at(1);if(n===void 0||n.length===0||c.basename(n)!==c.basename(e))return!1;try{return t(n)===t(e)}catch(e){throw Error(`无法解析本脚本自身的路径（argv[1]=${n}）：构建未发生，不要当成成功。`,{cause:e})}}export{u as asRecord,x as closeQuietly,S as invokedDirectly,l as isRecord,b as maskNonCode,f as packageNameOf,d as readManifest,_ as renameWithRetry,m as singleEntryChunk,v as writeArtifact};

package/dist/build/build-types.js

@@ -1,2 +1,2 @@
-import{readFile as e,readdir as t,rename as n,rm as r,writeFile as i}from"node:fs/promises";import a from"node:path";import{execFileSync as o}from"node:child_process";const s=/(?<=\bfrom\s*)["']\.{1,2}\/[^"'\n]*?(?<!\.d)\.(?:mts|cts|ts)["']/gu,c=/(?<=\bimport\(\s*)["']\.{1,2}\/[^"'\n]*?(?<!\.d)\.(?:mts|cts|ts)["']/gu,l=/(?<=\bdeclare\s+module\s*)["']\.{1,2}\/[^"'\n]*?(?<!\.d)\.(?:mts|cts|ts)["']/gu,u={cts:`cjs`,mts:`mjs`,ts:`js`},d=/\.(?<extension>mts|cts|ts)(?=["']$)/u;function f(e){return e.replace(d,(e,t)=>`.${u[t]}`)}function p(e){return e.replaceAll(s,f).replaceAll(c,f).replaceAll(l,f)}function m(e){return typeof e==`string`?e:Buffer.isBuffer(e)?e.toString(`utf8`):``}function h(e,t,n){try{o(e,t,{cwd:n,stdio:[`ignore`,`pipe`,`pipe`],encoding:`utf8`})}catch(e){let t=(e instanceof Error&&`stdout`in e&&`stderr`in e?[e.stdout,e.stderr]:[]).map(e=>m(e)).join(`
-`).trim();throw Error(t===``?String(e):t,{cause:e})}}async function g(e,n){let r=await t(e,{withFileTypes:!0}),i=r.filter(e=>!e.isDirectory()&&e.name.endsWith(`.d.ts`)).map(e=>`${n}${e.name}`),o=await Promise.all(r.filter(e=>e.isDirectory()).map(t=>g(a.join(e,t.name),`${n}${t.name}/`)));return[...i,...o.flat()]}async function _(t){let o=t.scratch??a.join(t.root,`.tmp`,`types`),s=t.outDir??a.join(t.root,`types`),c=t.tsconfig??`tsconfig.types.json`;await r(o,{recursive:!0,force:!0});try{h(process.execPath,[t.tscEntry,`-p`,c,`--outDir`,o],t.root);let l=await g(o,``);return await Promise.all(l.map(async t=>{let n=a.join(o,t),r=await e(n,`utf8`);await i(n,p(r),`utf8`)})),await r(s,{recursive:!0,force:!0}),await n(o,s),l}catch(e){throw await r(o,{recursive:!0,force:!0}),e}}export{_ as buildDeclarations,p as canonicalizeDeclarationSpecifiers,g as listDeclarations,h as runTool,m as textOf};
+import{maskNonCode as e,renameWithRetry as t}from"./build-artifacts.js";import{randomUUID as n}from"node:crypto";import{existsSync as r}from"node:fs";import{readFile as i,readdir as a,rm as o,writeFile as s}from"node:fs/promises";import c from"node:path";import{execFileSync as l}from"node:child_process";const u=/(?<=\bfrom\s*)["']\.{1,2}\/[^"'\n]*?(?<!\.d)\.(?:mts|cts|ts)["']/gu,d=/(?<=\bimport\(\s*)["']\.{1,2}\/[^"'\n]*?(?<!\.d)\.(?:mts|cts|ts)["']/gu,f=/(?<=\bdeclare\s+module\s*)["']\.{1,2}\/[^"'\n]*?(?<!\.d)\.(?:mts|cts|ts)["']/gu,p={cts:`cjs`,mts:`mjs`,ts:`js`},m=/\.(?<extension>mts|cts|ts)(?=["']$)/u;function h(e){return e.replace(m,(e,t)=>`.${p[t]}`)}function g(t){let n=e(t),r=(e,t)=>n.charAt(t)===`"`||n.charAt(t)===`'`?h(e):e;return t.replaceAll(u,r).replaceAll(d,r).replaceAll(f,r)}function _(e){return typeof e==`string`?e:Buffer.isBuffer(e)?e.toString(`utf8`):``}function v(e,t,n){try{l(e,t,{cwd:n,stdio:[`ignore`,`pipe`,`pipe`],encoding:`utf8`})}catch(e){let t=(e instanceof Error&&`stdout`in e&&`stderr`in e?[e.stdout,e.stderr]:[]).map(e=>_(e)).join(`
+`).trim();throw Error(t===``?String(e):t,{cause:e})}}async function y(e,t){let n=await a(e,{withFileTypes:!0}),r=n.filter(e=>!e.isDirectory()&&e.name.endsWith(`.d.ts`)).map(e=>`${t}${e.name}`),i=await Promise.all(n.filter(e=>e.isDirectory()).map(n=>y(c.join(e,n.name),`${t}${n.name}/`)));return[...r,...i.flat()]}async function b(e){let a=e.scratch??c.join(e.root,`.tmp`,`types`),l=e.outDir??c.join(e.root,`types`),u=e.tsconfig??`tsconfig.types.json`;await o(a,{recursive:!0,force:!0});try{v(process.execPath,[e.tscEntry,`-p`,u,`--outDir`,a],e.root);let d=await y(a,``);await Promise.all(d.map(async e=>{let t=c.join(a,e),n=await i(t,`utf8`);await s(t,g(n),`utf8`)}));let f=e.rename??t,p=null;r(l)&&(p=`${l}.backup-${process.pid}-${n()}`,await f(l,p));try{await f(a,l)}catch(e){if(p===null)throw e;try{await f(p,l)}catch(t){throw Error(`声明产物换入失败，且备份目录未能恢复（备份留在 ${p}）：${String(e)}；恢复失败：${String(t)}`,{cause:t})}throw e}return p!==null&&await o(p,{recursive:!0,force:!0}),d}catch(e){throw await o(a,{recursive:!0,force:!0}),e}}export{b as buildDeclarations,g as canonicalizeDeclarationSpecifiers,y as listDeclarations,v as runTool,_ as textOf};

package/dist/build/decorator-lowering.js

@@ -0,0 +1,5 @@
+import{maskNonCode as e}from"./build-artifacts.js";import{mkdtempSync as t,readFileSync as n,rmSync as r}from"node:fs";import i from"node:path";import{execFileSync as a}from"node:child_process";import{tmpdir as o}from"node:os";const s=/(?:^|[\s{;(,=:[?!&|>\]})])@[A-Za-z_$][\w$]*/u,c=/\.d\.[cm]?ts$/u,l=/\.[cm]?ts$/u,u=/^\s*if \(_metadata\) Object\.defineProperty\([A-Za-z_$][\w$]*, Symbol\.metadata,/u,d=[`__esDecorate(`,`__runInitializers(`];function f(t,n){return l.test(t)&&!c.test(t)&&s.test(e(n))}function p(e){return e.endsWith(`.mts`)?`.mjs`:e.endsWith(`.cts`)?`.cjs`:`.js`}function m(e,t,n){let r=[],i=[],a=0;for(let o of e.split(`
+`)){let e=n?.[a]??``;if(a+=1,u.test(o)&&!o.trimEnd().endsWith(`);`))throw Error(`dsh-plugin-shared: Symbol.metadata 发布语句不是单行（${o.trim().slice(0,80)}…）：按行裁剪会留下残片，产物会是非法 JS。`);let s=u.test(o)||o.startsWith(`//# sourceMappingURL=`),c=d.some(e=>o.includes(e));r.push(s?``:o),i.push(s||t&&c?``:e)}return{code:r.join(`
+`),mapLines:n===null?null:i}}function h(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function g(e,s,c,u=!1){if(e.length===0)return{code:e,map:null};let d=t(i.join(o(),`dsh-decorators-`)),f=``;try{try{a(process.execPath,[c.tscEntry,`--ignoreConfig`,`--noResolve`,`--target`,`es2024`,`--module`,`preserve`,`--sourceMap`,`--outDir`,d,s],{stdio:[`ignore`,`ignore`,`pipe`],encoding:`utf8`})}catch(e){
+/* v8 ignore next 3 -- 见上：否定支在当前调用方式下不可达 */
+e instanceof Error&&`stderr`in e&&typeof e.stderr==`string`&&(f=e.stderr.trim())}let t=i.join(d,`${i.basename(s).replace(l,``)}${p(s)}`),r;try{r=n(t,`utf8`)}catch(e){let n=f===``?`（tsc 没有输出 stderr）`:f;throw Error(`dsh-plugin-shared: 装饰器降级没有产出 ${i.basename(t)}（${s}）。tsc stderr：${n}`,{cause:e})}if(r.length===0)throw Error(`dsh-plugin-shared: 装饰器降级没有产出任何字节（${s}）`);let o=null;try{let r=JSON.parse(n(`${t}.map`,`utf8`));o=h(r)?r:null,o!==null&&(o.sources=[s],o.sourcesContent=[e])}catch{}let g=o?.mappings,_=g===void 0?null:g.split(`;`),v=m(r,u,_);return o!==null&&v.mapLines!==null&&(o.mappings=v.mapLines.join(`;`)),{code:v.code,map:o}}finally{r(d,{recursive:!0,force:!0})}}function _(e){return e.includes(`?`)?e.slice(0,e.indexOf(`?`)):e}function v(e){return{name:`dsh-plugin-shared:standard-decorators`,transform(t,n){let r=_(n);return f(r,t)?g(t,r,e):null}}}function y(e){return{name:`dsh-plugin-shared:standard-decorators`,enforce:`pre`,transform(t,n){let r=_(n);return f(r,t)?g(t,r,e,!0):void 0}}}export{g as lowerStandardDecorators,f as needsDecoratorLowering,v as rolldownDecorators,y as viteDecorators};

package/dist/{card-ui-C1lrHILm.js → card-ui-D2cuQvLS.js}

@@ -43,7 +43,7 @@ import{createElement as e,useCallback as t,useEffect as n,useId as r,useLayoutEf
 .dsu-selectValue{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .dsu-chevron{flex:none;color:var(--dsw-alias-label-tertiary);transition:transform .16s}
 .dsu-select[aria-expanded="true"] .dsu-chevron{transform:rotate(180deg)}
-.dsu-menu{position:fixed;z-index:70;padding:4px;background:var(--dsw-alias-bg-layer-2);border:.5px solid var(--dsw-alias-border-l3);border-radius:12px;box-shadow:0 12px 32px rgb(0 0 0 / 50%);max-height:280px;overflow:auto}
+.dsu-menu{position:fixed;position-area:block-end span-inline-start;justify-self:start;margin-top:6px;z-index:70;padding:4px;background:var(--dsw-alias-bg-layer-2);border:.5px solid var(--dsw-alias-border-l3);border-radius:12px;box-shadow:0 12px 32px rgb(0 0 0 / 50%);max-height:280px;overflow:auto}
 .dsu-option{appearance:none;border:0;background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:13px;line-height:1.4;width:100%;display:flex;align-items:center;justify-content:space-between;gap:12px;padding:8px 10px;border-radius:8px;cursor:pointer;text-align:left}
 .dsu-option:hover,.dsu-option[data-active="true"]{background:var(--dsw-alias-bg-layer-3)}
 .dsu-option:disabled{color:var(--dsw-alias-label-tertiary);cursor:not-allowed}
@@ -82,24 +82,24 @@ if(e===null||t===null)return;let n=e.getBoundingClientRect(),r=t.offsetWidth,i=t
 /* v8 ignore next 3 -- 任何重新进入/钉住都会 cancelHide；这次复查只防未来的异步路径 */
 v.current=null,p.current||m.current||h.current||u(!1)},120))},[y]),w=t(e=>{h.current=e,f(e)},[]);i(()=>{if(!l)return()=>{};b();let e=e=>{let{target:t}=e;t instanceof Node&&_.current?.contains(t)===!0||(h.current?b():x())},t=()=>{b()};return window.addEventListener(`scroll`,e,!0),window.addEventListener(`resize`,t),()=>{window.removeEventListener(`scroll`,e,!0),window.removeEventListener(`resize`,t)}},[l,a.detail,b,x]),n(()=>{if(!l)return()=>{};let e=e=>{e.key===`Escape`&&x()};return document.addEventListener(`keydown`,e),()=>{document.removeEventListener(`keydown`,e)}},[l,x]),n(()=>y,[y]);let T=e(`button`,{ref:g,type:`button`,className:`dsu-helpBtn`,"aria-label":`${a.label} 说明`,"aria-describedby":c,"aria-pressed":d,onClick:()=>{h.current?x():(w(!0),S())}},e(`svg`,{width:12,height:12,viewBox:`0 0 14 14`,"aria-hidden":!0},e(`circle`,{cx:7,cy:7,r:6,fill:`none`,stroke:`currentColor`,strokeWidth:1.2}),e(`path`,{d:`M7 6.2v4`,stroke:`currentColor`,strokeWidth:1.3,strokeLinecap:`round`}),e(`circle`,{cx:7,cy:4.3,r:.8,fill:`currentColor`}))),E=e(`div`,{ref:_,id:c,role:`tooltip`,className:`dsu-tip`,hidden:!l},a.detail),D=a.showLabel===!1?null:e(`span`,{className:`dsu-label${a.compact===!0?` dsu-labelMono`:``}`},a.label);return e(`span`,{className:`dsu-help`,onMouseEnter:()=>{p.current=!0,S()},onMouseLeave:()=>{p.current=!1,C()},onFocus:()=>{m.current=!0,S()},onBlur:e=>{let t=e.relatedTarget;t instanceof Node&&e.currentTarget.contains(t)||(m.current=!1,C())}},D,T,E)}function h(t){let n=`dsu-label${t.compact===!0?` dsu-labelMono`:``}`,r=t.controlId===void 0?e(`span`,{className:n},t.label):e(`label`,{className:n,htmlFor:t.controlId},t.label);return e(`div`,{className:`dsu-labelRow`},r,t.detail===void 0?null:e(m,{label:t.label,detail:t.detail,showLabel:!1}))}function g(t){let n=t.controlId===void 0?void 0:`${t.controlId}-hint`;return e(`div`,{className:`dsu-field${t.wide===!0?` dsu-fieldWide`:``}`},e(`div`,{className:`dsu-fieldMeta`},e(h,{label:t.label,detail:t.detail,compact:t.compact,controlId:t.controlId}),t.hint===void 0?null:e(`p`,{className:`dsu-hint`,id:n},t.hint)),e(`div`,{className:`dsu-control`},t.children))}function _(t){let n=r(),i=t.hint===void 0?void 0:`${n}-hint`;return e(g,{...t,controlId:n},e(`button`,{type:`button`,role:`switch`,id:n,className:`dsu-switch`,"aria-checked":t.checked,"aria-describedby":i,"data-field":t.field,disabled:t.disabled===!0,onClick:()=>{t.onChange(!t.checked)}},e(`span`,{className:`dsu-knob`})))}function v(t){let i=typeof t.value==`number`&&Number.isFinite(t.value)?String(t.value):``,[a,c]=s(i),[l,u]=s(!1),d=o(void 0),f=r(),p=r(),m=[t.hint===void 0?void 0:`${f}-hint`,l?p:void 0].filter(e=>e!==void 0),h=m.length===0?void 0:m.join(` `);n(()=>{t.value!==d.current&&(d.current=t.value,c(i),u(!1))},[t.value,i]);let _=e=>{let n=t.min??-1/0,r=t.max??1/0;if(!Number.isFinite(e)||e<n||e>r)return!1;let{step:i}=t;if(i===void 0||i<=0)return!0;let a=(e-(t.min??0))/i;return Math.abs(a-Math.round(a))<1e-9},v=e=>{if(c(e),e===``){u(!1),d.current=void 0,t.onChange(void 0);return}let n=Number(e);_(n)?(u(!1),d.current=n,t.onChange(n)):u(!0)},y=()=>{a===``||l||c(String(Number(a)))};return e(g,{...t,controlId:f},e(`div`,{className:`dsu-numberWrap`},e(`div`,{className:`dsu-number`},e(`input`,{className:`dsu-input`,type:`number`,inputMode:`numeric`,id:f,value:a,min:t.min,max:t.max,step:t.step,placeholder:t.placeholder,"aria-invalid":l||void 0,"aria-describedby":h,"data-field":t.field,disabled:t.disabled===!0,onChange:e=>{v(e.target.value)},onBlur:y}),t.unit===void 0?null:e(`span`,{className:`dsu-unit`},t.unit)),l?e(`p`,{className:`dsu-error`,id:p},t.invalidHint):null))}function y(t){let[i,a]=s(t.value),[o,c]=s(!1),l=r(),u=t.hint===void 0?void 0:`${l}-hint`;n(()=>{o||a(t.value)},[t.value,o]);let d={id:l,className:`dsu-input${t.multiline===!0?` dsu-textarea`:``}${t.monospace===!0?` dsu-mono`:``}`,value:i,placeholder:t.placeholder,"aria-describedby":u,"data-field":t.field,disabled:t.disabled===!0,onFocus:()=>{c(!0)},onBlur:()=>{c(!1)},onChange:e=>{a(e.target.value),t.onChange(e.target.value)}};return e(g,{...t,controlId:l},t.multiline===!0?e(`textarea`,d):e(`input`,d))}function b(t){let i=t.separator??`comma`,a=t.value.join(i===`newline`?`
 `:`, `),[o,c]=s(a),[l,u]=s(!1),d=r(),f=t.hint===void 0?void 0:`${d}-hint`;n(()=>{l||c(a)},[a,l]);let p=e=>e.split(i===`newline`?`
-`:`,`).map(e=>e.trim()).filter(e=>e.length>0),m={id:d,className:`dsu-input${i===`newline`?` dsu-textarea dsu-mono`:``}`,value:o,placeholder:t.placeholder,"aria-describedby":f,"data-field":t.field,disabled:t.disabled===!0,onFocus:()=>{u(!0)},onBlur:()=>{u(!1)},onChange:e=>{c(e.target.value),t.onChange(p(e.target.value))}};return e(g,{...t,controlId:d},e(i===`newline`?`textarea`:`input`,m))}function x(c){let[l,u]=s(!1),[d,f]=s(0),p=o(null),m=o(null),h=r(),_=r(),v=c.hint===void 0?void 0:`${_}-hint`,{disabled:y,value:b,options:x,onChange:S}=c,C=a(()=>x.map((e,t)=>({option:e,index:t})).filter(e=>e.option.disabled!==!0),[x]),w=x.find(e=>e.value===b)?.label??b,T=x[d],E=T!==void 0&&T.disabled!==!0,D=t(()=>{let e=p.current,t=m.current;
+`:`,`).map(e=>e.trim()).filter(e=>e.length>0),m={id:d,className:`dsu-input${i===`newline`?` dsu-textarea dsu-mono`:``}`,value:o,placeholder:t.placeholder,"aria-describedby":f,"data-field":t.field,disabled:t.disabled===!0,onFocus:()=>{u(!0)},onBlur:()=>{u(!1)},onChange:e=>{c(e.target.value),t.onChange(p(e.target.value))}};return e(g,{...t,controlId:d},e(i===`newline`?`textarea`:`input`,m))}function x(){return`happyDOM`in globalThis?!1:typeof CSS<`u`&&typeof CSS.supports==`function`&&CSS.supports(`position-area: block-end`)}function S(c){let[l,u]=s(!1),[d,f]=s(0),p=o(null),m=o(null),h=r(),_=r(),v=`--dsu-${_.replaceAll(/[^a-zA-Z0-9]/gu,``)}`,y=c.hint===void 0?void 0:`${_}-hint`,{disabled:b,value:S,options:C,onChange:w}=c,T=a(()=>C.map((e,t)=>({option:e,index:t})).filter(e=>e.option.disabled!==!0),[C]),E=C.find(e=>e.value===S)?.label??S,D=C[d],O=D!==void 0&&D.disabled!==!0,k=t(()=>{let e=p.current,t=m.current;
 /* v8 ignore next 3 -- place 只在 open 的 layout effect 里调用；refs 为空只可能是卸载竞态 */
-if(e===null||t===null)return;let n=e.getBoundingClientRect(),r=Math.min(n.width,window.innerWidth-16),{left:i}=n;i+r>window.innerWidth-8&&(i=window.innerWidth-r-8);let a=t.offsetHeight,o=n.bottom+6;o+a>window.innerHeight-8&&(o=n.top-a-6);let s=Math.max(8,window.innerWidth-r-8),c=Math.max(8,window.innerHeight-a-8);t.style.width=`${r}px`,t.style.left=`${Math.min(Math.max(8,i),s)}px`,t.style.top=`${Math.min(Math.max(8,o),c)}px`},[]),O=t(()=>{u(!1)},[]),k=t(()=>{if(y===!0)return;let e=C.find(e=>e.option.value===b)??C.at(0);e!==void 0&&(f(e.index),u(!0))},[y,b,C]),A=t(e=>{
+if(e===null||t===null)return;let n=e.getBoundingClientRect(),r=Math.min(n.width,window.innerWidth-16);if(t.style.width=`${r}px`,x())return;t.style.marginTop=`0px`;let{left:i}=n;i+r>window.innerWidth-8&&(i=window.innerWidth-r-8);let a=t.offsetHeight,o=n.bottom+6;o+a>window.innerHeight-8&&(o=n.top-a-6);let s=Math.max(8,window.innerWidth-r-8),c=Math.max(8,window.innerHeight-a-8);t.style.left=`${Math.min(Math.max(8,i),s)}px`,t.style.top=`${Math.min(Math.max(8,o),c)}px`},[]),A=t(()=>{u(!1)},[]),j=t(()=>{if(b===!0)return;let e=T.find(e=>e.option.value===S)??T.at(0);e!==void 0&&(f(e.index),u(!0))},[b,S,T]),M=t(e=>{
 /* v8 ignore next 3 -- 浮层只能经由 openMenu 打开；组件禁用时打不开 */
-if(y===!0)return;let t=x[e];
-/* v8 ignore next 3 -- disabled 选项在浏览器里不派发 click；越界下标由调用面保证 */
-t!==void 0&&t.disabled!==!0&&(S(t.value),O(),p.current?.focus())},[y,x,S,O]),j=t(e=>{let t=C.findIndex(e=>e.index===d);
+if(b===!0)return;let t=C[e];
+/* v8 ignore next 3 -- disabled 选项在浏览器里不派发 click；越界下标由调用方保证 */
+t!==void 0&&t.disabled!==!0&&(w(t.value),A(),p.current?.focus())},[b,C,w,A]),N=t(e=>{let t=T.findIndex(e=>e.index===d);
 /* v8 ignore next 5 -- open 时归一 effect 已保证 enabled 非空且 active 落在可用项上 */
-if(t===-1||C.length===0)return;let n=(t+e+C.length)%C.length,r=C[n];
+if(t===-1||T.length===0)return;let n=(t+e+T.length)%T.length,r=T[n];
 /* v8 ignore next 3 -- next 由取模保证在界内 */
-r!==void 0&&f(r.index)},[d,C]);i(()=>{if(!l)return()=>{};D();let e=e=>{let t=e.target;m.current?.contains(t)!==!0&&p.current?.contains(t)!==!0&&O()},t=e=>{let{target:t}=e;t instanceof Node&&m.current?.contains(t)===!0||O()},n=()=>{D()};return document.addEventListener(`pointerdown`,e,!0),window.addEventListener(`scroll`,t,!0),window.addEventListener(`resize`,n),()=>{document.removeEventListener(`pointerdown`,e,!0),window.removeEventListener(`scroll`,t,!0),window.removeEventListener(`resize`,n)}},[l,c.options,D,O]),n(()=>{if(!l)return;if(y===!0||C.length===0){O();return}if(C.some(e=>e.index===d))return;let e=C.find(e=>e.option.value===b)??C.at(0);
+r!==void 0&&f(r.index)},[d,T]);i(()=>{if(!l)return()=>{};k();let e=e=>{let t=e.target;m.current?.contains(t)!==!0&&p.current?.contains(t)!==!0&&A()},t=e=>{let{target:t}=e;t instanceof Node&&m.current?.contains(t)===!0||A()},n=()=>{k()};return document.addEventListener(`pointerdown`,e,!0),window.addEventListener(`scroll`,t,!0),window.addEventListener(`resize`,n),()=>{document.removeEventListener(`pointerdown`,e,!0),window.removeEventListener(`scroll`,t,!0),window.removeEventListener(`resize`,n)}},[l,c.options,k,A]),n(()=>{if(!l)return;if(b===!0||T.length===0){A();return}if(T.some(e=>e.index===d))return;let e=T.find(e=>e.option.value===S)??T.at(0);
 /* v8 ignore next 3 -- enabled 非空在上一分支已保证 */
-e!==void 0&&f(e.index)},[l,y,b,x,d,O,C]),i(()=>{if(!l)return;let e=m.current;
+e!==void 0&&f(e.index)},[l,b,S,C,d,A,T]),i(()=>{if(!l)return;let e=m.current;
 /* v8 ignore next 2 -- 同上，menu 在 open 的 commit 之后必然已挂上 */
 if(e===null)return;let t=e.querySelector(`[data-active="true"]`);
 /* v8 ignore next 2 -- active 已由归一 effect 保证落在可用项上 */
-t!==null&&(t.offsetTop<e.scrollTop?e.scrollTop=t.offsetTop:t.offsetTop+t.offsetHeight>e.scrollTop+e.clientHeight&&(e.scrollTop=t.offsetTop+t.offsetHeight-e.clientHeight))},[l,d,x]);let M=e=>{if(e.key===`ArrowDown`||e.key===`ArrowUp`){if(e.preventDefault(),!l){k();return}j(e.key===`ArrowDown`?1:-1)}else if(e.key===`Home`||e.key===`End`){if(e.preventDefault(),l||k(),C.length===0)return;let t=e.key===`Home`?C.at(0):C.at(-1);
+t!==null&&(t.offsetTop<e.scrollTop?e.scrollTop=t.offsetTop:t.offsetTop+t.offsetHeight>e.scrollTop+e.clientHeight&&(e.scrollTop=t.offsetTop+t.offsetHeight-e.clientHeight))},[l,d,C]);let P=e=>{if(e.key===`ArrowDown`||e.key===`ArrowUp`){if(e.preventDefault(),!l){j();return}N(e.key===`ArrowDown`?1:-1)}else if(e.key===`Home`||e.key===`End`){if(e.preventDefault(),l||j(),T.length===0)return;let t=e.key===`Home`?T.at(0):T.at(-1);
 /* v8 ignore next 3 -- enabled 为空已在上一条返回 */
-if(t===void 0)return;f(t.index)}else if(e.key===`Enter`||e.key===` `){if(e.preventDefault(),!l){k();return}A(d)}else(e.key===`Tab`||e.key===`Escape`)&&O()},N=[],P;for(let[t,n]of x.entries())n.group!==P&&(n.group!==void 0&&N.push(e(`div`,{key:`group-${t}-${n.group}`,className:`dsu-optionGroup`,role:`presentation`},n.group)),P=n.group),N.push(e(`button`,{key:`option-${n.value}`,type:`button`,role:`option`,id:`${h}-${t}`,className:`dsu-option`,tabIndex:-1,"aria-selected":n.value===c.value,"data-active":t===d,disabled:n.disabled===!0,onMouseDown:e=>{e.preventDefault()},onClick:()=>{A(t)},onMouseEnter:()=>{
+if(t===void 0)return;f(t.index)}else if(e.key===`Enter`||e.key===` `){if(e.preventDefault(),!l){j();return}M(d)}else(e.key===`Tab`||e.key===`Escape`)&&A()},F=[],I;for(let[t,n]of C.entries())n.group!==I&&(n.group!==void 0&&F.push(e(`div`,{key:`group-${t}-${n.group}`,className:`dsu-optionGroup`,role:`presentation`},n.group)),I=n.group),F.push(e(`button`,{key:`option-${n.value}`,type:`button`,role:`option`,id:`${h}-${t}`,className:`dsu-option`,tabIndex:-1,"aria-selected":n.value===c.value,"data-active":t===d,disabled:n.disabled===!0,onMouseDown:e=>{e.preventDefault()},onClick:()=>{M(t)},onMouseEnter:()=>{
 /* v8 ignore next -- happy-dom 对 disabled 元素不派发 mouse 事件；浏览器实现各有差异，保留禁用检查 */
-n.disabled!==!0&&f(t)}},e(`span`,null,n.label),e(`svg`,{className:`dsu-check`,width:14,height:14,viewBox:`0 0 14 14`,"aria-hidden":!0},e(`path`,{d:`M2.5 7.5l3 3 6-7`,fill:`none`,stroke:`currentColor`,strokeWidth:1.5,strokeLinecap:`round`,strokeLinejoin:`round`}))));return e(g,{...c,controlId:_},e(`div`,{className:`dsu-selectWrap`,onBlur:e=>{let t=e.relatedTarget;t instanceof Node&&e.currentTarget.contains(t)||O()}},e(`button`,{ref:p,type:`button`,id:_,className:`dsu-select dsu-input`,role:`combobox`,"aria-haspopup":`listbox`,"aria-expanded":l,"aria-controls":`${h}-list`,"aria-activedescendant":l&&E?`${h}-${d}`:void 0,"aria-describedby":v,"data-field":c.field,disabled:y===!0||x.length===0,onClick:()=>{l?O():k()},onKeyDown:M},e(`span`,{className:`dsu-selectValue`},w),e(`svg`,{className:`dsu-chevron`,width:14,height:14,viewBox:`0 0 14 14`,"aria-hidden":!0},e(`path`,{d:`M3 5l4 4 4-4`,fill:`none`,stroke:`currentColor`,strokeWidth:1.5,strokeLinecap:`round`,strokeLinejoin:`round`}))),e(`div`,{ref:m,id:`${h}-list`,role:`listbox`,className:`dsu-menu`,"aria-label":c.label,hidden:!l},...N)))}function S(t){let n=!t.writable||t.busy||!t.dirty,r;return r=t.error===null?t.writable?t.dirty?t.dirtyLabel:t.cleanLabel:t.readOnlyLabel:t.error,e(`div`,{className:`dsu-savebar`,"data-dirty":t.dirty},e(`button`,{type:`button`,className:`dsu-btn dsu-btnPrimary`,"data-field":`save`,disabled:n,onClick:t.onSave},t.busy?t.savingLabel:t.saveLabel),e(`button`,{type:`button`,className:`dsu-btn`,"data-field":`discard`,disabled:n,onClick:t.onDiscard},t.revertLabel),e(`span`,{className:t.error===null?`dsu-status`:`dsu-status dsu-statusError`},r))}export{y as a,h as c,f as d,d as f,c as h,v as i,m as l,l as m,x as n,_ as o,p,b as r,g as s,S as t,u};
+n.disabled!==!0&&f(t)}},e(`span`,null,n.label),e(`svg`,{className:`dsu-check`,width:14,height:14,viewBox:`0 0 14 14`,"aria-hidden":!0},e(`path`,{d:`M2.5 7.5l3 3 6-7`,fill:`none`,stroke:`currentColor`,strokeWidth:1.5,strokeLinecap:`round`,strokeLinejoin:`round`}))));return e(g,{...c,controlId:_},e(`div`,{className:`dsu-selectWrap`,onBlur:e=>{let t=e.relatedTarget;t instanceof Node&&e.currentTarget.contains(t)||A()}},e(`button`,{ref:p,type:`button`,id:_,style:{anchorName:v},className:`dsu-select dsu-input`,role:`combobox`,"aria-haspopup":`listbox`,"aria-expanded":l,"aria-controls":`${h}-list`,"aria-activedescendant":l&&O?`${h}-${d}`:void 0,"aria-describedby":y,"data-field":c.field,disabled:b===!0||C.length===0,onClick:()=>{l?A():j()},onKeyDown:P},e(`span`,{className:`dsu-selectValue`},E),e(`svg`,{className:`dsu-chevron`,width:14,height:14,viewBox:`0 0 14 14`,"aria-hidden":!0},e(`path`,{d:`M3 5l4 4 4-4`,fill:`none`,stroke:`currentColor`,strokeWidth:1.5,strokeLinecap:`round`,strokeLinejoin:`round`}))),e(`div`,{ref:m,id:`${h}-list`,role:`listbox`,className:`dsu-menu`,style:{positionAnchor:v,positionTryFallbacks:`flip-block, flip-inline`},"aria-label":c.label,hidden:!l},...F)))}function C(t){let n=!t.writable||t.busy||!t.dirty,r;return r=t.error===null?t.writable?t.dirty?t.dirtyLabel:t.cleanLabel:t.readOnlyLabel:t.error,e(`div`,{className:`dsu-savebar`,"data-dirty":t.dirty},e(`button`,{type:`button`,className:`dsu-btn dsu-btnPrimary`,"data-field":`save`,disabled:n,onClick:t.onSave},t.busy?t.savingLabel:t.saveLabel),e(`button`,{type:`button`,className:`dsu-btn`,"data-field":`discard`,disabled:n,onClick:t.onDiscard},t.revertLabel),e(`span`,{className:t.error===null?`dsu-status`:`dsu-status dsu-statusError`},r))}export{y as a,h as c,f as d,d as f,c as h,v as i,m as l,l as m,S as n,_ as o,p,b as r,g as s,C as t,u};

package/dist/card-ui.js

@@ -1 +1 @@
-export{h as CARD_UI_CSS,u as CardForm,s as Field,d as FieldGrid,c as FieldLabel,l as InfoTip,r as ListField,i as NumberField,t as SaveBar,f as Section,n as SelectField,p as StatusBar,a as TextField,o as ToggleField,m as splitHint}from"./card-ui-C1lrHILm.js";
+export{h as CARD_UI_CSS,u as CardForm,s as Field,d as FieldGrid,c as FieldLabel,l as InfoTip,r as ListField,i as NumberField,t as SaveBar,f as Section,n as SelectField,p as StatusBar,a as TextField,o as ToggleField,m as splitHint}from"./card-ui-D2cuQvLS.js";

package/dist/client-entry.js

@@ -1 +1 @@
-import{a as e,c as t,d as n,f as r,h as i,i as a,l as o,m as s,n as c,o as l,p as u,r as d,s as f,t as p,u as m}from"./card-ui-C1lrHILm.js";import{diffTouched as h}from"./card-diff.js";import{claimApply as g}from"./card-apply.js";import{fieldOf as _,isRecord as v}from"./record.js";import{errorText as y}from"./errors.js";const b=`@jayyuen66/dsh-plugin-shared`;function x(){}export{i as CARD_UI_CSS,m as CardForm,f as Field,n as FieldGrid,t as FieldLabel,o as InfoTip,d as ListField,a as NumberField,p as SaveBar,r as Section,c as SelectField,u as StatusBar,e as TextField,l as ToggleField,x as apply,g as claimApply,h as diffTouched,y as errorText,_ as fieldOf,v as isRecord,b as name,s as splitHint};
+import{a as e,c as t,d as n,f as r,h as i,i as a,l as o,m as s,n as c,o as l,p as u,r as d,s as f,t as p,u as m}from"./card-ui-D2cuQvLS.js";import{diffTouched as h}from"./card-diff.js";import{claimApply as g}from"./card-apply.js";import{fieldOf as _,isRecord as v}from"./record.js";import{errorText as y}from"./errors.js";const b=`@jayyuen66/dsh-plugin-shared`;function x(){}export{i as CARD_UI_CSS,m as CardForm,f as Field,n as FieldGrid,t as FieldLabel,o as InfoTip,d as ListField,a as NumberField,p as SaveBar,r as Section,c as SelectField,u as StatusBar,e as TextField,l as ToggleField,x as apply,g as claimApply,h as diffTouched,y as errorText,_ as fieldOf,v as isRecord,b as name,s as splitHint};

package/dist/client.js

@@ -54,7 +54,7 @@ const CARD_UI_CSS = `
 .dsu-selectValue{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .dsu-chevron{flex:none;color:var(--dsw-alias-label-tertiary);transition:transform .16s}
 .dsu-select[aria-expanded="true"] .dsu-chevron{transform:rotate(180deg)}
-.dsu-menu{position:fixed;z-index:70;padding:4px;background:var(--dsw-alias-bg-layer-2);border:.5px solid var(--dsw-alias-border-l3);border-radius:12px;box-shadow:0 12px 32px rgb(0 0 0 / 50%);max-height:280px;overflow:auto}
+.dsu-menu{position:fixed;position-area:block-end span-inline-start;justify-self:start;margin-top:6px;z-index:70;padding:4px;background:var(--dsw-alias-bg-layer-2);border:.5px solid var(--dsw-alias-border-l3);border-radius:12px;box-shadow:0 12px 32px rgb(0 0 0 / 50%);max-height:280px;overflow:auto}
 .dsu-option{appearance:none;border:0;background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:13px;line-height:1.4;width:100%;display:flex;align-items:center;justify-content:space-between;gap:12px;padding:8px 10px;border-radius:8px;cursor:pointer;text-align:left}
 .dsu-option:hover,.dsu-option[data-active="true"]{background:var(--dsw-alias-bg-layer-3)}
 .dsu-option:disabled{color:var(--dsw-alias-label-tertiary);cursor:not-allowed}
@@ -347,8 +347,8 @@ function NumberField(props) {
 		setInvalid(false);
 	}, [props.value, text]);
 	const accepts = (value) => {
-		const min = props.min ?? -Infinity;
-		const max = props.max ?? Infinity;
+		const min = props.min ?? -1e400;
+		const max = props.max ?? 1e400;
 		if (!Number.isFinite(value) || value < min || value > max) return false;
 		const { step } = props;
 		if (step === void 0 || step <= 0) return true;
@@ -472,6 +472,16 @@ function ListField(props) {
 	}, separator === "newline" ? (0, react.createElement)("textarea", shared) : (0, react.createElement)("input", shared));
 }
 // lib/card-ui/select.ts
+/** 浏览器是否支持 CSS anchor 定位（宿主 webview 支持，与宿主 Menu 同一套平台 API）。
+*  支持时浮层位置由 `position-area` 跟随触发器，缩放/平移不漂；happy-dom 等不支持处回退 JS 矩形。
+*  探测的是本组件实际依赖的 `position-area`，不是更早出现的 `anchor-name`：只支持
+*  `anchor-name` 的半档实现里浮层不会被真正定位。happy-dom 的 CSS.supports 对 anchor-name
+*  误返 true，但它并不真做 anchor 布局；happy-dom 在 window 上暴露 happyDOM 属性，据此排除
+*  （真实浏览器没有该属性）。 */
+function cssAnchorSupported() {
+	if ("happyDOM" in globalThis) return false;
+	return typeof CSS !== "undefined" && typeof CSS.supports === "function" && CSS.supports("position-area: block-end");
+}
 /** 自定义下拉：浮层固定定位，键盘可选，点击外部关闭。 */
 function SelectField(props) {
 	const [open, setOpen] = (0, react.useState)(false);
@@ -480,6 +490,7 @@ function SelectField(props) {
 	const menuRef = (0, react.useRef)(null);
 	const baseId = (0, react.useId)();
 	const controlId = (0, react.useId)();
+	const anchorId = `--dsu-${controlId.replaceAll(/[^a-zA-Z0-9]/gu, "")}`;
 	const describedBy = props.hint === void 0 ? void 0 : `${controlId}-hint`;
 	const { disabled, value, options, onChange } = props;
 	const enabled = (0, react.useMemo)(() => options.map((option, index) => ({
@@ -496,6 +507,9 @@ function SelectField(props) {
 		if (trigger === null || menu === null) return;
 		const rect = trigger.getBoundingClientRect();
 		const width = Math.min(rect.width, window.innerWidth - 16);
+		menu.style.width = `${width}px`;
+		if (cssAnchorSupported()) return;
+		menu.style.marginTop = "0px";
 		let { left } = rect;
 		if (left + width > window.innerWidth - 8) left = window.innerWidth - width - 8;
 		const height = menu.offsetHeight;
@@ -503,7 +517,6 @@ function SelectField(props) {
 		if (top + height > window.innerHeight - 8) top = rect.top - height - 6;
 		const maxLeft = Math.max(8, window.innerWidth - width - 8);
 		const maxTop = Math.max(8, window.innerHeight - height - 8);
-		menu.style.width = `${width}px`;
 		menu.style.left = `${Math.min(Math.max(8, left), maxLeft)}px`;
 		menu.style.top = `${Math.min(Math.max(8, top), maxTop)}px`;
 	}, []);
@@ -525,7 +538,7 @@ function SelectField(props) {
 		/* v8 ignore next 3 -- 浮层只能经由 openMenu 打开；组件禁用时打不开 */
 		if (disabled === true) return;
 		const option = options[index];
-		/* v8 ignore next 3 -- disabled 选项在浏览器里不派发 click；越界下标由调用面保证 */
+		/* v8 ignore next 3 -- disabled 选项在浏览器里不派发 click；越界下标由调用方保证 */
 		if (option === void 0 || option.disabled === true) return;
 		onChange(option.value);
 		close();
@@ -710,6 +723,7 @@ function SelectField(props) {
 		ref: triggerRef,
 		type: "button",
 		id: controlId,
+		style: { anchorName: anchorId },
 		className: "dsu-select dsu-input",
 		role: "combobox",
 		"aria-haspopup": "listbox",
@@ -745,6 +759,10 @@ function SelectField(props) {
 		id: `${baseId}-list`,
 		role: "listbox",
 		className: "dsu-menu",
+		style: {
+			positionAnchor: anchorId,
+			positionTryFallbacks: "flip-block, flip-inline"
+		},
 		"aria-label": props.label,
 		hidden: !open
 	}, ...optionNodes)));

package/dist/remote-marker.js

@@ -0,0 +1 @@
+import{Remote as e}from"@deepseek-ai/dsh-typert-protocol";function t(t,n){let r={kind:`method`,name:n,static:!1,private:!1,addInitializer:e=>{Reflect.apply(e,Object.create(t),[])}},i=e(n);Reflect.apply(i,void 0,[Reflect.get(t,n),r])}export{t as markRemote};

package/dist/types/build-artifacts.d.ts

@@ -15,7 +15,7 @@ export declare function asRecord(raw: unknown): Record<string, unknown>;
  * 读包根的 package.json，带上下文的失败信息。
  *
  * 惰性（调用时才读）而不是在消费方模块顶层读：顶层一次 JSON 语法错误会以未捕获的顶层
- * await 错误 + 裸 SyntaxError 收场，读者看不出是哪个文件坏了；而测试 import 构建模块时
+ * await 错误 + 不带文件路径的 SyntaxError 收场，读者看不出是哪个文件坏了；而测试 import 构建模块时
  * 只为拿构建函数，不该连带做一次磁盘 I/O。
  * @param root - 包根绝对路径
  * @returns 解析后的 manifest
@@ -51,23 +51,49 @@ export interface OutputItem {
 export declare function singleEntryChunk(output: readonly OutputItem[], source: string): OutputItem & {
     code: string;
 };
+/**
+ * rename 的 Windows 退避重试。
+ *
+ * POSIX 上 rename 换目录项是原子的，失败即真失败；Windows 上目标文件被其它进程持有
+ * （Electron / dev server 正 require 产物、杀毒或索引服务短暂占用）时会给 EPERM/EBUSY，
+ * 而占用通常在几十毫秒内释放。不重试的话这条失败是**间歇性**的：同一份安装里连着构建两次，
+ * 一次失败一次成功。其余错误码照旧立即抛出——真的没权限时重试只是拖慢失败。
+ * @param from - 草稿文件
+ * @param to - 目标文件
+ * @param attempt - 已重试次数
+ */
+export declare function renameWithRetry(from: string, to: string, attempt?: number): Promise<void>;
 /**
  * 原子写入：目标目录下 `.tmp/` 草稿 + rename；失败时清掉草稿再抛。
  *
  * 草稿落在**目标文件所在目录**下的 `.tmp/`，不是 `os.tmpdir()`，也不是产物旁边的裸名：
  *   - 不用 `os.tmpdir()`：rename 只在同一文件系统内原子，跨设备会以 EXDEV 失败，而系统临时
  *     目录常被挂到另一个分区/卷；
- *   - 跟随目标目录而不是写死包根：本函数住在公共库里，产物落点由调用方决定；
+ *   - 跟随目标目录而不是写死包根：本函数定义在公共库里，产物写到哪儿由调用方决定；
  *   - 不用「产物名 + 后缀」直接落在产物旁边：那个名字通常不在 `.gitignore` 里，构建被中断
  *     时半份产物会以未跟踪文件出现在 `git status`，被误当成源码改动提交。`.tmp/` 是各包
  *     统一忽略的目录，不需要为构建残留单独扩忽略规则。
  *
- * 失败信息带上两个路径并保留 cause：裸 `ENOENT … open '…/<uuid>.tmp'` 把注意力引到草稿名上，
+ * 失败信息带上两个路径并保留 cause：只有 `ENOENT … open '…/<uuid>.tmp'` 把注意力引到草稿名上，
  * 读者还得自己从中找出真正的产物路径。
  * @param target - 目标文件绝对路径
  * @param text - 产物正文
  */
 export declare function writeArtifact(target: string, text: string): Promise<void>;
+/**
+ * 把注释与字符串内容替换成空格，保留长度与换行；引号/反引号本身保留。
+ *
+ * 用途是给**形状判断**（装饰器语法、声明里的模块说明符）提供一份与原文逐字符对齐的
+ * “只看程序正文”文本：调用方拿同一套下标回到原文取值，既不误伤注释里的示例，也不会
+ * 把字面量类型里的 `from "./x.ts"` 当成真实说明符。
+ *
+ * 字符串里的转义对整体遮蔽；模板字面量的 `${}` 不做二次解析（本包不需要在表达式里
+ * 找装饰器或说明符）。正则字面量不做词法识别，里面的 `@` 可能造成一次多余的 tsc 调用
+ * ——方向是安全的（只多跑一次编译，不产出错字节）。
+ * @param code - 源文本
+ * @returns 与入参等长、换行位置不变的遮蔽文本
+ */
+export declare function maskNonCode(code: string): string;
 /** 异常路径上释放 rolldown bundle 的最小接口。 */
 export interface CloseableBundle {
     readonly close: () => Promise<void>;
@@ -86,7 +112,7 @@ export interface RolldownBundle extends CloseableBundle {
  * 调用方注入的 rolldown 构造器。
  *
  * 注入而不是由本包声明依赖：rolldown 是各包构建期自己的 devDependency，本包作为库
- * 不该为构建工具声明运行期依赖面。参数类型借 rolldown 自己的 InputOptions（仅类型
+ * 不该为构建工具声明运行期依赖。参数类型借 rolldown 自己的 InputOptions（仅类型
  * 导入，产物里没有它）。
  */
 export type RolldownFactory = (options: InputOptions) => Promise<RolldownBundle>;

package/dist/types/build-client.d.ts

@@ -1,8 +1,8 @@
 import type { RolldownFactory } from "./build-artifacts.js";
 /**
- * 宿主 seed 表里 react 家族的全部说明符（客户端产物只外置宿主真给得出的模块）。
+ * 宿主 seed 表里 react 家族的全部模块说明符——客户端产物只外置宿主真给得出的模块。
  * 与宿主客户端自己的模块表同源：那张表里 react 家族只有这四条。外置清单更大的包
- * （宿主外壳基座扩容后）由调用方在 `externals` 里给全量清单。
+ * （宿主 外壳 的 PLATFORM_MODULES，即宿主平台模块表，扩容后）由调用方在 `externals` 里给全量清单。
  */
 export declare const REACT_RUNTIME_MODULES: readonly string[];
 /**
@@ -38,9 +38,9 @@ export declare function collapseStorePaths(code: string): string;
  * 判断材料在这里。
  */
 export interface ClientNameContext {
-    /** package.json 的 name（外壳 id 的唯一来源）。 */
+    /** package.json 的 name（外壳 里 id 的唯一来源）。 */
     readonly pkgName: string;
-    /** 改写后的 chunk 正文（未包外壳）。 */
+    /** 改写后的 chunk 正文（尚未包进 外壳）。 */
     readonly body: string;
     /** 读包根下一份源码文件。 */
     readonly readSource: (relative: string) => Promise<string>;
@@ -68,9 +68,9 @@ export interface ClientBuildOptions {
 /**
  * 客户端外置规则：登记过的精确说明符外置，react 家族里**没登记**的说明符当场失败。
  *
- * 为什么既不静默内联也不前缀放行：外壳注入的 require 只在宿主模块表里查键。前缀放行会
- * 得到一条表里没有的 require（加载期 not in the module table，整张卡片静默不渲染）；而
- * 静默内联会把 node_modules 里那份 React 打进产物、与宿主那份并存，页面里两个 React
+ * 为什么既不悄悄内联也不按前缀放行：外壳 注入的 require 只在宿主模块表里查键。按前缀放行会
+ * 得到一条表里没有的 require（加载期 not in the module table，整张卡片不渲染也不给提示）；而
+ * 悄悄内联会把 node_modules 里那份 React 打进产物、与宿主那份并存，页面里两个 React
  * 实例， hooks 直接报错。两种失败都不在构建期报错，所以这里没有可观察的中间态。
  * 导出给各包的构建脚本复用与测试直接驱动，与构建走同一份判断。
  * @param externals - 外置说明符全量清单（精确匹配）

package/dist/types/build-types.d.ts

@@ -6,16 +6,22 @@ export interface TypesBuildOptions {
     readonly tscEntry: string;
     /** tsconfig 项目名（相对包根）。缺省 `tsconfig.types.json`。 */
     readonly tsconfig?: string;
-    /** 草稿目录绝对路径。缺省 `<root>/.tmp/types`（该目录在各包统一被 git 忽略，
+    /** scratch 临时目录的绝对路径。缺省 `<root>/.tmp/types`（该目录在各包统一被 git 忽略，
      * 且与 types/ 同一文件系统，最后一步 rename 原子且不跨设备）。 */
     readonly scratch?: string;
     /** 产物目录绝对路径。缺省 `<root>/types`。 */
     readonly outDir?: string;
+    /** 目录换入用的 rename（缺省走 Windows 退避重试）。注入点供测试制造换入失败，
+     *  以及让不支持 rename 的宿主替换实现。 */
+    readonly rename?: (from: string, to: string) => Promise<void>;
 }
 /**
- * 把一段声明正文里的相对源码后缀说明符改写成对侧产物后缀。
+ * 把一段声明正文里带源码后缀的相对说明符改写成对侧产物后缀。
  *
  * 三处 replace 各自收一种句法位置，互不依赖；同一个文件里三种都出现时不漏也不重。
+ * 三处正则都会在**注释与字符串内部**命中，所以替换前先用 {@link maskNonCode} 取一份
+ * 等长的正文遮蔽文本，只有“说明符起始引号在正文位置上”的命中才改写：JSDoc 示例里的
+ * `from "./x.ts"` 与字面量类型 `type P = 'from "./x.ts"'` 因此原样保留。
  * @param text - 声明文件正文
  * @returns 改写后的正文
  */

package/dist/types/card-ui/styles.d.ts

@@ -1,2 +1,2 @@
 /** 设置卡统一样式。颜色/圆角全部走宿主主题令牌。 */
-export declare const CARD_UI_CSS = "\n.dsu-form{display:flex;flex-direction:column}\n.dsu-section{margin-top:24px;padding-top:24px;border-top:.5px solid var(--dsw-alias-border-l1)}\n.dsu-form>.dsu-section:first-child{margin-top:0;padding-top:0;border-top:0}\n.dsu-sectionTitle{margin:0;font-size:15px;font-weight:600;line-height:1.4;color:var(--dsw-alias-label-primary)}\n.dsu-sectionHint{margin:4px 0 0;font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}\n.dsu-statusbar{display:flex;flex-wrap:wrap;gap:4px 8px;margin-top:8px;font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}\n.dsu-field{display:grid;grid-template-columns:minmax(0,1fr) minmax(240px,360px);column-gap:32px;align-items:center;padding:12px 0;border-top:.5px solid var(--dsw-alias-border-l2)}\n.dsu-fieldMeta{display:flex;flex-direction:column;gap:4px;min-width:0}\n.dsu-labelRow{display:flex;align-items:center;gap:6px;min-width:0}\n.dsu-label{font-size:13px;font-weight:500;line-height:1.5;color:var(--dsw-alias-label-primary)}\n.dsu-labelMono{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px}\n.dsu-hint{margin:0;font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}\n.dsu-control{min-width:0;display:flex;align-items:center;gap:8px}\n.dsu-fieldWide{grid-template-columns:minmax(0,1fr);align-items:start}\n.dsu-fieldWide .dsu-control{width:100%;max-width:720px;margin-top:2px}\n.dsu-help{display:inline-flex;align-items:center;gap:6px;min-width:0}\n.dsu-helpBtn{appearance:none;border:0;background:transparent;padding:0;width:16px;height:16px;display:inline-flex;align-items:center;justify-content:center;color:var(--dsw-alias-label-tertiary);cursor:help;border-radius:50%;flex:none}\n.dsu-help:hover .dsu-helpBtn,.dsu-helpBtn:focus-visible{color:var(--dsw-alias-label-primary)}\n.dsu-helpBtn:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:1px}\n.dsu-tip{position:fixed;z-index:60;box-sizing:border-box;max-width:min(340px,calc(100vw - 16px));max-height:calc(100vh - 16px);overflow:auto;overflow-wrap:anywhere;padding:10px 12px;border-radius:10px;background:var(--dsw-alias-bg-layer-2);border:.5px solid var(--dsw-alias-border-l3);box-shadow:0 12px 32px rgb(0 0 0 / 45%);font-size:12px;line-height:1.6;font-weight:400;color:var(--dsw-alias-label-secondary)}\n.dsu-input{width:100%;height:34px;padding:0 12px;border:.5px solid var(--dsw-alias-border-l4);border-radius:var(--dsw-radius-md);background:var(--dsw-alias-bg-layer-3);color:var(--dsw-alias-label-primary);font:inherit;font-size:13px}\n.dsu-input:focus-visible{outline:none;border-color:var(--dsw-alias-state-business-primary)}\n.dsu-input[aria-invalid=\"true\"]{border-color:var(--dsw-alias-state-error-primary)}\n.dsu-input:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}\n.dsu-input::placeholder{color:var(--dsw-alias-label-tertiary)}\n.dsu-textarea{height:auto;min-height:96px;padding:8px 12px;line-height:1.6;resize:vertical}\n.dsu-mono{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}\n.dsu-numberWrap{display:flex;flex-direction:column;gap:4px;width:100%;min-width:0}\n.dsu-number{display:flex;align-items:center;gap:8px;min-width:0}\n.dsu-number .dsu-input{min-width:0}\n.dsu-unit{flex:none;font-size:12px;color:var(--dsw-alias-label-tertiary)}\n.dsu-error{margin:0;font-size:12px;line-height:1.5;color:var(--dsw-alias-state-error-primary)}\n.dsu-switch{appearance:none;width:36px;height:20px;border-radius:999px;border:0;padding:2px;background:var(--dsw-alias-border-l3);display:flex;align-items:center;cursor:pointer;flex:none;transition:background-color .16s}\n.dsu-knob{width:16px;height:16px;border-radius:50%;background:var(--dsw-alias-label-primary);transition:transform .16s,background-color .16s}\n.dsu-switch[aria-checked=\"true\"]{background:var(--dsw-alias-label-primary)}\n.dsu-switch[aria-checked=\"true\"] .dsu-knob{transform:translateX(16px);background:var(--dsw-alias-label-primary-foreground)}\n.dsu-switch:disabled{opacity:.4;cursor:not-allowed}\n.dsu-switch:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:2px}\n.dsu-selectWrap{position:relative;width:100%;min-width:0}\n.dsu-select{display:flex;align-items:center;justify-content:space-between;gap:8px;text-align:left;cursor:pointer}\n.dsu-select[aria-expanded=\"true\"]{border-color:var(--dsw-alias-state-business-primary)}\n.dsu-selectValue{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}\n.dsu-chevron{flex:none;color:var(--dsw-alias-label-tertiary);transition:transform .16s}\n.dsu-select[aria-expanded=\"true\"] .dsu-chevron{transform:rotate(180deg)}\n.dsu-menu{position:fixed;z-index:70;padding:4px;background:var(--dsw-alias-bg-layer-2);border:.5px solid var(--dsw-alias-border-l3);border-radius:12px;box-shadow:0 12px 32px rgb(0 0 0 / 50%);max-height:280px;overflow:auto}\n.dsu-option{appearance:none;border:0;background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:13px;line-height:1.4;width:100%;display:flex;align-items:center;justify-content:space-between;gap:12px;padding:8px 10px;border-radius:8px;cursor:pointer;text-align:left}\n.dsu-option:hover,.dsu-option[data-active=\"true\"]{background:var(--dsw-alias-bg-layer-3)}\n.dsu-option:disabled{color:var(--dsw-alias-label-tertiary);cursor:not-allowed}\n.dsu-option:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:-2px}\n.dsu-optionGroup{padding:6px 10px 2px;font-size:11px;font-weight:600;color:var(--dsw-alias-label-tertiary)}\n.dsu-check{opacity:0;flex:none}\n.dsu-option[aria-selected=\"true\"] .dsu-check{opacity:1}\n.dsu-savebar{display:flex;align-items:center;gap:8px;padding:12px 0;margin-top:24px;border-top:.5px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-base)}\n.dsu-savebar[data-dirty=\"true\"]{position:sticky;bottom:0;z-index:2;box-shadow:0 -12px 24px rgb(0 0 0 / 35%)}\n.dsu-btn{appearance:none;border:.5px solid var(--dsw-alias-border-l2);background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:13px;line-height:1.5;border-radius:var(--dsw-radius-md);padding:5px 14px;cursor:pointer;transition:background-color .12s,border-color .12s,color .12s,filter .12s}\n.dsu-btn:hover:not(:disabled){background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-border-l3)}\n.dsu-btn:active:not(:disabled){background:var(--dsw-alias-bg-layer-1)}\n.dsu-btn:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:1px}\n.dsu-btn:disabled{opacity:.4;cursor:not-allowed}\n.dsu-btnPrimary{background:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-3)}\n.dsu-btnPrimary:hover:not(:disabled){background:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-primary);filter:brightness(.9)}\n.dsu-btnPrimary:active:not(:disabled){background:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-primary);filter:brightness(.84)}\n.dsu-btnDanger{color:var(--dsw-alias-state-error-primary)}\n.dsu-btnDanger:hover:not(:disabled){color:var(--dsw-alias-state-error-primary);border-color:var(--dsw-alias-state-error-primary);background:var(--dsw-alias-bg-layer-2)}\n.dsu-status{margin-left:auto;font-size:12px;color:var(--dsw-alias-label-tertiary)}\n.dsu-statusError{color:var(--dsw-alias-state-error-primary)}\n.dsu-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(200px,100%),1fr));gap:0 24px}\n.dsu-grid>.dsu-field{display:flex;flex-direction:column;align-items:stretch;gap:6px;padding:10px 0;border-top:.5px solid var(--dsw-alias-border-l1)}\n.dsu-grid>.dsu-field .dsu-control{width:100%}\n@media (max-width:640px){\n  .dsu-field{grid-template-columns:minmax(0,1fr);align-items:start}\n  .dsu-control{width:100%;max-width:720px}\n  .dsu-section{margin-top:20px;padding-top:20px}\n}\n@media (prefers-reduced-motion:reduce){\n  .dsu-switch,.dsu-knob,.dsu-chevron,.dsu-btn{transition:none}\n}\n";
+export declare const CARD_UI_CSS = "\n.dsu-form{display:flex;flex-direction:column}\n.dsu-section{margin-top:24px;padding-top:24px;border-top:.5px solid var(--dsw-alias-border-l1)}\n.dsu-form>.dsu-section:first-child{margin-top:0;padding-top:0;border-top:0}\n.dsu-sectionTitle{margin:0;font-size:15px;font-weight:600;line-height:1.4;color:var(--dsw-alias-label-primary)}\n.dsu-sectionHint{margin:4px 0 0;font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}\n.dsu-statusbar{display:flex;flex-wrap:wrap;gap:4px 8px;margin-top:8px;font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}\n.dsu-field{display:grid;grid-template-columns:minmax(0,1fr) minmax(240px,360px);column-gap:32px;align-items:center;padding:12px 0;border-top:.5px solid var(--dsw-alias-border-l2)}\n.dsu-fieldMeta{display:flex;flex-direction:column;gap:4px;min-width:0}\n.dsu-labelRow{display:flex;align-items:center;gap:6px;min-width:0}\n.dsu-label{font-size:13px;font-weight:500;line-height:1.5;color:var(--dsw-alias-label-primary)}\n.dsu-labelMono{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px}\n.dsu-hint{margin:0;font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}\n.dsu-control{min-width:0;display:flex;align-items:center;gap:8px}\n.dsu-fieldWide{grid-template-columns:minmax(0,1fr);align-items:start}\n.dsu-fieldWide .dsu-control{width:100%;max-width:720px;margin-top:2px}\n.dsu-help{display:inline-flex;align-items:center;gap:6px;min-width:0}\n.dsu-helpBtn{appearance:none;border:0;background:transparent;padding:0;width:16px;height:16px;display:inline-flex;align-items:center;justify-content:center;color:var(--dsw-alias-label-tertiary);cursor:help;border-radius:50%;flex:none}\n.dsu-help:hover .dsu-helpBtn,.dsu-helpBtn:focus-visible{color:var(--dsw-alias-label-primary)}\n.dsu-helpBtn:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:1px}\n.dsu-tip{position:fixed;z-index:60;box-sizing:border-box;max-width:min(340px,calc(100vw - 16px));max-height:calc(100vh - 16px);overflow:auto;overflow-wrap:anywhere;padding:10px 12px;border-radius:10px;background:var(--dsw-alias-bg-layer-2);border:.5px solid var(--dsw-alias-border-l3);box-shadow:0 12px 32px rgb(0 0 0 / 45%);font-size:12px;line-height:1.6;font-weight:400;color:var(--dsw-alias-label-secondary)}\n.dsu-input{width:100%;height:34px;padding:0 12px;border:.5px solid var(--dsw-alias-border-l4);border-radius:var(--dsw-radius-md);background:var(--dsw-alias-bg-layer-3);color:var(--dsw-alias-label-primary);font:inherit;font-size:13px}\n.dsu-input:focus-visible{outline:none;border-color:var(--dsw-alias-state-business-primary)}\n.dsu-input[aria-invalid=\"true\"]{border-color:var(--dsw-alias-state-error-primary)}\n.dsu-input:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}\n.dsu-input::placeholder{color:var(--dsw-alias-label-tertiary)}\n.dsu-textarea{height:auto;min-height:96px;padding:8px 12px;line-height:1.6;resize:vertical}\n.dsu-mono{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}\n.dsu-numberWrap{display:flex;flex-direction:column;gap:4px;width:100%;min-width:0}\n.dsu-number{display:flex;align-items:center;gap:8px;min-width:0}\n.dsu-number .dsu-input{min-width:0}\n.dsu-unit{flex:none;font-size:12px;color:var(--dsw-alias-label-tertiary)}\n.dsu-error{margin:0;font-size:12px;line-height:1.5;color:var(--dsw-alias-state-error-primary)}\n.dsu-switch{appearance:none;width:36px;height:20px;border-radius:999px;border:0;padding:2px;background:var(--dsw-alias-border-l3);display:flex;align-items:center;cursor:pointer;flex:none;transition:background-color .16s}\n.dsu-knob{width:16px;height:16px;border-radius:50%;background:var(--dsw-alias-label-primary);transition:transform .16s,background-color .16s}\n.dsu-switch[aria-checked=\"true\"]{background:var(--dsw-alias-label-primary)}\n.dsu-switch[aria-checked=\"true\"] .dsu-knob{transform:translateX(16px);background:var(--dsw-alias-label-primary-foreground)}\n.dsu-switch:disabled{opacity:.4;cursor:not-allowed}\n.dsu-switch:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:2px}\n.dsu-selectWrap{position:relative;width:100%;min-width:0}\n.dsu-select{display:flex;align-items:center;justify-content:space-between;gap:8px;text-align:left;cursor:pointer}\n.dsu-select[aria-expanded=\"true\"]{border-color:var(--dsw-alias-state-business-primary)}\n.dsu-selectValue{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}\n.dsu-chevron{flex:none;color:var(--dsw-alias-label-tertiary);transition:transform .16s}\n.dsu-select[aria-expanded=\"true\"] .dsu-chevron{transform:rotate(180deg)}\n.dsu-menu{position:fixed;position-area:block-end span-inline-start;justify-self:start;margin-top:6px;z-index:70;padding:4px;background:var(--dsw-alias-bg-layer-2);border:.5px solid var(--dsw-alias-border-l3);border-radius:12px;box-shadow:0 12px 32px rgb(0 0 0 / 50%);max-height:280px;overflow:auto}\n.dsu-option{appearance:none;border:0;background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:13px;line-height:1.4;width:100%;display:flex;align-items:center;justify-content:space-between;gap:12px;padding:8px 10px;border-radius:8px;cursor:pointer;text-align:left}\n.dsu-option:hover,.dsu-option[data-active=\"true\"]{background:var(--dsw-alias-bg-layer-3)}\n.dsu-option:disabled{color:var(--dsw-alias-label-tertiary);cursor:not-allowed}\n.dsu-option:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:-2px}\n.dsu-optionGroup{padding:6px 10px 2px;font-size:11px;font-weight:600;color:var(--dsw-alias-label-tertiary)}\n.dsu-check{opacity:0;flex:none}\n.dsu-option[aria-selected=\"true\"] .dsu-check{opacity:1}\n.dsu-savebar{display:flex;align-items:center;gap:8px;padding:12px 0;margin-top:24px;border-top:.5px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-base)}\n.dsu-savebar[data-dirty=\"true\"]{position:sticky;bottom:0;z-index:2;box-shadow:0 -12px 24px rgb(0 0 0 / 35%)}\n.dsu-btn{appearance:none;border:.5px solid var(--dsw-alias-border-l2);background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:13px;line-height:1.5;border-radius:var(--dsw-radius-md);padding:5px 14px;cursor:pointer;transition:background-color .12s,border-color .12s,color .12s,filter .12s}\n.dsu-btn:hover:not(:disabled){background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-border-l3)}\n.dsu-btn:active:not(:disabled){background:var(--dsw-alias-bg-layer-1)}\n.dsu-btn:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:1px}\n.dsu-btn:disabled{opacity:.4;cursor:not-allowed}\n.dsu-btnPrimary{background:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-3)}\n.dsu-btnPrimary:hover:not(:disabled){background:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-primary);filter:brightness(.9)}\n.dsu-btnPrimary:active:not(:disabled){background:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-primary);filter:brightness(.84)}\n.dsu-btnDanger{color:var(--dsw-alias-state-error-primary)}\n.dsu-btnDanger:hover:not(:disabled){color:var(--dsw-alias-state-error-primary);border-color:var(--dsw-alias-state-error-primary);background:var(--dsw-alias-bg-layer-2)}\n.dsu-status{margin-left:auto;font-size:12px;color:var(--dsw-alias-label-tertiary)}\n.dsu-statusError{color:var(--dsw-alias-state-error-primary)}\n.dsu-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(200px,100%),1fr));gap:0 24px}\n.dsu-grid>.dsu-field{display:flex;flex-direction:column;align-items:stretch;gap:6px;padding:10px 0;border-top:.5px solid var(--dsw-alias-border-l1)}\n.dsu-grid>.dsu-field .dsu-control{width:100%}\n@media (max-width:640px){\n  .dsu-field{grid-template-columns:minmax(0,1fr);align-items:start}\n  .dsu-control{width:100%;max-width:720px}\n  .dsu-section{margin-top:20px;padding-top:20px}\n}\n@media (prefers-reduced-motion:reduce){\n  .dsu-switch,.dsu-knob,.dsu-chevron,.dsu-btn{transition:none}\n}\n";

package/dist/types/config/oxlint.base.d.ts

@@ -41,7 +41,7 @@ export declare const OFF_JUSTIFICATIONS: Record<string, OffJustification>;
  * override 层的 off（这个测量方法见本文件头），所以一条规则可以同时是「TS 侧零命中、保持开启」
  * 与「`scripts/` 的无类型 .mjs 里有命中、按文体收窄」——`eslint/no-continue` 正是这一类，
  * 它的收窄在 SCRIPTS_OVERRIDES 里，不在这里。`eslint/no-await-in-loop` 则两侧都开着
- * （实测探针对 .mjs 照样报），两边都按代码写到位，没有收窄层。
+ * （实测探测对 .mjs 照样报），两边都按代码写到位，没有收窄层。
  */
 export declare const RETIRED_OFFS: string[];
 export declare const READONLY_SYNC_ALLOWLIST: string[];
@@ -88,7 +88,7 @@ export declare function resolveBundledJsPlugins(callerPlugins: NonNullable<Oxlin
 /**
  * `eslint-plugin-regexp` recommended 里带 `regexp/` 前缀的全部规则（63 条）。
  *
- * 不带它同 preset 的 4 条裸 eslint 规则（no-control-regex / no-misleading-character-class /
+ * 不带它同 preset 的 4 条不带插件前缀的 eslint 规则（no-control-regex / no-misleading-character-class /
  * no-regex-spaces / prefer-regex-literals）：oxlint 的内建 eslint 插件已有同名规则，重复挂只会
  * 把同一个缺陷报两遍。
  *
@@ -110,10 +110,10 @@ export declare const REGEXP_RULES: RuleTable;
  *  - `no-number-schema-with-int` 5 条（`z.number().int()` → `z.int()`，fixer 可修）。
  *  - `require-error-message` 5 条待按代码补错误文案。
  *  - `consistent-schema-var-name` 71 条**不挂**：本仓的 schema 常量是大写词（`MAX_DENIES_SCHEMA`、
- *    `STATS_SNAPSHOT_SCHEMA`），规则的默认口径是把 `Schema` 后缀再拼一次，得到
+ *    `STATS_SNAPSHOT_SCHEMA`），规则的默认做法是把 `Schema` 后缀再拼一次，得到
  *    `MAX_DENIES_SCHEMASchema` 这类坏名字；把它当命名缺陷改 71 处只是风格迁移，不指向缺陷。
  *
- * 该插件只对真的 import zod 的文件生效；本仓九个包都声明了 zod，规则面不会空转。
+ * 该插件只对真的 import zod 的文件生效；本仓九个包都声明了 zod，这些规则不会没有实际校验作用。
  */
 export declare const ZOD_RULES: RuleTable;
 /**
@@ -160,7 +160,7 @@ export declare const BASE_RULES: RuleTable;
  */
 export declare const TEST_OVERRIDES: OxlintOverride;
 /**
- * 生产代码面的 override：目前只有 `e18e/prefer-static-regex`。
+ * 针对生产代码的 override：目前只有 `e18e/prefer-static-regex`。
  *
  * 该规则在全仓 1778 条（生产 78、测试 1672、其余 28），没有 fixer；全局 off、这里 on，
  * 既保住「生产代码里的内联正则提到模块作用域」这条要求，又不把测试断言与构建脚本逼成

package/dist/types/config/vitest.base.d.ts

@@ -18,7 +18,7 @@ type CoverageOverride = Omit<Partial<CoverageConfig>, "include">;
 export interface PackageVitestOptions {
     /** `coverage.include` —— 本包该被统计的源文件（各包只有这里不同）；空数组/空串在工厂即抛。 */
     coverageInclude: string[];
-    /** 覆盖率覆盖项：逐键合并到公共面。要例外就在这里写，不要在 `test` 里塞 `coverage`。 */
+    /** 覆盖率覆盖项：逐键合并到公共配置。要例外就在这里写，不要在 `test` 里塞 `coverage`。 */
     coverage?: CoverageOverride;
     /** 追加/覆盖 test 字段（少用；出现即应在包内配置里写明为什么）。 */
     test?: PackageConfig["test"];

package/dist/types/decorator-lowering.d.ts

@@ -0,0 +1,45 @@
+/** 预转换的入参。 */
+export interface DecoratorLoweringOptions {
+    /** tsc 入口脚本的绝对路径（用 `process.execPath` 跑它，跨平台且不经 PATH / npx）。 */
+    readonly tscEntry: string;
+}
+/**
+ * 这个文件需要预转换吗（声明文件、后缀与装饰器形状三道筛）。
+ * @param id - 模块 id（可能带 query，调用方负责剥）
+ * @param code - 源文本
+ * @returns 需要预转换时为真
+ */
+export declare function needsDecoratorLowering(id: string, code: string): boolean;
+/** 源映射形状（`mappings` 是逐行映射那一串，可选）。 */
+interface SourceMapText {
+    sources?: string[];
+    sourcesContent?: string[];
+    mappings?: string;
+}
+/** tsc 产物与源映射（`map` 为 null 表示源映射缺席，不算致命）。 */
+export interface LoweredDecorators {
+    readonly code: string;
+    readonly map: SourceMapText | null;
+}
+/**
+ * 把一个带装饰器的 TS 文件编译成 JS。
+ * @param code - 源文本（只进源映射的 `sourcesContent`；编译交给 tsc 读盘上的原文）
+ * @param file - 源文件的**绝对路径**（tsc 按它定位产物名）
+ * @param options - tsc 入口
+ * @param coverageHints - 把注入的调用从源映射里摘掉（只有测试流水线要，见上）
+ * @returns 编译后的代码与源映射
+ */
+export declare function lowerStandardDecorators(code: string, file: string, options: DecoratorLoweringOptions, coverageHints?: boolean): LoweredDecorators;
+/** rolldown 插件：在它的解析器看到源码之前把标准装饰器编译掉。 */
+export declare function rolldownDecorators(options: DecoratorLoweringOptions): {
+    readonly name: string;
+    readonly transform: (code: string, id: string) => LoweredDecorators | null;
+};
+/** Vite 插件（测试流水线）：与上面同源，只是挂到 Vite 的钩子上（`enforce: "pre"` 保证在它前面）。
+ *  第三个实参 = 覆盖率提示：**只有测试流水线要**（构建产物的字节不该带它，见 pruneInjectedPlumbing）。 */
+export declare function viteDecorators(options: DecoratorLoweringOptions): {
+    readonly name: string;
+    readonly enforce: "pre";
+    readonly transform: (code: string, id: string) => LoweredDecorators | undefined;
+};
+export {};

package/dist/types/jsonl.d.ts

@@ -6,7 +6,7 @@
  *   - `0` 与负数**照样收缩**到 ≤2 行为止——「0 = 永不截断」是某消费方在**调用前**
  *     `maxBytes > 0` 那道触发策略的承诺，不是本函数的语义（见它自己的 jsonl-fuse 头注）。
  *     把 0 当成「不裁」会把这个承诺写成一个假象。
- *   - `NaN` 与 `+Infinity` 让 `字节数 > maxBytes` 恒假 ⇒ 循环一次都不进，整份原样返回，
+ *   - `NaN` 与 `+Infinity` 让 `字节数 > maxBytes` 永远不成立 ⇒ 循环一次都不进，整份原样返回，
  *     即**静默关掉收缩**。现存两个消费方都不会把这种值传进来：一个用固定常量作默认实参，
      另一个在调用前就把非有限值与负数归一成 0。但那道归一在**消费方**，本包并不强制——
      新增消费方时没有任何东西会提醒它。

package/dist/types/remote-marker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 把 {@link Remote} 的标记程序化地打到 `prototype[methodName]` 上。
+ *
+ * 官方 `Remote` 的运行时只读 `name` / `private` / `static` 与 `addInitializer`（TC39 的
+ * `access` 与 `metadata` 它一概不读），故这里只给这四位到底。初始器只做
+ * `Object.getPrototypeOf(this)` 后落标记，所以用原型造一枚替身实例即可。
+ *
+ * `Reflect.apply` 让装饰器工厂保持未类型化的调用签名 —— `Remote(name)` 的类型是
+ * `RemoteMethodDecorator`，它要求第二个参数是真 `ClassMethodDecoratorContext`，而这里喂的是
+ * 同形状的手写对象（平台类型不可构造）。
+ * @param prototype - 目标类原型（`X.prototype`）
+ * @param methodName - 要标记的实例方法名
+ */
+export declare function markRemote(prototype: object, methodName: string): void;

package/dist/types/tool-events.d.ts

@@ -11,11 +11,11 @@ export interface PtcDispatchStartEventData {
     name: string;
     arguments: unknown;
 }
-/** 一枚 PTC 子调度**结算**时记下的载荷：结算面沿用 `tool/result` 自己的词表。 */
+/** 一枚 PTC 子调度**结算**时记下的载荷：结算沿用 `tool/result` 自己的词表。 */
 export interface PtcDispatchEventData extends PtcDispatchStartEventData {
     isError: boolean;
     content: ContentBlock[];
-    /** 可重放的工具侧呈现元数据，与模型可见内容分开记账。 */
+    /** 可重放的工具侧呈现元数据，与模型可见内容分开记录。 */
     meta?: JsonValue;
     /** 可选的失败身份与原始用户可见细节，不在模型可见内容里。 */
     error?: {
@@ -48,7 +48,7 @@ export interface ToolCallRecord {
      * 只读判定、检查侧的 EDIT_TOOLS 与 refSearchTools 名单——而 editPathOf 的回退分支会把任何
      * 非 str_replace_editor 的调用一律判成 write。无名调用一旦进了记录，只要它的 arguments
      * 里有 file_path 就算成写操作。现在是靠三个消费方各自记得先判一次才没出事——那是同一条
-     * 不变式的三份手抄，漏一份就出事。
+     * 不变式的三份抄本，漏一份就出事。
      *
      * 与 callId 的差别是**为什么一个必选、一个可空**：callId 由 usableCallId 回退，且它有
      * `nc:<seq>` 回退值（消费方的 noCallId 组专门收那种行），缺了不影响归类；name 一旦缺了
@@ -117,7 +117,7 @@ export type EditTarget = {
 };
 /**
  * 一条 `apply_patch` 补丁操作的目标。`moveTo` 只出现在 update 上；源路径与目的路径
- * 都是文件效应，调用方需要分别记账。
+ * 都是文件效应，调用方需要分别记录。
  */
 export interface ApplyPatchTarget {
     readonly kind: "add" | "update" | "delete";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jayyuen66/dsh-plugin-shared",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "dsh 自研插件的共享工具库：tool 事件流记账扫描 + 卡片 apply/差异骨架 + 统一设置卡 UI 组件 + 官方作业结局映射 + 项目键派生 + 代理对安全截断。宿主半由各插件 import；客户端半以 ./client 共享行由插件 patch 启用，不由用户单独停用",
   "keywords": [
     "cordis",
@@ -92,6 +92,10 @@
       "types": "./dist/types/job-outcome.d.ts",
       "default": "./dist/job-outcome.js"
     },
+    "./lib/remote-marker": {
+      "types": "./dist/types/remote-marker.d.ts",
+      "default": "./dist/remote-marker.js"
+    },
     "./lib/canonicalize-region-paths": {
       "types": "./dist/types/canonicalize-region-paths.d.ts",
       "default": "./dist/canonicalize-region-paths.js"
@@ -112,6 +116,10 @@
       "types": "./dist/types/build-types.d.ts",
       "default": "./dist/build/build-types.js"
     },
+    "./lib/decorator-lowering": {
+      "types": "./dist/types/decorator-lowering.d.ts",
+      "default": "./dist/build/decorator-lowering.js"
+    },
     "./config/oxlint": {
       "types": "./dist/types/config/oxlint.base.d.ts",
       "default": "./dist/config/oxlint.base.js"
@@ -129,21 +137,23 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-fs-patch": "0.2.2-rc.1"
+    "@deepseek-ai/dsh-fs-patch": "0.2.2-rc.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.1.0",
-    "@deepseek-ai/dsh-brand": "0.2.2-rc.1",
-    "@deepseek-ai/dsh-client-locale": "0.2.2-rc.1",
-    "@deepseek-ai/dsh-jobs": "0.2.2-rc.1",
-    "@deepseek-ai/dsh-llm": "0.2.2-rc.1",
-    "@deepseek-ai/dsh-output-retention": "0.2.2-rc.1",
-    "@deepseek-ai/dsh-scope": "0.2.2-rc.1",
-    "@deepseek-ai/dsh-session": "0.2.2-rc.1",
-    "@deepseek-ai/dsh-shell": "0.2.2-rc.1",
-    "@deepseek-ai/dsh-tool-executor-ptc": "0.2.2-rc.1",
-    "@deepseek-ai/dsh-tools": "0.2.2-rc.1",
-    "@deepseek-ai/dsh-util-values": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-brand": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-error": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-jobs": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-output-retention": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-scope": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-shell": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-tool-executor-ptc": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.2.2-rc.2",
     "@e18e/eslint-plugin": "0.8.1",
     "@types/node": "26.6.6",
     "@types/react": "19.3.0",
@@ -154,25 +164,26 @@
     "eslint-plugin-zod": "5.2.2",
     "fast-check": "4.10.2",
     "happy-dom": "21.0.4",
-    "oxfmt": "0.76.0",
-    "oxlint": "1.91.0",
-    "oxlint-tsgolint": "7.0.2005",
+    "oxfmt": "0.78.0",
+    "oxlint": "1.93.0",
+    "oxlint-tsgolint": "7.0.2006",
     "react": "^19.3.0",
     "react-dom": "^19.3.1",
-    "rolldown": "1.2.16",
+    "rolldown": "1.3.2",
     "typescript": "7.0.2",
-    "vite": "8.3.6",
+    "vite": "8.3.8",
     "vitest": "5.1.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5||^4.0.6-alpha.1",
-    "@deepseek-ai/dsh": "^0.2.1-rc.5 || ^0.2.2-alpha.3",
-    "@deepseek-ai/dsh-client-locale": "^0.2.1-rc.5 || ^0.2.2-alpha.3",
-    "@deepseek-ai/dsh-jobs": "^0.2.1-rc.5 || ^0.2.2-alpha.3",
-    "@deepseek-ai/dsh-output-retention": "^0.2.1-rc.5 || ^0.2.2-alpha.3",
-    "@deepseek-ai/dsh-session": "^0.2.1-rc.5 || ^0.2.2-alpha.3",
-    "@deepseek-ai/dsh-shell": "^0.2.1-rc.5 || ^0.2.2-alpha.3",
-    "@deepseek-ai/dsh-tools": "^0.2.1-rc.5 || ^0.2.2-alpha.3",
+    "@deepseek-ai/dsh": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-jobs": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-output-retention": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-session": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-shell": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.2.2-rc.1",
     "react": "^19.3.0"
   },
   "peerDependenciesMeta": {
@@ -200,13 +211,16 @@
     "@deepseek-ai/dsh-tools": {
       "optional": true
     },
+    "@deepseek-ai/dsh-typert-protocol": {
+      "optional": true
+    },
     "react": {
       "optional": true
     }
   },
   "icon": "icon.svg",
   "engines": {
-    "dsh": "^0.2.1-rc.5 || ^0.2.2-alpha.3",
+    "dsh": "^0.2.2-rc.1",
     "node": ">=24.9.0"
   },
   "dsh": {