openalgo-script 0.2.0 → 0.4.0

package/spec/errors.json

@@ -2605,6 +2605,99 @@
       "refines": null,
       "test": "tests/engine/verify.test.ts"
     },
+    {
+      "code": "OS6020",
+      "title": "The report window holds no bars",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "The window from {from} to {to} holds none of the {count} bars supplied.",
+      "placeholders": {
+        "from": "the first moment the window covers, or the first bar supplied where the host named none",
+        "to": "the last moment it covers",
+        "count": "how many bars were supplied"
+      },
+      "cause": "A report is about the bars inside the window the host chose, and a window holding none of them has nothing to report: no equity point, no trade and no summary. The bars outside it are warmup, which execute and whose orders are real, so an empty window is not an empty run, and reporting one as a flat curve would tell a reader that nothing happened when something did.",
+      "fix": "Widen the window until it covers bars, or supply the bars it covers. Both bounds are inclusive and are compared against the times of the bars supplied rather than against a calendar, so a window that falls inside a gap in the data is empty however wide it looks.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "bars supplied: 1240, first day 1, last day 1240\nreport window: day 1300 to day 1400, bars inside 0",
+        "after": "bars supplied: 1240, first day 1, last day 1240\nreport window: day 1100 to day 1240, bars inside 141"
+      },
+      "spec": "language.md 7.1",
+      "refines": null,
+      "test": "tests/backtest/range.test.ts"
+    },
+    {
+      "code": "OS6021",
+      "title": "A run setting cannot be applied as stated",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "{setting} cannot be applied: {problem}.",
+      "placeholders": {
+        "setting": "the setting that cannot be applied, such as the charge schedule or the comparison tolerance",
+        "problem": "what makes it unusable, such as a charge line levied on a line declared after it"
+      },
+      "cause": "A run states the settings it is carried out under before its first bar, and a setting that cannot be carried out is refused there rather than quietly producing a figure. A charge line levied on lines not declared before it has no single evaluation order, so two engines would charge two different amounts and both would be defensible. A slippage stated in ticks with no tick size to measure a tick in would charge nothing at all, which is a backtest that lies in the strategy's favour. A comparison tolerance carrying a bound and no reason is a failed comparison somebody switched off.",
+      "fix": "State the setting so it can be carried out: declare a charge line after every line it is levied on, supply the tick size a slippage in ticks is measured in, or write down the reason a tolerance needs a bound. Nothing has been computed at the point this is refused, so correcting the setting and running again costs one run.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "charge lines: tax on levy, levy\nslippage: 2 ticks, tick size not supplied",
+        "after": "charge lines: levy, tax on levy\nslippage: 2 ticks, tick size 0.05"
+      },
+      "spec": "stdlib.md 17.1",
+      "refines": null,
+      "test": "tests/accounting/schedules.test.ts"
+    },
+    {
+      "code": "OS6022",
+      "title": "The bars are not the bars the record was made from",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "The bars supplied hash to {found}, and the record was made from {expected}.",
+      "placeholders": {
+        "found": "the hash of the bars supplied now",
+        "expected": "the hash the record names"
+      },
+      "cause": "A record names the bars it was made from by a hash over their canonical form, so a replay can prove it is replaying the same run rather than producing a different study under the same name. Bars are revised: a feed corrects a print, a session is extended, a split is applied to history. A replay over revised bars that reported the original figures would be the most convincing wrong answer this system can produce.",
+      "fix": "Replay against the bars the record names. Where the revision is the point, make a second record over the revised bars and compare the two runs, rather than overwriting one run with the other under one name.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "record: bars 1240, hash 9f2c4e...\nsupplied: bars 1240, hash 4ab70d...",
+        "after": "record: bars 1240, hash 9f2c4e...\nsupplied: bars 1240, hash 9f2c4e..."
+      },
+      "spec": "conformance.md 3",
+      "refines": null,
+      "test": "tests/backtest/record.test.ts"
+    },
+    {
+      "code": "OS6023",
+      "title": "Two cost models are stated at once",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "A charge schedule was supplied, and the declaration states a commission of {commission} in {commissionType}.",
+      "placeholders": {
+        "commission": "the commission the declaration states",
+        "commissionType": "the unit that commission is stated in"
+      },
+      "cause": "The declaration's commission is the script's own statement of what trading costs and a supplied schedule is the platform's, and the two describe the same money. Applied together they charge it twice; applied one at a time they charge whichever an engine happened to prefer, which is a rule nobody wrote down and a figure nobody can explain afterwards. So exactly one of the two is stated for a run, and stating both is refused before the first bar rather than reconciled behind the reader.",
+      "fix": "Supply the schedule and leave the declaration's commission at its default of zero, or state the commission in the declaration and supply no schedule. A schedule is the one of the two that can carry a floor, a cap, a charge levied on a charge, and a cost that falls on one side of the trade only.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "declaration: commission 20, per trade\nhost: charge schedule supplied, 4 lines",
+        "after": "declaration: commission 0, per trade\nhost: charge schedule supplied, 4 lines"
+      },
+      "spec": "language.md 13.3; stdlib.md 17.1",
+      "refines": null,
+      "test": "tests/backtest/settings.test.ts"
+    },
     {
       "code": "OS7001",
       "title": "Only a strategy can do that",
@@ -2984,6 +3077,53 @@
       "refines": null,
       "test": "tests/engine/closing.test.ts"
     },
