@pibbl/core 0.0.2 → 0.0.3-alpha.109.1

package/dist/features/viz/lib/financial-comparison.d.ts

@@ -0,0 +1,62 @@
+import type { LineAccessor } from "./types.js";
+/** Inputs for a fixed-base financial comparison. See {@link percentageReturns}. */
+export interface ComparisonBaseOptions<D> {
+    /** UTC-millisecond property or callback that identifies the common base observation. */
+    readonly time: LineAccessor<D>;
+    /** Numeric property or callback that supplies each instrument's observed value. */
+    readonly value: LineAccessor<D>;
+    /** Safe UTC-millisecond timestamp that must match exactly one eligible complete observation. */
+    readonly baseTime: number;
+    /**
+     * Excludes a row before either accessor runs and produces a derived gap.
+     * @param datum - Original source observation.
+     * @param index - Original source index.
+     * @param data - Complete original source array.
+     * @returns Whether this observation is eligible for the base and derived points.
+     */
+    readonly defined?: (datum: D, index: number, data: readonly D[]) => boolean;
+}
+/** One source-ordered cumulative simple-return observation. See {@link percentageReturns}. */
+export interface PercentageReturnPoint<D> {
+    /** Caller-owned original observation. */
+    readonly datum: D;
+    /** Original index, including rows that become gaps. */
+    readonly sourceIndex: number;
+    /** Evaluated finite timestamp, or null for a missing, invalid, or excluded row. */
+    readonly time: number | null;
+    /** Percentage change from the common base, or null for a gap. */
+    readonly returnPercent: number | null;
+}
+/** One source-ordered base-100 indexed observation. See {@link indexTo100}. */
+export interface IndexedValuePoint<D> {
+    /** Caller-owned original observation. */
+    readonly datum: D;
+    /** Original index, including rows that become gaps. */
+    readonly sourceIndex: number;
+    /** Evaluated finite timestamp, or null for a missing, invalid, or excluded row. */
+    readonly time: number | null;
+    /** Value indexed to 100 at the common base, or null for a gap. */
+    readonly indexValue: number | null;
+}
+/**
+ * Derives source-ordered cumulative simple percentage returns from one exact positive base.
+ *
+ * Each defined finite observation becomes `(value / baseValue - 1) * 100`, expressed in
+ * percentage points. This is a fixed-base return series, not a period-over-period return.
+ * Missing/nonfinite values become explicit gaps; a missing exact base returns undefined.
+ * @param data - Caller-owned source observations in presentation order.
+ * @param options - Time/value accessors, exact common base, and optional eligibility predicate.
+ * @returns Frozen points, or undefined when no eligible complete exact base exists.
+ * @see {@link ComparisonBaseOptions}
+ */
+export declare function percentageReturns<D>(data: readonly D[], options: ComparisonBaseOptions<D>): readonly PercentageReturnPoint<D>[] | undefined;
+/**
+ * Derives source-ordered values indexed to 100 at one exact positive base observation.
+ *
+ * Missing/nonfinite values become explicit gaps; a missing exact base returns undefined.
+ * @param data - Caller-owned source observations in presentation order.
+ * @param options - Time/value accessors, exact common base, and optional eligibility predicate.
+ * @returns Frozen points, or undefined when no eligible complete exact base exists.
+ * @see {@link ComparisonBaseOptions}
+ */
+export declare function indexTo100<D>(data: readonly D[], options: ComparisonBaseOptions<D>): readonly IndexedValuePoint<D>[] | undefined;

package/dist/features/viz/lib/financial-comparison.js

@@ -0,0 +1,98 @@
+import { finiteCoordinate, pointAccessor, pointData } from "./point-data.js";
+const DATE_LIMIT = 864e13;
+function validBaseTime(value) {
+  if (!Number.isSafeInteger(value) || Math.abs(value) > DATE_LIMIT)
+    throw new RangeError(
+      "comparison baseTime must be a safe integer UTC millisecond within Date range."
+    );
+}
+function percentageOf(value, base) {
+  return Math.abs(value) <= Number.MAX_VALUE / 100 ? value * 100 / base : value / base * 100;
+}
+function returnPercent(value, base) {
+  if (value === base) return 0;
+  const difference = value - base;
+  return Number.isFinite(difference) ? difference / base * 100 : percentageOf(value, base) - 100;
+}
+function comparisonBase(rows, baseTime) {
+  let matches = 0;
+  let baseValue;
+  for (const row of rows) {
+    if (!row.eligible || row.time !== baseTime || row.value === null) continue;
+    matches++;
+    baseValue = row.value;
+  }
+  if (matches === 0) return void 0;
+  if (matches > 1)
+    throw new RangeError(
+      "comparison baseTime matches multiple eligible complete observations and is ambiguous."
+    );
+  if (baseValue <= 0)
+    throw new RangeError("comparison base observation must be positive.");
+  return baseValue;
+}
+function comparisonPoints(data, options, derived, point) {
+  const rows = pointData(data, "comparison");
+  validBaseTime(options.baseTime);
+  const time = pointAccessor(options.time);
+  const value = pointAccessor(options.value);
+  const evaluated = rows.map((datum, index) => {
+    const eligible = options.defined?.(datum, index, rows) ?? true;
+    if (!eligible) return Object.freeze({ eligible, time: null, value: null });
+    const timestamp = time(datum, index, rows);
+    if (!finiteCoordinate(timestamp))
+      return Object.freeze({ eligible, time: null, value: null });
+    const observed = value(datum, index, rows);
+    return Object.freeze({
+      eligible,
+      time: timestamp,
+      value: finiteCoordinate(observed) ? observed : null
+    });
+  });
+  const base = comparisonBase(evaluated, options.baseTime);
+  if (base === void 0) return void 0;
+  return Object.freeze(rows.map((datum, sourceIndex) => {
+    const row = evaluated[sourceIndex];
+    if (!row.eligible || row.time === null)
+      return Object.freeze(point(datum, sourceIndex, null, null));
+    if (row.value === null)
+      return Object.freeze(point(datum, sourceIndex, row.time, null));
+    const result = derived(row.value, base);
+    if (!Number.isFinite(result))
+      throw new RangeError(
+        `comparison derived value at source index ${sourceIndex} must be finite.`
+      );
+    return Object.freeze(point(datum, sourceIndex, row.time, result));
+  }));
+}
+function percentageReturns(data, options) {
+  return comparisonPoints(
+    data,
+    options,
+    returnPercent,
+    (datum, sourceIndex, time, returnPercent2) => ({
+      datum,
+      sourceIndex,
+      time,
+      returnPercent: returnPercent2
+    })
+  );
+}
+function indexTo100(data, options) {
+  return comparisonPoints(
+    data,
+    options,
+    (value, base) => value === base ? 100 : percentageOf(value, base),
+    (datum, sourceIndex, time, indexValue) => ({
+      datum,
+      sourceIndex,
+      time,
+      indexValue
+    })
+  );
+}
+export {
+  indexTo100,
+  percentageReturns
+};
+//# sourceMappingURL=financial-comparison.js.map

