oakscriptjs 0.13.0 → 0.13.2

package/skills/oakscript/examples/ma-cross.js

@@ -0,0 +1,34 @@
+// Moving-average cross on the price pane: two averages, a fill between them,
+// markers on the crosses and two alert conditions.
+indicator("MA Cross", { shorttitle: "MA X", overlay: true });
+
+const src = input.source("close", "Source");
+const fastLength = input.int(9, "Fast length", { minval: 1 });
+const slowLength = input.int(21, "Slow length", { minval: 1 });
+const maType = input.string("EMA", "MA type", { options: ["SMA", "EMA", "WMA"] });
+
+// Inputs are plain values: a JS `if` on them is fine.
+function ma(source, length) {
+  if (maType === "SMA") return ta.sma(source, length);
+  if (maType === "WMA") return ta.wma(source, length);
+  return ta.ema(source, length);
+}
+
+const fast = ma(src, fastLength);
+const slow = ma(src, slowLength);
+const bullish = fast.gt(slow); // Series of 1 / 0: fast > slow
+
+const fastPlot = plot(fast, "Fast", { color: color.teal, linewidth: 2 });
+const slowPlot = plot(slow, "Slow", { color: color.orange, linewidth: 2 });
+fill(fastPlot, slowPlot, {
+  color: color.when(bullish, color.new(color.teal, 85), color.new(color.red, 85)),
+  title: "Trend fill",
+});
+
+const crossUp = ta.crossover(fast, slow);
+const crossDown = ta.crossunder(fast, slow);
+plotshape(crossUp, "Cross up", { style: "triangleup", location: "belowbar", color: color.teal, size: "small" });
+plotshape(crossDown, "Cross down", { style: "triangledown", location: "abovebar", color: color.red, size: "small" });
+
+alertcondition(crossUp, "Cross up", "Fast MA crossed above the slow MA");
+alertcondition(crossDown, "Cross down", "Fast MA crossed below the slow MA");

package/skills/oakscript/examples/macd-oscillator.js

@@ -0,0 +1,29 @@
+// MACD in its own pane: a four-colour histogram, the MACD and signal lines,
+// a zero level and a background on the signal crosses.
+indicator("MACD Oscillator", { shorttitle: "MACD", overlay: false, precision: 4 });
+
+const src = input.source("close", "Source");
+const fastLength = input.int(12, "Fast length", { minval: 1 });
+const slowLength = input.int(26, "Slow length", { minval: 1 });
+const signalLength = input.int(9, "Signal smoothing", { minval: 1, maxval: 50 });
+
+// A tuple comes back as an array: destructure it.
+const [macdLine, signalLine, hist] = ta.macd(src, fastLength, slowLength, signalLength);
+
+// Four colours: above / below zero, growing / falling. color.when() takes two colours,
+// so build the per-bar array in a bar loop (one entry per bar, undefined = na).
+const histColors = [];
+eachBar((c) => {
+  const h = c.get(hist);
+  const previous = c.get(hist, 1);
+  if (Number.isNaN(h)) histColors.push(undefined);
+  else if (h >= 0) histColors.push(h > previous ? "#26A69A" : "#B2DFDB");
+  else histColors.push(h < previous ? "#FF5252" : "#FFCDD2");
+});
+
+plot(hist, "Histogram", { style: plot.style_columns, color: histColors });
+plot(macdLine, "MACD", { color: color.blue, linewidth: 2 });
+plot(signalLine, "Signal", { color: color.orange });
+hline(0, "Zero", { color: color.gray, linestyle: hline.style_dotted });
+
+bgcolor(color.when(ta.cross(macdLine, signalLine), color.new(color.gray, 85)), { title: "Signal cross" });

package/skills/oakscript/examples/mtf-trend-filter.js

@@ -0,0 +1,46 @@
+// Multi-timeframe filter: a higher-timeframe EMA decides the trend, and a cross of the
+// chart EMA gives a signal only when it agrees with that trend, once per trend.
+indicator("MTF Trend Filter", { shorttitle: "MTF", overlay: true });
+
+const filterTf = input.timeframe("D", "Filter timeframe");
+const filterLength = input.int(20, "Filter EMA length", { minval: 1 });
+const signalLength = input.int(10, "Signal EMA length", { minval: 1 });
+
+// The expression runs on the higher-timeframe bars: compute every series INSIDE it.
+// Returning an array gives one series per element (a PineScript tuple).
+const [htfEma, htfClose] = request.security("", filterTf, () => [ta.ema(close, filterLength), close]);
+const upTrend = htfClose.gt(htfEma);
+
+const signalEma = ta.ema(close, signalLength);
+plot(htfEma, "Filter EMA", { color: color.gray, linewidth: 2, style: plot.style_stepline });
+plot(signalEma, "Signal EMA", { color: color.when(upTrend, color.teal, color.red) });
+
+const crossUp = ta.crossover(close, signalEma);
+const crossDown = ta.crossunder(close, signalEma);
+
+// Stateful logic (PineScript `var` + `:=`): a closure variable in a bar loop.
+let lastSignal = 0; // var int lastSignal = 0
+const signal = eachBar((c) => {
+  const up = c.get(upTrend) === 1;
+  if (c.get(crossUp) === 1 && up && lastSignal !== 1) {
+    lastSignal = 1;
+    return 1;
+  }
+  if (c.get(crossDown) === 1 && !up && lastSignal !== -1) {
+    lastSignal = -1;
+    return -1;
+  }
+  return 0;
+});
+
+plotshape(signal.eq(1), "Long", { style: "labelup", location: "belowbar", color: color.teal, text: "L", textcolor: color.white });
+plotshape(signal.eq(-1), "Short", { style: "labeldown", location: "abovebar", color: color.red, text: "S", textcolor: color.white });
+bgcolor(color.when(upTrend, color.new(color.teal, 92), color.new(color.red, 92)), { title: "Trend" });
+
+// One label on the last bar with the filter state.
+eachBar((c) => {
+  if (c.i === c.n - 1) {
+    const text = (c.get(upTrend) === 1 ? "Uptrend " : "Downtrend ") + filterTf;
+    label.new(c.i, c.high, text, "bar_index", "price", color.gray, "label_down", color.white);
+  }
+});

