@363045841yyt/klinechart-core 0.8.11-alpha.0 → 0.8.12

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

@@ -0,0 +1,253 @@
+/**
+ * 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 type { RendererTierResult } from '../types'
+import { isKLineChartError } from '../../errors'
+
+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/renderer-tier/detectRendererTier.ts

@@ -0,0 +1,168 @@
+/**
+ * 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
+}

package/src/renderer-tier/index.ts

@@ -0,0 +1,30 @@
+/**
+ * @klinechart-quant/core/renderer-tier — pre-mount renderer tier detection.
+ *
+ * Used by the `Renderer` factory to pick the highest backend the host
+ * environment supports (WebGPU → WebGL2 → Canvas2D → none).
+ *
+ * See `./detectRendererTier.ts` for design notes.
+ */
+
+export {
+    detectRendererTier,
+    detectRendererTierOrThrow,
+    compareRendererTier,
+    isTierAtLeast,
+} from './detectRendererTier'
+export {
+    selectBackend,
+    selectBackendOrThrow,
+    type BackendFactory,
+    type BackendRegistry,
+    type BackendSelection,
+    type SelectBackendOptions,
+} from './selectBackend'
+export {
+    RENDERER_TIER_RANK,
+    type RendererTier,
+    type RendererTierResult,
+    type RendererTierProbes,
+    type DetectRendererTierOptions,
+} from './types'

package/src/renderer-tier/selectBackend.ts

