@363045841yyt/klinechart-core 0.8.14 → 0.9.0-alpha.0

package/src/rendering/renderer-tier/__tests__/detectRendererTier.test.ts

@@ -0,0 +1,177 @@
+/**
+ * Tests for `detectRendererTier` + the rank helpers.
+ *
+ * Coverage:
+ *   1. Probe selection cascade — WebGPU wins, WebGL2 wins when no GPU,
+ *      Canvas2D wins when no WebGL, `'none'` when nothing.
+ *   2. `reason` string carries the failure narrative.
+ *   3. Probes throwing are treated as "not available", error message
+ *      folded into reason.
+ *   4. `tried` enumerates the probed order.
+ *   5. `detectRendererTierOrThrow` throws KLineChartError on `'none'`.
+ *   6. `compareRendererTier` honours `webgpu > webgl2 > canvas2d > none`.
+ *   7. `isTierAtLeast` works for all four tiers.
+ *   8. Production probes (no override) run without crashing — in Node
+ *      they should pick `'none'` since there's no document/navigator
+ *      with these capabilities.
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import {
+  detectRendererTier,
+  detectRendererTierOrThrow,
+  compareRendererTier,
+  isTierAtLeast,
+  RENDERER_TIER_RANK,
+  type RendererTier,
+} from '..'
+import { isKLineChartError } from '../../../errors'
+
+// Helpers — return preset probe maps for each scenario.
+const TRUE = (): boolean => true
+const FALSE = (): boolean => false
+const THROW = (msg: string) => (): boolean => {
+  throw new Error(msg)
+}
+
+describe('detectRendererTier — cascade', () => {
+  it('selects webgpu when available', () => {
+    const r = detectRendererTier({
+      probes: { webgpu: TRUE, webgl2: TRUE, canvas2d: TRUE },
+    })
+    expect(r.tier).toBe('webgpu')
+    expect(r.tried).toEqual(['webgpu'])
+  })
+
+  it('falls through to webgl2 when WebGPU unavailable', () => {
+    const r = detectRendererTier({
+      probes: { webgpu: FALSE, webgl2: TRUE, canvas2d: TRUE },
+    })
+    expect(r.tier).toBe('webgl2')
+    expect(r.tried).toEqual(['webgpu', 'webgl2'])
+  })
+
+  it('falls through to canvas2d when neither WebGPU nor WebGL2 available', () => {
+    const r = detectRendererTier({
+      probes: { webgpu: FALSE, webgl2: FALSE, canvas2d: TRUE },
+    })
+    expect(r.tier).toBe('canvas2d')
+    expect(r.tried).toEqual(['webgpu', 'webgl2', 'canvas2d'])
+  })
+
+  it('returns none when nothing works', () => {
+    const r = detectRendererTier({
+      probes: { webgpu: FALSE, webgl2: FALSE, canvas2d: FALSE },
+    })
+    expect(r.tier).toBe('none')
+    expect(r.tried).toEqual(['webgpu', 'webgl2', 'canvas2d'])
+  })
+})
+
+describe('detectRendererTier — reason narrative', () => {
+  it('selected tier reason mentions the tier', () => {
+    const r = detectRendererTier({ probes: { webgpu: TRUE } })
+    expect(r.reason).toContain('selected webgpu')
+  })
+
+  it('none reason enumerates all tried tiers', () => {
+    const r = detectRendererTier({
+      probes: { webgpu: FALSE, webgl2: FALSE, canvas2d: FALSE },
+    })
+    expect(r.reason).toContain('webgpu')
+    expect(r.reason).toContain('webgl2')
+    expect(r.reason).toContain('canvas2d')
+  })
+
+  it('probe throws are folded into the reason as "threw \\"...\\""', () => {
+    const r = detectRendererTier({
+      probes: {
+        webgpu: THROW('adapter init crashed'),
+        webgl2: FALSE,
+        canvas2d: FALSE,
+      },
+    })
+    expect(r.tier).toBe('none')
+    expect(r.reason).toContain('threw "adapter init crashed"')
+  })
+
+  it('probe throws cascade gracefully to the next tier', () => {
+    const r = detectRendererTier({
+      probes: { webgpu: THROW('gpu denied'), webgl2: TRUE, canvas2d: TRUE },
+    })
+    expect(r.tier).toBe('webgl2')
+  })
+})
+
+describe('detectRendererTierOrThrow', () => {
+  it('returns the tier result when a tier is found', () => {
+    const r = detectRendererTierOrThrow({ probes: { webgpu: TRUE } })
+    expect(r.tier).toBe('webgpu')
+  })
+
+  it('throws KLineChartError(INVALID_STATE) when no tier is found', () => {
+    try {
+      detectRendererTierOrThrow({
+        probes: { webgpu: FALSE, webgl2: FALSE, canvas2d: FALSE },
+      })
+      expect.fail('expected throw')
+    } catch (e) {
+      expect(isKLineChartError(e, 'INVALID_STATE')).toBe(true)
+    }
+  })
+})
+
+describe('compareRendererTier', () => {
+  it.each([
+    ['webgpu', 'webgl2', 1],
+    ['webgl2', 'webgpu', -1],
+    ['webgpu', 'webgpu', 0],
+    ['webgl2', 'canvas2d', 1],
+    ['canvas2d', 'webgl2', -1],
+    ['canvas2d', 'none', 1],
+    ['none', 'canvas2d', -1],
+    ['none', 'none', 0],
+  ] as Array<[RendererTier, RendererTier, -1 | 0 | 1]>)('%s vs %s = %d', (a, b, expected) => {
+    expect(compareRendererTier(a, b)).toBe(expected)
+  })
+})
+
+describe('isTierAtLeast', () => {
+  it('webgpu satisfies any minimum', () => {
+    expect(isTierAtLeast('webgpu', 'webgpu')).toBe(true)
+    expect(isTierAtLeast('webgpu', 'webgl2')).toBe(true)
+    expect(isTierAtLeast('webgpu', 'canvas2d')).toBe(true)
+    expect(isTierAtLeast('webgpu', 'none')).toBe(true)
+  })
+
+  it('webgl2 does not satisfy webgpu minimum', () => {
+    expect(isTierAtLeast('webgl2', 'webgpu')).toBe(false)
+    expect(isTierAtLeast('webgl2', 'webgl2')).toBe(true)
+  })
+
+  it('none satisfies only the none minimum', () => {
+    expect(isTierAtLeast('none', 'none')).toBe(true)
+    expect(isTierAtLeast('none', 'canvas2d')).toBe(false)
+  })
+})
+
+describe('RENDERER_TIER_RANK', () => {
+  it('ranks the tiers in the documented order', () => {
+    expect(RENDERER_TIER_RANK.webgpu).toBe(3)
+    expect(RENDERER_TIER_RANK.webgl2).toBe(2)
+    expect(RENDERER_TIER_RANK.canvas2d).toBe(1)
+    expect(RENDERER_TIER_RANK.none).toBe(0)
+  })
+})
+
+describe('detectRendererTier — production probes (no override)', () => {
+  it('runs without crashing in a Node environment', () => {
+    // In jsdom / Node, navigator may or may not exist; the contract is
+    // simply that the call returns a well-formed result and does not throw.
+    const r = detectRendererTier()
+    expect(typeof r.tier).toBe('string')
+    expect(typeof r.reason).toBe('string')
+    expect(Array.isArray(r.tried)).toBe(true)
+  })
+})

package/src/rendering/renderer-tier/__tests__/selectBackend.test.ts

@@ -0,0 +1,249 @@
+/**
+ * Tests for `selectBackend` / `selectBackendOrThrow`.
+ *
+ * Coverage:
+ *   1. Direct match — detected tier has a registered factory.
+ *   2. Downgrade — detected tier is webgpu but only webgl2 registered.
+ *   3. Floor — `minimum: 'webgl2'` rejects canvas2d even if registered.
+ *   4. Detection injection — `opts.detection` skips the sniffer.
+ *   5. Probe injection — `opts.detect.probes` flows through.
+ *   6. Empty registry → `tier: 'none'` with informative reason.
+ *   7. fallbackChain enumerates tried tiers high → low.
+ *   8. `factory` is the same function reference passed in.
+ *   9. `reason` strings differ between direct match and downgrade.
+ *  10. Invalid minimum → `KLineChartError('INVALID_PARAM')`.
+ *  11. `selectBackendOrThrow` throws `INVALID_STATE` on no match.
+ *  12. `detection.tier` is preserved even when downgrade occurs.
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import { selectBackend, selectBackendOrThrow, type BackendRegistry } from '..'
+import { isKLineChartError } from '../../../errors'
+import type { RendererTierResult } from '../types'
+
+const ALWAYS = (): boolean => true
+const NEVER = (): boolean => false
+
+function fakeFactory<T>(tag: T): () => T {
+  return () => tag
+}
+
+// Helper: build a detection result without running the sniffer.
+function fakeDetection(tier: RendererTierResult['tier']): RendererTierResult {
+  return {
+    tier,
+    reason: `synthetic detection: ${tier}`,
+    tried: [tier],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Direct match
+// ---------------------------------------------------------------------------
+
+describe('selectBackend — direct match', () => {
+  it('detected webgpu + webgpu factory registered → webgpu factory', () => {
+    const sel = selectBackend({
+      detection: fakeDetection('webgpu'),
+      registry: {
+        webgpu: fakeFactory('GPU'),
+        webgl2: fakeFactory('GL2'),
+        canvas2d: fakeFactory('C2D'),
+      },
+    })
+    expect(sel.tier).toBe('webgpu')
+    expect(sel.factory!()).toBe('GPU')
+    expect(sel.fallbackChain).toEqual(['webgpu'])
+    expect(sel.reason).toContain('direct match')
+  })
+
+  it('detected canvas2d + canvas2d factory registered → canvas2d factory', () => {
+    const sel = selectBackend({
+      detection: fakeDetection('canvas2d'),
+      registry: { canvas2d: fakeFactory('C2D') },
+    })
+    expect(sel.tier).toBe('canvas2d')
+    expect(sel.factory!()).toBe('C2D')
+    expect(sel.fallbackChain).toEqual(['canvas2d'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Downgrade
+// ---------------------------------------------------------------------------
+
+describe('selectBackend — downgrade', () => {
+  it('detected webgpu, only webgl2 registered → webgl2 factory', () => {
+    const sel = selectBackend({
+      detection: fakeDetection('webgpu'),
+      registry: { webgl2: fakeFactory('GL2') },
+    })
+    expect(sel.tier).toBe('webgl2')
+    expect(sel.factory!()).toBe('GL2')
+    expect(sel.fallbackChain).toEqual(['webgpu', 'webgl2'])
+    expect(sel.reason).toContain('downgrade')
+    expect(sel.reason).toContain('webgpu')
+  })
+
+  it('detected webgl2, only canvas2d registered → canvas2d factory', () => {
+    const sel = selectBackend({
+      detection: fakeDetection('webgl2'),
+      registry: { canvas2d: fakeFactory('C2D') },
+    })
+    expect(sel.tier).toBe('canvas2d')
+    expect(sel.fallbackChain).toEqual(['webgl2', 'canvas2d'])
+  })
+
+  it('null factory entries are skipped (treated as not registered)', () => {
+    const sel = selectBackend({
+      detection: fakeDetection('webgpu'),
+      registry: { webgpu: null, webgl2: fakeFactory('GL2') },
+    })
+    expect(sel.tier).toBe('webgl2')
+  })
+
+  it('detection.tier is preserved in the result even after downgrade', () => {
+    const sel = selectBackend({
+      detection: fakeDetection('webgpu'),
+      registry: { canvas2d: fakeFactory('C2D') },
+    })
+    expect(sel.tier).toBe('canvas2d')
+    expect(sel.detection.tier).toBe('webgpu')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Floor
+// ---------------------------------------------------------------------------
+
+describe('selectBackend — minimum floor', () => {
+  it('minimum=webgl2 rejects canvas2d even if registered', () => {
+    const sel = selectBackend({
+      detection: fakeDetection('canvas2d'),
+      registry: { canvas2d: fakeFactory('C2D') },
+      minimum: 'webgl2',
+    })
+    expect(sel.tier).toBe('none')
+    expect(sel.factory).toBeNull()
+    expect(sel.reason).toContain('minimum=webgl2')
+  })
+
+  it('minimum=webgl2 accepts a higher tier', () => {
+    const sel = selectBackend({
+      detection: fakeDetection('webgl2'),
+      registry: { webgl2: fakeFactory('GL2') },
+      minimum: 'webgl2',
+    })
+    expect(sel.tier).toBe('webgl2')
+  })
+
+  it('minimum=canvas2d does not affect behaviour (effective default)', () => {
+    const sel = selectBackend({
+      detection: fakeDetection('canvas2d'),
+      registry: { canvas2d: fakeFactory('C2D') },
+      minimum: 'canvas2d',
+    })
+    expect(sel.tier).toBe('canvas2d')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Empty / no-match registries
+// ---------------------------------------------------------------------------
+
+describe('selectBackend — no match', () => {
+  it('empty registry → tier:none + null factory', () => {
+    const sel = selectBackend({
+      detection: fakeDetection('webgpu'),
+      registry: {} as BackendRegistry,
+    })
+    expect(sel.tier).toBe('none')
+    expect(sel.factory).toBeNull()
+    expect(sel.reason).toContain('no registered backend')
+  })
+
+  it('detected none + no factories → tier:none with host reason', () => {
+    const sel = selectBackend({
+      detection: fakeDetection('none'),
+      registry: {} as BackendRegistry,
+    })
+    expect(sel.tier).toBe('none')
+    expect(sel.reason).toContain('no renderable tier')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Detection / probe pass-through
+// ---------------------------------------------------------------------------
+
+describe('selectBackend — probe pass-through', () => {
+  it('detect.probes flows to detectRendererTier', () => {
+    const sel = selectBackend({
+      registry: { canvas2d: fakeFactory('C2D') },
+      detect: {
+        probes: { webgpu: NEVER, webgl2: NEVER, canvas2d: ALWAYS },
+      },
+    })
+    expect(sel.detection.tier).toBe('canvas2d')
+    expect(sel.tier).toBe('canvas2d')
+  })
+
+  it('explicit detection overrides probe detection', () => {
+    const sel = selectBackend({
+      registry: { canvas2d: fakeFactory('C2D') },
+      detection: fakeDetection('webgpu'),
+      // detect.probes here would say 'canvas2d' if consulted —
+      // but they shouldn't be, since explicit detection wins.
+      detect: { probes: { webgpu: NEVER, webgl2: NEVER, canvas2d: ALWAYS } },
+    })
+    expect(sel.detection.tier).toBe('webgpu')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+describe('selectBackend — input validation', () => {
+  it('throws KLineChartError(INVALID_PARAM) on unknown minimum', () => {
+    try {
+      selectBackend({
+        detection: fakeDetection('webgpu'),
+        registry: { webgpu: fakeFactory('X') },
+        minimum: 'doesNotExist' as never,
+      })
+      expect.fail('expected throw')
+    } catch (e) {
+      expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Strict variant
+// ---------------------------------------------------------------------------
+
+describe('selectBackendOrThrow', () => {
+  it('returns the selection unchanged when a factory was found', () => {
+    const sel = selectBackendOrThrow({
+      detection: fakeDetection('webgpu'),
+      registry: { webgpu: fakeFactory('GPU') },
+    })
+    expect(sel.tier).toBe('webgpu')
+    // Type-narrowed: factory is non-null at compile time.
+    expect(sel.factory()).toBe('GPU')
+  })
+
+  it('throws KLineChartError(INVALID_STATE) on no match', () => {
+    try {
+      selectBackendOrThrow({
+        detection: fakeDetection('none'),
+        registry: {} as BackendRegistry,
+      })
+      expect.fail('expected throw')
+    } catch (e) {
+      expect(isKLineChartError(e, 'INVALID_STATE')).toBe(true)
+    }
+  })
+})

package/src/rendering/renderer-tier/detectRendererTier.ts

@@ -0,0 +1,160 @@
+/**
+ * Synchronous renderer tier detection.
+ *
+ * Probes (in descending capability order):
+ *
+ *   1. **webgpu**   `'gpu' in navigator`. We deliberately do NOT call
+ *                   `navigator.gpu.requestAdapter()` here — that's async
+ *                   and the answer can change between probe and use
+ *                   (e.g. user toggles the WebGPU flag). The renderer
+ *                   should retry adapter acquisition at startup; this
+ *                   sync check is a pre-mount fast path.
+ *
+ *   2. **webgl2**   `canvas.getContext('webgl2') !== null`. Probes a
+ *                   throwaway `<canvas>`; if the browser hard-disabled
+ *                   WebGL (some hardened policies do), this returns
+ *                   null and we fall through.
+ *
+ *   3. **canvas2d** `canvas.getContext('2d') !== null`. Universal
+ *                   fallback for browsers from the 2010s onwards.
+ *
+ *   4. **none**     None of the above worked — likely SSR (no document)
+ *                   or a sandboxed environment. The caller can decide
+ *                   whether that's an error or a "render nothing" state.
+ *
+ * All exceptions from a probe are caught and folded into the `reason`
+ * field — a probe that throws is treated identically to one that
+ * returns false (no tier-skip cascade).
+ */
+
+import { KLineChartError } from '../../errors'
+
+import {
+  RENDERER_TIER_RANK,
+  type DetectRendererTierOptions,
+  type RendererTier,
+  type RendererTierResult,
+} from './types'
+
+// ---------------------------------------------------------------------------
+// Production probes — only run when no override is supplied
+// ---------------------------------------------------------------------------
+
+function probeWebGpu(): boolean {
+  const nav = (globalThis as { navigator?: unknown }).navigator
+  if (typeof nav !== 'object' || nav === null) return false
+  return 'gpu' in (nav as object)
+}
+
+function probeWebGl2(): boolean {
+  const doc = (globalThis as { document?: { createElement?: (s: string) => unknown } }).document
+  if (typeof doc?.createElement !== 'function') return false
+  const canvas = doc.createElement('canvas') as {
+    getContext?: (id: string) => unknown
+  }
+  if (typeof canvas.getContext !== 'function') return false
+  return canvas.getContext('webgl2') !== null
+}
+
+function probeCanvas2d(): boolean {
+  const doc = (globalThis as { document?: { createElement?: (s: string) => unknown } }).document
+  if (typeof doc?.createElement !== 'function') return false
+  const canvas = doc.createElement('canvas') as {
+    getContext?: (id: string) => unknown
+  }
+  if (typeof canvas.getContext !== 'function') return false
+  return canvas.getContext('2d') !== null
+}
+
+// ---------------------------------------------------------------------------
+// runProbe — adapter that turns probe → "ok, false, or error string"
+// ---------------------------------------------------------------------------
+
+function runProbe(probe: () => boolean): { ok: boolean; error: string | null } {
+  try {
+    return { ok: probe() === true, error: null }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    return { ok: false, error: msg }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+const TIER_ORDER: ReadonlyArray<RendererTier> = ['webgpu', 'webgl2', 'canvas2d']
+
+/**
+ * Detect the best renderer tier available in the current environment.
+ *
+ * Returns synchronously. Use this at the call site of `createChart` to
+ * pick the renderer backend; persist the result if you re-mount, since
+ * recomputing is cheap but not free (probing creates a throwaway canvas).
+ */
+export function detectRendererTier(opts?: DetectRendererTierOptions): RendererTierResult {
+  const probes = opts?.probes ?? {}
+  const reasonParts: string[] = []
+  const tried: RendererTier[] = []
+
+  for (const tier of TIER_ORDER) {
+    tried.push(tier)
+    const probe =
+      tier === 'webgpu'
+        ? (probes.webgpu ?? probeWebGpu)
+        : tier === 'webgl2'
+          ? (probes.webgl2 ?? probeWebGl2)
+          : (probes.canvas2d ?? probeCanvas2d)
+    const r = runProbe(probe)
+    if (r.ok) {
+      return {
+        tier,
+        reason: `selected ${tier} (${reasonParts.length === 0 ? 'first probe succeeded' : reasonParts.join('; ')})`,
+        tried: [...tried],
+      }
+    }
+    reasonParts.push(r.error === null ? `${tier}: not available` : `${tier}: threw "${r.error}"`)
+  }
+
+  return {
+    tier: 'none',
+    reason: `no tier available — ${reasonParts.join('; ')}`,
+    tried: [...tried],
+  }
+}
+
+/**
+ * Strict variant: throws `KLineChartError('INVALID_STATE')` when no
+ * renderable tier is found. Use when you want a hard failure rather
+ * than a silent `'none'`.
+ */
+export function detectRendererTierOrThrow(opts?: DetectRendererTierOptions): RendererTierResult {
+  const r = detectRendererTier(opts)
+  if (r.tier === 'none') {
+    throw new KLineChartError('INVALID_STATE', `detectRendererTierOrThrow: ${r.reason}`)
+  }
+  return r
+}
+
+/**
+ * Three-way compare on the tier rank. `a > b → 1`, `a < b → -1`, equal → 0.
+ *
+ *   compareRendererTier('webgpu', 'webgl2') === 1
+ *   compareRendererTier('canvas2d', 'webgl2') === -1
+ *   compareRendererTier('webgl2', 'webgl2') === 0
+ */
+export function compareRendererTier(a: RendererTier, b: RendererTier): -1 | 0 | 1 {
+  const ra = RENDERER_TIER_RANK[a]
+  const rb = RENDERER_TIER_RANK[b]
+  if (ra > rb) return 1
+  if (ra < rb) return -1
+  return 0
+}
+
+/**
+ * `tier >= minimum` guard for renderer features that require a floor
+ * (e.g. GPU compute volume profile needs `>= 'webgl2'`).
+ */
+export function isTierAtLeast(tier: RendererTier, minimum: RendererTier): boolean {
+  return compareRendererTier(tier, minimum) >= 0
+}