openalgo-script 0.1.0-alpha.1 → 0.4.0

package/README.md

@@ -17,21 +17,59 @@ can write their own engine for it.
 
 ## Status
 
-**`0.1.0-alpha.0` parses. It does not yet compute anything.**
-
-That is the honest description of what an install gets you today: a lexer, a
-parser, a syntax tree, and diagnostics carrying a code, a line, a column and a
-fix. It will tell you whether a script is well formed. It will not calculate a
-moving average, draw anything, or place an order.
-
-The registry shows this version under `latest` only because a package must have
-one and this is the first release. The `-alpha.0` on the version is the part to
-read.
-
-The checker and the engine are Phase 2, and the roadmap says what each phase owes
-before it is allowed to finish. The specification is written first and the
-implementation follows it, which is why there is a great deal more specification
-here than there is compiler.
+**`0.4.0` runs studies, backtests strategies, and ships the language
+intelligence an editor needs.**
+
+What an install gets you today: the compiler, the engine, the chart adapter and
+the backtest. A script compiles in milliseconds in a browser tab and computes,
+bar by bar, the same numbers everywhere. One hundred and one independently
+written studies compile, load and run, and five of them match arithmetic
+transcribed from the specification alone, bit for bit, warmups included.
+
+A strategy is walked over a range of bars and what comes back is a document
+rather than a number: the program, the bars, the settings, every frame, every
+fill, the ledger and the report. That document replays to the same report and
+reruns to the same bytes, and `npm test` proves it over the shipped strategy
+examples on every run rather than asserting it in a page. Two records can be put
+beside each other, and a pair over different bars is reported incomparable
+instead of being subtracted into a table that reads like a result.
+
+What it does **not** do yet, stated plainly because the registry page is the
+first thing a stranger reads:
+
+- **The backtest does not model everything, and says which.** A bracket's stop
+  cannot fill, because the engine appends no order row for a bracket. A quantity
+  stated in cash or in a percentage of equity is refused rather than filled,
+  because a backtest works out no running equity to size against. The equity
+  curve marks a trade at the size it ended up entering, so a strategy that
+  scales in is reported with a drawdown deeper than the account had. A script
+  still cannot read its own equity mid-run. The `0.4.0` entry in
+  [`CHANGELOG.md`](./CHANGELOG.md) is the full list, and every item on it is
+  there because somebody would otherwise find it inside a report they had
+  already believed.
+- **No editor on screen, and that is the design.** The six headless functions are
+  here and resolve as `openalgo-script/editor`: highlight, complete, diagnose,
+  hover, signature and format, text in and data out, with no DOM at any tier. The
+  text component, the panel, the apply button, saving and the theme are yours,
+  and the drop-in adapter for one editor component wires the six into it without
+  drawing anything itself. What each function gives you, and what stays yours, is
+  in
+  [`docs/integrating/the-editor-half.md`](./docs/integrating/the-editor-half.md).
+  The language server that would put the same errors in a desktop editor is the
+  rest of Phase 4 and is not written.
+- **No second engine, and no case files to hand one.** The Python engine and the
+  conformance suite that would prove two engines agree are Phase 6. A run record
+  is the case, but the files a suite is run from cannot be written from one yet:
+  a case has to carry the source text and a record carries the source's hash.
+  Until an engine somebody else wrote passes that suite, the portability claim is
+  a design, not a result.
+
+The version is `0.4.0` rather than `1.0` because of that list. The studies
+surface is the part that is finished, and it is the part to build on.
+
+`ROADMAP.md` says what each phase owes before it is allowed to finish. The
+specification is written first and the implementation follows it, which is why
+there is still more specification here than compiler.
 
 ## What it looks like
 
@@ -75,7 +113,7 @@ OpenScript is the opposite of that:
 
 - **Yours.** Plain text files in a folder. Version control, diffs, your own editor.
 - **Local.** It compiles and runs on your machine. No execution quota, no loop
-  timeout, no cap on how many things you may draw.
+  timeout, and nothing you drew silently dropped to make room for the next one.
 - **Honest.** A higher timeframe read has to say whether it repaints. The
   compiler warns when a script would.
 - **Connected.** The same script places real orders through your own broker
