@xiongtao.xt/tau-plugins 0.0.0-stage → 0.2.0

package/types/packages/markdown/src/markdown.d.ts

@@ -0,0 +1,35 @@
+import type { Descendant } from "slate";
+import type { MarkdownTextRegistry } from "./textCodec";
+import { PositionMapper } from "./positionMapper";
+import type { CustomDirectiveHandler, MarkdownCodec } from "./codec";
+export interface SlateWithPositions {
+    content: Descendant[];
+    positionMap: PositionMapper;
+}
+export interface ImportFromMarkdownOptions {
+    /** 宿主注册的业务 directive（container / leaf / text 三种都查），优先于内置分支 */
+    customDirectives?: Record<string, CustomDirectiveHandler>;
+}
+/** 处理器级配置：宿主 codec 合并后的结果（框架不自带任何元素类型） */
+export interface ImportConfig {
+    textRegistry: MarkdownTextRegistry;
+    directives: Record<string, CustomDirectiveHandler>;
+    voidTypes: ReadonlySet<string>;
+    inlineWrapperDirectives: ReadonlySet<string>;
+    inlineHtmlWrappers?: ReadonlyMap<string, NonNullable<MarkdownCodec["inlineHtmlWrapper"]>>;
+    fenceByLanguage: ReadonlyMap<string, {
+        type: string;
+        property: string;
+    }>;
+    importNodes?: readonly NonNullable<MarkdownCodec["importNode"]>[];
+    fenceSourceProperties?: ReadonlyMap<string, string>;
+    normalizeHooks?: ReadonlyMap<string, NonNullable<MarkdownCodec["normalize"]>>;
+    inlineForms?: ReadonlyMap<string, NonNullable<MarkdownCodec["inlineForm"]>>;
+}
+/**
+ * Markdown 导入（带位置映射）
+ */
+export declare const importFromMarkdownWithPositionsUsing: (config: ImportConfig, markdown: string, ignoreTypes?: string[], options?: ImportFromMarkdownOptions) => SlateWithPositions;
+export declare const importFromMarkdownUsing: (config: ImportConfig, markdown: string, ignoreTypes?: string[], options?: ImportFromMarkdownOptions) => Descendant[];
+/** 粗判一段纯文本是否像 Markdown（粘贴时决定要不要按 Markdown 导入） */
+export declare const isMarkdownLikeText: (text: string) => boolean;

package/types/packages/markdown/src/markdownSerializerRegistry.d.ts

@@ -0,0 +1,47 @@
+import type { CustomElement } from "./types";
+export interface SerializerOutput {
+    output: string;
+    childrenStart?: {
+        line: number;
+        ch: number;
+    };
+    perLineOffset?: number;
+    childLineShifts?: Array<{
+        startIndex: number;
+        lineDelta: number;
+    }>;
+    skipChildren?: boolean;
+    propertyMappings?: {
+        [propName: string]: {
+            start: {
+                line: number;
+                ch: number;
+            };
+            multiline: boolean;
+        };
+    };
+}
+export interface MarkdownSerializer {
+    type: string;
+    isBlock?: boolean;
+    toMarkdown: (element: any, childrenStr: string, parentElement?: any) => string;
+    toMarkdownStructured?: (element: any, childrenStr: string, parentElement?: any) => SerializerOutput;
+}
+/**
+ * 导出端序列化器注册表：元素类型 → Markdown 文本的唯一出处。
+ * 框架不自带任何序列化器，全部经 createMarkdownProcessor({ codecs }) 注入（各扩展的 markdown.ts）。
+ */
+export declare class MarkdownSerializerRegistry {
+    private serializers;
+    private blockTypes;
+    private footnoteCounter;
+    private footnoteDefinitions;
+    constructor(serializers?: MarkdownSerializer[]);
+    resetFootnotes(): void;
+    addFootnote(content: string): number;
+    getFootnoteDefinitions(): string;
+    register(serializer: MarkdownSerializer): void;
+    registerMany(serializers: MarkdownSerializer[]): void;
+    getSerializer(type: string): MarkdownSerializer | undefined;
+    isBlock(element: CustomElement): boolean;
+}

package/types/packages/markdown/src/model.d.ts

@@ -0,0 +1,7 @@
+/** 扩展通过纯类型入口增强标记字段，框架不拥有具体格式。 */
+export interface TextMarkMap {
+}
+export interface FormattedText extends TextMarkMap {
+    type: "formatted";
+    text: string;
+}

