@johnmorrisdotca/houseki 0.0.0-stage → 0.1.1

package/dist/nature/rebound.js

@@ -0,0 +1,98 @@
+import { nextNatureUint32 } from './random.js';
+import { freezeNatureState } from './state.js';
+import { NatureOptionsError, validatePowerDropRequest, validateState } from './validation.js';
+function at(state, x, y) { return y * state.width + x; }
+function freeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            freeze(child);
+    }
+    return value;
+}
+function fits(state, piece) {
+    const own = new Set(piece.map(cell => `${cell.x},${cell.y}`));
+    if (own.size !== piece.length)
+        return false;
+    return piece.every(cell => cell.x >= 0 && cell.x < state.width && cell.y >= 0 && cell.y < state.height && state.activeCells[at(state, cell.x, cell.y)] && state.cells[at(state, cell.x, cell.y)] === null);
+}
+function translate(piece, dx, dy) {
+    return piece.map(cell => ({ ...cell, x: cell.x + dx, y: cell.y + dy }));
+}
+function turnAroundPivot(piece, pivotId, quarterTurn) {
+    if (quarterTurn === 0)
+        return piece.map(cell => ({ ...cell }));
+    const pivot = piece.find(cell => cell.id === pivotId);
+    return piece.map(cell => {
+        const dx = cell.x - pivot.x, dy = cell.y - pivot.y;
+        return { ...cell, x: pivot.x + (quarterTurn === 1 ? -dy : dy), y: pivot.y + (quarterTurn === 1 ? dx : -dx) };
+    });
+}
+function movesBetween(before, after) {
+    const previous = new Map(before.map(cell => [cell.id, cell]));
+    return after.flatMap(cell => {
+        const from = previous.get(cell.id);
+        return from.x === cell.x && from.y === cell.y ? [] : [{ id: cell.id, from: { x: from.x, y: from.y }, to: { x: cell.x, y: cell.y } }];
+    });
+}
+function preferredDirection(state, request) {
+    if (state.rules.reboundDirectionMode === 'seeded') {
+        const [randomState, value] = nextNatureUint32(state.randomState);
+        return [value % 2 === 0 ? 'left' : 'right', randomState];
+    }
+    if (request.lastHorizontalDirection)
+        return [request.lastHorizontalDirection, state.randomState];
+    return [state.committedPlacements % 2 === 0 ? 'left' : 'right', state.randomState];
+}
+/** Preview a single normal landing and, for a power drop, at most one validated one-cell rebound. */
+export function previewPowerDrop(state, request) {
+    validateState(state);
+    validatePowerDropRequest(state, request);
+    let normal = request.piece.map(cell => ({ ...cell }));
+    while (true) {
+        const lower = translate(normal, 0, 1);
+        if (!fits(state, lower))
+            break;
+        normal = lower;
+    }
+    const eligible = request.power && state.rules.reboundEnabled;
+    let randomStateAfter = state.randomState;
+    const attempts = [];
+    let finalCells = normal;
+    let selectedDirection;
+    let selectedTurn = 0;
+    if (eligible) {
+        const [first, nextState] = preferredDirection(state, request);
+        randomStateAfter = nextState;
+        const directions = [first, first === 'left' ? 'right' : 'left'];
+        const turn = request.quarterTurn ?? 0;
+        const rotated = turnAroundPivot(normal, request.pivotId, turn);
+        for (const direction of directions) {
+            const candidate = translate(rotated, direction === 'left' ? -1 : 1, 0);
+            const valid = fits(state, candidate);
+            attempts.push({ direction, quarterTurn: turn, valid });
+            if (valid) {
+                finalCells = candidate;
+                selectedDirection = direction;
+                selectedTurn = turn;
+                break;
+            }
+        }
+    }
+    return freeze({ normalLanding: normal, attempts, rebound: selectedDirection !== undefined, ...(selectedDirection ? { selectedDirection } : {}), quarterTurn: selectedTurn, finalCells, moves: movesBetween(request.piece, finalCells), randomStateAfter });
+}
+/** Commit a previewed landing as one immutable operation. A failed preview leaves the original state untouched. */
+export function applyPowerDrop(state, request) {
+    const preview = previewPowerDrop(state, request);
+    const cells = [...state.cells];
+    for (const pieceCell of preview.finalCells) {
+        const index = at(state, pieceCell.x, pieceCell.y);
+        if (cells[index] !== null)
+            throw new NatureOptionsError('piece-collision', 'Power-drop destination is occupied');
+        cells[index] = { id: pieceCell.id, kind: 'stone', colour: pieceCell.colour, ...(pieceCell.magnetic ? { magnetic: true } : {}), ...(pieceCell.anchored ? { anchored: true } : {}) };
+    }
+    const maxId = preview.finalCells.reduce((maximum, cell) => Math.max(maximum, cell.id), 0);
+    const next = freezeNatureState({ ...state, cells, randomState: preview.randomStateAfter, nextId: Math.max(state.nextId, maxId + 1), committedPlacements: state.committedPlacements + 1 });
+    const event = freeze({ type: 'power-drop-landed', power: request.power, rebound: preview.rebound, ...(preview.selectedDirection ? { direction: preview.selectedDirection } : {}), quarterTurn: preview.quarterTurn, moves: preview.moves, ids: preview.finalCells.map(cell => cell.id) });
+    return { state: next, accepted: true, events: [event], preview };
+}

