@brett_lamy/docstream 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@brett_lamy/docstream",
+  "version": "0.1.0",
+  "description": "GitBook-aware readonly markdown and AI stream renderer.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./styles.css": "./src/styles.css"
+  },
+  "dependencies": {
+    "hast-util-to-html": "^9.0.5",
+    "lowlight": "^3.3.0",
+    "lucide-react": "^1.17.0",
+    "mermaid": "^11.15.0",
+    "streamdown": "^2.5.0",
+    "yaml": "^2.9.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/src/assets.ts

@@ -0,0 +1,20 @@
+// Resolves repo-relative image paths (e.g. "readme-assets/logo.svg") against
+// the raw.githubusercontent.com URL of the file being edited. The AST keeps
+// the original relative src; only rendering resolves it.
+
+let assetBase: string | null = null
+
+export function setAssetBase(repo: string | null, branch: string | null, filePath: string | null) {
+  if (!repo || !branch || !filePath) {
+    assetBase = null
+    return
+  }
+  const dir = filePath.includes("/") ? filePath.slice(0, filePath.lastIndexOf("/") + 1) : ""
+  assetBase = `https://raw.githubusercontent.com/${repo}/${branch}/${dir}`
+}
+
+export function resolveAsset(src: string): string {
+  if (!src || /^(https?:|data:|blob:)/i.test(src)) return src
+  if (!assetBase) return src
+  return assetBase + src.replace(/^\.\//, "")
+}

package/src/docs/DocsRenderer.tsx

@@ -0,0 +1,311 @@
+import { useState, type ReactNode } from "react"
+import {
+  AlertTriangle,
+  CheckCircle2,
+  ChevronRight,
+  File,
+  Info,
+  XCircle,
+} from "lucide-react"
+
+import type { Block, DocumentNode, Inline } from "../gitbook/ast"
+import { resolveAsset } from "../assets"
+import { parseMarkdown } from "../gitbook/parse"
+import { OpenApiOperation } from "../openapi/OpenApiOperation"
+import { Mermaid } from "./Mermaid"
+import { HighlightedCode } from "./HighlightedCode"
+
+function InlineText({ nodes }: { nodes: Inline[] }) {
+  return (
+    <>
+      {nodes.map((n, i) => {
+        if (n.type === "image") {
+          const img = (
+            <img
+              src={resolveAsset(n.src)}
+              alt={n.alt ?? ""}
+              className="docs-inline-img"
+              style={{ width: n.width, height: n.height }}
+            />
+          )
+          return n.link ? (
+            <a key={i} href={n.link} target="_blank" rel="noreferrer" className="docs-inline-img-link">
+              {img}
+            </a>
+          ) : (
+            <span key={i}>{img}</span>
+          )
+        }
+        let el: ReactNode = n.text
+        if (n.code) el = <code>{el}</code>
+        if (n.bold) el = <strong>{el}</strong>
+        if (n.italic) el = <em>{el}</em>
+        if (n.strike) el = <s>{el}</s>
+        if (n.link)
+          el = (
+            <a href={n.link} target="_blank" rel="noreferrer">
+              {el}
+            </a>
+          )
+        return <span key={i}>{el}</span>
+      })}
+    </>
+  )
+}
+
+const HINT_ICONS = {
+  info: Info,
+  success: CheckCircle2,
+  warning: AlertTriangle,
+  danger: XCircle,
+}
+
+function embedSrc(url: string): string | null {
+  const yt = url.match(/(?:youtube\.com\/watch\?v=|youtu\.be\/)([\w-]+)/)
+  return yt ? `https://www.youtube.com/embed/${yt[1]}` : null
+}
+
+function Tabs({ block }: { block: Extract<Block, { type: "tabs" }> }) {
+  const [active, setActive] = useState(0)
+  return (
+    <div className="docs-tabs">
+      <div className="docs-tabs-header">
+        {block.tabs.map((t, i) => (
+          <button
+            key={i}
+            className={i === active ? "docs-tab-active" : ""}
+            onClick={() => setActive(i)}
+          >
+            {t.title}
+          </button>
+        ))}
+      </div>
+      <div className="docs-tabs-body">
+        <Blocks blocks={block.tabs[active]?.children ?? []} />
+      </div>
+    </div>
+  )
+}
+
+function BlockView({ block }: { block: Block }) {
+  switch (block.type) {
+    case "paragraph":
+      return (
+        <p>
+          <InlineText nodes={block.children} />
+        </p>
+      )
+    case "heading": {
+      const Tag = `h${block.level}` as const
+      return (
+        <Tag>
+          <InlineText nodes={block.children} />
+        </Tag>
+      )
+    }
+    case "code":
+      if (block.language === "mermaid") return <Mermaid code={block.code} />
+      return (
+        <div className="docs-code">
+          {(block.title || block.language) && (
+            <div className="docs-code-header">
+              <span>{block.title}</span>
+              <span className="docs-code-lang">{block.language}</span>
+            </div>
+          )}
+          <pre className={block.lineNumbers ? "docs-code-numbered" : ""}>
+            <HighlightedCode
+              code={block.code}
+              language={block.language}
+              lineNumbers={block.lineNumbers}
+            />
+          </pre>
+        </div>
+      )
+    case "hint": {
+      const Icon = HINT_ICONS[block.style] ?? Info
+      return (
+        <div className={`docs-hint docs-hint-${block.style}`}>
+          <Icon className="docs-hint-icon" />
+          <div>
+            <Blocks blocks={block.children} />
+          </div>
+        </div>
+      )
+    }
+    case "tabs":
+      return <Tabs block={block} />
+    case "expandable":
+      return (
+        <details className="docs-expandable">
+          <summary>{block.summary}</summary>
+          <div className="docs-expandable-body">
+            <Blocks blocks={block.children} />
+          </div>
+        </details>
+      )
+    case "stepper":
+      return (
+        <div className="docs-stepper">
+          {block.steps.map((s, i) => (
+            <div key={i} className="docs-step">
+              <div className="docs-step-rail">
+                <div className="docs-step-badge">{i + 1}</div>
+                {i < block.steps.length - 1 && <div className="docs-step-line" />}
+              </div>
+              <div className="docs-step-main">
+                {s.title && <div className="docs-step-title">{s.title}</div>}
+                <Blocks blocks={s.children} />
+              </div>
+            </div>
+          ))}
+        </div>
+      )
+    case "embed": {
+      const src = embedSrc(block.url)
+      return src ? (
+        <iframe className="docs-embed" src={src} title={block.url} allowFullScreen />
+      ) : (
+        <a className="docs-content-ref" href={block.url} target="_blank" rel="noreferrer">
+          <File className="size-4" /> {block.url}
+        </a>
+      )
+    }
+    case "content-ref":
+      return (
+        <a className="docs-content-ref" href={block.url}>
+          <File className="size-4" />
+          <span>
+            <InlineText nodes={block.children} />
+          </span>
+          <ChevronRight className="size-4 ml-auto" />
+        </a>
+      )
+    case "columns":
+      return (
+        <div className="docs-columns">
+          {block.columns.map((c, i) => (
+            <div key={i} className="docs-column">
+              <Blocks blocks={c.children} />
+            </div>
+          ))}
+        </div>
+      )
+    case "figure":
+      return (
+        <figure className="docs-figure">
+          {block.src && <img src={resolveAsset(block.src)} alt={block.alt} />}
+          {block.caption && <figcaption>{block.caption}</figcaption>}
+        </figure>
+      )
+    case "list": {
+      const Tag = block.ordered ? "ol" : "ul"
+      return (
+        <Tag className={block.task ? "docs-tasklist" : undefined}>
+          {block.items.map((item, i) => (
+            <li key={i}>
+              {block.task && <input type="checkbox" checked={!!item.checked} readOnly />}
+              <Blocks blocks={item.children} inline />
+            </li>
+          ))}
+        </Tag>
+      )
+    }
+    case "blockquote":
+      return (
+        <blockquote>
+          <Blocks blocks={block.children} />
+        </blockquote>
+      )
+    case "divider":
+      return <hr />
+    case "table":
+      if (block.view === "cards") {
+        const cards = block.rows.length ? block.rows : [block.header]
+        return (
+          <div className="docs-cards">
+            {cards.map((row, i) => (
+              <div key={i} className="docs-card">
+                {row.map((cell, j) => (
+                  <div key={j} className={j === 0 ? "docs-card-title" : "docs-card-body"}>
+                    <InlineText nodes={cell} />
+                  </div>
+                ))}
+              </div>
+            ))}
+          </div>
+        )
+      }
+      return (
+        <table className="docs-table">
+          <thead>
+            <tr>
+              {block.header.map((cell, i) => (
+                <th key={i}>
+                  <InlineText nodes={cell} />
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {block.rows.map((row, i) => (
+              <tr key={i}>
+                {row.map((cell, j) => (
+                  <td key={j}>
+                    <InlineText nodes={cell} />
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )
+    case "math":
+      return <pre className="docs-math">{block.formula}</pre>
+    case "updates":
+      return (
+        <div className="docs-updates">
+          {block.updates.map((u, i) => (
+            <div key={i} className="docs-update">
+              <div className="docs-update-date">{u.date}</div>
+              <div className="docs-update-body">
+                <Blocks blocks={u.children} />
+              </div>
+            </div>
+          ))}
+        </div>
+      )
+    case "openapi-operation":
+      return (
+        <OpenApiOperation
+          specUrl={block.specUrl}
+          path={block.path}
+          method={block.method || "get"}
+        />
+      )
+  }
+}
+
+function Blocks({ blocks, inline }: { blocks: Block[]; inline?: boolean }) {
+  return (
+    <div className={inline ? "docs-blocks-inline" : undefined} style={inline ? { display: "inline" } : undefined}>
+      {blocks.map((b, i) => (
+        <BlockView key={i} block={b} />
+      ))}
+    </div>
+  )
+}
+
+// Renders a markdown string inline — used for embedded markdown like
+// OpenAPI descriptions, which can themselves contain GitBook blocks.
+export function MarkdownContent({ markdown }: { markdown: string }) {
+  return <Blocks blocks={parseMarkdown(markdown).children} />
+}
+
+export function DocsRenderer({ doc }: { doc: DocumentNode }) {
+  return (
+    <article className="docs-article">
+      <Blocks blocks={doc.children} />
+    </article>
+  )
+}

package/src/docs/HighlightedCode.tsx

@@ -0,0 +1,71 @@
+import { useMemo } from "react"
+import { common, createLowlight } from "lowlight"
+import { toHtml } from "hast-util-to-html"
+
+const lowlight = createLowlight(common)
+
+const LANGUAGE_ALIASES: Record<string, string> = {
+  js: "javascript",
+  jsx: "javascript",
+  sh: "bash",
+  shell: "bash",
+  ts: "typescript",
+  tsx: "typescript",
+  yml: "yaml",
+}
+
+function normalizeLanguage(language: string | null) {
+  if (!language) return null
+  const normalized = language.toLowerCase()
+  return LANGUAGE_ALIASES[normalized] ?? normalized
+}
+
+function highlightedHtml(code: string, language: string | null) {
+  const normalized = normalizeLanguage(language)
+  if (normalized && lowlight.registered(normalized)) {
+    try {
+      return toHtml(lowlight.highlight(normalized, code))
+    } catch {
+      /* fall through to plain */
+    }
+  }
+  return null
+}
+
+export function HighlightedCode({
+  code,
+  language,
+  lineNumbers = false,
+}: {
+  code: string
+  language: string | null
+  lineNumbers?: boolean
+}) {
+  const lines = useMemo(() => code.split("\n"), [code])
+  const html = useMemo(() => {
+    if (lineNumbers) {
+      return lines.map((line) => highlightedHtml(line || " ", language))
+    }
+    return highlightedHtml(code, language)
+  }, [code, language, lineNumbers, lines])
+
+  if (lineNumbers) {
+    return (
+      <code className="hljs">
+        {(html as Array<string | null>).map((lineHtml, index) => (
+          <span key={index} className="docs-code-line">
+            <span className="docs-code-lineno">{index + 1}</span>
+            {lineHtml === null ? (
+              <span>{lines[index]}</span>
+            ) : (
+              <span dangerouslySetInnerHTML={{ __html: lineHtml }} />
+            )}
+          </span>
+        ))}
+      </code>
+    )
+  }
+
+  if (html === null) return <code>{code}</code>
+  return <code className="hljs" dangerouslySetInnerHTML={{ __html: html as string }} />
+}

package/src/docs/Mermaid.tsx

@@ -0,0 +1,37 @@
+import { useEffect, useRef, useState } from "react"
+
+let seq = 0
+
+export function Mermaid({ code }: { code: string }) {
+  const [svg, setSvg] = useState<string | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const idRef = useRef(`mermaid-${++seq}`)
+
+  useEffect(() => {
+    let cancelled = false
+    import("mermaid")
+      .then(async ({ default: mermaid }) => {
+        mermaid.initialize({ startOnLoad: false, securityLevel: "strict" })
+        const { svg } = await mermaid.render(idRef.current, code)
+        if (!cancelled) setSvg(svg)
+      })
+      .catch((e) => {
+        if (!cancelled) setError(String(e.message ?? e))
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [code])
+
+  if (error) {
+    return (
+      <pre className="docs-mermaid-error">
+        mermaid error: {error}
+        {"\n"}
+        {code}
+      </pre>
+    )
+  }
+  if (!svg) return <div className="docs-mermaid">Rendering diagram…</div>
+  return <div className="docs-mermaid" dangerouslySetInnerHTML={{ __html: svg }} />
+}

package/src/gitbook/ast.ts

@@ -0,0 +1,194 @@
+// AST for GitBook-flavored markdown. This is the single source of truth that
+// the parser, serializer, TipTap converters, and docs renderer all share.
+
+export type HintStyle = "info" | "success" | "warning" | "danger"
+
+export interface TextNode {
+  type: "text"
+  text: string
+  bold?: boolean
+  italic?: boolean
+  strike?: boolean
+  code?: boolean
+  link?: string
+}
+
+/** Inline HTML image, optionally wrapped in a link — GitHub README badge style. */
+export interface InlineImageNode {
+  type: "image"
+  src: string
+  alt?: string
+  width?: string
+  height?: string
+  link?: string
+}
+
+export type Inline = TextNode | InlineImageNode
+
+export interface ParagraphNode {
+  type: "paragraph"
+  children: Inline[]
+}
+
+export interface HeadingNode {
+  type: "heading"
+  level: 1 | 2 | 3 | 4 | 5 | 6
+  children: Inline[]
+}
+
+export interface CodeBlockNode {
+  type: "code"
+  language: string | null
+  title: string | null
+  lineNumbers: boolean
+  code: string
+}
+
+export interface HintNode {
+  type: "hint"
+  style: HintStyle
+  children: Block[]
+}
+
+export interface TabNode {
+  type: "tab"
+  title: string
+  children: Block[]
+}
+
+export interface TabsNode {
+  type: "tabs"
+  tabs: TabNode[]
+}
+
+export interface ExpandableNode {
+  type: "expandable"
+  summary: string
+  children: Block[]
+}
+
+export interface StepNode {
+  type: "step"
+  title: string
+  children: Block[]
+}
+
+export interface StepperNode {
+  type: "stepper"
+  steps: StepNode[]
+}
+
+export interface EmbedNode {
+  type: "embed"
+  url: string
+}
+
+export interface ContentRefNode {
+  type: "content-ref"
+  url: string
+  children: Inline[]
+}
+
+export interface ColumnNode {
+  type: "column"
+  children: Block[]
+}
+
+export interface ColumnsNode {
+  type: "columns"
+  columns: ColumnNode[]
+}
+
+export interface FigureNode {
+  type: "figure"
+  src: string
+  alt: string
+  caption: string
+}
+
+export interface ListItemNode {
+  type: "listItem"
+  children: Block[]
+  checked?: boolean // present only in task lists
+}
+
+export interface ListNode {
+  type: "list"
+  ordered: boolean
+  task: boolean
+  items: ListItemNode[]
+}
+
+export interface BlockquoteNode {
+  type: "blockquote"
+  children: Block[]
+}
+
+export interface DividerNode {
+  type: "divider"
+}
+
+export interface TableNode {
+  type: "table"
+  header: Inline[][]
+  rows: Inline[][][]
+  /** GitBook table view, e.g. "cards" for <table data-view="cards"> */
+  view?: string
+}
+
+export interface UpdateNode {
+  type: "update"
+  date: string
+  children: Block[]
+}
+
+export interface UpdatesNode {
+  type: "updates"
+  format: string | null
+  updates: UpdateNode[]
+}
+
+export interface OpenApiOperationNode {
+  type: "openapi-operation"
+  spec: string
+  path: string
+  method: string
+  specUrl: string
+  label: string
+}
+
+export interface MathNode {
+  type: "math"
+  formula: string
+}
+
+export type Block =
+  | ParagraphNode
+  | HeadingNode
+  | CodeBlockNode
+  | HintNode
+  | TabsNode
+  | ExpandableNode
+  | StepperNode
+  | EmbedNode
+  | ContentRefNode
+  | ColumnsNode
+  | FigureNode
+  | ListNode
+  | BlockquoteNode
+  | DividerNode
+  | TableNode
+  | MathNode
+  | UpdatesNode
+  | OpenApiOperationNode
+
+export interface DocumentNode {
+  type: "doc"
+  children: Block[]
+}
+
+export const text = (t: string, marks: Partial<Omit<TextNode, "type" | "text">> = {}): TextNode => ({
+  type: "text",
+  text: t,
+  ...marks,
+})