dsh-better-sidebar 0.10.0

package/src/client/subagent-activity.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure derivation of the compact LIVE line shown on a running subagent card:
+ * the last text output and the last tool call of the child's history tail
+ * (`subagent.history` events, oldest → newest). Renders nothing itself — the
+ * SubagentLiveLine component turns this into the card's status lines.
+ * Kept framework-free so the parser is unit-testable in the node environment.
+ */
+import type { SidebarHistoryEntry } from '../context-types.ts'
+
+/**
+ * Extract the concatenated plain text of a content-block list (the durable
+ * `ContentBlock[]` shape, structurally: blocks with `type: 'text'` carry
+ * `text`; anything else — tool_use, image, … — contributes nothing).
+ * @param content - the raw `content` field of a message event.
+ * @returns the joined text, or undefined when the message carries no text.
+ */
+export function contentText(content: unknown): string | undefined {
+  if (!Array.isArray(content)) return undefined
+  const parts: string[] = []
+  for (const block of content) {
+    if (block === null || typeof block !== 'object') continue
+    const candidate = block as { type?: unknown; text?: unknown }
+    if (candidate.type === 'text' && typeof candidate.text === 'string') {
+      parts.push(candidate.text)
+    }
+  }
+  return parts.length > 0 ? parts.join('\n') : undefined
+}
+
+/** The live status of one subagent card (both fields optional). */
+export interface LastActivity {
+  /** The latest assembled assistant text output in the tail. */
+  text?: string
+  /** The latest tool call in the tail. */
+  tool?: { name: string; args: string }
+}
+
+/**
+ * Fold a history tail into the last text output + last tool call (each is
+ * the LAST occurrence in event order). Lifecycle events and raw
+ * `assistant/chunk` rows are ignored — the card shows what the subagent is
+ * doing right now, not its plumbing.
+ * @param entries - the tail page from `subagent.history` (oldest → newest).
+ * @returns the last text and/or tool call; an empty object when the tail has neither.
+ */
+export function lastActivity(entries: SidebarHistoryEntry[]): LastActivity {
+  let text: string | undefined
+  let tool: { name: string; args: string } | undefined
+  for (const entry of entries) {
+    const { type, data } = entry.event
+    if (type === 'assistant/message') {
+      const message = data.message as { content?: unknown } | undefined
+      const extracted = contentText(message?.content)
+      if (extracted !== undefined) text = extracted
+    } else if (type === 'tool/call') {
+      tool = {
+        name: typeof data.name === 'string' ? data.name : 'tool',
+        args: typeof data.arguments === 'string' ? data.arguments : '',
+      }
+    }
+  }
+  if (text === undefined && tool === undefined) return {}
+  return {
+    ...(text === undefined ? {} : { text }),
+    ...(tool === undefined ? {} : { tool }),
+  }
+}

package/src/client/subagent-detect.ts