package/dist/features/viz/lib/financial-comparison.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/lib/financial-comparison.ts"],
+  "sourcesContent": ["import type { LineAccessor } from \"./types.js\";\nimport { finiteCoordinate, pointAccessor, pointData } from \"./point-data.js\";\n\n/** Inputs for a fixed-base financial comparison. See {@link percentageReturns}. */\nexport interface ComparisonBaseOptions<D> {\n  /** UTC-millisecond property or callback that identifies the common base observation. */\n  readonly time: LineAccessor<D>;\n  /** Numeric property or callback that supplies each instrument's observed value. */\n  readonly value: LineAccessor<D>;\n  /** Safe UTC-millisecond timestamp that must match exactly one eligible complete observation. */\n  readonly baseTime: number;\n  /**\n   * Excludes a row before either accessor runs and produces a derived gap.\n   * @param datum - Original source observation.\n   * @param index - Original source index.\n   * @param data - Complete original source array.\n   * @returns Whether this observation is eligible for the base and derived points.\n   */\n  readonly defined?: (datum: D, index: number, data: readonly D[]) => boolean;\n}\n\n/** One source-ordered cumulative simple-return observation. See {@link percentageReturns}. */\nexport interface PercentageReturnPoint<D> {\n  /** Caller-owned original observation. */\n  readonly datum: D;\n  /** Original index, including rows that become gaps. */\n  readonly sourceIndex: number;\n  /** Evaluated finite timestamp, or null for a missing, invalid, or excluded row. */\n  readonly time: number | null;\n  /** Percentage change from the common base, or null for a gap. */\n  readonly returnPercent: number | null;\n}\n\n/** One source-ordered base-100 indexed observation. See {@link indexTo100}. */\nexport interface IndexedValuePoint<D> {\n  /** Caller-owned original observation. */\n  readonly datum: D;\n  /** Original index, including rows that become gaps. */\n  readonly sourceIndex: number;\n  /** Evaluated finite timestamp, or null for a missing, invalid, or excluded row. */\n  readonly time: number | null;\n  /** Value indexed to 100 at the common base, or null for a gap. */\n  readonly indexValue: number | null;\n}\n\nconst DATE_LIMIT = 8_640_000_000_000_000;\n\nfunction validBaseTime(value: number): void {\n  if (!Number.isSafeInteger(value) || Math.abs(value) > DATE_LIMIT)\n    throw new RangeError(\n      \"comparison baseTime must be a safe integer UTC millisecond within Date range.\",\n    );\n}\n\nfunction percentageOf(value: number, base: number): number {\n  // Multiplying first preserves tiny finite indexed values; dividing first preserves\n  // large finite ratios whose multiplication would otherwise overflow unnecessarily.\n  return Math.abs(value) <= Number.MAX_VALUE / 100\n    ? (value * 100) / base\n    : (value / base) * 100;\n}\n\nfunction returnPercent(value: number, base: number): number {\n  if (value === base) return 0;\n  const difference = value - base;\n  return Number.isFinite(difference)\n    ? (difference / base) * 100\n    : percentageOf(value, base) - 100;\n}\n\ninterface EvaluatedComparisonRow {\n  readonly eligible: boolean;\n  readonly time: number | null;\n  readonly value: number | null;\n}\n\nfunction comparisonBase(\n  rows: readonly EvaluatedComparisonRow[],\n  baseTime: number,\n): number | undefined {\n  let matches = 0;\n  let baseValue: number | undefined;\n  for (const row of rows) {\n    if (!row.eligible || row.time !== baseTime || row.value === null) continue;\n    matches++;\n    baseValue = row.value;\n  }\n  if (matches === 0) return undefined;\n  if (matches > 1)\n    throw new RangeError(\n      \"comparison baseTime matches multiple eligible complete observations and is ambiguous.\",\n    );\n  if (baseValue! <= 0)\n    throw new RangeError(\"comparison base observation must be positive.\");\n  return baseValue;\n}\n\nfunction comparisonPoints<D, P>(\n  data: readonly D[],\n  options: ComparisonBaseOptions<D>,\n  derived: (value: number, base: number) => number,\n  point: (datum: D, sourceIndex: number, time: number | null, value: number | null) => P,\n): readonly P[] | undefined {\n  const rows = pointData(data, \"comparison\");\n  validBaseTime(options.baseTime);\n  const time = pointAccessor(options.time);\n  const value = pointAccessor(options.value);\n  const evaluated = rows.map((datum, index): EvaluatedComparisonRow => {\n    const eligible = options.defined?.(datum, index, rows) ?? true;\n    if (!eligible) return Object.freeze({ eligible, time: null, value: null });\n    const timestamp = time(datum, index, rows);\n    if (!finiteCoordinate(timestamp))\n      return Object.freeze({ eligible, time: null, value: null });\n    const observed = value(datum, index, rows);\n    return Object.freeze({\n      eligible,\n      time: timestamp,\n      value: finiteCoordinate(observed) ? observed : null,\n    });\n  });\n  const base = comparisonBase(evaluated, options.baseTime);\n  if (base === undefined) return undefined;\n  return Object.freeze(rows.map((datum, sourceIndex) => {\n    const row = evaluated[sourceIndex]!;\n    if (!row.eligible || row.time === null)\n      return Object.freeze(point(datum, sourceIndex, null, null));\n    if (row.value === null)\n      return Object.freeze(point(datum, sourceIndex, row.time, null));\n    const result = derived(row.value, base);\n    if (!Number.isFinite(result))\n      throw new RangeError(\n        `comparison derived value at source index ${sourceIndex} must be finite.`,\n      );\n    return Object.freeze(point(datum, sourceIndex, row.time, result));\n  }));\n}\n\n/**\n * Derives source-ordered cumulative simple percentage returns from one exact positive base.\n *\n * Each defined finite observation becomes `(value / baseValue - 1) * 100`, expressed in\n * percentage points. This is a fixed-base return series, not a period-over-period return.\n * Missing/nonfinite values become explicit gaps; a missing exact base returns undefined.\n * @param data - Caller-owned source observations in presentation order.\n * @param options - Time/value accessors, exact common base, and optional eligibility predicate.\n * @returns Frozen points, or undefined when no eligible complete exact base exists.\n * @see {@link ComparisonBaseOptions}\n */\nexport function percentageReturns<D>(\n  data: readonly D[],\n  options: ComparisonBaseOptions<D>,\n): readonly PercentageReturnPoint<D>[] | undefined {\n  return comparisonPoints(\n    data,\n    options,\n    returnPercent,\n    (datum, sourceIndex, time, returnPercent) => ({\n      datum,\n      sourceIndex,\n      time,\n      returnPercent,\n    }),\n  );\n}\n\n/**\n * Derives source-ordered values indexed to 100 at one exact positive base observation.\n *\n * Missing/nonfinite values become explicit gaps; a missing exact base returns undefined.\n * @param data - Caller-owned source observations in presentation order.\n * @param options - Time/value accessors, exact common base, and optional eligibility predicate.\n * @returns Frozen points, or undefined when no eligible complete exact base exists.\n * @see {@link ComparisonBaseOptions}\n */\nexport function indexTo100<D>(\n  data: readonly D[],\n  options: ComparisonBaseOptions<D>,\n): readonly IndexedValuePoint<D>[] | undefined {\n  return comparisonPoints(\n    data,\n    options,\n    (value, base) => value === base ? 100 : percentageOf(value, base),\n    (datum, sourceIndex, time, indexValue) => ({\n      datum,\n      sourceIndex,\n      time,\n      indexValue,\n    }),\n  );\n}\n"],
+  "mappings": "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",
+  "names": ["returnPercent"]
+}

