dsh-token-chart 0.0.0-stage → 0.1.0

package/src/buckets.ts

@@ -0,0 +1,120 @@
+/**
+ * The usage model: provider samples, bucket arithmetic, and the time helpers
+ * that turn them into chart-ready rows.
+ *
+ * @module dsh-token-chart/buckets
+ */
+import { DAY_MS } from './constants.ts'
+import type { Buckets, Derived, SessionEvent, UsageSample } from './types.ts'
+
+/** One zeroed bucket set. */
+export function zeroBuckets(): Buckets {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+}
+
+export function isCount(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
+}
+
+/**
+ * The last `usage` chunk embedded in one durable Assistant settlement stream.
+ * @param stream - compact records of the settlement.
+ * @returns the provider usage object, or undefined.
+ */
+export function lastStreamUsage(stream: readonly unknown[] | undefined): UsageSample | undefined {
+  if (!Array.isArray(stream)) return undefined
+  for (let index = stream.length - 1; index >= 0; index -= 1) {
+    const record = stream[index]
+    if (record === null || typeof record !== 'object') continue
+    if (record.type !== 'chunk') continue
+    const chunk = record.chunk
+    if (chunk !== null && typeof chunk === 'object' && chunk.type === 'usage') return chunk.usage
+  }
+  return undefined
+}
+
+/** The usage one durable settlement reports, if any. */
+export function usageOf(event: SessionEvent): UsageSample | undefined {
+  const data = event.data
+  if (data === null || typeof data !== 'object') return undefined
+  if (event.type === 'assistant/message' && data.usage !== undefined) return data.usage
+  if (event.type !== 'assistant/message' && event.type !== 'assistant/attempt') return undefined
+  return lastStreamUsage(data.stream)
+}
+
+/** Normalize one provider usage sample into the four billed buckets. */
+export function bucketsFrom(usage: UsageSample | undefined): Buckets | undefined {
+  if (usage === null || typeof usage !== 'object') return undefined
+  const input = usage.inputTokens
+  const output = usage.outputTokens
+  if (!isCount(input) || !isCount(output)) return undefined
+  const cacheRead = usage.cacheReadTokens === undefined ? 0 : usage.cacheReadTokens
+  const cacheWrite = usage.cacheWriteTokens === undefined ? 0 : usage.cacheWriteTokens
+  if (!isCount(cacheRead) || !isCount(cacheWrite)) return undefined
+  return { input, output, cacheRead, cacheWrite }
+}
+
+export function bucketsEqual(left: Buckets, right: Buckets): boolean {
+  return (
+    left.input === right.input &&
+    left.output === right.output &&
+    left.cacheRead === right.cacheRead &&
+    left.cacheWrite === right.cacheWrite
+  )
+}
+
+export function addInto(total: Buckets, buckets: Buckets): Buckets {
+  total.input += buckets.input
+  total.output += buckets.output
+  total.cacheRead += buckets.cacheRead
+  total.cacheWrite += buckets.cacheWrite
+  return total
+}
+
+export function subtract(total: Buckets, buckets: Buckets): Buckets {
+  total.input -= buckets.input
+  total.output -= buckets.output
+  total.cacheRead -= buckets.cacheRead
+  total.cacheWrite -= buckets.cacheWrite
+  return total
+}
+
+/** Derived figures shared by every response. */
+export function derived<T extends Record<string, unknown>>(buckets: Buckets, extra: T = {} as T): Derived & T {
+  const { input, output, cacheRead, cacheWrite } = buckets
+  const cache = cacheRead + cacheWrite
+  const billedInput = input + cacheRead + cacheWrite
+  const total = billedInput + output
+  return {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    cache,
+    total,
+    cacheHitRate: billedInput > 0 ? cacheRead / billedInput : 0,
+    ...extra,
+  }
+}
+
+/** Local calendar-day key `YYYY-MM-DD`. */
+export function dayKey(time: number): string {
+  const date = new Date(time)
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  return `${date.getFullYear()}-${month}-${day}`
+}
+
+/** Epoch ms of local midnight, `offset` days back. */
+export function startOfLocalDay(offset = 0): number {
+  const date = new Date()
+  date.setHours(0, 0, 0, 0)
+  return date.getTime() - offset * DAY_MS
+}
+
+export function timeLabel(time: number): string {
+  const date = new Date(time)
+  const hours = String(date.getHours()).padStart(2, '0')
+  const minutes = String(date.getMinutes()).padStart(2, '0')
+  return `${hours}:${minutes}`
+}