@@ -0,0 +1,125 @@
+/**
+ * Pure subagent-membership helpers over the sessions list feed (structural
+ * mirror world — no runtime imports). Used by the sidebar's auto-activation
+ * effect and the Subagent page:
+ *
+ * - {@link directSubagentCount}: direct durable children of one session,
+ * - {@link detectNewDirectSubagent}: the 0 → N transition that means "a new
+ *   subagent just spawned under the current session" (the auto-open trigger),
+ * - {@link countSubagentDescendants}: uninterrupted subagent-origin lineage
+ *   totals (mirror of the official `indexSubagentDescendants` over the
+ *   plugin's own summary rows).
+ */
+import type {
+  SidebarSessionList,
+  SidebarSessionSummary,
+  SidebarSubagentCatalog,
+} from '../context-types.ts'
+
+/** Count the direct subagent children of one session (durable `origin` rows). */
+export function directSubagentCount(
+  byId: SidebarSessionList['byId'],
+  sessionId: string,
+): number {
+  let count = 0
+  for (const summary of Object.values(byId)) {
+    if (summary.origin === 'subagent' && summary.parentId === sessionId) count += 1
+  }
+  return count
+}
+
+/**
+ * The main agent of the current session's tree: walk the durable parent
+ * chain upward until the first non-subagent session. The Subagent page shows
+ * THIS root's full topology regardless of how deep the current selection is
+ * (a session whose row is still hydrating, or a broken chain, degrades to
+ * the session itself).
+ */
+export function rootAncestor(
+  byId: SidebarSessionList['byId'],
+  sessionId: string | undefined,
+): string | undefined {
+  if (sessionId === undefined) return undefined
+  const seen = new Set<string>()
+  let current: SidebarSessionSummary | undefined = byId[sessionId]
+  while (current !== undefined && current.origin === 'subagent'
+    && current.parentId !== undefined && !seen.has(current.id)) {
+    seen.add(current.id)
+    current = byId[current.parentId]
+  }
+  return current?.id ?? sessionId
+}
+
+/**
+ * Collect every catalog branch (an entry with `hasChildren`) reachable from
+ * the root — the set of catalogs the always-expanded topology consumes.
+ * Cycles fail soft.
+ */
+export function collectBranchIds(
+  catalogs: Readonly<Record<string, SidebarSubagentCatalog>>,
+  rootId: string | undefined,
+): string[] {
+  const out: string[] = []
+  const seen = new Set<string>()
+  const visit = (parentId: string): void => {
+    if (seen.has(parentId)) return
+    seen.add(parentId)
+    for (const entry of catalogs[parentId]?.entries ?? []) {
+      if (entry.kind === 'child' && entry.hasChildren) {
+        out.push(entry.id)
+        visit(entry.id)
+      }
+    }
+  }
+  if (rootId !== undefined) visit(rootId)
+  return out
+}
+
+/**
+ * Whether a new direct subagent appeared under `sessionId` between two
+ * consecutive list snapshots (the count crossed 0 → >0). Switching to a
+ * session that already has subagents yields `false` (its baseline starts at
+ * the current count), so the auto-open never fights an existing layout.
+ */
+export function detectNewDirectSubagent(
+  prev: SidebarSessionList,
+  next: SidebarSessionList,
+  sessionId: string,
+): boolean {
+  return directSubagentCount(prev.byId, sessionId) === 0
+    && directSubagentCount(next.byId, sessionId) > 0
+}
+
+/** Descendant totals of one session through an uninterrupted subagent-origin chain. */
+export interface SubagentDescendantTotals {
+  count: number
+  runningCount: number
+}
+
+/**
+ * Index every subagent descendant under each ancestor it reaches through an
+ * uninterrupted subagent-origin chain (same semantics as the official
+ * `indexSubagentDescendants`; cycles fail soft).
+ */
+export function countSubagentDescendants(
+  byId: SidebarSessionList['byId'],
+  sessionId: string,
+): SubagentDescendantTotals {
+  const totals: SubagentDescendantTotals = { count: 0, runningCount: 0 }
+  for (const descendant of Object.values(byId)) {
+    if (descendant.origin !== 'subagent') continue
+    const seen = new Set<string>()
+    let current: SidebarSessionSummary | undefined = descendant
+    while (current?.origin === 'subagent' && current.parentId !== undefined
+      && !seen.has(current.id)) {
+      seen.add(current.id)
+      if (current.parentId === sessionId) {
+        totals.count += 1
+        if (descendant.running === true) totals.runningCount += 1
+        break
+      }
+      current = byId[current.parentId]
+    }
+  }
+  return totals
+}

package/src/client/subagent-jobs.ts