package/dist/features/viz/lib/financial-geometry.d.ts

@@ -0,0 +1,77 @@
+/** Local coordinates for one candle body and wick. */
+export interface CandleGeometry {
+    /** Normalized rectangle that paints the open/close body. */
+    readonly bodyBoundsLocal: Readonly<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /** Vertical wick endpoints in the caller's high/low coordinate order. */
+    readonly wickLocal: Readonly<{
+        x: number;
+        lowY: number;
+        highY: number;
+    }>;
+}
+/** Inputs already mapped into a series' local coordinate system. */
+export interface CandleGeometryInput {
+    readonly centerX: number;
+    readonly openY: number;
+    readonly closeY: number;
+    readonly highY: number;
+    readonly lowY: number;
+    readonly width: number;
+    readonly dojiHeight: number;
+}
+/** Inputs already mapped into a volume series' local coordinate system. */
+export interface VolumeGeometryInput {
+    readonly centerX: number;
+    readonly valueY: number;
+    readonly baselineY: number;
+    readonly width: number;
+}
+/** Options for the common financial mark width calculation. */
+export interface FinancialMarkWidthOptions {
+    /** A caller-selected local mark width. */
+    readonly width?: number;
+    /** Width to use when fewer than two distinct local x positions are available. */
+    readonly fallbackWidth?: number;
+}
+/**
+ * Calculates local, paint-ready candle geometry without consulting a scale.
+ *
+ * The body spans the mapped open and close coordinates. Equal values produce a
+ * centered doji whose height is at least one local unit.
+ *
+ * @param input - Already-mapped candle coordinates and local dimensions.
+ * @returns Frozen normalized body bounds and source-ordered wick endpoints.
+ */
+export declare function candleGeometry(input: CandleGeometryInput): CandleGeometry;
+/**
+ * Calculates the local rectangle for a volume column without consulting a scale.
+ *
+ * @param input - Mapped column center, mapped value and baseline, and local width.
+ * @returns Frozen rectangle with a nonnegative height; equal endpoints return height zero.
+ */
+export declare function volumeGeometry(input: VolumeGeometryInput): Readonly<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+/**
+ * Finds the smallest positive separation of adjacent mapped local x positions.
+ *
+ * @param positions - Mapped positions in source order.
+ * @returns The smallest positive adjacent separation, or undefined when none exists.
+ */
+export declare function smallestAdjacentSpacing(positions: readonly number[]): number | undefined;
+/**
+ * Computes a shared local mark width from mapped x spacing.
+ *
+ * @param positions - Mapped positions in source order.
+ * @param options - Optional explicit or singleton fallback width.
+ * @returns Explicit width, or 70% of the smallest spacing capped at 12 local units.
+ */
+export declare function financialMarkWidth(positions: readonly number[], options?: FinancialMarkWidthOptions): number;

package/dist/features/viz/lib/financial-geometry.js

@@ -0,0 +1,67 @@
+function finite(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value))
+    throw new RangeError(`${name} must be finite.`);
+  return value;
+}
+function positive(value, name) {
+  finite(value, name);
+  if (value <= 0) throw new RangeError(`${name} must be greater than zero.`);
+  return value;
+}
+function candleGeometry(input) {
+  const centerX = finite(input.centerX, "centerX");
+  const openY = finite(input.openY, "openY");
+  const closeY = finite(input.closeY, "closeY");
+  const highY = finite(input.highY, "highY");
+  const lowY = finite(input.lowY, "lowY");
+  const markWidth = positive(input.width, "width");
+  const dojiHeight = finite(input.dojiHeight, "dojiHeight");
+  if (dojiHeight < 0) throw new RangeError("dojiHeight must be nonnegative.");
+  const height = openY === closeY ? Math.max(1, dojiHeight) : Math.abs(closeY - openY);
+  const y = openY === closeY ? openY - height / 2 : Math.min(openY, closeY);
+  return Object.freeze({
+    bodyBoundsLocal: Object.freeze({
+      x: centerX - markWidth / 2,
+      y,
+      width: markWidth,
+      height
+    }),
+    wickLocal: Object.freeze({ x: centerX, lowY, highY })
+  });
+}
+function volumeGeometry(input) {
+  const centerX = finite(input.centerX, "centerX");
+  const valueY = finite(input.valueY, "valueY");
+  const baselineY = finite(input.baselineY, "baselineY");
+  const width = positive(input.width, "width");
+  return Object.freeze({
+    x: centerX - width / 2,
+    y: Math.min(valueY, baselineY),
+    width,
+    height: Math.abs(valueY - baselineY)
+  });
+}
+function smallestAdjacentSpacing(positions) {
+  let smallest = Infinity;
+  for (let index = 0; index < positions.length; index++) {
+    finite(positions[index], `positions[${index}]`);
+    if (index > 0) {
+      const separation = Math.abs(positions[index] - positions[index - 1]);
+      if (separation > 0) smallest = Math.min(smallest, separation);
+    }
+  }
+  return smallest === Infinity ? void 0 : smallest;
+}
+function financialMarkWidth(positions, options = {}) {
+  if (options.width !== void 0) return positive(options.width, "width");
+  const spacing = smallestAdjacentSpacing(positions);
+  if (spacing !== void 0) return Math.min(12, spacing * 0.7);
+  return positive(options.fallbackWidth ?? 8, "fallbackWidth");
+}
+export {
+  candleGeometry,
+  financialMarkWidth,
+  smallestAdjacentSpacing,
+  volumeGeometry
+};
+//# sourceMappingURL=financial-geometry.js.map

