forked/topola-viewer
1
0
Fork 0
mirror of https://github.com/PeWu/topola-viewer.git synced 2026-05-26 15:16:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix file paths in docs

Browse Source
This commit is contained in:
Przemek Więch
2026-05-12 00:33:42 +02:00
parent 20bddfaeb6
commit 6006cf725f
5 changed files with 23 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.github/workflows/README.md vendored
View File

@@ -4,9 +4,9 @@ This directory contains GitHub Actions workflow files that automate various task
## Files ## Files
- [codeql-analysis.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/codeql-analysis.yml): Performs CodeQL security analysis on the codebase to identify potential vulnerabilities. - [codeql-analysis.yml](codeql-analysis.yml): Performs CodeQL security analysis on the codebase to identify potential vulnerabilities.
- [deploy-docker.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/deploy-docker.yml): Automatically builds and publishes the lightweight Caddy-based Docker image of the application to GitHub Container Registry (GHCR). - [deploy-docker.yml](deploy-docker.yml): Automatically builds and publishes the lightweight Caddy-based Docker image of the application to GitHub Container Registry (GHCR).
- [deploy-everywhere.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/deploy-everywhere.yml): A manually triggered workflow that initiates deployment to both GitHub Pages and WikiTree Apps by calling their respective workflow files. - [deploy-everywhere.yml](deploy-everywhere.yml): A manually triggered workflow that initiates deployment to both GitHub Pages and WikiTree Apps by calling their respective workflow files.
- [deploy-gh-pages.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/deploy-gh-pages.yml): Handles the deployment of the application to GitHub Pages. - [deploy-gh-pages.yml](deploy-gh-pages.yml): Handles the deployment of the application to GitHub Pages.
- [deploy-wikitree-apps.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/deploy-wikitree-apps.yml): Manages the deployment of the application to WikiTree Apps using SFTP. - [deploy-wikitree-apps.yml](deploy-wikitree-apps.yml): Manages the deployment of the application to WikiTree Apps using SFTP.
- [node.js.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/node.js.yml): The main Continuous Integration (CI) workflow. It installs dependencies, checks formatting, lints, builds, and runs tests across multiple Node.js versions. - [node.js.yml](node.js.yml): The main Continuous Integration (CI) workflow. It installs dependencies, checks formatting, lints, builds, and runs tests across multiple Node.js versions.

4
docs/PLAYWRIGHT_DESIGN.md
View File