package/types/packages/markdown/src/positionMapper.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Markdown 位置（CodeMirror 格式）
+ */
+export interface MarkdownPosition {
+    line: number;
+    ch: number;
+}
+/**
+ * Slate 位置
+ */
+export interface SlatePosition {
+    path: number[];
+    offset: number;
+}
+/**
+ * 文本级别的映射条目
+ * 用于普通文本节点，支持字符级精确映射
+ */
+export interface TextMapping {
+    type: "text";
+    slateTextPath: number[];
+    slateOffset: number;
+    slateLength: number;
+    mdLine: number;
+    mdCh: number;
+    mdLength: number;
+    prefixLength: number;
+    suffixLength: number;
+    sourceOffsets?: readonly number[];
+    /** 手工改写的载体无法证明字符对应时，只提供首尾边界。 */
+    opaque?: boolean;
+    mdEnd?: MarkdownPosition;
+}
+/**
+ * 元素级别的映射条目
+ * 用于 void 元素（code-block, image 等）
+ */
+export interface ElementMapping {
+    type: "element";
+    slateElementPath: number[];
+    elementType: string;
+    isVoid: true;
+    mdStartLine: number;
+    mdStartCh: number;
+    mdEndLine: number;
+    mdEndCh: number;
+    propertyMappings?: {
+        [propName: string]: {
+            mdStartLine: number;
+            mdStartCh: number;
+            mdEndLine: number;
+            mdEndCh: number;
+        };
+    };
+}
+export type PositionMapping = TextMapping | ElementMapping;
+/**
+ * 位置映射器类（重新设计版本）
+ *
+ * 核心改进：
+ * 1. 文本节点级别映射（而非元素级别）
+ * 2. 支持格式标记的偏移处理
+ * 3. 双向映射都基于相同的数据结构
+ */
+export declare class PositionMapper {
+    private mappings;
+    /**
+     * 添加文本映射
+     */
+    addTextMapping(mapping: TextMapping): void;
+    /**
+     * 添加元素映射（void 元素）
+     */
+    addElementMapping(mapping: ElementMapping): void;
+    /**
+     * 清空映射表
+     */
+    clear(): void;
+    /**
+     * Slate 位置 → Markdown 位置
+     *
+     * @param pos Slate position {path: [0, 0], offset: 5}
+     * @returns Markdown position {line: 2, ch: 15} 或 null
+     */
+    slateToMarkdown(pos: SlatePosition): MarkdownPosition | null;
+    /**
+     * Markdown 位置 → Slate 位置
+     *
+     * @param pos Markdown position {line: 2, ch: 15}
+     * @returns Slate position {path: [0, 0], offset: 5} 或 null
+     */
+    markdownToSlate(pos: MarkdownPosition): SlatePosition | null;
+    /**
+     * 获取所有映射（调试用）
+     */
+    getMappings(): PositionMapping[];
+    /**
+     * 根据 Slate 元素路径查找元素映射
+     */
+    getElementMappingBySlatePath(path: number[]): ElementMapping | null;
+    /**
+     * 根据 Markdown 位置查找元素映射与属性信息
+     */
+    getElementPropertyByMarkdown(pos: MarkdownPosition): {
+        mapping: ElementMapping;
+        propertyName?: string;
+        relativePos?: MarkdownPosition;
+    } | null;
+    /**
+     * 清理无效路径的映射
+     */
+    pruneInvalidPaths(isValidPath: (path: number[]) => boolean): void;
+    /**
+     * 打印映射表（调试用）
+     */
+    debug(): void;
+    /**
+     * 调整子元素映射的位置（用于处理 childrenStart 和 perLineOffset）
+     *
+     * @param parentPath 父元素路径，如 [0]
+     * @param childrenStart 子元素内容在父输出中的起始位置
+     * @param perLineOffset 每行的额外偏移（用于 blockquote "> ", list "- " 等）
+     */
+    adjustChildMappings(parentPath: number[], childrenStart: {
+        line: number;
+        ch: number;
+    }, perLineOffset?: number, baseLine?: number): void;
+    /**
+     * 对指定子元素索引之后的映射进行行号偏移
+     */
+    shiftLinesForChildren(parentPath: number[], startIndex: number, lineDelta: number): void;
+    /**
+     * 调整内联包装元素（如 link）的子文本映射
+     */
+    adjustChildMappingsForInlineWrapper(parentPath: number[], wrapperPrefixLength: number, wrapperSuffixLength: number): void;
+    /**
+     * 判断 childPath 是否是 parentPath 的子路径
+     * 例如：[0, 1, 2] 是 [0, 1] 的子路径
+     */
+    private isChildPath;
+    /**
+     * 根据 Slate path 查找映射
+     */
+    private findMappingBySlate;
+    /**
+     * 根据 Markdown 位置查找映射（二分查找）
+     */
+    private findMappingByMarkdown;
+    /**
+     * 判断 Markdown 位置是否在元素范围内
+     */
+    private isWithinElementRange;
+    /**
+     * 判断 Markdown 位置是否在范围内（end 为排他）
+     */
+    private isWithinRange;
+    /**
+     * 判断位置是否落在区间结束边界（end inclusive，仅用于光标映射）
+     */
+    private isAtRangeInclusiveEnd;
+}