package/dist/nature/state.d.ts

@@ -0,0 +1,3 @@
+import type { NatureOptions, NatureState } from './types.js';
+export declare function freezeNatureState(state: NatureState): NatureState;
+export declare function createNatureState(options: NatureOptions): NatureState;

package/dist/nature/state.js

@@ -0,0 +1,22 @@
+import { NatureOptionsError, validateNatureOptions } from './validation.js';
+import { seedNatureState } from './random.js';
+export function freezeNatureState(state) {
+    const cells = Object.freeze(state.cells.map(entity => entity ? Object.freeze({ ...entity }) : null));
+    const activeCells = Object.freeze([...state.activeCells]);
+    const rules = Object.freeze({ ...state.rules });
+    return Object.freeze({ ...state, cells, activeCells, rules });
+}
+export function createNatureState(options) {
+    validateNatureOptions(options);
+    const cells = options.cells ?? Array(options.width * options.height).fill(null);
+    const maxId = cells.reduce((max, entity) => Math.max(max, entity?.id ?? 0), 0);
+    if (maxId >= 0x8000_0000)
+        throw new NatureOptionsError('invalid-cell', 'No stable IDs remain');
+    const seed = options.seed ?? 'houseki-shizen-default';
+    return freezeNatureState({
+        width: options.width, height: options.height,
+        activeCells: options.activeCells ?? Array(options.width * options.height).fill(true),
+        cells, seed, randomState: seedNatureState(seed), nextId: maxId + 1, committedPlacements: 0,
+        rules: { magneticEnabled: options.magneticEnabled ?? true, reboundEnabled: options.reboundEnabled ?? true, reboundDirectionMode: options.reboundDirectionMode ?? 'input-or-alternate' }
+    });
+}

package/dist/nature/types.d.ts

