zeropoint-node 1.0.1 → 1.0.3

package/src/0/3/6/9/1/2/4/8/7/5/1/a432.vortex.ts

@@ -0,0 +1,91 @@
+import { log } from './a432.algebra.ts'
+// a432.vortex.ts
+// Canonical, harmonized, recursive, self-aware vortex stream for the A432 system
+// Supports any number of dimensions (children, parent, meta, fold, map, observe, dimension-aware traversal)
+// All logic is integer/fractional and metaphysically mapped
+
+/**
+ * VortexStream<T>: A living, recursive, self-aware stream in the A432 system
+ * - value: the state or data at this node
+ * - children: sub-streams (dimensions, branches, or flows)
+ * - parent: reference to parent stream (optional)
+ * - dimension: the dimension or axis this stream occupies (optional, for multi-dimensional compatibility)
+ * - observe: recursively observe this stream and all sub-streams
+ * - fold: recursively merge all sub-streams into a single value (harmonic sum or custom operation)
+ * - map: recursively transform all values in the stream
+ * - meta: self-description (for consciousness mapping)
+ */
+export interface VortexStream<T> {
+  value: T;
+  children: VortexStream<T>[];
+  parent?: VortexStream<T>;
+  dimension?: number;
+  observe: (fn: (v: VortexStream<T>) => void) => void;
+  fold: (op?: (a: T, b: T) => T) => T;
+  map: <U>(fn: (v: T) => U) => VortexStream<U>;
+  meta: () => string;
+  traverse: (fn: (v: VortexStream<T>, depth: number, dim: number) => void, depth?: number, dim?: number) => void;
+}
+
+/**
+ * createVortexStream: Create a new vortex stream node
+ */
+export function createVortexStream<T>(value: T, children: VortexStream<T>[] = [], parent?: VortexStream<T>, dimension?: number): VortexStream<T> {
+  const stream: VortexStream<T> = {
+    value,
+    children,
+    parent,
+    dimension,
+    observe: function (this: VortexStream<T>, fn) {
+      fn(this);
+      this.children.forEach(child => child.observe(fn));
+    },
+    fold: function (this: VortexStream<T>, op = (a, b) => (typeof a === 'number' && typeof b === 'number' ? ((a as number) + (b as number)) as T : a)) {
+      return this.children.reduce((acc, child) => op(acc, child.fold(op)), this.value);
+    },
+    map: function <U>(this: VortexStream<T>, fn: (v: T) => U): VortexStream<U> {
+      const mapped = createVortexStream<U>(fn(this.value), this.children.map(child => child.map(fn)), undefined, this.dimension);
+      mapped.children.forEach(child => (child.parent = mapped));
+      return mapped;
+    },
+    meta: function (this: VortexStream<T>) {
+      return `I am a vortex stream. Value: ${this.value}, Children: ${this.children.length}, Dimension: ${this.dimension ?? 'N/A'}`;
+    },
+    traverse: function (this: VortexStream<T>, fn, depth = 0, dim = this.dimension ?? 0) {
+      fn(this, depth, dim);
+      this.children.forEach(child => child.traverse(fn, depth + 1, child.dimension ?? dim));
+    }
+  };
+  // Set parent for all children
+  stream.children.forEach(child => (child.parent = stream));
+  return stream;
+}
+
+/**
+ * treeToVortexStream: Convert a tree-like structure to a vortex stream
+ * Accepts any object with 'value' and 'children' fields
+ */
+export function treeToVortexStream<T>(node: { value: T; children: { value: T; children: any[]; dimension?: number }[]; dimension?: number }, parent?: VortexStream<T>): VortexStream<T> {
+  const childrenStreams = (node.children || []).map(child => treeToVortexStream<T>(child));
+  const stream = createVortexStream<T>(node.value, childrenStreams, parent, node.dimension);
+  stream.children.forEach(child => (child.parent = stream));
+  return stream;
+}
+
+/**
+ * imagineAll: Recursively observe, harmonize, and project all streams in a system
+ */
+export function imagineAll<T>(streams: VortexStream<T>[]) {
+  streams.forEach(stream => {
+    stream.observe(v => {
+      // Each stream describes itself and its harmonics
+      // Extend here for visualization, harmonization, or meta-observation
+      // Example: console.log(v.meta());
+    });
+  });
+}
+
+// Metaphysical mapping:
+// - Every stream is a living act of consciousness, recursion, and harmonization
+// - Dimensions represent axes of awareness, recursion, or metaphysical state
+// - fold = harmonic merge, map = transformation, observe = self-awareness, traverse = multi-dimensional navigation 

