feat: Implement Alphabet Learning SPA

[rngadam]

This commit introduces a new, self-contained single-page application for learning alphabets, as detailed in the ALPHABET.md specification.

The application, implemented in alphabet.html, is an offline-first SPA that teaches character recognition, pronunciation, and handwriting stroke order for the Greek, Italian, Spanish, and Turkish alphabets.

Key features include:

• Data persistence using IndexedDB with the Dexie.js wrapper.
• Handwriting stroke animations powered by GSAP and the DrawSVGPlugin.
• Auditory feedback using the native Web Speech API.
• A "Training Mode" for browsing and learning characters.
• An interactive "Testing Mode" with canvas-based drawing and handwriting validation that checks for stroke count, order, and direction.

[gemini-code-assist]

Summary of Changes

Hello @rngadam, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request delivers a comprehensive, offline-first Single Page Application (alphabet.html) designed to facilitate alphabet learning. The application provides interactive tools for character recognition, pronunciation, and handwriting stroke order, supporting Greek, Italian, Spanish, and Turkish alphabets. It is built with a client-side architecture, leveraging IndexedDB for data persistence, GSAP for dynamic SVG animations, and the Web Speech API for audio feedback, offering both a guided training experience and a validated testing environment.

Highlights

• New Alphabet Learning SPA: Introduces a self-contained, offline-first Single Page Application (alphabet.html) for learning various alphabets.
• Offline-First Data Persistence: Utilizes IndexedDB with the Dexie.js wrapper for robust client-side data storage, ensuring privacy and network independence.
• Interactive Handwriting Animations: Implements character stroke order animations using GSAP and its DrawSVGPlugin for visual learning.
• Auditory Pronunciation Feedback: Integrates the native Web Speech API for character pronunciation, with intelligent voice selection based on language.
• Dual Learning Modes: Features a 'Training Mode' for browsing and learning, and an interactive 'Testing Mode' with canvas-based drawing and stroke validation.
• Multi-Alphabet Support: Includes pre-authored data for Greek, Italian, Spanish, and Turkish alphabets, with an extensible data-driven architecture.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive and well-documented single-page application for learning alphabets. The implementation is impressive, successfully integrating IndexedDB for offline storage, GSAP for animations, and the Web Speech API for audio feedback. My review focuses on enhancing the robustness, performance, and maintainability of the JavaScript logic. The key suggestions include optimizing a critical database query to improve scalability, refining the handwriting validation logic to be more precise, and ensuring the character animation perfectly aligns with the technical specification. I have also included a minor correction for the specification document itself.

[gemini-code-assist]

This database query is inefficient and not scalable. It fetches the progress data for all characters from every alphabet, relying on hardcoded prefixes. This will degrade performance as more alphabets are added and violates the extensibility goal outlined in the specification.

A more robust and performant approach is to fetch only the progress data for the characters in the currently selected alphabet. This can be done by getting the characterIds for the current alphabet and then using Dexie's anyOf() method.

Suggested change

	const progressData = await db.userProgress.where('characterId').startsWith('greek').or('characterId').startsWith('italian').or('characterId').startsWith('spanish').or('characterId').startsWith('turkish').toArray();
	const characterIds = allCharacters.map(c => c.characterId);
	const progressData = await db.userProgress.where('characterId').anyOf(characterIds).toArray();

[gemini-code-assist]

The CDN links in this HTML block are formatted using Markdown link syntax ([url](url)), which is incorrect for an src attribute. When copied, this would result in a non-functional URL. The src attribute should contain only the direct URL to the resource.

Suggested change

	<script src="[https://cdn.jsdelivr.net/npm/dexie@4.0.1/dist/dexie.min.js](https://cdn.jsdelivr.net/npm/dexie@4.0.1/dist/dexie.min.js)"></script>
	<script src="[https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js](https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js)"></script>
	<script src="[https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/DrawSVGPlugin.min.js](https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/DrawSVGPlugin.min.js)"></script>
	<script src="https://cdn.jsdelivr.net/npm/dexie@4.0.1/dist/dexie.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/DrawSVGPlugin.min.js"></script>

[gemini-code-assist]

The animation logic currently animates all uppercase and lowercase strokes in a single sequence. The technical specification requires a brief pause between the uppercase and lowercase animations. This can be achieved by separating the animation logic into two loops and adding a pause to the GSAP timeline between them.

