Source-grounded story preview

Topo stories are committed JSON documents whose identity, narrative, and source anchors are independent of any renderer. The checked schema is exported as @topo/story/story.schema.json; anchors contain a repository-relative path, an optional symbol, and an optional exact pattern. A pattern with a symbol is matched within that symbol; without a symbol, it is matched within the explicit file. Source line ranges and excerpts are resolved from the current working tree at preview time and are never stored in the authored document.

Architecture sections may include a short summary caption (for example, "Config and publication"). It appears beneath the node title instead of the primary source filename. The full body narrative and source anchors remain available in the evidence panel. Other diagram families do not accept this caption field. Explicit summaries retain their compact caption typography. Without a summary, the source-symbol or filename caption keeps the larger source-reference type; adding summaries does not reduce the legibility of existing source stories. This caption is an unreleased repository-build capability, not part of the published npm 0.2.0 story contract.

Architecture and Sequence sections can also author semanticRole, a lowercase hyphenated slug such as "source-analysis". The native LENS control groups those explicit roles and compares only arrows actually drawn in the story. It does not infer runtime traffic, transitive impact, or omitted dependencies. Missing roles are neutral "component" or "participant" entries, never a frontend/backend guess based on position. This is also an unreleased repository-build capability.

Topocode adapts the emitted viewer's documented data-node-kind metadata before runtime initialization, preserving geometry and the pinned renderer files. Their receipts identify topocode-story-semantics-v2 and distinguish native output hashes from adapted output hashes. Active lens selection remains viewer-only; the authored semantic roles are durable diagram metadata.

Sequence spacing

Agents can request wider participant columns through authored data:

{
  "diagramFamily": "sequence",
  "sequenceLayout": { "minimumParticipantGap": 220 }
}

The gap is a minimum center-to-center distance in SVG units (integer, at least 108). Topocode expands the sequence viewBox and spreads its columns; it does not stretch text or add zoom. Omission preserves existing automatic spacing. Readability checks still reject layouts that cannot meet the supported text floor. This is an unreleased repository-build option, not npm 0.2.0 behavior.

Explicit module drilldowns

An authored section can declare "drilldown": { "storyId": "cli-surface" }. Clicking that node opens the child story's overview; add nodeId only when a particular destination node should be focused. This explicit destination wins over automatically discovered shared-evidence links. Other related stories and source evidence remain available in details. The sidebar docks only when enough diagram reading width is available. Opening details reserves space below the viewer rather than covering diagram titles. The evidence pane scrolls independently, and navigation controls remain keyboard-accessible and unobscured; non-Sequence focus still opens evidence automatically.

A child can declare "parent": { "storyId": "internal-modules", "nodeId": "cli" }. The storybook displays a visible return link even when the child is opened directly. Navigation from another story takes precedence over this canonical parent, so nested drilldowns return to the actual caller. Returning or reloading a focused parent does not automatically drill in again. The URL carries a validated stack of caller story IDs and optional authored node IDs across nested returns and reloads. Legacy from / fromFocus links still work; unknown story/node targets are ignored with a browser warning rather than used as redirect URLs. Sequence participant focus keeps the native details presentation; opening the storybook source panel remains explicit.

Targets must exist in the selected catalogue, target nodes must exist, and parent cycles are rejected before rendering. Direct hosted viewer.html pages can enter their child storybook routes; a downloaded isolated HTML file does not pretend to contain other diagrams. These are unreleased repository-build capabilities, not options in the published npm 0.2.0 schema.

Section IDs remain renderer-neutral, including IDs such as 1-start, src/api.ts, or Unicode text. Wrapper focus URLs and drilldown nodeId values use authored IDs. @topo/diagram-core exposes storyNodeIds(document, renderer?) as authored/native ID pairs for integrations: Archify may use a stable component hash, while Graphviz retains the authored ID. Native metadata, edge endpoints, and exported geometry keep their renderer IDs; activation maps back to the authored section. Direct viewers also accept authored #focus= fragments.

Native Architecture cards show at most three compact source links, matching the pinned renderer's schema. Topocode still validates every section anchor and retains all of them in the story evidence panel and evidence.json; grouped nodes do not discard source evidence to fit the renderer. The integrated Architecture and Sequence viewers omit the redundant native node-index rail: the surrounding story shell already supplies node navigation and full evidence. The diagram, interactive node controls, search, focus, and exports remain intact.

