@invinite-org/chartlang-adapter-kit 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Invinite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @invinite-org/chartlang-adapter-kit
+
+`experimental`
+
+SDK for writing chartlang adapters in consumer repos. It ships the adapter
+contract, capabilities model, emission validators, mock candles, and test base
+classes.
+
+## Install
+
+```bash
+pnpm add @invinite-org/chartlang-adapter-kit
+```
+
+## Public surface
+
+- `defineAdapter(opts) -> Adapter` — factory preserving optional hooks such as
+  `symInfo` and `resolveInputs`.
+- `capabilities` — builders for plots, alerts, 61 drawing kinds, drawing
+  groups, and Phase 4 capability fields: `intervals(...)`,
+  `multiTimeframe(...)`, `subPanes(...)`, `symInfoFields(...)`,
+  `maxDrawingsPerScript(...)`, `alertConditions(...)`, and `logs(...)`.
+- `validateEmission(e) -> ValidationResult` — validates plot, alert, drawing,
+  diagnostic, log, and alert-condition payloads.
+- `decodeDrawing(e) -> DrawingState | null`.
+- `bucketFor(kind)`, `KIND_BUCKET`, and drawing kind maps from core.
+- `mockCandleSource(bars, opts)` for tests, conformance scenarios,
+  and demos. `opts.mode` selects `"history"` (default), `"stream"`,
+  or `"history-then-stream"` (one history batch followed by per-bar
+  `close` events for the trailing `streamTail` bars).
+- `PassThroughAdapter`, `BufferingAdapter`.
+- Types: `Adapter`, `Capabilities`, `CandleEvent`, emissions, diagnostics,
+  input kinds, `SymInfoField`, `RunnerEmissions`, and `DefineAdapterOpts`.
+
+## Minimum-viable API call
+
+```ts
+import { capabilities, defineAdapter, mockCandleSource } from "@invinite-org/chartlang-adapter-kit";
+
+export default defineAdapter({
+    id: "demo",
+    name: "Demo",
+    capabilities: {
+        plots: capabilities.allLines(),
+        drawings: new Set(),
+        alerts: capabilities.alerts("toast"),
+        alertConditions: false,
+        logs: false,
+        inputs: new Set(),
+        intervals: capabilities.intervals([{ value: "1D", label: "1 day", group: "daily" }]).intervals,
+        multiTimeframe: false,
+        subPanes: 0,
+        symInfoFields: new Set(),
+        maxDrawingsPerScript: { lines: 0, labels: 0, boxes: 0, polylines: 0, other: 0 },
+        maxLookback: 5000,
+        maxTickHz: 10,
+    },
+    candles: () => mockCandleSource([], { interval: "1D" }),
+    onEmissions: () => {},
+});
+```
+
+## Docs
+
+See [`docs/adapters/contract.md`](../../docs/adapters/contract.md).
+
+## License
+
+MIT

package/dist/base/bufferingAdapter.d.ts

@@ -0,0 +1,52 @@
+import type { Adapter, CandleEvent, Capabilities, RunnerEmissions } from "../types.js";
+/**
+ * `Adapter` that records every `onEmissions` batch and exposes a
+ * `drain()` method to retrieve them all at once. Used by the
+ * conformance suite (Task 11) to collect emissions across a full
+ * fixture playback before asserting against golden bars.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     import {
+ *         BufferingAdapter,
+ *         capabilities,
+ *         mockCandleSource,
+ *     } from "@invinite-org/chartlang-adapter-kit";
+ *
+ *     const a = new BufferingAdapter(
+ *         "b", "Buffering",
+ *         {
+ *             plots: capabilities.allLines(),
+ *             drawings: new Set(),
+ *             alerts: new Set(),
+ *             alertConditions: false,
+ *             logs: false,
+ *             inputs: new Set(),
+ *             intervals: [],
+ *             multiTimeframe: false,
+ *             subPanes: 0,
+ *             symInfoFields: new Set(),
+ *             maxDrawingsPerScript: {
+ *                 lines: 0, labels: 0, boxes: 0, polylines: 0, other: 0,
+ *             },
+ *             maxLookback: 5000,
+ *             maxTickHz: 10,
+ *         },
+ *         mockCandleSource([]),
+ *     );
+ *     a.drain();
+ */
+export declare class BufferingAdapter implements Adapter {
+    readonly id: string;
+    readonly name: string;
+    readonly capabilities: Capabilities;
+    private readonly source;
+    private buffered;
+    constructor(id: string, name: string, capabilities: Capabilities, source: AsyncIterable<CandleEvent>);
+    candles(): AsyncIterable<CandleEvent>;
+    onEmissions(emissions: RunnerEmissions): void;
+    drain(): ReadonlyArray<RunnerEmissions>;
+    dispose(): void;
+}
+//# sourceMappingURL=bufferingAdapter.d.ts.map

