hyperprop-charting-library 0.1.131 → 0.1.133

package/docs/API.md

@@ -543,3 +543,82 @@ Use `getDrawings()` / `setDrawings()` for persistence.
 - `setIndicators(indicators: IndicatorInstanceOptions[]): void`
 - `resize(width?: number, height?: number): void`
 - `destroy(): void`
+
+---
+
+## Script Indicators (user-authored)
+
+`compileScriptIndicator(definition: ScriptIndicatorDefinition): IndicatorPlugin` — compiles a
+user-authored "Hyperprop Script" into a regular indicator plugin. Register the result with
+`chart.registerIndicator(...)` and add it with `chart.addIndicator(definition.id)`. Separate-pane
+scripts automatically get the shared grid, legend, live values, value lines, drag-resize and the
+hover controls (eye / gear / source / delete). Overlay scripts participate in price autoscale.
+
+```ts
+import { createChart, compileScriptIndicator } from "hyperprop-charting-library";
+
+const plugin = compileScriptIndicator({
+  id: "script:my-rsi",
+  name: "My RSI",
+  pane: "separate", // or "overlay"
+  inputs: [
+    { key: "length", label: "Length", type: "number", default: 14 },
+    { key: "color", label: "Color", type: "color", default: "#ab47bc" }
+  ],
+  source: `
+function compute(bars, inputs, hp) {
+  const closes = bars.map(b => b.c);
+  const gains = closes.map((c, i) => i === 0 ? null : Math.max(0, c - closes[i - 1]));
+  const losses = closes.map((c, i) => i === 0 ? null : Math.max(0, closes[i - 1] - c));
+  const avgGain = hp.rma(gains, inputs.length);
+  const avgLoss = hp.rma(losses, inputs.length);
+  const rsi = avgGain.map((g, i) => {
+    const l = avgLoss[i];
+    if (g == null || l == null) return null;
+    return l === 0 ? 100 : 100 - 100 / (1 + g / l);
+  });
+  return {
+    plots: [{ title: "RSI", values: rsi, color: inputs.color }],
+    range: { min: 0, max: 100 },
+    guides: [30, 70]
+  };
+}`
+});
+
+chart.registerIndicator(plugin);
+chart.addIndicator("script:my-rsi");
+```
+
+Script contract:
+
+- The source must define `function compute(bars, inputs, hp)`.
+- `bars`: `Array<{ time: Date, o, h, l, c, v? }>` — the full series.
+- `inputs`: resolved input values (defaults merged with per-instance overrides). `showValueLine`
+  is injected automatically and honored by separate panes.
+- `hp`: TA helpers, all `(values: Array<number|null>, length) => Array<number|null>` unless noted:
+  `sma`, `ema`, `rma`, `highest`, `lowest`, `stdev`, `change(values, length = 1)`,
+  `atr(bars, length)`.
+- Return `{ plots, range?, guides?, decimals? }`:
+  - `plots`: `Array<{ title?, values, color?, width?, style?: "line" | "histogram", negativeColor? }>`
+  - `range`: `{ min?, max? }` fixes the pane scale (e.g. `0..100` for oscillators).
+  - `guides`: dashed horizontal guide levels (e.g. `[30, 70]`).
+  - `decimals`: axis/legend decimal places.
+
+Errors never break the chart: compile or runtime errors render as an inline red message in the
+pane. Scripts are plain JavaScript executed in the page context — treat them like any other code
+you'd paste into your app (only run scripts you trust).
+
+### Execution budget
+
+Loop conditions are instrumented at compile time, and each `compute()` invocation gets a
+1000 ms wall-clock budget. A script that exceeds it (e.g. `while (true) {}`) throws
+`"Script exceeded the 1000ms execution budget"`, which renders as the usual inline pane error
+instead of freezing the tab. After a budget trip the script is circuit-broken — it is not run
+again for that compiled instance, so live ticks don't re-trigger the stall. Recompiling (editing
+the source and calling `compileScriptIndicator` again) resets the breaker. String/template/comment
+contents are never instrumented; `for...of` / `for...in` loops are left untouched.
+
+`validateScriptSource(source: string): string | null` — compile-checks a script without
+registering it, returning an error message or `null`. It runs under the same execution budget, so
+validating a script with a top-level infinite loop returns a budget error instead of hanging the
+caller. Use this for editor save-validation instead of running `new Function` yourself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperprop-charting-library",
-  "version": "0.1.131",
+  "version": "0.1.133",
   "description": "Lightweight TypeScript charting core",
   "type": "module",
   "main": "./dist/hyperprop-charting-library.cjs",