brick-engine-js 1.0.1

package/docs/reference/modules/SessionModal.adoc

@@ -0,0 +1,34 @@
+= SessionModal Module Reference
+:description: Handles the UI layer interaction for restoring saved active play sessions.
+:keywords: modal, ui, dialog, DOM, restoration, session
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+
+The `SessionModal` interacts directly with the DOM outside of the Canvas domain, creating standard HTML elements (divs and buttons) overlapping the P5.js context to prompt users whether they wish to resume their previous game session.
+
+== Lifecycle 
+
+=== `setup(): void`
+
+Creates the necessary DOM layer elements. Called typically during engine bootstrap by the `xref:../../view/GameView.adoc[GameView]`.
+Constructs the background container wrapper, title frames, dialogue text, and confirm/cancel action buttons. Sets their initial state utilizing the CSS `.hidden` class to keep them out of view until queried.
+
+=== `show(onConfirm: () => void, onCancel: () => void): void`
+
+Reveals the modal.
+
+**Parameters**
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`onConfirm` |`Function` |The closure executed if the user selects "Confirm".
+|`onCancel` |`Function` |The closure executed if the user selects "Cancel".
+|===
+
+**Behavior**
+
+Hooks the callback functions directly to the `mousePressed` listener of the individual DOM buttons. Upon clicking any of the buttons, it executes the passed callback and immediately invokes `_hide()`, returning to its hidden CSS boundary.

package/docs/reference/types/Axis.adoc

@@ -0,0 +1,28 @@
+= Axis Reference
+:description: Represents an axis in a 2D coordinate system.
+:keywords: axis, coordinate, 2d, transformation, mirror
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Represents an axis in a 2D coordinate system.
+
+== Possible Values
+
+[cols="1,3"]
+|===
+|Value |Description
+|`'x'` |The horizontal axis.
+|`'y'` |The vertical axis.
+|===
+
+== General Usage
+
+The `Axis` type is primarily used for transformation operations that apply selectively to one dimension, such as mirroring a piece across a specific axis.

package/docs/reference/types/Cell.adoc

@@ -0,0 +1,29 @@
+= Cell Reference
+:description: Represents the state of an individual unit within the 2D game grid.
+:keywords: cell, grid, unit, state
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Represents the state of an individual unit within the 2D game grid.
+
+== Attributes
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`value` |`number` |Lifecycle value. `0` is empty, `>0` is occupied.
+|`color` |xref:../enums/Color.adoc[Color] |The theme color to render the cell with.
+|`coordinate` |xref:Coordinate.adoc[Coordinate] |The `{x, y}` position of this cell.
+|===
+
+== General Usage
+
+Cells are managed by the `xref:../modules/GameGrid.adoc[GameGrid]` module. They are rarely created manually; instead, they are accessed and modified via methods like `grid.getCell(coord)` and `grid.setCellValue(coord, val)`.

package/docs/reference/types/ControlCallback.adoc

@@ -0,0 +1,23 @@
+= ControlCallback Reference
+:description: Type definition for functions that handle engine input.
+:keywords: callback, control, input, subscriber
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Type definition for functions that handle engine input.
+
+== Structure
+
+`type ControlCallback = (event: xref:GameEvent.adoc[GameEvent]) => void;`
+
+== General Usage
+
+This type ensures that functions passed to `modules.control.subscribe(key, type, callback)` (see `xref:../modules/GameControl.adoc[GameControl]`) correctly accept the `xref:GameEvent.adoc[GameEvent]` context.

package/docs/reference/types/Coordinate.adoc

@@ -0,0 +1,29 @@
+= Coordinate Reference
+:description: A foundational 2D point interface used for positioning on grid or display.
+:keywords: coordinate, point, position, 2d
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+A foundational 2D point interface used for positioning.
+
+== Attributes
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`x` |`number` |Horizontal axis value.
+|`y` |`number` |Vertical axis value.
+|===
+
+== General Usage
+
+Coordinates describe grid positions (columns/rows) as integers, or normalized screen positions as floats (0.0 to 1.0).
+Use `xref:../helpers/CoordinateHelper.adoc[CoordinateHelper]` for translations between these systems.

package/docs/reference/types/GameEntry.adoc

@@ -0,0 +1,29 @@
+= GameEntry Reference
+:description: Defines the structure for games registered in the engine's repository.
+:keywords: game, entry, repository, structure
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Defines the structure for games registered in the engine's repository.
+
+== Attributes
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`id` |`string` |The unique identifier of the game instance.
+|`name` |`string` |The human-readable label for the game.
+|`url` |`string` |The remote URL of the game's JavaScript bundle.
+|===
+
+== General Usage
+
+The repository uses `GameEntry` to populate menu lists and manage the lifecycle of different game instances.