package/types/packages/markdown/src/processor.d.ts

@@ -0,0 +1,27 @@
+import type { Descendant } from "slate";
+import type { MarkdownCodec } from "./codec";
+import { type ImportFromMarkdownOptions, type SlateWithPositions } from "./markdown";
+import { type MarkdownWithPositions } from "./markdown-helper";
+import type { CustomElement } from "./types";
+import type { FormattedText } from "./model";
+import { type MarkdownTextCodec, type LeafSerializationResult } from "./textCodec";
+export interface MarkdownProcessor {
+    importFromMarkdown(markdown: string, ignoreTypes?: string[], options?: ImportFromMarkdownOptions): Descendant[];
+    importFromMarkdownWithPositions(markdown: string, ignoreTypes?: string[], options?: ImportFromMarkdownOptions): SlateWithPositions;
+    getMarkdown(value: Descendant[]): string;
+    getMarkdownWithPositions(value: Descendant[]): MarkdownWithPositions;
+    elementToMarkdown(element: CustomElement, parentElement: CustomElement | null): string;
+    leafToMarkdown(leaf: FormattedText): string;
+    leafToMarkdownStructured(leaf: FormattedText): LeafSerializationResult;
+}
+export interface MarkdownProcessorOptions {
+    /** 元素类型的编解码（各扩展的 markdown.ts 提供）；处理器只认这里的类型，其余走 ER-006 兜底 */
+    codecs?: MarkdownCodec[];
+    textCodecs?: readonly MarkdownTextCodec[];
+}
+/**
+ * 创建 Markdown 处理器（01 §8.2）：框架不带任何元素类型，全部经 codecs 注入，
+ * 宿主把扩展包的 codec 列表（如 @tau/editor/markdown）与自己的业务 codec 合成一次，
+ * 渲染进程和 Electron 主进程共用，避免两边漂移。
+ */
+export declare function createMarkdownProcessor(options?: MarkdownProcessorOptions): MarkdownProcessor;

package/types/packages/markdown/src/textCodec.d.ts

@@ -0,0 +1,39 @@
+import type { MarkdownImportNode } from "./codec";
+import type { FormattedText } from "./model";
+export interface MarkdownTextRule {
+    nodeType: string;
+    directive?: string;
+    content: "children" | "value";
+    /** children 模式的源码包裹范围；指令沿用外层以保持既有位置口径。 */
+    position?: "self" | "inherit";
+    readMarks(node: MarkdownImportNode): Readonly<Record<string, unknown>> | null;
+}
+export interface MarkdownTextCodec {
+    id: string;
+    keys: readonly string[];
+    importRules: readonly MarkdownTextRule[];
+    exportWrap(leaf: Readonly<FormattedText>): {
+        prefix: string;
+        suffix: string;
+    } | null;
+}
+export interface LeafSerializationResult {
+    output: string;
+    prefixLength: number;
+    suffixLength: number;
+    /** 转义载体中每个原文本边界相对 output 的偏移。 */
+    sourceOffsets?: readonly number[];
+}
+/** 处理器实例私有的纯标记注册表，不加载 UI 或默认格式。 */
+export declare class MarkdownTextRegistry {
+    private readonly rules;
+    private readonly keys;
+    private readonly codecs;
+    constructor(codecs: readonly MarkdownTextCodec[]);
+    claim(node: MarkdownImportNode): {
+        rule: MarkdownTextRule;
+        marks: Readonly<Record<string, unknown>>;
+    } | null;
+    serialize(leaf: Readonly<FormattedText>): LeafSerializationResult;
+    private serializeKnown;
+}

