Skip to content

v3: replace React with Web Audio + Three.js native runtime - #1

Merged
EmergentMonk merged 15 commits into
mainfrom
upgrade/native-webaudio-threejs-v3
Sep 11, 2026
Merged

EmergentMonk merged 15 commits into
mainfrom
upgrade/native-webaudio-threejs-v3

Conversation

@EmergentMonk

@EmergentMonk EmergentMonk commented Sep 9, 2026

Copy link
Copy Markdown
Member

Summary

Massive QNTOY v3 rebuild that removes the React/Figma/Radix application stack and replaces it with a browser-native audio-visual architecture.

Runtime

  • plain semantic HTML, CSS, and JavaScript modules
  • Three.js GPU renderer for the 160×120 / 19,200-qutrit field
  • Web Audio API synth with lazy user-gesture startup
  • state-mapped oscillators, stereo panning, compressor, analyser, and entropy-coupled feedback delay
  • live analyser-driven Three.js spectrum ribbon
  • orbit / top / side camera modes

Simulation

  • browser-independent QutritField core
  • explicit seeded PRNG instead of Math.random()
  • incremental state-count tracking
  • normalized Shannon entropy
  • deterministic replay contract for equal seed + equal operation order
  • qutrit-inspired Mix / Phase / Measure operations with explicit scientific boundary wording

Data + controls

  • evolution, volume, reverb, stereo-spread, and point-size controls
  • keyboard shortcuts
  • 60-second CSV telemetry export
  • full JSON state snapshots
  • responsive accessible control rack
  • reduced-motion support

Project cleanup

  • removes React / ReactDOM / Radix UI / lucide-react / recharts / Figma component residue
  • runtime dependency surface reduced to three
  • Vite retained only as build/dev tooling
  • new architecture, roadmap, MIT license, and third-party notices

Verification

Local dependency-free verification before push:

  • node --test tests/core.test.mjs → 7/7 passing
  • node --check across all new JS modules → passing

GitHub Actions on this PR performs:

  • dependency install
  • syntax check
  • unit tests
  • production Vite build

Scientific boundary: QNTOY remains a qutrit-inspired stochastic information toy, not a physical quantum computer emulator or unitary qutrit simulator.

Summary by Sourcery

Replace the legacy React application with a deterministic browser-native QNTOY runtime that couples a Three.js qutrit field to Web Audio, accessible controls, reproducible exports, and automated verification.

New Features:

  • Rebuild QNTOY as a browser-native audio-visual instrument with semantic HTML, CSS, JavaScript modules, Three.js rendering, and Web Audio synthesis.
  • Add deterministic seeded qutrit-inspired field evolution with mixing, phase, measurement-like operations, entropy tracking, telemetry logging, and JSON snapshots.
  • Provide interactive simulation, audio, visualization, camera, accessibility, reduced-motion, keyboard, and responsive controls.

Bug Fixes:

  • Improve audio lifecycle handling, feedback initialization, spectrum clearing, CSV escaping, state validation, and reduced-motion listener cleanup.

Enhancements:

  • Reduce the runtime dependency surface to Three.js while removing the React, Radix UI, Figma residue, and legacy component stack.
  • Document the new architecture, reproducibility guarantees, scientific boundary, roadmap, licensing, and third-party notices.

Build:

  • Retain Vite for development and production builds and add Node 20 package metadata and verification scripts.

CI:

  • Add GitHub Actions coverage for dependency installation, syntax checks, unit tests, and production builds.

Documentation:

  • Rewrite the README for the v3 runtime, controls, architecture, reproducibility, telemetry, audio mapping, performance, and scientific scope.

Tests:

  • Add deterministic core, entropy, state-count, snapshot, audio lifecycle, CSV, validation, accessibility, and reduced-motion regression tests.

Chores:

  • Replace the legacy React application and UI component tree with the v3 native runtime structure.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @EmergentMonk, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 2 hours and 26 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 9, 2026

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review Completed 2026-09-09T13:36:05.529766Z 2260bb2 Manual request
🔒 Security Review Completed 2026-09-09T06:52:53.217573Z c83adb7 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@sourcery-ai

sourcery-ai Bot commented Sep 9, 2026

Copy link
Copy Markdown

Reviewer's Guide

This PR is a full v3 rewrite: it removes the React/Figma/Radix stack and implements a native HTML/CSS/ES-module application coordinated around a deterministic seeded qutrit-inspired core, with Three.js rendering, lazy Web Audio sonification, telemetry/snapshot exports, and CI-backed tests and builds.

Sequence diagram for seeded field evolution and audio-visual updates