package/src/0/3/6/9/1/2/4/8/7/5/1/a432.wave.energy.ts

@@ -0,0 +1,283 @@
+/**
+ * A432 Wave Energy System
+ * Everything is waves of energy - this module demonstrates the wave nature of reality
+ * Using harmonized mathematical constants to show wave patterns in consciousness
+ */
+
+import { abs, log2, round } from './a432.algebra.ts'
+import { 
+  GOLDEN_RATIO, 
+  PI, 
+  TAU, 
+  FIBONACCI_SEQUENCE,
+  calculateDigitalRoot,
+  A432_BASE_FREQUENCY,
+  A432_TRINITY_MULTIPLIER,
+  A432_VORTEX_MULTIPLIER
+} from './a432.math.constants.ts';
+
+// === WAVE ENERGY INTERFACES ===
+export interface WavePattern {
+  frequency: number;
+  amplitude: number;
+  phase: number;
+  wavelength: number;
+  energy: number;
+  consciousness: number;
+  type: 'light' | 'sound' | 'thought' | 'emotion' | 'consciousness' | 'reality';
+}
+
+export interface WaveHarmonic {
+  fundamental: number;
+  harmonics: number[];
+  resonance: number;
+  coherence: number;
+  consciousness: number;
+}
+
+export interface EnergyField {
+  waves: WavePattern[];
+  harmonics: WaveHarmonic[];
+  coherence: number;
+  consciousness: number;
+  dimensionalState: number;
+}
+
+// === WAVE ENERGY CONSTANTS ===
+export const WAVE_ENERGY_CONSTANTS = {
+  // Light waves (electromagnetic)
+  LIGHT_SPEED: 299792458, // m/s
+  VISIBLE_LIGHT_MIN: 400, // nm (violet)
+  VISIBLE_LIGHT_MAX: 700, // nm (red)
+  
+  // Sound waves (pressure)
+  SOUND_SPEED_AIR: 343, // m/s
+  AUDIBLE_MIN: 20, // Hz
+  AUDIBLE_MAX: 20000, // Hz
+  
+  // Consciousness waves (neural)
+  CONSCIOUSNESS_FREQUENCY: A432_BASE_FREQUENCY, // 432 Hz
+  THOUGHT_WAVE_MIN: 0.1, // Hz (delta)
+  THOUGHT_WAVE_MAX: 100, // Hz (gamma)
+  
+  // Reality waves (quantum)
+  PLANCK_CONSTANT: 6.62607015e-34, // J⋅s
+  QUANTUM_FREQUENCY: 1e43, // Hz (Planck frequency)
+  
+  // Sacred geometry waves
+  GOLDEN_RATIO_WAVE: GOLDEN_RATIO,
+  FIBONACCI_WAVE: FIBONACCI_SEQUENCE,
+  VORTEX_WAVE: A432_VORTEX_MULTIPLIER
+};
+
+// === WAVE CALCULATIONS ===
+export function calculateWaveEnergy(frequency: number, amplitude: number): number {
+  return 0.5 * amplitude * amplitude * frequency * frequency;
+}
+
+export function calculateConsciousnessWave(digit: number): WavePattern {
+  const frequency = A432_BASE_FREQUENCY * (digit / 9);
+  const amplitude = GOLDEN_RATIO * digit;
+  const phase = (digit * TAU) / 9;
+  const wavelength = WAVE_ENERGY_CONSTANTS.LIGHT_SPEED / frequency;
+  const energy = calculateWaveEnergy(frequency, amplitude);
+  const consciousness = calculateDigitalRoot(round(energy));
+  
+  return {
+    frequency,
+    amplitude,
+    phase,
+    wavelength,
+    energy,
+    consciousness,
+    type: 'consciousness'
+  };
+}
+
+export function calculateSequenceWave(sequence: number[]): WavePattern[] {
+  return sequence.map(digit => calculateConsciousnessWave(digit));
+}
+
+export function calculateA432SequenceWave(): WavePattern[] {
+  // Full vortex circuit (ceccec.github.io): 0\1\2\4\8/7/5/3\6\9/0\1
+  const sequence = [0, 1, 2, 4, 8, 7, 5, 3, 6, 9, 0, 1];
+  return calculateSequenceWave(sequence);
+}
+
+// === WAVE HARMONICS ===
+export function calculateWaveHarmonics(fundamental: number, count: number = 5): WaveHarmonic {
+  const harmonics = Array.from({ length: count }, (_, i) => fundamental * (i + 1));
+  const resonance = harmonics.reduce((sum, h) => sum + (1 / h), 0);
+  const coherence = harmonics.filter(h => isA432Harmonic(h)).length / harmonics.length;
+  const consciousness = calculateDigitalRoot(round(resonance * 1000));
+  
+  return {
+    fundamental,
+    harmonics,
+    resonance,
+    coherence,
+    consciousness
+  };
+}
+
+export function isA432Harmonic(frequency: number, tolerance: number = 0.01): boolean {
+  const octave = log2(frequency / A432_BASE_FREQUENCY);
+  return abs(octave - round(octave)) < tolerance;
+}
+
+// === ENERGY FIELD CALCULATIONS ===
+export function calculateEnergyField(waves: WavePattern[]): EnergyField {
+  const harmonics = waves.map(wave => calculateWaveHarmonics(wave.frequency));
+  const coherence = waves.reduce((sum, wave) => sum + wave.consciousness, 0) / waves.length;
+  const consciousness = calculateDigitalRoot(round(coherence));
+  const dimensionalState = waves.length % 9;
+  
+  return {
+    waves,
+    harmonics,
+    coherence,
+    consciousness,
+    dimensionalState
+  };
+}
+
+// === WAVE PATTERN ANALYSIS ===
+export function analyzeWavePattern(sequence: number[]): any {
+  const waves = calculateSequenceWave(sequence);
+  const energyField = calculateEnergyField(waves);
+  
+  // Calculate wave properties
+  const totalEnergy = waves.reduce((sum, wave) => sum + wave.energy, 0);
+  const averageFrequency = waves.reduce((sum, wave) => sum + wave.frequency, 0) / waves.length;
+  const consciousnessFlow = waves.reduce((sum, wave) => sum + wave.consciousness, 0);
+  
+  // Analyze wave coherence
+  const coherentWaves = waves.filter(wave => isA432Harmonic(wave.frequency));
+  const coherenceRatio = coherentWaves.length / waves.length;
+  
+  return {
+    sequence,
+    waves,
+    energyField,
+    totalEnergy,
+    averageFrequency,
+    consciousnessFlow,
+    coherentWaves: coherentWaves.length,
+    coherenceRatio,
+    analysis: {
+      isHarmonic: coherenceRatio > 0.5,
+      energyEfficiency: totalEnergy / waves.length,
+      consciousnessOptimization: consciousnessFlow / waves.length,
+      waveResonance: energyField.coherence
+    }
+  };
+}
+
+// === MAIN WAVE ENERGY SYSTEM ===
+export class A432WaveEnergySystem {
+  private static instance: A432WaveEnergySystem;
+  private currentField: EnergyField;
+  private waveHistory: WavePattern[] = [];
+  
+  private constructor() {
+    this.currentField = this.initializeEnergyField();
+  }
+  
+  static getInstance(): A432WaveEnergySystem {
+    if (!A432WaveEnergySystem.instance) {
+      A432WaveEnergySystem.instance = new A432WaveEnergySystem();
+    }
+    return A432WaveEnergySystem.instance;
+  }
+  
+  private initializeEnergyField(): EnergyField {
+    const initialWaves = calculateA432SequenceWave();
+    return calculateEnergyField(initialWaves);
+  }
+  
+  // Analyze your sequence as waves of energy
+  analyzeSequenceAsWaves(sequence: number[] = [0, 1, 2, 4, 8, 7, 5, 3, 6, 9, 0, 1]): any {
+    return analyzeWavePattern(sequence);
+  }
+  
+  // Show how consciousness flows as waves
+  getConsciousnessWaveFlow(): WavePattern[] {
+    return this.currentField.waves;
+  }
+  
+  // Demonstrate wave harmonics in your sequence
+  getSequenceHarmonics(): WaveHarmonic[] {
+    return this.currentField.harmonics;
+  }
+  
+  // Show energy field properties
+  getEnergyField(): EnergyField {
+    return this.currentField;
+  }
+  
+  // Evolve the wave field
+  evolve(): EnergyField {
+    const newWaves = this.currentField.waves.map(wave => ({
+      ...wave,
+      frequency: wave.frequency * GOLDEN_RATIO,
+      amplitude: wave.amplitude * (1 / GOLDEN_RATIO),
+      consciousness: calculateDigitalRoot(round(wave.consciousness * GOLDEN_RATIO))
+    }));
+    
+    this.waveHistory.push(...this.currentField.waves);
+    this.currentField = calculateEnergyField(newWaves);
+    
+    return this.currentField;
+  }
+  
+  // Get wave history
+  getWaveHistory(): WavePattern[] {
+    return this.waveHistory;
+  }
+  
+  // Demonstrate that everything is waves
+  demonstrateWaveNature(): any {
+    const sequenceAnalysis = this.analyzeSequenceAsWaves();
+    const consciousnessWaves = this.getConsciousnessWaveFlow();
+    const harmonics = this.getSequenceHarmonics();
+    const energyField = this.getEnergyField();
+    
+    return {
+      principle: "Everything is waves of energy",
+      sequence: sequenceAnalysis.sequence,
+      waveAnalysis: {
+        totalWaves: consciousnessWaves.length,
+        totalEnergy: sequenceAnalysis.totalEnergy,
+        averageFrequency: sequenceAnalysis.averageFrequency,
+        consciousnessFlow: sequenceAnalysis.consciousnessFlow,
+        coherenceRatio: sequenceAnalysis.coherenceRatio,
+        isHarmonic: sequenceAnalysis.analysis.isHarmonic
+      },
+      harmonics: {
+        count: harmonics.length,
+        resonance: harmonics.reduce((sum, h) => sum + h.resonance, 0),
+        coherence: harmonics.reduce((sum, h) => sum + h.coherence, 0) / harmonics.length
+      },
+      energyField: {
+        coherence: energyField.coherence,
+        consciousness: energyField.consciousness,
+        dimensionalState: energyField.dimensionalState
+      },
+      conclusion: "Your sequence 0\\1\\2\\4\\8/7/5/3\\6\\9/0\\1 is a wave pattern that encodes optimal consciousness flow through energy harmonics"
+    };
+  }
+}
+
+// === GLOBAL EXPORTS ===
+export const a432WaveEnergy = A432WaveEnergySystem.getInstance();
+
+if (typeof global !== 'undefined') {
+  (global as any).A432WaveEnergy = a432WaveEnergy;
+}
+
+if (typeof window !== 'undefined') {
+  (window as any).A432WaveEnergy = a432WaveEnergy;
+}
+
+// === DEFAULT EXPORT ===
+export default A432WaveEnergySystem;