+    {
+      "code": "OS7018",
+      "title": "A frame names an order this strategy did not place",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "The frame names intent {intent}, and this strategy holds no such order.",
+      "placeholders": {
+        "intent": "the intent id the frame named"
+      },
+      "cause": "Step 1 of the fold locates the row a frame is about, and a frame naming no row cannot be folded into anything. It is a fact about the host rather than about the strategy: a destination answering for an order another strategy placed, or answering for a run that has already ended. The frame changes nothing and is reported, because a fold that passed over it in silence would leave a host's mistake invisible to the only party who can correct it.",
+      "fix": "Answer with the intent id the engine sent. A destination's own reference is carried in the frame's reference field, where the engine records it and never parses it, and it is not what an answer is addressed by.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "engine sent: intent 7, intent 8\nframe: intent 11, status filled, filled qty 1",
+        "after": "engine sent: intent 7, intent 8\nframe: intent 8, status filled, filled qty 1"
+      },
+      "spec": "stdlib.md 17.8, 17.14",
+      "refines": null,
+      "test": null,
+      "deferred": "Nothing raises this yet. The fold refuses the frame and records the refusal as a word on the outcome it hands back, and a word is not a catalogue code, so nothing reports it against the run and a host answering for orders it was never handed stays invisible. Raised when the outcome of a fold carries a code and a bar carries a channel for a diagnostic that does not stop it, stdlib.md 17.8."
+    },
+    {
+      "code": "OS7019",
+      "title": "A fill was reported with no price",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "The frame reports {qty} filled for intent {intent}, and no average fill price.",
+      "placeholders": {
+        "qty": "the cumulative filled quantity the frame reports",
+        "intent": "the intent id the frame named"
+      },
+      "cause": "Step 3 of the fold takes the destination's own average over the cumulative quantity, because the engine never averages two averages of its own. A frame reporting more filled than the row holds and no price to take is a fill that can be marked against nothing: no position average, no realised profit, no equity point. It is refused whole rather than folded for its quantity alone, because a position holding a size and no price is worse than no position at all.",
+      "fix": "Report the average fill price the destination computed over the cumulative quantity, on every frame that reports a quantity greater than the last one. A frame carrying no new quantity needs no price.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "frame: intent 8, status filled, filled qty 3, average fill price absent",
+        "after": "frame: intent 8, status filled, filled qty 3, average fill price 104.25"
+      },
+      "spec": "stdlib.md 17.8, 17.14",
+      "refines": null,
+      "test": null,
+      "deferred": "Nothing raises this yet. The fold refuses the frame and records the refusal as a word on the outcome it hands back, and a word is not a catalogue code, so a destination reporting a fill that can be marked against nothing is refused in silence. Raised when the outcome of a fold carries a code and a bar carries a channel for a diagnostic that does not stop it, stdlib.md 17.8."
+    },
     {
       "code": "OS8001",
       "title": "A stateful call inside a branch",

package/src/adapters/charts/surfaces.ts

@@ -100,6 +100,23 @@ export interface ChartTableOptions {
   readonly borderWidth: number;
   /** The backdrop behind the whole grid, which is the grid's own `bgColor`. */
   readonly background?: string;
+  /**
+   * Column widths in media pixels, one per column.
+   *
+   * The chart's own default is one flat width for every column, which is a
+   * width chosen without seeing the text. A grid whose first column says
+   * "Moving averages" and whose second says "RSI: 27.22" has two columns that
+   * want different room, and one number cannot give it to both.
+   */
+  readonly cellWidth?: readonly number[];
+  /**
+   * `'auto'` to shrink a cell's type until its text fits the cell it is in.
+   *
+   * The chart measures the text it is about to draw, which nothing upstream of
+   * it can do, so this is what makes a column width that is slightly wrong
+   * merely slightly loose instead of two cells written over each other.
+   */
+  readonly fontSize?: number | 'auto';
 }
 
 /** A grid of cells pinned to a corner, and the options it is drawn with. */

package/src/adapters/charts/tables.ts

@@ -118,10 +118,98 @@ function oneTable(
       position: CORNERS[position] ?? 'top-right',
       borderWidth: numberField(declared.options.borderWidth, lookup, 0),
       ...(bgColour === undefined ? {} : { background: cssColour(bgColour) }),
+      ...(cols > 0 ? { cellWidth: columnWidths(grid, cols) } : {}),
+      // The chart measures the text it is about to draw and shrinks it to fit,
+      // which is the half of this that cannot be done from here.
+      fontSize: 'auto',
     },
   };
 }
 
