@brett_lamy/docstream 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "type": "module",
   "scripts": {
@@ -70,6 +70,7 @@
   },
   "dependencies": {
     "@brett_lamy/viz-engine": ">=0.2.0",
+    "framer-motion": "^13.1.1",
     "hast-util-to-html": "^9.0.5",
     "lowlight": "^3.3.0",
     "lucide-react": "^1.17.0",

package/src/docs/DocsRenderer.tsx

@@ -1,4 +1,5 @@
 import { useState, type ReactNode } from "react"
+import { LayoutGroup, motion } from "framer-motion"
 import {
   AlertTriangle,
   CheckCircle2,
@@ -92,18 +93,30 @@ function Tabs({ block, liveRenderer, sourceRenderer }: { block: Extract<Block, {
   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">
+      <LayoutGroup>
+        <div className="docs-tabs-header" role="tablist" aria-label="Content tabs">
+          {block.tabs.map((t, i) => (
+            <button
+              key={i}
+              type="button"
+              role="tab"
+              aria-selected={i === active}
+              className={i === active ? "docs-tab-active" : ""}
+              onClick={() => setActive(i)}
+            >
+              {i === active ? (
+                <motion.span
+                  className="docs-tab-indicator"
+                  layoutId="docs-tab-indicator"
+                  transition={{ type: "spring", bounce: 0.2, duration: 0.6 }}
+                />
+              ) : null}
+              <span className="docs-tab-label">{t.title}</span>
+            </button>
+          ))}
+        </div>
+      </LayoutGroup>
+      <div className="docs-tabs-body" role="tabpanel">
         <Blocks blocks={block.tabs[active]?.children ?? []} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
       </div>
     </div>

package/src/docs/reference.tsx

@@ -1,17 +1,99 @@
-import { createContext, useContext, useState, type ReactNode } from "react"
-import { AtSign, Globe, Hash } from "lucide-react"
+import { createContext, useContext, useId, useState, type ReactNode } from "react"
+import { ArrowUpRight, AtSign, Globe, Hash } from "lucide-react"
 
 import type { CitationDef, ReferenceNode } from "../gitbook/ast"
 
+export interface CitationPreview {
+  title?: string
+  description?: string
+  image?: string
+  siteName?: string
+  favicon?: string
+}
+
+export type CitationPreviewResolver = (citation: ReferenceNode) => CitationPreview | null | Promise<CitationPreview | null>
+
 export interface DocstreamRefContextValue {
   /** Called when a mention/tag chip (or a citation, if it has no url) is clicked. */
   onReferenceClick?: (ref: ReferenceNode) => void
   /** Full override for chip rendering; return null to fall back to the default. */
   renderReference?: (ref: ReferenceNode) => ReactNode | null
+  /** Resolves Open Graph-style metadata when a linked citation is hovered or focused. */
+  resolveCitationPreview?: CitationPreviewResolver
 }
 
 export const DocstreamRefContext = createContext<DocstreamRefContextValue>({})
 
+const previewCaches = new WeakMap<CitationPreviewResolver, Map<string, Promise<CitationPreview | null>>>()
+
+function resolvePreview(resolver: CitationPreviewResolver, citation: ReferenceNode) {
+  let cache = previewCaches.get(resolver)
+  if (!cache) {
+    cache = new Map()
+    previewCaches.set(resolver, cache)
+  }
+  const key = citation.url ?? citation.id
+  let request = cache.get(key)
+  if (!request) {
+    request = Promise.resolve(resolver(citation)).catch(() => null)
+    cache.set(key, request)
+  }
+  return request
+}
+
+function CitationHoverCard({ node }: { node: ReferenceNode }) {
+  const { onReferenceClick, resolveCitationPreview } = useContext(DocstreamRefContext)
+  const [preview, setPreview] = useState<CitationPreview | null>(null)
+  const [imageFailed, setImageFailed] = useState(false)
+  const [requested, setRequested] = useState(false)
+  const cardId = useId()
+  const host = node.url ? hostnameOf(node.url) : null
+
+  const requestPreview = () => {
+    if (!resolveCitationPreview || requested) return
+    setRequested(true)
+    void resolvePreview(resolveCitationPreview, node).then((value) => setPreview(value))
+  }
+
+  const title = preview?.title ?? node.label ?? host ?? node.url
+  const siteName = preview?.siteName ?? host
+  const favicon = preview?.favicon ?? (host ? `https://www.google.com/s2/favicons?sz=32&domain=${host}` : undefined)
+
+  return (
+    <span className="docs-cite-wrap" onMouseEnter={requestPreview} onFocus={requestPreview}>
+      <a
+        className="docs-cite"
+        href={node.url}
+        target="_blank"
+        rel="noreferrer"
+        aria-describedby={cardId}
+        onClick={() => onReferenceClick?.(node)}
+      >
+        {node.id}
+      </a>
+      <span className="docs-cite-card" id={cardId} role="tooltip">
+        {preview?.image && !imageFailed ? (
+          <span className="docs-cite-card-image-wrap">
+            <img className="docs-cite-card-image" src={preview.image} alt="" onError={() => setImageFailed(true)} />
+          </span>
+        ) : null}
+        <span className="docs-cite-card-body">
+          <span className="docs-cite-card-source">
+            {favicon ? <img className="docs-cite-card-favicon" src={favicon} alt="" /> : <Globe className="docs-cite-card-favicon" />}
+            <span>{siteName}</span>
+          </span>
+          <span className="docs-cite-card-title">{title}</span>
+          {preview?.description ? <span className="docs-cite-card-description">{preview.description}</span> : null}
+          <span className="docs-cite-card-url">
+            {node.url}
+            <ArrowUpRight aria-hidden="true" />
+          </span>
+        </span>
+      </span>
+    </span>
+  )
+}
+
 export function InlineReference({ node }: { node: ReferenceNode }) {
   const { onReferenceClick, renderReference } = useContext(DocstreamRefContext)
   const custom = renderReference?.(node)
@@ -20,18 +102,7 @@ export function InlineReference({ node }: { node: ReferenceNode }) {
   if (node.kind === "citation") {
     // Citations default to linking their source; hosts can still observe clicks.
     if (node.url) {
-      return (
-        <a
-          className="docs-cite"
-          href={node.url}
-          target="_blank"
-          rel="noreferrer"
-          title={node.label ?? node.url}
-          onClick={() => onReferenceClick?.(node)}
-        >
-          {node.id}
-        </a>
-      )
+      return <CitationHoverCard node={node} />
     }
     // Definition missing (not yet streamed, or standalone parseInline call).
     return (

package/src/gitbook/parse.ts

@@ -225,7 +225,7 @@ export function parseBlocks(lines: string[]): Block[] {
         const code = inner.find((b) => b.type === "code")
         if (code && code.type === "code") {
           code.title = tag.attrs.title ?? null
-          code.lineNumbers = tag.attrs.lineNumbers === "true"
+          code.lineNumbers = booleanAttr(tag.attrs, "lineNumbers") ?? booleanAttr(tag.attrs, "showLineNumbers") ?? true
           code.live = tag.attrs.live === "true"
           code.entry = tag.attrs.entry ?? null
           blocks.push(code)
@@ -428,13 +428,14 @@ export function parseBlocks(lines: string[]): Block[] {
     }
 
     // fenced code (``` or ~~~)
-    const fence = trimmed.match(/^(`{3,}|~{3,})(\S*)\s*$/)
+    const fence = trimmed.match(/^(`{3,}|~{3,})([^\s`]*)?(?:\s+(.*?))?\s*$/)
     if (fence) {
       flushParagraph()
       const marker = fence[1][0]
+      const attrs = parseAttrs(fence[3])
       const code: string[] = []
       i++
-      while (i < lines.length && !lines[i].trim().startsWith(marker.repeat(3))) {
+      while (i < lines.length && !lines[i].trim().startsWith(fence[1])) {
         code.push(lines[i])
         i++
       }
@@ -442,9 +443,11 @@ export function parseBlocks(lines: string[]): Block[] {
       blocks.push({
         type: "code",
         language: fence[2] || null,
-        title: null,
-        lineNumbers: false,
+        title: attrs.title ?? null,
+        lineNumbers: booleanAttr(attrs, "lineNumbers") ?? booleanAttr(attrs, "showLineNumbers") ?? true,
         code: code.join("\n"),
+        ...(booleanAttr(attrs, "live") === undefined ? {} : { live: booleanAttr(attrs, "live") }),
+        ...(attrs.entry ? { entry: attrs.entry } : {}),
       })
       continue
     }
@@ -459,7 +462,7 @@ export function parseBlocks(lines: string[]): Block[] {
         code.push(lines[i].slice(4))
         i++
       }
-      blocks.push({ type: "code", language: null, title: null, lineNumbers: false, code: code.join("\n") })
+      blocks.push({ type: "code", language: null, title: null, lineNumbers: true, code: code.join("\n") })
       continue
     }
 

package/src/gitbook/serialize.ts

@@ -34,18 +34,14 @@ function serializeBlock(b: Block): string {
     }
 
     case "code": {
-      const fence = "```" + (b.language ?? "")
-      const body = `${fence}\n${b.code}\n\`\`\``
-      if (b.title || b.lineNumbers || b.live || b.entry) {
-        const attrs = [
-          b.title ? ` title="${b.title}"` : "",
-          b.lineNumbers ? ` lineNumbers="true"` : "",
-          b.live ? ` live="true"` : "",
-          b.entry ? ` entry="${b.entry}"` : "",
-        ].join("")
-        return `{% code${attrs} %}\n${body}\n{% endcode %}`
-      }
-      return body
+      const attrs = [
+        b.title ? `title="${b.title}"` : "",
+        !b.lineNumbers ? `lineNumbers="false"` : "",
+        b.live ? `live="true"` : "",
+        b.entry ? `entry="${b.entry}"` : "",
+      ].filter(Boolean)
+      const info = [b.language ?? "", ...attrs].filter(Boolean).join(" ")
+      return `\`\`\`${info}\n${b.code}\n\`\`\``
     }
 
     case "hint":

package/src/index.ts

@@ -3,7 +3,7 @@ export type { PlaygroundStreamdownProps as GitbookStreamdownProps } from "./play
 export { DocsRenderer, MarkdownContent } from "./docs/DocsRenderer"
 export type { LivePreviewProps, LivePreviewRenderer, SourceReferenceRenderer } from "./docs/DocsRenderer"
 export { CitationSources, DocstreamRefContext, InlineReference } from "./docs/reference"
-export type { DocstreamRefContextValue } from "./docs/reference"
+export type { CitationPreview, CitationPreviewResolver, DocstreamRefContextValue } from "./docs/reference"
 export { ReplayEmbed, ReplayPreview } from "./replay"
 export type {
   ReplayEventsSource,

package/src/streamdown.tsx

@@ -5,7 +5,7 @@ import { parseMarkdown, trimPartialInlineToken } from "./gitbook/parse"
 // Re-exported so markdown-only consumers of ./streamdown can wire chip
 // click handling without importing the heavy root entry.
 export { CitationSources, DocstreamRefContext, InlineReference } from "./docs/reference"
-export type { DocstreamRefContextValue } from "./docs/reference"
+export type { CitationPreview, CitationPreviewResolver, DocstreamRefContextValue } from "./docs/reference"
 
 export interface GitbookStreamdownProps {
   children?: string

package/src/styles.css

@@ -176,6 +176,7 @@
 
 .docs-hint {
   display: flex;
+  align-items: center;
   gap: 12px;
   padding: 14px 16px;
   border-radius: 12px;
@@ -186,7 +187,6 @@
   width: 18px;
   height: 18px;
   flex-shrink: 0;
-  margin-top: 3px;
 }
 
 .docs-hint > div {
@@ -194,6 +194,14 @@
   min-width: 0;
 }
 
+.docs-hint > div > :first-child {
+  margin-top: 0;
+}
+
+.docs-hint > div > :last-child {
+  margin-bottom: 0;
+}
+
 .docs-hint-info {
   border-color: var(--gb-info-border);
   background: var(--gb-info-bg);
@@ -234,31 +242,77 @@
   border: 1px solid var(--gb-border);
   border-radius: 12px;
   overflow: hidden;
+  background: var(--gb-panel);
 }
 
 .docs-tabs-header {
   display: flex;
+  width: fit-content;
+  max-width: calc(100% - 24px);
   gap: 2px;
-  padding: 6px 8px 0;
+  margin: 10px auto 0;
+  padding: 4px;
+  overflow-x: auto;
+  border: 1px solid var(--gb-border);
+  border-radius: 999px;
   background: var(--gb-muted);
-  border-bottom: 1px solid var(--gb-border);
 }
 
 .docs-tabs-header button {
+  position: relative;
+  z-index: 0;
+  flex: 0 0 auto;
+  border: 0;
+  border-radius: 999px;
   padding: 7px 14px;
+  background: transparent;
+  font: inherit;
   font-size: 13.5px;
-  border-radius: 8px 8px 0 0;
+  line-height: 1.25;
   color: var(--gb-muted-foreground);
+  cursor: pointer;
+  -webkit-tap-highlight-color: transparent;
+  transition: color 160ms ease;
 }
 
 .docs-tabs-header .docs-tab-active {
-  background: var(--background, #ffffff);
-  color: var(--foreground, #18181b);
-  font-weight: 500;
+  color: var(--gb-panel-foreground);
+  font-weight: 600;
+}
+
+.docs-tabs-header button:hover:not(.docs-tab-active) {
+  color: var(--gb-panel-foreground);
+}
+
+.docs-tabs-header button:focus-visible {
+  outline: 2px solid var(--gb-primary);
+  outline-offset: 2px;
+}
+
+.docs-tab-indicator {
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  border: 1px solid var(--gb-border);
+  border-radius: inherit;
+  background: var(--gb-panel);
+  box-shadow: 0 1px 2px rgba(15, 23, 42, 0.08), 0 1px 6px rgba(15, 23, 42, 0.06);
+}
+
+.docs-tab-label {
+  position: relative;
 }
 
 .docs-tabs-body {
+  margin-top: 10px;
   padding: 14px 16px;
+  border-top: 1px solid var(--gb-border);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .docs-tabs-header button {
+    transition: none;
+  }
 }
 
 .docs-expandable {
@@ -996,6 +1050,12 @@
   color: var(--gb-accent-foreground);
 }
 
+.docs-cite-wrap {
+  position: relative;
+  display: inline-block;
+  vertical-align: super;
+}
+
 .docs-cite {
   display: inline-block;
   padding: 1px 5px;
@@ -1005,7 +1065,7 @@
   font-size: 10px;
   font-weight: 700;
   line-height: 1.4;
-  vertical-align: super;
+  vertical-align: baseline;
   text-decoration: none !important;
   cursor: pointer;
 }
@@ -1014,6 +1074,121 @@
   background: rgba(59, 130, 246, 0.22);
 }
 
+.docs-cite:focus-visible {
+  outline: 2px solid var(--gb-info);
+  outline-offset: 2px;
+}
+
+.docs-cite-card {
+  position: absolute;
+  top: calc(100% + 10px);
+  left: 50%;
+  z-index: 50;
+  display: block;
+  width: min(320px, calc(100vw - 32px));
+  overflow: hidden;
+  border: 1px solid var(--gb-border);
+  border-radius: 12px;
+  color: var(--gb-panel-foreground);
+  background: var(--gb-panel);
+  box-shadow: 0 12px 32px rgba(15, 23, 42, 0.16), 0 2px 8px rgba(15, 23, 42, 0.08);
+  opacity: 0;
+  visibility: hidden;
+  transform: translate(-50%, -4px);
+  transition: opacity 120ms ease, transform 120ms ease, visibility 120ms;
+  pointer-events: none;
+  text-align: left;
+  white-space: normal;
+}
+
+.docs-cite-wrap:hover .docs-cite-card,
+.docs-cite-wrap:focus-within .docs-cite-card {
+  opacity: 1;
+  visibility: visible;
+  transform: translate(-50%, 0);
+}
+
+.docs-cite-card-image-wrap {
+  display: block;
+  aspect-ratio: 1.91 / 1;
+  overflow: hidden;
+  border-bottom: 1px solid var(--gb-border);
+  background: var(--gb-muted);
+}
+
+.docs-cite-card-image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.docs-cite-card-body {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 14px 13px;
+}
+
+.docs-cite-card-source,
+.docs-cite-card-url {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  color: var(--gb-muted-foreground);
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 1.35;
+}
+
+.docs-cite-card-favicon {
+  width: 14px;
+  height: 14px;
+  flex: 0 0 auto;
+  border-radius: 3px;
+}
+
+.docs-cite-card-title {
+  display: -webkit-box;
+  overflow: hidden;
+  color: var(--gb-panel-foreground);
+  font-size: 14px;
+  font-weight: 650;
+  line-height: 1.35;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}
+
+.docs-cite-card-description {
+  display: -webkit-box;
+  overflow: hidden;
+  color: var(--gb-muted-foreground);
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 1.45;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 3;
+}
+
+.docs-cite-card-url {
+  margin-top: 2px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.docs-cite-card-url svg {
+  width: 12px;
+  height: 12px;
+  flex: 0 0 auto;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .docs-cite-card {
+    transition: none;
+  }
+}
+
 .docs-sources {
   display: flex;
   flex-wrap: wrap;