@t4r71/dsh-dual-axis-ui 0.1.0

package/lib/index.js

@@ -0,0 +1,13 @@
+//#region lib/types/index.js
+/**
+* 本包的宿主半边。这个包的实质内容全在浏览器半边，但 0.1.7 的客户端扫描只处理
+* 「有活动 Loader 行」的包：包名没有行，`dsh.client` 就不会被采集成客户端行，
+* 浏览器半边永远不会下发。这个空插件就是那一行的落点。
+* @module @t4r71/dsh-dual-axis-ui
+*/
+/** 插件名，loader 诊断用。 */
+const name = "dual-axis-ui";
+/** 不做任何事：两个界面面都由 ./client 那半边承担。 */
+async function apply() {}
+//#endregion
+export { apply as default, name };

package/lib/types/client/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 双轴访问模式组合包的浏览器半边：把这一条能力的两个界面面合成一个客户端插件。
+ *
+ * 为什么是一个插件而不是两个：0.1.7 的客户端模块系统里，客户端行 id 就是包名
+ * （client/modules/src/client/manifest.ts 的 WebBootEntry.id），`dsh.client` 是单个对象，
+ * `stripClientSuffix` 只剥掉结尾的 /client —— 一个 npm 包因此只能带一个客户端半边。
+ * 两个界面面（设置页那一行、输入框上方的两个下拉）于是共用这一次 apply。
+ *
+ * @module @t4r71/dsh-dual-axis/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+export declare const inject: string[];
+/**
+ * 挂载两个界面面：下拉那面先挂（它注册会话输入区的 slot 与词典），配置行那面随后。
+ * @param ctx - 浏览器插件上下文。
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/permission/PermissionCustomEditor.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 一条轴的 `custom` 路径编辑器：底座下拉加两个绝对路径列表。
+ *
+ * 这个编辑器是让 `custom` 成为一条完整策略语句的东西。另外三个取值本身各自就是
+ * 完整语句 —— 选中即提交 —— 而 `custom` 必须带底座，宿主的解析器宁可拒绝一条裸的
+ * `write:custom` 也不肯替用户猜一个。所以下拉里选中 `custom` 时不直接提交，而是展开
+ * 这个编辑器，由它提交完整的 `axis:custom:base=…,allow=…,deny=…` 参数。
+ *
+ * 两个路径框都是一行一条绝对路径。全局设置文档里存的是列表，而这个界面没有路径
+ * 选择器，所以文本是诚实的载体；一条相对路径会挡住提交并说明原因，而不是被解析到
+ * 某个用户从没指定过的目录上去。
+ *
+ * 提交要过一次风险确认：`base=all` 或带额外放行路径的 `custom` 都会放大该轴的
+ * 访问范围，所以「应用」先落到确认框，只有勾选并确认才真的写下去。不放大权限的
+ * 草稿（例如在 `workspace` 底座上只加排除路径）不过闸，免得确认变成噪音。
+ *
+ * @module @deepseek-ai/dsh-client-ui-permission-presets/client/PermissionCustomEditor
+ */
+import type { ReactNode } from 'react';
+import type { NarrowingNotice, PermissionAxis } from './presentation.ts';
+import type { PermissionSelectProps } from './PermissionSelect.tsx';
+import { type AxisEditorScope, type AxisEditorValue, type RuleGroupOption } from './axis-editor.ts';
+export type { AxisEditorValue } from './axis-editor.ts';
+/** 一条轴的路径编辑器的 props。 */
+export interface PermissionCustomEditorProps {
+    /** 这条编辑器写哪条轴；两个下拉没有可见标题，所以文案自己说明轴名。 */
+    axis: PermissionAxis;
+    /** 该轴在当前会话里的取值，编辑器以它为初值；会话还没有这条轴时为 undefined。 */
+    current: AxisEditorValue | undefined;
+    /** 该轴在部署设置里的取值；会话没有这条轴（{@link current} 缺席）时用它。 */
+    global: AxisEditorValue | undefined;
+    /**
+     * 写轴被读轴收窄的结论，由宿主解算后发布（见 {@link NarrowingNotice}）。
+     * 只有写轴有：不变量讲的就是写范围。undefined 表示这条会话当刻没有被收窄。
+     */
+    notice: NarrowingNotice | undefined;
+    /** 设置页当前定义的规则组；编辑器在渲染时调它，取的就是当刻那一份。 */
+    groups: () => readonly RuleGroupOption[];
+    /** 输入框是否被锁住（只读会话，或没有活绑定）。 */
+    locked: boolean;
+    /** 该轴是否已有一次提交在飞。 */
+    busy: boolean;
+    /**
+     * 提交完整的轴参数；宿主结清**并且文档里真的出现这条取值**之后兑现。
+     *
+     * 第二个参数是这份草稿落成记录之后的形状（{@link draftScope}）。它不是给宿主看的
+     * —— 宿主只收那一个参数串 —— 而是给提交路径核对用的：宿主对自己没写的改动也会回
+     * 「命令执行了」，只有拿写入后的记录比对才能分辨「写进去了」与「被拒了没写」。
+     */
+    onSubmit: (args: string, expected: AxisEditorScope) => Promise<boolean>;
+    /** 不提交就关掉编辑器。 */
+    onDismiss: () => void;
+    t: PermissionSelectProps['t'];
+}
+/**
+ * 渲染一条轴的 `custom` 路径编辑器。
+ *
+ * 草稿从会话当前值起步，**任何取值都算**：这条会话的轴是这个界面表达的对象，
+ * 编辑器打开时显示别的值（例如部署默认）就会与它旁边那个下拉自相矛盾。只有
+ * 会话值缺席时才退到该轴的部署默认值。一次失败的提交保留草稿并显示一句可读的话，
+ * 而不是抛出去，所以被拒的审批留下的是一个还能用的编辑器。
+ * @param props - 轴、起始值、写入口与词典座位。
+ * @returns 底座下拉、两个路径框与提交行。
+ */
+export declare function PermissionCustomEditor({ axis, current, global, notice, groups, locked, busy, onSubmit, onDismiss, t, }: PermissionCustomEditorProps): ReactNode;