+/**
+ * How wide each column has to be, in media pixels.
+ *
+ * The chart's default is one width for every column, chosen without seeing the
+ * text, and a grid whose header says "Moving averages" over cells saying
+ * "RSI: 27.22" has one column bleeding into the next. Nothing downstream can
+ * choose better, because by the time the chart has the grid it has lost which
+ * cells belong together; and nothing upstream can, because the script declares
+ * a size and writes text, not a layout.
+ *
+ * **This is an estimate, and it is allowed to be.** A real width needs the font
+ * the chart will draw with, and only the chart has it. So the width is counted
+ * off the characters and the chart's own `fontSize: 'auto'` corrects whatever
+ * this gets wrong: too narrow and the type shrinks a little, too wide and the
+ * column is a little loose. Either is a table that reads. The failure this
+ * replaces was neither.
+ *
+ * Delete it when the chart can size a column from its own measurements. It
+ * exists because that is not a thing it can be asked to do yet.
+ */
+function columnWidths(grid: readonly (readonly ChartCell[])[], cols: number): number[] {
+  const widths: number[] = [];
+  for (let col = 0; col < cols; col += 1) {
+    let widest = 0;
+    for (const row of grid) {
+      const text = row[col]?.text ?? '';
+      if (text.length > 0) widest = Math.max(widest, textWidth(text));
+    }
+    widths.push(Math.min(MAX_COLUMN, Math.max(MIN_COLUMN, Math.ceil(widest) + CELL_PADDING * 2)));
+  }
+  return widths;
+}
+
+/**
+ * Roughly how wide a string is at the type size the chart starts from.
+ *
+ * Counted rather than measured, and counted in two weights rather than one: a
+ * column of "Histogram: -7.01" is half punctuation and narrow digits, and
+ * treating every character as an em-and-a-bit makes that column half again as
+ * wide as it needs to be while "Moving averages" stays too narrow. Two weights
+ * is not typography, but it is enough to tell those two apart.
+ */
+function textWidth(text: string): number {
+  let width = 0;
+  for (const character of text) {
+    width += NARROW.has(character) ? BASE_SIZE * NARROW_EM : BASE_SIZE * WIDE_EM;
+  }
+  return width;
+}
+
+/** The characters that take noticeably less than an average advance. */
+const NARROW = new Set([...' .,:;!|ijlt1IJfr()[]{}-']);
+
+/**
+ * The type size the widths are counted at.
+ *
+ * The chart's own default row is 18 media pixels and it draws at 62% of the
+ * row, so this is the size a cell gets before anything shrinks it. Counting at
+ * a larger size would reserve room the text never uses.
+ */
+const BASE_SIZE = 11;
+const NARROW_EM = 0.32;
+const WIDE_EM = 0.56;
+
+/** What the chart insets a cell's text by, on each side. */
+const CELL_PADDING = 4;
+
+/**
+ * The narrowest a column is drawn.
+ *
+ * A column of one-character cells sized to its content is a sliver, and a grid
+ * of slivers reads as a rendering fault rather than as a narrow column.
+ */
+const MIN_COLUMN = 56;
+
+/**
+ * The widest a column is drawn.
+ *
+ * A cell holding a sentence would otherwise push the grid past the pane it is
+ * pinned inside, taking the chart with it. Past this the type shrinks instead,
+ * which is the chart's job and it is better at it.
+ */
+const MAX_COLUMN = 220;
+
 /**
  * One written cell, or none.
  *

package/src/adapters/codemirror/commands.ts

@@ -0,0 +1,53 @@
+/**
+ * Laying a script out again, as an editor command.
+ *
+ * `format` is the tier's, and the guarantee it carries is the one that makes a
+ * format button safe to put in front of somebody holding a position: laying a
+ * script out again cannot change what it computes. Every example and every gate
+ * script in the repository is formatted, both texts compiled, and the compiled
+ * programs compared field for field; and every call checks itself against the
+ * lexer, so a rule that is wrong returns the source untouched rather than a
+ * changed program.
+ *
+ * The whole document is replaced rather than a minimal edit computed. It is the
+ * honest version: a diff would have to be trusted to be equivalent to the
+ * replacement, and a formatter that moved a line somewhere unintended would do
+ * it silently. The cursor is kept where it was in the new text, clamped, because
+ * a format that sends the caret to the top of the file is a format nobody
+ * presses twice.
+ *
+ * **A document with two character line endings comes back with one character
+ * ones**, because that is what `language.md` 3.1 normalises a file to before
+ * anything reads it and what every offset in this tier indexes. It is the one
+ * change to a file's bytes that formatting makes without being asked, and it is
+ * recorded in `spec/editor-narrowings.json`.
+ */
+import { format } from '../../editor/index.js';
+import type { EditorView } from './contract.js';
+import { documentOf, normalisedOffset } from './positions.js';
+
+/**
+ * Lays the document out again, and says whether anything changed.
+ *
+ * ```ts
+ * keymap.of([{ key: "Shift-Alt-f", run: formatDocument }])
+ * ```
+ *
+ * False where the document is already laid out, which is what an editor command
+ * returns when it has nothing to do: the key press then falls through to
+ * whatever else is bound to it rather than being swallowed.
+ */
+export function formatDocument(view: EditorView): boolean {
+  const raw = view.state.doc.toString();
+  const held = documentOf(raw);
+  const laid = format(held.text);
+  if (laid === raw) return false;
+
+  const at = normalisedOffset(held, view.state.selection.main.head);
+  view.dispatch({
+    changes: { from: 0, to: view.state.doc.length, insert: laid },
+    selection: { anchor: Math.min(at, laid.length) },
+    scrollIntoView: true,
+  });
+  return true;
+}