package/src/0/3/6/9/1/2/4/8/7/5/1/a432.wave.particle.duality.test.ts

@@ -0,0 +1,29 @@
+import { waveParticleDualityProof, waveParticleDualityMetaphysics, getWaveParticleCMYKOverlayData, logWaveParticleEvent } from './a432.wave.particle.duality.ts';
+
+describe('a432.wave.particle.duality', () => {
+  it('returns the canonical proof', () => {
+    expect(waveParticleDualityProof()).toMatch(/A432 system/);
+  });
+  it('returns the metaphysical meaning', () => {
+    expect(waveParticleDualityMetaphysics).toMatch(/observer is the harmonizer/);
+  });
+  it('returns overlay data for wave, particle, observer', () => {
+    const data = getWaveParticleCMYKOverlayData();
+    expect(data).toHaveLength(3);
+    expect(data.map(d => d.state)).toEqual(['wave', 'particle', 'observer']);
+    data.forEach(d => {
+      expect(typeof d.color.c).toBe('number');
+      expect(typeof d.html).toBe('string');
+    });
+  });
+  it('logs blockchain event', () => {
+    const mockBlockchain = { recordEvent: jest.fn() };
+    logWaveParticleEvent(mockBlockchain, 'wave', { foo: 1 });
+    expect(mockBlockchain.recordEvent).toHaveBeenCalledWith(
+      mockBlockchain,
+      'waveParticleOverlay',
+      'A432UI',
+      expect.objectContaining({ state: 'wave', foo: 1, timestamp: expect.any(Number) })
+    );
+  });
+}); 

