@klarkxy/dsh-plugin-kit 0.1.0

package/lib/host-rpc.d.ts

@@ -0,0 +1,20 @@
+import { RpcResult } from "./contracts.js";
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/host-rpc.d.ts
+interface HostRpcContext {
+  webServer: {
+    register(route: {
+      kind: 'prefix';
+      path: string;
+      handler(req: IncomingMessage, res: ServerResponse): void | Promise<void>;
+    }): () => void;
+  };
+  connection: {
+    requestRejection?: (request: IncomingMessage) => number | undefined;
+  };
+}
+/** Safe host RPC registration. Missing requestRejection fails closed. Result type accepts any RpcResult shape. */
+declare function registerHostRpc<R extends RpcResult = RpcResult>(ctx: HostRpcContext, channel: string, call: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<R>): () => void;
+//#endregion
+export { HostRpcContext, registerHostRpc };
+//# sourceMappingURL=host-rpc.d.ts.map

package/lib/host-rpc.js

@@ -0,0 +1,95 @@
+//#region src/host-rpc.ts
+/** Safe host RPC registration. Missing requestRejection fails closed. Result type accepts any RpcResult shape. */
+function registerHostRpc(ctx, channel, call) {
+	return ctx.webServer.register({
+		kind: "prefix",
+		path: channel,
+		handler: async (req, res) => {
+			if (!ctx.connection.requestRejection) {
+				res.writeHead(503);
+				res.end();
+				return;
+			}
+			const rejection = ctx.connection.requestRejection(req);
+			if (rejection !== void 0) {
+				res.writeHead(rejection);
+				res.end();
+				return;
+			}
+			const pathname = new URL(req.url ?? "/", "http://dsh.internal").pathname;
+			const endpoint = pathname.startsWith(`${channel}/`) ? pathname.slice(channel.length + 1) : "";
+			if (req.method !== "POST" || !/^[a-z.]+$/.test(endpoint)) {
+				res.writeHead(404);
+				res.end();
+				return;
+			}
+			if (String(req.headers["content-type"] ?? "").split(";")[0]?.trim() !== "application/json") {
+				res.writeHead(415);
+				res.end();
+				return;
+			}
+			const controller = new AbortController();
+			res.on("close", () => {
+				if (!res.writableEnded) controller.abort();
+			});
+			try {
+				const chunks = [];
+				let size = 0;
+				for await (const chunk of req) {
+					const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+					size += buffer.length;
+					if (size > 65536) {
+						res.writeHead(413, { connection: "close" });
+						res.end();
+						req.destroy();
+						return;
+					}
+					chunks.push(buffer);
+				}
+				let request;
+				try {
+					const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+					if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+					request = parsed;
+				} catch {
+					res.writeHead(400);
+					res.end();
+					return;
+				}
+				if (request.type !== "client-request" || request.method !== endpoint || typeof request.rpcId !== "string") {
+					res.writeHead(400);
+					res.end();
+					return;
+				}
+				const raw = await call(endpoint, request.payload, controller.signal);
+				const result = raw.ok ? raw : {
+					...raw,
+					error: {
+						details: {},
+						...raw.error
+					}
+				};
+				if (!res.destroyed) {
+					res.writeHead(200, {
+						"content-type": "application/json",
+						"cache-control": "no-store"
+					});
+					res.end(JSON.stringify({
+						type: "server-response",
+						rpcId: request.rpcId,
+						result
+					}));
+				}
+			} catch {
+				if (!res.destroyed) {
+					res.writeHead(500);
+					res.end("rpc request failed");
+				}
+			}
+		}
+	});
+}
+//#endregion
+export { registerHostRpc };
+
+//# sourceMappingURL=host-rpc.js.map