package/docs/reference/types/GameEvent.adoc

@@ -0,0 +1,29 @@
+= GameEvent Reference
+:description: The context object delivered to input subscribers during events.
+:keywords: event, input, subscriber, context
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+The context object delivered to input subscribers.
+
+== Attributes
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`key` |xref:../enums/ControlKey.adoc[ControlKey] |The identifier for the triggered key.
+|`type` |xref:../enums/ControlEventType.adoc[ControlEventType] |Whether the key was `PRESSED` or is being `HELD`.
+|`modules` |xref:../interfaces/GameModules.adoc[GameModules] |Accessor for all engine services.
+|===
+
+== General Usage
+
+When a control callback is executed, it receives a `GameEvent`. This allows the game logic to react based on the key type and interact with the `xref:../interfaces/modules/Grid.adoc[Grid]`, `xref:../interfaces/modules/State.adoc[State]`, or `xref:../interfaces/modules/Score.adoc[Score]` modules.

package/docs/reference/types/Piece.adoc

@@ -0,0 +1,32 @@
+= Piece Reference
+:description: Represents a collection of cells that form a game piece or "stamp".
+:keywords: piece, stamp, cells, grid, collection
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Represents a collection of `xref:Cell.adoc[Cell]` objects that form a cohesive game piece or a pattern to be "stamped" onto the grid.
+
+== Definition
+
+[source,typescript]
+----
+export type Piece = Cell[];
+----
+
+== General Usage
+
+The `Piece` type is the main unit of interaction for complex grid operations. By working with an array of `xref:Cell.adoc[Cell]` instead of raw `xref:Coordinate.adoc[Coordinate]`, the engine can preserve properties like color and value during movement and transformation.
+
+Common operations involving pieces include:
+
+* **Stamping**: Permanently applying the piece's cells to the grid.
+* **Movement**: Shifting all cells within a piece simultaneously while checking for collisions.
+* **Transformation**: Rotating, mirroring, or projecting the piece onto different grid locations.

package/docs/reference/types/RendererMetrics.adoc

@@ -0,0 +1,29 @@
+= RendererMetrics Reference
+:description: Defines the calculated dimensions and offsets for the physical layout.
+:keywords: metrics, renderer, layout, dimensions, offsets
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Defines the calculated dimensions and offsets for the physical layout.
+
+== Attributes
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`display` |`object` |Contains `width`, `height`, and `origin` (xref:Coordinate.adoc[Coordinate]) for the main screen.
+|`hud` |`object` |Contains `width`, `height`, and `origin` (xref:Coordinate.adoc[Coordinate]) for the HUD area.
+|`cell` |`object` |Contains the `size` (number) in pixels of a single grid cell.
+|===
+
+== General Usage
+
+This data is calculated by the `xref:../modules/GameRenderer.adoc[GameRenderer]` and consumed by specialized sub-renderers like `xref:../modules/DisplayRenderer.adoc[DisplayRenderer]`, `xref:../modules/HudRenderer.adoc[HudRenderer]`, and `xref:../modules/GameText.adoc[GameText]` to ensure alignment.

package/docs/reference/types/Vector.adoc

@@ -0,0 +1,28 @@
+= Vector Reference
+:description: Represents a generic 2D vector for directional or magnitude calculations.
+:keywords: vector, direction, magnitude, 2d, transformation
+:toc: left
+:toclevels: 3
+:sectnums:
+:sectlinks:
+:icons: font
+:source-highlighter: highlight.js
+:reproducible:
+:experimental:
+:idprefix:
+:idseparator: -
+
+Represents a generic 2D vector for directional or magnitude calculations.
+
+== Attributes
+
+[cols="1,1,3"]
+|===
+|Name |Type |Description
+|`x` |`-1 \| 0 \| 1` |Horizontal direction offset.
+|`y` |`-1 \| 0 \| 1` |Vertical direction offset.
+|===
+
+== General Usage
+
+Unlike `xref:Coordinate.adoc[Coordinate]`, which usually implies a position, `Vector` is used for transformations, velocities, and offsets applied to coordinates.

package/docs/testing_best_practices.adoc