@@ -72,7 +72,7 @@ To establish clear architectural guardrails and prevent future regressions or re
### C. Maintaining Physical HTML Wrapper Files for Iframe Tests ### C. Maintaining Physical HTML Wrapper Files for Iframe Tests
* **Considered:** Storing a physical `tests/fixtures/embedded_frame.html` file in the repository to act as the container for iframe tests. * **Considered:** Storing a physical `tests/fixtures/embedded_frame.html` file in the repository to act as the container for iframe tests.
* **Rejected because:** Storing a physical, standalone test-only wrapper file can create environment port synchronization issues and static asset mapping overhead. * **Rejected because:** Storing a physical, standalone test-only wrapper file can create environment port synchronization issues and static asset mapping overhead.
* **Actual Implementation Note:** The implementation adopted a hybrid approach. A physical template file [embedded_frame.html](file:///home/pwiech/personal/github/topola-viewer/tests/fixtures/embedded_frame.html) is maintained as the structural source of truth for the frame, but it is loaded in-memory and served virtually on `/test-embedded-frame.html` via the network router, keeping it on the same origin/port dynamically to bypass cross-origin iframe blocks. * **Actual Implementation Note:** The implementation adopted a hybrid approach. A physical template file [embedded_frame.html](../tests/fixtures/embedded_frame.html) is maintained as the structural source of truth for the frame, but it is loaded in-memory and served virtually on `/test-embedded-frame.html` via the network router, keeping it on the same origin/port dynamically to bypass cross-origin iframe blocks.
### D. Retaining `start-server-and-test` for Dev Server Bootstrapping ### D. Retaining `start-server-and-test` for Dev Server Bootstrapping
* **Considered:** Continuing to rely on `start-server-and-test` or a custom bash script to verify when port `3000` is responsive before running tests. * **Considered:** Continuing to rely on `start-server-and-test` or a custom bash script to verify when port `3000` is responsive before running tests.
@@ -174,7 +174,7 @@ This section defines the granular step-by-step instructions and enumerates **eve
* `"test:e2e:ui": "playwright test --ui"` * `"test:e2e:ui": "playwright test --ui"`
2. Author `playwright.config.ts` to orchestrate the `webServer` dynamically based on execution context, and poll port `3000`. 2. Author `playwright.config.ts` to orchestrate the `webServer` dynamically based on execution context, and poll port `3000`.
**Key Configuration Details for [playwright.config.ts](file:///home/pwiech/personal/github/topola-viewer/playwright.config.ts):** **Key Configuration Details for [playwright.config.ts](../playwright.config.ts):**
* **Test Directory**: Target `./tests` folder. * **Test Directory**: Target `./tests` folder.
* **Parallelism & CI Tuning**: Enable fully parallel execution (`fullyParallel: true`), disable `forbidOnly` locally but enforce it in CI, and configure retries (2 in CI, 0 locally). * **Parallelism & CI Tuning**: Enable fully parallel execution (`fullyParallel: true`), disable `forbidOnly` locally but enforce it in CI, and configure retries (2 in CI, 0 locally).
* **Base Configuration**: Set the `baseURL` to `http://localhost:3000`, force the locale to `'en-US'` to ensure consistent translation keys across all runs, and capture traces on first retry. * **Base Configuration**: Set the `baseURL` to `http://localhost:3000`, force the locale to `'en-US'` to ensure consistent translation keys across all runs, and capture traces on first retry.

8
docs/README.md
View File

@@ -8,7 +8,7 @@ While new features *may* follow this methodology to ensure robust design validat
## Design Documents Registry ## Design Documents Registry
* **[DOCKER_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/DOCKER_DESIGN.md)**: Docker container packaging, lightweight Caddy web server configuration, and GitHub Actions publishing pipelines. * **[DOCKER_DESIGN.md](DOCKER_DESIGN.md)**: Docker container packaging, lightweight Caddy web server configuration, and GitHub Actions publishing pipelines.
* **[PLAYWRIGHT_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/PLAYWRIGHT_DESIGN.md)**: Playwright E2E testing architecture, Vite development/preview server lifecycle integration, tracking blocker interceptors, and embedded iframe communication. * **[PLAYWRIGHT_DESIGN.md](PLAYWRIGHT_DESIGN.md)**: Playwright E2E testing architecture, Vite development/preview server lifecycle integration, tracking blocker interceptors, and embedded iframe communication.
* **[SCREENSHOT_TESTS_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/SCREENSHOT_TESTS_DESIGN.md)**: Pixel-perfect visual regression testing infrastructure, animation stabilization, sandbox environment/DOM sanitization, and isolated Playwright projects. * **[SCREENSHOT_TESTS_DESIGN.md](SCREENSHOT_TESTS_DESIGN.md)**: Pixel-perfect visual regression testing infrastructure, animation stabilization, sandbox environment/DOM sanitization, and isolated Playwright projects.
* **[WEBMCP_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/WEBMCP_DESIGN.md)**: Model Context Protocol (MCP) bridge and TS tool registration for AI agent interaction. * **[WEBMCP_DESIGN.md](WEBMCP_DESIGN.md)**: Model Context Protocol (MCP) bridge and TS tool registration for AI agent interaction.

18
docs/WEBMCP_DESIGN.md
View File

@@ -236,7 +236,7 @@ Traverses downwards up to bounded ceiling generations.
## Detailed Implementation Plan ## Detailed Implementation Plan
This section lists the exact files to be created or modified to execute this design successfully. This section lists the exact files to be created or modified to execute this design successfully.
#### 1. [Modify] [webmcp.ts](file:///home/pwiech/personal/github/topola-viewer/src/webmcp.ts) #### 1. [Modify] [webmcp.ts](../src/webmcp.ts)
* **Rationale:** Serves as the core integration plug for the experimental WebMCP browser assistant setup and standard operational in-memory state cache. * **Rationale:** Serves as the core integration plug for the experimental WebMCP browser assistant setup and standard operational in-memory state cache.
* **Action steps:** * **Action steps:**
* Define isolated state stores for current `selection`, `detailIndi`, and `loadedGedcomData`. * Define isolated state stores for current `selection`, `detailIndi`, and `loadedGedcomData`.
@@ -244,32 +244,32 @@ This section lists the exact files to be created or modified to execute this des
* Expose default standard state setters for Topola view adapter. * Expose default standard state setters for Topola view adapter.
* Implement conversion and response helpers (`toMcpResponse`, `textMcpResponse`, `toBasicIndi`, `toFullIndi`) to standardise in-transit JSON streams. * Implement conversion and response helpers (`toMcpResponse`, `textMcpResponse`, `toBasicIndi`, `toFullIndi`) to standardise in-transit JSON streams.
### 2. [NEW] [webmcp_definitions.ts](file:///home/pwiech/personal/github/topola-viewer/src/webmcp_definitions.ts) ### 2. [NEW] [webmcp_definitions.ts](../src/webmcp_definitions.ts)
* **Rationale:** Keeps standard LLM tool definition blueprints separate from the execution bridge to avoid bloat and single interface monolithic designs. * **Rationale:** Keeps standard LLM tool definition blueprints separate from the execution bridge to avoid bloat and single interface monolithic designs.
### 3. [NEW] [webmcp_types.ts](file:///home/pwiech/personal/github/topola-viewer/src/webmcp_types.ts) ### 3. [NEW] [webmcp_types.ts](../src/webmcp_types.ts)
* **Rationale:** Defines ambient `navigator.modelContext` parameters and concrete structural bridge types cleanly. * **Rationale:** Defines ambient `navigator.modelContext` parameters and concrete structural bridge types cleanly.
### 4. [Modify] [app.tsx](file:///home/pwiech/personal/github/topola-viewer/src/app.tsx) ### 4. [Modify] [app.tsx](../src/app.tsx)
* **Rationale:** The top-level state component for Topola Viewer. It holds the interactive chart state and needs standard side effect hooks to update the WebMCP context on active selections. * **Rationale:** The top-level state component for Topola Viewer. It holds the interactive chart state and needs standard side effect hooks to update the WebMCP context on active selections.
* **Action steps:** * **Action steps:**
* Initialize WebMCP Bridge securely using `useState(() => new WebMcpBridge())` avoiding loose disconnected singleton memory leaks. * Initialize WebMCP Bridge securely using `useState(() => new WebMcpBridge())` avoiding loose disconnected singleton memory leaks.
* Add standard `React.useEffect` hook to monitor active viewport selection changes and feed them into the WebMCP in-transit state. * Add standard `React.useEffect` hook to monitor active viewport selection changes and feed them into the WebMCP in-transit state.
* Expose selection and inspection callbacks handlers to the bridge hook preset. * Expose selection and inspection callbacks handlers to the bridge hook preset.
### 5. [Modify] [gedcom_util.ts](file:///home/pwiech/personal/github/topola-viewer/src/util/gedcom_util.ts) ### 5. [Modify] [gedcom_util.ts](../src/util/gedcom_util.ts)
* **Rationale:** Handles core conversion formulas from raw gedcom pointers to JSON objects. Houses newly proposed BFS algorithms avoiding visual rendering components dependency. * **Rationale:** Handles core conversion formulas from raw gedcom pointers to JSON objects. Houses newly proposed BFS algorithms avoiding visual rendering components dependency.
* **Action steps:** * **Action steps:**
* Implement standard Breadth-First Search (BFS) method for isolated `find_relationship_path` relative footprint. * Implement standard Breadth-First Search (BFS) method for isolated `find_relationship_path` relative footprint.
* Draft flat array collection algorithms (bounded up to preset depth ceiling) for ancestors and descendants generation list. * Draft flat array collection algorithms (bounded up to preset depth ceiling) for ancestors and descendants generation list.
### 6. [Modify] [gedcom_util.spec.ts](file:///home/pwiech/personal/github/topola-viewer/src/util/gedcom_util.spec.ts) ### 6. [Modify] [gedcom_util.spec.ts](../src/util/gedcom_util.spec.ts)
* **Rationale:** Standard isolated unit test suite. It must accommodate boundary tests for newly added generic algorithms. * **Rationale:** Standard isolated unit test suite. It must accommodate boundary tests for newly added generic algorithms.
* **Action steps:** * **Action steps:**
* Add unit test cases for `find_relationship_path` with disconnected and connected multi relationships. * Add unit test cases for `find_relationship_path` with disconnected and connected multi relationships.
* Add test vectors for `get_ancestors` boundary ceilings (e.g., 5 generations) and cycles control. * Add test vectors for `get_ancestors` boundary ceilings (e.g., 5 generations) and cycles control.
### 7. [New] [webmcp.cy.js](file:///home/pwiech/personal/github/topola-viewer/cypress/e2e/webmcp.cy.js) ### 7. [New] [webmcp.cy.js](../cypress/e2e/webmcp.cy.js)
* **Rationale:** Formatted test files acting as automated integration coverage. Leverages Cypress stubs for isolated web tools inspection. * **Rationale:** Formatted test files acting as automated integration coverage. Leverages Cypress stubs for isolated web tools inspection.
* **Action steps:** * **Action steps:**
* Mock `navigator.modelContext` using `cy.visit` on before preset lifecycle hooks. * Mock `navigator.modelContext` using `cy.visit` on before preset lifecycle hooks.
@@ -300,9 +300,9 @@ To ensure the robustness and correctness of the WebMCP integration, we will empl
* Because interactive tools are bound to the experimental WebMCP protocol, manual verification can be accelerated using the **Model Context Tool Inspector Chrome Extension**. This grants operational developers a dashboard panel to trigger and fire tools independently inside standard dev viewports. * Because interactive tools are bound to the experimental WebMCP protocol, manual verification can be accelerated using the **Model Context Tool Inspector Chrome Extension**. This grants operational developers a dashboard panel to trigger and fire tools independently inside standard dev viewports.
### Files Created or Modified for Testing ### Files Created or Modified for Testing
* **[Modify] [gedcom_util.spec.ts](file:///home/pwiech/personal/github/topola-viewer/src/util/gedcom_util.spec.ts)** * **[Modify] [gedcom_util.spec.ts](../src/util/gedcom_util.spec.ts)**
* **Rationale:** Contains existing unit tests for GEDCOM data structures. It will be extended to verify the newly introduced relationship finding and bounded graph traversal algorithms without visual overhead. * **Rationale:** Contains existing unit tests for GEDCOM data structures. It will be extended to verify the newly introduced relationship finding and bounded graph traversal algorithms without visual overhead.
* **[New] [webmcp.cy.js](file:///home/pwiech/personal/github/topola-viewer/cypress/e2e/webmcp.cy.js)** * **[New] [webmcp.cy.js](../cypress/e2e/webmcp.cy.js)**
* **Rationale:** Will act as the dedicated automated integration suite for the WebMCP feature. It will stub `navigator.modelContext` to verify correct tool registration and that standard execution callbacks successfully sync back layout and selection changes inside the Topola visual DOM. * **Rationale:** Will act as the dedicated automated integration suite for the WebMCP feature. It will stub `navigator.modelContext` to verify correct tool registration and that standard execution callbacks successfully sync back layout and selection changes inside the Topola visual DOM.
## Future Considerations ## Future Considerations

4
tests/README.md
View File

@@ -5,8 +5,8 @@ This directory houses all automated test specifications and validation fixtures
## Test Design Reference Documents ## Test Design Reference Documents
Before writing new or adjusting existing tests, developers should review their corresponding systems design guidelines under the `docs/` directory to align with established conventions and paradigms: Before writing new or adjusting existing tests, developers should review their corresponding systems design guidelines under the `docs/` directory to align with established conventions and paradigms:
* **[PLAYWRIGHT_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/PLAYWRIGHT_DESIGN.md)**: Explains overall Playwright orchestration, server hooks, mock GEDCOM network intercept routines, tracking blockages, and in-memory iframe environments. * **[PLAYWRIGHT_DESIGN.md](../docs/PLAYWRIGHT_DESIGN.md)**: Explains overall Playwright orchestration, server hooks, mock GEDCOM network intercept routines, tracking blockages, and in-memory iframe environments.
* **[SCREENSHOT_TESTS_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/SCREENSHOT_TESTS_DESIGN.md)**: Outlines visual testing strategies, viewport locks, dynamic footer/changelog sanitization overrides in virtual DOMs, threshold sensitivities, and local baseline update policies. * **[SCREENSHOT_TESTS_DESIGN.md](../docs/SCREENSHOT_TESTS_DESIGN.md)**: Outlines visual testing strategies, viewport locks, dynamic footer/changelog sanitization overrides in virtual DOMs, threshold sensitivities, and local baseline update policies.
--- ---