@@ -0,0 +1,124 @@
+export type HorizontalDirection = 'left' | 'right';
+export type ReboundDirectionMode = 'input-or-alternate' | 'seeded';
+export type QuarterTurn = -1 | 0 | 1;
+/** Stable board occupant. Obstacles collide and block attraction but cannot move or attract. */
+export interface NatureEntity {
+    readonly id: number;
+    readonly kind: 'stone' | 'obstacle';
+    readonly colour?: string;
+    readonly magnetic?: boolean;
+    readonly anchored?: boolean;
+}
+export interface NaturePieceCell extends NatureEntity {
+    readonly kind: 'stone';
+    readonly x: number;
+    readonly y: number;
+}
+export interface NatureRules {
+    readonly magneticEnabled: boolean;
+    readonly reboundEnabled: boolean;
+    readonly reboundDirectionMode: ReboundDirectionMode;
+}
+export interface NatureOptions {
+    readonly width: number;
+    readonly height: number;
+    readonly seed?: string;
+    /** Row-major passability mask. False cells are permanent gaps and cannot hold pieces. */
+    readonly activeCells?: readonly boolean[];
+    /** Row-major initial occupants; false mask cells must be empty. */
+    readonly cells?: readonly (NatureEntity | null)[];
+    readonly magneticEnabled?: boolean;
+    readonly reboundEnabled?: boolean;
+    readonly reboundDirectionMode?: ReboundDirectionMode;
+}
+export interface NatureState {
+    readonly width: number;
+    readonly height: number;
+    readonly activeCells: readonly boolean[];
+    readonly cells: readonly (NatureEntity | null)[];
+    readonly seed: string;
+    readonly randomState: number;
+    readonly nextId: number;
+    readonly committedPlacements: number;
+    readonly rules: NatureRules;
+}
+export interface NatureMove {
+    readonly id: number;
+    readonly from: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly to: {
+        readonly x: number;
+        readonly y: number;
+    };
+}
+export interface AttractionPairPreview {
+    readonly ids: readonly [number, number];
+    readonly axis: 'horizontal' | 'vertical';
+    readonly emptyGap: number;
+    readonly midpoint: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly anchoredId?: number;
+    readonly moves: readonly NatureMove[];
+}
+export interface MagneticPreview {
+    readonly pairs: readonly AttractionPairPreview[];
+    readonly moves: readonly NatureMove[];
+    readonly cells: readonly (NatureEntity | null)[];
+}
+export interface PowerDropRequest {
+    readonly piece: readonly NaturePieceCell[];
+    readonly pivotId: number;
+    readonly power: boolean;
+    readonly lastHorizontalDirection?: HorizontalDirection;
+    /** A caller-selected quarter-turn applied with the one-cell rebound. */
+    readonly quarterTurn?: QuarterTurn;
+}
+export interface ReboundAttemptPreview {
+    readonly direction: HorizontalDirection;
+    readonly quarterTurn: QuarterTurn;
+    readonly valid: boolean;
+}
+export interface PowerDropPreview {
+    readonly normalLanding: readonly NaturePieceCell[];
+    readonly attempts: readonly ReboundAttemptPreview[];
+    readonly rebound: boolean;
+    readonly selectedDirection?: HorizontalDirection;
+    readonly quarterTurn: QuarterTurn;
+    readonly finalCells: readonly NaturePieceCell[];
+    readonly moves: readonly NatureMove[];
+    readonly randomStateAfter: number;
+}
+export type NatureEvent = {
+    readonly type: 'magnetic-pulse';
+    readonly pairs: readonly AttractionPairPreview[];
+    readonly moves: readonly NatureMove[];
+} | {
+    readonly type: 'magnetic-stones-marked';
+    readonly ids: readonly number[];
+    readonly randomState: number;
+} | {
+    readonly type: 'power-drop-landed';
+    readonly power: boolean;
+    readonly rebound: boolean;
+    readonly direction?: HorizontalDirection;
+    readonly quarterTurn: QuarterTurn;
+    readonly moves: readonly NatureMove[];
+    readonly ids: readonly number[];
+};
+export interface NatureTransition {
+    readonly state: NatureState;
+    readonly accepted: boolean;
+    readonly reason?: string;
+    readonly events: readonly NatureEvent[];
+    readonly preview?: MagneticPreview | PowerDropPreview;
+}
+export interface MarkingOptions {
+    readonly probability: number;
+    readonly maximum?: number;
+    readonly anchoredProbability?: number;
+}
+export type NatureErrorCode = 'invalid-nature-options' | 'invalid-grid-size' | 'invalid-seed' | 'invalid-mask' | 'invalid-cell' | 'duplicate-id' | 'invalid-marking-options' | 'invalid-power-drop' | 'piece-collision' | 'invalid-piece-position';

package/dist/nature/types.js

@@ -0,0 +1 @@
+export {};

package/dist/nature/validation.d.ts

@@ -0,0 +1,10 @@
+import type { MarkingOptions, NatureEntity, NatureErrorCode, NatureOptions, NatureState, PowerDropRequest } from './types.js';
+export declare class NatureOptionsError extends RangeError {
+    readonly code: NatureErrorCode;
+    constructor(code: NatureErrorCode, message: string);
+}
+export declare function validateNatureOptions(options: NatureOptions): void;
+export declare function validateEntity(value: unknown, ids: Set<number>, label: string): asserts value is NatureEntity;
+export declare function validateState(state: NatureState): void;
+export declare function validateMarkingOptions(options: MarkingOptions): void;
+export declare function validatePowerDropRequest(state: NatureState, request: PowerDropRequest): void;