package/dist/features/viz/lib/financial-geometry.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/lib/financial-geometry.ts"],
+  "sourcesContent": ["/** Local coordinates for one candle body and wick. */\nexport interface CandleGeometry {\n  /** Normalized rectangle that paints the open/close body. */\n  readonly bodyBoundsLocal: Readonly<{\n    x: number;\n    y: number;\n    width: number;\n    height: number;\n  }>;\n  /** Vertical wick endpoints in the caller's high/low coordinate order. */\n  readonly wickLocal: Readonly<{ x: number; lowY: number; highY: number }>;\n}\n\n/** Inputs already mapped into a series' local coordinate system. */\nexport interface CandleGeometryInput {\n  readonly centerX: number;\n  readonly openY: number;\n  readonly closeY: number;\n  readonly highY: number;\n  readonly lowY: number;\n  readonly width: number;\n  readonly dojiHeight: number;\n}\n\n/** Inputs already mapped into a volume series' local coordinate system. */\nexport interface VolumeGeometryInput {\n  readonly centerX: number;\n  readonly valueY: number;\n  readonly baselineY: number;\n  readonly width: number;\n}\n\n/** Options for the common financial mark width calculation. */\nexport interface FinancialMarkWidthOptions {\n  /** A caller-selected local mark width. */\n  readonly width?: number;\n  /** Width to use when fewer than two distinct local x positions are available. */\n  readonly fallbackWidth?: number;\n}\n\nfunction finite(value: number, name: string): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value))\n    throw new RangeError(`${name} must be finite.`);\n  return value;\n}\n\nfunction positive(value: number, name: string): number {\n  finite(value, name);\n  if (value <= 0) throw new RangeError(`${name} must be greater than zero.`);\n  return value;\n}\n\n/**\n * Calculates local, paint-ready candle geometry without consulting a scale.\n *\n * The body spans the mapped open and close coordinates. Equal values produce a\n * centered doji whose height is at least one local unit.\n *\n * @param input - Already-mapped candle coordinates and local dimensions.\n * @returns Frozen normalized body bounds and source-ordered wick endpoints.\n */\nexport function candleGeometry(input: CandleGeometryInput): CandleGeometry {\n  const centerX = finite(input.centerX, \"centerX\");\n  const openY = finite(input.openY, \"openY\");\n  const closeY = finite(input.closeY, \"closeY\");\n  const highY = finite(input.highY, \"highY\");\n  const lowY = finite(input.lowY, \"lowY\");\n  const markWidth = positive(input.width, \"width\");\n  const dojiHeight = finite(input.dojiHeight, \"dojiHeight\");\n  if (dojiHeight < 0) throw new RangeError(\"dojiHeight must be nonnegative.\");\n  const height =\n    openY === closeY ? Math.max(1, dojiHeight) : Math.abs(closeY - openY);\n  const y = openY === closeY ? openY - height / 2 : Math.min(openY, closeY);\n  return Object.freeze({\n    bodyBoundsLocal: Object.freeze({\n      x: centerX - markWidth / 2,\n      y,\n      width: markWidth,\n      height,\n    }),\n    wickLocal: Object.freeze({ x: centerX, lowY, highY }),\n  });\n}\n\n/**\n * Calculates the local rectangle for a volume column without consulting a scale.\n *\n * @param input - Mapped column center, mapped value and baseline, and local width.\n * @returns Frozen rectangle with a nonnegative height; equal endpoints return height zero.\n */\nexport function volumeGeometry(\n  input: VolumeGeometryInput,\n): Readonly<{ x: number; y: number; width: number; height: number }> {\n  const centerX = finite(input.centerX, \"centerX\");\n  const valueY = finite(input.valueY, \"valueY\");\n  const baselineY = finite(input.baselineY, \"baselineY\");\n  const width = positive(input.width, \"width\");\n  return Object.freeze({\n    x: centerX - width / 2,\n    y: Math.min(valueY, baselineY),\n    width,\n    height: Math.abs(valueY - baselineY),\n  });\n}\n\n/**\n * Finds the smallest positive separation of adjacent mapped local x positions.\n *\n * @param positions - Mapped positions in source order.\n * @returns The smallest positive adjacent separation, or undefined when none exists.\n */\nexport function smallestAdjacentSpacing(\n  positions: readonly number[],\n): number | undefined {\n  let smallest = Infinity;\n  for (let index = 0; index < positions.length; index++) {\n    finite(positions[index]!, `positions[${index}]`);\n    if (index > 0) {\n      const separation = Math.abs(positions[index]! - positions[index - 1]!);\n      if (separation > 0) smallest = Math.min(smallest, separation);\n    }\n  }\n  return smallest === Infinity ? undefined : smallest;\n}\n\n/**\n * Computes a shared local mark width from mapped x spacing.\n *\n * @param positions - Mapped positions in source order.\n * @param options - Optional explicit or singleton fallback width.\n * @returns Explicit width, or 70% of the smallest spacing capped at 12 local units.\n */\nexport function financialMarkWidth(\n  positions: readonly number[],\n  options: FinancialMarkWidthOptions = {},\n): number {\n  if (options.width !== undefined) return positive(options.width, \"width\");\n  const spacing = smallestAdjacentSpacing(positions);\n  if (spacing !== undefined) return Math.min(12, spacing * 0.7);\n  return positive(options.fallbackWidth ?? 8, \"fallbackWidth\");\n}\n"],
+  "mappings": "AAwCA,SAAS,OAAO,OAAe,MAAsB;AACnD,MAAI,OAAO,UAAU,YAAY,CAAC,OAAO,SAAS,KAAK;AACrD,UAAM,IAAI,WAAW,GAAG,IAAI,kBAAkB;AAChD,SAAO;AACT;AAEA,SAAS,SAAS,OAAe,MAAsB;AACrD,SAAO,OAAO,IAAI;AAClB,MAAI,SAAS,EAAG,OAAM,IAAI,WAAW,GAAG,IAAI,6BAA6B;AACzE,SAAO;AACT;AAWO,SAAS,eAAe,OAA4C;AACzE,QAAM,UAAU,OAAO,MAAM,SAAS,SAAS;AAC/C,QAAM,QAAQ,OAAO,MAAM,OAAO,OAAO;AACzC,QAAM,SAAS,OAAO,MAAM,QAAQ,QAAQ;AAC5C,QAAM,QAAQ,OAAO,MAAM,OAAO,OAAO;AACzC,QAAM,OAAO,OAAO,MAAM,MAAM,MAAM;AACtC,QAAM,YAAY,SAAS,MAAM,OAAO,OAAO;AAC/C,QAAM,aAAa,OAAO,MAAM,YAAY,YAAY;AACxD,MAAI,aAAa,EAAG,OAAM,IAAI,WAAW,iCAAiC;AAC1E,QAAM,SACJ,UAAU,SAAS,KAAK,IAAI,GAAG,UAAU,IAAI,KAAK,IAAI,SAAS,KAAK;AACtE,QAAM,IAAI,UAAU,SAAS,QAAQ,SAAS,IAAI,KAAK,IAAI,OAAO,MAAM;AACxE,SAAO,OAAO,OAAO;AAAA,IACnB,iBAAiB,OAAO,OAAO;AAAA,MAC7B,GAAG,UAAU,YAAY;AAAA,MACzB;AAAA,MACA,OAAO;AAAA,MACP;AAAA,IACF,CAAC;AAAA,IACD,WAAW,OAAO,OAAO,EAAE,GAAG,SAAS,MAAM,MAAM,CAAC;AAAA,EACtD,CAAC;AACH;AAQO,SAAS,eACd,OACmE;AACnE,QAAM,UAAU,OAAO,MAAM,SAAS,SAAS;AAC/C,QAAM,SAAS,OAAO,MAAM,QAAQ,QAAQ;AAC5C,QAAM,YAAY,OAAO,MAAM,WAAW,WAAW;AACrD,QAAM,QAAQ,SAAS,MAAM,OAAO,OAAO;AAC3C,SAAO,OAAO,OAAO;AAAA,IACnB,GAAG,UAAU,QAAQ;AAAA,IACrB,GAAG,KAAK,IAAI,QAAQ,SAAS;AAAA,IAC7B;AAAA,IACA,QAAQ,KAAK,IAAI,SAAS,SAAS;AAAA,EACrC,CAAC;AACH;AAQO,SAAS,wBACd,WACoB;AACpB,MAAI,WAAW;AACf,WAAS,QAAQ,GAAG,QAAQ,UAAU,QAAQ,SAAS;AACrD,WAAO,UAAU,KAAK,GAAI,aAAa,KAAK,GAAG;AAC/C,QAAI,QAAQ,GAAG;AACb,YAAM,aAAa,KAAK,IAAI,UAAU,KAAK,IAAK,UAAU,QAAQ,CAAC,CAAE;AACrE,UAAI,aAAa,EAAG,YAAW,KAAK,IAAI,UAAU,UAAU;AAAA,IAC9D;AAAA,EACF;AACA,SAAO,aAAa,WAAW,SAAY;AAC7C;AASO,SAAS,mBACd,WACA,UAAqC,CAAC,GAC9B;AACR,MAAI,QAAQ,UAAU,OAAW,QAAO,SAAS,QAAQ,OAAO,OAAO;AACvE,QAAM,UAAU,wBAAwB,SAAS;AACjD,MAAI,YAAY,OAAW,QAAO,KAAK,IAAI,IAAI,UAAU,GAAG;AAC5D,SAAO,SAAS,QAAQ,iBAAiB,GAAG,eAAe;AAC7D;",
+  "names": []
+}

