maze-blockly-wrapper 0.7.6 → 0.7.13

package/README.md

@@ -131,16 +131,72 @@ interface MazeConfig {
 ```
 
 ### RunResult
+Each game component returns a result object via the `onRunFinish` callback when specific conditions are met.
 
+#### MazeGame Result
+**When sent:** Triggered when the spider reaches the finish line OR when maximum moves are exceeded.
 ```typescript
 interface RunResult {
-  steps: number;
-  reachedFinish: boolean;
-  maxMovesExceeded: boolean;
-  finalPosition: Position;
-  path: Position[];
-  executionTime: number;
-  error?: string;
+  steps: number;           // Number of steps taken
+  reachedFinish: boolean;  // True if spider reached the finish cell
+  maxMovesExceeded: boolean; // True if maxMoves limit was hit
+  finalPosition: Position; // Where the spider ended up
+  path: Position[];        // Array of positions visited (todo)
+  executionTime: number;   // Time in ms (todo)
+  inventory: string[];     // Collected items (COIN, KEY, etc.)
+}
+```
+
+#### FilmGame Result
+**When sent:** Triggered when the user clicks the "Finish" button to check their movie against the target.
+```typescript
+interface RunResult {
+  commands: number;        // Total drawing commands used
+  reachedTarget: boolean;  // True if accuracy > 80%
+  maxCommandsExceeded: boolean;
+  shapes: Shape[];         // Array of shapes drawn by student
+  executionTime: number;   // Time in ms
+  accuracy: number;        // 0-1 score representing similarity to target
+  tickCount: number;       // Final tick count
+  comparisonResult: {      // Detailed breakdown
+    shapeCountMatch: boolean;
+    shapeTypesMatch: boolean;
+    positionAccuracy: number;
+    sizeAccuracy: number;
+    colorAccuracy: number;
+  };
+}
+```
+
+#### DrawingGame Result
+**When sent:** Triggered automatically when code execution completes.
+```typescript
+interface RunResult {
+  commands: number;        // Total commands executed
+  reachedTarget: boolean;  // True if game state marked as won (custom logic)
+  maxCommandsExceeded: boolean;
+  finalPosition: Position; // Final pen position
+  drawnPath: Position[];   // Array of points visited by pen
+  executionTime: number;   // Time in ms
+  accuracy: number;        // 0-1 score comparing drawn path to target path
+}
+```
+
+#### MusicGame Result
+**When sent:** Triggered automatically when the music finishes playing.
+```typescript
+interface RunResult {
+  commands: number;        // Total notes/pauses played
+  reachedTarget: boolean;  // True if accuracy is 100%
+  maxCommandsExceeded: boolean;
+  notes: Note[];           // Array of notes played
+  executionTime: number;   // Playback time in ms
+  accuracy: number;        // 0-100 score comparing played notes to editor notes
+  comparisonResult: {
+    noteCountMatch: boolean;
+    melodyAccuracy: number; // Pitch/Duration match score
+    rhythmAccuracy: number; // Timing match score
+  };
 }
 ```
 

package/dist/components/MusicDemo.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+declare const MusicDemo: React.FC;
+export default MusicDemo;

package/dist/components/music/GameControls.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+interface GameControlsProps {
+    isPlaying: boolean;
+    isPaused: boolean;
+    onPlay: () => void;
+    onPause: () => void;
+    onStop: () => void;
+    onReset: () => void;
+}
+declare const GameControls: React.FC<GameControlsProps>;
+export default GameControls;

package/dist/components/music/MusicBlocklyContainer.d.ts

@@ -0,0 +1,41 @@
+import { Component } from 'react';
+import type { InstrumentType, MusicBlocklyConfig, NoteDuration, NoteName, NoteOctave } from './types';
+interface MusicBlocklyContainerProps {
+    config: MusicBlocklyConfig;
+    onWorkspaceChange: (code: string) => void;
+    className?: string;
+    onPreloadInstruments?: (instruments: InstrumentType[]) => Promise<void>;
+}
+interface MusicBlocklyContainerState {
+    initialized: boolean;
+    error: string | null;
+    showNoteDialog: boolean;
+    noteDialogValues: {
+        note: NoteName;
+        octave: NoteOctave;
+        duration: NoteDuration;
+    };
+    activeField: any | null;
+}
+declare class MusicBlocklyContainer extends Component<MusicBlocklyContainerProps, MusicBlocklyContainerState> {
+    private blocklyDiv;
+    private workspace;
+    private updateTimeout;
+    constructor(props: MusicBlocklyContainerProps);
+    componentDidMount(): void;
+    componentDidUpdate(prevProps: MusicBlocklyContainerProps): void;
+    componentWillUnmount(): void;
+    /**
+     * Preload common instruments when Blockly container is ready
+     */
+    private preloadInstruments;
+    private initializeBlockly;
+    private generateCode;
+    private registerGenerators;
+    getWorkspace(): any;
+    private handleOpenNoteEditor;
+    private handleNoteSave;
+    private handleNoteClose;
+    render(): JSX.Element;
+}
+export default MusicBlocklyContainer;

package/dist/components/music/MusicCanvas.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import { type GraphicsConfig, type Note, type Pause } from './types';
+interface MusicCanvasProps {
+    width: number;
+    height: number;
+    notes: (Note | Pause)[];
+    currentBeat: number;
+    isPlaying: boolean;
+    selectedRows: number;
+    graphicsConfig: GraphicsConfig;
+    editorNotes?: (Note | Pause)[];
+}
+declare const MusicCanvas: React.FC<MusicCanvasProps>;
+export default MusicCanvas;

package/dist/components/music/MusicEditor.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { MusicBlocklyConfig } from './types';
+interface MusicEditorProps {
+    config: MusicBlocklyConfig;
+    onWorkspaceChange: (code: string) => void;
+    tempo: number;
+    onTempoChange: (tempo: number) => void;
+    blocklyRef?: React.RefObject<any>;
+}
+declare const MusicEditor: React.FC<MusicEditorProps>;
+export default MusicEditor;

package/dist/components/music/MusicGame.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import { type WithTranslation } from 'react-i18next';
+import { type GraphicsConfig, type MusicConfig, type RunResult } from './types';
+interface MusicGameProps extends WithTranslation {
+    className?: string;
+    isEditable?: boolean;
+    configuration?: MusicConfig;
+    onChange?: (config: MusicConfig) => void;
+    onRunFinish?: (result: RunResult) => void;
+    maxCommands?: number;
+    showControls?: boolean;
+    graphicsConfig?: Partial<GraphicsConfig>;
+}
+declare const MusicGameWithTranslation: React.ComponentType<Omit<MusicGameProps, keyof WithTranslation>>;
+export default MusicGameWithTranslation;

package/dist/components/music/MusicTabs.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+import type { GraphicsConfig, InstrumentType, MusicBlocklyConfig, MusicConfig, MusicState, Note, Pause } from './types';
+interface MusicTabsProps {
+    musicConfig: MusicConfig;
+    gameState: MusicState;
+    editorState: MusicState;
+    generatedCode: string;
+    blocklyConfig: MusicBlocklyConfig;
+    onConfigChange: (config: MusicConfig) => void;
+    onCodeChange: (code: string) => void;
+    onEditorStateChange: (state: Partial<MusicState>) => void;
+    onEditorNotesChange?: (notes: (Note | Pause)[]) => void;
+    graphicsConfig: GraphicsConfig;
+    className?: string;
+    blocklyRef?: React.RefObject<any>;
+    editorBlocklyRef?: React.RefObject<any>;
+    editorNotes?: (Note | Pause)[];
+    onPreloadInstruments?: (instruments: InstrumentType[]) => Promise<void>;
+}
+declare const MusicTabs: React.FC<MusicTabsProps>;
+export default MusicTabs;

package/dist/components/music/MusicVisualEditor.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import { type GraphicsConfig, type InstrumentType, type Note, type Pause } from './types';
+interface MusicVisualEditorProps {
+    tempo: number;
+    onTempoChange: (tempo: number) => void;
+    selectedRows: number;
+    onSelectedRowsChange: (rows: number) => void;
+    onCodeChange: (code: string) => void;
+    onNotesChange?: (notes: (Note | Pause)[]) => void;
+    graphicsConfig: GraphicsConfig;
+    onPreloadInstruments?: (instruments: InstrumentType[]) => Promise<void>;
+}
+declare const MusicVisualEditor: React.FC<MusicVisualEditorProps>;
+export default MusicVisualEditor;

package/dist/components/music/NoteDialog.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { NoteDuration, NoteName, NoteOctave } from './types';
+interface NoteDialogProps {
+    show: boolean;
+    onClose: () => void;
+    onSave: (note: NoteName, octave: NoteOctave, duration: NoteDuration) => void;
+    initialValues: {
+        note: NoteName;
+        octave: NoteOctave;
+        duration: NoteDuration;
+    };
+}
+declare const NoteDialog: React.FC<NoteDialogProps>;
+export default NoteDialog;

package/dist/components/music/audioEngine.d.ts

@@ -0,0 +1,54 @@
+import { type InstrumentType, type Note, type NoteDuration, type NoteOctave } from './types';
+/**
+ * Audio engine for playing musical notes using real instrument samples (SoundFont)
+ */
+export declare class AudioEngine {
+    private audioContext;
+    private masterGain;
+    private activeNotes;
+    private loadedInstruments;
+    private loadingInstruments;
+    private readonly instrumentMap;
+    constructor();
+    private initAudioContext;
+    /**
+     * Pre-load one or more instruments (public method for proactive loading)
+     */
+    preloadInstruments(instrumentTypes: InstrumentType[]): Promise<void>;
+    /**
+     * Load an instrument SoundFont (lazy loading)
+     */
+    private loadInstrument;
+    /**
+     * Play a single note using SoundFont samples
+     */
+    playNote(note: Note, tempo: number, instrument?: InstrumentType, onComplete?: () => void): Promise<void>;
+    /**
+     * Convert note name and octave to SoundFont format (e.g., "C4", "D#5")
+     */
+    private getNoteNameForSoundfont;
+    /**
+     * Fallback: Play note using oscillator (for drums or when SoundFont fails)
+     */
+    private playNoteWithOscillator;
+    /**
+     * Configure oscillator and gain based on instrument type with better synthesis
+     */
+    private configureInstrument;
+    /**
+     * Play a keyboard key (for interactive playing)
+     */
+    playKeyboardNote(noteName: string, octave: NoteOctave, duration?: NoteDuration, instrument?: InstrumentType): void;
+    /**
+     * Stop all playing notes
+     */
+    stopAll(): void;
+    /**
+     * Resume audio context (needed for browsers that suspend it)
+     */
+    resume(): Promise<void>;
+    /**
+     * Cleanup and close audio context
+     */
+    dispose(): void;
+}

package/dist/components/music/blockly-messages.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Load music-specific Blockly messages
+ * This should be called before registerMusicBlocks()
+ */
+export declare function loadMusicBlocklyMessages(): void;

package/dist/components/music/blocks.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Register music blocks with Blockly
+ */
+export declare function registerMusicBlocks(): void;

package/dist/components/music/fields/FieldMusicNote.d.ts

@@ -0,0 +1,2 @@
+export declare function getFieldMusicNoteClass(): any;
+export declare function registerFieldMusicNote(): void;

package/dist/components/music/graphicsConfig.d.ts

@@ -0,0 +1,3 @@
+import type { GraphicsConfig } from './types';
+export declare const defaultGraphicsConfig: GraphicsConfig;
+export declare function mergeGraphicsConfig(userConfig?: Partial<GraphicsConfig>): GraphicsConfig;

package/dist/components/music/index.d.ts

@@ -0,0 +1,12 @@
+export { default as MusicGame } from './MusicGame';
+export { default as MusicCanvas } from './MusicCanvas';
+export { default as MusicEditor } from './MusicEditor';
+export { default as MusicVisualEditor } from './MusicVisualEditor';
+export { default as MusicTabs } from './MusicTabs';
+export { default as GameControls } from './GameControls';
+export { default as MusicBlocklyContainer } from './MusicBlocklyContainer';
+export * from './types';
+export * from './blocks';
+export * from './blockly-messages';
+export * from './graphicsConfig';
+export * from './audioEngine';

package/dist/components/music/types.d.ts

@@ -0,0 +1,76 @@
+export type NoteDuration = 'whole' | 'half' | 'quarter' | 'eighth' | 'sixteenth';
+export type NoteName = 'C' | 'D' | 'E' | 'F' | 'G' | 'A' | 'B';
+export type NoteOctave = 1 | 2 | 3 | 4 | 5;
+export type InstrumentType = 'piano' | 'guitar' | 'acoustic_guitar' | 'electric_guitar' | 'bass' | 'drums' | 'flute' | 'violin' | 'saxophone';
+export interface Note {
+    id: string;
+    name: NoteName;
+    octave: NoteOctave;
+    duration: NoteDuration;
+    row: number;
+    startBeat: number;
+    instrument?: InstrumentType;
+}
+export interface Pause {
+    id: string;
+    duration: NoteDuration;
+    row: number;
+    startBeat: number;
+}
+export type MusicCommand = Note | Pause;
+export interface MusicState {
+    isPlaying: boolean;
+    isPaused: boolean;
+    currentBeat: number;
+    commands: MusicCommand[];
+    commandCount: number;
+    maxCommands: number;
+    selectedRows: number;
+    instrument: InstrumentType;
+    tempo: number;
+}
+export interface MusicConfig {
+    targetNotes: Note[];
+    maxCommands: number;
+    selectedRows: number;
+    tempo: number;
+    instrument: InstrumentType;
+}
+export interface MusicBlocklyConfig {
+    allowedTypes: Set<string>;
+    limits: Record<string, number>;
+    toolbox: string;
+    initialXml: string;
+}
+export interface RunResult {
+    commands: number;
+    reachedTarget: boolean;
+    maxCommandsExceeded: boolean;
+    notes: Note[];
+    executionTime: number;
+    accuracy: number;
+    comparisonResult?: {
+        noteCountMatch: boolean;
+        melodyAccuracy: number;
+        rhythmAccuracy: number;
+    };
+}
+export interface GraphicsConfig {
+    canvas: {
+        backgroundColor: string;
+        borderColor: string;
+        borderWidth: number;
+    };
+    staff: {
+        lineColor: string;
+        lineWidth: number;
+        spacing: number;
+    };
+    notes: {
+        fillColor: string;
+        strokeColor: string;
+        strokeWidth: number;
+    };
+}
+export declare const DURATION_TO_BEATS: Record<NoteDuration, number>;
+export declare function getNoteFrequency(note: NoteName, octave: NoteOctave): number;