@@ -0,0 +1,190 @@
+= Testing Best Practices with Vitest
+:toc: left
+:icons: font
+
+This document defines the standards and best practices for unit testing in the Brick Engine project using **Vitest**. It is designed to be easily parsed by both developers and AI assistants.
+
+== Core Pattern: Triple A (AAA)
+
+All tests must follow the **Arrange, Act, Assert** pattern. Use explicit comments to demarcate these phases, as this helps AI models understand the test logic context.
+
+=== [ARRANGE]
+Set up the test environment, prepare data, and initialize the object under test.
+[source,typescript]
+----
+// [ARRANGE]
+const grid = new GameGrid();
+const coordinate = { x: 5, y: 5 };
+----
+
+=== [ACT]
+Execute the specific method or behavior being tested. Limit this to a single action if possible.
+[source,typescript]
+----
+// [ACT]
+const result = grid.isValidCoordinate(coordinate);
+----
+
+=== [ASSERT]
+Verify the outcome. Use descriptive expectations.
+[source,typescript]
+----
+// [ASSERT]
+expect(result).toBe(true);
+----
+
+== Naming Conventions
+
+Test descriptions should follow the pattern: `should [expected result] when [scenario or action]`.
+
+*   *Bad:* `test grid validation`
+*   *Good:* `should return true when coordinate is within grid boundaries`
+
+== AI-Assisted Testing Best Practices
+
+To facilitate AI-driven test generation and debugging:
+
+1.  **Be Explicit**: Use the `// [ARRANGE]`, `// [ACT]`, and `// [ASSERT]` tags.
+2.  **Context Injection**: When asking an AI to write a test, provide the interface of the module and dependencies.
+3.  **One Logic per Test**: Avoid "Giant Tests". Test one specific behavior per `it` block.
+4.  **Mocking Constants**: Always mock global configurations (like `configs`) to ensure tests are deterministic.
+
+== Vitest Configuration Standard
+
+*   **Globals**: Use `globals: true` to avoid importing `describe`, `it`, `expect` in every file.
+*   **Environment**: Use `@vitest-environment jsdom` at the top of files that interact with DOM or p5.js.
+*   **Coverage**: Target at least 80% coverage for "Engines" and "Helpers".
+*   **Aliases**: If using bundler aliases (e.g., `@client-game`), define them in `vitest.config.ts` using `resolve.alias`.
+
+== Advanced Mocking & Stubs
+
+=== Mocking Browser APIs
+For tests requiring browser features in JSDOM:
+
+[source,typescript]
+----
+// [ARRANGE]
+vi.stubGlobal('localStorage', {
+    getItem: vi.fn(),
+    setItem: vi.fn(),
+});
+
+vi.stubGlobal('AudioContext', vi.fn().mockImplementation(function() {
+    return {
+        createGain: vi.fn().mockReturnThis(),
+        destination: {},
+    };
+}));
+----
+
+=== Constructible Mocks
+When mocking a class that will be instantiated with `new`, Vitest requires the mock to be a `function` or `class`:
+
+[source,typescript]
+----
+vi.mock('./MyModule', () => ({
+    default: vi.fn().mockImplementation(function() {
+        return {
+            doSomething: vi.fn()
+        };
+    })
+}));
+----
+
+=== Hoisted Variables
+If you need to share variables between your test and the `vi.mock` factory (which is hoisted), use `vi.hoisted`:
+
+[source,typescript]
+----
+const { mockRef } = vi.hoisted(() => ({
+    mockRef: { id: 1 }
+}));
+
+vi.mock('./module', () => ({
+    default: () => mockRef
+}));
+----
+
+== Testing Entry Points (main.ts)
+
+Tests for entry points that execute code on import require isolation:
+
+1.  Use `vi.resetModules()` in `beforeEach`.
+2.  Use dynamic `import()` within the `it` block.
+3.  Set environment flags (like `APP_MODE`) *before* the dynamic import.
+
+[source,typescript]
+----
+it('should init in client mode', async () => {
+    (isClientMode as vi.Mock).mockReturnValue(true);
+    await import('./main'); // Triggers execution
+    expect(p5).toHaveBeenCalled();
+});
+----
+
+=== Workaround for Dynamic Imports with Webpack/TS (TS1323)
+
+When the project uses a `tsconfig.json` meant for the browser (e.g., configuring `module: commonjs`), running bundlers like `webpack` over the test files can trigger **TS1323** because the TS compiler doesn't understand the dynamic inputs naturally.
+
+**To resolve this properly without ANY `@ts-expect-error`:**
+1.  Set the `module` resolving option in `tsconfig.json` to `"ESNext"` or `"ES2020"` so TS allows dynamic imports. Webpack can still easily compile it targeting ES5.
+2.  Create ambient definition files (e.g., `src/client-game.d.ts`) containing module declarations (`declare module '@client-game';`) to resolve TS2307 dynamically missing paths.
+
+[source,typescript]
+----
+it('should init in client mode', async () => {
+    // Both dynamic imports work natively without errors!
+    const { isClientMode } = await import('./config/env');
+    (isClientMode as unknown as Mock).mockReturnValue(true);
+    
+    // Import and execute
+    await import('./main');
+    
+    // ... assertions ...
+});
+----
+
+== ESLint & Type Safety in Tests
+
+Maintain code quality even in tests:
+
+*   **Avoid `any`**: Use `unknown as vi.Mock` or cast to specific interfaces.
+*   **Private Members**: Use `// @ts-expect-error` or `(instance as any)._privateProp` only when absolutely necessary to verify internal state, but prefer testing public behavior.
+*   **Mock Dependencies**: Mock sub-packages (e.g., `view` or `manager`) when testing core orchestrators to isolate logic.
+
+== Example: Testing a Grid Engine
+
+[source,typescript]
+----
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import GridAnalysisEngine from './GridAnalysisEngine';
+import { Grid } from '../../../types/modules';
+
+describe('GridAnalysisEngine', () => {
+    let engine: GridAnalysisEngine;
+    let mockGrid: Grid;
+
+    beforeEach(() => {
+        // [ARRANGE]
+        mockGrid = {
+            width: 10,
+            height: 20,
+            isCellActive: vi.fn(),
+            // ... other properties
+        } as unknown as Grid;
+        engine = new GridAnalysisEngine(mockGrid);
+    });
+
+    it('should identify full rows when all cells in a row are active', () => {
+        // [ARRANGE]
+        vi.mocked(mockGrid.isCellActive).mockImplementation(({ y }) => y === 5);
+
+        // [ACT]
+        const fullRows = engine.getFullRows();
+
+        // [ASSERT]
+        expect(fullRows).toContain(5);
+        expect(fullRows.length).toBe(1);
+    });
+});
+----