package/types/packages/markdown/src/types.d.ts

@@ -0,0 +1,8 @@
+import type { FormattedText } from "./model";
+export type { FormattedText } from "./model";
+/** 框架只看树结构；具体元素的字段和类型由 codec 解释。 */
+export interface CustomElement {
+    type: string;
+    children: Array<CustomElement | FormattedText>;
+}
+export declare const isFormattedText: (node: CustomElement | FormattedText) => node is FormattedText;

package/types/packages/plugins/src/contract.d.ts

@@ -0,0 +1,49 @@
+import type { PluginPages } from "./pages";
+import type { PluginEditor } from "./editor";
+import type { PluginSettings } from "./settings";
+import type { PluginSidebar } from "./sidebar";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface Disposable {
+    dispose(): void | Promise<void>;
+}
+export interface PluginStorage {
+    get(key: string): Promise<JsonValue | undefined>;
+    set(key: string, value: JsonValue): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface PluginCommand {
+    /** 插件内的局部 ID，宿主会添加插件命名空间。 */
+    id: string;
+    title: string;
+    run(input: JsonValue): JsonValue | Promise<JsonValue>;
+}
+export interface PluginContext {
+    readonly pluginId: string;
+    readonly workspaceId: string;
+    readonly signal: AbortSignal;
+    readonly commands: {
+        register(command: PluginCommand): Disposable;
+    };
+    readonly storage: PluginStorage;
+    readonly pages: PluginPages;
+    readonly editor: PluginEditor;
+    readonly settings: PluginSettings;
+    readonly sidebar: PluginSidebar;
+    readonly fetch: typeof globalThis.fetch;
+    /** 将订阅等资源交给宿主，在停用或激活失败时逆序回收。 */
+    register(resource: Disposable): Disposable;
+}
+export interface PluginInstance {
+    activate(context: PluginContext): void | Promise<void>;
+    deactivate?(): void | Promise<void>;
+}
+export interface PluginDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly apiVersion: 1;
+    /** 每次启用创建新实例，运行状态不放在定义对象上。 */
+    create(): PluginInstance;
+}

package/types/packages/plugins/src/editor.d.ts

@@ -0,0 +1,37 @@
+import type { EditorExtension as InternalExtension } from "../../editor/contracts";
+import type { MarkdownCodec } from "../../markdown/src/index";
+import type { Disposable } from "./index";
+export { defineElement as defineEditorElement } from "../../editor/contracts";
+export type { ElementRenderProps as EditorElementRenderProps } from "../../editor/contracts";
+export type { MarkdownCodec as EditorMarkdownCodec } from "../../markdown/src/index";
+/** 作者通过模块增强登记自定义节点，无需引用编辑器内部包。 */
+declare const elementMapBrand: unique symbol;
+declare const inlineMapBrand: unique symbol;
+export interface EditorElementMap {
+    [elementMapBrand]: never;
+}
+export interface EditorInlineElementMap {
+    [inlineMapBrand]: never;
+}
+declare module "../../editor/api" {
+    interface ExtensionElementMap extends EditorElementMap {
+        [elementMapBrand]: never;
+    }
+    interface ExtensionInlineElementMap extends EditorInlineElementMap {
+        [inlineMapBrand]: never;
+    }
+}
+export type PluginEditorExtension = Pick<InternalExtension, "id" | "apiVersion" | "elements" | "commands" | "hotkeys" | "menu"> & {
+    plugins?: never;
+};
+export declare function defineEditorExtension(definition: Omit<PluginEditorExtension, "apiVersion">): PluginEditorExtension;
+export interface PluginEditorContribution {
+    /** 目前只有开发台场景；其他场景需宿主明确接入后开放。 */
+    scene: "workbench";
+    extension: PluginEditorExtension;
+    /** 纯函数定义可由主进程独立导入，本次只在开发台装配。 */
+    codecs?: readonly MarkdownCodec[];
+}
+export interface PluginEditor {
+    register(contribution: PluginEditorContribution): Disposable;
+}

package/types/packages/plugins/src/index.d.ts