@@ -0,0 +1,161 @@
+/**
+ * Pure derivations for the Subagent page's background-job section. Kept
+ * framework-free so the node test environment can unit-test them: the job
+ * rows arrive through the harness `session/jobs` push mirror
+ * (`jobsBySession` in the sessions list feed) — nothing here issues
+ * requests, and the row ordering / status mapping mirror the official
+ * ui-jobs header list.
+ */
+import type {
+  SidebarSessionList,
+  SidebarSessionSummary,
+  SidebarJobStatus,
+  SidebarJobView,
+} from '../context-types.ts'
+import type { CopyKey } from './locales.ts'
+
+/** One row of the jobs section: the job plus its owning session's title. */
+export interface TreeJob {
+  ownerSessionId: string
+  ownerTitle: string
+  job: SidebarJobView
+}
+
+/** Whether the registry still holds the job open (its duration ticks). */
+export function isJobLive(job: SidebarJobView): boolean {
+  return job.status === 'running' || job.status === 'stopping'
+}
+
+/**
+ * Every session id of the topology tree rooted at `rootId` (the root plus
+ * each session whose uninterrupted subagent-origin chain reaches it — same
+ * lineage semantics as {@link countSubagentDescendants}; cycles fail soft).
+ * Sessions outside the tree (orphans, other trees) are excluded, so the
+ * jobs section never shows foreign work.
+ */
+export function treeSessionIds(
+  byId: SidebarSessionList['byId'],
+  rootId: string | undefined,
+): Set<string> {
+  const ids = new Set<string>()
+  if (rootId === undefined) return ids
+  for (const summary of Object.values(byId)) {
+    const seen = new Set<string>()
+    let current: SidebarSessionSummary | undefined = summary
+    let reachesRoot = false
+    while (current !== undefined && !seen.has(current.id)) {
+      seen.add(current.id)
+      if (current.id === rootId) {
+        reachesRoot = true
+        break
+      }
+      if (current.origin !== 'subagent' || current.parentId === undefined) break
+      current = byId[current.parentId]
+    }
+    if (reachesRoot) ids.add(summary.id)
+  }
+  return ids
+}
+
+/**
+ * Whether a NEW background job appeared for one session between two
+ * consecutive list snapshots (a job id the previous snapshot lacked).
+ * Unlike the subagent auto-open (0 → N only), ANY new job id triggers: the
+ * agent may start several jobs over a session, and each new one should
+ * surface the Jobs page (a fresh page load never triggers — its baseline
+ * starts at the current snapshot).
+ */
+export function detectNewJob(
+  prev: SidebarSessionList,
+  next: SidebarSessionList,
+  sessionId: string,
+): boolean {
+  const prevIds = new Set((prev.jobsBySession?.[sessionId] ?? []).map(job => job.id))
+  return (next.jobsBySession?.[sessionId] ?? []).some(job => !prevIds.has(job.id))
+}
+
+/**
+ * Collect the background jobs of the whole current tree, owner-labeled.
+ * Sessions without a mirror entry contribute nothing; an absent mirror
+ * (runtime older than the jobs feed) yields an empty list.
+ */
+export function collectTreeJobs(
+  byId: SidebarSessionList['byId'],
+  jobsBySession: Readonly<Record<string, readonly SidebarJobView[]>> | undefined,
+  rootId: string | undefined,
+): TreeJob[] {
+  const rows: TreeJob[] = []
+  if (jobsBySession === undefined) return rows
+  for (const sessionId of treeSessionIds(byId, rootId)) {
+    const jobs = jobsBySession[sessionId]
+    if (jobs === undefined || jobs.length === 0) continue
+    const ownerTitle = byId[sessionId]?.displayTitle ?? sessionId
+    for (const job of jobs) rows.push({ ownerSessionId: sessionId, ownerTitle, job })
+  }
+  return rows
+}
+
+/**
+ * Live rows first in start order, then settled rows newest-first (mirror of
+ * the official ui-jobs ordering); a tie falls back to start order so the
+ * sort never depends on the host's map iteration.
+ */
+export function orderJobs(rows: readonly TreeJob[]): TreeJob[] {
+  return [...rows].sort((left, right) => {
+    const liveLeft = isJobLive(left.job)
+    if (liveLeft !== isJobLive(right.job)) return liveLeft ? -1 : 1
+    if (liveLeft) return left.job.startedAt - right.job.startedAt
+    const finished = (right.job.finishedAt ?? right.job.startedAt) - (left.job.finishedAt ?? left.job.startedAt)
+    return finished !== 0 ? finished : left.job.startedAt - right.job.startedAt
+  })
+}
+
+/** The sidebar's StateDot states for the five wire statuses. */
+export type JobDotState = 'ongoing' | 'warning' | 'done' | 'error'
+
+/**
+ * Status marker semantics. `stopping` and `killed` share the attention
+ * color: both mean the work ended (or is ending) on request rather than on
+ * its own.
+ */
+export function jobDotState(status: SidebarJobStatus): JobDotState {
+  switch (status) {
+    case 'running': return 'ongoing'
+    case 'stopping': return 'warning'
+    case 'completed': return 'done'
+    case 'killed': return 'warning'
+    case 'failed': return 'error'
+  }
+}
+
+/** Human status word of one wire status (localized through the passed translator). */
+export function jobStatusLabel(
+  status: SidebarJobStatus,
+  t: (key: CopyKey, params?: Record<string, string | number>) => string,
+): string {
+  switch (status) {
+    case 'running': return t('jobStatusRunning')
+    case 'stopping': return t('jobStatusStopping')
+    case 'completed': return t('jobStatusCompleted')
+    case 'killed': return t('jobStatusKilled')
+    case 'failed': return t('jobStatusFailed')
+  }
+}
+
+/**
+ * Elapsed time in at most two adjacent units (mirror of the official
+ * ui-jobs duration wording). A background job that outlives an hour is
+ * already exceptional, so hours is the widest unit.
+ */
+export function formatJobDuration(
+  elapsedMs: number,
+  t: (key: CopyKey, params?: Record<string, string | number>) => string,
+): string {
+  const total = Math.max(0, Math.floor(elapsedMs / 1_000))
+  const seconds = total % 60
+  const minutes = Math.floor(total / 60) % 60
+  const hours = Math.floor(total / 3_600)
+  if (hours > 0) return t('jobDurationHours', { hours, minutes })
+  if (minutes > 0) return t('jobDurationMinutes', { minutes, seconds })
+  return t('jobDurationSeconds', { seconds })
+}

