Skip to content

Commit b549de1

Browse files
author
DavidQ
committed
Level 18.4 Codebase Consistency (Overlay Slice)
- Normalized naming - Removed duplicate helpers - Fixed import/export anti-patterns - Enforced consistency rules
1 parent 00103bf commit b549de1

8 files changed

Lines changed: 135 additions & 124 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,11 @@ MODEL: GPT-5.3-codex
22
REASONING: high
33

44
COMMAND:
5-
- Identify overlay public APIs
6-
- Freeze contracts
7-
- Remove unstable/internal exposure
5+
- Scan overlay runtime files only
6+
- Normalize naming conventions
7+
- Deduplicate helpers
8+
- Fix import/export patterns
89
- Validate tests
910

1011
Output:
11-
<project folder>/tmp/BUILD_PR_LEVEL_18_3_CONTRACT_STABILIZATION_OVERLAY_SLICE.zip
12+
<project folder>/tmp/BUILD_PR_LEVEL_18_4_CODEBASE_CONSISTENCY_OVERLAY_SLICE.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
Level 18.3 Contract Stabilization (Overlay Slice)
1+
Level 18.4 Codebase Consistency (Overlay Slice)
22

3-
- Stabilized overlay APIs
4-
- Locked selectors/providers
5-
- Removed unstable surfaces
3+
- Normalized naming
4+
- Removed duplicate helpers
5+
- Fixed import/export anti-patterns
6+
- Enforced consistency rules

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1-
[ ] contracts documented
2-
[ ] no breaking changes
1+
[ ] naming consistent
2+
[ ] no duplicate helpers
3+
[ ] imports clean
34
[ ] tests pass

‎docs/pr/BUILD_PR_LEVEL_18_4_CODEBASE_CONSISTENCY_OVERLAY_SLICE.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# BUILD PR LEVEL 18.4 — Codebase Consistency (Overlay Slice)
2+
3+
Purpose:
4+
Enforce consistency rules within overlay runtime.
5+
6+
Scope:
7+
- Overlay runtime only
8+
- No repo-wide sweep
9+
10+
Changes:
11+
- Normalize naming
12+
- Remove duplicate helpers
13+
- Enforce single-class-per-file where applicable
14+
- Fix import/export anti-patterns
15+
16+
Validation:
17+
- Overlay tests pass
18+
- No regressions in samples using overlays

‎samples/phase-17/shared/overlayExpansionContracts.js‎

Lines changed: 2 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ David Quesenberry
44
04/16/2026
55
overlayExpansionContracts.js
66
*/
7+
import { normalizeOverlayRuntimeExtensions } from '/samples/phase-17/shared/overlayRuntimeExtensionNormalization.js';
78

89
const DEFAULT_CHANNEL = 'debug';
910

@@ -45,61 +46,6 @@ function resolveInitialOverlayId(overlays, initialOverlayId) {
4546
return exists ? requestedId : overlays[0].id;
4647
}
4748