package/dist/base/bufferingAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bufferingAdapter.d.ts","sourceRoot":"","sources":["../../src/base/bufferingAdapter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,gBAAiB,YAAW,OAAO;aAIxB,EAAE,EAAE,MAAM;aACV,IAAI,EAAE,MAAM;aACZ,YAAY,EAAE,YAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAN3B,OAAO,CAAC,QAAQ,CAAyB;gBAGrB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,YAAY,EACzB,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC;IAGvD,OAAO,IAAI,aAAa,CAAC,WAAW,CAAC;IAIrC,WAAW,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI;IAI7C,KAAK,IAAI,aAAa,CAAC,eAAe,CAAC;IAMvC,OAAO,IAAI,IAAI;CAGlB"}

package/dist/base/bufferingAdapter.js

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+/**
+ * `Adapter` that records every `onEmissions` batch and exposes a
+ * `drain()` method to retrieve them all at once. Used by the
+ * conformance suite (Task 11) to collect emissions across a full
+ * fixture playback before asserting against golden bars.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     import {
+ *         BufferingAdapter,
+ *         capabilities,
+ *         mockCandleSource,
+ *     } from "@invinite-org/chartlang-adapter-kit";
+ *
+ *     const a = new BufferingAdapter(
+ *         "b", "Buffering",
+ *         {
+ *             plots: capabilities.allLines(),
+ *             drawings: new Set(),
+ *             alerts: new Set(),
+ *             alertConditions: false,
+ *             logs: false,
+ *             inputs: new Set(),
+ *             intervals: [],
+ *             multiTimeframe: false,
+ *             subPanes: 0,
+ *             symInfoFields: new Set(),
+ *             maxDrawingsPerScript: {
+ *                 lines: 0, labels: 0, boxes: 0, polylines: 0, other: 0,
+ *             },
+ *             maxLookback: 5000,
+ *             maxTickHz: 10,
+ *         },
+ *         mockCandleSource([]),
+ *     );
+ *     a.drain();
+ */
+export class BufferingAdapter {
+    id;
+    name;
+    capabilities;
+    source;
+    buffered = [];
+    constructor(id, name, capabilities, source) {
+        this.id = id;
+        this.name = name;
+        this.capabilities = capabilities;
+        this.source = source;
+    }
+    candles() {
+        return this.source;
+    }
+    onEmissions(emissions) {
+        this.buffered.push(emissions);
+    }
+    drain() {
+        const out = this.buffered.slice();
+        this.buffered = [];
+        return out;
+    }
+    dispose() {
+        this.buffered = [];
+    }
+}
+//# sourceMappingURL=bufferingAdapter.js.map

package/dist/base/bufferingAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bufferingAdapter.js","sourceRoot":"","sources":["../../src/base/bufferingAdapter.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,OAAO,gBAAgB;IAIL;IACA;IACA;IACC;IANb,QAAQ,GAAsB,EAAE,CAAC;IAEzC,YACoB,EAAU,EACV,IAAY,EACZ,YAA0B,EACzB,MAAkC;QAHnC,OAAE,GAAF,EAAE,CAAQ;QACV,SAAI,GAAJ,IAAI,CAAQ;QACZ,iBAAY,GAAZ,YAAY,CAAc;QACzB,WAAM,GAAN,MAAM,CAA4B;IACpD,CAAC;IAEJ,OAAO;QACH,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,WAAW,CAAC,SAA0B;QAClC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAED,KAAK;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;QACnB,OAAO,GAAG,CAAC;IACf,CAAC;IAED,OAAO;QACH,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;IACvB,CAAC;CACJ"}

package/dist/base/index.d.ts

@@ -0,0 +1,3 @@
+export { BufferingAdapter } from "./bufferingAdapter.js";
+export { PassThroughAdapter } from "./passThroughAdapter.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/base/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/base/index.js

@@ -0,0 +1,5 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+export { BufferingAdapter } from "./bufferingAdapter.js";
+export { PassThroughAdapter } from "./passThroughAdapter.js";
+//# sourceMappingURL=index.js.map

package/dist/base/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/base/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAE/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/base/passThroughAdapter.d.ts

