fastapi-voyager 0.11.11__tar.gz → 0.12.1__tar.gz

fastapi_voyager-0.12.1/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: fastapi-voyager
+Version: 0.12.1
+Summary: Visualize FastAPI application's routing tree and dependencies
+Project-URL: Homepage, https://github.com/allmonday/fastapi-voyager
+Project-URL: Source, https://github.com/allmonday/fastapi-voyager
+Author-email: Tangkikodo <allmonday@126.com>
+License: MIT
+License-File: LICENSE
+Keywords: fastapi,openapi,routing,visualization
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic-resolve>=1.13.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: uvicorn; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![pypi](https://img.shields.io/pypi/v/fastapi-voyager.svg)](https://pypi.python.org/pypi/fastapi-voyager)
+![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-voyager)
+[![PyPI Downloads](https://static.pepy.tech/badge/fastapi-voyager/month)](https://pepy.tech/projects/fastapi-voyager)
+
+
+> This repo is still in early stage, it supports pydantic v2 only
+
+Visualize your FastAPI endpoints, and explore them interactively.
+
+[visit online demo](https://www.newsyeah.fun/voyager/) of project: [composition oriented development pattern](https://github.com/allmonday/composition-oriented-development-pattern)
+
+<img width="1600" height="986" alt="image" src="https://github.com/user-attachments/assets/8829cda0-f42d-4c84-be2f-b019bb5fe7e1" />
+
+## Installation
+
+```bash
+pip install fastapi-voyager
+# or
+uv add fastapi-voyager
+```
+
+```shell
+voyager -m path.to.your.app.module --server
+```
+
+> [Sub-Application mounts](https://fastapi.tiangolo.com/advanced/sub-applications/) are not supported yet, but you can specify the name of the FastAPI application used with `--app`. Only a single application (default: 'app') can be selected, but in a scenario where `api` is attached through `app.mount("/api", api)`, you can select `api` like this:
+
+```shell
+voyager -m path.to.your.app.module --server --app api
+```
+
+## Mount into project
+
+```python
+from fastapi import FastAPI
+from fastapi_voyager import create_voyager
+from tests.demo import app
+
+app.mount('/voyager', create_voyager(
+    app, 
+    module_color={"tests.service": "red"}, 
+    module_prefix="tests.service"),
+    swagger_url="/docs")
+```
+
+## Features
+
+For scenarios of using FastAPI as internal API integration endpoints, `fastapi-voyager` helps to visualize the dependencies.
+
+It is also an architecture inspection tool that can identify issues in data relationships during design phase before turly implemtatioin.
+
+If the process of building the view model follows the ER model, the full potential of fastapi-voyager can be realized. It allows for quick identification of APIs  that use entities, as well as which entities are used by a specific API
+
+### highlight nodes and links
+click a node to highlight it's upperstream and downstream nodes. figure out the related models of one page, or homw many pages are related with one model.
+
+
+<img width="1100" height="700" alt="image" src="https://github.com/user-attachments/assets/3e0369ea-5fa4-469a-82c1-ed57d407e53d" />
+
+### focus on nodes
+
+Double click a node, and then toggle focus to hide irrelevant nodes.
+
+<img width="1061" height="937" alt="image" src="https://github.com/user-attachments/assets/79709b02-7571-43fc-abc9-17a287a97515" />
+
+### view source code
+
+double click a node or route to show source code or open file in vscode.
+
+<img width="1297" height="940" alt="image" src="https://github.com/user-attachments/assets/c8bb2e7d-b727-42a6-8c9e-64dce297d2d8" />
+
+<img width="1132" height="824" alt="image" src="https://github.com/user-attachments/assets/b706e879-e4fc-48dd-ace1-99bf97e3ed6a" />
+
+
+## Command Line Usage
+
+### open in browser
+
+```bash
+# open in browser
+voyager -m tests.demo --server  
+
+voyager -m tests.demo --server --port=8002
+```
+
+### generate the dot file
+```bash
+# generate .dot file
+voyager -m tests.demo  
+
+voyager -m tests.demo --app my_app
+
+voyager -m tests.demo --schema Task
+
+voyager -m tests.demo --show_fields all
+
+voyager -m tests.demo --module_color=tests.demo:red --module_color=tests.service:tomato
+
+voyager -m tests.demo -o my_visualization.dot
+
+voyager --version
+
+voyager --help
+```
+
+## About pydantic-resolve
+
+pydantic-resolve's `@ensure_subset` decorator helps safely pick fields from the 'source class' while **indicating the reference** from the current class to the base class.
+
+pydantic-resolve is a lightweight tool designed to build complex, nested data in a simple, declarative way. In version 2.0.0alpha, it will introduce an important feature: ER Diagram, and fastapi-voyager will support this feature, allowing for a clearer understanding of the business relationships between the data.
+
+Developers can use fastapi-voyager without needing to know anything about pydantic-resolve, but I still highly recommend everyone to give it a try.
+
+## Dependencies
+
+- FastAPI
+- [pydantic-resolve](https://github.com/allmonday/pydantic-resolve)
+- Quasar
+
+
+## Credits
+
+- https://apis.guru/graphql-voyager/, thanks for inspiration.
+- https://github.com/tintinweb/vscode-interactive-graphviz, thanks for web visualization.
+
+
+## How to develop & contribute?
+
+fork, clone.
+
+install uv.
+
+```shell
+uv venv
+source .venv/bin/activate
+uv pip install ".[dev]"
+uvicorn tests.programatic:app  --reload
+```
+
+open `localhost:8000/voyager`
+
+
+frontend: 
+- `src/web/vue-main.js`: main js
+
+backend: 
+- `voyager.py`: main entry
+- `render.py`: generate dot file
+- `server.py`: serve mode
+
+
+## Plan & Raodmap
+- [ideas](./docs/idea.md)
+- [changelog & roadmap](./docs/changelog.md)

fastapi_voyager-0.12.1/README.md

@@ -0,0 +1,154 @@
+[![pypi](https://img.shields.io/pypi/v/fastapi-voyager.svg)](https://pypi.python.org/pypi/fastapi-voyager)
+![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-voyager)
+[![PyPI Downloads](https://static.pepy.tech/badge/fastapi-voyager/month)](https://pepy.tech/projects/fastapi-voyager)
+
+
+> This repo is still in early stage, it supports pydantic v2 only
+
+Visualize your FastAPI endpoints, and explore them interactively.
+
+[visit online demo](https://www.newsyeah.fun/voyager/) of project: [composition oriented development pattern](https://github.com/allmonday/composition-oriented-development-pattern)
+
+<img width="1600" height="986" alt="image" src="https://github.com/user-attachments/assets/8829cda0-f42d-4c84-be2f-b019bb5fe7e1" />
+
+## Installation
+
+```bash
+pip install fastapi-voyager
+# or
+uv add fastapi-voyager
+```
+
+```shell
+voyager -m path.to.your.app.module --server
+```
+
+> [Sub-Application mounts](https://fastapi.tiangolo.com/advanced/sub-applications/) are not supported yet, but you can specify the name of the FastAPI application used with `--app`. Only a single application (default: 'app') can be selected, but in a scenario where `api` is attached through `app.mount("/api", api)`, you can select `api` like this:
+
+```shell
+voyager -m path.to.your.app.module --server --app api
+```
+
+## Mount into project
+
+```python
+from fastapi import FastAPI
+from fastapi_voyager import create_voyager
+from tests.demo import app
+
+app.mount('/voyager', create_voyager(
+    app, 
+    module_color={"tests.service": "red"}, 
+    module_prefix="tests.service"),
+    swagger_url="/docs")
+```
+
+## Features
+
+For scenarios of using FastAPI as internal API integration endpoints, `fastapi-voyager` helps to visualize the dependencies.
+
+It is also an architecture inspection tool that can identify issues in data relationships during design phase before turly implemtatioin.
+
+If the process of building the view model follows the ER model, the full potential of fastapi-voyager can be realized. It allows for quick identification of APIs  that use entities, as well as which entities are used by a specific API
+
+### highlight nodes and links
+click a node to highlight it's upperstream and downstream nodes. figure out the related models of one page, or homw many pages are related with one model.
+
+
+<img width="1100" height="700" alt="image" src="https://github.com/user-attachments/assets/3e0369ea-5fa4-469a-82c1-ed57d407e53d" />
+
+### focus on nodes
+
+Double click a node, and then toggle focus to hide irrelevant nodes.
+
+<img width="1061" height="937" alt="image" src="https://github.com/user-attachments/assets/79709b02-7571-43fc-abc9-17a287a97515" />
+
+### view source code
+
+double click a node or route to show source code or open file in vscode.
+
+<img width="1297" height="940" alt="image" src="https://github.com/user-attachments/assets/c8bb2e7d-b727-42a6-8c9e-64dce297d2d8" />
+
+<img width="1132" height="824" alt="image" src="https://github.com/user-attachments/assets/b706e879-e4fc-48dd-ace1-99bf97e3ed6a" />
+
+
+## Command Line Usage
+
+### open in browser
+
+```bash
+# open in browser
+voyager -m tests.demo --server  
+
+voyager -m tests.demo --server --port=8002
+```
+
+### generate the dot file
+```bash
+# generate .dot file
+voyager -m tests.demo  
+
+voyager -m tests.demo --app my_app
+
+voyager -m tests.demo --schema Task
+
+voyager -m tests.demo --show_fields all
+
+voyager -m tests.demo --module_color=tests.demo:red --module_color=tests.service:tomato
+
+voyager -m tests.demo -o my_visualization.dot
+
+voyager --version
+
+voyager --help
+```
+
+## About pydantic-resolve
+
+pydantic-resolve's `@ensure_subset` decorator helps safely pick fields from the 'source class' while **indicating the reference** from the current class to the base class.
+
+pydantic-resolve is a lightweight tool designed to build complex, nested data in a simple, declarative way. In version 2.0.0alpha, it will introduce an important feature: ER Diagram, and fastapi-voyager will support this feature, allowing for a clearer understanding of the business relationships between the data.
+
+Developers can use fastapi-voyager without needing to know anything about pydantic-resolve, but I still highly recommend everyone to give it a try.
+
+## Dependencies
+
+- FastAPI
+- [pydantic-resolve](https://github.com/allmonday/pydantic-resolve)
+- Quasar
+
+
+## Credits
+
+- https://apis.guru/graphql-voyager/, thanks for inspiration.
+- https://github.com/tintinweb/vscode-interactive-graphviz, thanks for web visualization.
+
+
+## How to develop & contribute?
+
+fork, clone.
+
+install uv.
+
+```shell
+uv venv
+source .venv/bin/activate
+uv pip install ".[dev]"
+uvicorn tests.programatic:app  --reload
+```
+
+open `localhost:8000/voyager`
+
+
+frontend: 
+- `src/web/vue-main.js`: main js
+
+backend: 
+- `voyager.py`: main entry
+- `render.py`: generate dot file
+- `server.py`: serve mode
+
+
+## Plan & Raodmap
+- [ideas](./docs/idea.md)
+- [changelog & roadmap](./docs/changelog.md)

fastapi_voyager-0.12.1/docs/changelog.md

@@ -0,0 +1,122 @@
+# Changelog & roadmap
+
+## <0.9:
+- [x] group schemas by module hierarchy
+- [x] module-based coloring via Analytics(module_color={...})
+- [x] view in web browser
+    - [x] config params
+    - [x] make a explorer dashboard, provide list of routes, schemas, to make it easy to switch and search
+- [x] support programmatic usage
+- [x] better schema /router node appearance
+- [x] hide fields duplicated with parent's (show `parent fields` instead)
+- [x] refactor the frontend to vue, and tweak the build process
+- [x] find dependency based on picked schema and it's field.
+- [x] optimize static resource (cdn -> local)
+- [x] add configuration for highlight (optional)
+- [x] alt+click to show field details
+- [x] display source code of routes (including response_model)
+- [x] handle excluded field 
+- [x] add tooltips
+- [x] route
+    - [x] group routes by module hierarchy
+    - [x] add response_model in route
+- [x] fixed left bar show tag/ route
+- [x] export voyager core data into json (for better debugging)
+    - [x] add api to rebuild core data from json, and render it
+- [x] fix Generic case  `test_generic.py`
+- [x] show tips for routes not return pydantic type.
+- [x] fix duplicated link from class and parent class, it also break clicking highlight
+- [x] refactor: abstract render module
+
+## 0.9
+- [x] refactor: server.py
+    - [x] rename create_app_with_fastapi -> create_voyager
+    - [x] add doc for parameters
+- [x] improve initialization time cost
+    - [x] query route / schema info through realtime api
+    - [x] adjust fe
+- 0.9.3
+    - [x] adjust layout 
+        - [x] show field detail in right panel
+        - [x] show route info in bottom
+- 0.9.4
+    - [x] close schema sidebar when switch tag/route
+    - [x] schema detail panel show fields by default
+    - [x] adjust schema panel's height
+    - [x] show from base information in subset case
+- 0.9.5
+    - [x] route list should have a max height 
+
+## 0.10
+- 0.10.1
+    - [x] refactor voyager.py tag -> route structure
+    - [x] fix missing route (tag has only one route which return primitive value)
+    - [x] make right panel resizable by dragging
+    - [x] allow closing tag expansion item
+    - [x] hide brief mode if not configured
+    - [x] add focus button to only show related nodes under current route/tag graph in dialog
+- 0.10.2
+    - [x] fix graph height
+    - [x] show version in title
+- 0.10.3
+    - [x] fix focus in brief-mode
+    - [x] ui: adjust focus position
+    - [x] refactor naming
+    - [x] fix layout issue when rendering huge graph
+- 0.10.4
+    - [x] fix: when focus is on, should ensure changes from other params not broken.
+- 0.10.5
+    - [x] double click to show details, and highlight as tomato
+    
+
+## 0.11
+- 0.11.1
+    - [x] support opening route in swagger
+        - [x] config docs path
+    - [x] provide option to hide routes in brief mode (auto hide in full graph mode)
+- 0.11.2
+    - [x] enable/disable module cluster  (to save space)
+- 0.11.3
+    - [x] support online repo url
+- 0.11.4
+    - [x] add loading for field detail panel
+- 0.11.5
+    - [x] optimize open in swagger link
+    - [x] change jquery cdn
+- 0.11.6
+    - [x] flag of loading full graph in first render or not
+    - [x] optimize loading static resource 
+- 0.11.7
+    - [x] fix swagger link
+- 0.11.8
+    - [x] fix swagger link in another way
+- 0.11.9
+    - [x] replace issubclass with safe_issubclass to prevent exception.
+- 0.11.10
+    - [x] fix bug during updating forward refs
+- 0.11.11
+    - [x] replace print with logging and add `--log-level` in cli, by default info
+    - [x] fill node title color with module color
+    - [x] optimize cluster render logic
+
+## 0.12
+- 0.12.1
+    - [x] sort tag / route names in left panel
+    - [x] display schema name on top of detail panel
+    - [x] optimize dbclick style
+    - [x] persist the tag/ route in url
+- 0.12.2
+    - [ ] search tag/ route
+    - [ ] refactor render.py
+    - [ ] reorg: move variable into reactive in vue-main.js
+
+## 0.13
+- 0.12.0
+    - [ ] integration with pydantic-resolve
+        - [ ] show hint for resolve, post fields
+        - [ ] display loader as edges
+    - [ ] add tests
+
+## 0.13
+todo
+

fastapi_voyager-0.12.1/docs/idea.md

@@ -0,0 +1,22 @@
+# Idea
+
+## backlog
+- [ ] user can generate nodes/edges manually and connect to generated ones
+    - [ ] eg: add owner
+    - [ ] add extra info for schema
+- [ ] optimize static resource (allow manually config url)
+- [ ] improve search dialog
+    - [ ] add route/tag list
+- [ ] type alias should not be kept as node instead of compiling to original type
+- [ ] how to correctly handle the generic type ?
+- [ ] support Google analysis config
+- [ ] sort field name in nodes (only table inside right panel), pending
+- [ ] set max limit for fields in nodes
+
+## in analysis
+- [ ] upgrade network algorithm (optional)
+- [ ] click field to highlight links
+- [ ] animation effect for edges
+- [ ] display standard ER diagram spec. `hard but important`
+    - [ ] display potential invalid links
+    - [ ] highlight relationship belongs to ER diagram

{fastapi_voyager-0.11.11 → fastapi_voyager-0.12.1}/src/fastapi_voyager/server.py

@@ -57,6 +57,9 @@ def create_voyager(
 
 		# include tags and their routes
 		tags = voyager.tags
+		for t in tags:
+			t.routes.sort(key=lambda r: r.name)
+		tags.sort(key=lambda t: t.name)
 
 		schemas = voyager.nodes[:]
 		schemas.sort(key=lambda s: s.name)

{fastapi_voyager-0.11.11 → fastapi_voyager-0.12.1}/src/fastapi_voyager/version.py

@@ -1,2 +1,2 @@
 __all__ = ["__version__"]
-__version__ = "0.11.11"
+__version__ = "0.12.1"

{fastapi_voyager-0.11.11 → fastapi_voyager-0.12.1}/src/fastapi_voyager/web/component/schema-code-display.js

@@ -157,6 +157,7 @@ export default defineComponent({
         <q-linear-progress indeterminate color="primary" size="2px"/>
       </div>
       <div class="q-ml-lg q-mt-md">
+        <p style="font-size: 16px;"> {{ schemaName }} </p>
         <a :href="link" target="_blank" rel="noopener" style="font-size:12px; color:#3b82f6;">
           Open in VSCode
         </a>

{fastapi_voyager-0.11.11 → fastapi_voyager-0.12.1}/src/fastapi_voyager/web/graph-ui.js

@@ -58,9 +58,10 @@ export class GraphUI {
   }
 
   highlightSchemaBanner(node) {
-    const ele = node.querySelector("polygon[fill='#009485']")
+    const polygons = node.querySelectorAll("polygon");
+    const ele = polygons[2]; // select the second polygon
     if (ele) {
-      ele.setAttribute('fill', 'tomato');
+      ele.setAttribute('stroke-width', '3.5');
     }
   }
 
@@ -160,12 +161,6 @@ export class GraphUI {
               }
             }
           });
-
-        $(document).on("keydown.graphui", function (evt) {
-          if (evt.keyCode === 27 && self.gv) {
-            self.gv.highlight();
-          }
-        });
       },
     });
   }

{fastapi_voyager-0.11.11 → fastapi_voyager-0.12.1}/src/fastapi_voyager/web/index.html

@@ -59,6 +59,9 @@
     .adjust-fit {
       height: calc(100vh - 54px);
     }
+
+    .github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}
+
     /* App boot loading overlay & gating */
     #app-loading-overlay {
       position: fixed;
@@ -167,9 +170,8 @@
                   </div>
                 </q-tooltip>
               </q-btn>
-            <a href="https://github.com/allmonday/fastapi-voyager" target="_blank" class="github-corner" aria-label="View source on GitHub"><svg width="52" height="52" viewBox="0 0 250 250" style="fill:#009485; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"/><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"/><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"/></svg></a><style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style></div>
-            <!-- <q-toolbar-title class="text-primary row">
-            </q-toolbar-title> -->
+            <a href="https://github.com/allmonday/fastapi-voyager" target="_blank" class="github-corner" aria-label="View source on GitHub"><svg width="52" height="52" viewBox="0 0 250 250" style="fill:#009485; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"/><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"/><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"/></svg></a>
+          </div>
           </q-toolbar>
         </q-header>
 

{fastapi_voyager-0.11.11 → fastapi_voyager-0.12.1}/src/fastapi_voyager/web/vue-main.js

@@ -59,6 +59,66 @@ const app = createApp({
       showDetail.value = false;
     }
 
+    function readQuerySelection() {
+      if (typeof window === "undefined") {
+        return { tag: null, route: null };
+      }
+      const params = new URLSearchParams(window.location.search);
+      return {
+        tag: params.get("tag") || null,
+        route: params.get("route") || null,
+      };
+    }
+
+    function findTagByRoute(routeId) {
+      return (
+        state.rawTags.find((tag) =>
+          (tag.routes || []).some((route) => route.id === routeId)
+        )?.name || null
+      );
+    }
+
+    function syncSelectionToUrl() {
+      if (typeof window === "undefined") {
+        return;
+      }
+      const params = new URLSearchParams(window.location.search);
+      if (state.tag) {
+        params.set("tag", state.tag);
+      } else {
+        params.delete("tag");
+      }
+      if (state.routeId) {
+        params.set("route", state.routeId);
+      } else {
+        params.delete("route");
+      }
+      const hash = window.location.hash || "";
+      const search = params.toString();
+      const base = window.location.pathname;
+      const newUrl = search ? `${base}?${search}${hash}` : `${base}${hash}`;
+      window.history.replaceState({}, "", newUrl);
+    }
+
+    function applySelectionFromQuery(selection) {
+      let applied = false;
+      if (selection.tag && state.rawTags.some((tag) => tag.name === selection.tag)) {
+        state.tag = selection.tag;
+        state._tag = selection.tag;
+        applied = true;
+      }
+      if (selection.route && state.routeItems?.[selection.route]) {
+        state.routeId = selection.route;
+        applied = true;
+        const inferredTag = findTagByRoute(selection.route);
+        if (inferredTag) {
+          state.tag = inferredTag;
+          state._tag = inferredTag;
+        }
+      }
+      return applied;
+    }
+
     async function loadInitial() {
       state.initializing = true;
       try {
@@ -82,6 +142,14 @@ const app = createApp({
         state.version = data.version || "";
         state.swaggerUrl = data.swagger_url || null
 
+        const querySelection = readQuerySelection();
+        const restoredFromQuery = applySelectionFromQuery(querySelection);
+        if (restoredFromQuery) {
+          syncSelectionToUrl();
+          onGenerate();
+          return;
+        }
+
         switch (data.initial_page_policy) {
           case "full":
             onGenerate()
@@ -246,6 +314,7 @@ const app = createApp({
       state.focus = false;
       schemaCodeName.value = "";
       onGenerate();
+      syncSelectionToUrl();
     }
 
     function toggleTag(tagName, expanded = null) {
@@ -262,6 +331,7 @@ const app = createApp({
 
       state.detailDrawer = false;
       showRouteDetail.value = false;
+      syncSelectionToUrl();
     }
 
     function selectRoute(routeId) {
@@ -275,6 +345,7 @@ const app = createApp({
       state.focus = false;
       schemaCodeName.value = "";
       onGenerate();
+      syncSelectionToUrl();
     }
 
     function toggleShowModule(val) {

{fastapi_voyager-0.11.11 → fastapi_voyager-0.12.1}/tests/programatic.py

@@ -8,5 +8,5 @@ app.mount(
         module_color={"tests.service": "purple", "tests.demo": "#ccaa00", "tests": "green"}, 
         module_prefix="tests.service", 
         swagger_url="/docs",
-        initial_page_policy='full',
+        initial_page_policy='first',
         online_repo_url="https://github.com/allmonday/fastapi-voyager/blob/main"))