package/src/adapters/codemirror/completion.ts

@@ -0,0 +1,74 @@
+/**
+ * Completions, as the editor's completion source.
+ *
+ * The whole of the work is done by `complete`, which reads the standard library
+ * manifest, the checker's bindings and the error catalogue. What is here is the
+ * translation: the editor wants a range to replace, a list of rows, and a note
+ * about whether the list is already filtered.
+ *
+ * **The list is already filtered**, by the word the writer has typed, compared
+ * exactly, because the language's names are case sensitive. So `filter` is false
+ * and the editor is told not to filter it again: its own matcher is fuzzy and
+ * case insensitive, and running it over a list that has already answered the
+ * question would put `EMA` in front of somebody as though it compiled.
+ *
+ * **A planned call is shown and marked.** `complete` carries the catalogue's own
+ * OS2020 sentence on a planned row, so that is what goes in the row's expanded
+ * note, and the row is pushed to the bottom of the list with the editor's own
+ * boost. A host that would rather not show them at all drops them with one
+ * field, which is why they are marked rather than filtered here.
+ */
+import { complete } from '../../editor/index.js';
+import type { Completion } from '../../editor/index.js';
+import type {
+  EditorCompletion,
+  EditorCompletionContext,
+  EditorCompletionResult,
+} from './contract.js';
+import { COMPLETION_TYPES } from './tokens.js';
+
+/** As far down the list as the editor will move a row. */
+const PLANNED_BOOST = -99;
+
+function rowOf(one: Completion): EditorCompletion {
+  const info = one.refusal ?? one.summary;
+  const type = COMPLETION_TYPES[one.kind];
+  return {
+    label: one.label,
+    ...(type === undefined ? {} : { type }),
+    detail: one.detail,
+    ...(info === undefined ? {} : { info }),
+    ...(one.insert === one.label ? {} : { apply: one.insert }),
+    ...(one.planned ? { boost: PLANNED_BOOST } : {}),
+  };
+}
+
+/**
+ * Every completion for the position the editor is asking about.
+ *
+ * ```ts
+ * autocompletion({ override: [openscriptCompletion] })
+ * ```
+ *
+ * Nothing comes back for an empty list rather than an empty list, because the
+ * editor reads the two differently: an empty result closes the panel and null
+ * lets another source answer, and a host with a snippet source of its own should
+ * keep it.
+ */
+export function openscriptCompletion(
+  context: EditorCompletionContext,
+): EditorCompletionResult | null {
+  const rows = complete(context.state.doc.toString(), context.pos);
+  // The first row carries the range every row replaces, so an empty list and a
+  // list whose first row is missing are one answer: nothing. Two guards for that
+  // would be one guard and a line no test can reach.
+  const first = rows[0];
+  if (first === undefined) return null;
+
+  return {
+    from: first.replace.offset,
+    to: first.replace.offset + first.replace.length,
+    options: rows.map(rowOf),
+    filter: false,
+  };
+}

