Skip to content

Level meter improvements - #57

Merged
danigb merged 35 commits into
mainfrom
level-meter
Sep 12, 2026
Merged

danigb merged 35 commits into
mainfrom
level-meter

Conversation

@danigb

@danigb danigb commented Sep 12, 2026

Copy link
Copy Markdown
Owner

Made with Claude

danigb and others added 30 commits September 8, 2026 16:25
process() returned the literal true, so this.r was recorded and never read and
dispose() never stopped the processor. Twenty-two packages return this.r.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
src/processor.ts -> src/worklet.ts (hand-written) and src/_processor.ts ->
src/processor.ts (generated bundle), matching all 22 other packages, and the
level-meter special case comes out of .github/workflows/test.yml. Adds the
"test": "jest" script the package never had, and a comment on why index.ts
hand-rolls new AudioWorkletNode instead of using createWorkletConstructor.

No behaviour change; the tests land in the next commit.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
test-utils.ts (createWorkletTestContext copied from state-variable-filter, plus
runProcess) and worklet.test.ts with the six groups: pass-through, attack,
release, silence, channel bounds and disposal.

Five assertions are written against intended behaviour and fail today, marked
it.failing with the ticket that fixes each. They reproduce the audit's numbers
exactly: a full-scale sample reads -19.99999987 dB, the fall rate is 36x the
declared 8.7 dB/s and differs by sample rate, an empty inputs[0] freezes the
reading, and channels 9 and up come out silent.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
Split attack from release, derive the rate from sampleRate, and add a hold
marker and a clip latch.

  peak = blockPeak > peak * decay ? blockPeak : peak * decay

where decay is 10^(-releaseDbPerSecond * 128/sampleRate / 20), computed once at
construction. Instant attack falls out of the comparison; the release is one
multiply; and because the constant depends on sampleRate, the reading does not.

Defaults are K-Meter's - releaseDbPerSecond 8.7 (26 dB / 3 s), holdMs 1500,
clipHoldMs 1500, clipThreshold 1 - all overridable through processorOptions and
none of them AudioParams. Peak state flushes to exact zero below 1e-10 so
silence reads -Infinity rather than -200 dB: a correctness fix, not a
performance one.

The attack and release groups from 02 now pass, including agreement across
44.1, 48 and 96 kHz, and hold and clip get groups of their own. The hold marker
and clip latch stay processor-internal until 06 gives the buffer a layout.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
Separate the three numbers one loop conflated. Copy is bounded by
min(input.length, output.length) and runs outside the measurement loop;
measurement is bounded by min(input.length, peaks.length); and the decay runs
over every slot, every block, including when input.length is 0. this.max is
gone.

index.ts validates maxChannels - an integer from 1 to 32, RangeError otherwise -
instead of turning 0 into 16 through an || and handing everything else to the
buffer constructor.

The pass-through, silence and channel-bounds groups from 02 now pass; no
it.failing assertions remain. Adds src/index.test.ts for the factory's own
surface.

thoughts/modules-status.md:61 still says the processor caps at 8 and is now
false - a parent-repo edit, not made here.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
Feature-detect crossOriginIsolated && SharedArrayBuffer. Shared when both are
there - today's path, unchanged - and otherwise the processor owns the buffer
and posts a copy of it every postIntervalMs (default 16 ms), which the main
thread copies into the same view shape. getLevels() reads the same view and
returns the same numbers either way; meter.transport says which is running.

Defines the versioned layout both transports carry - [0] version, [1] channel
count, [2] clip flags, then a fixed stride of 4 per channel and a 2-slot tail -
with the rms, true-peak and LUFS slots reserved and unwritten so 06, 10 and 11
do not each bump the version.

The channel count survives a disconnected input: an empty inputs[0] is "nothing
this block", not "zero channels", and reporting 0 would hide 04's decay.

maxChannels now tops out at 24 rather than 32: the clip flags are one bit per
channel in one Float32, which holds integers exactly only to 2^24. The 04
changeset is corrected to match.

README's COOP/COEP paragraph is replaced with a note that shared memory is an
upgrade.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
A rewrite of `meter-ui.ts`, plus the shared animation-frame driver in its own
file so ticket 16's `subscribe` can reuse it without importing the renderer.

`{minDb: -12, maxDb: 0}` placed a gradient stop at -0.5 and threw
`IndexSizeError` on the first frame, inside the caller's `requestAnimationFrame`.
Every stop now goes through `dbToUnit`, which clamps; all six ranges in the
ticket's table render. The range is validated at construction, where it is
findable.

Also from §C7/§C8: the context-bound gradient and pattern are dropped on
`setCanvas`; `attach(canvas, meter)` owns the loop, the `ResizeObserver` and the
`devicePixelRatio` sizing, and `detach()` leaves neither pending; the bar layout
shrinks the inter-channel gap instead of the bar, so eight channels in 10 px
still draw eight bars rather than none; the stripe tile comes from
`OffscreenCanvas` or a clone of the target canvas, never `document`; and
`orientation` is read.

New: the RMS bar inset in the peak bar, the hold marker, a latching clip
indicator in its own slice at the top of the scale, a dB scale with ticks, and
colours as options with today's green/yellow/red as the defaults.

`setCanvas()` + `render(levels)` stays the manual path; `render` no longer takes
a channel count (ticket 06). `Levels` is declared locally until 06 lands.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
The loudness algorithm of ITU-R BS.1770-5, as a module with no Web Audio in
it: `sampleRate` is an argument, nothing is allocated after construction, and
channels arrive as `Float32Array[]`. Ticket 09's `dsp.ts` will re-export it;
until then it stands on its own so the conformance work is not waiting on the
extraction.

  kWeightingCoefficients(sampleRate)   both biquads, derived - never a table
  createLoudnessAnalyzer(...)          100 ms blocks, M (4) and S (30)

The derivation is the point. BS.1770-5 publishes coefficients only at 48 kHz
and a browser AudioContext is 44.1 as often as 48, so the analog design is kept
and the bilinear transform re-applied at the target rate. At 48 kHz that
reproduces all ten published coefficients to within 1e-12.