package/eslint.config.mjs

@@ -0,0 +1,29 @@
+import globals from 'globals';
+import pluginJs from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default [
+    {
+        ignores: ['dist/', 'node_modules/', 'docs/', 'public/docs/', 'scripts/'],
+    },
+    // Base config for all files
+    pluginJs.configs.recommended,
+    ...tseslint.configs.recommended,
+
+    // Browser globals for most files
+    {
+        files: ['**/*.{js,mjs,cjs,ts}'],
+        languageOptions: { globals: globals.browser },
+    },
+
+    // Node globals for config files
+    {
+        files: ['**/webpack.config.js', 'eslint.config.mjs'],
+        languageOptions: { globals: globals.node },
+        rules: {
+            '@typescript-eslint/no-require-imports': 'off',
+            '@typescript-eslint/no-var-requires': 'off',
+            'no-undef': 'off', // globals.node should handle this, but just in case
+        },
+    },
+];

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "brick-engine-js",
+  "version": "1.0.1",
+  "description": "A lightweight brick engine built with p5.js and TypeScript",
+  "type": "commonjs",
+  "main": "dist/brick-engine.js",
+  "types": "dist/index.d.ts",
+  "license": "ISC",
+  "author": "LeonardoPinheiroLacerda",
+  "scripts": {
+    "start": "webpack serve --open",
+    "build": "webpack --mode production && npm run docs:build",
+    "build:types": "tsc --emitDeclarationOnly",
+    "lint": "eslint .",
+    "format": "npx prettier -w .",
+    "format:check": "npx prettier -c .",
+    "docs:diagram": "./scripts/generate-diagrams.sh",
+    "docs:build": "node ./scripts/generate-docs.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build && npm run build:types"
+  },
+  "dependencies": {
+    "colord": "^2.9.3",
+    "p5": "^2.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/p5": "^1.7.7",
+    "@types/webpack-env": "^1.18.8",
+    "@vitest/coverage-v8": "^4.0.18",
+    "asciidoctor": "^3.0.4",
+    "copy-webpack-plugin": "^13.0.1",
+    "css-loader": "^7.1.3",
+    "dotenv": "^17.3.1",
+    "eslint": "^10.0.0",
+    "globals": "^17.3.0",
+    "html-webpack-plugin": "^5.6.6",
+    "jsdom": "^28.1.0",
+    "mini-css-extract-plugin": "^2.10.0",
+    "prettier": "^3.8.1",
+    "ts-loader": "^9.5.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^4.0.18",
+    "webpack": "^5.105.1",
+    "webpack-cli": "^6.0.1",
+    "webpack-dev-server": "^5.2.3"
+  },
+  "overrides": {
+    "minimatch": "^10.2.1"
+  }
+}

package/public/CNAME

@@ -0,0 +1 @@
+brickengine.com.br