more reviewing, thinking about atom bundles...

not sure what the standalone repo is going to be yet, but it will be relatively permissive since this is prototype/educational setup

.vscode/cozy-and-windy/README.md

@@ -0,0 +1,26 @@
+# Cozy and Windy
+
+Editor theme ported from the Rider scheme of the same name.
+
+It colors the editor surface, C/C++ syntax, and tape-atom DSL keywords
+emitted by `local.tape-atom-syntax`. It does not change workbench chrome.
+
+## Install
+
+```powershell
+cd C:\projects\Pikuma\ps1\.vscode\cozy-and-windy
+npm run package
+code --install-extension .\cozy-and-windy-0.1.0.vsix --force
+```
+
+Reload the window. Select **Cozy and Windy** as the color theme, or set
+`workbench.colorTheme` to `Cozy and Windy` in the PS1 workspace settings.
+
+Keep `local.tape-atom-syntax` installed. This theme colors those token
+types; it does not classify them.
+
+## Inspect
+
+Open `hello_camera.atom.c` and run **Developer: Inspect Editor Tokens and Scopes**
+on `MipsAtom_`, an atom name, `atom_info`, `R_PrimCursor`, a `gte_*` call,
+and a `mac_*` call.

.vscode/cozy-and-windy/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "cozy-and-windy",
+	"displayName": "Cozy and Windy",
+	"description": "Editor theme ported from the Rider Cozy and Windy scheme. Colors C/C++ and tape-atom DSL keywords.",
+	"publisher": "local",
+	"version": "0.1.0",
+	"engines": {
+		"vscode": "^1.80.0"
+	},
+	"categories": [
+		"Themes"
+	],
+	"scripts": {
+		"package": "npx --yes @vscode/vsce@3.6.1 package --allow-missing-repository --skip-license --out cozy-and-windy-0.1.0.vsix"
+	},
+	"contributes": {
+		"themes": [
+			{
+				"label": "Cozy and Windy",
+				"uiTheme": "vs-dark",
+				"path": "./themes/cozy-and-windy-color-theme.json"
+			}
+		]
+	}
+}

.vscode/cozy-and-windy/themes/cozy-and-windy-color-theme.json

@@ -0,0 +1,132 @@
+{
+	"name": "Cozy and Windy",
+	"type": "dark",
+	"semanticHighlighting": true,
+	"colors": {
+		// 121212
+		// 111212
+		// 211f1e
+		// 191817
+		"editor.background": "#191817",
+		"editor.foreground": "#dfc6ba",
+		"editor.lineHighlightBackground": "#1c1c1c",
+		"editor.selectionBackground": "#164371",
+		"editor.selectionForeground": "#c8c8c8",
+		"editorLineNumber.foreground": "#43c3c3",
+		"editorLineNumber.activeForeground": "#00fff4",
+		"editorIndentGuide.background1": "#181818",
+		"editorIndentGuide.activeBackground1": "#202020",
+		"editorRuler.foreground": "#505050",
+		"editorGutter.background": "#211f1e",
+		"editorBracketMatch.background": "#3b514d",
+		"editor.foldBackground": "#0c0c0c6a",
+		"editor.wordHighlightBackground": "#211f1e4d",
+		"editor.wordHighlightStrongBackground": "#303030",
+		"editorCursor.foreground": "#00fff4",
+		"editorWhitespace.foreground": "#181818",
+		// "editorLineHighlightBorder": "#1c1c1c",
+		"editorWidget.background": "#211f1e",
+		"editorSuggestWidget.background": "#2c334b",
+		"editorHoverWidget.background": "#2c334b"
+	},
+	"semanticTokenColors": {
+		"comment": { "foreground": "#868686", "fontStyle": "italic" },
+		"keyword": { "foreground": "#d8bd5b" },
+		"string": { "foreground": "#d46a54" },
+		"number": { "foreground": "#b5cea8" },
+		"operator": { "foreground": "#be8e78" },
+		"class": { "foreground": "#54a4d6" },
+		"struct": { "foreground": "#54a4d6" },
+		"enum": { "foreground": "#54a4d6" },
+		"type": { "foreground": "#54a4d6" },
+		"interface": { "foreground": "#7984ab" },
+		"function": { "foreground": "#cccab5" },
+		// "function": { "foreground": "#6090a9" },
+		"method": { "foreground": "#6090a9" },
+		"variable": { "foreground": "#bc966c" },
+		"parameter": { "foreground": "#ce8365" },
+		"property": { "foreground": "#acb8c8" },
+		"*.static": { "foreground": "#9e95c6" },
+		"macro": { "foreground": "#5ea852" },
+		"namespace": { "foreground": "#8e8e8e" },
+		"typeParameter": { "foreground": "#b8d7a3" },
+		"enumMember": { "foreground": "#a373b0" },
+		"label": { "foreground": "#c8c8c8", "fontStyle": "bold" },
+		"tapeAtomKeyword": { "foreground": "#d8bd5b", "fontStyle": "bold" },
+		"tapeAtomName": { "foreground": "#b1b7d6", "fontStyle": "bold" },
+		"tapeComponentKeyword": { "foreground": "#d68a36", "fontStyle": "bold" },
+		"tapeComponentName": { "foreground": "#b1b7d6", "fontStyle": "bold" },
+		"tapeAnnotation": { "foreground": "#d8bd5b" },
+		"tapeBindType": { "foreground": "#54a4d6" },
+		"tapePhase": { "foreground": "#b8d7a3", "fontStyle": "italic" },
+		"tapeLabel": { "foreground": "#959595", "fontStyle": "bold" },
+		// "tapeCpuInstruction": { "foreground": "#6d9aa0" },
+		// "tapeCpuInstruction": { "foreground": "#cf7539" },
+		// "tapeCpuInstruction": { "foreground": "#d16b3a" },
+		"tapeCpuInstruction": { "foreground": "#d5895a" },
+		"tapeGteInstruction": { "foreground": "#988bcb" },
+		"tapeGpuInstruction": { "foreground": "#bf7dac" },
+		"tapeComponentInstruction": { "foreground": "#8baa5d" },
+		// "tapeGprRegister": { "foreground": "#92d4d9" },
+		"tapeGprRegister": { "foreground": "#a2bfa8" },
+		"tapeCop2Register": { "foreground": "#945cd9" },
+		"tapeDuffleType": { "foreground": "#54a4d6" },
+		"tapeAttribute": { "foreground": "#73a07c" },
+		"tapeGprRegister.tapeRead": { "foreground": "#5bb8b0", "fontStyle": "italic" },
+		"tapeGprRegister.tapeWrite": { "foreground": "#2d8f8c", "fontStyle": "bold" },
+		"tapeCop2Register.tapeRead": { "foreground": "#b08ae0", "fontStyle": "italic" },
+		"tapeCop2Register.tapeWrite": { "foreground": "#7b3ec4", "fontStyle": "bold" },
+		// "*.tapeAuto": { },
+		"tapeControlFlow": { "foreground": "#63d169", "fontStyle": "bold" },
+		"tapeDelaySlot": { "foreground": "#ff5647" }
+	},
+	"tokenColors": [
+		{ "scope": ["comment", "comment.block", "comment.line", "comment.block.documentation"], "settings": { "foreground": "#868686", "fontStyle": "italic" } },
+		{ "scope": ["keyword", "keyword.control", "keyword.other"], "settings": { "foreground": "#d8bd5b" } },
+		{ "scope": ["string", "string.quoted"], "settings": { "foreground": "#d46a54" } },
+		{ "scope": ["string.quoted.other"], "settings": { "foreground": "#d69d85" } },
+		{ "scope": ["constant.numeric"], "settings": { "foreground": "#b5cea8" } },
+		{ "scope": ["punctuation", "keyword.operator"], "settings": { "foreground": "#be8e78" } },
+		{ "scope": ["keyword.operator.overload"], "settings": { "foreground": "#b87e76" } },
+		{ "scope": ["entity.name.type", "entity.name.type.class", "entity.name.type.struct", "entity.name.type.enum"], "settings": { "foreground": "#54a4d6" } },
+		{ "scope": ["entity.name.type.interface"], "settings": { "foreground": "#7984ab" } },
+		{ "scope": ["entity.name.function"], "settings": { "foreground": "#cccab5" } },
+		{ "scope": ["entity.name.function.member"], "settings": { "foreground": "#6090a9" } },
+		{ "scope": ["variable.other.local"], "settings": { "foreground": "#bc966c" } },
+		{ "scope": ["variable.parameter"], "settings": { "foreground": "#ce8365" } },
+		{ "scope": ["variable.other.property"], "settings": { "foreground": "#acb8c8" } },
+		{ "scope": ["variable.other.constant"], "settings": { "foreground": "#9e95c6" } },
+		{ "scope": ["variable.other.global", "variable.other.defaultLibrary"], "settings": { "foreground": "#bf7dac" } },
+		{ "scope": ["support.type", "support.function"], "settings": { "foreground": "#8baa5d" } },
+		{ "scope": ["meta.preprocessor"], "settings": { "foreground": "#5ea852" } },
+		// { "scope": ["variable.parameter.preprocessor"], "settings": { "foreground": "#636363" } },
+		{ "scope": ["variable.parameter.preprocessor"], "settings": { "foreground": "#bc966c" } },
+		{ "scope": ["keyword.control.directive"], "settings": { "foreground": "#d68a36" } },
+		{ "scope": ["entity.name.namespace"], "settings": { "foreground": "#8e8e8e" } },
+		{ "scope": ["entity.name.type.parameter"], "settings": { "foreground": "#b8d7a3" } },
+		{ "scope": ["variable.other.enummember"], "settings": { "foreground": "#a373b0" } },
+		{ "scope": ["entity.name.type.concept"], "settings": { "foreground": "#76ff7d" } },
+		{ "scope": ["entity.name.type.dependent"], "settings": { "foreground": "#448b5a", "fontStyle": "bold" } },
+		{ "scope": ["entity.name.label"], "settings": { "foreground": "#c8c8c8", "fontStyle": "bold" } },
+		{ "scope": ["invalid"], "settings": { "foreground": "#ff5647" } },
+		{ "scope": ["keyword.codetag.todo"], "settings": { "foreground": "#c10000", "fontStyle": "bold italic" } },
+		{ "scope": ["keyword.control.duffle.atom"], "settings": { "foreground": "#d8bd5b", "fontStyle": "bold" } },
+		{ "scope": ["entity.name.function.duffle.atom"], "settings": { "foreground": "#cccab5", "fontStyle": "bold" } },
+		{ "scope": ["keyword.control.duffle.component"], "settings": { "foreground": "#d68a36", "fontStyle": "bold" } },
+		{ "scope": ["entity.name.function.duffle.component"], "settings": { "foreground": "#6090a9", "fontStyle": "bold" } },
+		{ "scope": ["support.function.duffle.annotation"], "settings": { "foreground": "#d8bd5b" } },
+		{ "scope": ["entity.name.type.duffle.bind"], "settings": { "foreground": "#54a4d6" } },
+		{ "scope": ["entity.name.tag.duffle.phase"], "settings": { "foreground": "#b8d7a3", "fontStyle": "italic" } },
+		{ "scope": ["entity.name.label.duffle.atom"], "settings": { "foreground": "#c8c8c8", "fontStyle": "bold" } },
+		{ "scope": ["support.function.duffle.cpu"], "settings": { "foreground": "#6d9aa0" } },
+		{ "scope": ["support.function.duffle.gte"], "settings": { "foreground": "#988bcb" } },
+		{ "scope": ["support.function.duffle.gpu"], "settings": { "foreground": "#bf7dac" } },
+		{ "scope": ["support.function.duffle.component"], "settings": { "foreground": "#8baa5d" } },
+		{ "scope": ["keyword.control.duffle.branch"], "settings": { "foreground": "#76ff7d", "fontStyle": "bold" } },
+		{ "scope": ["keyword.operator.duffle.delayslot"], "settings": { "foreground": "#ff5647" } },
+		{ "scope": ["variable.other.constant.duffle.gpr"], "settings": { "foreground": "#3fa8a6" } },
+		{ "scope": ["variable.other.constant.duffle.cop2"], "settings": { "foreground": "#945cd9" } },
+		{ "scope": ["storage.type.duffle.type"], "settings": { "foreground": "#54a4d6" } },
+		{ "scope": ["storage.modifier.duffle.attr"], "settings": { "foreground": "#73a07c" } }
+	]
+}

.vscode/install_extensions.ps1

@@ -0,0 +1,43 @@
+# Package and install the local VS Code Insiders extensions under .vscode/.
+# Usage:
+#   .\install_extensions.ps1
+#   .\install_extensions.ps1 -SkipPackage
+
+param([switch] $SkipPackage)
+
+$path_vscode   = $PSScriptRoot
+$code_insiders = "C:\apps\Microsoft VS Code Insiders\bin\code-insiders.cmd"
+if (-not (test-path -literalpath $code_insiders)) {
+	$found = get-command code-insiders -erroraction silentlycontinue
+	if ($found) { $code_insiders = $found.source }
+}
+
+if (-not (test-path -literalpath $code_insiders)) { throw "code-insiders not found. Install VS Code Insiders or add it to PATH." }
+
+$extensions = @(
+	(join-path $path_vscode "tape-atom-syntax"),
+	(join-path $path_vscode "cozy-and-windy")
+)
+
+foreach ($extension in $extensions) {
+	$package_json = join-path $extension "package.json"
+	if (-not (test-path -literalpath $package_json)) { throw "missing $package_json" }
+
+	$manifest = get-content -literalpath $package_json -raw | convertfrom-json
+	$vsix     = join-path $extension ("{0}-{1}.vsix" -f $manifest.name, $manifest.version)
+
+	if (-not $SkipPackage) {
+		if (-not $manifest.scripts.package) { throw "$package_json has no scripts.package" }
+		write-host "packaging $($manifest.displayName) ($($manifest.name)@$($manifest.version))"
+		& npm --prefix $extension run package
+		if ($LASTEXITCODE -ne 0) { throw "npm run package failed for $extension" }
+	}
+
+	if (-not (test-path -literalpath $vsix)) { throw "missing $vsix" }
+
+	write-host "installing $vsix"
+	& $code_insiders --install-extension $vsix --force
+	if ($LASTEXITCODE -ne 0) { throw "install failed for $vsix" }
+}
+
+write-host "done. reload the Insiders window (Developer: Reload Window)."

.vscode/tape-atom-syntax/classifier.js

@@ -0,0 +1,222 @@
+"use strict";
+
+const { nearestCall } = require("./lexer");
+const { mergeIndexes, scanSource } = require("./source-index");
+
+const TOKEN_TYPES = [
+	"tapeAtomKeyword",
+	"tapeAtomName",
+	"tapeComponentKeyword",
+	"tapeComponentName",
+	"tapeAnnotation",
+	"tapeBindType",
+	"tapePhase",
+	"tapeLabel",
+	"tapeCpuInstruction",
+	"tapeControlFlow",
+	"tapeGteInstruction",
+	"tapeGpuInstruction",
+	"tapeComponentInstruction",
+	"tapeDelaySlot",
+	"tapeGprRegister",
+	"tapeCop2Register",
+	"tapeDuffleType",
+	"tapeAttribute",
+	"keyword",
+	"macro",
+];
+
+const TOKEN_MODIFIERS = ["declaration", "tapeRead", "tapeWrite", "tapeAuto"];
+const TOKEN_TYPE_INDEX = new Map(TOKEN_TYPES.map((name, index) => [name, index]));
+const TOKEN_MODIFIER_INDEX = new Map(TOKEN_MODIFIERS.map((name, index) => [name, index]));
+
+const ATOM_KEYWORDS = new Set(["MipsAtom_", "MipsAtom_Proc_"]);
+const COMPONENT_KEYWORDS = new Set(["MipsAtomComp_", "MipsAtomComp_Proc_"]);
+const ANNOTATIONS = new Set([
+	"atom_info", "atom_bind", "atom_reads", "atom_writes", "atom_label",
+	"atom_offset", "atom_reg", "atom_type", "atom_ctx", "atom_phase",
+	"atom_auto_reg", "phase_auto_reg", "atom_dbg_skip",
+]);
+
+const DSL_KEYWORDS = new Set([
+	"FI_", "I_", "NI_", "Relative_", "Struct_", "Enum_", "Union_", "Array_",
+	"Slice_", "TypeR_", "TypeV_", "align_", "internal", "local_persist", "global",
+	"RO_", "LP_", "gknown", "expect_", "cexpr_",
+	"asm", "asm_words", "asm_rpins", "asm_clobber",
+	"O_", "S_", "C_", "T_", "tmpl", "glue", "r_", "v_", "tr_", "tv_",
+	"rgcc", "r_use", "r_set", "r_mod", "r_imm", "r_mem",
+	"u1_", "u2_", "u4_", "u8_", "s1_", "s2_", "s4_", "s8_",
+	"u1_r", "u2_r", "u4_r", "u8_r", "u1_v", "u2_v", "u4_v", "u8_v",
+]);
+
+const DELAY_SLOT_KEYWORDS = new Set(["LdSlot_", "BdSlot_", "DmaSlot_", "GteDelay_"]);
+
+const CONTROL_FLOW_PREFIXES = /^(?:branch_|jump_|call_)/;
+
+const ROLE_TO_TYPE = {
+	atomName: "tapeAtomName",
+	componentName: "tapeComponentName",
+	bindType: "tapeBindType",
+	duffleType: "tapeDuffleType",
+	gprRegister: "tapeGprRegister",
+	cop2Register: "tapeCop2Register",
+};
+
+function registerType(name, index) {
+	const kind = index.registers.get(name);
+	if (kind === "gpr" || /^R_[A-Za-z0-9_]+$/.test(name)) return "tapeGprRegister";
+	if (kind === "cop2" || /^(?:C2_|gte_cr_)[A-Za-z0-9_]+$/.test(name)) return "tapeCop2Register";
+	return null;
+}
+
+function instructionType(name, index) {
+	const domain = index.macros.get(name);
+	if (domain === "control") return "tapeControlFlow";
+	if (domain === "cpu") return "tapeCpuInstruction";
+	if (domain === "gte") return "tapeGteInstruction";
+	if (domain === "gpu") return "tapeGpuInstruction";
+	if (domain === "component") {
+		if (/^mac_gte_/.test(name)) return "tapeGteInstruction";
+		if (/^mac_gp/.test(name)) return "tapeGpuInstruction";
+		if (/^mac_/.test(name)) return "tapeComponentInstruction";
+		return "macro";
+	}
+	if (domain === "utility") return "macro";
+	if (/^gte_(?!cr_)/.test(name)) return "tapeGteInstruction";
+	if (/^gp[01]_/.test(name)) return "tapeGpuInstruction";
+	if (/^mac_gte_/.test(name)) return "tapeGteInstruction";
+	if (/^mac_gp/.test(name)) return "tapeGpuInstruction";
+	if (/^mac_/.test(name)) return "tapeComponentInstruction";
+	return null;
+}
+
+function modifierMask(modifiers) {
+	let mask = 0;
+	for (const modifier of modifiers) {
+		const index = TOKEN_MODIFIER_INDEX.get(modifier);
+		if (index !== undefined) mask |= (1 << index);
+	}
+	return mask;
+}
+
+function isRegUseAccess(tokens, tokenIndex) {
+	const prev = tokens[tokenIndex - 1];
+	if (!prev || prev.text !== ".") return false;
+	const prevPrev = tokens[tokenIndex - 2];
+	if (!prevPrev || prevPrev.kind !== "identifier") return false;
+	const next = tokens[tokenIndex + 1];
+	if (next && next.text === ".") return false;
+	if (prevPrev.text === "r") return true;
+	const prev3 = tokens[tokenIndex - 3];
+	const prev4 = tokens[tokenIndex - 4];
+	if (prev3 && prev3.text === "." && prev4 && prev4.kind === "identifier" && prev4.text === "r") return true;
+	return false;
+}
+
+function classifyDocument(source, filePath, workspaceIndex, shouldCancel = () => false) {
+	const scanned = scanSource(source, filePath);
+	const index = mergeIndexes(workspaceIndex, scanned.index);
+	const spans = [];
+
+	for (let tokenIndex = 0; tokenIndex < scanned.tokens.length; tokenIndex += 1) {
+		if (shouldCancel()) break;
+		const token = scanned.tokens[tokenIndex];
+		if (token.kind !== "identifier") continue;
+
+		let type = null;
+		let modifiers = [];
+		const declaration = scanned.declarations.get(token.start);
+		const context = nearestCall(scanned.contexts, tokenIndex);
+
+		if (declaration) {
+			type = ROLE_TO_TYPE[declaration.role] || null;
+			modifiers = declaration.modifiers.slice();
+		} else if (ATOM_KEYWORDS.has(token.text)) {
+			type = "tapeAtomKeyword";
+		} else if (COMPONENT_KEYWORDS.has(token.text)) {
+			type = "keyword";
+		} else if (ANNOTATIONS.has(token.text)) {
+			type = "tapeAnnotation";
+		} else if (context && context.callee === "atom_bind" && context.argIndex === 0) {
+			type = "tapeBindType";
+		} else if (context && context.callee === "atom_phase" && context.argIndex === 0) {
+			type = "tapePhase";
+			modifiers = ["declaration"];
+		} else if (context && context.callee === "atom_ctx" && context.argIndex === 0) {
+			type = "tapeAtomName";
+		} else if (context && context.callee === "atom_label" && context.argIndex === 0) {
+			type = "tapeLabel";
+			modifiers = ["declaration"];
+		} else if (context && context.callee === "atom_offset" && context.argIndex <= 1) {
+			type = "tapeLabel";
+		} else if (context && context.callee === "atom_reads") {
+			type = registerType(token.text, index);
+			if (type) modifiers = ["tapeRead"];
+		} else if (context && context.callee === "atom_writes") {
+			type = registerType(token.text, index);
+			if (type) modifiers = ["tapeWrite"];
+		} else if (context && context.callee === "atom_auto_reg") {
+			if (context.argIndex === 0) type = "tapeAtomName";
+			if (context.argIndex === 1) {
+				type = "tapeGprRegister";
+				modifiers = ["declaration", "tapeAuto"];
+			}
+		} else if (context && context.callee === "phase_auto_reg") {
+			if (context.argIndex === 0) type = "tapePhase";
+			if (context.argIndex === 1) {
+				type = "tapeGprRegister";
+				modifiers = ["declaration", "tapeAuto"];
+			}
+		}
+
+		if (!type && index.bindTypes.has(token.text)) type = "tapeBindType";
+		if (!type && DSL_KEYWORDS.has(token.text)) type = "keyword";
+		if (!type && index.types.has(token.text)) type = "tapeDuffleType";
+		if (!type && index.attributes.has(token.text)) type = "tapeAttribute";
+		if (!type) type = registerType(token.text, index);
+		if (!type && DELAY_SLOT_KEYWORDS.has(token.text)) type = "tapeDelaySlot";
+		if (!type) {
+			const domain = index.macros.get(token.text);
+			if (domain === "control" || (domain && CONTROL_FLOW_PREFIXES.test(token.text))) {
+				type = "tapeControlFlow";
+			}
+		}
+		if (!type && isRegUseAccess(scanned.tokens, tokenIndex)) type = "tapeGprRegister";
+		if (!type) type = instructionType(token.text, index);
+		if (!type && /^(?:Slice_|A[0-9]+_)/.test(token.text)) type = "tapeDuffleType";
+		if (!type && /_[RV]$/.test(token.text)) type = "tapeDuffleType";
+		if (!type && index.atoms.has(token.text)) type = "tapeAtomName";
+		if (!type && index.components.has(token.text)) type = "tapeComponentName";
+		if (!type && index.phases.has(token.text)) type = "tapePhase";
+		if (!type && index.labels.has(token.text)) type = "tapeLabel";
+		if (!type) continue;
+
+		spans.push({
+			text: token.text,
+			type,
+			typeIndex: TOKEN_TYPE_INDEX.get(type),
+			modifiers,
+			modifierMask: modifierMask(modifiers),
+			start: token.start,
+			length: token.end - token.start,
+			line: token.line,
+			character: token.character,
+		});
+	}
+
+	spans.sort((left, right) => left.start - right.start || left.length - right.length);
+	const nonOverlapping = [];
+	for (const span of spans) {
+		const previous = nonOverlapping[nonOverlapping.length - 1];
+		if (!previous || previous.start + previous.length <= span.start) nonOverlapping.push(span);
+	}
+
+	return { spans: nonOverlapping, errors: scanned.errors };
+}
+
+module.exports = {
+	TOKEN_MODIFIERS,
+	TOKEN_TYPES,
+	classifyDocument,
+	modifierMask,
+};

.vscode/tape-atom-syntax/extension.js

@@ -0,0 +1,111 @@
+"use strict";
+
+const vscode = require("vscode");
+const { TOKEN_MODIFIERS, TOKEN_TYPES, classifyDocument } = require("./classifier");
+const { createIndex, mergeIndexes, scanSource } = require("./source-index");
+
+const SOURCE_GLOB = "**/*.{c,h,cc,cpp,cxx,hh,hpp,hxx}";
+const EXCLUDE_GLOB = "**/{gen,build,.slop_cache,toolchain,node_modules}/**";
+const EXCLUDED_SEGMENTS = new Set(["gen", "build", ".slop_cache", "toolchain", "node_modules"]);
+
+function isExcluded(uri) {
+	const segments = uri.fsPath.replaceAll("\\", "/").split("/");
+	return segments.some((segment) => EXCLUDED_SEGMENTS.has(segment));
+}
+
+function formatError(filePath, error) {
+	return `${filePath}:${error.offset}: ${error.kind}`;
+}
+
+async function activate(context) {
+	const output = vscode.window.createOutputChannel("Tape Atom DSL");
+	const emitter = new vscode.EventEmitter();
+	const legend = new vscode.SemanticTokensLegend(TOKEN_TYPES, TOKEN_MODIFIERS);
+	let workspaceIndex = createIndex();
+	let rebuildGeneration = 0;
+	let debounceHandle = null;
+
+	async function rebuildIndex() {
+		const generation = ++rebuildGeneration;
+		const files = await vscode.workspace.findFiles(SOURCE_GLOB, EXCLUDE_GLOB);
+		let nextIndex = createIndex();
+
+		for (const uri of files) {
+			if (generation !== rebuildGeneration) return;
+			if (isExcluded(uri)) continue;
+			try {
+				const bytes = await vscode.workspace.fs.readFile(uri);
+				const source = Buffer.from(bytes).toString("utf8");
+				const result = scanSource(source, uri.fsPath);
+				nextIndex = mergeIndexes(nextIndex, result.index);
+				for (const error of result.errors) output.appendLine(formatError(uri.fsPath, error));
+			} catch (error) {
+				output.appendLine(`${uri.fsPath}: ${error.stack || error.message || error}`);
+			}
+		}
+
+		if (generation !== rebuildGeneration) return;
+		workspaceIndex = nextIndex;
+		emitter.fire();
+	}
+
+	function scheduleRebuild(uri) {
+		if (uri && isExcluded(uri)) return;
+		if (debounceHandle !== null) clearTimeout(debounceHandle);
+		debounceHandle = setTimeout(() => {
+			debounceHandle = null;
+			rebuildIndex().catch((error) => output.appendLine(error.stack || String(error)));
+		}, 100);
+	}
+
+	const provider = {
+		onDidChangeSemanticTokens: emitter.event,
+		provideDocumentSemanticTokens(document, cancellationToken) {
+			try {
+				const result = classifyDocument(
+					document.getText(),
+					document.uri.fsPath,
+					workspaceIndex,
+					() => cancellationToken.isCancellationRequested
+				);
+				const builder = new vscode.SemanticTokensBuilder(legend);
+				for (const span of result.spans) {
+					if (cancellationToken.isCancellationRequested) break;
+					builder.push(span.line, span.character, span.length, span.typeIndex, span.modifierMask);
+				}
+				for (const error of result.errors) {
+					output.appendLine(formatError(document.uri.fsPath || document.uri.toString(), error));
+				}
+				return builder.build();
+			} catch (error) {
+				output.appendLine(`${document.uri}: ${error.stack || error.message || error}`);
+				return new vscode.SemanticTokensBuilder(legend).build();
+			}
+		},
+	};
+
+	const selector = [
+		{ language: "c", scheme: "file" },
+		{ language: "c", scheme: "untitled" },
+		{ language: "cpp", scheme: "file" },
+		{ language: "cpp", scheme: "untitled" },
+	];
+	const watcher = vscode.workspace.createFileSystemWatcher(SOURCE_GLOB);
+
+	context.subscriptions.push(
+		output,
+		emitter,
+		watcher,
+		watcher.onDidCreate(scheduleRebuild),
+		watcher.onDidChange(scheduleRebuild),
+		watcher.onDidDelete(scheduleRebuild),
+		vscode.languages.registerDocumentSemanticTokensProvider(selector, provider, legend),
+		{ dispose() { if (debounceHandle !== null) clearTimeout(debounceHandle); } }
+	);
+
+	await rebuildIndex();
+}
+
+function deactivate() {}
+
+module.exports = { activate, deactivate };

.vscode/tape-atom-syntax/lexer.js

@@ -0,0 +1,186 @@
+"use strict";
+
+function isIdentifierStart(code) {
+	return code === 95 ||
+		(code >= 65 && code <= 90) ||
+		(code >= 97 && code <= 122);
+}
+
+function isIdentifierContinue(code) {
+	return isIdentifierStart(code) || (code >= 48 && code <= 57);
+}
+
+function lex(source) {
+	if (typeof source !== "string") throw new TypeError("source must be a string");
+
+	const tokens = [];
+	const errors = [];
+	let offset = 0;
+	let line = 0;
+	let character = 0;
+
+	function advance() {
+		if (source[offset] === "\r" && source[offset + 1] === "\n") {
+			offset += 2;
+			line += 1;
+			character = 0;
+			return;
+		}
+		if (source[offset] === "\n") {
+			offset += 1;
+			line += 1;
+			character = 0;
+			return;
+		}
+		offset += 1;
+		character += 1;
+	}
+
+	function pushToken(kind, start, startLine, startCharacter) {
+		tokens.push({
+			kind,
+			text: source.slice(start, offset),
+			start,
+			end: offset,
+			line: startLine,
+			character: startCharacter,
+		});
+	}
+
+	while (offset < source.length) {
+		const ch = source[offset];
+
+		if (/\s/.test(ch)) {
+			advance();
+			continue;
+		}
+
+		if (ch === "/" && source[offset + 1] === "/") {
+			while (offset < source.length && source[offset] !== "\r" && source[offset] !== "\n") advance();
+			continue;
+		}
+
+		if (ch === "/" && source[offset + 1] === "*") {
+			const start = offset;
+			advance();
+			advance();
+			let closed = false;
+			while (offset < source.length) {
+				if (source[offset] === "*" && source[offset + 1] === "/") {
+					advance();
+					advance();
+					closed = true;
+					break;
+				}
+				advance();
+			}
+			if (!closed) errors.push({ kind: "unterminated-block-comment", offset: start });
+			continue;
+		}
+
+		if (ch === "\"" || ch === "'") {
+			const quote = ch;
+			const start = offset;
+			advance();
+			let closed = false;
+			while (offset < source.length) {
+				if (source[offset] === "\\") {
+					advance();
+					if (offset < source.length) advance();
+					continue;
+				}
+				if (source[offset] === quote) {
+					advance();
+					closed = true;
+					break;
+				}
+				if (source[offset] === "\n" || source[offset] === "\r") break;
+				advance();
+			}
+			if (!closed) errors.push({ kind: "unterminated-literal", offset: start });
+			continue;
+		}
+
+		const code = source.charCodeAt(offset);
+		if (isIdentifierStart(code)) {
+			const start = offset;
+			const startLine = line;
+			const startCharacter = character;
+			advance();
+			while (offset < source.length && isIdentifierContinue(source.charCodeAt(offset))) advance();
+			pushToken("identifier", start, startLine, startCharacter);
+			continue;
+		}
+
+		const start = offset;
+		const startLine = line;
+		const startCharacter = character;
+		advance();
+		pushToken("punctuation", start, startLine, startCharacter);
+	}
+
+	return { tokens, errors };
+}
+
+function buildCallContexts(tokens) {
+	const contexts = Array.from({ length: tokens.length }, () => []);
+	const calls = [];
+	const errors = [];
+	const stack = [];
+
+	for (let tokenIndex = 0; tokenIndex < tokens.length; tokenIndex += 1) {
+		const token = tokens[tokenIndex];
+
+		if (token.text === ")") {
+			if (stack.length === 0) {
+				errors.push({ kind: "unmatched-close-paren", offset: token.start });
+			} else {
+				const frame = stack.pop();
+				if (frame.callee !== null) calls.push({ ...frame, closeTokenIndex: tokenIndex });
+			}
+		}
+
+		contexts[tokenIndex] = stack
+			.filter((frame) => frame.callee !== null)
+			.map((frame) => ({
+				callee: frame.callee,
+				calleeTokenIndex: frame.calleeTokenIndex,
+				openTokenIndex: frame.openTokenIndex,
+				argIndex: frame.argIndex,
+			}));
+
+		if (token.text === "(") {
+			const previous = tokens[tokenIndex - 1];
+			const hasCallee = previous && previous.kind === "identifier";
+			stack.push({
+				callee: hasCallee ? previous.text : null,
+				calleeTokenIndex: hasCallee ? tokenIndex - 1 : -1,
+				openTokenIndex: tokenIndex,
+				argIndex: 0,
+			});
+			continue;
+		}
+
+		if (token.text === "," && stack.length > 0) {
+			const frame = stack[stack.length - 1];
+			if (frame.callee !== null) frame.argIndex += 1;
+		}
+	}
+
+	for (const frame of stack) {
+		errors.push({ kind: "unmatched-open-paren", offset: tokens[frame.openTokenIndex].start });
+	}
+
+	return { contexts, calls, errors };
+}
+
+function nearestCall(contexts, tokenIndex, callee) {
+	const entries = contexts[tokenIndex] || [];
+	for (let contextIndex = entries.length - 1; contextIndex >= 0; contextIndex -= 1) {
+		const entry = entries[contextIndex];
+		if (callee === undefined || entry.callee === callee) return entry;
+	}
+	return null;
+}
+
+module.exports = { buildCallContexts, lex, nearestCall };

.vscode/tape-atom-syntax/package.json

@@ -0,0 +1,85 @@
+{
+	"name": "atomasm-psx",
+	"displayName": "AtomAsm-PSX",
+	"description": "Semantic highlighting for the PS1 Tape/Atom MIPS macro DSL",
+	"publisher": "local",
+	"version": "0.3.0",
+	"engines": { "vscode": "^1.80.0" },
+	"categories": ["Programming Languages"],
+	"activationEvents": ["onLanguage:c", "onLanguage:cpp"],
+	"main": "./extension.js",
+	"files": [
+		"classifier.js",
+		"extension.js",
+		"lexer.js",
+		"source-index.js",
+		"syntaxes/tape_atom.tmLanguage.json"
+	],
+	"scripts": {
+		"test": "node --test test/*.test.js",
+		"package": "npx --yes @vscode/vsce@3.6.1 package --allow-missing-repository --skip-license --out atomasm-psx-0.3.0.vsix"
+	},
+	"contributes": {
+		"semanticTokenTypes": [
+			{ "id": "tapeAtomKeyword", "superType": "keyword", "description": "Tape atom declaration keyword" },
+			{ "id": "tapeAtomName", "superType": "function", "description": "Tape atom name" },
+			{ "id": "tapeComponentKeyword", "superType": "keyword", "description": "Tape atom component declaration keyword" },
+			{ "id": "tapeComponentName", "superType": "function", "description": "Tape atom component name" },
+			{ "id": "tapeAnnotation", "superType": "macro", "description": "Tape atom annotation" },
+			{ "id": "tapeBindType", "superType": "type", "description": "Tape bind structure type" },
+			{ "id": "tapePhase", "superType": "label", "description": "Tape atom phase" },
+			{ "id": "tapeLabel", "superType": "label", "description": "Tape atom branch label" },
+			{ "id": "tapeCpuInstruction", "superType": "macro", "description": "MIPS CPU instruction emitter" },
+			{ "id": "tapeControlFlow", "superType": "keyword", "description": "MIPS branch or jump instruction" },
+			{ "id": "tapeGteInstruction", "superType": "macro", "description": "GTE instruction emitter" },
+			{ "id": "tapeGpuInstruction", "superType": "macro", "description": "GPU command emitter" },
+			{ "id": "tapeComponentInstruction", "superType": "macro", "description": "Tape atom component invocation" },
+			{ "id": "tapeDelaySlot", "superType": "keyword", "description": "Load or branch delay slot annotation" },
+			{ "id": "tapeGprRegister", "superType": "variable", "description": "MIPS GPR alias" },
+			{ "id": "tapeCop2Register", "superType": "variable", "description": "COP2 data or control register alias" },
+			{ "id": "tapeDuffleType", "superType": "type", "description": "Duffle type or type constructor" },
+			{ "id": "tapeAttribute", "superType": "keyword", "description": "Duffle linkage or storage attribute" },
+			{ "id": "keyword", "description": "Standard keyword (DSL built-in macros)" },
+			{ "id": "macro", "description": "Standard macro (utility #define with no instruction domain)" }
+		],
+		"semanticTokenModifiers": [
+			{ "id": "tapeRead", "description": "Register declared in atom_reads" },
+			{ "id": "tapeWrite", "description": "Register declared in atom_writes" },
+			{ "id": "tapeAuto", "description": "Auto-allocated register" }
+		],
+		"semanticTokenScopes": [
+			{
+				"language": "c",
+				"scopes": {
+					"tapeAtomKeyword": ["keyword.control.duffle.atom"],
+					"tapeAtomName": ["entity.name.function.duffle.atom"],
+					"tapeComponentKeyword": ["keyword.control.duffle.component"],
+					"tapeComponentName": ["entity.name.function.duffle.component"],
+					"tapeAnnotation": ["support.function.duffle.annotation"],
+					"tapeBindType": ["entity.name.type.duffle.bind"],
+					"tapePhase": ["entity.name.tag.duffle.phase"],
+					"tapeLabel": ["entity.name.label.duffle.atom"],
+					"tapeCpuInstruction": ["support.function.duffle.cpu"],
+					"tapeControlFlow": ["keyword.control.duffle.branch"],
+					"tapeGteInstruction": ["support.function.duffle.gte"],
+					"tapeGpuInstruction": ["support.function.duffle.gpu"],
+					"tapeComponentInstruction": ["support.function.duffle.component"],
+					"tapeDelaySlot": ["keyword.operator.duffle.delayslot"],
+					"tapeGprRegister": ["variable.other.constant.duffle.gpr"],
+					"tapeCop2Register": ["variable.other.constant.duffle.cop2"],
+					"tapeDuffleType": ["storage.type.duffle.type"],
+					"tapeAttribute": ["storage.modifier.duffle.attr"],
+				"keyword": ["keyword"],
+				"macro": ["entity.name.function.preprocessor"]
+				}
+			}
+		],
+		"grammars": [
+			{
+				"scopeName": "tape_atom.injection",
+				"path": "./syntaxes/tape_atom.tmLanguage.json",
+				"injectTo": ["source.c", "source.cpp"]
+			}
+		]
+	}
+}

.vscode/tape-atom-syntax/source-index.js

@@ -0,0 +1,341 @@
+"use strict";
+
+const path = require("node:path");
+const { buildCallContexts, lex, nearestCall } = require("./lexer");
+
+const BASE_TYPES = [
+	"B1", "B2", "B4", "B8", "F4", "F8", "S1", "S2", "S4", "S8",
+	"U1", "U2", "U4", "U8", "MipsAtom", "MipsCode", "Reg",
+];
+
+const C_BUILTINS = new Set([
+	"void", "type", "char", "short", "int", "long", "float", "double",
+	"unsigned", "signed", "bool", "size_t", "uint8_t", "uint16_t", "uint32_t",
+	"int8_t", "int16_t", "int32_t",
+]);
+
+const BASE_ATTRIBUTES = [
+	"FI_", "I_", "NI_", "Relative_", "Struct_", "Enum_", "Union_", "Array_",
+	"Slice_", "TypeR_", "TypeV_", "align_", "internal", "local_persist", "global",
+	"RO_", "LP_", "gknown", "expect_", "cexpr_",
+	"asm", "asm_words", "asm_rpins", "asm_clobber",
+	"O_", "S_", "C_", "T_", "tmpl", "glue", "r_", "v_", "tr_", "tv_",
+	"rgcc", "r_use", "r_set", "r_mod", "r_imm", "r_mem",
+	"u1_", "u2_", "u4_", "u8_", "s1_", "s2_", "s4_", "s8_",
+	"u1_r", "u2_r", "u4_r", "u8_r", "u1_v", "u2_v", "u4_v", "u8_v",
+];
+
+function createIndex() {
+	return {
+		atoms: new Set(),
+		components: new Set(),
+		componentAliases: new Set(),
+		macros: new Map(),
+		registers: new Map(),
+		bindTypes: new Set(),
+		types: new Set(BASE_TYPES),
+		phases: new Set(),
+		labels: new Set(),
+		attributes: new Set(BASE_ATTRIBUTES),
+		componentCallees: new Map(),
+	};
+}
+
+function cloneIndex(source) {
+	const result = createIndex();
+	for (const key of ["atoms", "components", "componentAliases", "bindTypes", "types", "phases", "labels", "attributes"]) {
+		for (const value of source[key]) result[key].add(value);
+	}
+	for (const [name, domain] of source.macros) result.macros.set(name, domain);
+	for (const [name, domain] of source.registers) result.registers.set(name, domain);
+	for (const [name, callees] of source.componentCallees) result.componentCallees.set(name, callees.slice());
+	return result;
+}
+
+function mergeIndexes(...sources) {
+	const result = createIndex();
+	for (const source of sources) {
+		if (!source) continue;
+		for (const key of ["atoms", "components", "componentAliases", "bindTypes", "types", "phases", "labels", "attributes"]) {
+			for (const value of source[key]) result[key].add(value);
+		}
+		for (const [name, domain] of source.macros) {
+			const existing = result.macros.get(name);
+			if (!existing || domainRank(domain) >= domainRank(existing)) result.macros.set(name, domain);
+		}
+		for (const [name, domain] of source.registers) result.registers.set(name, domain);
+		for (const [name, callees] of source.componentCallees) {
+			const existing = result.componentCallees.get(name) || [];
+			result.componentCallees.set(name, existing.concat(callees));
+		}
+	}
+	return resolveComponentDomains(result);
+}
+
+function domainFromPath(filePath) {
+	const base = path.basename(filePath.replaceAll("\\", "/")).toLowerCase();
+	if (base === "mips.h") return "cpu";
+	if (base === "gte.h") return "gte";
+	if (base === "gp.h") return "gpu";
+	return null;
+}
+
+function prefixDomain(name) {
+	if (/^(?:branch_|jump_|call_)/.test(name)) return "control";
+	if (/^gte_(?!cr_)/.test(name) || name.startsWith("mac_gte_") || name.startsWith("ac_gte_")) return "gte";
+	if (/^gp[01]_/.test(name) || name.startsWith("mac_gp_") || name.startsWith("ac_gp_")) return "gpu";
+	return null;
+}
+
+function collectBraceIdentifiers(tokens, openBraceIndex) {
+	const names = [];
+	let depth = 0;
+	for (let tokenIndex = openBraceIndex; tokenIndex < tokens.length; tokenIndex += 1) {
+		if (tokens[tokenIndex].text === "{") depth += 1;
+		if (tokens[tokenIndex].text === "}") {
+			depth -= 1;
+			if (depth === 0) break;
+		}
+		if (tokens[tokenIndex].kind === "identifier") names.push(tokens[tokenIndex].text);
+	}
+	return names;
+}
+
+function resolveComponentDomains(index) {
+	const hardwareRank = { cpu: 1, gpu: 2, gte: 3, control: 4 };
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const [alias, callees] of index.componentCallees) {
+			let best = index.macros.get(alias) || "component";
+			let bestRank = hardwareRank[best] || 0;
+			for (const callee of callees) {
+				const domain = prefixDomain(callee) || index.macros.get(callee);
+				const rank = hardwareRank[domain] || 0;
+				if (rank > bestRank) {
+					best = domain;
+					bestRank = rank;
+				}
+			}
+			if (bestRank > 0 && index.macros.get(alias) !== best) {
+				index.macros.set(alias, best);
+				changed = true;
+			}
+		}
+	}
+	return index;
+}
+
+function domainRank(domain) {
+	if (domain === "control") return 4;
+	if (domain === "cpu" || domain === "gte" || domain === "gpu") return 3;
+	if (domain === "component") return 2;
+	return 1;
+}
+
+function registerKind(name) {
+	if (/^R_[A-Za-z0-9_]+$/.test(name)) return "gpr";
+	if (/^(?:C2_|gte_cr_)[A-Za-z0-9_]+$/.test(name)) return "cop2";
+	return null;
+}
+
+function componentAlias(name) {
+	return name.startsWith("ac_") ? `mac_${name.slice(3)}` : null;
+}
+
+function findFunctionNameBefore(tokens, calleeTokenIndex) {
+	let closeIndex = calleeTokenIndex - 1;
+	while (closeIndex >= 0 && tokens[closeIndex].kind === "identifier" && tokens[closeIndex].text === "atom_dbg_skip") {
+		closeIndex -= 1;
+	}
+	if (!tokens[closeIndex] || tokens[closeIndex].text !== ")") return null;
+
+	let depth = 1;
+	for (let tokenIndex = closeIndex - 1; tokenIndex >= 0; tokenIndex -= 1) {
+		if (tokens[tokenIndex].text === ")") depth += 1;
+		if (tokens[tokenIndex].text === "(") depth -= 1;
+		if (depth !== 0) continue;
+		const name = tokens[tokenIndex - 1];
+		return name && name.kind === "identifier" ? name : null;
+	}
+	return null;
+}
+
+function scanSource(source, filePath) {
+	const lexical = lex(source);
+	const balanced = buildCallContexts(lexical.tokens);
+	const tokens = lexical.tokens;
+	const contexts = balanced.contexts;
+	const index = createIndex();
+	const declarations = new Map();
+	const domain = domainFromPath(filePath);
+
+	function mark(token, role, modifiers = ["declaration"]) {
+		declarations.set(token.start, { role, modifiers });
+	}
+
+	function addComponent(token) {
+		index.components.add(token.text);
+		mark(token, "componentName");
+		const alias = componentAlias(token.text);
+		if (alias) {
+			index.componentAliases.add(alias);
+			index.macros.set(alias, prefixDomain(alias) || prefixDomain(token.text) || "component");
+		}
+	}
+
+	function bindComponentCallees(alias, callees) {
+		if (!alias) return;
+		index.componentAliases.add(alias);
+		index.componentCallees.set(alias, callees);
+		if (!index.macros.has(alias)) index.macros.set(alias, "component");
+	}
+
+	for (let tokenIndex = 0; tokenIndex < tokens.length; tokenIndex += 1) {
+		const token = tokens[tokenIndex];
+		if (token.kind !== "identifier") continue;
+
+		const kind = registerKind(token.text);
+		if (kind) {
+			index.registers.set(token.text, kind);
+			if (tokens[tokenIndex + 1] && tokens[tokenIndex + 1].text === "=") {
+				mark(token, kind === "gpr" ? "gprRegister" : "cop2Register");
+			}
+		}
+
+		const context = nearestCall(contexts, tokenIndex);
+		if (context && context.argIndex === 0) {
+			if (context.callee === "MipsAtom_") {
+				index.atoms.add(token.text);
+				mark(token, "atomName");
+			}
+			if (context.callee === "MipsAtomComp_") addComponent(token);
+			if (context.callee === "atom_bind") index.bindTypes.add(token.text);
+			if (context.callee === "atom_phase" || context.callee === "phase_auto_reg") index.phases.add(token.text);
+			if (context.callee === "atom_label" || context.callee === "atom_offset") index.labels.add(token.text);
+		}
+
+		const isWrappedType = context && (
+			((context.callee === "Struct_" || context.callee === "Union_") && context.argIndex === 0) ||
+			(context.callee === "Enum_" && context.argIndex === 1)
+		);
+		if (isWrappedType) {
+			index.types.add(token.text);
+			mark(token, token.text.startsWith("Binds_") ? "bindType" : "duffleType");
+			if (token.text.startsWith("Binds_")) index.bindTypes.add(token.text);
+		}
+
+		if (context && context.callee === "atom_offset" && context.argIndex === 1) index.labels.add(token.text);
+
+		if (context && context.callee === "atom_auto_reg") {
+			if (context.argIndex === 0) index.atoms.add(token.text);
+			if (context.argIndex === 1) {
+				index.registers.set(token.text, "gpr");
+				mark(token, "gprRegister", ["declaration", "tapeAuto"]);
+			}
+		}
+
+		if (context && context.callee === "phase_auto_reg" && context.argIndex === 1) {
+			index.registers.set(token.text, "gpr");
+			mark(token, "gprRegister", ["declaration", "tapeAuto"]);
+		}
+
+		if (token.text === "define" && tokens[tokenIndex - 1] && tokens[tokenIndex - 1].text === "#") {
+			const name = tokens[tokenIndex + 1];
+			if (name && name.kind === "identifier" && name.line === token.line) {
+				if (/^(?:RegUse_|Struct_|Enum_|Union_|TypeR_|TypeV_|Relative_|Binds_)/.test(name.text)) {
+					index.types.add(name.text);
+				} else if (/^(?:ac_|mac_)/.test(name.text)) {
+					const alias = name.text.startsWith("ac_") ? componentAlias(name.text) : name.text;
+					const rest = [];
+					for (let restIndex = tokenIndex + 2; restIndex < tokens.length && tokens[restIndex].line === name.line; restIndex += 1) {
+						if (tokens[restIndex].kind === "identifier") rest.push(tokens[restIndex].text);
+					}
+					if (alias) {
+						index.componentAliases.add(alias);
+						index.macros.set(alias, prefixDomain(alias) || "component");
+						if (rest.length) index.componentCallees.set(alias, rest);
+					}
+				} else {
+					index.macros.set(name.text, domain || "utility");
+				}
+			}
+		}
+
+		if (token.text === "typedef") {
+			let endIndex = tokenIndex + 1;
+			let hasBrace = false;
+			let lastIdentifier = null;
+			while (endIndex < tokens.length && tokens[endIndex].text !== ";") {
+				if (tokens[endIndex].text === "{") hasBrace = true;
+				if (tokens[endIndex].kind === "identifier" && !C_BUILTINS.has(tokens[endIndex].text)) lastIdentifier = tokens[endIndex];
+				endIndex += 1;
+			}
+			if (!hasBrace && lastIdentifier && !C_BUILTINS.has(lastIdentifier.text)) {
+				index.types.add(lastIdentifier.text);
+				mark(lastIdentifier, "duffleType");
+			}
+		}
+
+		if (token.text === "MipsAtom_Proc_") {
+			const functionName = findFunctionNameBefore(tokens, tokenIndex);
+			if (functionName) {
+				const atomName = functionName.text.endsWith("_proc")
+					? functionName.text.slice(0, -5)
+					: functionName.text;
+				index.atoms.add(atomName);
+				index.atoms.add(functionName.text);
+				mark(functionName, "atomName");
+			}
+		}
+
+		if (token.text === "MipsAtomComp_Proc_") {
+			const functionName = findFunctionNameBefore(tokens, tokenIndex);
+			if (functionName) addComponent(functionName);
+		}
+	}
+
+	for (const call of balanced.calls) {
+		if (call.callee === "MipsAtomComp_") {
+			const name = tokens[call.openTokenIndex + 1];
+			const brace = tokens[call.closeTokenIndex + 1];
+			if (name && name.kind === "identifier" && brace && brace.text === "{") {
+				bindComponentCallees(componentAlias(name.text), collectBraceIdentifiers(tokens, call.closeTokenIndex + 1));
+			}
+		}
+		if (call.callee === "MipsAtomComp_Proc_") {
+			const functionName = findFunctionNameBefore(tokens, call.calleeTokenIndex);
+			let braceIndex = -1;
+			for (let tokenIndex = call.openTokenIndex + 1; tokenIndex < call.closeTokenIndex; tokenIndex += 1) {
+				if (tokens[tokenIndex].text === "{") {
+					braceIndex = tokenIndex;
+					break;
+				}
+			}
+			if (functionName && braceIndex >= 0) {
+				bindComponentCallees(componentAlias(functionName.text), collectBraceIdentifiers(tokens, braceIndex));
+			}
+		}
+		if (!domain) continue;
+		const name = tokens[call.calleeTokenIndex];
+		const after = tokens[call.closeTokenIndex + 1];
+		if (!name || !after || after.text !== "{") continue;
+		if (/^(?:gp0_|gp1_|gte_|mac_)/.test(name.text)) index.macros.set(name.text, domain);
+	}
+
+	return {
+		index: resolveComponentDomains(cloneIndex(index)),
+		declarations,
+		tokens,
+		contexts,
+		errors: [...lexical.errors, ...balanced.errors],
+	};
+}
+
+module.exports = {
+	createIndex,
+	domainFromPath,
+	mergeIndexes,
+	resolveComponentDomains,
+	scanSource,
+};

.vscode/tape-atom-syntax/syntaxes/tape_atom.tmLanguage.json

@@ -0,0 +1,71 @@
+{
+	"scopeName": "tape_atom.injection",
+	"injectionSelector": "L:source.c -comment -string, L:source.cpp -comment -string",
+	"patterns": [
+		{ "include": "#atom-declarations" },
+		{ "include": "#component-declarations" },
+		{ "include": "#annotation-arguments" },
+		{ "include": "#annotations" },
+		{ "include": "#delay-slots" },
+		{ "include": "#types" },
+		{ "include": "#attributes" }
+	],
+	"repository": {
+		"atom-declarations": {
+			"patterns": [
+				{
+					"match": "\\b(MipsAtom_)\\s*\\(\\s*([A-Za-z_][A-Za-z0-9_]*)",
+					"captures": {
+						"1": { "name": "keyword.control.duffle.atom" },
+						"2": { "name": "entity.name.function.duffle.atom" }
+					}
+				},
+				{ "match": "\\bMipsAtom_Proc_\\b", "name": "keyword.control.duffle.atom" },
+				{ "match": "\\b[A-Za-z_][A-Za-z0-9_]*_proc\\b", "name": "entity.name.function.duffle.atom" }
+			]
+		},
+		"component-declarations": {
+			"patterns": [
+				{
+					"match": "\\b(MipsAtomComp_)\\s*\\(\\s*(ac_[A-Za-z0-9_]*)",
+					"captures": {
+						"1": { "name": "keyword" },
+						"2": { "name": "entity.name.function.duffle.component" }
+					}
+				},
+				{ "match": "\\bMipsAtomComp_Proc_\\b", "name": "keyword" }
+			]
+		},
+		"annotation-arguments": {
+			"patterns": [
+				{
+					"match": "\\b(atom_offset)\\s*\\(\\s*([A-Za-z_][A-Za-z0-9_]*)\\s*,\\s*([A-Za-z_][A-Za-z0-9_]*)",
+					"captures": {
+						"1": { "name": "support.function.duffle.annotation" },
+						"2": { "name": "entity.name.label.duffle.atom" },
+						"3": { "name": "entity.name.label.duffle.atom" }
+					}
+				},
+				{ "match": "(?<=\\batom_bind\\()\\s*Binds_[A-Za-z0-9_]+", "name": "entity.name.type.duffle.bind" },
+				{ "match": "(?<=\\batom_phase\\()\\s*[A-Za-z_][A-Za-z0-9_]*", "name": "entity.name.tag.duffle.phase" },
+				{ "match": "(?<=\\batom_label\\()\\s*[A-Za-z_][A-Za-z0-9_]*", "name": "entity.name.label.duffle.atom" }
+			]
+		},
+		"annotations": {
+			"match": "\\b(atom_info|atom_bind|atom_reads|atom_writes|atom_label|atom_offset|atom_reg|atom_type|atom_ctx|atom_phase|atom_auto_reg|phase_auto_reg|atom_dbg_skip)\\b",
+			"name": "support.function.duffle.annotation"
+		},
+		"delay-slots": {
+			"match": "\\b(LdSlot_|BdSlot_|DmaSlot_|GteDelay_)\\b",
+			"name": "keyword.operator.duffle.delayslot"
+		},
+		"types": {
+			"match": "\\b(?:Binds_[A-Za-z0-9_]+|RegUse_[A-Za-z0-9_]+)\\b",
+			"name": "storage.type.duffle.type"
+		},
+		"attributes": {
+			"match": "\\b(?:FI_|I_|NI_|Relative_|Struct_|Enum_|Union_|Array_|Slice_|TypeR_|TypeV_|align_|internal|local_persist|global|RO_|LP_|gknown|expect_|cexpr_|asm|asm_words|asm_rpins|asm_clobber|O_|S_|C_|T_|tmpl|glue|r_|v_|tr_|tv_|rgcc|r_use|r_set|r_mod|r_imm|r_mem|u[1248]_|u[1248]_r|u[1248]_v|s[1248]_)\\b",
+			"name": "keyword"
+		}
+	}
+}

.vscode/tape-atom-syntax/test/classifier.test.js

@@ -0,0 +1,128 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { classifyDocument } = require("../classifier");
+const { createIndex } = require("../source-index");
+
+function byText(result, text) {
+	return result.spans.filter((span) => span.text === text);
+}
+
+test("classifyDocument distinguishes declaration, annotation, phase, bind, and label roles", () => {
+	const source = [
+		"typedef Struct_(Binds_CubeTri) { U4 PrimCursor; };",
+		"MipsAtom_(cube_g4_face) atom_info(atom_bind(Binds_CubeTri), atom_phase(cube_g4),",
+		"\tatom_reads(R_PrimCursor), atom_writes(R_FaceCursor)) {",
+		"\tbranch_le_zero(R_T0, atom_offset(cull, exit)),",
+		"\tatom_label(exit)",
+		"};",
+	].join("\n");
+
+	const result = classifyDocument(source, "C:/x/code/hello_camera/hello_camera.atom.c", createIndex());
+
+	assert.equal(byText(result, "MipsAtom_")[0].type, "tapeAtomKeyword");
+	assert.deepEqual(byText(result, "cube_g4_face")[0].modifiers, ["declaration"]);
+	assert.equal(byText(result, "atom_bind")[0].type, "tapeAnnotation");
+	assert.equal(byText(result, "Binds_CubeTri").at(-1).type, "tapeBindType");
+	assert.equal(byText(result, "cube_g4")[0].type, "tapePhase");
+	assert.deepEqual(byText(result, "cube_g4")[0].modifiers, ["declaration"]);
+	assert.equal(byText(result, "cull")[0].type, "tapeLabel");
+	assert.equal(byText(result, "exit").every((span) => span.type === "tapeLabel"), true);
+});
+
+test("classifyDocument applies read and write modifiers to GPRs", () => {
+	const source = "atom_info(atom_reads(R_PrimCursor), atom_writes(R_FaceCursor))";
+	const result = classifyDocument(source, "C:/x/code/test.atom.c", createIndex());
+
+	assert.deepEqual(byText(result, "R_PrimCursor")[0].modifiers, ["tapeRead"]);
+	assert.deepEqual(byText(result, "R_FaceCursor")[0].modifiers, ["tapeWrite"]);
+});
+
+test("classifyDocument separates CPU, GTE, GPU, and component domains", () => {
+	const workspace = createIndex();
+	workspace.macros.set("load_word", "cpu");
+	workspace.macros.set("gte_cmdw_rtpt", "gte");
+	workspace.macros.set("gp1_word_DisplayOn", "gpu");
+	workspace.macros.set("mac_yield", "control");
+	workspace.componentAliases.add("mac_yield");
+
+	const source = "load_word(R_T0, R_T1, 0), gte_cmdw_rtpt, gp1_word_DisplayOn(), mac_yield(), C2_MAC0, gte_cr_OFX_Code";
+	const result = classifyDocument(source, "C:/x/code/test.c", workspace);
+
+	assert.equal(byText(result, "load_word")[0].type, "tapeCpuInstruction");
+	assert.equal(byText(result, "gte_cmdw_rtpt")[0].type, "tapeGteInstruction");
+	assert.equal(byText(result, "gp1_word_DisplayOn")[0].type, "tapeGpuInstruction");
+	assert.equal(byText(result, "mac_yield")[0].type, "tapeControlFlow");
+	assert.equal(byText(result, "C2_MAC0")[0].type, "tapeCop2Register");
+	assert.equal(byText(result, "gte_cr_OFX_Code")[0].type, "tapeCop2Register");
+});
+
+test("component invocations keep the domain resolved from their emitted instructions", () => {
+	const workspace = createIndex();
+	workspace.macros.set("mac_load_word_imm", "cpu");
+	workspace.macros.set("mac_gcmd_push", "gpu");
+	workspace.macros.set("mac_gte_store_f3", "gte");
+	workspace.macros.set("mac_load_v3s4", "cpu");
+
+	const source = "mac_load_word_imm(dst, imm), mac_gcmd_push(cmd), mac_gte_store_f3(cursor), mac_load_v3s4()";
+	const result = classifyDocument(source, "C:/x/code/hello_camera/hello_camera.atom.c", workspace);
+
+	assert.equal(byText(result, "mac_load_word_imm")[0].type, "tapeCpuInstruction");
+	assert.equal(byText(result, "mac_gcmd_push")[0].type, "tapeGpuInstruction");
+	assert.equal(byText(result, "mac_gte_store_f3")[0].type, "tapeGteInstruction");
+	assert.equal(byText(result, "mac_load_v3s4")[0].type, "tapeCpuInstruction");
+});
+
+test("utility macros without a hardware domain use the standard macro token", () => {
+	const workspace = createIndex();
+	workspace.macros.set("load_word", "cpu");
+	workspace.macros.set("assert", "utility");
+	workspace.macros.set("stringify", "utility");
+	workspace.macros.set("u4_hi", "utility");
+
+	const source = "load_word(R_T0, R_T1, 0), assert(ok), stringify(name), u4_hi(imm)";
+	const result = classifyDocument(source, "C:/x/code/hello_camera/hello_camera.c", workspace);
+
+	assert.equal(byText(result, "load_word")[0].type, "tapeCpuInstruction");
+	assert.equal(byText(result, "assert")[0].type, "macro");
+	assert.equal(byText(result, "stringify")[0].type, "macro");
+	assert.equal(byText(result, "u4_hi")[0].type, "macro");
+});
+
+test("document-local declarations override an empty workspace index", () => {
+	const source = [
+		"MipsAtomComp_(ac_new_component) { nop };",
+		"MipsAtomComp_Proc_(ab, { nop })",
+		"mac_new_component(),",
+	].join("\n");
+	const result = classifyDocument(source, "C:/x/code/duffle/math.atom.c", createIndex());
+
+	assert.equal(byText(result, "MipsAtomComp_")[0].type, "keyword");
+	assert.equal(byText(result, "MipsAtomComp_Proc_")[0].type, "keyword");
+	assert.equal(byText(result, "ac_new_component")[0].type, "tapeComponentName");
+	assert.equal(byText(result, "mac_new_component")[0].type, "tapeComponentInstruction");
+});
+
+test("delay slot markers share the tapeDelaySlot token", () => {
+	const source = "LdSlot_ nop, BdSlot_ nop, DmaSlot_ nop2, GteDelay_ nop";
+	const result = classifyDocument(source, "C:/x/code/duffle/gte.atom.c", createIndex());
+
+	assert.equal(byText(result, "LdSlot_")[0].type, "tapeDelaySlot");
+	assert.equal(byText(result, "BdSlot_")[0].type, "tapeDelaySlot");
+	assert.equal(byText(result, "DmaSlot_")[0].type, "tapeDelaySlot");
+	assert.equal(byText(result, "GteDelay_")[0].type, "tapeDelaySlot");
+});
+
+test("classifier returns ordered non-overlapping spans and partial malformed output", () => {
+	const source = "atom_reads(R_A /* broken";
+	const result = classifyDocument(source, "C:/x/code/test.atom.c", createIndex());
+
+	assert.equal(result.errors.some((error) => error.kind === "unterminated-block-comment"), true);
+	for (let spanIndex = 1; spanIndex < result.spans.length; spanIndex += 1) {
+		const previous = result.spans[spanIndex - 1];
+		const current = result.spans[spanIndex];
+		assert.equal(previous.start + previous.length <= current.start, true);
+	}
+});

.vscode/tape-atom-syntax/test/contract.test.js

@@ -0,0 +1,88 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const test = require("node:test");
+
+const { TOKEN_MODIFIERS, TOKEN_TYPES } = require("../classifier");
+
+const ROOT = path.resolve(__dirname, "..");
+
+function readJson(filePath) {
+	const raw = fs.readFileSync(filePath, "utf8");
+	const stripped = raw.replace(/\/\/.*$/gm, "").replace(/,\s*([}\]])/g, "$1");
+	return JSON.parse(stripped);
+}
+
+function collectScopeNames(value, output = new Set()) {
+	if (Array.isArray(value)) {
+		for (const entry of value) collectScopeNames(entry, output);
+		return output;
+	}
+	if (!value || typeof value !== "object") return output;
+	if (typeof value.name === "string") output.add(value.name);
+	for (const child of Object.values(value)) collectScopeNames(child, output);
+	return output;
+}
+
+test("package semantic legend matches classifier exports", () => {
+	const packageJson = readJson(path.join(ROOT, "package.json"));
+	const contributedTypes = packageJson.contributes.semanticTokenTypes.map((entry) => entry.id);
+	const contributedModifiers = packageJson.contributes.semanticTokenModifiers.map((entry) => entry.id);
+
+	assert.equal(packageJson.version, "0.3.0");
+	assert.deepEqual(contributedTypes, TOKEN_TYPES);
+	assert.deepEqual(contributedModifiers, TOKEN_MODIFIERS.filter((name) => name !== "declaration"));
+});
+
+test("package includes runtime files only and acknowledges local-only metadata", () => {
+	const packageJson = readJson(path.join(ROOT, "package.json"));
+
+	assert.deepEqual(packageJson.files, [
+		"classifier.js",
+		"extension.js",
+		"lexer.js",
+		"source-index.js",
+		"syntaxes/tape_atom.tmLanguage.json",
+	]);
+	assert.equal(packageJson.scripts.package.includes("--allow-missing-repository"), true);
+	assert.equal(packageJson.scripts.package.includes("--skip-license"), true);
+});
+
+test("every semantic token has a scope mapping; DSL-specific tokens also have grammar scopes", () => {
+	const packageJson = readJson(path.join(ROOT, "package.json"));
+	const grammar = readJson(path.join(ROOT, "syntaxes", "tape_atom.tmLanguage.json"));
+	const mappings = packageJson.contributes.semanticTokenScopes[0].scopes;
+	const grammarScopes = collectScopeNames(grammar);
+
+	const grammarRequired = new Set([
+		"tapeAtomKeyword", "tapeAtomName", "tapeComponentName",
+		"tapeAnnotation", "tapeBindType", "tapePhase", "tapeLabel",
+		"tapeDelaySlot", "tapeDuffleType", "keyword",
+	]);
+
+	for (const tokenType of TOKEN_TYPES) {
+		assert.equal(Array.isArray(mappings[tokenType]), true, `missing scope mapping: ${tokenType}`);
+		if (grammarRequired.has(tokenType)) {
+			assert.equal(mappings[tokenType].some((scope) => grammarScopes.has(scope)), true, `grammar does not emit: ${tokenType}`);
+		}
+	}
+});
+
+test("TextMate offset labels stay scoped to atom_offset calls", () => {
+	const grammar = readJson(path.join(ROOT, "syntaxes", "tape_atom.tmLanguage.json"));
+	const serialized = JSON.stringify(grammar);
+	const offsetRule = grammar.repository["annotation-arguments"].patterns
+		.find((rule) => rule.match.includes("atom_offset"));
+
+	assert.equal(serialized.includes("(?<=,)"), false);
+	assert.equal(offsetRule.captures[1].name, "support.function.duffle.annotation");
+	assert.equal(offsetRule.captures[2].name, "entity.name.label.duffle.atom");
+	assert.equal(offsetRule.captures[3].name, "entity.name.label.duffle.atom");
+});
+
+test("workspace enables semantic highlighting", () => {
+	const settings = readJson(path.resolve(ROOT, "..", "settings.json"));
+	assert.equal(settings["editor.semanticHighlighting.enabled"], true);
+});

.vscode/tape-atom-syntax/test/lexer.test.js

@@ -0,0 +1,77 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { buildCallContexts, lex, nearestCall } = require("../lexer");
+
+test("lex skips comments, strings, and character literals", () => {
+	const source = [
+		"MipsAtom_(visible)",
+		"// MipsAtom_(line_comment)",
+		"const char *s = \"atom_reads(R_Hidden)\";",
+		"char c = '\\''; /* gte_cmdw_hidden */",
+		"atom_reads(R_Visible)",
+	].join("\n");
+
+	const result = lex(source);
+	const identifiers = result.tokens
+		.filter((token) => token.kind === "identifier")
+		.map((token) => token.text);
+
+	assert.deepEqual(result.errors, []);
+	assert.equal(identifiers.includes("visible"), true);
+	assert.equal(identifiers.includes("R_Visible"), true);
+	assert.equal(identifiers.includes("line_comment"), false);
+	assert.equal(identifiers.includes("R_Hidden"), false);
+	assert.equal(identifiers.includes("gte_cmdw_hidden"), false);
+});
+
+test("lex reports unterminated block comments without returning comment tokens", () => {
+	const result = lex("R_Visible /* atom_reads(R_Hidden)");
+
+	assert.equal(result.tokens.some((token) => token.text === "R_Visible"), true);
+	assert.equal(result.tokens.some((token) => token.text === "R_Hidden"), false);
+	assert.deepEqual(result.errors.map((error) => error.kind), ["unterminated-block-comment"]);
+});
+
+test("line comments stop at CRLF boundaries", () => {
+	const result = lex("// atom_reads(R_Hidden)\r\natom_reads(R_Visible)\r\n");
+	const identifiers = result.tokens
+		.filter((token) => token.kind === "identifier")
+		.map((token) => token.text);
+
+	assert.equal(identifiers.includes("R_Hidden"), false);
+	assert.equal(identifiers.includes("R_Visible"), true);
+});
+
+test("balanced contexts retain multiline nesting and argument indexes", () => {
+	const source = [
+		"atom_info(",
+		"\tatom_phase(cube_g4),",
+		"\tatom_reads(R_A, nested(R_B, R_C)),",
+		"\tatom_writes(R_D)",
+		")",
+	].join("\n");
+	const lexical = lex(source);
+	const balanced = buildCallContexts(lexical.tokens);
+
+	const byText = new Map();
+	lexical.tokens.forEach((token, index) => {
+		if (token.kind === "identifier") byText.set(token.text, index);
+	});
+
+	assert.equal(nearestCall(balanced.contexts, byText.get("cube_g4")).callee, "atom_phase");
+	assert.equal(nearestCall(balanced.contexts, byText.get("R_A")).callee, "atom_reads");
+	assert.equal(nearestCall(balanced.contexts, byText.get("R_A")).argIndex, 0);
+	assert.equal(nearestCall(balanced.contexts, byText.get("R_C")).callee, "nested");
+	assert.equal(nearestCall(balanced.contexts, byText.get("R_D")).callee, "atom_writes");
+	assert.deepEqual(balanced.errors, []);
+});
+
+test("balanced contexts report unmatched parentheses", () => {
+	const lexical = lex("atom_reads(R_A");
+	const balanced = buildCallContexts(lexical.tokens);
+
+	assert.deepEqual(balanced.errors.map((error) => error.kind), ["unmatched-open-paren"]);
+});

.vscode/tape-atom-syntax/test/source-index.test.js

@@ -0,0 +1,134 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const {
+	createIndex,
+	domainFromPath,
+	mergeIndexes,
+	scanSource,
+} = require("../source-index");
+
+test("scanSource discovers current atom and component forms", () => {
+	const source = [
+		"MipsAtom_(cube_g4_face) atom_info(atom_phase(cube_g4), atom_reads(R_PrimCursor)) { mac_yield() };",
+		"MipsAtomComp_(ac_load_pair) { load_word(R_T0, R_T1, 0) };",
+		"internal MipsAtom* normalize_proc(AtomArena_R aa) MipsAtom_Proc_(aa, { mac_yield() })",
+		"FI_ void ac_store_pair(MipsAtomBuilder_R ab) atom_dbg_skip MipsAtomComp_Proc_(ab, { store_word(R_T0, R_T1, 0) })",
+	].join("\n");
+
+	const result = scanSource(source, "C:/projects/Pikuma/ps1/code/duffle/mips.atom.c");
+
+	assert.equal(result.index.atoms.has("cube_g4_face"), true);
+	assert.equal(result.index.atoms.has("normalize"), true);
+	assert.equal(result.index.components.has("ac_load_pair"), true);
+	assert.equal(result.index.components.has("ac_store_pair"), true);
+	assert.equal(result.index.componentAliases.has("mac_load_pair"), true);
+	assert.equal(result.index.componentAliases.has("mac_store_pair"), true);
+	assert.equal(result.index.macros.get("mac_store_pair"), "component");
+	assert.equal(result.index.componentCallees.get("mac_store_pair").includes("store_word"), true);
+	assert.equal(result.index.phases.has("cube_g4"), true);
+	assert.equal(result.index.registers.get("R_PrimCursor"), "gpr");
+	assert.deepEqual(result.errors, []);
+});
+
+test("scanSource discovers binds, labels, registers, typedefs, and macro domains", () => {
+	const source = [
+		"typedef Struct_(Binds_CubeTri) { U4 PrimCursor; };",
+		"typedef Enum_(U4, PadStatus) { PadStatus_Ok };",
+		"typedef U4 const MipsCode;",
+		"enum { R_PrimCursor = R_T7 atom_reg, C2_Custom = 12, gte_cr_Custom = 13 };",
+		"#define load_word(rt, base, off) enc_i(rt, base, off)",
+		"atom_bind(Binds_CubeTri)",
+		"atom_label(exit)",
+		"atom_offset(entry, exit)",
+	].join("\n");
+
+	const result = scanSource(source, "C:/projects/Pikuma/ps1/code/duffle/mips.h");
+
+	assert.equal(result.index.bindTypes.has("Binds_CubeTri"), true);
+	assert.equal(result.index.types.has("PadStatus"), true);
+	assert.equal(result.index.types.has("MipsCode"), true);
+	assert.equal(result.index.registers.get("R_PrimCursor"), "gpr");
+	assert.equal(result.index.registers.get("C2_Custom"), "cop2");
+	assert.equal(result.index.registers.get("gte_cr_Custom"), "cop2");
+	assert.equal(result.index.macros.get("load_word"), "cpu");
+	assert.equal(result.index.labels.has("entry"), true);
+	assert.equal(result.index.labels.has("exit"), true);
+});
+
+test("domainFromPath uses the declaration file rather than parent directory names", () => {
+	assert.equal(domainFromPath("C:/x/code/hello_gte/hello_gte.atom.c"), null);
+	assert.equal(domainFromPath("C:/x/code/duffle/mips.h"), "cpu");
+	assert.equal(domainFromPath("C:/x/code/duffle/gte.h"), "gte");
+	assert.equal(domainFromPath("C:/x/code/duffle/gp.h"), "gpu");
+});
+
+test("component aliases inherit the domain of the instructions they emit", () => {
+	const headers = mergeIndexes(
+		scanSource("#define load_word(a,b,c) 1\n#define store_word(a,b,c) 1\n#define shift_aright_var(a,b,c) 1\n#define jump_reg(rd) 1\n", "C:/x/code/duffle/mips.h").index,
+		scanSource("#define gte_sw(rt, base, off) 1\n", "C:/x/code/duffle/gte.h").index
+	);
+	const math = scanSource(
+		[
+			"MipsAtomComp_(ac_load_v3s4) { load_word(R_T0, R_T1, 0) };",
+			"#define mac_load_p3s4 mac_load_v3s4",
+		].join("\n"),
+		"C:/x/code/duffle/math.atom.c"
+	);
+	const shift = scanSource(
+		"MipsAtomComp_(ac_shift_aright_var_v3_self) { shift_aright_var(R_T0, R_T0, R_T1) };",
+		"C:/x/code/duffle/gte.atom.c"
+	);
+	const gte = scanSource(
+		"MipsAtomComp_(ac_gte_store_f3) { gte_sw(C2_SXY0, R_T0, 0) };",
+		"C:/x/code/duffle/gte.atom.c"
+	);
+	const yieldAtom = scanSource(
+		"MipsAtomComp_(ac_yield) { load_word(R_AtomJmp, R_TapePtr, 0), jump_reg(R_AtomJmp), nop };",
+		"C:/x/code/duffle/lottes_tape.h"
+	);
+
+	const merged = mergeIndexes(headers, math.index, shift.index, gte.index, yieldAtom.index);
+	assert.equal(merged.macros.get("mac_load_v3s4"), "cpu");
+	assert.equal(merged.macros.get("mac_load_p3s4"), "cpu");
+	assert.equal(merged.macros.get("mac_shift_aright_var_v3_self"), "cpu");
+	assert.equal(merged.macros.get("mac_gte_store_f3"), "gte");
+	assert.equal(merged.macros.get("mac_yield"), "control");
+});
+
+test("scanSource tags utility header defines as utility, not a hardware domain", () => {
+	const source = [
+		"#define assert(cond) ((void)(cond))",
+		"#define stringify(name) #name",
+		"#define u4_hi(imm) ((imm) >> 16)",
+	].join("\n");
+	const result = scanSource(source, "C:/projects/Pikuma/ps1/code/duffle/dsl.h");
+
+	assert.equal(result.index.macros.get("assert"), "utility");
+	assert.equal(result.index.macros.get("stringify"), "utility");
+	assert.equal(result.index.macros.get("u4_hi"), "utility");
+});
+
+test("mergeIndexes prefers a hardware domain over a later utility define", () => {
+	const left = createIndex();
+	left.macros.set("sub_s", "utility");
+	const right = createIndex();
+	right.macros.set("sub_s", "cpu");
+
+	assert.equal(mergeIndexes(left, right).macros.get("sub_s"), "cpu");
+	assert.equal(mergeIndexes(right, left).macros.get("sub_s"), "cpu");
+});
+
+test("mergeIndexes preserves domain-specific aliases", () => {
+	const left = createIndex();
+	left.macros.set("load_word", "cpu");
+	const right = createIndex();
+	right.componentAliases.add("mac_gte_store");
+	right.macros.set("mac_gte_store", "gte");
+
+	const merged = mergeIndexes(left, right);
+	assert.equal(merged.macros.get("load_word"), "cpu");
+	assert.equal(merged.macros.get("mac_gte_store"), "gte");
+});

LICENSE

@@ -1,24 +1,17 @@
-This is free and unencumbered software released into the public domain.
+Copyright (C) 2026 Edward R. Gonzalez
 
-Anyone is free to copy, modify, publish, use, compile, sell, or
+This software is provided 'as-is', without any express or implied
-distribute this software, either in source code form or as a compiled
+warranty.  In no event will the authors be held liable for any damages
-binary, for any purpose, commercial or non-commercial, and by any
+arising from the use of this software.
-means.
 
-In jurisdictions that recognize copyright laws, the author or authors
+Permission is granted to anyone to use this software for any purpose,
-of this software dedicate any and all copyright interest in the
+including commercial applications, and to alter it and redistribute it
-software to the public domain. We make this dedication for the benefit
+freely, subject to the following restrictions:
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+1. The origin of this software must not be misrepresented; you must not
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   claim that you wrote the original software. If you use this software
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+   in a product, an acknowledgment in the product documentation would be
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+   appreciated but is not required.
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+2. Altered source versions must be plainly marked as such, and must not be
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+   misrepresented as being the original software.
-OTHER DEALINGS IN THE SOFTWARE.
+3. This notice may not be removed or altered from any source distribution.
-
-For more information, please refer to <https://unlicense.org>

code/duffle/dsl.atom.h

@@ -70,8 +70,8 @@
 /* ----------------------------------------------------------------------------
  * atom_reg (per-enum opt-in marker for the DWARF register-alias registry)
  *
- * The bare `atom_reg` token adjacent to an enum entry in mips.h / lottes_tape.h flags that alias as debug-visible for scan_source's register_alias_registry.
+ * Bare `atom_reg` token adjacent to an enum entry that alias as debug-visible for scan_source's register_alias_registry.
- * The C preprocessor strips it to a comment so no runtime symbol is created; the Lua scanner reads the bare token.
+ * Lua scanner reads the bare token.
  * ----------------------------------------------------------------------------*/
 #define atom_reg /* atom_reg: opt the preceding enum entry into the DWARF registry */
 

code/duffle/dsl.h

@@ -3,7 +3,7 @@
 #	include "assert.h"
 #endif
 
-#define offset_of(type, member)  cast(U8,__builtin_offsetof(type,member))
+#define offset_of(type, member)  cast(U8,__builtin_offsetof(type,member)) // Compiler builtin version of O_
 #define static_assert            _Static_assert
 #define typeof                   __typeof__
 #define typeof_ptr(ptr)          typeof((ptr)[0])
@@ -97,6 +97,7 @@
 #define Array_expand(type,len)         type Array_sym(type, len)[len]; typedef PtrSet_(Array_sym(type, len))
 #define Array_(type,len)               Array_expand(type,len)
 #define Bit_(id,b)                     id = (1 << b), tmpl(id,pos) = b
+#define Bitmask_(b)                    (1u << b)
 #define Enum_(underlying_type, symbol) underlying_type TSet_(symbol); enum   symbol
 #define Proc_(symbol)                  symbol
 #define Relative_(symbol)              // Does nothing but annotate that a symbol is associated with another.
@@ -139,17 +140,17 @@ enum { false = 0, true  = 1, true_overflow, };
 
 typedef void Proc_(VoidFn) (void);
 
-#define kilo(n)                (C_(U4, n) << 10)
+#define Kilo_(n) (C_(U4, n) << 10)
-#define mega(n)                (C_(U4, n) << 20)
+#define Mega_(n) (C_(U4, n) << 20)
-#define giga(n)                (C_(U4, n) << 30)
+#define Giga_(n) (C_(U4, n) << 30)
-#define tera(n)                (C_(U4, n) << 40)
+#define Tera_(n) (C_(U4, n) << 40)
 
-#define null                    C_(U4,    0)
+#define null             C_(U4,    0)
-#define nullptr                 C_(void*, 0)
+#define nullptr          C_(void*, 0)
-#define O_(type, field)         C_(U4, & C_(type*,0)->field)
+#define O_(type, field)  C_(U4, & C_(type*,0)->field)
-#define OA_(type, member, idx)  C_(U4, & C_(type*,0)->member[idx])
+#define OA_(type, aexpr) C_(U4, & C_(type*,0) aexpr)
-#define OT_(field)              O_(typeof_ptr(& field), filed))
+#define OT_(field)       O_(typeof_ptr(& field), field))
-#define S_(data)                C_(U4, sizeof(data))
+#define S_(data)         C_(U4, sizeof(data))
 
 #define sop_1(op,a,b) C_(U1, s1_(a) op s1_(b))
 #define sop_2(op,a,b) C_(U2, s2_(a) op s2_(b))
@@ -185,7 +186,7 @@ def_signed_ops(le, <=)
 #define alignas                             _Alignas
 #define alignof                             _Alignof
 #define byte_pad(amount, ...)               B1 glue(_PAD_, __VA_ARGS__) [amount]
-#define pcast(type, data)                   (C_(type*, & (data)) [0])
+#define C_ptr(type, data)                   (C_(type*, & (data)) [0])
 
 #define dbg_args(...)                      __VA_ARGS__
 
@@ -200,6 +201,8 @@ def_signed_ops(le, <=)
 #define defer_info(type,expr, ...) for(type       info= {__VA_ARGS__}; info.once!=1;++info.once,(expr))    // Defer with tracked state
 
 #define do_while(cond) for (U8 once=0; once!=1 || (cond); ++once)
+
+#define Jmp_nZero_(cond,label) if (cond) goto label;
 #pragma endregion Control Flow & Iteration
 
 #define span_iter(type, iter, m_begin, op, m_end) ( \
@@ -216,16 +219,16 @@ def_signed_ops(le, <=)
 typedef Span_(S4);
 typedef Span_(U4);
 
-#if 0
 #pragma region Debug
-#define debug_trap() __builtin_debugtrap()
+#define debug_trap() __builtin_trap()
 #if BUILD_DEBUG
-IA_ void assert(U8 cond) { if(cond){return;} else{debug_trap(); ms_exit_process(1);} }
+	#define assert(cond) if(cond == false){debug_trap();}
 #else
-#define assert(cond)
+#	ifndef assert
+#		include <assert.h>
+#	endif
 #endif
 #pragma endregion Debug
-#endif
 
 #define GCC_OPTIMIZATION_DISABLE _Pragma("GCC push_options") _Pragma("GCC optimize(\"O0\")")
 #define GCC_OPTIMIZATION_ENABLE  _Pragma("GCC pop_options")

code/duffle/gen/macs.h

@@ -17,7 +17,7 @@
 //   source: C:\projects\Pikuma\ps1\code\duffle\bios.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\psyq.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\pad.c
-//   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.c
+//   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\mips.atom.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\gte.atom.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\gp.atom.c
@@ -58,10 +58,21 @@ WORD_COUNT(mac_yield_load, 1)
 ,	nop
 WORD_COUNT(mac_yield_tail, 3)
 
+/* atom_dbg_skip */
+#define mac_load_half_v3(tx, ty, tz, base, offset) \
+	load_half(tx, base, offset + OA_(U2,[0])) \
+,	load_half(ty, base, offset + OA_(U2,[1])) \
+,	load_half(tz, base, offset + OA_(U2,[2]))
+WORD_COUNT(mac_load_half_v3, 3)
+
+#define mac_load_v3s2(transfer, base, offset) \
+	mac_load_half_v3(transfer.x, transfer.y, transfer.z, base, offset)
+WORD_COUNT(mac_load_v3s2, 3)
+
 /* atom_dbg_skip */
 #define mac_load_v2s2(rs_x, rs_y, r_base, offset) \
-	load_half( rs_x, r_base, offset + O_(V3_S2,x)) \
+	load_half(rs_x, r_base, offset + O_(V3_S2,x)) \
-,	load_half( rs_y, r_base, offset + O_(V3_S2,y))
+,	load_half(rs_y, r_base, offset + O_(V3_S2,y))
 WORD_COUNT(mac_load_v2s2, 2)
 
 /* atom_dbg_skip */
@@ -71,26 +82,75 @@ WORD_COUNT(mac_load_v2s2, 2)
 WORD_COUNT(mac_store_v2s2, 2)
 
 /* atom_dbg_skip */
-#define mac_load_v3s4(rs_x, rs_y, rs_z, r_base, offset) \
+#define mac_load_word_v3(tx, ty, tz, base, offset) \
-	load_word( rs_x, r_base, offset + O_(V3_S4,x)) \
+	load_word(tx, base, offset + OA_(U4,[0])) \
-,	load_word( rs_y, r_base, offset + O_(V3_S4,y)) \
+,	load_word(ty, base, offset + OA_(U4,[1])) \
-,	load_word( rs_z, r_base, offset + O_(V3_S4,z))
+,	load_word(tz, base, offset + OA_(U4,[2]))
+WORD_COUNT(mac_load_word_v3, 3)
+
+#define mac_load_v3s4(transfer, base, offset) \
+	mac_load_word_v3(transfer.x, transfer.y, transfer.z, base, offset)
 WORD_COUNT(mac_load_v3s4, 3)
 
-/* atom_dbg_skip */
+#define mac_load_p3s4(transfer, base, offset) \
-#define mac_store_v3s4(rt_x, rt_y, rt_z, base, offset) \
+	mac_load_word_v3(transfer.x, transfer.y, transfer.z, base, offset)
-	store_word(rt_x, base, offset + O_(V3_S4,x)) \
+WORD_COUNT(mac_load_p3s4, 3)
-,	store_word(rt_y, base, offset + O_(V3_S4,y)) \
-,	store_word(rt_z, base, offset + O_(V3_S4,z))
-WORD_COUNT(mac_store_v3s4, 3)
 
 /* atom_dbg_skip */
-#define mac_sub_v3s4(rds_x, rds_y, rds_z, rt_x, rt_y, rt_z) \
+#define mac_store_half_v3(tx, ty, tz, base, offset) \
-	sub_s(rds_x, rds_x, rt_x) \
+	store_half(tx, base, offset + OA_(U2,[0])) \
-,	sub_s(rds_y, rds_y, rt_y) \
+,	store_half(ty, base, offset + OA_(U2,[1])) \
-,	sub_s(rds_z, rds_z, rt_z)
+,	store_half(tz, base, offset + OA_(U2,[2]))
+WORD_COUNT(mac_store_half_v3, 3)
+
+#define mac_store_v3s2(transfer, base, offset) \
+	mac_store_half_v3(transfer.x, transfer.y, transfer.z, base, offset)
+WORD_COUNT(mac_store_v3s2, 3)
+
+/* atom_dbg_skip */
+#define mac_store_word_v3(tx, ty, tz, base, offset) \
+	store_word(tx, base, offset + OA_(U4,[0])) \
+,	store_word(ty, base, offset + OA_(U4,[1])) \
+,	store_word(tz, base, offset + OA_(U4,[2]))
+WORD_COUNT(mac_store_word_v3, 3)
+
+#define mac_store_v3s4(transfer, base, offset) \
+	mac_store_word_v3(transfer.x, transfer.y, transfer.z, base, offset)
+WORD_COUNT(mac_store_v3s4, 3)
+
+#define mac_store_p3s4(transfer, base, offset) \
+	mac_store_word_v3(transfer.x, transfer.y, transfer.z, base, offset)
+WORD_COUNT(mac_store_p3s4, 3)
+
+/* atom_dbg_skip */
+#define mac_add_si_v3s4(rt_x, rt_y, rt_z, base, offset) \
+	add_si(rt_x, base, O_(V3_S4,x)) \
+,	add_si(rt_y, base, O_(V3_S4,y)) \
+,	add_si(rt_z, base, O_(V3_S4,z))
+WORD_COUNT(mac_add_si_v3s4, 3)
+
+/* atom_dbg_skip */
+#define mac_sub_s_v3(dx, dy, dz, sx, sy, sz, tx, ty, tz) \
+	sub_s(dx, sx, tx) \
+,	sub_s(dy, sy, ty) \
+,	sub_s(dz, sz, tz)
+WORD_COUNT(mac_sub_s_v3, 3)
+
+#define mac_sub_v3s4(d, s, t) \
+	mac_sub_s_v3(d.x, d.y, d.z, s.x, s.y, s.z, t.x, t.y, t.z)
 WORD_COUNT(mac_sub_v3s4, 3)
 
+/* atom_dbg_skip */
+#define mac_sub_s_v3_self(ds_x, ds_y, ds_z, tx, ty, tz) \
+	sub_s(ds_x, ds_x, tx) \
+,	sub_s(ds_y, ds_y, ty) \
+,	sub_s(ds_z, ds_z, tz)
+WORD_COUNT(mac_sub_s_v3_self, 3)
+
+#define mac_sub_v3s4_self(ds, t) \
+	mac_sub_s_v3_self(ds.x, ds.y, ds.z, t.x, t.y, t.z)
+WORD_COUNT(mac_sub_v3s4_self, 3)
+
 /* atom_dbg_skip */
 #define mac_store_rects2(rt_x, rt_y, rt_width, rt_height, base, offset) \
 	store_half(rt_x,      base, offset + O_(Rect_S2,x)) \
@@ -99,6 +159,30 @@ WORD_COUNT(mac_sub_v3s4, 3)
 ,	store_half(rt_height, base, offset + O_(Rect_S2,height))
 WORD_COUNT(mac_store_rects2, 4)
 
+/* atom_dbg_skip */
+#define mac_load_word_imm(dst, imm) \
+	load_upper_i(dst, u4_hi(imm)) \
+,	or_i_self(   dst, u4_lo(imm))
+WORD_COUNT(mac_load_word_imm, 2)
+
+#define mac_shift_aright_v3_self(dt_x, dt_y, dt_z, shift_amount) \
+	shift_aright(dt_x, dt_x, shift_amount) \
+,	shift_aright(dt_y, dt_y, shift_amount) \
+,	shift_aright(dt_z, dt_z, shift_amount)
+WORD_COUNT(mac_shift_aright_v3_self, 3)
+
+#define mac_shift_aright_var_v3(rd_v0, rd_v1, rd_v2, rs_v0, rs_v1, rs_v2, r_shift) \
+	shift_aright_var(rd_v0, rs_v0, r_shift) \
+,	shift_aright_var(rd_v1, rs_v1, r_shift) \
+,	shift_aright_var(rd_v2, rs_v2, r_shift)
+WORD_COUNT(mac_shift_aright_var_v3, 3)
+
+#define mac_shift_aright_var_v3_self(rds_v0, rds_v1, rds_v2, r_shift) \
+	shift_aright_var(rds_v0, rds_v0, r_shift) \
+,	shift_aright_var(rds_v1, rds_v1, r_shift) \
+,	shift_aright_var(rds_v2, rds_v2, r_shift)
+WORD_COUNT(mac_shift_aright_var_v3_self, 3)
+
 /* atom_dbg_skip */
 #define mac_load_tri_indices(r_face_cusor, r_i0, r_i1, r_i2) \
 	load_half_u(r_i0, r_face_cusor, 0 * S_(S2)) \
@@ -119,19 +203,19 @@ WORD_COUNT(mac_gte_store_f3, 3)
 ,	add_u_self(R_AT, r_vert_base) \
 ,	load_word(R_V0, R_AT, O_(V3_S2,x)) \
 ,	load_word(R_V1, R_AT, O_(V3_S2,z)) \
-,	gte_mv_to_data_r(R_V0, C2_VXY0) \
+,	LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY0) \
 ,	gte_mv_to_data_r(R_V1, C2_VZ0) \
 ,	shift_lleft(R_AT, r_v1, v3s2_byteoff) \
 ,	add_u_self(R_AT, r_vert_base) \
 ,	load_word(R_V0, R_AT, O_(V3_S2,x)) \
 ,	load_word(R_V1, R_AT, O_(V3_S2,z)) \
-,	gte_mv_to_data_r(R_V0, C2_VXY1) \
+,	LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY1) \
 ,	gte_mv_to_data_r(R_V1, C2_VZ1) \
 ,	shift_lleft(R_AT, r_v2, v3s2_byteoff) \
 ,	add_u_self(R_AT, r_vert_base) \
 ,	load_word(R_V0, R_AT, O_(V3_S2,x)) \
 ,	load_word(R_V1, R_AT, O_(V3_S2,z)) \
-,	gte_mv_to_data_r(R_V0, C2_VXY2) \
+,	LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY2) \
 ,	gte_mv_to_data_r(R_V1, C2_VZ2)
 WORD_COUNT(mac_gte_load_tri_verts, 18)
 
@@ -149,16 +233,21 @@ WORD_COUNT(mac_gte_store_g4_p3, 1)
 
 /* atom_dbg_skip */
 #define mac_gte_sqr_v3(r_sx, r_sy, r_sz, r_sq_x, r_sq_y, r_sq_z) \
-	gte_mv_to_data_r(r_sx, C2_IR1) \
+	mac_gte_sqr_v3s4(r_sx, r_sy, r_sz, nop) \
-,	gte_mv_to_data_r(r_sy, C2_IR2) \
-,	gte_mv_to_data_r(r_sz, C2_IR3) \
-,	nop \
-,	gte_cmdw_sqr \
 ,	gte_mv_from_data_r(r_sq_x, C2_MAC1) \
 ,	gte_mv_from_data_r(r_sq_y, C2_MAC2) \
 ,	gte_mv_from_data_r(r_sq_z, C2_MAC3)
 WORD_COUNT(mac_gte_sqr_v3, 8)
 
+/* atom_dbg_skip */
+#define mac_gte_sqr_v3s4(r_sx, r_sy, r_sz, delay_slot) \
+	gte_mv_to_data_r(r_sx, C2_IR1) \
+,	gte_mv_to_data_r(r_sy, C2_IR2) \
+,	gte_mv_to_data_r(r_sz, C2_IR3) \
+,	delay_slot \
+,	gte_cmdw_sqr
+WORD_COUNT(mac_gte_sqr_v3s4, 5)
+
 /* atom_dbg_skip */
 #define mac_gte_gpf_scale(r_sx, r_sy, r_sz, r_recip_est, r_shift, r_dx, r_dy, r_dz) \
 	gte_mv_to_data_r(r_recip_est, C2_IR0) \
@@ -175,58 +264,46 @@ WORD_COUNT(mac_gte_sqr_v3, 8)
 ,	shift_aright_var(r_dz, r_dz, r_shift)
 WORD_COUNT(mac_gte_gpf_scale, 13)
 
-#define mac_apply_matrix_lv(r_mtx, r_vec, r_out, r_t0, r_t1, r_t2) \
+#define mac_trans_mt3s3s4(r_mtx, r_off, r_t0, r_t1, r_t2) \
-	load_word(r_t0, r_mtx,  0) \
+	load_word(r_t0, r_off, O_(V3_S4,x)) \
-,	nop \
-,	gte_mv_to_ctrl_r(r_t0, gte_cr_RT11_Code) \
-,	load_word(r_t0, r_mtx,  4) \
-,	nop \
-,	gte_mv_to_ctrl_r(r_t0, gte_cr_RT12_Code) \
-,	load_word(r_t0, r_mtx,  8) \
-,	nop \
-,	gte_mv_to_ctrl_r(r_t0, gte_cr_RT13_Code) \
-,	load_word(r_t0, r_mtx, 12) \
-,	nop \
-,	gte_mv_to_ctrl_r(r_t0, gte_cr_RT21_Code) \
-,	load_half_u(r_t0, r_mtx, 16) \
-,	nop \
-,	gte_mv_to_ctrl_r(r_t0, gte_cr_RT22_Code) \
-,	nop2	/* Load PACKED pos into V0 (libgte SVECTOR layout).
-	 * r_vec points to atom-0-staged packed data ((pos.y << 16) | pos.x at +0, pos.z at +4).
-	 * LWC2 base register MUST be the pointer r_vec, NOT the loaded value r_t0. */ \
-,	load_word(r_t0, r_vec, 0) \
-,	nop \
-,	gte_lw(C2_VXY0, r_vec, 0) \
-,	load_word(r_t0, r_vec, 4) \
-,	nop \
-,	gte_lw(C2_VZ0, r_vec, 4)	/* RTPS: cv=3 (no translation), sf=1 (no shift, integer), v=0 (V0 input),
-	 * mx=0 (rotation matrix). MAC = RT row · V0 + 0. RTPS also writes
-	 * SXY0/1/2 + SZ0..SZ3 (perspective division); ignored. */ \
-,	gte_cmdw_rtps_sf1	/* Read MAC1/2/3 → out. */ \
-,	gte_mv_from_data_r(r_t0, C2_MAC1) \
-,	gte_mv_from_data_r(r_t1, C2_MAC2) \
-,	gte_mv_from_data_r(r_t2, C2_MAC3) \
-,	nop \
-,	store_word(r_t0, r_out, 0) \
-,	store_word(r_t1, r_out, 4) \
-,	store_word(r_t2, r_out, 8)
-WORD_COUNT(mac_apply_matrix_lv, 31)
-
-#define mac_trans_matrix(r_mtx, r_off, r_t1) \
-	load_word(r_t1, r_off, O_(V3_S4,x)) \
-,	nop \
-,	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[0])) \
 ,	load_word(r_t1, r_off, O_(V3_S4,y)) \
-,	nop \
+,	load_word(r_t2, r_off, O_(V3_S4,z)) \
+,	store_word(r_t0, r_mtx, O_(MT3_S2S4,t[0])) \
 ,	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[1])) \
-,	load_word(r_t1, r_off, O_(V3_S4,z)) \
+,	store_word(r_t2, r_mtx, O_(MT3_S2S4,t[2]))
-,	nop \
+WORD_COUNT(mac_trans_mt3s3s4, 6)
-,	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[2]))
-WORD_COUNT(mac_trans_matrix, 9)
 
+/* atom_dbg_skip */
+#define mac_lzcr_round_even_half_shift(r_shift, r_mag_sq, r_mag_sq_copy) \
+	and_i(r_shift, r_shift, gte_lzcr_even_mask) \
+,	or_u(r_mag_sq_copy, r_mag_sq, 0) \
+,	li_s(r_mag_sq, 31) \
+,	sub_s(r_mag_sq, r_mag_sq, r_shift) \
+,	shift_aright(r_mag_sq, r_mag_sq, 1)
+WORD_COUNT(mac_lzcr_round_even_half_shift, 5)
+
+#define mac_gte_general_purpose_interopolation(to_ir0, to_ir1, to_ir2, to_ir3, fr_mac1, fr_mac2, fr_mac3, nop_slot1, nop_slot2) \
+	gte_mv_to_data_r(to_ir0, C2_IR0) \
+,	gte_mv_to_data_r(to_ir1, C2_IR1) /* IR1 = src.x (preserved in r_tmp — r_mac2_scratch was clobbered to MAC2 in stage 1.5) */ \
+,	gte_mv_to_data_r(to_ir2, C2_IR2) \
+,	gte_mv_to_data_r(to_ir3, C2_IR3) /* IR3 = src.z (reloaded) */ \
+,	GteDelay_ nop_slot1 \
+,	GteDelay_ nop_slot2 \
+,	gte_cmdw_gpf \
+,	gte_mv_from_data_r(fr_mac1, C2_MAC1) \
+,	gte_mv_from_data_r(fr_mac2, C2_MAC2) \
+,	gte_mv_from_data_r(fr_mac3, C2_MAC3)
+WORD_COUNT(mac_gte_general_purpose_interopolation, 10)
+
+#define mac_gte_mv_from_data_r_mac123(fr_mac1, fr_mac2, fr_mac3) \
+	gte_mv_from_data_r(fr_mac1, C2_MAC1) \
+,	gte_mv_from_data_r(fr_mac2, C2_MAC2) \
+,	gte_mv_from_data_r(fr_mac3, C2_MAC3)
+WORD_COUNT(mac_gte_mv_from_data_r_mac123, 3)
+
+/* atom_dbg_skip */
 #define mac_gcmd_push(cmd, reg_transfer, reg_base, port) \
-	load_upper_i(reg_transfer, u4_hi(cmd)) \
+	mac_load_word_imm(reg_transfer, cmd) \
-,	or_i_self(   reg_transfer, u4_lo(cmd))	/* load_upper_i(reg_transfer, cmd >> 16),	// or_i_self(   reg_transfer, cmd & 0xFFFF), */ \
 ,	store_word(  reg_transfer, reg_base, port)
 WORD_COUNT(mac_gcmd_push, 3)
 
@@ -249,6 +326,7 @@ WORD_COUNT(mac_pack_color_word, 3)
 	mac_pack_color_word(r_base, O_(Poly_F3,color), gp0_cmd_poly_f3, r, g, b)
 WORD_COUNT(mac_format_f3_color, 3)
 
+/* atom_dbg_skip */
 #define mac_format_g4_color(r_prim_cursor, r0, g0, b0, r1, g1, b1, r2, g2, b2, r3, g3, b3) \
 	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c0), gp0_cmd_poly_g4, r0,g0,b0) \
 ,	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c1), 0,               r1,g1,b1) \
@@ -270,16 +348,16 @@ WORD_COUNT(mac_format_g4_color, 12)
 WORD_COUNT(mac_insert_ot_tag, 11)
 
 /* atom_dbg_skip */
-#define mac_pad_set_centered_axes(r_state, r_scratch) \
+#define mac_pad_set_centered_axes(state, scratch) \
-	load_upper_i(r_scratch, (PadAxis_Centered_Word >> 16) & 0xFFFF) \
+	load_upper_i(scratch, (PadAxis_Centered >> 16) & 0xFFFF) \
-,	or_i_self(   r_scratch,  PadAxis_Centered_Word        & 0xFFFF) \
+,	or_i_self(   scratch,  PadAxis_Centered        & 0xFFFF)		/* mac_load_word_imm(scratch, PadAxis_Centered), */ \
-,	store_word(  r_scratch, r_state, O_(PadState,axes))
+,	store_word(       scratch, state, O_(PadState,axes))
 WORD_COUNT(mac_pad_set_centered_axes, 3)
 
 /* atom_dbg_skip */
-#define mac_pad_set_id_byte(r_state, r_id, id_value) \
+#define mac_pad_set_id_byte(state, r_id, id_value) \
 	add_ui(    r_id, R_0, id_value) \
-,	store_byte(r_id, r_state, O_(PadState,id))
+,	store_byte(r_id, state, O_(PadState,id))
 WORD_COUNT(mac_pad_set_id_byte, 2)
 
 /* atom_dbg_skip */
@@ -291,6 +369,6 @@ WORD_COUNT(mac_pad_set_status, 2)
 /* atom_dbg_skip */
 #define mac_pad_store_inverted_buttons(r_buttons, r_pad_state) \
 	nor_u(       r_buttons, r_buttons, R_0) \
-,	store_half(  r_buttons, r_pad_state, O_(PadState,   buttons))
+,	store_half(  r_buttons, r_pad_state, O_(PadState,buttons))
 WORD_COUNT(mac_pad_store_inverted_buttons, 2)
 

code/duffle/gen/offsets.h

@@ -14,7 +14,7 @@
 //   source: C:\projects\Pikuma\ps1\code\duffle\bios.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\psyq.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\pad.c
-//   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.c
+//   source: C:\projects\Pikuma\ps1\code\duffle\math.atom.h
 //   source: C:\projects\Pikuma\ps1\code\duffle\mips.atom.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\gte.atom.c
 //   source: C:\projects\Pikuma\ps1\code\duffle\gp.atom.c
@@ -25,7 +25,15 @@
 #pragma region duffle
 
 
-// --- atom: normalize_v3s4 (66 words) ---
+// --- atom: example_atom_proc (10 words) ---
+
+#define _atom_offset_example_atom_proc_skip           2
+
+enum {
+    atom_offset_example_atom_proc_skip = _atom_offset_example_atom_proc_skip,
+};
+
+// --- atom: build_normalize_v3s4 (61 words) ---
 
 #define _atom_offset_aligned_done_srav_path           3
 #define _atom_offset_srav_path_aligned_done           4

code/duffle/gp.atom.c

@@ -9,36 +9,34 @@ ATOM_FILE_DEBUGGER_LINE_MARKER(gp_atom_c);
 #pragma region MACs (Mips Atom Components)
 
 FI_ Slice_MipsCode ac_gcmd_push(AtomBuilder_R ab, U4 cmd, U4 reg_transfer, U4 reg_base, U2 port)
-MipsAtomComp_Proc_(ac_gcmd_push, ab, {
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
-	load_upper_i(reg_transfer, u4_hi(cmd)),
+	mac_load_word_imm(reg_transfer, cmd),
-	or_i_self(   reg_transfer, u4_lo(cmd)),
-	// load_upper_i(reg_transfer, cmd >> 16),
-	// or_i_self(   reg_transfer, cmd & 0xFFFF),
 	store_word(  reg_transfer, reg_base, port),
 })
 
-FI_ Slice_MipsCode ac_store_rgb8(AtomBuilder_R ab, U1 rr, U1 rg, U1 rb, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_store_rgb8, ab, {
+FI_ Slice_MipsCode ac_store_rgb8(AtomBuilder_R ab, U1 rr, U1 rg, U1 rb, U4 base, U4 offset) 
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	store_byte(rr, base, offset + O_(RGB8,r)),
 	store_byte(rg, base, offset + O_(RGB8,g)),
 	store_byte(rb, base, offset + O_(RGB8,b)),
 })
 
 FI_ Slice_MipsCode ac_pack_color_word(AtomBuilder_R ab, U4 r_base, U4 off, U4 cmd, U1 r, U1 g, U1 b)
-atom_dbg_skip MipsAtomComp_Proc_(ac_pack_color_word, ab, {
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	load_upper_i(R_AT, (cmd) << 8  | (b)),
 	or_i_self(   R_AT, ((g)  << 8) | (r)),
 	store_word(  R_AT, r_base, (off)),
 })
 
 FI_ Slice_MipsCode ac_format_f3_color(AtomBuilder_R ab, U4 r_base, U1 r, U1 g, U1 b)
-atom_dbg_skip MipsAtomComp_Proc_(ac_format_f3_color, ab, { mac_pack_color_word(r_base, O_(Poly_F3,color), gp0_cmd_poly_f3, r, g, b) })
+atom_dbg_skip MipsAtomComp_Proc_(ab, { mac_pack_color_word(r_base, O_(Poly_F3,color), gp0_cmd_poly_f3, r, g, b) })
 
 FI_ Slice_MipsCode ac_format_g4_color(AtomBuilder_R ab, U4 r_prim_cursor,
 	U1 r0, U1 g0, U1 b0,
   U1 r1, U1 g1, U1 b1,
   U1 r2, U1 g2, U1 b2,
   U1 r3, U1 g3, U1 b3)
-MipsAtomComp_Proc_(ac_format_g4_color, ab, {
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c0), gp0_cmd_poly_g4, r0,g0,b0),
 	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c1), 0,               r1,g1,b1),
 	mac_pack_color_word(r_prim_cursor, O_(Poly_G4,c2), 0,               r2,g2,b2),
@@ -46,7 +44,8 @@ MipsAtomComp_Proc_(ac_format_g4_color, ab, {
 })
 
 /* Words: 11; Correctly inserts a primitive into the Ordering Table linked list. */
-I_ Slice_MipsCode ac_insert_ot_tag(AtomBuilder_R ab, U4 r_ot_base, U4 r_prim_cursor, U4 poly_size) MipsAtomComp_Proc_(ac_insert_ot_tag, ab, {
+// TODO(Ed): Expose R_T1 as a r_t0, r_V0 as r_t2
+I_ Slice_MipsCode ac_insert_ot_tag(AtomBuilder_R ab, Reg r_ot_base, Reg r_prim_cursor, U2 poly_size) MipsAtomComp_Proc_(ab, {
 	shift_lleft( R_T1, R_T1, S_(U4)/2),                        // T1 = otz * S_(U4) (otz arg is implicit R_T1)
 	add_u_self(  R_T1, r_ot_base),                             // T1 = & OrderingTable[OTZ]
 	load_word(   R_AT, R_T1,          O_(PolyTag,code)),       // AT = old_ot_head

code/duffle/gp.h

@@ -21,7 +21,7 @@
  *    4. Semantic encoders      gp0_word_poly_f3(r,g,b)
  *    3. Composite encoders     enc_color_word(cmd, r, g, b)
  *    2. Per-field encoders     enc_gp0_color_r(r), enc_gp0_color_g(g), ...
- *    1. Bitfield layout consts gp0_color_red_shift = 0, gp0_color_red_mask = 0xFF
+ *    1. Bitfield layout consts gp0_color_red_shift = 0, gp0_color_red_width = 8
  *    0. Opcode IDs             gp0_cmd_poly_f3 = 0x20
  *
  *  Vendor mnemonics (gte_mtc2, gte_mfc2, etc.) are NOT in this header.
@@ -68,13 +68,14 @@ enum {
 
 #define gp0_send(word) (HW_GP0[0] = (word))
 #define gp1_send(word) (HW_GP1[0] = (word))
+#define DmaSlot_ // Annotate an instruction as filling a CPU <-> Command DMA delay slot/s
 
 /* ============================================================================
  *  GP0 command byte constants + Layer 1 (GPU bitfield shifts)
  *  ============================================================================
  *  8-bit GP0 opcodes (the upper byte of a primitive's first word). These are the BYTE only.
  *  NO macro body past this point uses a raw shift or raw mask.
- *  Mirrors the OPCODE_SHIFT / RS_SHIFT / REG_MASK convention from mips.h.
+ *  Mirrors the OPCODE_SHIFT / RS_SHIFT convention from mips.h.
  * ============================================================================ */
 enum {
 	gp0_cmd_Nop             = 0x00,
@@ -116,21 +117,20 @@ enum {
 	gp0_cmd_SetDrawOffset        = 0xE5,
 	gp0_cmd_SetMaskBit           = 0xE6,
 
-	/* bitfield shifts / widths / masks ----
+	/* bitfield shifts / widths ----
 		* Generic GP0/GP1 command byte (upper 8 bits of every word sent to either port). */
 	gp0_cmd_shift = 24,
 	gp0_cmd_width =  8,
-	gp0_cmd_mask  = 0xFF,
 
 	/* Color word layout (lives in Poly_F3.color, Poly_G4.c0..c3, etc.):
 		*   bits 31..24 = command byte
 		*   bits 23..16 = BLUE
 		*   bits 15..08 = GREEN
 		*   bits 07..00 = RED     (PSX GPU is BGR, NOT RGB) */
-	gp0_color_cmd_shift   = 24, gp0_color_cmd_width   = 8, gp0_color_cmd_mask   = 0xFF,
+	gp0_color_cmd_shift   = 24, gp0_color_cmd_width   = 8,
-	gp0_color_blue_shift  = 16, gp0_color_blue_width  = 8, gp0_color_blue_mask  = 0xFF,
+	gp0_color_blue_shift  = 16, gp0_color_blue_width  = 8,
-	gp0_color_green_shift =  8, gp0_color_green_width = 8, gp0_color_green_mask = 0xFF,
+	gp0_color_green_shift =  8, gp0_color_green_width = 8,
-	gp0_color_red_shift   =  0, gp0_color_red_width   = 8, gp0_color_red_mask   = 0xFF,
+	gp0_color_red_shift   =  0, gp0_color_red_width   = 8,
 };
 
 /* ============================================================================
@@ -143,12 +143,12 @@ enum {
  * ============================================================================ */
 
 /* ---- Layer 1.5: per-field encoders ---- */
-#define enc_gp0_cmd(cmd)       (((cmd) & gp0_cmd_mask)         << gp0_cmd_shift)
+#define enc_gp0_cmd(cmd)       ((cmd) << gp0_cmd_shift)
 
-#define enc_gp0_color_cmd(cmd) (((cmd) & gp0_color_cmd_mask)   << gp0_color_cmd_shift)
+#define enc_gp0_color_cmd(cmd) ((cmd) << gp0_color_cmd_shift)
-#define enc_gp0_color_r(r)     (((r)   & gp0_color_red_mask)   << gp0_color_red_shift)
+#define enc_gp0_color_r(r)     ((r)   << gp0_color_red_shift)
-#define enc_gp0_color_g(g)     (((g)   & gp0_color_green_mask) << gp0_color_green_shift)
+#define enc_gp0_color_g(g)     ((g)   << gp0_color_green_shift)
-#define enc_gp0_color_b(b)     (((b)   & gp0_color_blue_mask)  << gp0_color_blue_shift)
+#define enc_gp0_color_b(b)     ((b)   << gp0_color_blue_shift)
 
 /* ---- Layer 2: composite encoders ---- */
 #define enc_color_word(cmd, r, g, b) (enc_gp0_color_cmd(cmd) | enc_gp0_color_r(r) | enc_gp0_color_g(g) | enc_gp0_color_b(b))
@@ -211,38 +211,38 @@ enum {
 	gp1_disp_Color24    = 0x1,
 	gp1_disp_VInterlace = 0x1,
 
-	/* ---- Layer 1: GP1 display-mode + range + draw-area shifts/masks ---- */
+	/* ---- Layer 1: GP1 display-mode + range + draw-area shifts/widths ---- */
-	gp1_disp_hres_shift      =  0, gp1_disp_hres_width      = 2, gp1_disp_hres_mask      = 0x3,
+	gp1_disp_hres_shift      =  0, gp1_disp_hres_width      = 2,
-	gp1_disp_vres_shift      =  2, gp1_disp_vres_width      = 1, gp1_disp_vres_mask      = 0x1,
+	gp1_disp_vres_shift      =  2, gp1_disp_vres_width      = 1,
-	gp1_disp_color_shift     =  4, gp1_disp_color_width     = 1, gp1_disp_color_mask     = 0x1,
+	gp1_disp_color_shift     =  4, gp1_disp_color_width     = 1,
-	gp1_disp_interlace_shift =  5, gp1_disp_interlace_width = 1, gp1_disp_interlace_mask = 0x1,
+	gp1_disp_interlace_shift =  5, gp1_disp_interlace_width = 1,
 
 	/* GP1 horizontal display range: bits 0..11 = X2, bits 12..23 = X1 */
-	gp1_hrange_x1_shift = 12, gp1_hrange_x1_width = 12, gp1_hrange_x1_mask = 0xFFF,
+	gp1_hrange_x1_shift = 12, gp1_hrange_x1_width = 12,
-	gp1_hrange_x2_shift =  0, gp1_hrange_x2_width = 12, gp1_hrange_x2_mask = 0xFFF,
+	gp1_hrange_x2_shift =  0, gp1_hrange_x2_width = 12,
 
 	/* GP1 vertical display range: bits 0..9 = Y2, bits 10..19 = Y1 */
-	gp1_vrange_y1_shift = 10, gp1_vrange_y1_width = 10, gp1_vrange_y1_mask = 0x3FF,
+	gp1_vrange_y1_shift = 10, gp1_vrange_y1_width = 10,
-	gp1_vrange_y2_shift =  0, gp1_vrange_y2_width = 10, gp1_vrange_y2_mask = 0x3FF,
+	gp1_vrange_y2_shift =  0, gp1_vrange_y2_width = 10,
 
 	/* GP1 draw area (top-left or bottom-right): bits 0..9 = X, bits 10..19 = Y
-		* (10-bit signed — caller pre-signs and masks with the named mask) */
+		* (10-bit signed — caller pre-signs) */
-	gp1_draw_x_shift =  0, gp1_draw_x_width = 10, gp1_draw_x_mask = 0x3FF,
+	gp1_draw_x_shift =  0, gp1_draw_x_width = 10,
-	gp1_draw_y_shift = 10, gp1_draw_y_width = 10, gp1_draw_y_mask = 0x3FF,
+	gp1_draw_y_shift = 10, gp1_draw_y_width = 10,
 };
 
 /* ---- Layer 1.5: GP1 per-field encoders ---- */
-#define enc_gp1_disp_hres(h)      (((h) & gp1_disp_hres_mask)      << gp1_disp_hres_shift)
+#define enc_gp1_disp_hres(h)      ((h) << gp1_disp_hres_shift)
-#define enc_gp1_disp_vres(v)      (((v) & gp1_disp_vres_mask)      << gp1_disp_vres_shift)
+#define enc_gp1_disp_vres(v)      ((v) << gp1_disp_vres_shift)
-#define enc_gp1_disp_color(c)     (((c) & gp1_disp_color_mask)     << gp1_disp_color_shift)
+#define enc_gp1_disp_color(c)     ((c) << gp1_disp_color_shift)
-#define enc_gp1_disp_interlace(i) (((i) & gp1_disp_interlace_mask) << gp1_disp_interlace_shift)
+#define enc_gp1_disp_interlace(i) ((i) << gp1_disp_interlace_shift)
 
-#define enc_gp1_hrange_x1(x1) (((x1) & gp1_hrange_x1_mask) << gp1_hrange_x1_shift)
+#define enc_gp1_hrange_x1(x1) ((x1) << gp1_hrange_x1_shift)
-#define enc_gp1_hrange_x2(x2) (((x2) & gp1_hrange_x2_mask) << gp1_hrange_x2_shift)
+#define enc_gp1_hrange_x2(x2) ((x2) << gp1_hrange_x2_shift)
-#define enc_gp1_vrange_y1(y1) (((y1) & gp1_vrange_y1_mask) << gp1_vrange_y1_shift)
+#define enc_gp1_vrange_y1(y1) ((y1) << gp1_vrange_y1_shift)
-#define enc_gp1_vrange_y2(y2) (((y2) & gp1_vrange_y2_mask) << gp1_vrange_y2_shift)
+#define enc_gp1_vrange_y2(y2) ((y2) << gp1_vrange_y2_shift)
-#define enc_gp1_draw_x(x)     (((x)  & gp1_draw_x_mask)    << gp1_draw_x_shift)
+#define enc_gp1_draw_x(x)     ((x)  << gp1_draw_x_shift)
-#define enc_gp1_draw_y(y)     (((y)  & gp1_draw_y_mask)    << gp1_draw_y_shift)
+#define enc_gp1_draw_y(y)     ((y)  << gp1_draw_y_shift)
 
 /* ---- Layer 2: GP1 composite encoders ---- */
 #define enc_gp1_disp_mode_word(h, v, c, i) (enc_gp0_cmd(gp1_cmd_DisplayMode)            | enc_gp1_disp_hres(h)  | enc_gp1_disp_vres(v) | enc_gp1_disp_color(c) | enc_gp1_disp_interlace(i))
@@ -419,14 +419,11 @@ typedef Struct_(PolyTag) {
 	};
 };
 
-/* DSL cast convention: every cast uses `C_()`, every pointer qualifier is `R_` (restrict) or `V_` (volatile).
- * No raw C-style casts. RHS values are assumed to be `U4` — caller passes a `U4` directly. */
 #define set_len(tag,v)  (C_(PolyTag_R,tag)->len  = u4_(v))
 #define set_addr(tag,v) (C_(PolyTag_R,tag)->addr = u4_(v))
-/* `set_code` is no longer in the new PolyTag design — the code byte lives in the primitive body
+/* `set_code` is no longer in the new PolyTag design
  * (e.g. `((Poly_F3*)(p))->code`), not in the tag.
- *  Use the typed primitive structs (Poly_F3, Poly_G4, etc.) and the `set_poly_*` setters,
+ *  Use the typed primitive structs (Poly_F3, Poly_G4, etc.) and the `set_poly_*` setters, which set both the tag's length and the code. */
- *  which set both the tag's length and the code. */
 #define get_len(tag)  C_(U4,C_(PolyTag_R,tag)->len)
 #define get_addr(tag) C_(U4,C_(PolyTag_R,tag)->addr)
 
@@ -555,14 +552,14 @@ typedef Struct_(Poly_GT4) {
  *    bits 12..31  = reserved (zero)
  * ============================================================================ */
 enum {
-	/* ---- Layer 1: TPage bitfield shifts / widths / masks ---- */
+	/* ---- Layer 1: TPage bitfield shifts / widths ---- */
-	gp0_tpage_x_shift            =  0, gp0_tpage_x_width            =  4, gp0_tpage_x_mask            = 0xF,
+	gp0_tpage_x_shift            =  0, gp0_tpage_x_width            =  4,
-	gp0_tpage_y_shift            =  4, gp0_tpage_y_width            =  1, gp0_tpage_y_mask            = 0x1,
+	gp0_tpage_y_shift            =  4, gp0_tpage_y_width            =  1,
-	gp0_tpage_semi_trans_shift   =  5, gp0_tpage_semi_trans_width   =  2, gp0_tpage_semi_trans_mask   = 0x3,
+	gp0_tpage_semi_trans_shift   =  5, gp0_tpage_semi_trans_width   =  2,
-	gp0_tpage_color_depth_shift  =  7, gp0_tpage_color_depth_width  =  2, gp0_tpage_color_depth_mask  = 0x3,
+	gp0_tpage_color_depth_shift  =  7, gp0_tpage_color_depth_width  =  2,
-	gp0_tpage_dither_shift       =  9, gp0_tpage_dither_width       =  1, gp0_tpage_dither_mask       = 0x1,
+	gp0_tpage_dither_shift       =  9, gp0_tpage_dither_width       =  1,
-	gp0_tpage_draw_to_disp_shift = 10, gp0_tpage_draw_to_disp_width =  1, gp0_tpage_draw_to_disp_mask = 0x1,
+	gp0_tpage_draw_to_disp_shift = 10, gp0_tpage_draw_to_disp_width =  1,
-	gp0_tpage_tex_disable_shift  = 11, gp0_tpage_tex_disable_width  =  1, gp0_tpage_tex_disable_mask  = 0x1,
+	gp0_tpage_tex_disable_shift  = 11, gp0_tpage_tex_disable_width  =  1,
 
 	/* TPage color-depth payload values (NOT bit positions — these go in
 	 * the 2-bit field at gp0_tpage_color_depth_shift). */
@@ -573,7 +570,7 @@ enum {
 	/* Default TPage value libpsyx's SetDefDrawEnv writes (matches the `li v1, 10; sh v1, 20(v0)` sequence at C11_only.elf:0x8001273C). */
 	gp0_tpage_default    = 10,
 
-	/* TPage semi-transparency mode payload values (NOT bit positions). */
+	/* TPage semi-transparency mode payload values. */
 	gp0_tpage_semi_trans_none  = 0x0,
 	gp0_tpage_semi_trans_alpha = 0x1,
 	gp0_tpage_semi_trans_add   = 0x2,
@@ -581,13 +578,13 @@ enum {
 };
 
 /* ---- Layer 1.5: TPage per-field encoders. Mirrors enc_gte_sf/mx/v in gte.h. ---- */
-#define enc_gp0_tpage_x(x)            (((x) & gp0_tpage_x_mask)            << gp0_tpage_x_shift)
+#define enc_gp0_tpage_x(x)            ((x) << gp0_tpage_x_shift)
-#define enc_gp0_tpage_y(y)            (((y) & gp0_tpage_y_mask)            << gp0_tpage_y_shift)
+#define enc_gp0_tpage_y(y)            ((y) << gp0_tpage_y_shift)
-#define enc_gp0_tpage_semi_trans(s)   (((s) & gp0_tpage_semi_trans_mask)   << gp0_tpage_semi_trans_shift)
+#define enc_gp0_tpage_semi_trans(s)   ((s) << gp0_tpage_semi_trans_shift)
-#define enc_gp0_tpage_color_depth(c)  (((c) & gp0_tpage_color_depth_mask)  << gp0_tpage_color_depth_shift)
+#define enc_gp0_tpage_color_depth(c)  ((c) << gp0_tpage_color_depth_shift)
-#define enc_gp0_tpage_dither(d)       (((d) & gp0_tpage_dither_mask)       << gp0_tpage_dither_shift)
+#define enc_gp0_tpage_dither(d)       ((d) << gp0_tpage_dither_shift)
-#define enc_gp0_tpage_draw_to_disp(d) (((d) & gp0_tpage_draw_to_disp_mask) << gp0_tpage_draw_to_disp_shift)
+#define enc_gp0_tpage_draw_to_disp(d) ((d) << gp0_tpage_draw_to_disp_shift)
-#define enc_gp0_tpage_tex_disable(t)  (((t) & gp0_tpage_tex_disable_mask)  << gp0_tpage_tex_disable_shift)
+#define enc_gp0_tpage_tex_disable(t)  ((t) << gp0_tpage_tex_disable_shift)
 
 /* ---- Layer 2: TPage composite encoder. Mirrors enc_gte_cmdw in gte.h ---- */
 #define enc_gp0_tpage_word(x, y, semi_trans, color_depth, dither, draw_to_disp, tex_disable) \
@@ -617,17 +614,17 @@ typedef Struct_(TexturePage) { U4 raw; };
  *    bits 24..31  = command byte — 0x20 (4bpp load) or 0x25 (8bpp load)
  * ============================================================================ */
 enum {
-	/* ---- Layer 1: CLUT bitfield shifts / widths / masks ---- */
+	/* ---- Layer 1: CLUT bitfield shifts / widths ---- */
-	gp0_clut_y_shift = 0, gp0_clut_y_width = 6, gp0_clut_y_mask = 0x3F,
+	gp0_clut_y_shift = 0, gp0_clut_y_width = 6,
-	gp0_clut_x_shift = 6, gp0_clut_x_width = 9, gp0_clut_x_mask = 0x1FF,
+	gp0_clut_x_shift = 6, gp0_clut_x_width = 9,
 	/* CLUT-load cmd-byte variants — the upper byte of the GP0 word. */
 	gp0_clut_cmd_Load4bpp = 0x20,
 	gp0_clut_cmd_Load8bpp = 0x25,
 };
 
 /* ---- Layer 1.5: CLUT per-field encoders ---- */
-#define enc_gp0_clut_x(x) (((x) & gp0_clut_x_mask) << gp0_clut_x_shift)
+#define enc_gp0_clut_x(x) ((x) << gp0_clut_x_shift)
-#define enc_gp0_clut_y(y) (((y) & gp0_clut_y_mask) << gp0_clut_y_shift)
+#define enc_gp0_clut_y(y) ((y) << gp0_clut_y_shift)
 
 /* ---- Layer 2: CLUT composite encoder ---- */
 #define enc_gp0_clut_word(cmd, x, y) (enc_gp0_cmd(cmd) | enc_gp0_clut_x(x) | enc_gp0_clut_y(y))

code/duffle/gte.atom.c

@@ -11,7 +11,8 @@ ATOM_FILE_DEBUGGER_LINE_MARKER(gte_atom_c);
 #pragma region MACs (Mips Atom Components)
 
 /* Words: 3; Loads 3 S2 indices from the face array */
-FI_ Slice_MipsCode ac_load_tri_indices(AtomBuilder_R ab, U4 r_face_cusor, U4 r_i0, U4 r_i1, U4 r_i2) atom_dbg_skip MipsAtomComp_Proc_(ac_load_tri_indices, ab, {
+FI_ Slice_MipsCode ac_load_tri_indices(AtomBuilder_R ab, U4 r_face_cusor, U4 r_i0, U4 r_i1, U4 r_i2)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	load_half_u(r_i0, r_face_cusor, 0 * S_(S2)),
 	load_half_u(r_i1, r_face_cusor, 1 * S_(S2)),
 	load_half_u(r_i2, r_face_cusor, 2 * S_(S2)),
@@ -19,17 +20,17 @@ FI_ Slice_MipsCode ac_load_tri_indices(AtomBuilder_R ab, U4 r_face_cusor, U4 r_i
 
 /* Words: 3; Stores the 3 transformed (V2_S2 screen) vertices to the F3.
  * PIPELINE: post-RTPT (SXY0=v0.screen, SXY1=v1.screen, SXY2=v2.screen). */
-FI_ Slice_MipsCode ac_gte_store_f3(AtomBuilder_R ab, U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_store_f3, ab, {
+FI_ Slice_MipsCode ac_gte_store_f3(AtomBuilder_R ab, U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	gte_sw(C2_SXY0, r_primitive_cursor, O_(Poly_F3,p0)),
 	gte_sw(C2_SXY1, r_primitive_cursor, O_(Poly_F3,p1)),
 	gte_sw(C2_SXY2, r_primitive_cursor, O_(Poly_F3,p2)),
 })
 
 /* Words: 18; Translates indices to vertex addresses and pushes them to GTE  */
-I_ Slice_MipsCode ac_gte_load_tri_verts(AtomBuilder_R ab, U4 r_vert_base, U4 r_v0, U4 r_v1, U4 r_v2) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_load_tri_verts, ab, {
+I_ Slice_MipsCode ac_gte_load_tri_verts(AtomBuilder_R ab, U4 r_vert_base, U4 r_v0, U4 r_v1, U4 r_v2) atom_dbg_skip MipsAtomComp_Proc_(ab, {
-	shift_lleft(R_AT, r_v0, v3s2_byteoff), add_u_self(R_AT, r_vert_base), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), gte_mv_to_data_r(R_V0, C2_VXY0), gte_mv_to_data_r(R_V1, C2_VZ0),
+	shift_lleft(R_AT, r_v0, v3s2_byteoff), add_u_self(R_AT, r_vert_base), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY0), gte_mv_to_data_r(R_V1, C2_VZ0),
-	shift_lleft(R_AT, r_v1, v3s2_byteoff), add_u_self(R_AT, r_vert_base), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), gte_mv_to_data_r(R_V0, C2_VXY1), gte_mv_to_data_r(R_V1, C2_VZ1),
+	shift_lleft(R_AT, r_v1, v3s2_byteoff), add_u_self(R_AT, r_vert_base), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY1), gte_mv_to_data_r(R_V1, C2_VZ1),
-	shift_lleft(R_AT, r_v2, v3s2_byteoff), add_u_self(R_AT, r_vert_base), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), gte_mv_to_data_r(R_V0, C2_VXY2), gte_mv_to_data_r(R_V1, C2_VZ2),
+	shift_lleft(R_AT, r_v2, v3s2_byteoff), add_u_self(R_AT, r_vert_base), load_word(R_V0, R_AT, O_(V3_S2,x)), load_word(R_V1, R_AT, O_(V3_S2,z)), LdSlot_ gte_mv_to_data_r(R_V0, C2_VXY2), gte_mv_to_data_r(R_V1, C2_VZ2),
 })
 
 /* Words: 3; Stores the 3 transformed (V2_S2 screen) vertices of the
@@ -37,7 +38,7 @@ I_ Slice_MipsCode ac_gte_load_tri_verts(AtomBuilder_R ab, U4 r_vert_base, U4 r_v
  * PIPELINE: post-RTPT, pre-RTPS (SXY0=v0.screen, SXY1=v1.screen, SXY2=v2.screen).
  * MUST be called BEFORE V3-RTPS, otherwise SXY0/1/2 get overwritten with v3
  * (RTPS writes only to SXY2, but to keep the three registers aligned with v0/v1/v2 you must store before RTPS). */
-FI_ Slice_MipsCode ac_gte_store_g4_p012(AtomBuilder_R ab, U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_store_g4_p012, ab, {
+FI_ Slice_MipsCode ac_gte_store_g4_p012(AtomBuilder_R ab, Reg r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	gte_sw(C2_SXY0, r_primitive_cursor, O_(Poly_G4,p0)),
 	gte_sw(C2_SXY1, r_primitive_cursor, O_(Poly_G4,p1)),
 	gte_sw(C2_SXY2, r_primitive_cursor, O_(Poly_G4,p2)),
@@ -47,28 +48,41 @@ FI_ Slice_MipsCode ac_gte_store_g4_p012(AtomBuilder_R ab, U4 r_primitive_cursor)
  * PIPELINE: post-RTPS (SXY2 holds v3.screen because RTPS writes its single-vertex result to SXY2;
  * SXY0 still holds v0.screen from the earlier RTPT.
  */
-FI_ Slice_MipsCode ac_gte_store_g4_p3(AtomBuilder_R ab, U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_store_g4_p3, ab, { gte_sw(C2_SXY2, r_primitive_cursor, O_(Poly_G4,p3)) })
+FI_ Slice_MipsCode ac_gte_store_g4_p3(AtomBuilder_R ab, U4 r_primitive_cursor) atom_dbg_skip MipsAtomComp_Proc_(ab, { gte_sw(C2_SXY2, r_primitive_cursor, O_(Poly_G4,p3)) })
 
 /* ─── STAGE 1 of normalize: SQR + mfc2 MAC1/2/3 ───
  * Emits squared magnitude per component (in MAC1/2/3) into caller-provided scratch regs.
  * Stage 2 of normalize consumes these directly.
  * Words: 8.  Clobbers: IR1/2/3, MAC1/2/3.  Uses gte_cmdw_sqr (sf=0, lm=1). */
-FI_ Slice_MipsCode ac_gte_sqr_v3(AtomBuilder_R ab, U4 r_sx, U4 r_sy, U4 r_sz, U4 r_sq_x, U4 r_sq_y, U4 r_sq_z) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_sqr_v3, ab, {
+FI_ Slice_MipsCode ac_gte_sqr_v3(AtomBuilder_R ab, U4 r_sx, U4 r_sy, U4 r_sz, U4 r_sq_x, U4 r_sq_y, U4 r_sq_z) atom_dbg_skip MipsAtomComp_Proc_(ab, {
-	gte_mv_to_data_r(r_sx, C2_IR1),
+	mac_gte_sqr_v3s4(r_sx, r_sy, r_sz, nop),
-	gte_mv_to_data_r(r_sy, C2_IR2),
-	gte_mv_to_data_r(r_sz, C2_IR3),
-	nop, gte_cmdw_sqr,
 	gte_mv_from_data_r(r_sq_x, C2_MAC1),
 	gte_mv_from_data_r(r_sq_y, C2_MAC2),
 	gte_mv_from_data_r(r_sq_z, C2_MAC3),
 })
 
+/* ─── SQR FIRE — mtc2 3 GPRs into IR1/IR2/IR3, then fire SQR. ───
+ * The SQR command always squares IR1/IR2/IR3 — those C2 registers are fixed.
+ * The GPRs holding the source vector are caller-determined.
+ * Words: 5 (3 mtc2 + 1 nop hazard + 1 cmd). */
+FI_ Slice_MipsCode ac_gte_sqr_v3s4(AtomBuilder_R ab, Reg r_sx, Reg r_sy, Reg r_sz, MipsCode delay_slot)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	gte_mv_to_data_r(r_sx, C2_IR1),
+	gte_mv_to_data_r(r_sy, C2_IR2),
+	gte_mv_to_data_r(r_sz, C2_IR3),
+	delay_slot, gte_cmdw_sqr,
+})
+
 /* ─── STAGE 4 of normalize: mtc2 IR0..3 + GPF + mfc2 MAC + srav finalize ───
  * Reusable standalone — given an IR0 = 1/|v| estimate (typically from a sqrtbl lookup) and a shift count 
  * (typically (31 - LZCR)/2), multiplies IR0*IR[i] via GPF and shifts right to produce the normalized output.
  * Used standalone for "scale vector by scalar".
  * Words: 11.  Clobbers: IR0..3, MAC1..3.  Uses gte_cmdw_gpf (sf=0, lm=0). */
-FI_ Slice_MipsCode ac_gte_gpf_scale(AtomBuilder_R ab, U4 r_sx, U4 r_sy, U4 r_sz, U4 r_recip_est, U4 r_shift, U4 r_dx, U4 r_dy, U4 r_dz) atom_dbg_skip MipsAtomComp_Proc_(ac_gte_gpf_scale, ab, {
+FI_ Slice_MipsCode ac_gte_gpf_scale(AtomBuilder_R ab, 
+	U4 r_sx, U4 r_sy, U4 r_sz, 
+	U4 r_recip_est, U4 r_shift, 
+	U4 r_dx, U4 r_dy, U4 r_dz)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
 	gte_mv_to_data_r(r_recip_est, C2_IR0),
 	gte_mv_to_data_r(r_sx,        C2_IR1),
 	gte_mv_to_data_r(r_sy,        C2_IR2),
@@ -83,84 +97,73 @@ FI_ Slice_MipsCode ac_gte_gpf_scale(AtomBuilder_R ab, U4 r_sx, U4 r_sy, U4 r_sz,
 	shift_aright_var(r_dz, r_dz, r_shift),
 })
 
-/* ─── APPLY MATRIX LV (libgte ApplyMatrixLV port) ───
- * Atom component — auto-generates mac_apply_matrix_lv Mac composer macro.
- * Uses GTE RTPS (cv=1, sf=1, v=0) with lwc2-loaded V0/VZ0 inputs.
- * Per PSX-SPX `geometrytransformationenginegte.md` lines 416-418:
- *   IR1 = MAC1 = (TRX*1000h + RT11*VX0 + RT12*VY0 + RT13*VZ0) SAR (sf*12)
- *   IR2 = MAC2 = (TRY*1000h + RT21*VX0 + RT22*VY0 + RT23*VZ0) SAR (sf*12)
- *   IR3 = MAC3 = (TRZ*1000h + RT31*VX0 + RT32*VY0 + RT33*VZ0) SAR (sf*12)
- * RTPS uses the FULL row of the rotation matrix (not just diagonal like MVMVA with mx=0).
- * libgte's `gte_ApplyMatrix` calls `gte_rtv0()` = RTPS cv=1 v=0 mx=0.
- * Per `gte.h` line 405 the body sets cv=3 (BK, zero-initialized) so no TR contribution.
- *
- * Operands:
- *   r_mtx  : MT3_S2S4* (matrix pointer)
- *   r_vec  : U4 (pointer to PACKED V0 data — (pos.y << 16) | pos.x at +0, pos.z at +4)
- *   r_out  : V3_S4* (output pointer; MAC1/2/3 stored here)
- *   r_t0/1/2 : 3 GPR codes for matrix load + intermediate state
- * Words: ~26.  Clobbers: r_t0, r_t1, r_t2 (C2 $0..$4, VXY0/VZ0, MAC1/2/3, SXY0/1/2). */
-FI_ Slice_MipsCode ac_apply_matrix_lv(AtomBuilder_R ab
-	,	U4 r_mtx, U4 r_vec, U4 r_out
-	,	U4 r_t0,  U4 r_t1,  U4 r_t2
-) MipsAtomComp_Proc_(ac_apply_matrix_lv, ab, {
-	/* Load MATRIX rows into GTE RT11..RT33 (libgte convention: ctc2 to C2 $0..$4 in order).
-	 * load_half_u zero-extends the last word so RT33 = m[2][2] and TRX = 0. */
-	load_word(r_t0, r_mtx,  0), nop,
-	gte_mv_to_ctrl_r(r_t0, gte_cr_RT11_Code),
-	load_word(r_t0, r_mtx,  4), nop,
-	gte_mv_to_ctrl_r(r_t0, gte_cr_RT12_Code),
-	load_word(r_t0, r_mtx,  8), nop,
-	gte_mv_to_ctrl_r(r_t0, gte_cr_RT13_Code),
-	load_word(r_t0, r_mtx, 12), nop,
-	gte_mv_to_ctrl_r(r_t0, gte_cr_RT21_Code),
-	load_half_u(r_t0, r_mtx, 16), nop,
-	gte_mv_to_ctrl_r(r_t0, gte_cr_RT22_Code),
-	nop2,
-
-	/* Load PACKED pos into V0 (libgte SVECTOR layout).
-	 * r_vec points to atom-0-staged packed data ((pos.y << 16) | pos.x at +0, pos.z at +4).
-	 * LWC2 base register MUST be the pointer r_vec, NOT the loaded value r_t0. */
-	load_word(r_t0, r_vec, 0), nop,
-	gte_lw(C2_VXY0, r_vec, 0),
-	load_word(r_t0, r_vec, 4), nop,
-	gte_lw(C2_VZ0, r_vec, 4),
-
-	/* RTPS: cv=3 (no translation), sf=1 (no shift, integer), v=0 (V0 input),
-	 * mx=0 (rotation matrix). MAC = RT row · V0 + 0. RTPS also writes
-	 * SXY0/1/2 + SZ0..SZ3 (perspective division); ignored. */
-	gte_cmdw_rtps_sf1,
-
-	/* Read MAC1/2/3 → out. */
-	gte_mv_from_data_r(r_t0, C2_MAC1),
-	gte_mv_from_data_r(r_t1, C2_MAC2),
-	gte_mv_from_data_r(r_t2, C2_MAC3),
-	nop,
-	store_word(r_t0, r_out, 0),
-	store_word(r_t1, r_out, 4),
-	store_word(r_t2, r_out, 8),
-})
-
 /* ─── TRANS MATRIX (libgte TransMatrix port) ───
  * Atom component — auto-generates mac_trans_matrix Mac composer macro.
  * m->t = v (struct copy; libgte's TransMatrix at 0x8001a540 is just 3 store_words, no GTE, no add).
  * Uses 1 GPR (r_t1 = off value) per axis; per-axis load-delay-slot pattern.
  * Words: 9.  Clobbers: r_t1. */
-FI_ Slice_MipsCode ac_trans_matrix(AtomBuilder_R ab
+FI_ Slice_MipsCode ac_trans_mt3s3s4(AtomBuilder_R ab
 	,	U4 r_mtx, U4 r_off
-	,	U4 r_t1
+	,	U4 r_t0, U4 r_t1, U4 r_t2
-) MipsAtomComp_Proc_(ac_trans_matrix, ab, {
+) MipsAtomComp_Proc_(ab, {
-	load_word(r_t1, r_off, O_(V3_S4,x)),
+	load_word(r_t0, r_off, O_(V3_S4,x)),
-	nop,
-	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[0])),
-
 	load_word(r_t1, r_off, O_(V3_S4,y)),
-	nop,
+	load_word(r_t2, r_off, O_(V3_S4,z)),
+	store_word(r_t0, r_mtx, O_(MT3_S2S4,t[0])),
 	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[1])),
+	store_word(r_t2, r_mtx, O_(MT3_S2S4,t[2])),
+})
 
-	load_word(r_t1, r_off, O_(V3_S4,z)),
+/* ─── LZCR ROUND EVEN + HALF-SHIFT ───
-	nop,
+ * Takes the raw LZCR leading-zero/ones count (from mfc2 C2_LZCR, range 1..32
-	store_word(r_t1, r_mtx, O_(MT3_S2S4,t[2])),
+ * per PSX-SPX cop2r31) and the |v|² sum (in r_mag_sq from the MAC1+MAC2+MAC3
+ * add). Produces:
+ *   r_shift        ← LZCR rounded down to even (clear bit 0)
+ *   r_mag_sq_copy  ← |v|² sum (moved out of r_mag_sq before it's overwritten)
+ *   r_mag_sq       ← (31 - even_LZCR) / 2 = the final srav/GPF shift amount
+ *
+ * Rounding to even ensures (31 - LZCR) is always odd, so the >> 1 division
+ * is consistent — no 0.5 loss. The caller branches on LZCR < 24 to decide
+ * left-shift vs right-shift of r_mag_sq_copy, then saves the shift count.
+ *
+ * Note: C2_LZCR (cop2r31) is a fixed read-only C2 data register — the caller
+ * must read it via mfc2 from C2_LZCR; there is no register choice at the
+ * hardware level. Only the GPR that holds the result is caller-determined. */
+FI_ Slice_MipsCode ac_lzcr_round_even_half_shift(AtomBuilder_R ab,
+	U4 r_shift,
+	U4 r_mag_sq,
+	U4 r_mag_sq_copy)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	and_i(r_shift, r_shift, gte_lzcr_even_mask),
+	or_u(r_mag_sq_copy, r_mag_sq, 0),
+	li_s(r_mag_sq, 31),
+	sub_s(r_mag_sq, r_mag_sq, r_shift),
+	shift_aright(r_mag_sq, r_mag_sq, 1),
+})
+
+FI_ Slice_MipsCode ac_gte_general_purpose_interopolation(AtomBuilder_R ab
+	, Reg to_ir0,  Reg to_ir1,  Reg to_ir2, Reg to_ir3
+	, Reg fr_mac1, Reg fr_mac2, Reg fr_mac3
+	, MipsCode nop_slot1, MipsCode nop_slot2)
+MipsAtomComp_Proc_(ab, {
+	gte_mv_to_data_r(to_ir0, C2_IR0),
+	gte_mv_to_data_r(to_ir1, C2_IR1), /* IR1 = src.x (preserved in r_tmp — r_mac2_scratch was clobbered to MAC2 in stage 1.5) */
+	gte_mv_to_data_r(to_ir2, C2_IR2),
+	gte_mv_to_data_r(to_ir3, C2_IR3), /* IR3 = src.z (reloaded) */
+	GteDelay_ nop_slot1,
+	GteDelay_ nop_slot2,
+	gte_cmdw_gpf,
+	gte_mv_from_data_r(fr_mac1, C2_MAC1),
+	gte_mv_from_data_r(fr_mac2, C2_MAC2),
+	gte_mv_from_data_r(fr_mac3, C2_MAC3),
+})
+
+FI_ Slice_MipsCode ac_gte_mv_from_data_r_mac123(AtomBuilder_R ab
+	, Reg fr_mac1, Reg fr_mac2, Reg fr_mac3)
+MipsAtomComp_Proc_(ab, {
+	gte_mv_from_data_r(fr_mac1, C2_MAC1),
+	gte_mv_from_data_r(fr_mac2, C2_MAC2),
+	gte_mv_from_data_r(fr_mac3, C2_MAC3),
 })
 
 #pragma endregion MACs (Mips Atom Components)
@@ -206,7 +209,7 @@ FI_ Slice_MipsCode ac_trans_matrix(AtomBuilder_R ab
  * The later 64 entries (octaves 2-3) are the `srav` branch when the magnitude's top bit is well above bit 24.
  *
  * 192-entry table is reproduced verbatim from libgte (verified against libpsn00b/psxgte/vector.s:100-123 — 24 rows × 8 halfwords, last entry 0x0804). */
-internal RO_ S2  gte_normalize_sqr_tbl[192] align_(2) = {
+internal S2 const gte_normalize_sqr_tbl[192] align_(2) = {
 	0x1000, 0x0fe0, 0x0fc1, 0x0fa3, 0x0f85, 0x0f68, 0x0f4c, 0x0f30,
 	0x0f15, 0x0efb, 0x0ee1, 0x0ec7, 0x0eae, 0x0e96, 0x0e7e, 0x0e66,
 	0x0e4f, 0x0e38, 0x0e22, 0x0e0c, 0x0df7, 0x0de2, 0x0dcd, 0x0db9,
@@ -233,6 +236,22 @@ internal RO_ S2  gte_normalize_sqr_tbl[192] align_(2) = {
 	0x0820, 0x081c, 0x0818, 0x0814, 0x0810, 0x080c, 0x0808, 0x0804,
 };
 
+typedef Struct_(Binds_build_normalize_v3s4) {
+	U4 scratch;
+	U2 src_offset;
+	U2 dst_offset;
+};
+typedef Struct_(RegUse_build_normalize_v3s4) {
+	Reg scratch;
+	Reg src_ptr;
+	Reg dst_ptr;
+	Reg recip_est; // |v|² sum + shift-input + sqrtbl[index]
+	Reg norm; Reg shift;
+	Reg src_x;
+	union { Reg mac1_scratch; } t3;
+	union { Reg mac2_scratch; } t4;
+	union { Reg btarget, shift_count, lookup_addr, src_z; } t5;
+};
 /* ─── Full normalize (all 4 stages inline) ───
  * Generic 4-stage GTE normalize (SQR → sum+LZCR → align+sqrtbl → GPF+srav).
  *
@@ -249,9 +268,9 @@ internal RO_ S2  gte_normalize_sqr_tbl[192] align_(2) = {
  *   r_mac1_scratch       : MAC1 result scratch (also holds aligned |v|² in stage 3)
  *   r_mac2_scratch       : MAC2 result scratch → result.x after stage 4 sra
  *   r_recip_est          : src.y PRESERVED across stages 1-2 → fed to IR2 in stage 4 → result.y
- *   r_lzcr               : |v|² sum (stage 2) → shift count (stage 3) → 1/|v| (stage 4 IR0)
+ *   r_norm               : |v|² sum (stage 2) → half-shift (stage 3) → 1/|v| (stage 4 IR0)
  *   r_shift              : shift count SAVED in stage 3 → consumed by stage 4 srav
- *   r_branch_tmp         : src.z PRESERVED across stages 1-2 → fed to IR3 in stage 4 → result.z (also sqrtbl base addr)
+*   r_branch_tmp         : src.z PRESERVED across stages 1-2 → fed to IR3 in stage 4 → result.z (also sqrtbl base addr)
  *
  * Atom_labels are srav_path / aligned_done 
  * (NOT namespaced — they're internal to this proc; 
@@ -264,95 +283,66 @@ internal RO_ S2  gte_normalize_sqr_tbl[192] align_(2) = {
  * Sqrtbl: hardcoded to 0x800185B4 (libgte msc02.rel.data). Note: swapped to local.
  * Pipeline: clobbers IR0..3, MAC1..3, LZCS, LZCR.
  */
-/* MipsAtom_Proc_ wrapper: declares the static MipsCode[] body, then calls atombuilder_unroll(ab, ...) to copy the encoded instructions into the caller's MipsAtomBuilder arena.  */
+internal MipsAtom* build_normalize_v3s4(AtomArena_R aa,	U2 src_offset, U2 dst_offset, RegUse_build_normalize_v3s4 r)
-internal MipsAtom* normalize_v3s4_proc(AtomArena_R aa,	U4 r_scratch /* GPR code: scratch base carrier (e.g., R_T4 = R_ResolveScratch) */
+MipsAtom_Proc_(aa, {
-	,	U4 r_src_offset, U4 r_dst_offset     /* GPR codes: PARAMETERIZED offsets (caller passes O_ macros) */
+	// load_word(r.scratch, R_TapePtr, O_(Binds_build_normalize_v3s4,scratch)),
-	,	U4 r_src_ptr, U4 r_dst_ptr, U4 r_tmp /* GPR codes: 3 scratch regs (src/dst computed + tmp) */
+	// add_ui_self(R_TapePtr, S_(Binds_build_normalize_v3s4)),
-	,	U4 r_mac1_scratch, U4 r_mac2_scratch /* GPR codes: 2 more: MAC1/MAC2 scratch */
+
-	,	U4 r_recip_est                       /* GPR code: |v|² sum + shift-input + sqrtbl[index] */
+	add_si(r.src_ptr, r.scratch, src_offset), /* r_src_ptr = &src */
-	,	U4 r_lzcr, U4 r_shift                /* GPR codes: lzcr + final srav amount */
-	,	U4 r_branch_tmp                      /* GPR code: scratch (shift count, branch target, lookup addr) */
-)
-MipsAtom_Proc_(normalize_v3s4, aa, {
-	add_si(r_src_ptr, r_scratch, r_src_offset),     /* r_src_ptr = &src */
-	add_si(r_dst_ptr, r_scratch, r_dst_offset),     /* r_dst_ptr = &dst */
-	nop,
 
 	/* Load src.x/y/z from r_src_ptr (caller-determined address) into r_tmp/r_recip_est/r_branch_tmp.
-	 * r_tmp holds src.x throughout stages 1-2 — r_mac2_scratch is clobbered to MAC2 in stage 1.5 (line below). */
+	 * r.rt1_src_x holds src.x throughout stages 1-2 — r_mac2_scratch is clobbered to MAC2 in stage 1.5 (line below). */
-	load_word(r_tmp,          r_src_ptr, O_(V3_S4,x)),
+	mac_load_word_v3(r.src_x, r.recip_est, r.t5.src_z, r.src_ptr, 0),
-	load_word(r_recip_est,    r_src_ptr, O_(V3_S4,y)),
-	load_word(r_branch_tmp,   r_src_ptr, O_(V3_S4,z)),
-	nop, /* load-delay */
 
 	/* Stage 1: mtc2 src → IR1/2/3, SQR fires. */
-	gte_mv_to_data_r(r_tmp,        C2_IR1),
+	LdSlot_ mac_gte_sqr_v3s4(r.src_x, r.recip_est, r.t5.src_z, LdSlot_ nop),
-	gte_mv_to_data_r(r_recip_est,  C2_IR2),
-	gte_mv_to_data_r(r_branch_tmp, C2_IR3),
-	nop, gte_cmdw_sqr,
 
 	/* Stage 2: mfc2 MAC1/2/3, sum, mtc2 LZCS. */
-	gte_mv_from_data_r(r_mac1_scratch, C2_MAC1),
+	mac_gte_mv_from_data_r_mac123(r.t3.mac1_scratch, r.t4.mac2_scratch, r.norm), LdSlot_ nop,
-	gte_mv_from_data_r(r_mac2_scratch, C2_MAC2),
+	add_u_self(        r.norm, r.t3.mac1_scratch),
-	gte_mv_from_data_r(r_lzcr,         C2_MAC3),
+	add_u_self(        r.norm, r.t4.mac2_scratch),
-	nop,
+	gte_mv_to_data_r(  r.norm,  C2_LZCS), GteDelay_ nop2,
-	add_u(r_lzcr, r_lzcr, r_mac2_scratch),
+	gte_mv_from_data_r(r.shift, C2_LZCR), GteDelay_ nop,
-	add_u(r_lzcr, r_lzcr, r_mac1_scratch),
-	gte_mv_to_data_r(r_lzcr, C2_LZCS),
-	nop2,
-	gte_mv_from_data_r(r_shift, C2_LZCR),
-	nop,
 
-	/* Stage 3: compute srav amount (r_lzcr) + align |v|² to bit 24.
+	/* Stage 3: round LZCR to even, compute half-shift, align |v|² to bit 24.
-	 * IMPORTANT: the sllv/srav below writes the aligned |v|² to r_mac1_scratch (NOT r_lzcr),
+	 * r_norm holds |v|² sum; r_shift holds the LZCR count from mfc2.
-	 * so r_lzcr retains the shift count all the way to the start of stage 4.
+	 * After the component: r_shift = even(LZCR), r_norm = half-shift, r_mac1_scratch = |v|². */
-	 */
+	mac_lzcr_round_even_half_shift(r.shift, r.norm, r.t3.mac1_scratch),
-	and_i(   r_shift, r_shift, -2),
-	or_u(r_mac1_scratch, r_lzcr, 0),                            /* FIX B: save sum before clobbering r_lzcr with shift count */
-	li_s(    r_lzcr,           31),
-	sub_s(   r_lzcr, r_lzcr, r_shift),
-	shift_aright(r_lzcr, r_lzcr, 1),
 	/* r_branch_tmp = LZCR - 24 (overwrites r_branch_tmp; src.z no longer needed after SQR) */
-	add_si(  r_branch_tmp, r_shift, -24),
+	add_si(        r.t5.btarget, r.shift, -24),
-	branch_lt_zero(r_branch_tmp, atom_offset(aligned_done, srav_path)), nop,    /* FIX A: bltz → srav_path (LZCR<24 path) */
+	branch_lt_zero(r.t5.btarget, atom_offset(aligned_done, srav_path)), BdSlot_ nop, /* bltz → srav_path (LZCR <  24 path) */
-	jump_rel(atom_offset(srav_path, aligned_done)),                              /* FIX A: b → aligned_done (LZCR>=24 path) */
+		jump_rel(atom_offset(srav_path, aligned_done)),                                /* b → aligned_done (LZCR >= 24 path) */
-	shift_lleft_var(r_mac1_scratch, r_mac1_scratch, r_branch_tmp),              /* FIX B: src=sum (r_mac1_scratch), dst=same */
+		BdSlot_ shift_lleft_var(r.t3.mac1_scratch, r.t3.mac1_scratch, r.t5.btarget),   /* src=sum (r_mac1_scratch), dst=same */
-	atom_label(srav_path)
+		atom_label(srav_path)
-	li_s(    r_branch_tmp, 24),
+			li_s( r.t5.shift_count, 24),
-	sub_s(   r_branch_tmp, r_branch_tmp, r_shift),
+			sub_s(r.t5.shift_count, r.t5.shift_count, r.shift),
-	shift_aright_var(r_mac1_scratch, r_mac1_scratch, r_branch_tmp),             /* FIX B: src=sum (r_mac1_scratch), dst=same */
+			shift_aright_var(r.t3.mac1_scratch, r.t3.mac1_scratch, r.t5.shift_count), /* src=sum (r_mac1_scratch), dst=same */
 	atom_label(aligned_done)
-	/* Save the shift count to r_shift before the next 5 instructions overwrite r_lzcr
+		// Save the shift count to r_shift before the next 5 instructions overwrite r_norm (the sqrtbl lookup loads 1/|v| into r_norm, which becomes IR0 in stage 4).
-	 * (the sqrtbl lookup loads 1/|v| into r_lzcr, which becomes IR0 in stage 4). */
+		or_u(r.shift, r.norm, 0), /* r_shift ← shift count (preserved through stage 4) */
-	or_u(r_shift, r_lzcr, 0),                                    /* r_shift ← shift count (preserved through stage 4) */
+		/* r_mac1_scratch holds |v|² aligned (top bit at bit 7). */
-	/* r_mac1_scratch holds |v|² aligned (top bit at bit 7). */
+		add_si(     r.t3.mac1_scratch, r.t3.mac1_scratch, -64),
-	add_si(     r_mac1_scratch, r_mac1_scratch, -64),
+		shift_lleft(r.t3.mac1_scratch, r.t3.mac1_scratch, 1),
-	shift_lleft(r_mac1_scratch, r_mac1_scratch, 1),
+		mac_load_word_imm(r.t5.lookup_addr, & gte_normalize_sqr_tbl), add_u_self(r.t5.lookup_addr, r.t3.mac1_scratch),
-	load_upper_i(r_branch_tmp, u4_hi(& gte_normalize_sqr_tbl)),
+		load_half(r.norm, r.t5.lookup_addr, 0), /* r_norm = sqrtbl[aligned-64] = 1/|v| (IR0 in stage 4) */
-	or_i_self(   r_branch_tmp, u4_lo(& gte_normalize_sqr_tbl)),
-	add_u(r_branch_tmp, r_branch_tmp, r_mac1_scratch),
-	load_half(r_lzcr,   r_branch_tmp, 0), nop,                  /* r_lzcr = sqrtbl[aligned-64] = 1/|v| (IR0 in stage 4) */
 
-	/* FIX bug C: r_branch_tmp held the sqrtbl base+index, NOT src.z. Reload src.z from scratch now that r_branch_tmp is free. */
+	/* r_branch_tmp held the sqrtbl base+index, NOT src.z. Reload src.z from scratch now that r_branch_tmp is free. */
-	load_word(r_branch_tmp, r_src_ptr, O_(V3_S4,z)), nop,        /* r_branch_tmp = src.z (for IR3 in stage 4) */
+	LdSlot_ load_word(r.t5.src_z, r.src_ptr, O_(V3_S4,z)), /* r_branch_tmp = src.z (for IR3 in stage 4) */
-
-	/* Stage 4: GPF + srav finalize (r_shift = shift count, r_lzcr = 1/|v|). */
-	gte_mv_to_data_r(r_lzcr,         C2_IR0),
-	gte_mv_to_data_r(r_tmp,          C2_IR1),                    /* IR1 = src.x (preserved in r_tmp — r_mac2_scratch was clobbered to MAC2 in stage 1.5) */
-	gte_mv_to_data_r(r_recip_est,    C2_IR2),
-	gte_mv_to_data_r(r_branch_tmp,   C2_IR3),                    /* IR3 = src.z (reloaded) */
-	nop2, gte_cmdw_gpf,
-	gte_mv_from_data_r(r_mac2_scratch, C2_MAC1),
-	gte_mv_from_data_r(r_recip_est,    C2_MAC2),
-	gte_mv_from_data_r(r_branch_tmp,   C2_MAC3),
-	shift_aright_var(r_mac2_scratch, r_mac2_scratch, r_shift),   /* sra by r_shift = (31-LZCR)/2 (saved before sqrtbl lookup) */
-	shift_aright_var(r_recip_est,    r_recip_est,    r_shift),
-	shift_aright_var(r_branch_tmp,   r_branch_tmp,   r_shift),
 
+	/* Stage 4: GPF + srav finalize (r_shift = shift count, r_norm = 1/|v|). */
+	LdSlot_ mac_gte_general_purpose_interopolation(
+		r.norm, 
+		r.src_x,  /* IR1 = src.x (preserved in r_tmp — r_mac2_scratch was clobbered to MAC2 in stage 1.5) */
+		r.recip_est, 
+		r.t5.src_z,  /* IR3 = src.z (reloaded) */
+		r.t4.mac2_scratch, r.recip_est, r.t5.src_z,
+		GteDelay_ add_si(r.dst_ptr, r.scratch, dst_offset), // pre-laoding destination to register here.
+		GteDelay_ nop
+	),
+	/* sra by r_shift = (31-LZCR)/2 (saved before sqrtbl lookup) */
+	mac_shift_aright_var_v3_self(r.t4.mac2_scratch, r.recip_est, r.t5.src_z, r.shift),
 	/* Store result.x/y/z to r_dst_ptr (caller-determined dst address). */
-	store_word(r_mac2_scratch, r_dst_ptr, O_(V3_S4,x)),
+	mac_store_word_v3(r.t4.mac2_scratch, r.recip_est, r.t5.src_z, r.dst_ptr, 0),
-	store_word(r_recip_est,    r_dst_ptr, O_(V3_S4,y)),
-	store_word(r_branch_tmp,   r_dst_ptr, O_(V3_S4,z)),
 
 	mac_yield()
 })
@@ -372,7 +362,7 @@ internal MipsAtom_(set_gte_mt3s2s4) atom_info(
 	load_word(R_T3, R_TapePtr, O_(Binds_SetGteMT3S2S4,transform)),
 	add_ui_self(    R_TapePtr, S_(Binds_SetGteMT3S2S4)),
 	/* Load 3x3 Rotation + 3x1 Translation from R_T3 into GTE CONTROL Regs (ctc2) */
-	load_word(R_T0, R_T3, 0),  load_word(R_T1, R_T3,  4),
+	load_word(R_T0, R_T3, 0),  load_word(R_T1, R_T3,  4), 
 	gte_mv_to_ctrl_r(R_T0, gte_cr_RT11), gte_mv_to_ctrl_r(R_T1, gte_cr_RT12),
 	load_word(R_T0, R_T3, 8),  load_word(R_T1, R_T3, 12), load_word(R_T2, R_T3, 16),
 	gte_mv_to_ctrl_r(R_T0, gte_cr_RT13), gte_mv_to_ctrl_r(R_T1, gte_cr_RT21), gte_mv_to_ctrl_r(R_T2, gte_cr_RT22),

code/duffle/gte.h

@@ -33,7 +33,7 @@
  *  gte.h — Geometry Transformation Engine (COP2) for the PS1
  * ============================================================================
  *
- *  Hand-rolled DSL for emitting GTE/MIPS instruction words as raw `.word` constants from C.
+ *  Hand-rolled DSL for emitting GTE/MIPS instruction words from C.
  *  No GCC inline-assembly string syntax in the code body.
  *
  *  STYLE NOTES
@@ -177,42 +177,36 @@ enum {
  * Mirrors the OPCODE_SHIFT / RS_SHIFT convention used in mips.h.
  */
 
-	gte_shift_sf  = 19,  gte_width_sf  = 1,  gte_mask_sf  = 0x1,
+	gte_shift_sf  = 19,  gte_width_sf  = 1,
-	gte_shift_mx  = 17,  gte_width_mx  = 2,  gte_mask_mx  = 0x3,
+	gte_shift_mx  = 17,  gte_width_mx  = 2,
-	gte_shift_v   = 15,  gte_width_v   = 2,  gte_mask_v   = 0x3,
+	gte_shift_v   = 15,  gte_width_v   = 2,
-	gte_shift_cv  = 13,  gte_width_cv  = 2,  gte_mask_cv = 0x3,
+	gte_shift_cv  = 13,  gte_width_cv  = 2,
-	gte_shift_lm  = 10,  gte_width_lm  = 1,  gte_mask_lm  = 0x1,
+	gte_shift_lm  = 10,  gte_width_lm  = 1,
-	gte_shift_cmd =  0,  gte_width_cmd = 6,  gte_mask_cmd = 0x3F,
+	gte_shift_cmd =  0,  gte_width_cmd = 6,
 
 	/* Fake command number (bits 24-20) — IGNORED by the GTE hardware per PSX-SPX `geometrytransformationenginegte.md` line 48.
 	 * libgte's compiler emits non-zero values in this field as a disassembly signature. */
 	gte_shift_fake_cmd = 20,
 	gte_width_fake_cmd = 5,
-	gte_mask_fake_cmd  = 0x1F,
 };
 
 /* --- GTE Control Register Aliases (Pitfall 1) ---
- * Three pairs of aliases map to the SAME C2 control-register slot on real silicon:
+ * Three pairs of aliases map to the C2 control-register slot:
  *   C2[24] = gte_cr_RBK (background R)         | gte_cr_OFX (screen offset X)
  *   C2[25] = gte_cr_GBK (background G)         | gte_cr_OFY (screen offset Y)
  *   C2[26] = gte_cr_BBK (background B)         | gte_cr_H   (projection plane distance H)
- * Cross-alias writes inside one atom body, or across the wave-context boundary,
+ * Cross-alias writes inside one atom body, or across the wave-context boundary, silently clobber each other.
- * silently clobber each other. The metaprogram's check_gte_cr_alias_writes
+ * The metaprogram's check_gte_cr_alias_writes (CHECK_RULES row) warns about each pair per source.
- * (CHECK_RULES row) warns about each pair per source. See
+ * See psx-spx docs/gte_reference.md §"Control-register alias table" for the silicon rationale and the libgte outer-product convention.
- * docs/gte_reference.md §"Control-register alias table" for the silicon
- * rationale and the libgte outer-product convention.
  */
 
 /* --- RT-matrix packed-slot convention (Pitfall 4) ---
  * The silicon packs two 16-bit RT elements per 32-bit C2 slot:
  *   C2[2] = (RT22 << 16) | RT13       (gte_cr_RT13 writes the low  half, gte_cr_RT22 writes the high half)
  *   C2[4] = (RT33 << 16) | RT22       (gte_cr_RT22 writes the low  half — clobbers prior RT22 value if RT13 was also written)
- * OP and MVMVA read D1/D2/D3 from these packed slots. The libgte outer-product
+ * OP and MVMVA read D1/D2/D3 from these packed slots.
- * convention (see ac_apply_matrix_lv at gte.atom.c:108-122) writes C2[2] then
+ * The libgte outer-product convention (see ac_apply_matrix_lv at gte.atom.c:108-122) writes C2[2] then C2[4] in sequence;
- * C2[4] in sequence; the SECOND write's low half is RT22, not RT13. An agent
+ * the SECOND write's low half is RT22, not RT13. 
- * who writes gte_cr_RT13 then gte_cr_RT22 to the SAME source GPR clobbers the
- * RT13 value. See docs/gte_reference.md §"RT-matrix packed-slot convention"
- * for the canonical write pattern.
  */
 
 /* --- GTE Control Register Indices (for ctc2/cfc2) ---
@@ -301,8 +295,7 @@ enum { _C2_TX_SUBS_ = 0
 // #define gte_mv_from_data_r(rt, rd) enc_gte_tx(cop_mf, (rt), (rd)) /* Move GTE Control Register (rd) to GPR (rt) */
 
 /* GTE Data vs Control Register Transfers
- *
+ * Each macro emits a single instruction for one of MFC2/CFC2/MTC2/CTC2.
- * Each macro emits a single .word constant for one of MFC2/CFC2/MTC2/CTC2.
  *
  * `rd` is the C2 register index in the file the sub-opcode names:
  *   gte_mv_from_data_r / gte_mv_to_data_r  →  C2 data register file
@@ -317,14 +310,14 @@ enum { _C2_TX_SUBS_ = 0
 #define gte_mv_from_ctrl_r(rt, rd) enc_gte_tx(sub_cfc2, (rt), (rd)) /* Copy From ctrl reg */
 #define gte_mv_to_data_r(rt, rd)   enc_gte_tx(sub_mtc2, (rt), (rd)) /* Move To   data reg */
 #define gte_mv_to_ctrl_r(rt, rd)   enc_gte_tx(sub_ctc2, (rt), (rd)) /* Copy To   ctrl reg */
+#define GteDelay_ // Annotate an instruction as filling a CPU <-> GTE DMA delay slot/s
 
 /* COP2 Data Load (lwc2): `lwc2 rt, off(rs)`
  * Layout: [op_lwc2:6][rs:5][rt:5][imm:16]
  *   - rs: GPR base address
  *   - rt: COP2 data register index (0..31)
  *   - imm: signed 16-bit offset
- * NOTE: When `rs` is a runtime register, the encoding cannot be pre-baked
+ * NOTE: When `rs` is a runtime register, the encoding cannot be pre-baked into a .word — use the string-style `gte_load_v0` macro below instead. */
- * into a .word — use the string-style `gte_load_v0` macro below instead. */
 #define enc_gte_lw(rt, base, off) enc_i(op_lwc2, (base), (rt), (off))
 /* Store Word */
 #define enc_gte_sw(rt, base, off) enc_i(op_swc2, (base), (rt), (off))
@@ -333,8 +326,7 @@ enum { _C2_TX_SUBS_ = 0
  * `swc2` is redundant when we're already inside the `gte_` namespace.
  *   gte_lw rt, base, off  →  lwc2 rt, off(base)
  *   gte_sw rt, base, off  →  swc2 rt, off(base)
- * For the typical user-facing vector-level load (xy + z as two instructions),
+ * For the typical user-facing vector-level load (xy + z as two instructions), use the higher-level `gte_load_vN` macros below. */
- * use the higher-level `gte_load_vN` macros below. */
 #define gte_lw(rt, base, off) enc_gte_lw(rt, base, off)
 #define gte_sw(rt, base, off) enc_gte_sw(rt, base, off)
 
@@ -351,13 +343,13 @@ enum { _C2_TX_SUBS_ = 0
 #define gte_cmd_base (enc_op(op_cop2) | (1 << 25))
 
 /* Per-field encoders. Each one does (value & mask) << shift on its own. */
-#define enc_gte_sf(sf)          (((sf)  & gte_mask_sf      ) << gte_shift_sf )
+#define enc_gte_sf(sf)      ((sf)  << gte_shift_sf )
-#define enc_gte_mx(mx)          (((mx)  & gte_mask_mx      ) << gte_shift_mx )
+#define enc_gte_mx(mx)      ((mx)  << gte_shift_mx )
-#define enc_gte_v(v)            (((v)   & gte_mask_v       ) << gte_shift_v  )
+#define enc_gte_v(v)        ((v)   << gte_shift_v  )
-#define enc_gte_cv(cv)          (((cv)  & gte_mask_cv      ) << gte_shift_cv )
+#define enc_gte_cv(cv)      ((cv)  << gte_shift_cv )
-#define enc_gte_lm(lm)          (((lm)  & gte_mask_lm      ) << gte_shift_lm )
+#define enc_gte_lm(lm)      ((lm)  << gte_shift_lm )
-#define enc_gte_cmd(cmd)        (((cmd) & gte_mask_cmd     ) << gte_shift_cmd )
+#define enc_gte_cmd(cmd)    ((cmd) << gte_shift_cmd )
-#define enc_gte_fake_cmd(x)     (((x)   & gte_mask_fake_cmd) << gte_shift_fake_cmd)
+#define enc_gte_fake_cmd(x) ((x)   << gte_shift_fake_cmd)
 
 /* Composite: all six GTE fields + the COP2/CO base. */
 #define enc_gte_cmdw(sf, mx, v, cv, lm, cmd) ( \
@@ -409,10 +401,11 @@ enum { _C2_TX_SUBS_ = 0
 #define gte_cmdw_rtpt   (gte_cmd_base | enc_gte_cmd(gte_cmd_rtpt ) | gte_cmdw_psyq_compat)
 #define gte_cmdw_nclip  (gte_cmd_base | enc_gte_cmd(gte_cmd_nclip))
 #define gte_cmdw_op     (gte_cmd_base | enc_gte_cmd(gte_cmd_op   ))
-#define gte_cmdw_outer_product gte_cmdw_op      /* "outer product" -- NOCASH/Sdk terminology */
+#define gte_cmdw_outer_product gte_cmdw_op      /* "outer product" -- PSY-Q terminology */
-#define gte_cmdw_wedge         gte_cmdw_op      /* "wedge product"  -- geometric-algebra terminology.
+#define gte_cmdw_wedge         gte_cmdw_op      /* "wedge product"  -- geometric-algebra terminology. */
-	* RGA(Lengyel): the GTE OP is a 3D signed-16-bit D x IR cross, not a generic RGA exterior product.
+#define gte_cmdw_cross         gte_cmdw_op      /* "cross product"  -- geometric-algebra terminology.
-	* The wedge alias is the 3D complement interpretation of the same 3 scalars (MAC1..MAC3). */
+	* RGA(Lengyel): The GTE OP is a 3D signed-16-bit D x IR cross, not a generic RGA exterior product.
+	* The wedge alias is a 3D complement interpretation of the same 3 scalars (MAC1..MAC3). */
 #define gte_cmdw_mvmva  (gte_cmd_base | enc_gte_cmd(gte_cmd_mvmva))
 
 /* MVMVA with sf=0 (no shift, full-integer), cv=3 (no translation), v=3 (IR vector input).
@@ -440,22 +433,11 @@ enum { _C2_TX_SUBS_ = 0
 #define gte_cmdw_mvmva_pass1_c11  (gte_cmd_base | enc_gte_v(2) | enc_gte_mx(3) | enc_gte_cmd(gte_cmd_mvmva))
 #define gte_cmdw_mvmva_no_tr gte_cmdw_mvmva_ir
 
-/* MVMVA pass 2 — EXACT C11 ApplyMatrixLV command.
+/* MVMVA pass 2 — C11 ApplyMatrixLV command.
- * Command word: 0x4A49E012.
+ * Decoded: op_cop2 | CO | fake_cmd=4 | sf=1 (>>12) | mx=0 (RT matrix) | v=3 (IR) | cv=3 (no translation) | lm=0 | cmd=MVMVA.
- * bits 31-26: 010010 = COP2
+ * Reads (RT row · IR) >> 12 into MAC1/2/3. Per-field composition (no opaque literal)
- * bit 25: 1 (CO set)
+ * keeps the bit layout visible at the call site + matches the libgte C-side byte-exact. */
- * bits 24-20: 01001 = 9 (fake_cmd)
+#define gte_cmdw_mvmva_c11_pass2  (gte_cmd_base | enc_gte_fake_cmd(4) | enc_gte_sf(1) | enc_gte_v(3) | enc_gte_mx(0) | enc_gte_cv(3) | enc_gte_cmd(gte_cmd_mvmva))
- * bit 19: 1 (sf=1)
- * bits 18-17: 00 (mx=0, RT matrix)
- * bits 16-15: 11 (v=3, IR)
- * bits 14-13: 11 (cv=3, no translation)
- * bits 5-0: 010010 = MVMVA
- * sf=1, mx=0, v=3, cv=3. Pass 2 reads RT matrix, IR input, >>12. */
-#define gte_cmdw_mvmva_c11_pass2_exact  0x4A49E012
-
-/* MVMVA pass 1 — C11's exact command: 0x4A41E012.
- * bit 25: 1, sf=0, mx=0, v=3, cv=3. Pass 1 reads RT matrix, IR input, no shift. */
-#define gte_cmdw_mvmva_c11_pass1_exact  0x4A41E012
 
 /* MVMVA: sf=1 (>>12), mx=0 (RT matrix), v=0 (V0), cv=3 (no TR). */
 #define gte_cmdw_mvmva_sf1_mx0_v0_cv3  (gte_cmd_base | enc_gte_sf(1) | enc_gte_cv(3) | enc_gte_v(0) | enc_gte_mx(0) | enc_gte_cmd(gte_cmd_mvmva))
@@ -485,16 +467,24 @@ enum { _C2_TX_SUBS_ = 0
 
 /* GPF — General-purpose Interpolation.
  * PSX-SPX `geometrytransformationenginegte.md` §"GPF":
- *   [MAC1,MAC2,MAC3] = (([IR1,IR2,IR3] * IR0) + [MAC1,MAC2,MAC3]) SAR (sf*12)
+ *   [MAC1,MAC2,MAC3] = (([IR1,IR2,IR3] * IR0) + [MAC1,MAC2,MAC3]) SAR (sf * 12)
  *   [IR1,IR2,IR3]    = [MAC1,MAC2,MAC3]
  * Sourced verbatim from libgte msc02 VectorNormal disassembly at 0x8001613c:
  *   0x4B90003D = gte_cmd_base | gte_cmdw_gpf_compat | enc_gte_cmd(0x3D)
- *   bit 19     sf=0
+ *   bit 19     sf = 0
- *   bit 10     lm=0
+ *   bit 10     lm = 0
- *   bits 5-0   cmd=0x3D=GPF
+ *   bits 5-0   cmd = 0x3D = GPF
  *   bits 24-20 = 0x19 (libgte "nonsense SDK command number" signature) */
 #define gte_cmdw_gpf   (gte_cmd_base | enc_gte_cmd(gte_cmd_gpf) | gte_cmdw_gpf_fake_sig)
 
+/* Mask to round LZCR (leading-zero/ones count, range 1..32 per PSX-SPX cop2r31)
+ * down to even. The normalize_v3s4 half-shift logic computes (31 - LZCR) >> 1;
+ * clearing bit 0 ensures the subtraction result is always odd,
+ * so the >> 1 division is consistent (no 0.5 loss). */
+enum {
+	gte_lzcr_even_mask = 0xFFFE, /* all bits except bit 0 */
+};
+
 #define gte_cmdw_rotate_translate_perspective_single gte_cmdw_rtps
 #define gte_cmdw_rotate_translate_perspective_triple gte_cmdw_rtpt
 /* RGA(Lengyel): RTPS/RTPT consume the matrix expansion of a rigid transformation (rotation matrix + translation vector) loaded into the RT/TR control registers.

code/duffle/lottes_tape.h

@@ -101,11 +101,12 @@ enum {
 };
 
 typedef U2 Reg; // Register parameter used with atom or atom component procedures
+#define Reg_(type) tmpl(Reg,type) // Just a way to template register allocations of C-struct types.
 
 typedef U4 const MipsCode; // Underlying type to mips asm words.
 typedef Slice_(MipsCode);
 
-typedef U4 const MipsAtom; 
+typedef U4 const MipsAtom; // Underlying type to a mips atom defnition 
 typedef Slice_(MipsAtom); 
 // Sometimes a user will define a bundle of atoms that represent a procedure of work as:
 //   MipsAtom* <identifier>[...];
@@ -117,10 +118,13 @@ typedef Slice_(MipsAtom);
 #define MipsAtom_(sym) MipsCode sym [] align_(4) =
 
 // Used for atoms with value-args
-//   FI_ void ac_X(args) MipsAtomComp_Proc_(ac_X, { body })
+//   internal MipsAtom* X_proc(AtomArena_R aa, args) MipsAtom_Proc_(X, aa, { body })
 // expands to:
-//   FI_ void ac_X(args) { MipsCode ac_X[] align_(4) = { body }; return ac_X; }
+//   internal MipsAtom* X_proc(AtomArena_R aa, args) { MipsCode atom_comp_code[] align_(4) = { body }; return atomarena_push(aa, slice_from_array(MipsCode, atom_comp_code)); }
-#define MipsAtom_Proc_(sym, aa, ...) { MipsCode sym [] align_(4) = __VA_ARGS__; return atomarena_push(aa, slice_from_array(MipsCode, sym)); }
+// The atom name is derived by the Lua metaprogram from the preceding
+// `MipsAtom* X_proc(...)` declaration (backward walk from the macro site,
+// strips the `_proc` suffix).
+#define MipsAtom_Proc_(aa, ...) { MipsCode atom_comp_code[] align_(4) = __VA_ARGS__; return atomarena_push(aa, slice_from_array(MipsCode, atom_comp_code)); }
 
 // Used for components with no args (e.g., ac_load_tri_indices) or identifier-args (hardcoded register names).
 //   MipsAtomComp_(ac_X) { body }
@@ -129,24 +133,26 @@ typedef Slice_(MipsAtom);
 #define MipsAtomComp_(sym) MipsCode sym [] align_(4) =
 
 // Used for components with value-args (mandatory `ab` (atom-builder) arg).
-//   FI_ void ac_X(MipsAtomBuilder_R ab, args) MipsAtomComp_Proc_(ac_X, ab, { body })
+//   FI_ void ac_X(MipsAtomBuilder_R ab, args) MipsAtomComp_Proc_(ab, { body })
 // expands to:
 //   FI_ void ac_X(MipsAtomBuilder_R ab, args) {
-//       MipsCode ac_X[] align_(4) = { body };
+//       MipsCode atom_comp_code[] align_(4) = { body };
-//       atombuilder_unroll(ab, slice_from_array(MipsCode, ac_X));
+//       atombuilder_push(ab, slice_from_array(MipsCode, atom_comp_code));
 //   }
 // The body must NOT include mac_yield() (the parent atom yields).
-// Inline-only callers (the generated `mac_<name>` aliases) skip this arg via metaprogram filtering;
+// The component name is derived by the Lua metaprogram from the preceding `FI_ Slice_MipsCode ac_X(...)` declaration (backward walk from the macro site).
-// escape callers (ac_<name> invoked as a function) pass a long-lived builder.
+// Inline-only callers (the generated `mac_<name>` aliases) skip the `ab` arg via metaprogram filtering; escape callers (ac_<name> invoked as a function) pass a long-lived builder.
-#define MipsAtomComp_Proc_(sym, ab, ...) { MipsCode sym [] align_(4) = __VA_ARGS__; atombuilder_push(ab, slice_from_array(MipsCode, sym)); }
+#define MipsAtomComp_Proc_(ab, ...) { MipsCode atom_comp_code[] align_(4) = __VA_ARGS__; atombuilder_push(ab, slice_from_array(MipsCode, atom_comp_code)); }
+
+#define MipsAtomComp_ProcMap_(ab, base_command) atom_dbg_skip MipsAtomComp_Proc_(ab, {base_command })
 
 /* Line-table anchor: gcc only adds a file to the .debug_line file table when the contains line-numbered content.
 	Files containing only atoms and atom components.
    Place `ATOM_FILE_LINE_MARKER();` once at file scope in any `.atom.c` that defines atoms.
-	 The macro expands to a file-scope `internal U4 const` declaration keeps the file in the line table.
+	 Macro expands to a file-scope `internal U4 const` declaration keeps the file in the line table.
-	 The constant is in `.rodata` and unreferenced; the linker may eliminate it.
+	 The constant is in `.rodata` so the linker may eliminate it.
-	 The two-level concat + `__LINE__` suffix makes the identifier unique per call site
+	 Two-level concat + `__LINE__` suffix makes the identifier unique per call site
-	 (the identifier embeds the source line, so duplicates across `#include`d files don't collide). */
+	 (identifier embeds the source line, so duplicates across `#include`d files don't collide). */
 #define ATOM_FILE_DEBUGGER_LINE_MARKER(file_name) internal U4 const tmpl(atom_file_debugger_line_marker,file_name) = 0
 
 typedef Slice_MipsAtom Tape;
@@ -239,6 +245,7 @@ atom_dbg_skip MipsAtomComp_(ac_yield_tail) {
 	add_ui_self(R_TapePtr, S_(MipsCode)),
 	jump_reg(  R_AtomJmp), nop,
 };
+
 #pragma endregion Macro Atom Components
 
 #pragma region Atom Builder
@@ -284,37 +291,118 @@ FI_ MipsAtom* atomarena_push(AtomArena_R aa, Slice_MipsCode code) {
 	return C_(MipsAtom*, dest);
 }
 FI_ void atomarena_reset(AtomArena_R aa) { aa->used = 0; }
-#pragma region Atom Arena
+#pragma endregion Atom Arena
 
 #pragma region RegFile (Register File Allocator)
 // A specialized allocator utilized to help the user track which registers are bound to values
 // that must be preserved for the arena's bounds.
+// TODO(Ed): Technically we can do this at comp-time with the metaprogram, but we may have namespace conflicts.
+// Unless we follow a convention for #define <Scope_Prefix> or something per register allocation boundary.
 
-enum {
+/* ABI + tape reserves that are never handed out by alloc. */
-	RegFileArena_Len,
+U4 const regfile_abi_mask =
-};
+	(1u << R_0)  | (1u << R_AT)  |
-typedef Enum_(U4, RegFileEntry) {
+	(1u << R_K0) | (1u << R_K1)  |
-	// TODO(Ed): Define RF_Field, each field is maped by index + bit pos.
+	(1u << R_GP) | (1u << R_SP)  |
-	// the index is the upper portion of a U4 and the bit pos in the lower pos.
+	(1u << R_FP) | (1u << R_RA)  |
+	(1u << R_T8) | (1u << R_T9); /* AtomJmp + TapePtr */
 
-	regfileentry_todo_,
-	// TODO(Ed): Is there a trick we can do with the current register enums to 
-	// just resolve an entry automatically when doing a pin?
-};
 typedef Struct_(RegFile) {
-	U1 GPR[RegFileArena_Len];
+	A2_U2 GPR;
-	U1 GTE[RegFileArena_Len];
+	A2_U2 GTE;
-	U1 GP[RegFileArena_Len];
 };
-
+#define regfile(pin_mask) {.GPR={u4_lo(pin_mask), u4_hi(pin_mask)} }
-void regfile_pin(U4 register) {
+FI_ void regfile_init(RegFile_R rf) {
-
+	/* pack the 32-bit ABI mask into the two U2s */
-	assert(false);
+	rf->GPR[0] = u4_lo(regfile_abi_mask);
+	rf->GPR[1] = u4_hi(regfile_abi_mask);
+	rf->GTE[0] = rf->GTE[1] = 0;
 }
+FI_ RegFile regfile_make(void) { RegFile rf; regfile_init(& rf); return rf; }
 
+typedef Struct_(RegFile_RInfo) {
+	U2_R section;
+	U2   mask;
+	B2   occupied;
+};
+FI_ RegFile_RInfo regfile_rinfo(A2_U2 file, Reg r_id) {
+	U2   s_id     = r_id >> 4;
+	U2_R section  = & file[s_id];
+	U2   mask     = u2_(1u << (r_id & 15));
+	B2   occupied = (section[0] & mask) != 0;
+	return (RegFile_RInfo){section, mask, occupied};
+}
+FI_ Reg regfile__alloc_helper(A2_U2 file, Reg r_id) {
+	Reg result = 0; RegFile_RInfo info = regfile_rinfo(file, r_id);
+	if (info.occupied == false) {
+		info.section[0] |= info.mask;
+		result = r_id;
+	}
+	return result; 
+}
+I_ Reg regfile_alloc(RegFile_R rf) {
+	U2 allocated = 0;
+	for index_iter(Reg, r_id, R_T0, <=, R_T7) {
+		allocated = regfile__alloc_helper(rf->GPR, r_id); Jmp_nZero_(allocated,resolved);
+	}
+	allocated = regfile__alloc_helper(rf->GPR, R_V0); Jmp_nZero_(allocated,resolved);
+	allocated = regfile__alloc_helper(rf->GPR, R_V1);
+	assert(allocated != 0);
+resolved: return allocated;
+}
+FI_ Reg regfile_pin(RegFile_R rf, Reg r_id) {
+	RegFile_RInfo info = regfile_rinfo(rf->GPR, r_id);
+	assert(info.occupied == false);
+	info.section[0] |= info.mask;
+	return r_id;
+}
+FI_ void regfile_pin_mask(RegFile_R rf, U4 mask) {
+	B4 occupied = u4_r(rf->GPR)[0] & mask;
+	assert(occupied == false);
+	u4_r(rf->GPR)[0] |= mask;
+}
+FI_ void regfile_free_mask(RegFile_R rf, U4 mask) {
+	if (regfile_abi_mask & mask) return;
+	u4_r(rf->GPR)[0] &= ~mask;
+}
+FI_ void regfile_free_reg(RegFile_R rf, Reg r_id) {
+	/* never free the ABI set */
+	if (regfile_abi_mask & (1u << r_id)) return;
+	RegFile_RInfo info = regfile_rinfo(rf->GPR, r_id);
+	info.section[0] &= ~info.mask;
+}
+FI_ void regfile_reset(RegFile_R rf) {
+	rf->GPR[0] = u4_lo(regfile_abi_mask);
+	rf->GPR[1] = u4_hi(regfile_abi_mask);
+}
+FI_ void regfile_reset_to_mask(RegFile_R rf, U4 mask) {
+	rf->GPR[0] = u4_lo(mask);
+	rf->GPR[1] = u4_hi(mask);
+}
 #pragma endregion RegFileArena (Register File Allocator)
 
 #pragma region Mips Atom Procs
+/* RegUse structs are a convention to organize register allocations for a mips atom procedure.
+	Unlike the usual enum-based declarations, they provide a namespaced scope 
+	and have view types via union declarations.
+*/
+#define RegUse_(proc_name) (tmpl(RegUse,proc_name))
+
+	typedef Struct_(RegUse_example_atom_proc) {
+		Reg const ro_register; // Scratch base carrier.
+		Reg usual_modifiable;
+		union { Reg view_1, view_2, view_3; } t1;
+	};
+	internal MipsAtom* example_atom_proc(AtomArena_R aa, U2 offset, RegUse_example_atom_proc r) 
+	MipsAtom_Proc_(aa, {
+		add_si(r.usual_modifiable, r.ro_register, offset),
+		or_u(r.t1.view_1, r.ro_register, 0),
+		branch_lt_zero(r.t1.view_1, atom_offset(example_atom_proc, skip)), BdSlot_ nop,
+		li_s(r.t1.view_2, 100),
+	atom_label(skip)
+		add_si(r.t1.view_3, r.usual_modifiable, 10),
+		mac_yield(),
+	})
 
 #pragma endregion Mips Atom Procs
 

code/duffle/math.atom.c

@@ -1,53 +0,0 @@
-#ifdef INTELLISENSE_DIRECTIVES
-#	include "gen/macs.h"
-#	include "gen/offsets.h"
-#	include "math.h"
-#	include "lottes_tape.h"
-#endif
-
-ATOM_FILE_DEBUGGER_LINE_MARKER(math_atom_c);
-
-#pragma region MACs (Mips Atom Component)
-
-FI_ Slice_MipsCode ac_load_v2s2(AtomBuilder_R ab, U4 rs_x, U4 rs_y, U4 r_base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_load_v2s2, ab, {
-	load_half( rs_x, r_base, offset + O_(V3_S2,x)),
-	load_half( rs_y, r_base, offset + O_(V3_S2,y)),
-})
-
-FI_ Slice_MipsCode ac_store_v2s2(AtomBuilder_R ab, U4 rt_x, U4 rt_y, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_store_v2s2, ab, {
-	store_half(rt_x, base, offset + O_(V2_S2,x)),
-	store_half(rt_y, base, offset + O_(V2_S2,y)),
-})
-
-FI_ Slice_MipsCode ac_load_v3s4(AtomBuilder_R ab, U4 rs_x, U4 rs_y, U4 rs_z, U4 r_base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_load_v3s4, ab, {
-	load_word( rs_x, r_base, offset + O_(V3_S4,x)),
-	load_word( rs_y, r_base, offset + O_(V3_S4,y)),
-	load_word( rs_z, r_base, offset + O_(V3_S4,z)),
-})
-// TODO(Ed): we could generate these mappings properly..
-#define ac_load_p3s4 ac_load_v3s4
-#define mac_load_p3s4 mac_load_v3s4
-
-FI_ Slice_MipsCode ac_store_v3s4(AtomBuilder_R ab, U4 rt_x, U4 rt_y, U4 rt_z, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_store_v3s4, ab, {
-	store_word(rt_x, base, offset + O_(V3_S4,x)),
-	store_word(rt_y, base, offset + O_(V3_S4,y)),
-	store_word(rt_z, base, offset + O_(V3_S4,z)),
-})
-// TODO(Ed): we could generate these mappings properly..
-#define ac_store_p3s4 ac_store_v3s4
-#define mac_store_p3s4 mac_store_v3s4
-
-FI_ Slice_MipsCode ac_sub_v3s4(AtomBuilder_R ab, U4 rds_x, U4 rds_y, U4 rds_z, U4 rt_x,  U4 rt_y,  U4 rt_z) atom_dbg_skip MipsAtomComp_Proc_(ac_sub_v3s4, ab, {
-	sub_s(rds_x, rds_x, rt_x),
-	sub_s(rds_y, rds_y, rt_y),
-	sub_s(rds_z, rds_z, rt_z),
-})
-
-FI_ Slice_MipsCode ac_store_rects2(AtomBuilder_R ab, U4 rt_x, U4 rt_y, U4 rt_width, U4 rt_height, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ac_store_rects2, ab, {
-	store_half(rt_x,      base, offset + O_(Rect_S2,x)),
-	store_half(rt_y,      base, offset + O_(Rect_S2,y)),
-	store_half(rt_width,  base, offset + O_(Rect_S2,width)),
-	store_half(rt_height, base, offset + O_(Rect_S2,height)),
-})
-
-#pragma endregion MACs (Mips Atom Component)

code/duffle/math.atom.h

@@ -0,0 +1,96 @@
+#ifdef INTELLISENSE_DIRECTIVES
+#	include "gen/macs.h"
+#	include "gen/offsets.h"
+#	include "math.h"
+#	include "lottes_tape.h"
+#endif
+
+ATOM_FILE_DEBUGGER_LINE_MARKER(math_atom_c);
+
+#define v3s4_R_0() ((Reg_(V3_S4)){R_0,R_0,R_0})
+
+typedef Struct_(Reg_V3_S2) { Reg x, y, z; };
+typedef Struct_(Reg_V3_S4) { Reg x, y, z; }; // Register allocation of a V3_S4
+typedef Struct_(Reg_P3_S4) { Reg x, y, z; }; // Register allocation of a P3_S4
+
+#pragma region MACs (Mips Atom Component)
+
+FI_ Slice_MipsCode ac_load_half_v3(AtomBuilder_R ab, Reg tx, Reg ty, Reg tz, Reg base, U2 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	load_half(tx, base, offset + OA_(U2,[0])),
+	load_half(ty, base, offset + OA_(U2,[1])),
+	load_half(tz, base, offset + OA_(U2,[2])),
+})
+
+FI_ Slice_MipsCode ac_load_v3s2(AtomBuilder_R ab, Reg_(V3_S2) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_load_half_v3(transfer.x, transfer.y, transfer.z, base, offset))
+
+FI_ Slice_MipsCode ac_load_v2s2(AtomBuilder_R ab, U4 rs_x, U4 rs_y, U4 r_base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	load_half(rs_x, r_base, offset + O_(V3_S2,x)),
+	load_half(rs_y, r_base, offset + O_(V3_S2,y)),
+})
+
+FI_ Slice_MipsCode ac_store_v2s2(AtomBuilder_R ab, U4 rt_x, U4 rt_y, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	store_half(rt_x, base, offset + O_(V2_S2,x)),
+	store_half(rt_y, base, offset + O_(V2_S2,y)),
+})
+
+FI_ Slice_MipsCode ac_load_word_v3(AtomBuilder_R ab, Reg tx, Reg ty, Reg tz, Reg base, U2 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	load_word(tx, base, offset + OA_(U4,[0])),
+	load_word(ty, base, offset + OA_(U4,[1])),
+	load_word(tz, base, offset + OA_(U4,[2])),
+})
+
+FI_ Slice_MipsCode ac_load_v3s4(AtomBuilder_R ab, Reg_(V3_S4) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_load_word_v3(transfer.x, transfer.y, transfer.z, base, offset))
+FI_ Slice_MipsCode ac_load_p3s4(AtomBuilder_R ab, Reg_(P3_S4) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_load_word_v3(transfer.x, transfer.y, transfer.z, base, offset))
+
+FI_ Slice_MipsCode ac_store_half_v3(AtomBuilder_R ab, Reg tx, Reg ty, Reg tz, Reg base, U2 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	store_half(tx, base, offset + OA_(U2,[0])),
+	store_half(ty, base, offset + OA_(U2,[1])),
+	store_half(tz, base, offset + OA_(U2,[2])),
+})
+
+FI_ Slice_MipsCode ac_store_v3s2(AtomBuilder_R ab, Reg_(V3_S2) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_store_half_v3(transfer.x, transfer.y, transfer.z, base, offset))
+
+FI_ Slice_MipsCode ac_store_word_v3(AtomBuilder_R ab, Reg tx, Reg ty, Reg tz, Reg base, U2 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	store_word(tx, base, offset + OA_(U4,[0])),
+	store_word(ty, base, offset + OA_(U4,[1])),
+	store_word(tz, base, offset + OA_(U4,[2])),
+})
+
+FI_ Slice_MipsCode ac_store_v3s4(AtomBuilder_R ab, Reg_(V3_S4) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_store_word_v3(transfer.x, transfer.y, transfer.z, base, offset))
+FI_ Slice_MipsCode ac_store_p3s4(AtomBuilder_R ab, Reg_(P3_S4) transfer, Reg base, U2 offset) MipsAtomComp_ProcMap_(ab, mac_store_word_v3(transfer.x, transfer.y, transfer.z, base, offset))
+
+FI_ Slice_MipsCode ac_add_si_v3s4(AtomBuilder_R ab, Reg rt_x,  Reg rt_y,  Reg rt_z, Reg base, U2 offset)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	add_si(rt_x, base, O_(V3_S4,x)),
+	add_si(rt_y, base, O_(V3_S4,y)),
+	add_si(rt_z, base, O_(V3_S4,z)),
+})
+
+FI_ Slice_MipsCode ac_sub_s_v3(AtomBuilder_R ab
+	, Reg dx, Reg dy, Reg dz
+	, Reg sx, Reg sy, Reg sz
+	, Reg tx, Reg ty, Reg tz
+) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	sub_s(dx, sx, tx),
+	sub_s(dy, sy, ty),
+	sub_s(dz, sz, tz),
+})
+
+FI_ Slice_MipsCode ac_sub_v3s4(AtomBuilder_R ab, Reg_(V3_S4) d, Reg_(V3_S4) s, Reg_(V3_S4) t) MipsAtomComp_ProcMap_(ab, mac_sub_s_v3(d.x, d.y, d.z, s.x, s.y, s.z, t.x, t.y, t.z))
+
+FI_ Slice_MipsCode ac_sub_s_v3_self(AtomBuilder_R ab, Reg ds_x, Reg ds_y, Reg ds_z, Reg tx,  Reg ty,  Reg tz) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	sub_s(ds_x, ds_x, tx),
+	sub_s(ds_y, ds_y, ty),
+	sub_s(ds_z, ds_z, tz),
+})
+
+FI_ Slice_MipsCode ac_sub_v3s4_self(AtomBuilder_R ab, Reg_(V3_S4) ds, Reg_(V3_S4) t) MipsAtomComp_ProcMap_(ab, mac_sub_s_v3_self(ds.x, ds.y, ds.z, t.x, t.y, t.z))
+
+FI_ Slice_MipsCode ac_store_rects2(AtomBuilder_R ab, U4 rt_x, U4 rt_y, U4 rt_width, U4 rt_height, U4 base, U4 offset) atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	store_half(rt_x,      base, offset + O_(Rect_S2,x)),
+	store_half(rt_y,      base, offset + O_(Rect_S2,y)),
+	store_half(rt_width,  base, offset + O_(Rect_S2,width)),
+	store_half(rt_height, base, offset + O_(Rect_S2,height)),
+})
+
+#pragma endregion MACs (Mips Atom Component)

code/duffle/math.h

@@ -24,6 +24,7 @@ enum {
 };
 
 typedef Array_(U1, 2);
+typedef Array_(U2, 2);
 typedef Array_(U4, 2);
 typedef Array_(S2, 2);
 typedef Array_(S2, 3);
@@ -46,6 +47,9 @@ typedef Struct_(V4_S4)      { S4 x; S4 y; S4 z; S4 w; };
 // typedef Struct_(P3_S4)      { S4 x; S4 y; S4 z; S4 w1; }; // RGA(Lengyel): Affine point with implicit weight one. Storage alias of V3_S4. Use P3_S4 when the value is a point.
 typedef V3_S4 P3_S4;
 
+typedef Struct_(R1_U2) { U2 p0; U2 p1; };
+typedef Struct_(R1_S2) { S2 p0; S2 p1; };
+
 typedef Struct_(R2_S2)      { V2_S2 p0; V2_S2 p1; }; // Range-2 Signed 2-Byte (16-bit)
 typedef Struct_(R2_S4)      { V2_S4 p0; V2_S4 p1; }; // Range-2 Signed 4-Byte (32-bit)
 
@@ -64,6 +68,8 @@ typedef Array_(V2_S2, 2);
 typedef Array_(V2_S2, 3);
 typedef Array_(V2_S2, 4);
 
+#define r1u2(p0,p1) (R1_U2){p0,p1}
+
 enum {
 	fp_one = (1 << 12),
 };
@@ -106,10 +112,10 @@ FI_ void mul_a3s4(A3_S4_R out_a, A3_S4 b) {
 	(out_a[0])[2] *= b[2];
 }
 
-FI_ void add_v3s4   (V3_S4_R out_a, V3_S4 b) {  add_a3s4   (pcast(A3_S4_R, out_a), pcast(A3_S4, b));  }
+FI_ void add_v3s4   (V3_S4_R out_a, V3_S4 b) {  add_a3s4   (C_ptr(A3_S4_R, out_a), C_ptr(A3_S4, b));  }
-FI_ void add_v3s4_fp(V3_S4_R out_a, V3_S4 b) {  add_a3s4_fp(pcast(A3_S4_R, out_a), pcast(A3_S4, b));  }
+FI_ void add_v3s4_fp(V3_S4_R out_a, V3_S4 b) {  add_a3s4_fp(C_ptr(A3_S4_R, out_a), C_ptr(A3_S4, b));  }
 
-FI_ void sub_v3s4   (V3_S4_R out_a, V3_S4 b) {  sub_a3s4   (pcast(A3_S4_R, out_a), pcast(A3_S4, b));  }
+FI_ void sub_v3s4   (V3_S4_R out_a, V3_S4 b) {  sub_a3s4   (C_ptr(A3_S4_R, out_a), C_ptr(A3_S4, b));  }
-FI_ void sub_v3s4_fp(V3_S4_R out_a, V3_S4 b) {  sub_a3s4_fp(pcast(A3_S4_R, out_a), pcast(A3_S4, b));  }
+FI_ void sub_v3s4_fp(V3_S4_R out_a, V3_S4 b) {  sub_a3s4_fp(C_ptr(A3_S4_R, out_a), C_ptr(A3_S4, b));  }
 
-FI_ void mul_v3s4   (V3_S4_R out_a, V3_S4 b) {  mul_a3s4   (pcast(A3_S4_R, out_a), pcast(A3_S4, b));  }
+FI_ void mul_v3s4   (V3_S4_R out_a, V3_S4 b) {  mul_a3s4   (C_ptr(A3_S4_R, out_a), C_ptr(A3_S4, b));  }

code/duffle/memory.h

@@ -73,7 +73,7 @@ typedef Slice_(B1);
 
 #define slice_iter(container, iter)     (T_((container).ptr) iter = (container).ptr; iter != slice_end(container); ++ iter)
 #define slice_arg_from_array(type, ...) & (tmpl(Slice,type)) { .ptr = Array_decl(type,__VA_ARGS__), .len = Array_len( Array_decl(type,__VA_ARGS__)) }
-#define slice_from_array(type, array)     (tmpl(Slice,type)) { .ptr = array, .len = S_(array) / S_(type) }
+#define slice_from_array(type, array)     (tmpl(Slice,type)) { .ptr = array, .len = Array_len(array) }
 
 FI_ void slice_zero_(Slice s) { slice_assert(s); mem_zero(u4_(s.ptr), s.len); }
 #define  slice_zero(s)        slice_zero_(slice_to_ut(s))

code/duffle/mips.atom.c

@@ -1,12 +1,49 @@
 #ifdef INTELLISENSE_DIRECTIVES
-#	include "gen/macs.h"
+#		include "gen/macs.h"
-#	include "gen/offsets.h"
+#		include "gen/offsets.h"
 #	include "bios.h"
+#	include "mips.h"
 #	include "lottes_tape.h"
 #endif
 
 ATOM_FILE_DEBUGGER_LINE_MARKER(mips_atom_c);
 
+#pragma region MACs (Mips Atom Components)
+
+FI_ Slice_MipsCode ac_load_word_imm(AtomBuilder_R ab, Reg dst, U4 imm)
+atom_dbg_skip MipsAtomComp_Proc_(ab, {
+	load_upper_i(dst, u4_hi(imm)),
+	or_i_self(   dst, u4_lo(imm)),
+})
+
+FI_ Slice_MipsCode ac_shift_aright_v3_self(AtomBuilder_R ab, Reg dt_x, Reg dt_y, Reg dt_z, U2 shift_amount)
+MipsAtomComp_Proc_( ab, {
+	shift_aright(dt_x, dt_x, shift_amount),
+	shift_aright(dt_y, dt_y, shift_amount),
+	shift_aright(dt_z, dt_z, shift_amount),	
+})
+
+FI_ Slice_MipsCode ac_shift_aright_var_v3(AtomBuilder_R ab
+	, Reg rd_v0, Reg rd_v1, Reg rd_v2
+	, Reg rs_v0, Reg rs_v1, Reg rs_v2
+	, Reg r_shift)
+MipsAtomComp_Proc_(ab, {
+	shift_aright_var(rd_v0, rs_v0, r_shift),
+	shift_aright_var(rd_v1, rs_v1, r_shift),
+	shift_aright_var(rd_v2, rs_v2, r_shift),
+})
+
+FI_ Slice_MipsCode ac_shift_aright_var_v3_self(AtomBuilder_R ab
+	, Reg rds_v0, Reg rds_v1, Reg rds_v2
+	, Reg r_shift)
+MipsAtomComp_Proc_(ab, {
+	shift_aright_var(rds_v0, rds_v0, r_shift),
+	shift_aright_var(rds_v1, rds_v1, r_shift),
+	shift_aright_var(rds_v2, rds_v2, r_shift),
+})
+
+#pragma endregion MACs (Mips Atom Components)
+
 #pragma region Baked Atoms
 
 /* Flushes the Instruction Cache (PSX A-function 0x44 via BIOS stub at 0xA0).

code/duffle/mips.h

@@ -259,22 +259,22 @@ enum { _BitOffsets = 0
 	, SHAMT_SHIFT  = 6  /* Shift Amount */
 	, FC_SHIFT     = 0
 
-/* Bit Masks to prevent overflow into adjacent fields */
+/* IMM_MASK is the 16-bit two's-complement truncation for the immediate field.
+ * It is NOT a range guard — it is load-bearing for negative branch offsets
+ * (the metaprogram emits raw signed offsets; the mask truncates them to the
+ * 16-bit representation the hardware expects). The static analysis
+ * `immediate_field_width` check validates ranges at build time. */
 
-	, OPCODE_MASK  = 0x3F
-	, REG_MASK     = 0x1F
-	, SHAMT_MASK   = 0x1F /* Shift Amount */
-	, FC_MASK      = 0x3F
 	, IMM_MASK     = 0xFFFF
 };
 
-#define enc_op(op)       (((op)    & OPCODE_MASK) << OPCODE_SHIFT)
+#define enc_op(op)       ((op)    << OPCODE_SHIFT)
-#define enc_rs(rs)       (((rs)    & REG_MASK)    << RS_SHIFT)
+#define enc_rs(rs)       ((rs)    << RS_SHIFT)
-#define enc_rt(rt)       (((rt)    & REG_MASK)    << RT_SHIFT)
+#define enc_rt(rt)       ((rt)    << RT_SHIFT)
-#define enc_rd(rd)       (((rd)    & REG_MASK)    << RD_SHIFT)
+#define enc_rd(rd)       ((rd)    << RD_SHIFT)
-#define enc_shamt(shamt) (((shamt) & SHAMT_MASK)  << SHAMT_SHIFT)
+#define enc_shamt(shamt) ((shamt) << SHAMT_SHIFT)
-#define enc_fc(fc)       (((fc)    & FC_MASK)     << FC_SHIFT)
+#define enc_fc(fc)       ((fc)    << FC_SHIFT)
-#define enc_imm(imm)     (((imm)   & IMM_MASK))
+#define enc_imm(imm)     ((imm) & IMM_MASK)
 
 /* MIPS R-Type Instruction Format (Register-to-Register) */
 #define enc_r(op, rs, rt, rd, shamt, fc) (enc_op(op) | enc_rs(rs) | enc_rt(rt) | enc_rd(rd) | enc_shamt(shamt) | enc_fc(fc))
@@ -318,7 +318,10 @@ enum { _BitOffsets = 0
 #define load_half(rt, base, off)   enc_i(op_lh,    (base), (rt), (off))
 #define load_byte_u(rt, base, off) enc_i(op_lbu,   (base), (rt), (off))
 #define load_half_u(rt, base, off) enc_i(op_lhu,   (base), (rt), (off))
+#define LdSlot_
+
 #define store_word(rt, base, off)  enc_i(op_sw,    (base), (rt), (off))
+
 #define add_ui(rt, rs, imm)        enc_i(op_addiu, (rs),   (rt), (imm))
 #define and_i(rt, rs, imm)         enc_i(op_andi,  (rs),   (rt), (imm))
 // #define and_si                     and_i
@@ -379,6 +382,9 @@ enum { _BitOffsets = 0
  */
 #define jump(off)                  enc_i(op_j,     R_0, R_0, (off))
 
+// Annotate an instruction as filling a branch-delay slot.
+#define BdSlot_
+
 /* jump_rel off — unconditional relative jump (the within-atom-safe `jump`).
  * MIPS I R3000A has no "branch always" opcode. The idiom for an unconditional relative jump is `beq $0, $0, off`. */
 #define jump_rel(off)              branch_equal(R_0, R_0, (off))
@@ -411,6 +417,7 @@ enum { _BitOffsets = 0
 #define div_s(rd, rs, rt)          enc_r(op_special, (rs), (rt), (rd), 0, fc_div)
 #define div_u(rd, rs, rt)          enc_r(op_special, (rs), (rt), (rd), 0, fc_divu)
 
+// TODO(Ed): Change convention of 'self' to ds for (destination is source)?
 #define add_u_self(rd_rs, rt)      add_u(rd_rs, rd_rs, rt)
 
 /* --- Arithmetic I-type (immediate) --- */
@@ -457,7 +464,8 @@ enum { _BitOffsets = 0
 #define nop2 nop, nop
 
 // li_s — load signed 16-bit immediate into GPR (addiu rt, $0, imm — sign-extends).
-#define li_s(rt, imm)  add_ui((rt), R_0, (imm))
+#define li_s(rt, imm)       add_ui((rt), R_0, (imm))
+// #define load_imm_s(rt, imm) add_ui((rt), R_0, (imm))
 
 #define load_imm_1w(rt, imm)    add_ui((rt),  R_0, (imm))
 #define load_imm_1w_s0(rt, imm) add_si((rt)), R_0, (imm))

code/duffle/pad.atom.c

@@ -11,18 +11,19 @@ ATOM_FILE_DEBUGGER_LINE_MARKER(pad_atom_c);
 
 #pragma region MACs (Mips Atom Components)
 
-FI_ Slice_MipsCode ac_pad_set_centered_axes(AtomBuilder_R ab, U4 r_state, U4 r_scratch) atom_dbg_skip MipsAtomComp_Proc_(ac_pad_set_centered_axes, ab, {
+FI_ Slice_MipsCode ac_pad_set_centered_axes(AtomBuilder_R ab, Reg state, Reg scratch) atom_dbg_skip MipsAtomComp_Proc_(ab, {
-    load_upper_i(r_scratch, (PadAxis_Centered_Word >> 16) & 0xFFFF),
+		load_upper_i(scratch, (PadAxis_Centered >> 16) & 0xFFFF),
-    or_i_self(   r_scratch,  PadAxis_Centered_Word        & 0xFFFF),
+    or_i_self(   scratch,  PadAxis_Centered        & 0xFFFF),
-    store_word(  r_scratch, r_state, O_(PadState,axes)),
+		// mac_load_word_imm(scratch, PadAxis_Centered),
+    store_word(       scratch, state, O_(PadState,axes)),
 })
 
-FI_ Slice_MipsCode ac_pad_set_id_byte(AtomBuilder_R ab, U1 r_state, U1 r_id, U1 id_value) atom_dbg_skip MipsAtomComp_Proc_(ac_pad_set_id_byte, ab, {
+FI_ Slice_MipsCode ac_pad_set_id_byte(AtomBuilder_R ab, Reg state, Reg r_id, U1 id_value) atom_dbg_skip MipsAtomComp_Proc_(ab, {
     add_ui(    r_id, R_0, id_value),
-    store_byte(r_id, r_state, O_(PadState,id)),
+    store_byte(r_id, state, O_(PadState,id)),
 })
 
-FI_ Slice_MipsCode ac_pad_set_status(AtomBuilder_R ab, U4 r_tmp, U1 r_state, U4 pad_status) atom_dbg_skip MipsAtomComp_Proc_(ac_pad_set_status, ab, {
+FI_ Slice_MipsCode ac_pad_set_status(AtomBuilder_R ab, U4 r_tmp, U1 r_state, U4 pad_status) atom_dbg_skip MipsAtomComp_Proc_(ab, {
     add_ui(    r_tmp, R_0, pad_status),
     store_word(r_tmp, r_state, O_(PadState,status)),
 })
@@ -30,9 +31,9 @@ FI_ Slice_MipsCode ac_pad_set_status(AtomBuilder_R ab, U4 r_tmp, U1 r_state, U4
 /* Invert r_buttons (active-low → active-high) and store to PadState.buttons.
  * r_buttons must already be loaded (the caller is responsible for filling the load-delay slot of
  * the preceding load_half_u with an instruction that doesn't read r_buttons). */
-FI_ Slice_MipsCode ac_pad_store_inverted_buttons(AtomBuilder_R ab, U1 r_buttons, U1 r_pad_state) atom_dbg_skip MipsAtomComp_Proc_(ac_pad_store_inverted_buttons, ab, {
+FI_ Slice_MipsCode ac_pad_store_inverted_buttons(AtomBuilder_R ab, U1 r_buttons, U1 r_pad_state) atom_dbg_skip MipsAtomComp_Proc_(ab, {
     nor_u(       r_buttons, r_buttons, R_0),
-    store_half(  r_buttons, r_pad_state, O_(PadState,   buttons)),
+    store_half(  r_buttons, r_pad_state, O_(PadState,buttons)),
 })
 
 #pragma endregion MACs (Mips Atom Components)
@@ -54,12 +55,12 @@ FI_ Slice_MipsCode ac_pad_store_inverted_buttons(AtomBuilder_R ab, U1 r_buttons,
  *   byte_swap16(x) = (x >> 8) | (x << 8); nor(x, R_0) = ~x. store_half truncates to 16 bits so the upper-16 mask is implicit in the store.
  *
  * Register use (atom-local; no wave-context touched):
- *   R_T0 = raw base      (kept throughout; axes loads read raw[4..7] from R_T0)
+ *   R_T0 = raw base      : Kept throughout; axes loads read raw[4..7] from R_T0.
- *   R_T1 = state base    (kept throughout; all stores go through R_T1)
+ *   R_T1 = state base    : Kept throughout; all stores go through R_T1.
- *   R_T2 = raw[0] status (alive across the disc/pending/id dispatch, then dead)
+ *   R_T2 = raw[0] status : Alive across the disc/pending/id dispatch, then dead.
- *   R_T3 = raw[1] id     (alive across the id dispatch, then dead)
+ *   R_T3 = raw[1] id     : Alive across the id dispatch, then dead.
- *   R_T4 = scratch       (shifts, compares, immediate loads, store values)
+ *   R_T4 = scratch       : Shifts, compares, immediate loads, store values.
- *   R_T5 = scratch       (parallel lui+ori for the 0x80808080 axes constant + byte-swap target)
+ *   R_T5 = scratch       : Parallel lui + ori for the 0x80808080 axes constant + byte-swap target.
  */
 enum {
 	R_PadRaw    = R_T0 atom_reg atom_type(U1),
@@ -124,7 +125,8 @@ atom_label(id_dispatch) /* === Case 3-6: ID dispatch */
 	 * R_T5 is then "dead" — only consumed at the analog_pad range check downstream. */
 	mac_pad_set_status(R_T4, R_PadState, PadStatus_Digital),
 	load_half_u(       R_T4, R_PadRaw, O_(PadBiosRaw, buttons)), /* R_T4 = raw_buttons; */
-	load_upper_i(R_T5, PadAxis_Centered_Hi), or_i_self(R_T5, PadAxis_Centered_Lo), /* fills the buttons-load's delay slot (doesn't read R_T4) */
+	mac_load_word_imm(R_T5, PadAxis_Centered), /* fills the buttons-load's delay slot (doesn't read R_T4) */
+	// load_upper_i(R_T5, PadAxis_Centered_Hi), or_i_self(R_T5, PadAxis_Centered_Lo), 
 	mac_pad_store_inverted_buttons(R_T4, R_PadState),            /* R_T4 settled: nor + sh writes ~raw_buttons to state.buttons */
 	store_word(R_T5,    R_PadState, O_(PadState, axes)),         /* single sw writes the 4-byte axes block at offset 8 (left_x, left_y, right_x, right_y) */
 	mac_pad_set_id_byte(R_PadState, R_T4, PadRawId_Digital),

code/duffle/pad.c

@@ -36,7 +36,7 @@ NI_ void pad_bios_init_start(PadBiosRaw* raw0, PadBiosRaw* raw1)
 	 *   $t2 = 0xB0 (BIOS B-table address) */
 	asm volatile(
 		asm_words(
-			or_u(    R_A2, R_A0, R_0),                 /* $a2 = $a1 = raw1 */
+			or_u(    R_A2, R_A1, R_0),                 /* $a2 = $a1 = raw1 */
 			add_ui(  R_A1, R_0, bios_pad_buffer_size), /* $a1 = 0x22 */
 			add_ui(  R_A3, R_0, bios_pad_buffer_size), /* $a3 = 0x22 */
 			add_ui(  R_T1, R_0, bios_init_pad_2),      /* $t1 = 0x12 */
@@ -64,8 +64,8 @@ NI_ void pad_bios_init_start(PadBiosRaw* raw0, PadBiosRaw* raw1)
 		asm_words(
 			add_ui(  R_T1, R_0, bios_start_pad_2), /* $t1 = 0x13 */
 			add_ui(  R_T2, R_0, bios_btable_addr), /* $t2 = 0xB0 (re-load) */
-			call_reg(R_T2),                             /* jalr $t2, $ra */
+			call_reg(R_T2),                        /* jalr $t2, $ra */
-			nop                                           /* BD slot */
+			nop                                    /* BD slot */
 		)
 		asm_clobber:
 			rlit(R_AT),

code/duffle/pad.h

@@ -81,9 +81,9 @@ typedef Enum_(U1, PadUnknownId) {
 	PadUnknownId_Sentinel      = 0xFF,
 };
 typedef Enum_(U4, PadAxisCentered) {
-	PadAxis_Centered_Hi   = 0x8080,
+	PadAxis_Centered_Hi = 0x8080,
-	PadAxis_Centered_Lo   = 0x8080,
+	PadAxis_Centered_Lo = 0x8080,
-	PadAxis_Centered_Word = 0x80808080U,
+	PadAxis_Centered    = 0x80808080U,
 };
 typedef Enum_(U1, PadDeadZone) {
 	PadDeadZone_LowBound  = 0x70,  /* left_x <  LowBound  → active;  delta = 0x80 - left_x > 0 (rightward pull) */

code/hello_camera/gen/offsets.h

@@ -8,7 +8,7 @@
 #pragma region hello_camera
 
 
-// --- atom: pad_input_cube_rotation (60 words) ---
+// --- atom: pad_input_cube_rotation (61 words) ---
 
 #define _atom_offset_dpad_left_exit_dpad_left         6
 #define _atom_offset_dpad_right_exit_dpad_right       6
@@ -44,7 +44,7 @@ enum {
     atom_offset_circle_z_exit_circle_z = _atom_offset_circle_z_exit_circle_z,
 };
 
-// --- atom: cube_g4_face (76 words) ---
+// --- atom: cube_g4_face (75 words) ---
 
 #define _atom_offset_cull_cube_g4_face_exit           41
 #define _atom_offset_bounds_chk_cube_g4_face_exit     24

code/hello_camera/hello_camera.atom.c

@@ -10,7 +10,7 @@
 #	include "duffle/pad.h"
 #	include "duffle/word_count.metadata.h"
 #	include "duffle/psyq.h"
-#	include "duffle/math.atom.c"
+#	include "duffle/math.atom.h"
 #	include "duffle/mips.atom.c"
 #	include "duffle/gte.atom.c"
 #	include "duffle/gp.atom.c"
@@ -26,7 +26,7 @@ ATOM_FILE_DEBUGGER_LINE_MARKER(hello_joypad_atom_c);
 #pragma region MACs (Mips Atom components)
 
 FI_ Slice_MipsCode ac_put_disp_env(AtomBuilder_R ab, U4 reg_transfer, U4 reg_base, U2 port)
-MipsAtomComp_Proc_(ac_put_disp_env, ab, {
+MipsAtomComp_Proc_(ab, {
 	// Emits 5 GP0 commands for buffer 0 (display_area = (0,0,320,240)).
 	// Sequence per libpsyx PutDispEnv: DrawArea TL → DrawArea BR → Mask → DrawArea TL → DrawArea BR
 	mac_gcmd_push(gp0_word_draw_area_top_left_origin,      reg_transfer, reg_base, port),
@@ -37,7 +37,7 @@ MipsAtomComp_Proc_(ac_put_disp_env, ab, {
 })
 
 I_ Slice_MipsCode ac_put_draw_env(AtomBuilder_R ab, U4 reg_transfer, U4 reg_base, U2 port)
-MipsAtomComp_Proc_(ac_put_draw_env, ab, {
+MipsAtomComp_Proc_(ab, {
 	/*
 	* ORIGIN: each code word corresponds to the EXACT value libpsyx's PutDrawEnv function would compute for the same DrawEnv settings.
 	* References:
@@ -94,34 +94,28 @@ MipsAtomComp_Proc_(ac_put_draw_env, ab, {
 #pragma region Atom Procs
 // Modular Atoms
 
-/* Scratchpad layout for the resolve_look_at bundle.
+#define AtomBundle_(name)              Struct_(tmpl(AtomBundle,name))
- * The chain atoms communicate entirely via the wave-context GPR carrier R_ResolveScratch (R_T4) + hardcoded offsets into smem.scratchpad
+#define AtomBundle_Len(name)           S_(tmpl(AtomBundle,name))/S_(MipsAtom*)
- * (PS1 hardware scratchpad at 0x1F800000).
+#define AtomBundleEntry_(bundle,entry) tmpl(bundle,entry)
- *
- * Atom 0 (input_and_sub) STAGES the C-side inputs (eye, up_in) into the scratchpad;
- * AT THE SAME TIME it computes fwd = target - eye and stores it at scratch+0.
- * Atoms 1-6 then read/write specific scratchpad offsets internally using
- * `r_scratch + hardcoded_offset` — no tape-data pointers are passed between atoms.
- *   +0   fwd   (atom 0 writes; atom  1 reads)
- *   +16  uz    (atom 1 writes; atoms 2 + 4 read)
- *   +32  right (atom 2 writes; atom  3 reads)
- *   +48  ux    (atom 3 writes; atoms 4 + 6 read)
- *   +64  up    (atom 4 writes; atom  5 reads)
- *   +80  uy    (atom 5 writes; atom  6 reads)
- *   +96  eye   (atom 0 stages from C-side pointer; atom 6 reads)
- *   +128 up_in (atom 0 stages from C-side pointer; atom 2 reads)
- */
 
-// enum {
+#pragma region resolve_look_at
-// 	R_LookAt    = R_T0 atom_reg atom_type(MT3_S2S4*),
+/* ─── resolve_look_at bundle chain atoms ──────────────────────────── */
-// 	R_CamEye    = R_T1 atom_reg atom_type(P3_S4*),
+
-// 	R_CamTarget = R_T2 atom_reg atom_type(P3_S4*),
+typedef AtomBundle_(resolve_look_at) { MipsAtom*
-// 	R_WorldUp   = R_T3 atom_reg atom_type(V3_S4*),
+	input_and_sub,
-// };
+	normalize_fwd_uz,
+	cross_uz_up_into_right,
+	normalize_right_ux,
+	cross_uz_ux_to_up,
+	normalize_up_uy,
+	populate,
+	set_gte_mt3s2s4,
+	matrix_vector,
+	trans_matrix;
+};
 
 enum {
-	/* Wave-context GPR carrier for the resolve_look_at bundle: the scratch base.
+	// TODO(Ed): We can resolve scratch at anytime its fixed to a specific address.
-	* Set by atom 0 (popped from tape), read by atoms 1-6 (used as pointer base). */
 	R_ResolveScratch = R_T4 atom_reg atom_type(U4*),
 #define R_ResolveScratch_Code R_T4_Code
 };
@@ -132,30 +126,7 @@ typedef Struct_(Binds_ResolveLookAt) {
 	V3_S4*    up_in;
 };
 
-/* ─── ResolveLookAtScratch — offset schema for the resolve_look_at bundle's
+/* ─── ResolveLookAtScratch — offset schema for the resolve_look_at bundle's */
- * scratchpad slots (PS1 hardware scratchpad at 0x1F800000).
- *
- * Each slot is 16 bytes: V3_S4 is already 16 bytes (4 × S4 = x/y/z/pad).
- * The struct fields are contiguous — slot i starts at offset i*16.
- * Used by the assembly via O_(ResolveLookAtScratch, fld.x/y/z) which resolves to a compile-time byte offset.
- * NOT a runtime struct — the struct is purely a schema for offsets; the assembly uses `r_scratch + O_(...)` to compute slot addresses at runtime.
- *
- * Slot producers/consumers (referenced by the resolve_look_at chain atoms):
- *   +0    fwd    0 writes (target - eye);     atom  1 (normalize) reads
- *   +16   uz     1 writes (normalize fwd);    atoms 2 + 4 read (cross operands)
- *   +32   right  2 writes (cross uz x up_in); atom  3 (normalize) reads
- *   +48   ux     3 writes (normalize right);  atoms 4 + 6 read
- *   +64   up     4 writes (cross uz x ux);    atom  5 (normalize) reads
- *   +80   uy     5 writes (normalize up);     atom  6 reads
- *   +96   eye    0 stages (C-side input);     atom  6 reads (translation column)
- *   +112  target reserved (currently written nowhere — kept for symmetry w/ eye)
- *   +128  up_in  0 stages (C-side input); atom 2 reads (cross operand)
- *
- * Fields use P3_S4 (point) for eye/target (RGA: affine point, implicit weight 1);
- * V3_S4 (vector) for fwd/uz/right/ux/up/uy/up_in (RGA: Euclidean vector).
- * P3_S4 is a storage alias of V3_S4 (see math.h comment: "Storage alias of V3_S4.
- * Use P3_S4 when the value is a point.") — both are 16 bytes.
- */
 typedef Struct_(ResolveLookAtScratch) {
 	V3_S4 fwd;       /* offset  +0  (16 bytes — 4 S4 fields incl. internal pad) */
 	V3_S4 uz;        /* offset +16 (16 bytes) */
@@ -168,32 +139,17 @@ typedef Struct_(ResolveLookAtScratch) {
 	V3_S4 up_in;     /* offset +128 (16 bytes) */
 };
 
-/* ─── resolve_look_at bundle chain atoms ────────────────────────────
- * 4 unique atom procs in the resolve_look_at bundle (4 chain atoms + 3 calls to generic normalize_v3s4_proc).
- * All 4 chain atoms are runtime-built MipsAtom_Proc_ atoms: each function declares a static MipsCode[] body, 
- * then calls atombuilder_unroll() to append it to the caller's MipsAtomBuilder arena. resolve_look_at_init() 
- * uses this pattern to pre-build the bundle into the static arena (smem.resolve_look_at_arena).
- *
- * Atom roster:
- *	0: resolve_look_at__input_and_sub              (chain atom)
- *	1: normalize_v3s4_proc (gte.atom.c)            (generic normalize; called for fwd→uz)
- *	2: resolve_look_at__cross_uz_up_in_to_right    (chain atom)
- *	3: normalize_v3s4_proc (gte.atom.c)            (generic normalize; called for right→ux)
- *	4: resolve_look_at__cross_uz_ux_to_up          (chain atom)
- *	5: normalize_v3s4_proc (gte.atom.c)            (generic normalize; called for up→uy)
- *	6: resolve_look_at__populate_and_translate     (chain atom)
- *
- * The generic normalize_v3s4_proc is a parameterized 4-stage GTE normalize (SQR → mfc2 → LZCS → GPF → srav);
- * it accepts scratch base + offset args so any caller (with a scratch base + struct schema) can use it.
- */
-
 typedef Struct_(Binds_ResolveLookAtSub) {
 	P3_S4* target;  /* U4 (C-side P3_S4* — read by atom 0 directly; NOT a scratchpad address) */
 	P3_S4* eye;     /* U4 (C-side P3_S4* — read by atom 0 directly; staged into scratchpad by atom 0) */
 	V3_S4* up_in;   /* U4 (C-side V3_S4* — read by atom 0 directly; staged into scratchpad by atom 0) */
 	ResolveLookAtScratch* scratchpad;
 };
-
+typedef Struct_(RegUse_resolve_look_at_input_and_sub) {
+	Reg scratch;
+	Reg target; Reg eye; Reg up_in;
+	Reg t0; Reg t1; Reg t2; Reg t3; Reg t4;
+};
 /* Atom 0 in the bundle: input_and_sub. Stages C-side inputs into the scratchpad and computes fwd = target - eye.
  * Staging work:
  *   * Stage eye.x/y/z   → scratch (for atom 6's translation column)
@@ -212,81 +168,63 @@ typedef Struct_(Binds_ResolveLookAtSub) {
  *   R_V0         : hardcoded (load eye.z / target.z)
  * Pool cost: 8 GPRs + R_T4 (carrier) + R_AT + R_V0 (hardcoded) = 11 GPRs.
  */
-internal MipsAtom* resolve_look_at__input_and_sub_proc(AtomArena_R aa,	
+// internal MipsAtom* resolve_look_at_input_and_sub(AtomArena_R aa, RegUse_resolve_look_at_input_and_sub r) 
-			// TODO(Ed): We can resolve scratch at anytime its fixed to a specific address.
+internal MipsAtom* AtomBundleEntry_(resolve_look_at,input_and_sub)(AtomArena_R aa, RegUse_resolve_look_at_input_and_sub r) 
-			U4 r_scratch
+atom_info(atom_bind(Binds_ResolveLookAtSub)) MipsAtom_Proc_(aa, {
-	,	U4 r_target_ptr,U4 r_eye_ptr, U4 r_up_in_ptr
+	load_word(r.target,  R_TapePtr, O_(Binds_ResolveLookAtSub,target)),
-	,	U4 r_tmp0,      U4 r_tmp1,    U4 r_tmp2, U4 r_tmp3
+	load_word(r.eye,     R_TapePtr, O_(Binds_ResolveLookAtSub,eye)),
-) MipsAtom_Proc_(resolve_look_at__input_and_sub, aa, {
+	load_word(r.up_in,   R_TapePtr, O_(Binds_ResolveLookAtSub,up_in)),
-	load_word(r_target_ptr, R_TapePtr, O_(Binds_ResolveLookAtSub,target)),
+	load_word(r.scratch, R_TapePtr, O_(Binds_ResolveLookAtSub,scratchpad)),
-	load_word(r_eye_ptr,    R_TapePtr, O_(Binds_ResolveLookAtSub,eye)),
+	LdSlot_ add_ui_self( R_TapePtr, S_(Binds_ResolveLookAtSub)),
-	load_word(r_up_in_ptr,  R_TapePtr, O_(Binds_ResolveLookAtSub,up_in)),
-	load_word(r_scratch,    R_TapePtr, O_(Binds_ResolveLookAtSub,scratchpad)),
-	add_ui_self(            R_TapePtr, S_(Binds_ResolveLookAtSub)),
-
-	// Stage eye.x/y/z into the scratchpad (atom 6 reads these for the translation column).
-	mac_load_p3s4( r_tmp0, r_tmp1, r_tmp2, r_eye_ptr, 0),
-	mac_store_p3s4(r_tmp0, r_tmp1, r_tmp2, r_scratch, O_(ResolveLookAtScratch,eye)),
 
 	/* Stage up_in.x/y/z into the scratchpad. */
-	mac_load_p3s4( r_tmp0, r_tmp1, r_tmp2, r_up_in_ptr, 0),
+	mac_load_word_v3( r.t0, r.t1, r.t2, r.up_in,   0), LdSlot_
-	mac_store_p3s4(r_tmp0, r_tmp1, r_tmp2, r_scratch, O_(ResolveLookAtScratch,up_in)),
+	mac_store_word_v3(r.t0, r.t1, r.t2, r.scratch, O_(ResolveLookAtScratch,up_in)),
+
+	// Stage eye.x/y/z into the scratchpad (atom 6 reads these for the translation column).
+	mac_load_word_v3( r.t0, r.t1, r.t2, r.eye,      0), LdSlot_
+	mac_store_word_v3(r.t0, r.t1, r.t2, r.scratch, O_(ResolveLookAtScratch,eye)),
 
 	/* Compute fwd = target - eye. */
-	mac_load_p3s4(r_tmp0, r_tmp1, r_tmp2, r_target_ptr, 0),
+	// mac_load_p3s4(t3, R_AT, t4, r.eye,    0),
-	mac_load_p3s4(r_tmp3, R_AT, R_V0, r_eye_ptr, 0),
+	mac_load_word_v3(r.t3, R_AT, r.t4, r.target, 0), LdSlot_ 
-	mac_sub_v3s4(
+	mac_sub_s_v3_self(
-		r_tmp0, r_tmp1, r_tmp2,
+		r.t3, R_AT, r.t4,
-		r_tmp3, R_AT,   R_V0),
+		r.t0, r.t1, r.t2),
-	mac_store_v3s4(r_tmp0, r_tmp1, r_tmp2, r_scratch, O_(ResolveLookAtScratch,fwd)),
+	mac_store_word_v3(r.t3, R_AT, r.t4, r.scratch, O_(ResolveLookAtScratch,fwd)),
 
 	mac_yield()
 })
 
-/* Atoms 2 + 4 in the bundle: out = a × b (GTE outer product on IR/D vectors).
+typedef Struct_(RegUse_resolve_look_at_cross_uz_up_into_right) {
- * No bind pop — the three operand pointers (a, b, out) are derived in-body from r_scratch + hardcoded_offset.
+	Reg scratch;
- * Each atom has its own variant because the offsets are baked into the body and each atom uses unique GPRs.
+	Reg a; Reg b; Reg c; /* load a.x/y/z; result out.x/y/z */
- *
+	Reg d; /* load b.x */
- * GTE register layout (per PSX-SPX + duffle gte.h):
+	Reg f; /* r_f = &right (out ptr), r_g = &uz, r_h = &up_in */
- *   IR1/2/3  = a.x/y/z    (mtc2)
+	
- *   VXY0     = b.x        (mtc2)
+	union { Reg t1, g, target0; };
- *   VZ0      = b.y        (mtc2)
+	union { Reg t2, h, target1; };
- *   VXY1     = b.z        (mtc2)
+	Reg t0;
- *   OP       = outer product
+};
- *   MAC1/2/3 = out.x/y/z  (mfc2)
- *
- * Pool cost: r_scratch (R_T4 carrier) + 7 body GPRs + R_AT + R_V0 (hardcoded) = 10 GPRs.
- */
-
 /* Atom 2: cross uz × up_in → right. */
-internal MipsAtom* resolve_look_at__cross_uz_up_in_to_right_proc(AtomArena_R aa, U4 r_scratch
+// internal MipsAtom* AtomBundleEntry_(resolve_look_at, cross_uz_up_to_right)(AtomArena_R aa, 
-	,	U4 r_a, U4 r_b, U4 r_c /* load a.x/y/z; result out.x/y/z */
+internal MipsAtom* resolve_look_at_cross_uz_up_into_right(AtomArena_R aa, 
-	,	U4 r_d                 /* load b.x */
+	RegUse_resolve_look_at_cross_uz_up_into_right r
-	,	U4 r_f, U4 r_g, U4 r_h /* r_f = &right (out ptr), r_g = &uz, r_h = &up_in */
+) MipsAtom_Proc_(aa, {
-) MipsAtom_Proc_(resolve_look_at__cross_uz_up_in_to_right, aa, {
 	/* FIX: build packed RT22+RT33 with proper sign extension. */
-	add_si(r_g, r_scratch, O_(ResolveLookAtScratch,uz)),    /* r_g = &uz */
+	add_si(r.g, r.scratch, O_(ResolveLookAtScratch,uz)),    /* r_g = &uz */
-	add_si(r_h, r_scratch, O_(ResolveLookAtScratch,up_in)), /* r_h = &up_in */
+	add_si(r.h, r.scratch, O_(ResolveLookAtScratch,up_in)), /* r_h = &up_in */
-	add_si(r_f, r_scratch, O_(ResolveLookAtScratch,right)), /* r_f = &right (out) */
+	add_si(r.f, r.scratch, O_(ResolveLookAtScratch,right)), /* r_f = &right (out) */
 	nop,
 
 	/* Load a (uz).x/y/z into r_a/r_b/r_c. */
-	load_word(r_a, r_g, O_(V3_S4,x)),
+	mac_load_word_v3(r.a, r.b, r.c, r.g, 0),   LdSlot_
-	load_word(r_b, r_g, O_(V3_S4,y)),
-	load_word(r_c, r_g, O_(V3_S4,z)),
-	nop,
-
 	/* Load b (up_in).x/y/z into r_d + R_AT/R_V0 (R_AT/R_V0 are hardcoded scratch). */
-	load_word(r_d,  r_h, O_(V3_S4,x)),
+	mac_load_word_v3(r.d, R_AT, r.t0, r.h, 0), LdSlot_ // (taken by gte_mv_from_ctrl_r)
-	load_word(R_AT, r_h, O_(V3_S4,y)),
-	load_word(R_V0, r_h, O_(V3_S4,z)),
-	nop,
-
-	/* Save the two RT control-register slots OP will clobber. We reuse
-	 * r_g/r_h (scratch pointers, no longer needed) as the save targets. */
-	gte_mv_from_ctrl_r(r_g, gte_cr_RT11),    /* r_g = C2 r0 (RT11|RT12) */
-	gte_mv_from_ctrl_r(r_h, gte_cr_RT22),    /* r_h = C2 r4 (RT22|RT33) */
 
+	/* Save the two RT control-register slots OP will clobber. We reuse r_g/r_h (scratch pointers, no longer needed) as the save targets. */
+	gte_mv_from_ctrl_r(r.target0, gte_cr_RT11),    /* r_g = C2 r0 (RT11|RT12) */
+	gte_mv_from_ctrl_r(r.target1, gte_cr_RT22),    /* r_h = C2 r4 (RT22|RT33) */
 	/* Load uz.x/uz.y/uz.z into COP2 control registers.
 	 * OP reads D1 = RT11 from $0.low, D2 = RT22 from $2.high, D3 = RT33 from $4.high.
 	 * RT22 is in BOTH $2.high AND $4.low (shared bit position). OP reads from $2.high.
@@ -295,121 +233,101 @@ internal MipsAtom* resolve_look_at__cross_uz_up_in_to_right_proc(AtomArena_R aa,
 	 * The $2 and $4 writes don't clobber each other (separate registers).
 	 * The 2nd ctc2 DOES clobber $4.low (becomes a.z.low, NOT a.y.high), but since OP
 	 * reads RT22 from $2.high (which the 2nd ctc2 doesn't touch), D2 is still a.y.high.
-	 * This is libpsyx's OuterProduct12 convention EXACTLY. */
+	 * This is libpsyx's OuterProduct12 convention. */
-	gte_mv_to_ctrl_r(r_b, gte_cr_RT13),    /* $2 = r_b = a.y. RT13=a.y.low, RT22=a.y.high. */
+	gte_mv_to_ctrl_r(r.b, gte_cr_RT13),    /* $2 = r_b = a.y. RT13=a.y.low, RT22=a.y.high. */
-	gte_mv_to_ctrl_r(r_c, gte_cr_RT22),    /* $4 = r_c = a.z. RT22=a.z.low, RT33=a.z.high. */
+	gte_mv_to_ctrl_r(r.c, gte_cr_RT22),    /* $4 = r_c = a.z. RT22=a.z.low, RT33=a.z.high. */
 
 	/* Load uz into the RT diagonal. */
-	gte_mv_to_ctrl_r(r_a, gte_cr_RT11),   /* D1 = RT11 = uz.x (low 16 of $0, sign-extended by OP). */
+	gte_mv_to_ctrl_r(r.a, gte_cr_RT11),   /* D1 = RT11 = uz.x (low 16 of $0, sign-extended by OP). */
-	nop2,                                 /* CTC2 retirement (CPU→COP2 2-slot delay) */
+	GteDelay_ nop2,                         /* CTC2 retirement (CPU→COP2 2-slot delay) */
 
 	/* Load up_in into IR (the second operand for OP). */
-	gte_mv_to_data_r(r_d,  C2_IR1),       /* IR1 = up_in.x */
+	gte_mv_to_data_r(r.d,  C2_IR1),       /* IR1 = up_in.x */
 	gte_mv_to_data_r(R_AT, C2_IR2),       /* IR2 = up_in.y */
-	gte_mv_to_data_r(R_V0, C2_IR3),       /* IR3 = up_in.z */
+	gte_mv_to_data_r(r.t0, C2_IR3),       /* IR3 = up_in.z */
-	nop2,                                 /* MTC2 retirement (CPU→COP2 2-slot delay) */
+	GteDelay_ nop2,                         /* MTC2 retirement (CPU→COP2 2-slot delay) */
 
-	gte_cmdw_outer_product, /* OP: MAC1/2/3 = uz × up_in
+	gte_cmdw_cross, /* OP: MAC1/2/3 = uz × up_in
 		*   MAC1 = IR3*D2 - IR2*D3 = up_in.z*uz.y.high - up_in.y*uz.z.high
 		*   MAC2 = IR1*D3 - IR3*D1 = up_in.x*uz.z.high - up_in.z*uz.x
-		*   MAC3 = IR2*D1 - IR1*D2 = up_in.y*uz.x - up_in.x*uz.y.high
+		*   MAC3 = IR2*D1 - IR1*D2 = up_in.y*uz.x      - up_in.x*uz.y.high
 		* For up_in = (0, -fp_one, 0):
 		*   MAC1 = 0 - (-fp_one)*uz.z.high = fp_one*uz.z.high
 		*   MAC2 = 0 - 0 = 0
 		*   MAC3 = (-fp_one)*uz.x - 0 = -fp_one*uz.x */
 
 	/* Restore the RT slots we clobbered. */
-	gte_mv_to_ctrl_r(r_g, gte_cr_RT11),   /* restore C2 r0 (RT11|RT12) */
+	gte_mv_to_ctrl_r(r.target0, gte_cr_RT11),   /* restore C2 r0 (RT11|RT12) */
-	gte_mv_to_ctrl_r(r_h, gte_cr_RT22),   /* restore C2 r4 (RT22|RT33) */
+	gte_mv_to_ctrl_r(r.target1, gte_cr_RT22),   /* restore C2 r4 (RT22|RT33) */
 
 	/* mfc2 MAC1/2/3 → r_a/r_b/r_c (out.x/y/z). */
-	gte_mv_from_data_r(r_a, C2_MAC1),
+	mac_gte_mv_from_data_r_mac123(r.a, r.b, r.c),
-	gte_mv_from_data_r(r_b, C2_MAC2),
+	GteDelay_ nop,  /* MFC2 retirement */
-	gte_mv_from_data_r(r_c, C2_MAC3),
-	nop,  /* MFC2 retirement */
 
 	/* Right-shift MAC by 12 to convert from GTE's S12.20 fixed-point scale back to libpsyx OuterProduct12 convention (S12.0, fp_one=4096=1<<12).
 	 * Without this, MAC values (~16M for unit-vector cross products) overflow the GTE's 16-bit IR registers when atom 3 normalizes via mtc2. */
-	shift_aright(r_a, r_a, 12),
+	mac_shift_aright_v3_self(r.a, r.b, r.c, 12),
-	shift_aright(r_b, r_b, 12),
-	shift_aright(r_c, r_c, 12),
-
 	/* Store out.x/y/z to r_f (out ptr = scratch+32). */
-	store_word(r_a, r_f, O_(V3_S4,x)),
+	mac_store_word_v3(r.a, r.b, r.c, r.f, 0),
-	store_word(r_b, r_f, O_(V3_S4,y)),
-	store_word(r_c, r_f, O_(V3_S4,z)),
 
 	mac_yield()
 })
 
+typedef Struct_(RegUse_resolve_look_at__cross_uz_ux_to_up_proc) {
+	Reg const   scratch;          /* pinned T4 */
+	Reg_(V3_S4) a;                /* uz components, then MAC / out */
+	Reg_(V3_S4) b;                /* ux components */
+	union { Reg t0, up; };        /* &up, dedicated */
+	union { Reg t1, uz, rt11; };  /* &uz, then RT11 save */
+	union { Reg t2, ux, rt22; };  /* &ux, then RT22 save */
+};
 /* Atom 4: cross uz × ux → up. */
-internal MipsAtom* resolve_look_at__cross_uz_ux_to_up_proc(AtomArena_R aa,	U4 r_scratch
+internal MipsAtom* resolve_look_at__cross_uz_ux_to_up_proc(AtomArena_R aa,
-	,	U4 r_a, U4 r_b, U4 r_c /* load a.x/y/z; result out.x/y/z */
+	RegUse_resolve_look_at__cross_uz_ux_to_up_proc r
-	,	U4 r_d                 /* load b.x */
+) MipsAtom_Proc_(aa, {
-	,	U4 r_f, U4 r_g, U4 r_h /* r_f = &up (out ptr), r_g = &uz, r_h = &ux */
+	add_si(r.uz, r.scratch, O_(ResolveLookAtScratch,uz)), /* r.uz = &uz */
-) MipsAtom_Proc_(resolve_look_at__cross_uz_ux_to_up, aa, {
+	add_si(r.ux, r.scratch, O_(ResolveLookAtScratch,ux)), /* r.ux = &ux */
-	/* Compute the three scratch pointers from r_scratch. */
+	add_si(r.up, r.scratch, O_(ResolveLookAtScratch,up)), /* r.up = &up (out) */
-	add_si(r_g, r_scratch, O_(ResolveLookAtScratch,uz)), /* r_g = &uz */
-	add_si(r_h, r_scratch, O_(ResolveLookAtScratch,ux)), /* r_h = &ux */
-	add_si(r_f, r_scratch, O_(ResolveLookAtScratch,up)), /* r_f = &up (out) */
-	nop,
 
-	/* Load a (uz).x/y/z into r_a/r_b/r_c. */
+	mac_load_v3s4(r.a, r.uz, 0), LdSlot_
-	load_word(r_a, r_g, O_(V3_S4,x)),
+	mac_load_v3s4(r.b, r.ux, 0), LdSlot_ /* taken by gte_mv_from_ctrl_r */
-	load_word(r_b, r_g, O_(V3_S4,y)),
-	load_word(r_c, r_g, O_(V3_S4,z)),
-	nop,
-
-	/* Load b (ux).x/y/z into r_d + R_AT/R_V0. */
-	load_word(r_d,  r_h, O_(V3_S4,x)),
-	load_word(R_AT, r_h, O_(V3_S4,y)),
-	load_word(R_V0, r_h, O_(V3_S4,z)),
-	nop,
 
 	/* OP reads D1/D2/D3 from RT11/RT22/RT33 ($0/$2/$4), not V0/V1/V2.
-	 * Mirror atom 1: cfc2 RT save, ctc2 RT diagonal from uz, mtc2 IR from ux,
+	 * Mirror atom 1: cfc2 RT save, ctc2 RT diagonal from uz, mtc2 IR from ux, ctc2 RT restore. */
-	 * ctc2 RT restore. */
 
-	/* Save the two RT control-register slots OP will clobber (reusing
+	/* Save the two RT control-register slots OP will clobber (reusing r.uz/r.ux — they're no longer needed as scratch pointers). */
-	 * r_g/r_h — they're no longer needed as scratch pointers). */
+	gte_mv_from_ctrl_r(r.rt11, gte_cr_RT11),    /* r.rt11 = C2 $0 (RT11|RT12) */
-	gte_mv_from_ctrl_r(r_g, gte_cr_RT11),    /* r_g = C2 $0 (RT11|RT12) */
+	gte_mv_from_ctrl_r(r.rt22, gte_cr_RT22),    /* r.rt22 = C2 $4 (RT22|RT33) */
-	gte_mv_from_ctrl_r(r_h, gte_cr_RT22),    /* r_h = C2 $4 (RT22|RT33) */
 
 	/* Load uz into the RT diagonal — same packing as atom 1.
 	 * OP reads D1 = RT11 from $0.low, D2 = RT22 from $2.high, D3 = RT33 from $4.high.
 	 * RT22 is shared between $2.high and $4.low — the ctc2 sequence to $2 then $4
-	 * sets RT22 to uz.y.high (via $2), then to uz.z.low (via $4). OP reads
+	 * sets RT22 to uz.y.high (via $2), then to uz.z.low (via $4). 
-	 * RT22 from $2.high which the second ctc2 doesn't touch, so D2 stays uz.y.high.
+	 * OP reads RT22 from $2.high which the second ctc2 doesn't touch, so D2 stays uz.y.high. */
-	 * (This is libpsyx OuterProduct12 convention EXACTLY.) */
+	gte_mv_to_ctrl_r(r.a.y, gte_cr_RT13),   /* $2 = uz.y. RT13=uz.y.low, RT22=uz.y.high. */
-	gte_mv_to_ctrl_r(r_b, gte_cr_RT13),    /* $2 = uz.y. RT13=uz.y.low, RT22=uz.y.high. */
+	gte_mv_to_ctrl_r(r.a.z, gte_cr_RT22),   /* $4 = uz.z. RT22=uz.z.low, RT33=uz.z.high. */
-	gte_mv_to_ctrl_r(r_c, gte_cr_RT22),    /* $4 = uz.z. RT22=uz.z.low, RT33=uz.z.high. */
+	gte_mv_to_ctrl_r(r.a.x, gte_cr_RT11),   /* $0 = uz.x. RT11=uz.x. */
-	gte_mv_to_ctrl_r(r_a, gte_cr_RT11),   /* $0 = uz.x. RT11=uz.x. */
+	GteDelay_ nop2,                         /* CTC2 retirement (CPU→COP2 2-slot delay) */
-	nop2,                                 /* CTC2 retirement (CPU→COP2 2-slot delay) */
 
 	/* Load ux into the IR registers (the second operand for OP). */
-	gte_mv_to_data_r(r_d,  C2_IR1),       /* IR1 = ux.x */
+	gte_mv_to_data_r(r.b.x, C2_IR1),       /* IR1 = ux.x */
-	gte_mv_to_data_r(R_AT, C2_IR2),       /* IR2 = ux.y */
+	gte_mv_to_data_r(r.b.y, C2_IR2),       /* IR2 = ux.y */
-	gte_mv_to_data_r(R_V0, C2_IR3),       /* IR3 = ux.z */
+	gte_mv_to_data_r(r.b.z, C2_IR3),       /* IR3 = ux.z */
-	nop2,                                 /* MTC2 retirement (CPU→COP2 2-slot delay) */
+	GteDelay_ nop2,                        /* MTC2 retirement (CPU→COP2 2-slot delay) */
 
-	gte_cmdw_outer_product,
+	gte_cmdw_cross,
 
 	/* Restore the RT slots we clobbered. */
-	gte_mv_to_ctrl_r(r_g, gte_cr_RT11),   /* restore C2 $0 (RT11|RT12) */
+	gte_mv_to_ctrl_r(r.rt11, gte_cr_RT11),   /* restore C2 $0 (RT11|RT12) */
-	gte_mv_to_ctrl_r(r_h, gte_cr_RT22),   /* restore C2 $4 (RT22|RT33) */
+	gte_mv_to_ctrl_r(r.rt22, gte_cr_RT22),   /* restore C2 $4 (RT22|RT33) */
+
+	mac_gte_mv_from_data_r_mac123(r.a.x, r.a.y, r.a.z),
+	GteDelay_ nop,
 
-	gte_mv_from_data_r(r_a, C2_MAC1),
-	gte_mv_from_data_r(r_b, C2_MAC2),
-	gte_mv_from_data_r(r_c, C2_MAC3),
-	nop,
 	/* Right-shift MAC by 12 to convert from GTE's S12.20 scale back to libpsyx
 	 * OuterProduct12 convention (S12.0, fp_one=4096). See atom 1 for rationale. */
-	shift_aright(r_a, r_a, 12),
+	mac_shift_aright_v3_self(r.a.x, r.a.y, r.a.z, 12),
-	shift_aright(r_b, r_b, 12),
+	mac_store_v3s4(r.a, r.up, 0),
-	shift_aright(r_c, r_c, 12),
-	store_word(r_a, r_f, O_(V3_S4,x)),
-	store_word(r_b, r_f, O_(V3_S4,y)),
-	store_word(r_c, r_f, O_(V3_S4,z)),
 
 	mac_yield()
 })
@@ -417,165 +335,81 @@ internal MipsAtom* resolve_look_at__cross_uz_ux_to_up_proc(AtomArena_R aa,	U4 r_
 typedef Struct_(Binds_ResolveLookAtPopAndTrans) {
 	U4 look_at;  /* U4 (MT3_S2S4* — destination matrix address) */
 };
-/* Atom 6 in the bundle: write look_at->m[][] from ux/uy/uz, then compute the translation column t[] = R * (-eye).
+typedef Struct_(RegUse_resolve_look_at__populate_proc) {
- *
+	Reg const   scratch;
- * GPR codes (assigned by resolve_look_at_init):
+	Reg         look_at;
- *   r_look_at   : MT3_S2S4* (popped from tape; output matrix destination)
+	Reg_(V3_S4) row;              /* one matrix row, reused */
- *   r_pux       : pointer to ux   (offset O_(ResolveLookAtScratch,ux))
+	Reg ux;
- *   r_puy       : pointer to uy   (offset O_(ResolveLookAtScratch,uy))
+	Reg uy;
- *   r_puz       : pointer to uz   (offset O_(ResolveLookAtScratch,uz))
+	Reg uz;
- *   r_peye      : pointer to eye  (offset O_(ResolveLookAtScratch,eye))
+};
- *   r_tmp0/1/2  : atom-local scratch (load + MVMVA + store temps)
+/* Atom 6a: write look_at->m[][] from ux/uy/uz as S2. Zero t[].
- *
+ * MT3_S2S4 { A3x3_S2 m; A3_S4 t; }
- * 4 pointer regs (r_pux/r_puy/r_puz/r_peye) are DEDICATED — they hold the scratch addresses for the entire body.
+ *   m[][] is S2 packed (9 × 2 = 18 bytes at offset 0)
- * They are computed in-body via `add_si(r_px, r_scratch, O_(ResolveLookAtScratch, field))` so no tape-data pointer is needed.
+ *   t[0/1/2] is S4     (3 × 4 = 12 bytes at offset 18)
- *
- * Struct layout (per duffle/math.h):
- *   MT3_S2S4 { A3x3_S2 m; A3_S4 t; }  →  m[][] is S2 packed (9 × 2 = 18 bytes at offset 0) 
- *                                        t[0/1/2] is S4     (3 × 4 = 12 bytes at offset 18)
- *
- * Translation column: GTE MVMVA with the world rotation matrix pre-set
- * (helper emits set_gte_world before the bundle, per the bundle design).
- * MVMVA computes R * pos (with cv=0/mx=0/sf=0/v=0); MAC1/2/3 = R * (-eye).
- * Pool cost: r_look_at (1) + r_scratch (R_T4 carrier) + 4 ptr regs + 3 tmp regs = 9 GPRs.
  */
-internal MipsAtom* resolve_look_at__populate_proc(AtomArena_R aa
+internal MipsAtom* resolve_look_at__populate_proc(AtomArena_R aa,
-	,	U4 r_look_at
+	RegUse_resolve_look_at__populate_proc r
-	,	U4 r_scratch
+) MipsAtom_Proc_(aa, {
-	,	U4 r_pux, U4 r_puy, U4 r_puz
+	load_word(r.look_at, R_TapePtr, O_(Binds_ResolveLookAtPopAndTrans,look_at)),
-	,	U4 r_tmp0, U4 r_tmp1, U4 r_tmp2
+	LdSlot_ add_ui_self( R_TapePtr, S_(Binds_ResolveLookAtPopAndTrans)),
-) MipsAtom_Proc_(resolve_look_at__populate, aa, {
-	/* Pop look_at* (the matrix output) — advance R_TapePtr by 4 bytes. */
-	load_word(r_look_at, R_TapePtr, O_(Binds_ResolveLookAtPopAndTrans,look_at)),
-	add_ui_self(         R_TapePtr, S_(Binds_ResolveLookAtPopAndTrans)),
 
-	/* Compute the 3 scratch pointers in their dedicated GPRs (eye isn't needed by 6a — 6b reads it). */
+	add_si(r.ux, r.scratch, O_(ResolveLookAtScratch,ux)), /* r.ux = &ux */ LdSlot_
-	add_si(r_pux, r_scratch, O_(ResolveLookAtScratch,ux)),  /* r_pux = &ux */
+	add_si(r.uy, r.scratch, O_(ResolveLookAtScratch,uy)), /* r.uy = &uy */ LdSlot_
-	add_si(r_puy, r_scratch, O_(ResolveLookAtScratch,uy)),  /* r_puy = &uy */
+	add_si(r.uz, r.scratch, O_(ResolveLookAtScratch,uz)), /* r.uz = &uz */ LdSlot_
-	add_si(r_puz, r_scratch, O_(ResolveLookAtScratch,uz)),  /* r_puz = &uz */
-	nop,
 
-	/* ── m[0] = (S2)ux ── */
+	mac_load_v3s4(r.row, r.ux, 0), LdSlot_ mac_store_v3s2(r.row, r.look_at, O_(MT3_S2S4,m[0])),
-	load_word(r_tmp0, r_pux, O_(V3_S4,x)),
+	mac_load_v3s4(r.row, r.uy, 0), LdSlot_ mac_store_v3s2(r.row, r.look_at, O_(MT3_S2S4,m[1])),
-	load_word(r_tmp1, r_pux, O_(V3_S4,y)),
+	mac_load_v3s4(r.row, r.uz, 0), LdSlot_ mac_store_v3s2(r.row, r.look_at, O_(MT3_S2S4,m[2])),
-	load_word(r_tmp2, r_pux, O_(V3_S4,z)),
-	nop,
-	store_half(r_tmp0, r_look_at, O_(MT3_S2S4,m[0][0])),
-	store_half(r_tmp1, r_look_at, O_(MT3_S2S4,m[0][1])),
-	store_half(r_tmp2, r_look_at, O_(MT3_S2S4,m[0][2])),
-
-	/* ── m[1] = (S2)uy ── */
-	load_word(r_tmp0, r_puy, O_(V3_S4,x)),
-	load_word(r_tmp1, r_puy, O_(V3_S4,y)),
-	load_word(r_tmp2, r_puy, O_(V3_S4,z)),
-	nop,
-	store_half(r_tmp0, r_look_at, O_(MT3_S2S4,m[1][0])),
-	store_half(r_tmp1, r_look_at, O_(MT3_S2S4,m[1][1])),
-	store_half(r_tmp2, r_look_at, O_(MT3_S2S4,m[1][2])),
-
-	/* ── m[2] = (S2)uz ── */
-	load_word(r_tmp0, r_puz, O_(V3_S4,x)),
-	load_word(r_tmp1, r_puz, O_(V3_S4,y)),
-	load_word(r_tmp2, r_puz, O_(V3_S4,z)),
-	nop,
-	store_half(r_tmp0, r_look_at, O_(MT3_S2S4,m[2][0])),
-	store_half(r_tmp1, r_look_at, O_(MT3_S2S4,m[2][1])),
-	store_half(r_tmp2, r_look_at, O_(MT3_S2S4,m[2][2])),
 
 	/* Zero t[0..2] — atom 6c writes the final values here. */
-	store_word(R_0, r_look_at, O_(MT3_S2S4,t[0])),
+	mac_store_v3s4(v3s4_R_0(), r.look_at, O_(MT3_S2S4,t)),
-	store_word(R_0, r_look_at, O_(MT3_S2S4,t[1])),
-	store_word(R_0, r_look_at, O_(MT3_S2S4,t[2])),
-
 	mac_yield()
 })
 
-/* Atom 6b in the bundle: matrix-vector product off = R * (-eye) >> 12.
+typedef Struct_(RegUse_resolve_look_at__matrix_vector_proc) {
- * Uses RTPS with V0 loaded from scratch via lwc2. The RT matrix is
+	Reg const   scratch;
- * pre-loaded by atom 6a.5 (resolve_look_at__load_rt).
+	Reg         look_at;
- * Stores off to scratch+96 (overwriting the packed pos).
+	Reg         eye;              /* &scratch.eye; store dest for off */
+	Reg_(V3_S4) v;                /* RT words, then -eye, then off */
+};
+/* Atom 6b: off = look_at.m * (-eye) >> 12. Stores off over scratch.eye.
  *
- * GPR codes (assigned by resolve_look_at_init):
+ * C11 ApplyMatrixLV:
- *   r_scratch : R_ResolveScratch (R_T4) — scratch base
+ *   1. ctc2 RT matrix (5 ctc2s to C2[0..4])
- *   r_peye    : pointer to eye (slot +96, reused as off destination)
+ *   2. lw v.x/y/z from memory
- *   r_tmp0/1/2: -eye + GTE transfer scratch
+ *   3. S15 decomposition (negu + sra 15 + negu + andi 0x7FFF + negu)
- *
+ *   4. mtc2 HIGH bits to IR1/2/3, nop, MVMVA pass1 (sf=0, mx=0, v=3, cv=3)
- * Pool cost: r_scratch (carrier) + 1 ptr reg + 3 tmp regs = 5 GPRs.
+ *   5. mfc2 MACs
+ *   6. mtc2 LOW bits to IR1/2/3, nop, MVMVA pass2 (sf=1, mx=0, v=3, cv=3)
+ *   7. mfc2 MACs
+ *   8. Combine: (pass1 << 3) + pass2
  */
-internal MipsAtom* resolve_look_at__matrix_vector_proc(AtomArena_R aa
+internal MipsAtom* resolve_look_at__matrix_vector_proc(AtomArena_R aa,
-	,	U4 r_scratch
+	RegUse_resolve_look_at__matrix_vector_proc r
-	,	U4 r_peye
+) MipsAtom_Proc_(aa, {
-	,	U4 r_look_at
+	load_word(r.look_at, R_TapePtr, O_(Binds_ResolveLookAtPopAndTrans,look_at)),
-	,	U4 r_tmp0, U4 r_tmp1, U4 r_tmp2
+	LdSlot_ add_ui_self( R_TapePtr, S_(Binds_ResolveLookAtPopAndTrans)),
-) MipsAtom_Proc_(resolve_look_at__matrix_vector, aa, {
-	/* === EXACT C11 ApplyMatrixLV replication ===
-	 * The C11 does:
-	 *   1. ctc2 RT matrix (5 ctc2s to C2[0..4])
-	 *   2. lw v.x/y/z from memory
-	 *   3. S15 decomposition (negu + sra 15 + negu + andi 0x7FFF + negu)
-	 *   4. mtc2 HIGH bits to IR1/2/3, nop, MVMVA pass1 (sf=0, mx=0, v=3, cv=3)
-	 *   5. mfc2 MACs
-	 *   6. mtc2 LOW bits to IR1/2/3, nop, MVMVA pass2 (sf=1, mx=0, v=3, cv=3)
-	 *   7. mfc2 MACs
-	 *   8. Combine: (pass1 << 3) + pass2
-	 *
-	 * For S16-fitting pos (|pos| < 32768), pos >> 15 = 0, so pass1 = 0.
-	 * The combine simplifies: result = 0 + pass2 = pass2.
-	 * So we skip the S15 decomposition and just do pass 2 directly.
-	 * We still use v=3 (IR input) and mx=0 (RT matrix) like the C11. */
 
-	/* Pop look_at* from tape. */
+	/* Load RT from look_at.m into C2[0..4]. Packed S2 pairs, same as set_gte_mt3s2s4. */
-	load_word(r_look_at, R_TapePtr, O_(Binds_ResolveLookAtPopAndTrans,look_at)),
+	load_word(  r.v.x, r.look_at, O_(MT3_S2S4, m[0][0])), /* RT11|RT12 */ LdSlot_ add_si(r.eye, r.scratch, O_(ResolveLookAtScratch,eye)), /* r.eye = &eye */
-	add_ui_self(         R_TapePtr, S_(Binds_ResolveLookAtPopAndTrans)),
+	load_word(  r.v.y, r.look_at, O_(MT3_S2S4, m[0][2])), /* RT13|RT21 */ LdSlot_ gte_mv_to_ctrl_r(r.v.x, gte_cr_RT11),
+	load_word(  r.v.z, r.look_at, O_(MT3_S2S4, m[1][1])), /* RT22|RT23 */ LdSlot_ gte_mv_to_ctrl_r(r.v.y, gte_cr_RT12),
+	load_word(  r.v.x, r.look_at, O_(MT3_S2S4, m[2][0])), /* RT31|RT32 */ LdSlot_ gte_mv_to_ctrl_r(r.v.z, gte_cr_RT13),
+	load_half_u(r.v.y, r.look_at, O_(MT3_S2S4, m[2][2])), /* RT33 */      LdSlot_ gte_mv_to_ctrl_r(r.v.x, gte_cr_RT21),
+	/* pos = -eye. The three loads also retire the last CTC2. */                  gte_mv_to_ctrl_r(r.v.y, gte_cr_RT22),
+	GteDelay_ mac_load_p3s4(r.v, r.eye, 0), LdSlot_ mac_sub_v3s4(r.v, v3s4_R_0(), r.v),   /* pos.x = -eye.x */
+	/* mtc2 pos (as S16) to IR1/2/3. The GTE takes low 16 bits. pos fits in S16. For negative pos, the 32-bit sign-extended value's low 16 bits = correct S16. */
+	gte_mv_to_data_r(r.v.x, C2_IR1),
+	gte_mv_to_data_r(r.v.y, C2_IR2),
+	gte_mv_to_data_r(r.v.z, C2_IR3),
+	GteDelay_ nop2,
 
-	/* r_peye = &eye (slot +96, reused as off destination). */
+	/* MVMVA pass 2 — C11 ApplyMatrixLV command.
-	add_si(r_peye, r_scratch, O_(ResolveLookAtScratch,eye)),
-	nop,
-
-	/* === Load RT matrix from look_at into C2[0..4] via ctc2 ===
-	 * Exact s  ame sequence as set_gte_mt3s2s4 / C11's ApplyMatrixLV. */
-	load_word(  r_tmp0, r_look_at,  0), nop, gte_mv_to_ctrl_r(r_tmp0, gte_cr_RT11),
-	load_word(  r_tmp0, r_look_at,  4), nop, gte_mv_to_ctrl_r(r_tmp0, gte_cr_RT12),
-	load_word(  r_tmp0, r_look_at,  8), nop, gte_mv_to_ctrl_r(r_tmp0, gte_cr_RT13),
-	load_word(  r_tmp0, r_look_at, 12), nop, gte_mv_to_ctrl_r(r_tmp0, gte_cr_RT21),
-	load_half_u(r_tmp0, r_look_at, 16), nop, gte_mv_to_ctrl_r(r_tmp0, gte_cr_RT22),
-	nop2,  /* CTC2 retirement (2 slots × 5 ctc2s) */
-
-	/* Load pos = -eye after the matrix load releases r_tmp0. */
-	load_word(r_tmp0, r_peye, O_(P3_S4,x)),
-	load_word(r_tmp1, r_peye, O_(P3_S4,y)),
-	load_word(r_tmp2, r_peye, O_(P3_S4,z)),
-	nop,
-	sub_u(r_tmp0, R_0, r_tmp0),  /* pos.x = -eye.x */
-	sub_u(r_tmp1, R_0, r_tmp1),
-	sub_u(r_tmp2, R_0, r_tmp2),
-
-	/* === mtc2 pos (as S16) to IR1/2/3 ===
-	 * The GTE takes low 16 bits. pos fits in S16. For negative pos, the
-	 * 32-bit sign-extended value's low 16 bits = correct S16. */
-	/* Mask pos to 16 bits to be safe. For S16-fitting pos, pos & 0xFFFF
-	 * gives the correct S16 value (sign bit preserved). */
-	/* r_tmp0/1/2 already have pos values. */
-	gte_mv_to_data_r(r_tmp0, C2_IR1),
-	gte_mv_to_data_r(r_tmp1, C2_IR2),
-	gte_mv_to_data_r(r_tmp2, C2_IR3),
-	nop2,  /* MTC2 retirement (2 slots) */
-
-	/* === MVMVA pass 2 EXACT C11 command: 0x4A49E012 ===
 	 * sf=1, mx=0 (RT), v=3 (IR), cv=3. Reads RT × IR >> 12. */
-	gte_cmdw_mvmva_c11_pass2_exact,
+	gte_cmdw_mvmva_c11_pass2,                           GteDelay_ nop,
-	nop,  /* GTE interlock */
+	mac_gte_mv_from_data_r_mac123(r.v.x, r.v.y, r.v.z), GteDelay_ nop,
-
+	mac_store_v3s4(r.v, r.eye, 0),
-	/* === mfc2 MAC1/2/3 → r_tmp0/1/2 === */
-	gte_mv_from_data_r(r_tmp0, C2_MAC1),
-	gte_mv_from_data_r(r_tmp1, C2_MAC2),
-	gte_mv_from_data_r(r_tmp2, C2_MAC3),
-	nop,
-
-	/* === Store off → scratch+96 (overwriting pos) === */
-	store_word(r_tmp0, r_peye, O_(V3_S4,x)),
-	store_word(r_tmp1, r_peye, O_(V3_S4,y)),
-	store_word(r_tmp2, r_peye, O_(V3_S4,z)),
 
 	mac_yield()
 })
@@ -592,24 +426,18 @@ internal MipsAtom* resolve_look_at__matrix_vector_proc(AtomArena_R aa
  * Pool cost: r_look_at (1) + r_scratch (carrier) + r_off_ptr + 1 clobber = 4 GPRs.
  */
 I_ MipsAtom* resolve_look_at__trans_matrix_proc(AtomArena_R aa
-	,	U4 r_look_at
+	,	U4 r_look_at,	U4 r_scratch,	U4 r_off_ptr
-	,	U4 r_scratch
+	,	U4 r_tmp0, U4 r_tmp1, U4 r_tmp2
-	,	U4 r_off_ptr
+) MipsAtom_Proc_(aa, {
-	,	U4 r_tmp0
-) MipsAtom_Proc_(resolve_look_at__trans_matrix, aa, {
-	/* Pop look_at* from tape. */
-	load_word(r_look_at, R_TapePtr, O_(Binds_ResolveLookAtPopAndTrans,look_at)),
-	add_ui_self(         R_TapePtr, S_(Binds_ResolveLookAtPopAndTrans)),
-
 	/* r_off_ptr = &off (= &scratch.eye since atom 6b overwrote eye with off). */
-	add_si(r_off_ptr, r_scratch, O_(ResolveLookAtScratch,eye)),
+	add_si(r_off_ptr, r_scratch, O_(ResolveLookAtScratch,eye)), nop,
-	nop,
 
 	/* Copy off → look_at.t[] (mac_trans_matrix: m->t = v). */
-	mac_trans_matrix(r_look_at, r_off_ptr, r_tmp0),
+	mac_trans_mt3s3s4(r_look_at, r_off_ptr, r_tmp0, r_tmp1, r_tmp2),
 
 	mac_yield()
 })
+#pragma endregion resolve_look_at
 
 #pragma endregion Atom Procs
 
@@ -628,7 +456,7 @@ internal MipsAtom_(screen_env_init) atom_info(atom_phase(screen_init)
 ) {
 	/* display[0] = (0, 0, 320, 240); rest of struct zeroed. */
 	add_ui(R_ScreenX, R_0, ScreenRes_X), add_ui(R_ScreenY, R_0, ScreenRes_Y),
-	mac_store_v2s2(R_ScreenX, R_ScreenY, R_ScreenBuf, O_(DisplayEnv,display_area.width) + OA_(DoubleBuffer,display,0)),
+	mac_store_v2s2(R_ScreenX, R_ScreenY, R_ScreenBuf, O_(DisplayEnv,display_area.width) + O_(DoubleBuffer,display[0])),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,display_area) + O_(DoubleBuffer,display[0])),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,screen)       + O_(DoubleBuffer,display[0])),
 	store_word(R_0, R_ScreenBuf, O_(DisplayEnv,vinterlace)   + O_(DoubleBuffer,display[0])),
@@ -741,15 +569,15 @@ internal MipsAtom_(pad_input_cube_rotation) atom_info(atom_bind(Binds_PadApplyIn
 	load_word(R_PadStateT5, R_TapePtr, O_(Binds_PadApplyInput,state)),
 	load_word(R_CubeRot,    R_TapePtr, O_(Binds_PadApplyInput,cube_rot)),
 	load_word(R_FloorRot,   R_TapePtr, O_(Binds_PadApplyInput,floor_rot)),
-	add_ui_self(            R_TapePtr, S_(Binds_PadApplyInput)),
+	LdSlot_ add_ui_self(    R_TapePtr, S_(Binds_PadApplyInput)),
 
 	/* Load pad[0].buttons into R_T0. */
-	load_word(R_T0, R_PadStateT5, O_(PadState,buttons)), nop,
+	load_word(R_T0, R_PadStateT5, O_(PadState,buttons)), LdSlot_ nop,
 	// Note(Ed): Potential op with delay slot?
 
 	/* D-pad Left: cube_rot.y += 30, floor_rot.y += 5.  */
-	and_i(R_T3, R_T0, Pad_Left), branch_le_zero(R_T3, atom_offset(dpad_left, exit_dpad_left)),
+	and_i(R_T3, R_T0, Pad_Left), branch_le_zero(R_T3, atom_offset(dpad_left, exit_dpad_left)), BdSlot_
-		load_half( R_T4, R_CubeRot,  O_(V3_S2,y)),   /* BD-slot */
+		load_half( R_T4, R_CubeRot,  O_(V3_S2,y)), LdSlot_
 		load_half( R_T3, R_FloorRot, O_(V3_S2,y)),
 		add_si(    R_T4, R_T4, 30),
 		add_si(    R_T3, R_T3, 5),
@@ -758,8 +586,8 @@ internal MipsAtom_(pad_input_cube_rotation) atom_info(atom_bind(Binds_PadApplyIn
 	atom_label(exit_dpad_left)
 
 	/* D-pad Right: cube_rot.y -= 30, floor_rot.y -= 5. */
-	and_i(R_T3, R_T0, Pad_Right), branch_le_zero(R_T3, atom_offset(dpad_right, exit_dpad_right)),
+	and_i(R_T3, R_T0, Pad_Right), branch_le_zero(R_T3, atom_offset(dpad_right, exit_dpad_right)), BdSlot_
-		load_half( R_T4, R_CubeRot,  O_(V3_S2,y)),   /* BD-slot */
+		load_half( R_T4, R_CubeRot,  O_(V3_S2,y)), LdSlot_
 		load_half( R_T3, R_FloorRot, O_(V3_S2,y)),
 		add_si(    R_T4, R_T4, -30),
 		add_si(    R_T3, R_T3, -5),
@@ -769,7 +597,7 @@ internal MipsAtom_(pad_input_cube_rotation) atom_info(atom_bind(Binds_PadApplyIn
 
 	/* Analog left-stick X: dead zone 0x70..0x90.
 	 * Cube delta = (0x80 - left_x) >> 2; floor delta = (0x80 - left_x) >> 5. */
-	load_byte_u(R_T3, R_PadStateT5, O_(PadState,left.x)),
+	load_byte_u(R_T3, R_PadStateT5, O_(PadState,left.x)), LdSlot_ //?
 
 	/* Dead-zone check: skip analog if left_x in [0x70, 0x90] inclusive. Outside dead zone on LOW side: left_x < 0x70 (strictly).
 	 * set_lt_u(R_T4, R_T3, R_T4=0x70) → R_T4 = (left_x < 0x70) ? 1 : 0. */
@@ -778,14 +606,14 @@ internal MipsAtom_(pad_input_cube_rotation) atom_info(atom_bind(Binds_PadApplyIn
 
 atom_label(dead_check_upper)
 	/* left_x >= 0x70 → check upper bound. */
-	load_byte_u(R_T3, R_PadStateT5, O_(PadState,left.x)), /* reload */
+	load_byte_u(R_T3, R_PadStateT5, O_(PadState,left.x)), /* reload */ LdSlot_ //? 
 	add_ui(     R_T4, R_0, PadDeadZone_HighBound),
 
 	/* R_T4 = (0x90 < left_x) ? 1 : 0 → (left_x > 0x90) ? 1 : 0 */
-	set_lt_u(R_T4, R_T4, R_T3), branch_ne(R_T4, R_0, atom_offset(dead_zone_high_check, dead_high_active)),
+	set_lt_u(R_T4, R_T4, R_T3), branch_ne(R_T4, R_0, atom_offset(dead_zone_high_check, dead_high_active)), BdSlot_
 	add_ui(  R_T4, R_0, PadDeadZone_Center), /* BD-slot: pre-load 0x80 for dead_high_active */
 	jump_rel(atom_offset(dead_zone_skip, exit_stick)),
-		mac_yield_load(),
+		BdSlot_ mac_yield_load(), LdSlot_
 
 atom_label(dead_low_active)
 	/* R_T3 = left_x (from line 632 lbu; not clobbered between dead_zone_low_check branch + its BD-slot `add_ui R_T4, 0x80`).
@@ -796,18 +624,18 @@ atom_label(dead_low_active)
 
 	/* R_T4 = cube_delta */
 	shift_aright(R_T4, R_T3, 2),
-	load_half(   R_T0, R_CubeRot, O_(V3_S2,y)), nop,
+	load_half(   R_T0, R_CubeRot, O_(V3_S2,y)), LdSlot_ nop,
 	add_u(       R_T0, R_T0, R_T4),
 	store_half(  R_T0, R_CubeRot, O_(V3_S2,y)),
 	/* R_T4 = floor_delta — moved into the load-delay slot of the floor load below (fills the 1-instruction gap;
 	 * doesn't read R_T0; R_T4 settles by the subsequent add_u). */
-	load_half(   R_T0, R_FloorRot, O_(V3_S2,y)),
+	load_half(   R_T0, R_FloorRot, O_(V3_S2,y)), LdSlot_
 	shift_aright(R_T4, R_T3, 5),
 	add_u(       R_T0, R_T0, R_T4),
 	store_half(  R_T0, R_FloorRot, O_(V3_S2,y)),
 
 	jump_rel(atom_offset(end_low, exit_stick)),
-		mac_yield_load(),
+		BdSlot_ mac_yield_load(), LdSlot_
 
 atom_label(dead_high_active)
 	/* R_T3 = left_x (from line 641 lbu in dead_check_upper; not clobbered between dead_zone_high_check branch + its BD-slot `add_ui R_T4, 0x80`).
@@ -817,18 +645,18 @@ atom_label(dead_high_active)
 	/* delta = 0x80 - left_x (signed negative). */
 
 	shift_aright(R_T4, R_T3, 2),                      /* R_T4 = cube_delta (signed) */
-	load_half(   R_T0, R_CubeRot, O_(V3_S2,y)), nop,
+	load_half(   R_T0, R_CubeRot, O_(V3_S2,y)), LdSlot_ nop,
 	add_u(       R_T0, R_T0, R_T4),
 	store_half(  R_T0, R_CubeRot, O_(V3_S2,y)),
 
 	/* R_T4 = floor_delta (signed) — moved into the load-delay slot of the floor load below. */
-	load_half(   R_T0, R_FloorRot, O_(V3_S2,y)),
+	load_half(   R_T0, R_FloorRot, O_(V3_S2,y)), LdSlot_
 	shift_aright(R_T4, R_T3, 5),
 	add_u(       R_T0, R_T0, R_T4),
 	store_half(  R_T0, R_FloorRot, O_(V3_S2,y)),
 
 atom_label(no_jump_fallthrough)
-	mac_yield_load(),
+	mac_yield_load(), LdSlot_
 
 atom_label(exit_stick)
 	/* NOT mac_yield() — R_AtomJmp was already loaded in the BD-slot of the dead-zone/exit branch. */
@@ -850,40 +678,43 @@ internal MipsAtom_(pad_input_cam) atom_info(atom_bind(Binds_PadInputCam)
 	/* Bind pop: state → R_CamPadState (R_T5), cam → R_Cam (R_T4), advance R_TapePtr by 8. */
 	load_word(R_CamPadState, R_TapePtr, O_(Binds_PadInputCam,state)),
 	load_word(R_Cam,         R_TapePtr, O_(Binds_PadInputCam,cam)),
-	add_ui_self(             R_TapePtr, S_(Binds_PadInputCam)),
+	LdSlot_ add_ui_self(     R_TapePtr, S_(Binds_PadInputCam)),
 
 	/* Load pad[0].buttons into R_T0; nop fills the load-delay slot. */
-	load_word(R_T0, R_CamPadState, O_(PadState,buttons)),
+	load_word(R_T0, R_CamPadState, O_(PadState,buttons)), LdSlot_
-	load_word(R_T1, R_Cam, O_(Camera,pos.x)), // BD-Slot.
+	load_word(R_T1, R_Cam, O_(Camera,pos.x)),
 
 	// D-pad Left → cam.pos.x -= 50.  and_i fulfills BD-slot for load on R_Cam.
-	and_i(R_T3, R_T0, Pad_Left), branch_le_zero(R_T3, atom_offset(left_x, exit_left_x)), mac_yield_load(),
+	LdSlot_ and_i(R_T3, R_T0, Pad_Left), branch_le_zero(R_T3, atom_offset(left_x, exit_left_x)), BdSlot_ mac_yield_load(), LdSlot_
-		add_si(R_T1, R_T1, -50), store_word(R_T1, R_Cam, O_(Camera,pos.x)),
+		add_si(R_T1, R_T1, -50), store_word(R_T1, R_Cam, O_(Camera,pos.x)), 
-atom_label(exit_left_x)
+	atom_label(exit_left_x)
+
 	/* D-pad Right → cam.pos.x += 50. Reuses R_T1 from Left. */
-	and_i(R_T3, R_T0, Pad_Right), branch_le_zero(R_T3, atom_offset(right_x, exit_right_x)), nop,
+	and_i(R_T3, R_T0, Pad_Right), branch_le_zero(R_T3, atom_offset(right_x, exit_right_x)), BdSlot_ nop,
 		add_si(R_T1, R_T1,  50), store_word(R_T1, R_Cam, O_(Camera,pos.x)),
-atom_label(exit_right_x)
+	atom_label(exit_right_x)
 
 	/* D-pad Up → cam.pos.y -= 50. Load pos.y BEFORE the andi. */
-	load_word(R_T1, R_Cam, O_(Camera,pos.y)),
+	load_word(R_T1, R_Cam, O_(Camera,pos.y)), LdSlot_ 
-	and_i(R_T3, R_T0, Pad_Up), branch_le_zero(R_T3, atom_offset(up_y, exit_up_y)), nop,
+	and_i(R_T3, R_T0, Pad_Up), branch_le_zero(R_T3, atom_offset(up_y, exit_up_y)), BdSlot_ nop,
 		add_si(R_T1, R_T1, -50), store_word(R_T1, R_Cam, O_(Camera,pos.y)),
-atom_label(exit_up_y)
+	atom_label(exit_up_y)
+
 	/* D-pad Down → cam.pos.y += 50. Reuses R_T1 from Up. */
-	and_i(R_T3, R_T0, Pad_Down), branch_le_zero(R_T3, atom_offset(down_y, exit_down_y)), nop,
+	and_i(R_T3, R_T0, Pad_Down), branch_le_zero(R_T3, atom_offset(down_y, exit_down_y)), BdSlot_ nop,
 		add_si(R_T1, R_T1,  50), store_word(R_T1, R_Cam, O_(Camera,pos.y)),
-atom_label(exit_down_y)
+	atom_label(exit_down_y)
 
 	/* D-pad Cross → cam.pos.z -= 50. Load pos.z BEFORE the andi. */
-	load_word(R_T1, R_Cam, O_(Camera,pos.z)),
+	load_word(R_T1, R_Cam, O_(Camera,pos.z)), LdSlot_
-	and_i(R_T3, R_T0, Pad_Cross), branch_le_zero(R_T3, atom_offset(cross_z, exit_cross_z)), nop,
+	and_i(R_T3, R_T0, Pad_Cross), branch_le_zero(R_T3, atom_offset(cross_z, exit_cross_z)), BdSlot_ nop,
 		add_si(R_T1, R_T1, -50), store_word(R_T1, R_Cam, O_(Camera,pos.z)),
-atom_label(exit_cross_z)
+	atom_label(exit_cross_z)
+
 	/* D-pad Circle → cam.pos.z += 50. Reuses R_T1 from Cross. */
-	and_i(R_T3, R_T0, Pad_Circle), branch_le_zero(R_T3, atom_offset(circle_z, exit_circle_z)), nop,
+	and_i(R_T3, R_T0, Pad_Circle), branch_le_zero(R_T3, atom_offset(circle_z, exit_circle_z)), BdSlot_ nop,
 		add_si(R_T1, R_T1,  50), store_word(R_T1, R_Cam, O_(Camera,pos.z)),
-atom_label(exit_circle_z)
+	atom_label(exit_circle_z)
 
 	mac_yield_tail(),
 };
@@ -913,7 +744,7 @@ internal MipsAtom_(rbind_cube_g4_face) atom_info(atom_bind(Binds_CubeTri), atom_
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_CubeTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_CubeTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_CubeTri,OtBase)),
-	add_ui_self(            R_TapePtr, S_(Binds_CubeTri)),
+	LdSlot_ add_ui_self(    R_TapePtr, S_(Binds_CubeTri)),
 	mac_yield()
 };
 
@@ -926,20 +757,20 @@ MipsAtom_(cube_g4_face) atom_info(atom_phase(cube_g4),
 	load_half_u(R_T0, R_FaceCursor, 0 * S_(S2)),
 	load_half_u(R_T1, R_FaceCursor, 1 * S_(S2)),
 	load_half_u(R_T2, R_FaceCursor, 2 * S_(S2)),
-	load_half_u(R_T3, R_FaceCursor, 3 * S_(S2)),
+	// load_half_u(R_T3, R_FaceCursor, 3 * S_(S2)),
 
-	mac_gte_load_tri_verts(R_VertBase, R_T0, R_T1, R_T2),
+	LdSlot_ mac_gte_load_tri_verts(R_VertBase, R_T0, R_T1, R_T2), GteDelay_ load_half_u(R_T3, R_FaceCursor, 3 * S_(S2)), LdSlot_
-	nop2, gte_cmdw_rotate_translate_perspective_triple, // required cpu -> gte delay slot
+	GteDelay_ nop, gte_cmdw_rotate_translate_perspective_triple,
 	gte_cmdw_nclip,
 
-	gte_mv_from_data_r(R_T0, C2_MAC0), nop,
+	gte_mv_from_data_r(R_T0, C2_MAC0), GteDelay_ nop,
 	branch_le_zero(R_T0, atom_offset(cull, cube_g4_face_exit)),
 		/* BD-slot: Write the prim tag (R_0=0; overwrites the legacy tag word in the prim_buffer).
 		 * If branch IS taken (face culled), the body is skipped and this 0-tag is stranded —
 		 * harmless because the OT entry that points to this prim is created later. */
-		store_word(R_0, R_PrimCursor, O_(Poly_G4, tag)),
+		BdSlot_ store_word(R_0, R_PrimCursor, O_(Poly_G4, tag)),
 		shift_lleft(R_AT, R_T3, v3s2_byteoff), add_u(R_AT, R_AT, R_VertBase),
-		load_word(R_V0, R_AT, O_(V3_S2, x)),   load_word(R_V1, R_AT, O_(V3_S2, z)),
+		load_word(R_V0, R_AT, O_(V3_S2, x)),   load_word(R_V1, R_AT, O_(V3_S2, z)), LdSlot_
 		gte_mv_to_data_r(R_V0, C2_VXY0),       gte_mv_to_data_r(R_V1, C2_VZ0),
 
 		mac_gte_store_g4_p012(R_PrimCursor),
@@ -951,7 +782,7 @@ MipsAtom_(cube_g4_face) atom_info(atom_phase(cube_g4),
 		add_ui(      R_AT, R_0,  OrderingTbl_Len),
 		set_lt_u(    R_AT, R_T1, R_AT),
 
-		branch_equal(R_AT, R_0,  atom_offset(bounds_chk, cube_g4_face_exit)), nop,
+		branch_equal(R_AT, R_0,  atom_offset(bounds_chk, cube_g4_face_exit)), BdSlot_ nop,
 			mac_insert_ot_tag(R_OtBase, R_PrimCursor, S_(Poly_G4)),
 			mac_format_g4_color(R_PrimCursor,
 				/* c0 magenta */ 0xFF, 0x00, 0xFF,
@@ -983,7 +814,7 @@ MipsAtom_(rbind_floor_f3_face) atom_info(atom_bind(Binds_FloorTri), atom_phase(f
 	load_word(R_FaceCursor, R_TapePtr, O_(Binds_FloorTri,FaceCursor)),
 	load_word(R_VertBase,   R_TapePtr, O_(Binds_FloorTri,VertBase)),
 	load_word(R_OtBase,     R_TapePtr, O_(Binds_FloorTri,OtBase)),
-	add_ui_self(            R_TapePtr, S_(Binds_FloorTri)),
+	LdSlot_ add_ui_self(    R_TapePtr, S_(Binds_FloorTri)),
 	mac_yield()
 };
 
@@ -1030,7 +861,7 @@ internal MipsAtom_(sync_primitive_arena) atom_info(atom_bind(Binds_SyncPrimitive
 	, atom_writes(R_TapePtr)
 ){
 	load_word(R_AT, R_TapePtr, O_(Binds_SyncPrimitiveArena,used)),
-	load_word(R_T0, R_TapePtr, O_(Binds_SyncPrimitiveArena,cursor)),
+	load_word(R_T0, R_TapePtr, O_(Binds_SyncPrimitiveArena,cursor)), LdSlot_
 	add_ui_self(    R_TapePtr, S_(Binds_SyncPrimitiveArena)),
 	/* Calculate byte offset and store directly back to RAM */
 	sub_u(     R_T0, R_PrimCursor, R_T0), // R_T0    = R_PrimCursor - binds.cursor

code/hello_camera/hello_camera.c

@@ -1,7 +1,7 @@
 #pragma region Vendors
 #include <stdio.h>
 #include <stdlib.h>
-#include <assert.h>
+// #include <assert.h>
 // #include "libgpu.h"
 // #include "libetc.h"
 // #include "libgte.h"
@@ -32,7 +32,7 @@
 
 #pragma region Duffle TUs
 #include "duffle/pad.c"
-#include "duffle/math.atom.c"
+#include "duffle/math.atom.h"
 #include "duffle/mips.atom.c"
 #include "duffle/gte.atom.c"
 #include "duffle/gp.atom.c"
@@ -60,8 +60,12 @@ enum {
 enum {
 	Scratchpad_Len           = 1024,
 	MemTape_Len              = 512,
+
 	ResolveLookAtArena_Words = 1024,
 	ResolveLookAtArena_Size  = ResolveLookAtArena_Words * S_(MipsCode),
+
+	CT_InitAtomMem_Words     = Kilo_(4),
+	CT_InitAtomMem_Size       = CT_InitAtomMem_Words * S_(MipsCode),
 };
 typedef Struct_(SMemory) {
 	PrimitiveArena          primitives;
@@ -85,8 +89,14 @@ typedef Struct_(SMemory) {
 	// TODO(Ed): We don't need this we can just cast at any point an address to a desired view of scratchpad, we have the address.
 	U4_V scratchpad; // d-cache
 
+	U1 ct_init_atom_mem[CT_InitAtomMem_Size];
+	MipsAtom* normalize_v3s4;
+	// TODO(Ed): Convert normalize_v3s4 to a generic atom?
+	// This would allow us to reduce specializations with the loss being some cycles to loading registers.
+	// The cost would be 3 loads (scratch, src_ptr, dst_offset) from tape and 
+
 	U1        resolve_look_at_mem[ResolveLookAtArena_Size];
-	MipsAtom* resolve_look_at_atom_addrs[10];
+	MipsAtom* resolve_look_at_bundle[AtomBundle_Len(resolve_look_at)];
 };
 global SMemory smem;
 extern SMemory smem;
@@ -131,241 +141,155 @@ I_ void resolve_look_at_c11(MT3_S2S4* look_at, P3_S4* eye, P3_S4* target, V3_S4*
 }
 FI_ void camera_look_at_c11(Camera* c, P3_S4* target, V3_S4* up_in) { resolve_look_at_c11(& c->look_at, & c->pos, target, up_in); }
 
-/* Pre-build all 7 chain atoms of the resolve_look_at bundle into the static arena.
- * Called ONCE from main() before the frame loop.
- * After this returns, the smem.resolve_look_at_atom_addrs[] array contains valid MIPS atom pointers
- * for the frame-time bundle helper to emit via tb_emit(tb, captured_addr).
- *
- * 4 unique procs in hello_camera.atom.c (chain atoms 0, 2, 4, 6); atoms 1, 3, 5
- * share the GENERIC normalize_v3s4_proc from gte.atom.c (called 3x with different
- * O_(ResolveLookAtScratch,...) offsets):
- * 	0: resolve_look_at__input_and_sub_proc
- * 	1: normalize_v3s4_proc                  (fwd → uz; offsets 0, 16)
- * 	2: resolve_look_at__cross_uz_up_in_to_right_proc
- * 	3: normalize_v3s4_proc                  (right → ux; offsets 32, 48)
- * 	4: resolve_look_at__cross_uz_ux_to_up_proc
- * 	5: normalize_v3s4_proc                  (up → uy; offsets 64, 80)
- * 	6: resolve_look_at__populate_and_translate_proc
- *
- * Task 12.16 promotion: the bundle-specific resolve_look_at__chain_normalize_proc
- * has been promoted to the generic normalize_v3s4_proc (gte.atom.c), which now
- * takes r_scratch + r_src_offset + r_dst_offset as U4 parameters. The 3 callers
- * pass O_(ResolveLookAtScratch,...) macros as offset args. The metaprogram emits
- * one set of `atom_offset__normalize_v3s4__srav_path__aligned_done` defs
- * (namespaced by atom name) in duffle/gen/offsets.h, shared by all 3 callers.
- *
- * GPR pool per atom: 10 free GPRs (R_T0..R_T3 + R_T5..R_T7 + R_V0 + R_V1 + R_AT).
- * R_T4 is reserved as the wave-context carrier (R_ResolveScratch).
- */
-/* === EXPLICIT REGISTER ALLOCATION TRACKER ===
- * Every GPR used by every atom is tracked below. NO GPR is assigned to
- * two atoms at overlapping lifetimes. The tape runtime preserves R_T8/R_T9
- * (R_AtomJmp/R_TapePtr) and clobbers R_T0-R_T7, R_AT, R_V0, R_V1.
- * R_T4 is reserved as R_ResolveScratch (wave-context carrier).
- *
- * GPR pool: R_T0($8), R_T1($9), R_T2($10), R_T3($11), R_T5($13),
- *           R_T6($14), R_T7($15), R_V0($2), R_V1($3), R_AT($1)
- * Reserved: R_T4($12) = R_ResolveScratch
- * Tape: R_T8($24) = R_AtomJmp, R_T9($25) = R_TapePtr (preserved)
- *
- * === ATOM 0: input_and_sub (stages eye/up_in, computes fwd) ===
- * Pop tape → R_T0(target), R_T1(eye), R_T2(up_in).
- * Use R_T3,R_T5,R_T6,R_T7 as temps.
- * NO conflict with other atoms (each atom has independent lifetime).
- *
- * === ATOM 1: normalize fwd→uz ===
- * r_src_offset=0, r_dst_offset=16.
- * r_src_ptr=R_T0, r_dst_ptr=R_T1, r_tmp=R_T2 (preserved for stage 4).
- * r_mac1=R_T3, r_mac2=R_T5, r_recip=R_T6, r_lzcr=R_T7, r_shift=R_V0, r_branch=R_V1.
- *
- * === ATOM 2: cross uz×up_in→right ===
- * r_a=R_T0, r_b=R_T1, r_c=R_T2, r_d=R_T3, r_f(out)=R_T5, r_g=R_T6, r_h=R_T7.
- *
- * === ATOM 3: normalize right→ux ===
- * Same GPR pool as atom 1.
- *
- * === ATOM 4: cross uz×ux→up ===
- * r_a=R_T0, r_b=R_T1, r_c=R_T2, r_d=R_T3, r_f(out)=R_T5, r_g=R_T6, r_h=R_T7.
- *
- * === ATOM 5: normalize up→uy ===
- * Same GPR pool as atom 1.
- *
- * === ATOM 6a: populate (m[][] from ux/uy/uz, t[]=0) ===
- * r_look_at=R_T0 (pop tape), r_scratch=R_T4.
- * r_pux=R_T1, r_puy=R_T3, r_puz=R_T5.
- * r_tmp0=R_T2, r_tmp1=R_T6, r_tmp2=R_V0.
- *
- * === ATOM 6a.5: set_gte_mt3s2s4 (ctc2 RT matrix) ===
- * BAKED atom. Uses R_T3 internally (hardcoded in gte.atom.c).
- * NO conflict — different GPR pool, and the atom body hardcodes R_T3
- * as the matrix pointer. We DON'T need to assign R_T3 to atom 6a.5
- * because it's a baked atom with its own GPR usage.
- *
- * === ATOM 6b: matrix_vector (RT * (-eye) >> 12) ===
- * r_look_at=R_T0 (pop tape), r_scratch=R_T4.
- * r_peye=R_T1.
- * r_tmp0=R_T2, r_tmp1=R_T3, r_tmp2=R_T5.
- * Uses mac_apply_matrix_lv which internally uses these temps.
- *
- * === ATOM 6c: trans_matrix (off → look_at->t[]) ===
- * r_look_at=R_T0 (pop tape), r_scratch=R_T4.
- * r_off_ptr=R_T1.
- * r_tmp0=R_T2.
- *
- * === CONFLICT CHECK ===
- * All atoms use the same GPR pool R_T0-R_T3, R_T5-R_T7, R_V0-R_V1.
- * But atoms are SEQUENTIAL — each atom's lifetime is disjoint from
- * the next atom's lifetime. The tape yield handshake between atoms
- * preserves R_TapePtr (R_T9) and R_AtomJmp (R_T8).
- *
- * The GPR pool is SHARED across atoms (they run sequentially, not
- * concurrently). Each atom's build call assigns specific R_T* codes
- * for that atom's body. The same R_T* code can be reused across atoms
- * because the previous atom's body has already yielded.
- */
-internal void resolve_look_at_init(void) {
-	/* Wrap the static arena in a MipsAtomBuilder. */
-	AtomArena ab = atomarena_make(slice_ut_arr(smem.resolve_look_at_mem));
 
-	/* === ATOM 0: input_and_sub === */
+
-	U4 const r_target_ptr = R_T0;  /* tape pop → target */
+internal void compile_resolve_look_at(void) {
-	U4 const r_eye_ptr    = R_T1;  /* tape pop → eye */
+	/* Wrap the static arena in a MipsAtomBuilder. */
-	U4 const r_up_in_ptr  = R_T2;  /* tape pop → up_in */
+	AtomArena   ab = atomarena_make(slice_ut_arr(smem.resolve_look_at_mem));
-	U4 const r_tmp0_0     = R_T3;
+	TapeBuilder tb = tb_make(slice_ut_arr(smem.resolve_look_at_bundle));
-	U4 const r_tmp1_0     = R_T5;
+
-	U4 const r_tmp2_0     = R_T6;
+	U4 pin_mask = regfile_abi_mask | (1 << R_ResolveScratch);
-	U4 const r_tmp3_0     = R_T7;
+	RegFile rf  = regfile(pin_mask);
-	smem.resolve_look_at_atom_addrs[0] = resolve_look_at__input_and_sub_proc(& ab,
+#define ralloc() regfile_alloc(& rf)
-		R_ResolveScratch,
+#define ralloc_v3() { ralloc(), ralloc(), ralloc() }
-		r_target_ptr, r_eye_ptr, r_up_in_ptr,
+
-		r_tmp0_0, r_tmp1_0, r_tmp2_0, r_tmp3_0);
+	tb_emit_(AtomBundleEntry_(resolve_look_at, input_and_sub)(& ab,
+		RegUse_(resolve_look_at_input_and_sub) {
+			.scratch = R_ResolveScratch,
+			.target  = ralloc(),
+			.eye     = ralloc(),
+			.up_in   = ralloc(),
+			.t0      = ralloc(),
+			.t1      = ralloc(),
+			.t2      = ralloc(),
+			.t3      = ralloc(),
+			.t4      = ralloc(),
+		}
+	));
+	regfile_reset_to_mask(& rf, pin_mask);
 
 	/* === ATOM 1: normalize fwd→uz === */
-	U4 const r_src_offset_1  = O_(ResolveLookAtScratch, fwd);
+	U2 src_offset  = O_(ResolveLookAtScratch, fwd);
-	U4 const r_dst_offset_1  = O_(ResolveLookAtScratch, uz);
+	U2 dst_offset  = O_(ResolveLookAtScratch, uz);
-	U4 const r_src_ptr_1     = R_T0;
+	smem.resolve_look_at_bundle[1] = build_normalize_v3s4(& ab,
-	U4 const r_dst_ptr_1     = R_T1;
+		src_offset, dst_offset, RegUse_(build_normalize_v3s4){
-	U4 const r_tmp_1         = R_T2;
+			.scratch   = R_ResolveScratch,
-	U4 const r_mac1_1        = R_T3;
+			.src_ptr   = ralloc(), 
-	U4 const r_mac2_1        = R_T5;
+			.dst_ptr   = ralloc(),
-	U4 const r_recip_1       = R_T6;
+			.recip_est = ralloc(), 
-	U4 const r_lzcr_1        = R_T7;
+			.norm      = ralloc(),
-	U4 const r_shift_1       = R_V0;
+			.shift     = ralloc(),
-	U4 const r_branch_1      = R_V1;
+			.src_x     = ralloc(),
-	smem.resolve_look_at_atom_addrs[1] = normalize_v3s4_proc(& ab,
+			.t3 = ralloc(),
-		R_ResolveScratch,
+			.t4 = ralloc(),
-		r_src_offset_1, r_dst_offset_1,
+			.t5 = ralloc(),
-		r_src_ptr_1, r_dst_ptr_1, r_tmp_1,
+		});
-		r_mac1_1, r_mac2_1, r_recip_1, r_lzcr_1,
+	regfile_reset_to_mask(& rf, pin_mask);
-		r_shift_1, r_branch_1);
 
 	/* === ATOM 2: cross uz×up_in→right === */
-	U4 const r_a_2 = R_T0;
+	// smem.resolve_look_at_bundle[2] = AtomBundleEntry_(resolve_look_at,cross_uz_up_to_right)(& ab,
-	U4 const r_b_2 = R_T1;
+	smem.resolve_look_at_bundle[2] = resolve_look_at_cross_uz_up_into_right(& ab,
-	U4 const r_c_2 = R_T2;
+		RegUse_(resolve_look_at_cross_uz_up_into_right) {
-	U4 const r_d_2 = R_T3;
+			.scratch = R_ResolveScratch,
-	U4 const r_f_2 = R_T5;  /* out ptr (HARDCODED in body: scratch+32) */
+			.a  = ralloc(), 
-	U4 const r_g_2 = R_T6;  /* a ptr = scratch+16 */
+			.b  = ralloc(), 
-	U4 const r_h_2 = R_T7;  /* b ptr = scratch+128 */
+			.c  = ralloc(),
-	smem.resolve_look_at_atom_addrs[2] = resolve_look_at__cross_uz_up_in_to_right_proc(& ab,
+			.d  = ralloc(),
-		R_ResolveScratch,
+			.f  = ralloc(),
-		r_a_2, r_b_2, r_c_2, r_d_2, r_f_2, r_g_2, r_h_2);
+			.t1 = ralloc(),
+			.t2 = ralloc(),
+			.t0 = ralloc(),
+		});
+	regfile_reset_to_mask(& rf, pin_mask);	
 
 	/* === ATOM 3: normalize right→ux === */
-	U4 const r_src_offset_3  = O_(ResolveLookAtScratch, right);
+	src_offset  = O_(ResolveLookAtScratch, right);
-	U4 const r_dst_offset_3  = O_(ResolveLookAtScratch, ux);
+	dst_offset  = O_(ResolveLookAtScratch, ux);
-	U4 const r_src_ptr_3     = R_T0;
+	smem.resolve_look_at_bundle[3] = build_normalize_v3s4(& ab,
-	U4 const r_dst_ptr_3     = R_T1;
+		src_offset, dst_offset, RegUse_(build_normalize_v3s4){
-	U4 const r_tmp_3         = R_T2;
+			.scratch   = R_ResolveScratch,
-	U4 const r_mac1_3        = R_T3;
+			.src_ptr   = ralloc(),
-	U4 const r_mac2_3        = R_T5;
+			.dst_ptr   = ralloc(),
-	U4 const r_recip_3       = R_T6;
+			.recip_est = ralloc(),
-	U4 const r_lzcr_3        = R_T7;
+			.norm      = ralloc(),
-	U4 const r_shift_3       = R_V0;
+			.shift     = ralloc(),
-	U4 const r_branch_3      = R_V1;
+			.src_x     = ralloc(),
-	smem.resolve_look_at_atom_addrs[3] = normalize_v3s4_proc(& ab,
+			.t3        = ralloc(),
-		R_ResolveScratch,
+			.t4        = ralloc(),
-		r_src_offset_3, r_dst_offset_3,
+			.t5        = ralloc(),
-		r_src_ptr_3, r_dst_ptr_3, r_tmp_3,
+		});
-		r_mac1_3, r_mac2_3, r_recip_3, r_lzcr_3,
+	regfile_reset_to_mask(& rf, pin_mask);	
-		r_shift_3, r_branch_3);
 
 	/* === ATOM 4: cross uz×ux→up === */
-	U4 const r_a_4 = R_T0;
+	smem.resolve_look_at_bundle[4] = resolve_look_at__cross_uz_ux_to_up_proc(& ab,
-	U4 const r_b_4 = R_T1;
+		RegUse_(resolve_look_at__cross_uz_ux_to_up_proc){
-	U4 const r_c_4 = R_T2;
+			.scratch = R_ResolveScratch,
-	U4 const r_d_4 = R_T3;
+			.a  = ralloc_v3(),   /* T0 T1 T2 */
-	U4 const r_f_4 = R_T5;  /* out ptr (HARDCODED: scratch+64) */
+			.b  = ralloc_v3(),   /* T3 T5 T6 */
-	U4 const r_g_4 = R_T6;  /* a ptr = scratch+16 */
+			.t0 = ralloc(),      /* T7  = up */
-	U4 const r_h_4 = R_T7;  /* b ptr = scratch+48 */
+			.t1 = ralloc(),      /* V0  = uz / rt11 */
-	smem.resolve_look_at_atom_addrs[4] = resolve_look_at__cross_uz_ux_to_up_proc(& ab,
+			.t2 = ralloc(),      /* V1  = ux / rt22 */
-		R_ResolveScratch,
+		});
-		r_a_4, r_b_4, r_c_4, r_d_4, r_f_4, r_g_4, r_h_4);
+	regfile_reset_to_mask(& rf, pin_mask);	
 
 	/* === ATOM 5: normalize up→uy === */
-	U4 const r_src_offset_5  = O_(ResolveLookAtScratch, up);
+	src_offset = O_(ResolveLookAtScratch, up);
-	U4 const r_dst_offset_5  = O_(ResolveLookAtScratch, uy);
+	dst_offset = O_(ResolveLookAtScratch, uy);
-	U4 const r_src_ptr_5     = R_T0;
+	smem.resolve_look_at_bundle[5] = build_normalize_v3s4(& ab,
-	U4 const r_dst_ptr_5     = R_T1;
+		src_offset, dst_offset,
-	U4 const r_tmp_5         = R_T2;
+		RegUse_(build_normalize_v3s4){
-	U4 const r_mac1_5        = R_T3;
+			.scratch   = R_ResolveScratch,
-	U4 const r_mac2_5        = R_T5;
+			.src_ptr   = ralloc(),
-	U4 const r_recip_5       = R_T6;
+			.dst_ptr   = ralloc(),
-	U4 const r_lzcr_5        = R_T7;
+			.recip_est = ralloc(),
-	U4 const r_shift_5       = R_V0;
+			.norm      = ralloc(),
-	U4 const r_branch_5      = R_V1;
+			.shift     = ralloc(),
-	smem.resolve_look_at_atom_addrs[5] = normalize_v3s4_proc(& ab,
+			.src_x     = ralloc(),
-		R_ResolveScratch,
+			.t3 = ralloc(),
-		r_src_offset_5, r_dst_offset_5,
+			.t4 = ralloc(),
-		r_src_ptr_5, r_dst_ptr_5, r_tmp_5,
+			.t5 = ralloc(),
-		r_mac1_5, r_mac2_5, r_recip_5, r_lzcr_5,
+		});
-		r_shift_5, r_branch_5);
+	regfile_reset_to_mask(& rf, pin_mask);
 
 	/* === ATOM 6a: populate (m[][] from ux/uy/uz, t[]=0) === */
-	U4 const r_look_at_6a = R_T0;  /* tape pop → look_at* */
+	smem.resolve_look_at_bundle[6] = resolve_look_at__populate_proc(& ab,
-	U4 const r_scratch_6a = R_ResolveScratch;
+		RegUse_(resolve_look_at__populate_proc){
-	U4 const r_pux_6a      = R_T1;
+			.scratch = R_ResolveScratch,
-	U4 const r_puy_6a      = R_T3;
+			.look_at = ralloc(),     /* T0 */
-	U4 const r_puz_6a      = R_T5;
+			.row     = ralloc_v3(),  /* T1 T2 T3 */
-	U4 const r_tmp0_6a     = R_T2;
+			.ux      = ralloc(),     /* T5 = ux */
-	U4 const r_tmp1_6a     = R_T6;
+			.uy      = ralloc(),     /* T6 = uy */
-	U4 const r_tmp2_6a     = R_V0;
+			.uz      = ralloc(),     /* T7 = uz */
-	smem.resolve_look_at_atom_addrs[6] = resolve_look_at__populate_proc(& ab,
+		});
-		r_look_at_6a, r_scratch_6a,
+	regfile_reset_to_mask(& rf, pin_mask);
-		r_pux_6a, r_puy_6a, r_puz_6a,
-		r_tmp0_6a, r_tmp1_6a, r_tmp2_6a);
 
 	/* === ATOM 6a.5: set_gte_mt3s2s4 (BAKED — ctc2 RT matrix) ===
 	 * This is a BAKED atom from gte.atom.c. Its body hardcodes R_T3 as
 	 * the matrix pointer (popped from tape). It does NOT need GPR
 	 * assignment from us — it has its own internal GPR usage.
 	 * We just take its address. */
-	smem.resolve_look_at_atom_addrs[7] = (MipsAtom*) & set_gte_mt3s2s4;
+	smem.resolve_look_at_bundle[7] = (MipsAtom*) & set_gte_mt3s2s4;
 
-	/* === ATOM 6b: matrix_vector (RT * (-eye) >> 12) ===
+	/* === ATOM 6b: matrix_vector (RT * (-eye) >> 12) === */
-	 * Uses mac_apply_matrix_lv component macro which internally uses
+	smem.resolve_look_at_bundle[8] = resolve_look_at__matrix_vector_proc(& ab,
-	 * r_t0 for the RT matrix load + V0 load, then r_t0/r_t1/r_t2
+		RegUse_(resolve_look_at__matrix_vector_proc){
-	 * for the mfc2/store. We pass our GPRs. */
+			.scratch = R_ResolveScratch,
-	U4 const r_scratch_6b = R_ResolveScratch;
+			.look_at = ralloc(),     /* T0 */
-	U4 const r_peye_6b    = R_T1;  /* scratch+96 (packed V0 dst, then off dst) */
+			.eye     = ralloc(),     /* T1 */
-	U4 const r_look_at_6b = R_T0;  /* tape pop → look_at* */
+			.v       = ralloc_v3(),  /* T2 T3 T5 */
-	U4 const r_tmp0_6b    = R_T2;
+		});
-	U4 const r_tmp1_6b    = R_T3;
-	U4 const r_tmp2_6b    = R_T5;
-	smem.resolve_look_at_atom_addrs[8] = resolve_look_at__matrix_vector_proc(& ab,
-		r_scratch_6b, r_peye_6b, r_look_at_6b,
-		r_tmp0_6b, r_tmp1_6b, r_tmp2_6b);
 
 	/* === ATOM 6c: trans_matrix (off → look_at->t[]) === */
-	U4 const r_look_at_6c = R_T0;  /* tape pop → look_at* */
+	U4 r_look_at_6c = R_T0;  /* tape pop → look_at* */
-	U4 const r_scratch_6c = R_ResolveScratch;
+	U4 r_scratch_6c = R_ResolveScratch;
-	U4 const r_off_ptr_6c = R_T1;  /* &scratch.eye (= off dst) */
+	U4 r_off_ptr_6c = R_T1;  /* &scratch.eye (= off dst) */
-	U4 const r_tmp0_6c    = R_T2;
+	U4 r_tmp0_6c    = R_T2;
-	smem.resolve_look_at_atom_addrs[9] = resolve_look_at__trans_matrix_proc(& ab,
+	smem.resolve_look_at_bundle[9] = resolve_look_at__trans_matrix_proc(& ab,
-		r_look_at_6c, r_scratch_6c, r_off_ptr_6c, r_tmp0_6c);
+		r_look_at_6c, r_scratch_6c, r_off_ptr_6c, r_tmp0_6c, R_T3, R_T4);
 
 	/* Sanity check: arena didn't overflow. */
 	assert(ab.used <= ResolveLookAtArena_Size);
+#undef ralloc
 }
 
 /* Emit the resolve_look_at bundle into the tape. Called once per frame from update().
@@ -379,37 +303,42 @@ internal void resolve_look_at_init(void) {
  *                                       ----
  *                                       5 tb_data words total per frame.
  */
-I_ void resolve_look_at(
+I_ void resolve_look_at(TapeBuilder_R tb
-		TapeBuilder_R tb
 	,	MT3_S2S4* look_at
 	,	P3_S4*    eye
 	,	P3_S4*    target
 	,	V3_S4*    up_in
 ){
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[0]); {
+	tb_emit(tb, smem.resolve_look_at_bundle[0]); {
 		tb_data(tb, u4_(target));
 		tb_data(tb, u4_(eye));
 		tb_data(tb, u4_(up_in));
 		tb_data(tb, u4_(smem.scratchpad));
 	}
 
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[1]); { }
+	tb_emit(tb, smem.resolve_look_at_bundle[1]); { 
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[2]); { }
+		// tb_data(tb, u4_(Scratchpad_Loc));
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[3]); { }
+	}
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[4]); { }
+	tb_emit(tb, smem.resolve_look_at_bundle[2]); { }
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[5]); { }
+	tb_emit(tb, smem.resolve_look_at_bundle[3]); { 
+		// tb_data(tb, u4_(Scratchpad_Loc));
+	}
+	tb_emit(tb, smem.resolve_look_at_bundle[4]); { }
+	tb_emit(tb, smem.resolve_look_at_bundle[5]); { 
+		// tb_data(tb, u4_(Scratchpad_Loc));
+	}
 
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[6]); {
+	tb_emit(tb, smem.resolve_look_at_bundle[6]); {
 		tb_data(tb, u4_(look_at));
 	}
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[7]); {
+	tb_emit(tb, smem.resolve_look_at_bundle[7]); {
 		tb_data(tb, u4_(look_at));
 	}
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[8]); {
+	tb_emit(tb, smem.resolve_look_at_bundle[8]); {
 		tb_data(tb, u4_(look_at));
 	}
-	tb_emit(tb, smem.resolve_look_at_atom_addrs[9]); {
+	tb_emit(tb, smem.resolve_look_at_bundle[9]); {
-		tb_data(tb, u4_(look_at));
+		// tb_data(tb, u4_(look_at));
 	}
 }
 
@@ -425,9 +354,9 @@ void update(PrimitiveArena* pa, U4* ordering_buf)
 			tb_emit_(pad_bios_snapshot);
 				tb_data_(raw,   & smem.pad_raw[0]);
 				tb_data_(state, & smem.pad[0]);
-			tb_emit_(pad_bios_snapshot);
+			// tb_emit_(pad_bios_snapshot);
-				tb_data_(raw,   & smem.pad_raw[1]);
+			// 	tb_data_(raw,   & smem.pad_raw[1]);
-				tb_data_(state, & smem.pad[1]);
+			// 	tb_data_(state, & smem.pad[1]);
 
 			tb_emit_(pad_input_cam);
 				tb_data_(state, & smem.pad[0]);
@@ -602,8 +531,7 @@ int main(void)
 		/* Direct BIOS: poll both ports during VBlank. */
 		pad_bios_init_start(& smem.pad_raw[0], & smem.pad_raw[1]);
 
-		/* Pre-build the resolve_look_at bundle atoms into the static arena. */
+		compile_resolve_look_at();
-		resolve_look_at_init();
 
 		/* Pinned registers for the GPU init atom. */
 		register U4*           io_base_addr rgcc(R_IO_BaseAddr) = u4_r(IO_BASE_ADDR);
@@ -624,4 +552,3 @@ int main(void)
 	return 0;
 }
 GCC_OPTIMIZATION_ENABLE
-

code/hello_joypad/hello_joypad.atom.c

@@ -25,7 +25,7 @@ ATOM_FILE_DEBUGGER_LINE_MARKER(hello_joypad_atom_c);
 #pragma region MACs (Mips Atom components)
 
 FI_ Slice_MipsCode ac_put_disp_env(MipsAtomBuilder_R ab, U4 reg_transfer, U4 reg_base, U2 port)
-MipsAtomComp_Proc_(ac_put_disp_env, ab, {
+MipsAtomComp_Proc_(ab, {
 	// Emits 5 GP0 commands for buffer 0 (display_area = (0,0,320,240)).
 	// Sequence per libpsyx PutDispEnv: DrawArea TL → DrawArea BR → Mask → DrawArea TL → DrawArea BR
 	mac_gcmd_push(gp0_word_draw_area_top_left_origin,      reg_transfer, reg_base, port),
@@ -36,7 +36,7 @@ MipsAtomComp_Proc_(ac_put_disp_env, ab, {
 })
 
 FI_ Slice_MipsCode ac_put_draw_env(MipsAtomBuilder_R ab, U4 reg_transfer, U4 reg_base, U2 port)
-MipsAtomComp_Proc_(ac_put_draw_env, ab, {
+MipsAtomComp_Proc_(ab, {
 	/*
 	* ORIGIN: each code word corresponds to the EXACT value libpsyx's PutDrawEnv function would compute for the same DrawEnv settings.
 	* References:

scripts/build_psyq.ps1

@@ -532,6 +532,7 @@ function build-hello_camera {
 
 	$compile_args = @()
 	$compile_args += $f_debug
+	$compile_args += ($f_define + 'BUILD_DEBUG')
 	$compile_args += $f_optimize_none
 	# $compile_args += $f_optimize_intrinsics
 	# $compile_args += $f_optimize_size

scripts/duffle.lua

@@ -1014,14 +1014,20 @@ end
 -- Section 7: domain tables
 -- ════════════════════════════════════════════════════════════════════════════
 
--- The annotation DSL has been reduced to a single annotation macro: atom_info(atom_bind(Binds_X), atom_reads(...), atom_writes(...))
+-- atom_info sub-calls: atom_bind, atom_reads, atom_writes, atom_view, atom_reg_types, atom_ctx, atom_phase.
--- All phase / region / cadence / async / resource / group tokens have been dropped.
--- They may be reintroduced later as optional sub-calls of atom_info;
--- For now, the parser only recognizes atom_info + its three sub-calls (atom_bind, atom_reads, atom_writes).
 M.TAPE_ATOM_MACROS = {
 	["atom_info"] = { kind = "info", binds = false },
 }
 
+-- Empty C macros that prefix the next encoder. Zero words.
+-- BdSlot_ nop is one nop word. The marker is not the BD instruction.
+M.DELAY_MARKERS = {
+	["GteDelay_"] = true,
+	["LdSlot_"]   = true,
+	["BdSlot_"]   = true,
+	["DmaSlot_"]  = true,
+}
+
 -- GTE command-alias resolution table.
 --
 -- Maps every source-side GTE command macro to its canonical short ident.
@@ -1328,6 +1334,12 @@ M.GTE_CR_ALIAS_GROUPS = {
 	{ 26, { "gte_cr_BBK", "gte_cr_H"   } },   -- background B vs projection plane distance H
 }
 
+-- Packed RT slots named by the gte.h packed-slot comment.
+-- first must be written before second.
+M.GTE_PACKED_SLOT_RELATIONS = {
+	{ slot = 2, first = "gte_cr_RT13", second = "gte_cr_RT22" },
+}
+
 -- Operand-class table for the COP2->GPR load-delay check.
 -- Maps each emitting-token ident to the set of GPR operand positions it reads.
 -- Covers the current encoder vocabulary (`code/duffle/mips.h` + `code/duffle/gte.h`); add rows here as new encoders land.
@@ -1589,6 +1601,8 @@ M.INSTRUCTION_LATENCY = {
 	["atom_bind"]           = 0,
 	["atom_reads"]          = 0,
 	["atom_writes"]         = 0,
+	["BdSlot_"]             = 0,
+	["LdSlot_"]             = 0,
 }
 
 -- Default cycle cost for unknown macros.
@@ -1962,6 +1976,52 @@ M.INSTRUCTION_GPR_EFFECTS = {
 	shift_aright_var        = { reads = {2, 3}, writes = {1} },
 }
 
+-------------------------------------------------------------------------------
+-- IMMEDIATE_FIELD_WIDTHS — maps instruction names to their immediate-argument
+-- positions (1-based) and field widths (in bits). Consumed by the
+-- `immediate_field_width` static-analysis check. Parallel to
+-- INSTRUCTION_GPR_EFFECTS.
+--
+-- `signed = true` means the field is sign-extended (the value must fit in
+-- the signed range). `signed = false` (default) means zero-extended.
+-------------------------------------------------------------------------------
+M.IMMEDIATE_FIELD_WIDTHS = {
+    -- CPU I-type immediates: 16-bit signed (addiu/addi/slti sign-extend)
+    add_ui      = { { arg = 3, width = 16, signed = true } },
+    add_si      = { { arg = 3, width = 16, signed = true } },
+    add_ui_self = { { arg = 2, width = 16, signed = true } },
+    slt_si      = { { arg = 3, width = 16, signed = true } },
+    slt_ui      = { { arg = 3, width = 16, signed = true } },
+    -- CPU I-type immediates: 16-bit unsigned (andi/ori/xori zero-extend)
+    and_i       = { { arg = 3, width = 16 } },
+    or_i        = { { arg = 3, width = 16 } },
+    or_i_self   = { { arg = 2, width = 16 } },
+    xor_i       = { { arg = 3, width = 16 } },
+    load_upper_i = { { arg = 2, width = 16 } },
+    -- Load/store offsets: 16-bit signed
+    load_word    = { { arg = 3, width = 16, signed = true } },
+    load_half    = { { arg = 3, width = 16, signed = true } },
+    load_half_u  = { { arg = 3, width = 16, signed = true } },
+    load_byte    = { { arg = 3, width = 16, signed = true } },
+    load_byte_u  = { { arg = 3, width = 16, signed = true } },
+    store_word   = { { arg = 3, width = 16, signed = true } },
+    store_half   = { { arg = 3, width = 16, signed = true } },
+    store_byte   = { { arg = 3, width = 16, signed = true } },
+    -- Shift amount: 5-bit unsigned
+    shift_lleft      = { { arg = 3, width = 5 } },
+    shift_lleft_self = { { arg = 2, width = 5 } },
+    shift_lright     = { { arg = 3, width = 5 } },
+    shift_aright     = { { arg = 3, width = 5 } },
+    shift_aright_var = { { arg = 3, width = 5 } },
+    -- Branch offsets: 16-bit signed
+    branch_equal   = { { arg = 3, width = 16, signed = true } },
+    branch_ne      = { { arg = 3, width = 16, signed = true } },
+    branch_le_zero = { { arg = 2, width = 16, signed = true } },
+    branch_lt_zero = { { arg = 2, width = 16, signed = true } },
+    branch_ge_zero = { { arg = 2, width = 16, signed = true } },
+    branch_gt_zero = { { arg = 2, width = 16, signed = true } },
+}
+
 -- Bounded GPR-value rules consumed by the same forward event walk as `INSTRUCTION_GPR_EFFECTS`.
 -- A rule describes a literal/constant-producing transform; if its required inputs are not constant, the destination is invalidated rather than carrying a stale value.
 -- The lattice is deliberately closed to `{kind = "unknown"}` and `{kind = "constant", value = <U4>}`.
@@ -2188,6 +2248,43 @@ local function _project_emission_inner(root_body_entry, ctx_table)
 	local invocation_stack = {}   -- stack of currently-open invocation records
 	local next_inv_id      = 0
 
+	local reg_use_schema = ctx_table.reg_use_schema
+	local reg_use_param  = ctx_table.reg_use_param
+	local atom_name      = ctx_table.atom_name
+
+	local slot_readonly = {}
+	if reg_use_schema then
+		for _, slot in ipairs(reg_use_schema.slots or {}) do
+			slot_readonly[slot.name] = slot.readonly == true
+		end
+	end
+
+	local function apply_sub(sub_map, operand)
+		if not (sub_map and type(operand) == "string") then return operand end
+		if sub_map[operand] then return sub_map[operand] end
+		local dot = operand:find(".", 1, true)
+		if dot then
+			local head = operand:sub(1, dot - 1)
+			local mapped = sub_map[head]
+			if type(mapped) == "string" then
+				return mapped .. operand:sub(dot)
+			end
+		end
+		return operand
+	end
+
+	local function resolve_gpr_key(operand)
+		if type(operand) ~= "string" then return nil end
+		if operand:sub(1, 2) == "R_" then return operand end
+		if not (reg_use_schema and reg_use_param) then return nil end
+		local prefix = reg_use_param .. "."
+		if operand:sub(1, #prefix) ~= prefix then return nil end
+		local member_path = operand:sub(#prefix + 1)
+		local slot = reg_use_schema.alias_to_slot[member_path]
+		if not slot then return nil, member_path end
+		return "reguse:" .. atom_name .. ":" .. slot, nil, slot
+	end
+
 	local function open_invocation_ids_snapshot()
 		local ids = {}
 		for _, inv in ipairs(invocation_stack) do
@@ -2198,7 +2295,7 @@ local function _project_emission_inner(root_body_entry, ctx_table)
 
 	local function emit_word(encoder, args, line, word_call_text,
 		def_source_now, def_line_now,
-		immediate_call_text, root_call_text_w)
+		immediate_call_text, root_call_text_w, sub_map)
 		local inv_ids   = open_invocation_ids_snapshot()
 		local outermost = inv_ids[1] or 0
 		-- For words emitted at the root atom body, `immediate_call_text` is nil and the walker's `word_call_text` (the word's own token, e.g. "nop") becomes the effective call_text.
@@ -2206,6 +2303,42 @@ local function _project_emission_inner(root_body_entry, ctx_table)
 		-- The call that triggered the body expansion we're currently walking.
 		local eff_call_text      = immediate_call_text or word_call_text
 		local eff_root_call_text = root_call_text_w
+		local gpr_keys = nil
+		if reg_use_schema or sub_map then
+			gpr_keys = {}
+			for pos, arg in ipairs(args or {}) do
+				local effective = apply_sub(sub_map, arg)
+				local key, unresolved, slot = resolve_gpr_key(effective)
+				gpr_keys[pos] = key
+				if unresolved then
+					errors[#errors + 1] = {
+						kind = "reguse_unresolved",
+						line = line,
+						msg  = string.format("RegUse operand %q does not resolve in schema %q",
+							effective, (reg_use_schema and reg_use_schema.name) or "?"),
+					}
+				end
+				if key and slot and slot_readonly[slot] then
+					local effects = M.INSTRUCTION_GPR_EFFECTS or {}
+					local row = effects[encoder]
+					if row and row.writes then
+						for _, wpos in ipairs(row.writes) do
+							if wpos == pos then
+								errors[#errors + 1] = {
+									kind = "reguse_const_write",
+									line = line,
+									msg  = string.format("RegUse slot %q is Reg const; %s writes it",
+										slot, encoder),
+								}
+							end
+						end
+					end
+				end
+			end
+		end
+		if not reg_use_schema then
+			gpr_keys = nil
+		end
 		items[#items + 1] = {
 			kind                     = "word",
 			encoder                  = encoder,
@@ -2217,6 +2350,7 @@ local function _project_emission_inner(root_body_entry, ctx_table)
 			root_call_text           = eff_root_call_text,
 			invocation_ids           = inv_ids,
 			outermost_invocation_id  = outermost,
+			gpr_keys                 = gpr_keys,
 		}
 		word_events[#word_events + 1] = {
 			i                        = word_idx,
@@ -2229,6 +2363,7 @@ local function _project_emission_inner(root_body_entry, ctx_table)
 			invocation_ids           = inv_ids,
 			outermost_invocation_id  = outermost,
 			word_count               = 1,
+			gpr_keys                 = gpr_keys,
 		}
 		word_idx = word_idx + 1
 	end
@@ -2332,6 +2467,15 @@ local function _project_emission_inner(root_body_entry, ctx_table)
 				pos = (next_pos > pos) and next_pos or (pos + 1)
 				goto continue_loop
 			end
+			if M.DELAY_MARKERS[ident] then
+				local arg_pos = nil
+				if consuming_encoder and consuming_paren then
+					arg_pos = count_top_level_commas(tok, consuming_paren + 1, pos) + 1
+				end
+				emit_marker("delay", ident, nil, tok_line, nil, nil, consuming_encoder, arg_pos)
+				pos = after
+				goto continue_loop
+			end
 			if ident ~= "atom_label" and ident ~= "atom_offset" then
 				-- Ordinary ident; nothing to emit, step past the ident only.
 				pos = after
@@ -2472,14 +2616,24 @@ local function _project_emission_inner(root_body_entry, ctx_table)
 		local line_of    = body_entry.line_of or M.LineIndex("")
 		local def_source = body_entry.source or ""
 		local def_line   = body_entry.declaration or 0
+		local sub_map    = body_entry.sub_map
 		-- Per-token dispatch: each matched branch returns; only the fall-through
 		-- "opaque word" emit handles direct encoders + mac_X-without-component.
 		local function process_token(bt)
 			local tok = M.trim(bt.tok or "")
 			if tok == "" then return end
-			local ident    = M.read_ident(tok, 1) or "?"
+			local ident, after = M.read_ident(tok, 1)
+			if not ident then ident = "?" end
 			local _, args  = token_ident_and_args(tok)
 			local tok_line = line_of(body_off + bt.rel) or 0
+			if M.DELAY_MARKERS[ident] then
+				emit_marker("delay", ident, nil, tok_line)
+				local rest = M.trim(tok:sub(after or (#tok + 1)))
+				if rest ~= "" then
+					process_token({ tok = rest, rel = bt.rel })
+				end
+				return
+			end
 			-- embedded markers live only in non-marker tokens.
 			-- Pass `ident` as the consuming instruction so `emit_embedded_markers` can compute each marker's arg position + record the consuming_encoder for the offsets pass.
 			-- Canonicalize `jump_rel` to `branch_equal` (its preprocessor-expanded form) so the `consuming_encoder` metadata in marker records is canonical. 
@@ -2527,12 +2681,22 @@ local function _project_emission_inner(root_body_entry, ctx_table)
 					-- Propagate trackers into the recursive walk:
 					--   immediate_call_text = this call's tok (the IMMEDIATE outer call for words emitted in this body)
 					--   root_call_text      = the OUTERMOST call (immutable across the recursion)
+					local formal_names = ctx_table.component_index[bare]
+						and ctx_table.component_index[bare].arg_names
+					local child_map = nil
+					if formal_names then
+						child_map = {}
+						for i, fname in ipairs(formal_names) do
+							child_map[fname] = apply_sub(sub_map, args[i])
+						end
+					end
 					walk_body_entry({
 							body_tokens = comp.body_tokens or {},
 							body_off    = comp.body_off or 0,
 							line_of     = comp.line_of,
 							source      = comp.source,
 							declaration = comp.declaration,
+							sub_map     = child_map,
 						},
 						inv.id,
 						invocation_root_call_text,
@@ -2570,7 +2734,7 @@ local function _project_emission_inner(root_body_entry, ctx_table)
 			local n         = resolve_count(ident, tok_line)
 			local out_ident = (ident == "nop2") and "nop" or ident
 			for _ = 1, n do
-				emit_word(out_ident, args, tok_line, tok, def_source, def_line, walk_immediate_call_text, walk_root_call_text)
+				emit_word(out_ident, args, tok_line, tok, def_source, def_line, walk_immediate_call_text, walk_root_call_text, sub_map)
 			end
 		end
 		
@@ -2617,6 +2781,7 @@ end
 ---     `nop2` is normalized to encoder `nop` (per the spec).
 ---   * `atom_label(F)` markers: one `label` item with `name = "F"`, `word_index = current word_idx`; zero-width (does NOT advance word_idx).
 ---   * `atom_offset(B, T)` markers: one `offset` item with `name = "B"`, `target = "T"`, `word_index = current word_idx`; zero-width.
+---   * Delay markers (`GteDelay_` / `LdSlot_` / `BdSlot_` / `DmaSlot_`): one `delay` item; zero-width. The following encoder is the next token.
 ---   * `mac_X(...)` calls: emit `invoke_begin` (zero-width), recurse into the component body, emit `invoke_end` (zero-width).
 ---     The component body's words land between the begin/end pair; one invocation record is allocated per call (monotonic ID per atom).
 ---   * Unknown uncounted macros emit 1 opaque word + one warning per occurrence.
@@ -2635,7 +2800,7 @@ end
 --- @param components      table   -- bare-name → component definition (corpus.components); REQUIRED — consumed at the invocation-construction site to stamp
 ---                                   `invocation.debug_skip`. A missing or non-table `components` raises a fail-loud error rather than silently falling back.
 --- @return EmissionProjection
-function M.project_emission(body_text, component_index, word_counts, components)
+function M.project_emission(body_text, component_index, word_counts, components, reg_use_ctx)
 	-- The recursive walk delegates to `_project_emission_inner` so component bodies (which arrive as
 	-- `{body_tokens, body_off, line_of, source, declaration}` records from `corpus.component_body_index`)
 	-- re-enter the same walker with the same shared output state.
@@ -2678,7 +2843,151 @@ function M.project_emission(body_text, component_index, word_counts, components)
 		component_index = component_index or {},
 		word_counts     = word_counts     or {},
 		components      = components,
+		reg_use_schema  = reg_use_ctx and reg_use_ctx.reg_use_schema,
+		reg_use_param   = reg_use_ctx and reg_use_ctx.reg_use_param,
+		atom_name       = reg_use_ctx and reg_use_ctx.atom_name,
+		schema_name     = reg_use_ctx and reg_use_ctx.schema_name,
 	})
 end
 
-return M
+-------------------------------------------------------------------------------
+-- find_function_decl_for — backward walk for MipsAtomComp_Proc_ name extraction.
+--
+-- After the `sym` arg was dropped from MipsAtomComp_Proc_, the component name
+-- is derived from the preceding `FI_ Slice_MipsCode ac_X(args)` function
+-- declaration. This function walks backward from `before_pos` to find it.
+--
+-- Returns (raw_name, args_inner) or (nil, nil).
+--   raw_name   — e.g. "ac_load_word_imm"
+--   args_inner — e.g. "AtomBuilder_R ab, Reg dst, U4 imm"
+--
+-- The walk finds the LAST "Slice_MipsCode" before before_pos, then skips
+-- whitespace + qualifiers (FI_, atom_dbg_skip, comments) until it finds an
+-- ident followed by "(". That ident is the function name; the parens contents
+-- are the args.
+-------------------------------------------------------------------------------
+function M.find_function_decl_for(source, before_pos, slice_mips_code_len)
+	local search_pos = 1
+	local last_match = nil
+	while true do
+		local found = source:find("Slice_MipsCode", search_pos, true)
+		if not found or found >= before_pos then break end
+		last_match = found
+		search_pos = found + slice_mips_code_len
+	end
+	if not last_match then return nil, nil end
+
+	local pos = last_match + slice_mips_code_len
+	while pos < before_pos do
+		-- skip whitespace
+		while pos <= #source do
+			local c = source:sub(pos, pos)
+			if c == " " or c == "\t" or c == "\n" or c == "\r" then
+				pos = pos + 1
+			else
+				break
+			end
+		end
+		if pos > #source then break end
+		-- skip line comments
+		if source:sub(pos, pos + 1) == "//" then
+			while pos <= #source and source:sub(pos, pos) ~= "\n" do pos = pos + 1 end
+			pos = pos + 1
+			goto continue
+		end
+		-- skip block comments
+		if source:sub(pos, pos + 1) == "/*" then
+			local close = source:find("*/", pos + 2, true)
+			if not close then break end
+			pos = close + 2
+			goto continue
+		end
+		-- try to read an ident
+		local ident, ident_end = M.read_ident(source, pos)
+		if not ident then break end
+		-- check if the next non-ws char after ident is "("
+		local next_pos = M.skip_ws_and_cmt(source, ident_end)
+		if source:sub(next_pos, next_pos) == "(" then
+			local inner = M.read_parens(source, next_pos)
+			if inner then
+				return ident, inner
+			end
+		end
+		-- ident not followed by "(" — it's a qualifier (FI_, atom_dbg_skip, etc); skip it
+		pos = ident_end
+		::continue::
+	end
+	return nil, nil
+end
+
+-------------------------------------------------------------------------------
+-- find_atom_proc_decl_for — backward walk for MipsAtom_Proc_ name extraction.
+--
+-- The atom name is the preceding `MipsAtom* ident(args)` function ident.
+-- This function walks backward from `before_pos` to find it.
+--
+-- Returns (raw_name, args_inner, func_ident, after_paren) or (nil, nil).
+--   raw_name    — the function ident as written
+--   args_inner  — e.g. "AtomArena_R aa, U4 r_scratch, ..."
+--   after_paren — source position after the function `)`
+--
+-- The walk finds the LAST "MipsAtom*" before before_pos, then skips
+-- whitespace + qualifiers (internal, I_, FI_, comments) until it finds an
+-- ident followed by "(". That ident is the name. The parens contents are the args.
+-------------------------------------------------------------------------------
+function M.find_atom_proc_decl_for(source, before_pos, mips_atom_ptr_len)
+	local search_pos = 1
+	local last_match = nil
+	while true do
+		-- plain=true: "*" is literal, no escaping needed
+		local found = source:find("MipsAtom*", search_pos, true)
+		if not found or found >= before_pos then break end
+		last_match = found
+		search_pos = found + mips_atom_ptr_len
+	end
+	if not last_match then return nil, nil end
+
+	local pos = last_match + mips_atom_ptr_len
+	while pos < before_pos do
+		-- skip whitespace
+		while pos <= #source do
+			local c = source:sub(pos, pos)
+			if c == " " or c == "\t" or c == "\n" or c == "\r" then
+				pos = pos + 1
+			else
+				break
+			end
+		end
+		if pos > #source then break end
+		-- skip line comments
+		if source:sub(pos, pos + 1) == "//" then
+			while pos <= #source and source:sub(pos, pos) ~= "\n" do pos = pos + 1 end
+			pos = pos + 1
+			goto continue
+		end
+		-- skip block comments
+		if source:sub(pos, pos + 1) == "/*" then
+			local close = source:find("*/", pos + 2, true)
+			if not close then break end
+			pos = close + 2
+			goto continue
+		end
+		-- try to read an ident
+		local ident, ident_end = M.read_ident(source, pos)
+		if not ident then break end
+		-- check if the next non-ws char after ident is "("
+		local next_pos = M.skip_ws_and_cmt(source, ident_end)
+		if source:sub(next_pos, next_pos) == "(" then
+			local inner, after_paren = M.read_parens(source, next_pos)
+			if inner then
+				return ident, inner, ident, after_paren
+			end
+		end
+		-- ident not followed by "(" — it's a qualifier; skip it
+		pos = ident_end
+		::continue::
+	end
+	return nil, nil
+end
+
+	return M

scripts/elf_dwarf.lua

@@ -612,13 +612,13 @@ function M.read_elf_sections(elf_path, section_names)
 end
 
 --- Read ELF symbol addresses by walking the `.symtab` + `.strtab` sections directly (no `nm` subprocess). 
---- Returns a map `{name -> {addr, size_bytes}}` for every `code_<name>` symbol.
+--- Returns a map `{name -> {addr, size_bytes}}` for every defined symbol.
 ---
 --- **Conventions:**
 --- - ELF32 symtab entry = 16 bytes (`st_name:4 + st_value:4 + st_size:4 + st_info:1 + st_other:1 + st_shndx:2`); offsets within each entry are zero-based wire offsets.
 --- - Direct Lua `string.byte`/`string.sub`/`string.find` boundaries receive `+ 1`.
 --- - We filter on STB_GLOBAL (high nibble of st_info = 1) to match `nm`'s default (external symbols only). STB_WEAK excluded.
---- - The `code_` prefix is stripped (MipsAtom_ macros emit bare atom names, no `code_` prefix).
+--- - Keys are the ELF symbol names as written (the C ident).
 --- - `st_size > 0` filter excludes undefined/imported symbols.
 ---
 --- @param elf_path Path

scripts/gdb/gdb_tape_atoms.gdb

@@ -16,7 +16,7 @@ define tape_atoms
   echo "[gdb_tape_atoms] STUB: run .\\build_psyq.ps1 to regenerate, then re-source this file."
 end
 document tape_atoms
-  List every tape atom symbol in the loaded ELF (code_<name>) with its .rodata address and word count.
+  List every tape atom symbol in the loaded ELF with its .rodata address and word count.
   STUB state: runtime file not sourced. Run build_psyq.ps1 to regenerate.
 end
 

scripts/passes/annotation.lua

@@ -477,8 +477,8 @@ local function validate(ctx, src, corpus_pipe_ctx)
 	-- Project the pre-scanned atoms to the AtomEntry shape this pass needs.
 	local atoms = {}
 	for _, a in ipairs(scan.atoms) do
-		if a.kind == "atom" then
+		if a.kind == "atom" or a.kind == "atom_proc" then
-			atoms[#atoms + 1] = { line = a.line, name = a.raw_name }
+			atoms[#atoms + 1] = { line = a.line, name = a.raw_name or a.name }
 		end
 	end
 

scripts/passes/atoms_source_map.lua

@@ -83,6 +83,7 @@ local function canonical_word_entries(atom)
 			line       = event.call_line or item.line or 0,
 			text       = event.call_text or item.call_text or "",
 			body_line  = event.body_line or item.body_line or item.line or 0,
+			gpr_keys   = event.gpr_keys,
 			invocation = (event.outermost_invocation_id
 				and paths.invocations
 				and paths.invocations[event.outermost_invocation_id]) or nil,
@@ -260,12 +261,12 @@ local function append_gdb_commands(lines, matched)
 	for _, a in ipairs(matched) do
 		-- gdb 12.1 quirk: literals in printf args require an attached target.
 		-- Use the per-atom convenience vars set above as printf args.
-		lines[#lines + 1] = string.format('  printf "  code_%%-32s @ 0x%%08x  %%4d words\\n", $__atom_name_%d, $__atom_addr_%d, $__atom_words_%d',
+		lines[#lines + 1] = string.format('  printf "  %%-32s @ 0x%%08x  %%4d words\\n", $__atom_name_%d, $__atom_addr_%d, $__atom_words_%d',
 			a.idx, a.idx, a.idx)
 	end
 	lines[#lines + 1] = "end"
 	lines[#lines + 1] = "document tape_atoms"
-	lines[#lines + 1] = "  List every tape atom symbol in the loaded ELF (code_<name>) with .rodata addr + word count."
+	lines[#lines + 1] = "  List every tape atom symbol in the loaded ELF with .rodata addr + word count."
 	lines[#lines + 1] = "end"
 	lines[#lines + 1] = ""
 
@@ -284,10 +285,10 @@ local function append_gdb_commands(lines, matched)
 	for _, a in ipairs(matched) do
 		lines[#lines + 1] = string.format("define break_atom_%s", a.name)
 		lines[#lines + 1] = string.format("  break *$__atom_addr_%d", a.idx)
-		lines[#lines + 1] = string.format('  printf "  Breakpoint set at code_%s (0x%%08x)\\n", $__atom_addr_%d', a.name, a.idx)
+		lines[#lines + 1] = string.format('  printf "  Breakpoint set at %s (0x%%08x)\\n", $__atom_addr_%d', a.name, a.idx)
 		lines[#lines + 1] = "end"
 		lines[#lines + 1] = string.format("document break_atom_%s", a.name)
-		lines[#lines + 1] = string.format("  Set a breakpoint at code_%s.", a.name)
+		lines[#lines + 1] = string.format("  Set a breakpoint at %s.", a.name)
 		lines[#lines + 1] = "end"
 		lines[#lines + 1] = ""
 	end
@@ -322,7 +323,7 @@ local function append_gdb_commands(lines, matched)
 		-- Precompute end_addr (gdb 12.1's expression evaluator chokes on `addr + words*4`).
 		lines[#lines + 1] = string.format("  set $__end_%d = $__atom_addr_%d + $__atom_words_%d * 4", a.idx, a.idx, a.idx)
 		lines[#lines + 1] = string.format("  if $__pc >= $__atom_addr_%d && $__pc < $__end_%d", a.idx, a.idx)
-		lines[#lines + 1] = string.format('    printf "atom:    code_%%s\\n", $__atom_name_%d', a.idx)
+		lines[#lines + 1] = string.format('    printf "atom:    %%s\\n", $__atom_name_%d', a.idx)
 		lines[#lines + 1] = '    printf "addr:    0x%08x\\n", $__pc'
 		lines[#lines + 1] = string.format("    set $__word = ($__pc - $__atom_addr_%d) / 4", a.idx)
 		lines[#lines + 1] = string.format('    printf "word:    %%d/%%d\\n", $__word, $__atom_words_%d', a.idx)
@@ -491,8 +492,19 @@ function M.render_atom_source_map(atom)
 	local lines = {}
 	lines[#lines + 1] = string.format("ATOM %s  %d", (atom.raw_name or atom.name), total)
 	for _, entry in ipairs(entries) do
-		lines[#lines + 1] = string.format("WORD %d  LINE %d  TEXT %s",
+		local word_line = string.format("WORD %d  LINE %d  TEXT %s",
 			entry.pos, entry.line, entry.text)
+		local keys = {}
+		for pos = 1, 16 do
+			local k = entry.gpr_keys and entry.gpr_keys[pos]
+			if type(k) == "string" and k:sub(1, 7) == "reguse:" then
+				keys[#keys + 1] = k
+			end
+		end
+		if #keys > 0 then
+			word_line = word_line .. "  KEYS " .. table.concat(keys, ",")
+		end
+		lines[#lines + 1] = word_line
 	end
 	lines[#lines + 1] = "ENDATOM"
 	return table.concat(lines, "\n") .. "\n"
@@ -529,7 +541,7 @@ function M.render_atom_provenance(atom, wc, rel_path)
 	return table.concat(lines, "\n") .. "\n"
 end
 
---- Pass entry. For each source that declares at least one `MipsAtom_(name)` / `MipsCode code_<name>`,
+--- Pass entry. For each source that declares at least one tape atom,
 --- emit two files in `<out_root>/`: `<basename>.atoms.sourcemap.txt` (per-word call-site map) and `<basename>.atoms.provenance.txt`
 --- (per-word definition + body line, resolved via the outermost `mac_X(...)` invocation).
 --- When `ctx.flags.gdb_runtime` is true and `ctx.flags.elf_path` exists, also emit the post-link gdb script `<ctx.out_root>/gdb_tape_atoms_runtime.gdb`.

scripts/passes/components.lua

@@ -7,7 +7,7 @@
 --- then resolves the function-args string from the preceding `FI_ Slice_MipsCode ac_X(...)` declaration via a backward walk.
 ---
 --- `MipsAtom_Proc_(X, ab, { body })` declarations (kind="atom_proc") are ATOMS, not components, and are deliberately excluded —
---- atoms get emitted via `tb_emit(tb, code_<name>)` linker symbols, not inlined as `mac_*` macros.
+--- the ELF symbol is the C ident. Raw `MipsCode code_*` is leftover, not the atom rule.
 ---
 --- Emits one `gen/macs.h` per *immediate source directory* with `#define mac_X(sig) \` macros plus `WORD_COUNT(mac_X, N)` entries for downstream offset computation.
 --- All sources inside the same directory contribute to the same file (per-directory aggregation).
@@ -96,48 +96,21 @@ local M = {}
 -- so this file reads it forward rather than re-walking the source.
 -- ════════════════════════════════════════════════════════════════════════════
 
---- Find the args of the function declaration that immediately precedes a `MipsAtomComp_Proc_` invocation of the given name.
+--- Find the args of the function declaration that immediately precedes a `MipsAtomComp_Proc_` invocation.
 --- Returns the args string (e.g., `"U4 off, U4 code, U1 r, U1 g, U1 b"`) or nil if no function declaration is found.
 ---
---- Convention: function form is
+--- After the `sym` arg was dropped from MipsAtomComp_Proc_, the component name
----   `FI_ Slice_MipsCode ac_X(args) MipsAtomComp_Proc_(ac_X, { body })`
+--- and the args both come from the preceding `FI_ Slice_MipsCode ac_X(args)`
---- We find the LAST occurrence of `"ac_X("` before `before_pos` and extract the args from inside the parens.
+--- declaration. The shared `duffle.find_function_decl_for` helper does the
---- We then verify the preceding context ends with `Slice_MipsCode`
+--- backward walk; this function returns just the args.
---- (the function-decl keyword with possible qualifiers between).
 ---
 --- @param source     string
---- @param name       string
+--- @param name       string  (retained for signature stability; unused — the walk derives the name)
 --- @param before_pos integer
 --- @return string|nil
 local function find_function_args_for(source, name, before_pos)
-	-- Find the LAST occurrence of `name + "("` in `source[1..before_pos]`.
+	local _, args_inner = duffle.find_function_decl_for(source, before_pos, #MIPS_ATOM)
-	local name_open  = name .. "("
+	return args_inner
-	local last_idx   = nil
-	local scan_pos   = 1
-	while true do
-		-- Pass `before_pos + 1` so string.find only returns positions < before_pos + 1
-		-- (string.find's 4th arg `plain` is true; we use the 3rd arg `init` for the upper bound).
-		local found = source:find(name_open, scan_pos, true)
-		if not found or found >= before_pos then break end
-		last_idx = found
-		scan_pos = found + #name_open
-	end
-	if not last_idx then return nil end
-
-	-- Verify the preceding context ends with "MipsAtom" (with possible qualifiers between).
-	local before   = source:sub(1, last_idx - 1)
-	local trimmed  = duffle.trim(before)
-	if trimmed:sub(-#MIPS_ATOM) ~= MIPS_ATOM then
-		-- Preceding context is not a function declaration.
-		return nil
-	end
-
-	local open_paren = last_idx + #name  -- position of "("
-	-- scan: MipsAtom ac_X(
-	local inner      = duffle.read_parens(source, open_paren)
-	-- scan: MipsAtom ac_X(<args>)
-	if not inner then return nil end
-	return inner
 end
 
 -- ════════════════════════════════════════════════════════════════════════════
@@ -186,6 +159,14 @@ local function extract_arg_names(args_str)
 	return names
 end
 
+local function formal_arg_names(args_str)
+	local names = extract_arg_names(args_str)
+	if not names then return nil end
+	if names[1] == "ab" then table.remove(names, 1) end
+	if #names == 0 then return nil end
+	return names
+end
+
 -- ════════════════════════════════════════════════════════════════════════════
 -- Component projection (read from pre-scanned SourceScan)
 -- ════════════════════════════════════════════════════════════════════════════
@@ -206,7 +187,7 @@ local function project_components(source, scan)
 		-- Only `MipsAtomComp_(ac_X)` (kind="comp_bare") and `MipsAtomComp_Proc_(ac_X, ...)` (kind="comp_proc")
 		-- are COMPONENTS — they get inlined via `mac_<name>` aliases inside atom bodies.
 		-- `MipsAtom_Proc_` (kind="atom_proc") is an ATOM (ends with `mac_yield()`); it gets emitted via
-		-- `tb_emit(tb, code_<name>)` (linker symbol), NOT inlined as a macro. Including `atom_proc` here
+		-- `tb_emit` of the C ident, NOT inlined as a macro. Including `atom_proc` here
 		-- would incorrectly emit `mac_<name>` aliases for atoms, polluting `gen/macs.h`.
 		-- See `docs/duffle_dsl_primer.md` §"mac_* aliases" for the contract.
 		if a.kind == "comp_bare" or a.kind == "comp_proc" then
@@ -224,6 +205,7 @@ local function project_components(source, scan)
 				body_off    = a.body_off,
 				body_tokens = a.body_tokens,
 				args        = args,
+				arg_names   = formal_arg_names(args),
 				comment     = comment,
 				kind        = a.kind,  -- "comp_bare" | "comp_proc"; provenance emitter reads this.
 				debug_skip  = a.debug_skip == true,
@@ -411,6 +393,10 @@ end
 --- @param cache        table<string, integer>
 --- @return integer
 local function gp0_contrib_rec(name, comp_by_name, cache)
+	if name:match("^insert_ot_tag") then
+		cache[name] = 0
+		return 0
+	end
 	if cache[name] ~= nil then return cache[name] end
 	cache[name] = -1
 	local cc = comp_by_name[name]
@@ -426,8 +412,15 @@ local function gp0_contrib_rec(name, comp_by_name, cache)
 					-- Nested `mac_X(...)` call: recurse.
 					local nested = ident:sub(MAC_PREFIX_LEN + 1)
 					n = n + gp0_contrib_rec(nested, comp_by_name, cache)
+				elseif ident == "gte_sw" then
+					n = n + 1
 				elseif ident == "store_word" or ident == "store_half" or ident == "store_byte" then
-					if trimmed:find("R_PrimCursor", 1, true) then
+					if trimmed:find("R_PrimCursor", 1, true)
+						or trimmed:find("O_(Poly_", 1, true)
+						or trimmed:find("r_prim_cursor", 1, true)
+						or trimmed:find("r_primitive_cursor", 1, true)
+						or trimmed:find("r_base", 1, true)
+					then
 						n = n + 1
 					end
 				end
@@ -493,18 +486,9 @@ end
 --- @param args_str string|nil
 --- @return string
 local function signature_from_args(args_str)
-	local arg_names = extract_arg_names(args_str)
+	local names = formal_arg_names(args_str)
-	if    arg_names and #arg_names > 0 then
+	if names then
-		-- Drop the leading `ab` (atom-builder) first arg if present.
+		return table.concat(names, ", ")
-		-- Convention: `MipsAtomComp_Proc_` components always declare `ab` as the first function-arg
-		-- (type `MipsAtomBuilder_R`), mirroring the macro signature in `lottes_tape.h`.
-		if arg_names[1] == "ab" then
-			table.remove(arg_names, 1)
-		end
-		if #arg_names > 0 then
-			return table.concat(arg_names, ", ")
-		end
-		return "..."  -- `ab` was the only arg; fall through to variadic
 	end
 	return "..."
 end
@@ -737,6 +721,7 @@ local function update_canonical_component_body_index(corpus, src, components, sc
 				source      = src.path,
 				declaration = c.line,
 				kind        = c.kind,
+				arg_names   = c.arg_names,
 			}
 		end
 	end

scripts/passes/dwarf_injection.lua

@@ -2,7 +2,7 @@
 ---
 --- Reads the post-link ELF directly (io.open; walks the ELF32 section header table to find
 --- `.debug_info` + `.debug_abbrev` + `.debug_str` + `.debug_line` + `.debug_aranges` + `.debug_rnglists`),
---- APPENDS synthetic DWARF line-program sequences for every `code_<name>` atom, EXTENDS the `.debug_aranges`
+--- APPENDS synthetic DWARF line-program sequences for every tape atom, EXTENDS the `.debug_aranges`
 --- and main-CU range tables with the atom ranges, and INSERTS synthetic atom/component DIE children into the
 --- existing main compilation unit in `.debug_info` (no second compilation unit).
 --- Per-atom `DW_TAG_subprogram` + per-register `DW_TAG_variable` entries make
@@ -1344,7 +1344,7 @@ local function build_new_abbrev()
 		attr(   DW_AT_name,         DW_FORM_string)
 	  .. attr(DW_AT_low_pc,       DW_FORM_addr)
 	  .. attr(DW_AT_high_pc,      DW_FORM_addr)
-	  .. attr(DW_AT_linkage_name, DW_FORM_string))  -- equals DW_AT_name; lets gdb's symbol-table lookup resolve to our subprogram (not the gcc global `code_<name>` const U4 array)
+	  .. attr(DW_AT_linkage_name, DW_FORM_string))  -- equals DW_AT_name; gdb resolves the subprogram, not the gcc global array
 
 	local abbrev_variable = abbrev(ABBREV_VARIABLE, DW_TAG_variable, false,  -- DW_CHILDREN_no
 		attr(   DW_AT_name,     DW_FORM_string)
@@ -1857,7 +1857,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
 	end
 
 	-- 4) Emit per-atom DW_TAG_subprograms (children of main CU).
-	--    Subprogram names match nm symbols without a `code_` prefix.
+	--    Subprogram names match the written C ident (the ELF symbol).
 	--    The gcc global `<name>[]` is a DW_TAG_variable without children; our subprogram has the wave-context var children.
 	--    gdb's symbol resolution picks our subprogram (it has low_pc/high_pc + children) over the gcc global for function-context lookups.
 	for _, atom in ipairs(atom_table) do
@@ -2313,5 +2313,6 @@ end
 M.compute_loclists_offsets_for_test     = compute_loclists_offsets
 M.build_debug_loclists_section_for_test = build_debug_loclists_section
 M.tape_piece_size_for_test              = tape_piece_size
+M.build_atom_table_for_test             = build_atom_table
 
 return M

scripts/passes/emission_model.lua

@@ -155,8 +155,28 @@ local function project_atom(atom_record, src, corpus)
 	local body  = atom_record.body or ""
 	local wc    = corpus.word_counts or {}
 	local cbi   = corpus.component_body_index or {}
+	local schema = nil
+	if atom_record.reg_use_schema_name then
+		schema = corpus.reg_use_schemas and corpus.reg_use_schemas[atom_record.reg_use_schema_name]
+	end
 	-- That construction site stamps `invocation.debug_skip` while appending each record to `proj.invocations`.
-	local proj  = duffle.project_emission(body, cbi, wc, corpus.components)
+	local proj  = duffle.project_emission(body, cbi, wc, corpus.components, {
+		reg_use_schema = schema,
+		reg_use_param  = atom_record.reg_use_param_name,
+		atom_name      = atom_record.name,
+		schema_name    = atom_record.reg_use_schema_name,
+	})
+	if atom_record.reg_use_schema_name and not schema then
+		proj.errors[#proj.errors + 1] = {
+			kind = "reguse_missing_schema",
+			msg  = string.format("RegUse schema %q is missing", atom_record.reg_use_schema_name),
+		}
+	end
+	for _, err in ipairs(corpus.reg_use_errors or {}) do
+		if err.schema_name == atom_record.reg_use_schema_name then
+			proj.errors[#proj.errors + 1] = err
+		end
+	end
 	local paths = {
 		tokens       = atom_record.body_tokens or {},
 		line_in_body = duffle.build_body_line_index(body),

scripts/passes/offsets.lua

@@ -1,7 +1,8 @@
 --- passes/offsets.lua — Branch-offset generator.
 ---
 --- Reads the pre-scanned SourceScan payload (produced once upstream by `duffle.scan_source`)
---- for `MipsAtom_(name)` and `MipsCode code_<name>` declarations, computes the word offset
+--- for `MipsAtom_(name)` and leftover `MipsCode code_*` declarations, computes the word offset
+--- (ELF symbol is the C ident; raw `code_*` is leftover, not the atom rule)
 --- from each `atom_offset(F, T)` marker to its target `atom_label(T)` declaration, and emits
 --- `gen/offsets.h` with one `#define _atom_offset_F_T = N` per branch.
 ---

scripts/passes/report.lua

@@ -4,8 +4,8 @@
 ---   - `build/gen/<dir_basename>.annotations.txt` — one per source-directory containing atoms; aggregates across all sources in the directory.
 ---   - `build/gen/annotation_validation.txt` — the project summary.
 ---
---- The annotation pass emits `errors.h` files per module and the canonical `corpus.sources_by_dir` projection groups sources by directory.
+--- The canonical `corpus.sources_by_dir` projection groups sources by directory.
---- This pass iterates the dir projection directly and re-validates each source via `annotation.validate()` to get the detailed per-source results.
+--- This pass builds one ModuleView per directory and walks SECTION_RENDERERS.
 
 -- ════════════════════════════════════════════════════════════════════════════
 -- Module-scope requires + package.path setup
@@ -20,11 +20,6 @@
 local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./"
 local duffle         = dofile(_bootstrap_dir .. "../duffle_paths.lua")
 
--- Load the annotation pass so we can re-validate each source against the canonical corpus projection.
--- The annotation pass exposes `M.validate`, which returns the per-source AnnotationResult (atoms / annots / macros / binds / errors / warnings)
--- that the report pass renders into the per-module `<dir_basename>.annotations.txt` output.
-local annotation = dofile(_bootstrap_dir .. "annotation.lua")
-
 -- Load atoms_source_map for the `render_source_map` / `render_provenance` module functions (used by `render_module_atoms_md` to produce `<module>.atoms.md` without re-walking source tokens).
 -- The pass itself emits no per-source files anymore; we only consume the two pure renderers here.
 -- Defined BEFORE the renderer functions below so their upvalues resolve to this local (not the global `atoms_source_map`, which is nil).
@@ -225,7 +220,7 @@ local function render_module_atoms_md(dir, dir_sources, wc)
 			for _, atom in ipairs(atoms_list) do
 				lines[#lines + 1] = string.format(
 					"### atom: %s (line %d, %d words)",
-					atom.name, atom.line or 0, #(atom.paths.items or {}))
+					atom.name, atom.line or 0, #((atom.paths or {}).word_events or {}))
 				lines[#lines + 1] = ""
 				lines[#lines + 1] = "**Sourcemap** — per-word call site:"
 				lines[#lines + 1] = "```"
@@ -246,17 +241,544 @@ local function render_module_atoms_md(dir, dir_sources, wc)
 	return table.concat(lines, "\n") .. "\n"
 end
 
---- Render the consolidated per-module markdown (`build/<module>.atom_meta_report.md`).
+local function decl_words(atom)
---- Aggregates annotation + static-analysis content across all sources in `dir`.
+	local p = atom.paths or {}
---- Annotations come from re-running `annotation.validate()` per source (the existing pattern);
+	return #(p.word_events or {})
---- static-analysis comes from `corpus.static_analysis_results[dir_basename]` (populated by `static_analysis.lua` — no second corpus_pipe_ctx build).
+end
---- @param dir           string
+
---- @param dir_sources   SourceFile[]
+local function count_kinds(decls)
---- @param annot_results AnnotationResult[]
+	local n = { atom = 0, atom_proc = 0, comp_bare = 0, comp_proc = 0 }
---- @param sa_results    table -- corpus.static_analysis_results[dir_basename]
+	for _, a in ipairs(decls or {}) do
---- @return string
+		if n[a.kind] ~= nil then n[a.kind] = n[a.kind] + 1 end
-local function render_module_meta_report(dir, dir_sources, annot_results, sa_results)
+	end
+	return n
+end
+
+local function slot_suffix(key)
+	if type(key) ~= "string" or key:sub(1, 7) ~= "reguse:" then return nil end
+	return key:match("([^:]+)$")
+end
+
+local function decl_names(view)
+	local names = {}
+	for _, a in ipairs(view.decls or {}) do
+		if a.name then names[a.name] = true end
+	end
+	return names
+end
+
+local function path_in_module(path, view)
+	if type(path) ~= "string" or path == "" then return false end
+	local norm = path:gsub("\\", "/")
+	local dir  = (view.dir or ""):gsub("\\", "/")
+	if dir ~= "" and (norm == dir or norm:sub(1, #dir + 1) == dir .. "/") then
+		return true
+	end
+	for _, src in ipairs(view.sources or {}) do
+		if (src.path or ""):gsub("\\", "/") == norm then return true end
+	end
+	return false
+end
+
+local function build_module_view(dir, dir_sources, corpus)
+	local decls = {}
+	for _, src in ipairs(dir_sources or {}) do
+		for _, a in ipairs((src.scan and src.scan.atoms) or {}) do
+			if not a.source_path then a.source_path = src.path end
+			decls[#decls + 1] = a
+		end
+	end
 	local dir_basename = source_basename(dir)
+	local sa = (corpus.static_analysis_results or {})[dir_basename] or {}
+	local schemas = {}
+	for name, schema in pairs(corpus.reg_use_schemas or {}) do
+		for _, a in ipairs(decls) do
+			if a.reg_use_schema_name == name then
+				schemas[#schemas + 1] = schema
+				break
+			end
+		end
+	end
+	return {
+		dir      = dir,
+		sources  = dir_sources or {},
+		decls    = decls,
+		schemas  = schemas,
+		findings = sa.findings or {},
+		sa       = sa,
+		corpus   = corpus,
+	}
+end
+
+local function render_section_declarations(add, view)
+	if #view.decls == 0 then add("_(none)_"); add(""); return end
+	add("| kind | name | source | line | words | min | max | branches | paths |")
+	add("|------|------|--------|------|-------|-----|-----|----------|-------|")
+	for _, a in ipairs(view.decls) do
+		local p = a.paths or {}
+		add(string.format("| %s | %s | %s | %d | %d | %s | %s | %s | %s |",
+			a.kind or "?",
+			a.name or "?",
+			source_basename(a.source_path or ""),
+			a.line or 0,
+			decl_words(a),
+			tostring(p.cycles_min or "—"),
+			tostring(p.cycles_max or "—"),
+			tostring(p.branches or "—"),
+			tostring(p.paths or "—")))
+	end
+	add("")
+end
+
+local function render_section_components(add, view)
+	local rows = {}
+	local index = (view.corpus and view.corpus.component_body_index) or {}
+	for _, a in ipairs(view.decls) do
+		if a.kind == "comp_bare" or a.kind == "comp_proc" then
+			local idx = index[a.name] or {}
+			local args = idx.arg_names or {}
+			rows[#rows + 1] = {
+				name = a.name,
+				kind = a.kind,
+				args = table.concat(args, ", "),
+				words = decl_words(a),
+				map = a.map_command or "—",
+			}
+		end
+	end
+	if #rows == 0 then add("_(none)_"); add(""); return end
+	add("| name | kind | arg_names | words | map |")
+	add("|------|------|-----------|-------|-----|")
+	for _, r in ipairs(rows) do
+		add(string.format("| %s | %s | %s | %d | %s |",
+			r.name, r.kind, r.args ~= "" and r.args or "—", r.words, r.map))
+	end
+	add("")
+end
+
+local function render_section_reguse(add, view)
+	local wrote = false
+	for _, schema in ipairs(view.schemas or {}) do
+		wrote = true
+		add(string.format("### %s", schema.name or "?"))
+		for _, slot in ipairs(schema.slots or {}) do
+			local aliases = table.concat(slot.aliases or { slot.name }, ", ")
+			local ro = slot.readonly and " readonly" or ""
+			add(string.format("- slot `%s` aliases %s%s", slot.name, aliases, ro))
+		end
+		for _, a in ipairs(view.decls) do
+			if a.reg_use_schema_name == schema.name then
+				add(string.format("- bound `%s` param `%s`", a.name, a.reg_use_param_name or "?"))
+			end
+		end
+		add("")
+	end
+	local bound = {}
+	for _, schema in ipairs(view.schemas or {}) do
+		if schema.name then bound[schema.name] = true end
+	end
+	local errors = {}
+	for _, err in ipairs((view.corpus and view.corpus.reg_use_errors) or {}) do
+		if bound[err.schema_name] or path_in_module(err.source_file, view) then
+			errors[#errors + 1] = err
+		end
+	end
+	if #errors > 0 then
+		wrote = true
+		add("### parse errors")
+		for _, err in ipairs(errors) do
+			add(string.format("- `%s` %s", err.kind or "?", err.schema_name or ""))
+		end
+		add("")
+	end
+	if not wrote then add("_(none)_"); add("") end
+end
+
+local function render_section_annotations(add, view)
+	local rows = {}
+	for _, src in ipairs(view.sources) do
+		for _, info in ipairs((src.scan and src.scan.atom_infos) or {}) do
+			rows[#rows + 1] = {
+				source = source_basename(src.path),
+				line   = info.info_line or 0,
+				name   = info.atom_name or "?",
+				binds  = info.binds or "—",
+				reads  = (#(info.reads or {}) > 0 and table.concat(info.reads, ",")) or "—",
+				writes = (#(info.writes or {}) > 0 and table.concat(info.writes, ",")) or "—",
+				phase  = info.phase or "—",
+			}
+		end
+	end
+	if #rows == 0 then add("_(none)_"); add(""); return end
+	add("| source | line | name | binds | reads | writes | phase |")
+	add("|--------|------|------|-------|-------|--------|-------|")
+	for _, r in ipairs(rows) do
+		add(string.format("| %s | %d | %s | %s | %s | %s | %s |",
+			r.source, r.line, r.name, r.binds, r.reads, r.writes, r.phase))
+	end
+	add("")
+end
+
+local function render_section_component_annotations(add, view)
+	local rows = {}
+	for _, src in ipairs(view.sources) do
+		for _, info in ipairs((src.scan and src.scan.component_atom_infos) or {}) do
+			rows[#rows + 1] = {
+				source = source_basename(src.path),
+				line   = info.info_line or 0,
+				name   = info.atom_name or "?",
+				reads  = (#(info.reads or {}) > 0 and table.concat(info.reads, ",")) or "—",
+				writes = (#(info.writes or {}) > 0 and table.concat(info.writes, ",")) or "—",
+			}
+		end
+	end
+	if #rows == 0 then add("_(none)_"); add(""); return end
+	add("| source | line | name | reads | writes |")
+	add("|--------|------|------|-------|--------|")
+	for _, r in ipairs(rows) do
+		add(string.format("| %s | %d | %s | %s | %s |",
+			r.source, r.line, r.name, r.reads, r.writes))
+	end
+	add("")
+end
+
+local function render_section_binds(add, view)
+	local wrote = false
+	for _, src in ipairs(view.sources) do
+		for _, b in ipairs((src.scan and src.scan.binds) or {}) do
+			wrote = true
+			add(string.format("### %s (%s:%s, %s bytes)",
+				b.name, source_basename(src.path), tostring(b.line or 0), tostring(b.bytes or "—")))
+			for _, f in ipairs(b.fields or {}) do
+				add(string.format("- `+%s %s`", tostring(f.offset or "?"), f.name or "?"))
+			end
+			add("")
+		end
+	end
+	if not wrote then add("_(none)_"); add("") end
+end
+
+local function render_section_phases(add, view)
+	local corpus = view.corpus or {}
+	local names  = decl_names(view)
+	local wrote  = false
+	for phase, entry in pairs(corpus.atom_phases or {}) do
+		local here = {}
+		for _, atom_name in ipairs(entry.atoms or {}) do
+			if names[atom_name] then here[#here + 1] = atom_name end
+		end
+		if #here > 0 then
+			wrote = true
+			add(string.format("- phase `%s`: %s", phase, table.concat(here, ", ")))
+		end
+	end
+	for name, entry in pairs(corpus.atom_views or {}) do
+		if names[name] then
+			wrote = true
+			add(string.format("- view `%s` binds `%s`", name, entry.binds_name or "—"))
+		end
+	end
+	for name, entry in pairs(corpus.atom_ctxs or {}) do
+		if names[name] then
+			wrote = true
+			add(string.format("- ctx `%s` rbind `%s`", name, entry.rbind_atom or "—"))
+		end
+	end
+	if not wrote then add("_(none)_") end
+	add("")
+end
+
+local function render_section_aliases(add, view)
+	local names = {}
+	local seen  = {}
+	for _, src in ipairs(view.sources or {}) do
+		for name, entry in pairs((src.scan and src.scan.register_alias_registry) or {}) do
+			if not seen[name] then
+				seen[name] = entry
+				names[#names + 1] = name
+			end
+		end
+	end
+	table.sort(names)
+	if #names == 0 then add("_(none)_"); add(""); return end
+	add("| alias | type |")
+	add("|-------|------|")
+	for _, name in ipairs(names) do
+		local e = seen[name]
+		add(string.format("| %s | %s |", name, (e and e.default_type) or "—"))
+	end
+	add("")
+end
+
+local function render_section_autoreg(add, view)
+	local allowed = decl_names(view)
+	for phase, entry in pairs((view.corpus and view.corpus.atom_phases) or {}) do
+		for _, atom_name in ipairs(entry.atoms or {}) do
+			if allowed[atom_name] then allowed[phase] = true end
+		end
+	end
+	local wrote = false
+	local seen  = {}
+	local function dump(label, table_map)
+		local scopes = {}
+		for scope in pairs(table_map or {}) do
+			if allowed[scope] and not seen[label .. "\0" .. scope] then
+				scopes[#scopes + 1] = scope
+			end
+		end
+		table.sort(scopes)
+		for _, scope in ipairs(scopes) do
+			seen[label .. "\0" .. scope] = true
+			wrote = true
+			local syms = {}
+			for sym, gpr in pairs(table_map[scope] or {}) do
+				if type(gpr) == "string" and gpr ~= sym then
+					syms[#syms + 1] = string.format("%s → %s", sym, gpr)
+				else
+					syms[#syms + 1] = tostring(sym)
+				end
+			end
+			table.sort(syms)
+			add(string.format("- %s `%s`: %s", label, scope, table.concat(syms, ", ")))
+		end
+	end
+	local corpus = view.corpus or {}
+	dump("atom", corpus.atom_auto_regs)
+	dump("phase", corpus.phase_auto_regs)
+	for _, src in ipairs(view.sources or {}) do
+		dump("atom", src.scan and src.scan.atom_auto_regs)
+		dump("phase", src.scan and src.scan.phase_auto_regs)
+	end
+	if not wrote then add("_(none)_") end
+	add("")
+end
+
+local function render_section_collisions(add, view)
+	local rows = {}
+	for _, c in ipairs((view.corpus and view.corpus.collisions) or {}) do
+		local first = c.first_site or {}
+		local other = c.conflicting_site or {}
+		if path_in_module(first.path, view) or path_in_module(other.path, view) then
+			rows[#rows + 1] = c
+		end
+	end
+	if #rows == 0 then add("_(none)_"); add(""); return end
+	for _, c in ipairs(rows) do
+		local first = c.first_site or {}
+		local other = c.conflicting_site or {}
+		add(string.format("- `%s` `%s` first %s:%s conflict %s:%s",
+			c.kind or "?", c.name or "?",
+			tostring(first.path or "?"), tostring(first.line or "?"),
+			tostring(other.path or "?"), tostring(other.line or "?")))
+	end
+	add("")
+end
+
+local function render_section_findings(add, view)
+	local by_atom = {}
+	for _, f in ipairs(view.findings or {}) do
+		local key = f.atom or "?"
+		by_atom[key] = by_atom[key] or {}
+		by_atom[key][#by_atom[key] + 1] = f
+	end
+	if next(by_atom) == nil then add("_(none)_"); add(""); return end
+	local seen = {}
+	local function emit(name, fs)
+		add("### " .. name)
+		for _, f in ipairs(fs) do
+			local msg = f.msg or ""
+			local slot = slot_suffix(f.gpr_key or f.producer_destination)
+			if slot and not msg:find("(slot ", 1, true) then
+				msg = msg .. " (slot " .. slot .. ")"
+			end
+			add(string.format("- `[%s/%s] %s`", f.kind or "info", f.check or "?", msg))
+		end
+		add("")
+	end
+	for _, a in ipairs(view.decls) do
+		if by_atom[a.name] then
+			seen[a.name] = true
+			emit(a.name, by_atom[a.name])
+		end
+	end
+	local leftovers = {}
+	for name in pairs(by_atom) do
+		if not seen[name] then leftovers[#leftovers + 1] = name end
+	end
+	table.sort(leftovers)
+	for _, name in ipairs(leftovers) do emit(name, by_atom[name]) end
+end
+
+local function render_section_relations(add, view)
+	local wrote = false
+	for _, a in ipairs(view.decls) do
+		local rels = (a.paths and a.paths.relations) or {}
+		if #rels > 0 then
+			wrote = true
+			add("### " .. a.name)
+			for _, rel in ipairs(rels) do
+				local dest = rel.destination or rel.producer_destination or "—"
+				local slot = slot_suffix(dest)
+				local dest_s = tostring(dest)
+				if slot then dest_s = dest_s .. " (slot " .. slot .. ")" end
+				add(string.format("- `%s` words %s → %s dest %s",
+					rel.semantic or "?",
+					tostring(rel.producer_word or "?"),
+					tostring(rel.consumer_word or "?"),
+					dest_s))
+			end
+			add("")
+		end
+	end
+	if not wrote then add("_(none)_"); add("") end
+end
+
+local HIDDEN_UNLESS_WRITTEN = {
+	R_AT = true, R_TapePtr = true, R_AtomJmp = true,
+}
+
+local PHYSICAL_GPR = {
+	R_T0 = true, R_T1 = true, R_T2 = true, R_T3 = true,
+	R_T4 = true, R_T5 = true, R_T6 = true, R_T7 = true,
+	R_V0 = true, R_V1 = true,
+}
+
+local function encoder_wrote_key(atom, key)
+	for _, ev in ipairs((atom.paths and atom.paths.word_events) or {}) do
+		for _, dest in pairs(ev.gpr_keys or {}) do
+			if dest == key then return true end
+		end
+	end
+	return false
+end
+
+local function written_name_for(key, atom)
+	local slot = key:match("^reguse:.+:(.+)$")
+	if slot then
+		local param = atom.reg_use_param_name
+		if param and param ~= "" then return param .. "." .. slot end
+		return slot
+	end
+	return key
+end
+
+local function aliases_for_key(key, atom, view)
+	local slot = key:match("^reguse:.+:(.+)$")
+	if not slot then return "—" end
+	local schema_name = atom.reg_use_schema_name
+	local schema = view.corpus and view.corpus.reg_use_schemas and view.corpus.reg_use_schemas[schema_name]
+	if not schema then return "—" end
+	for _, s in ipairs(schema.slots or {}) do
+		if s.name == slot then
+			local names = {}
+			for _, alias in ipairs(s.aliases or {}) do
+				if alias ~= slot then names[#names + 1] = alias end
+			end
+			if #names == 0 then
+				if s.aliases and #s.aliases > 0 then return table.concat(s.aliases, ", ") end
+				return "—"
+			end
+			return table.concat(names, ", ")
+		end
+	end
+	return "—"
+end
+
+local function physical_for_key(key, atom, view)
+	if PHYSICAL_GPR[key] then return key end
+	local corpus = view.corpus or {}
+	local alias = (corpus.register_alias_registry or {})[key]
+	if type(alias) == "table" then
+		local phys = alias.physical or alias.gpr or alias.code_name
+		if type(phys) == "string" and PHYSICAL_GPR[phys] then return phys end
+		if type(alias.name) == "string" and PHYSICAL_GPR[alias.name] then return alias.name end
+	elseif type(alias) == "string" and PHYSICAL_GPR[alias] then
+		return alias
+	end
+	local atom_map = (corpus.atom_auto_regs or {})[atom.name]
+	if type(atom_map) == "table" then
+		local slot = key:match("^reguse:.+:(.+)$") or key
+		local bound = atom_map[slot] or atom_map["R_" .. slot]
+		if type(bound) == "string" and PHYSICAL_GPR[bound] then return bound end
+	end
+	return "—"
+end
+
+local function last_relation_for(key, atom)
+	local last = nil
+	for _, rel in ipairs((atom.paths and atom.paths.relations) or {}) do
+		local dest = rel.destination or rel.producer_destination
+		if dest == key then last = rel end
+	end
+	if not last then return "—" end
+	local sem = last.semantic or "?"
+	local a = last.producer_word
+	local b = last.consumer_word
+	if a and b then return string.format("%s w%s→%s", sem, tostring(a), tostring(b)) end
+	return sem
+end
+
+local function render_section_forward(add, view)
+	local wrote = false
+	for _, a in ipairs(view.decls) do
+		local gpr = a.paths and a.paths.forward_state and a.paths.forward_state.gpr_values
+		local keys = {}
+		for k in pairs(gpr or {}) do
+			if k == "R_0" then
+				-- hidden
+			elseif HIDDEN_UNLESS_WRITTEN[k] and not encoder_wrote_key(a, k) then
+				-- hidden
+			else
+				keys[#keys + 1] = k
+			end
+		end
+		if #keys > 0 then
+			wrote = true
+			add("### " .. a.name)
+			add("| written | aliases | physical | lattice | last relation |")
+			add("|---|---|---|---|---|")
+			table.sort(keys)
+			for _, k in ipairs(keys) do
+				local slot = gpr[k]
+				local lattice = "—"
+				if slot and slot.kind == "constant" then
+					lattice = tostring(slot.value)
+				end
+				add(string.format("| `%s` | %s | %s | %s | %s |",
+					written_name_for(k, a),
+					aliases_for_key(k, a, view),
+					physical_for_key(k, a, view),
+					lattice,
+					last_relation_for(k, a)))
+			end
+			add("")
+		end
+	end
+	if not wrote then add("_(none)_"); add("") end
+end
+
+local SECTION_RENDERERS = {
+	{ header = "## Declarations",          render = render_section_declarations },
+	{ header = "## Components",            render = render_section_components },
+	{ header = "## RegUse schemas",        render = render_section_reguse },
+	{ header = "## Annotations",           render = render_section_annotations },
+	{ header = "## Component annotations", render = render_section_component_annotations },
+	{ header = "## Binds_* structs",       render = render_section_binds },
+	{ header = "## Phases / views / ctx",  render = render_section_phases },
+	{ header = "## Register aliases",      render = render_section_aliases },
+	{ header = "## Auto-reg",              render = render_section_autoreg },
+	{ header = "## Collisions",            render = render_section_collisions },
+	{ header = "## Findings",              render = render_section_findings },
+	{ header = "## Relations",             render = render_section_relations },
+	{ header = "## GPR model",             render = render_section_forward },
+}
+
+--- Render the consolidated per-module markdown (`build/<module>.atom_meta_report.md`).
+--- One ModuleView from the corpus; SECTION_RENDERERS walks it.
+--- @param view table
+--- @return string
+local function render_module_meta_report(view)
+	local dir_basename = source_basename(view.dir)
 	local lines        = {
 		"# " .. dir_basename .. " — atom meta report",
 		"> Auto-generated by ps1_meta.lua (passes/report.lua). Do not edit.",
@@ -264,199 +786,41 @@ local function render_module_meta_report(dir, dir_sources, annot_results, sa_res
 	}
 	local function add(s) lines[#lines + 1] = s end
 
-	-- Module summary table.
+	local kinds = count_kinds(view.decls)
-	local n_atoms        = 0
+	local n_annot, n_binds, n_macros = 0, 0, 0
-	local n_annot        = 0
+	for _, src in ipairs(view.sources) do
-	local n_binds        = 0
+		n_annot  = n_annot  + #((src.scan and src.scan.atom_infos) or {})
-	local n_macros       = 0
+		n_binds  = n_binds  + #((src.scan and src.scan.binds) or {})
-	local n_bare, n_proc = 0, 0
+		n_macros = n_macros + #((src.scan and src.scan.macros) or {})
-	for _, r in ipairs(annot_results) do
-		n_atoms  = n_atoms  + #r.atoms
-		n_annot  = n_annot  + #r.annots
-		n_binds  = n_binds  + #r.binds
-		n_macros = n_macros + #r.macros
 	end
-	for _, a in ipairs(sa_results.atoms or {}) do
+	local n_err, n_warn, n_info = 0, 0, 0
-		if     a.kind == "comp_bare" then n_bare = n_bare + 1
+	for _, f in ipairs(view.findings or {}) do
-		elseif a.kind == "comp_proc" then n_proc = n_proc + 1
+		if     f.kind == "error"   then n_err  = n_err  + 1
+		elseif f.kind == "warning" then n_warn = n_warn + 1
+		else                            n_info = n_info + 1
 		end
 	end
 
 	add("## Module summary"); add("")
 	add("| metric | value |"); add("|--------|-------|")
-	add(string.format("| sources | %d |", #dir_sources))
+	add(string.format("| sources | %d |", #view.sources))
-	add(string.format("| atoms | %d (atoms: %d, comp_bare: %d, comp_proc: %d) |",
+	add(string.format("| decls | %d (atom: %d, atom_proc: %d, comp_bare: %d, comp_proc: %d) |",
-		#(sa_results.atoms or {}),
+		#view.decls, kinds.atom, kinds.atom_proc, kinds.comp_bare, kinds.comp_proc))
-		#(sa_results.atoms or {}) - n_bare - n_proc, n_bare, n_proc))
 	add(string.format("| annotations | %d |", n_annot))
 	add(string.format("| binds structs | %d |", n_binds))
 	add(string.format("| macro decls | %d |", n_macros))
 	add(string.format("| findings | %d (errors: %d, warnings: %d, info: %d) |",
-		#(sa_results.findings or {}),
+		#(view.findings or {}), n_err, n_warn, n_info))
-		#(sa_results.errors   or {}),
-		#(sa_results.warnings or {}),
-		#(sa_results.info     or {})))
 	add("")
 
-	-- Sources
 	add("## Sources"); add("")
-	for _, s in ipairs(dir_sources) do add("- `" .. s.path .. "`") end
+	for _, s in ipairs(view.sources) do add("- `" .. s.path .. "`") end
 	add("")
 
-	-- Atoms (annotation)
+	for _, row in ipairs(SECTION_RENDERERS) do
-	add("## Atoms"); add("")
+		add(row.header); add("")
-	add("| kind | name | source | line |"); add("|------|------|--------|------|")
+		row.render(add, view)
-	for _, r in ipairs(annot_results) do
-		local src_name = source_basename(r.source)
-		for _, a in ipairs(r.atoms) do
-			add(string.format("| atom | %s | %s | %d |", a.name, src_name, a.line))
-		end
 	end
-	add("")
-
-	-- Annotations
-	add("## Annotations"); add("")
-	if #annot_results == 0 then
-		add("_(none)_")
-	else
-		add("| source | line | name | binds | reads | writes |")
-		add("|--------|------|------|-------|-------|--------|")
-		for _, r in ipairs(annot_results) do
-			local src_name = source_basename(r.source)
-			for _, a in ipairs(r.annots) do
-				local binds  = a.binds  or "—"
-				local reads  = (#a.reads  > 0 and table.concat(a.reads,  ",")) or "—"
-				local writes = (#a.writes > 0 and table.concat(a.writes, ",")) or "—"
-				add(string.format("| %s | %d | %s | %s | %s | %s |"
-					, src_name, a.line, a.name, binds, reads, writes))
-			end
-		end
-	end
-	add("")
-
-	-- Binds_* structs
-	add("## Binds_* structs"); add("")
-	if #annot_results == 0 then
-		add("_(none)_")
-	else
-		for _, r in ipairs(annot_results) do
-			local src_name = source_basename(r.source)
-			for _, b in ipairs(r.binds) do
-				add(string.format("### %s (%s:%d, %d bytes)",
-					b.name, src_name, b.line, b.bytes))
-				for _, f in ipairs(b.fields) do
-					add(string.format("- `+%d %s`", f.offset, f.name))
-				end
-				add("")
-			end
-		end
-	end
-
-	-- Macro decls
-	add("## Macro word-count declarations"); add("")
-	if #annot_results == 0 then
-		add("_(none)_")
-	else
-		add("| source | line | macro declaration |")
-		add("|--------|------|-------------------|")
-		for _, r in ipairs(annot_results) do
-			local src_name = source_basename(r.source)
-			for _, m in ipairs(r.macros) do
-				add(string.format("| %s | %d | %s |",
-					src_name, m.line, m.name))
-			end
-		end
-	end
-	add("")
-
-	-- Findings by atom (static-analysis)
-	add("## Static analysis — findings by atom"); add("")
-	local by_atom = {}
-	for _, f in ipairs(sa_results.findings or {}) do
-		by_atom[f.atom] = by_atom[f.atom] or {}
-		by_atom[f.atom][#by_atom[f.atom] + 1] = f
-	end
-	if next(by_atom) == nil then
-		add("_(no findings)_")
-	else
-		for _, a in ipairs(sa_results.atoms or {}) do
-			local fs = by_atom[a.name]
-			if fs then
-				add(string.format("### %s", a.name))
-				for _, f in ipairs(fs) do
-					add(string.format("- `[%s] %s`", f.check, f.msg))
-				end
-				add("")
-			end
-		end
-	end
-
-	-- Errors / Warnings / Info
-	local function add_findings(label, entries)
-		add(string.format("## %s", label))
-		if #entries == 0 then
-			add("_(none)_")
-		else
-			for _, e in ipairs(entries) do
-				add(string.format("- line %d  %s", e.line, e.msg))
-			end
-		end
-		add("")
-	end
-	add_findings("Errors",   sa_results.errors   or {})
-	add_findings("Warnings", sa_results.warnings or {})
-	add_findings("Info",     sa_results.info     or {})
-
-	-- Per-atom cycle counts (path-aware)
-	add("## Per-atom cycle counts (path-aware, best case, no stalls)"); add("")
-	add("| atom | source | min | max | branches | paths | notes |")
-	add("|------|--------|-----|-----|----------|-------|-------|")
-	local sorted = {}
-	for _, a in ipairs(sa_results.atoms or {}) do sorted[#sorted + 1] = a end
-	table.sort(sorted, function(x, y)
-		return ((x.paths or {}).cycles_max or 0) > ((y.paths or {}).cycles_max or 0)
-	end)
-	for _, a in ipairs(sorted) do
-		local p        = a.paths or {}
-		local src_name = a.source_path and source_basename(a.source_path) or ""
-		local notes    = ""
-		if p.has_loops then notes = notes .. " [loop!]" end
-		if p.unknown_macros and #p.unknown_macros > 0 then
-			notes = notes .. " [unknown: " .. table.concat(p.unknown_macros, ", ") .. "]"
-		end
-		add(string.format("| %s | %s | %d | %d | %d | %d | %s |",
-			a.name, src_name,
-			p.cycles_min or 0, p.cycles_max or 0,
-			p.branches   or 0, p.paths      or 0, notes))
-	end
-	add("")
-
-	-- Per-source scan summary
-	add("## Per-source scan summary"); add("")
-	for _, src in ipairs(dir_sources) do
-		local src_atoms = {}
-		for _, a in ipairs(sa_results.atoms or {}) do
-			if a.source_path == src.path then src_atoms[#src_atoms + 1] = a end
-		end
-		if #src_atoms > 0 then
-			local mn, mx = math.huge, -1
-			for _, a in ipairs(src_atoms) do
-				local p = a.paths or {}
-				if (p.cycles_min or 0) < mn then mn = p.cycles_min or 0 end
-				if (p.cycles_max or 0) > mx then mx = p.cycles_max or 0 end
-			end
-			local path_str
-			if mx > 0 then
-				path_str = string.format("  cycles=%d..%d", mn, mx)
-			else
-				path_str = string.format("  %d cycles", mn)
-			end
-			add(string.format("- `%s` — %d atom%s%s",
-				src.basename, #src_atoms,
-				#src_atoms == 1 and "" or "s", path_str))
-		end
-	end
-	add("")
 
 	return table.concat(lines, "\n") .. "\n"
 end
@@ -474,19 +838,8 @@ local REPORT_RENDERERS = {
 		basename = function(dir_basename) return dir_basename .. ".atom_meta_report" end,
 		once     = false,
 		gather   = function(ctx, dir, dir_sources)
-			-- Annotations: re-run `annotation.validate()` per source (the existing pattern).
+			local corpus = ctx.shared.corpus
-			local annot_results = {}
+			return render_module_meta_report(build_module_view(dir, dir_sources, corpus))
-			for _, src in ipairs(dir_sources) do
-				if src.scan then
-					local r = annotation.validate(ctx, src, nil)
-					r.source = src.path
-					annot_results[#annot_results + 1] = r
-				end
-			end
-			-- Static-analysis: read stashed projection (no re-validate).
-			local dir_basename = dir:match("([^/\\]+)$") or dir
-			local sa_results   = (ctx.shared.corpus.static_analysis_results or {})[dir_basename] or {}
-			return render_module_meta_report(dir, dir_sources, annot_results, sa_results)
 		end,
 	},
 	{
@@ -554,32 +907,30 @@ function M.run(ctx)
 			end
 		end
 
-		-- For the summary, compute per-module totals once (re-validating annotations per source — same pattern as the meta_report renderer).
+		local view = build_module_view(dir, dir_sources, corpus)
-		local annot_results = {}
+		local n_annot, n_binds, n_macros = 0, 0, 0
 		for _, src in ipairs(dir_sources) do
-			if src.scan then
+			n_annot  = n_annot  + #((src.scan and src.scan.atom_infos) or {})
-				local r = annotation.validate(ctx, src, nil)
+			n_binds  = n_binds  + #((src.scan and src.scan.binds) or {})
-				r.source = src.path
+			n_macros = n_macros + #((src.scan and src.scan.macros) or {})
-				annot_results[#annot_results + 1] = r
+		end
+		local n_err, n_warn, n_info = 0, 0, 0
+		for _, f in ipairs(view.findings or {}) do
+			if     f.kind == "error"   then n_err  = n_err  + 1
+			elseif f.kind == "warning" then n_warn = n_warn + 1
+			else                            n_info = n_info + 1
 			end
 		end
-		local n_annot, n_binds, n_macros = 0, 0, 0
-		for _, r in ipairs(annot_results) do
-			n_annot  = n_annot  + #r.annots
-			n_binds  = n_binds  + #r.binds
-			n_macros = n_macros + #r.macros
-		end
-		local sa_results = (corpus.static_analysis_results or {})[dir_basename] or {}
 		all_modules[#all_modules + 1] = {
 			module   = dir_basename,
-			atoms    = #(sa_results.atoms or {}),
+			atoms    = #view.decls,
 			annots   = n_annot,
 			binds    = n_binds,
 			macros   = n_macros,
-			findings = #(sa_results.findings or {}),
+			findings = #(view.findings or {}),
-			errors   = #(sa_results.errors   or {}),
+			errors   = n_err,
-			warnings = #(sa_results.warnings or {}),
+			warnings = n_warn,
-			info     = #(sa_results.info     or {}),
+			info     = n_info,
 		}
 	end
 

scripts/passes/scan_source.lua

@@ -6,6 +6,7 @@
 ---   MipsAtom_Proc_         (kind = "atom_proc", body inside last {})
 ---   MipsAtomComp_          (kind = "comp_bare")
 ---   MipsAtomComp_Proc_     (kind = "comp_proc", body inside last {})
+---   MipsAtomComp_ProcMap_  (kind = "comp_proc", body is the one command)
 ---   atom_dbg_skip          — bare whole-atom/component debug-step marker; following declaration disambiguates
 ---   MipsCode code_<name>   (kind = "raw_atom", offsets pass only)
 ---   typedef Struct_(Binds_X) { fields }
@@ -137,6 +138,16 @@ local QUALIFIER_KEYWORDS = {
 local AC_PREFIX     = "ac_"
 local AC_PREFIX_LEN = 3
 
+-- The function-decl keyword that precedes a MipsAtomComp_Proc_ call.
+-- Used by the backward walk in duffle.find_function_decl_for.
+local SLICE_MIPS_CODE    = "Slice_MipsCode"
+local SLICE_MIPS_CODE_LEN = #SLICE_MIPS_CODE
+
+-- The return type that precedes a MipsAtom_Proc_ function declaration.
+-- Used by the backward walk in duffle.find_atom_proc_decl_for.
+local MIPS_ATOM_PTR    = "MipsAtom*"
+local MIPS_ATOM_PTR_LEN = #MIPS_ATOM_PTR
+
 --- Strip the "ac_" prefix from a component name.
 --- Returns the input unchanged if it doesn't start with the prefix.
 --- @param raw_name string
@@ -405,31 +416,51 @@ local function walk_body_fields(body, build_field)
 	return fields
 end
 
--- Parse the `<type> <field>;` declarations from a Struct_ body.
+-- Parse the `<type> <field>[, <field>...];` declarations from a Struct_ body.
+-- After the type and `*` chain, keep reading `, ident` until `;`.
+-- Same type, same pointer depth for every name on that list.
 -- Returns the raw fields array with `{name, type_name, pointer_depth}` only (NO offset / byte_size).
 -- The propagation pass `resolve_struct_field_sizes` walks each struct's fields AFTER type resolution and populates offset + byte_size in place.
--- Returns (fields). The aggregate byte_count is computed in the propagation pass (it depends on whether every field's type resolved).
 local function parse_struct_body_fields(body)
-	return walk_body_fields(body, function(type_name, type_end, after_type)
+	local fields = {}
-		-- Parse the trailing `*` chain to derive pointer_depth.
+	local body_pos = 1
-		local depth, cursor = 0, after_type
+	local body_len = #body
-		while cursor <= #body and body:sub(cursor, cursor) == "*" do
+	while body_pos <= body_len do
-			depth  = depth  + 1
+		body_pos = duffle.skip_ws_and_cmt(body, body_pos)
-			cursor = cursor + 1
+		if body_pos > body_len then break end
-			cursor = duffle.skip_ws_and_cmt(body, cursor)
+		local type_name, type_end = duffle.read_ident(body, body_pos)
+		if not type_name then
+			body_pos = body_pos + 1
+		else
+			local depth, cursor = 0, duffle.skip_ws_and_cmt(body, type_end)
+			while cursor <= body_len and body:sub(cursor, cursor) == "*" do
+				depth = depth + 1
+				cursor = duffle.skip_ws_and_cmt(body, cursor + 1)
+			end
+			while cursor <= body_len do
+				local field_ident, field_end = duffle.read_ident(body, cursor)
+				if not field_ident then break end
+				fields[#fields + 1] = {
+					name          = field_ident,
+					type_name     = type_name,
+					pointer_depth = depth,
+					offset        = nil,
+					byte_size     = nil,
+				}
+				cursor = duffle.skip_ws_and_cmt(body, field_end)
+				if body:sub(cursor, cursor) == "," then
+					cursor = duffle.skip_ws_and_cmt(body, cursor + 1)
+				else
+					break
+				end
+			end
+			if cursor <= body_len and body:sub(cursor, cursor) == ";" then
+				cursor = cursor + 1
+			end
+			body_pos = cursor
 		end
-		-- Read the field ident immediately after the type chain.
+	end
-		local field_ident, field_end = duffle.read_ident(body, cursor)
+	return fields
-		if not field_ident then return nil, type_end + 1 end
-		return {
-			name          = field_ident,
-			type_name     = type_name,
-			pointer_depth = depth,
-			-- offset + byte_size filled by resolve_struct_field_sizes
-			offset        = nil,
-			byte_size     = nil,
-		}, field_end
-	end)
 end
 
 -- Parse the `Enum_(<underlying>, <name>) { <body> }` body for entries.
@@ -1241,6 +1272,53 @@ local function parse_atom_dbg_reg_default(source, pos, ident_end, line_of, out)
 	return after_paren
 end
 
+--- Lookahead for `atom_info(...)` after a declaration's closing paren.
+--- Records into `dest` (atom_infos or component_atom_infos). Returns the position after the info, or after_paren if none.
+local function parse_atom_info_after_decl(source, after_paren, raw_name, line_of, out, dest)
+	local lookahead            = duffle.skip_ws_and_cmt(source, after_paren)
+	local look_ident, look_end = duffle.read_ident(source, lookahead)
+	if look_ident ~= "atom_info" then return after_paren end
+	local info_open = duffle.skip_ws_and_cmt(source, look_end)
+	if source:sub(info_open, info_open) ~= "(" then return after_paren end
+	local info_inner, info_after = duffle.read_parens(source, info_open)
+	if not info_inner then return after_paren end
+	local info_line = line_of(info_open)
+	local ai_binds, ai_reads, ai_writes, ai_view, ai_overrides, ai_ctx, ai_phase = scan_atom_info_subcalls(info_inner, info_line)
+	dest = dest or out.atom_infos
+	dest[#dest + 1] = {
+		atom_name = raw_name or "?", binds = ai_binds,
+		reads     = ai_reads or {}, writes = ai_writes or {},
+		view      = ai_view,
+		reg_type_overrides = ai_overrides,
+		ctx_atom  = ai_ctx,
+		phase     = ai_phase,
+		info_line = line_of(lookahead),
+	}
+	if ai_view and raw_name then
+		out.atom_views[raw_name] = {
+			atom_name          = raw_name,
+			binds_name         = ai_view,
+			reg_type_overrides = ai_overrides,
+			info_line          = line_of(lookahead),
+		}
+	elseif raw_name and ai_overrides then
+		out.atom_views[raw_name] = out.atom_views[raw_name] or { atom_name = raw_name, binds_name = nil, reg_type_overrides = nil, info_line = line_of(lookahead) }
+		out.atom_views[raw_name].reg_type_overrides = ai_overrides
+	end
+	if raw_name then
+		if ai_ctx then
+			out.atom_ctxs = out.atom_ctxs or {}
+			out.atom_ctxs[raw_name] = { rbind_atom = ai_ctx, info_line = line_of(lookahead), source = source }
+		end
+		if ai_phase then
+			out.atom_phases = out.atom_phases or {}
+			out.atom_phases[ai_phase] = out.atom_phases[ai_phase] or { atoms = {} }
+			out.atom_phases[ai_phase].atoms[#out.atom_phases[ai_phase].atoms + 1] = raw_name
+		end
+	end
+	return info_after
+end
+
 --- Parse: `MipsAtom_(<name>) [atom_info(<binds>, <reads>, <writes>)] { <body> }`
 --- @param source    string
 --- @param pos       integer
@@ -1254,53 +1332,8 @@ local function parse_mips_atom(source, pos, ident_end, line_of, out)
 
 	local raw_name = duffle.read_ident(inner, 1)
 
-	-- Lookahead for atom_info(...) between `)` and `{`. Captures sub-calls; updates brace search start.
+	-- Lookahead for atom_info(...) between `)` and `{`.
-	local brace_search_pos     = after_paren
+	local brace_search_pos = parse_atom_info_after_decl(source, after_paren, raw_name, line_of, out, out.atom_infos)
-	local lookahead            = duffle.skip_ws_and_cmt(source, after_paren)
-	local look_ident, look_end = duffle.read_ident(source, lookahead)
-	if    look_ident == "atom_info" then
-		local info_open = duffle.skip_ws_and_cmt(source, look_end)
-		if source:sub(info_open, info_open) == "(" then
-			local info_inner, info_after = duffle.read_parens(source, info_open)
-			-- info_line feeds the per-atom reg_type_overrides table.
-			local info_line = line_of(info_open)
-			local ai_binds, ai_reads, ai_writes, ai_view, ai_overrides, ai_ctx, ai_phase = scan_atom_info_subcalls(info_inner, info_line)
-			out.atom_infos[#out.atom_infos + 1] = {
-				atom_name = raw_name or "?", binds = ai_binds,
-				reads     = ai_reads or {}, writes = ai_writes or {},
-				view      = ai_view,
-				reg_type_overrides = ai_overrides,
-				ctx_atom  = ai_ctx,
-				phase     = ai_phase,
-				info_line = line_of(lookahead),
-			}
-			if ai_view and raw_name then
-				out.atom_views[raw_name] = {
-					atom_name          = raw_name,
-					binds_name         = ai_view,
-					reg_type_overrides = ai_overrides,
-					info_line          = line_of(lookahead),
-				}
-			elseif raw_name and ai_overrides then
-				-- Record per-atom overrides even without atom_view.
-				out.atom_views[raw_name] = out.atom_views[raw_name] or { atom_name = raw_name, binds_name = nil, reg_type_overrides = nil, info_line = line_of(lookahead) }
-				out.atom_views[raw_name].reg_type_overrides = ai_overrides
-			end
-			-- Project the per-atom atom_ctx / atom_phase declarations onto the global phase index.
-			if raw_name then
-				if ai_ctx then
-					out.atom_ctxs = out.atom_ctxs or {}
-					out.atom_ctxs[raw_name] = { rbind_atom = ai_ctx, info_line = line_of(lookahead), source = source }
-				end
-				if ai_phase then
-					out.atom_phases = out.atom_phases or {}
-					out.atom_phases[ai_phase] = out.atom_phases[ai_phase] or { atoms = {} }
-					out.atom_phases[ai_phase].atoms[#out.atom_phases[ai_phase].atoms + 1] = raw_name
-				end
-			end
-			brace_search_pos = info_after
-		end
-	end
 
 	local  body, after_brace, body_off = find_body_braces(source, brace_search_pos, open_paren + 1)
 	if not body then return after_brace end
@@ -1325,7 +1358,9 @@ local function parse_mips_atom_comp(source, pos, ident_end, line_of, out)
 	local  raw_name = duffle.read_ident(inner, 1)
 	if not raw_name then return open_paren + 1 end
 
-	local  body, after_brace, body_off = find_body_braces(source, after_paren, open_paren + 1)
+	out.component_atom_infos = out.component_atom_infos or {}
+	local brace_search_pos = parse_atom_info_after_decl(source, after_paren, strip_ac_prefix(raw_name), line_of, out, out.component_atom_infos)
+	local  body, after_brace, body_off = find_body_braces(source, brace_search_pos, open_paren + 1)
 	if not body then return after_brace end
 	local name = strip_ac_prefix(raw_name)
 	register_atom(out, "comp_bare", line_of(pos), name, body, body_off, raw_name, pos, after_paren, source)
@@ -1357,7 +1392,11 @@ local function parse_mips_atom_comp_proc(source, pos, ident_end, line_of, out)
 	local body, close_pos = duffle.read_braces(inner, last_brace_pos)
 	if close_pos > #inner + 1 then return after_paren end
 
-	local raw_name = inner:match("^%s*([%w_]+)") or "?"
+	-- The component name is derived from the preceding function declaration
+	-- (`FI_ Slice_MipsCode ac_X(...)`), not from the first macro arg (which
+	-- is now `ab`). The backward walk finds the function decl before open_paren.
+	local raw_name = duffle.find_function_decl_for(source, open_paren, SLICE_MIPS_CODE_LEN)
+	if not raw_name then raw_name = "?" end
 	local name     = strip_ac_prefix(raw_name)
 	-- Position of body[1] in source = open_paren + 1 (start of inner) + last_brace_pos + 1 (past '{').
 	local body_off = open_paren + 2 + last_brace_pos
@@ -1366,15 +1405,35 @@ local function parse_mips_atom_comp_proc(source, pos, ident_end, line_of, out)
 	return after_paren
 end
 
---- Parse: `MipsAtom_Proc_(<name>, <abuilder>, { <body> })` — body is inside the LAST `{` in args.
+--- Parse: `MipsAtomComp_ProcMap_(ab, command)` — body is the one command (second arg).
---- Per Task 12.10: full support for the runtime-proc atom form. Registers the atom
+--- Reuses the proc name walk. Kind is `comp_proc`. The C expansion wraps
---- with kind `"atom_proc"` so offsets.lua / components.lua can emit
+--- `atom_dbg_skip MipsAtomComp_Proc_(ab, {command })`; source-as-written is the map.
----   * `mac_<name>` aliases in `gen/macs.h` (the components pass)
+--- @param source    string
----   * `atom_offset__X__Y` defs in `gen/offsets.h` (the offsets pass)
+--- @param pos       integer
---- The atom name is the FIRST ident of the args (the second arg `ab` is the
+--- @param ident_end integer
---- atom-builder, not the name). Unlike `MipsAtomComp_Proc_`, there is no `ac_`
+--- @param line_of   fun(pos: integer): integer
---- prefix on the symbol — `MipsAtom_Proc_` is the runtime-proc wrapper, so the
+--- @param out       SourceScan
---- symbol IS the bare atom name (e.g. `normalize_v3s4`, not `ac_normalize_v3s4`).
+--- @return integer
+local function parse_mips_atom_comp_proc_map(source, pos, ident_end, line_of, out)
+	local inner, after_paren, open_paren = read_parens_after(source, ident_end)
+	if not inner then return after_paren end
+	local args = duffle.split_top_level_commas(inner)
+	if #args < 2 then return after_paren end
+	local command = duffle.trim(args[2])
+	if command == "" then return after_paren end
+	local raw_name = duffle.find_function_decl_for(source, open_paren, SLICE_MIPS_CODE_LEN)
+	if not raw_name then raw_name = "?" end
+	local name = strip_ac_prefix(raw_name)
+	local body_off = open_paren + 1 + (inner:find(command, 1, true) or 1) - 1
+	register_atom(out, "comp_proc", line_of(pos), name, command, body_off, raw_name, pos, after_paren, source)
+	local entry = out.atoms[#out.atoms]
+	entry.map_command = command
+	return after_paren
+end
+
+--- Parse: `MipsAtom_Proc_(aa, { body })` — body is inside the LAST `{` in args.
+--- Kind is `atom_proc`. The name is the preceding function ident as written.
+--- Offsets walk this kind. Components do not emit a `mac_*` alias for it.
 --- @param source    string
 --- @param pos       integer
 --- @param ident_end integer
@@ -1398,14 +1457,57 @@ local function parse_mips_atom_proc(source, pos, ident_end, line_of, out)
 	local body, close_pos = duffle.read_braces(inner, last_brace_pos)
 	if close_pos > #inner + 1 then return after_paren end
 
-	-- The atom name is the FIRST ident of the args (matches MipsAtomComp_Proc_'s "first ident" rule).
+	-- The atom name is the preceding function ident as written
-	-- MipsAtom_Proc_ has no `ac_` prefix; `strip_ac_prefix` is a no-op for unprefixed names.
+	-- (`internal MipsAtom* X(...)`). The first macro arg is the arena.
-	local raw_name = inner:match("^%s*([%w_]+)") or "?"
+	local raw_name, args_inner, func_ident, after_func_paren =
-	local name     = strip_ac_prefix(raw_name)
+		duffle.find_atom_proc_decl_for(source, open_paren, MIPS_ATOM_PTR_LEN)
+	if not raw_name then raw_name = "?" end
+	local name = strip_ac_prefix(raw_name)
+	if after_func_paren then
+		parse_atom_info_after_decl(source, after_func_paren, name, line_of, out, out.atom_infos)
+	else
+		parse_atom_info_after_decl(source, pos, name, line_of, out, out.atom_infos)
+	end
+	local reg_use_schema_name = nil
+	local reg_use_param_name  = nil
+	if args_inner then
+		local arg_tokens = duffle.split_top_level_commas(args_inner)
+		for _, tok in ipairs(arg_tokens) do
+			local trimmed = duffle.trim(tok)
+			local schema_suffix, param = trimmed:match("RegUse_([%w_]+)%s+([%w_]+)$")
+			if schema_suffix then
+				if reg_use_schema_name then
+					out.reg_use_errors[#out.reg_use_errors + 1] = {
+						kind        = "reguse_multiple_params",
+						schema_name = "RegUse_" .. schema_suffix,
+						source_line = line_of(pos),
+					}
+				else
+					reg_use_schema_name = "RegUse_" .. schema_suffix
+					reg_use_param_name  = param
+				end
+			end
+		end
+	end
 	-- Position of body[1] in source = open_paren + 1 (start of inner) + last_brace_pos + 1 (past '{').
 	local body_off = open_paren + 2 + last_brace_pos
 	register_atom(out, "atom_proc", line_of(pos), name, body, body_off, raw_name, pos, after_paren, source)
 
+	local entry = out.atoms[#out.atoms]
+	entry.reg_use_schema_name = reg_use_schema_name
+	entry.reg_use_param_name  = reg_use_param_name
+	if reg_use_schema_name and func_ident then
+		local expected = "RegUse_" .. func_ident
+		if reg_use_schema_name ~= expected then
+			out.reg_use_errors[#out.reg_use_errors + 1] = {
+				kind        = "reguse_name_mismatch",
+				schema_name = reg_use_schema_name,
+				func_ident  = func_ident,
+				source_line = line_of(pos),
+			}
+		end
+	end
+
 	return after_paren
 end
 
@@ -1513,6 +1615,236 @@ local function register_typedef_alias(underlying, name, pos, line_of, out)
 	}
 end
 
+local parse_reg_use_schema_body
+
+local function fields_for_reg_type(type_name, type_registry)
+	local reg_name = "Reg_" .. type_name
+	local entry = type_registry and type_registry[reg_name]
+	if entry and entry.fields and #entry.fields > 0 then
+		local names = {}
+		for _, field in ipairs(entry.fields) do
+			if field.name then names[#names + 1] = field.name end
+		end
+		if #names > 0 then return names end
+	end
+	if entry and entry.body and parse_reg_use_schema_body then
+		local schema = parse_reg_use_schema_body(entry.body, type_registry)
+		if schema and schema.slots then
+			local names = {}
+			for _, slot in ipairs(schema.slots) do
+				if slot.name then names[#names + 1] = slot.name end
+			end
+			if #names > 0 then return names end
+		end
+	end
+	return nil
+end
+
+parse_reg_use_schema_body = function(body, type_registry, opts)
+	opts = opts or {}
+	local require_types = opts.require_types == true
+	local pending = false
+	local slots = {}
+	local alias_to_slot = {}
+	local slot_names = {}
+	local errors = {}
+
+	local function add_alias(path, slot)
+		if alias_to_slot[path] then
+			errors[#errors + 1] = { kind = "reguse_duplicate_alias", path = path }
+			return false
+		end
+		alias_to_slot[path] = slot
+		return true
+	end
+
+	local function add_slot(name, aliases, readonly)
+		if slot_names[name] then
+			errors[#errors + 1] = { kind = "reguse_duplicate_slot", name = name }
+			return nil
+		end
+		slot_names[name] = true
+		local slot = { name = name, aliases = aliases, readonly = readonly == true }
+		slots[#slots + 1] = slot
+		return slot
+	end
+
+	local function parse_reg_names(text, pos)
+		local names = {}
+		while pos <= #text do
+			pos = duffle.skip_ws_and_cmt(text, pos)
+			local name, name_end = duffle.read_ident(text, pos)
+			if not name then return nil, pos end
+			names[#names + 1] = name
+			pos = duffle.skip_ws_and_cmt(text, name_end)
+			if text:sub(pos, pos) == "," then
+				pos = pos + 1
+			else
+				break
+			end
+		end
+		if text:sub(pos, pos) == ";" then pos = pos + 1 end
+		return names, pos
+	end
+
+	local pos = 1
+	while pos <= #body do
+		pos = duffle.skip_ws_and_cmt(body, pos)
+		if pos > #body then break end
+		local first, first_end = duffle.read_ident(body, pos)
+		if not first then
+			pos = pos + 1
+			goto continue
+		end
+		local after = duffle.skip_ws_and_cmt(body, first_end)
+		if first == "const" then
+			errors[#errors + 1] = { kind = "reguse_const_reg_spelling" }
+			return nil, errors
+		elseif first == "union" then
+			if body:sub(after, after) ~= "{" then
+				errors[#errors + 1] = { kind = "reguse_malformed" }
+				return nil, errors
+			end
+			local inner, after_braces = duffle.read_braces(body, after)
+			if not inner then
+				errors[#errors + 1] = { kind = "reguse_malformed" }
+				return nil, errors
+			end
+			local members = {}
+			local union_readonly = nil
+			local inner_pos = 1
+			while inner_pos <= #inner do
+				inner_pos = duffle.skip_ws_and_cmt(inner, inner_pos)
+				if inner_pos > #inner then break end
+				local m_type, m_type_end = duffle.read_ident(inner, inner_pos)
+				if not m_type then
+					inner_pos = inner_pos + 1
+					goto continue_inner
+				end
+				if m_type == "const" then
+					errors[#errors + 1] = { kind = "reguse_const_reg_spelling" }
+					return nil, errors
+				end
+				if m_type ~= "Reg" then
+					errors[#errors + 1] = { kind = "reguse_malformed" }
+					return nil, errors
+				end
+				local m_after = duffle.skip_ws_and_cmt(inner, m_type_end)
+				local m_readonly = false
+				local maybe_const, maybe_end = duffle.read_ident(inner, m_after)
+				if maybe_const == "const" then
+					m_readonly = true
+					m_after = duffle.skip_ws_and_cmt(inner, maybe_end)
+				end
+				if union_readonly == nil then
+					union_readonly = m_readonly
+				elseif union_readonly ~= m_readonly then
+					errors[#errors + 1] = { kind = "reguse_mixed_const" }
+					return nil, errors
+				end
+				local names, new_inner = parse_reg_names(inner, m_after)
+				if not names or #names == 0 then
+					errors[#errors + 1] = { kind = "reguse_malformed" }
+					return nil, errors
+				end
+				for _, n in ipairs(names) do members[#members + 1] = n end
+				inner_pos = new_inner
+				::continue_inner::
+			end
+			if #members == 0 then
+				errors[#errors + 1] = { kind = "reguse_malformed" }
+				return nil, errors
+			end
+			local after_close = duffle.skip_ws_and_cmt(body, after_braces)
+			local inst_name, inst_end = duffle.read_ident(body, after_close)
+			local aliases = {}
+			local slot_name
+			if inst_name then
+				slot_name = inst_name
+				for _, m in ipairs(members) do
+					local path = inst_name .. "." .. m
+					if not add_alias(path, slot_name) then return nil, errors end
+					aliases[#aliases + 1] = path
+				end
+				after_close = inst_end
+			else
+				slot_name = members[1]
+				for _, m in ipairs(members) do
+					if not add_alias(m, slot_name) then return nil, errors end
+					aliases[#aliases + 1] = m
+				end
+			end
+			if not add_slot(slot_name, aliases, union_readonly) then return nil, errors end
+			after_close = duffle.skip_ws_and_cmt(body, after_close)
+			if body:sub(after_close, after_close) == ";" then after_close = after_close + 1 end
+			pos = after_close
+		elseif first == "Reg" or first == "Reg_" then
+			local typed_fields = nil
+			if first == "Reg_" then
+				if body:sub(after, after) ~= "(" then
+					errors[#errors + 1] = { kind = "reguse_malformed" }
+					return nil, errors
+				end
+				local type_inner, after_paren = duffle.read_parens(body, after)
+				if not type_inner then
+					errors[#errors + 1] = { kind = "reguse_malformed" }
+					return nil, errors
+				end
+				local type_ident = duffle.trim(type_inner)
+				typed_fields = fields_for_reg_type(type_ident, type_registry)
+				if not typed_fields then
+					if require_types then
+						errors[#errors + 1] = { kind = "reguse_unknown_reg_type", type_name = type_ident }
+					else
+						pending = true
+					end
+				end
+				after = duffle.skip_ws_and_cmt(body, after_paren)
+			end
+			local readonly = false
+			local maybe_const, maybe_end = duffle.read_ident(body, after)
+			if maybe_const == "const" then
+				readonly = true
+				after = duffle.skip_ws_and_cmt(body, maybe_end)
+			end
+			local names, new_pos = parse_reg_names(body, after)
+			if not names or #names == 0 then
+				errors[#errors + 1] = { kind = "reguse_malformed" }
+				return nil, errors
+			end
+			for _, n in ipairs(names) do
+				if first == "Reg_" then
+					if typed_fields then
+						for _, field in ipairs(typed_fields) do
+							local path = n .. "." .. field
+							if not add_alias(path, path) then return nil, errors end
+							if not add_slot(path, { path }, readonly) then return nil, errors end
+						end
+					end
+				else
+					if not add_alias(n, n) then return nil, errors end
+					if not add_slot(n, { n }, readonly) then return nil, errors end
+				end
+			end
+			pos = new_pos
+		else
+			errors[#errors + 1] = { kind = "reguse_malformed" }
+			return nil, errors
+		end
+		::continue::
+	end
+	if #slots == 0 then
+		if pending and not require_types then
+			return { slots = slots, alias_to_slot = alias_to_slot, pending = true }, errors
+		end
+		if #errors == 0 then
+			errors[#errors + 1] = { kind = "reguse_malformed" }
+		end
+		return nil, errors
+	end
+	return { slots = slots, alias_to_slot = alias_to_slot, pending = pending }, errors
+end
+
 --- Parse: `typedef` declarations.
 ---
 --- Recognizes four shapes:
@@ -1546,6 +1878,21 @@ local function parse_typedef_binds(source, pos, ident_end, line_of, out)
 		local body, after_brace = find_body_braces(source, after_paren, open_paren + 1)
 		if not body then return after_brace end
 		register_struct_type(body, name, pos, line_of, out)
+		if name:sub(1, 7) == "RegUse_" then
+			local schema, schema_errors = parse_reg_use_schema_body(body, out.type_name_registry)
+			if schema then
+				schema.name        = name
+				schema.source_file = out._source_file
+				schema.source_line = line_of(pos)
+				out.reg_use_schemas[name] = schema
+			end
+			for _, err in ipairs(schema_errors or {}) do
+				err.schema_name = name
+				err.source_file = out._source_file
+				err.source_line = line_of(pos)
+				out.reg_use_errors[#out.reg_use_errors + 1] = err
+			end
+		end
 		attach_debug_skip_marker(out, "unrelated")
 		return after_brace
 
@@ -1876,6 +2223,7 @@ local DECL_PARSERS = {
 	MipsAtom_Proc_             = parse_mips_atom_proc,
 	MipsAtomComp_              = parse_mips_atom_comp,
 	MipsAtomComp_Proc_         = parse_mips_atom_comp_proc,
+	MipsAtomComp_ProcMap_     = parse_mips_atom_comp_proc_map,
 	-- `atom_dbg_skip` is the only debug-skip parser entry. Every other
 	-- identifier follows the ordinary unrelated-token path; there is no alias.
 	atom_dbg_skip              = parse_dbg_skip_marker,
@@ -1895,6 +2243,137 @@ local DECL_PARSERS = {
 -- Only the bare `atom_dbg_skip` marker reaches `parse_dbg_skip_marker`.
 -- Unknown identifiers follow the same unrelated-token path as every other unsupported source token.
 
+local TAPE_SKIP_MACROS = {
+	MipsAtom_ = true,
+	MipsAtom_Proc_ = true,
+	MipsAtomComp_ = true,
+	MipsAtomComp_Proc_ = true,
+	MipsAtomComp_ProcMap_ = true,
+	Struct_ = true,
+	Enum_ = true,
+}
+
+local function collect_addrs_assigns(text)
+	local addrs = {}
+	local pos = 1
+	local n = #text
+	while pos <= n do
+		pos = duffle.skip_ws_and_cmt(text, pos)
+		if pos > n then break end
+		local ident, ident_end = duffle.read_ident(text, pos)
+		if ident == "addrs" then
+			local after = duffle.skip_ws_and_cmt(text, ident_end)
+			if text:sub(after, after) == "[" then
+				local inner, after_br = duffle.read_brackets(text, after)
+				local idx = inner and tonumber(duffle.trim(inner))
+				after_br = duffle.skip_ws_and_cmt(text, after_br or after)
+				if idx and text:sub(after_br, after_br) == "=" then
+					local rhs = duffle.skip_ws_and_cmt(text, after_br + 1)
+					local rhs_ident = duffle.read_ident(text, rhs)
+					if rhs_ident then addrs[idx] = rhs_ident end
+					pos = rhs
+				else
+					pos = after_br or (after + 1)
+				end
+			else
+				pos = ident_end
+			end
+		elseif ident then
+			pos = ident_end
+		else
+			pos = pos + 1
+		end
+	end
+	return addrs
+end
+
+local function collect_tb_emits(body, addrs)
+	local names = {}
+	local pos = 1
+	local n = #body
+	while pos <= n do
+		pos = duffle.skip_ws_and_cmt(body, pos)
+		if pos > n then break end
+		local ident, ident_end = duffle.read_ident(body, pos)
+		if ident == "tb_emit_" or ident == "tb_emit" then
+			local after = duffle.skip_ws_and_cmt(body, ident_end)
+			if body:sub(after, after) == "(" then
+				local inner, after_p = duffle.read_parens(body, after)
+				local name
+				if ident == "tb_emit_" then
+					name = duffle.trim(inner or ""):match("^([%w_]+)")
+				else
+					local args = duffle.split_top_level_commas(inner or "")
+					local last = duffle.trim(args[#args] or "")
+					local idx = last:match("^addrs%s*%[%s*(%d+)%s*%]$")
+					if idx then
+						name = addrs[tonumber(idx)]
+					else
+						name = last:match("([%w_]+)$")
+					end
+				end
+				if name then names[#names + 1] = name end
+				pos = after_p or (after + 1)
+			else
+				pos = ident_end
+			end
+		elseif ident then
+			pos = ident_end
+		else
+			pos = pos + 1
+		end
+	end
+	return names
+end
+
+-- Linear appearance order of tb_emit / tb_emit_ in each C function body.
+-- Commented-out emits are skipped by skip_ws_and_cmt. No C if/loop CFG.
+local function scan_tape_chains(source)
+	local addrs = collect_addrs_assigns(source)
+	local chains = {}
+	local pos = 1
+	local n = #source
+	while pos <= n do
+		pos = duffle.skip_ws_and_cmt(source, pos)
+		if pos > n then break end
+		local ident, ident_end = duffle.read_ident(source, pos)
+		if ident and TAPE_SKIP_MACROS[ident] then
+			local after = duffle.skip_ws_and_cmt(source, ident_end)
+			if source:sub(after, after) == "(" then
+				local _, after_p = duffle.read_parens(source, after)
+				after = duffle.skip_ws_and_cmt(source, after_p or after)
+			end
+			if source:sub(after, after) == "{" then
+				local _, after_b = duffle.read_braces(source, after)
+				pos = after_b or (after + 1)
+			else
+				pos = after
+			end
+		elseif ident then
+			local after = duffle.skip_ws_and_cmt(source, ident_end)
+			if source:sub(after, after) == "(" then
+				local _, after_p = duffle.read_parens(source, after)
+				after = duffle.skip_ws_and_cmt(source, after_p or after)
+				if source:sub(after, after) == "{" then
+					local body, after_b = duffle.read_braces(source, after)
+					local names = collect_tb_emits(body or "", addrs)
+					if #names > 0 then
+						chains[#chains + 1] = names
+					end
+					pos = after_b or (after + 1)
+				else
+					pos = after
+				end
+			else
+				pos = ident_end
+			end
+		else
+			pos = pos + 1
+		end
+	end
+	return chains
+end
+
 -- ════════════════════════════════════════════════════════════════════════════
 -- The single source walker
 -- ════════════════════════════════════════════════════════════════════════════
@@ -1913,6 +2392,7 @@ local function scan_source(source, source_file, code_macros, code_macro_bodies)
 		raw_atoms         = {},
 		binds             = {},
 		atom_infos        = {},
+		component_atom_infos = {},
 		macros            = {},
 		-- Raw marker evidence for annotation validation. The `debug_skip` boolean
 		-- is stamped on the declaration record itself; the projection lives on AtomEntry.debug_skip.
@@ -1937,6 +2417,8 @@ local function scan_source(source, source_file, code_macros, code_macro_bodies)
 		-- typedef chain walking (cycle-guarded, depth <= 8), and struct field sums.
 		-- See `propagate_type_sizes()` below.
 		type_name_registry = {},
+		reg_use_schemas    = {},
+		reg_use_errors     = {},
 		-- Shared `R_*_Code -> integer code` registry
 		-- (passed in from M.run pass 1; same reference so preprocessor intercept writes are visible to the enum-value resolver).
 		-- Stripped from `src.scan` before return.
@@ -2004,6 +2486,7 @@ local function scan_source(source, source_file, code_macros, code_macro_bodies)
 	-- Runs AFTER the source walk so all typedef / Struct_ / Enum_ declarations have been parsed into `out.type_name_registry`.
 	-- Mutates each entry's `byte_size` field in place; fields with pointer_depth > 0 already carry byte_size = 4 from parse time and are unaffected.
 	propagate_type_sizes(out)
+	out.tape_chains = scan_tape_chains(source)
 
 	return out
 end
@@ -2166,16 +2649,21 @@ local function merge_corpus_registries(corpus)
 	corpus.atom_ctxs               = corpus.atom_ctxs               or {}
 	corpus.atom_phases             = corpus.atom_phases             or {}
 	corpus.atom_infos              = corpus.atom_infos              or {}
+	corpus.component_atom_infos    = corpus.component_atom_infos    or {}
 	corpus.atom_auto_regs          = corpus.atom_auto_regs          or {}
 	corpus.phase_auto_regs         = corpus.phase_auto_regs         or {}
 	corpus.collisions              = corpus.collisions              or {}
+	corpus.reg_use_schemas         = corpus.reg_use_schemas         or {}
+	corpus.reg_use_errors          = corpus.reg_use_errors          or {}
+	corpus.tape_chains             = corpus.tape_chains             or {}
 
 	-- Replace the existing corpus collections with empty tables so a re-run on the same corpus produces identical state (deterministic merge).
 	-- This is safe because M.run is the only writer to these tables within a single orchestrator invocation.
 	for _, key in ipairs({
 		"register_alias_registry", "type_name_registry", "binds_by_name",
 		"atoms_by_name", "atom_views", "atom_ctxs", "atom_phases",
-		"atom_infos", "collisions",
+		"atom_infos", "component_atom_infos", "collisions", "reg_use_schemas", "reg_use_errors",
+		"tape_chains",
 	}) do
 		corpus[key] = {}
 	end
@@ -2268,6 +2756,65 @@ local function merge_corpus_registries(corpus)
 			for _, info in ipairs(scan.atom_infos or {}) do
 				corpus.atom_infos[#corpus.atom_infos + 1] = info
 			end
+			for _, info in ipairs(scan.component_atom_infos or {}) do
+				corpus.component_atom_infos[#corpus.component_atom_infos + 1] = info
+			end
+
+			for name, schema in pairs(scan.reg_use_schemas or {}) do
+				if corpus.reg_use_schemas[name] == nil then
+					corpus.reg_use_schemas[name] = schema
+				end
+			end
+			for _, err in ipairs(scan.reg_use_errors or {}) do
+				corpus.reg_use_errors[#corpus.reg_use_errors + 1] = err
+			end
+			for _, chain in ipairs(scan.tape_chains or {}) do
+				corpus.tape_chains[#corpus.tape_chains + 1] = chain
+			end
+		end
+	end
+end
+
+local SCHEMA_BODY_ERROR = {
+	reguse_malformed          = true,
+	reguse_unknown_reg_type   = true,
+	reguse_duplicate_alias    = true,
+	reguse_duplicate_slot     = true,
+	reguse_const_reg_spelling = true,
+	reguse_mixed_const        = true,
+}
+
+-- Re-parse every RegUse_* body against the merged type_name_registry.
+-- Scan-time expansion still runs when Reg_T is in the same source.
+-- Missing Reg_T after merge is reguse_unknown_reg_type, not a fallback table.
+local function resolve_reg_use_schemas(corpus)
+	local kept = {}
+	for _, err in ipairs(corpus.reg_use_errors or {}) do
+		if not SCHEMA_BODY_ERROR[err.kind] then
+			kept[#kept + 1] = err
+		end
+	end
+	corpus.reg_use_errors = kept
+
+	for name, type_entry in pairs(corpus.type_name_registry or {}) do
+		if name:sub(1, 7) == "RegUse_" and type_entry.body then
+			local fresh, errs = parse_reg_use_schema_body(
+				type_entry.body, corpus.type_name_registry, { require_types = true })
+			if fresh then
+				fresh.name = name
+				local old = corpus.reg_use_schemas[name]
+				fresh.source_file = (old and old.source_file) or type_entry.source_file
+				fresh.source_line = (old and old.source_line) or type_entry.source_line
+				corpus.reg_use_schemas[name] = fresh
+			else
+				corpus.reg_use_schemas[name] = nil
+			end
+			for _, err in ipairs(errs or {}) do
+				err.schema_name = name
+				err.source_file = type_entry.source_file
+				err.source_line = type_entry.source_line
+				corpus.reg_use_errors[#corpus.reg_use_errors + 1] = err
+			end
 		end
 	end
 end
@@ -2356,6 +2903,7 @@ function M.run(ctx)
 
 	-- Merge per-source scans into the corpus registries (see merge_corpus_registries for first-wins + collision discipline).
 	merge_corpus_registries(corpus)
+	resolve_reg_use_schemas(corpus)
 
 	-- code_macros and code_macro_bodies are function-local; the GC reclaims them on M.run return.
 	return { outputs = {}, errors = {}, warnings = {} }