Public website

The public product website is separate from the Home created in consumer repositories. It is generated by website/build.mjs: plain static HTML/CSS, repository Markdown rendered by Marked, and a small browser module for themes, clipboard interaction, and background motion. No browser framework, runtime GitHub API, analytics, third-party fonts, or server-side service is required.

Build and preview

After the normal developer dependency/renderer setup and core build:

corepack yarn website:build
node website/serve.mjs

Open http://127.0.0.1:4188/topo-code/. Output lives in dist/public-site; generated files are never committed. The preview server is local only.

The final visual direction is Contour + Blueprint. The comparison page and temporary theme selector have been removed.

The marketing homepage embeds the live From idea to architecture story immediately after its introduction. Its "See it in action" link jumps to the demo, which embeds the generated viewer.html directly in its native presentation mode. Only the diagram, title, and viewer controls appear: no storybook sidebar or outer details wrapper. Focus, export, Blueprint theme ownership, and expand/restore remain live. "Open full storybook" supplies source details and module navigation; the separate Demo page keeps the full shell unchanged. It is not a screenshot or a separately authored copy.

SITE_BASE_PATH=/ builds for a later custom domain. The default is /topo-code/. Build-time path validation rejects traversal and malformed paths. The website test suite exercises both deployment shapes.

corepack yarn website:test

If another preview owns port 4188, leave it running and use WEBSITE_TEST_PORT=4289 corepack yarn website:test with a free port. The test server is always separate; the suite never reuses an existing preview.

Content ownership