package/lib/host-rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-rpc.js","names":[],"sources":["../src/host-rpc.ts"],"sourcesContent":["import type { IncomingMessage, ServerResponse } from 'node:http'\nimport type { RpcResult } from './contracts.ts'\n\nexport interface HostRpcContext {\n  webServer: { register(route: { kind: 'prefix'; path: string; handler(req: IncomingMessage, res: ServerResponse): void | Promise<void> }): () => void }\n  connection: { requestRejection?: (request: IncomingMessage) => number | undefined }\n}\n\n/** Safe host RPC registration. Missing requestRejection fails closed. Result type accepts any RpcResult shape. */\nexport function registerHostRpc<R extends RpcResult = RpcResult>(\n  ctx: HostRpcContext,\n  channel: string,\n  call: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<R>,\n): () => void {\n  return ctx.webServer.register({ kind: 'prefix', path: channel, handler: async (req, res) => {\n    // Require the host's origin/auth policy. Missing policy must not expose settings.\n    if (!ctx.connection.requestRejection) { res.writeHead(503); res.end(); return }\n    const rejection = ctx.connection.requestRejection(req)\n    if (rejection !== undefined) { res.writeHead(rejection); res.end(); return }\n    const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname\n    const endpoint = pathname.startsWith(`${channel}/`) ? pathname.slice(channel.length + 1) : ''\n    if (req.method !== 'POST' || !/^[a-z.]+$/.test(endpoint)) { res.writeHead(404); res.end(); return }\n    if (String(req.headers['content-type'] ?? '').split(';')[0]?.trim() !== 'application/json') {\n      res.writeHead(415); res.end(); return\n    }\n    const controller = new AbortController()\n    res.on('close', () => { if (!res.writableEnded) controller.abort() })\n    try {\n      const chunks: Buffer[] = []\n      let size = 0\n      for await (const chunk of req) {\n        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)\n        size += buffer.length\n        if (size > 64 * 1024) { res.writeHead(413, { connection: 'close' }); res.end(); req.destroy(); return }\n        chunks.push(buffer)\n      }\n      let request: Record<string, unknown>\n      try {\n        const parsed: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'))\n        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error()\n        request = parsed as Record<string, unknown>\n      } catch { res.writeHead(400); res.end(); return }\n      if (request.type !== 'client-request' || request.method !== endpoint || typeof request.rpcId !== 'string') {\n        res.writeHead(400); res.end(); return\n      }\n      const raw = await call(endpoint, request.payload, controller.signal)\n      const result = raw.ok ? raw : { ...raw, error: { details: {}, ...raw.error } }\n      if (!res.destroyed) {\n        res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' })\n        res.end(JSON.stringify({ type: 'server-response', rpcId: request.rpcId, result }))\n      }\n    } catch {\n      if (!res.destroyed) { res.writeHead(500); res.end('rpc request failed') }\n    }\n  } })\n}\n"],"mappings":";;AASA,SAAgB,gBACd,KACA,SACA,MACY;CACZ,OAAO,IAAI,UAAU,SAAS;EAAE,MAAM;EAAU,MAAM;EAAS,SAAS,OAAO,KAAK,QAAQ;GAE1F,IAAI,CAAC,IAAI,WAAW,kBAAkB;IAAE,IAAI,UAAU,GAAG;IAAG,IAAI,IAAI;IAAG;GAAO;GAC9E,MAAM,YAAY,IAAI,WAAW,iBAAiB,GAAG;GACrD,IAAI,cAAc,KAAA,GAAW;IAAE,IAAI,UAAU,SAAS;IAAG,IAAI,IAAI;IAAG;GAAO;GAC3E,MAAM,WAAW,IAAI,IAAI,IAAI,OAAO,KAAK,qBAAqB,CAAC,CAAC;GAChE,MAAM,WAAW,SAAS,WAAW,GAAG,QAAQ,EAAE,IAAI,SAAS,MAAM,QAAQ,SAAS,CAAC,IAAI;GAC3F,IAAI,IAAI,WAAW,UAAU,CAAC,YAAY,KAAK,QAAQ,GAAG;IAAE,IAAI,UAAU,GAAG;IAAG,IAAI,IAAI;IAAG;GAAO;GAClG,IAAI,OAAO,IAAI,QAAQ,mBAAmB,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,MAAM,oBAAoB;IAC1F,IAAI,UAAU,GAAG;IAAG,IAAI,IAAI;IAAG;GACjC;GACA,MAAM,aAAa,IAAI,gBAAgB;GACvC,IAAI,GAAG,eAAe;IAAE,IAAI,CAAC,IAAI,eAAe,WAAW,MAAM;GAAE,CAAC;GACpE,IAAI;IACF,MAAM,SAAmB,CAAC;IAC1B,IAAI,OAAO;IACX,WAAW,MAAM,SAAS,KAAK;KAC7B,MAAM,SAAS,OAAO,SAAS,KAAK,IAAI,QAAQ,OAAO,KAAK,KAAK;KACjE,QAAQ,OAAO;KACf,IAAI,OAAO,OAAW;MAAE,IAAI,UAAU,KAAK,EAAE,YAAY,QAAQ,CAAC;MAAG,IAAI,IAAI;MAAG,IAAI,QAAQ;MAAG;KAAO;KACtG,OAAO,KAAK,MAAM;IACpB;IACA,IAAI;IACJ,IAAI;KACF,MAAM,SAAkB,KAAK,MAAM,OAAO,OAAO,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC;KACzE,IAAI,CAAC,UAAU,OAAO,WAAW,YAAY,MAAM,QAAQ,MAAM,GAAG,MAAM,IAAI,MAAM;KACpF,UAAU;IACZ,QAAQ;KAAE,IAAI,UAAU,GAAG;KAAG,IAAI,IAAI;KAAG;IAAO;IAChD,IAAI,QAAQ,SAAS,oBAAoB,QAAQ,WAAW,YAAY,OAAO,QAAQ,UAAU,UAAU;KACzG,IAAI,UAAU,GAAG;KAAG,IAAI,IAAI;KAAG;IACjC;IACA,MAAM,MAAM,MAAM,KAAK,UAAU,QAAQ,SAAS,WAAW,MAAM;IACnE,MAAM,SAAS,IAAI,KAAK,MAAM;KAAE,GAAG;KAAK,OAAO;MAAE,SAAS,CAAC;MAAG,GAAG,IAAI;KAAM;IAAE;IAC7E,IAAI,CAAC,IAAI,WAAW;KAClB,IAAI,UAAU,KAAK;MAAE,gBAAgB;MAAoB,iBAAiB;KAAW,CAAC;KACtF,IAAI,IAAI,KAAK,UAAU;MAAE,MAAM;MAAmB,OAAO,QAAQ;MAAO;KAAO,CAAC,CAAC;IACnF;GACF,QAAQ;IACN,IAAI,CAAC,IAAI,WAAW;KAAE,IAAI,UAAU,GAAG;KAAG,IAAI,IAAI,oBAAoB;IAAE;GAC1E;EACF;CAAE,CAAC;AACL"}

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+import { AiFeatureScope, AiPolicy, AiServices, AuxiliaryRequest, AuxiliaryResult, CHAT_EVENTS_SLOT, ContextKnowledge, EvidenceRef, KnowledgeKind, KnowledgeScope, MemoryMutationOptions, MemoryQuery, MemoryRecord, MemoryService, ModelRole, ModelRoute, ModelTarget, NewMemoryRecord, ProcedureKnowledge, ProducerMessageSource, ProducerSourceKind, PurposeSpec, ResolvedRoute, RpcResult, SubagentSessionLike, TaskCheckpoint, TaskContract, UsageReceipt, isSubagentSession, producerMessageSource, projectIdFromCwd } from "./contracts.js";
+import { HostRpcContext, registerHostRpc } from "./host-rpc.js";
+import { FeatureModelRoute, LlmTextCaller, callLlmText, resolveFeatureModel } from "./llm-call.js";
+export { type AiFeatureScope, type AiPolicy, type AiServices, type AuxiliaryRequest, type AuxiliaryResult, CHAT_EVENTS_SLOT, type ContextKnowledge, type EvidenceRef, type FeatureModelRoute, type HostRpcContext, type KnowledgeKind, type KnowledgeScope, type LlmTextCaller, type MemoryMutationOptions, type MemoryQuery, type MemoryRecord, type MemoryService, type ModelRole, type ModelRoute, type ModelTarget, type NewMemoryRecord, type ProcedureKnowledge, type ProducerMessageSource, type ProducerSourceKind, type PurposeSpec, type ResolvedRoute, type RpcResult, type SubagentSessionLike, type TaskCheckpoint, type TaskContract, type UsageReceipt, callLlmText, type isSubagentSession, producerMessageSource, projectIdFromCwd, registerHostRpc, resolveFeatureModel };

package/lib/index.js

@@ -0,0 +1,4 @@
+import { CHAT_EVENTS_SLOT, producerMessageSource, projectIdFromCwd } from "./contracts.js";
+import { registerHostRpc } from "./host-rpc.js";
+import { callLlmText, resolveFeatureModel } from "./llm-call.js";
+export { CHAT_EVENTS_SLOT, callLlmText, producerMessageSource, projectIdFromCwd, registerHostRpc, resolveFeatureModel };

package/lib/llm-call.d.ts

@@ -0,0 +1,36 @@
+import { GenerateOptions, LlmRuntime } from "@deepseek-ai/dsh-llm";
+//#region src/llm-call.d.ts
+/** A feature's own saved model. Empty means the host default chat model. */
+interface FeatureModelRoute {
+  readonly provider: string;
+  readonly model: string;
+  readonly reasoningEffort?: string;
+}
+type LlmTextCaller = Pick<LlmRuntime, 'prepareCall' | 'resolveCallConfig'>;
+interface LlmTextRequest {
+  plugin: string;
+  route: FeatureModelRoute;
+  system: string;
+  text: string;
+  maxTokens: number;
+  signal: AbortSignal;
+  sessionId?: string;
+  /** Auxiliary-call marker adapters may special-case (e.g. disable thinking for titles). */
+  purpose?: GenerateOptions['purpose'];
+  /** Rechecked before the call returns text. A false result discards the output. */
+  isCurrent?: () => boolean;
+}
+interface LlmTextResult {
+  text: string;
+  provider: string;
+  model: string;
+  inputTokens?: number;
+  outputTokens?: number;
+}
+/** Plugin selection first; otherwise the live session model, then the host default. */
+declare function resolveFeatureModel(host: unknown, saved: FeatureModelRoute | undefined, sessionId?: string): FeatureModelRoute | undefined;
+/** One native model call. No retry, timeout policy, or provider queue. */
+declare function callLlmText(llm: LlmTextCaller, request: LlmTextRequest): Promise<LlmTextResult>;
+//#endregion
+export { FeatureModelRoute, LlmTextCaller, LlmTextRequest, LlmTextResult, callLlmText, resolveFeatureModel };
+//# sourceMappingURL=llm-call.d.ts.map

package/lib/llm-call.js

@@ -0,0 +1,118 @@
+import { producerMessageSource } from "./contracts.js";
+import { BlockAssembler, ReasoningEffortId, createUserMessage } from "@deepseek-ai/dsh-llm";
+//#region src/llm-call.ts
+function routeOf(value) {
+	if (typeof value?.provider !== "string" || !value.provider.trim()) return void 0;
+	if (typeof value.model !== "string" || !value.model.trim()) return void 0;
+	const effort = typeof value.reasoningEffort === "string" ? value.reasoningEffort.trim() : "";
+	return effort ? {
+		provider: value.provider.trim(),
+		model: value.model.trim(),
+		reasoningEffort: effort
+	} : {
+		provider: value.provider.trim(),
+		model: value.model.trim()
+	};
+}
+/** Plugin selection first; otherwise the live session model, then the host default. */
+function resolveFeatureModel(host, saved, sessionId) {
+	const explicit = routeOf(saved);
+	if (explicit) return explicit;
+	const face = host;
+	if (sessionId && face?.agents && face.sessionProjections) {
+		const session = face.agents.get(sessionId)?.session;
+		if (session) {
+			try {
+				const pending = face.sessionProjections.stateOf(session, "modelSelection")?.pending;
+				const selected = routeOf(pending ?? void 0);
+				if (selected) return selected;
+			} catch {}
+			const header = session.requestHeader?.();
+			const recorded = header?.config;
+			if (recorded) {
+				const route = routeOf(header?.adapterDefaults?.reasoningEffort === true ? {
+					provider: recorded.provider,
+					model: recorded.model
+				} : recorded);
+				if (route) return route;
+			}
+		}
+	}
+	return routeOf(face?.agentDefaultModel?.currentSelection());
+}
+function joinText(assembler) {
+	return assembler.blocks().filter((block) => block.type === "text").map((block) => block.text).join("");
+}
+async function readStream(stream, signal, live) {
+	const assembler = new BlockAssembler();
+	const iterator = stream[Symbol.asyncIterator]();
+	try {
+		while (live()) {
+			if (signal.aborted) break;
+			const item = await iterator.next();
+			if (item.done) break;
+			assembler.push(item.value);
+		}
+	} finally {
+		try {
+			const closing = iterator.return?.();
+			if (closing) closing.catch(() => {});
+		} catch {}
+	}
+	return assembler;
+}
+/** One native model call. No retry, timeout policy, or provider queue. */
+async function callLlmText(llm, request) {
+	request.signal.throwIfAborted();
+	const live = () => request.isCurrent?.() !== false && !request.signal.aborted;
+	if (!live()) throw Object.assign(/* @__PURE__ */ new Error("调用已取消。"), { name: "AbortError" });
+	const effort = request.route.reasoningEffort?.trim();
+	const prepared = await llm.prepareCall({
+		provider: request.route.provider,
+		model: request.route.model,
+		...effort ? { reasoningEffort: ReasoningEffortId(effort) } : {},
+		maxTokens: request.maxTokens
+	}, request.signal);
+	if (!live()) throw Object.assign(/* @__PURE__ */ new Error("调用已取消。"), { name: "AbortError" });
+	const options = {
+		provider: prepared.config.provider,
+		model: prepared.config.model,
+		...prepared.config.reasoningEffort ? { reasoningEffort: prepared.config.reasoningEffort } : {},
+		...prepared.config.maxTokens !== void 0 ? { maxTokens: Math.min(request.maxTokens, prepared.config.maxTokens) } : { maxTokens: request.maxTokens },
+		...prepared.config.temperature !== void 0 ? { temperature: prepared.config.temperature } : {},
+		...prepared.config.stop ? { stop: [...prepared.config.stop] } : {},
+		system: request.system,
+		messages: [createUserMessage({
+			source: producerMessageSource(request.plugin),
+			content: [{
+				type: "text",
+				text: request.text
+			}]
+		})],
+		signal: request.signal,
+		...request.purpose ? { purpose: request.purpose } : {},
+		...request.sessionId ? { sessionId: request.sessionId } : {}
+	};
+	const assembler = await readStream(prepared.stream(options), request.signal, live);
+	if (request.signal.aborted || assembler.finish.kind === "aborted") throw Object.assign(/* @__PURE__ */ new Error("调用已取消。"), { name: "AbortError" });
+	if (!live()) throw Object.assign(/* @__PURE__ */ new Error("调用已取消。"), { name: "AbortError" });
+	if (assembler.finish.kind === "error") {
+		const code = assembler.finish.failure.code;
+		throw Object.assign(new Error(assembler.finish.failure.message || "模型调用失败。"), { code });
+	}
+	if (assembler.blocks().some((block) => block.type === "tool-call") || assembler.finish.kind === "tool-calls") throw new Error("这次调用不使用工具。");
+	if (assembler.finish.kind !== "stop") throw new Error("模型调用未完成。");
+	return {
+		text: joinText(assembler),
+		provider: prepared.config.provider,
+		model: prepared.config.model,
+		...assembler.usage ? {
+			inputTokens: assembler.usage.inputTokens,
+			outputTokens: assembler.usage.outputTokens
+		} : {}
+	};
+}
+//#endregion
+export { callLlmText, resolveFeatureModel };
+
+//# sourceMappingURL=llm-call.js.map

package/lib/llm-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-call.js","names":[],"sources":["../src/llm-call.ts"],"sourcesContent":["import {\n  BlockAssembler, ReasoningEffortId, createUserMessage,\n  type GenerateOptions, type LlmRuntime, type StreamChunk,\n} from '@deepseek-ai/dsh-llm'\nimport { producerMessageSource, type ModelRoute } from './contracts.ts'\n\n/** A feature's own saved model. Empty means the host default chat model. */\nexport interface FeatureModelRoute {\n  readonly provider: string\n  readonly model: string\n  readonly reasoningEffort?: string\n}\n\nexport type LlmTextCaller = Pick<LlmRuntime, 'prepareCall' | 'resolveCallConfig'>\n\nexport interface LlmTextRequest {\n  plugin: string\n  route: FeatureModelRoute\n  system: string\n  text: string\n  maxTokens: number\n  signal: AbortSignal\n  sessionId?: string\n  /** Auxiliary-call marker adapters may special-case (e.g. disable thinking for titles). */\n  purpose?: GenerateOptions['purpose']\n  /** Rechecked before the call returns text. A false result discards the output. */\n  isCurrent?: () => boolean\n}\n\nexport interface LlmTextResult {\n  text: string\n  provider: string\n  model: string\n  inputTokens?: number\n  outputTokens?: number\n}\n\ntype SessionModelsHost = {\n  agents?: { get(sessionId: string): { session?: { requestHeader?: () => { config?: ModelRoute; adapterDefaults?: { reasoningEffort?: unknown } } | undefined } } | undefined }\n  sessionProjections?: { stateOf(session: unknown, key: string): { pending?: ModelRoute | null } | undefined }\n  agentDefaultModel?: { currentSelection(): ModelRoute | undefined }\n}\n\nfunction routeOf(value: { provider?: unknown; model?: unknown; reasoningEffort?: unknown } | undefined): FeatureModelRoute | undefined {\n  if (typeof value?.provider !== 'string' || !value.provider.trim()) return undefined\n  if (typeof value.model !== 'string' || !value.model.trim()) return undefined\n  const effort = typeof value.reasoningEffort === 'string' ? value.reasoningEffort.trim() : ''\n  return effort\n    ? { provider: value.provider.trim(), model: value.model.trim(), reasoningEffort: effort }\n    : { provider: value.provider.trim(), model: value.model.trim() }\n}\n\n/** Plugin selection first; otherwise the live session model, then the host default. */\nexport function resolveFeatureModel(host: unknown, saved: FeatureModelRoute | undefined, sessionId?: string): FeatureModelRoute | undefined {\n  const explicit = routeOf(saved)\n  if (explicit) return explicit\n  const face = host as SessionModelsHost | undefined\n  if (sessionId && face?.agents && face.sessionProjections) {\n    const session = face.agents.get(sessionId)?.session\n    if (session) {\n      try {\n        const pending = face.sessionProjections.stateOf(session, 'modelSelection')?.pending\n        const selected = routeOf(pending ?? undefined)\n        if (selected) return selected\n      } catch { /* fall through to the recorded route */ }\n      const header = session.requestHeader?.()\n      const recorded = header?.config\n      if (recorded) {\n        const selected = header?.adapterDefaults?.reasoningEffort === true\n          ? { provider: recorded.provider, model: recorded.model }\n          : recorded\n        const route = routeOf(selected)\n        if (route) return route\n      }\n    }\n  }\n  return routeOf(face?.agentDefaultModel?.currentSelection())\n}\n\nfunction joinText(assembler: BlockAssembler): string {\n  return assembler.blocks()\n    .filter((block): block is { type: 'text'; text: string } => block.type === 'text')\n    .map(block => block.text)\n    .join('')\n}\n\nasync function readStream(stream: AsyncIterable<StreamChunk>, signal: AbortSignal, live: () => boolean): Promise<BlockAssembler> {\n  const assembler = new BlockAssembler()\n  const iterator = stream[Symbol.asyncIterator]()\n  try {\n    while (live()) {\n      if (signal.aborted) break\n      const item = await iterator.next()\n      if (item.done) break\n      assembler.push(item.value)\n    }\n  } finally {\n    try { const closing = iterator.return?.(); if (closing) void closing.catch(() => {}) } catch { /* producer ignored abort */ }\n  }\n  return assembler\n}\n\n/** One native model call. No retry, timeout policy, or provider queue. */\nexport async function callLlmText(llm: LlmTextCaller, request: LlmTextRequest): Promise<LlmTextResult> {\n  request.signal.throwIfAborted()\n  const live = () => request.isCurrent?.() !== false && !request.signal.aborted\n  if (!live()) throw Object.assign(new Error('调用已取消。'), { name: 'AbortError' })\n  const effort = request.route.reasoningEffort?.trim()\n  const prepared = await llm.prepareCall({\n    provider: request.route.provider,\n    model: request.route.model,\n    ...(effort ? { reasoningEffort: ReasoningEffortId(effort) } : {}),\n    maxTokens: request.maxTokens,\n  }, request.signal)\n  if (!live()) throw Object.assign(new Error('调用已取消。'), { name: 'AbortError' })\n  const options: GenerateOptions = {\n    provider: prepared.config.provider,\n    model: prepared.config.model,\n    ...(prepared.config.reasoningEffort ? { reasoningEffort: prepared.config.reasoningEffort } : {}),\n    ...(prepared.config.maxTokens !== undefined ? { maxTokens: Math.min(request.maxTokens, prepared.config.maxTokens) } : { maxTokens: request.maxTokens }),\n    ...(prepared.config.temperature !== undefined ? { temperature: prepared.config.temperature } : {}),\n    ...(prepared.config.stop ? { stop: [...prepared.config.stop] } : {}),\n    system: request.system,\n    messages: [createUserMessage({\n      source: producerMessageSource(request.plugin),\n      content: [{ type: 'text', text: request.text }],\n    })],\n    signal: request.signal,\n    ...(request.purpose ? { purpose: request.purpose } : {}),\n    ...(request.sessionId ? { sessionId: request.sessionId as GenerateOptions['sessionId'] } : {}),\n  }\n  const assembler = await readStream(prepared.stream(options), request.signal, live)\n  if (request.signal.aborted || assembler.finish.kind === 'aborted') {\n    throw Object.assign(new Error('调用已取消。'), { name: 'AbortError' })\n  }\n  if (!live()) throw Object.assign(new Error('调用已取消。'), { name: 'AbortError' })\n  if (assembler.finish.kind === 'error') {\n    const code = assembler.finish.failure.code\n    throw Object.assign(new Error(assembler.finish.failure.message || '模型调用失败。'), { code })\n  }\n  if (assembler.blocks().some(block => block.type === 'tool-call') || assembler.finish.kind === 'tool-calls') {\n    throw new Error('这次调用不使用工具。')\n  }\n  if (assembler.finish.kind !== 'stop') throw new Error('模型调用未完成。')\n  return {\n    text: joinText(assembler),\n    provider: prepared.config.provider,\n    model: prepared.config.model,\n    ...(assembler.usage ? { inputTokens: assembler.usage.inputTokens, outputTokens: assembler.usage.outputTokens } : {}),\n  }\n}\n"],"mappings":"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"}

package/lib/model-menu.d.ts

@@ -0,0 +1,42 @@
+import { ModelRoute } from "./contracts.js";
+//#region src/model-menu.d.ts
+/** One selectable model. `efforts` are the advertised reasoning efforts. */
+interface ModelMenuChoice {
+  readonly provider: string;
+  readonly model: string;
+  readonly label: string;
+  readonly efforts: ReadonlyArray<{
+    id: string;
+    name: string;
+  }>;
+}
+/** The stored selection. Empty provider/model means "follow the default". */
+type ModelMenuRoute = ModelRoute;
+/** The catalog face this helper needs; stays structural so hosts may add more. */
+interface ModelCatalogClient {
+  readonly remote?: {
+    readonly session?: {
+      readonly modelCatalog?: () => Promise<unknown>;
+    };
+  };
+}
+declare function modelMenuChoiceKey(provider: string, model: string): string;
+declare function parseModelMenuChoiceKey(value: string): {
+  provider: string;
+  model: string;
+} | undefined;
+/** Parse the host session catalog into flat choices, keeping a saved route selectable. */
+declare function parseModelMenuChoices(value: unknown, bound?: ModelMenuRoute): ModelMenuChoice[];
+/** An empty saved route means no explicit model. */
+declare function modelMenuOverride(route: ModelMenuRoute | undefined): ModelRoute | undefined;
+declare function normalizeModelMenuRoute(value: unknown): ModelMenuRoute;
+/** Load the host catalog once per mount and republish whenever it answers. */
+declare function useModelMenuChoices(client: ModelCatalogClient, bound?: ModelMenuRoute): ModelMenuChoice[];
+/** Reasoning-effort options for one choice; the saved value stays selectable. */
+declare function modelMenuEffortOptions(choice: ModelMenuChoice | undefined, current?: string): Array<{
+  id: string;
+  name: string;
+}>;
+//#endregion
+export { ModelCatalogClient, ModelMenuChoice, ModelMenuRoute, modelMenuChoiceKey, modelMenuEffortOptions, modelMenuOverride, normalizeModelMenuRoute, parseModelMenuChoiceKey, parseModelMenuChoices, useModelMenuChoices };
+//# sourceMappingURL=model-menu.d.ts.map

package/lib/model-menu.js

@@ -0,0 +1,152 @@
+import { useEffect, useState } from "react";
+//#region src/model-menu.ts
+/**
+* Shared plugin-page model menu.
+*
+* A feature plugin's own settings row exposes a model select. An empty
+* selection means the host default chat model for that feature's own call.
+*
+* Browser-safe and React-optional: pure helpers live here so hosts and clients
+* share one catalog contract without bundling React into the host build.
+*/
+const KEY_SEPARATOR = "";
+function modelMenuChoiceKey(provider, model) {
+	return provider && model ? `${provider}${KEY_SEPARATOR}${model}` : "";
+}
+function parseModelMenuChoiceKey(value) {
+	const index = value.indexOf(KEY_SEPARATOR);
+	if (index <= 0) return void 0;
+	const provider = value.slice(0, index);
+	const model = value.slice(index + 1);
+	if (!provider || !model) return void 0;
+	return {
+		provider,
+		model
+	};
+}
+function asRecord(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function asText(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function parseEffort(value) {
+	const row = asRecord(value);
+	const id = row ? asText(row.id) : void 0;
+	if (!id) return void 0;
+	return {
+		id,
+		name: row ? asText(row.name) ?? id : id
+	};
+}
+/** Parse the host session catalog into flat choices, keeping a saved route selectable. */
+function parseModelMenuChoices(value, bound) {
+	const envelope = asRecord(value);
+	const root = (envelope && envelope.ok === true ? asRecord(envelope.value) : void 0) ?? envelope ?? {};
+	const groups = Array.isArray(root.groups) ? root.groups : [];
+	const choices = [];
+	for (const group of groups) {
+		const groupRow = asRecord(group);
+		const provider = groupRow ? asText(groupRow.id) : void 0;
+		if (!provider || !groupRow || !Array.isArray(groupRow.models)) continue;
+		const providerName = asText(groupRow.name) ?? provider;
+		for (const entry of groupRow.models) {
+			const modelRow = asRecord(entry);
+			const model = modelRow ? asText(modelRow.id) : void 0;
+			if (!model || !modelRow) continue;
+			const name = asText(modelRow.name) ?? model;
+			const reasoning = asRecord(modelRow.reasoning);
+			const efforts = reasoning && Array.isArray(reasoning.efforts) ? reasoning.efforts.flatMap((effort) => {
+				const parsed = parseEffort(effort);
+				return parsed ? [parsed] : [];
+			}) : [];
+			choices.push({
+				provider,
+				model,
+				label: `${providerName} / ${name}`,
+				efforts
+			});
+		}
+	}
+	if (bound?.provider && bound.model && !choices.some((item) => item.provider === bound.provider && item.model === bound.model)) choices.push({
+		provider: bound.provider,
+		model: bound.model,
+		label: `${bound.provider} / ${bound.model}`,
+		efforts: []
+	});
+	return choices;
+}
+/** An empty saved route means no explicit model. */
+function modelMenuOverride(route) {
+	const provider = route?.provider?.trim();
+	const model = route?.model?.trim();
+	if (!provider || !model) return void 0;
+	const effort = route?.reasoningEffort?.trim();
+	return effort ? {
+		provider,
+		model,
+		reasoningEffort: effort
+	} : {
+		provider,
+		model
+	};
+}
+function normalizeModelMenuRoute(value) {
+	const row = asRecord(value);
+	if (!row) return {
+		provider: "",
+		model: ""
+	};
+	const provider = asText(row.provider) ?? "";
+	const model = asText(row.model) ?? "";
+	const effort = asText(row.reasoningEffort);
+	if (!provider || !model || provider.length > 250 || model.length > 250) return {
+		provider: "",
+		model: ""
+	};
+	return effort && effort.length <= 80 ? {
+		provider,
+		model,
+		reasoningEffort: effort
+	} : {
+		provider,
+		model
+	};
+}
+/** Load the host catalog once per mount and republish whenever it answers. */
+function useModelMenuChoices(client, bound) {
+	const [choices, setChoices] = useState([]);
+	useEffect(() => {
+		if (typeof document === "undefined") return;
+		let live = true;
+		const load = () => {
+			client.remote?.session?.modelCatalog?.()?.then((value) => {
+				if (live) setChoices(parseModelMenuChoices(value, bound));
+			}).catch(() => {
+				if (live) setChoices([]);
+			});
+		};
+		load();
+		return () => {
+			live = false;
+		};
+	}, [
+		client,
+		bound?.provider,
+		bound?.model
+	]);
+	return choices;
+}
+/** Reasoning-effort options for one choice; the saved value stays selectable. */
+function modelMenuEffortOptions(choice, current) {
+	const listed = (choice?.efforts ?? []).map((item) => ({ ...item }));
+	if (current && !listed.some((item) => item.id === current)) listed.push({
+		id: current,
+		name: current
+	});
+	return listed;
+}
+//#endregion
+export { modelMenuChoiceKey, modelMenuEffortOptions, modelMenuOverride, normalizeModelMenuRoute, parseModelMenuChoiceKey, parseModelMenuChoices, useModelMenuChoices };
+
+//# sourceMappingURL=model-menu.js.map

package/lib/model-menu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-menu.js","names":[],"sources":["../src/model-menu.ts"],"sourcesContent":["/**\n * Shared plugin-page model menu.\n *\n * A feature plugin's own settings row exposes a model select. An empty\n * selection means the host default chat model for that feature's own call.\n *\n * Browser-safe and React-optional: pure helpers live here so hosts and clients\n * share one catalog contract without bundling React into the host build.\n */\nimport { useEffect, useState } from 'react'\nimport type { ModelRoute } from './contracts.ts'\n\n/** One selectable model. `efforts` are the advertised reasoning efforts. */\nexport interface ModelMenuChoice {\n  readonly provider: string\n  readonly model: string\n  readonly label: string\n  readonly efforts: ReadonlyArray<{ id: string; name: string }>\n}\n\n/** The stored selection. Empty provider/model means \"follow the default\". */\nexport type ModelMenuRoute = ModelRoute\n\n/** The catalog face this helper needs; stays structural so hosts may add more. */\nexport interface ModelCatalogClient {\n  readonly remote?: {\n    readonly session?: { readonly modelCatalog?: () => Promise<unknown> }\n  }\n}\n\nconst KEY_SEPARATOR = '\\u001f'\n\nexport function modelMenuChoiceKey(provider: string, model: string): string {\n  return provider && model ? `${provider}${KEY_SEPARATOR}${model}` : ''\n}\n\nexport function parseModelMenuChoiceKey(value: string): { provider: string; model: string } | undefined {\n  const index = value.indexOf(KEY_SEPARATOR)\n  if (index <= 0) return undefined\n  const provider = value.slice(0, index)\n  const model = value.slice(index + KEY_SEPARATOR.length)\n  if (!provider || !model) return undefined\n  return { provider, model }\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined\n}\n\nfunction asText(value: unknown): string | undefined {\n  return typeof value === 'string' && value.trim() ? value.trim() : undefined\n}\n\nfunction parseEffort(value: unknown): { id: string; name: string } | undefined {\n  const row = asRecord(value)\n  const id = row ? asText(row.id) : undefined\n  if (!id) return undefined\n  return { id, name: row ? asText(row.name) ?? id : id }\n}\n\n/** Parse the host session catalog into flat choices, keeping a saved route selectable. */\nexport function parseModelMenuChoices(value: unknown, bound?: ModelMenuRoute): ModelMenuChoice[] {\n  const envelope = asRecord(value)\n  // Host remote calls resolve to a result envelope ({ ok, value }); older hosts\n  // and unit tests hand over the bare catalog. Accept both.\n  const root = (envelope && envelope.ok === true ? asRecord(envelope.value) : undefined) ?? envelope ?? {}\n  const groups = Array.isArray(root.groups) ? root.groups : []\n  const choices: ModelMenuChoice[] = []\n  for (const group of groups) {\n    const groupRow = asRecord(group)\n    const provider = groupRow ? asText(groupRow.id) : undefined\n    if (!provider || !groupRow || !Array.isArray(groupRow.models)) continue\n    const providerName = asText(groupRow.name) ?? provider\n    for (const entry of groupRow.models) {\n      const modelRow = asRecord(entry)\n      const model = modelRow ? asText(modelRow.id) : undefined\n      if (!model || !modelRow) continue\n      const name = asText(modelRow.name) ?? model\n      const reasoning = asRecord(modelRow.reasoning)\n      const efforts = reasoning && Array.isArray(reasoning.efforts)\n        ? reasoning.efforts.flatMap(effort => { const parsed = parseEffort(effort); return parsed ? [parsed] : [] })\n        : []\n      choices.push({ provider, model, label: `${providerName} / ${name}`, efforts })\n    }\n  }\n  if (bound?.provider && bound.model && !choices.some(item => item.provider === bound.provider && item.model === bound.model)) {\n    choices.push({ provider: bound.provider, model: bound.model, label: `${bound.provider} / ${bound.model}`, efforts: [] })\n  }\n  return choices\n}\n\n/** An empty saved route means no explicit model. */\nexport function modelMenuOverride(route: ModelMenuRoute | undefined): ModelRoute | undefined {\n  const provider = route?.provider?.trim()\n  const model = route?.model?.trim()\n  if (!provider || !model) return undefined\n  const effort = route?.reasoningEffort?.trim()\n  return effort ? { provider, model, reasoningEffort: effort } : { provider, model }\n}\n\nexport function normalizeModelMenuRoute(value: unknown): ModelMenuRoute {\n  const row = asRecord(value)\n  if (!row) return { provider: '', model: '' }\n  const provider = asText(row.provider) ?? ''\n  const model = asText(row.model) ?? ''\n  const effort = asText(row.reasoningEffort)\n  if (!provider || !model || provider.length > 250 || model.length > 250) return { provider: '', model: '' }\n  return effort && effort.length <= 80 ? { provider, model, reasoningEffort: effort } : { provider, model }\n}\n\n/** Load the host catalog once per mount and republish whenever it answers. */\nexport function useModelMenuChoices(client: ModelCatalogClient, bound?: ModelMenuRoute): ModelMenuChoice[] {\n  const [choices, setChoices] = useState<ModelMenuChoice[]>([])\n  useEffect(() => {\n    if (typeof document === 'undefined') return\n    let live = true\n    const load = () => {\n      void client.remote?.session?.modelCatalog?.()\n        ?.then(value => { if (live) setChoices(parseModelMenuChoices(value, bound)) })\n        .catch(() => { if (live) setChoices([]) })\n    }\n    load()\n    return () => { live = false }\n  }, [client, bound?.provider, bound?.model])\n  return choices\n}\n\n/** Reasoning-effort options for one choice; the saved value stays selectable. */\nexport function modelMenuEffortOptions(\n  choice: ModelMenuChoice | undefined,\n  current?: string,\n): Array<{ id: string; name: string }> {\n  const listed = (choice?.efforts ?? []).map(item => ({ ...item }))\n  if (current && !listed.some(item => item.id === current)) listed.push({ id: current, name: current })\n  return listed\n}\n"],"mappings":"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"}

package/lib/official-ui.d.ts

@@ -0,0 +1,110 @@
+//#region src/official-ui.d.ts
+/**
+ * Shared contract that keeps every plugin's browser-side UI on the official
+ * DeepSeek Harness Web design language.
+ *
+ * Two rules produce that language, and both are load-bearing here:
+ *
+ * 1. Colour, radius, elevation and focus come from the host theme's real
+ *    `--dsw-*` tokens, written under their own names. Plugins never invent a
+ *    token, never alias the official ones behind a private palette (a private
+ *    alias is just a second, diverging theme), and never carries a literal
+ *    fallback — the host publishes light and dark, and a literal would pin one
+ *    of them. The only non-colour custom properties used are the host's own
+ *    content-font axis and frame clearance.
+ *
+ * 2. Anything the host already ships is used, not reimplemented. Controls come
+ *    from `@deepseek-ai/dsh-client-ui-primitives` (`Button`, `Input`,
+ *    `Checkbox`, `Switch`, `Tag`, `Pill`, `SegmentedControl`, `Menu`, `Modal`,
+ *    `Tooltip`, `Toast`, `DisclosureRow`, `StateDot`, `PathLabel`, the settings
+ *    form suite). This module only styles what primitives do not cover: page
+ *    scaffolding, field layout, banners, empty states and scroll regions.
+ *
+ * The metrics below are transcribed from the primitives' own CSS modules so a
+ * feature panel lines up pixel-for-pixel with a native one: the 14/22 body and
+ * 13/20 compact type tiers, the 0.5px hairline scale, and the elevation family
+ * that draws a surface's edge in its shadow (`border: 0`) instead of a border.
+ */
+/**
+ * Every `--dsw-*` token this repo is allowed to reference, grouped by role.
+ *
+ * Plugins may only colour through this list. It is exported so the guard test
+ * can fail a build when a stylesheet reaches for anything else — the failure
+ * mode this prevents is silent: an unknown token resolves to nothing, so a
+ * border disappears or a label inherits the wrong colour with no error anywhere.
+ */
+declare const OFFICIAL_THEME_TOKENS: {
+  /** Surfaces, from the page up to the topmost nested card. */
+  readonly surface: readonly ["--dsw-alias-bg-base", "--dsw-alias-bg-layer-1", "--dsw-alias-bg-layer-2", "--dsw-alias-bg-layer-3", "--dsw-alias-bg-layer-4", "--dsw-alias-bg-module-platform", "--dsw-alias-bg-overlay"];
+  /** Hairlines. l1 is near-invisible on a menu surface, so menus use l2+. */
+  readonly border: readonly ["--dsw-alias-border-l1", "--dsw-alias-border-l2", "--dsw-alias-border-l3", "--dsw-alias-border-l4"];
+  /** Text. `caption` is menu shortcut text, `dimmed` is placeholder text. */
+  readonly label: readonly ["--dsw-alias-label-primary", "--dsw-alias-label-secondary", "--dsw-alias-label-tertiary", "--dsw-alias-label-caption", "--dsw-alias-label-dimmed", "--dsw-alias-label-error", "--dsw-alias-label-primary-foreground"];
+  /** Interactive fills. The `-danger` hover belongs to destructive rows. */
+  readonly interactive: readonly ["--dsw-alias-interactive-bg-hover", "--dsw-alias-interactive-bg-active", "--dsw-alias-interactive-bg-hover-danger"];
+  /** Accent and status. `business` is the focus ring's default colour. */
+  readonly accent: readonly ["--dsw-alias-brand-primary", "--dsw-alias-button-primary-fill", "--dsw-alias-button-primary-hover", "--dsw-alias-button-tool-bar-fill", "--dsw-alias-button-tool-bar-hover", "--dsw-alias-button-ghost-active-fill", "--dsw-alias-button-ghost-active-border"];
+  readonly state: readonly ["--dsw-alias-state-business-primary", "--dsw-alias-state-success-primary", "--dsw-alias-state-warn-primary", "--dsw-alias-state-error-primary", "--dsw-alias-state-idle-primary"];
+  /** Corner scale: sm 8, md 12, lg the large card, panel the modal. */
+  readonly radius: readonly ["--dsw-radius-sm", "--dsw-radius-md", "--dsw-radius-lg", "--dsw-radius-panel"];
+  /** An elevated surface draws its edge in the shadow, so it keeps border: 0. */
+  readonly elevation: readonly ["--dsw-elevation-soft", "--dsw-elevation-stroke", "--dsw-elevation-stroke-color", "--dsw-elevation-panel", "--dsw-elevation-prominent"];
+  /** Floats, masks and scrollbars. */
+  readonly overlay: readonly ["--dsw-menu-surface-fill", "--dsw-menu-backdrop-filter", "--dsw-mask-blur", "--dsw-alias-bg-mask-1", "--dsw-alias-menu-icon", "--dsw-alias-scrollbar-bg-l2", "--dsw-alias-scrollbar-hover-l2", "--dsw-shadow-lv3"];
+  /** Motion, focus and type axis, published by the host rather than by a component. */
+  readonly system: readonly ["--dsw-focus-ring-width", "--dsw-focus-ring-color", "--dsw-font-markdown-code-font-family", "--ds-transition-duration", "--ds-ease-in-out", "--ds-font-family-code", "--dsh-scrollbar-thumb", "--dsh-scrollbar-thumb-hover", "--dsh-content-font-size-secondary", "--dsh-content-font-delta", "--dsh-frame-top-clearance"];
+};
+/** Every official token name, flat. Used by the token guard test. */
+declare const OFFICIAL_THEME_TOKEN_NAMES: readonly string[];
+/** The elevation steps a surface can be raised by, softest first. */
+type OfficialElevation = 'soft' | 'stroke' | 'panel' | 'prominent';
+/**
+ * The host's focus ring shorthand, verbatim. Writing this per control is how
+ * rings drift apart; a stylesheet that draws its own focus style should use
+ * {@link officialFocus} instead. The colour fallback is the host's own default.
+ */
+declare const OFFICIAL_FOCUS_RING = "var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary))";
+/**
+ * A complete `outline` declaration at the official geometry. `offset` defaults
+ * to the 2px the native controls use; the host's inline field rules sit at 1px
+ * and a segmented tab pulls the ring inside itself at -2px.
+ */
+declare function officialFocus(offset?: string): string;
+/**
+ * An elevated surface. The host draws a raised surface's edge inside its
+ * shadow rather than as a border, so a card sets `border: 0` and takes the edge
+ * from the elevation — which is also why its border stays off the alias-border
+ * set that a flat, non-elevated rule would use.
+ */
+declare function officialElevation(level: OfficialElevation): string;
+/**
+ * An elevated surface whose edge should read as a specific hairline. Rebinding
+ * the stroke colour is how a menu card picks l1 while a panel picks l3, without
+ * the two growing apart by hand.
+ */
+declare function officialStrokedElevation(level: OfficialElevation, color: string): string;
+/**
+ * The shared stylesheet for a plugin UI, scoped under that plugin's root class.
+ *
+ * Scoping is what keeps this safe to always-bundle into every client: the rules
+ * can only match inside the plugin's own subtree, so two plugins can both mount
+ * `dsh-ui-card` without either styling the other's markup.
+ *
+ * Each recipe matches the root element *and* its descendants, because the
+ * commonest arrangement is one element that is both — a surface that carries
+ * the root class and `dsh-ui-card`, or a portaled dialog that is the root and
+ * the `dsh-ui-surface`. A descendant-only scope would silently leave those
+ * unstyled, with no error anywhere.
+ *
+ * A caveat worth knowing: `Modal` and `Menu` portal to `document.body`, so their
+ * content leaves the plugin's subtree entirely. A portaled surface therefore
+ * needs its own root class on an element inside the portal.
+ *
+ * Only patterns that primitives do not provide live here. If a control appears
+ * below that `Button`/`Input`/`Switch`/`Tag`/`Menu` already covers, that is a
+ * bug in this file: use the primitive and delete the recipe.
+ */
+declare function officialUiCss(roots: string | readonly string[]): string;
+//#endregion
+export { OFFICIAL_FOCUS_RING, OFFICIAL_THEME_TOKENS, OFFICIAL_THEME_TOKEN_NAMES, OfficialElevation, officialElevation, officialFocus, officialStrokedElevation, officialUiCss };
+//# sourceMappingURL=official-ui.d.ts.map