package/src/adapters/codemirror/contract.ts

@@ -0,0 +1,156 @@
+/**
+ * The editor component's own shapes, as this adapter targets them.
+ *
+ * **Why they are declared here rather than imported.** The editor component is a
+ * peer dependency: a host that wants a text area installs it, and a host that
+ * wants only the language must not be made to. This repository therefore does
+ * not install it, cannot type check against it, and would fail its own layering
+ * check the moment a file here imported it. It is the same decision the chart
+ * adapter took, for the same reason, and `src/adapters/charts/contract.ts` says
+ * it at length.
+ *
+ * So the shapes this produces values for are declared below and the host's own
+ * build is where the two meet. Each one is a one line check that costs a host
+ * nothing and fails to compile if this file has drifted:
+ *
+ * ```ts
+ * import type { StreamParser } from "<the editor's language package>";
+ * import type { CompletionSource } from "<the editor's completion package>";
+ * import type { Diagnostic } from "<the editor's lint package>";
+ *
+ * const parser: StreamParser<unknown> = openscriptStream;
+ * const source: CompletionSource = openscriptCompletion;
+ * const linter: (view: EditorView) => Diagnostic[] = openscriptLint;
+ * ```
+ *
+ * **That line catches a value of the wrong shape and not an argument of the
+ * wrong shape.** A method's parameters are compared in both directions, so a
+ * hook declared here as taking something the editor never passes still assigns.
+ * That is the failure the chart adapter has actually made, so every member below
+ * takes the editor's own argument, spelled as the editor spells it, and every
+ * test drives each one with the argument the editor passes rather than with one
+ * of its own.
+ *
+ * **A style name is not checked by any of those lines.** The names this adapter
+ * returns from `token` are looked up by the editor in its own table of
+ * highlighting tags at run time, and an unknown one is a warning on a console
+ * rather than a compile error. That is why the whole mapping is one exported
+ * record a host can replace in a line, and why it is recorded in
+ * `spec/editor-narrowings.json` as the one thing here a type cannot hold.
+ */
+
+/**
+ * One line of the document, as the editor's tokenizer sees it.
+ *
+ * The editor hands a tokenizer a line at a time and expects `pos` to have moved
+ * forward when `token` returns. Only the members this adapter reads are
+ * declared: a narrower shape is still assignable from the editor's wider one.
+ */
+export interface EditorStringStream {
+  /** The line's text, without its line ending. */
+  readonly string: string;
+  /** Where the tokenizer has got to, which this adapter moves. */
+  pos: number;
+  /** Where the current token began. */
+  readonly start: number;
+  /** Whether `pos` is at the end of the line. */
+  eol(): boolean;
+  /** Whether `pos` is at the start of the line. */
+  sol(): boolean;
+}
+
+/**
+ * A tokenizer the editor drives one line at a time.
+ *
+ * `token` returns a style name, or null for text with no style of its own. The
+ * state is the tokenizer's to define, and the editor copies it at line
+ * boundaries so that it can restart mid document, which is why `copyState` is
+ * here.
+ */
+export interface EditorStreamParser<State> {
+  readonly name?: string;
+  startState?(indentUnit: number): State;
+  token(stream: EditorStringStream, state: State): string | null;
+  copyState?(state: State): State;
+  blankLine?(state: State, indentUnit: number): void;
+  readonly languageData?: Readonly<Record<string, unknown>>;
+}
+
+/** The document, which the editor holds as a rope rather than as a string. */
+export interface EditorText {
+  readonly length: number;
+  toString(): string;
+}
+
+/** The part of the editor's state this adapter reads. */
+export interface EditorState {
+  readonly doc: EditorText;
+  readonly selection: {
+    readonly main: { readonly head: number; readonly from: number; readonly to: number };
+  };
+}
+
+/** The part of the editor's view this adapter reads and dispatches to. */
+export interface EditorView {
+  readonly state: EditorState;
+  dispatch(transaction: {
+    readonly changes: { readonly from: number; readonly to: number; readonly insert: string };
+    readonly selection?: { readonly anchor: number };
+    readonly scrollIntoView?: boolean;
+  }): void;
+}
+
+/** What the editor hands a completion source. */
+export interface EditorCompletionContext {
+  readonly state: EditorState;
+  readonly pos: number;
+  /** Whether the writer asked for completions rather than merely typing. */
+  readonly explicit: boolean;
+}
+
+/** One row of the editor's completion list. */
+export interface EditorCompletion {
+  readonly label: string;
+  /** The editor's own name for the icon beside a row. */
+  readonly type?: string;
+  readonly detail?: string;
+  readonly info?: string;
+  /** The text to insert, where it differs from the label. */
+  readonly apply?: string;
+  /** Moves a row up or down the list, from -99 to 99. */
+  readonly boost?: number;
+}
+
+export interface EditorCompletionResult {
+  readonly from: number;
+  readonly to?: number;
+  readonly options: readonly EditorCompletion[];
+  /** False when the list is already filtered, which this adapter's is. */
+  readonly filter?: boolean;
+}
+
+/** One squiggle in the editor's lint panel and gutter. */
+export interface EditorDiagnostic {
+  readonly from: number;
+  readonly to: number;
+  readonly severity: 'hint' | 'info' | 'warning' | 'error';
+  readonly message: string;
+  /** Where the diagnostic came from, shown beside the message. */
+  readonly source?: string;
+  readonly actions?: readonly {
+    readonly name: string;
+    apply(view: EditorView, from: number, to: number): void;
+  }[];
+}
+
+/** What the editor shows over the text, and the element it shows. */
+export interface EditorTooltipView {
+  readonly dom: unknown;
+}
+
+export interface EditorTooltip {
+  readonly pos: number;
+  readonly end?: number;
+  readonly above?: boolean;
+  create(view: EditorView): EditorTooltipView;
+}