The 2.58e-5 residual the ticket recorded on the shelf's b0/b2 turned out to be
avoidable, not inherent: it is the textbook RBJ shelf's `Vb = sqrt(Vh)`.
libebur128 uses `Vb = Vh^0.4996667741545416`, and with it the residual
disappears into the last bit. The test still asserts a tolerance rather than
equality, and pins the RBJ variant's 2.58e-5 alongside it so the exponent
cannot be "simplified" back without the failure naming its own cause.

Conformance: EBU Tech 3341 cases 1, 2, 6, 9-14, synthesised from the table's
own descriptions rather than vendored as fixtures. Cases 13 and 14 walk a
400 ms tone past the 100 ms accumulation grid in 20 ms steps, which a meter
built on block powers rather than a 400 ms audio ring cannot follow exactly;
the bound is arithmetic (`gridQuantisationDb`), the four tones per case that
do land on the grid are asserted at the document's own +/-0.1 LU, and the rest
against the bound.

Also: a silent channel reads -Infinity rather than the ring-out of the tone it
used to carry, and channel weights default to 1.0 with the BS.1770 Table 3
vectors exported to be passed deliberately - nothing infers a layout from a
channel count.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
Stage 4 of BS.1770-5 on top of the same 100 ms accumulator: the gating block
of eq (3) is the momentary window emitted once per block, which is already the
400 ms block at 75% overlap the standard asks for. So Integrated costs one
histogram, not a second pass.

  ABSOLUTE_GATE_LUFS = -70            eq (6), Tech 3341 2.3, Tech 3342 5
  INTEGRATED_RELATIVE_GATE_LU = -10   eq (6), Tech 3341 2.3
  LRA_RELATIVE_GATE_LU = -20          Tech 3342 3.1

The two relative gates are different numbers and getting them crossed is
silent - both produce a plausible reading - so each is a named constant citing
its clause, and a test asserts all three.

Memory is O(1) in programme length: 1000 bins of 0.1 LU from the absolute gate,
so both gates are a re-scan of 1000 bins at query time. Two departures from the
plan, both deliberate:

- The ticket said "1000 bins, -70 to +5 LU at 0.1 LU", which is 750 bins. The
  bin count and the 4 KB figure both fix 1000 at 0.1 LU, so the range is -70
  to +30 - libebur128's, and past anything a digital signal reaches.
- Each bin also carries the exact summed energy, 8 KB more. Counts alone would
  answer both gates, but then the gated mean is built from bin centres and
  carries up to 0.05 LU against an EBU tolerance of +/-0.1. With the energies
  the mean is exact and only the threshold is quantised. Percentiles still use
  the centres, where 0.1 LU sits inside Tech 3342's +/-1 LU.