package/src/client/theme.ts

@@ -0,0 +1,44 @@
+/**
+ * Live theme access for surfaces that cannot consume the token colors
+ * directly — xterm's palette and CodeMirror's theme extensions need concrete
+ * values, but the app's scheme flips at runtime (ui-layout's ThemePresenter
+ * projects prefers-color-scheme and the user's choice onto
+ * body[data-ds-dark-theme] and html { color-scheme }). This module reads the
+ * resolved scheme and token values, and notifies subscribers on flips, so
+ * the terminal and the editor re-theme in place instead of freezing in the
+ * scheme they happened to be created under.
+ */
+
+/** Whether the app shell resolved to the dark scheme.
+ *
+ * The presenter sets `html { color-scheme }` together with the body palette
+ * attribute, so a set color-scheme means the decision is authoritative (an
+ * absent attribute is then LIGHT even when the OS prefers dark — the user
+ * chose light). Before the presenter has run, fall back to the OS media
+ * query as the best guess.
+ */
+export function isDarkScheme(): boolean {
+  if (typeof document === 'undefined') return true
+  const decided = document.documentElement.style.colorScheme !== ''
+  if (decided) return document.body.hasAttribute('data-ds-dark-theme')
+  return typeof matchMedia !== 'undefined' && matchMedia('(prefers-color-scheme: dark)').matches
+}
+
+/** One token's computed value on <body> ('' while the theme has not applied). */
+export function tokenValue(name: string): string {
+  if (typeof document === 'undefined') return ''
+  return getComputedStyle(document.body).getPropertyValue(name).trim()
+}
+
+/**
+ * Subscribe to color-scheme flips (the presenter toggles the body
+ * attribute). The callback fires after the attribute changed; re-read the
+ * scheme inside it.
+ * @returns the disposer.
+ */
+export function subscribeColorScheme(callback: () => void): () => void {
+  if (typeof document === 'undefined') return () => {}
+  const observer = new MutationObserver(() => { callback() })
+  observer.observe(document.body, { attributes: true, attributeFilter: ['data-ds-dark-theme'] })
+  return () => { observer.disconnect() }
+}