package/skills/oakscript/reference/errors.md

@@ -0,0 +1,68 @@
+# Errors and how to read them
+
+A script fails in one of three ways: it does not compile, it stops with a runtime error, or it runs and gives a
+wrong output. Fix them in that order, then check the values.
+
+## Compile errors (syntax)
+
+The source is loaded as JavaScript: a syntax error comes with a line and a column of your source.
+
+| Message | Cause | Fix |
+|---|---|---|
+| `Missing initializer in const declaration`, `Unexpected token ':'` | a TypeScript annotation (`const a: number = 5`) | remove the types: the script is JavaScript |
+| `Unexpected identifier`, `Unexpected token '='` | Pine syntax: `x := 1`, `var x = 0`, `a = b ? c : d` on one line without `const`, `=>` functions, named arguments `f(a, length = 5)` | JS syntax: `x = 1`, `let x = 0`, `const a = ...`, `function f() {}`, options objects |
+| `Unexpected token 'export'` / `'import'` at a wrong place | an import below other code, an export | imports first, no exports |
+
+A host that compiles a script also runs it once on zero bars (a declaration pass: title, inputs, plots,
+strategy properties). Errors in the declarations or in top-level code show up there, with the line.
+
+## Runtime errors
+
+The run stops at the first error; the message names the call. The ones you will meet:
+
+| Message | Cause | Fix |
+|---|---|---|
+| `TypeError: series.toArray is not a function` | a number or NaN passed where a Series is expected: `plot(close - open)`, `plot(5)`, `ta.sma(a * 2, 10)` | Series methods: `close.sub(open)`, `a.mul(2)`; a constant level: `hline(5)` |
+| `TypeError: ta.xyz is not a function` / `xyz is not defined` | a name that does not exist (typo, Pine-only name such as `shape`, `location`, `size`, `xloc`, `bar_index`) | [pine-differences.md](pine-differences.md): strings for the constants, `c.i` for `bar_index` |
+| `TypeError: Cannot read properties of undefined (reading 'toArray')` | a missing Series argument, e.g. `ta.vwma(close, 20)` | pass it: `ta.vwma(close, 20, volume)` |
+| `Error on bar N: Invalid value of the 'length' argument (0.0) in the 'sma' function. It must be > 0.` | a length of 0, negative or NaN (often an input) | `minval: 1` on the input, or guard the value |
+| `Error on bar N: The 'sma' function references too many historical candles (6000), the limit is 5000.` | a window longer than 5000 bars | a shorter length |
+| `Error on bar N: The script attempts to reference historical data that is too far from the current bar (K bars back)...` | `x.offset(k)` / `c.get(x, k)` with k above 5000, or a history that keeps growing (`c.get(x, c.i)`) | bounded offsets |
+| `c.get(): the offset cannot be negative` / `Series.offset(-1)...` | reading a future bar | offsets >= 0; for a left shift of a marker use `offset` of `plotshape` |
+| `indicator(): the script already declared indicator(); a script has one declaration.` | two declarations | one `indicator()` or `strategy()` |
+| `strategy.entry() must be called inside strategy.eachBar().` | an order at the top level | move it into `strategy.eachBar((c) => ...)` |
+| `strategy.position_size must be read inside strategy.eachBar().` | a per-bar strategy value at the top level | read it in the loop; return it from the loop to plot it |
+| `strategy.eachBar(): declare the script with strategy() first.` | `strategy.*` in an `indicator()` script | declare `strategy(...)` |
+| `strategy.eachBar() runs once per script run.` | two strategy loops | one loop with all the logic |
+| `strategy.X is not provided by the strategy engine.` | the host's engine lacks a variable or a risk rule | use another value, or ask the host |
+| `request.security(): the expression returned a series computed on the chart bars...` | `request.security("", "D", () => myEma)` | compute inside: `() => ta.ema(close, 20)` |
+| `request.security needs the bars of X (D): pass them with ChartContext.bars.` (`MissingSymbolDataError`) | another symbol whose bars the host has not loaded | an app loads them and runs again; in your own host give `bars()` |
+| `Invalid symbol: X` | a symbol without bars | check the ticker id, or `ignore_invalid_symbol = true` |
+| `Invalid timeframe "XYZ"` | a bad timeframe string | `"1"`, `"60"`, `"240"`, `"D"`, `"W"`, `"M"`... |
+| `request.security_lower_tf: timeframe "D" is higher than the chart timeframe "60".` | `security_lower_tf` on a higher timeframe | `request.security` for higher timeframes |
+| `The chart timeframe is not known: pass it as executeScript(body, bars, inputs, { timeframe }).` (also time zone, session, `syminfo.*`) | a direct `executeScript` call without the chart context | pass `{ timeframe, timezone, session, ... }`; an app gives them |
+| `chart.point.now() needs a current bar: call it inside eachBar().` | a per-bar call at the top level | call it in a bar loop |
+| `oakscriptjs/script functions can only run inside executeScript()` | a script API call outside a run (e.g. from a timer, or a Node module that calls `plot` at import) | only the host runs the body |
+| `Script did not finish within Ns and was stopped.` (app) | an endless or very slow loop | bound the loops, compute Series outside the bar loops |
+
+## Silent mistakes (no error, wrong output)
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| a branch taken on every bar, or never | `if (ta.crossover(a, b))`, `cond ? x : y`, `a > b` with Series at the top level: an object is always true, an object comparison always false | `cond.iff(x, y)`, `a.gt(b)`, or `c.get(cond) === 1` in a loop |
+| one colour on every bar | `color: fast > slow ? color.green : color.red` | `color.when(fast.gt(slow), color.green, color.red)` |
+| an empty plot | NaN on every bar: a `ta.*` Series returned from a bar loop, a division by zero, a NaN input | compute `ta.*` before the loop, guard divisions (`range.gt(0).iff(x.div(range), 0)`) |
+| a plot that starts late | the warm-up of long lengths, or of a higher timeframe (20 daily bars on an hourly chart is 480 bars) | expected; shorter lengths or more bars |
+| values that look like the future (backtests too good) | `barmerge.lookahead_on` on a series that is not offset | lookahead off, or `.offset(1)` inside the expression |
+| a strategy without trades | conditions read as `c.get(cond)` on NaN-only Series, orders placed outside the conditions you expect, `pyramiding: 0` blocking a second entry in the same direction | plot the conditions (`plotshape`) and check them first |
+| `na(series)` / `nz(series)` has no effect | they take numbers | in a loop on `c.get(x)`, or `x.iff(x, 0)` |
+| an input never changes the output | the input value is not used, or its title changed (new id) | use the returned value; keep titles stable |
+
+## Checking the output
+
+After a clean run, read the values instead of trusting the code:
+
+- the last values of each plot (`run.result.plots.plot0.slice(-5)` in a direct call; the app shows them in the
+  data window and the legend);
+- the number of markers / labels (a signal on every bar, or none, is a bug);
+- for a strategy, the trade count and a few trades (entry and exit bars and prices).