@@ -0,0 +1,201 @@
+/**
+ * Renderer backend selector — bridges the tier-detection layer
+ * ({@link detectRendererTier}) to the actual backend factory the
+ * `Renderer` interface will instantiate.
+ *
+ * Why this exists separately from {@link detectRendererTier}:
+ *
+ *   - Detection answers "what's *possible*?".
+ *   - Selection answers "what's *registered* and matches what's possible?".
+ *
+ * In practice the answers diverge. A consumer can:
+ *
+ *   (a) Choose to omit a backend they don't want to ship (e.g. drop the
+ *       WebGPU backend to save bundle size; the selector then falls
+ *       through to WebGL2 even when the host supports WebGPU).
+ *   (b) Override a backend for a specific tier (e.g. inject a Canvas2D
+ *       backend stub during tests, so the chart still renders headless).
+ *
+ * Both shapes need a *structural* fallback chain, not just "give me the
+ * factory for the detected tier". This module formalises that chain so
+ * the wiring is consistent across React, Vue, Angular, and any future
+ * adapter.
+ *
+ * Pure data: no DOM, no async, no side effects. The returned factory is
+ * just the function the caller registered.
+ */
+
+import { KLineChartError } from '../errors'
+import {
+    RENDERER_TIER_RANK,
+    type DetectRendererTierOptions,
+    type RendererTier,
+    type RendererTierResult,
+} from './types'
+import { detectRendererTier, isTierAtLeast } from './detectRendererTier'
+
+// ---------------------------------------------------------------------------
+// Public shape
+// ---------------------------------------------------------------------------
+
+/**
+ * Opaque factory shape. We don't constrain the Renderer construction here —
+ * the consumer's backend implementation knows its own signature. The
+ * selector is purely about *which* factory to hand back.
+ */
+export type BackendFactory<T = unknown> = () => T
+
+/**
+ * Map of tier → registered factory. Tiers that are absent or `null` are
+ * treated as "not registered" and skipped during selection.
+ *
+ * `'none'` is intentionally absent from the type. A `'none'` tier is the
+ * absence of any rendering capability; there is nothing to register.
+ */
+export type BackendRegistry<T = unknown> = Partial<
+    Record<Exclude<RendererTier, 'none'>, BackendFactory<T> | null>
+>
+
+/**
+ * Selection result. `tier` is the effective tier the chosen factory
+ * targets — which is at most the detected tier. `fallbackChain`
+ * enumerates the tiers the selector traversed (high → low). When no
+ * backend is registered for any tier ≤ the detected tier, returns
+ * `tier: 'none'` and `factory: null`.
+ */
+export interface BackendSelection<T = unknown> {
+    readonly tier: RendererTier
+    readonly factory: BackendFactory<T> | null
+    readonly fallbackChain: ReadonlyArray<RendererTier>
+    readonly reason: string
+    /**
+     * The original tier-detection result. Useful for telemetry — when
+     * `tier < detection.tier` the consumer knows the host could have
+     * done better but the registry was the binding constraint.
+     */
+    readonly detection: RendererTierResult
+}
+
+export interface SelectBackendOptions<T = unknown> {
+    readonly registry: BackendRegistry<T>
+    /**
+     * Tier-detection probes pass-through for tests. Same shape as
+     * {@link DetectRendererTierOptions}.
+     */
+    readonly detect?: DetectRendererTierOptions
+    /**
+     * Optional pre-computed detection result. When provided, the selector
+     * skips `detectRendererTier()` and uses this directly. Useful when
+     * the caller cached the detection at app startup.
+     */
+    readonly detection?: RendererTierResult
+    /**
+     * Optional floor — refuse to select a backend below this tier even
+     * if a lower-tier factory is registered. Used by features that need
+     * GPU compute (`minimum: 'webgl2'`). When the floor can't be met,
+     * the result has `tier: 'none'` and `factory: null`.
+     */
+    readonly minimum?: RendererTier
+}
+
+// ---------------------------------------------------------------------------
+// Selection
+// ---------------------------------------------------------------------------
+
+const SEARCH_ORDER: ReadonlyArray<Exclude<RendererTier, 'none'>> = [
+    'webgpu',
+    'webgl2',
+    'canvas2d',
+]
+
+/**
+ * Pick the highest registered backend at or below the detected tier
+ * (and at or above the optional minimum). Pure-data.
+ *
+ *   const sel = selectBackend({
+ *     registry: { webgpu: makeGpu, webgl2: makeGl2, canvas2d: makeC2d },
+ *   })
+ *   if (sel.factory === null) throw new Error('no renderer')
+ *   const renderer = sel.factory()
+ *
+ * Telemetry pattern:
+ *
+ *   if (sel.tier !== sel.detection.tier) {
+ *     log('renderer downgrade', sel.detection.tier, '→', sel.tier, sel.reason)
+ *   }
+ */
+export function selectBackend<T = unknown>(
+    opts: SelectBackendOptions<T>,
+): BackendSelection<T> {
+    const detection = opts.detection ?? detectRendererTier(opts.detect)
+    const detectedTier = detection.tier
+    const minimum = opts.minimum ?? 'none'
+
+    // Validate the minimum is a known tier; reject 'none' as a minimum
+    // because a 'none' floor is meaningless — nothing can be below it.
+    if (!(minimum in RENDERER_TIER_RANK)) {
+        throw new KLineChartError(
+            'INVALID_PARAM',
+            `selectBackend: minimum must be a RendererTier, got ${JSON.stringify(minimum)}`,
+        )
+    }
+
+    const chain: RendererTier[] = []
+    // Search from the detected tier downwards through SEARCH_ORDER.
+    for (const candidate of SEARCH_ORDER) {
+        // Skip tiers above the detected ceiling.
+        if (RENDERER_TIER_RANK[candidate] > RENDERER_TIER_RANK[detectedTier]) {
+            continue
+        }
+        chain.push(candidate)
+        // Skip below the configured minimum.
+        if (!isTierAtLeast(candidate, minimum)) {
+            // No further candidate will satisfy the minimum.
+            break
+        }
+        const factory = opts.registry[candidate] ?? null
+        if (factory !== null) {
+            return {
+                tier: candidate,
+                factory,
+                fallbackChain: chain,
+                reason:
+                    candidate === detectedTier
+                        ? `direct match: detected ${candidate} and ${candidate} backend is registered`
+                        : `downgrade: detected ${detectedTier}, but only ${candidate} backend is registered`,
+                detection,
+            }
+        }
+    }
+
+    return {
+        tier: 'none',
+        factory: null,
+        fallbackChain: chain,
+        reason:
+            detectedTier === 'none'
+                ? `host has no renderable tier`
+                : `no registered backend at or below detected ${detectedTier}` +
+                  (opts.minimum !== undefined && opts.minimum !== 'none'
+                      ? ` (minimum=${opts.minimum})`
+                      : ''),
+        detection,
+    }
+}
+
+/**
+ * Strict variant: throws `KLineChartError('INVALID_STATE')` if no factory
+ * could be selected. Use when a renderable backend is mandatory.
+ */
+export function selectBackendOrThrow<T = unknown>(
+    opts: SelectBackendOptions<T>,
+): BackendSelection<T> & { factory: BackendFactory<T> } {
+    const sel = selectBackend(opts)
+    if (sel.factory === null) {
+        throw new KLineChartError(
+            'INVALID_STATE',
+            `selectBackendOrThrow: ${sel.reason}`,
+        )
+    }
+    return sel as BackendSelection<T> & { factory: BackendFactory<T> }
+}