• Marketing: website/build.mjs.
• Public docs: a curated set of maintained docs/*.md guides, with primary navigation. Other repository-relative links resolve to GitHub when they are not published pages.
• Roadmap: website/roadmap.json, curated Now / Next / Later. This is a rough outline, not the entire issue tracker or a delivery-date promise.
• Demo configuration: website/demo/.topo/config.json.
• Owner-selected theme: Blueprint in website/themes.mjs. Retired browser theme preferences no longer affect the site.
• Owner-selected mark: Contour in website/brand.mjs. The header and generated favicon share the same contour geometry.

Documentation is rendered directly from its maintained source, not copied into a second documentation tree. Public instructions describe the released product; development and release documents retain their separately labeled procedures.

Curated source-backed demo

Each build validates the eight curated stories against the working source and requires their story/evidence files to be committed. It clones that exact local revision into a temporary repository, retains the real origin, applies the demo catalogue configuration, then runs the actual topo init and topo bundle. The emitted bundle is copied unchanged, including notices and evidence receipts. No scanner or model is invoked. A local unpushed revision has local evidence; its GitHub source links become available only after that revision is published.

stories/public/internal-modules.topo.json covers the thirteen private runtime modules; build-only @topo/eslint-config remains in the companion context, not the primary map. Its twelve visible arrows are a selected dependency spine; each node's narrative contains all declared incoming/outgoing internal dependencies (31 declarations). dependency-context.topo.json groups internal consumers and nineteen direct external dependency names into five roles, preserving dependency/dev/peer/optional kinds and requested versions in details. Neither map claims runtime calls or a transitive dependency inventory. Stable node IDs are reserved for future curated drilldowns; only real cross-story links are emitted.

The internal map's LENS groups modules into command orchestration, source analysis, contracts/evidence, graph shaping, rendering/view data, and supplemental evidence. These are authored responsibilities, not inferred frontend/backend types. Comparing two roles highlights only direct cross-role arrows drawn in this deliberately sparse map; the full declaration lists remain in node details.

cli-surface.topo.json and diagram-core-surface.topo.json are child boundary views, not implementation walkthroughs. They show the command/package entry points, exported modules/functions/interfaces, and selected declared references. CLI's command binary is distinct from its root barrel exports. Only the renderer root's actual exports are shown, not every exported symbol in its source tree. These remain private workspace interfaces, not a stable public SDK.

Explicit node drilldown targets connect the module map to both children and the CLI's renderer reference to diagram-core. A child parent declaration provides a return link even after direct opening. Source evidence and other related-story links remain available; published targets are validated.

story-to-screen.topo.json now shows From idea to architecture as a native sequence: you ask the agent, the CLI supplies deterministic scan evidence, the agent uses the scan results to build a diagram, hands it to you for review, and the cycle repeats. Validation/rendering round-trips are intentionally omitted from this overview. Its outcome is understanding code at a glance rather than reading files one by one. The repository lifeline makes source reads and authored stories explicit; routine Git procedure is omitted from this product explanation. This is the documented collaboration workflow, not a call trace of one process. Scan never invokes the model; agent interpretation does not require the separate topo enrich command. Operational prerequisites remain in the usage guides.

Three algorithm sequences add implementation-level explanations without inventing services or runtime telemetry:

• algorithm-evidence-extraction: TypeScript/JavaScript scan, compiler resolution, deterministic graph construction, and the semantic pass. Missing assignments remain unassigned; no architecture is invented.
• algorithm-anchor-resolution: the CLI's captured-source path through exact anchor resolution and freshness checks. Optional digests, first-name TypeScript AST lookup, exact patterns, and refusal conditions stay explicit.
• algorithm-graph-projection: reusable indexed projection and directed edge aggregation with hidden-edge accounting. Tarjan cycle groups are prepared upstream, not recalculated for every view. This is distinct from rendering, Repository page generation, and the manually authored module map.

The scanner, story, and graph boxes drill into these sequences. Each has a canonical return to its module, complete source anchors, and per-message rationale. Lifelines denote local code/API/data boundaries, not new services. Each starts with a named logical initiator and its goal: @topo/languages requests code evidence, the CLI story validator checks draft evidence, and the graph layout session requests a visible graph before placing nodes. Avoid generic "Caller" lifelines that conceal why the algorithm is being invoked.

catalogue.storyIds selects exactly these eight maps. Existing development stories and examples are preserved but excluded from the demo. Hash-bound evidence fails on source drift; it must be reassessed, not silently regenerated during builds.

The website palette applies a presentation-only stylesheet to the same-origin embedded storybook shell. It never rewrites generated bundle files or renderer receipts. The embedded Home uses Blueprint rather than a competing dark/light button; standalone Home retains its native dark/light control. Broader renderer palette support is not implied by this shell styling.

Background motion

The contour artwork is original and procedural, inspired by the owner's topographic references rather than copied image or shader assets:

• https://codepen.io/trydionel/pen/GmVKpy
• https://dietcode.io/p/topographic/
• https://codepen.io/josev1207/pen/ZEdEmgQ

Keep it subordinate to content, palette-aware, pausable, and static for prefers-reduced-motion. Documentation uses a quieter static background. The original WebGL field changes slowly at up to 24 frames per second, with drawing resolution capped at 800,000 pixels. Hidden tabs stop animating. Graphics unavailability or context loss displays the prebuilt SVG fallback and reports a browser warning instead of breaking the page.

GitHub Pages

.github/workflows/website.yml builds and checks on pull requests, pushes to main, and manual dispatch. Only a successful main-branch push or dispatch can deploy. Deployments use GitHub's Pages artifact and OIDC flow; PRs have read-only contents permissions and never deploy.

Enable Settings → Pages → Source → GitHub Actions once, then allow the github-pages environment to deploy from main. The workflow uses actions/configure-pages to discover the actual base path, supporting project Pages and later custom-domain deployment. DNS/domain purchase is separate. No additional visual approval job is inserted.

CI checks rendered local links and fragments, Blueprint styling, mobile layout, keyboard access, accessibility, motion preferences, source freshness, dependency coverage, and module-to-context/return navigation. A website workflow in a branch is not a published website; deployment requires integration into main and Pages configuration.