@freecallai/pro 0.0.0-stage → 0.0.1

package/dist/types/rich-text/public/types.d.ts

@@ -0,0 +1,588 @@
+import { JSONContent } from '@tiptap/core';
+export type KnowledgeType = 'normal' | 'reasoning' | 'agent';
+export type CapabilitySlot = 'questionAction' | 'knowledgeInline' | 'knowledgeBlock' | 'sceneAction' | 'toolbarOnly';
+export type CapabilityId = 'todo' | 'ticket' | 'originalReply' | 'memory' | 'tagged' | 'variable' | 'image' | 'video' | 'separator' | 'attribute' | 'tool' | 'agentSelect' | 'reasoningPolish' | 'reasoningTemplate';
+export interface KnowledgeSceneV1 {
+    /** 场景数据版本，固定为 1。
+     * @en Scene schema version, currently 1.
+     */
+    schemaVersion: 1;
+    /** 已持久化的场景 ID，新建时可省略。
+     * @en Persisted scene ID; omit for a new scene.
+     */
+    id?: string;
+    /** 知识类型：常规、推理或 Agent。
+     * @en Knowledge type: normal, reasoning, or Agent.
+     */
+    type: KnowledgeType;
+    /** 顾客问法纯文本，不包含显示标签或模型协议标记。
+     * @en Plain customer intent, without display tags or model protocol tokens.
+     */
+    question: {
+        text: string;
+    };
+    /** Tiptap JSON 正文、Agent 选择及切换类型时保留的正文。
+     * @en Tiptap JSON content, Agent selection, and content retained during type changes.
+     */
+    knowledge: {
+        doc: JSONContent | null;
+        retainedDoc?: JSONContent | null;
+        agentRef?: {
+            id: string;
+            name: string;
+        } | null;
+    };
+    /** 按能力 ID 保存的版本化插件状态，不与问法文本混写。
+     * @en Versioned plugin state keyed by capability ID, separate from question text.
+     */
+    extensionState: Record<string, {
+        version: number;
+        data: unknown;
+    }>;
+}
+/** Backend-neutral condition envelope owned by the consuming page. */
+export interface KnowledgeConditionV1 {
+    /** 条件数据版本，固定为 1。
+     * @en Condition schema version, currently 1.
+     */
+    schemaVersion: 1;
+    /** 已持久化的条件 ID。
+     * @en Persisted condition ID.
+     */
+    id?: string;
+    /** 条件中的场景列表；sceneKey 在同一条件内唯一。
+     * @en Ordered scenes; sceneKey is unique within the condition.
+     */
+    scenes: Array<{
+        sceneKey: string;
+        scene: KnowledgeSceneV1;
+    }>;
+}
+/** 迁移诊断必须保留原始字段或节点位置。
+ * @en Migration issue with a required original field or node path.
+ */
+export type MigrationIssueV1 = EditorDiagnostic & {
+    source: 'migration';
+    path: string;
+};
+/** Target structured persistence contract implemented by the consuming app. */
+export interface LoadedConditionV1 {
+    /** 结构化结果无 kind，可与旧版只读分支按 kind 收窄。
+     * @en Structured results omit kind so callers can narrow the legacy branch.
+     */
+    kind?: never;
+    /** 已加载的完整结构化条件。
+     * @en Complete structured condition returned by loading.
+     */
+    condition: KnowledgeConditionV1;
+    /** 服务端不透明版本号，用于后续更新。
+     * @en Opaque server revision for the next update.
+     */
+    revision: string;
+    /** 无损迁移中的提示或警告，每条都带来源路径；错误须走旧版只读分支。
+     * @en Path-based info or warnings from lossless migration; errors require the legacy read-only branch.
+     */
+    migrationIssues: Array<MigrationIssueV1 & {
+        severity: 'info' | 'warning';
+    }>;
+}
+/** Old condition that cannot be represented without losing data. Never pass it to the V1 save input. */
+export interface LegacyReadonlyConditionV1 {
+    /** 旧版条件只读分支标识。
+     * @en Discriminant for an unmigratable legacy condition.
+     */
+    kind: 'legacyReadonly';
+    /** Stable ID of the original condition. */
+    conditionId: string;
+    /** Complete JSON response data kept outside the new editor schema. */
+    rawCondition: Record<string, unknown>;
+    /** At least one error with a source path explains why editing is unavailable. */
+    migrationIssues: MigrationIssueV1[];
+}
+export type ConditionLoadV1 = LoadedConditionV1 | LegacyReadonlyConditionV1;
+export interface SaveConditionInputV1 {
+    /** 待保存的完整条件。
+     * @en Complete condition to save.
+     */
+    condition: KnowledgeConditionV1;
+    /** 新建时为 null，更新时为上次读取的服务端版本号。
+     * @en Null for creation; the last server revision for an update.
+     */
+    expectedRevision: string | null;
+    /** 一次保存请求的幂等键。
+     * @en Idempotency key for one save request.
+     */
+    idempotencyKey: string;
+}
+export interface SavedConditionV1 {
+    /** 服务端回读的完整条件。
+     * @en Complete condition echoed by the server.
+     */
+    condition: KnowledgeConditionV1;
+    /** 本次保存后的新版本号。
+     * @en New server revision after saving.
+     */
+    revision: string;
+}
+export interface KnowledgePersistenceAdapterV1 {
+    /** 按条件 ID 载入完整结构化数据。
+     * @en Load complete structured data by condition ID.
+     */
+    load(conditionId: string, signal: AbortSignal): Promise<PortResult<ConditionLoadV1>>;
+    /** 使用版本号与幂等键保存完整条件。
+     * @en Save the complete condition with revision and idempotency key.
+     */
+    save(input: SaveConditionInputV1, signal: AbortSignal): Promise<PortResult<SavedConditionV1>>;
+}
+export interface CapabilityRuleV1 {
+    /** 能力标识，应与 slot 一起匹配内置能力目录。
+     * @en Capability ID; match together with slot against the built-in catalog.
+     */
+    id: CapabilityId;
+    /** 能力所在位置。
+     * @en Capability placement.
+     */
+    slot: CapabilitySlot;
+    /** 是否允许此能力参与编辑。
+     * @en Whether this capability may be used while editing.
+     * @defaultValue -
+     */
+    enabled?: boolean;
+    /** 是否在工具栏中显示；不改变已存节点。
+     * @en Toolbar visibility; does not delete stored nodes.
+     * @defaultValue -
+     */
+    visible?: boolean;
+    /** 覆盖工具栏显示名称；提供时必须包含非空白字符。
+     * @en Override the displayed toolbar label; it must be nonblank when provided.
+     */
+    label?: string;
+    /** 覆盖工具栏排序权重。
+     * @en Override toolbar ordering weight.
+     */
+    order?: number;
+    /** 选项分页或媒体限制；形状由能力类型决定。
+     * @en Selection paging or media limits, depending on capability kind.
+     */
+    options?: unknown;
+}
+export interface SceneConfigInputV1 {
+    /** 配置版本，固定为 1。
+     * @en Configuration schema version, currently 1.
+     */
+    schemaVersion: 1;
+    /** 宿主配置修订号，用于标识配置快照。
+     * @en Host configuration revision identifying the snapshot.
+     */
+    revision?: string;
+    /** 能力规则；同一 id 与 slot 不得重复。
+     * @en Capability rules; each id and slot pair must be unique.
+     */
+    rules: CapabilityRuleV1[];
+}
+export interface SceneConfigLayersV1 {
+    /** 配置中心快照；当前实现中只要不可用或过期就锁定编辑。
+     * @en Remote configuration snapshot; this version locks editing whenever it is unavailable or expired.
+     */
+    remote?: {
+        status: 'ready';
+        snapshot: SceneConfigInputV1;
+        expiresAt: number;
+        required: boolean;
+    } | {
+        status: 'unavailable';
+        required: boolean;
+    };
+    /** 页面级能力覆盖，不能扩大上层权限或限制。
+     * @en Page-level capability overrides cannot widen upstream permissions or limits.
+     */
+    page?: SceneConfigInputV1;
+}
+export interface HostPolicySnapshotV1 {
+    /** 权限快照修订号。
+     * @en Authorization snapshot revision.
+     */
+    revision: string;
+    /** 权限过期时间，Unix 毫秒时间戳。
+     * @en Authorization expiry as Unix milliseconds.
+     */
+    expiresAt: number;
+    /** 允许的能力与可选限制；不在列表中的能力不可插入。
+     * @en Allowed capabilities and optional limits; omitted capabilities cannot be inserted.
+     */
+    allowed: Array<{
+        id: CapabilityId;
+        slot: CapabilitySlot;
+        options?: unknown;
+    }>;
+}
+export interface EditorDiagnostic {
+    /** 机器可读的问题代码。
+     * @en Machine-readable issue code.
+     */
+    code: string;
+    /** 提示级别。
+     * @en Diagnostic severity.
+     */
+    severity: 'info' | 'warning' | 'error';
+    /** 问题来源。
+     * @en Source of the issue.
+     */
+    source: 'config' | 'plugin' | 'port' | 'validation' | 'migration';
+    /** 可直接展示的说明。
+     * @en Human-readable message.
+     */
+    message: string;
+    /** 相关场景键。
+     * @en Related scene key.
+     */
+    sceneKey?: string;
+    /** 相关能力 ID。
+     * @en Related capability ID.
+     */
+    capabilityId?: CapabilityId;
+    /** 相关能力位置。
+     * @en Related capability placement.
+     */
+    slot?: CapabilitySlot;
+    /** 出错的数据路径。
+     * @en Path to invalid data.
+     */
+    path?: string;
+    /** 是否可重试。
+     * @en Whether the operation may be retried.
+     */
+    retryable?: boolean;
+}
+export interface ChangeMeta {
+    /** 发生变更的场景键。
+     * @en Key of the changed scene.
+     */
+    sceneKey: string;
+    /** 本实例递增的变更修订号，用于 ackRevision。
+     * @en Instance-local change revision used by ackRevision.
+     */
+    revision: number;
+    /** 变更来源。
+     * @en Origin of the change.
+     */
+    origin: 'user' | 'plugin' | 'typeSwitch' | 'undo';
+    /** 插件变更时的能力 ID。
+     * @en Capability ID for a plugin-origin change.
+     */
+    capabilityId?: CapabilityId;
+}
+export type PortErrorCode = 'ABORTED' | 'UNAVAILABLE' | 'FORBIDDEN' | 'INVALID_RESPONSE' | 'CONFLICT' | 'TIMEOUT' | 'NETWORK' | 'UNKNOWN';
+export type PortResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: {
+        code: PortErrorCode;
+        message: string;
+        retryable: boolean;
+        traceId?: string;
+        issues?: EditorDiagnostic[];
+    };
+};
+export interface PortRequestContext {
+    /** 发起请求的场景键。
+     * @en Scene key that initiated the request.
+     */
+    sceneKey: string;
+    /** 发起请求的能力标识。
+     * @en Capability that initiated the request.
+     */
+    capabilityId: CapabilityId;
+    /** 单次请求标识，可用于日志追踪。
+     * @en Per-request ID for tracing.
+     */
+    requestId: string;
+    /** 场景切换或请求失效时触发的取消信号。
+     * @en Abort signal triggered when the scene or request becomes stale.
+     */
+    signal: AbortSignal;
+    /** 上传端口可调用此函数报告 0–100 的进度。
+     * @en Upload ports may report progress from 0 to 100 through this callback.
+     */
+    reportProgress?: (percent: number) => void;
+}
+export interface Page<T> {
+    /** 当前页的选项，数量不得超过请求的 limit。
+     * @en Items in this page; length must not exceed the requested limit.
+     */
+    items: T[];
+    /** 下一页游标；没有更多数据时省略。同一次查询中不得返回当前或已用过的游标。
+     * @en Next-page cursor; omit when complete. Never repeat the current or an earlier cursor in one query.
+     */
+    nextCursor?: string;
+}
+export interface CapabilityOption {
+    /** 非空白的稳定选项 ID，分页间不得重复。
+     * @en Nonblank stable option ID, unique across pages.
+     */
+    id: string;
+    /** 非空白的显示名称；待办/打标方案名不得含花括号或换行。
+     * @en Nonblank display label; todo and tag plan names cannot contain braces or line breaks.
+     */
+    label: string;
+    /** 禁止选择此项。
+     * @en Disable selection of this item.
+     * @defaultValue -
+     */
+    disabled?: boolean;
+    /** 是否有子项；点击后以此项 ID 作为 parentId 请求下级。
+     * @en Whether this is a category; request children using its ID as parentId.
+     * @defaultValue -
+     */
+    hasChildren?: boolean;
+    /** 推理模板的可选纯文本预览。
+     * @en Optional plain-text preview for a reasoning template.
+     */
+    preview?: string;
+}
+export interface ToolFormField {
+    /** 字段键，对应工具节点 params 的属性名。
+     * @en Field key in the tool node's params.
+     */
+    id: string;
+    /** 非空白的字段显示名，也用作隐藏视觉标签时的无障碍名称。
+     * @en Nonblank field label, also used as the accessible name when visually hidden.
+     */
+    label: string;
+    /** 字段输入形式。
+     * @en Field input control.
+     */
+    kind: 'text' | 'number' | 'switch' | 'textarea' | 'radio' | 'checkbox';
+    /** 是否必填。
+     * @en Whether the field is required.
+     * @defaultValue -
+     */
+    required?: boolean;
+    /** 输入提示。
+     * @en Input placeholder.
+     */
+    placeholder?: string;
+    /** 数值下限。
+     * @en Numeric minimum.
+     */
+    min?: number;
+    /** 数值上限。
+     * @en Numeric maximum.
+     */
+    max?: number;
+    /** 文本最大字符数。
+     * @en Maximum text length.
+     */
+    maxLength?: number;
+    /** 单选项；旗帜色仅接受十六进制颜色。
+     * @en Radio choices; flag colors accept hexadecimal values only.
+     */
+    options?: Array<{
+        value: string;
+        label: string;
+        color?: string;
+    }>;
+    /** 初次插入时的默认值。
+     * @en Default value for a new tool token.
+     */
+    defaultValue?: string | boolean;
+    /** 隐藏视觉标签，保留输入控件的无障碍名称。
+     * @en Hide the visual label while keeping the control's accessible name.
+     */
+    hideLabel?: boolean;
+    /** 旗帜色单选项样式。
+     * @en Flag-style radio choices.
+     */
+    appearance?: 'flag';
+    /** 仅当前置字段等于指定值时显示此字段。
+     * @en Show this field only when an earlier field matches the value.
+     */
+    visibleWhen?: {
+        fieldId: string;
+        equals: string | boolean;
+    };
+}
+export interface ToolFormDefinition {
+    /** 工具 ID，应与请求一致。
+     * @en Tool ID, matching the request.
+     */
+    toolId: string;
+    /** 当前用户是否有权插入此工具。
+     * @en Whether the current user may insert this tool.
+     * @defaultValue -
+     */
+    permitted: boolean;
+    /** 表单字段列表；未声明的字段及嵌套配置会被拒绝，避免静默忽略业务设置。
+     * @en Dynamic form fields; undeclared fields and nested settings are rejected rather than silently ignored.
+     */
+    fields: ToolFormField[];
+}
+export interface VariableOption extends CapabilityOption {
+    /** 可选的变量分组；同组变量在选择浮层右栏展示，未分组变量留在左栏。
+     * @en Optional display group; grouped variables appear in the right column, ungrouped variables in the left.
+     */
+    group?: string;
+    /** 非空白的变量协议文本，插入知识正文。
+     * @en Nonblank variable token inserted into the knowledge document.
+     */
+    token: string;
+}
+export interface AgentSummary {
+    /** 自定义 Agent 的稳定 ID。
+     * @en Stable custom Agent ID.
+     */
+    id: string;
+    /** 非空白的 Agent 显示名称。
+     * @en Nonblank Agent display name.
+     */
+    name: string;
+}
+export interface AgentPrompt extends AgentSummary {
+    /** Agent 的只读提示词预览。
+     * @en Read-only preview of the Agent prompt.
+     */
+    prompt: string;
+    /** 可选的 Agent 提示词版本。
+     * @en Optional Agent prompt revision.
+     */
+    revision?: string;
+}
+export interface MediaAsset {
+    /** 持久化资源 ID。
+     * @en Persisted asset ID.
+     */
+    id?: string;
+    /** 可展示的资源 URL。
+     * @en Renderable asset URL.
+     */
+    url: string;
+    /** 资源类型。
+     * @en Asset kind.
+     */
+    kind: 'image' | 'video';
+    /** 视频封面 URL。
+     * @en Video poster URL.
+     */
+    posterUrl?: string;
+}
+export interface RichTextHostPorts {
+    /** 分页查询变量，返回含 token 的平铺变量选项；可用 group 在前端分栏。
+     * @en Search flat, paged variable options with tokens; group controls the client-side columns.
+     */
+    listVariables?: (query: {
+        search?: string;
+        cursor?: string;
+        limit: number;
+    }, ctx: PortRequestContext) => Promise<PortResult<Page<VariableOption>>>;
+    /** 上传图片或视频，返回可保存的资源标识与 URL。
+     * @en Upload an image or video and return its persisted asset identity and URL.
+     */
+    uploadMedia?: (input: {
+        file: File;
+        kind: 'image' | 'video';
+    }, ctx: PortRequestContext) => Promise<PortResult<MediaAsset>>;
+    /** 分页搜索可选的自定义 Agent。
+     * @en Search selectable custom Agents with pagination.
+     */
+    searchAgents?: (query: {
+        search?: string;
+        cursor?: string;
+        limit: number;
+    }, ctx: PortRequestContext) => Promise<PortResult<Page<AgentSummary>>>;
+    /** 获取所选 Agent 的名称与提示词。
+     * @en Load the selected Agent's name and prompt.
+     */
+    getAgentPrompt?: (input: {
+        agentId: string;
+    }, ctx: PortRequestContext) => Promise<PortResult<AgentPrompt>>;
+    /** 查询待办、工单、打标、属性、工具和推理模板等能力选项；工单使用 capabilityId: 'ticket'。
+     * @en Query options for todo, tickets, tagging, attributes, tools, and reasoning templates; tickets use capabilityId: 'ticket'.
+     */
+    listCapabilityOptions?: (input: {
+        capabilityId: string;
+        parentId?: string;
+        search?: string;
+        cursor?: string;
+        limit: number;
+    }, ctx: PortRequestContext) => Promise<PortResult<Page<CapabilityOption>>>;
+    /** 提出润色后的推理正文，不直接覆盖当前内容。
+     * @en Propose polished reasoning content without directly replacing the current document.
+     */
+    proposeReasoning?: (input: {
+        scene: KnowledgeSceneV1;
+    }, ctx: PortRequestContext) => Promise<PortResult<{
+        proposedDoc: JSONContent;
+        explanation?: string;
+    }>>;
+    /** 根据模板 ID 获取问法与 Tiptap JSON 正文。
+     * @en Load a template's question and Tiptap JSON document by ID.
+     */
+    getReasoningTemplate?: (input: {
+        templateId: string;
+    }, ctx: PortRequestContext) => Promise<PortResult<{
+        question: string;
+        doc: JSONContent;
+    }>>;
+    /** 获取工具权限及动态表单字段；宿主须在此校验业务权限。
+     * @en Load tool permission and dynamic fields; the host must enforce business access here.
+     */
+    getToolForm?: (input: {
+        toolId: string;
+    }, ctx: PortRequestContext) => Promise<PortResult<ToolFormDefinition>>;
+    /** 打开已选 Agent 的配置页；应在点击回调开始时同步新开标签页。
+     * @en Open the selected Agent's configuration in a new tab synchronously on click.
+     */
+    openAgentConfig?: (input: {
+        agentId: string;
+        target: '_blank';
+    }, ctx: PortRequestContext) => Promise<PortResult<void>>;
+}
+export interface FkpRichTextProps {
+    /** 场景的稳定键，同一条件内唯一；切换键会重置当前交互状态。
+     * @en Stable scene key, unique within a condition; changing it resets transient UI state.
+     * @defaultValue 'default'
+     */
+    sceneKey: string;
+    /** 受控的单场景数据；通过 update:modelValue 回写。
+     * @en Controlled single-scene data, updated through update:modelValue.
+     * @defaultValue emptyScene()
+     */
+    modelValue: KnowledgeSceneV1;
+    /** 配置中心和页面级能力规则。
+     * @en Remote and page-level capability rules.
+     */
+    config?: SceneConfigLayersV1;
+    /** 宿主权限快照；过期或无效时禁止编辑。
+     * @en Host authorization snapshot; expired or invalid snapshots lock editing.
+     */
+    policy?: HostPolicySnapshotV1;
+    /** 宿主提供的异步业务接口；组件不直接发 HTTP 请求。
+     * @en Asynchronous host business ports; the component makes no direct HTTP calls.
+     */
+    ports?: RichTextHostPorts;
+    /** 宿主已接收的 change 修订号；配合受控回显避免旧值覆盖新编辑。
+     * @en Last acknowledged change revision, preventing stale controlled echoes.
+     * @defaultValue 0
+     */
+    ackRevision?: number;
+    /** 只读展示。
+     * @en Read-only rendering.
+     * @defaultValue false
+     */
+    readonly?: boolean;
+    /** 禁用编辑交互。
+     * @en Disable editing interactions.
+     * @defaultValue false
+     */
+    disabled?: boolean;
+}
+export interface FkpRichTextHandle {
+    /** 撤销最近一次尚未被后续编辑覆盖的知识类型切换。
+     * @en Undo the most recent uninterrupted knowledge type switch.
+     */
+    undoTypeSwitch(): boolean;
+}
+export declare const emptyDoc: () => JSONContent;
+export declare const emptyScene: (type?: KnowledgeType) => KnowledgeSceneV1;