package/src/adapters/codemirror/index.ts

@@ -0,0 +1,66 @@
+/**
+ * The editor adapter: the language intelligence, wired into a text component.
+ *
+ * This and the chart adapter are the only modules in the repository allowed to
+ * know two worlds at once, and it is the piece a platform with its own editor
+ * replaces rather than the piece it patches. Everything under `src/editor` stays
+ * ignorant of any component, and the layering check is what keeps it that way.
+ *
+ * **The editor component is a peer dependency, and nothing here imports it.** A
+ * package that pulled a text component into everyone's install would defeat the
+ * point of a language a platform can take on its own, so the shapes this
+ * produces are declared in `contract.ts` and the host's own build is where the
+ * two are compared, in one line per piece. See that file for the lines. The
+ * entry point resolves and every function here runs in an install that holds no
+ * editor at all, which `scripts/check-entry-points.mjs` proves on every build.
+ *
+ * Six functions in, five pieces out:
+ *
+ *     openscriptStream             highlighting, a line at a time
+ *     openscriptCompletion         the completion list
+ *     openscriptLint               errors as you type, with their fixes
+ *     openscriptHoverTooltip       what the thing under the pointer is
+ *     openscriptSignatureTooltip   the call being written
+ *     formatDocument               lay the script out again
+ *
+ * The two tooltips take the markup as a parameter and have no default for it, so
+ * nothing in this package names a browser global at any tier. A host that wants
+ * none of this calls the six functions itself and draws its own. That is not the fallback, it is the supported path: what a host gives up
+ * by taking these instead is recorded in `spec/editor-narrowings.json`, which is
+ * three lines long and worth reading before choosing.
+ */
+export type {
+  EditorCompletion,
+  EditorCompletionContext,
+  EditorCompletionResult,
+  EditorDiagnostic,
+  EditorState,
+  EditorStreamParser,
+  EditorStringStream,
+  EditorText,
+  EditorTooltip,
+  EditorTooltipView,
+  EditorView,
+} from './contract.js';
+
+export { COMPLETION_TYPES, HIGHLIGHT_TOKENS } from './tokens.js';
+
+export type { StreamState } from './stream.js';
+export { openscriptStream } from './stream.js';
+
+export { openscriptCompletion } from './completion.js';
+
+export { diagnosticsFor, openscriptLint } from './lint.js';
+
+export type { Renderer } from './tooltips.js';
+export {
+  hoverLines,
+  openscriptHoverTooltip,
+  openscriptSignatureTooltip,
+  signatureLines,
+} from './tooltips.js';
+
+export { formatDocument } from './commands.js';
+
+export type { Document } from './positions.js';
+export { documentOf, normalisedOffset } from './positions.js';