package/skills/oakscript/reference/pine-differences.md

@@ -0,0 +1,84 @@
+# Pine Script v6 and OakScript
+
+The names, arguments, defaults and results follow Pine Script v6 (the `ta.*`, `math.*`, `str.*`, `array.*`,
+`matrix.*`, `map.*` and drawing functions are covered almost entirely). The differences come from JavaScript and
+from the vectorized execution.
+
+## Translation table
+
+| Pine Script v6 | OakScript |
+|---|---|
+| `//@version=6` | nothing |
+| `indicator("T", overlay=true)` | `indicator("T", { overlay: true })` |
+| `len = input.int(14, "Length", minval=1)` | `const len = input.int(14, "Length", { minval: 1 })` |
+| `src = input.source(close, "Source")` | `const src = input.source("close", "Source")` (the default is a name) |
+| `a + b`, `a - b`, `a * b`, `a / b` on series | `a.add(b)`, `a.sub(b)`, `a.mul(b)`, `a.div(b)` |
+| `a > b`, `a == b`, `a and b`, `not a` on series | `a.gt(b)`, `a.eq(b)`, `a.and(b)`, `a.not()` |
+| `cond ? x : y` on series | `cond.iff(x, y)` |
+| `x[1]` | `x.offset(1)`; in a bar loop `c.get(x, 1)` |
+| `na`, `na(x)`, `nz(x)` | `NaN`, `na(v)` / `nz(v)` on numbers; `x.iff(x, 0)` for `nz` on a Series |
+| `var float s = na` + `s := ...` | `let s = NaN;` before `eachBar((c) => { s = ...; })` |
+| `if close > open` (per bar) | in a bar loop: `if (c.close > c.open)` |
+| `for i = 0 to n - 1` | `for (let i = 0; i < n; i++)` in a bar loop |
+| `switch` / `if` returning a value | JS `switch` / `if` in a bar loop, or `iff` chains on Series |
+| `bar_index`, `last_bar_index` | `c.i`, `c.n - 1` |
+| `myFunc(x) => ...` | a JS `function`; on Series it composes Series methods |
+| `[a, b] = f()` | `const [a, b] = f()` |
+| `plot(x, "T", color=c, style=plot.style_columns)` | `plot(x, "T", { color: c, style: plot.style_columns })` |
+| `plot(x, color = cond ? c1 : c2)` | `plot(x, "T", { color: color.when(cond, c1, c2) })` |
+| `plotshape(cond, style=shape.triangleup, location=location.belowbar, size=size.small)` | `plotshape(cond, "T", { style: "triangleup", location: "belowbar", size: "small" })` |
+| `label.new(bar_index, high, "A", style=label.style_label_down)` | `label.new(c.i, c.high, "A", undefined, undefined, undefined, "label_down")` (positional) |
+| `line.new(x1, y1, x2, y2, extend=extend.right)` | `line.new(x1, y1, x2, y2, "bar_index", "right")` |
+| `xloc.bar_time`, `yloc.abovebar`, `line.style_dashed`, `format.volume`, `display.none` | `"bar_time"`, `"abovebar"`, `"dashed"`, `"volume"`, `"none"` |
+| `dayofweek.monday` | `2` (1 = Sunday ... 7 = Saturday) |
+| `request.security(sym, "D", ta.ema(close, 20))` | `request.security(sym, "D", () => ta.ema(close, 20))` |
+| `strategy.entry("L", strategy.long, when = cond)` | `strategy.eachBar((c) => { if (c.get(cond) === 1) strategy.entry("L", strategy.long); })` |
+| `strategy.opentrades.entry_price(0)` | `strategy.opentrade(0)?.entry_price` |
+| `strategy.closedtrades.profit(i)` | `strategy.closedtrade(i)?.profit` |
+| `array.new_float(10, 0)`, `matrix.new<float>()`, `map.new<string, float>()` | `import { array, matrix, map } from "oakscriptjs";` then `array.new_float(10, 0)`, `matrix.new_matrix(...)`, `map.new_map()`; or plain JS arrays / `Map` |
+| `log.info("x = " + str.tostring(x))` | not available: plot it with `display: "data_window"` or put it in a label |
+
+Constants that **do** exist as namespaces: `color.*`, `plot.style_*`, `plot.linestyle_*`, `hline.style_*`,
+`strategy.long / short / fixed / cash / percent_of_equity`, `strategy.commission.*`, `strategy.direction.*`,
+`strategy.oca.*`, `barmerge.*`, `position.*`, `text.align_* / wrap_* / format_*`, `alert.freq_*`,
+`session.regular / extended`, `math.pi / e / phi / rphi`.
+
+## Execution differences
+
+- **Vectorized**: top-level code runs once on all bars. A Pine statement that runs per bar becomes either a
+  Series expression or a bar-loop statement. Top-level JS `if` / ternaries see plain values only (inputs,
+  constants), never per-bar values.
+- **`ta.*` in conditional code**: in Pine a `ta.*` call inside an `if` (or the right side of `and` / `or`) keeps
+  a history of the bars where it ran. Computing it before the loop sees every bar, which can differ. For exact
+  ports use `callsite` (`import { callsite } from "oakscriptjs";`): `callsite.crossover()`, `barssince()`,
+  `highest()`, `lowest()`, `sma()`, `sum()`, `stdev()`, `linreg()`, `pivothigh()`... called with plain values in the
+  loop, or `callsite.whenCalled(calledSeries, fn, ...sources)`.
+- **Recalculation**: no rollback per tick in indicators; the host runs the script again on new data. Strategies
+  can run inside the bar (`calc_on_order_fills`, bar magnifier ticks); `varip(initial)` keeps its value through
+  those runs.
+- **History**: at most 5000 bars back (`max_bars_back` is fixed), as Pine's default.
+- **Time unit**: `time`, `time_close`, `timestamp()` and `input.time` are in ms as in Pine; `c.time` is the bar's
+  own time (UNIX seconds unless the host uses ms).
+
+## API differences
+
+- `ta.vwma(source, length, volume)` needs the volume Series (Pine reads the chart volume).
+- `color.from_gradient` takes numbers: build per-bar gradients in a bar loop.
+- `plot()` has no `offset`, `show_last`, `trackprice` or `join` option; shift a series right with
+  `x.offset(k)`. `plotshape`, `plotchar`, `plotarrow` and `bgcolor` accept `offset` (negative too).
+- `fill()` accepts `show_last` / `fillgaps` / `display` and ignores them.
+- `input.enum` and `input.price` do not exist (use `input.string(..., { options })` and `input.float`).
+- `request.*`: only `request.security` and `request.security_lower_tf`. No `request.financial`,
+  `request.dividends`, `request.earnings`, `request.splits`, `request.economic`, `request.seed`,
+  `request.currency_rate`, `request.footprint`. `ticker.*`: only `ticker.heikinashi` and `ticker.standard`.
+- `box.set_xloc()` is not implemented.
+- `math.random(min, max, seed)`: with a seed, Pine's sequence, but one generator per seed value (Pine has one
+  per call site): two calls with the same seed need `callsite.random(seed)`.
+- `math.log`, `math.exp`, `math.pow`, `math.sin`, `math.cos`, `math.tan`, `math.log10` can differ from Pine in
+  the last digit. Pine rounds constant expressions (`1 / 255`) to 16 decimals: wrap them in `math.constant()`
+  when a script truncates them (`math.constant(1 / 255)`).
+- Strategy results come from the host's engine; the deprecated `when` argument does not exist.
+- No Pine libraries (`import user/lib/1`), no `type` / `method` / `enum` declarations: use JS objects, classes
+  and functions. No type keywords (`float`, `series int`...).
+- `syminfo.*`, `timeframe.*`, `time()`, `session.*` need the host's chart context (an app gives it).
+- Strings: JS strings; `+` concatenates; `str.tostring(x, "#.##")`, `str.format("{0} {1}", a, b)`.

