BUILD PR: centralize high score helpers across games.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,10 +1,8 @@
 MODEL: GPT-5.3-codex
 REASONING: high
 COMMAND:
-Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_28_CLAMP_CORE_BATCH.md exactly.
-Edit only:
-- src/engine/utils/math.js (export fix only if needed)
-- listed game files
-Fail fast if clamp is not available.
+Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_29_HIGHSCORE_HELPERS_BATCH.md exactly.
+Edit only listed files.
+Create shared helper file.
 Do not expand scope.
-Package to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_28_CLAMP_CORE_BATCH_delta.zip
+Package to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_29_HIGHSCORE_HELPERS_BATCH_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD PR: centralize clamp(value,min,max) across core game batch.
+BUILD PR: centralize high score helpers across games.

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-clamp core batch extraction
+high score helpers centralized

docs/dev/reports/validation_checklist.txt

@@ -1 +1 @@
-clamp centralized
+helpers moved to shared

docs/pr/BUILD_PR_SHARED_EXTRACTION_29_HIGHSCORE_HELPERS_BATCH.md

@@ -0,0 +1,64 @@
+# BUILD_PR_SHARED_EXTRACTION_29_HIGHSCORE_HELPERS_BATCH
+
+## Purpose
+Centralize duplicated high score helper functions across game implementations into a shared game utility.
+
+## Single PR Purpose
+Normalize ONLY these helpers:
+
+- sanitizeScore(value)
+- sanitizeInitials(value)
+- sanitizeRow(row)
+- sortRows(rows)
+
+Target files:
+
+1. games/Asteroids/systems/AsteroidsHighScoreService.js
+2. games/SpaceDuel/game/SpaceDuelHighScoreService.js
+3. games/SpaceInvaders/game/SpaceInvadersHighScoreService.js
+
+## Exact Files Allowed
+
+### New shared file (allowed in this PR)
+1. src/shared/utils/highScoreUtils.js
+
+### Consumers
+2. games/Asteroids/systems/AsteroidsHighScoreService.js
+3. games/SpaceDuel/game/SpaceDuelHighScoreService.js
+4. games/SpaceInvaders/game/SpaceInvadersHighScoreService.js
+
+## Shared Helper Creation
+Create:
+src/shared/utils/highScoreUtils.js
+
+Export exactly:
+- sanitizeScore
+- sanitizeInitials
+- sanitizeRow
+- sortRows
+
+Use ONE of the existing implementations as source-of-truth.
+Do NOT merge logic.
+Do NOT change behavior.
+
+## Consumer Changes
+
+For each consumer file:
+- remove local helper implementations for the 4 functions
+- import from src/shared/utils/highScoreUtils.js
+- keep all logic intact
+
+## Constraints
+- no engine changes
+- no other helpers
+- no behavior change
+- exact batch only
+
+## Validation
+- helpers exist only in shared file
+- consumers import correctly
+- behavior unchanged
+
+## Non-Goals
+- no other score systems
+- no UI changes

games/Asteroids/systems/AsteroidsHighScoreService.js

@@ -5,6 +5,12 @@ David Quesenberry
 AsteroidsHighScoreService.js
 */
 import { StorageService } from '../../../src/engine/persistence/index.js';