package/dist/types/rich-text/runtime/action-ports.d.ts

@@ -0,0 +1,15 @@
+import { hostActions, CapabilityDescriptor } from '../config/descriptor';
+import { RichTextHostPorts } from '../public/types';
+type HostAction = (typeof hostActions)[keyof typeof hostActions];
+export type HostActionId = HostAction['id'];
+type HostActionPort<A extends HostActionId> = Extract<HostAction, {
+    id: A;
+}>['requiredPorts'][number];
+export type ActionPorts<A extends HostActionId> = Readonly<Required<Pick<RichTextHostPorts, HostActionPort<A>>>>;
+/** Only callbacks named by this action enter its execution context. */
+export declare function projectDeclaredPorts(descriptor: CapabilityDescriptor, actionId: string, ports: RichTextHostPorts | undefined): Readonly<Partial<RichTextHostPorts>> | null;
+/** Read-only view data is projected without creating an editor action. */
+export declare function projectReadPorts(descriptor: CapabilityDescriptor, ports: RichTextHostPorts | undefined): Readonly<Partial<RichTextHostPorts>> | null;
+/** Typed host wrapper; the runtime port list comes from the descriptor. */
+export declare function projectActionPorts<A extends HostActionId>(actionId: A, ports: RichTextHostPorts | undefined): ActionPorts<A> | null;
+export {};