package/dist/features/viz/lib/financial-indicators.d.ts

@@ -0,0 +1,114 @@
+import type { LineAccessor } from "./types.js";
+/**
+ * Inputs shared by source-aligned moving-average indicators.
+ *
+ * @see {@link MovingAveragePoint}
+ * @see {@link LineAccessor}
+ */
+export interface MovingAverageOptions<D> {
+    /**
+     * Numeric property or callback that supplies each observation.
+     *
+     * @see {@link LineAccessor}
+     */
+    readonly value: LineAccessor<D>;
+    /**
+     * Required number of consecutive complete observations in each window.
+     *
+     * @see {@link MovingAveragePoint}
+     */
+    readonly period: number;
+    /**
+     * Excludes a row before its value accessor runs and resets the current window.
+     *
+     * @param datum - Source observation under consideration.
+     * @param index - Zero-based source index.
+     * @param data - Complete caller-supplied source data.
+     * @returns Whether the observation participates in the current consecutive window.
+     * @see {@link LineAccessor}
+     */
+    readonly defined?: (datum: D, index: number, data: readonly D[]) => boolean;
+}
+/**
+ * Inputs for source-aligned population-standard-deviation Bollinger bands.
+ *
+ * @see {@link MovingAverageOptions}
+ * @see {@link BollingerBandPoint}
+ */
+export interface BollingerBandsOptions<D> extends MovingAverageOptions<D> {
+    /**
+     * Number of population standard deviations from the mean; defaults to 2.
+     *
+     * @see {@link BollingerBandPoint}
+     */
+    readonly multiplier?: number;
+}
+/**
+ * One source-aligned simple or exponential moving-average observation.
+ *
+ * @see {@link MovingAverageOptions}
+ */
+export interface MovingAveragePoint<D> {
+    /** Caller-owned original observation. */
+    readonly datum: D;
+    /** Original source index, including rows that become gaps. */
+    readonly sourceIndex: number;
+    /** Average after a complete consecutive window, or null during warmup/a gap. */
+    readonly average: number | null;
+}
+/**
+ * One source-aligned population-standard-deviation Bollinger-band observation.
+ *
+ * @see {@link BollingerBandsOptions}
+ */
+export interface BollingerBandPoint<D> {
+    /** Caller-owned original observation. */
+    readonly datum: D;
+    /** Original source index, including rows that become gaps. */
+    readonly sourceIndex: number;
+    /** Window mean, or null during warmup/a gap. */
+    readonly mean: number | null;
+    /** Mean minus multiplier population standard deviations, or null during warmup/a gap. */
+    readonly lower: number | null;
+    /** Mean plus multiplier population standard deviations, or null during warmup/a gap. */
+    readonly upper: number | null;
+}
+/**
+ * Derives a source-aligned simple moving average from consecutive finite observations.
+ *
+ * Missing, nonfinite, and excluded observations produce null and reset warmup. Results are
+ * population-neutral arithmetic means; no timestamps are inferred or changed.
+ *
+ * @param data - Source observations, retained in their original order.
+ * @param options - Value accessor, consecutive period, and optional participation callback.
+ * @returns Frozen source-aligned average observations, with null during warmup and gaps.
+ * @see {@link MovingAverageOptions}
+ * @see {@link MovingAveragePoint}
+ */
+export declare function simpleMovingAverage<D>(data: readonly D[], options: MovingAverageOptions<D>): readonly MovingAveragePoint<D>[];
+/**
+ * Derives a source-aligned exponential moving average seeded by the first complete SMA window.
+ *
+ * Its smoothing factor is `2 / (period + 1)`. Missing, nonfinite, and excluded observations
+ * produce null and reset the seed window.
+ *
+ * @param data - Source observations, retained in their original order.
+ * @param options - Value accessor, consecutive seed period, and optional participation callback.
+ * @returns Frozen source-aligned average observations, with null during warmup and gaps.
+ * @see {@link MovingAverageOptions}
+ * @see {@link MovingAveragePoint}
+ */
+export declare function exponentialMovingAverage<D>(data: readonly D[], options: MovingAverageOptions<D>): readonly MovingAveragePoint<D>[];
+/**
+ * Derives source-aligned Bollinger bands from trailing consecutive population-standard-deviation windows.
+ *
+ * Missing, nonfinite, and excluded observations produce null bands and reset warmup. The multiplier
+ * defaults to 2; caller-owned data are neither sorted nor mutated.
+ *
+ * @param data - Source observations, retained in their original order.
+ * @param options - Value accessor, period, participation callback, and optional band multiplier.
+ * @returns Frozen source-aligned population-standard-deviation band observations.
+ * @see {@link BollingerBandsOptions}
+ * @see {@link BollingerBandPoint}
+ */
+export declare function bollingerBands<D>(data: readonly D[], options: BollingerBandsOptions<D>): readonly BollingerBandPoint<D>[];

package/dist/features/viz/lib/financial-indicators.js