Session control per Tech 3341 2.2 and 2.4: startIntegration / stopIntegration
(the document's 'stand-by') / resetIntegration, the last clearing both
histograms because 2.4 says LRA resets with Integrated. Integration is on from
construction so an offline call - where the programme is the buffer - needs no
ceremony.

Conformance: Tech 3341 cases 3, 4, 5 and 6 for Integrated, Tech 3342 cases 1-4
for LRA. 3342 #4 is also the test of the -20 LU gate, since the two -50 dBFS
segments sit above the absolute gate and below the relative one - without the
relative stage it reads 30 LU, not 15. For the absolute gate, appending 130 s
of -80 dBFS to a programme changes the reading by exactly nothing (`toBe`),
and 3341 #4 reads as #3 does. For the relative gate, 20 s at -23 followed by
20 s at -43 reads -23, where an absolute-only meter reports the -26 mean.

`gainToTarget(-23, -14)` is 9. Returns dB and leaves applying it to the caller:
normalising a buffer has to think about the true-peak ceiling.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
Per-sample RMS one-pole on the mean square, time constant from sampleRate,
default 600 ms to 99 % of a step (K-Meter's average meter, not the peak's
release). One sqrt per block per channel; state flushed to zero below 1e-20 so
silence reads -Infinity. Channels with no input this block get the coefficient
raised to the block length once, which is the same answer as 128 zeros without
the loop.

getLevels() returns one reused, allocation-free object over the layout 05
defined: channelCount, peak/hold/rms/truePeak/clipped per channel, clearClip(),
momentary/shortTerm, error, snapshot() and version. Everything in dB; the raw
view stays linear. truePeak, momentary and shortTerm read NaN while their
measurement is off, so "not measured" is distinguishable from "silent".

version and snapshot() are implemented rather than stubbed: version advances
only when the view's contents change, which is what useSyncExternalStore needs
and what 16 would otherwise have had to add. readView() is the single
main-thread hook both live in.

readView() also checks the layout word, so registering two builds of the
processor in one context fails loudly instead of reading a stride that moved.

getPeaks() is kept and marked @deprecated.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
this.n was written in the constructor and never read - the loops bound
themselves on the views' own lengths.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
Conformance is the exit criterion, so the ring changes shape rather than the
standard. The accumulation grid drops from 100 ms to 20 ms: Momentary is the
last 20 slots, Short-term the last 150.

Tech 3341 #13 and #14 walk a 400 ms tone past the grid in 20 ms steps, and on
a 100 ms grid the best-placed window covered as little as 360 ms of a tone
offset by 40 ms - 0.46 LU low at eight of the twenty offsets, asserted against
an arithmetic bound because the document's +/-0.1 LU was out of reach. On a
20 ms grid every offset those cases use lands on the grid, so both now assert
-23.0 and -38+i at the document's own tolerance with nothing subtracted.
`gridQuantisationDb` and the comment that explained it are gone; nothing else
needed them.

The gating is untouched. BS.1770-5 eq (3)'s 400 ms block at a 100 ms hop is now
"the last 20 sub-blocks, every fifth one" - `GATING_HOP_SUB_BLOCKS` - so the
histograms see exactly the blocks they saw before. Measured over 5 minutes of
48 kHz stereo, both versions read the same integrated loudness to the last
digit (-23.091), which is the check that the hop really did not move.

Cost, same measurement: 128 ms against 141 ms for the 100 ms version, ~2300x
realtime. Not slower - `process()` still hands the filter loop 128-sample
runs, and only the ring bookkeeping got more frequent. Memory is 120 more ring
slots per channel and nothing that grows with the programme.

Why 20 and not some other number: it is the coarsest grid #13 and #14 can be
read on, and it divides every sample rate in practical use into whole samples
(960 at 48 kHz, 882 at 44.1, 1920 at 96). A test asserts that across the whole
CD/DAT family; the docstring on SUB_BLOCK_MS says why it must not be raised
back to 100.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
`getLevels()` is pull, and it was the only thing the package offered. Everyone
who does not want a canvas - a React component, a Svelte store, a div whose
width is a percentage - had to write their own animation loop, decide how to
throttle it, and re-derive the dB-to-pixel clamp that §C7 shows the package
itself got wrong.

- `meter.subscribe(listener)` returns the unsubscribe. Under `"message"` a
  posted frame is the trigger; under `"shared"` memory has no events, so 07's
  module-level driver is. Both go through one gate keyed on `version` and the
  driver's frame counter, so a subscriber is told at most once per animation
  frame on either transport, and not at all while nothing is changing. Turn
  `postIntervalMs` down and the extra messages coalesce rather than waking React
  four times between paints; the tick delivers whatever a message could not, so
  no update is lost.
- Subscribers ref-count the same driver renderers use. No subscriber and no
  attached renderer means no frame pending. `dispose()` drops both - composed
  with `disposable()`, not replacing its cascade.
- `dbToUnit` and `formatDb` are re-exported from the main entry, from the file
  the renderer already uses them in. One implementation, two callers.
- `meter-ui.ts` drops its local `Levels` and imports 06's, type-only so the
  cycle back to `index.ts` is erased.

`version` and `snapshot()` were already right in 06 and needed nothing here.

README gains "Build your own": the DOM meter, the React hook and the canvas
one. The first two are pasted from `index.test.ts`, which runs them against a
stubbed DOM and a twelve-line stand-in for React's `useSyncExternalStore`
contract; the third is what `meter-ui.test.ts`'s attach group runs. The stale
`render(peaks, 2)` call and the "only horizontal" note went with them.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
`site/examples/LevelMeterExample.tsx` draws one meter twice - the DOM recipe
beside the canvas renderer, reading the same `getLevels()` - over a percussive
source, which is what makes peak, RMS, the hold marker and the clip latch four
visibly different things. It is also the first example page to prove the two
recipes work as pasted, and a standing check of the shared animation frame:
two renderers on one page, one callback.

`meter.subscribe` is stable for the life of the node, so the React recipe hands
it to `useSyncExternalStore` directly rather than wrapping it in a closure that
would make React resubscribe on every render - and, in this design, stop and
restart the shared driver each time. Said so on the method.

The docs page (`site/content/docs/(effects)/level-meter.mdx`) still teaches an
API that does not exist and does not mount this component; that is ticket 13.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
src/dsp.ts is createLevelAnalyzer(sampleRate, options) with process() /
results() / flush() / reset(), holding exactly the peak, hold, clip and RMS
behaviour 03/04/06 established and no worklet globals. worklet.ts is a thin
per-quantum driver over it; the proof that nothing moved is that 02's suite
passes unmodified - 45 tests, untouched.

results(into) writes the layout in place, so the worklet hands over its shared
or posted buffer and no copy happens anywhere. The ballistics run on a fixed
128-sample frame and process() carries a partial frame across calls, so chunking
cannot move a reading: offline and realtime leave the buffer byte-identical over
the same samples, asserted in offline.test.ts.

src/offline.ts is analyze(channels, sampleRate, options) - chunked, yielding
between chunks, onProgress per chunk - plus analyzeAudioBuffer(), the adapter,
in the offline entry rather than the core. Non-Float32 input goes through a
Float32Array first, which is Math.fround in bulk.

Both packages get an exports map with . and ./dsp, keeping main/module/types
alongside, and a second tsup entry. A synthlet-source condition on ./dsp points
at the source, which is what lets one package's worklet bundle another's DSP
in-repo with no build ordering; tsconfig paths and the jest moduleNameMapper
resolve the same subpath for tsc and ts-jest.

lookahead-limiter/src/dsp-entry.ts publishes createTruePeakDetector (and the
limiter API) while leaving createSlidingMin internal. dsp.test.ts asserts the
subpath reaches it, and that the ./dsp bundle - built by the test with esbuild,
not read from dist/ - contains no PROCESSOR string.

truePeak and loudness options are accepted and default off; 10 and 11 fill them.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
To meter a connection you had to break it: disconnect the edge, reconnect
through the meter, and put it back on `dispose()`, which nothing helped you
with. `LevelMeter.tap(source)` adds a second outgoing edge instead - additive,
reversible, and with nothing downstream that a thrown processor could silence.
The context comes from the node, so there is none to pass.

The browser check the ticket asks to record. A `numberOfOutputs: 0` worklet
node counting its own `process()` calls for 2 s, against
`elapsed * sampleRate / 128`, in Chrome 152 on macOS 15 (headful; headless
agreed to the block):

  variant                                       outputs  calls  expected  ratio  with audio
  A  tap, source also reaches the destination         0    652       652  1.000         652
  B  tap, source NOT connected to the destination     0    652       652  1.000         652
  C  control, pass-through in the signal path         1    652       652  1.000         652
  D  tap with nothing connected to its input          0    652       652  1.000           0

B is the load-bearing case and it is not pruned: full block rate, real signal.
D shows the node is rendered even with nothing on its input. **Firefox and
Safari are unverified on this machine** - Firefox is not installed, and Safari's
autoplay policy needs a real gesture with no command-line flag to bypass it.
The page that produced this is not in the repo; the README states the result
and the zero-gain-sink fallback.

`onprocessorerror` is handled in both forms. A dead processor was
indistinguishable from a silent signal - the browser stops calling `process()`
for good and the readings simply stop moving - so it now sets the flag the
accessor already exposed and calls an optional `onError`.

Both forms are one `createMeter`, differing only in the number of outputs; each
entry point wraps it in `disposable()`, and `tap` adds the incoming edge to the
cascade rather than replacing it.

The checklist's "skip the copy loop entirely when there are no outputs" is
folded into 15, which deletes the copy loop and the output outright: the
processor becomes `numberOfOutputs: 0` always, and pass-through becomes a native
`GainNode` with a tap beside it. Not polished here, per the ticket's own note.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
`createRegistrar` stores the `addModule` promise on the context before it
settles, so concurrent callers share one registration. It also stored the
rejection: a CSP that blocks `blob:`, a context that was closed, a dev-server
hiccup, and every later `register*Worklet(ctx)` on that context returned the
same failure forever, with no way to retry (§S3).

That was tolerable while registration was an explicit call a developer could
watch fail. It stops being tolerable in the next commit, where
`LevelMeter.tap` registers implicitly and a cached failure is invisible - so it
is fixed here, first, and in the shared contract rather than in one package.

`scripts/_worklet.ts` plus the copy in all 23 packages, made by
`bash scripts/copy_files.sh`; `worklet-copies.test.ts` passes, which is what
proves the fix reached every one of them. The regression test goes through
`registerLevelMeterWorklet`, since that is `createRegistrar`'s output and this
is the package the caching matters to.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
createTruePeakDetector, imported from @synthlet/lookahead-limiter/dsp, one
instance per channel, driven from dsp.ts and writing the layout slot 06
reserved. Same ballistics as the sample peak - instant attack, the same
release - with its own state; the layout has one slot for it, so there is no
separate true-peak hold marker and the stride does not move. Sample peak stays
reported alongside. TRUE_PEAK_CEILING_DBTP (-1, EBU R 128) is exported for
renderers.

Opt-in, and here is why. 5 min of 48 kHz stereo, best of 3:

  truePeak: false    207 ms    1.84 us/block   1449x realtime
  truePeak: true    2188 ms   19.45 us/block    137x realtime   (10.6x)

With it off no detector is allocated and the reserved slot is not written.

Both meter-specific optimisations were measured and NEITHER was taken, so
lookahead-limiter/src/dsp.ts is unchanged. Best of 5, 60 s of 48 kHz stereo,
per detector call, against the shipped modulo version:

                        loud    quiet   sparse
  walking index (no %)  0.88x   0.97x    1.19x
  + cannot-win bound    0.58x   0.85x    1.88x

Dropping the modulo is slower on the loud material people actually meter - V8
handles the constant modulus better than the branch handles the loop - and the
windowMax * sum|taps| early-out loses 42% on loud audio, paying only on
material that is mostly near-silence. The plan predicted the second one; the
first is the surprise.

A channel that stops arriving is drained with TP_HISTORY zeros and then costs
nothing, so 14 unused slots of a 16-channel buffer do not pay for a detector
nobody reads, and a channel that returns does not reconstruct the window it
left behind.

The meter's dBTP is asserted equal to the limiter's own detector on the same
signal, and within 0.1 dB of a full-scale sine from 60 Hz to 10 kHz - the same
bound lookahead-limiter asserts. Offline equals realtime with truePeak on as
well as off.

@synthlet/level-meter now depends on @synthlet/lookahead-limiter. The graph
stays acyclic: the limiter has no @synthlet dependencies.

index.ts is NOT in this commit - Agent B has ~300 uncommitted lines there for
15/16. Its four small edits for this ticket (the truePeak option, the
processorOptions field, the accessor reading slot +3, and the
TRUE_PEAK_CEILING_DBTP re-export) are in the working tree.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
The `loudness` option reaches the core, and the two tail slots reach the
reader. `dsp.ts` already carries the wiring - it went in with ticket 10's
commit, which is what two agents in one file looks like - so what lands here is
the factory's half and the suite that holds the seam.

  createLevelAnalyzer(sr, { loudness: true, channelWeights })
  analyze(channels, sr, { loudness: true })   -> momentary, shortTerm
  LevelMeter.tap(source, { loudness: true })  -> levels.momentary / .shortTerm

`./dsp` now re-exports the loudness surface, so `kWeightingCoefficients`,
`createLoudnessAnalyzer`, `gainToTarget` and BS.1770-5's constants are
importable without pulling the worklet in behind them.

**The buffer never holds NaN.** "Not measured" and "silent" are different
answers, and it is tempting to put the first one in the tail - but `NaN` does
not equal itself, so `readView`'s change check would fire on every block and
wake every subscriber sixty times a second over a reading that never moved. So
the tail holds a real number or stays untouched, and the accessor is what maps
"off" to `NaN` - the same arrangement true peak already uses.

Silence is the other half of that: with the measurement on, a silent channel
reads `-Infinity` through the accessor, not a floor.

Cost, since `loudness: false` has to stay free. `createLevelAnalyzer` over 5
minutes of 48 kHz stereo in 128-sample blocks, best of three:

  loudness: false   282 ms for 300 s   (1064x realtime)
  loudness: true    897 ms for 300 s    (334x realtime)

So loudness roughly triples the meter's own cost rather than rounding into it -
worth knowing, and still 334x realtime, still well under ticket 10's true-peak
path. With the option off the core is never constructed and the per-block call
is a `?.` that finds nothing, which is what "costs nothing measurable" means
here. No timing assertion in the suite: this machine is running three agents'
suites at once and a bound loose enough to survive that would assert nothing.

`index.ts` here also carries Agent A's in-flight ticket-14 restructure
(`ready`, `engine`, the `GainNode` pass-through); it is theirs, and it is in
this commit because the file cannot be staged in halves.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
`LevelMeter.tap(source)` is now the whole thing: no context argument, no
`registerLevelMeterWorklet` call to forget, no `await`. The docs page forgot
that call (§C9), which is not carelessness - it is what happens when the step
with nothing to do with metering is the one that has to come first.

The trick is that a tap has no output, so nothing downstream can notice it is
not connected yet. `tap` returns synchronously; `ready` registers the worklet,
builds the node and connects the edge. Until then the view is zero-filled, so
`getLevels()` reads `channelCount` 0 and `-Infinity` everywhere and never
throws, `subscribe` fires nothing, and `dispose()` cancels the pending connect
without building anything.

Pass-through is a native `GainNode` with a tap beside it. The audio never waits
for registration, there is no JavaScript in the signal path, and §S2 closes in
both modes: a dead processor has nothing downstream left to silence.
`LevelMeterNode` is the type; `LevelMeterWorkletNode` stays as a deprecated
alias for one release.

Also here: `output` for multi-output nodes; a named error for a node with no
outputs that says what to tap instead (`ac.destination` is the one people reach
for first); `BaseAudioContext` throughout, which needed `createRegistrar`
widened from `AudioContext` in `scripts/_worklet.ts` - a pure widening, no
caller breaks, copied to all 23 packages and checked by
`worklet-copies.test.ts`. That is a second change to the shared contract beyond
the rejection-cache fix, so it is called out rather than buried.

`src/index.ts` for this ticket is not in this commit: Agent A picked it up in
3a518b2 ("Level meter 11: loudness through both drivers") while it was still
uncommitted here. Nothing was lost - it is the same code - but the attribution
is wrong and this note is where it is recorded.

Still outstanding, and deliberately not committed: `worklet.ts` loses the copy
loop and its output (`numberOfOutputs: 0` always) and `worklet.test.ts` loses
the pass-through group. Both edits are made in the working tree, but both files
also carry Agent A's in-flight ticket 12 work, and `processor.ts` is a bundle of
the whole file - so committing mine would commit theirs, which is currently
failing one of its own assertions. It lands as soon as 12 is in.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
The example built the meter as a pass-through and threaded the graph through
it. With `LevelMeter.tap(input)` the meter is a second edge off the node it
measures: the chain above is written as if the meter were not there, which is
the point of the ticket and the one place in the repo where it runs in a real
browser.

`LevelMeterTap` rather than the deprecated `LevelMeterWorkletNode`, and the
compound owns a teardown callback rather than a node, since a tap is no longer
one.

Unverified: `site/node_modules` is not installed in this worktree, so this file
has been prettier-checked and read against the package's types but never
compiled or run.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
Momentary and Short-term are readings. Integrated is not - it is defined over a
programme, and the original audit deferred it on exactly that ground: "a
synthesiser that has been running since page load has no programme". The two
drivers answer that differently, and the option that says so is `integrate`:

  offline    integrate: true   the buffer *is* the programme
  realtime   integrate: false  startIntegration() is where one begins

  const { integrated, lra } = await analyze(channels, sr, { loudness: true });
  meter.startIntegration(); meter.integrated; meter.resetIntegration();

**The tail grows by one slot**, to three. Integrated rides the same transport as
everything else rather than a message of its own, so it arrives with the ungated
readings and `"shared"` still has nothing to post at all. Nothing else moves -
same header, same stride, same `LEVELS_LAYOUT_VERSION`, which has not shipped
yet - and the three duplicated `TAIL` constants (`index.ts` and two test files)
move with it.

**No LRA slot.** Tech 3342 describes a whole programme and asks a meter to warn
that the value is unstable for the first 60 s; as a live readout it is close to
meaningless. `analyze()` returns it and nothing else does.

`meter.integrated` is on the node, not on `Levels`. A renderer is handed
`Levels`, and ticket 12 asks that integrated not appear in the default UI - a
number that only means something relative to a boundary somebody set invites
being read as though it always did. What a renderer cannot see it cannot draw.

Session commands sent before the worklet exists are queued and delivered on
attach. `startIntegration()` in the line after `LevelMeter.tap(source)` has to
mean the same thing as one a second later, or the programme boundary depends on
how fast registration happened.

Tests: offline and realtime integrate to the same LUFS on the same input once
the session is declared, on a signal whose quiet half is above the -70 LUFS
absolute gate and below the -10 LU relative one - so agreement is agreement
about gating, not about arithmetic that never gated. Plus Tech 3342 case 1
(LRA = 10 +/-1 LU) through `analyze`, the command sequence, the queued command,
and `gainToTarget(-23, -14) === 9` from `./dsp`.

README: the delivery-target table, dated, with EBU R 128's -23.0 LUFS and
-1 dBTP quoted from recommendations h and m. The streaming row is marked as an
approximation that is not verified here, because those numbers drift and a
README that pretends otherwise is worse than one that says so.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
The docs page taught an API that did not exist: LevelMeterUI called without
new, a .peaks property that was never a property, and a LevelMeter(ac) that
threw because nothing registered the worklet. Three hard failures in a
fifteen-line sample, and no example component at all - the page was text and
two broken code blocks, because a demo was structurally impossible while the
factory required a cross-origin isolated page.

Rewritten against the API as it is: LevelMeter.tap(node) first, pass-through
second, the canvas renderer and subscribe, what it measures with the
ballistics table, the opt-ins and what they cost, offline, and the transport
note. LevelMeterExample is mounted.

Verified by running it, not by reading it. The static export was served over
plain http with no COOP or COEP headers and driven in headless Chrome:
crossOriginIsolated false, SharedArrayBuffer undefined, the example opens, two
canvases paint, and the readout goes from -inf to -4.9 dB when triggered.
That is 05's success criterion 4 and 13's criterion 2, short of the deploy.

Adds .changeset/level-meter-folder.md: the release note for the whole folder,
led by the ballistics change, with the migration for getPeaks(),
registerLevelMeterWorklet and the COOP/COEP headers nobody needs any more.

The package README is C's - it lands with their loudness wiring, and the two
were read against each other before this was written.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
A master meter in ExamplePane, so every docs page with an example shows what
it is putting out. LevelMeter.tap(synth) is the whole of it - a Compound is
its output node - disposed with the synth. The pane cannot see the synth its
children build, so the pane creates a slot, useSynth fills it, and MasterMeter
taps whatever lands in it; no example component changed and two panes on one
page each get their own. The meter stays out of useSynth: the hook builds the
synth, the pane owns the chrome.

That also makes 08's assumption a permanent soak test: every visitor to every
example page runs a numberOfOutputs: 0 worklet node in their browser.

synthlet/dsp: the umbrella's first exports map, re-exporting
@synthlet/level-meter/dsp and @synthlet/lookahead-limiter/dsp with the same
shape and the same synthlet-source condition as 09, so the pattern is decided
twice by the same rule. dsp.test.ts asserts it resolves under
testEnvironment: node with no AudioContext in scope, and that the bundle
carries none of the twenty-three worklet strings.

site/content/docs/metering-and-loudness.mdx: the three questions a meter
answers, the two AnalyserNode correctness arguments, which number to want and
what each costs, the delivery-targets table (the same one, same date and
sources, as the README's), and the offline recipe. Cross-links both ways with
the limiter page.

Everything in the guide was run before it was written, in headless Chrome on
plain http:

  - the offline recipe printed -6.92 LUFS integrated, gainToTarget -7.08 dB,
    and -14.00000000034 LUFS after applying it, with true peak -13.09 dBTP.
    The numbers in the comments are those numbers.
  - the master meter is present and moving on the built state-variable-filter
    page, 128x24, aria-label "Output level".

Tone interop, verified against Tone 15.0.4: it is NOT one line. Tone's default
context is a ponyfill - rawContext is a wrapper with _nativeAudioContext
underneath, its nodes are not instanceof AudioNode, and LevelMeter.tap throws
"AudioWorklet not supported" on it. Tone.setContext(new AudioContext()) makes
rawContext native, and then a native GainNode with Tone connected into it taps
in one line: -6.000 dBFS from an Oscillator at volume -6, -0.00002 dBFS at
unity. The guide says that, and says why.

Left for later, as the brief asks: useSynth and the Synth type still take an
AudioContext rather than a BaseAudioContext - instrument/07 has not landed.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
Rewritten around what the package is for. The old one led with the package's
biggest liability sold as its headline feature - "the peaks live in a
SharedArrayBuffer, so reading them costs nothing" - which is what kept the meter
off its own documentation site. That is now one paragraph at the bottom, under
"Transport", saying no headers are needed.

The order is the ticket's: what it is (the one-line tap, first thing on the
page), why not `AnalyserNode`, quick start, tap or pass-through, what it
measures, the two opt-in measurements with what they cost, offline analysis as a
section rather than a footnote, the delivery targets, then the recipes.

**The `AnalyserNode` comparison leads with correctness, not convenience.**
`AnalyserNode` down-mixes to mono before it analyses, so a stereo bus with a hot
right channel reads as neither channel; and it only ever shows the last
`fftSize` samples at the moment you ask, so a dropped frame or a 30 fps loop
never sees what happened in between. A worklet sees every sample, which is the
entire point of a peak meter. The old README offered only the convenience
argument, which is the weakest of the three.

Costs are measured rather than asserted. CPU time over five minutes of 48 kHz
stereo, best of twelve runs, because wall time on this machine is worthless
right now:

  peak, hold, clip, RMS     74 ms   ~4100x realtime
  ... plus loudness        181 ms   ~1700x realtime
  ... plus true peak       3.3 s      ~91x realtime

The true-peak figure lines up with the audit's own 3.1 s / 97x, which is the
check that the number means anything.

**Every code sample runs.** `src/readme.test.ts` pastes each one and executes it
against Web Audio stubs, with the offline ones running for real against no stubs
at all - `analyze` on a synthesised EBU tone reads -23 LUFS, and the
normalisation round trip lands on -14. The three "Build your own" recipes are
not duplicated there: `index.test.ts` and `meter-ui.test.ts` already paste and
run them, and two copies of a sample is one copy too many.

Kept as they were: B's one-line `tap` framing, the pass-through and
browser-support notes, the `subscribe` section and all three recipes. Not added:
a "Works on http" section - ticket 14 has not landed, and a README should not
describe a driver that does not exist yet.

The delivery-target table is the one from ticket 12, unchanged, and matches the
site guide's row for row.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
`AudioWorklet` is `[SecureContext]` in the Web Audio IDL, so on a page that is
not a secure context `ac.audioWorklet` is not a rejected promise or a feature
flag - it is `undefined`, and every ticket in this folder so far ran behind the
throw that produces. A phone on the LAN, an intranet tool, a kiosk, an https
page inside an http iframe. `localhost` is a secure context, which is exactly
why it works on every developer's machine and fails on the first device that is
not one.

`src/script-processor.ts` is a second realtime driver over the *same* core:
`createScriptProcessor(bufferSize, inputChannels, 1)`, results written straight
into the levels view - same thread as the reader, so no transport at all - and
16's subscribers fired once per buffer. A zero-gain sink to the destination
keeps Chrome calling it, which is 08's named fallback applied where it is known
to be needed.

Engine selection lives in the factory, not the registrar: no `audioWorklet` ->
script processor immediately and synchronously, since there is nothing to wait
for; registration *rejects* (a CSP that blocks `blob:`) -> script processor,
which is the seam 15 left in `ready`. `ready` now rejects only when no engine
can run. `engine: "script-processor"` forces it, which is how the fallback stays
testable from https. `meter.engine` is a live getter beside `meter.transport`.

Deviation from the checklist, deliberately. It says to slice `inputBuffer` into
128-frame quanta, on the grounds that a 1024-frame buffer fed to the core in one
call "would decay once where the worklet decays eight times". That stopped being
true when 09 landed: `createLevelAnalyzer.process` carries a partial frame
across calls and applies the ballistics once per `ANALYSIS_FRAME`, so slicing in
the driver would be the same arithmetic written twice. The driver makes one
call, and `script-processor.test.ts` asserts the two engines produce *equal*
level buffers - at every allowed buffer size, with true peak and loudness on and
off, and across a 1024-frame buffer of silence where the release has to fall
eight times. That is success criterion 2, asserted rather than observed.

Browser check, headless Chrome 152 on macOS, engine forced on an https page: it
meters. `engine` reads "script-processor", `channelCount` 2, peak 0 dBFS,
rms -3.021 dB, and a worklet meter on the same oscillator reads -3.002 - 0.02 dB
apart, which is the moment each was sampled. Cost per 1024-frame stereo buffer,
21.3 ms of audio:

  peak/hold/RMS/clip        7.5 us    0.035 % of realtime
  + loudness               18.3 us    0.086 %
  + truePeak              261.7 us    1.23 %
  both                    271.7 us    1.27 %

True peak is again the expensive one, by a factor of ~23 over the loudness path
here - the same 48 MACs per sample per channel the worklet runs.

Not verified, and not verifiable from here: a real plain-http page from a real
phone, and Firefox, Safari and iOS Safari. Firefox is not installed on this
machine and Safari's autoplay policy needs a gesture with no flag to bypass it.

The README's "Works on http" section is written but not in this commit: the file
is Agent C's now and carries their uncommitted rewrite, so it lands with theirs.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
The true-peak cost appeared as "~10.6× everything else in the meter put
together" in four places and as "11× the loudness path" in a fifth, and neither
ratio reproduces against the code as it now stands. The absolute cost does: A's
changeset measured 2188 ms per 5 minutes of 48 kHz stereo, a later CPU-time
measurement of the same code gets roughly 3.3 s, and B's in-browser figure for
the script-processor engine works out at about 3.7 s. Three independent
measurements, one number.

What moved is the denominator. A's run had 207 ms in it for everything else;
measured as CPU time, best of twelve, peak/hold/clip/RMS is 74 ms and 181 ms with
loudness on. So the same true-peak cost is 10.6x, 18x or 44x depending on what
you divide by, and none of those is wrong - the ratio was just never the stable
part.

So every document now leads with the absolute figures and says "more than
everything else in the meter put together, by better than an order of magnitude",
which is true under every denominator anyone has measured. Where a ratio still
reads better - the level-meter docs page - it names what it is a ratio of. The
true-peak changeset keeps A's measurement block and explains why the ratio it
implies is not the one the other documents quote, rather than quietly disagreeing
with it.

Also reconciled, beyond the four files this was scoped to:

- `.changeset/level-meter-dsp-subpath.md`, which had the same claim as "11× the
  loudness path" - a sixth place, and a different denominator again.
- `packages/level-meter/src/index.ts`, the `truePeak` option's JSDoc, which is
  the copy users actually see in an editor tooltip. That edit is **not in this
  commit**: `index.ts` currently imports an untracked `./_levels` from another
  agent's in-flight refactor, so committing it would break HEAD. It is in the
  working tree for whoever lands that file next.

No contradiction found between B's "Works on http" README section and the two
mdx pages: neither page mentions secure contexts or the `script-processor`
engine at all. That is a gap rather than a disagreement, and it belongs to
whoever writes 14's docs half.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
The README grew a "Works on http" section when ticket 14 landed; the site still
described a package that only ran on https, without saying so. A reader on the
docs page had no way to learn that `ac.audioWorklet` is `undefined` on a phone
on the LAN, or that the meter already handles it.

`level-meter.mdx` gets the section, between "Offline" and "Transport": what
`[SecureContext]` means in practice, the same `tap` call on both, `meter.engine`,
the `ScriptProcessorNode` driver over the same core, when it is chosen, and
`{ engine: "script-processor" }` to force it. Facts are the README's; the site's
job is to be shorter and to link out for the rest.

Three things the page says that the README does not have to:

- **The demo above cannot show it.** GitHub Pages is https, so the example on
  this page is always on the worklet. Forcing the engine is the only way to see
  the other one from here, which is worth saying on the page that carries the
  demo.
- **"Transport" now opens by saying which question it answers.** Engine and
  transport were two feature-detected diagnostics with similar-sounding names
  and no statement of the difference; the guide gets a two-row table putting
  them side by side, since it was the page already listing `transport`.
- **The verification caveat travels with the claims.** Headless Chrome 152 with
  the engine forced, agreeing with a worklet meter to 0.02 dB - and not a real
  plain-http page from a real phone, and not Firefox, Safari or iOS Safari. A
  public page that keeps the measurements and drops the "not checked" list is
  the version of this section worth avoiding.

B's per-buffer cost table is cited rather than restated: 7.5 µs for peak, hold,
RMS and clip, 18.3 with loudness, 261.7 with true peak, per 1024-frame buffer -
attributed to the README, which is where it was measured.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
…in reduction

`lookahead-limiter` computes a gain every sample and showed none of it. Its own
plan deferred the readout "pending the SharedArrayBuffer decision"; ticket 05
made that decision and nothing had picked it up, so its demo still asked the
listener to *hear* a ceiling hold - the one thing a limiter is supposed to make
inaudible.

The second problem was that there was about to be a second transport. After
05, 06 and 16 `level-meter` owned a contract - versioned slot layout, shared
buffer or postMessage, accessor, version, subscribe - and a limiter writing its
own would mean `LevelMeterUI` could draw only one of them.

**Note for reviewers of a level-meter branch: this commit changes
`lookahead-limiter` too, and `scripts/`.**

`scripts/_levels.ts` is that contract, **moved rather than rewritten**: the
header, the SAB-or-post selection, the reader, the writer, `version`,
`subscribe`, and the module-level animation frame that used to be
`level-meter/src/driver.ts`. `level-meter` now uses the copy, and every test
from 05, 06 and 16 passes unchanged - which is criterion 6, and the only guard
worth having on a move. `copy_files.sh` gains the opt-in `LEVELS_FILE` rule and
`worklet-copies.test.ts` the matching group, naming `level-meter` and
`lookahead-limiter`, so the two copies cannot drift.

The limiter: `{ meter: true }`, default off for the same reason `truePeak` and
`loudness` are - it sits at the end of every master chain and most have nothing
reading this. When on, the processor writes the block's largest reduction,
`20·log10` of the smallest gain applied, into one slot. The gain is already
computed per sample and `dsp.ts` already hands it back through `gainOut`, so
metering reads the number rather than recomputing it: no DSP change at all.
`limiter.getLevels().gainReduction`, `limiter.subscribe(fn)`,
`limiter.transport`. With the meter off the processor allocates nothing for it,
never touches the port, and its `processorOptions` are byte-for-byte what they
were - which is what its two existing assertions check.

`LevelMeterUI` gains `mode: "reduction"`: one bar hanging *down* from 0 dB, the
way every GR meter draws it. It is one branch - which end of the axis the bar is
anchored to - over the same `fill` the peak bar uses, because the reduction
reading is adapted into a one-channel `Levels` first. That is criterion 4 meant
literally.

The limiter's example draws it, and its README and docs page carry the option,
the reading, and the line that it is the same contract as
`@synthlet/level-meter`.

Also here, and not part of the ticket: `state-variable-filter`'s registration
test stubbed `addModule` as a bare `jest.fn()` returning `undefined`. My ticket
15 registrar fix attaches a `.catch` to clear the cache on rejection, so that
stub started throwing - a regression I introduced in 19ef8fd and did not catch
because I had been running only this folder's tests. The stub now resolves, as
the real `addModule` does. `npx jest` over the whole repo is green: 2616 tests,
78 suites.

Both worklet bundles regenerated and committed.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
Ticket 10 added @synthlet/lookahead-limiter to @synthlet/level-meter's
package.json - the meter measures dBTP with the limiter's own detector - but
package-lock.json was never regenerated, so the lock did not record it.

npm ci tolerates it today only by accident: the umbrella package depends on
the limiter too, so the workspace symlink exists either way and the import
resolves. It would stop being true the moment the umbrella's dependency
changed or level-meter was installed on its own.

npm install --package-lock-only, unedited. The seven dropped "peer": true
markers are npm's own normalisation of root devDependencies it now records as
direct rather than peer-installed; no resolved version changed.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
danigb and others added 5 commits September 8, 2026 18:19
site/.source/index.js is generated by fumadocs-mdx on postinstall and on every
site build, and it is tracked. Its import order follows the order the content
directories are read in, so (modifiers) and (modulators) swap places between
runs on different filesystems; this is the output three consecutive runs here
agree on.

No content change - the entries are identical, only their order differs. CI
does not build the site, so nothing in .github/workflows/test.yml reads this
file; it is committed so the tree is clean.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
Reverts e1f06af. Its premise was wrong: site/.source/index.js is not stable
across runs. `npx fumadocs-mdx` and `next build` enumerate the content
directories in different orders, and the interleaving of (modifiers) and
(modulators) changes between runs of the same command - so committing any one
ordering fixes nothing and the next site build dirties the file again.

The file is generated, it is tracked, and its churn predates this branch. CI
does not build the site, so nothing in .github/workflows/test.yml reads it.
Leaving it at the ordering ticket 18 committed keeps this branch's diff to what
the branch actually changed.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
**The loudness windows froze when the input went away.**
`createLoudnessAnalyzer.process()` returned early on an empty `channels`, so a
worklet whose input is unconnected - which Chrome delivers as an empty
`inputs[0]`, passed straight through by the driver with an explicit length -
stopped advancing the M/S windows entirely. They held the last tone forever.
That is the exact freeze ticket 04 removed from the peak, still present one
measurement over.

An empty `channels` with a length is now "nothing arrived this block", not "no
time passed". No channel is fed, so `blockHasSignal` stays 0 everywhere and
`finishSubBlock` writes zeros into the ring and flushes the filter state for
every channel seen so far; the readings fall to -Infinity over the window
instead of sticking. Without a length there is still nothing to advance by, so
`process([])` alone is unchanged.

The gating hop keeps ticking through it, and the histograms barely notice: the
three 400 ms blocks that straddle the end of the tone hold signal and enter the
histogram as they would at any level change, and after that nothing does - a
gating block of pure silence has zero energy, so its loudness is -Infinity,
which is not above the -70 LUFS absolute gate of eq (6). The test asserts both
halves: the reading moves by less than 0.05 LU as the tone ends, and is then
bit-identical after a further minute of nothing.

Tested at both levels - directly on the core, and through
`createLevelAnalyzer({ loudness: true })`, which is the path the worklet
actually takes.

**Cost text.** `dsp.ts` (the `truePeak` option and the comment in
`createLevelAnalyzer`) and `offline.ts`'s header still said true peak costs
"11x the entire loudness path", the last of the ratios that do not reproduce.
They now carry the absolute figures and "more than everything else in the meter
put together by better than an order of magnitude", matching the README, the
site and the changesets.

`processor.ts` regenerated: `dsp.ts` and `loudness.ts` are both bundled into the
worklet, and the fix is a behaviour change on the audio thread.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
…esets)