+import {
+  sanitizeScore,
+  sanitizeInitials,
+  sanitizeRow,
+  sortRows,
+} from '../../../src/shared/utils/highScoreUtils.js';
 
 const DEFAULT_KEY = 'toolboxaid:games:asteroids:high-score-table';
 const DEFAULT_ROWS = [
@@ -15,29 +21,6 @@ const DEFAULT_ROWS = [
   { initials: 'BOT', score: 500 },
 ];
 
-function sanitizeScore(value) {
-  if (!Number.isFinite(value)) {
-    return 0;
-  }
-  return Math.max(0, Math.trunc(value));
-}
-
-function sanitizeInitials(value) {
-  const letters = String(value ?? '').toUpperCase().replace(/[^A-Z]/g, '');
-  return (letters || 'AAA').slice(0, 3).padEnd(3, 'A');
-}
-
-function sanitizeRow(row) {
-  return {
-    initials: sanitizeInitials(row?.initials),
-    score: sanitizeScore(row?.score),
-  };
-}
-
-function sortRows(rows) {
-  return [...rows].sort((a, b) => b.score - a.score);
-}
-
 export default class AsteroidsHighScoreService {
   constructor({ key = DEFAULT_KEY, tableSize = 5, storage = null } = {}) {
     this.key = key;

games/SpaceDuel/game/SpaceDuelHighScoreService.js

@@ -5,6 +5,12 @@ David Quesenberry
 SpaceDuelHighScoreService.js
 */
 import { StorageService } from '../../../src/engine/persistence/index.js';
+import {
+  sanitizeScore,
+  sanitizeInitials,
+  sanitizeRow,
+  sortRows,
+} from '../../../src/shared/utils/highScoreUtils.js';
 
 const DEFAULT_KEY = 'toolboxaid:games:space-duel:high-scores';
 const DEFAULT_TABLE = [
@@ -15,29 +21,6 @@ const DEFAULT_TABLE = [
   { initials: 'BOT', score: 500 },
 ];
 
-function sanitizeInitials(value) {
-  const letters = String(value ?? '').toUpperCase().replace(/[^A-Z]/g, '');
-  return (letters || '???').slice(0, 3).padEnd(3, 'A');
-}
-
-function sanitizeScore(value) {
-  if (!Number.isFinite(value)) {
-    return 0;
-  }
-  return Math.max(0, Math.trunc(value));
-}
-
-function sanitizeRow(row) {
-  return {
-    initials: sanitizeInitials(row?.initials),
-    score: sanitizeScore(row?.score),
-  };
-}
-
-function sortRows(rows) {
-  return [...rows].sort((a, b) => b.score - a.score);
-}
-
 export default class SpaceDuelHighScoreService {
   constructor({
     key = DEFAULT_KEY,

games/SpaceInvaders/game/SpaceInvadersHighScoreService.js

@@ -5,6 +5,12 @@ David Quesenberry
 SpaceInvadersHighScoreService.js
 */
 import { StorageService } from '../../../src/engine/persistence/index.js';
+import {
+  sanitizeScore,
+  sanitizeInitials,
+  sanitizeRow,
+  sortRows,
+} from '../../../src/shared/utils/highScoreUtils.js';
 
 const DEFAULT_KEY = 'toolboxaid:games:space-invaders:high-score-table';
 const DEFAULT_ROWS = [
@@ -15,29 +21,6 @@ const DEFAULT_ROWS = [
   { initials: 'BOT', score: 500 },
 ];
 
-function sanitizeScore(value) {
-  if (!Number.isFinite(value)) {
-    return 0;
-  }
-  return Math.max(0, Math.trunc(value));
-}
-
-function sanitizeInitials(value) {
-  const letters = String(value ?? '').toUpperCase().replace(/[^A-Z]/g, '');
-  return (letters || 'AAA').slice(0, 3).padEnd(3, 'A');
-}
-
-function sanitizeRow(row) {
-  return {
-    initials: sanitizeInitials(row?.initials),
-    score: sanitizeScore(row?.score),
-  };
-}
-
-function sortRows(rows) {
-  return [...rows].sort((a, b) => b.score - a.score);
-}
-
 export default class SpaceInvadersHighScoreService {
   constructor({ key = DEFAULT_KEY, tableSize = 5, storage = null } = {}) {
     this.key = key;

src/shared/utils/highScoreUtils.js

@@ -0,0 +1,22 @@
+export function sanitizeScore(value) {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, Math.trunc(value));
+}
+
+export function sanitizeInitials(value) {
+  const letters = String(value ?? "").toUpperCase().replace(/[^A-Z]/g, "");
+  return (letters || "AAA").slice(0, 3).padEnd(3, "A");
+}
+
+export function sanitizeRow(row) {
+  return {
+    initials: sanitizeInitials(row?.initials),
+    score: sanitizeScore(row?.score),
+  };
+}
+
+export function sortRows(rows) {
+  return [...rows].sort((a, b) => b.score - a.score);
+}