package/lib/types/client/permission/PermissionRow.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Permission preference row: the default preset for subsequently created
+ * sessions. Current-session switches remain on the composer's read/write
+ * axis dropdowns.
+ */
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { PermissionSettingsState } from './settings-store.ts';
+import type { PermissionSettingsKey } from './locales.ts';
+/** Registration-side business face for the host-backed preference. */
+export interface PermissionRowInjected {
+    hooks: {
+        /** Permission settings snapshot bound by the renderer as usePermission. */
+        permission: SnapshotStore<PermissionSettingsState>;
+    };
+    /** Load the descriptor when the row first renders. */
+    load: () => Promise<void>;
+    /** Persist one advertised preset. */
+    select: (preset: string) => Promise<void>;
+}
+/** Full component props. */
+export type PermissionRowProps = PropsRuntime<'settings.general.item'> & PropsLocale<'settings.permission'> & InjectFace<PermissionRowInjected>;
+/**
+ * Render the new-session Permission default selector. The row keeps the host's
+ * single preset enum on purpose: its options come from the Host settings
+ * schema (which still publishes one bundled preset per mode), not from the
+ * current-session two-axis catalog, so splitting it here would invent a second
+ * source of truth for the same durable value. A visible pick applies directly —
+ * the full-access acknowledgement step was removed with the composer's.
+ * @param props - composed slot props.
+ * @returns the row, or null when the host does not expose permission settings.
+ */
+export declare function PermissionRow({ load, select, usePermission, t }: PermissionRowProps): import("react").JSX.Element | null;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Permission row copy. */
+        'settings.permission': PermissionSettingsKey;
+    }
+}

package/lib/types/client/permission/PermissionSelect.d.ts