@@ -130,9 +168,11 @@ and the dependencies only ever point one way.
         |       \            /
         |   .../adapters/charts       <- knows both. The only place that does
         |
-   .../editor
+   .../editor                         <- the six headless functions. No DOM, no
+        |                                 package, nothing on screen
         |
-   .../adapters/codemirror            <- knows the editor component. Nothing else does
+   .../adapters/codemirror            <- knows both. Takes its markup from the
+                                         host, so it draws nothing either
 ```
 
 The language ships as one package with an entry point per tier, so a consumer who
@@ -140,13 +180,20 @@ wants only the compiler never pays for an adapter. A tier is declared only once
 exists: an entry point that resolves to nothing fails at a consumer's run time
 rather than honestly at install.
 
+These four resolve today, from an install holding nothing but the manifest and the
+built output. That is a check rather than a sentence: `scripts/check-entry-points.mjs`
+builds exactly that install in a temporary directory, with no package of any kind
+beside it, and imports every one of them.
+
 | Entry point | Is | Depends on |
 |---|---|---|
 | `openalgo-script` | Compiler and engine | Nothing |
-| `openalgo-script/editor` | Highlight, complete, diagnose, hover, signature, format. No DOM | The compiler |
+| `openalgo-script/editor` | The six headless language functions an editor needs | The compiler |
 | `openalgo-script/adapters/charts` | Turns a compiled study into a chart's indicator descriptor | The compiler and a chart |
-| `openalgo-script/adapters/codemirror` | A drop-in editor language package | The editor half and an editor component |
-| The Python engine, on its own index | The same compiled program, run on a server | Nothing |
+| `openalgo-script/adapters/codemirror` | Wires the six into a text component | The editor half and a text component |
+
+The server-side engine is not among them: it is a separate package in another
+language, and the roadmap says which phase owes it.
 
 An adapter is the only thing allowed to know two worlds at once, which is what
 makes it the piece a platform replaces rather than the piece they patch. A
@@ -155,8 +202,10 @@ else. A platform with its own editor does the same on that side.
 
 This is enforced rather than promised. `scripts/check-layering.mjs` runs in
 continuous integration and fails the build if the compiler imports a chart, if
-anything outside an adapter imports a package, or if the compiler or the editor
-half so much as mentions a browser global.
+anything outside an adapter imports a package, or if anything under `src` so much
+as mentions a browser global. That last one holds of the adapters too: the editor
+adapter takes a tooltip's markup from the host rather than building an element,
+so every file in the package loads in a worker and on a server.
 
 ## Taking it, one step at a time
 
@@ -166,7 +215,7 @@ Each row is usable on its own. Nobody has to take the next one.
 |---|---|---|
 | Scripts that produce numbers | `openalgo-script`, and the six-item host interface | An afternoon |
 | Those studies on your chart | the charts adapter, plus a chart | Days. Free if the chart is the one this adapter already targets |
-| Traders authoring in your app | `openalgo-script/editor`, and your own text component or the drop-in one | Days |
+| Traders authoring in your app | The editor half, and your own text component or the drop-in adapter | Days |
 | Traders trading from it | Wire the order half of the host interface to your order API | About a week |
 | To run it on your own stack | Implement the compiled program format in your language, then pass the conformance suite | Weeks |
 
@@ -184,18 +233,24 @@ fails the build.
 
 | Guarantee | How you can tell | Today |
 |---|---|---|
-| No `eval`, no generated code, runs under a strict content security policy | Grep the source. There is no code construction anywhere, and the compiler emits data | Enforced |
+| The package cannot build code out of text: every door to a generator is a module, and it imports none of them | `scripts/check-layering.mjs`. Nothing under `src` may import a module from the runtime's own namespace, at either spelling, and no load may have a specifier that is not written down. So there is no virtual machine, no worker and no child process in the graph to reach. Unreachable by construction, not unmatched by a pattern | Enforced |
+| The two names that need no import, the string evaluator and the function builder, are refused | A runtime switch you set on your own process, `--disallow-code-generation-from-strings`. Our own suite runs under it. It refuses those two names and closes no other door: see [`docs/integrating/running-the-engine.md`](./docs/integrating/running-the-engine.md) for what it does not cover and what is yours to do | Yours to turn on |
+| No generator anywhere in this repository's own text | `scripts/check-no-eval.mjs`, over the source, both built outputs, the tooling, the hooks and the build steps, attacking itself with every form it knows before it reads a file. **It is a lint, not a proof.** It has now been got past five times, the last by a constructor reached through a key assembled at run time, and a list of spellings only ever has to be beaten once more. Treat a pass as evidence that no known form is present | **Lint** |
+| A generator that runs is refused | The suite runs under the setting that refuses to compile text, so a builder throws the moment its path executes, however it was spelled. This caught the form the scan missed. What it cannot cover: a line no test reaches, and the module doors above, which is why the row above it matters more than this one | Enforced, for code the tests execute |
 | Zero runtime dependencies | `dependencies` is empty and stays empty | Enforced |
 | The pieces are separable: take the language without the chart, or the chart without the language | `scripts/check-layering.mjs`. The core may not import a package or touch a browser global | Enforced |
 | Small modules with a stated surface | `scripts/check-modularity.mjs`. A module's index is its only door | Enforced |
-| Every error is documented, with a code, a cause and a fix | `scripts/check-error-codes.mjs`, and the code type is generated from the catalogue so an invented code will not compile | Enforced |
+| Every error is documented, with a code, a cause and a fix | `scripts/check-error-codes.mjs` reads every file in the tree, and the code type is generated from the catalogue so an invented code will not compile. `scripts/check-catalogue-tests.mjs` compares the catalogue a reader opens with the file the compiler is generated from, string for string, so the two cannot say different things | Enforced |
 | No fact is stated in two places | `scripts/check-duplication.mjs` | Enforced, with recorded debt |
-| The compiled program is implementable without reading our code | `spec/compiled-program.md` and `spec/host-interface.md` | Written |
+| The compiled program is implementable without reading our code | `spec/compiled-program.md` and `spec/host-interface.md`. Every engine test drives a host built from those pages rather than one we wrote | Written, and used |
 | Two engines agree to the last decimal | The conformance suite, run against both. A disagreement blocks a release | Phase 6 gate |
-| A runaway script stops | Instruction, memory and wall clock budgets, enforced by the engine that owns the loop | Phase 2 gate |
-| A failing script does not take anything else down | One script's failure is a diagnostic on that script | Phase 2 gate |
+| A runaway script stops | Instruction, memory and wall clock budgets, counters in the loop the engine owns. `tests/engine/budget.test.ts` | Enforced |
+| A failing script does not take anything else down | One script's failure is a diagnostic on that script and reaches nothing else | Enforced |
+| Every entry point in the export map resolves from a real install | `scripts/check-entry-points.mjs`. Each one is imported from a temporary install built from the `files` list alone, with no package beside it, which is also what says both adapters' peer dependencies are optional in fact and not only in the manifest | Enforced |
+| A completion, a tooltip and a default come from the compiler, not from a list | The names are the standard library manifest the checker resolves against; what a call is for is the cell `spec/stdlib.md` prints, read at build time by `scripts/generate-library-prose.mjs`; a default is the one `scripts/check-defaults.mjs` holds the compiler to. `tests/editor/hover.test.ts` fails if the manifest and the specification describe different sets of names | Enforced |
+| Laying a script out again cannot change what it computes | `tests/editor/format.test.ts`. Every example and every gate script is formatted, both texts are compiled, and the compiled programs are compared. Each call also checks itself against the lexer, so a rule that is wrong returns your source untouched rather than a changed program | Enforced |
 | A saved script never stops working | The language version is declared per file and old front ends are retained | Phase 7, with a test per retained version |
-| Performance | A benchmark with a number, in continuous integration | Phase 2 gate |
+| Performance | Eight benchmarks with recorded budgets, run by `npm test` and in continuous integration. A regression past a budget fails the build | Enforced |
 
 The rows marked as gates are not promises we intend to keep. They are conditions a
 phase does not finish without, and each one is written into the roadmap beside the

package/dist/adapters/charts/alerts.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Declared alerts into the chart's watched conditions.
+ *
+ * An `alert()` call site is lifted by the compiler into one declared entry: a
+ * boolean channel carrying the chain of guards that reaches the call, a string
+ * channel carrying the message, a stable key and a title (`stdlib.md` 16.1). The
+ * chart's own watched condition is a row with a stable id, a title and a
+ * predicate it evaluates per bar, so the mapping is the boolean channel: it
+ * rides the values table as a column, and the predicate reads that column at the
+ * bar it is judging.
+ *
+ * **Nothing fires for history, and the chart is what applies that.** It judges
+ * only bars that are new since it last looked, so a study added at noon to a
+ * chart holding two years announces none of them, and a settings change, which
+ * recomputes the whole history without adding a bar, announces nothing either.
+ * That is `stdlib.md` 16.2 reached from the host's side rather than the engine's,
+ * and it is the rule the descriptor's own slot already carries.
+ *
+ * **An absent condition is not a true one.** The column holds a number where the
+ * channel published `true` and `null` everywhere else, so an alert under a guard
+ * that was absent during warmup does not fire. That is `language.md` 6.6's three
+ * valued logic reaching a surface, and it is the most common reason a new alert
+ * looks dead.
+ *
+ * **The message is computed on the bar that fired, and it travels.** It is a
+ * string per bar, so it cannot ride the table of numbers the calculation
+ * returns, and the entry's own field takes a function of the same context the
+ * predicate was judged on: the bars, the columns, the settings and the bar's
+ * index. The settings are the study instance (`produced.ts`), so the message
+ * reads the run's own string channel there, at the one bar it is asked about,
+ * and the alert a user receives carries the numbers the script put in it.
+ *
+ * A message the bar published nothing for falls back to the declared title,
+ * which is what the chart itself does for an entry that states no message. That
+ * is the honest answer for the one case that reaches it: `message` is a required
+ * argument, so the string is absent only where the expression that built it was,
+ * and absence reaching a surface draws nothing of its own (`language.md` 6.7).
+ *
+ * **One thing a declared alert carries still has no field on the chart's entry**
+ * and is left out rather than approximated. The **frequency** (`stdlib.md` 16.2)
+ * has nowhere to land: the chart evaluates each entry once for each new bar,
+ * which is `"oncePerBar"`; `"once"` would need state that lives as long as the
+ * study instance and `"everyUpdate"` would need the entry to be evaluated again
+ * on a bar that is still moving, and the entry is handed neither. It is recorded
+ * with its reason in `spec/chart-narrowings.json`, which
+ * `scripts/check-chart-surface.mjs` refuses to let grow in silence.
+ */
+import type { CompiledProgram } from '../../core/emit/index.js';
+import type { ColumnSpec } from './columns.js';
+import type { InputLookup } from './fields.js';
+import type { MessageColumn } from './produced.js';
+import type { Columns } from './run.js';
+import type { ChartAlertSpec } from './surfaces.js';
+/** The key one alert's condition column travels under. */
+export declare function alertKey(index: number): string;
+export interface AlertBuild {
+    readonly alerts: readonly ChartAlertSpec[];
+    readonly columns: readonly ColumnSpec[];
+}
+/**
+ * Each declared alert's message channel, as the run left it.
+ *
+ * Indexed by the alert's position in `outputs.alerts`, so an entry the program
+ * declares without a message channel holds an empty column rather than shifting
+ * the ones after it.
+ */
+export declare function alertMessages(program: CompiledProgram, columns: Columns): readonly MessageColumn[];
+/** The rows a user subscribes to, fixed before the first bar. */
+export declare function buildAlerts(program: CompiledProgram, lookup: InputLookup): AlertBuild;
+//# sourceMappingURL=alerts.d.ts.map

package/dist/adapters/charts/alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.d.ts","sourceRoot":"","sources":["../../../src/adapters/charts/alerts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAqB,cAAc,EAAE,MAAM,eAAe,CAAC;AAEvE,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;CACzC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,OAAO,GACf,SAAS,aAAa,EAAE,CAK1B;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,GAAG,UAAU,CAyBrF"}

package/dist/adapters/charts/alerts.js

@@ -0,0 +1,52 @@
+import { stringField } from './fields.js';
+import { producedFor } from './produced.js';
+/** The key one alert's condition column travels under. */
+export function alertKey(index) {
+    return `openscript:alert:${index}`;
+}
+/**
+ * Each declared alert's message channel, as the run left it.
+ *
+ * Indexed by the alert's position in `outputs.alerts`, so an entry the program
+ * declares without a message channel holds an empty column rather than shifting
+ * the ones after it.
+ */
+export function alertMessages(program, columns) {
+    return program.outputs.alerts.map((declared) => {
+        const channel = declared.messageChannel;
+        return channel === null ? [] : (columns[channel] ?? []);
+    });
+}
+/** The rows a user subscribes to, fixed before the first bar. */
+export function buildAlerts(program, lookup) {
+    const alerts = [];
+    const columns = [];
+    for (let index = 0; index < program.outputs.alerts.length; index += 1) {
+        const declared = program.outputs.alerts[index];
+        if (declared === undefined)
+            continue;
+        const key = alertKey(index);
+        const title = stringField(declared.title, lookup, '');
+        columns.push({ key, channel: declared.condChannel, part: 'flag' });
+        alerts.push({
+            id: declared.key,
+            title,
+            // A program whose alert has no message channel states no message, and the
+            // chart's own default for that is the title. Declaring a function that
+            // returned the title anyway would hide that fact behind this adapter.
+            ...(declared.messageChannel === null
+                ? {}
+                : {
+                    message: (ctx) => messageAt(producedFor(ctx.settings).messages[index], ctx.index) ?? title,
+                }),
+            when: (ctx) => ctx.values[key]?.[ctx.index] === 1,
+        });
+    }
+    return { alerts, columns };
+}
+/** The message one bar published, or nothing where it published none. */
+function messageAt(column, index) {
+    const value = column?.[index];
+    return typeof value === 'string' ? value : undefined;
+}
+//# sourceMappingURL=alerts.js.map

package/dist/adapters/charts/alerts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.js","sourceRoot":"","sources":["../../../src/adapters/charts/alerts.ts"],"names":[],"mappings":"AAiDA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAI5C,0DAA0D;AAC1D,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,oBAAoB,KAAK,EAAE,CAAC;AACrC,CAAC;AAOD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAwB,EACxB,OAAgB;IAEhB,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;QAC7C,MAAM,OAAO,GAAG,QAAQ,CAAC,cAAc,CAAC;QACxC,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,WAAW,CAAC,OAAwB,EAAE,MAAmB;IACvE,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtE,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,QAAQ,KAAK,SAAS;YAAE,SAAS;QACrC,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5B,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QACtD,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACnE,MAAM,CAAC,IAAI,CAAC;YACV,EAAE,EAAE,QAAQ,CAAC,GAAG;YAChB,KAAK;YACL,0EAA0E;YAC1E,uEAAuE;YACvE,sEAAsE;YACtE,GAAG,CAAC,QAAQ,CAAC,cAAc,KAAK,IAAI;gBAClC,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC;oBACE,OAAO,EAAE,CAAC,GAAsB,EAAU,EAAE,CAC1C,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK;iBAC3E,CAAC;YACN,IAAI,EAAE,CAAC,GAAsB,EAAW,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;SAC9E,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC;AAED,yEAAyE;AACzE,SAAS,SAAS,CAAC,MAAiC,EAAE,KAAa;IACjE,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC"}

package/dist/adapters/charts/bars.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A chart's bar as the engine reads one.
+ *
+ * One fact differs across the boundary and it is easy to get wrong in a way
+ * nothing catches. A chart's bar time is in **seconds** and the engine's is in
+ * **milliseconds**, so every time crosses through here and nowhere else; a study
+ * comparing `time` against an anchor would be a thousand times out and would
+ * still draw. Every other field is spelled on both sides as
+ * `host-interface.md` 3.1 spells it, so nothing here renames anything.
+ *
+ * **Absence survives the crossing.** A bar with no volume arrives with the field
+ * missing and leaves with it missing, because a script that sizes something by
+ * volume has to be able to tell "no trades" from "nobody said", and a zero put
+ * in here would answer the wrong one of those for ever.
+ *
+ * **Nothing here says where a session begins.** The session is a range of hours
+ * in the instrument record (`host-interface.md` 4.3), the engine derives the
+ * per-bar facts from it, and a chart's own host states those hours alongside
+ * the exchange and the lot size. An option here that set the flags per bar would be
+ * a second source for a fact the engine already derives, and the two would
+ * disagree on the study every intraday chart draws.
+ */
+import type { BarState, HostBar } from '../../core/engine/index.js';
+import type { ChartBar, ChartCalcContext } from './contract.js';
+/** Milliseconds in a second, so the conversion is named rather than a literal. */
+export declare const MS = 1000;
+export declare function hostBar(bar: ChartBar): HostBar;
+/** A chart's wall clock reading, in the units the engine's `chart.now()` uses. */
+export declare function hostNow(seconds: number): number;
+/**
+ * What the host states about one execution.
+ *
+ * Only the newest bar can be unconfirmed or driven by a live feed: every bar
+ * before it is history, whatever the feed behind the chart is doing now. The
+ * chart's own calculation context says which of those two the newest bar is,
+ * and says nothing at all about the ones before it, which is the same split.
+ */
+export declare function stateFor(index: number, bars: readonly ChartBar[], ctx: ChartCalcContext | undefined): BarState;
+//# sourceMappingURL=bars.d.ts.map

package/dist/adapters/charts/bars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bars.d.ts","sourceRoot":"","sources":["../../../src/adapters/charts/bars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEhE,kFAAkF;AAClF,eAAO,MAAM,EAAE,OAAO,CAAC;AAEvB,wBAAgB,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAU9C;AAED,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,QAAQ,EAAE,EACzB,GAAG,EAAE,gBAAgB,GAAG,SAAS,GAChC,QAAQ,CAKV"}

package/dist/adapters/charts/bars.js

@@ -0,0 +1,32 @@
+/** Milliseconds in a second, so the conversion is named rather than a literal. */
+export const MS = 1000;
+export function hostBar(bar) {
+    return {
+        open: bar.open,
+        high: bar.high,
+        low: bar.low,
+        close: bar.close,
+        time: Number.isFinite(bar.time) ? bar.time * MS : null,
+        ...(bar.volume === undefined ? {} : { volume: bar.volume }),
+        ...(bar.oi === undefined ? {} : { oi: bar.oi }),
+    };
+}
+/** A chart's wall clock reading, in the units the engine's `chart.now()` uses. */
+export function hostNow(seconds) {
+    return seconds * MS;
+}
+/**
+ * What the host states about one execution.
+ *
+ * Only the newest bar can be unconfirmed or driven by a live feed: every bar
+ * before it is history, whatever the feed behind the chart is doing now. The
+ * chart's own calculation context says which of those two the newest bar is,
+ * and says nothing at all about the ones before it, which is the same split.
+ */
+export function stateFor(index, bars, ctx) {
+    const last = index === bars.length - 1;
+    const isConfirmed = !last || ctx === undefined ? true : ctx.barState.isConfirmed;
+    const isRealtime = last && ctx !== undefined ? ctx.barState.isRealtime : false;
+    return { isConfirmed, isRealtime };
+}
+//# sourceMappingURL=bars.js.map

package/dist/adapters/charts/bars.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bars.js","sourceRoot":"","sources":["../../../src/adapters/charts/bars.ts"],"names":[],"mappings":"AAyBA,kFAAkF;AAClF,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;AAEvB,MAAM,UAAU,OAAO,CAAC,GAAa;IACnC,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI;QACtD,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;QAC3D,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;KAChD,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,OAAO,OAAO,GAAG,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAa,EACb,IAAyB,EACzB,GAAiC;IAEjC,MAAM,IAAI,GAAG,KAAK,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IACvC,MAAM,WAAW,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC;IACjF,MAAM,UAAU,GAAG,IAAI,IAAI,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;IAC/E,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;AACrC,CAAC"}

package/dist/adapters/charts/candles.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A candle plot: one declaration, four columns.
+ *
+ * `plotCandles` is one entry with one key and one legend row, and the four
+ * values it draws travel as four ordinary columns that the entry names. The
+ * chart's descriptor has exactly that shape, so the mapping is a rename.
+ *
+ * The colours are where the two contracts differ and the difference is worth
+ * stating. A candle's colour is declared four ways: one for a bar that closed at
+ * or above its open, one for a bar that closed below, and two overrides for the
+ * wick and the border alone. Where all four are constants they are the series'
+ * own style and cost nothing per bar. Where a script passed a series colour
+ * instead, the value arrives on a channel and the colour is decided per bar,
+ * which is the split callback the chart takes.
+ *
+ * **A null override means the wick or the border follows the body**, which is
+ * the opposite of a null colour on a line plot: the host may choose an
+ * undecorated line's colour because nothing depends on it, and a wick the host
+ * coloured independently of the body it grows out of would draw a different
+ * candle on every chart. So an override with neither a channel nor a declared
+ * value is answered with the body's own colour for that bar, and one with a
+ * declared value is left alone for the style to carry.
+ */
+import type { CandleChannels } from '../../core/emit/index.js';
+import type { ChartBarColor, ChartColorContext, ChartSeriesStyle } from './contract.js';
+import type { ColumnSpec } from './columns.js';
+import type { InputLookup } from './fields.js';
+export interface CandleBuild {
+    readonly ohlc: {
+        readonly open: string;
+        readonly high: string;
+        readonly low: string;
+        readonly close: string;
+    };
+    readonly style: ChartSeriesStyle;
+    readonly columns: readonly ColumnSpec[];
+    readonly colorParts: ((ctx: ChartColorContext) => ChartBarColor | undefined) | undefined;
+}
+export declare function buildCandle(key: string, ohlc: CandleChannels, lookup: InputLookup): CandleBuild;
+//# sourceMappingURL=candles.d.ts.map

package/dist/adapters/charts/candles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candles.d.ts","sourceRoot":"","sources":["../../../src/adapters/charts/candles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAExF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,GAAG,EAAE,iBAAiB,KAAK,aAAa,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CAC1F;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,GAAG,WAAW,CAmE/F"}

package/dist/adapters/charts/candles.js

@@ -0,0 +1,85 @@
+import { cssColour } from './colours.js';
+import { colourAt, colourColumns } from './columns.js';
+import { colourField } from './fields.js';
+export function buildCandle(key, ohlc, lookup) {
+    const keys = {
+        open: `${key}:open`,
+        high: `${key}:high`,
+        low: `${key}:low`,
+        close: `${key}:close`,
+    };
+    const up = colourField(ohlc.colorUp, lookup);
+    const down = colourField(ohlc.colorDown, lookup);
+    const wick = colourField(ohlc.wickColor, lookup);
+    const border = colourField(ohlc.borderColor, lookup);
+    const borderUp = border ?? up;
+    const borderDown = border ?? down;
+    const wickUp = wick ?? up;
+    const wickDown = wick ?? down;
+    const style = {
+        ...(up === undefined ? {} : { upColor: cssColour(up) }),
+        ...(down === undefined ? {} : { downColor: cssColour(down) }),
+        ...(borderUp === undefined ? {} : { borderUpColor: cssColour(borderUp) }),
+        ...(borderDown === undefined ? {} : { borderDownColor: cssColour(borderDown) }),
+        ...(wickUp === undefined ? {} : { wickUpColor: cssColour(wickUp) }),
+        ...(wickDown === undefined ? {} : { wickDownColor: cssColour(wickDown) }),
+    };
+    const columns = [
+        { key: keys.open, channel: ohlc.open, part: 'value' },
+        { key: keys.high, channel: ohlc.high, part: 'value' },
+        { key: keys.low, channel: ohlc.low, part: 'value' },
+        { key: keys.close, channel: ohlc.close, part: 'value' },
+    ];
+    const parts = [
+        { name: `${key}:up`, channel: ohlc.colorUpChannel },
+        { name: `${key}:down`, channel: ohlc.colorDownChannel },
+        { name: `${key}:wick`, channel: ohlc.wickColorChannel },
+        { name: `${key}:border`, channel: ohlc.borderColorChannel },
+    ];
+    for (const part of parts) {
+        if (part.channel !== null)
+            columns.push(...colourColumns(part.name, part.channel));
+    }
+    const perBar = parts.some((one) => one.channel !== null);
+    return {
+        ohlc: keys,
+        style,
+        columns,
+        colorParts: perBar
+            ? (ctx) => {
+                const rising = isRising(ctx, keys.open, keys.close);
+                const bodyChannel = rising ? ohlc.colorUpChannel : ohlc.colorDownChannel;
+                const body = bodyChannel === null
+                    ? undefined
+                    : colourAt(ctx.values, ctx.index, rising ? `${key}:up` : `${key}:down`);
+                const wickPart = override(ctx, `${key}:wick`, ohlc.wickColorChannel, wick, body);
+                const borderPart = override(ctx, `${key}:border`, ohlc.borderColorChannel, border, body);
+                return {
+                    ...(body === undefined ? {} : { body }),
+                    ...(wickPart === undefined ? {} : { wick: wickPart }),
+                    ...(borderPart === undefined ? {} : { border: borderPart }),
+                };
+            }
+            : undefined,
+    };
+}
+/** Whether this bar closed at or above its own open, by the candle's columns. */
+function isRising(ctx, openKey, closeKey) {
+    const open = ctx.values[openKey]?.[ctx.index];
+    const close = ctx.values[closeKey]?.[ctx.index];
+    if (typeof open !== 'number' || typeof close !== 'number')
+        return true;
+    return close >= open;
+}
+/**
+ * The wick or the border for one bar.
+ *
+ * Its own channel wins, then a declared constant, which the series style already
+ * carries and this leaves alone, and otherwise the part follows the body.
+ */
+function override(ctx, name, channel, declared, body) {
+    if (channel !== null)
+        return colourAt(ctx.values, ctx.index, name);
+    return declared === undefined ? body : undefined;
+}
+//# sourceMappingURL=candles.js.map

package/dist/adapters/charts/candles.js.map

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

package/dist/adapters/charts/colours.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A colour on either side of the boundary.
+ *
+ * The language carries a colour as four numbers, three whole channels and an
+ * alpha that is an ordinary number from 0 to 1. A chart carries one as a CSS
+ * string. The two directions are not symmetric and it is worth saying why.
+ *
+ * **Out of the language, nothing is lost.** The functional form is written
+ * rather than eight hexadecimal digits, because a hexadecimal alpha is a byte
+ * and the language's is not: `fade(x, 93)` is an alpha of 0.07, which no pair of
+ * hexadecimal digits holds exactly, and a study whose band came back a shade off
+ * would be a difference nobody could account for.
+ *
+ * **Into the language, alpha is the part that goes missing.** A chart's colour
+ * control is a swatch with no alpha channel, so the value it stores back is six
+ * digits and the transparency the script asked for is gone. Rather than turn
+ * every translucent input opaque the first time somebody opens the dialog, a
+ * value with no alpha of its own keeps the alpha the script declared, and only
+ * a value that states one replaces it.
+ *
+ * A per-bar colour reaches a chart through the values table, which holds columns
+ * of numbers, so it travels as two columns: the three channels packed into one
+ * whole number, and the alpha beside them as itself. One column would have to
+ * put the alpha in a byte and lose exactly what the functional form is here to
+ * keep.
+ */
+import type { ColourValue, Value } from '../../core/engine/index.js';
+/** The CSS spelling of a colour. */
+export declare function cssColour(colour: ColourValue): string;
+/** The CSS spelling of a value that may not be a colour at all. */
+export declare function cssOf(value: Value): string | undefined;
+export declare function isColourValue(value: Value): value is ColourValue;
+export declare function colourOf(r: number, g: number, b: number, a: number): ColourValue;
+/**
+ * A CSS colour back into the language's four numbers.
+ *
+ * `alpha` is what a value with no alpha of its own is given: the alpha the
+ * script declared for that input, so a swatch that cannot express transparency
+ * does not remove it. Anything unparseable is nothing, which the caller turns
+ * into the refusal the input's own validation would have produced.
+ */
+export declare function parseColour(text: string, alpha: number): ColourValue | undefined;
+/** The three channels as one whole number, for a column of per-bar colours. */
+export declare function packChannels(colour: ColourValue): number;
+/** The CSS spelling of a packed triple and the alpha that travelled beside it. */
+export declare function unpackColour(packed: number, alpha: number): string;
+//# sourceMappingURL=colours.d.ts.map

package/dist/adapters/charts/colours.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colours.d.ts","sourceRoot":"","sources":["../../../src/adapters/charts/colours.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAMrE,oCAAoC;AACpC,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAErD;AAED,mEAAmE;AACnE,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAEtD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,WAAW,CAEhE;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW,CAEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CA2BhF;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAExD;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlE"}