48-
function normalizeRuntimeExtensionEntry(entry) {
49-
if (!entry || typeof entry !== 'object') {
50-
return null;
51-
}
52-
53-
const overlayId = String(entry.overlayId || '').trim();
54-
const onStep = typeof entry.onStep === 'function' ? entry.onStep : null;
55-
const onRender = typeof entry.onRender === 'function' ? entry.onRender : null;
56-
const resolvePanelSize = typeof entry.resolvePanelSize === 'function' ? entry.resolvePanelSize : null;
57-
const resolveContextBehavior = typeof entry.resolveContextBehavior === 'function'
58-
? entry.resolveContextBehavior
59-
: null;
60-
if (!onStep && !onRender) {
61-
return null;
62-
}
63-
64-
const layerOrderRaw = Number(entry.layerOrder);
65-
const layerOrder = Number.isFinite(layerOrderRaw) ? layerOrderRaw : 0;
66-
const visualPriorityRaw = Number(entry.visualPriority);
67-
const visualPriority = Number.isFinite(visualPriorityRaw) ? visualPriorityRaw : layerOrder;
68-
const panelWidthRaw = Number(entry.panelWidth);
69-
const panelHeightRaw = Number(entry.panelHeight);
70-
const panelWidth = Number.isFinite(panelWidthRaw) && panelWidthRaw > 0 ? panelWidthRaw : 260;
71-
const panelHeight = Number.isFinite(panelHeightRaw) && panelHeightRaw > 0 ? panelHeightRaw : 96;
72-
73-
return Object.freeze({
74-
overlayId,
75-
onStep,
76-
onRender,
77-
resolvePanelSize,
78-
resolveContextBehavior,
79-
compose: entry.compose === true,
80-
layerOrder,
81-
visualPriority,
82-
panelWidth,
83-
panelHeight,
84-
});
85-
}
86-
87-
function normalizeRuntimeExtensions(runtimeExtensions) {
88-
if (!Array.isArray(runtimeExtensions) || runtimeExtensions.length === 0) {
89-
return Object.freeze([]);
90-
}
91-
92-
const normalized = [];
93-
for (let i = 0; i < runtimeExtensions.length; i += 1) {
94-
const candidate = normalizeRuntimeExtensionEntry(runtimeExtensions[i]);
95-
if (!candidate) {
96-
continue;
97-
}
98-
normalized.push(candidate);
99-
}
100-
return Object.freeze(normalized);
101-
}
102-
10349
export function defineOverlayExtensionContract({
10450
id = '',
10551
overlays = [],
@@ -124,7 +70,7 @@ export function defineOverlayExtensionContract({
12470
const normalizedPersistenceKey = String(persistenceKey || '').trim();
12571
const normalizedChannel = String(channel || DEFAULT_CHANNEL).trim() || DEFAULT_CHANNEL;
12672
const normalizedInitialOverlayId = resolveInitialOverlayId(normalizedOverlays, initialOverlayId);
127-
const normalizedRuntimeExtensions = normalizeRuntimeExtensions(runtimeExtensions);
73+
const normalizedRuntimeExtensions = normalizeOverlayRuntimeExtensions(runtimeExtensions);
12874

12975
return Object.freeze({
13076
id: normalizedId,

‎samples/phase-17/shared/overlayGameplayRuntime.js‎

Lines changed: 3 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
isOverlayRuntimeToggleModifierActive,
1010
LEVEL17_OVERLAY_CYCLE_KEY,
1111
} from '/samples/phase-17/shared/overlayCycleInput.js';
12+
import { normalizeOverlayRuntimeExtensions } from '/samples/phase-17/shared/overlayRuntimeExtensionNormalization.js';
1213
import { cloneJsonData, safeJsonParse, safeJsonStringify } from '/src/shared/io/index.js';
1314
import { asFiniteNumber } from '/src/shared/number/index.js';
1415

@@ -64,62 +65,6 @@ const OVERLAY_RUNTIME_DEFAULT_PRESET_DEFINITIONS = Object.freeze([
6465
}),
6566
]);
6667

67-
function normalizeRuntimeExtensionEntry(entry) {
68-
if (!entry || typeof entry !== 'object') {
69-
return null;
70-
}
71-
72-
const overlayId = String(entry.overlayId || '').trim();
73-
const onStep = typeof entry.onStep === 'function' ? entry.onStep : null;
74-
const onRender = typeof entry.onRender === 'function' ? entry.onRender : null;
75-
if (!onStep && !onRender) {
76-
return null;
77-
}
78-
79-
const layerOrderRaw = Number(entry.layerOrder);
80-
const layerOrder = Number.isFinite(layerOrderRaw) ? layerOrderRaw : 0;
81-
const visualPriorityRaw = Number(entry.visualPriority);
82-
const visualPriority = Number.isFinite(visualPriorityRaw) ? visualPriorityRaw : layerOrder;
83-
const compose = entry.compose === true;
84-
const panelWidthRaw = Number(entry.panelWidth);
85-
const panelHeightRaw = Number(entry.panelHeight);
86-
const panelWidth = Number.isFinite(panelWidthRaw) && panelWidthRaw > 0 ? panelWidthRaw : 260;
87-
const panelHeight = Number.isFinite(panelHeightRaw) && panelHeightRaw > 0 ? panelHeightRaw : 96;
88-
const resolvePanelSize = typeof entry.resolvePanelSize === 'function' ? entry.resolvePanelSize : null;
89-
const resolveContextBehavior = typeof entry.resolveContextBehavior === 'function'
90-
? entry.resolveContextBehavior
91-
: null;
92-
93-
return Object.freeze({
94-
overlayId,
95-
onStep,
96-
onRender,
97-
resolvePanelSize,
98-
resolveContextBehavior,
99-
compose,
100-
layerOrder,
101-
visualPriority,
102-
panelWidth,
103-
panelHeight,
104-
});
105-
}
106-
107-
function normalizeRuntimeExtensions(runtimeExtensions) {
108-
if (!Array.isArray(runtimeExtensions) || runtimeExtensions.length === 0) {
109-
return Object.freeze([]);
110-
}
111-
112-
const normalized = [];
113-
for (let i = 0; i < runtimeExtensions.length; i += 1) {
114-
const candidate = normalizeRuntimeExtensionEntry(runtimeExtensions[i]);
115-
if (!candidate) {
116-
continue;
117-
}
118-
normalized.push(candidate);
119-
}
120-
return Object.freeze(normalized);
121-
}
122-
12368
function shouldRunRuntimeExtension(extension, activeOverlayId) {
12469
if (!extension) {
12570
return false;
@@ -1697,7 +1642,7 @@ export function createOverlayGameplayRuntime({
16971642
cycleKey = LEVEL17_OVERLAY_CYCLE_KEY,
16981643
} = {}) {
16991644
const runtime = {
1700-
runtimeExtensions: normalizeRuntimeExtensions(runtimeExtensions),
1645+
runtimeExtensions: normalizeOverlayRuntimeExtensions(runtimeExtensions),
17011646
interactionVisible: true,
17021647
interactionIndex: 0,
17031648
interactionCycleLatch: false,
@@ -1734,7 +1679,7 @@ export function setOverlayGameplayRuntimeExtensions(runtime, runtimeExtensions)
17341679
if (!runtime) {
17351680
return false;
17361681
}
1737-
runtime.runtimeExtensions = normalizeRuntimeExtensions(runtimeExtensions);
1682+
runtime.runtimeExtensions = normalizeOverlayRuntimeExtensions(runtimeExtensions);
17381683
normalizeInteractionIndex(runtime);
17391684
return true;
17401685
}

‎samples/phase-17/shared/overlayRuntimeExtensionNormalization.js‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
/*
2+
Toolbox Aid
3+
David Quesenberry
4+
04/17/2026
5+
overlayRuntimeExtensionNormalization.js
6+
*/
7+
8+
export function normalizeOverlayRuntimeExtensionEntry(entry) {
9+
if (!entry || typeof entry !== 'object') {
10+
return null;
11+
}
12+
13+
const overlayId = String(entry.overlayId || '').trim();
14+
const onStep = typeof entry.onStep === 'function' ? entry.onStep : null;
15+
const onRender = typeof entry.onRender === 'function' ? entry.onRender : null;
16+
if (!onStep && !onRender) {
17+
return null;
18+
}
19+
20+
const layerOrderRaw = Number(entry.layerOrder);
21+
const layerOrder = Number.isFinite(layerOrderRaw) ? layerOrderRaw : 0;
22+
const visualPriorityRaw = Number(entry.visualPriority);
23+
const visualPriority = Number.isFinite(visualPriorityRaw) ? visualPriorityRaw : layerOrder;
24+
const panelWidthRaw = Number(entry.panelWidth);
25+
const panelHeightRaw = Number(entry.panelHeight);
26+
const panelWidth = Number.isFinite(panelWidthRaw) && panelWidthRaw > 0 ? panelWidthRaw : 260;
27+
const panelHeight = Number.isFinite(panelHeightRaw) && panelHeightRaw > 0 ? panelHeightRaw : 96;
28+
const resolvePanelSize = typeof entry.resolvePanelSize === 'function' ? entry.resolvePanelSize : null;
29+
const resolveContextBehavior = typeof entry.resolveContextBehavior === 'function'
30+
? entry.resolveContextBehavior
31+
: null;
32+
33+
return Object.freeze({
34+
overlayId,
35+
onStep,
36+
onRender,
37+
resolvePanelSize,
38+
resolveContextBehavior,
39+
compose: entry.compose === true,
40+
layerOrder,
41+
visualPriority,
42+
panelWidth,
43+
panelHeight,
44+
});
45+
}
46+
47+
export function normalizeOverlayRuntimeExtensions(runtimeExtensions) {
48+
if (!Array.isArray(runtimeExtensions) || runtimeExtensions.length === 0) {
49+
return Object.freeze([]);
50+
}
51+
52+
const normalized = [];
53+
for (let i = 0; i < runtimeExtensions.length; i += 1) {
54+
const candidate = normalizeOverlayRuntimeExtensionEntry(runtimeExtensions[i]);
55+
if (!candidate) {
56+
continue;
57+
}
58+
normalized.push(candidate);
59+
}
60+
return Object.freeze(normalized);
61+
}

‎tests/runtime/Phase19OverlayExpansionFramework.test.mjs‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,14 @@ function assertOverlayRuntimeSliceUsesSharedFiniteNumberHelper() {
7575
new URL('../../samples/phase-17/shared/overlayGameplayRuntime.js', import.meta.url),
7676
'utf8'
7777
);
78+
const contractsSource = readFileSync(
79+
new URL('../../samples/phase-17/shared/overlayExpansionContracts.js', import.meta.url),
80+
'utf8'
81+
);
82+
const normalizationSource = readFileSync(
83+
new URL('../../samples/phase-17/shared/overlayRuntimeExtensionNormalization.js', import.meta.url),
84+
'utf8'
85+
);
7886
const importSpecifiers = Array.from(
7987
runtimeSource.matchAll(/^\s*import\s+[\s\S]*?\sfrom\s+['"]([^'"]+)['"]\s*;?\s*$/gm),
8088
(match) => String(match[1] || '').trim()
@@ -99,6 +107,36 @@ function assertOverlayRuntimeSliceUsesSharedFiniteNumberHelper() {
99107
false,
100108
'Overlay runtime slice should not keep a local duplicate JSON-clone helper.'
101109
);
110+
assert.equal(
111+
runtimeSource.includes("import { normalizeOverlayRuntimeExtensions } from '/samples/phase-17/shared/overlayRuntimeExtensionNormalization.js';"),
112+
true,
113+
'Overlay runtime slice should import shared runtime-extension normalization helper.'
114+
);
115+
assert.equal(
116+
contractsSource.includes("import { normalizeOverlayRuntimeExtensions } from '/samples/phase-17/shared/overlayRuntimeExtensionNormalization.js';"),
117+
true,
118+
'Overlay runtime contracts should import shared runtime-extension normalization helper.'
119+
);
120+
assert.equal(
121+
runtimeSource.includes('function normalizeRuntimeExtensionEntry('),
122+
false,
123+
'Overlay runtime slice should not duplicate runtime-extension entry normalization locally.'
124+
);
125+
assert.equal(
126+
contractsSource.includes('function normalizeRuntimeExtensionEntry('),
127+
false,
128+
'Overlay runtime contracts should not duplicate runtime-extension entry normalization locally.'
129+
);
130+
assert.equal(
131+
normalizationSource.includes('export function normalizeOverlayRuntimeExtensionEntry('),
132+
true,
133+
'Shared runtime-extension normalization helper should expose entry normalization.'
134+
);
135+
assert.equal(
136+
normalizationSource.includes('export function normalizeOverlayRuntimeExtensions('),
137+
true,
138+
'Shared runtime-extension normalization helper should expose list normalization.'
139+
);
102140
assert.equal(
103141
runtimeSource.includes('export function synchronizeOverlayGameplayRuntimeState('),
104142
false,

0 commit comments

Comments
 (0)