sequenceDiagram
    participant App as app.js
    participant Core as QutritField
    participant Audio as QNTOYAudio
    participant View as QutritVisualizer

    loop simulation update
        App->>Core: step(rate)
        Core-->>App: changes
        App->>View: applyChanges(changes)
        App->>Audio: sonifyChanges(changes, field)
        Audio->>Audio: setEntropy(entropy)
        View->>Audio: getLevel()
        View->>Audio: getSpectrum()
    end
Loading

Sequence diagram for lazy Web Audio startup

sequenceDiagram
    actor User
    participant App as app.js
    participant Audio as QNTOYAudio
    participant Browser as Web Audio API

    User->>App: click START AUDIO
    App->>Audio: toggle()
    Audio->>Audio: ensureContext()
    Audio->>Browser: createAudioContext and audio graph
    Audio->>Browser: resume()
    Browser-->>Audio: running context
    Audio-->>App: enabled
    App->>Audio: chord(entropy)
Loading

Flow diagram for deterministic exports and telemetry

flowchart LR
    Field[QutritField state] --> Snapshot["snapshot()"]
    Snapshot --> JSON["downloadSnapshot()"]
    Field --> Logger[QNLogger]
    Audio[QNTOYAudio] --> Logger
    Logger --> Sample["sample() every second"]
    Sample --> CSV["toCSV()"]
    CSV --> Download[qntoy-log.csv]
Loading

File-Level Changes

Change Details Files
Replaced the framework-based application shell with a semantic, browser-native runtime and accessible control surface.
  • Added a single HTML entry point with runtime status, visualization host, transport and field-operation controls, sliders, telemetry, seed handling, exports, and keyboard affordances.
  • Reimplemented responsive styling, CRT-inspired presentation, reduced-motion behavior, and focus-visible accessibility without Tailwind or component libraries.
  • Removed the React/TSX application, Figma residue, Radix UI components, and legacy CSS/component files.
index.html
src/styles.css
src/App.tsx
src/main.tsx
src/index.css
src/styles/globals.css
src/components/
src/components/figma/
src/components/ui/
src/Attributions.md
src/guidelines/Guidelines.md
Introduced a deterministic, browser-independent three-state field simulation with incremental accounting and reproducible operations.
  • Added seeded FNV-1a hashing and Mulberry32 PRNG usage instead of Math.random().
  • Implemented Uint8Array state storage, incremental counts, normalized Shannon entropy, cycle tracking, change records, reset/reseed/randomize, and qutrit-inspired mix, phase, measure, and pulse transforms.
  • Added JSON-compatible snapshots and unit coverage for determinism, counts, entropy, operation validity, reseeding, and snapshot metadata.
src/core.js
tests/core.test.mjs
ARCHITECTURE.md
Added a lazily initialized Web Audio synthesis and feedback-processing layer driven by field changes and entropy.
  • Built state-frequency oscillators with envelopes, filters, stereo panning, capped transition sonification, pulse/chord effects, compressor, analyser, and entropy-controlled delay feedback.
  • Exposed runtime controls for volume, reverb mix, stereo spread, root frequency, analyser level, and reverb timing while keeping audio creation behind user interaction.
src/audio.js
ARCHITECTURE.md
Added a Three.js GPU visualizer that updates the qutrit field incrementally and couples rendering to analyser output.
  • Created one BufferGeometry with custom shader attributes for state height/color and audio-reactive point rendering.
  • Added reference grid, frame, FFT spectrum ribbon, orbit/top/side camera modes, resize handling, reduced-motion camera behavior, and resource disposal.
src/visualizer.js
ARCHITECTURE.md
Added a thin DOM controller, telemetry/export workflows, and automated build verification.
  • Connected model changes to visual and audio consumers, scheduled simulation at roughly 30 Hz, throttled telemetry updates, and wired controls and shortcuts.
  • Implemented one-second CSV telemetry logging for 60-second runs plus full JSON snapshot downloads.
  • Added Node/Vite scripts and GitHub Actions for dependency installation, syntax checks, tests, and production builds.
src/app.js
src/logger.js
package.json
.github/workflows/ci.yml
vite.config.js
.gitignore
Documented the new architecture, project direction, licensing, dependency notices, and scientific scope.
  • Added architecture, roadmap, MIT license, and third-party notices documentation.
  • Updated README for v3 setup, controls, reproducibility, entropy/audio mappings, performance, citation, and explicit non-physical quantum-model boundaries.
README.md
ARCHITECTURE.md
ROADMAP.md
LICENSE
THIRD_PARTY_NOTICES.md

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

Copy link
Copy Markdown
Member Author

Latest head hardening complete at 4cc52cd: seeded PRNG now wraps to uint32 per draw, with a 100,000-draw regression test. Local suite is 8/8 and GitHub CI run #2 is fully green (install, syntax, tests, production build).