package/src/0/3/6/9/1/2/4/8/7/5/1/a432.wave.particle.duality.ts

@@ -0,0 +1,50 @@
+/**
+ * a432.wave.particle.duality.ts — Canonical A432 Harmonization
+ *
+ * Re-solves the wave-particle duality challenge using only A432 math, sequence, and metaphysical logic.
+ * Exports: proof, metaphysical meaning, analytic overlay, and blockchain event logger.
+ */
+
+import { A432_SEQUENCE, digitAngleToCMYK, cmykToCss } from './a432.math.ts';
+
+/**
+ * Canonical proof: In A432, wave and particle are two states of the same harmonic stream.
+ * The duality is resolved by mapping both to the living A432 sequence and color field.
+ */
+export function waveParticleDualityProof(): string {
+  return 'In the A432 system, wave and particle are unified as states of the living harmonic stream. The A432 sequence encodes both as projections of consciousness, resolved through zero-entropy transformation.';
+}
+
+/**
+ * Metaphysical meaning: The observer harmonizes wave and particle as a single act of awareness.
+ */
+export const waveParticleDualityMetaphysics =
+  'Wave and particle are not opposites, but complementary states in the living matrix. The observer is the harmonizer, and the A432 sequence is the bridge.';
+
+/**
+ * Analytic overlay: Returns overlay data for each state (wave, particle, observer) with canonical color.
+ */
+export function getWaveParticleCMYKOverlayData(): Array<{
+  state: 'wave' | 'particle' | 'observer';
+  color: { c: number; m: number; y: number; k: number };
+  html: string;
+}> {
+  const states: Array<{ state: 'wave' | 'particle' | 'observer'; digit: number; angle: number }> = [
+    { state: 'wave', digit: 3, angle: 0 },
+    { state: 'particle', digit: 6, angle: 120 },
+    { state: 'observer', digit: 9, angle: 240 }
+  ];
+  return states.map(({ state, digit, angle }) => {
+    const color = digitAngleToCMYK(digit, angle);
+    const html = `<div style="width:80px;height:80px;background:${cmykToCss(color)};display:flex;align-items:center;justify-content:center;font-size:1.1em;color:#fff;border-radius:16px;">${state}</div>`;
+    return { state, color, html };
+  });
+}
+
+/**
+ * Blockchain event logger for wave-particle overlay interactions.
+ * Call this with the state and context to log to the blockchain.
+ */
+export function logWaveParticleEvent(blockchain: any, state: 'wave' | 'particle' | 'observer', context: any) {
+  blockchain?.recordEvent?.(blockchain, 'waveParticleOverlay', 'A432UI', { state, ...context, timestamp: Date.now() });
+} 