@@ -0,0 +1,7 @@
+import type { PluginDefinition } from "./contract";
+export type { JsonValue, Disposable, PluginStorage, PluginCommand, PluginContext, PluginInstance, PluginDefinition, } from "./contract";
+export type { PluginSettings, PluginSettingsDefinition, PluginSettingsProps, PluginSettingsHandle, } from "./settings";
+export * from "./editor";
+export * from "./sidebar";
+export type { PluginPageDefinition, PluginPageHandle, PluginPageParams, PluginPageProps, PluginPages, } from "./pages";
+export declare function definePlugin(definition: Omit<PluginDefinition, "apiVersion">): PluginDefinition;

package/types/packages/plugins/src/pages.d.ts

@@ -0,0 +1,23 @@
+import type { ComponentType } from "react";
+import type { Disposable, PluginContext } from "./index";
+export type PluginPageParams = Record<string, string | number | boolean>;
+export interface PluginPageProps {
+    readonly context: PluginContext;
+    readonly params: Readonly<PluginPageParams>;
+}
+export interface PluginPageDefinition {
+    id: string;
+    title: string;
+    component: ComponentType<PluginPageProps>;
+    match?: "single" | "params";
+    /** params 页缺省按完整参数区分实例；提供时只按该身份去重。 */
+    getId?(params: Readonly<PluginPageParams>): string;
+}
+export interface PluginPageHandle extends Disposable {
+    readonly id: string;
+    open(params?: PluginPageParams): Promise<void>;
+}
+export interface PluginPages {
+    register(definition: PluginPageDefinition): PluginPageHandle;
+}
+export declare function normalizePageParams(value: unknown): PluginPageParams;

package/types/packages/plugins/src/settings.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentType } from "react";
+import type { Disposable, PluginContext } from "./index";
+export interface PluginSettingsProps {
+    readonly context: PluginContext;
+}
+export interface PluginSettingsDefinition {
+    id: string;
+    title: string;
+    description?: string;
+    component: ComponentType<PluginSettingsProps>;
+}
+export interface PluginSettingsHandle extends Disposable {
+    readonly id: string;
+    open(): Promise<void>;
+}
+export interface PluginSettings {
+    /** 分区随本次激活回收，保存使用 context.storage。 */
+    register(definition: PluginSettingsDefinition): PluginSettingsHandle;
+}

package/types/packages/plugins/src/sidebar.d.ts

@@ -0,0 +1,29 @@
+import type { Disposable } from "./contract";
+import type { PluginPageHandle, PluginPageParams } from "./pages";
+export declare const SIDEBAR_GROUPS: Readonly<{
+    readonly daily: "daily";
+    readonly knowledge: "knowledge";
+    readonly learning: "learning";
+    readonly ai: "ai";
+    readonly sharing: "sharing";
+    readonly plugins: "plugins";
+}>;
+export interface PluginSidebarGroupDefinition {
+    id: string;
+    title: string;
+}
+export interface PluginSidebarGroupHandle extends Disposable {
+    readonly id: string;
+}
+export interface PluginSidebarItemDefinition {
+    id: string;
+    title: string;
+    /** 缺省或分组不存在时归入默认插件分组。 */
+    group?: string;
+    page: PluginPageHandle;
+    params?: PluginPageParams;
+}
+export interface PluginSidebar {
+    registerGroup(definition: PluginSidebarGroupDefinition): PluginSidebarGroupHandle;
+    registerItem(definition: PluginSidebarItemDefinition): Disposable;
+}

package/types/packages/shared/service-contract.d.ts

@@ -0,0 +1,6 @@
+/** 服务标识符的类型只用于约束注册与获取，运行时以 id 匹配。 */
+export interface ServiceIdentifier<T> {
+    readonly id: string;
+    readonly __serviceType: T;
+}
+export declare function createServiceId<T>(id: string): ServiceIdentifier<T>;

package/types/packages/shared/service-registry.d.ts

