@brett_lamy/docstream 1.17.0 → 1.18.1

package/dist/styles.css

@@ -443,6 +443,34 @@
   margin: 4px 0 6px;
 }
 
+/* A step's body starts at the top, so a step without a title has its first line beside its number. */
+:is(.docs-step-main, .docs-step-media-body) > [data-docstream-blocks] > :first-child {
+  margin-top: 0;
+}
+
+.docs-step-main > [data-docstream-blocks]:first-child {
+  padding-top: 2px;
+}
+
+/* A step whose heading opens with a thumbnail: the image in its own column, the title and body beside it. */
+.docs-step-media {
+  display: flex;
+  align-items: flex-start;
+  gap: 16px;
+}
+
+.docs-step-media-body {
+  flex: 1;
+  min-width: 0;
+}
+
+@media (max-width: 560px) {
+  .docs-step-media {
+    flex-direction: column;
+    gap: 8px;
+  }
+}
+
 .docs-embed {
   width: 100%;
   aspect-ratio: 16 / 9;
@@ -1712,6 +1740,124 @@
   text-decoration: none !important;
 }
 
+/* Thumbnail images (`![alt](src "thumbnail: 0:39.8")`): a small frame with a badge; hover or focus
+   opens a card with the full image. First in a paragraph, the text runs beside it. */
+/* Float, not flex: the text keeps its own first line, so a list marker lines up with it. */
+.docs-media {
+  display: flow-root;
+}
+
+.docs-media > .docs-thumb,
+.docs-media > .docs-thumb-link {
+  float: left;
+  margin: 3px 14px 4px 0;
+}
+
+.docs-media-body {
+  display: block;
+  overflow: hidden;
+}
+
+.docs-thumb-link {
+  text-decoration: none !important;
+}
+
+.docs-thumb {
+  position: relative;
+  display: inline-block;
+  flex: none;
+  vertical-align: top;
+  border-radius: 10px;
+  outline: none;
+}
+
+.docs-thumb-frame {
+  position: relative;
+  display: block;
+  width: var(--docs-thumb-width, 168px);
+  aspect-ratio: 16 / 10;
+  overflow: hidden;
+  border: 1px solid var(--gb-border);
+  border-radius: 10px;
+  background: var(--gb-muted, #f4f4f5);
+  box-shadow: 0 1px 2px rgba(15, 23, 42, 0.06);
+  cursor: zoom-in;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+
+.docs-thumb-frame img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  object-position: top left;
+}
+
+.docs-thumb:hover .docs-thumb-frame,
+.docs-thumb:focus-visible .docs-thumb-frame {
+  border-color: var(--gb-panel-foreground, #18181b);
+  box-shadow: 0 0 0 2px var(--gb-border);
+}
+
+.docs-thumb-badge {
+  position: absolute;
+  right: 7px;
+  bottom: 7px;
+  padding: 2px 7px;
+  border-radius: 6px;
+  color: #f4f4f5;
+  background: rgba(39, 39, 42, 0.78);
+  font: 500 12px/1.4 var(--gb-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-variant-numeric: tabular-nums;
+  pointer-events: none;
+}
+
+.docs-thumb-card {
+  position: absolute;
+  top: calc(100% + 10px);
+  left: 0;
+  z-index: 60;
+  display: block;
+  width: min(var(--docs-thumb-card-width, 720px), calc(100vw - 32px));
+  overflow: hidden;
+  padding: 10px;
+  border: 1px solid var(--gb-border);
+  border-radius: 16px;
+  background: var(--gb-panel);
+  box-shadow: 0 18px 48px rgba(15, 23, 42, 0.22), 0 2px 8px rgba(15, 23, 42, 0.1);
+  opacity: 0;
+  visibility: hidden;
+  transform: translateY(-4px);
+  transition: opacity 0.14s ease, transform 0.14s ease, visibility 0.14s;
+  pointer-events: none;
+}
+
+.docs-thumb-card img {
+  display: block;
+  width: 100%;
+  height: auto;
+  border-radius: 8px;
+}
+
+.docs-thumb-card .docs-thumb-badge {
+  right: 18px;
+  bottom: 18px;
+  font-size: 14px;
+}
+
+.docs-thumb:hover .docs-thumb-card,
+.docs-thumb:focus-visible .docs-thumb-card {
+  opacity: 1;
+  visibility: visible;
+  transform: translateY(0);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .docs-thumb-card {
+    transition: none;
+  }
+}
+
 .oas {
   border: 1px solid var(--gb-border);
   border-radius: 12px;

package/package.json

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

package/src/docs/DocsRenderer.tsx

@@ -10,11 +10,11 @@ import {
   XCircle,
 } from "lucide-react"
 
-import type { Block, CodeBlockNode, CommandNode, DocumentNode, Inline, PackageManager, SourceRefNode } from "../gitbook/ast"
+import type { Block, CodeBlockNode, CommandNode, DocumentNode, Inline, PackageManager, SourceRefNode, StepNode } from "../gitbook/ast"
 import { PACKAGE_MANAGERS, packageManagerCommands } from "../gitbook/package-managers"
 import { slugify } from "../gitbook/outline"
 import { resolveAsset, useAsset } from "../assets"
-import { parseMarkdown } from "../gitbook/parse"
+import { parseBlocks, parseMarkdown } from "../gitbook/parse"
 import { serializeMarkdown } from "../gitbook/serialize"
 import { DocstreamDemoContext, DocstreamDemoRuntimeContext, DocstreamDemoVFSContext } from "../demo/context"
 import type { DemoVFS } from "../demo/vfs"
@@ -36,6 +36,7 @@ import { OpenApiOperation } from "../openapi/OpenApiOperation"
 import { Mermaid } from "./Mermaid"
 import { HighlightedCode } from "./HighlightedCode"
 import { CitationSources, InlineReference } from "./reference"
+import { ImageThumbnail, leadingThumbnail, thumbnailLabel } from "./ImageThumbnail"
 import { DocumentProperties } from "./DocumentProperties"
 import { TaskCheckbox, TaskStateChangeContext, type TaskStateChangeHandler } from "./TaskCheckbox"
 import { getTaskState } from "../gitbook/tasks"
@@ -103,6 +104,8 @@ function InlineText({ nodes }: { nodes: Inline[] }) {
           if (!emphasized && !n.link) return <InlineReference key={i} node={n} />
           el = <InlineReference node={n} />
         } else if (n.type === "image") {
+          const label = thumbnailLabel(n)
+          if (label !== null) return <ImageThumbnail key={i} image={n} label={label} />
           const img = (
             <AssetImg
               url={n.src}
@@ -334,12 +337,25 @@ function Tabs({ block, liveRenderer, sourceRenderer }: { block: Extract<Block, {
 function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & Renderers) {
   const onTaskStateChange = useContext(TaskStateChangeContext)
   switch (block.type) {
-    case "paragraph":
+    case "paragraph": {
+      // A paragraph that opens with a thumbnail sets its text beside it.
+      const lead = leadingThumbnail(block.children)
+      if (lead) {
+        return (
+          <p className="docs-media">
+            <ImageThumbnail image={lead.image} label={lead.label} />
+            <span className="docs-media-body">
+              <InlineText nodes={lead.rest} />
+            </span>
+          </p>
+        )
+      }
       return (
         <p>
           <InlineText nodes={block.children} />
         </p>
       )
+    }
     case "heading": {
       const Tag = `h${block.level}` as const
       return (
@@ -426,10 +442,7 @@ function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & R
                 <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} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
-              </div>
+              <StepMain step={s} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
             </div>
           ))}
         </div>
@@ -601,6 +614,40 @@ function isReactLanguage(language: string | null): boolean {
   return language === "jsx" || language === "tsx" || language === "react"
 }
 
+/**
+ * A step's title and body. A title heading that opens with a thumbnail image puts the image in a column
+ * of its own, with the title and the body beside it.
+ */
+function StepMain({ step, liveRenderer, sourceRenderer }: { step: StepNode } & Renderers) {
+  const lead = useMemo(() => {
+    if (!step.heading) return null
+    const [heading] = parseBlocks(step.heading.split("\n").filter((line) => line.trim()))
+    return heading?.type === "heading" ? leadingThumbnail(heading.children) : null
+  }, [step.heading])
+  const body = <Blocks blocks={step.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
+  if (!lead) {
+    return (
+      <div className="docs-step-main">
+        {step.title && <div className="docs-step-title">{step.title}</div>}
+        {body}
+      </div>
+    )
+  }
+  return (
+    <div className="docs-step-main docs-step-media">
+      <ImageThumbnail image={lead.image} label={lead.label} />
+      <div className="docs-step-media-body">
+        {step.title && (
+          <div className="docs-step-title">
+            <InlineText nodes={lead.rest} />
+          </div>
+        )}
+        {body}
+      </div>
+    </div>
+  )
+}
+
 function Blocks({ blocks, inline, liveRenderer, sourceRenderer }: { blocks: Block[]; inline?: boolean } & Renderers) {
   return (
     <div

package/src/docs/ImageThumbnail.tsx

@@ -0,0 +1,49 @@
+import { useId } from "react"
+import type { Inline, InlineImageNode } from "../gitbook/ast"
+import { useAsset } from "../asset-resolver"
+import { thumbnailLabel } from "../gitbook/thumbnail"
+
+export { thumbnailLabel }
+
+/** The paragraph's leading thumbnail (whitespace before it ignored) and the inlines after it. */
+export function leadingThumbnail(nodes: Inline[]): { image: InlineImageNode; label: string; rest: Inline[] } | null {
+  const at = nodes.findIndex((n) => !(n.type === "text" && !n.text.trim()))
+  const first = nodes[at]
+  if (!first || first.type !== "image") return null
+  const label = thumbnailLabel(first)
+  if (label === null) return null
+  const rest = nodes.slice(at + 1)
+  // Drop the space that separated the image from the text.
+  if (rest[0]?.type === "text") rest[0] = { ...rest[0], text: rest[0].text.replace(/^\s+/, "") }
+  return { image: first, label, rest }
+}
+
+/**
+ * A small framed image with an optional badge (a timestamp, say); hovering or focusing it opens a card
+ * with the full image. First in a paragraph or list item, the text runs beside it.
+ */
+export function ImageThumbnail({ image, label }: { image: InlineImageNode; label: string }) {
+  const src = useAsset(image.src)
+  const cardId = useId()
+  const alt = image.alt ?? ""
+  const badge = label ? <span className="docs-thumb-badge">{label}</span> : null
+  const thumb = (
+    <span className="docs-thumb" tabIndex={0} role="img" aria-label={alt || label || "Image"} aria-describedby={cardId}>
+      <span className="docs-thumb-frame">
+        <img src={src} alt="" loading="lazy" draggable={false} />
+        {badge}
+      </span>
+      <span className="docs-thumb-card" id={cardId} role="tooltip">
+        <img src={src} alt={alt} loading="lazy" />
+        {badge}
+      </span>
+    </span>
+  )
+  return image.link ? (
+    <a href={image.link} target="_blank" rel="noreferrer" className="docs-thumb-link">
+      {thumb}
+    </a>
+  ) : (
+    thumb
+  )
+}

package/src/gitbook/index.ts

@@ -12,3 +12,4 @@ export { PACKAGE_MANAGERS, packageManagerCommands } from "./package-managers"
 export { flattenBlocks, flattenForPlainMarkdown } from "./flatten"
 export { documentOutline, slugify } from "./outline"
 export type { OutlineEntry } from "./outline"
+export { stepTitleText, thumbnailLabel } from "./thumbnail"

package/src/gitbook/parse.ts

@@ -1,3 +1,4 @@
+import { stepTitleText } from "./thumbnail"
 import type {
   Block,
   CodeBlockNode,
@@ -1081,7 +1082,7 @@ function parseSteps(lines: string[]): { items: StepNode[]; end: number } {
     const heading = inner[0]?.type === "heading" ? inner[0] : undefined
     const step: StepNode = { type: "step", title, children: inner }
     if (heading) {
-      step.title = plainText(heading.children)
+      step.title = stepTitleText(heading.children)
       inner.shift()
       // The title heading as written (level, formatting, blank lines before it), where not `### title`.
       const written = body.slice(0, (heading.gap ?? 0) + (heading.setext ? 2 : 1)).join("\n")

package/src/gitbook/serialize.ts

@@ -1,3 +1,4 @@
+import { stepTitleText } from "./thumbnail"
 import type {
   Block,
   CitationDef,
@@ -94,7 +95,7 @@ function tagsFor(b: TaggedNode): [string, string] {
 function stepHeading(s: StepNode): string {
   if (s.heading !== undefined) {
     const again = parseBlocks(s.heading.split("\n"))
-    if (again.length === 1 && again[0].type === "heading" && plainText(again[0].children) === s.title) return s.heading
+    if (again.length === 1 && again[0].type === "heading" && stepTitleText(again[0].children) === s.title) return s.heading
   }
   return s.title ? `### ${s.title}` : ""
 }

package/src/gitbook/thumbnail.ts

@@ -0,0 +1,20 @@
+import type { Inline } from "./ast"
+import { plainText } from "./inline"
+
+const THUMBNAIL = /^thumbnail(?:\s*:\s*(.*))?$/i
+
+/**
+ * The badge of a thumbnail image, or `null` when the image isn't one. An image is a thumbnail when its
+ * Markdown title starts with `thumbnail`: `![Overview](shot.jpg "thumbnail")`, or with a badge,
+ * `![Overview](shot.jpg "thumbnail: 0:39.8")`. Elsewhere the title is just a tooltip.
+ */
+export function thumbnailLabel(node: Inline): string | null {
+  if (node.type !== "image" || !node.title) return null
+  const match = THUMBNAIL.exec(node.title.trim())
+  return match ? (match[1]?.trim() ?? "") : null
+}
+
+/** A step's title from its heading: the plain text, without thumbnail images (they show beside it). */
+export function stepTitleText(nodes: Inline[]): string {
+  return plainText(nodes.filter((n) => thumbnailLabel(n) === null)).trim()
+}

package/src/index.ts

@@ -87,6 +87,7 @@ export type {
 export type { ReplayEvent } from "./replay/types"
 export { isReplayQaUrl, normalizeReplayEmbedUrl } from "./replay/url"
 export { ReplayFile, isRrwebUrl } from "./replay/ReplayFile"
+export { ImageThumbnail, leadingThumbnail, thumbnailLabel } from "./docs/ImageThumbnail"
 export type { ReplayFileProps } from "./replay/ReplayFile"
 export { VideoEmbed } from "./video"
 export type { VideoEmbedProps } from "./video"

package/src/styles.css

@@ -443,6 +443,34 @@
   margin: 4px 0 6px;
 }
 
+/* A step's body starts at the top, so a step without a title has its first line beside its number. */
+:is(.docs-step-main, .docs-step-media-body) > [data-docstream-blocks] > :first-child {
+  margin-top: 0;
+}
+
+.docs-step-main > [data-docstream-blocks]:first-child {
+  padding-top: 2px;
+}
+
+/* A step whose heading opens with a thumbnail: the image in its own column, the title and body beside it. */
+.docs-step-media {
+  display: flex;
+  align-items: flex-start;
+  gap: 16px;
+}
+
+.docs-step-media-body {
+  flex: 1;
+  min-width: 0;
+}
+
+@media (max-width: 560px) {
+  .docs-step-media {
+    flex-direction: column;
+    gap: 8px;
+  }
+}
+
 .docs-embed {
   width: 100%;
   aspect-ratio: 16 / 9;
@@ -1712,6 +1740,124 @@
   text-decoration: none !important;
 }
 
+/* Thumbnail images (`![alt](src "thumbnail: 0:39.8")`): a small frame with a badge; hover or focus
+   opens a card with the full image. First in a paragraph, the text runs beside it. */
+/* Float, not flex: the text keeps its own first line, so a list marker lines up with it. */
+.docs-media {
+  display: flow-root;
+}
+
+.docs-media > .docs-thumb,
+.docs-media > .docs-thumb-link {
+  float: left;
+  margin: 3px 14px 4px 0;
+}
+
+.docs-media-body {
+  display: block;
+  overflow: hidden;
+}
+
+.docs-thumb-link {
+  text-decoration: none !important;
+}
+
+.docs-thumb {
+  position: relative;
+  display: inline-block;
+  flex: none;
+  vertical-align: top;
+  border-radius: 10px;
+  outline: none;
+}
+
+.docs-thumb-frame {
+  position: relative;
+  display: block;
+  width: var(--docs-thumb-width, 168px);
+  aspect-ratio: 16 / 10;
+  overflow: hidden;
+  border: 1px solid var(--gb-border);
+  border-radius: 10px;
+  background: var(--gb-muted, #f4f4f5);
+  box-shadow: 0 1px 2px rgba(15, 23, 42, 0.06);
+  cursor: zoom-in;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+
+.docs-thumb-frame img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  object-position: top left;
+}
+
+.docs-thumb:hover .docs-thumb-frame,
+.docs-thumb:focus-visible .docs-thumb-frame {
+  border-color: var(--gb-panel-foreground, #18181b);
+  box-shadow: 0 0 0 2px var(--gb-border);
+}
+
+.docs-thumb-badge {
+  position: absolute;
+  right: 7px;
+  bottom: 7px;
+  padding: 2px 7px;
+  border-radius: 6px;
+  color: #f4f4f5;
+  background: rgba(39, 39, 42, 0.78);
+  font: 500 12px/1.4 var(--gb-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-variant-numeric: tabular-nums;
+  pointer-events: none;
+}
+
+.docs-thumb-card {
+  position: absolute;
+  top: calc(100% + 10px);
+  left: 0;
+  z-index: 60;
+  display: block;
+  width: min(var(--docs-thumb-card-width, 720px), calc(100vw - 32px));
+  overflow: hidden;
+  padding: 10px;
+  border: 1px solid var(--gb-border);
+  border-radius: 16px;
+  background: var(--gb-panel);
+  box-shadow: 0 18px 48px rgba(15, 23, 42, 0.22), 0 2px 8px rgba(15, 23, 42, 0.1);
+  opacity: 0;
+  visibility: hidden;
+  transform: translateY(-4px);
+  transition: opacity 0.14s ease, transform 0.14s ease, visibility 0.14s;
+  pointer-events: none;
+}
+
+.docs-thumb-card img {
+  display: block;
+  width: 100%;
+  height: auto;
+  border-radius: 8px;
+}
+
+.docs-thumb-card .docs-thumb-badge {
+  right: 18px;
+  bottom: 18px;
+  font-size: 14px;
+}
+
+.docs-thumb:hover .docs-thumb-card,
+.docs-thumb:focus-visible .docs-thumb-card {
+  opacity: 1;
+  visibility: visible;
+  transform: translateY(0);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .docs-thumb-card {
+    transition: none;
+  }
+}
+
 .oas {
   border: 1px solid var(--gb-border);
   border-radius: 12px;