hyperprop-charting-library 0.1.136 → 0.1.137

package/dist/index.js

@@ -2121,6 +2121,82 @@ var hashScriptSource = (source) => {
   }
   return (hash >>> 0).toString(36);
 };
+var SCRIPT_SOURCE_INPUT_VALUES = ["open", "high", "low", "close", "hl2", "hlc3", "ohlc4"];
+var slugifyInputLabel = (label) => {
+  const slug = String(label).trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return slug || "input";
+};
+var createScriptInputHelper = (values, registry) => {
+  const usedKeys = /* @__PURE__ */ new Set();
+  const resolveKey = (label, options) => {
+    let key = options?.key ?? slugifyInputLabel(label);
+    if (usedKeys.has(key)) {
+      let suffix = 2;
+      while (usedKeys.has(`${key}_${suffix}`)) suffix += 1;
+      key = `${key}_${suffix}`;
+    }
+    usedKeys.add(key);
+    return key;
+  };
+  const resolve = (key, fallback, coerce) => {
+    if (!values) return fallback;
+    const raw = values[key];
+    if (raw === void 0 || raw === null) return fallback;
+    const coerced = coerce(raw);
+    return coerced === void 0 ? fallback : coerced;
+  };
+  const coerceNumber = (raw) => {
+    const num = typeof raw === "number" ? raw : Number(raw);
+    return Number.isFinite(num) ? num : void 0;
+  };
+  const numberInput = (integer) => (label, defaultValue, options) => {
+    const key = resolveKey(label, options);
+    registry?.push({
+      key,
+      label,
+      type: "number",
+      default: defaultValue,
+      ...options?.min !== void 0 ? { min: options.min } : {},
+      ...options?.max !== void 0 ? { max: options.max } : {},
+      ...options?.step !== void 0 ? { step: options.step } : integer ? { step: 1 } : {}
+    });
+    const value = resolve(key, defaultValue, coerceNumber);
+    return integer ? Math.round(value) : value;
+  };
+  const selectInput = (label, defaultValue, choices, options) => {
+    const key = resolveKey(label, options);
+    const normalized = (Array.isArray(choices) ? choices : []).map(
+      (choice) => typeof choice === "string" ? { value: choice, label: choice } : { value: String(choice.value), label: String(choice.label ?? choice.value) }
+    );
+    registry?.push({ key, label, type: "select", default: defaultValue, options: normalized });
+    return resolve(key, defaultValue, (raw) => typeof raw === "string" ? raw : String(raw));
+  };
+  return Object.freeze({
+    int: numberInput(true),
+    float: numberInput(false),
+    bool: (label, defaultValue = false, options) => {
+      const key = resolveKey(label, options);
+      registry?.push({ key, label, type: "boolean", default: defaultValue });
+      return resolve(
+        key,
+        defaultValue,
+        (raw) => typeof raw === "boolean" ? raw : raw === "true" ? true : raw === "false" ? false : void 0
+      );
+    },
+    color: (label, defaultValue, options) => {
+      const key = resolveKey(label, options);
+      registry?.push({ key, label, type: "color", default: defaultValue });
+      return resolve(key, defaultValue, (raw) => typeof raw === "string" ? raw : void 0);
+    },
+    string: (label, defaultValue = "", options) => {
+      const key = resolveKey(label, options);
+      registry?.push({ key, label, type: "string", default: defaultValue });
+      return resolve(key, defaultValue, (raw) => typeof raw === "string" ? raw : String(raw));
+    },
+    select: selectInput,
+    source: (label = "Source", defaultValue = "close", options) => selectInput(label, defaultValue, SCRIPT_SOURCE_INPUT_VALUES, options)
+  });
+};
 var SCRIPT_GUARD_BUDGET_MS = 1e3;
 var ScriptBudgetError = class extends Error {
   constructor() {
@@ -2395,31 +2471,34 @@ var injectLoopGuards = (source, guardName) => {
   }
   return out;
 };
-var compileScriptCompute = (source, guard) => {
+var compileScriptFactory = (source) => {
   const makeFactory = (body) => new Function(
     "__hpGuard",
+    "input",
     `"use strict";
 ${body}
 ;if (typeof compute !== "function") { throw new Error("Script must define function compute(bars, inputs, hp)"); }
 return compute;`
   );
-  let factory;
   try {
-    factory = makeFactory(injectLoopGuards(source, "__hpGuard"));
+    return makeFactory(injectLoopGuards(source, "__hpGuard"));
   } catch {
-    factory = makeFactory(source);
+    return makeFactory(source);
   }
-  guard.reset();
-  return factory(guard);
 };
-var validateScriptSource = (source) => {
+var extractScriptInputs = (source) => {
+  const registry = [];
   try {
-    compileScriptCompute(source, createScriptGuard());
-    return null;
+    const factory = compileScriptFactory(source);
+    const guard = createScriptGuard();
+    guard.reset();
+    factory(guard, createScriptInputHelper(null, registry));
+    return { inputs: registry, error: null };
   } catch (error) {
-    return error instanceof Error ? error.message : String(error);
+    return { inputs: registry, error: error instanceof Error ? error.message : String(error) };
   }
 };
+var validateScriptSource = (source) => extractScriptInputs(source).error;
 var drawScriptError = (ctx, renderContext, name, message) => {
   ctx.save();
   ctx.font = "11px -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif";
@@ -2436,18 +2515,24 @@ var compileScriptIndicator = (definition) => {
   for (const input of definition.inputs ?? []) {
     defaultInputs[input.key] = input.default;
   }
-  let compiled = null;
+  let factory = null;
   let compileError = null;
   const guard = createScriptGuard();
   try {
-    compiled = compileScriptCompute(definition.source, guard);
+    factory = compileScriptFactory(definition.source);
+    const declared = [];
+    guard.reset();
+    factory(guard, createScriptInputHelper(null, declared));
+    for (const input of declared) {
+      defaultInputs[input.key] = input.default;
+    }
   } catch (error) {
     compileError = error instanceof Error ? error.message : String(error);
   }
   const sourceKey = hashScriptSource(definition.source);
   let trippedError = null;
   const runCompute = (data, inputs) => {
-    if (!compiled) {
+    if (!factory || compileError) {
       return { error: compileError ?? "Script failed to compile" };
     }
     if (trippedError) {
@@ -2455,6 +2540,7 @@ var compileScriptIndicator = (definition) => {
     }
     try {
       guard.reset();
+      const compiled = factory(guard, createScriptInputHelper(inputs, null));
       const result = compiled(data, inputs, SCRIPT_HELPERS);
       if (!result || !Array.isArray(result.plots)) {
         return { error: "compute() must return { plots: [...] }" };
@@ -2949,6 +3035,24 @@ function createChart(element, options = {}) {
   let drawingDoubleClickHandler = null;
   let drawingEditTextHandler = null;
   let magnetMode = "none";
+  let priceScaleMode = "linear";
+  let priceScaleInverted = false;
+  const PRICE_SCALE_LOG_FLOOR = 1e-9;
+  const priceScaleTransform = (price) => priceScaleMode === "log" ? Math.log10(Math.max(PRICE_SCALE_LOG_FLOOR, price)) : price;
+  const priceScaleUntransform = (value) => priceScaleMode === "log" ? Math.pow(10, value) : value;
+  const percentBaselineForXStart = (xStartValue) => {
+    if (priceScaleMode !== "percent") return null;
+    const bar = data[clamp(Math.round(xStartValue), 0, Math.max(0, data.length - 1))];
+    return bar && bar.c > 0 ? bar.c : null;
+  };
+  const formatPriceForScale = (price, percentBaseline) => {
+    if (percentBaseline !== null) {
+      const pct = (price / percentBaseline - 1) * 100;
+      const rounded = Math.abs(pct) < 5e-3 ? 0 : pct;
+      return `${rounded > 0 ? "+" : ""}${rounded.toFixed(2)}%`;
+    }
+    return formatPrice(price);
+  };
   let magnetModifierActive = false;
   let shiftKeyActive = false;
   const MAGNET_WEAK_THRESHOLD_PX = 16;
@@ -4282,9 +4386,14 @@ function createChart(element, options = {}) {
       yMax
     };
     plotBottomForHit = fullChartBottom;
+    const scaledYMin = priceScaleTransform(yMin);
+    const scaledYRange = priceScaleTransform(yMax) - scaledYMin || 1;
     const yFromPrice = (price) => {
-      return chartBottom - (price - yMin) / yRange * chartHeight;
+      const ratio = (priceScaleTransform(price) - scaledYMin) / scaledYRange;
+      return priceScaleInverted ? chartTop + ratio * chartHeight : chartBottom - ratio * chartHeight;
     };
+    const percentBaseline = percentBaselineForXStart(xStart);
+    const formatAxisPrice = (price) => formatPriceForScale(price, percentBaseline);
     const xFromDrawingPoint = (point) => chartLeft + (point.index + 0.5 - xStart) / xSpan * chartWidth;
     const FIB_RATIOS = [0, 0.236, 0.382, 0.5, 0.618, 0.786, 1, 1.618];
     const FIB_EXT_RATIOS = [0, 0.382, 0.5, 0.618, 1, 1.272, 1.618, 2.618];
@@ -5191,19 +5300,40 @@ function createChart(element, options = {}) {
     const yTicks = Math.max(1, Math.floor(yTickCountInput));
     const gridColor = grid.color ?? mergedOptions.gridColor;
     const priceTicks = [];
-    {
-      const targetStep = yRange / Math.max(1, yTicks);
-      let step;
-      if (targetStep > 0 && Number.isFinite(targetStep)) {
-        const base = Math.pow(10, Math.floor(Math.log10(targetStep)));
-        const frac = targetStep / base;
-        step = (frac <= 1 ? 1 : frac <= 2 ? 2 : frac <= 2.5 ? 2.5 : frac <= 5 ? 5 : 10) * base;
-        const instrumentTick = getConfiguredTickSize();
-        if (instrumentTick > 0 && step < instrumentTick * 1e6) {
-          step = Math.max(instrumentTick, Math.round(step / instrumentTick) * instrumentTick);
+    const pickNiceStep = (targetStep) => {
+      if (!(targetStep > 0) || !Number.isFinite(targetStep)) return 1;
+      const base = Math.pow(10, Math.floor(Math.log10(targetStep)));
+      const frac = targetStep / base;
+      return (frac <= 1 ? 1 : frac <= 2 ? 2 : frac <= 2.5 ? 2.5 : frac <= 5 ? 5 : 10) * base;
+    };
+    if (percentBaseline !== null) {
+      const pctMin = (yMin / percentBaseline - 1) * 100;
+      const pctMax = (yMax / percentBaseline - 1) * 100;
+      const step = pickNiceStep((pctMax - pctMin) / Math.max(1, yTicks));
+      const firstTick = Math.ceil(pctMin / step) * step;
+      for (let i = 0; ; i += 1) {
+        const pct = firstTick + i * step;
+        if (pct > pctMax + step * 1e-6) break;
+        priceTicks.push(percentBaseline * (1 + pct / 100));
+        if (priceTicks.length > 200) break;
+      }
+    } else if (priceScaleMode === "log" && yMin > 0 && yMax / yMin > 4) {
+      const mantissas = Math.log10(yMax / yMin) > 8 ? [1] : [1, 2, 5];
+      const firstDecade = Math.floor(Math.log10(Math.max(PRICE_SCALE_LOG_FLOOR, yMin)));
+      const lastDecade = Math.ceil(Math.log10(yMax));
+      for (let decade = firstDecade; decade <= lastDecade; decade += 1) {
+        for (const mantissa of mantissas) {
+          const price = mantissa * Math.pow(10, decade);
+          if (price >= yMin && price <= yMax) priceTicks.push(price);
+          if (priceTicks.length > 200) break;
         }
-      } else {
-        step = 1;
+      }
+    } else {
+      const targetStep = yRange / Math.max(1, yTicks);
+      let step = pickNiceStep(targetStep);
+      const instrumentTick = getConfiguredTickSize();
+      if (targetStep > 0 && Number.isFinite(targetStep) && instrumentTick > 0 && step < instrumentTick * 1e6) {
+        step = Math.max(instrumentTick, Math.round(step / instrumentTick) * instrumentTick);
       }
       const firstTick = Math.ceil(yMin / step) * step;
       for (let i = 0; ; i += 1) {
@@ -5966,7 +6096,7 @@ function createChart(element, options = {}) {
       ctx.font = `${yAxisFontSize}px ${mergedOptions.fontFamily}`;
       for (const price of priceTicks) {
         const y = clamp(yFromPrice(price), chartTop + priceScaleTickLabelInset, chartBottom - priceScaleTickLabelInset);
-        drawText(formatPrice(price), chartRight + 6, y, "left", "middle", yAxis.textColor);
+        drawText(formatAxisPrice(price), chartRight + 6, y, "left", "middle", yAxis.textColor);
       }
       ctx.font = prevFont;
     }
@@ -6041,7 +6171,7 @@ function createChart(element, options = {}) {
         ...ticker.showCountdownInLabel ? [getCountdownText()] : []
       ].map((value) => value === null || value === void 0 ? "" : String(value).trim()).filter((value) => value.length > 0);
       addPriceAxisLabel({
-        text: formatPrice(tickerPrice),
+        text: formatAxisPrice(tickerPrice),
         ...tickerSubtexts.length > 0 ? { subtexts: tickerSubtexts } : {},
         subtextColor: ticker.labelSubtextColor ?? ticker.labelTextColor ?? "#0b1220",
         ...ticker.labelSubtextFontSize === void 0 ? {} : { subtextFontSize: ticker.labelSubtextFontSize },
@@ -6068,7 +6198,7 @@ function createChart(element, options = {}) {
         const previousClose = previousCloseCandidate;
         drawReferenceLine(previousClose, labels.previousCloseColor, "dashed");
         addPriceAxisLabel({
-          text: `PDC ${formatPrice(previousClose)}`,
+          text: `PDC ${formatAxisPrice(previousClose)}`,
           price: previousClose,
           backgroundColor: labels.backgroundColor,
           textColor: labels.mutedTextColor,
@@ -6087,7 +6217,7 @@ function createChart(element, options = {}) {
         if (point.l < visibleLow) visibleLow = point.l;
       }
       addPriceAxisLabel({
-        text: `H ${formatPrice(visibleHigh)}`,
+        text: `H ${formatAxisPrice(visibleHigh)}`,
         price: visibleHigh,
         backgroundColor: labels.backgroundColor,
         textColor: labels.textColor,
@@ -6095,7 +6225,7 @@ function createChart(element, options = {}) {
         priority: 40
       });
       addPriceAxisLabel({
-        text: `L ${formatPrice(visibleLow)}`,
+        text: `L ${formatAxisPrice(visibleLow)}`,
         price: visibleLow,
         backgroundColor: labels.backgroundColor,
         textColor: labels.textColor,
@@ -6107,7 +6237,7 @@ function createChart(element, options = {}) {
       if (Number.isFinite(labels.bidPrice)) {
         drawReferenceLine(labels.bidPrice, labels.bidColor, "dotted");
         addPriceAxisLabel({
-          text: `B ${formatPrice(labels.bidPrice)}`,
+          text: `B ${formatAxisPrice(labels.bidPrice)}`,
           price: labels.bidPrice,
           backgroundColor: labels.bidColor,
           textColor: "#0b1220",
@@ -6118,7 +6248,7 @@ function createChart(element, options = {}) {
       if (Number.isFinite(labels.askPrice)) {
         drawReferenceLine(labels.askPrice, labels.askColor, "dotted");
         addPriceAxisLabel({
-          text: `A ${formatPrice(labels.askPrice)}`,
+          text: `A ${formatAxisPrice(labels.askPrice)}`,
           price: labels.askPrice,
           backgroundColor: labels.askColor,
           textColor: "#0b1220",
@@ -6379,8 +6509,11 @@ function createChart(element, options = {}) {
       ctx.restore();
     };
     if (crosshair.showPriceLabel) {
-      const hoverPrice = yMin + (chartBottom - cy) / chartHeight * yRange;
-      const priceText = formatPrice(hoverPrice);
+      const scaledYMin = priceScaleTransform(yMin);
+      const scaledYRange = priceScaleTransform(yMin + yRange) - scaledYMin || 1;
+      const hoverRatio = priceScaleInverted ? (cy - chartTop) / chartHeight : (chartBottom - cy) / chartHeight;
+      const hoverPrice = priceScaleUntransform(scaledYMin + hoverRatio * scaledYRange);
+      const priceText = formatPriceForScale(hoverPrice, percentBaselineForXStart(xStart));
       const priceWidth = getRightAxisLabelWidth(chartRight, getPriceLabelWidth(priceText, labelPaddingX));
       const priceX = getRightAxisLabelX(chartRight);
       const priceY = clamp(cy - labelHeight / 2, chartTop, chartBottom - labelHeight);
@@ -6548,8 +6681,8 @@ function createChart(element, options = {}) {
     const maxRange = bounds.hardSpan;
     const nextRange = clamp(currentRange * factor, minRange, maxRange);
     const anchorRatio = clamp((anchorY - drawState.chartTop) / drawState.chartHeight, 0, 1);
-    const anchorPrice = currentMax - anchorRatio * currentRange;
-    const nextMax = anchorPrice + anchorRatio * nextRange;
+    const anchorPrice = priceScaleInverted ? currentMin + anchorRatio * currentRange : currentMax - anchorRatio * currentRange;
+    const nextMax = priceScaleInverted ? anchorPrice + (1 - anchorRatio) * nextRange : anchorPrice + anchorRatio * nextRange;
     const nextMin = nextMax - nextRange;
     const clamped = clampYRange(nextMin, nextMax);
     yMinOverride = clamped.min;
@@ -6573,7 +6706,7 @@ function createChart(element, options = {}) {
       const currentMin = yMinOverride ?? drawState.yMin;
       const currentMax = yMaxOverride ?? drawState.yMax;
       const range = currentMax - currentMin || 1;
-      const priceShift = deltaY / drawState.chartHeight * range;
+      const priceShift = deltaY / drawState.chartHeight * range * (priceScaleInverted ? -1 : 1);
       const clamped = clampYRange(currentMin + priceShift, currentMax + priceShift);
       yMinOverride = clamped.min;
       yMaxOverride = clamped.max;
@@ -6806,8 +6939,14 @@ function createChart(element, options = {}) {
     if (!drawState) {
       return 0;
     }
-    const ratio = clamp((drawState.chartBottom - y) / drawState.chartHeight, 0, 1);
-    return drawState.yMin + ratio * (drawState.yMax - drawState.yMin);
+    const ratio = clamp(
+      priceScaleInverted ? (y - drawState.chartTop) / drawState.chartHeight : (drawState.chartBottom - y) / drawState.chartHeight,
+      0,
+      1
+    );
+    const scaledMin = priceScaleTransform(drawState.yMin);
+    const scaledMax = priceScaleTransform(drawState.yMax);
+    return priceScaleUntransform(scaledMin + ratio * (scaledMax - scaledMin));
   };
   const applyMagnet = (y, index, price) => {
     const effective = magnetModifierActive ? "strong" : magnetMode;
@@ -6879,8 +7018,10 @@ function createChart(element, options = {}) {
   };
   const canvasYFromDrawingPrice = (price) => {
     if (!drawState) return 0;
-    const range = drawState.yMax - drawState.yMin || 1;
-    return drawState.chartBottom - (price - drawState.yMin) / range * drawState.chartHeight;
+    const scaledMin = priceScaleTransform(drawState.yMin);
+    const scaledRange = priceScaleTransform(drawState.yMax) - scaledMin || 1;
+    const ratio = (priceScaleTransform(price) - scaledMin) / scaledRange;
+    return priceScaleInverted ? drawState.chartTop + ratio * drawState.chartHeight : drawState.chartBottom - ratio * drawState.chartHeight;
   };
   const distanceToSegment = (x, y, x1, y1, x2, y2) => {
     const dx = x2 - x1;
@@ -8894,6 +9035,16 @@ function createChart(element, options = {}) {
     magnetMode = mode;
   };
   const getMagnetMode = () => magnetMode;
+  const setPriceScale = (options2) => {
+    if (options2.mode === "linear" || options2.mode === "log" || options2.mode === "percent") {
+      priceScaleMode = options2.mode;
+    }
+    if (typeof options2.inverted === "boolean") {
+      priceScaleInverted = options2.inverted;
+    }
+    scheduleDraw();
+  };
+  const getPriceScale = () => ({ mode: priceScaleMode, inverted: priceScaleInverted });
   const getDrawings = () => drawings.map((drawing) => serializeDrawing(drawing));
   const setDrawings = (nextDrawings) => {
     drawings = dedupeDrawingIds(nextDrawings.map((drawing) => normalizeDrawingState(drawing)));
@@ -8963,6 +9114,7 @@ function createChart(element, options = {}) {
       drawings: getDrawings(),
       indicators: getIndicators(),
       magnetMode: getMagnetMode(),
+      priceScale: getPriceScale(),
       drawingDefaults
     };
   };
@@ -8982,6 +9134,9 @@ function createChart(element, options = {}) {
     if (state.magnetMode === "none" || state.magnetMode === "weak" || state.magnetMode === "strong") {
       setMagnetMode(state.magnetMode);
     }
+    if (state.priceScale && typeof state.priceScale === "object") {
+      setPriceScale(state.priceScale);
+    }
     if (state.drawingDefaults && typeof state.drawingDefaults === "object") {
       for (const [tool, defaults] of Object.entries(state.drawingDefaults)) {
         if (defaults && typeof defaults === "object") {
@@ -9076,6 +9231,8 @@ function createChart(element, options = {}) {
     onDrawingEditText,
     setMagnetMode,
     getMagnetMode,
+    setPriceScale,
+    getPriceScale,
     cancelDrawing,
     setTradeMarkers,
     setSelectedDrawing,
@@ -9101,7 +9258,9 @@ function createChart(element, options = {}) {
 export {
   FIB_DEFAULT_PALETTE,
   POSITION_DEFAULT_COLORS,
+  SCRIPT_SOURCE_INPUT_VALUES,
   compileScriptIndicator,
   createChart,
+  extractScriptInputs,
   validateScriptSource
 };

package/docs/API.md

@@ -563,6 +563,7 @@ an up measurement, red for down.
 - `cancelDrawing(): boolean` — abort an in-progress multi-click drawing (between the first click and the final point, e.g. a half-drawn trendline/ray/fib). Returns `true` if a draft was cancelled. Wire it to Escape.
 - Hold **Shift** while drawing or dragging an endpoint of a `trendline`/`ray`/`arrow` to constrain it to the nearest 0/45/90° angle (e.g. a perfectly horizontal line).
 - `setMagnetMode(mode): void` / `getMagnetMode()` — magnet/snap for all drawing tools. `"none"` off, `"weak"` snaps to a candle's OHLC only when the cursor is near a value, `"strong"` always snaps to the nearest OHLC of the bar under the cursor. Holding Cmd/Ctrl while drawing/dragging forces strong snapping regardless of the mode.
+- `setPriceScale(options: { mode?: "linear" | "log" | "percent"; inverted?: boolean }): void` / `getPriceScale()` — price-scale modes for the main pane (TradingView-style). `"log"` maps prices through log10 (wide ranges get 1/2/5-per-decade axis marks). `"percent"` keeps the linear mapping but relabels the axis (ticks, last-price/PDC/H/L/bid/ask tags and the crosshair) as % change from the first visible bar's close, updating as you pan. `inverted: true` flips the axis top-to-bottom. All viewport state stays in plain price space, so switching modes never moves your zoom, and drawings/orders/indicators follow automatically. Indicator panes keep their own scales. Included in `saveState()` as `priceScale`.
 - `setActiveDrawingTool(tool: DrawingToolType | null): void` (`DrawingToolType` = `"horizontal-line" | "vertical-line" | "trendline" | "ray" | "fib-retracement" | "fib-extension" | "long-position" | "short-position" | "price-range" | "rectangle" | "text" | "note" | "parallel-channel" | "ellipse" | "arrow" | "brush" | "callout" | "measure"`)
 - `getActiveDrawingTool(): DrawingToolType | null`
 - `onActiveDrawingToolChange(handler: ((tool: DrawingToolType | null) => void) | null): void` — fires whenever the active tool changes, including the chart auto-reverting to the cursor after a tool completes (all tools do this when their shape is placed; `measure` does it after every measurement). Keeps host toolbars in sync without polling.
@@ -583,7 +584,7 @@ an up measurement, red for down.
 - `updateIndicator(id: string, patch: Partial<IndicatorInstanceOptions>): void`
 - `removeIndicator(id: string): void`
 - `setIndicators(indicators: IndicatorInstanceOptions[]): void`
-- `saveState(): ChartSavedState` — one JSON-serializable snapshot of the full user-visible setup: `{ version: 1, chartType, viewport, drawings, indicators, magnetMode, drawingDefaults }`. Chart *data* is not included; keep feeding bars through `setData`/`upsertBar`.
+- `saveState(): ChartSavedState` — one JSON-serializable snapshot of the full user-visible setup: `{ version: 1, chartType, viewport, drawings, indicators, magnetMode, priceScale, drawingDefaults }`. Chart *data* is not included; keep feeding bars through `setData`/`upsertBar`.
 - `loadState(state: Partial<ChartSavedState>): void` — restore a `saveState()` blob. Tolerant of partial blobs (missing sections are left untouched), so it doubles as a bulk setter. Register custom script indicator plugins with `registerIndicator` *before* calling it so their instances resolve. Viewport is applied last so pane changes don't clobber the restore.
 - `takeScreenshot(options?: { type?: "image/png" | "image/jpeg"; quality?: number }): string` — returns a data URL of the current frame (default PNG) at the chart's device pixel ratio. Everything on the canvas is included: series, indicators, panes, drawings, legends.
 
@@ -653,6 +654,43 @@ Script contract:
 - `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.
+
+### Pine-style input declarations
+
+Instead of maintaining a separate JSON `inputs` schema, scripts can declare their settings inline
+at the top level — the same idea as TradingView's `input.int(14, "Length")`. The declared
+constants always hold the live settings values, and hosts can auto-generate the settings dialog
+from the declarations:
+
+```ts
+const length = input.int("Length", 14, { min: 1, max: 500 });
+const source = input.source("Source", "close"); // open/high/low/close/hl2/hlc3/ohlc4
+const smooth = input.bool("Smooth", true);
+const color  = input.color("Line color", "#f59e0b");
+
+function compute(bars, inputs, hp) {
+  const values = bars.map(b => source === "open" ? b.o : b.c);
+  const line = smooth ? hp.ema(values, length) : hp.sma(values, length);
+  return { plots: [{ title: "MA", values: line, color }] };
+}
+```
+
+Available declarations (all return the resolved value; `opts` is `{ key?, min?, max?, step? }`):
+
+- `input.int(label, default, opts?)` / `input.float(label, default, opts?)` → number
+- `input.bool(label, default?)` → boolean
+- `input.color(label, default)` → color string
+- `input.string(label, default?)` → string
+- `input.select(label, default, choices)` → string (choices: `string[]` or `{value, label}[]`)
+- `input.source(label?, default?)` → one of `open/high/low/close/hl2/hlc3/ohlc4`
+
+Settings keys default to a slug of the label (`"Line color"` → `line_color`); pass
+`{ key: "..." }` to pin one explicitly (keeps saved settings stable if you rename the label).
+
+`extractScriptInputs(source: string): { inputs: ScriptIndicatorInputDef[], error: string | null }`
+— runs the script's top level with a recording helper and returns the declared schema; hosts use
+this to auto-generate settings dialogs. The legacy JSON `inputs` array on
+`ScriptIndicatorDefinition` still works; on key collisions the inline declarations win.
 - `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)`.

package/package.json

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