@@ -0,0 +1,25 @@
+import type { ServiceIdentifier } from "./service-contract";
+/**
+ * 服务注册表：宿主平台能力的统一容器。
+ * 注册与消费均以 ServiceIdentifier 匹配；可由编辑器、白板等宿主共享使用。
+ */
+export interface ServiceRegistry {
+    /** 获取必选服务，未注册时抛出包含服务 id 的错误 */
+    get<T>(id: ServiceIdentifier<T>): T;
+    /** 获取可选服务，未注册时返回 undefined；用于消费侧显式降级 */
+    tryGet<T>(id: ServiceIdentifier<T>): T | undefined;
+    has<T>(id: ServiceIdentifier<T>): boolean;
+}
+/**
+ * 注册单个服务。实现值既可以是实例，也可以是 `(registry) => impl` 工厂：
+ * 工厂在首次 get 时才求值，因此注册顺序无关，且可在工厂内依赖其他服务。
+ * 注意：注册的值如果本身是函数，会被视为工厂。
+ */
+export type ServiceRegister = <T>(id: ServiceIdentifier<T>, impl: T | ((registry: ServiceRegistry) => T)) => void;
+export type ServiceRegistration = (register: ServiceRegister) => void;
+export declare function createServiceRegistry(...registrations: ServiceRegistration[]): ServiceRegistry;
+/**
+ * 基于父注册表派生子注册表：get 时优先命中子级覆盖项，未命中则委托父级。
+ * 用于协同编辑等需要按上下文覆盖个别服务的场景，覆盖粒度可到单个服务。
+ */
+export declare function createChildRegistry(parent: ServiceRegistry, ...overrides: ServiceRegistration[]): ServiceRegistry;

package/types/packages/themes/src/bootstrap.d.ts

@@ -0,0 +1,26 @@
+import { type ThemeMode } from "./defineTheme";
+import "./register";
+/** 明暗偏好：固定浅色 / 固定深色 / 跟随系统（与主题族正交） */
+export type Appearance = ThemeMode | "system";
+export declare const DEFAULT_THEME_KEY = "paper";
+export declare const DEFAULT_APPEARANCE: Appearance;
+export declare const THEME_STORAGE_KEY = "tau-theme";
+export declare const APPEARANCE_STORAGE_KEY = "tau-appearance";
+export interface ThemeRuntimeConfig {
+    defaultTheme: string;
+    defaultAppearance: Appearance;
+    themeStorageKey: string;
+    appearanceStorageKey: string;
+    themes: string[];
+}
+export interface ResolvedThemePreference {
+    theme: string;
+    appearance: Appearance;
+    mode: ThemeMode;
+}
+export declare function themeRuntimeConfig(overrides?: Partial<Omit<ThemeRuntimeConfig, "themes">>): ThemeRuntimeConfig;
+/**
+ * 存储值 → 生效主题。首帧内联脚本经 toString() 内嵌本函数，必须自包含（不引用模块内其它符号）。
+ */
+export declare function resolveThemePreference(savedTheme: string | null, savedAppearance: string | null, prefersDark: boolean, config: ThemeRuntimeConfig): ResolvedThemePreference;
+export declare function createThemeBootstrapScript(config?: ThemeRuntimeConfig): string;

package/types/packages/themes/src/defineTheme.d.ts

@@ -0,0 +1,45 @@
+/**
+ * defineTheme 协议 —— 一个文件声明一个主题族的全部。
+ *
+ * 与 definePage 同构的声明式协议（设计见 docs/redesign/02-UI设计系统规范.md §2.2）：
+ *  - 一个主题族 = key/名字 + 浅色、深色两套 palette/tokens 映射函数；深浅都是必填，
+ *    不存在「只有浅色的主题」，明暗是与主题族正交的维度（用户偏好 light/dark/system）；
+ *  - tokens() 返回值被约束为全键 SemanticTokens，漏键 = 编译错误（杜绝补丁式主题）；
+ *  - 派生逻辑（accent hover/soft 等）写在映射函数里，显式可读，不藏在 CSS calc 中；
+ *  - 注册进纯数据注册表；运行时由 theme.ts 切换 data-theme / data-mode。
+ *
+ * 运行时：tokens.css 的 [data-theme][data-mode] 数据块级联取值（index.html 内联脚本首帧
+ * 预置，theme.ts 只切属性 + 持久化），数据块与 tokens() 产物由 theme-parity 测试守护；
+ * 后续优化为构建期 codegen（`pnpm ui:themes` 生成数据块），协议不变。
+ */
+import type { SemanticTokens } from "./tokenContract";
+export type ThemeMode = "light" | "dark";
+export declare const THEME_MODES: readonly ThemeMode[];
+/** 原始色板输入（主题作者自由组织，不进组件；数值型输入用于派生计算） */
+export type ThemePalette = Record<string, string | number>;
+/** 主题族的一套明暗配色 */
+export interface ThemeVariant {
+    palette: ThemePalette;
+    /** 色板 → 语义 token 的纯函数映射产物（全键强制） */
+    tokens: SemanticTokens;
+}
+export interface ThemeDefinition extends Record<ThemeMode, ThemeVariant> {
+    key: string;
+    name: string;
+    /** 设置页等列表中的排序权重（升序，同权重按注册顺序）；缺省 0 */
+    order: number;
+}
+export interface ThemeVariantArgs {
+    palette: ThemePalette;
+    tokens: (p: ThemePalette) => SemanticTokens;
+}
+export interface ThemeDefinitionArgs extends Record<ThemeMode, ThemeVariantArgs> {
+    key: string;
+    name: string;
+    order?: number;
+}
+export declare function defineTheme(args: ThemeDefinitionArgs): ThemeDefinition;
+export declare function getThemeRegistry(): ReadonlyMap<string, ThemeDefinition>;
+/** 按 order 排序的主题列表（供设置页等枚举展示；不依赖注册 / import 顺序） */
+export declare function listThemes(): ThemeDefinition[];
+export declare function getTheme(key: string): ThemeDefinition | undefined;