**One source of truth for the layout.** `index.ts` carried its own `HEADER`,
`STRIDE`, `TAIL`, `levelsLength`, `toDb` and a copy of the slot map in a
comment, all of which `dsp.ts` already exports - and `dsp.ts` has been in the
main-thread bundle since 14, through `script-processor.ts`, so there was nothing
to save by duplicating them. It imports them now, reads fields by name
(`levelIndex(c, LEVEL_HOLD)` rather than `slot(c) + 1`, `view[tail +
TAIL_INTEGRATED]` rather than `+ 2`), and re-exports `LEVELS_LAYOUT_VERSION`
from the core so the published surface is unchanged. The comment claiming the
layout was "duplicated in `worklet.ts`" was describing the state before 09.

`worklet.test.ts` and `index.test.ts` each redeclared the same four constants -
which is why the tail growing to 3 needed an edit in both, and why either could
have gone on passing the day it disagreed with the core. They import them too.

**The limiter's `transport` is `undefined` while its meter is off**, rather than
`"message"`, which described a transport that does not exist: with `meter:
false` nothing is allocated, nothing is posted and there is nothing being
carried. Typed and documented as such.

**Changesets.** `@synthlet/lookahead-limiter` had none at all, despite gaining
the `./dsp` subpath (09), the `meter` option with `getLevels()`/`subscribe()`
(17) and the `_levels.ts` copy - so `@synthlet/level-meter` would have shipped
depending on `^0.2.0` and importing a `./dsp` subpath the published 0.2.0 does
not have. A minor changeset for the limiter fixes that at the root:
`updateInternalDependencies` is `"patch"`, so `changeset version` rewrites the
meter's range to the limiter's new `^0.3.0`. `npx changeset status` confirms
both are in the release at minor, so no range needs bumping by hand.

And one patch changeset for the registrar change, listing all 25 packages whose
`src/_worklet.ts` it touched - the rejection is no longer cached, and
`createRegistrar` takes a `BaseAudioContext`. Cross-checked name by name against
`changeset status`.

No worklet source changed, so no bundle was regenerated.
`npx jest packages/level-meter packages/lookahead-limiter`: 422 tests, 12
suites, green.

Claude-Session: https://claude.ai/code/session_01CJPiXRX7L6KzgBvdxuPnX8
@danigb
danigb merged commit 8803cbc into main Sep 12, 2026
1 check passed
@danigb
danigb deleted the level-meter branch September 12, 2026 15:01
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