oakscriptjs 0.13.2 → 0.14.0

package/src/script/index.ts

@@ -75,6 +75,8 @@ import type {
 } from '../runtime/types.js';
 import { BarData, Series, MAX_BARS_BACK, historyError } from '../runtime/series.js';
 import * as taSeries from '../ta-series.js';
+import * as pineConstants from './constants.js';
+import { drawingNamespace, isPlainObject, namedArguments, unknownArgument } from './drawing-args.js';
 import * as colorCore from '../color/index.js';
 import { inputColorDefault } from '../color/parse.js';
 import { fixnan as fixnanValues, isNA, nz } from '../utils/index.js';
@@ -109,7 +111,7 @@ import { SessionBars, sessionFlags, strayPeriods, type SessionFlags } from '../s
 import { afterCompletion, heikinAshi, mapToChart, periodsOf, resample } from '../security/resample.js';
 import { securityLowerTf, securityOther, type OtherSymbolChart } from '../security/other.js';
 import { position } from '../types/index.js';
-import type { ChartPoint } from '../types/index.js';
+import type { Box, ChartPoint, Label, Line, Linefill, Polyline, Table } from '../types/index.js';
 import {
   STRATEGY_CONSTANTS,
   STRATEGY_DEFAULTS,
@@ -135,7 +137,7 @@ import { sessionPeriods, type SessionPeriods } from '../session/context.js';
 
 /** Everything one run of a script produced. */
 export interface ScriptRunResult {
-  metadata: { title: string; shortTitle?: string; overlay: boolean; precision?: number; format?: string };
+  metadata: { title: string; shortTitle?: string; overlay: boolean; precision?: number; format?: string; scale?: 'right' | 'left' | 'none' };
   inputConfig: InputConfig[];
   plotConfig: PlotConfig[];
   hlineConfig: HLineConfig[];
@@ -218,6 +220,8 @@ interface Collector {
   overlay: boolean;
   precision?: number;
   format?: string;
+  /** indicator(..., { scale }): the price scale the script uses. */
+  scale?: 'right' | 'left' | 'none';
   inputValues: Record<string, unknown>;
   inputConfig: InputConfig[];
   inputIds: Set<string>;
@@ -275,7 +279,7 @@ function collector(): Collector {
 function freshCollector(inputValues: Record<string, unknown>): Collector {
   return {
     title: 'Untitled',
-    overlay: true,
+    overlay: false,
     inputValues,
     inputConfig: [],
     inputIds: new Set(),
@@ -452,6 +456,7 @@ export function executeScript(
         overlay: c.overlay,
         precision: c.precision,
         format: c.format,
+        ...(c.scale ? { scale: c.scale } : {}),
       },
       inputConfig: c.inputConfig,
       plotConfig: c.plotConfig,
@@ -595,9 +600,12 @@ export function varip<T>(initial: T): VaripVariable<T> {
 
 export interface IndicatorOptions {
   shorttitle?: string;
+  /** true: drawn on the price pane; false (default, as PineScript): in its own pane. */
   overlay?: boolean;
   precision?: number;
   format?: string;
+  /** The price scale: `scale.right`, `scale.left` or `scale.none` (recorded in `metadata.scale` for the host). */
+  scale?: 'right' | 'left' | 'none';
   /** Lines kept before the oldest are deleted (default 50; PineScript keeps up to 5 more). */
   max_lines_count?: number;
   /** Labels kept before the oldest are deleted (default 50). */
@@ -614,9 +622,10 @@ export function indicator(title: string, options: IndicatorOptions = {}): void {
   declare(c, 'indicator');
   c.title = title;
   c.shortTitle = options.shorttitle;
-  c.overlay = options.overlay ?? true;
+  c.overlay = options.overlay ?? false;
   c.precision = options.precision;
   c.format = options.format;
+  c.scale = options.scale;
   setDrawingLimits({
     line: options.max_lines_count,
     label: options.max_labels_count,
@@ -688,61 +697,132 @@ function registerNumeric(type: 'int' | 'float', defval: number, title?: string,
   return typeof v === 'number' ? v : defval;
 }
 
-/** PineScript `input.*` — declares an input AND returns its current value. */
-export const input = {
-  int(defval: number, title?: string, opts: NumericInputOptions = {}): number {
-    return Math.round(registerNumeric('int', defval, title, opts));
+/** Named arguments of an input: its options, with `title` (and `defval` when every argument is named). */
+type InputArgs<O, D> = O & { title?: string; defval?: D };
+
+const COMMON_INPUT_KEYS = ['tooltip', 'inline', 'group', 'confirm', 'display', 'active'] as const;
+/** The PineScript arguments of each input kind (named arguments are checked against them). */
+const INPUT_KEYS: Record<string, readonly string[]> = {
+  int: ['defval', 'title', 'minval', 'maxval', 'step', ...COMMON_INPUT_KEYS],
+  float: ['defval', 'title', 'minval', 'maxval', 'step', ...COMMON_INPUT_KEYS],
+  price: ['defval', 'title', ...COMMON_INPUT_KEYS],
+  bool: ['defval', 'title', ...COMMON_INPUT_KEYS],
+  string: ['defval', 'title', 'options', ...COMMON_INPUT_KEYS],
+  text_area: ['defval', 'title', ...COMMON_INPUT_KEYS],
+  color: ['defval', 'title', ...COMMON_INPUT_KEYS],
+  source: ['defval', 'title', ...COMMON_INPUT_KEYS],
+  timeframe: ['defval', 'title', 'options', ...COMMON_INPUT_KEYS],
+  session: ['defval', 'title', 'options', ...COMMON_INPUT_KEYS],
+  symbol: ['defval', 'title', 'options', ...COMMON_INPUT_KEYS],
+  time: ['defval', 'title', ...COMMON_INPUT_KEYS],
+};
+
+/**
+ * The default, title and options of an `input.*` call, as PineScript writes it: `(defval, title, options)`,
+ * `(defval, { title, ...options })` or every argument by name (`{ defval, title, ...options }`). An unknown named
+ * argument throws with the closest names (`min` for `minval`).
+ */
+function inputArgs<D, O extends object>(
+  kind: string,
+  defvalOrArgs: unknown,
+  titleOrArgs: unknown,
+  opts: O | undefined
+): { defval: D; title: string | undefined; opts: O } {
+  const name = `input.${kind}`;
+  const keys = INPUT_KEYS[kind]!;
+  let named: Record<string, unknown> = {};
+  let defval = defvalOrArgs;
+  let title: unknown = titleOrArgs;
+  if (isPlainObject(defvalOrArgs)) {
+    named = { ...defvalOrArgs };
+    defval = named.defval;
+    title = undefined;
+  } else if (isPlainObject(titleOrArgs)) {
+    named = { ...titleOrArgs };
+    title = undefined;
+  }
+  if (opts !== undefined) {
+    if (!isPlainObject(opts)) throw new TypeError(`${name}(): the options are an object, e.g. { tooltip: "..." }.`);
+    named = { ...named, ...opts };
+  }
+  for (const key of Object.keys(named)) if (!keys.includes(key)) throw unknownArgument(name, key, keys);
+  if (title !== undefined && typeof title !== 'string') {
+    throw new TypeError(`${name}(): the title is a string, got ${typeof title}.`);
+  }
+  const { defval: namedDefval, title: namedTitle, ...rest } = named;
+  return {
+    defval: (defval ?? namedDefval) as D,
+    title: (title as string | undefined) ?? (namedTitle as string | undefined),
+    opts: rest as O,
+  };
+}
+
+/** PineScript `input.*` — declares an input AND returns its current value. The arguments after the default can be
+ *  named, as in PineScript: `input.int(14, "Length", { minval: 1 })`, `input.int(14, { title: "Length", minval: 1 })`,
+ *  `input.int({ defval: 14, title: "Length" })`. */
+export const input = strictNamespace('input', {
+  int(defval: number | InputArgs<NumericInputOptions, number>, title?: string | InputArgs<NumericInputOptions, number>, opts?: NumericInputOptions): number {
+    const a = inputArgs<number, NumericInputOptions>('int', defval, title, opts);
+    return Math.round(registerNumeric('int', a.defval, a.title, a.opts));
   },
-  float(defval: number, title?: string, opts: NumericInputOptions = {}): number {
-    return registerNumeric('float', defval, title, opts);
+  float(defval: number | InputArgs<NumericInputOptions, number>, title?: string | InputArgs<NumericInputOptions, number>, opts?: NumericInputOptions): number {
+    const a = inputArgs<number, NumericInputOptions>('float', defval, title, opts);
+    return registerNumeric('float', a.defval, a.title, a.opts);
   },
-  bool(defval: boolean, title?: string, opts: InputOptions = {}): boolean {
-    return registerInput<boolean>({ type: 'bool', defval, title, ...common(opts) }, 'input_bool');
+  bool(defval: boolean | InputArgs<InputOptions, boolean>, title?: string | InputArgs<InputOptions, boolean>, opts?: InputOptions): boolean {
+    const a = inputArgs<boolean, InputOptions>('bool', defval, title, opts);
+    return registerInput<boolean>({ type: 'bool', defval: a.defval, title: a.title, ...common(a.opts) }, 'input_bool');
   },
-  string(defval: string, title?: string, opts: StringInputOptions = {}): string {
-    return registerInput<string>({ type: 'string', defval, title, options: opts.options, ...common(opts) }, 'input_string');
+  string(defval: string | InputArgs<StringInputOptions, string>, title?: string | InputArgs<StringInputOptions, string>, opts?: StringInputOptions): string {
+    const a = inputArgs<string, StringInputOptions>('string', defval, title, opts);
+    return registerInput<string>({ type: 'string', defval: a.defval, title: a.title, options: a.opts.options, ...common(a.opts) }, 'input_string');
   },
-  /** Multi-line text ("
-" between the lines), e.g. a list a script parses (#184). */
-  text_area(defval: string, title?: string, opts: InputOptions = {}): string {
-    return registerInput<string>({ type: 'text_area', defval, title, ...common(opts) }, 'input_text_area');
+  /** Multi-line text (lines separated by a newline), e.g. a list a script parses (#184). */
+  text_area(defval: string | InputArgs<InputOptions, string>, title?: string | InputArgs<InputOptions, string>, opts?: InputOptions): string {
+    const a = inputArgs<string, InputOptions>('text_area', defval, title, opts);
+    return registerInput<string>({ type: 'text_area', defval: a.defval, title: a.title, ...common(a.opts) }, 'input_text_area');
   },
   /**
    * Declares a colour input. As in PineScript, the default keeps an alpha of 2 decimals: an input default
    * `color.new(c, 90)` has the alpha byte 26 (25 in the script). A value given by the host is not changed.
    */
-  color(defval: string, title?: string, opts: InputOptions = {}): string {
-    return registerInput<string>({ type: 'color', defval: inputColorDefault(defval), title, ...common(opts) }, 'input_color');
+  color(defval: string | InputArgs<InputOptions, string>, title?: string | InputArgs<InputOptions, string>, opts?: InputOptions): string {
+    const a = inputArgs<string, InputOptions>('color', defval, title, opts);
+    return registerInput<string>({ type: 'color', defval: inputColorDefault(a.defval), title: a.title, ...common(a.opts) }, 'input_color');
   },
   /** Declares a source input and returns it as a Series. */
-  source(defval: string = 'close', title?: string, opts: InputOptions = {}): Series {
-    const name = registerInput<string>({ type: 'source', defval, title, ...common(opts) }, 'input_source');
+  source(defval: string | Series = 'close', title?: string | InputArgs<InputOptions, string | Series>, opts?: InputOptions): Series {
+    const a = inputArgs<string | Series, InputOptions>('source', defval, title, opts);
+    const name = registerInput<string>({ type: 'source', defval: sourceName(a.defval ?? 'close'), title: a.title, ...common(a.opts) }, 'input_source');
     return sourceSeries(name);
   },
   /** Timeframe string ("60", "1D", "W"). As in PineScript, "" means the chart timeframe. */
-  timeframe(defval: string, title?: string, opts: StringInputOptions = {}): string {
-    return registerInput<string>(
-      { type: 'timeframe', defval, title, options: opts.options, ...common(opts) },
-      'input_timeframe'
-    );
+  timeframe(defval: string | InputArgs<StringInputOptions, string>, title?: string | InputArgs<StringInputOptions, string>, opts?: StringInputOptions): string {
+    const a = inputArgs<string, StringInputOptions>('timeframe', defval, title, opts);
+    return registerInput<string>({ type: 'timeframe', defval: a.defval, title: a.title, options: a.opts.options, ...common(a.opts) }, 'input_timeframe');
   },
   /** Session string ("0930-1600", "0930-1600:23456"). */
-  session(defval: string, title?: string, opts: StringInputOptions = {}): string {
-    return registerInput<string>(
-      { type: 'session', defval, title, options: opts.options, ...common(opts) },
-      'input_session'
-    );
+  session(defval: string | InputArgs<StringInputOptions, string>, title?: string | InputArgs<StringInputOptions, string>, opts?: StringInputOptions): string {
+    const a = inputArgs<string, StringInputOptions>('session', defval, title, opts);
+    return registerInput<string>({ type: 'session', defval: a.defval, title: a.title, options: a.opts.options, ...common(a.opts) }, 'input_session');
   },
   /** Ticker id ("NASDAQ:MSFT"), for `request.security` of another symbol (#180). */
-  symbol(defval: string, title?: string, opts: StringInputOptions = {}): string {
-    return registerInput<string>({ type: 'symbol', defval, title, options: opts.options, ...common(opts) }, 'input_symbol');
+  symbol(defval: string | InputArgs<StringInputOptions, string>, title?: string | InputArgs<StringInputOptions, string>, opts?: StringInputOptions): string {
+    const a = inputArgs<string, StringInputOptions>('symbol', defval, title, opts);
+    return registerInput<string>({ type: 'symbol', defval: a.defval, title: a.title, options: a.opts.options, ...common(a.opts) }, 'input_symbol');
+  },
+  /** PineScript `input.price`: a price level, a float input (the host shows it as a number). */
+  price(defval: number | InputArgs<InputOptions, number>, title?: string | InputArgs<InputOptions, number>, opts?: InputOptions): number {
+    const a = inputArgs<number, InputOptions>('price', defval, title, opts);
+    return registerNumeric('float', a.defval, a.title, a.opts);
   },
   /** Date and time as a UNIX time in milliseconds, e.g. `input.time(timestamp('2024-01-01'), 'Start')`. */
-  time(defval: number, title?: string, opts: InputOptions = {}): number {
-    const v = registerInput<unknown>({ type: 'time', defval, title, ...common(opts) }, 'input_time');
-    return typeof v === 'number' ? v : defval;
+  time(defval: number | InputArgs<InputOptions, number>, title?: string | InputArgs<InputOptions, number>, opts?: InputOptions): number {
+    const a = inputArgs<number, InputOptions>('time', defval, title, opts);
+    const v = registerInput<unknown>({ type: 'time', defval: a.defval, title: a.title, ...common(a.opts) }, 'input_time');
+    return typeof v === 'number' ? v : a.defval;
   },
-};
+});
 
 // ── OHLCV builtins ───────────────────────────────────────────────────────────
 
@@ -755,11 +835,27 @@ export const hl2 = new Series(ctxBars, (b) => (b.high + b.low) / 2);
 export const hlc3 = new Series(ctxBars, (b) => (b.high + b.low + b.close) / 3);
 export const ohlc4 = new Series(ctxBars, (b) => (b.open + b.high + b.low + b.close) / 4);
 export const hlcc4 = new Series(ctxBars, (b) => (b.high + b.low + b.close + b.close) / 4);
+/** PineScript `bar_index`: the index of each bar (0 on the first). In a bar loop, `c.i` is the same number. */
+export const bar_index = new Series(ctxBars, (_b, i) => i);
+bar_index.fullHistory = true;
+/** PineScript `last_bar_index`: the index of the last bar, on every bar. In a bar loop, `c.n - 1`. */
+export const last_bar_index = new Series(ctxBars, (_b, _i, data) => data.length - 1);
+last_bar_index.fullHistory = true;
 // built-in price variables keep the whole history (no 5000-bar limit)
 for (const s of [hl2, hlc3, ohlc4, hlcc4]) s.fullHistory = true;
 
 const SOURCES: Record<string, Series> = { open, high, low, close, volume, hl2, hlc3, ohlc4, hlcc4 };
 
+/** The name of a source default: `input.source(close)` as `input.source("close")` (PineScript passes the series). */
+function sourceName(defval: string | Series): string {
+  if (typeof defval === 'string') return defval;
+  const name = Object.keys(SOURCES).find((k) => SOURCES[k] === defval);
+  if (!name) {
+    throw new Error('input.source(): the default must be a built-in source (open, high, low, close, volume, hl2, hlc3, ohlc4, hlcc4).');
+  }
+  return name;
+}
+
 function sourceSeries(name: string): Series {
   const builtin = SOURCES[name];
   if (builtin) return builtin;
@@ -788,9 +884,86 @@ function barsSeries(compute: (b: Bar[]) => Series): Series {
   });
 }
 
+// ── Guards for script mistakes ───────────────────────────────────────────────
+
+/** Edit distance of two names (for the "did you mean" of a namespace). */
+function editDistance(a: string, b: string): number {
+  const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    let diag = row[0]!;
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const up = row[j]!;
+      row[j] = Math.min(up + 1, row[j - 1]! + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+      diag = up;
+    }
+  }
+  return row[b.length]!;
+}
+
+/** Names a tool reads to probe an object (promise, JSON, test matchers, module interop): never an error. */
+const PROBED_NAMES = new Set(['then', 'toJSON', 'asymmetricMatch', 'nodeType', 'tagName', 'inspect', 'default']);
+
+/**
+ * A namespace whose unknown members throw instead of being `undefined`: `ta.smaa(close, 5)` fails with
+ * "ta.smaa does not exist. Did you mean ta.sma?" rather than "ta.smaa is not a function", and `color.purpel`
+ * fails where it is read rather than giving a plot with no colour.
+ */
+function strictNamespace<T extends object>(name: string, members: T): T {
+  return new Proxy(members, {
+    get(target, prop, receiver) {
+      if (typeof prop === 'symbol' || prop in target || PROBED_NAMES.has(prop) || /^[_$@]/.test(prop)) {
+        return Reflect.get(target, prop, receiver);
+      }
+      const keys = Object.keys(target);
+      const lower = prop.toLowerCase();
+      const ranked = keys
+        .map((k) => ({ k, d: editDistance(lower, k.toLowerCase()) }))
+        .filter(({ k, d }) => {
+          const key = k.toLowerCase();
+          return d <= Math.max(1, Math.floor(prop.length / 3)) || key.includes(lower) || (key.length >= 3 && lower.includes(key));
+        })
+        .sort((x, y) => x.d - y.d)
+        .slice(0, 3)
+        .map(({ k }) => `${name}.${k}`);
+      throw new TypeError(
+        `${name}.${prop} does not exist.` + (ranked.length ? ` Did you mean ${ranked.join(', ')}?` : '') +
+          ' See docs/inventory.md for the supported functions.'
+      );
+    },
+  });
+}
+
+/**
+ * The ta.* functions compute a whole Series in one call. Called inside an eachBar() callback, a call runs again on
+ * every bar (slow) and returns a Series, not the value of the bar, and it has no per-bar history: the call throws
+ * with the fix.
+ */
+function outsideBarLoops<T extends Record<string, unknown>>(members: T): T {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(members)) {
+    if (typeof value !== 'function') {
+      out[key] = value;
+      continue;
+    }
+    const fn = value as (...args: unknown[]) => unknown;
+    out[key] = function (this: unknown, ...args: unknown[]) {
+      if (currentBar >= 0) {
+        throw new Error(
+          `ta.${key}() was called inside eachBar(): a ta.* call computes the whole Series at once. ` +
+            `Compute it before the loop (const x = ta.${key}(...)) and read the bar's value with c.get(x). ` +
+            'For a Pine ta.* call inside an if block or a for loop, use the callsite.* call sites.'
+        );
+      }
+      return fn.apply(this, args);
+    };
+  }
+  return out as T;
+}
+
 /** ta.* with the chart-implicit (bars-first) functions bound to the context,
  *  so scripts call them like PineScript: `ta.tr(true)`, `ta.atr(14)`. */
-export const ta = {
+export const ta = strictNamespace('ta', outsideBarLoops({
   ...taSeries,
   tr: (handleNa: boolean = false): Series => taSeries.tr(bars(), handleNa),
   atr: (length: number): Series => taSeries.atr(bars(), length),
@@ -838,6 +1011,8 @@ export const ta = {
     (source: Series, anchor?: Series): Series;
     (source: Series, anchor: Series | undefined, stdev_mult: number): [Series, Series, Series];
   },
+  /** `ta.vwma(source, length)` with the chart volume, as PineScript; a third argument gives another volume. */
+  vwma: (source: Series, length: number, vol?: Series): Series => taSeries.vwma(source, length, vol ?? volume),
   /** `ta.mfi(source, length)` with the chart volume (PineScript takes 2 arguments). */
   mfi: (source: Series, length: number): Series => taSeries.mfi(source, length, volume),
   /** `ta.pivothigh(source, leftbars, rightbars)` or `ta.pivothigh(leftbars, rightbars)` (source = high).
@@ -860,7 +1035,7 @@ export const ta = {
   iii: barsSeries(taSeries.iii),
   wad: barsSeries(taSeries.wad),
   wvad: barsSeries(taSeries.wvad),
-};
+}));
 
 /** PineScript `fixnan(source)`: each `na` value becomes the previous non-`na` value.
  *  Accepts a Series or a per-bar color array (`undefined` = `na`, as returned by `color.when`). */
@@ -903,15 +1078,17 @@ function colorWhen(cond: Series, colorTrue: string, colorFalse?: string): Array<
 }
 
 /** color.* plus `when` — per-bar conditional colors for plot()/fill()/bgcolor()/barcolor(). */
-export const color = {
+export const color = strictNamespace('color', {
   ...colorCore,
   new: colorCore.new_color,
   when: colorWhen,
-};
+});
 
 // ── Drawing declarations ─────────────────────────────────────────────────────
 
 export interface ScriptPlotOptions {
+  /** Shift in bars (PineScript `offset`): the value of bar i is drawn on bar i + offset (negative: to the left). */
+  offset?: number;
   /** Static color, or a per-bar color array from color.when(). */
   color?: string | string[];
   linewidth?: number;
@@ -968,10 +1145,14 @@ function plotImpl(series: Series, title: string = DEFAULT_OUTPUT_TITLES.plot, op
   const values = series.toArray();
   const b = bars();
   const data: TimeValue[] = [];
-  for (let i = 0; i < b.length; i++) {
+  // offset (PineScript plot(offset = k)): the value and colour of bar i are drawn on bar i + k; bars past the
+  // chart's first or last bar are dropped
+  const off = Math.trunc(options.offset ?? 0);
+  for (let j = Math.max(0, off); j < b.length && j - off < b.length; j++) {
+    const i = j - off;
     const value = values[i];
     if (value === undefined || !Number.isFinite(value)) continue; // PineScript plots +/-Infinity as na
-    data.push(perBar ? { time: b[i]!.time, value, color: perBar[i] } : { time: b[i]!.time, value });
+    data.push(perBar ? { time: b[j]!.time, value, color: perBar[i] } : { time: b[j]!.time, value });
   }
   c.plots[id] = data;
   return { id, kind: 'plot' };
@@ -2316,7 +2497,8 @@ export const weekofyear = calendar(timeCore.weekofyear);
 /** PineScript `dayofmonth(time, timezone?)`; the default time zone is the exchange time zone. */
 export const dayofmonth = calendar(timeCore.dayofmonth);
 /** PineScript `dayofweek(time, timezone?)`; the default time zone is the exchange time zone. */
-export const dayofweek = calendar(timeCore.dayofweek);
+/** `dayofweek(time, timezone?)`, with the PineScript constants `dayofweek.sunday` (1) ... `dayofweek.saturday` (7). */
+export const dayofweek = Object.assign(calendar(timeCore.dayofweek), pineConstants.daysOfWeek);
 /** PineScript `hour(time, timezone?)`; the default time zone is the exchange time zone. */
 export const hour = calendar(timeCore.hour);
 /** PineScript `minute(time, timezone?)`; the default time zone is the exchange time zone. */
@@ -2355,7 +2537,7 @@ export function inSession(time: number, session: string, timezone?: string): boo
 }
 
 /** PineScript `str.*`; `format_time` and the dates of `format` use the exchange time zone by default. */
-export const str = {
+export const str = strictNamespace('str', {
   ...strCore,
   // format.mintick uses the chart symbol's tick and price scale (syminfo.mintick, syminfo.pricescale)
   tostring: ((value: unknown, format?: string, mintick?: number, pricescale?: number) =>
@@ -2368,7 +2550,7 @@ export const str = {
   format(pattern: string, ...args: unknown[]): string {
     return formatMessage(pattern, args, exchangeTimezone);
   },
-};
+});
 
 // ── Session values (issue #100) ──────────────────────────────────────────────
 
@@ -2811,60 +2993,249 @@ function security_lower_tf<T extends SecurityValue>(
 }
 
 /** PineScript `request.*`: `security` (issue #101, other symbols #179, lower timeframes #181) and `security_lower_tf`. */
-export const request = { security, security_lower_tf };
+/** PineScript parameters of `request.security` / `request.security_lower_tf`, in their positional order. */
+const SECURITY_PARAMETERS = ['symbol', 'timeframe', 'expression', 'gaps', 'lookahead', 'ignore_invalid_symbol', 'currency', 'calc_bars_count'] as const;
+const SECURITY_LOWER_TF_PARAMETERS = ['symbol', 'timeframe', 'expression', 'ignore_invalid_symbol', 'currency', 'ignore_invalid_timeframe', 'calc_bars_count'] as const;
+
+/** Named arguments of `request.security` (PineScript names). */
+export interface SecurityArgs<T extends SecurityValue = SecurityValue> {
+  symbol?: string;
+  timeframe?: string;
+  expression?: () => T;
+  gaps?: string;
+  lookahead?: string;
+  ignore_invalid_symbol?: boolean;
+  currency?: string;
+  calc_bars_count?: number;
+}
+
+/** Named arguments of `request.security_lower_tf` (PineScript names). */
+export interface SecurityLowerTfArgs<T extends SecurityValue = SecurityValue> {
+  symbol?: string;
+  timeframe?: string;
+  expression?: () => T;
+  ignore_invalid_symbol?: boolean;
+  currency?: string;
+  ignore_invalid_timeframe?: boolean;
+  calc_bars_count?: number;
+}
+
+/** `currency` and `calc_bars_count` change the values in PineScript: they throw instead of being ignored. */
+function unsupportedSecurityArgs(name: string, currency: unknown, calcBarsCount: unknown): void {
+  if (currency !== undefined && currency !== '' && currency !== 'NONE') {
+    throw new Error(`${name}(): the currency argument (conversion of the values) is not supported.`);
+  }
+  if (calcBarsCount !== undefined) throw new Error(`${name}(): the calc_bars_count argument is not supported.`);
+}
+
+/** `request.security` with PineScript's named arguments: `request.security(sym, "D", () => close, { lookahead: barmerge.lookahead_on })`. */
+function securityCall<T extends SecurityValue>(
+  ...args:
+    | [symbol: string, timeframe: string, expression: () => T, gaps?: string, lookahead?: string, ignore_invalid_symbol?: boolean]
+    | [symbol: string, timeframe: string, expression: () => T, args: SecurityArgs<T>]
+    | [args: SecurityArgs<T> & { symbol: string; timeframe: string; expression: () => T }]
+): T extends unknown[] ? Series[] : Series {
+  const a = namedArguments('request.security', SECURITY_PARAMETERS, args);
+  unsupportedSecurityArgs('request.security', a[6], a[7]);
+  return security(a[0] as string, a[1] as string, a[2] as () => T, a[3] as string | undefined, a[4] as string | undefined, a[5] as boolean | undefined);
+}
+
+/** `request.security_lower_tf` with PineScript's named arguments. */
+function securityLowerTfCall<T extends SecurityValue>(
+  ...args:
+    | [symbol: string, timeframe: string, expression: () => T, ignore_invalid_symbol?: boolean]
+    | [symbol: string, timeframe: string, expression: () => T, args: SecurityLowerTfArgs<T>]
+    | [args: SecurityLowerTfArgs<T> & { symbol: string; timeframe: string; expression: () => T }]
+): T extends unknown[] ? number[][][] : number[][] {
+  const a = namedArguments('request.security_lower_tf', SECURITY_LOWER_TF_PARAMETERS, args);
+  unsupportedSecurityArgs('request.security_lower_tf', a[4], a[6]);
+  if (a[5] !== undefined && a[5] !== false) throw new Error('request.security_lower_tf(): the ignore_invalid_timeframe argument is not supported.');
+  return security_lower_tf(a[0] as string, a[1] as string, a[2] as () => T, a[3] as boolean | undefined);
+}
+
+export const request = strictNamespace('request', { security: securityCall, security_lower_tf: securityLowerTfCall });
 
 // ── Drawing objects ──────────────────────────────────────────────────────────
 // The drawing namespaces come from this bundle so that they share the registry that
 // executeScript() resets. `line.all` etc. are read like PineScript variables.
 
 /** PineScript `line.*`; `line.all` lists the live lines in creation order. */
-export const line = {
-  ...lineCore,
-  get all() {
-    return lineCore.all();
-  },
+// ── Drawing namespaces (named arguments, Series arguments in bar loops) ──────
+
+type Numeric = number | Series;
+/** A function whose number parameters also take a Series (read on the current bar inside a bar loop). */
+type WithSeries<F> = F extends (...args: infer A) => infer R
+  ? (...args: { [K in keyof A]: number extends A[K] ? A[K] | Series : A[K] }) => R
+  : never;
+type ScriptDrawing<T> = { [K in keyof T]: T[K] extends (...args: never[]) => unknown ? T[K] & WithSeries<T[K]> : T[K] };
+type Colour = string | undefined;
+
+/** Named arguments of `label.new` (PineScript parameter names). */
+export interface LabelNewArgs {
+  x?: Numeric;
+  y?: Numeric;
+  point?: ChartPoint;
+  text?: string;
+  xloc?: 'bar_index' | 'bar_time';
+  yloc?: 'price' | 'abovebar' | 'belowbar';
+  color?: Colour;
+  style?: NonNullable<Label['style']>;
+  textcolor?: Colour;
+  size?: string | number;
+  textalign?: 'left' | 'center' | 'right';
+  tooltip?: string;
+  text_font_family?: 'default' | 'monospace';
+  force_overlay?: boolean;
+  text_formatting?: number;
+}
+
+/** Named arguments of `line.new`. */
+export interface LineNewArgs {
+  x1?: Numeric;
+  y1?: Numeric;
+  x2?: Numeric;
+  y2?: Numeric;
+  first_point?: ChartPoint;
+  second_point?: ChartPoint;
+  xloc?: 'bar_index' | 'bar_time';
+  extend?: 'none' | 'left' | 'right' | 'both';
+  color?: Colour;
+  style?: 'solid' | 'dotted' | 'dashed' | 'arrow_left' | 'arrow_right' | 'arrow_both';
+  width?: Numeric;
+  force_overlay?: boolean;
+}
+
+/** Named arguments of `box.new`. */
+export interface BoxNewArgs {
+  left?: Numeric;
+  top?: Numeric;
+  right?: Numeric;
+  bottom?: Numeric;
+  top_left?: ChartPoint;
+  bottom_right?: ChartPoint;
+  border_color?: Colour;
+  border_width?: Numeric;
+  border_style?: 'solid' | 'dotted' | 'dashed';
+  extend?: 'none' | 'left' | 'right' | 'both';
+  xloc?: 'bar_index' | 'bar_time';
+  bgcolor?: Colour;
+  text?: string;
+  text_size?: string | number;
+  text_color?: Colour;
+  text_halign?: 'left' | 'center' | 'right';
+  text_valign?: 'top' | 'center' | 'bottom';
+  text_wrap?: 'none' | 'auto';
+  text_font_family?: 'default' | 'monospace';
+  force_overlay?: boolean;
+  text_formatting?: number;
+}
+
+/** Named arguments of `table.new`. */
+export interface TableNewArgs {
+  position?: string;
+  columns?: number;
+  rows?: number;
+  bgcolor?: Colour;
+  frame_color?: Colour;
+  frame_width?: number;
+  border_color?: Colour;
+  border_width?: number;
+  force_overlay?: boolean;
+}
+
+/** Named arguments of `table.cell`. */
+export interface TableCellArgs {
+  table_id?: Table;
+  column?: number;
+  row?: number;
+  text?: string;
+  width?: number;
+  height?: number;
+  text_color?: Colour;
+  text_halign?: 'left' | 'center' | 'right';
+  text_valign?: 'top' | 'center' | 'bottom';
+  text_size?: string | number;
+  bgcolor?: Colour;
+  tooltip?: string;
+  text_font_family?: 'default' | 'monospace';
+  text_formatting?: number;
+}
+
+/** Named arguments of `polyline.new`. */
+export interface PolylineNewArgs {
+  points?: ChartPoint[];
+  curved?: boolean;
+  closed?: boolean;
+  xloc?: 'bar_index' | 'bar_time';
+  line_color?: Colour;
+  fill_color?: Colour | null;
+  line_style?: 'solid' | 'dotted' | 'dashed';
+  line_width?: number;
+  force_overlay?: boolean;
+}
+
+/** Named arguments of `linefill.new`. */
+export interface LinefillNewArgs {
+  line1?: Line;
+  line2?: Line;
+  color?: Colour;
+}
+
+const loopBar = (): number => currentBar;
+
+/** Wraps a drawing namespace and keeps its `all` getter (the live drawings in creation order). */
+function drawings<T extends Record<string, unknown>, D>(name: string, members: T, all: () => D[]) {
+  const out = drawingNamespace(name, members, loopBar) as ScriptDrawing<T>;
+  return Object.defineProperty(out, 'all', { get: all, enumerable: true }) as Omit<ScriptDrawing<T>, 'all'> & { readonly all: D[] };
+}
+
+const lineNs = drawings('line', { ...lineCore, ...pineConstants.lineStyles }, () => lineCore.all());
+/** PineScript `line.*` (with `line.style_*`); `line.all` lists the live lines in creation order. */
+export const line = lineNs as typeof lineNs & {
+  new: ((args: LineNewArgs) => Line) &
+    ((x1: Numeric, y1: Numeric, x2: Numeric, y2: Numeric, args: LineNewArgs) => Line) &
+    ((first_point: ChartPoint, second_point: ChartPoint, args: LineNewArgs) => Line);
 };
 
-/** PineScript `label.*`; `label.all` lists the live labels in creation order. */
-export const label = {
-  ...labelCore,
-  get all() {
-    return labelCore.all();
-  },
+const labelNs = drawings('label', { ...labelCore, ...pineConstants.labelStyles }, () => labelCore.all());
+/** PineScript `label.*` (with `label.style_*`); `label.all` lists the live labels in creation order. */
+export const label = labelNs as typeof labelNs & {
+  new: ((args: LabelNewArgs) => Label) &
+    ((x: Numeric, y: Numeric, args: LabelNewArgs) => Label) &
+    ((x: Numeric, y: Numeric, text: string, args: LabelNewArgs) => Label) &
+    ((point: ChartPoint, args: LabelNewArgs) => Label) &
+    ((point: ChartPoint, text: string, args: LabelNewArgs) => Label);
 };
 
+const boxNs = drawings('box', { ...boxCore }, () => boxCore.all());
 /** PineScript `box.*`; `box.all` lists the live boxes in creation order. */
-export const box = {
-  ...boxCore,
-  get all() {
-    return boxCore.all();
-  },
+export const box = boxNs as typeof boxNs & {
+  new: ((args: BoxNewArgs) => Box) &
+    ((left: Numeric, top: Numeric, right: Numeric, bottom: Numeric, args: BoxNewArgs) => Box) &
+    ((top_left: ChartPoint, bottom_right: ChartPoint, args: BoxNewArgs) => Box);
 };
 
+const linefillNs = drawings('linefill', { ...linefillCore }, () => linefillCore.all());
 /** PineScript `linefill.*`; `linefill.all` lists the live linefills in creation order. */
-export const linefill = {
-  ...linefillCore,
-  get all() {
-    return linefillCore.all();
-  },
+export const linefill = linefillNs as typeof linefillNs & {
+  new: ((args: LinefillNewArgs) => Linefill) & ((line1: Line, line2: Line, args: LinefillNewArgs) => Linefill);
 };
 
+const polylineNs = drawings('polyline', { ...polylineCore }, () => polylineCore.all());
 /** PineScript `polyline.*`; `polyline.all` lists the live polylines in creation order. */
-export const polyline = {
-  ...polylineCore,
-  get all() {
-    return polylineCore.all();
-  },
+export const polyline = polylineNs as typeof polylineNs & {
+  new: ((args: PolylineNewArgs) => Polyline) & ((points: ChartPoint[], args: PolylineNewArgs) => Polyline);
 };
 
+const tableNs = drawings('table', { ...tableCore }, () => tableCore.all());
 /**
  * PineScript `table.*`; `table.all` lists the live tables in creation order. The live tables go to `result.tables`.
  */
-export const table = {
-  ...tableCore,
-  get all() {
-    return tableCore.all();
-  },
+export const table = tableNs as typeof tableNs & {
+  new: ((args: TableNewArgs) => Table) & ((position: string, columns: number, rows: number, args: TableNewArgs) => Table);
+  cell: ((args: TableCellArgs) => void) &
+    ((table_id: Table, column: number, row: number, args: TableCellArgs) => void) &
+    ((table_id: Table, column: number, row: number, text: string, args: TableCellArgs) => void);
 };
 
 /** PineScript `position.*` constants (table positions). */
@@ -2873,6 +3244,11 @@ export { position };
 /** PineScript `text.format_*`, `text.align_*` and `text.wrap_*` constants. */
 export const text = { ...textCore };
 
+/** PineScript constant namespaces (`shape.triangleup`, `size.small`, `xloc.bar_time`, `extend.right`...): the strings
+ *  the functions take. */
+export const { shape, location, size, xloc, yloc, extend, display, format, font, scale, order, currency, adjustment } =
+  pineConstants;
+
 /**
  * PineScript `chart.point.*`. `chart.point.now(price?)` is the point of the current bar
  * (index, time, and `price`, default the close), so it runs inside eachBar().
@@ -2984,13 +3360,13 @@ export type {
 const { saveRandom: _saveRandom, restoreRandom: _restoreRandom, ...mathScript } = mathCore;
 void _saveRandom;
 void _restoreRandom;
-export const math = {
+export const math = strictNamespace('math', {
   ...mathScript,
   round_to_mintick: ((number: number | Series, mintick?: number) => {
     const tick = mintick ?? syminfo.mintick;
     return number instanceof Series ? mathCore.round_to_mintick(number, tick) : mathCore.round_to_mintick(number, tick);
   }) as typeof mathCore.round_to_mintick,
-};
+});
 export * as compare from '../compare/index.js';
 export { isInputActive } from '../runtime/input-active.js';
 export type {