package/skills/oakscript/reference/plotting.md

@@ -0,0 +1,193 @@
+# Plotting
+
+Every output is declared and filled in one call. Titles name the outputs in the host's legend, settings and
+alerts: give each one a title.
+
+## plot
+
+`plot(series, title, { color, linewidth, style, linestyle, histbase, display, force_overlay, editable })`
+returns a handle for `fill()`.
+
+| `style` | Draws |
+|---|---|
+| `plot.style_line` (default), `plot.style_linebr` | a line; `linebr` leaves gaps on na bars |
+| `plot.style_stepline`, `plot.style_steplinebr`, `plot.style_stepline_diamond` | steps |
+| `plot.style_histogram` | bars from `histbase` (default 0) |
+| `plot.style_columns` | columns from 0 |
+| `plot.style_area`, `plot.style_areabr` | filled area |
+| `plot.style_circles`, `plot.style_cross` | points |
+
+`linestyle`: `plot.linestyle_solid` / `_dashed` / `_dotted`. `display`: `"all"`, `"none"` (hidden but listed),
+`"data_window"`, `"status_line"`, `"pane"`. `force_overlay: true` draws on the price pane from a script in its
+own pane. NaN values are not drawn.
+
+```js
+indicator("RSI with levels", { overlay: false });
+const r = ta.rsi(close, 14);
+plot(r, "RSI", { color: color.purple, linewidth: 2 });
+plot(ta.sma(r, 14), "RSI MA", { color: color.orange, linestyle: plot.linestyle_dashed });
+plot(r.sub(50), "Momentum", { style: plot.style_columns, color: color.when(r.gt(50), color.new(color.teal, 60), color.new(color.red, 60)) });
+const upper = hline(70, "Overbought", { color: color.red });
+const lower = hline(30, "Oversold", { color: color.green });
+hline(50, "Middle", { color: color.gray, linestyle: hline.style_dotted });
+fill(upper, lower, color.new(color.purple, 90), "Band");
+```
+
+## Colours
+
+- Constants: `color.red`, `color.green`, `color.blue`, `color.orange`, `color.teal`, `color.purple`, `color.gray`,
+  `color.white`, `color.black`, `color.yellow`, `color.aqua`, `color.lime`, `color.maroon`, `color.navy`,
+  `color.olive`, `color.silver`, `color.fuchsia`; any CSS colour string (`"#2962FF"`, `"rgba(41,98,255,0.5)"`).
+- `color.new(c, transp)` (0 opaque, 100 invisible), `color.rgb(r, g, b, transp?)`,
+  `color.from_gradient(value, bottom, top, bottomColor, topColor)` on numbers, `color.r/g/b/t(c)`.
+- **Per-bar colours** are arrays with one colour per bar (`undefined` = na, not drawn):
+  `color.when(cond, colorTrue, colorFalse?)` for two colours; a bar loop for more, or for a gradient.
+
+```js
+indicator("RSI gradient", { overlay: false });
+const r = ta.rsi(close, 14);
+const colors = [];
+eachBar((c) => {
+  colors.push(color.from_gradient(c.get(r), 30, 70, color.red, color.green)); // numbers, one bar at a time
+});
+plot(r, "RSI", { color: colors, linewidth: 2 });
+```
+
+## hline and fill
+
+- `hline(price, title, { color, linestyle, linewidth })`: a constant level (default dashed);
+  `linestyle: hline.style_solid / _dashed / _dotted`.
+- `fill(handle1, handle2, color, title)` or `fill(h1, h2, { color, title })`: between two plots or two hlines.
+  The colour can be a per-bar array.
+- Gradient fill: `fill(p1, p2, topValue, bottomValue, topColor, bottomColor, title)` (values: numbers or Series).
+
+```js
+indicator("Bollinger fill", { overlay: true });
+const [basis, upper, lower] = ta.bb(close, 20, 2);
+plot(basis, "Basis", { color: color.orange });
+const pu = plot(upper, "Upper", { color: color.blue });
+const pl = plot(lower, "Lower", { color: color.blue });
+fill(pu, pl, upper, lower, color.new(color.blue, 70), color.new(color.blue, 95), "Gradient");
+```
+
+Note: `ta.bb` returns `[basis, upper, lower]` as in Pine.
+
+## Shapes, characters, arrows
+
+- `plotshape(cond, title, { style, location, color, text, textcolor, size, offset, tooltip })`: a shape on
+  each bar where `cond` is not 0 / na. `style`: `"xcross"` (default), `"cross"`, `"triangleup"`,
+  `"triangledown"`, `"flag"`, `"circle"`, `"arrowup"`, `"arrowdown"`, `"labelup"`, `"labeldown"`, `"square"`,
+  `"diamond"`. `location`: `"abovebar"` (default), `"belowbar"`, `"top"`, `"bottom"`, `"absolute"` (at the
+  series value). `size`: `"auto"`, `"tiny"`, `"small"`, `"normal"`, `"large"`, `"huge"`.
+- `plotchar(cond, title, { char, location, color, size, offset })`: a character.
+- `plotarrow(series, title, { colorup, colordown, minheight, maxheight })`: an up arrow for a positive value,
+  a down arrow for a negative one.
+
+```js
+indicator("Markers", { overlay: true });
+const ema = ta.ema(close, 20);
+plotshape(ta.crossover(close, ema), "Buy", { style: "labelup", location: "belowbar", color: color.green, text: "Buy", textcolor: color.white });
+plotshape(ta.crossunder(close, ema), "Sell", { style: "labeldown", location: "abovebar", color: color.red, text: "Sell", textcolor: color.white });
+// a pivot is known 5 bars later: offset -5 puts the mark on the pivot bar; "absolute" places it at the value
+plotshape(ta.pivothigh(5, 5), "Pivot high", { style: "diamond", location: "absolute", offset: -5, color: color.orange, size: "tiny" });
+plotchar(ta.pivotlow(5, 5), "Pivot low", { char: "^", location: "belowbar", offset: -5, color: color.teal });
+plotarrow(ta.change(close, 3), "3-bar change", { colorup: color.teal, colordown: color.red });
+plot(ema, "EMA");
+```
+
+## Background and bar colours
+
+```js
+indicator("Trend colours", { overlay: true });
+const ema = ta.ema(close, 50);
+plot(ema, "EMA", { color: color.gray });
+barcolor(color.when(close.gt(ema), color.teal, color.red), { title: "Trend bars" });
+bgcolor(color.when(ta.cross(close, ema), color.new(color.yellow, 80)), { title: "Cross" });
+```
+
+`bgcolor(colors, { offset, title, force_overlay })`, `barcolor(colors, { title })`: a colour or a per-bar array.
+
+## Candles and bars
+
+`plotcandle(o, h, l, c, title, { color, wickcolor, bordercolor })` and `plotbar(o, h, l, c, title, { color })`
+draw OHLC from four Series (no candle on a bar with an na value).
+
+```js
+indicator("Heikin Ashi", { overlay: false });
+const haClose = ohlc4;
+const highs = [];
+const lows = [];
+const haOpen = eachBar((c) => {
+  const o = c.i === 0 ? (c.open + c.close) / 2 : (c.prev() + c.get(haClose, 1)) / 2; // c.prev(): haOpen[1]
+  highs.push(Math.max(c.high, o, c.get(haClose)));
+  lows.push(Math.min(c.low, o, c.get(haClose)));
+  return o;
+});
+plotcandle(haOpen, seriesOf(highs), seriesOf(lows), haClose, "HA", {
+  color: color.when(haClose.gt(haOpen), color.teal, color.red),
+  wickcolor: color.gray,
+});
+```
+
+## Drawings
+
+Drawings are created in a bar loop, with **positional** arguments in the Pine order and string constants. Skip
+an argument with `undefined`.
+
+| Call | Arguments |
+|---|---|
+| `label.new` | `x, y, text, xloc ("bar_index" / "bar_time"), yloc ("price" / "abovebar" / "belowbar"), color, style, textcolor, size, textalign, tooltip` |
+| `line.new` | `x1, y1, x2, y2, xloc, extend ("none" / "left" / "right" / "both"), color, style ("solid" / "dashed" / "dotted" / "arrow_left" / "arrow_right" / "arrow_both"), width` |
+| `box.new` | `left, top, right, bottom, border_color, border_width, border_style, extend, xloc, bgcolor, text, text_size, text_color` |
+| `table.new` | `position, columns, rows, bgcolor, frame_color, frame_width, border_color, border_width` |
+| `table.cell` | `table, column, row, text, width, height, text_color, text_halign, text_valign, text_size, bgcolor, tooltip` |
+| `polyline.new` | `points (chart.point.from_index(i, price)...), curved, closed, xloc, line_color, fill_color, line_style, line_width` |
+| `linefill.new` | `line1, line2, color` |
+
+Label styles: `"label_down"`, `"label_up"`, `"label_left"`, `"label_right"`, `"label_center"`, `"none"`, and the
+shape names. `x` is a bar index (`c.i`, or `c.i + 10` for a future bar) or, with `"bar_time"`, a UNIX time in ms.
+Positions of tables: `position.top_right`, `position.bottom_left`...
+
+```js
+indicator("Drawings", { overlay: true, max_labels_count: 20 });
+const ph = ta.pivothigh(5, 5);
+const hi = ta.highest(50);
+const lo = ta.lowest(50);
+eachBar((c) => {
+  const p = c.get(ph);
+  if (!Number.isNaN(p)) {
+    label.new(c.i - 5, p, str.tostring(p, "#.##"), "bar_index", "price", color.red, "label_down", color.white, "small");
+  }
+  if (c.i === c.n - 1) {
+    line.new(c.i - 49, c.get(hi), c.i + 10, c.get(hi), "bar_index", "none", color.green, "dashed", 2);
+    box.new(c.i - 49, c.get(hi), c.i, c.get(lo), color.gray, 1, "dotted", "none", "bar_index", color.new(color.gray, 90), "50-bar range");
+    const t = table.new(position.bottom_right, 1, 1, color.new(color.black, 30));
+    table.cell(t, 0, 0, "Range " + str.tostring(c.get(hi) - c.get(lo), "#.##"), 0, 0, color.white);
+  }
+});
+plot(close, "Close", { display: "none" });
+```
+
+- Keep one object and update it (`line.set_xy1(l, x, y)`, `label.set_text(lb, t)`, `box.set_top(b, y)`...)
+  rather than creating one per bar when only the last one matters.
+- Objects above `max_labels_count` / `max_lines_count` / `max_boxes_count` / `max_polylines_count` (default 50)
+  are deleted oldest first; `label.delete(lb)` deletes one. `const keep = varDrawing();` then
+  `keep.value = line.new(...)` is Pine's `var line keep = na` (that object is never deleted by the limit).
+- `label.all`, `line.all`... list the live objects.
+
+## Alerts
+
+- `alertcondition(cond, title, message)`: a condition the user can create an alert on.
+- `alert(message, freq)` inside a bar loop: an alert call on that bar; `freq`: `alert.freq_once_per_bar`
+  (default), `alert.freq_once_per_bar_close`, `alert.freq_all`.
+
+```js
+indicator("Alerts", { overlay: true });
+const ma = ta.sma(close, 20);
+const up = ta.crossover(close, ma);
+plot(ma, "SMA");
+alertcondition(up, "Cross up", "Close crossed above the SMA");
+eachBar((c) => {
+  if (c.get(up) === 1) alert("Close " + str.tostring(c.close, "#.##") + " crossed above the SMA", alert.freq_once_per_bar_close);
+});
+```