@codex review
@codex security review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4cc52cd372

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/audio.js Outdated
Comment thread src/logger.js Outdated
Comment thread src/logger.js Outdated
Comment thread src/app.js
Comment thread src/audio.js Outdated
Comment thread src/app.js Outdated
Comment thread src/core.js Outdated

Copy link
Copy Markdown
Member Author

Fixed all Codex P2 findings in 51739fcd and resolved the review threads.

Key changes:

  • STOP AUDIO now hard-mutes immediately, closes the active AudioContext to clear voices/delay tails, and rebuilds a clean graph on restart.
  • Initial wet/dry, delay, feedback, and master parameters are assigned directly before graph connection; smoothing is only used after startup.
  • CSV output now uses a proper field encoder that doubles embedded quotes and quotes comma/newline-containing values.
  • Global shortcuts ignore focused interactive elements, preserving native Space activation on buttons and controls.
  • Normal evolution now respects the 120 ms telemetry throttle; user-triggered operations still force immediate telemetry refreshes.
  • replaceStates() validates original snapshot values before Uint8Array conversion, rejecting fractional/out-of-range/string values without mutating the field.
  • Added 5 focused regression tests for these cases.

Verification on head 51739fcd: dependency install ✅, syntax check ✅, unit tests ✅, production build ✅.

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 51739fcd54

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/audio.js Outdated
Comment thread src/visualizer.js Outdated
Comment thread src/audio.js Outdated
Comment thread src/core.js Outdated

Copy link
Copy Markdown
Member Author

Fixed the latest four Codex P2 findings on final head 463c4bcc:

  • audio graph now initializes from the current field entropy; entropy is cached even before an AudioContext exists and toggleAudio() supplies the field entropy before graph creation
  • reduced-motion mode freezes the shader uTime uniform so the 19,200-point surface no longer procedurally undulates
  • getSpectrum() now zeroes the caller-supplied FFT buffer whenever audio is disabled or no analyser exists, preventing a frozen stale ribbon after STOP AUDIO
  • setState() now rejects non-integer indexes before typed-array access/count mutation

Regression coverage added for entropy-aware graph creation, disabled-spectrum clearing, and fractional-index count integrity.

CI run #5 on this head passed dependency install, syntax check, unit tests, and production Vite build.

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 463c4bcc10

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/visualizer.js Outdated
Comment thread src/audio.js Outdated
Comment thread index.html Outdated

Copy link
Copy Markdown
Member Author

Fixed the latest three P2 findings on head 9e5293071b690a6665b14bb1f65ff5adf7dfa8a8:

  • reduced-motion now gates uAudio, uTime, FFT ribbon motion, and live ribbon opacity so audio cannot keep the visual surface breathing/pulsing;
  • audio toggles are serialized in both the engine and UI continuation path, with regression coverage for overlapping start/stop requests;
  • all three state-distribution meters now have explicit accessible names via aria-labelledby, with a static regression check.

CI run #10 passed install, syntax checks, unit tests, and the production Vite build. All three corresponding review threads have been resolved.

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9e5293071b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/audio.js Outdated

Copy link
Copy Markdown
Member Author

Fixed the latest P2 on head 42da85b9 by replacing queued opposite audio transitions with coalesced in-flight transitions. While START/STOP is pending, overlapping activations share the same transition, the audio button is disabled with aria-busy, and keyboard repeat is ignored. A replacement AudioContext can therefore only be started by a fresh later user gesture. Regression coverage now includes both overlapping STARTs and the previously missing audio-on → overlapping STOPs → fresh restart sequence. CI run #13 is fully green (install, syntax, tests, production build).

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 42da85b9f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/visualizer.js Outdated

Copy link
Copy Markdown
Member Author

Fixed the live prefers-reduced-motion tracking P2 on head 2260bb23004d18d56b13dfbcfc496f7e6503e7ec.

Changes:

  • store the MediaQueryList and subscribe to its change event
  • update reducedMotion immediately when the preference changes
  • stop/re-enable orbit auto-rotation according to the active view
  • immediately zero motion/audio shader uniforms, flatten the spectrum, and reset point-cloud rotation when reduced motion is enabled
  • support legacy addListener/removeListener fallbacks
  • unregister the media-query listener during dispose()
  • add regression coverage for listener registration, live state handling, orbit policy, and cleanup

Verification: CI run #15 passed dependency install, syntax checks, unit tests, and production build.

@codex review

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sourcery assessment

Approved.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: 2260bb2300

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@EmergentMonk
EmergentMonk merged commit 1d4cfbd into main Sep 11, 2026
2 checks passed
@EmergentMonk
EmergentMonk deleted the upgrade/native-webaudio-threejs-v3 branch September 11, 2026 09:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant