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

package/dist/render/Renderer.d.ts

@@ -0,0 +1,116 @@
+/**
+ * High-level renderer interface — the drawing primitives the chart's
+ * scene layers (candles, volume, indicators, drawings) call into.
+ *
+ * Both the existing WebGL renderer (currently spread across
+ * `src/core/renderers/{candle,subVolume,crosshair,...}.ts`) and the
+ * P1 WebGPU renderer implement this contract. v0's WebGL path will
+ * be refactored to fit behind it in a follow-up PR (this file ships
+ * the contract first; the legacy code is unchanged until the next
+ * step is approved).
+ *
+ * Design notes:
+ * - `drawInstances` is the workhorse: render N copies of a unit geometry
+ *   parameterized by an instance buffer. K-lines, volume bars, footprint
+ *   cells, heatmap tiles all reduce to instanced primitives — see
+ *   `docs/ROADMAP.md` §2.3 for the K-line example.
+ * - `drawLines` covers MA-style continuous polylines, drawings, axes.
+ * - `dispatchCompute` exists only because WebGPU has compute shaders;
+ *   the WebGL implementation throws on call so callers can feature-detect
+ *   via `caps.compute`. Volume Profile binning, M4 downsampling, footprint
+ *   aggregation will use it on the WebGPU path.
+ * - `setUniforms` is intentionally schemaless on the interface — the
+ *   uniform layout is owned by each shader/program. Callers pass a
+ *   structured object that the backend translates into uniform writes.
+ *
+ * This file is **pure interface** in this PR; behaviour comes in the
+ * next two PRs (Scale interfaces, then a Renderer impl that wraps
+ * the existing WebGL primitives).
+ */
+import type { SurfaceBackend, SurfaceRegion } from './SurfaceBackend';
+/** Reported by the backend so feature-conditional code can branch. */
+export type RendererCapabilities = {
+    /** WebGPU compute shaders available. WebGL backends report false. */
+    compute: boolean;
+    /** Storage buffers usable as ring buffers / scatter-add targets. */
+    storageBuffer: boolean;
+    /** Maximum elements per drawInstances call (engine-imposed cap). */
+    maxInstances: number;
+    /** Friendly name, e.g. "webgl2" or "webgpu". */
+    name: string;
+};
+/** Vertex/instance buffer wrapper. Backends own the GPU handle. */
+export type BufferHandle = {
+    readonly __brand: 'BufferHandle';
+};
+/** Pipeline / shader program wrapper. */
+export type PipelineHandle = {
+    readonly __brand: 'PipelineHandle';
+};
+/** Compute shader handle (WebGPU only). */
+export type ComputePipelineHandle = {
+    readonly __brand: 'ComputePipelineHandle';
+};
+export type BufferUsage = 'vertex' | 'instance' | 'index' | 'uniform' | 'storage';
+export type DrawInstancesParams = {
+    pipeline: PipelineHandle;
+    /** Unit-geometry buffer (e.g. a single rectangle) shared across instances. */
+    vertices: BufferHandle;
+    /** Per-instance attribute buffer (e.g. one row per K-line). */
+    instances: BufferHandle;
+    /** Number of instances to draw. */
+    instanceCount: number;
+    /** Vertices per instance (e.g. 4 for a quad, 6 if using triangles). */
+    vertexCount: number;
+    /** Uniform block — opaque object the backend reads. */
+    uniforms?: Record<string, unknown>;
+};
+export type DrawLinesParams = {
+    pipeline: PipelineHandle;
+    vertices: BufferHandle;
+    vertexCount: number;
+    /** Line strip vs disconnected segments. */
+    topology?: 'strip' | 'list';
+    uniforms?: Record<string, unknown>;
+};
+export type DispatchComputeParams = {
+    pipeline: ComputePipelineHandle;
+    /** Workgroup counts per axis. */
+    workgroups: [number, number?, number?];
+    /** Input/output buffer bindings, keyed by binding index. */
+    bindings: Record<number, BufferHandle>;
+    uniforms?: Record<string, unknown>;
+};
+/**
+ * The drawing-primitives interface every backend implements.
+ *
+ * Backends own the GPU resources; callers receive opaque handles
+ * (`BufferHandle`, `PipelineHandle`) and pass them back for draws.
+ */
+export interface Renderer {
+    /** Underlying surface (for region binding and final composite). */
+    readonly surface: SurfaceBackend;
+    /** Reported feature flags — caller branches on `caps.compute` etc. */
+    readonly caps: RendererCapabilities;
+    createBuffer(usage: BufferUsage, sizeBytes: number): BufferHandle;
+    writeBuffer(handle: BufferHandle, data: ArrayBufferView, offsetBytes?: number): void;
+    destroyBuffer(handle: BufferHandle): void;
+    /**
+     * Compile a shader pipeline. The exact pipeline descriptor is backend-specific;
+     * adapters typically expose factory helpers (e.g. `createCandlePipeline`) that
+     * internally call this with the right vertex/fragment sources.
+     */
+    createPipeline(descriptor: unknown): PipelineHandle;
+    destroyPipeline(handle: PipelineHandle): void;
+    /** WebGPU only — WebGL implementations MUST throw with a clear message. */
+    createComputePipeline(descriptor: unknown): ComputePipelineHandle;
+    destroyComputePipeline(handle: ComputePipelineHandle): void;
+    beginFrame(region: SurfaceRegion): void;
+    drawInstances(params: DrawInstancesParams): void;
+    drawLines(params: DrawLinesParams): void;
+    /** WebGPU only — WebGL implementations MUST throw. Caller checks caps first. */
+    dispatchCompute(params: DispatchComputeParams): void;
+    endFrame(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=Renderer.d.ts.map

package/dist/render/Renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../src/render/Renderer.ts"],"names":[],"mappings":"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"}

package/dist/render/Renderer.js

@@ -0,0 +1,31 @@
+/**
+ * High-level renderer interface — the drawing primitives the chart's
+ * scene layers (candles, volume, indicators, drawings) call into.
+ *
+ * Both the existing WebGL renderer (currently spread across
+ * `src/core/renderers/{candle,subVolume,crosshair,...}.ts`) and the
+ * P1 WebGPU renderer implement this contract. v0's WebGL path will
+ * be refactored to fit behind it in a follow-up PR (this file ships
+ * the contract first; the legacy code is unchanged until the next
+ * step is approved).
+ *
+ * Design notes:
+ * - `drawInstances` is the workhorse: render N copies of a unit geometry
+ *   parameterized by an instance buffer. K-lines, volume bars, footprint
+ *   cells, heatmap tiles all reduce to instanced primitives — see
+ *   `docs/ROADMAP.md` §2.3 for the K-line example.
+ * - `drawLines` covers MA-style continuous polylines, drawings, axes.
+ * - `dispatchCompute` exists only because WebGPU has compute shaders;
+ *   the WebGL implementation throws on call so callers can feature-detect
+ *   via `caps.compute`. Volume Profile binning, M4 downsampling, footprint
+ *   aggregation will use it on the WebGPU path.
+ * - `setUniforms` is intentionally schemaless on the interface — the
+ *   uniform layout is owned by each shader/program. Callers pass a
+ *   structured object that the backend translates into uniform writes.
+ *
+ * This file is **pure interface** in this PR; behaviour comes in the
+ * next two PRs (Scale interfaces, then a Renderer impl that wraps
+ * the existing WebGL primitives).
+ */
+export {};
+//# sourceMappingURL=Renderer.js.map

package/dist/render/Renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Renderer.js","sourceRoot":"","sources":["../../src/render/Renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG"}

package/dist/render/SurfaceBackend.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Low-level GPU surface backend.
+ *
+ * Abstracts canvas + context lifecycle, viewport / scissor regions, clear,
+ * compositing into a 2D canvas overlay, and teardown. Both the existing
+ * WebGL surface (`src/core/renderers/webgl/sharedWebGLSurface.ts`) and the
+ * P1 WebGPU surface implement this contract.
+ *
+ * This file is **pure interface** — no implementation. It exists so that:
+ *
+ * 1. Existing WebGL code can declare conformance via a one-line adapter
+ *    (see `createLegacyWebGLBackend` below) without changing any behaviour.
+ * 2. P1's WebGPU implementation has a fixed target to write against.
+ * 3. The higher-level `Renderer` (`./Renderer.ts`) can compose a backend
+ *    without knowing which GPU API it sits on.
+ *
+ * Design notes:
+ * - All region coordinates are in **logical pixels** with the surface
+ *   responsible for DPR scaling internally. This matches the existing
+ *   `WebGLRegion` semantics so the legacy adapter is a transparent pass-through.
+ * - `compositeTo` takes a 2D `CanvasRenderingContext2D` because the chart's
+ *   final composition target is a 2D overlay canvas — WebGL/WebGPU pixels
+ *   are drawn into the overlay via `drawImage`. Future paths that bypass
+ *   the 2D overlay (direct-to-screen WebGPU) can leave `compositeTo` as a no-op.
+ */
+export type SurfaceRegion = {
+    /** logical-pixel X of the region's top-left within the surface */
+    x: number;
+    /** logical-pixel Y of the region's top-left within the surface */
+    y: number;
+    /** logical-pixel width */
+    width: number;
+    /** logical-pixel height */
+    height: number;
+    /** device pixel ratio used to convert logical → physical */
+    dpr: number;
+};
+export type CompositeOptions = {
+    /** multiplied into the destination context's globalAlpha (0..1) */
+    alpha?: number;
+    /** if false, blocks `imageSmoothingEnabled` during the drawImage */
+    imageSmoothingEnabled?: boolean;
+};
+/**
+ * One GPU surface (WebGL2 today, WebGPU in P1). Stateless w.r.t. drawing
+ * primitives — those belong to `Renderer`.
+ */
+export interface SurfaceBackend {
+    /** Returns false if the underlying context could not be initialised. */
+    isAvailable(): boolean;
+    /**
+     * Resize the underlying canvas's physical (DPR-scaled) drawing buffer.
+     * Idempotent when called with the same arguments.
+     */
+    resize(widthLogical: number, heightLogical: number, dpr: number): void;
+    /**
+     * Bind a region for subsequent draw commands.
+     * Activates scissor + viewport sized to `region`. Returns false if the
+     * region is empty or the backend is unavailable.
+     */
+    bindRegion(region: SurfaceRegion): boolean;
+    /**
+     * Clear the most recently bound region to transparent black.
+     * Must be called after `bindRegion`. Backends MAY no-op if no region
+     * is currently bound.
+     */
+    clearRegion(region: SurfaceRegion): void;
+    /**
+     * Copy the contents of `region` (in surface coordinates) onto the
+     * provided 2D context at its current origin. Used to composite GPU
+     * output into the final 2D overlay canvas the user sees.
+     *
+     * Implementations MUST restore any context state they mutate
+     * (`globalAlpha`, `imageSmoothingEnabled`, transform).
+     */
+    compositeTo(targetCtx: CanvasRenderingContext2D, region: SurfaceRegion, options?: CompositeOptions): void;
+    /**
+     * Tear down GPU resources. After dispose, all other methods become no-ops.
+     * Idempotent.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=SurfaceBackend.d.ts.map

package/dist/render/SurfaceBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SurfaceBackend.d.ts","sourceRoot":"","sources":["../../src/render/SurfaceBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,MAAM,aAAa,GAAG;IACxB,kEAAkE;IAClE,CAAC,EAAE,MAAM,CAAA;IACT,kEAAkE;IAClE,CAAC,EAAE,MAAM,CAAA;IACT,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC3B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oEAAoE;IACpE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAClC,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC3B,wEAAwE;IACxE,WAAW,IAAI,OAAO,CAAA;IAEtB;;;OAGG;IACH,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAEtE;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAA;IAE1C;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;IAExC;;;;;;;OAOG;IACH,WAAW,CACP,SAAS,EAAE,wBAAwB,EACnC,MAAM,EAAE,aAAa,EACrB,OAAO,CAAC,EAAE,gBAAgB,GAC3B,IAAI,CAAA;IAEP;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAA;CAClB"}

package/dist/render/SurfaceBackend.js

@@ -0,0 +1,27 @@
+/**
+ * Low-level GPU surface backend.
+ *
+ * Abstracts canvas + context lifecycle, viewport / scissor regions, clear,
+ * compositing into a 2D canvas overlay, and teardown. Both the existing
+ * WebGL surface (`src/core/renderers/webgl/sharedWebGLSurface.ts`) and the
+ * P1 WebGPU surface implement this contract.
+ *
+ * This file is **pure interface** — no implementation. It exists so that:
+ *
+ * 1. Existing WebGL code can declare conformance via a one-line adapter
+ *    (see `createLegacyWebGLBackend` below) without changing any behaviour.
+ * 2. P1's WebGPU implementation has a fixed target to write against.
+ * 3. The higher-level `Renderer` (`./Renderer.ts`) can compose a backend
+ *    without knowing which GPU API it sits on.
+ *
+ * Design notes:
+ * - All region coordinates are in **logical pixels** with the surface
+ *   responsible for DPR scaling internally. This matches the existing
+ *   `WebGLRegion` semantics so the legacy adapter is a transparent pass-through.
+ * - `compositeTo` takes a 2D `CanvasRenderingContext2D` because the chart's
+ *   final composition target is a 2D overlay canvas — WebGL/WebGPU pixels
+ *   are drawn into the overlay via `drawImage`. Future paths that bypass
+ *   the 2D overlay (direct-to-screen WebGPU) can leave `compositeTo` as a no-op.
+ */
+export {};
+//# sourceMappingURL=SurfaceBackend.js.map

package/dist/render/SurfaceBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SurfaceBackend.js","sourceRoot":"","sources":["../../src/render/SurfaceBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}

package/dist/render/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Renderer abstraction barrel.
+ *
+ * The two interfaces (`SurfaceBackend`, `Renderer`) define the contract every
+ * GPU backend implements. v0's WebGL code (in `src/core/renderers/`) will be
+ * refactored to fit behind these in a follow-up PR; this PR ships the contract
+ * only, so subsequent PRs can land WebGPU and WebGL impls in parallel without
+ * either blocking on the other's interface decisions.
+ */
+export type { SurfaceBackend, SurfaceRegion, CompositeOptions, } from './SurfaceBackend';
+export type { Renderer, RendererCapabilities, BufferHandle, PipelineHandle, ComputePipelineHandle, BufferUsage, DrawInstancesParams, DrawLinesParams, DispatchComputeParams, } from './Renderer';
+//# sourceMappingURL=index.d.ts.map

package/dist/render/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EACR,cAAc,EACd,aAAa,EACb,gBAAgB,GACnB,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EACR,QAAQ,EACR,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,qBAAqB,GACxB,MAAM,YAAY,CAAA"}

package/dist/render/index.js

@@ -0,0 +1,11 @@
+/**
+ * Renderer abstraction barrel.
+ *
+ * The two interfaces (`SurfaceBackend`, `Renderer`) define the contract every
+ * GPU backend implements. v0's WebGL code (in `src/core/renderers/`) will be
+ * refactored to fit behind these in a follow-up PR; this PR ships the contract
+ * only, so subsequent PRs can land WebGPU and WebGL impls in parallel without
+ * either blocking on the other's interface decisions.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/render/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/renderer-tier/detectRendererTier.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 { type DetectRendererTierOptions, type RendererTier, type RendererTierResult } from './types';
+/**
+ * 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 declare function detectRendererTier(opts?: DetectRendererTierOptions): RendererTierResult;
+/**
+ * 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 declare function detectRendererTierOrThrow(opts?: DetectRendererTierOptions): RendererTierResult;
+/**
+ * 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 declare function compareRendererTier(a: RendererTier, b: RendererTier): -1 | 0 | 1;
+/**
+ * `tier >= minimum` guard for renderer features that require a floor
+ * (e.g. GPU compute volume profile needs `>= 'webgl2'`).
+ */
+export declare function isTierAtLeast(tier: RendererTier, minimum: RendererTier): boolean;
+//# sourceMappingURL=detectRendererTier.d.ts.map

package/dist/renderer-tier/detectRendererTier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detectRendererTier.d.ts","sourceRoot":"","sources":["../../src/renderer-tier/detectRendererTier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAEH,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EACjB,KAAK,kBAAkB,EAC1B,MAAM,SAAS,CAAA;AAmDhB;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,CAAC,EAAE,yBAAyB,GACjC,kBAAkB,CA+BpB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACrC,IAAI,CAAC,EAAE,yBAAyB,GACjC,kBAAkB,CASpB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAMhF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAEhF"}

package/dist/renderer-tier/detectRendererTier.js

@@ -0,0 +1,143 @@
+/**
+ * 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, } from './types';
+// ---------------------------------------------------------------------------
+// Production probes — only run when no override is supplied
+// ---------------------------------------------------------------------------
+function probeWebGpu() {
+    const nav = globalThis.navigator;
+    if (typeof nav !== 'object' || nav === null)
+        return false;
+    return 'gpu' in nav;
+}
+function probeWebGl2() {
+    const doc = globalThis.document;
+    if (typeof doc?.createElement !== 'function')
+        return false;
+    const canvas = doc.createElement('canvas');
+    if (typeof canvas.getContext !== 'function')
+        return false;
+    return canvas.getContext('webgl2') !== null;
+}
+function probeCanvas2d() {
+    const doc = globalThis.document;
+    if (typeof doc?.createElement !== 'function')
+        return false;
+    const canvas = doc.createElement('canvas');
+    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) {
+    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 = ['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) {
+    const probes = opts?.probes ?? {};
+    const reasonParts = [];
+    const tried = [];
+    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) {
+    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, b) {
+    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, minimum) {
+    return compareRendererTier(tier, minimum) >= 0;
+}
+//# sourceMappingURL=detectRendererTier.js.map

package/dist/renderer-tier/detectRendererTier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detectRendererTier.js","sourceRoot":"","sources":["../../src/renderer-tier/detectRendererTier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EACH,kBAAkB,GAIrB,MAAM,SAAS,CAAA;AAEhB,8EAA8E;AAC9E,4DAA4D;AAC5D,8EAA8E;AAE9E,SAAS,WAAW;IAChB,MAAM,GAAG,GAAI,UAAsC,CAAC,SAAS,CAAA;IAC7D,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IACzD,OAAO,KAAK,IAAK,GAAc,CAAA;AACnC,CAAC;AAED,SAAS,WAAW;IAChB,MAAM,GAAG,GAAI,UAAwE,CAAC,QAAQ,CAAA;IAC9F,IAAI,OAAO,GAAG,EAAE,aAAa,KAAK,UAAU;QAAE,OAAO,KAAK,CAAA;IAC1D,MAAM,MAAM,GAAG,GAAG,CAAC,aAAa,CAAC,QAAQ,CAExC,CAAA;IACD,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU;QAAE,OAAO,KAAK,CAAA;IACzD,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAA;AAC/C,CAAC;AAED,SAAS,aAAa;IAClB,MAAM,GAAG,GAAI,UAAwE,CAAC,QAAQ,CAAA;IAC9F,IAAI,OAAO,GAAG,EAAE,aAAa,KAAK,UAAU;QAAE,OAAO,KAAK,CAAA;IAC1D,MAAM,MAAM,GAAG,GAAG,CAAC,aAAa,CAAC,QAAQ,CAExC,CAAA;IACD,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU;QAAE,OAAO,KAAK,CAAA;IACzD,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,IAAI,CAAA;AAC3C,CAAC;AAED,8EAA8E;AAC9E,qEAAqE;AACrE,8EAA8E;AAE9E,SAAS,QAAQ,CAAC,KAAoB;IAClC,IAAI,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAChD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;QACtD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;IACpC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,MAAM,UAAU,GAAgC,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAA;AAEhF;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAC9B,IAAgC;IAEhC,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,EAAE,CAAA;IACjC,MAAM,WAAW,GAAa,EAAE,CAAA;IAChC,MAAM,KAAK,GAAmB,EAAE,CAAA;IAEhC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAChB,MAAM,KAAK,GACP,IAAI,KAAK,QAAQ;YACb,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,WAAW,CAAC;YAChC,CAAC,CAAC,IAAI,KAAK,QAAQ;gBACf,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,WAAW,CAAC;gBAChC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,IAAI,aAAa,CAAC,CAAA;QAChD,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;QACzB,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC;YACP,OAAO;gBACH,IAAI;gBACJ,MAAM,EAAE,YAAY,IAAI,KAAK,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBAC3G,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC;aACpB,CAAA;QACL,CAAC;QACD,WAAW,CAAC,IAAI,CACZ,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,YAAY,CAAC,CAAC,KAAK,GAAG,CAC9E,CAAA;IACL,CAAC;IAED,OAAO;QACH,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,uBAAuB,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QACvD,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC;KACpB,CAAA;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACrC,IAAgC;IAEhC,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAA;IAClC,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,MAAM,IAAI,eAAe,CACrB,eAAe,EACf,8BAA8B,CAAC,CAAC,MAAM,EAAE,CAC3C,CAAA;IACL,CAAC;IACD,OAAO,CAAC,CAAA;AACZ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAe,EAAE,CAAe;IAChE,MAAM,EAAE,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAA;IAChC,MAAM,EAAE,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAA;IAChC,IAAI,EAAE,GAAG,EAAE;QAAE,OAAO,CAAC,CAAA;IACrB,IAAI,EAAE,GAAG,EAAE;QAAE,OAAO,CAAC,CAAC,CAAA;IACtB,OAAO,CAAC,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAkB,EAAE,OAAqB;IACnE,OAAO,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;AAClD,CAAC"}

package/dist/renderer-tier/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @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';
+//# sourceMappingURL=index.d.ts.map

package/dist/renderer-tier/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/renderer-tier/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACH,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,EACnB,aAAa,GAChB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACH,aAAa,EACb,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,GAC5B,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACH,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GACjC,MAAM,SAAS,CAAA"}

package/dist/renderer-tier/index.js

@@ -0,0 +1,12 @@
+/**
+ * @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, } from './selectBackend';
+export { RENDERER_TIER_RANK, } from './types';
+//# sourceMappingURL=index.js.map

package/dist/renderer-tier/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/renderer-tier/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACH,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,EACnB,aAAa,GAChB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACH,aAAa,EACb,oBAAoB,GAKvB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACH,kBAAkB,GAKrB,MAAM,SAAS,CAAA"}