package/types/packages/themes/src/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 主题契约根入口：token 词汇表、defineTheme 协议与注册表、内置主题、偏好解析与首帧脚本生成。
+ * 纯数据 + 纯函数，不依赖 DOM / React，可在 Node（vite 配置、主进程、测试）中直接使用。
+ * DOM 应用见 `@tau/themes/dom`，React 运行时见 `@tau/themes/react`。
+ */
+import "./register";
+export * from "./tokenContract";
+export { THEME_MODES, defineTheme, getTheme, getThemeRegistry, listThemes } from "./defineTheme";
+export type { ThemeDefinition, ThemeDefinitionArgs, ThemeMode, ThemePalette, ThemeVariant, ThemeVariantArgs, } from "./defineTheme";
+export { APPEARANCE_STORAGE_KEY, DEFAULT_APPEARANCE, DEFAULT_THEME_KEY, THEME_STORAGE_KEY, createThemeBootstrapScript, resolveThemePreference, themeRuntimeConfig, type Appearance, type ResolvedThemePreference, type ThemeRuntimeConfig, } from "./bootstrap";

package/types/packages/themes/src/register.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 内置主题的副作用注册。各入口 import 本文件，保证取注册表前主题已就位。
+ */
+import "./themes/paper.theme";
+import "./themes/ocean.theme";
+import "./themes/mint.theme";
+import "./themes/wisteria.theme";
+import "./themes/sakura.theme";
+import "./themes/ink.theme";

package/types/packages/themes/src/themes/ink.theme.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 主题「水墨」—— 宣纸落墨：近白而非纯白、近黑而非纯黑，彩度压到最低，素净留白。
+ *
+ * 浅色（宣纸）：微暖米白纸底 + 浓墨；accent 取低饱和「青黛」（墨中带一丝蓝灰），仍是墨色却可辨识；
+ * 状态色取国画颜料（石绿 / 藤黄 / 朱砂 / 花青 / 赭石）并全部降饱和；阴影比其它主题更淡，画面更平静。
+ * 深色（松烟）：暖黑墨底 + 宣纸色墨字 + 提亮青黛；层级口径同暖纸 · 夜。
+ *
+ * 对比度按 02 规范 §2.5，深浅两套均由 theme-parity.test.ts 校验。
+ */
+declare const _default: import("../defineTheme").ThemeDefinition;
+export default _default;

package/types/packages/themes/src/themes/mint.theme.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 主题「薄荷」—— 取自移动端薄荷 Mint（浅色·清新）：灰绿纸底 + 松墨 + 翠绿 accent。
+ *
+ * 浅色（晴）：底色 / 墨色 / 状态色沿用移动端；ink-2 与 accent 按桌面 AA 门禁压深。
+ * 深色（夜林）：移动端无深色版，按同色相推演——墨绿夜底 + 淡薄荷白墨 + 中饱和翠绿 accent；
+ * 绿调强度介于「整页泛绿」与「近中性（与水墨 · 松烟难分）」之间。
+ *
+ * 对比度按 02 规范 §2.5，深浅两套均由 theme-parity.test.ts 校验。
+ */
+declare const _default: import("../defineTheme").ThemeDefinition;
+export default _default;