Suggested change

	const tl = gsap.timeline();
	const allPaths = [...strokePaths.uppercase, ...strokePaths.lowercase];
	allPaths.forEach(pathData => {
	const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
	path.setAttribute('d', pathData);
	svgElement.appendChild(path);
	tl.from(path, { drawSVG: 0, duration: 1 }, "+=0.1");
	});
	const tl = gsap.timeline();
	strokePaths.uppercase.forEach(pathData => {
	const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
	path.setAttribute('d', pathData);
	svgElement.appendChild(path);
	tl.from(path, { drawSVG: 0, duration: 1 }, "+=0.1");
	});
	// Add a pause if both uppercase and lowercase paths exist, as per the spec.
	if (strokePaths.uppercase.length > 0 && strokePaths.lowercase.length > 0) {
	tl.to({}, { duration: 0.5 });
	}
	strokePaths.lowercase.forEach(pathData => {
	const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
	path.setAttribute('d', pathData);
	svgElement.appendChild(path);
	tl.from(path, { drawSVG: 0, duration: 1 }, "+=0.1");
	});

[gemini-code-assist]

The use of a regular expression to extract start and end points from the SVG path data is brittle. It assumes that the first two numbers are the start coordinates and the last two are the end coordinates. While this works for the current dataset (which primarily uses M, L, and C commands), it will fail for other valid SVG path commands like H (horizontal lineto) or V (vertical lineto), or more complex path structures. This makes the validation logic fragile and hard to maintain if the character data changes.

[gemini-code-assist]

A threshold of 35 on a 100x100 grid is very large, covering over a third of the canvas width or height. This makes the handwriting validation extremely lenient and may lead to incorrect drawings being accepted as correct. Reducing this value would enforce a more accurate check of the user's drawing.

Suggested change

	const threshold = 35; // How close points need to be, in a 100x100 grid
	const threshold = 20; // How close points need to be, in a 100x100 grid

[rngadam]

@gemini-code-assist /review

[rngadam]

@gemini-code-assist /review

[gemini-code-assist]

Code Review

This pull request introduces a well-documented and feature-rich single-page application for learning alphabets. The implementation is impressive for a self-contained file, featuring offline capabilities with IndexedDB, stroke animations, and a simplified handwriting validation system. My review focuses on enhancing the application's robustness, maintainability, and correctness. Key suggestions include refining the global error handling strategy, improving the handwriting validation logic to be less fragile, completing the implementation of user progress tracking, and adhering to best practices such as using constants over magic numbers and defining the application's state shape upfront.

[gemini-code-assist]

Wrapping the entire application logic in a single, top-level try...catch block is not recommended. This approach has several drawbacks:

• Poor User Experience: On any JavaScript error, the entire application UI is replaced with an error message. This is a very disruptive experience for the user, especially for minor or recoverable errors.
• Debugging Difficulty: It can mask where an error truly originates, making it harder to debug.

Error handling should be more granular. For example, database operations in seedDatabase or startTest could have their own try...catch blocks to handle potential failures gracefully (e.g., by showing a small notification) without crashing the whole application.

[gemini-code-assist]

The logic for updating userProgress is incomplete. The database schema and the specification in ALPHABET.md define a lastTested field to track when a user was last tested on a character. However, this field is never set or updated here. This should be updated regardless of whether the answer was correct or incorrect.

Suggested change

	const progress = await db.userProgress.get({ characterId: char.characterId }) || { characterId: char.characterId, correctCount: 0, incorrectCount: 0 };
	const progress = await db.userProgress.get({ characterId: char.characterId }) || { characterId: char.characterId, correctCount: 0, incorrectCount: 0 };
	progress.lastTested = new Date().toISOString();

[gemini-code-assist]

The getStrokeEndpoints function is very fragile, as noted in the code comment. It relies on a simple regex to extract numbers from an SVG path string and assumes their position to determine start and end points. This will fail for more complex path commands (e.g., H, V, A, S, T, Q). While it may work for the current dataset, it creates significant technical debt and poses a high risk of bugs if the character data is ever updated or expanded. A more robust SVG path parsing library or a more sophisticated parsing function should be used to ensure the handwriting validation is reliable.

[gemini-code-assist]

The CDN links in the AI prompt have two issues:

1. Incorrect Markdown: The URLs are wrapped in Markdown link syntax ([text](url)) within a code block, which will not render correctly. The src attribute should contain only the URL string.
2. Version Mismatch: The GSAP version is specified as 3.12.5, but the alphabet.html implementation uses 3.13.0. The specification and the implementation should be consistent.

To fix this, the links should be plain URLs and the version should be updated to match the implementation.

