oakscriptjs 0.13.1 → 0.14.0

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

@@ -0,0 +1,85 @@
+# 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 })` or `input.int(14, { title: "Length", minval: 1 })` |
+| `src = input.source(close, "Source")` | `const src = input.source(close, "Source")` |
+| `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` | the Series `bar_index`, `last_bar_index`; in a bar loop `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: shape.triangleup, location: location.belowbar, size: size.small })` |
+| `label.new(bar_index, high, "A", style=label.style_label_down)` (in an `if`) | in a bar loop: `label.new(bar_index, high, "A", { style: label.style_label_down })` (or `c.i`, `c.high`) |
+| `line.new(x1, y1, x2, y2, extend=extend.right)` | `line.new(x1, y1, x2, y2, { extend: extend.right })` |
+| `xloc.bar_time`, `yloc.abovebar`, `line.style_dashed`, `format.volume`, `display.none`, `dayofweek.monday` | the same |
+| `request.security(sym, "D", ta.ema(close, 20))` | `request.security(sym, "D", () => ta.ema(close, 20))` |
+| `request.security(sym, "W", high[1], lookahead = barmerge.lookahead_on)` | `request.security(sym, "W", () => high.offset(1), { lookahead: barmerge.lookahead_on })` |
+| `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.opentrades` is the count: a JavaScript number cannot also hold the functions) |
+| `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 |
+
+The Pine constants exist with their Pine names: `shape.*`, `location.*`, `size.*`, `xloc.*`, `yloc.*`,
+`extend.*`, `display.*`, `format.*`, `font.family_*`, `scale.*`, `order.*`, `currency.*`, `adjustment.*`,
+`label.style_*`, `line.style_*`, `dayofweek.*`, `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`. Their values are the strings the functions take
+(`shape.triangleup` is `"triangleup"`).
+
+## 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
+
+- `color.from_gradient` takes numbers: build per-bar gradients in a bar loop.
+- `plot()` has no `show_last`, `trackprice` or `join` option. `offset` shifts the plot as in Pine (values past the
+  first or last bar are not drawn).
+- `fill()` accepts `show_last` / `fillgaps` / `display` and ignores them.
+- `input.enum` does not exist (no `enum` declarations): use `input.string(..., { options })`.
+- `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`.
+- `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,199 @@
+# 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`: `shape.xcross` (default), `shape.cross`, `shape.triangleup`,
+  `shape.triangledown`, `shape.flag`, `shape.circle`, `shape.arrowup`, `shape.arrowdown`, `shape.labelup`,
+  `shape.labeldown`, `shape.square`, `shape.diamond`. `location`: `location.abovebar` (default), `location.belowbar`,
+  `location.top`, `location.bottom`, `location.absolute` (at the series value). `size`: `size.auto`, `size.tiny`,
+  `size.small`, `size.normal`, `size.large`, `size.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: shape.labelup, location: location.belowbar, color: color.green, text: "Buy", textcolor: color.white });
+plotshape(ta.crossunder(close, ema), "Sell", { style: shape.labeldown, location: 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: shape.diamond, location: location.absolute, offset: -5, color: color.orange, size: size.tiny });
+plotchar(ta.pivotlow(5, 5), "Pivot low", { char: "^", location: 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 the Pine arguments: the first ones by position, the others by name in an
+object after them (Pine's named arguments), e.g. `label.new(c.i, c.high, "A", { style: label.style_label_down })`.
+Every argument can be named (`line.new({ x1, y1, x2, y2, extend: extend.right })`); an unknown name throws with the
+closest names. In the loop, a Series argument is its value on the current bar: `label.new(bar_index, high, "A")` is
+`label.new(c.i, c.high, "A")`.
+
+| Call | Arguments |
+|---|---|
+| `label.new` | `x, y, text, xloc (xloc.bar_index / xloc.bar_time), yloc (yloc.price / yloc.abovebar / yloc.belowbar), color, style, textcolor, size, textalign, tooltip, text_font_family, force_overlay, text_formatting` |
+| `line.new` | `x1, y1, x2, y2, xloc, extend (extend.none / left / right / both), color, style (line.style_solid / dashed / dotted / arrow_left / arrow_right / arrow_both), width, force_overlay` |
+| `box.new` | `left, top, right, bottom, border_color, border_width, border_style, extend, xloc, bgcolor, text, text_size, text_color, text_halign, text_valign, text_wrap, text_font_family, force_overlay, text_formatting` |
+| `table.new` | `position, columns, rows, bgcolor, frame_color, frame_width, border_color, border_width` |
+| `table.cell` | `table_id, column, row, text, width, height, text_color, text_halign, text_valign, text_size, bgcolor, tooltip, text_font_family, text_formatting` |
+| `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.style_label_down`, `label.style_label_up`, `label.style_label_left`, `label.style_label_right`,
+`label.style_label_center`, `label.style_none`, and `label.style_<shape>`. `x` is a bar index (`c.i`, or `c.i + 10`
+for a future bar) or, with `xloc.bar_time`, a UNIX time in ms. The constants are the strings (`"label_down"`), which
+also work.
+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, "#.##"), { color: color.red, style: label.style_label_down, textcolor: color.white, size: size.small });
+  }
+  if (c.i === c.n - 1) {
+    line.new(c.i - 49, c.get(hi), c.i + 10, c.get(hi), { color: color.green, style: line.style_dashed, width: 2 });
+    box.new(c.i - 49, c.get(hi), c.i, c.get(lo), { border_color: color.gray, border_style: line.style_dotted, bgcolor: color.new(color.gray, 90), text: "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,185 @@
+# 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,           // true: price pane; false (default): 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" in its own pane.
+
+## 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). They
+have Pine's names (`minval`, not `min`): an unknown name throws with the closest names. The title can also be in the
+options object (`input.int(14, { title: "Length", minval: 1 })`), or every argument named (`input.int({ defval: 14,
+title: "Length" })`).
+
+```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: shape.circle, location: location.belowbar, color: color.teal, size: 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: 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).

