STV_ADR_004: Concrete dependency and delivery stack

Status: accepted. Date: 2026-10-18. Scope: solution/software architecture. Decision owner: project owner. Supersedes: none. Superseded by: none. The original proposal refined STV_ADR_001: Static build integration and browser runtime, STV_ADR_002: Portable graph and rendered-detail bundle and STV_ADR_003: Transactional exploration and semantic rank layout.

Context

The owner requested an implementation-ready concept after finding the initial proposal insufficiently specific about external libraries and tools. The accepted baseline requires semantic levels, cycles, native keyboard interaction, full rendered details, offline file URLs and installed Firefox on Windows. The initial custom-layout proposal lacked a technology comparison.

Decision

Select ELK.js 0.10.0 for ordering suggestions, D3 zoom 3.0.0 and selection 3.0.0 for viewport interactions, Floating UI DOM 1.7.4 for panel placement and Beautiful Soup 4.13.5 with html.parser for final rendered Need extraction. STV owns semantic projection, state, final edge routing, accessible controls and panel lifecycle. Library algorithms do not replace domain requirements.

Use esbuild 0.25.12 to create a bundled IIFE without runtime workers or module requests, Hatchling 1.27.0/build 1.3.0 to package prebuilt assets, pytest 8.4.2 and Node’s native test runner for unit/integration checks, and Selenium 4.35.0 with release Firefox/geckodriver for browser verification. Exact browser/driver versions are recorded per release rather than declared permanently supported.

Detailed roles, licenses, selected manifests and sources are in Technology stack and dependency decisions; implementation contracts are in Implementation concept and handover and Implementation verification plan.

Rationale

Existing libraries handle general graph ordering, viewport gestures, overlay geometry and HTML parsing. STV keeps semantic constraints and accessible DOM interactions explicit. This avoids replacing the hard hierarchy with force layout or treating a canvas graph as automatically keyboard accessible. Selenium verifies the installed release Firefox rather than a patched browser.

Logical components and interfaces

Beautiful Soup is confined to Rendered detail extraction (STV_SWE_DETAIL_BUILD). ELK is isolated by the Semantic rank layout (STV_SWE_LAYOUT) adapter. D3 belongs to Accessible view and viewport (STV_SWE_RENDER) and Floating UI to Hover, persistent details a... (STV_SWE_INSPECT). Browser libraries are built into the wheel’s local assets through Static bundle emission (STV_SWE_BUNDLE). Host projects require Python dependencies only; Node remains a maintainer tool.

Consequences and constraints

ELK’s y coordinates and routes cannot be trusted after semantic projection; STV recomputes them under its hard constraints. The measured minified library bundle is approximately 1.5 MB, before graph data. Full Need bodies load from local per-object scripts on demand. Include dependency notices and the selected ELK source/license redistribution materials. Python transitive hashes are captured when assembling the first implementation environment.

Alternatives considered

Entirely custom graph ordering: not selected because a general solver already provides useful ordering and cycle handling; only domain constraints remain custom.
ELK output used unchanged: rejected because topology-derived layers do not guarantee semantic hierarchy or right-side test placement.
Cytoscape/canvas-first rendering: not selected because HTML controls and rich details would still require an accessible DOM representation and synchronization.
React: not selected; the isolated views do not need a framework lifecycle.
Playwright Firefox for release verification: not selected because it uses a patched Firefox rather than the required installed release browser.
lxml: not selected; html.parser meets the initial extraction use case without a native parser dependency.