package/src/chunk/echarts.entry.ts

@@ -0,0 +1,27 @@
+/**
+ * Build entry for the package-local lazy chunk `client.echarts.js`.
+ *
+ * Only what the token-usage surfaces actually draw is pulled in: bar, line and
+ * pie series plus the grid/tooltip/legend/dataZoom components and the SVG
+ * renderer.
+ * Everything else ECharts ships (maps, 3D, GL, canvas renderer, the full
+ * component set) is tree-shaken away by the bundler.
+ */
+import * as echarts from 'echarts/core'
+import { BarChart, LineChart, PieChart } from 'echarts/charts'
+import { GridComponent, TooltipComponent, LegendComponent, DataZoomComponent } from 'echarts/components'
+import { SVGRenderer } from 'echarts/renderers'
+
+echarts.use([
+  BarChart,
+  LineChart,
+  PieChart,
+  GridComponent,
+  TooltipComponent,
+  LegendComponent,
+  // The x-axis range slider under the chart.
+  DataZoomComponent,
+  SVGRenderer,
+])
+
+export default echarts

package/src/client/api.ts

@@ -0,0 +1,126 @@
+/**
+ * Transport and shared state: the preference store every seat reads,
+ * the JSON helpers, and the polling hooks the surfaces use.
+ *
+ * @module dsh-token-chart/client/api
+ */
+import type { Prefs } from '../types.ts'
+
+import type { EndpointState } from './models.ts'
+
+import { React } from './react.ts'
+
+import { API, DEFAULT_PREFS } from './contract.ts'
+
+export const useSyncExternalStore =
+  typeof React.useSyncExternalStore === 'function'
+    ? React.useSyncExternalStore
+    : (subscribe: (onStoreChange: () => void) => () => void, getSnapshot: () => unknown) => {
+        const [value, setValue] = React.useState(getSnapshot)
+        React.useEffect(() => subscribe(() => setValue(getSnapshot())), [subscribe, getSnapshot])
+        return value
+      }
+
+/** Snapshot store every seat subscribes to. */
+export interface PrefsStore {
+  get: () => Prefs
+  set: (next: Prefs) => void
+  subscribe: (listener: () => void) => () => void
+}
+
+export const prefsStore: PrefsStore = (() => {
+  let value: Prefs = { ...DEFAULT_PREFS }
+  const listeners = new Set<() => void>()
+  return {
+    get: () => value,
+    set: (next: Prefs) => {
+      value = next
+      for (const listener of [...listeners]) (listener as () => void)()
+    },
+    subscribe: (listener: () => void) => {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+})()
+
+export function usePrefs(): Prefs {
+  return useSyncExternalStore(prefsStore.subscribe, prefsStore.get) as Prefs
+}
+
+/* --------------------------------------------------------- api client */
+
+export async function apiGet(path: string): Promise<{ value: any }> {
+  const response = await fetch(`${API}${path}`, { headers: { accept: 'application/json' } })
+  const payload = await response.json().catch(() => null)
+  if (payload === null || payload.ok !== true) {
+    throw new Error(payload?.error?.message ?? `HTTP ${response.status}`)
+  }
+  return payload
+}
+
+export async function apiPost(path: string, body: unknown): Promise<{ value: any }> {
+  const response = await fetch(`${API}${path}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body ?? {}),
+  })
+  const payload = await response.json().catch(() => null)
+  if (payload === null || payload.ok !== true) {
+    throw new Error(payload?.error?.message ?? `HTTP ${response.status}`)
+  }
+  return payload
+}
+
+/**
+ * Poll one API path: initial load, then a refresh whenever `tick` changes.
+ * @param path - API path including its query string.
+ * @param tick - refresh trigger.
+ */
+export function useEndpoint(path: string, tick: number): EndpointState {
+  const [state, setState] = React.useState<EndpointState>({ loading: true, value: undefined })
+  React.useEffect(() => {
+    let live = true
+    setState((current) => ({ ...current, loading: true }))
+    apiGet(path)
+      .then((payload) => {
+        if (!live) return
+        setState({ loading: false, value: payload.value, error: undefined })
+      })
+      .catch((error) => {
+        if (!live) return
+        setState({
+          loading: false,
+          value: undefined,
+          error: String((error as Error)?.message ?? error),
+        } as EndpointState)
+      })
+    return () => {
+      live = false
+    }
+  }, [path, tick])
+  return state
+}
+
+/* ------------------------------------------------------------- layout */
+
+export function useElementWidth(): [React.RefObject<any>, number] {
+  const ref = React.useRef(null)
+  const [width, setWidth] = React.useState(0)
+  React.useEffect(() => {
+    const node = ref.current as HTMLElement | null
+    if (node === null) return undefined
+    const update = (): void => setWidth((node as HTMLElement).clientWidth)
+    update()
+    if (typeof ResizeObserver === 'undefined') {
+      window.addEventListener('resize', update)
+      return () => window.removeEventListener('resize', update)
+    }
+    const observer = new ResizeObserver(update)
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [])
+  return [ref, width]
+}
+
+/* ----------------------------------------------------------- charts */

package/src/client/charts.tsx

@@ -0,0 +1,255 @@
+/**
+ * Built-in SVG fallback charts, used when the ECharts chunk is
+ * unavailable (offline first paint, chunk failure, degraded mode).
+ *
+ * @module dsh-token-chart/client/charts
+ */
+import type { ChartPoint, SeriesSpec, SliceSpec, Translate } from './models.ts'
+
+import { useElementWidth } from './api.ts'
+import { compactTokens, exactTokens, percentText } from './format.ts'
+
+/** One bar/line chart: bars and lines share points and a metric axis. */
+export function CartesianChart({
+  points,
+  series,
+  height = 210,
+}: {
+  points: ChartPoint[]
+  series: SeriesSpec[]
+  height?: number
+  t: Translate
+}) {
+  const [ref, width] = useElementWidth()
+  const box = Math.max(220, width || 320)
+  const hasRight = series.some((entry) => entry.axis === 'right')
+  const padding = { top: 12, right: hasRight ? 46 : 14, bottom: 30, left: 48 }
+  const innerWidth = Math.max(40, box - padding.left - padding.right)
+  const innerHeight = Math.max(40, height - padding.top - padding.bottom)
+
+  const leftMax = Math.max(
+    1,
+    ...series
+      .filter((entry) => entry.axis !== 'right')
+      .flatMap((entry) => points.map((point) => Number(point.values[entry.key]) || 0)),
+  )
+  const rightMax = Math.max(
+    0.0001,
+    ...series
+      .filter((entry) => entry.axis === 'right')
+      .flatMap((entry) => points.map((point) => Number(point.values[entry.key]) || 0)),
+  )
+  const scaleY = (value: number, axis: 'left' | 'right' | undefined): number => {
+    const max = axis === 'right' ? rightMax : leftMax
+    return padding.top + innerHeight - (Math.max(0, value) / max) * innerHeight
+  }
+  const step = innerWidth / Math.max(1, points.length)
+  const barSeries = series.filter((entry) => entry.type === 'bar')
+  const barWidth = Math.max(2, Math.min(26, (step * 0.72) / Math.max(1, barSeries.length)))
+  const gridLines = [0, 0.25, 0.5, 0.75, 1]
+  const labelEvery = Math.max(1, Math.ceil(points.length / Math.max(2, Math.floor(innerWidth / 56))))
+
+  const children: any[] = []
+  for (const ratio of gridLines) {
+    const y = padding.top + innerHeight * ratio
+    children.push(
+      <line
+        key={`grid-${ratio}`}
+        x1={padding.left}
+        x2={padding.left + innerWidth}
+        y1={y}
+        y2={y}
+        stroke="var(--dsw-alias-border-l1)"
+        strokeWidth={1}
+        strokeDasharray={ratio === 1 ? undefined : '3 4'}
+      />,
+    )
+  }
+  children.push(
+    <text
+      key="axis-left-max"
+      x={padding.left - 8}
+      y={padding.top + 4}
+      textAnchor="end"
+      fontSize={10}
+      fill="var(--dsw-alias-label-secondary)"
+    >
+      {compactTokens(leftMax)}
+    </text>,
+  )
+  children.push(
+    <text
+      key="axis-left-zero"
+      x={padding.left - 8}
+      y={padding.top + innerHeight}
+      textAnchor="end"
+      fontSize={10}
+      fill="var(--dsw-alias-label-secondary)"
+    >
+      {'0'}
+    </text>,
+  )
+  if (hasRight) {
+    children.push(
+      <text
+        key="axis-right-max"
+        x={padding.left + innerWidth + 8}
+        y={padding.top + 4}
+        fontSize={10}
+        fill="var(--dsw-alias-label-secondary)"
+      >
+        {percentText(rightMax)}
+      </text>,
+    )
+  }
+
+  points.forEach((point, index) => {
+    if (index % labelEvery !== 0) return
+    children.push(
+      <text
+        key={`label-${index}`}
+        x={padding.left + step * index + step / 2}
+        y={padding.top + innerHeight + 16}
+        textAnchor="middle"
+        fontSize={10}
+        fill="var(--dsw-alias-label-secondary)"
+      >
+        {String(point.label ?? '')}
+      </text>,
+    )
+  })
+
+  barSeries.forEach((entry, seriesIndex) => {
+    points.forEach((point, index) => {
+      const value = Math.max(0, Number(point.values[entry.key]) || 0)
+      if (value <= 0) return
+      const x = padding.left + step * index + step / 2 - (barWidth * barSeries.length) / 2 + barWidth * seriesIndex
+      const y = scaleY(value, entry.axis)
+      children.push(
+        <rect
+          key={`bar-${entry.key}-${index}`}
+          x={x}
+          y={y}
+          width={barWidth}
+          height={Math.max(1, padding.top + innerHeight - y)}
+          rx={Math.min(3, barWidth / 2)}
+          fill={entry.color}
+        >
+          <title>{`${entry.label}: ${exactTokens(value)}`}</title>
+        </rect>,
+      )
+    })
+  })
+
+  for (const entry of series.filter((item) => item.type === 'line')) {
+    const coordinates = points.map((point, index) => {
+      const value = Number(point.values[entry.key]) || 0
+      return [padding.left + step * index + step / 2, scaleY(value, entry.axis)]
+    })
+    children.push(
+      <polyline
+        key={`line-${entry.key}`}
+        points={coordinates.map((pair) => pair.join(',')).join(' ')}
+        fill="none"
+        stroke={entry.color}
+        strokeWidth={2}
+        strokeLinejoin="round"
+        strokeLinecap="round"
+      />,
+    )
+    coordinates.forEach((pair, index) => {
+      children.push(
+        <circle key={`dot-${entry.key}-${index}`} cx={pair[0]} cy={pair[1]} r={2.6} fill={entry.color}>
+          <title>{`${entry.label}: ${exactTokens(points[index].values[entry.key])}`}</title>
+        </circle>,
+      )
+    })
+  }
+
+  return (
+    <div className="dtc-chart" ref={ref}>
+      {
+        <svg width={box} height={height} role="img" aria-label={series.map((entry) => entry.label).join(', ')}>
+          {children}
+        </svg>
+      }
+      <Legend series={series} />
+    </div>
+  )
+}
+
+export function Legend({ series }: { series: SeriesSpec[] }) {
+  return (
+    <div className="dtc-legend">
+      {series.map((entry) => (
+        <span key={entry.key} className="dtc-legend-item">
+          <span className="dtc-swatch" style={{ background: entry.color }} />
+          <span>{entry.label}</span>
+        </span>
+      ))}
+    </div>
+  )
+}
+
+/** Donut chart over prepared slices. */
+export function PieChart({ slices, t }: { slices: SliceSpec[]; t: Translate }) {
+  const [ref, width] = useElementWidth()
+  const box = Math.max(180, Math.min(width || 240, 240))
+  const size = box
+  const radius = size / 2 - 6
+  const inner = radius * 0.58
+  const center = size / 2
+  const total = slices.reduce((sum, slice) => sum + (Number(slice.value) || 0), 0)
+  if (total <= 0) return <p className="dtc-empty">{t('panel.empty')}</p>
+  let angle = -Math.PI / 2
+  const paths = slices.map((slice, index) => {
+    const fraction = (Number(slice.value) || 0) / total
+    const sweep = fraction * Math.PI * 2
+    const start = angle
+    const end = angle + sweep
+    angle = end
+    const large = sweep > Math.PI ? 1 : 0
+    const point = (r: number, a: number): [number, number] => [center + r * Math.cos(a), center + r * Math.sin(a)]
+    const [x1, y1] = point(radius, start)
+    const [x2, y2] = point(radius, end)
+    const [x3, y3] = point(inner, end)
+    const [x4, y4] = point(inner, start)
+    const d =
+      slice.value <= 0
+        ? ''
+        : `M ${x1} ${y1} A ${radius} ${radius} 0 ${large} 1 ${x2} ${y2} L ${x3} ${y3} A ${inner} ${inner} 0 ${large} 0 ${x4} ${y4} Z`
+    return (
+      <path
+        key={`slice-${slice.key}-${index}`}
+        d={d}
+        fill={slice.color}
+        fillOpacity={slice.opacity ?? 1}
+        stroke="var(--dsw-alias-bg-base)"
+        strokeWidth={1.5}
+      >
+        <title>{`${slice.label}: ${exactTokens(slice.value)} (${percentText(fraction)})`}</title>
+      </path>
+    )
+  })
+  return (
+    <div className="dtc-chart dtc-chart-pie" ref={ref}>
+      <svg width={size} height={size} role="img" aria-label={t('chart.pie')}>
+        {paths}
+      </svg>
+      {
+        <div className="dtc-legend dtc-legend-column">
+          {slices.map((slice, index) => (
+            <span key={`legend-${slice.key}-${index}`} className="dtc-legend-item">
+              <span className="dtc-swatch" style={{ background: slice.color, opacity: slice.opacity ?? 1 }} />
+              <span>{`${slice.label} · ${compactTokens(slice.value)} · ${percentText((Number(slice.value) || 0) / total)}`}</span>
+            </span>
+          ))}
+        </div>
+      }
+    </div>
+  )
+}
+
+/** Page sizes offered under a table, smallest first. */
+export const PAGE_SIZES = [10, 20, 50]
+export const DEFAULT_PAGE_SIZE = 20

package/src/client/chrome.tsx

@@ -0,0 +1,127 @@
+/**
+ * Shell chrome: the icon shared by the menu and the settings row, the
+ * session-header entry, the settings-nav marker and the style installer.
+ *
+ * @module dsh-token-chart/client/chrome
+ */
+import type { Translate } from './models.ts'
+
+export function PanelIcon({ size = 18, active = false }: { size?: number; active?: boolean }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      aria-hidden={true}
+      style={{ opacity: active ? 1 : 0.9, display: 'block' }}
+    >
+      <rect x={3} y={12} width={4} height={9} rx={1} fill="currentColor" />
+      <rect x={9} y={8} width={4} height={13} rx={1} fill="currentColor" opacity={0.75} />
+      <rect x={15} y={4} width={4} height={17} rx={1} fill="currentColor" opacity={0.5} />
+    </svg>
+  )
+}
+
+/** The session-header usage entry; always present (see the settings copy). */
+export function HeaderUsageButton({
+  sessionId,
+  open,
+  t,
+}: {
+  sessionId: string
+  open: (sessionId: string) => boolean
+  t: Translate
+}) {
+  return (
+    <button
+      type="button"
+      className="dtc-header-button"
+      aria-label={t('usage.openDrawer')}
+      title={t('usage.title')}
+      onClick={() => open(sessionId)}
+    >
+      <svg width={16} height={16} viewBox="0 0 24 24" fill="none" aria-hidden={true}>
+        <path d="M4 19V9M10 19V5M16 19v-7M22 19H2" stroke="currentColor" strokeWidth={1.6} strokeLinecap="round" />
+      </svg>
+      <span className="dtc-header-label">{t('panel.title')}</span>
+    </button>
+  )
+}
+
+/** True when the clicked element is one of the product's usage pills. */
+export function isUsagePill(target: any): boolean {
+  let node = target
+  for (let depth = 0; depth < 6 && node !== null && node !== undefined; depth += 1) {
+    if (node.nodeType === 1 && node.tagName === 'BUTTON') {
+      const text = node.textContent ?? ''
+      if (node.getAttribute('aria-haspopup') === 'dialog' && /\btok\b/i.test(text)) return true
+      return false
+    }
+    node = node.parentNode
+  }
+  return false
+}
+
+/** The Host route that serves the compiled stylesheet. */
+const STYLE_PATH = '/token-chart/assets/token-chart.css'
+/** Where the stylesheet link is remembered, so a re-mount does not duplicate it. */
+const STYLE_LINK_MARKER = 'data-dtc-styles'
+
+export const SETTINGS_NAV_MARKER = 'data-dtc-settings-nav'
+
+/**
+ * Keep the marker on our own settings-nav row.
+ *
+ * The settings shell projects only `id`, `order` and `label` from a
+ * `settings.section` registration and picks its icon from a closed list of
+ * built-in ids, so there is no icon field to set. Until that contract grows
+ * one, identify our localized row after the dialog mounts and draw the same
+ * glyph the left-sidebar menu uses through CSS on the marker.
+ * @param label - locale-aware resolver for the section label.
+ * @returns disposer removing the observer and every marker it set.
+ */
+export function registerSettingsNavIcon(label: () => string): () => void {
+  let disposed = false
+  const sync = () => {
+    if (disposed) return
+    const current = label().trim()
+    for (const button of document.querySelectorAll('[role="dialog"] nav button')) {
+      if (current !== '' && (button.textContent ?? '').trim() === current) button.setAttribute(SETTINGS_NAV_MARKER, '')
+      else button.removeAttribute(SETTINGS_NAV_MARKER)
+    }
+  }
+  sync()
+  const observer = new MutationObserver(sync)
+  observer.observe(document.body, { childList: true, subtree: true, characterData: true })
+  return () => {
+    disposed = true
+    observer.disconnect()
+    for (const marked of document.querySelectorAll(`[${SETTINGS_NAV_MARKER}]`))
+      marked.removeAttribute(SETTINGS_NAV_MARKER)
+  }
+}
+
+/**
+ * Link the plugin's compiled stylesheet.
+ *
+ * The CSS is a real artifact served by the Host half and loaded as a stylesheet
+ * resource — nothing about styling rides inside the client bundle, and the
+ * loader removes the link again when this fiber is disposed.
+ *
+ * @returns disposer removing the link.
+ */
+export function installStyles(): () => void {
+  const existing = document.querySelector(`link[${STYLE_LINK_MARKER}]`)
+  if (existing !== null) return () => {}
+
+  const link = document.createElement('link')
+  link.rel = 'stylesheet'
+  link.href = STYLE_PATH
+  link.setAttribute(STYLE_LINK_MARKER, '')
+  document.head.appendChild(link)
+
+  return () => {
+    link.remove()
+  }
+}