Suggested change

	<script src="[https://cdn.jsdelivr.net/npm/dexie@4.0.1/dist/dexie.min.js](https://cdn.jsdelivr.net/npm/dexie@4.0.1/dist/dexie.min.js)"></script>
	<script src="[https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js](https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js)"></script>
	<script src="[https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/DrawSVGPlugin.min.js](https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/DrawSVGPlugin.min.js)"></script>
	<script src="https://cdn.jsdelivr.net/npm/dexie@4.0.1/dist/dexie.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/gsap@3.13.0/dist/gsap.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/gsap@3.13.0/dist/DrawSVGPlugin.min.js"></script>

[gemini-code-assist]

The appState object is mutated later in the code by adding new properties like currentCharForTest and incorrectAttempts (lines 585-586). For better code clarity and maintainability, it's best practice to define the complete shape of the state object at initialization. This makes the state structure explicit and helps prevent bugs from typos when accessing state properties.

Suggested change

	let appState = {
	currentAlphabetId: null,
	currentMode: 'train', // 'train' or 'test'
	};
	let appState = {
	currentAlphabetId: null,
	currentMode: 'train', // 'train' or 'test',
	currentCharForTest: null,
	incorrectAttempts: 0
	};

[gemini-code-assist]

Using onclick to assign event handlers is generally discouraged in modern JavaScript. It only allows for a single handler for an event and can be easily overwritten. It's better to use addEventListener for greater flexibility and consistency. This allows multiple listeners to be attached to the same event and provides more control over the event handling process (e.g., capturing vs. bubbling). This also applies to other event handlers assigned via on... properties, like on line 636.

Suggested change

	replayAnimationBtn.onclick = performActions;
	replayAnimationBtn.addEventListener('click', performActions);

[gemini-code-assist]

The number of incorrect attempts (3) is a "magic number" hardcoded directly in the logic. This makes the code harder to read and maintain. This value should be extracted into a named constant at the top of the script (e.g., const MAX_INCORRECT_ATTEMPTS = 3;). This practice should be applied to other magic numbers in the file, such as feedback timeouts and canvas dimensions.

