dsh-claude-desktop-theme 0.2.0 → 0.4.0

package/lib/index.js

@@ -9,7 +9,9 @@ var DEFAULT_FEATURES = Object.freeze({
   conversation: true,
   "tool-calls": false,
   statistics: false,
-  "composer-pet": true
+  "composer-pet": true,
+  "composer-stats": false,
+  "context-panel": true
 });
 var DEFAULT_APPEARANCE = Object.freeze({
   canvas: "",
@@ -20,6 +22,9 @@ var DEFAULT_FONTS = Object.freeze({
   uiCjk: "",
   code: ""
 });
+var DEFAULT_VIEW = Object.freeze({
+  showEmptyGroups: false
+});
 var FONT_NAME_MAX_LENGTH = 64;
 
 // src/shared/stats.ts
@@ -126,13 +131,13 @@ function applyUsageEvent(state, event) {
   return state;
 }
 function pairs(record) {
-  return Object.entries(record).filter(([, count2]) => count2 > 0).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+  return Object.entries(record).filter(([, count4]) => count4 > 0).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
 }
 function hourPairs(hours) {
   const sparse = [];
   for (let hour = 0; hour < hours.length; hour += 1) {
-    const count2 = hours[hour] ?? 0;
-    if (count2 > 0) sparse.push([hour, count2]);
+    const count4 = hours[hour] ?? 0;
+    if (count4 > 0) sparse.push([hour, count4]);
   }
   return sparse;
 }
@@ -295,11 +300,11 @@ var byTokens = (left, right) => right[1] - left[1] || byKey(left[0], right[0]);
 function peak(counts, skip) {
   let best = null;
   let bestCount = 0;
-  for (const [key, count2] of counts) {
-    if (key === skip || count2 <= 0) continue;
-    if (count2 > bestCount || count2 === bestCount && best !== null && key < best) {
+  for (const [key, count4] of counts) {
+    if (key === skip || count4 <= 0) continue;
+    if (count4 > bestCount || count4 === bestCount && best !== null && key < best) {
       best = key;
-      bestCount = count2;
+      bestCount = count4;
     }
   }
   return best;
@@ -307,11 +312,11 @@ function peak(counts, skip) {
 function collect(value, collected) {
   if (value.prompts <= 0 && value.tokens <= 0) return;
   const dates = /* @__PURE__ */ new Set();
-  for (const [date, count2] of value.days) {
+  for (const [date, count4] of value.days) {
     dates.add(date);
-    collected.prompts.set(date, (collected.prompts.get(date) ?? 0) + count2);
+    collected.prompts.set(date, (collected.prompts.get(date) ?? 0) + count4);
   }
-  for (const [hour, count2] of value.hours) collected.hours.set(hour, (collected.hours.get(hour) ?? 0) + count2);
+  for (const [hour, count4] of value.hours) collected.hours.set(hour, (collected.hours.get(hour) ?? 0) + count4);
   for (const [model, tokens, input, output] of value.models) {
     const previous = collected.modelUsage.get(model) ?? { t: 0, i: 0, o: 0 };
     collected.modelUsage.set(model, {
@@ -342,9 +347,9 @@ function totalsFor(collected, start) {
   }
   const active = /* @__PURE__ */ new Set();
   let messages = 0;
-  for (const [date, count2] of collected.prompts) {
+  for (const [date, count4] of collected.prompts) {
     if (!inRange(date)) continue;
-    messages += count2;
+    messages += count4;
     active.add(date);
   }
   const models = /* @__PURE__ */ new Map();
@@ -383,8 +388,8 @@ function aggregateUsage(values, options) {
   const days = [];
   for (const date of dates) {
     if (cutoff !== null && date < cutoff) continue;
-    const count2 = collected.prompts.get(date) ?? 0;
-    if (count2 > 0) days.push([date, count2]);
+    const count4 = collected.prompts.get(date) ?? 0;
+    if (count4 > 0) days.push([date, count4]);
   }
   const modelDays = [];
   for (const [date, perModel] of [...collected.modelDays.entries()].sort(([left], [right]) => byKey(left, right))) {
@@ -397,10 +402,10 @@ function aggregateUsage(values, options) {
   let busyHour = null;
   let busyCount = 0;
   for (let hour = 0; hour < HOURS_PER_DAY; hour += 1) {
-    const count2 = collected.hours.get(hour) ?? 0;
-    if (count2 > busyCount) {
+    const count4 = collected.hours.get(hour) ?? 0;
+    if (count4 > busyCount) {
       busyHour = hour;
-      busyCount = count2;
+      busyCount = count4;
     }
   }
   return {
@@ -616,6 +621,362 @@ function mountStatistics(ctx, isEnabled) {
   });
 }
 
+// src/shared/context.ts
+var CONTEXT_KEY = "ccdContext";
+var CONTEXT_STATE_VERSION = 1;
+var CHARS_PER_TOKEN = 4;
+var BLOCK_OVERHEAD = 4;
+var DEFAULT_THRESHOLD_RATIO = 0.8;
+var DEFAULT_HEADROOM_TOKENS = 65536;
+var CONTEXT_ENTRY_LIMIT = 200;
+function count2(value) {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+function readCount(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+function readEntries(value) {
+  if (!Array.isArray(value)) return [];
+  const entries = [];
+  for (const entry of value) {
+    if (!Array.isArray(entry) || entry.length < 2) continue;
+    const [name, tokens] = entry;
+    if (typeof name !== "string" || name === "") continue;
+    const priced = typeof tokens === "number" && Number.isFinite(tokens) && tokens > 0 ? tokens : 0;
+    if (priced === 0) continue;
+    entries.push([name, priced]);
+  }
+  return entries;
+}
+function readContextView(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const raw = value;
+  return {
+    tools: readEntries(raw["tools"]),
+    files: readEntries(raw["files"]),
+    skills: readEntries(raw["skills"]),
+    skillTokens: count2(typeof raw["skillTokens"] === "number" ? raw["skillTokens"] : 0),
+    fileTokens: count2(typeof raw["fileTokens"] === "number" ? raw["fileTokens"] : 0),
+    compaction: readCount(raw["compaction"])
+  };
+}
+function emptyContextView() {
+  return { tools: [], files: [], skills: [], skillTokens: 0, fileTokens: 0, compaction: null };
+}
+function compactionThreshold(window, reserved, ratio = DEFAULT_THRESHOLD_RATIO, headroom = DEFAULT_HEADROOM_TOKENS) {
+  const capacity = count2(window);
+  if (capacity === 0 || reserved === null || !Number.isFinite(reserved) || reserved < 0) return null;
+  const pressureBudget = capacity - reserved - count2(headroom);
+  if (pressureBudget <= 0) return null;
+  return Math.floor(Math.min(capacity * ratio, pressureBudget));
+}
+
+// src/host/context/compaction.ts
+var DEFAULT_BACKEND = "@deepseek-ai/dsh-compaction-basic";
+function ratioOf(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= 1 ? value : null;
+}
+function headroomOf(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+function policyOf(entry) {
+  const config = entry.options?.config;
+  const record = typeof config === "object" && config !== null ? config : {};
+  const ratio = ratioOf(record["thresholdRatio"]);
+  const headroom = headroomOf(record["headroomTokens"]);
+  const named = entry.options?.name === DEFAULT_BACKEND;
+  if (ratio === null && headroom === null && !named) return null;
+  return {
+    ratio: ratio ?? DEFAULT_THRESHOLD_RATIO,
+    headroom: headroom ?? DEFAULT_HEADROOM_TOKENS
+  };
+}
+function readCompactionPolicy(ctx) {
+  const loader = ctx.get("loader");
+  if (loader === void 0 || typeof loader.entries !== "function") return null;
+  try {
+    let found = null;
+    for (const entry of loader.entries()) {
+      if (entry.disabled === true) continue;
+      const policy = policyOf(entry);
+      if (policy !== null) found = policy;
+    }
+    return found;
+  } catch {
+    return null;
+  }
+}
+
+// src/host/context/pricing.ts
+var SURFACE_TYPES = /* @__PURE__ */ new Set([
+  "system/message",
+  "developer/message",
+  "user/message",
+  "assistant/message",
+  "tool/result"
+]);
+function priceContent(blocks) {
+  let tokens = 0;
+  for (const block of blocks) {
+    if (block.type === "text" || block.type === "reasoning") {
+      tokens += Math.ceil((block.text ?? "").length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+      continue;
+    }
+    if (block.type === "tool-call") {
+      tokens += Math.ceil((block.name ?? "").length / CHARS_PER_TOKEN) + Math.ceil((block.arguments ?? "").length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+      continue;
+    }
+    tokens += BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / CHARS_PER_TOKEN);
+  }
+  return tokens;
+}
+function priceMessage(message) {
+  if (message === null) return 0;
+  if (message.role === "system") {
+    if (message.content.length === 0) return 0;
+    let characters = 0;
+    for (const block of message.content) {
+      characters += block.type === "text" ? (block.text ?? "").length : JSON.stringify(block).length;
+    }
+    return Math.ceil(characters / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+  }
+  return priceContent(message.content) + BLOCK_OVERHEAD;
+}
+function derivedMessage(event) {
+  switch (event.type) {
+    case "user/message":
+      return { content: event.data?.content ?? [] };
+    case "system/message":
+    case "developer/message":
+    case "assistant/message": {
+      const message = event.data?.message;
+      if (message === void 0 || message.content.length === 0) return null;
+      return message;
+    }
+    case "tool/result":
+      return event.data?.message ?? null;
+    default:
+      return null;
+  }
+}
+function isSurfaceEvent(event) {
+  return SURFACE_TYPES.has(event.type) && event.surfaceOp !== void 0;
+}
+function priceTool(tool) {
+  return Math.ceil(JSON.stringify(tool).length / CHARS_PER_TOKEN);
+}
+function allocate(total, weights) {
+  if (weights.length === 0) return [];
+  const safe = weights.map((weight) => Number.isFinite(weight) && weight > 0 ? weight : 1);
+  const sum = safe.reduce((running, weight) => running + weight, 0);
+  const out = [];
+  let placed = 0;
+  for (let index = 0; index < safe.length - 1; index += 1) {
+    const share = Math.round(total * safe[index] / sum);
+    out.push(share);
+    placed += share;
+  }
+  out.push(Math.max(0, total - placed));
+  return out;
+}
+
+// src/host/context/unit.ts
+var KIND_OTHER = 0;
+var KIND_INSTRUCTIONS = 1;
+var KIND_SKILLS = 2;
+function initContextState() {
+  return { nodes: [], tools: [], window: 0, reserved: null };
+}
+function count3(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function optionalCount(value) {
+  return readCount(value);
+}
+function textOf(event) {
+  return (event.data?.content ?? []).map((block) => block.type === "text" ? block.text ?? "" : "").join("\n");
+}
+function sectionStart(text, path) {
+  const needles = [
+    `Instructions from: ${path}`,
+    `Additional instructions from: ${path}`,
+    `Updated instructions from: ${path}`
+  ];
+  let found = -1;
+  for (const needle of needles) {
+    const at = text.indexOf(needle);
+    if (at >= 0 && (found < 0 || at < found)) found = at;
+  }
+  return found;
+}
+function nextSection(text, from) {
+  const marker = /^(?:Additional |Updated )?[Ii]nstructions from: /m;
+  const rest = text.slice(from);
+  const at = marker.exec(rest);
+  return at === null ? text.length : from + at.index;
+}
+function instructionEntries(event, tokens) {
+  const text = textOf(event);
+  const weights = /* @__PURE__ */ new Map();
+  for (const change of event.data?.source?.changes ?? []) {
+    const path = change.path;
+    if (typeof path !== "string" || path === "" || change.action === "remove") continue;
+    const at = sectionStart(text, path);
+    const weight = at < 0 ? 1 : Math.max(1, nextSection(text, at + 1) - at);
+    weights.set(path, (weights.get(path) ?? 0) + weight);
+  }
+  const paths = [...weights.keys()];
+  if (paths.length === 0) return [];
+  const shares = allocate(tokens, paths.map((path) => weights.get(path) ?? 1));
+  return paths.map((path, index) => [path, shares[index] ?? 0]);
+}
+function skillEntries(event, tokens) {
+  const listed = event.data?.source?.entries ?? [];
+  const named = [];
+  for (const entry of listed) {
+    const name = entry.name;
+    if (typeof name !== "string" || name === "") continue;
+    const weight = name.length + (entry.description?.length ?? 0);
+    const seen = named.find((candidate) => candidate.name === name);
+    if (seen === void 0) named.push({ name, weight });
+    else seen.weight += weight;
+  }
+  if (named.length === 0) return [];
+  const shares = allocate(tokens, named.map((entry) => entry.weight));
+  return named.map((entry, index) => [entry.name, shares[index] ?? 0]);
+}
+function kindOf(event) {
+  if (event.type !== "user/message") return KIND_OTHER;
+  const kind = event.data?.source?.kind;
+  if (kind === "agent-instructions") return KIND_INSTRUCTIONS;
+  if (kind === "skill-catalog") return KIND_SKILLS;
+  return KIND_OTHER;
+}
+function pricedTools(tools) {
+  if (tools === void 0 || tools.length === 0) return [];
+  return tools.map((tool) => [tool.name, priceTool(tool)]).sort((left, right) => right[1] - left[1] || (left[0] < right[0] ? -1 : left[0] > right[0] ? 1 : 0)).slice(0, CONTEXT_ENTRY_LIMIT);
+}
+function sameTools(left, right) {
+  if (left.length !== right.length) return false;
+  return left.every((entry, index) => entry[0] === right[index]?.[0] && entry[1] === right[index]?.[1]);
+}
+function applyContextEvent(state, event) {
+  if (event.type === "request/header") {
+    const header = event.data?.header;
+    const tools = pricedTools(header?.tools);
+    const reserved = optionalCount(header?.config?.maxTokens);
+    return sameTools(tools, state.tools) && reserved === state.reserved ? state : { ...state, tools, reserved };
+  }
+  if (event.type === "request/context") {
+    const window = count3(event.data?.contextWindow);
+    return window === state.window ? state : { ...state, window };
+  }
+  if (!isSurfaceEvent(event)) return state;
+  const tokens = priceMessage(derivedMessage(event));
+  const kind = kindOf(event);
+  const entries = kind === KIND_INSTRUCTIONS ? instructionEntries(event, tokens) : kind === KIND_SKILLS ? skillEntries(event, tokens) : [];
+  const node = [event.seq, tokens, kind, entries];
+  const op = event.surfaceOp;
+  if (op === void 0 || op === "append") {
+    return { ...state, nodes: [...state.nodes, node] };
+  }
+  const start = state.nodes.findIndex((candidate) => candidate[0] === op.startSeq);
+  const end = state.nodes.findIndex((candidate) => candidate[0] === op.endSeq);
+  if (start < 0 || end < 0 || start > end) return { ...state, nodes: [...state.nodes, node] };
+  const nodes = state.nodes.slice();
+  nodes.splice(start, end - start + 1, node);
+  return { ...state, nodes };
+}
+function mergeEntries(nodes, kind) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    if (node[2] !== kind) continue;
+    for (const [name, tokens] of node[3]) merged.set(name, (merged.get(name) ?? 0) + tokens);
+  }
+  return [...merged].filter(([, tokens]) => tokens > 0).sort((left, right) => right[1] - left[1] || (left[0] < right[0] ? -1 : left[0] > right[0] ? 1 : 0)).slice(0, CONTEXT_ENTRY_LIMIT).map(([name, tokens]) => [name, tokens]);
+}
+function sumKind(nodes, kind) {
+  let tokens = 0;
+  for (const node of nodes) if (node[2] === kind) tokens += node[1];
+  return tokens;
+}
+function viewContext(state, policy) {
+  return {
+    tools: state.tools,
+    files: mergeEntries(state.nodes, KIND_INSTRUCTIONS),
+    skills: mergeEntries(state.nodes, KIND_SKILLS),
+    skillTokens: sumKind(state.nodes, KIND_SKILLS),
+    fileTokens: sumKind(state.nodes, KIND_INSTRUCTIONS),
+    compaction: policy === null ? null : compactionThreshold(state.window, state.reserved, policy.ratio, policy.headroom)
+  };
+}
+function schemaOf2(parse) {
+  return { parse };
+}
+function readContextState(value) {
+  const raw = typeof value === "object" && value !== null ? value : {};
+  const nodes = [];
+  if (Array.isArray(raw["nodes"])) {
+    for (const entry of raw["nodes"]) {
+      if (!Array.isArray(entry) || entry.length < 3) continue;
+      const [seq, tokens, kind, entries] = entry;
+      if (typeof seq !== "number" || !Number.isInteger(seq) || seq < 0) continue;
+      nodes.push([
+        seq,
+        count3(tokens),
+        typeof kind === "number" && Number.isInteger(kind) ? kind : KIND_OTHER,
+        readEntries(entries)
+      ]);
+    }
+  }
+  return {
+    nodes,
+    tools: readEntries(raw["tools"]),
+    window: count3(raw["window"]),
+    reserved: optionalCount(raw["reserved"])
+  };
+}
+function readContextView2(value) {
+  return readContextView(value) ?? emptyContextView();
+}
+function createContextProjection(policy) {
+  const views2 = /* @__PURE__ */ new WeakMap();
+  return {
+    key: CONTEXT_KEY,
+    stateSchema: schemaOf2(readContextState),
+    init: () => initContextState(),
+    apply: (state, event) => applyContextEvent(state, event),
+    wire: {
+      viewSchema: schemaOf2(readContextView2),
+      view(state) {
+        const cached = views2.get(state);
+        if (cached !== void 0) return cached;
+        const view = viewContext(state, policy());
+        views2.set(state, view);
+        return view;
+      }
+    },
+    stateVersion: CONTEXT_STATE_VERSION
+  };
+}
+
+// src/host/context/service.ts
+function mountContextBreakdown(ctx, isEnabled) {
+  ctx.inject(["sessionProjections"], (injected) => {
+    if (!isEnabled()) return;
+    const projections = injected.get("sessionProjections");
+    if (projections === void 0) return;
+    try {
+      projections.register(createContextProjection(() => readCompactionPolicy(injected)));
+    } catch (error) {
+      try {
+        console.warn(`[${PLUGIN_ID}] context: the projection unit could not be registered`, error);
+      } catch {
+      }
+    }
+  });
+}
+
 // src/host/index.ts
 var HEX_COLOUR = /^(#[0-9a-fA-F]{3}|#[0-9a-fA-F]{6})?$/;
 var FONT_NAME = new RegExp(`^[\\p{L}\\p{N} ._-]{0,${FONT_NAME_MAX_LENGTH}}$`, "u");
@@ -629,7 +990,9 @@ var Config = z.object({
     conversation: z.boolean().default(DEFAULT_FEATURES.conversation),
     "tool-calls": z.boolean().default(DEFAULT_FEATURES["tool-calls"]),
     statistics: z.boolean().default(DEFAULT_FEATURES.statistics),
-    "composer-pet": z.boolean().default(DEFAULT_FEATURES["composer-pet"])
+    "composer-pet": z.boolean().default(DEFAULT_FEATURES["composer-pet"]),
+    "composer-stats": z.boolean().default(DEFAULT_FEATURES["composer-stats"]),
+    "context-panel": z.boolean().default(DEFAULT_FEATURES["context-panel"])
   }).default({ ...DEFAULT_FEATURES }).description("\u6309\u6A21\u5757\u542F\u7528").volatile(),
   /* One volatile node per section, exactly like `features`: Cordis rejects a
      volatile field nested inside another volatile field ("volatile fields
@@ -643,7 +1006,10 @@ var Config = z.object({
     uiLatin: z.string().default(DEFAULT_FONTS.uiLatin).description("\u754C\u9762\u897F\u6587\u5B57\u4F53\u540D\uFF08\u7559\u7A7A\u7528\u7CFB\u7EDF\u6808\uFF09").pattern(FONT_NAME),
     uiCjk: z.string().default(DEFAULT_FONTS.uiCjk).description("\u754C\u9762\u4E2D\u6587\u5B57\u4F53\u540D\uFF08\u7559\u7A7A\u7528\u7CFB\u7EDF\u6808\uFF09").pattern(FONT_NAME),
     code: z.string().default(DEFAULT_FONTS.code).description("\u4EE3\u7801\u4E0E\u7B49\u5BBD\u5B57\u4F53\u540D\uFF08\u7559\u7A7A\u7528\u7CFB\u7EDF\u6808\uFF09").pattern(FONT_NAME)
-  }).default({ ...DEFAULT_FONTS }).description("\u5B57\u4F53").volatile()
+  }).default({ ...DEFAULT_FONTS }).description("\u5B57\u4F53").volatile(),
+  view: z.object({
+    showEmptyGroups: z.boolean().default(DEFAULT_VIEW.showEmptyGroups).description("\u663E\u793A\u7A7A\u5206\u7EC4\uFF08\u5173\u6389\u65F6\u6CA1\u6709\u4F1A\u8BDD\u7684\u5DE5\u4F5C\u533A\u4E0D\u518D\u663E\u793A\uFF09")
+  }).default({ ...DEFAULT_VIEW }).description("\u89C6\u56FE\u9009\u9879").volatile()
 });
 function readValue(node, fallback) {
   if (node === void 0) return fallback;
@@ -659,6 +1025,7 @@ function readValue(node, fallback) {
 function apply(ctx, config) {
   const host = typeof config === "object" && config !== null ? config : {};
   mountStatistics(ctx, () => readValue(host.enabled, false) === true);
+  mountContextBreakdown(ctx, () => readValue(host.enabled, false) === true);
 }
 export {
   Config,

package/lib/types/client/compat/account-menu.d.ts

@@ -1,4 +1,4 @@
-import type { Disposer } from '../contracts/ports.ts';
+import type { Disposer, ThemePreferencePort } from '../contracts/ports.ts';
 /** Marks the portalled account menu for the stylesheet. */
 export declare const ACCOUNT_MENU_ATTRIBUTE = "data-ccd-account-menu";
 /**
@@ -38,8 +38,8 @@ export declare function accountNameToken(name: string): string;
  * the account itself (the account name over a workspace line). DSH's account
  * menu is a portalled `Menu` of plain rows and the signed-in name only exists on
  * the sidebar trigger, so this mirrors that real value onto the open menu and
- * tags it: no row is added, renamed or reordered — the stylesheet only reshapes
- * the card and prints the name it was given.
+ * tags it. The contact row becomes a More submenu whose feedback action still
+ * invokes the original host button.
  *
  * The menu is recognised structurally (a fixed-position `[role="menu"]` that is
  * open while the trigger reports `aria-expanded`), so no menu class hash is
@@ -49,4 +49,4 @@ export declare function accountNameToken(name: string): string;
  * @param report - sink for observer failures; the native menu stays untouched.
  * @returns disposer that disconnects the observers and clears every mark.
  */
-export declare function mountAccountMenu(document: Document, report: (error: unknown) => void): Disposer;
+export declare function mountAccountMenu(document: Document, report: (error: unknown) => void, theme?: ThemePreferencePort | null): Disposer;

package/lib/types/client/compat/account-more.d.ts

@@ -0,0 +1,3 @@
+import type { Disposer } from '../contracts/ports.ts';
+/** ui-settings-account's pinned Menu items are Settings, Contact, Sign in/out. */
+export declare function mountAccountMore(menu: HTMLElement): Disposer;

package/lib/types/client/compat/account-theme.d.ts

@@ -0,0 +1,3 @@
+import type { Disposer, ThemePreferencePort } from '../contracts/ports.ts';
+/** A compact theme row sharing the settings page's native preference service. */
+export declare function mountAccountTheme(menu: HTMLElement, theme: ThemePreferencePort | null): Disposer;

package/lib/types/client/compat/adapter.d.ts

@@ -1,5 +1,5 @@
 import type { Context } from '@deepseek-ai/cordis';
-import type { HostServices, ThemePreferencePort } from '../contracts/ports.ts';
+import type { ContextProjectionPort, HostServices, SidebarSessionsPort, ThemePreferencePort } from '../contracts/ports.ts';
 /**
  * Build the theme service's preference face.
  *
@@ -13,5 +13,26 @@ import type { HostServices, ThemePreferencePort } from '../contracts/ports.ts';
  * @returns the port, or null when this build cannot read or write the preference.
  */
 export declare function createThemePreferencePort(ctx: Context): ThemePreferencePort | null;
+/** Read collapsed membership from the same two catalogs the host browser uses. */
+export declare function createSidebarSessionsPort(ctx: Context): SidebarSessionsPort | null;
+/**
+ * Build the context ring's data face over the client session list.
+ *
+ * `ctx.sessions.list` is the Session Controller's catalog store and the one
+ * place the browser sees host-computed projections: `contextPressure` is the
+ * ring's own occupancy, `contextBreakdown` its three-way composition, and
+ * `ccdContext` this plugin's rows — all of them wire values the host shipped,
+ * carried for sessions that were never opened as well as the live one. Reading
+ * them here rather than recomputing them in the browser is what keeps the
+ * panel's header identical to the ring beside it.
+ *
+ * A session with no capacity yet is null: the host's own `ContextMeter` renders
+ * nothing in that state either, so the ring the panel hangs from is not there
+ * to open.
+ *
+ * @param ctx - client context carrying the session service.
+ * @returns the port, or null when this build does not publish a session list.
+ */
+export declare function createContextProjections(ctx: Context): ContextProjectionPort | null;
 /** This compatibility boundary targets the pinned SDK, not arbitrary DSH versions. */
 export declare function createHostServices(ctx: Context): HostServices;

package/lib/types/client/compat/browser-header.d.ts

@@ -0,0 +1,57 @@
+import type { Disposer } from '../contracts/ports.ts';
+/**
+ * The browsing region's header line, and the word that names it.
+ *
+ * The reference draws this region as ONE line: the group's name at the inline
+ * start and, at the trailing edge, the plus that starts a Session, Search and
+ * the view options. DSH renders those controls on a section header of its own,
+ * above a tree whose first row is the first Workspace's, so `sidebar.css` parks
+ * the header on that row's line — and this module is what tells it when. The
+ * merge holds only while the tree actually leads with a Workspace row: flat
+ * mode renders no group at all, and `compat/empty-groups.ts` takes every group
+ * off screen when there is nothing to show, so in both the header stays in the
+ * flow and is the region's own title line.
+ *
+ * That title is a word the host serves (`section.workspaces` when the tree is
+ * grouped, `section.sessions` when it is a flat list) and the reference's is
+ * 最近会话 / Recents. The word is rewritten the way the sidebar's navigation
+ * labels are: only a string the host itself rendered is replaced — a locale
+ * this module does not know keeps the host's own word — and every write is
+ * undone on release. The grouped word takes the reference's name only while the
+ * plugin's no-history prompt is up, which `empty-groups.ts` marks
+ * `data-ccd-empty-state="new"`; a region that still has groups to show keeps
+ * the host's own heading.
+ *
+ * The state is one marker attribute on the browsing region rather than a style
+ * per element, so a single answer covers every re-render the host makes and
+ * dropping the attribute restores the host's own two-row layout.
+ *
+ * The parked band is locked to the tree's content, not to the region's top
+ * edge: the header sits on the first Workspace row's line, so it has to leave
+ * with that row when the tree scrolls. No attribute reports a scroll, and the
+ * scroller is a sibling of the header rather than an ancestor, so CSS cannot
+ * see it (a scroll-driven animation timeline resolves against an ancestor);
+ * this module therefore listens to the scroller and publishes its distance as
+ * `--ccd-header-scroll` for the band's `top`. That is one deliberate listener
+ * beside the observers — the same exception `view-switch.ts` records for the
+ * column's width — and it writes only when the value changes.
+ */
+/** Marker on the browsing region while its header shares the first row's line. */
+export declare const BROWSER_HEADER_ATTRIBUTE = "data-ccd-header-merged";
+/** Custom property carrying the tree's scrolled distance, in px. */
+export declare const HEADER_SCROLL_PROPERTY = "--ccd-header-scroll";
+/**
+ * The name the browsing region's own title line draws.
+ * @param text - the host's word, exactly as it rendered it.
+ * @param noHistory - whether the plugin's no-history prompt is on screen.
+ * @returns the reference's name, or null to leave the host's own word.
+ */
+export declare function browserHeaderWord(text: string, noHistory: boolean): string | null;
+/**
+ * Publish the browsing region's merged-header state, and name its title line.
+ *
+ * @param document - renderer document carrying the sidebar.
+ * @param report - sink for observer failures; the host's two-row layout stays.
+ * @returns disposer that drops the marker and restores every label.
+ */
+export declare function mountBrowserHeader(document: Document, report: (error: unknown) => void): Disposer;

package/lib/types/client/compat/browser-menu.d.ts

@@ -0,0 +1,16 @@
+/** Browser capture menu backed by the native webview. */
+export interface BrowserPopupLayout {
+    readonly width: number;
+    readonly align: 'start' | 'end';
+}
+interface BrowserMenuActions {
+    popup(anchor: HTMLElement, content: HTMLElement, layout: BrowserPopupLayout): void;
+    dismiss(): void;
+    notice(anchor: HTMLElement, text: string): void;
+}
+export interface BrowserMenus {
+    more(anchor: HTMLElement): void;
+    release(): void;
+}
+export declare function mountBrowserMenus(node: HTMLElement, actions: BrowserMenuActions): BrowserMenus;
+export {};

package/lib/types/client/compat/composer-menus.d.ts

@@ -3,9 +3,12 @@ import type { Disposer } from '../contracts/ports.ts';
 export declare const FLIPPED_MENU_ATTRIBUTE = "data-ccd-menu-flipped";
 /**
  * Place bottom-edge Composer and hero-chip menus above their anchors, using
- * the Menu primitive's side=top geometry. Cap only cards taller than the free
- * space above the anchor so later content growth keeps its natural height.
- * MutationObserver and resize reapply placement when the host updates it.
+ * the Menu primitive's side=top geometry. The side is decided from the two free
+ * spaces alone — the room above wins whenever it is the larger one — so a card
+ * short enough to fit below does not stay under a control the reference opens
+ * upwards from. Cap only cards taller than the free space above the anchor so
+ * later content growth keeps its natural height. MutationObserver and resize
+ * reapply placement when the host updates it.
  * @returns disposer that restores each menu and releases the observers.
  */
 export declare function mountComposerMenuPlacement(document: Document, report: (error: unknown) => void): Disposer;