@@ -0,0 +1,89 @@
+import type { HostObservable, InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { PermissionAxis } from './presentation.ts';
+import type { PermissionCatalogState } from './catalog.ts';
+import { PERMISSION_ACCESS_NS } from './locales.ts';
+import type { DualAxisAxisWire } from './presentation.ts';
+import type { SessionAxesView } from './session-axes-data.ts';
+import { type RuleGroupOption } from './axis-editor.ts';
+import { type AxisEditorValue } from './PermissionCustomEditor.tsx';
+/** Business face injected by the permission package's slot registration. */
+export interface PermissionSelectInjected {
+    hooks: {
+        /** One process catalog shared with the slash popup (axis values + defaults). */
+        permissionCatalog: HostObservable<PermissionCatalogState>;
+    };
+    /**
+     * Submit one axis switch for the current session. Each dropdown writes only
+     * its own axis. The three closed values are complete statements and go
+     * straight through; `custom` is not one — it is assembled by the path editor,
+     * which is why this surface never sends a bare `<axis>:custom`.
+     *
+     * `expected` is the value the submission MEANS, and it is what makes a refused
+     * write visible: the host's `Session.command` answers whether the line resolved
+     * to a registered command, not whether that command succeeded
+     * (`packages/api/session-controller/src/client/sessions/session.ts:387-391` —
+     * `matched: result.value !== undefined`), so a `/axis` entry the host refuses
+     * settles as a perfectly ordinary admission. The implementation therefore reads
+     * the stored pair back out of the settings document and answers `false` when it
+     * never becomes `expected`.
+     * @param axis - which axis the entry writes.
+     * @param args - the complete entry string after the command name.
+     * @param expected - the axis value this entry is meant to store.
+     * @returns whether the stored pair now carries `expected` on `axis`.
+     */
+    select: (axis: PermissionAxis, args: string, expected: DualAxisAxisWire) => Promise<boolean>;
+    /**
+     * The deployment default for one axis, read from the dual-axis settings
+     * section — the pair a NEW session starts from. Only a conversation that has
+     * no value of its own for that axis opens the editor on it; a live session's
+     * own axes are what the editor opens on. Undefined when the deployment serves
+     * no such section or keeps preferences process-local; the editor's own
+     * deployment fallback (read `all`, write `workspace`) covers that case
+     * without an error and without widening the write axis.
+     * @param axis - which axis's deployment default to read.
+     * @returns the deployment value, or undefined when there is none.
+     */
+    global: (axis: PermissionAxis) => PermissionAxisEditorSource | undefined;
+    /**
+     * 设置页当前定义的规则组，编辑器多选列表的来源。
+     *
+     * 与 {@link global} 不同的是这里每次都取**当刻**的库：编辑器只把库读成一份勾选
+     * 列表，用户勾了什么存在它自己的草稿里，所以设置页新增或改名一个组只是多出/改掉
+     * 一行，不会替掉已经勾好的清单。
+     * @returns 每个可用的组一项；设置页没有定义任何组时是空列表。
+     */
+    groupLibrary: () => readonly RuleGroupOption[];
+    /**
+     * 这条会话当刻的那一对轴，从配置文档镜像里按会话 id 读。
+     *
+     * 与 {@link groupLibrary} 同一条读路径（共享的 describe 镜像），但它是**订阅式**的：
+     * 宿主改完轴会发 `settings/document-updated`，镜像重读，组件跟着重渲染。
+     */
+    sessionAxes: SessionAxesInjected;
+}
+/** 会话轴取值面：一个订阅式 hook 加一个同步取值函数。 */
+export interface SessionAxesInjected {
+    /**
+    * React hook：当前会话该显示的那一对轴，以及那份取值的来源。
+    *
+    * 返回的永远是三态。没有记录时**不是** undefined 而是 `{ state: 'default' }`：
+    * 那种情形下宿主执行的正是这条会话的**种子**（设置页那一行，子代理子会话则是父会话
+    * 当刻的记录），界面按同一份计算显示同一个值 —— 显示内置默认对就会「界面显示 A、
+    * 宿主执行 B」，设置页默认是「禁止读」时那一轮仍会被当成「全盘读」。只有连文档都读
+    * 不到时才是 `{ state: 'unknown' }`，由两个下拉如实显示「未设置」。
+    * @param sessionId - 当前会话 id。
+    * @returns 三态取值。
+    */
+    useAxes: (sessionId: string | undefined) => SessionAxesView;
+    /**
+    * 同一个值的同步读取，供非 React 调用方（编辑器初值、提交后的核对）使用。
+    * @param sessionId - 当前会话 id。
+    * @returns 三态取值。
+    */
+    axesOf: (sessionId: string | undefined) => SessionAxesView;
+}
+/** One axis's value as the editor reads it: the kind plus the custom detail. */
+export type PermissionAxisEditorSource = AxisEditorValue;
+/** Complete props derived from the conversation slot, injected hooks, and locale. */
+export type PermissionSelectProps = PropsRuntime<'conversation.input.permission'> & InjectFace<PermissionSelectInjected> & PropsLocale<typeof PERMISSION_ACCESS_NS>;
+export declare function PermissionSelect({ locked, select, global, groupLibrary, sessionAxes, usePermissionCatalog, t, sessionId, }: PermissionSelectProps): import("react").JSX.Element | null;

package/lib/types/client/permission/axis-editor.d.ts

@@ -0,0 +1,263 @@
+/**
+ * 输入框上方两个访问轴下拉的 `custom` 路径编辑器：把一条轴收成可编辑的草稿、
+ * 把草稿收成宿主 `/permission` 命令接受的参数串，并给出全局初值与兜底默认值。
+ *
+ * 这里不碰 React、不碰 DOM、也不碰宿主 —— 界面半边每次展开编辑器与每次提交都走
+ * 这几个函数，因此"界面上能编的形状"与"宿主解析器接受的形状"只有这一份定义。
+ * 宿主的语法在 `dsh-dual-axis` 的 `parseAxisEntry` / `parseCustomFragment`：
+ * `<axis>:<kind>[:base=<deny|workspace|all>,groups=<id>|<id>,allow=<绝对路径>,deny=<绝对路径>]`，
+ * `allow` / `deny` 重复 key 表示多条、逗号分隔，路径必须是绝对路径；`groups` 只写
+ * **组 id**，组体由宿主在判定时按 id 现取。
+ *
+ * @module @deepseek-ai/dsh-client-ui-permission-presets/client/axis-editor
+ */
+import type { PermissionAxis, PermissionAxisValue } from './presentation.ts';
+/** `custom` 可叠加的三个底座，与宿主 `AxisBase` 同一套字面量。 */
+export declare const AXIS_BASES: readonly ["deny", "workspace", "all"];
+/** 一个底座取值。 */
+export type AxisBase = typeof AXIS_BASES[number];
+/**
+ * 一条轴在编辑器里的草稿。四个取值共用同一种形状：切到 `custom` 再切回来时，
+ * 已经打好的路径不会丢，只是不再参与提交。
+ */
+export interface AxisDraft {
+    /** 当前选中的轴取值。 */
+    kind: PermissionAxisValue;
+    /** `custom` 的底座；非 `custom` 时保留上一次的选择。 */
+    base: AxisBase;
+    /**
+     * 这条对话预设里引用的规则组 id。
+     *
+     * 存的是 **id 而不是组体**：组的内容永远只有设置页那一份，判定时按 id 现取
+     * （规格 §「为什么对话里绝不能存组体」）。顺序即提交顺序。
+     */
+    groups: readonly string[];
+    /** 额外放行的绝对路径，每行一条。 */
+    allow: string;
+    /** 额外禁止的绝对路径，每行一条；与底座取并后再减去它们，禁止优先。 */
+    deny: string;
+}
+/**
+ * 设置页定义的一个规则组，编辑器多选用的那一份。
+ *
+ * `read` / `write` 是这个组覆盖了哪几根轴：写侧组出现在读轴的选择器里不会报错，
+ * 但它对这条读轴什么也不做，所以界面要如实标出来。
+ */
+export interface RuleGroupOption {
+    /** 会话引用的稳定标识。 */
+    readonly id: string;
+    /** 人读的名字；设置页留空时宿主用 id 顶上。 */
+    readonly name: string;
+    /** 这个组是否带读侧规则。 */
+    readonly read: boolean;
+    /** 这个组是否带写侧规则。 */
+    readonly write: boolean;
+}
+/** 多选列表里的一行：设置页定义的组，或一个已经引用不到定义的 id。 */
+export interface GroupChoice {
+    /** 组 id。 */
+    readonly id: string;
+    /** 显示名；引用不到的 id 用 id 本身。 */
+    readonly name: string;
+    /** 这个组覆盖哪些轴；引用不到的 id 是 `none`。 */
+    readonly coverage: 'both' | 'read' | 'write' | 'none';
+    /** 设置页当前是否定义了这个 id。 */
+    readonly missing: boolean;
+    /** 这一行是否被勾选。 */
+    readonly checked: boolean;
+}
+/**
+ * 把设置节的 `groups` 读成多选用的组清单。
+ *
+ * 读取是宽容的：读不懂的成员跳过，不抛 —— 这个清单只是给人选的东西，坏取值由宿主
+ * 的 `parseLibrary` 在判定时响亮失败，界面不该因为一个坏成员就整块打不开。
+ * @param value - 设置节里的 `groups`，未信任。
+ * @returns 每个可用的组一项，顺序与文档一致，id 去重。
+ */
+export declare function groupOptionsOf(value: unknown): readonly RuleGroupOption[];
+/**
+ * 多选列表的完整内容：设置页定义的组，加上这条对话已经引用、但设置页不再定义的 id。
+ *
+ * 后一类必须留在列表里并保持勾选：它们缺席就等于「打开编辑器再应用」会**静默**把
+ * 引用删掉，而宿主正是靠这些引用响亮失败的（规格 §「引用不到的组 id → 响亮失败」）。
+ * 取消勾选仍然允许 —— 移除一个引用属于收窄，永远允许。
+ * @param library - 设置页当前定义的组。
+ * @param selected - 这条对话预设里引用的 id。
+ * @returns 列表的每一行。
+ */
+export declare function groupChoicesOf(library: readonly RuleGroupOption[], selected: readonly string[]): readonly GroupChoice[];
+/**
+ * 编辑器里一条轴的起始取值：会话当前值，或部署设置值。
+ *
+ * 两条都是**未信任输入**：会话那条来自宿主投影，部署那条来自设置文档。读不懂的
+ * 成员由 {@link initialDraft} 逐项兜底，界面不会因为一个坏取值打不开。
+ */
+export interface AxisEditorValue {
+    /** 轴取值。 */
+    kind: string;
+    /** `custom` 时的底座。 */
+    base?: string;
+    /** `custom` 时这条预设引用的规则组 id。 */
+    groups?: readonly string[];
+    /** `custom` 时额外放行的绝对路径。 */
+    allow?: readonly string[];
+    /** `custom` 时额外禁止的绝对路径。 */
+    deny?: readonly string[];
+}
+/**
+ * 某一轴拿不到任何配置时使用的兜底轴：读轴 `all`、写轴 `workspace`，
+ * 即 `dsh-sandbox` 的 `DEFAULT_READ_SCOPE` / `DEFAULT_WRITE_SCOPE`。
+ *
+ * 这两条是**部署默认值**，不是"兜底给全盘权限"：读轴 `all`、写轴 `workspace`
+ * 正是 `dsh-sandbox` 里那两条默认轴，所以拿不到全局配置时也不会把写权限放大。
+ * @param axis - 轴名。
+ * @returns 该轴的兜底取值。
+ */
+export declare function fallbackAxis(axis: PermissionAxis): Exclude<PermissionAxisValue, 'custom'>;
+/**
+ * 一条空白草稿：以给定取值起步，并以该取值本身为底座。
+ *
+ * 底座取"这条轴当前的取值"而不是写死的 `workspace`：拿不到任何全局配置时，读轴的
+ * 兜底是 `all`，于是编辑器的底座也必须是 `all` —— 若写死 `workspace`，兜底打开的
+ * 编辑器会静默把读轴收窄成会话工作区，与那条兜底值本身矛盾。
+ * @param kind - 起步取值，同时用作底座。
+ * @returns 一份可编辑的草稿。
+ */
+export declare function emptyDraft(kind: PermissionAxisValue): AxisDraft;
+/** 一条 `groups` 项里分隔组 id 的字符；与宿主 `GROUP_ID_SEPARATOR` 同一个字符。 */
+export declare const GROUP_ID_SEPARATOR = "|";
+/**
+ * 一条轴的起始草稿：**这条会话自己的轴**优先，它缺席时才退到部署设置值，再没有
+ * 才用该轴的部署默认值。它永远不会空着打开，也永远不抛 —— 兜底就是这个函数的
+ * 全部意义。
+ *
+ * 「会话优先」不是顺序偏好而是这个界面的定义：编辑器表达的就是这条会话，打开时
+ * 显示别的值会与它旁边那个下拉自相矛盾。会话读轴是 `deny` 时初值必须是 `deny`，
+ * 不是部署默认的 `all`。
+ * @param axis - 正在编辑的轴。
+ * @param current - 这条会话在该轴上的取值，宿主投影还没有这条轴时为 undefined。
+ * @param global - 部署设置在该轴上的取值，只在会话没有取值时兜底。
+ * @returns 一份不用重打任何东西就能提交的草稿。
+ */
+export declare function initialDraft(axis: PermissionAxis, current: AxisEditorValue | undefined, global: AxisEditorValue | undefined): AxisDraft;
+/**
+ * 一个写法是否为绝对路径。相对路径只能相对宿主进程的 cwd 解析，永远不是写这份配置
+ * 的人想说的位置，所以与宿主一样在这里就拒绝，而不是留给宿主报一句难读的错。
+ * @param value - 待检查的路径写法。
+ * @returns 该写法是否为绝对路径。
+ */
+export declare function isAbsolutePath(value: string): boolean;
+/**
+ * 把一个多行文本框读成路径列表：去掉空行与首尾空白。
+ * @param text - 文本框里的原文。
+ * @returns 其中每一行作为一条路径。
+ */
+export declare function pathLines(text: string): string[];
+/** 一份草稿收成参数串的结果：成功给出片段，失败给出一句可读的说明。 */
+export type DraftParse = {
+    ok: true;
+    fragment: string;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * 把一份 `custom` 草稿收成宿主解析器接受的参数片段
+ * （`base=<…>,groups=<id>|<id>,allow=<…>,deny=<…>`，`allow` / `deny` 每条重复一次 key）。
+ *
+ * 路径里的逗号、以及组 id 里的三类分隔符都会被宿主的解析器当成别的东西，因此它们
+ * 在这里就拒绝，而不是拼出一条宿主读成另一个意思的命令行。
+ * @param draft - 编辑器里的草稿。
+ * @param problemOf - 生成本地化说明的回调。
+ * @returns 参数片段，或一句说明这份草稿为什么还不能提交的话。
+ */
+export declare function customFragment(draft: AxisDraft, problemOf: (key: 'baseUnknown' | 'notAbsolute' | 'commaUnsupported' | 'groupUnsupported') => string): DraftParse;
+/**
+ * 一份 `custom` 草稿提交出去之后，宿主文档里应当出现的那条轴值。
+ *
+ * 与 {@link customFragment} 同一份草稿、同一套取值：片段是发给宿主的那句话，这里是
+ * 那句话落成记录之后的形状。两者一起用才有意义 —— 宿主对自己没写的改动同样会回一句
+ * 「命令执行了」（`Session.command` 的 `matched` 只说明命令被解析到，见
+ * `packages/api/session-controller/src/client/sessions/session.ts:387-391`），所以界面
+ * 只能拿写入之后的记录来核对这次提交到底有没有生效。
+ *
+ * 组 id 去重，因为宿主 `normalizeScope` 的 `groupIds` 也去重；路径列表保持顺序，
+ * 因为宿主的 `pathList` 保序。
+ * @param draft - 编辑器里的草稿。
+ * @returns 宿主文档里那条轴的形状。
+ */
+export declare function draftScope(draft: AxisDraft): AxisEditorScope;
+/**
+ * 宿主文档里一条轴值的形状（`dual-axis-sessions` 的记录成员）。
+ *
+ * 只有这里真的会读的成员：`groups` 是这条轴引用的组 id，`allow` / `deny` 是它自己
+ * 追加与排除的绝对路径。
+ */
+export interface AxisEditorScope {
+    /** 轴取值。 */
+    readonly kind: string;
+    /** `custom` 的底座。 */
+    readonly base?: string;
+    /** `custom` 引用的规则组 id。 */
+    readonly groups?: readonly string[];
+    /** `custom` 额外放行的绝对路径。 */
+    readonly allow?: readonly string[];
+    /** `custom` 额外排除的绝对路径。 */
+    readonly deny?: readonly string[];
+}
+/**
+ * 两条轴值是不是同一件事 —— 按值比，不按引用比。
+ *
+ * 比较的是宿主写进文档之后的那份形状：`groups` / `allow` / `deny` 只有一条轴真的是
+ * `custom` 时才参与比较（`deny` / `workspace` / `all` 都不带这些成员），列表按顺序比，
+ * 因为顺序是取值的一部分（提交顺序就是用户勾选的顺序）。
+ * @param left - 一条轴值。
+ * @param right - 另一条轴值。
+ * @returns 两者是否描述同一条轴。
+ */
+export declare function sameStoredAxis(left: AxisEditorScope | undefined, right: AxisEditorScope | undefined): boolean;
+/**
+ * 把一个 `custom` 取值收成编辑器草稿（当前值显示用）。
+ * @param axis - 该取值所属的轴。
+ * @param value - 轴值，可能是 `custom` 并带底座与两个列表。
+ * @returns 一份可编辑的草稿。
+ */
+export declare function draftOfAxisState(axis: PermissionAxis, value: {
+    kind: PermissionAxisValue;
+    base?: string;
+    groups?: readonly string[];
+    allow?: readonly string[];
+    deny?: readonly string[];
+}): AxisDraft;
+/**
+ * 一条轴取值是否会**放开**权限：只有 `all`（整台主机）与带额外放行路径的 `custom`
+ * 会，`deny` / `workspace` 和空清单的 `custom` 不会。
+ *
+ * 这个判定就是发布版二次确认闸的开关。它按**取值本身**算，不按界面动作算：同一条
+ * `write:all`，无论从下拉选出还是从编辑器拼出，都要过一次同样的确认。
+ * @param value - 轴取值。
+ * @returns 该取值是否会放大访问范围。
+ */
+export declare function widensAccess(value: PermissionAxisValue): boolean;
+/**
+ * 一条 `custom` 提交片段是否会放开权限：底座是 `all`，或带了任何额外放行路径。
+ * 排除清单不收窄判定 —— `base=all,deny=/x` 仍然是整台主机减去一条路径。
+ * @param fragment - `customFragment` 产出的片段。
+ * @returns 该片段是否会放大访问范围。
+ */
+export declare function fragmentWidensAccess(fragment: string): boolean;
+/**
+ * 把一条轴值读成一行摘要（当前值显示用），例如 `自定义：基于 工作区，+3 −1`。
+ * @param value - 轴值。
+ * @param text - 文案表。
+ * @returns 一行说明。
+ */
+export declare function axisSummary(value: {
+    kind: PermissionAxisValue;
+    base?: string;
+    allow?: readonly string[];
+    deny?: readonly string[];
+}, text: {
+    custom: (base: string, allow: number, deny: number) => string;
+    base: (base: string) => string;
+}): string | undefined;

package/lib/types/client/permission/catalog.d.ts

@@ -0,0 +1,62 @@
+/** Identity-stable process permission catalog shared by both selection surfaces. */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { PermissionCatalog } from '@deepseek-ai/dsh-permission-presets/client';
+/** Observable complete catalog for the current Host generation. */
+export interface PermissionCatalogState {
+    /** Last complete catalog for this generation, or null before one succeeds. */
+    value: PermissionCatalog | null;
+}
+/** One latest-result-wins catalog reader for the whole browser process. */
+export declare class PermissionCatalogDirectory {
+    private readonly ctx;
+    /** Complete snapshot consumed by both the slash popup and composer seat. */
+    readonly store: SnapshotStore<PermissionCatalogState>;
+    /**
+     * One tick per invalidation (a catalog notification or a connection-generation
+     * change), published before the replacement read starts. Consumers that must
+     * drop displayed options subscribe here instead of to {@link store}, whose
+     * publications also settle a read a displayed surface is waiting for.
+     */
+    readonly invalidations: SnapshotStore<{
+        count: number;
+    }>;
+    private readonly connection;
+    private readonly stopCatalog;
+    private readonly stopGeneration;
+    private generationId;
+    private initialized;
+    private epoch;
+    private pending;
+    private failure;
+    private disposed;
+    /**
+     * Subscribe to both invalidation sources before the first read, closing the
+     * install/read race.
+     * @param ctx - root Client context carrying Remote and Connection.
+     */
+    constructor(ctx: ClientContext);
+    /**
+     * Publish one invalidation tick for consumers holding displayed options.
+     * Neither caller can run after disposal: `dispose()` unsubscribes the
+     * catalog-changed listener, and `syncGeneration()` returns early when the
+     * directory is disposed.
+     */
+    private invalidate;
+    /** Force a fresh complete read for the active connection generation. */
+    refresh(): void;
+    /**
+     * Resolve a complete current-generation catalog for an imperative popup
+     * open. An active refresh settles before a retained value can be reused.
+     * @returns The active Host generation's complete permission catalog.
+     */
+    load(): Promise<PermissionCatalog>;
+    /** Stop subscriptions and revoke every late settlement's write access. */
+    dispose(): void;
+    /** Observe generation loss/replacement and hard-clear the old Host value. */
+    private syncGeneration;
+    /** Start one independent read; the newest epoch in the same generation wins. */
+    private startRead;
+    /** Fence by disposal, refresh epoch, and the actual Connection generation. */
+    private accepts;
+}

package/lib/types/client/permission/index.d.ts

@@ -0,0 +1,54 @@
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { accessEn } from './locales.ts';
+export type { AxisLabelKey, PermissionPresetLabelKey } from './presentation.ts';
+export type { PermissionRowInjected, PermissionRowProps } from './PermissionRow.tsx';
+export type { PermissionCatalogState } from './catalog.ts';
+export type { PermissionSelectInjected, PermissionSelectProps, PermissionAxisEditorSource, } from './PermissionSelect.tsx';
+export type { PermissionDefaultOption, PermissionSettingsState, } from './settings-store.ts';
+/**
+ * 双轴组合包在宿主上注册的设置节名（`@t4r71/dsh-dual-axis`）。
+ *
+ * 0.1.7 的设置命名空间就是 Loader entry id（`packages/settings/settings/src/index.ts`
+ * 的 `describe()` 按已装载 entry 投影），而宿主那一行在 `cordis.patch.yml` 里就叫
+ * `dual-axis`（`packages/bundle/dual-axis/src/config.ts` 的 `DUAL_AXIS_ROW_ID`）。
+ * 0.1.6 的 `sandbox-axis` 已经退役：写它取不到任何值，于是这张表单永远返回
+ * undefined，编辑器的部署兜底静默退化成编译期默认。
+ *
+ * 这一节持有「新会话从哪两条轴开始」。两个下拉的路径编辑器只在**会话还没有这条轴**
+ * 时以它为初值；对话级的选择永远优先。
+ */
+export declare const DUAL_AXIS_SETTINGS_NAMESPACE = "dual-axis";
+/** 提交之后最多等多久，等这次取值出现在设置文档里。 */
+export declare const AXIS_CONFIRM_TIMEOUT_MS = 3000;
+/** 上面那段等待的轮询间隔。 */
+export declare const AXIS_CONFIRM_POLL_MS = 100;
+/**
+ * 双轴设置节的取值形状。两条轴都当作未信任输入读：文档可能被人手改过，也可能由
+ * 别的写入方改过，所以这里只声明"是个对象"，真正的收窄在
+ * {@link PermissionSelect} 的 `globalOf` 里按 `kind` 判定；读不懂就当作没有部署值，
+ * 由编辑器用该轴的部署默认值兜底。
+ */
+export interface DualAxisSection {
+    /** 新会话起步的读轴。 */
+    read?: unknown;
+    /** 新会话起步的写轴。 */
+    write?: unknown;
+    /** 组库：会话按 id 引用的具名规则片段。多选列表只读它。 */
+    groups?: unknown;
+    /** 新会话默认加载哪些组；判定路径不读它，界面这边也不读。 */
+    defaultGroups?: unknown;
+}
+/** Required services (cordis fiber inject). */
+export declare const inject: string[];
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Current-session preset picker and read/write axis copy. */
+        'permission.access': keyof typeof accessEn;
+    }
+}
+/**
+ * Client plugin body: register the /permission popup picker over the
+ * permissions projection.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;