The optional diagramFamily selects architecture, workflow, sequence, dataflow, or lifecycle; omission retains the legacy Architecture behavior. Sequence and Dataflow connections require a nonempty label because their native schemas require explicit relationship meaning. Architecture, Workflow, and Lifecycle connections may omit labels, and Topocode does not invent them. Dataflow previews preserve single-line authored node text by selecting the largest intrinsic pinned-font size that satisfies native node bounds and gaps, then emit matching node widths and a compact native viewBox. Content that cannot satisfy the renderer's legible minimum still fails explicitly. Lifecycle state widths are derived from their authored titles, then all states are placed together within their semantic native lanes so a wide state cannot silently reuse a neighboring state's column. The Archify 3.0.0 adapter retains native Lifecycle schema v1; it reserves the native minimum route gap and sizes states for final 14.5px typography so the adaptive viewer still meets Topocode's 12px effective on-screen text floor. Lifecycle uses an explicit Arial/Helvetica sans-serif stack rather than the host's system-ui face, keeping wide-label fitting stable across the supported macOS and Linux browser environments. Native v3 Lifecycle output omits empty bands and adds the terminal state's double border; neither changes authored state or transition membership.

The optional classification is source-grounded or capability-demo; omission retains the source-grounded behavior. Every source-grounded section must cite at least one resolved anchor. Capability demos are explicitly non-factual, contain no repository anchors, and appear in the generated Diagram capabilities catalogue category after source-grounded stories. Wrappers preserve the classification in visible text and data-story-classification.

Initialize a site before preview; no scan is required:

corepack yarn topo init /absolute/path/to/repository
corepack yarn topo story preview /absolute/path/to/repository /absolute/path/to/repository/stories/checkout.topo.json
corepack yarn topo serve /absolute/path/to/repository

Each story wrapper is written to .topo/cache/site/stories/<story-id>/index.html, with the native renderer artifact at viewer.html. Topocode keeps the vendored Archify runtime and integrity pin unchanged while adding scoped output rules for readable authored text and responsive containment. The generated application shell keeps a persistent diagram inventory beside the main viewer iframe. Classification, summary, return, and node controls remain available without placing a second navigation card over the rendered diagram. The shell is served at / and on every story route; the retired repository explorer is not generated. Run topo preview to select a committed story while refreshing all committed stories and the shared Home inventory without scanning:

corepack yarn topo preview /absolute/path/to/repository \
  /absolute/path/to/repository/stories/checkout.topo.json

topo story preview is the authoring-workflow spelling of the same command. Before committing a new or updated story, validate its structure and anchors against the current working tree without generating output:

corepack yarn topo story validate /absolute/path/to/repository \
  /absolute/path/to/repository/stories/checkout.topo.json

See local story authoring for the identity-preserving agent workflow and executable branch-change walkthrough.

The story file must be tracked, committed, and unchanged relative to HEAD. Source files may contain uncommitted changes: the CLI states that the preview describes the working tree while retaining the committed revision in rendered metadata. Source-grounded native rendering also requires the repository's Git origin remote for evidence validation. Initialization and anchor-free capability demos do not require a remote. This is the existing native evidence contract, not an instruction to invent a remote or misclassify factual stories as demos.

An optional nonempty category field supplies the story's catalogue category. Without it, Topocode derives a category from the first directory below stories/, or uses Stories for documents directly in that directory. Repository configuration can override either result; see story catalogue.

Missing files, symbols, patterns, invalid documents, unavailable renderers, and renderer failures exit nonzero. Rendering completes in memory before the generated file is atomically replaced, so renderer failures do not publish a partial story.

The viewer exports canonical authored geometry as SVG. Native v3 PNG exports place that same geometry, uniformly scaled, inside a title row and padded canvas card; the complete PNG therefore has a different aspect ratio than the bare SVG. No diagram content is cropped to force the old ratio. Local serving permits blob images only for generated story viewers so the pinned runtime can rasterize its serialized SVG without broadening the Content Security Policy for shell pages.

Successful structure and anchor validation does not establish semantic accuracy or complete explanation coverage. It is objective evidence for the author and human reviewer, not a staleness or coverage gate.

Reproducibility check

The regression suite renders the same frozen resolved story twice through the pinned @topo/diagram-core package and compares the complete returned artifact and generated HTML for exact equality. This verifies equivalence for the pinned renderer, dependency set, runtime, and input exercised by the test. It does not claim unmeasured universal byte identity across arbitrary renderers or environments.

@topo/story also exposes the renderer-neutral StoryRenderer contract. A contract-only substitute renderer test consumes the same story unchanged, proving renderer replacement does not require rewriting authored documents.