{"id":25188573,"url":"https://github.com/kleinpanic/maze_solver","last_synced_at":"2026-05-24T11:04:51.579Z","repository":{"id":275230448,"uuid":"877606182","full_name":"kleinpanic/maze_solver","owner":"kleinpanic","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-01T01:07:36.000Z","size":26222,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-09T20:36:39.764Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kleinpanic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-23T23:24:35.000Z","updated_at":"2025-02-01T01:07:40.000Z","dependencies_parsed_at":"2025-02-01T02:19:53.456Z","dependency_job_id":"f1ca41ae-b478-46c1-b858-59f0391c949f","html_url":"https://github.com/kleinpanic/maze_solver","commit_stats":null,"previous_names":["kleinpanic/maze_solver"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2Fmaze_solver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2Fmaze_solver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2Fmaze_solver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2Fmaze_solver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kleinpanic","download_url":"https://codeload.github.com/kleinpanic/maze_solver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157281,"owners_count":20893221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-09T20:29:12.578Z","updated_at":"2026-05-24T11:04:51.573Z","avatar_url":"https://github.com/kleinpanic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python Maze Solver\n\n[![CI](https://img.shields.io/github/actions/workflow/status/kleinpanic/maze_solver/ci.yml?branch=main\u0026label=CI)](https://github.com/kleinpanic/maze_solver/actions/workflows/ci.yml)\n[![Pages](https://img.shields.io/github/actions/workflow/status/kleinpanic/maze_solver/pages.yml?branch=main\u0026label=Pages)](https://github.com/kleinpanic/maze_solver/actions/workflows/pages.yml)\n[![Security](https://img.shields.io/github/actions/workflow/status/kleinpanic/maze_solver/security.yml?branch=main\u0026label=Security)](https://github.com/kleinpanic/maze_solver/actions/workflows/security.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg)](pyproject.toml)\n\nMaze Solver is an interactive maze generation and pathfinding lab. It ships three interfaces over the same algorithm core:\n\n- a Tkinter GUI for step-by-step desktop visualization,\n- a terminal UI for reproducible command-line runs,\n- a static Canvas WebUI designed for GitHub Pages: \u003chttps://kleinpanic.github.io/maze_solver/\u003e.\n\nThe project treats mazes as grid graphs, where open cells are vertices and north/south/east/west moves are edges. Solver and generator metadata live beside the implementations, so the GUI, TUI, WebUI, tests, and documentation stay aligned as the catalog grows.\n\n## Features\n\n- Real-time visualization of visited cells, frontier cells, and final paths.\n- Deterministic maze generation with seeds.\n- Shared Python package under `src/maze_solver`.\n- Browser-side educational WebUI with Canvas animation, Big-O notes, runtime metrics, per-solver math breakdowns, generator theory, maze-structure statistics, and an algorithm comparison table.\n- Desktop GUI with algorithm metadata, runtime controls, and high-contrast visualization states.\n- Terminal UI with reproducible runs, optional ANSI color, and compact solver statistics.\n- CI for Python 3.11, 3.12, and 3.13.\n- GitHub Pages deployment from `web/dist`.\n- Automated tagged releases for `v*` tags, including Python distributions and a zipped WebUI build.\n- CodeQL, dependency review, and Dependabot configuration.\n\n## Solver Catalog\n\n| Algorithm | Complete | Optimal | Weighted | Time | Space |\n| --- | --- | --- | --- | --- | --- |\n| Breadth-First Search | Yes | Yes | No | `O(V + E)` | `O(V)` |\n| Lee Algorithm | Yes | Yes | No | `O(V + E)` | `O(V)` |\n| Depth-First Search | Yes | No | No | `O(V + E)` | `O(V)` |\n| Flood Fill Solver | Yes | Yes | No | `O(V + E)` | `O(V)` |\n| A* Search | Yes | Yes | Yes | `O(E log V)` | `O(V)` |\n| Iterative Deepening A* | Yes | Yes | No | `O(b^d)` worst case | `O(d)` |\n| Dijkstra's Algorithm | Yes | Yes | Yes | `O((V + E) log V)` | `O(V)` |\n| Uniform-Cost Search | Yes | Yes | Yes | `O((V + E) log V)` | `O(V)` |\n| SPFA | Yes | Yes | Yes | `O(VE)` worst case | `O(V)` |\n| Bidirectional BFS | Yes | Yes | No | `O(b^(d/2))` idealized | `O(b^(d/2))` |\n| Greedy Best-First Search | Yes | No | No | `O(E log V)` | `O(V)` |\n| Left-Hand Wall Follower | Topology-dependent | No | No | `O(k)` | `O(k)` |\n| Right-Hand Wall Follower | Topology-dependent | No | No | `O(k)` | `O(k)` |\n| Tremaux's Algorithm | Yes | No | No | `O(V + E)` | `O(V + E)` |\n| Pledge Algorithm | Topology-dependent | No | No | `O(k)` | `O(k)` |\n| Iterative Deepening Depth-First Search | Yes | Yes | No | `O(b^d)` | `O(d)` |\n| Bellman-Ford | Yes | Yes | Yes | `O(VE)` | `O(V)` |\n| Dead-End Filling | Yes | No | No | `O(V + E)` | `O(V)` |\n| Random Mouse | No | No | No | Unbounded | `O(k)` |\n\n## Generator Catalog\n\nRecursive Backtracker, Randomized Prim, Randomized Kruskal, Wilson, Aldous-Broder, Hunt and Kill, Binary Tree, Sidewinder, Growing Tree, Eller, and Recursive Division are available in the Python core and the WebUI. The browser view explains each generator's graph model, perfect-maze claim, asymptotic cost, texture bias, invariant, and carving procedure while reporting wall ratio, dead ends, junctions, and corridor bias for the current maze.\n\nSee [docs/ALGORITHMS.md](docs/ALGORITHMS.md) for the full catalog, complexity notes, and references.\n\n## Quick Start\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npython -m pip install -e \".[dev]\"\npython3 main.py\n```\n\nRun a terminal solve:\n\n```bash\nmaze-solver-tui --rows 21 --cols 41 --seed 2026 --algorithm Dijkstra\n```\n\nAdd `--color always --legend` for a colorized terminal render with the state legend.\n\nRun the WebUI locally:\n\n```bash\ncd web\nnpm ci\nnpm run build\ncd ..\nmaze-solver-web\n```\n\nThen open the URL printed by the command. It starts at port `4173`, falls forward when the port is busy, and stops cleanly on Ctrl-C.\n\n## Development\n\nRun Python checks:\n\n```bash\nsource .venv/bin/activate\npytest\nruff check .\nruff format --check .\n```\n\nRun WebUI checks:\n\n```bash\ncd web\nnpm test\nnpm run build\n```\n\nCreate a release:\n\n```bash\ngit tag vX.Y.Z\ngit push origin vX.Y.Z\n```\n\nThe `Release` workflow verifies Python and WebUI checks before publishing the GitHub release.\n\n## Repository Layout\n\n```text\nsrc/maze_solver/        Python package and algorithm core\ntests/                  Python tests for solvers and generators\nweb/                    Static Canvas WebUI\ndocs/ALGORITHMS.md      Algorithm catalog and references\n.github/workflows/      CI, Pages, and security workflows\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkleinpanic%2Fmaze_solver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkleinpanic%2Fmaze_solver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkleinpanic%2Fmaze_solver/lists"}