Story navigation and details

Source-grounded

The rendering module's exposed functions, shared input/output interfaces, and declared renderer dependencies. Arrows mean exports, contract references, or declared package dependencies—not private rendering steps. This private workspace API is bundled into @jdylanmc/topo-code; it is not a separately published stable SDK. Unlabelled spokes from the package box to API/utility boxes mean root exports; labelled edges distinguish other references.

  • @jdylanmc/topo-archify Open @topo/cli: public surface: @topo/diagram-coreOpen Dependency context by role: RenderingOpen Dependency context by role: Archify and GraphvizOpen Dependency context by role: Build, test, docsOpen Dependency context by role: Development toolsOpen Topocode internal modules: @topo/diagram-core

    Declared peer: @jdylanmc/topo-archify@0.1.0. This package supplies the pinned native Archify runtime. Consumers meet the peer requirement; it is not a child module re-exported by diagram-core.

    packages/diagram-core/package.json:1-34
    {
  "name": "@topo/diagram-core",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "files": [
    "dist",
    "archify-pin.json",
    "LICENSE",
    "THIRD_PARTY_NOTICES.md"
  ],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -b",
    "typecheck": "tsc -b --pretty false",
    "test": "tsc -b && node --test test/*.test.mjs"
  },
  "dependencies": {
    "@topo/story": "workspace:*",
    "@viz-js/viz": "3.30.0"
  },
  "peerDependencies": {
    "@jdylanmc/topo-archify": "0.1.0"
  },
  "devDependencies": {
    "@types/node": "^22",
    "typescript": "^7.0.2"
  }
}
  • Single-story API

    renderStory(story: ResolvedStoryDocument) -> StoryArtifact | Promise<StoryArtifact>. Input is already resolved source evidence, not raw repository scanning or an unvalidated JSON draft. The return can be synchronous or asynchronous, so callers can await it uniformly. The story's renderer selection controls the backend; this view deliberately does not expand private layout or rendering algorithms.

    packages/diagram-core/src/index.ts:1629-1629
    export function renderStory(story: ResolvedStoryDocument): StoryArtifact | Promise<StoryArtifact> {
  • @topo/story Open Source-anchor resolution and freshness: Anchor resolverOpen Dependency context by role: Code analysisOpen Dependency context by role: Language parsingOpen Dependency context by role: Schema contractsOpen Dependency context by role: JSON validationOpen Dependency context by role: Build, test, docsOpen Dependency context by role: Development toolsOpen Topocode internal modules: @topo/story

    Referenced interfaces: ResolvedStoryDocument: authored document, document path, repository root, source revision/dirty state, and resolved anchors. StoryArtifact: HTML kind/media type, contents, optional backend assets, and renderer identity/provenance (including original/adapted output hashes when supplied). These interfaces belong to @topo/story; diagram-core consumes/returns them. The legacy RenderInput / Artifact declarations in types.ts are not re-exported by diagram-core's package-root index.

    packages/story/package.json:1-33
    {
  "name": "@topo/story",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "files": [
    "dist",
    "story.schema.json"
  ],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./story.schema.json": "./story.schema.json"
  },
  "scripts": {
    "build": "tsc -b",
    "typecheck": "tsc -b --pretty false",
    "test": "vitest run"
  },
  "dependencies": {
    "@topo/languages": "workspace:*",
    "typescript-compiler-api": "npm:typescript@6.0.3"
  },
  "devDependencies": {
    "@types/node": "^22",
    "ajv": "8.17.1",
    "typescript": "^7.0.2",
    "vite": "8.2.2",
    "vitest": "^5.0.0"
  }
}
    packages/story/src/index.ts:76-85
    export interface ResolvedStoryDocument {
  readonly document: StoryDocument;
  readonly documentPath: string;
  readonly repositoryRoot: string;
  readonly source: {
    readonly revision: string;
    readonly dirty: boolean;
  };
  readonly anchors: readonly ResolvedSourceAnchor[];
}
    packages/story/src/index.ts:87-100
    export interface StoryArtifact {
  readonly kind: "html";
  readonly mediaType: "text/html";
  readonly contents: string;
  readonly assets?: Readonly<Record<string, string>>;
  readonly renderer: {
    readonly name: string;
    readonly pin: string;
    readonly sha256?: string;
    readonly sourceOutputSha256?: string;
    readonly outputSha256?: string;
    readonly adaptation?: string;
  };
}
  • Architecture batch API

    renderArchitectureStories(stories, options?) -> StoryArtifact[] renderArchitectureStoryBatch(stories, options?) -> Generator<StoryArtifact> Input: readonly ResolvedStoryDocument[]. The optional sourceEvidence mode is native or wrapper. These entry points accept Architecture stories; they are not general-purpose batching APIs for every diagram family.

    packages/diagram-core/src/index.ts:1569-1572
    export function renderArchitectureStories(
  stories: readonly ResolvedStoryDocument[],
  options: { readonly sourceEvidence?: "native" | "wrapper" } = {},
): StoryArtifact[] {
    packages/diagram-core/src/index.ts:1576-1579
    export function* renderArchitectureStoryBatch(
  stories: readonly ResolvedStoryDocument[],
  options: { readonly sourceEvidence?: "native" | "wrapper" } = {},
): Generator<StoryArtifact> {
  • @topo/diagram-core Open @topo/cli: public surface: @topo/diagram-coreOpen Dependency context by role: RenderingOpen Dependency context by role: Archify and GraphvizOpen Dependency context by role: Build, test, docsOpen Dependency context by role: Development toolsOpen Topocode internal modules: @topo/diagram-core

    The root exports renderStory, renderArchitectureStories, renderArchitectureStoryBatch, verifyArchifyIntegrity, the ArchifyIntegrity type, architectureComponentWidth, storyNodeIds, and CORE_THEME_SCRIPT. It references @topo/story for contracts, @jdylanmc/topo-archify as its native peer, and @viz-js/viz as a dependency. No bin entry is declared. Private helpers such as specification builders, renderGraphviz and viewer adaptation routines are intentionally not presented as public APIs.

    packages/diagram-core/package.json:1-34
    {
  "name": "@topo/diagram-core",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "files": [
    "dist",
    "archify-pin.json",
    "LICENSE",
    "THIRD_PARTY_NOTICES.md"
  ],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -b",
    "typecheck": "tsc -b --pretty false",
    "test": "tsc -b && node --test test/*.test.mjs"
  },
  "dependencies": {
    "@topo/story": "workspace:*",
    "@viz-js/viz": "3.30.0"
  },
  "peerDependencies": {
    "@jdylanmc/topo-archify": "0.1.0"
  },
  "devDependencies": {
    "@types/node": "^22",
    "typescript": "^7.0.2"
  }
}
    packages/diagram-core/src/index.ts:1629-1629
    export function renderStory(story: ResolvedStoryDocument): StoryArtifact | Promise<StoryArtifact> {
    packages/diagram-core/src/index.ts:1569-1572
    export function renderArchitectureStories(
  stories: readonly ResolvedStoryDocument[],
  options: { readonly sourceEvidence?: "native" | "wrapper" } = {},
): StoryArtifact[] {
    packages/diagram-core/src/index.ts:1576-1579
    export function* renderArchitectureStoryBatch(
  stories: readonly ResolvedStoryDocument[],
  options: { readonly sourceEvidence?: "native" | "wrapper" } = {},
): Generator<StoryArtifact> {
    packages/diagram-core/src/index.ts:483-487
    export function architectureComponentWidth(
  title: string,
  sublabel = "",
  finalTypography = false,
): number {
    packages/diagram-core/src/node-ids.ts:11-14
    export function storyNodeIds(
  document: StoryDocument,
  renderer: "archify" | "graphviz" = document.renderer ?? "archify",
): readonly (readonly [string, string])[] {
    packages/diagram-core/src/integrity.ts:6-6
    export function verifyArchifyIntegrity(): ArchifyIntegrity {
    packages/diagram-core/src/integrity.ts:4-4
    export type ArchifyIntegrity = RuntimeIntegrity;
    packages/diagram-core/src/index.ts:23-23
    export { CORE_THEME_SCRIPT } from "./theme.js";
  • Integrity API

    verifyArchifyIntegrity() -> ArchifyIntegrity. The root also re-exports the ArchifyIntegrity type, an alias of the renderer package's RuntimeIntegrity contract. This reports verified runtime identity/inventory; it does not certify the correctness of an authored architecture explanation.

    packages/diagram-core/src/integrity.ts:6-6
    export function verifyArchifyIntegrity(): ArchifyIntegrity {
    packages/diagram-core/src/integrity.ts:4-4
    export type ArchifyIntegrity = RuntimeIntegrity;
    packages/diagram-core/src/index.ts:26-29
    export {
  verifyArchifyIntegrity,
  type ArchifyIntegrity,
} from "./integrity.js";
  • @topo/cli Open @topo/cli: public surfaceOpen Dependency context by role: Build, test, docsOpen Dependency context by role: Development toolsOpen Topocode internal modules: @topo/cliOpen From idea to architecture: Topocode CLI

    The CLI manifest declares @topo/diagram-core as a runtime workspace dependency. This is the consumer boundary you drilled through—not an assertion that every CLI function directly calls a renderer. Click to return to the CLI's exposed surface.

    packages/cli/package.json:1-40
    {
  "name": "@topo/cli",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "bin": {
    "topo": "./dist/main.js"
  },
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -b && node ../../scripts/package-skills.mjs",
    "typecheck": "tsc -b --pretty false",
    "test": "vitest run --no-file-parallelism"
  },
  "dependencies": {
    "@topo/diagram-core": "workspace:*",
    "@topo/enrichment": "workspace:*",
    "@topo/graph": "workspace:*",
    "@topo/languages": "workspace:*",
    "@topo/modules": "workspace:*",
    "@topo/reports": "workspace:*",
    "@topo/scanner": "workspace:*",
    "@topo/schema": "workspace:*",
    "@topo/site": "workspace:*",
    "@topo/story": "workspace:*",
    "@topo/views": "workspace:*",
    "@topo/workspace": "workspace:*"
  },
  "devDependencies": {
    "@types/node": "^22.20.1",
    "typescript": "^7.0.2",
    "vite": "8.2.2",
    "vitest": "^5.0.0"
  }
}
  • Exported utilities

    architectureComponentWidth(title, sublabel?, finalTypography?) -> number. storyNodeIds(document, renderer?) -> readonly authored/native ID pairs. CORE_THEME_SCRIPT -> string. storyNodeIds keeps authored section IDs separate from native renderer identities. Archify uses stable component hashes for IDs outside its identifier syntax; Graphviz keeps authored IDs. Activation maps native IDs back to authored sections, and authored focus maps to native targets. Renderer metadata and edge endpoints keep native IDs. These are current root exports supporting integration and presentation. They are exposed helpers, not separate renderer backends or an invitation to depend on private implementation functions.

    packages/diagram-core/src/index.ts:483-487
    export function architectureComponentWidth(
  title: string,
  sublabel = "",
  finalTypography = false,
): number {
    packages/diagram-core/src/node-ids.ts:11-14
    export function storyNodeIds(
  document: StoryDocument,
  renderer: "archify" | "graphviz" = document.renderer ?? "archify",
): readonly (readonly [string, string])[] {
    packages/diagram-core/src/index.ts:23-23
    export { CORE_THEME_SCRIPT } from "./theme.js";
  • @viz-js/viz Open @topo/cli: public surface: @topo/diagram-coreOpen Dependency context by role: RenderingOpen Dependency context by role: Archify and GraphvizOpen Dependency context by role: Build, test, docsOpen Dependency context by role: Development toolsOpen Topocode internal modules: @topo/diagram-core

    Declared dependency: @viz-js/viz@3.30.0. It supplies Graphviz for explicitly selected technical workflows. It is not a silent fallback when native Archify rendering fails, and its artifacts have separate provenance.

    packages/diagram-core/package.json:1-34
    {
  "name": "@topo/diagram-core",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "files": [
    "dist",
    "archify-pin.json",
    "LICENSE",
    "THIRD_PARTY_NOTICES.md"
  ],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -b",
    "typecheck": "tsc -b --pretty false",
    "test": "tsc -b && node --test test/*.test.mjs"
  },
  "dependencies": {
    "@topo/story": "workspace:*",
    "@viz-js/viz": "3.30.0"
  },
  "peerDependencies": {
    "@jdylanmc/topo-archify": "0.1.0"
  },
  "devDependencies": {
    "@types/node": "^22",
    "typescript": "^7.0.2"
  }
}