@brett_lamy/docstream 0.5.7 → 0.6.1

package/README.md

@@ -32,6 +32,10 @@ Import the package CSS once near your app entrypoint:
 import "@brett_lamy/docstream/styles.css"
 ```
 
+The stylesheet provides heading hierarchy and consistent spacing for the
+`DocsRenderer`, `MarkdownContent`, and streaming render paths. Host CSS can
+override those defaults through the normal cascade.
+
 If your TypeScript app checks CSS side-effect imports, include Vite's standard environment declaration or an equivalent CSS module declaration:
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "0.5.7",
+  "version": "0.6.1",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "publishConfig": {
     "access": "public"

package/src/docs/DocsRenderer.tsx

@@ -376,7 +376,11 @@ function isReactLanguage(language: string | null): boolean {
 
 function Blocks({ blocks, inline, liveRenderer, sourceRenderer }: { blocks: Block[]; inline?: boolean } & Renderers) {
   return (
-    <div className={inline ? "docs-blocks-inline" : undefined} style={inline ? { display: "inline" } : undefined}>
+    <div
+      data-docstream-blocks=""
+      className={inline ? "docs-blocks-inline" : undefined}
+      style={inline ? { display: "inline" } : undefined}
+    >
       {blocks.map((b, i) => (
         <BlockView key={i} block={b} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
       ))}

package/src/docs/reference.tsx

@@ -1,5 +1,5 @@
 import { createContext, useContext, useId, useState, type ReactNode } from "react"
-import { ArrowUpRight, AtSign, Globe, Hash } from "lucide-react"
+import { ArrowUpRight, AtSign, FolderGit2, Globe, Hash } from "lucide-react"
 
 import type { CitationDef, ReferenceNode } from "../gitbook/ast"
 
@@ -112,7 +112,7 @@ export function InlineReference({ node }: { node: ReferenceNode }) {
     )
   }
 
-  const Icon = node.kind === "mention" ? AtSign : Hash
+  const Icon = node.kind === "mention" ? AtSign : node.kind === "codebase" ? FolderGit2 : Hash
   return (
     <button
       type="button"

package/src/gitbook/ast.ts

@@ -23,7 +23,7 @@ export interface InlineImageNode {
   link?: string
 }
 
-export type ReferenceKind = "mention" | "tag" | "citation"
+export type ReferenceKind = "mention" | "tag" | "codebase" | "citation"
 
 /**
  * Inline reference chip: `@mention`, `#tag`, or footnote-style citation `[^id]`.

package/src/gitbook/inline.ts

@@ -10,8 +10,13 @@ export const refDefinitions = new Map<string, string>()
 // parseMarkdown and consumed here to resolve [^id] markers.
 export const footnoteDefinitions = new Map<string, { url: string; label?: string }>()
 