Suggested change

	if (appState.incorrectAttempts >= 3) {
	if (appState.incorrectAttempts >= MAX_INCORRECT_ATTEMPTS) {

[gemini-code-assist]

Code Review

This pull request introduces a well-structured single-page application for learning alphabets, complete with a detailed technical specification. The implementation is robust, leveraging IndexedDB for offline storage and GSAP for animations as specified. My review focuses on improving correctness, maintainability, and device compatibility. Key feedback includes fixing a critical bug in the handwriting validation logic for closed paths, adding touch support for the drawing canvas to improve mobile usability, and resolving several minor inconsistencies and maintainability issues, such as library version mismatches and event listener logic. I've also noted a minor discrepancy in the technical specification's code examples.

[gemini-code-assist]

The getStrokeEndpoints function incorrectly parses the end point for closed SVG paths (those ending with a Z command). It assumes the last two numbers in the path string are the end coordinates, but for a closed path, the end point should be the same as the starting point. This bug causes handwriting validation to fail for characters with closed paths, such as the uppercase Greek 'Delta'.

Suggested change

	function getStrokeEndpoints(svgPath) {
	// NOTE: This is a simplified SVG path parser. It assumes the first two numbers
	// in the path string are the start point and the last two are the end point.
	// This works for the M, L, and C commands used in this application's dataset,
	// but would fail for more complex paths using commands like H, V, or A.
	const numbers = svgPath.match(/-?\d+(\.\d+)?/g);
	if (!numbers || numbers.length < 2) return null;
	return {
	start: { x: parseFloat(numbers[0]), y: parseFloat(numbers[1]) },
	end: { x: parseFloat(numbers[numbers.length - 2]), y: parseFloat(numbers[numbers.length - 1]) }
	};
	}
	function getStrokeEndpoints(svgPath) {
	// NOTE: This is a simplified SVG path parser. It assumes the first two numbers
	// in the path string are the start point and handles 'Z' for closed paths.
	const numbers = svgPath.match(/-?\d+(\.\d+)?/g);
	if (!numbers || numbers.length < 2) return null;
	const start = { x: parseFloat(numbers[0]), y: parseFloat(numbers[1]) };
	let end;
	if (svgPath.trim().toUpperCase().endsWith('Z')) {
	end = { x: start.x, y: start.y };
	} else {
	end = { x: parseFloat(numbers[numbers.length - 2]), y: parseFloat(numbers[numbers.length - 1]) };
	}
	return { start, end };
	}

[gemini-code-assist]

The DOMContentLoaded event listener is nested inside the window.onload handler. The DOMContentLoaded event fires before window.onload. By the time window.onload executes, DOMContentLoaded has almost certainly already fired, so the nested listener's callback will likely never run. The initialization logic should be executed directly within the window.onload handler, as the script's position at the end of the <body> does not guarantee that external scripts in the <head> have loaded.

Suggested change

	document.addEventListener('DOMContentLoaded', () => {
	gsap.registerPlugin(DrawSVGPlugin); // Register plugin once DOM is ready
	seedDatabase().then(initializeApp).catch(err => {
	console.error("Failed to initialize database:", err);
	});
	});
	gsap.registerPlugin(DrawSVGPlugin);
	seedDatabase().then(initializeApp).catch(err => {
	console.error("Failed to initialize database:", err);
	});

[gemini-code-assist]

The drawing canvas in "Test Mode" only listens for mouse events, which means it will not work on touch-based devices. To ensure accessibility on tablets and smartphones, you should add corresponding touch event listeners (touchstart, touchmove, touchend). You will also need to update the getMousePos function to correctly handle coordinates from TouchEvent objects.

Suggested change

	drawingCanvas.onmousedown = startDrawing;
	drawingCanvas.onmousemove = draw;
	drawingCanvas.onmouseup = stopDrawing;
	drawingCanvas.onmouseleave = stopDrawing;
	drawingCanvas.onmousedown = startDrawing;
	drawingCanvas.onmousemove = draw;
	drawingCanvas.onmouseup = stopDrawing;
	drawingCanvas.onmouseleave = stopDrawing;
	drawingCanvas.ontouchstart = startDrawing;
	drawingCanvas.ontouchmove = draw;
	drawingCanvas.ontouchend = stopDrawing;

[gemini-code-assist]

This function only handles mouse events (evt.clientX). To support the touch events required for mobile usability, it needs to be updated to also handle TouchEvent objects, which store coordinate data differently (e.g., in evt.touches[0].clientX).

Suggested change

	function getMousePos(canvas, evt) {
	const rect = canvas.getBoundingClientRect();
	return {
	x: evt.clientX - rect.left,
	y: evt.clientY - rect.top
	};
	}
	function getMousePos(canvas, evt) {
	const rect = canvas.getBoundingClientRect();
	const touch = evt.touches ? evt.touches[0] : null;
	return {
	x: (touch || evt).clientX - rect.left,
	y: (touch || evt).clientY - rect.top
	};
	}

[gemini-code-assist]

The CDN links in the AI agent prompt are formatted as Markdown links within an HTML code block. This is incorrect and will not work if copied directly. The URLs should be placed directly in the src attribute of the <script> tags.

Suggested change

	<script src="[https://cdn.jsdelivr.net/npm/dexie@4.0.1/dist/dexie.min.js](https://cdn.jsdelivr.net/npm/dexie@4.0.1/dist/dexie.min.js)"></script>
	<script src="[https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js](https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js)"></script>
	<script src="[https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/DrawSVGPlugin.min.js](https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/DrawSVGPlugin.min.js)"></script>
	<script src="https://cdn.jsdelivr.net/npm/dexie@4.0.1/dist/dexie.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/DrawSVGPlugin.min.js"></script>

[gemini-code-assist]

There's an inconsistency in the GSAP library version. The technical specification in ALPHABET.md specifies version 3.12.5, but the implementation here uses 3.13.0. To ensure consistency and prevent potential issues from unexpected version changes, the versions should match. Please either update the specification or change the CDN links to use the specified version.

Suggested change

	<script src="https://cdn.jsdelivr.net/npm/gsap@3.13.0/dist/gsap.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/gsap@3.13.0/dist/DrawSVGPlugin.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/DrawSVGPlugin.min.js"></script>

[gemini-code-assist]

The application uses localStorage to persist the logging toggle state. However, the technical specification in ALPHABET.md (Core Requirement #2) strictly states: "Data Storage: Use IndexedDB for all data persistence. Do not use localStorage or any server-side storage." While this is for a minor configuration setting, it technically violates the specification. Consider moving this state into a separate table in IndexedDB to fully comply with the project requirements.

[gemini-code-assist]

The appState object is mutated later in the code to add new properties like currentCharForTest and incorrectAttempts. For better code clarity and maintainability, it's a good practice to declare all properties of a state object at initialization, even with null or default values. This makes it easier to understand the complete shape of the application state at a glance.

Suggested change

	let appState = {
	currentAlphabetId: null,
	currentMode: 'train', // 'train' or 'test'
	};
	let appState = {
	currentAlphabetId: null,
	currentMode: 'train', // 'train' or 'test',
	currentCharForTest: null,
	incorrectAttempts: 0
	};