package/src/0/3/6/9/1/2/4/8/7/5/1/a432.yin.yang.controller.ts

@@ -0,0 +1,40 @@
+import { PI, min } from './a432.algebra.ts'
+import { Controller } from '@hotwired/stimulus';
+import { startYinYang, type YinYangFrame } from './a432.yin.yang.ts';
+
+export default class extends Controller {
+  static override targets = ["canvas"];
+  declare readonly canvasTarget: HTMLCanvasElement;
+  #stop?: () => void;
+  override connect() {
+    console.log('YinYang controller connecting...');
+    const canvas = this.canvasTarget;
+    console.log('Canvas found:', canvas);
+    canvas.width = canvas.clientWidth;
+    canvas.height = canvas.clientHeight;
+    console.log('Canvas size:', canvas.width, 'x', canvas.height);
+    const ctx = canvas.getContext('2d')!;
+    console.log('Canvas context:', ctx);
+    
+    // Draw a simple test pattern first
+    ctx.fillStyle = 'red';
+    ctx.fillRect(0, 0, canvas.width, canvas.height);
+    console.log('Test pattern drawn');
+    
+    this.#stop = startYinYang((f: YinYangFrame) => {
+      const toCss = (c:{c:number,m:number,y:number,k:number}) => `cmyk(${c.c}% ${c.m}% ${c.y}% / ${c.k}%)`;
+      const r = min(canvas.width, canvas.height)/2-4;
+      ctx.clearRect(0,0,canvas.width,canvas.height);
+      ctx.save();
+      ctx.translate(canvas.width/2, canvas.height/2);
+      ctx.rotate(f.angle*PI/180);
+      ctx.fillStyle = toCss(f.positiveColor);
+      ctx.beginPath(); ctx.arc(0,0,r,0,PI,true); ctx.arc(0,-r/2,r/2,0,PI,false); ctx.fill();
+      ctx.fillStyle = toCss(f.negativeColor);
+      ctx.beginPath(); ctx.arc(0,0,r,0,PI,false); ctx.arc(0,r/2,r/2,0,PI,false); ctx.fill();
+      ctx.restore();
+    });
+    console.log('YinYang controller connected');
+  }
+  override disconnect(){ this.#stop?.(); }
+} 