package/dist/nature/validation.js

@@ -0,0 +1,117 @@
+export class NatureOptionsError extends RangeError {
+    code;
+    constructor(code, message) { super(message); this.name = 'NatureOptionsError'; this.code = code; }
+}
+const ownKeysOnly = (value, allowed, code, label) => {
+    if (Object.keys(value).some(key => !allowed.includes(key)))
+        throw new NatureOptionsError(code, `${label} contains an unsupported field`);
+};
+export function validateNatureOptions(options) {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        throw new NatureOptionsError('invalid-nature-options', 'Nature options must be an object');
+    ownKeysOnly(options, ['width', 'height', 'seed', 'activeCells', 'cells', 'magneticEnabled', 'reboundEnabled', 'reboundDirectionMode'], 'invalid-nature-options', 'Nature options');
+    if (!Number.isSafeInteger(options.width) || !Number.isSafeInteger(options.height) || options.width < 1 || options.height < 1 || options.width > 32 || options.height > 32 || options.width * options.height > 1024)
+        throw new NatureOptionsError('invalid-grid-size', 'Grid dimensions must be integers from 1 to 32 with at most 1024 cells');
+    if (options.seed !== undefined && (typeof options.seed !== 'string' || options.seed.length < 1 || options.seed.length > 200))
+        throw new NatureOptionsError('invalid-seed', 'Seed must contain 1–200 characters');
+    const size = options.width * options.height;
+    if (options.activeCells !== undefined && (!Array.isArray(options.activeCells) || options.activeCells.length !== size || options.activeCells.some(value => typeof value !== 'boolean')))
+        throw new NatureOptionsError('invalid-mask', 'Active-cell mask must contain one boolean per grid cell');
+    if (options.cells !== undefined && (!Array.isArray(options.cells) || options.cells.length !== size))
+        throw new NatureOptionsError('invalid-cell', 'Cells must contain one entry per grid cell');
+    if (options.magneticEnabled !== undefined && typeof options.magneticEnabled !== 'boolean' || options.reboundEnabled !== undefined && typeof options.reboundEnabled !== 'boolean')
+        throw new NatureOptionsError('invalid-nature-options', 'Feature flags must be boolean');
+    if (options.reboundDirectionMode !== undefined && options.reboundDirectionMode !== 'input-or-alternate' && options.reboundDirectionMode !== 'seeded')
+        throw new NatureOptionsError('invalid-nature-options', 'Unsupported rebound direction mode');
+    const ids = new Set();
+    for (let index = 0; index < (options.cells?.length ?? 0); index++) {
+        const entity = options.cells[index];
+        if (entity === null)
+            continue;
+        validateEntity(entity, ids, `Grid cell ${index}`);
+        if (options.activeCells?.[index] === false)
+            throw new NatureOptionsError('invalid-cell', `Grid cell ${index} is masked but occupied`);
+    }
+}
+export function validateEntity(value, ids, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new NatureOptionsError('invalid-cell', `${label} must be null or an entity`);
+    const entity = value;
+    ownKeysOnly(value, ['id', 'kind', 'colour', 'magnetic', 'anchored'], 'invalid-cell', label);
+    if (!Number.isSafeInteger(entity.id) || entity.id < 1 || entity.id > 0x7fff_ffff || ids.has(entity.id))
+        throw new NatureOptionsError(ids.has(entity.id) ? 'duplicate-id' : 'invalid-cell', `${label} has an invalid or duplicate stable ID`);
+    if (entity.kind !== 'stone' && entity.kind !== 'obstacle')
+        throw new NatureOptionsError('invalid-cell', `${label} has an invalid kind`);
+    if (entity.kind === 'stone') {
+        if (typeof entity.colour !== 'string' || entity.colour.length < 1 || entity.colour.length > 32)
+            throw new NatureOptionsError('invalid-cell', `${label} must have a colour`);
+        if (entity.magnetic !== undefined && typeof entity.magnetic !== 'boolean' || entity.anchored !== undefined && typeof entity.anchored !== 'boolean')
+            throw new NatureOptionsError('invalid-cell', `${label} magnetic properties must be boolean`);
+        if (entity.anchored && !entity.magnetic)
+            throw new NatureOptionsError('invalid-cell', `${label} cannot be anchored unless it is magnetic`);
+    }
+    else if ('colour' in entity || 'magnetic' in entity || 'anchored' in entity)
+        throw new NatureOptionsError('invalid-cell', `${label} obstacle cannot have stone properties`);
+    ids.add(entity.id);
+}
+export function validateState(state) {
+    if (!state || typeof state !== 'object')
+        throw new NatureOptionsError('invalid-nature-options', 'Nature state must be an object');
+    ownKeysOnly(state, ['width', 'height', 'activeCells', 'cells', 'seed', 'randomState', 'nextId', 'committedPlacements', 'rules'], 'invalid-nature-options', 'Nature state');
+    if (!Array.isArray(state.activeCells) || !Array.isArray(state.cells) || !state.rules || typeof state.rules !== 'object' || Array.isArray(state.rules))
+        throw new NatureOptionsError('invalid-nature-options', 'Nature state is missing its grid or rules');
+    ownKeysOnly(state.rules, ['magneticEnabled', 'reboundEnabled', 'reboundDirectionMode'], 'invalid-nature-options', 'Nature rules');
+    if (typeof state.rules.magneticEnabled !== 'boolean' || typeof state.rules.reboundEnabled !== 'boolean' || (state.rules.reboundDirectionMode !== 'input-or-alternate' && state.rules.reboundDirectionMode !== 'seeded'))
+        throw new NatureOptionsError('invalid-nature-options', 'Nature rules are malformed');
+    validateNatureOptions({ width: state.width, height: state.height, seed: state.seed, activeCells: state.activeCells, cells: state.cells, magneticEnabled: state.rules?.magneticEnabled, reboundEnabled: state.rules?.reboundEnabled, reboundDirectionMode: state.rules?.reboundDirectionMode });
+    if (!Number.isSafeInteger(state.randomState) || state.randomState < 0 || state.randomState > 0xffff_ffff || !Number.isSafeInteger(state.nextId) || state.nextId < 1 || state.nextId > 0x8000_0000 || !Number.isSafeInteger(state.committedPlacements) || state.committedPlacements < 0)
+        throw new NatureOptionsError('invalid-nature-options', 'Nature state counters are malformed');
+    const maxId = state.cells.reduce((maximum, entity) => Math.max(maximum, entity?.id ?? 0), 0);
+    if (state.nextId <= maxId)
+        throw new NatureOptionsError('invalid-nature-options', 'nextId must be greater than all board IDs');
+}
+export function validateMarkingOptions(options) {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        throw new NatureOptionsError('invalid-marking-options', 'Marking options must be an object');
+    ownKeysOnly(options, ['probability', 'maximum', 'anchoredProbability'], 'invalid-marking-options', 'Marking options');
+    if (typeof options.probability !== 'number' || !Number.isFinite(options.probability) || options.probability < 0 || options.probability > 1)
+        throw new NatureOptionsError('invalid-marking-options', 'Magnetic probability must be between zero and one');
+    if (options.maximum !== undefined && (!Number.isSafeInteger(options.maximum) || options.maximum < 0 || options.maximum > 1024))
+        throw new NatureOptionsError('invalid-marking-options', 'Maximum magnetic count must be an integer from zero to 1024');
+    if (options.anchoredProbability !== undefined && (typeof options.anchoredProbability !== 'number' || !Number.isFinite(options.anchoredProbability) || options.anchoredProbability < 0 || options.anchoredProbability > 1))
+        throw new NatureOptionsError('invalid-marking-options', 'Anchored probability must be between zero and one');
+}
+export function validatePowerDropRequest(state, request) {
+    if (!request || typeof request !== 'object' || Array.isArray(request))
+        throw new NatureOptionsError('invalid-power-drop', 'Power-drop request must be an object');
+    ownKeysOnly(request, ['piece', 'pivotId', 'power', 'lastHorizontalDirection', 'quarterTurn'], 'invalid-power-drop', 'Power-drop request');
+    if (!Array.isArray(request.piece) || request.piece.length < 1 || request.piece.length > 16 || !Number.isSafeInteger(request.pivotId) || typeof request.power !== 'boolean')
+        throw new NatureOptionsError('invalid-power-drop', 'Power-drop requires 1–16 cells, a pivot ID and a power flag');
+    if (request.lastHorizontalDirection !== undefined && request.lastHorizontalDirection !== 'left' && request.lastHorizontalDirection !== 'right')
+        throw new NatureOptionsError('invalid-power-drop', 'Last horizontal direction must be left or right');
+    const turns = [-1, 0, 1];
+    if (request.quarterTurn !== undefined && !turns.includes(request.quarterTurn))
+        throw new NatureOptionsError('invalid-power-drop', 'Quarter-turn must be -1, 0 or 1');
+    const ids = new Set(state.cells.flatMap(entity => entity ? [entity.id] : []));
+    const pieceIds = new Set();
+    let hasPivot = false;
+    for (const [index, cell] of request.piece.entries()) {
+        if (!cell || typeof cell !== 'object' || Array.isArray(cell))
+            throw new NatureOptionsError('invalid-power-drop', `Piece cell ${index} is malformed`);
+        ownKeysOnly(cell, ['id', 'kind', 'colour', 'magnetic', 'anchored', 'x', 'y'], 'invalid-power-drop', `Piece cell ${index}`);
+        const { x, y, ...entity } = cell;
+        if (!Number.isSafeInteger(x) || !Number.isSafeInteger(y) || entity.kind !== 'stone')
+            throw new NatureOptionsError('invalid-power-drop', `Piece cell ${index} has invalid coordinates or is not a stone`);
+        validateEntity(entity, ids, `Piece cell ${index}`);
+        pieceIds.add(entity.id);
+        if (entity.id === request.pivotId)
+            hasPivot = true;
+        const at = y * state.width + x;
+        if (x < 0 || x >= state.width || y < 0 || y >= state.height || !state.activeCells[at] || state.cells[at] !== null)
+            throw new NatureOptionsError('invalid-piece-position', `Piece cell ${index} starts outside an empty active grid cell`);
+    }
+    if (!hasPivot || pieceIds.size !== request.piece.length)
+        throw new NatureOptionsError('invalid-power-drop', 'Piece cells need unique IDs and must include the pivot ID');
+    if (new Set(request.piece.map(cell => `${cell.x},${cell.y}`)).size !== request.piece.length)
+        throw new NatureOptionsError('invalid-power-drop', 'Piece cells cannot overlap');
+}