@@ -0,0 +1,135 @@
+import { finiteCoordinate, pointAccessor, pointData } from "./point-data.js";
+function validatePeriod(period) {
+  if (!Number.isSafeInteger(period) || period <= 0)
+    throw new RangeError(
+      "moving-average period must be a positive safe integer."
+    );
+}
+function validateMultiplier(multiplier) {
+  if (!Number.isFinite(multiplier) || multiplier < 0)
+    throw new RangeError(
+      "Bollinger multiplier must be finite and non-negative."
+    );
+}
+function values(data, options) {
+  const rows = pointData(data, "moving average");
+  validatePeriod(options.period);
+  const value = pointAccessor(options.value);
+  return Object.freeze(
+    rows.map((datum, index) => {
+      if (!(options.defined?.(datum, index, rows) ?? true)) return null;
+      const observed = value(datum, index, rows);
+      return finiteCoordinate(observed) ? observed : null;
+    })
+  );
+}
+function summary(window) {
+  let scale = 0;
+  for (const value of window) scale = Math.max(scale, Math.abs(value));
+  if (scale === 0) return [0, 0];
+  let normalizedSum = 0;
+  for (const value of window) normalizedSum += value / scale;
+  const meanNormalized = normalizedSum / window.length;
+  let squaredDifferenceSum = 0;
+  for (const value of window) {
+    const difference = value / scale - meanNormalized;
+    squaredDifferenceSum += difference * difference;
+  }
+  const varianceNormalized = squaredDifferenceSum / window.length;
+  const mean = meanNormalized * scale;
+  const deviation = Math.sqrt(varianceNormalized) * scale;
+  if (!Number.isFinite(mean) || !Number.isFinite(deviation))
+    throw new RangeError("moving-average derived value must be finite.");
+  return [mean, deviation];
+}
+function weighted(previous, next, alpha) {
+  const scale = Math.max(Math.abs(previous), Math.abs(next));
+  if (scale === 0) return 0;
+  const result = (previous / scale * (1 - alpha) + next / scale * alpha) * scale;
+  if (!Number.isFinite(result))
+    throw new RangeError("moving-average derived value must be finite.");
+  return result;
+}
+function simpleMovingAverage(data, options) {
+  const observed = values(data, options);
+  const window = [];
+  return Object.freeze(
+    data.map((datum, sourceIndex) => {
+      const value = observed[sourceIndex];
+      if (value === null) {
+        window.length = 0;
+        return Object.freeze({ datum, sourceIndex, average: null });
+      }
+      window.push(value);
+      if (window.length > options.period) window.shift();
+      const average = window.length === options.period ? summary(window)[0] : null;
+      return Object.freeze({ datum, sourceIndex, average });
+    })
+  );
+}
+function exponentialMovingAverage(data, options) {
+  const observed = values(data, options);
+  const seed = [];
+  const alpha = 2 / (options.period + 1);
+  let average;
+  return Object.freeze(
+    data.map((datum, sourceIndex) => {
+      const value = observed[sourceIndex];
+      if (value === null) {
+        seed.length = 0;
+        average = void 0;
+        return Object.freeze({ datum, sourceIndex, average: null });
+      }
+      if (average === void 0) {
+        seed.push(value);
+        if (seed.length < options.period)
+          return Object.freeze({ datum, sourceIndex, average: null });
+        average = summary(seed)[0];
+      } else average = weighted(average, value, alpha);
+      return Object.freeze({ datum, sourceIndex, average });
+    })
+  );
+}
+function bollingerBands(data, options) {
+  const multiplier = options.multiplier ?? 2;
+  validateMultiplier(multiplier);
+  const observed = values(data, options);
+  const window = [];
+  return Object.freeze(
+    data.map((datum, sourceIndex) => {
+      const value = observed[sourceIndex];
+      if (value === null) {
+        window.length = 0;
+        return Object.freeze({
+          datum,
+          sourceIndex,
+          mean: null,
+          lower: null,
+          upper: null
+        });
+      }
+      window.push(value);
+      if (window.length > options.period) window.shift();
+      if (window.length < options.period)
+        return Object.freeze({
+          datum,
+          sourceIndex,
+          mean: null,
+          lower: null,
+          upper: null
+        });
+      const [mean, deviation] = summary(window);
+      const lower = mean - multiplier * deviation;
+      const upper = mean + multiplier * deviation;
+      if (!Number.isFinite(lower) || !Number.isFinite(upper))
+        throw new RangeError("Bollinger derived value must be finite.");
+      return Object.freeze({ datum, sourceIndex, mean, lower, upper });
+    })
+  );
+}
+export {
+  bollingerBands,
+  exponentialMovingAverage,
+  simpleMovingAverage
+};
+//# sourceMappingURL=financial-indicators.js.map

