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
- [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.
- [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-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-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-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.
- [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.
- [codeql-analysis.yml](codeql-analysis.yml): Performs CodeQL security analysis on the codebase to identify potential vulnerabilities.
- [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](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](deploy-gh-pages.yml): Handles the deployment of the application to GitHub Pages.
- [deploy-wikitree-apps.yml](deploy-wikitree-apps.yml): Manages the deployment of the application to WikiTree Apps using SFTP.
- [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
* **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.
* **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
* **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"`
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.
* **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.

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
* **[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.
* **[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.
* **[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.
* **[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.
* **[DOCKER_DESIGN.md](DOCKER_DESIGN.md)**: Docker container packaging, lightweight Caddy web server configuration, and GitHub Actions publishing pipelines.
* **[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](SCREENSHOT_TESTS_DESIGN.md)**: Pixel-perfect visual regression testing infrastructure, animation stabilization, sandbox environment/DOM sanitization, and isolated Playwright projects.
* **[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
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.
* **Action steps:**
* 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.
* 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.
### 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.
### 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.
* **Action steps:**
* 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.
* 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.
* **Action steps:**
* 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.
### 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.
* **Action steps:**
* 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.
### 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.
* **Action steps:**
* 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.
### 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.
* **[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.
## 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
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.
* **[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.
* **[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](../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.
---