package/src/client/xlsx-to-univer.ts

@@ -0,0 +1,260 @@
+/**
+ * Convert a SheetJS (xlsx) workbook into Univer's {@link IWorkbookData} so
+ * {@link XlsxView} can render it through the Univer sheets preset.
+ *
+ * v1 scope (matches docs/plans/2026-08-10-office-preview-design.md §3.6):
+ * - Sheet names + order
+ * - Cell values, typed (string / number / boolean / error → force-string)
+ * - Cell formulas (text form; Univer's formula engine computes them)
+ * - Merged cells (!merges → mergeData)
+ * - Column widths (!cols → columnData) and row heights (!rows → rowData)
+ *
+ * Out of scope for v1 (SheetJS community edition does not parse them and the
+ * Pro edition is commercial): cell styles (font/fill/border/alignment),
+ * conditional formatting, charts. Users who need style fidelity get the
+ * download button on the binary placeholder.
+ *
+ * The function is pure (no DOM, no Univer imports) so it is unit-testable
+ * without jsdom or canvas.
+ */
+import type * as XLSX from 'xlsx'
+// Types come from @univerjs/presets (which re-exports @univerjs/core's type
+// surface). The enum values BooleanNumber / CellValueType are imported as
+// runtime values from the same module — the bundler inlines them, and the
+// test environment has @univerjs/presets available as a dependency.
+import { BooleanNumber, CellValueType, type LocaleType, type ICellData, type IColumnData, type IRowData, type IWorkbookData, type IWorksheetData, type IObjectArrayPrimitiveType, type IObjectMatrixPrimitiveType, type IRange } from '@univerjs/presets'
+
+/** SheetJS workbook (the slice of the module we use). */
+type XLSXWorkbook = XLSX.WorkBook
+
+/**
+ * Build a Univer workbook snapshot from a SheetJS workbook.
+ *
+ * @param wb - the parsed workbook from `XLSX.read(buf, { type: 'array' })`
+ * @param appVersion - the Univer package version, written into `appVersion`
+ *   (Univer requires the field but does not gate on it).
+ * @param locale - the locale Univer should render in.
+ */
+export function xlsxWorkbookToUniver(
+  wb: XLSXWorkbook,
+  appVersion: string,
+  locale: LocaleType,
+): IWorkbookData {
+  const sheetOrder: string[] = []
+  const sheets: Record<string, Partial<IWorksheetData>> = {}
+
+  wb.SheetNames.forEach((name, index) => {
+    const sheetId = `sheet-${index}`
+    sheetOrder.push(sheetId)
+    sheets[sheetId] = worksheetToUniver(wb.Sheets[name] ?? {}, name, sheetId)
+  })
+
+  // Univer requires at least one sheet; an empty workbook gets a placeholder.
+  if (sheetOrder.length === 0) {
+    const fallbackId = 'sheet-0'
+    sheetOrder.push(fallbackId)
+    sheets[fallbackId] = {
+      id: fallbackId,
+      name: 'Sheet1',
+      rowCount: 20,
+      columnCount: 26,
+      cellData: {},
+      rowData: {},
+      columnData: {},
+      mergeData: [],
+    }
+  }
+
+  return {
+    id: 'workbook',
+    name: wb.Props?.Title || 'Workbook',
+    appVersion,
+    locale,
+    styles: {},
+    sheetOrder,
+    sheets,
+  }
+}
+
+/** Convert one SheetJS worksheet to a Univer IWorksheetData. */
+function worksheetToUniver(
+  ws: XLSX.WorkSheet,
+  name: string,
+  sheetId: string,
+): Partial<IWorksheetData> {
+  const cellData: IObjectMatrixPrimitiveType<ICellData> = {}
+  const merges: IRange[] = []
+
+  // Cell values + formulas: iterate every cell address (skip the !-prefixed
+  // special keys SheetJS uses for sheet-level metadata).
+  for (const addr of Object.keys(ws)) {
+    if (addr.startsWith('!')) continue
+    const cell = ws[addr] as XLSX.CellObject | undefined
+    if (cell === undefined) continue
+    const { r, c } = decodeAddr(addr)
+    const converted = convertCell(cell)
+    if (converted === null) continue
+    let row = cellData[r]
+    if (row === undefined) {
+      row = {}
+      cellData[r] = row
+    }
+    row[c] = converted
+  }
+
+  // Merged cells: SheetJS's Range uses { s: { r, c }, e: { r, c } } (0-indexed),
+  // which is exactly Univer's IRange shape — copy verbatim.
+  if (Array.isArray(ws['!merges'])) {
+    for (const m of ws['!merges']!) {
+      if (m === undefined || m === null) continue
+      merges.push({ startRow: m.s.r, endRow: m.e.r, startColumn: m.s.c, endColumn: m.e.c })
+    }
+  }
+
+  const { rowCount, columnCount } = dimensions(ws, cellData)
+
+  return {
+    id: sheetId,
+    name,
+    tabColor: '',
+    hidden: BooleanNumber.FALSE,
+    freeze: { startRow: -1, startColumn: -1, xSplit: 0, ySplit: 0 },
+    rowCount,
+    columnCount,
+    defaultColumnWidth: 96,
+    defaultRowHeight: 22,
+    mergeData: merges,
+    cellData,
+    rowData: convertRows(ws['!rows']),
+    columnData: convertCols(ws['!cols']),
+    rowHeader: { width: 46 },
+    columnHeader: { height: 20 },
+    showGridlines: BooleanNumber.TRUE,
+    rightToLeft: BooleanNumber.FALSE,
+  }
+}
+
+/** Map a SheetJS CellObject onto Univer's ICellData (or null for empty). */
+function convertCell(cell: XLSX.CellObject): ICellData | null {
+  const out: ICellData = {}
+  // Type mapping: b→BOOLEAN, n→NUMBER, s→STRING, d→STRING, e→FORCE_STRING, z→skip
+  switch (cell.t) {
+    case 'b':
+      out.t = CellValueType.BOOLEAN
+      out.v = cell.v === true
+      break
+    case 'n':
+      out.t = CellValueType.NUMBER
+      out.v = typeof cell.v === 'number' ? cell.v : Number(cell.v)
+      break
+    case 'e':
+      // Excel error strings like #REF! — display verbatim, no formula engine.
+      out.t = CellValueType.FORCE_STRING
+      out.v = String(cell.w ?? cell.v ?? '')
+      break
+    case 's':
+    case 'd':
+    case 'z':
+    default:
+      // String / date / stub. SheetJS renders dates as ISO strings in `w`
+      // when cellDates is on; otherwise `v` is the serial number. Use `w`
+      // (formatted text) when present so users see what Excel showed.
+      out.t = CellValueType.STRING
+      out.v = cell.w ?? (cell.v !== undefined ? String(cell.v) : '')
+      break
+  }
+  // Formula: keep as text; Univer's formula engine computes on load.
+  if (typeof cell.f === 'string' && cell.f !== '') {
+    out.f = cell.f
+  }
+  return out
+}
+
+/** Convert SheetJS `!cols` (ColInfo[]) to Univer columnData (sparse, by index). */
+function convertCols(cols: XLSX.ColInfo[] | undefined): IObjectArrayPrimitiveType<Partial<IColumnData>> {
+  if (!Array.isArray(cols)) return {}
+  const out: IObjectArrayPrimitiveType<Partial<IColumnData>> = {}
+  cols.forEach((info, index) => {
+    if (info === undefined || info === null) return
+    const w = info.wpx ?? (info.width !== undefined ? Math.round(info.width * 7) : undefined)
+    out[index] = {
+      ...(w !== undefined ? { w } : {}),
+      ...(info.hidden === true ? { hd: BooleanNumber.TRUE } : {}),
+    }
+  })
+  return out
+}
+
+/** Convert SheetJS `!rows` (RowInfo[]) to Univer rowData (sparse, by index). */
+function convertRows(rows: XLSX.RowInfo[] | undefined): IObjectArrayPrimitiveType<Partial<IRowData>> {
+  if (!Array.isArray(rows)) return {}
+  const out: IObjectArrayPrimitiveType<Partial<IRowData>> = {}
+  rows.forEach((info, index) => {
+    if (info === undefined || info === null) return
+    const h = info.hpx ?? info.hpt
+    out[index] = {
+      ...(h !== undefined ? { h: Math.round(h) } : {}),
+      ...(info.hidden === true ? { hd: BooleanNumber.TRUE } : {}),
+    }
+  })
+  return out
+}
+
+/**
+ * Resolve the worksheet dimensions. SheetJS's `!ref` is authoritative when
+ * present; otherwise fall back to the max row/col we actually wrote, with a
+ * small floor so the canvas has somewhere to paint.
+ */
+function dimensions(
+  ws: XLSX.WorkSheet,
+  cellData: IObjectMatrixPrimitiveType<ICellData>,
+): { rowCount: number; columnCount: number } {
+  const ref = ws['!ref']
+  if (typeof ref === 'string' && ref !== '') {
+    const range = decodeRange(ref)
+    return {
+      rowCount: Math.max(range.endRow + 1, 20),
+      columnCount: Math.max(range.endColumn + 1, 10),
+    }
+  }
+  let maxRow = -1
+  let maxCol = -1
+  for (const r of Object.keys(cellData)) {
+    const rowNum = Number(r)
+    if (rowNum > maxRow) maxRow = rowNum
+    const rowObj = cellData[rowNum]!
+    for (const c of Object.keys(rowObj)) {
+      const colNum = Number(c)
+      if (colNum > maxCol) maxCol = colNum
+    }
+  }
+  return {
+    rowCount: Math.max(maxRow + 1, 20),
+    columnCount: Math.max(maxCol + 1, 10),
+  }
+}
+
+/** Decode an A1-style address (e.g. "AB12") to 0-indexed {row, col}. */
+function decodeAddr(addr: string): { r: number; c: number } {
+  let col = 0
+  let i = 0
+  while (i < addr.length) {
+    const ch = addr.charCodeAt(i)
+    if (ch >= 65 && ch <= 90) {
+      col = col * 26 + (ch - 64)
+      i += 1
+    } else {
+      break
+    }
+  }
+  const row = Number(addr.slice(i)) - 1
+  return { r: row, c: col - 1 }
+}
+
+/** Decode an A1-style range (e.g. "A1:AB12") to 0-indexed bounds. */
+function decodeRange(range: string): { startRow: number; endRow: number; startColumn: number; endColumn: number } {
+  const at = range.indexOf(':')
+  const start = decodeAddr(at === -1 ? range : range.slice(0, at))
+  const end = at === -1 ? start : decodeAddr(range.slice(at + 1))
+  return { startRow: start.r, endRow: end.r, startColumn: start.c, endColumn: end.c }
+}