package/dist/features/viz/lib/financial-indicators.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/viz/lib/financial-indicators.ts"],
+  "sourcesContent": ["import type { LineAccessor } from \"./types.js\";\nimport { finiteCoordinate, pointAccessor, pointData } from \"./point-data.js\";\n\n/**\n * Inputs shared by source-aligned moving-average indicators.\n *\n * @see {@link MovingAveragePoint}\n * @see {@link LineAccessor}\n */\nexport interface MovingAverageOptions<D> {\n  /**\n   * Numeric property or callback that supplies each observation.\n   *\n   * @see {@link LineAccessor}\n   */\n  readonly value: LineAccessor<D>;\n  /**\n   * Required number of consecutive complete observations in each window.\n   *\n   * @see {@link MovingAveragePoint}\n   */\n  readonly period: number;\n  /**\n   * Excludes a row before its value accessor runs and resets the current window.\n   *\n   * @param datum - Source observation under consideration.\n   * @param index - Zero-based source index.\n   * @param data - Complete caller-supplied source data.\n   * @returns Whether the observation participates in the current consecutive window.\n   * @see {@link LineAccessor}\n   */\n  readonly defined?: (datum: D, index: number, data: readonly D[]) => boolean;\n}\n\n/**\n * Inputs for source-aligned population-standard-deviation Bollinger bands.\n *\n * @see {@link MovingAverageOptions}\n * @see {@link BollingerBandPoint}\n */\nexport interface BollingerBandsOptions<D> extends MovingAverageOptions<D> {\n  /**\n   * Number of population standard deviations from the mean; defaults to 2.\n   *\n   * @see {@link BollingerBandPoint}\n   */\n  readonly multiplier?: number;\n}\n\n/**\n * One source-aligned simple or exponential moving-average observation.\n *\n * @see {@link MovingAverageOptions}\n */\nexport interface MovingAveragePoint<D> {\n  /** Caller-owned original observation. */\n  readonly datum: D;\n  /** Original source index, including rows that become gaps. */\n  readonly sourceIndex: number;\n  /** Average after a complete consecutive window, or null during warmup/a gap. */\n  readonly average: number | null;\n}\n\n/**\n * One source-aligned population-standard-deviation Bollinger-band observation.\n *\n * @see {@link BollingerBandsOptions}\n */\nexport interface BollingerBandPoint<D> {\n  /** Caller-owned original observation. */\n  readonly datum: D;\n  /** Original source index, including rows that become gaps. */\n  readonly sourceIndex: number;\n  /** Window mean, or null during warmup/a gap. */\n  readonly mean: number | null;\n  /** Mean minus multiplier population standard deviations, or null during warmup/a gap. */\n  readonly lower: number | null;\n  /** Mean plus multiplier population standard deviations, or null during warmup/a gap. */\n  readonly upper: number | null;\n}\n\nfunction validatePeriod(period: number): void {\n  if (!Number.isSafeInteger(period) || period <= 0)\n    throw new RangeError(\n      \"moving-average period must be a positive safe integer.\",\n    );\n}\n\nfunction validateMultiplier(multiplier: number): void {\n  if (!Number.isFinite(multiplier) || multiplier < 0)\n    throw new RangeError(\n      \"Bollinger multiplier must be finite and non-negative.\",\n    );\n}\n\nfunction values<D>(\n  data: readonly D[],\n  options: MovingAverageOptions<D>,\n): readonly (number | null)[] {\n  const rows = pointData(data, \"moving average\");\n  validatePeriod(options.period);\n  const value = pointAccessor(options.value);\n  return Object.freeze(\n    rows.map((datum, index) => {\n      if (!(options.defined?.(datum, index, rows) ?? true)) return null;\n      const observed = value(datum, index, rows);\n      return finiteCoordinate(observed) ? observed : null;\n    }),\n  );\n}\n\nfunction summary(window: readonly number[]): readonly [number, number] {\n  let scale = 0;\n  for (const value of window) scale = Math.max(scale, Math.abs(value));\n  if (scale === 0) return [0, 0];\n  let normalizedSum = 0;\n  for (const value of window) normalizedSum += value / scale;\n  const meanNormalized = normalizedSum / window.length;\n  let squaredDifferenceSum = 0;\n  for (const value of window) {\n    const difference = value / scale - meanNormalized;\n    squaredDifferenceSum += difference * difference;\n  }\n  const varianceNormalized = squaredDifferenceSum / window.length;\n  const mean = meanNormalized * scale;\n  const deviation = Math.sqrt(varianceNormalized) * scale;\n  if (!Number.isFinite(mean) || !Number.isFinite(deviation))\n    throw new RangeError(\"moving-average derived value must be finite.\");\n  return [mean, deviation];\n}\n\nfunction weighted(previous: number, next: number, alpha: number): number {\n  const scale = Math.max(Math.abs(previous), Math.abs(next));\n  if (scale === 0) return 0;\n  const result =\n    ((previous / scale) * (1 - alpha) + (next / scale) * alpha) * scale;\n  if (!Number.isFinite(result))\n    throw new RangeError(\"moving-average derived value must be finite.\");\n  return result;\n}\n\n/**\n * Derives a source-aligned simple moving average from consecutive finite observations.\n *\n * Missing, nonfinite, and excluded observations produce null and reset warmup. Results are\n * population-neutral arithmetic means; no timestamps are inferred or changed.\n *\n * @param data - Source observations, retained in their original order.\n * @param options - Value accessor, consecutive period, and optional participation callback.\n * @returns Frozen source-aligned average observations, with null during warmup and gaps.\n * @see {@link MovingAverageOptions}\n * @see {@link MovingAveragePoint}\n */\nexport function simpleMovingAverage<D>(\n  data: readonly D[],\n  options: MovingAverageOptions<D>,\n): readonly MovingAveragePoint<D>[] {\n  const observed = values(data, options);\n  const window: number[] = [];\n  return Object.freeze(\n    data.map((datum, sourceIndex) => {\n      const value = observed[sourceIndex];\n      if (value === null) {\n        window.length = 0;\n        return Object.freeze({ datum, sourceIndex, average: null });\n      }\n      window.push(value);\n      if (window.length > options.period) window.shift();\n      const average =\n        window.length === options.period ? summary(window)[0] : null;\n      return Object.freeze({ datum, sourceIndex, average });\n    }),\n  );\n}\n\n/**\n * Derives a source-aligned exponential moving average seeded by the first complete SMA window.\n *\n * Its smoothing factor is `2 / (period + 1)`. Missing, nonfinite, and excluded observations\n * produce null and reset the seed window.\n *\n * @param data - Source observations, retained in their original order.\n * @param options - Value accessor, consecutive seed period, and optional participation callback.\n * @returns Frozen source-aligned average observations, with null during warmup and gaps.\n * @see {@link MovingAverageOptions}\n * @see {@link MovingAveragePoint}\n */\nexport function exponentialMovingAverage<D>(\n  data: readonly D[],\n  options: MovingAverageOptions<D>,\n): readonly MovingAveragePoint<D>[] {\n  const observed = values(data, options);\n  const seed: number[] = [];\n  const alpha = 2 / (options.period + 1);\n  let average: number | undefined;\n  return Object.freeze(\n    data.map((datum, sourceIndex) => {\n      const value = observed[sourceIndex];\n      if (value === null) {\n        seed.length = 0;\n        average = undefined;\n        return Object.freeze({ datum, sourceIndex, average: null });\n      }\n      if (average === undefined) {\n        seed.push(value);\n        if (seed.length < options.period)\n          return Object.freeze({ datum, sourceIndex, average: null });\n        average = summary(seed)[0];\n      } else average = weighted(average, value, alpha);\n      return Object.freeze({ datum, sourceIndex, average });\n    }),\n  );\n}\n\n/**\n * Derives source-aligned Bollinger bands from trailing consecutive population-standard-deviation windows.\n *\n * Missing, nonfinite, and excluded observations produce null bands and reset warmup. The multiplier\n * defaults to 2; caller-owned data are neither sorted nor mutated.\n *\n * @param data - Source observations, retained in their original order.\n * @param options - Value accessor, period, participation callback, and optional band multiplier.\n * @returns Frozen source-aligned population-standard-deviation band observations.\n * @see {@link BollingerBandsOptions}\n * @see {@link BollingerBandPoint}\n */\nexport function bollingerBands<D>(\n  data: readonly D[],\n  options: BollingerBandsOptions<D>,\n): readonly BollingerBandPoint<D>[] {\n  const multiplier = options.multiplier ?? 2;\n  validateMultiplier(multiplier);\n  const observed = values(data, options);\n  const window: number[] = [];\n  return Object.freeze(\n    data.map((datum, sourceIndex) => {\n      const value = observed[sourceIndex];\n      if (value === null) {\n        window.length = 0;\n        return Object.freeze({\n          datum,\n          sourceIndex,\n          mean: null,\n          lower: null,\n          upper: null,\n        });\n      }\n      window.push(value);\n      if (window.length > options.period) window.shift();\n      if (window.length < options.period)\n        return Object.freeze({\n          datum,\n          sourceIndex,\n          mean: null,\n          lower: null,\n          upper: null,\n        });\n      const [mean, deviation] = summary(window);\n      const lower = mean - multiplier * deviation;\n      const upper = mean + multiplier * deviation;\n      if (!Number.isFinite(lower) || !Number.isFinite(upper))\n        throw new RangeError(\"Bollinger derived value must be finite.\");\n      return Object.freeze({ datum, sourceIndex, mean, lower, upper });\n    }),\n  );\n}\n"],
+  "mappings": "AACA,SAAS,kBAAkB,eAAe,iBAAiB;AAgF3D,SAAS,eAAe,QAAsB;AAC5C,MAAI,CAAC,OAAO,cAAc,MAAM,KAAK,UAAU;AAC7C,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AACJ;AAEA,SAAS,mBAAmB,YAA0B;AACpD,MAAI,CAAC,OAAO,SAAS,UAAU,KAAK,aAAa;AAC/C,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AACJ;AAEA,SAAS,OACP,MACA,SAC4B;AAC5B,QAAM,OAAO,UAAU,MAAM,gBAAgB;AAC7C,iBAAe,QAAQ,MAAM;AAC7B,QAAM,QAAQ,cAAc,QAAQ,KAAK;AACzC,SAAO,OAAO;AAAA,IACZ,KAAK,IAAI,CAAC,OAAO,UAAU;AACzB,UAAI,EAAE,QAAQ,UAAU,OAAO,OAAO,IAAI,KAAK,MAAO,QAAO;AAC7D,YAAM,WAAW,MAAM,OAAO,OAAO,IAAI;AACzC,aAAO,iBAAiB,QAAQ,IAAI,WAAW;AAAA,IACjD,CAAC;AAAA,EACH;AACF;AAEA,SAAS,QAAQ,QAAsD;AACrE,MAAI,QAAQ;AACZ,aAAW,SAAS,OAAQ,SAAQ,KAAK,IAAI,OAAO,KAAK,IAAI,KAAK,CAAC;AACnE,MAAI,UAAU,EAAG,QAAO,CAAC,GAAG,CAAC;AAC7B,MAAI,gBAAgB;AACpB,aAAW,SAAS,OAAQ,kBAAiB,QAAQ;AACrD,QAAM,iBAAiB,gBAAgB,OAAO;AAC9C,MAAI,uBAAuB;AAC3B,aAAW,SAAS,QAAQ;AAC1B,UAAM,aAAa,QAAQ,QAAQ;AACnC,4BAAwB,aAAa;AAAA,EACvC;AACA,QAAM,qBAAqB,uBAAuB,OAAO;AACzD,QAAM,OAAO,iBAAiB;AAC9B,QAAM,YAAY,KAAK,KAAK,kBAAkB,IAAI;AAClD,MAAI,CAAC,OAAO,SAAS,IAAI,KAAK,CAAC,OAAO,SAAS,SAAS;AACtD,UAAM,IAAI,WAAW,8CAA8C;AACrE,SAAO,CAAC,MAAM,SAAS;AACzB;AAEA,SAAS,SAAS,UAAkB,MAAc,OAAuB;AACvE,QAAM,QAAQ,KAAK,IAAI,KAAK,IAAI,QAAQ,GAAG,KAAK,IAAI,IAAI,CAAC;AACzD,MAAI,UAAU,EAAG,QAAO;AACxB,QAAM,UACF,WAAW,SAAU,IAAI,SAAU,OAAO,QAAS,SAAS;AAChE,MAAI,CAAC,OAAO,SAAS,MAAM;AACzB,UAAM,IAAI,WAAW,8CAA8C;AACrE,SAAO;AACT;AAcO,SAAS,oBACd,MACA,SACkC;AAClC,QAAM,WAAW,OAAO,MAAM,OAAO;AACrC,QAAM,SAAmB,CAAC;AAC1B,SAAO,OAAO;AAAA,IACZ,KAAK,IAAI,CAAC,OAAO,gBAAgB;AAC/B,YAAM,QAAQ,SAAS,WAAW;AAClC,UAAI,UAAU,MAAM;AAClB,eAAO,SAAS;AAChB,eAAO,OAAO,OAAO,EAAE,OAAO,aAAa,SAAS,KAAK,CAAC;AAAA,MAC5D;AACA,aAAO,KAAK,KAAK;AACjB,UAAI,OAAO,SAAS,QAAQ,OAAQ,QAAO,MAAM;AACjD,YAAM,UACJ,OAAO,WAAW,QAAQ,SAAS,QAAQ,MAAM,EAAE,CAAC,IAAI;AAC1D,aAAO,OAAO,OAAO,EAAE,OAAO,aAAa,QAAQ,CAAC;AAAA,IACtD,CAAC;AAAA,EACH;AACF;AAcO,SAAS,yBACd,MACA,SACkC;AAClC,QAAM,WAAW,OAAO,MAAM,OAAO;AACrC,QAAM,OAAiB,CAAC;AACxB,QAAM,QAAQ,KAAK,QAAQ,SAAS;AACpC,MAAI;AACJ,SAAO,OAAO;AAAA,IACZ,KAAK,IAAI,CAAC,OAAO,gBAAgB;AAC/B,YAAM,QAAQ,SAAS,WAAW;AAClC,UAAI,UAAU,MAAM;AAClB,aAAK,SAAS;AACd,kBAAU;AACV,eAAO,OAAO,OAAO,EAAE,OAAO,aAAa,SAAS,KAAK,CAAC;AAAA,MAC5D;AACA,UAAI,YAAY,QAAW;AACzB,aAAK,KAAK,KAAK;AACf,YAAI,KAAK,SAAS,QAAQ;AACxB,iBAAO,OAAO,OAAO,EAAE,OAAO,aAAa,SAAS,KAAK,CAAC;AAC5D,kBAAU,QAAQ,IAAI,EAAE,CAAC;AAAA,MAC3B,MAAO,WAAU,SAAS,SAAS,OAAO,KAAK;AAC/C,aAAO,OAAO,OAAO,EAAE,OAAO,aAAa,QAAQ,CAAC;AAAA,IACtD,CAAC;AAAA,EACH;AACF;AAcO,SAAS,eACd,MACA,SACkC;AAClC,QAAM,aAAa,QAAQ,cAAc;AACzC,qBAAmB,UAAU;AAC7B,QAAM,WAAW,OAAO,MAAM,OAAO;AACrC,QAAM,SAAmB,CAAC;AAC1B,SAAO,OAAO;AAAA,IACZ,KAAK,IAAI,CAAC,OAAO,gBAAgB;AAC/B,YAAM,QAAQ,SAAS,WAAW;AAClC,UAAI,UAAU,MAAM;AAClB,eAAO,SAAS;AAChB,eAAO,OAAO,OAAO;AAAA,UACnB;AAAA,UACA;AAAA,UACA,MAAM;AAAA,UACN,OAAO;AAAA,UACP,OAAO;AAAA,QACT,CAAC;AAAA,MACH;AACA,aAAO,KAAK,KAAK;AACjB,UAAI,OAAO,SAAS,QAAQ,OAAQ,QAAO,MAAM;AACjD,UAAI,OAAO,SAAS,QAAQ;AAC1B,eAAO,OAAO,OAAO;AAAA,UACnB;AAAA,UACA;AAAA,UACA,MAAM;AAAA,UACN,OAAO;AAAA,UACP,OAAO;AAAA,QACT,CAAC;AACH,YAAM,CAAC,MAAM,SAAS,IAAI,QAAQ,MAAM;AACxC,YAAM,QAAQ,OAAO,aAAa;AAClC,YAAM,QAAQ,OAAO,aAAa;AAClC,UAAI,CAAC,OAAO,SAAS,KAAK,KAAK,CAAC,OAAO,SAAS,KAAK;AACnD,cAAM,IAAI,WAAW,yCAAyC;AAChE,aAAO,OAAO,OAAO,EAAE,OAAO,aAAa,MAAM,OAAO,MAAM,CAAC;AAAA,IACjE,CAAC;AAAA,EACH;AACF;",
+  "names": []
+}