package/dist/types/rich-text/runtime/media-state.d.ts

@@ -0,0 +1,6 @@
+/** Versioned state read from a media node before an asynchronous update. */
+export interface MediaNodeState {
+    kind: 'image' | 'video';
+    status: 'ready' | 'uploading' | 'error';
+    nodeVersion: number;
+}

package/dist/types/rich-text/runtime/media-target.d.ts

@@ -0,0 +1,8 @@
+import { Editor, JSONContent } from '@tiptap/core';
+export interface MediaTarget {
+    insert(content: JSONContent | JSONContent[]): boolean;
+    status(): 'ready' | 'lost' | 'disposed';
+    dispose(): void;
+}
+export declare function captureMediaTarget(editor: Editor): MediaTarget;
+export declare function captureMediaTargetAt(editor: Editor, clientX: number, clientY: number): MediaTarget | null;

package/dist/types/rich-text/runtime/media-upload-session.d.ts

@@ -0,0 +1,59 @@
+import { ResolvedCapability } from '../config/resolve';
+import { MediaTarget } from './media-target';
+import { MediaNodeState } from './media-state';
+import { PluginPlan } from './operations';
+import { KnowledgeSceneV1, PortRequestContext, PortResult, RichTextHostPorts } from '../public/types';
+import { MediaKind } from '../model/node-contract';
+type PortError = Extract<PortResult<unknown>, {
+    ok: false;
+}>['error'];
+type UpdatePlan = Extract<PluginPlan, {
+    kind: 'updateNode';
+}>;
+interface MediaEditor {
+    insertPendingMedia(file: File, kind: MediaKind, target: MediaTarget): string | null;
+    getMediaState(id: string): MediaNodeState | null;
+    failMedia(id: string, message: string, expectedVersion: number): boolean;
+    retryMedia(id: string, expectedVersion: number): boolean;
+    reportMediaProgress(id: string, expectedVersion: number, percent: number): boolean;
+    focus(): void;
+}
+export interface UploadRetention {
+    active: Set<string>;
+    files: Set<string>;
+    markFailed: Array<{
+        id: string;
+        nodeVersion: number;
+    }>;
+}
+export interface MediaUploadSessionHost {
+    editor(): MediaEditor | undefined;
+    capability(kind: MediaKind): ResolvedCapability | undefined;
+    canUse(kind: MediaKind): boolean;
+    scene(): {
+        scene: KnowledgeSceneV1;
+        sceneKey: string;
+        revision: number;
+    };
+    sceneKey(): string;
+    ports(): RichTextHostPorts | undefined;
+    context(kind: MediaKind, controller: AbortController): PortRequestContext;
+    track(controller: AbortController, start: boolean): void;
+    diagnostic(code: string, message: string, source: 'config' | 'plugin' | 'port' | 'validation', kind?: MediaKind): void;
+    portDiagnostic(error: PortError, kind: MediaKind): void;
+    applyNodeUpdate(plan: UpdatePlan, kind: MediaKind): boolean;
+}
+/** Owns upload files, selection bookmark, and async completion across scene changes. */
+export declare function createMediaUploadSession(host: MediaUploadSessionHost): {
+    selectTarget: (target: MediaTarget | null) => void;
+    takeTarget: () => MediaTarget | null;
+    clearTarget: () => void;
+    has: (id: string) => boolean;
+    removeAbsent: (present: ReadonlySet<string>) => void;
+    classify: (currentScene: KnowledgeSceneV1, next: KnowledgeSceneV1) => UploadRetention;
+    activeControllers: (active: ReadonlySet<string>) => Set<AbortController>;
+    retain: (retention?: UploadRetention) => void;
+    enqueue: (files: File[], target: MediaTarget, requestedKind?: MediaKind, restoreFocus?: boolean) => Promise<void>;
+    retry: (id: string) => void;
+};
+export {};