This document defines the coding standards and architectural patterns for the Loop 2.1 simulator. Every Claude instance working on this project must read this before writing or modifying code.

These standards describe the architecture that exists now (v.307, ~15,500 lines, 574 functions). The restructuring in v.267–v.288 established these patterns. New features must fit into this structure, not beside it.

Loop 2.1 is a single HTML file. No build step, no framework, no npm, no external dependencies beyond Google STUN servers for WebRTC. This constraint is permanent.

const loops = L21.loops;
const alu   = L21.alu;
const mem   = L21.mem;
const clock = L21.clock;

Single delegated click listener on document. Buttons declare actions via data-action="functionName" with optional data-arg, data-arg2.

<button data-action="togglePause" data-arg="working">⏸</button>

ELEMENT_RECEIVER_ACTIONS Set: functions that receive the DOM element as argument instead of parsed data attributes.

To add a button: add data-action in HTML, write the function. No listener registration needed.

renderAllComponents() is the master render, called once per frame when something changed. Render functions read from L21, write to DOM/canvas. They never modify L21. One-way flow: tick mutates state → render displays.

Dirty flags (alu.displayNeedsRefresh, mem.displayNeedsRefresh) skip expensive updates when state hasn't changed.

Bus rendering: renderBusA() calls renderUnidirectionalBus('a'). Generic functions read BUS_CONFIGS.

The bus system is the canonical example of multi-instance component structure. Study it before adding anything new:

1. Config table entry. BUS_CONFIGS[busId] — all metadata in one place.

2. Generic functions. selBusSrc(busId, id), toggleBusGeneric(busId), tickUnidirectionalBus(busId), renderUnidirectionalBus(busId). Each takes bus ID, looks up config.

3. Legacy delegates. function selCSrc(id) { selBusSrc('c', id); } — for data-action compat. Don't create new ones.

4. State in L21. L21.buses.a through L21.buses.i. Shared shape.

For any new multi-instance component: config table → generic functions → L21 state with shared shape.

1. State. New sub-object in L21. All properties, types, defaults. Const alias.
2. Config table. If multi-instance or has metadata, create/extend a table.
3. Tick logic. Add to appropriate phase. Follow hot-path rules.
4. Operator actions. Named functions per conventions. Modify L21 state.
5. HTML. data-action on buttons. No inline onclick.
6. Rendering. Read L21, write DOM/canvas. Add to renderAllComponents(). Dirty flags if expensive.
7. Snapshot. Add to both captureFullSnapshot() and restoreFromSnapshot().
8. Session log. Dual-format entries (MACHINE.CODE || Human description). OP. prefix for operator actions.
9. Tests. Initialization, key behaviors, edge cases.

captureFullSnapshot() serializes L21 to a plain object. restoreFromSnapshot(snap) writes it back. Both must be updated when L21 state changes. Values must be primitives or plain objects/arrays — no DOM refs, functions, or class instances. Exclude non-serializable values and re-derive on restore.

Dual-format: machine code left of ||, human description right.

writeLogLine('OP.BUS.A.SRC=ALU', 'Bus A source set to ALU');
writeLogLine('BUS.A.XFER w=31400', 'Bus A delivered word 31400');

Operator actions: OP. prefix. Machine events: no prefix. Log writes conditional on logger.active, guard at call site.

Major sections: // ================================================================. Sub-blocks: // ── description ──────.

Section order (approximate): Skins → Constants → L21 namespace → UI state → Net bus/P2P → Op count/loop defs/bus configs → Switch/inject → Clock/lookups → Bus sidebar/generics → Speed/clock → CBX → Challenges → Network monitor → Networking → Files → Working scratch → Tick engine → Main loop → Bus delegates → ALU → Memory → Logger → Snapshots → Sound → PM/TG → Counters → Render → Init → Event delegation.

New code goes in the matching section. If none fits, create a new section with a header comment in a logical position.

Version lives in exactly one place: const APP_VERSION = '307';. Title and UI read from it dynamically. No other version string in the file.

1. APP_VERSION updated. Search for const APP_VERSION. Change string. Confirm one instance.
2. Syntax check passes.

   sed -n '/<script>/,/<\/script>/p' file.html | sed '1d' | sed 's/<\/script>//' > /tmp/check.js && node --check /tmp/check.js

3. Test suite passes. All tests green.
4. Filename matches. loop2-stage2 (NNN).html where NNN = APP_VERSION.
5. No unrelated changes. No drive-by refactoring, no bonus features.