-// @mention / #tag body: letter/underscore start, then word chars, dots, dashes.
+// @mention / #tag / $codebase body: letter/underscore start, then word chars, dots,
+// dashes. Codebase ids may also carry `/` (`$org/repo`). A letter start keeps prices
+// like $5 plain text.
 const REFERENCE_BODY_RE = /^[@#]([A-Za-z_][\w.-]*)/
+const CODEBASE_BODY_RE = /^\$([A-Za-z_][\w.\/-]*)/
+const SIGIL_KIND = { "@": "mention", "#": "tag", $: "codebase" } as const
+const KIND_SIGIL = { mention: "@", tag: "#", codebase: "$" } as const
 // Chips are only recognized at start-of-input or after whitespace/open brackets,
 // so brett@replay.io and C# stay plain text.
 const isReferenceBoundary = (prev: string | undefined) =>
@@ -131,14 +136,14 @@ export function parseInline(src: string, marks: Marks = {}): Inline[] {
       continue
     }
 
-    // @mention / #tag chips, only at a word boundary
-    if ((rest[0] === "@" || rest[0] === "#") && isReferenceBoundary(src[i - 1])) {
-      const m = rest.match(REFERENCE_BODY_RE)
+    // @mention / #tag / $codebase chips, only at a word boundary
+    if ((rest[0] === "@" || rest[0] === "#" || rest[0] === "$") && isReferenceBoundary(src[i - 1])) {
+      const m = rest.match(rest[0] === "$" ? CODEBASE_BODY_RE : REFERENCE_BODY_RE)
       if (m) {
-        const id = m[1].replace(/[.-]+$/, "")
+        const id = m[1].replace(/[./-]+$/, "")
         if (id) {
           flush()
-          out.push({ type: "reference", kind: rest[0] === "@" ? "mention" : "tag", id })
+          out.push({ type: "reference", kind: SIGIL_KIND[rest[0] as "@" | "#" | "$"], id })
           i += 1 + id.length
           continue
         }
@@ -200,14 +205,14 @@ export function parseInline(src: string, marks: Marks = {}): Inline[] {
 const escapeText = (t: string) =>
   t
     .replace(/([*_~`[\]\\])/g, "\\$1")
-    // Escape @/# only at a chip boundary so emails/C# survive untouched.
+    // Escape @/#/$ only at a chip boundary so emails/C#/$5 survive untouched.
     // Note: node-local — a boundary formed across adjacent inline nodes
     // (previous node ending in whitespace) is not caught; rare, accepted.
-    .replace(/(^|[\s([{])([@#])(?=[A-Za-z_])/g, "$1\\$2")
+    .replace(/(^|[\s([{])([@#$])(?=[A-Za-z_])/g, "$1\\$2")
 
 export function serializeReference(n: ReferenceNode): string {
   if (n.kind === "citation") return `[^${n.id}]`
-  return `${n.kind === "mention" ? "@" : "#"}${n.id}`
+  return `${KIND_SIGIL[n.kind]}${n.id}`
 }
 
 function serializeImage(n: InlineImageNode): string {

package/src/styles.css

@@ -68,44 +68,87 @@
   white-space: pre-wrap;
 }
 
+:is([data-docstream], .docs-article) {
+  color: var(--foreground, #18181b);
+  line-height: 1.65;
+  font-size: 15.5px;
+}
+
 .docs-article {
   max-width: 760px;
   margin: 0 auto;
   padding: 48px 32px 120px;
-  line-height: 1.65;
-  font-size: 15.5px;
 }
 
-.docs-article > div > * + * {
-  margin-top: 0.85em;
+:is([data-docstream], .docs-article) [data-docstream-blocks] > * {
+  margin-block: 0;
+}
+
+:is([data-docstream], .docs-article) [data-docstream-blocks] > * + * {
+  margin-block-start: 0.9em;
+}
+
+:is([data-docstream], .docs-article) :is(h1, h2, h3, h4, h5, h6) {
+  color: inherit;
+  display: block;
+  font-family: inherit;
+  font-weight: 650;
+  line-height: 1.25;
+  margin-block: 1.6em 0.45em;
+  text-wrap: pretty;
+}
+
+:is([data-docstream], .docs-article) [data-docstream-blocks] > :is(h1, h2, h3, h4, h5, h6) {
+  margin-block-start: 1.6em;
 }
 
-.docs-article h1 {
+:is([data-docstream], .docs-article) [data-docstream-blocks] > :first-child:is(h1, h2, h3, h4, h5, h6) {
+  margin-block-start: 0;
+}
+
+:is([data-docstream], .docs-article) h1 {
   font-size: 2.2em;
   font-weight: 700;
-  margin-top: 0.6em;
 }
 
-.docs-article h2 {
+:is([data-docstream], .docs-article) h2 {
   font-size: 1.5em;
-  font-weight: 650;
-  margin-top: 1.4em;
+  font-weight: 675;
   padding-bottom: 0.2em;
   border-bottom: 1px solid var(--border, #e4e4e7);
 }
 
-.docs-article h3 {
+:is([data-docstream], .docs-article) h3 {
   font-size: 1.2em;
   font-weight: 600;
-  margin-top: 1.1em;
 }
 
-.docs-article a {
+:is([data-docstream], .docs-article) h4 {
+  font-size: 1.08em;
+  font-weight: 600;
+}
+
+:is([data-docstream], .docs-article) h5 {
+  font-size: 1em;
+  font-weight: 600;
+}
+
+:is([data-docstream], .docs-article) h6 {
+  font-size: 0.92em;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+}
+
+:is([data-docstream], .docs-article) p {
+  margin-block: 0;
+}
+
+:is([data-docstream], .docs-article) a {
   color: var(--gb-primary);
   text-decoration: underline;
 }
 
-.docs-article code {
+:is([data-docstream], .docs-article) code {
   background: var(--gb-muted);
   border-radius: 4px;
   padding: 0.15em 0.35em;
@@ -113,12 +156,12 @@
   font-family: ui-monospace, Menlo, monospace;
 }
 
-.docs-article ul {
+:is([data-docstream], .docs-article) ul {
   list-style: disc;
   padding-left: 1.5em;
 }
 
-.docs-article ol {
+:is([data-docstream], .docs-article) ol {
   list-style: decimal;
   padding-left: 1.5em;
 }
@@ -148,24 +191,24 @@
   margin: 0;
 }
 
-.docs-article blockquote {
+:is([data-docstream], .docs-article) blockquote {
   border-left: 3px solid var(--gb-border);
   padding-left: 1em;
   color: var(--gb-muted-foreground);
 }
 
-.docs-article hr {
+:is([data-docstream], .docs-article) hr {
   border: none;
   border-top: 1px solid var(--gb-border);
   margin: 2em 0;
 }
 
-.docs-article figure img {
+:is([data-docstream], .docs-article) figure img {
   border-radius: 12px;
   max-width: 100%;
 }
 
-.docs-article figcaption {
+:is([data-docstream], .docs-article) figcaption {
   text-align: center;
   font-size: 13px;
   color: var(--gb-muted-foreground);
@@ -1073,6 +1116,16 @@
   color: var(--gb-accent-foreground);
 }
 
+.docs-ref-codebase {
+  border: 1px solid rgba(34, 197, 94, 0.45);
+  background: rgba(34, 197, 94, 0.1);
+  color: rgb(74, 222, 128);
+}
+
+.docs-ref-codebase:hover {
+  background: rgba(34, 197, 94, 0.18);
+}
+
 .docs-cite-wrap {
   position: relative;
   display: inline-block;