Qualia WASM Portal — Operator & Integrator Manual

Product name: Qualia — Semantic Subjectivity Bifurcation Portal
Version: 0.0.29 Branch: 0.0.29 Artifact: docs/pkg/qualia/qualia.js + qualia_bg.wasm
Companion: wasm-viewport-migration-plan.md, q42-acoustic-plane-draft.md

1. What this is

The Qualia WASM portal is a single cdylib that bundles:

JavaScript is glue only: import init, new QualiaPortal(canvas), resize, requestAnimationFrame(tick). No geometry, no particle engines, no spectral math in the hot path.

┌──────────── BAKE (cold, heap OK) ────────────┐
│  NQuin → Tensor10D SOA + optional STFT sidecar │
└────────────────────┬───────────────────────────┘
                     │ upload once
┌────────────────────▼───────────────────────────┐
│  GpuContext + VramLedger (U0 LLM / U1 tensor / │
│  U2 viewport / U3 acoustic — one device)       │
└────────┬───────────────────┬───────────────────┘
         │                   │
    projector.wgsl      AudioWorklet (stereo)
    ambient + bloom     SAB or MessagePort

2. Hardware tiers

QualiaPortal::new(canvas) probes WebGPU and selects a tier:

Operational modes (Full / Eco / Reserve) throttle bloom and particle draw counts via VramLedger. U3 is muted in Reserve.

3. Build & deploy

3.1 Slim portal (GitHub Pages / spatial demo)

# From repo root
$env:RUSTFLAGS = "-C target-feature=+simd128"
wasm-pack build crates/qualia-core-db `
  --target web --release --out-dir crates/qualia-core-db/pkg-qualia `
  --no-default-features -- --features portal

# Publish to docs
Copy-Item crates/qualia-core-db/pkg-qualia/qualia_core_db.js docs/pkg/qualia/qualia.js
Copy-Item crates/qualia-core-db/pkg-qualia/qualia_core_db_bg.wasm docs/pkg/qualia/qualia_bg.wasm
Copy-Item crates/qualia-core-db/pkg-qualia/qualia_core_db.d.ts docs/pkg/qualia/qualia.d.ts

Or use scripts/package-qualia-wasm.ps1 when execution policy allows.

3.2 Verification

cargo test -p qualia-core-db phenomenal_contract --lib
cargo test -p qualia-core-db audio:: --lib
node docs/tests/phenomenal-verify.mjs --wasm-api docs/pkg/qualia/qualia.d.ts
node docs/tests/wasm-size-check.mjs docs/pkg/qualia/qualia_bg.wasm

3.3 Local preview (COOP/COEP for SharedArrayBuffer)

npx --yes serve docs -p 4173

Open http://localhost:4173/spatial.html. The page registers coi-serviceworker.js on first load; reload once after the service worker activates to gain crossOriginIsolated and SAB zero-copy audio.

4. JavaScript integration

4.1 Minimal mount

import init, { QualiaPortal } from './pkg/qualia/qualia.js';
import { mountPortal, mountAcousticPlane, setAcousticEnabled } from './js/qualia-shell.js';

await init();
const canvas = document.getElementById('ambient-canvas');
const portal = await mountPortal(canvas);

function frame() {
  portal.tick(canvas, 16.67);
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);

4.2 Daemon-linked phenomenal path

qualia-shell.js provides:

• connectPortalToDaemon(portal) — GET /tensor/slice + Lamport SSE /tensor/events
• Ed25519 standpoint gate (crypto.subtle sign of canonical {nonce|class|t_slice|t_window})
• Badge states: Offline → Slice unavailable → Auth Failed → Live

4.3 U3 sonification

import { mountAcousticPlane, setAcousticEnabled } from './js/qualia-shell.js';
import { ensureCrossOriginIsolation, isCrossOriginIsolated } from './js/qualia-coi.js';

await ensureCrossOriginIsolation({ quiet: true });
await mountAcousticPlane(portal, { useSab: isCrossOriginIsolated() });
setAcousticEnabled(true, portal);
portal.set_acoustic_enabled(true);

Sync loop (inside mountAcousticPlane):

1. publish_acoustic_sab(sab) or acoustic_uniform_floats() → worklet
2. bake_stft_sidecar_demo(32) every ~2 s → preview bins refresh
3. drain_sonic_tokens(n) → token accents on the worklet thread

5. QualiaPortal API reference

5.1 Viewport & navigation

5.2 U3 AcousticPlane

Full binary layouts: q42-acoustic-plane-draft.md.

5.3 AcousticUniform float layout (82)

6. Phenomenal σ parity (vision ↔ hearing)

The same σ field drives both U2 and U3:

fract(σ) is invariant under integer wraps: sigma_to_wavelength_nm(σ) == sigma_to_wavelength_nm(σ + n).

CI oracle: cargo test -p qualia-core-db phenomenal_sigma_visual_audio_parity --lib

7. Cross-origin isolation (COOP/COEP)

Note: wgpu WebGPU does not require SAB. Only U3 zero-copy uses it.

8. Troubleshooting

9. Related documents

Qualia — where meaning meets the manifold.