package/skills/oakscript/reference/script-structure.md

@@ -0,0 +1,182 @@
+# Script structure
+
+## Execution model
+
+Pine Script runs a script once per bar. OakScript runs the script body **once per calculation, over all the bars
+at once**:
+
+- Top-level code computes whole Series (one value per bar) with `ta.*` and the Series methods.
+- Logic that needs the bars one by one (state, `if` on values, loops) goes in `eachBar((c) => ...)` or, for a
+  strategy, `strategy.eachBar((c) => ...)`.
+- The host runs the body again when bars arrive or an input changes; every run starts from scratch, so plain
+  `let` variables are reset on each run (as Pine resets `var` on a recalculation).
+
+Order of a script: declaration, inputs, Series math, bar loops, outputs. Outputs can appear anywhere after the
+values they plot.
+
+## Declaration
+
+```js
+indicator("Average True Range Bands", {
+  shorttitle: "ATR Bands", // legend title
+  overlay: true,           // default true: price pane; false: own pane
+  precision: 2,            // decimals shown
+  max_labels_count: 100,   // also max_lines_count, max_boxes_count, max_polylines_count (default 50)
+});
+const atr = ta.atr(14);
+plot(close.add(atr.mul(2)), "Upper");
+plot(close.sub(atr.mul(2)), "Lower");
+```
+
+`strategy(title, options)` replaces `indicator()` for a strategy (default `overlay: false`); its properties are in
+[strategies.md](strategies.md). A script without a declaration runs with the title "Untitled" and overlay on.
+
+## Inputs
+
+Each `input.*` call declares the input for the host's settings and returns its current value: the host's
+override when there is one, else the default.
+
+| Call | Returns |
+|---|---|
+| `input.int(defval, title, { minval, maxval, step })` | integer (rounded) |
+| `input.float(defval, title, { minval, maxval, step })` | number |
+| `input.bool(defval, title)` | boolean |
+| `input.string(defval, title, { options: [...] })` | string (a choice list with `options`) |
+| `input.text_area(defval, title)` | multi-line string |
+| `input.color(defval, title)` | colour string |
+| `input.source("close", title)` | Series (`open high low close volume hl2 hlc3 ohlc4 hlcc4`, or another script's output when the host allows it) |
+| `input.timeframe("D", title, { options })` | timeframe string (`""`: the chart timeframe) |
+| `input.session("0930-1600", title)` | session string |
+| `input.symbol("NASDAQ:AAPL", title)` | ticker id for `request.security` |
+| `input.time(timestamp("2024-01-01"), title)` | UNIX time in ms |
+
+Options of every kind: `group`, `inline`, `tooltip`, `confirm`, `display`, `active` (false greys the input out).
+
+```js
+indicator("Inputs demo");
+const showMa = input.bool(true, "Show MA", { group: "Average", inline: "ma" });
+const maLength = input.int(20, "Length", { minval: 1, maxval: 500, group: "Average", inline: "ma", active: showMa });
+const maColor = input.color(color.blue, "Colour", { group: "Average" });
+const mode = input.string("Close", "Price", { options: ["Close", "HL2"], tooltip: "Price of the average" });
+const src = mode === "HL2" ? hl2 : close; // inputs are plain values: JS operators work on them
+plot(ta.sma(src, maLength), "MA", { color: maColor, display: showMa ? "all" : "none" });
+```
+
+**Input ids.** The host sets inputs by id: the title in snake case (`"Fast length"` is `fast_length`, a repeated
+title gets `_2`, `_3`). Keep titles stable: renaming one resets the user's value.
+
+## Series
+
+`close`, `open`, `high`, `low`, `volume`, `hl2`, `hlc3`, `ohlc4`, `hlcc4`, the `ta.*` results and the inputs from
+`input.source` are `Series`: one number per bar, NaN for na.
+
+| Pine | Series method |
+|---|---|
+| `a + b`, `a - b`, `a * b`, `a / b`, `a % b`, `-a`, `math.pow(a, n)` | `a.add(b)`, `a.sub(b)`, `a.mul(b)`, `a.div(b)`, `a.mod(b)`, `a.neg()`, `a.pow(n)` |
+| `a > b`, `a >= b`, `a < b`, `a <= b`, `a == b`, `a != b` | `a.gt(b)`, `a.gte(b)`, `a.lt(b)`, `a.lte(b)`, `a.eq(b)`, `a.neq(b)` (1 / 0, false with na) |
+| `a and b`, `a or b`, `not a` | `a.and(b)`, `a.or(b)`, `a.not()` |
+| `cond ? x : y` | `cond.iff(x, y)` (na and 0 are false) |
+| `a[n]` | `a.offset(n)` (n >= 0) |
+
+`b` can be a Series or a number. Comparisons follow the Pine rules (1e-10 tolerance). `series.toArray()` gives
+the values as a `number[]` (oldest first); `seriesOf(numbers)` turns an array with one value per bar back into a
+Series.
+
+```js
+indicator("Body ratio", { overlay: false });
+const body = close.sub(open);
+const range = high.sub(low);
+const ratio = range.gt(0).iff(body.div(range), 0);           // guard the division
+plot(ratio, "Body / range", { style: plot.style_columns, color: color.when(ratio.gt(0), color.teal, color.red) });
+hline(0);
+```
+
+`ta.*` takes Series and lengths (a plain number; `ta.sma`, `ta.wma`, `ta.stdev`, `ta.variance`, `ta.highest`,
+`ta.lowest` also accept a Series of lengths) and returns a Series, or an array of Series for the Pine tuples
+(`ta.macd`, `ta.bb`, `ta.kc`, `ta.dmi`, `ta.supertrend`, `ta.ichimoku`, `ta.vwap(src, anchor, mult)`). The chart
+functions read the bars themselves: `ta.atr(14)`, `ta.tr(true)`, `ta.sar()`, `ta.supertrend(3, 10)`,
+`ta.dmi(14, 14)`, `ta.wpr(14)`, `ta.mfi(hlc3, 14)`, `ta.highest(20)` (high), `ta.pivothigh(5, 5)`. The volume
+indicators are variables: `ta.obv`, `ta.accdist`, `ta.pvt`, `ta.nvi`, `ta.pvi`, `ta.iii`, `ta.wad`, `ta.wvad`.
+
+## Bar loops: eachBar
+
+`eachBar(fn)` calls `fn(c)` once per bar, oldest first, and returns a Series of the values it returns
+(`true` / `false` become 1 / 0, no return value becomes NaN).
+
+| `c.` | Value |
+|---|---|
+| `i`, `n` | bar index (Pine `bar_index`), number of bars (`c.i === c.n - 1` is the last bar) |
+| `time` | bar open time, in the unit of the bars (UNIX seconds by default) |
+| `open`, `high`, `low`, `close`, `volume` | the bar's prices |
+| `get(series, k = 0)` | `series[k]` as a number (NaN before the first bar) |
+| `prev(k = 1)` | this loop's own return value k bars back (Pine self-reference) |
+
+```js
+indicator("ATR trailing stop", { overlay: true });
+const atr = ta.atr(14);
+let stop = NaN; // var float stop = na
+let dir = 1;    // var int dir = 1
+const dirs = [];
+const trail = eachBar((c) => {
+  const offset = 3 * c.get(atr);
+  if (Number.isNaN(offset)) { dirs.push(NaN); return NaN; }
+  if (dir === 1) {
+    stop = Number.isNaN(stop) ? c.close - offset : Math.max(stop, c.close - offset);
+    if (c.close < stop) { dir = -1; stop = c.close + offset; }
+  } else {
+    stop = Math.min(stop, c.close + offset);
+    if (c.close > stop) { dir = 1; stop = c.close - offset; }
+  }
+  dirs.push(dir);
+  return stop;
+});
+const up = seriesOf(dirs).eq(1);
+plot(trail, "Stop", { style: plot.style_linebr, color: color.when(up, color.teal, color.red) });
+plotshape(up.and(up.offset(1).not()), "Flip up", { style: "circle", location: "belowbar", color: color.teal, size: "tiny" });
+```
+
+- A `let` before the loop is Pine `var`: it keeps its value from bar to bar. A `const` inside the callback is a
+  plain per-bar variable.
+- Several outputs from one loop: push into arrays declared before the loop, then `seriesOf(array)`.
+- Plain `Math.*` is fine on numbers; Pine's `math.*` is available too (`math.max`, `math.round`...).
+- History: `c.get(x, k)` and `x.offset(k)` reach at most 5000 bars back (the built-in prices have no limit).
+- `varip(initial)` (declare it at the top level, use `.value`) keeps its value through the intrabar runs of a
+  strategy; without them it is a plain variable.
+- A `ta.*` call in an `if` block or in the right side of `&&` / `||` sees only some bars in Pine. To port that
+  exactly, use the call sites of `callsite` (`import { callsite } from "oakscriptjs";`), e.g.
+  `const since = callsite.barssince();` then `since(cond)` in the loop.
+
+## Builtins
+
+| Name | Value |
+|---|---|
+| `time`, `time_close`, `time_tradingday`, `timenow` | Series of UNIX ms |
+| `time(tf, session?, timezone?)`, `time_close(tf, ...)` | period open / close time, NaN outside the session |
+| `year(t)`, `month(t)`, `dayofmonth(t)`, `dayofweek(t)`, `hour(t)`, `minute(t)`, `second(t)`, `weekofyear(t)` | calendar fields of a time (number or Series) in the exchange time zone (or the given one) |
+| `timestamp("2024-01-01")`, `timestamp(2024, 1, 1, 9, 30)` | UNIX ms |
+| `barstate.isfirst / islast / isconfirmed / isrealtime / isnew / ishistory / islastconfirmedhistory` | Series of 1 / 0 |
+| `session.isfirstbar / islastbar / ismarket / ispremarket / ispostmarket` | Series of 1 / 0 |
+| `timeframe.period`, `timeframe.isintraday`, `timeframe.isdaily`, `timeframe.multiplier`..., `timeframe.change("W")`, `timeframe.in_seconds()` | chart timeframe values |
+| `syminfo.tickerid`, `syminfo.mintick`, `syminfo.timezone`, `syminfo.currency`, `syminfo.type`... | symbol values |
+| `str.tostring(x, "#.##")`, `str.format("{0} / {1}", a, b)`, `str.*` | text |
+| `math.*`, `color.*`, `compare.*` | as in Pine; `compare` gives the Pine comparison of two numbers |
+
+The time, session, timeframe and symbol values come from the host's chart context. An app supplies them; in your
+own `executeScript` call pass them in the 4th argument, or the script stops with "... is not known: pass it as
+executeScript(body, bars, inputs, { ... })".
+
+```js
+indicator("Session marks", { overlay: true });
+const newDay = timeframe.change("D");
+bgcolor(color.when(newDay, color.new(color.blue, 80)), { title: "New day" });
+plotchar(barstate.islast, "Last", { char: "L", location: "abovebar" });
+plot(close, "Close", { display: "none" });
+```
+
+## Drawings
+
+`label.new`, `line.new`, `box.new`, `polyline.new`, `linefill.new` and `table.new` create objects; the host draws
+the ones alive after the last bar. Create them in a bar loop with bar indexes (`c.i`) or bar times. Old objects
+are deleted above `max_*_count` (default 50). To keep one object and move it, store it in a variable and update
+it with the `set_*` functions, or hold it with `varDrawing()` (Pine `var line l = na`). See
+[plotting.md](plotting.md#drawings).