dsh-claude-desktop-theme 0.2.0 → 0.3.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/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/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;

package/lib/types/client/compat/context-panel.d.ts

@@ -0,0 +1,47 @@
+import type { ContextPanelPort, ContextProjectionPort } from '../contracts/ports.ts';
+/**
+ * The context ring's breakdown panel, driven instead of replaced.
+ *
+ * DSH opens its own 264px panel from the ring's `onClick` and publishes no face
+ * that reads or drives it, so this module owns the interaction outright: it
+ * intercepts the trigger's click, holds the open and expanded state, and reads
+ * the numbers off the session list — where the host's own `contextPressure` and
+ * `contextBreakdown` projections, and this plugin's `ccdContext`, all arrive as
+ * wire values.
+ *
+ * Three details decide how it is written:
+ *
+ * - **The trigger's click is intercepted in the capture phase.** DSH's handler
+ *   is React's `onClick`, delegated at the renderer root; stopping the event on
+ *   the button before it bubbles keeps that handler from running, so the host's
+ *   panel never opens. This is the same device `compat/view-options.ts` uses for
+ *   the sidebar's menu, and it is why the host's open state never has to be
+ *   driven — a driven panel would be dismissed by the host's own
+ *   `useDismissOnOutsidePointer` the moment the reader clicked inside ours.
+ * - **The document element carries the open marker.** `composer.css` keys the
+ *   host panel's removal off `[data-ccd-context-open]`, so a click that somehow
+ *   reaches DSH's handler still leaves the reader looking at one panel. The
+ *   marker is belt to the interception's braces, not the mechanism.
+ * - **A trigger that goes away closes the panel.** The ring is drawn by the
+ *   Conversation page, so a session switch, a page change or a compaction that
+ *   empties the reading all replace it; each of those has to put the panel away
+ *   rather than leave it hanging over a control that is no longer there.
+ */
+/** Marks the host popup this module has taken over; the sheet keeps it off screen. */
+export declare const OPEN_MARKER = "data-ccd-context-open";
+/** Marks the ring trigger while this plugin's panel is the one on screen. */
+export declare const OPEN_ATTRIBUTE = "data-ccd-context-panel";
+/** The driver's own face, plus the release the mounting scope holds. */
+export interface ContextPanelDriver {
+    readonly port: ContextPanelPort;
+    dispose(): void;
+}
+/**
+ * Watch the context ring and open this plugin's panel from it.
+ *
+ * @param document - renderer document carrying the Conversation page.
+ * @param projections - the host's context readings, off the session list.
+ * @param report - sink for observer failures; the ring keeps DSH's own panel.
+ * @returns the port the card reads through, and the release of every observer.
+ */
+export declare function createContextPanelDriver(document: Document, projections: ContextProjectionPort, report: (error: unknown) => void): ContextPanelDriver;

package/lib/types/client/compat/empty-groups.d.ts

@@ -0,0 +1,46 @@
+import type { Disposer, SidebarSessionsPort, ViewOptionsSettingsPort } from '../contracts/ports.ts';
+/**
+ * Workspaces with nothing to show, kept out of the sidebar.
+ *
+ * The `显示空分组` row in the view-options card writes `view.showEmptyGroups`,
+ * whose default is off: a Workspace whose rows are all hidden by the current
+ * filter disappears from the column instead of standing there as a heading over
+ * nothing. With no durable history, all headings give way to a welcome prompt
+ * even if empty groups are enabled. DSH has no such setting of its own — the host draws one empty state
+ * for the whole tree (`EmptySessions`, `data-row-key="empty"`, rendered only
+ * when there are no groups at all), never one per Workspace — so this is the
+ * plugin's own behaviour and this module is where it is decided.
+ *
+ * A group is the `WorkspaceBrowser` box that holds one Workspace's row, its
+ * nested groups and its Session rows (`._7514NG_groupSection`). It is empty
+ * when nothing under it is a row the reader can see:
+ *
+ * - a Session row keeps it (except one `compat/blank-session-rows.ts` already
+ *   hides — a provisional New Session is not something to show a group for);
+ * - the `overflow:` row ("Show {n} more sessions") keeps it, because it is the
+ *   host saying there are more rows behind it;
+ * - a nested group's Sessions count, which is why the test walks the whole
+ *   subtree rather than the direct children;
+ * - collapsed membership comes from the host catalogs and native filter;
+ *   while those are loading, an unknown collapsed Workspace stays reachable.
+ *
+ * The marker is an attribute the sidebar sheet turns into `display: none`. It is
+ * written after the commit that drew the rows, which is the one thing about this
+ * module worth knowing: the host measures its keyed rows inside that commit
+ * (`blank-session-rows.ts` records the 200 ms glide that follows a late change),
+ * so a group hidden here can arrive with the rows below it already placed. The
+ * plugin's own default makes this the common path, so the first paint is checked
+ * on a real machine; if it shows, the fix is to write the same attribute from
+ * the previous pass's answer before the rows mount, not to move this test.
+ *
+ * @param document - renderer document carrying the sidebar.
+ * @param hideEmpty - whether empty groups are being kept out (the config's
+ *   `view.showEmptyGroups`, inverted).
+ * @param report - sink for observer failures; the column stays as the host drew it.
+ * @returns disposer that disconnects the observer and clears every marker.
+ */
+export declare function mountEmptyGroups(document: Document, hideEmpty: boolean, report: (error: unknown) => void, options?: {
+    source?: SidebarSessionsPort | null;
+    settings?: ViewOptionsSettingsPort;
+    showAll?: () => void;
+}): Disposer;