package/dist/nature.d.ts

@@ -0,0 +1,8 @@
+export * from './nature/types.js';
+export { NatureOptionsError } from './nature/validation.js';
+export { createNatureState } from './nature/state.js';
+export { markMagneticStones } from './nature/marking.js';
+export { applyMagneticPulse, previewMagneticPulse } from './nature/attraction.js';
+export { applyPowerDrop, previewPowerDrop } from './nature/rebound.js';
+export { applyEarthquake, applyLightning, isEnvironmentTurnScheduled, previewEarthquake, previewFault, previewJumble, previewLightning } from './nature/environment.js';
+export type { EarthquakeKind, EarthquakeOptions, EnvironmentEvent, EnvironmentPreview, EnvironmentSchedule, EnvironmentTransition, FaultPreview, JumblePreview, LightningOptions, LightningPreview } from './nature/environment.js';

package/dist/nature.js

@@ -0,0 +1,7 @@
+export * from './nature/types.js';
+export { NatureOptionsError } from './nature/validation.js';
+export { createNatureState } from './nature/state.js';
+export { markMagneticStones } from './nature/marking.js';
+export { applyMagneticPulse, previewMagneticPulse } from './nature/attraction.js';
+export { applyPowerDrop, previewPowerDrop } from './nature/rebound.js';
+export { applyEarthquake, applyLightning, isEnvironmentTurnScheduled, previewEarthquake, previewFault, previewJumble, previewLightning } from './nature/environment.js';