Redesign the Storage Monitor as a storage-composition breakdown (snippets · datasets · app)

src/core/storage-estimate.ts

@@ -1,89 +1,104 @@
 /**
- * Storage estimate summarization (spec §02 → Storage Monitor; spec §10 → "Warn
- * before storage failure"; docs/architecture/02 §6).
+ * Storage composition summarization (spec §02 → Storage Monitor; docs/architecture/02 §6).
  *
- * Portable core: no browser APIs, no React. The browser's Storage Manager API
- * (`navigator.storage.estimate()`) yields a raw `{ usage, quota }` pair in
- * bytes — both optional, since a browser may omit them. This module turns that
- * raw pair into presentation-ready facts: a clamped fraction, an escalating
- * level, and an availability flag. The infrastructure adapter
- * (`src/app/infrastructure/storage-estimate.ts`) feature-detects the API and
- * feeds its output through here; all the math lives in this pure function so it
- * is trivially testable.
+ * Portable core: no browser APIs, no React. The Storage Monitor is **not** a "used
+ * of quota" gauge — the browser's `quota` from `navigator.storage.estimate()` is a
+ * padded, browser-decided approximation, not a real free-space figure, so a budget
+ * fraction would be false precision (web.dev → storage-for-the-web). Instead we show
+ * what storage is *made of*: Snippets, Datasets, and App (everything else — the
+ * precached app shell + IndexedDB overhead). This module turns three measured byte
+ * counts into ordered segments; the math lives here so it is trivially testable.
  *
- * Thresholds: warning at >= 0.8 is the documented value (arch 02 §6 `WARN_AT`).
- * Critical at >= 0.95 is not specified by spec/arch; it is this module's default
- * for the second escalation step ("nearly full") and is the single source of
- * truth here.
+ * The only reliable figure from the estimate is `usage` (bytes actually stored for
+ * the whole origin). Snippet and dataset bytes we measure ourselves, so
+ * `App = usage − snippets − datasets`. When the estimate is missing we still show
+ * snippets + datasets from our own data.
  */
 