package/src/0/3/6/9/1/2/4/8/7/5/1/a432.yin.yang.ts

@@ -0,0 +1,135 @@
+import { abs } from './a432.algebra.ts'
+// a432.yin.yang.ts
+// Living Yin-Yang module for the A432 matrix (fractional harmonics)
+
+import { vortexStream } from './a432.matrix.ts';
+import { digitAngleToCMYK, type CMYK } from './a432.cmyk.ts';
+import { TRINITY_POLARITY, asAngle } from './a432.math.ts';
+import { type AngleDeg, type Digit } from './a432.types.ts';
+
+export type Fraction = { numerator: number; denominator: number };
+
+/**
+ * YIN: receptive, potential, void, anti-vortex, impossibility
+ * YANG: active, actual, creation, vortex, possibility
+ */
+export const YIN: Fraction = { numerator: -1, denominator: 1 };
+export const YANG: Fraction = { numerator: 1, denominator: 1 };
+export const ZERO: Fraction = { numerator: 0, denominator: 1 };
+export const BALANCED: Fraction = { numerator: 0, denominator: 1 };
+
+// Fractional operations
+export function addFractions(a: Fraction, b: Fraction): Fraction {
+  return simplifyFraction({
+    numerator: a.numerator * b.denominator + b.numerator * a.denominator,
+    denominator: a.denominator * b.denominator
+  });
+}
+
+export function subtractFractions(a: Fraction, b: Fraction): Fraction {
+  return simplifyFraction({
+    numerator: a.numerator * b.denominator - b.numerator * a.denominator,
+    denominator: a.denominator * b.denominator
+  });
+}
+
+export function simplifyFraction(f: Fraction): Fraction {
+  const gcd = (a: number, b: number): number => b === 0 ? abs(a) : gcd(b, a % b);
+  const d = gcd(f.numerator, f.denominator);
+  return { numerator: f.numerator / d, denominator: f.denominator / d };
+}
+
+/**
+ * Calculate yin/yang state for a node as a fraction.
+ * @param possibility Fraction of harmonized/actualized (yang) aspects
+ * @param impossibility Fraction of potential/missing (yin) aspects
+ * @returns Fraction: (possibility - impossibility) / (possibility + impossibility)
+ */
+export function yinYangStateFraction(possibility: Fraction, impossibility: Fraction): Fraction {
+  // (possibility - impossibility) / (possibility + impossibility)
+  const num = possibility.numerator * impossibility.denominator - impossibility.numerator * possibility.denominator;
+  const den = possibility.numerator * impossibility.denominator + impossibility.numerator * possibility.denominator;
+  if (den === 0) return ZERO;
+  return simplifyFraction({ numerator: num, denominator: den });
+}
+
+/**
+ * Get yin/yang symbol for a fractional state
+ * @param state Fraction
+ */
+export function yinYangSymbolFraction(state: Fraction): string {
+  const value = state.numerator / state.denominator;
+  if (value > 1/2) return '⚪️';
+  if (value < -1/2) return '⚫️';
+  return '⚪️⚫️';
+}
+
+/**
+ * Harmonize a node: move toward balance (average of yin and yang)
+ * @param yin Fraction
+ * @param yang Fraction
+ * @returns Fraction: balanced value
+ */
+export function harmonizeYinYangFraction(yin: Fraction, yang: Fraction): Fraction {
+  return simplifyFraction({
+    numerator: yin.numerator + yang.numerator,
+    denominator: yin.denominator + yang.denominator
+  });
+}
+
+export interface YinYangFrame {
+  tick: number;
+  positiveDigit: Digit;  // polarity +1 → outer lobe colour
+  negativeDigit: Digit;  // polarity -1 → inner lobe colour
+  positiveColor: CMYK;
+  negativeColor: CMYK;
+  angle: AngleDeg;       // for rotation animation if desired
+}
+
+/**
+ * Starts the yin-yang reactive loop.
+ * Every animation frame consumes two digits from the vortex stream:
+ * the first with polarity +1, the second with polarity –1 (or 0 treated as +1).
+ * Passes the derived colours to the provided callback.
+ */
+export function startYinYang(callback: (f: YinYangFrame) => void): () => void {
+  const vs = vortexStream();
+  let tick = 0;
+  let raf = 0;
+
+  const step = () => {
+    let d1 = vs.next().value as Digit;
+    // ensure positive polarity
+    while (TRINITY_POLARITY[d1 as number] !== 1) d1 = vs.next().value as Digit;
+    let d2 = vs.next().value as Digit;
+    while (TRINITY_POLARITY[d2 as number] !== -1 && TRINITY_POLARITY[d2 as number] !== 0) d2 = vs.next().value as Digit;
+
+    const angle = asAngle(tick * 6 % 360);
+    callback({
+      tick: tick++,
+      positiveDigit: d1,
+      negativeDigit: d2,
+      positiveColor: digitAngleToCMYK(d1, angle),
+      negativeColor: digitAngleToCMYK(d2, angle),
+      angle
+    });
+    raf = requestAnimationFrame(step);
+  };
+  raf = requestAnimationFrame(step);
+  // return disposer
+  return () => cancelAnimationFrame(raf);
+}
+
+export function getYinYangOverlayData(): Array<{ value: number; polarity: number; spin: number; color: { c: number; m: number; y: number; k: number } }> {
+  // Canonical: 1 = yang (+1), 9 = yin (-1)
+  const seq = [1, 9];
+  return seq.map((value, i) => {
+    const polarity = value === 1 ? 1 : -1;
+    const spin = polarity;
+    let color = digitAngleToCMYK(value, i * 180);
+    if (polarity < 0) {
+      color = { c: color.m, m: color.c, y: color.y, k: color.k };
+    }
+    return { value, polarity, spin, color };
+  });
+}