@@ -0,0 +1,49 @@
+import type { Adapter, CandleEvent, Capabilities, RunnerEmissions } from "../types.js";
+/**
+ * Minimal `Adapter` that forwards a supplied `AsyncIterable<CandleEvent>`
+ * and drops every emission. Useful as a runtime test fixture when the
+ * caller doesn't need to observe outputs.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     import {
+ *         PassThroughAdapter,
+ *         capabilities,
+ *         mockCandleSource,
+ *     } from "@invinite-org/chartlang-adapter-kit";
+ *
+ *     const a = new PassThroughAdapter(
+ *         "p", "Passthrough",
+ *         {
+ *             plots: capabilities.allLines(),
+ *             drawings: new Set(),
+ *             alerts: new Set(),
+ *             alertConditions: false,
+ *             logs: false,
+ *             inputs: new Set(),
+ *             intervals: [],
+ *             multiTimeframe: false,
+ *             subPanes: 0,
+ *             symInfoFields: new Set(),
+ *             maxDrawingsPerScript: {
+ *                 lines: 0, labels: 0, boxes: 0, polylines: 0, other: 0,
+ *             },
+ *             maxLookback: 5000,
+ *             maxTickHz: 10,
+ *         },
+ *         mockCandleSource([]),
+ *     );
+ *     void a;
+ */
+export declare class PassThroughAdapter implements Adapter {
+    readonly id: string;
+    readonly name: string;
+    readonly capabilities: Capabilities;
+    private readonly source;
+    constructor(id: string, name: string, capabilities: Capabilities, source: AsyncIterable<CandleEvent>);
+    candles(): AsyncIterable<CandleEvent>;
+    onEmissions(_emissions: RunnerEmissions): void;
+    dispose(): void;
+}
+//# sourceMappingURL=passThroughAdapter.d.ts.map

package/dist/base/passThroughAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passThroughAdapter.d.ts","sourceRoot":"","sources":["../../src/base/passThroughAdapter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,kBAAmB,YAAW,OAAO;aAE1B,EAAE,EAAE,MAAM;aACV,IAAI,EAAE,MAAM;aACZ,YAAY,EAAE,YAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAHP,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,YAAY,EACzB,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC;IAGvD,OAAO,IAAI,aAAa,CAAC,WAAW,CAAC;IAIrC,WAAW,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAI9C,OAAO,IAAI,IAAI;CAGlB"}

package/dist/base/passThroughAdapter.js

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+/**
+ * Minimal `Adapter` that forwards a supplied `AsyncIterable<CandleEvent>`
+ * and drops every emission. Useful as a runtime test fixture when the
+ * caller doesn't need to observe outputs.
+ *
+ * @since 0.1
+ * @stable
+ * @example
+ *     import {
+ *         PassThroughAdapter,
+ *         capabilities,
+ *         mockCandleSource,
+ *     } from "@invinite-org/chartlang-adapter-kit";
+ *
+ *     const a = new PassThroughAdapter(
+ *         "p", "Passthrough",
+ *         {
+ *             plots: capabilities.allLines(),
+ *             drawings: new Set(),
+ *             alerts: new Set(),
+ *             alertConditions: false,
+ *             logs: false,
+ *             inputs: new Set(),
+ *             intervals: [],
+ *             multiTimeframe: false,
+ *             subPanes: 0,
+ *             symInfoFields: new Set(),
+ *             maxDrawingsPerScript: {
+ *                 lines: 0, labels: 0, boxes: 0, polylines: 0, other: 0,
+ *             },
+ *             maxLookback: 5000,
+ *             maxTickHz: 10,
+ *         },
+ *         mockCandleSource([]),
+ *     );
+ *     void a;
+ */
+export class PassThroughAdapter {
+    id;
+    name;
+    capabilities;
+    source;
+    constructor(id, name, capabilities, source) {
+        this.id = id;
+        this.name = name;
+        this.capabilities = capabilities;
+        this.source = source;
+    }
+    candles() {
+        return this.source;
+    }
+    onEmissions(_emissions) {
+        // intentional no-op
+    }
+    dispose() {
+        // intentional no-op
+    }
+}
+//# sourceMappingURL=passThroughAdapter.js.map

package/dist/base/passThroughAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passThroughAdapter.js","sourceRoot":"","sources":["../../src/base/passThroughAdapter.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,+DAA+D;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,OAAO,kBAAkB;IAEP;IACA;IACA;IACC;IAJrB,YACoB,EAAU,EACV,IAAY,EACZ,YAA0B,EACzB,MAAkC;QAHnC,OAAE,GAAF,EAAE,CAAQ;QACV,SAAI,GAAJ,IAAI,CAAQ;QACZ,iBAAY,GAAZ,YAAY,CAAc;QACzB,WAAM,GAAN,MAAM,CAA4B;IACpD,CAAC;IAEJ,OAAO;QACH,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,WAAW,CAAC,UAA2B;QACnC,oBAAoB;IACxB,CAAC;IAED,OAAO;QACH,oBAAoB;IACxB,CAAC;CACJ"}