Wiki Design System (JS Bundle)

• AppShellProps
• SiteHeaderProps
• GraphViewerProps
• MermaidViewerProps
• ProseProps
• CodeBlockProps
• SourceRefProps
• Window

The wiki bundle is framework-free by design: a generated page is plain semantic HTML that the Go generator emits, and all interactivity lives in a single JavaScript file, internal/wiki/design/bundle.js, that "enhances" that HTML in the browser. The contract between the two halves is documented in internal/wiki/design/index.d.ts, which declares the DOM markup each component expects (as *Props interfaces) and the window.Astrolabe API the bundle installs Window. Nothing in this file is type-checked or shipped — it exists so the generator, the theme, and human readers agree on the shapes involved.

The bundle is vendored from an "Astrolabe" design-system artifact and embedded into every generated site: designFS bundles tokens.css, bundle.css, bundle.js, the favicon and fonts, and writeAssets copies them into assets/astrolabe/ for plain-HTML sites while the Astro theme stages the same files from the same source designFS. This is what lets Wiki Bundle & Pages emit static markup that still behaves like a modern docs app, and what lets Astro Theme & Site Rendering reuse the identical assets.

How it works

The bootstrapping path is enhance(scope): after a page loads (or after dynamically injected content, such as a graph detail panel), it finds each component by its marker class or attribute and mounts the matching enhancer — .al-shell gets the app shell wiring, .al-prose gets typography enhancements, .al-code figures get line numbers and copy buttons, [data-al-theme] elements get theme selectors, and figure.al-diagram[data-mermaid] gets the diagram viewer enhance. The same object also exposes icon and the two-tone brand mark used by the header. Because everything hangs off window.Astrolabe, WebMCP Integration can drive the same components on behalf of a reader's AI agent.

AppShell and SiteHeader define the page skeleton. AppShellProps documents the grid — header.al-header, nav.al-nav, main > article.al-article.al-prose + aside.al-toc plus a .al-scrim — and AppShell.mount wires the narrow-screen drawer, nav, ToC and code blocks inside it AppShellProps. SiteHeader is the sticky top bar holding the brand, breadcrumb, version selector, theme selector and a repository link SiteHeaderProps.

Prose, CodeBlock and SourceRef shape the article content the generator writes. .al-prose provides the typography for page bodies, with Prose.mount adding heading ids, anchors and table wrappers ProseProps. Code is emitted pre-highlighted — .tok-* spans inside per-line elements — so CodeBlock.mount only needs to add optional line numbers, highlighted-line markers, a source ref and a copy button CodeBlockProps. Source references are pinned to commit SHAs, never branch names: GitRef carries an optional path and line range plus the mandatory sha and a broken flag GitRef, and SourceRef turns one into an inline link to a file, line range or commit at the configured host SourceRefProps. The related collapsible "Relevant source files" block is SourceListProps SourceListProps.

MermaidViewer renders diagrams from Mermaid source with pan, zoom, a source toggle, copy and fullscreen. It requires a host-provided window.mermaid (11.x) rather than bundling its own copy MermaidViewerProps. Its theming is notable: mermaidTheme maps every diagram color to a CSS custom property from the token sheet — surfaces, inks, borders, plus the viz-1…viz-5 palette — and flips darkMode based on the current data-theme, so diagrams re-theme instantly when the reader changes theme mermaidTheme.

GraphViewer renders the knowledge graph with a force layout, distinguishing node kinds by colour and shape (so the graph stays readable for colour-blind readers), with search, focus-on-select, and a detail panel whose links reuse SourceRef GraphViewerProps. Mounting returns { select, fit } so the search box and keyboard handlers can drive the same selection state the detail panel reflects.

All interactive viewers share infrastructure at the top of the bundle: a panZoom helper providing wheel-zoom (only when Ctrl/Meta is held, so page scrolling wins outside fullscreen), pointer-drag, arrow-key panning and fit() to center content at a capped zoom panZoom, plus fullscreenToggle for the scrim-and-Escape fullscreen mode. ThemeSelector persists the choice under astrolabe:theme, resolves "system" against prefers-color-scheme and contrast media queries, and dispatches an astrolabe:themechange event that diagram re-rendering listens to.

Relationships

flowchart TD
    Gen["internal/wiki Writer (generated HTML)"] -->|"emits semantic markup (.al-*, data-al-*)"| Bundle
    Bundle["window.Astrolabe (bundle.js)"] --> AppShell
    Bundle --> SiteHeader
    Bundle --> Prose
    Bundle --> CodeBlock
    Bundle --> MermaidViewer
    Bundle --> GraphViewer
    Bundle --> SourceRef
    Assets["internal/wiki designFS embed"] -->|"writeAssets → assets/astrolabe/"| Bundle
    Theme["theme/src/lib/bundle.ts readIndex / readVersion"] -->|"stages same assets"| Bundle
    WebMCP["internal/wiki/webmcp webmcp.js"] -->|"drives"| Bundle
    Tokens["tokens.css (compiled from tokens.json)"] -->|"CSS variables"| MermaidViewer

Reference

Generated by astrolabe from commit ecc180b3 (tag 0.4.0).