package/skills/oakscript/reference/strategies.md

@@ -0,0 +1,140 @@
+# Strategies
+
+A strategy is a script declared with `strategy()` whose orders go to an order engine. OakScriptJS does not fill
+orders itself: the host supplies the engine (an app's backtester, or your own), which fills the orders, keeps the
+trades and computes the results the host shows (net profit, drawdown, list of trades...).
+
+## Declaration and sizing
+
+```js
+strategy("Breakout", {
+  overlay: true,                                   // default false
+  initial_capital: 10000,                          // default 100000
+  default_qty_type: strategy.percent_of_equity,    // or strategy.fixed (units), strategy.cash (amount)
+  default_qty_value: 25,                           // default 100 (% of equity)
+  pyramiding: 0,                                   // entries allowed in the same direction beyond the first
+  commission_type: strategy.commission.percent,    // or .cash_per_contract, .cash_per_order
+  commission_value: 0.1,
+  slippage: 2,                                     // ticks added to market and stop fills
+});
+const length = input.int(20, "Channel length", { minval: 2 });
+const upper = ta.highest(high, length).offset(1);
+const lower = ta.lowest(low, length).offset(1);
+plot(upper, "Upper", { color: color.green });
+plot(lower, "Lower", { color: color.red });
+strategy.eachBar((c) => {
+  if (strategy.position_size <= 0) strategy.entry("Long", strategy.long, { stop: c.get(upper) });
+  if (strategy.position_size >= 0) strategy.entry("Short", strategy.short, { stop: c.get(lower) });
+});
+```
+
+Other properties, with the Pine Script v6 names and defaults: `currency`, `margin_long` / `margin_short` (100),
+`process_orders_on_close` (false), `close_entries_rule` (`"FIFO"`), `calc_on_order_fills`, `calc_on_every_tick`,
+`use_bar_magnifier`, `fill_orders_on_standard_ohlc`, `backtest_fill_limits_assumption`, `risk_free_rate` (2).
+A host can override them from its settings.
+
+Order size: the `qty` option of an order (units) wins over `default_qty_type` / `default_qty_value`.
+
+## The bar loop
+
+`strategy.eachBar((c) => ...)` is the strategy's `eachBar` (same `c`, returns a Series) and runs once per script.
+On each bar:
+
+1. the engine fills the orders placed before (market orders at the bar's open; stop / limit orders when the
+   bar reaches their price);
+2. the callback runs at the bar's close: read the state, place, change or cancel orders;
+3. with `process_orders_on_close: true`, new market orders fill at that close; else at the next bar's open.
+
+Order calls and per-bar `strategy.*` reads throw outside `strategy.eachBar()`. Compute every Series before it.
+
+## Orders
+
+| Call | Use |
+|---|---|
+| `strategy.entry(id, strategy.long / strategy.short, { qty, limit, stop, oca_name, oca_type, comment, alert_message })` | open a position; an entry in the other direction reverses the position; market order without `limit` / `stop` |
+| `strategy.order(id, direction, { qty, limit, stop, ... })` | a raw order: adds to or reduces the position, no reversal logic |
+| `strategy.exit(id, { from_entry, qty, qty_percent, stop, limit, loss, profit, trail_price, trail_points, trail_offset, comment, ... })` | stop loss / take profit / trailing stop for an entry; `stop` / `limit` / `trail_price` are prices, `loss` / `profit` / `trail_points` / `trail_offset` are in ticks |
+| `strategy.close(id, { qty, qty_percent, comment, immediately })` | close the trades of entry `id` at market |
+| `strategy.close_all({ comment, immediately })` | close the whole position at market |
+| `strategy.cancel(id)`, `strategy.cancel_all()` | cancel pending orders |
+
+- A call with the id of a pending order changes that order (calling `strategy.exit` on every bar with new prices
+  moves the stop).
+- `NaN` in an option means "not given" (it is removed), as `na` in Pine.
+- `strategy.exit` placed while the entry is still pending waits for it (`from_entry`).
+
+```js
+strategy("Trailing exit", { overlay: true, initial_capital: 10000, default_qty_type: strategy.fixed, default_qty_value: 10 });
+const fast = ta.ema(close, 12);
+const slow = ta.ema(close, 26);
+const atr = ta.atr(14);
+const goLong = ta.crossover(fast, slow);
+const goFlat = ta.crossunder(fast, slow);
+strategy.eachBar((c) => {
+  if (c.get(goLong) === 1) strategy.entry("Long", strategy.long, { comment: "EMA cross" });
+  if (c.get(goFlat) === 1) strategy.close("Long", { comment: "Cross down" });
+  if (strategy.position_size > 0) {
+    const trade = strategy.opentrade(0);                     // Pine strategy.opentrades.*(0)
+    const stop = trade.entry_price - 2 * c.get(atr);
+    strategy.exit("Stop", { from_entry: "Long", stop, comment: "ATR stop" });
+  }
+});
+plot(fast, "Fast");
+plot(slow, "Slow");
+```
+
+## Reading the results
+
+Inside `strategy.eachBar()`, from the engine, for the current bar:
+
+| Variable | Meaning |
+|---|---|
+| `strategy.position_size` | signed quantity: > 0 long, < 0 short, 0 flat |
+| `strategy.position_avg_price`, `strategy.position_entry_name` | average entry price (NaN when flat), entry id |
+| `strategy.equity`, `strategy.initial_capital` | initial capital + net profit + open profit |
+| `strategy.netprofit`, `strategy.openprofit`, `strategy.grossprofit`, `strategy.grossloss` (and `_percent`) | profits |
+| `strategy.opentrades`, `strategy.closedtrades`, `strategy.wintrades`, `strategy.losstrades`, `strategy.eventrades` | trade counts |
+| `strategy.max_drawdown`, `strategy.max_runup`, `strategy.avg_trade`... | statistics |
+| `strategy.opentrade(i)`, `strategy.closedtrade(i)` | trade `i` (0 = oldest): `{ entry_id, entry_price, entry_bar_index, entry_time, size, profit, commission, exit_price, exit_bar_index, ... }`, undefined when there is none |
+| `strategy.default_entry_qty(price)` | the quantity a default-size entry would get |
+
+Pine's `strategy.closedtrades.profit(i)` is `strategy.closedtrade(i)?.profit`. `strategy.initial_capital` and
+`strategy.account_currency` can be read anywhere.
+
+```js
+strategy("Equity curve", { overlay: false, initial_capital: 5000, default_qty_type: strategy.cash, default_qty_value: 1000 });
+strategy.risk.allow_entry_in(strategy.direction.long);   // risk rules: top level, after strategy()
+const rsi = ta.rsi(close, 14);
+const equity = strategy.eachBar((c) => {
+  if (c.get(rsi) < 30) strategy.entry("Long", strategy.long);
+  if (c.get(rsi) > 70) strategy.close_all({ comment: "RSI > 70" });
+  const last = strategy.closedtrade(strategy.closedtrades - 1);
+  if (last && last.exit_bar_index === c.i && last.profit < 0) alert("Losing trade closed");
+  return strategy.equity;                                // the loop's Series: equity per bar
+});
+plot(equity, "Equity", { color: color.teal });
+hline(5000, "Initial capital", { color: color.gray });
+```
+
+Risk rules: `strategy.risk.allow_entry_in(dir)`, `max_drawdown(value, type)`, `max_intraday_loss(value, type)`,
+`max_cons_loss_days(count)`, `max_intraday_filled_orders(count)`, `max_position_size(contracts)` (type:
+`"percent_of_equity"` or `"cash"`). An engine that does not support a rule or a variable throws
+"... is not provided by the strategy engine".
+
+## The host side
+
+A host passes an engine factory to `executeScript`:
+
+```ts
+import { executeScript, type StrategyEngine } from 'oakscriptjs/script';
+
+const run = executeScript(body, bars, inputs, chart, {
+  strategyEngine: ({ properties, bars, chart }) => new MyEngine(properties, bars), // implements StrategyEngine
+});
+// run.strategyConfig: the resolved properties
+```
+
+`StrategyEngine` methods: `processBar(i)`, `processClose(i)`, `entry`, `order`, `exit`, `close`, `close_all`,
+`cancel`, `cancel_all`, `get(variable)`, `openTrade(i)`, `closedTrade(i)`, and optionally `risk(rule)`,
+`defaultEntryQty(price)`. The option objects keep the Pine names. Without an engine, `strategy()` declares the
+strategy and `strategy.eachBar()` throws "no strategy engine".