scan-engine 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# Scan Engine
+
+Headless scan engine for switch-scanning interfaces. This package provides scanning strategies (row/column, linear, snake, elimination, etc.) without any UI. You provide a `ScanSurface` adapter for your UI and wire `ScanCallbacks` for selection events.
+
+## Install
+
+```bash
+npm install scan-engine
+```
+
+## Usage
+
+```ts
+import { LinearScanner, type ScanSurface, type ScanConfigProvider } from 'scan-engine';
+
+const surface: ScanSurface = {
+  getItemsCount: () => items.length,
+  getColumns: () => 8,
+  setFocus: (indices) => highlight(indices),
+  setSelected: (index) => flash(index),
+  getItemData: (index) => ({ label: items[index].label })
+};
+
+const config: ScanConfigProvider = {
+  get: () => ({
+    scanRate: 800,
+    scanInputMode: 'auto',
+    scanDirection: 'circular',
+    scanPattern: 'linear',
+    scanTechnique: 'point',
+    scanMode: null,
+    continuousTechnique: 'crosshair',
+    compassMode: 'continuous',
+    eliminationSwitchCount: 4,
+    allowEmptyItems: false,
+    initialItemPause: 0,
+    scanLoops: 0,
+    criticalOverscan: { enabled: false, fastRate: 100, slowRate: 1000 },
+    colorCode: { errorRate: 0.1, selectThreshold: 0.95 }
+  })
+};
+
+const scanner = new LinearScanner(surface, config, {
+  onSelect: (index) => console.log('Selected', index)
+});
+
+scanner.start();
+```
+
+## Continuous Scanning UI Hooks
+
+Continuous scanning is headless. Provide optional hooks for UI:
+
+```ts
+import type { ContinuousUpdate, ScanSurface, ScanCallbacks } from 'scan-engine';
+
+const surface: ScanSurface = {
+  getItemsCount: () => items.length,
+  getColumns: () => 8,
+  setFocus: (indices) => highlight(indices),
+  setSelected: (index) => flash(index),
+  resolveIndexAtPoint: (xPercent, yPercent) => resolveIndex(xPercent, yPercent)
+};
+
+const callbacks: ScanCallbacks = {
+  onContinuousUpdate: (state: ContinuousUpdate) => {
+    renderContinuousOverlay(state);
+  }
+};
+```
+
+If you are using a DOM grid, the companion package `scan-engine-dom` provides an overlay renderer and hit-testing helper.
+
+## Strategies
+
+- Row/Column
+- Linear
+- Snake
+- Quadrant
+- Group-Row-Column
+- Elimination
+- Continuous (crosshair, gliding, eight-direction)
+- Probability
+- Cause/Effect
+- ColorCode
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+type SwitchAction = 'select' | 'step' | 'reset' | 'cancel' | 'menu' | 'switch-1' | 'switch-2' | 'switch-3' | 'switch-4' | 'switch-5' | 'switch-6' | 'switch-7' | 'switch-8';
+interface ScanItemData {
+    label?: string;
+    isEmpty?: boolean;
+}
+interface ScanItemStyle {
+    backgroundColor?: string;
+    textColor?: string;
+    borderColor?: string;
+    borderWidth?: number;
+    boxShadow?: string;
+    opacity?: number;
+}
+interface FocusMeta {
+    phase?: 'major' | 'minor' | 'item';
+    scanRate?: number;
+    scanPattern?: string;
+    scanTechnique?: string;
+    scanDirection?: string;
+}
+type ContinuousTechnique = 'gliding' | 'crosshair' | 'eight-direction';
+type ContinuousState = 'x-scan' | 'y-scan' | 'x-scanning' | 'x-capturing' | 'y-scanning' | 'y-capturing' | 'direction-scan' | 'moving' | 'processing';
+interface ContinuousUpdate {
+    technique: ContinuousTechnique;
+    state: ContinuousState;
+    xPos: number;
+    yPos: number;
+    bufferLeft: number;
+    bufferRight: number;
+    bufferTop: number;
+    bufferBottom: number;
+    fineXPos: number;
+    fineYPos: number;
+    lockedXPosition: number;
+    compassAngle: number;
+    currentDirection: number;
+    directionName: string;
+    directionDx: number;
+    directionDy: number;
+}
+interface ScanSurface {
+    getItemsCount(): number;
+    getColumns(): number;
+    setFocus(indices: number[], meta?: FocusMeta): void;
+    setSelected(index: number): void;
+    getItemData?(index: number): ScanItemData | null;
+    setItemStyle?(index: number, style: ScanItemStyle): void;
+    clearItemStyles?(): void;
+    getContainerElement?(): HTMLElement | null;
+    resolveIndexAtPoint?(xPercent: number, yPercent: number): number | null;
+}
+interface ScanCallbacks {
+    onScanStep?: () => void;
+    onSelect?: (index: number) => void;
+    onRedraw?: () => void;
+    onContinuousUpdate?: (state: ContinuousUpdate) => void;
+}
+interface CriticalOverscanConfig {
+    enabled: boolean;
+    fastRate: number;
+    slowRate: number;
+}
+interface ColorCodeConfig {
+    errorRate: number;
+    selectThreshold: number;
+}
+interface ScanConfig {
+    scanRate: number;
+    scanInputMode: 'auto' | 'manual';
+    scanDirection: 'circular' | 'reverse' | 'oscillating';
+    scanPattern: 'row-column' | 'column-row' | 'linear' | 'snake' | 'quadrant' | 'elimination';
+    scanTechnique: 'block' | 'point';
+    scanMode: 'group-row-column' | 'continuous' | 'probability' | 'cause-effect' | 'color-code' | null;
+    continuousTechnique: ContinuousTechnique;
+    compassMode: 'continuous' | 'fixed-8';
+    eliminationSwitchCount: 2 | 3 | 4 | 5 | 6 | 7 | 8;
+    allowEmptyItems: boolean;
+    initialItemPause: number;
+    scanLoops: number;
+    criticalOverscan: CriticalOverscanConfig;
+    colorCode: ColorCodeConfig;
+}
+interface ScanConfigProvider {
+    get(): ScanConfig;
+}
+
+declare enum OverscanState {
+    FAST = "fast",
+    SLOW_BACKWARD = "slow_backward"
+}
+declare abstract class Scanner {
+    protected surface: ScanSurface;
+    protected config: ScanConfigProvider;
+    protected callbacks: ScanCallbacks;
+    protected isRunning: boolean;
+    protected timer: number | null;
+    protected stepCount: number;
+    protected overscanState: OverscanState;
+    protected loopCount: number;
+    constructor(surface: ScanSurface, config: ScanConfigProvider, callbacks?: ScanCallbacks);
+    start(): void;
+    stop(): void;
+    handleAction(action: SwitchAction): void;
+    protected handleSelectAction(): void;
+    protected abstract step(): void;
+    protected abstract reset(): void;
+    protected reportCycleCompleted(): void;
+    protected scheduleNextStep(): void;
+    protected triggerSelection(index: number): void;
+    protected triggerRedraw(): void;
+    abstract getCost(itemIndex: number): number;
+    protected abstract doSelection(): void;
+    mapContentToGrid<T>(content: T[], _rows: number, _cols: number): T[];
+}
+
+declare class RowColumnScanner extends Scanner {
+    private level;
+    private currentRow;
+    private currentCol;
+    private totalRows;
+    private isColumnRow;
+    private useBlockScanning;
+    start(): void;
+    private recalcDimensions;
+    protected reset(): void;
+    protected step(): void;
+    private stepMajor;
+    private stepMinor;
+    private highlightMajor;
+    handleAction(action: SwitchAction): void;
+    protected doSelection(): void;
+    getCost(itemIndex: number): number;
+    mapContentToGrid<T>(content: T[], rows: number, cols: number): T[];
+}
+
+declare class LinearScanner extends Scanner {
+    private currentIndex;
+    private totalItems;
+    private direction;
+    start(): void;
+    private countItems;
+    protected reset(): void;
+    protected step(): void;
+    handleAction(action: SwitchAction): void;
+    protected doSelection(): void;
+    getCost(itemIndex: number): number;
+}
+
+declare class SnakeScanner extends Scanner {
+    private currentRow;
+    private currentCol;
+    private direction;
+    private maxRow;
+    private maxCol;
+    start(): void;
+    private updateDimensions;
+    protected reset(): void;
+    protected step(): void;
+    handleAction(action: SwitchAction): void;
+    protected doSelection(): void;
+    getCost(itemIndex: number): number;
+    mapContentToGrid<T>(content: T[], rows: number, cols: number): T[];
+}
+
+declare class QuadrantScanner extends Scanner {
+    private level;
+    private currentQuad;
+    private currentRow;
+    private currentCol;
+    private quads;
+    start(): void;
+    private calcQuadrants;
+    protected reset(): void;
+    protected step(): void;
+    private stepQuadrant;
+    private stepRow;
+    private stepCell;
+    private highlightQuad;
+    private highlightRowSegment;
+    handleAction(action: SwitchAction): void;
+    protected doSelection(): void;
+    private restartTimer;
+    getCost(itemIndex: number): number;
+    mapContentToGrid<T>(content: T[], rows: number, cols: number): T[];
+}
+
+declare class GroupScanner extends Scanner {
+    private level;
+    private currentGroup;
+    private currentRow;
+    private currentCol;
+    private groups;
+    start(): void;
+    private calcGroups;
+    protected reset(): void;
+    protected step(): void;
+    private stepGroup;
+    private stepRow;
+    private stepCell;
+    private highlightGroup;
+    private highlightRow;
+    handleAction(action: SwitchAction): void;
+    protected doSelection(): void;
+    private restartTimer;
+    getCost(itemIndex: number): number;
+}
+
+declare class EliminationScanner extends Scanner {
+    private rangeStart;
+    private rangeEnd;
+    private currentBlock;
+    private numSwitches;
+    private partitionHistory;
+    start(): void;
+    protected reset(): void;
+    private clearHighlights;
+    protected step(): void;
+    private highlightCurrentBlock;
+    private calculatePartitions;
+    private getSwitchAction;
+    handleAction(action: SwitchAction): void;
+    protected doSelection(): void;
+    private restartTimer;
+    getCost(itemIndex: number): number;
+    protected scheduleNextStep(): void;
+}
+
+declare class ContinuousScanner extends Scanner {
+    private state;
+    private xPos;
+    private yPos;
+    private technique;
+    private numCols;
+    private numRows;
+    private bufferWidth;
+    private direction;
+    private pauseTimer;
+    private bufferLeft;
+    private bufferRight;
+    private bufferTop;
+    private bufferBottom;
+    private fineXPos;
+    private fineYPos;
+    private lockedXPosition;
+    private currentDirection;
+    private compassAngle;
+    private compassMode;
+    private directionStepCounter;
+    private directionStepsPerChange;
+    private directions;
+    start(): void;
+    stop(): void;
+    protected reset(): void;
+    protected step(): void;
+    private getDirectionFromAngle;
+    protected scheduleNextStep(): void;
+    handleAction(action: SwitchAction): void;
+    protected doSelection(): void;
+    private selectFocusedItem;
+    private selectAtPoint;
+    private selectAtPercent;
+    private estimateIndexAtPercent;
+    private emitUpdate;
+    getCost(itemIndex: number): number;
+}
+
+declare class ProbabilityScanner extends Scanner {
+    private predictor;
+    private scanOrder;
+    private currentIndex;
+    start(): void;
+    protected reset(): void;
+    protected step(): void;
+    handleAction(action: SwitchAction): void;
+    protected doSelection(): void;
+    private updateProbabilities;
+    getCost(itemIndex: number): number;
+}
+
+declare class CauseEffectScanner extends Scanner {
+    start(): void;
+    handleAction(action: SwitchAction): void;
+    protected doSelection(): void;
+    protected step(): void;
+    protected reset(): void;
+    getCost(_itemIndex: number): number;
+}
+
+declare class ColorCodeScanner extends Scanner {
+    private probabilities;
+    private colors;
+    start(): void;
+    stop(): void;
+    handleAction(action: SwitchAction): void;
+    protected step(): void;
+    protected reset(): void;
+    getCost(_itemIndex: number): number;
+    protected doSelection(): void;
+    private initializeBelief;
+    private assignColors;
+    private applyColors;
+    private updateBelief;
+}
+
+interface Prediction {
+    text: string;
+    probability: number;
+}
+declare class PredictorManager {
+    private predictor;
+    constructor();
+    addToContext(char: string): void;
+    resetContext(): void;
+    predictNext(): Prediction[];
+}
+
+export { CauseEffectScanner, ColorCodeScanner, ContinuousScanner, type ContinuousState, type ContinuousTechnique, type ContinuousUpdate, EliminationScanner, type FocusMeta, GroupScanner, LinearScanner, OverscanState, PredictorManager, ProbabilityScanner, QuadrantScanner, RowColumnScanner, type ScanCallbacks, type ScanConfig, type ScanConfigProvider, type ScanItemData, type ScanItemStyle, type ScanSurface, Scanner, SnakeScanner, type SwitchAction };