-/** Raw input shape, mirroring the browser's `StorageEstimate` (bytes, both optional). */
-export interface StorageEstimateInput {
-  /** Bytes currently used, or undefined when the browser omits it. */
-  usage?: number;
-  /** Total bytes available (quota), or undefined when the browser omits it. */
-  quota?: number;
+/** A category of stored data and its measured size in bytes. */
+export interface StorageSegment {
+  key: 'snippets' | 'datasets' | 'app';
+  /** User-facing label, centralized here so the component stays presentational. */
+  label: string;
+  bytes: number;
 }
 
-/** Escalating fullness level driving the storage monitor's warning copy/colour. */
-export type StorageLevel = 'ok' | 'warning' | 'critical';
-
-/** Presentation-ready summary derived from a raw estimate. */
-export interface StorageSummary {
-  /** Bytes used (0 when unusable). */
-  usedBytes: number;
-  /** Quota in bytes (0 when unusable). */
-  quotaBytes: number;
-  /** usedBytes / quotaBytes, clamped to 0..1; 0 when quota is 0/undefined. */
-  fraction: number;
-  /** Escalating fullness level derived from `fraction`. */
-  level: StorageLevel;
-  /** False when usage/quota are missing or non-finite — the estimate is unusable. */
-  available: boolean;
+/** Measured inputs: snippet/dataset bytes (always known) + origin usage (when the API is present). */
+export interface StorageInput {
+  /** Whole-origin bytes from `navigator.storage.estimate().usage`, if available. */
+  usageBytes?: number;
+  /** Summed serialized size of all snippets. */
+  snippetBytes: number;
+  /** Summed size of all datasets (each `Dataset` carries its byte `size`). */
+  datasetBytes: number;
 }
 
-/** Fraction at which the monitor begins warning (arch 02 §6 `WARN_AT`). */
-export const WARNING_THRESHOLD = 0.8;
-/** Fraction at which the monitor escalates to critical ("nearly full"). */
-export const CRITICAL_THRESHOLD = 0.95;
+/** Presentation-ready storage composition. */
+export interface StorageComposition {
+  /** Ordered segments to display: Snippets, Datasets, then App when measurable. */
+  segments: StorageSegment[];
+  /** Sum of the segments shown — origin `usage` when measured, else snippets+datasets. */
+  totalBytes: number;
+  /**
+   * True when the origin estimate was available, so the `app` segment (the precached
+   * shell + overhead) is meaningful and `totalBytes` is whole-origin usage. False when
+   * the Storage Manager API is absent — we still show snippets + datasets, and
+   * `totalBytes` is just their sum.
+   */
+  originMeasured: boolean;
+}
 
-/** A non-finite or negative number is not a usable byte count. */
+/**
+ * The monitor stays hidden until the user's own data — snippets + datasets — reaches
+ * this size (spec §02). Below it storage is noise (nothing to manage), and the bar
+ * would be dominated by the immovable precached app shell anyway. Deliberately keyed
+ * off *user* bytes, not total: the ~precache baseline is roughly constant, so gating
+ * on total would make the monitor always-visible and the breakdown unbalanced.
+ */
+export const STORAGE_MONITOR_MIN_USER_BYTES = 10 * 1024 * 1024;
+
+/** A finite, non-negative byte count, or null when the value is unusable. */
 function usableBytes(n: number | undefined): number | null {
   if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) return null;
   return n;
 }
 
-/** Map a clamped fraction to its escalation level. */
-function levelFor(fraction: number): StorageLevel {
-  if (fraction >= CRITICAL_THRESHOLD) return 'critical';
-  if (fraction >= WARNING_THRESHOLD) return 'warning';
-  return 'ok';
+/** A finite, non-negative byte count; junk degrades to 0. */
+function nonNeg(n: number): number {
+  return usableBytes(n) ?? 0;
 }
 
 /**
- * Turn a raw storage estimate into a presentation-ready summary. Pure: no I/O.
- * When usage is missing/invalid, or quota is missing/invalid/zero, the estimate
- * is unusable — `available: false`, everything zeroed, level `ok` (we don't warn
- * on data we don't have). Otherwise the fraction is `usage / quota` clamped to
- * 0..1 and the level escalates at the thresholds above.
+ * Decompose measured storage into ordered segments. The `app` segment (everything
+ * beyond our snippets+datasets) is included only when the origin `usage` is available
+ * and at least our measured data — a smaller estimate is the browser's approximation
+ * lagging, not real, so we fall back to a snippets+datasets-only view.
  */
-export function summarizeStorage(input: StorageEstimateInput): StorageSummary {
-  const usage = usableBytes(input.usage);
-  const quota = usableBytes(input.quota);
+export function summarizeStorage(input: StorageInput): StorageComposition {
+  const snippets = nonNeg(input.snippetBytes);
+  const datasets = nonNeg(input.datasetBytes);
+  const usage = usableBytes(input.usageBytes);
+  const known = snippets + datasets;
 
-  // Quota of 0 can't yield a meaningful fraction; treat as unusable.
-  if (usage === null || quota === null || quota === 0) {
-    return { usedBytes: 0, quotaBytes: 0, fraction: 0, level: 'ok', available: false };
+  const segments: StorageSegment[] = [
+    { key: 'snippets', label: 'Snippets', bytes: snippets },
+    { key: 'datasets', label: 'Datasets', bytes: datasets },
+  ];
+
+  if (usage !== null && usage >= known) {
+    segments.push({ key: 'app', label: 'App', bytes: usage - known });
+    return { segments, totalBytes: usage, originMeasured: true };
   }
+  return { segments, totalBytes: known, originMeasured: false };
+}
 
-  const fraction = Math.min(1, usage / quota);
-  return {
-    usedBytes: usage,
-    quotaBytes: quota,
-    fraction,
-    level: levelFor(fraction),
-    available: true,
-  };
+/** UTF-8 byte length of a value's JSON serialization (0 when it can't be serialized). */
+export function jsonByteSize(value: unknown): number {
+  try {
+    return new TextEncoder().encode(JSON.stringify(value) ?? '').length;
+  } catch {
+    return 0;
+  }
 }
 
 const BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB'] as const;