@brett_lamy/docstream 1.16.2 → 1.18.0

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

@@ -86,6 +86,9 @@ export type {
 } from "./replay/ReplayPreview"
 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"
 export { StlViewer, isStlUrl, parseStl } from "./stl"

package/src/replay/ReplayFile.tsx

@@ -0,0 +1,39 @@
+import { useEffect, useRef, useState } from 'react';
+import { useAsset } from '../asset-resolver';
+import { ReplayPreview } from './ReplayPreview';
+import type { ReplayPlayerOptions } from './ReplayPlayer';
+
+export interface ReplayFileProps extends Omit<ReplayPlayerOptions, 'url'> {
+  /** The `.rrweb` file as written in the document; the host's asset resolver maps it to a loadable URL. */
+  url: string;
+}
+
+/**
+ * An rrweb recording file (a JSON event array, or `{ events }`), played in the replay browser frame.
+ * The URL goes through `AssetResolverProvider`, and the file is fetched only once the frame nears the
+ * viewport, so a page of recordings doesn't download them all up front.
+ */
+export function ReplayFile({ url, ...options }: ReplayFileProps) {
+  const src = useAsset(url);
+  const ref = useRef<HTMLDivElement>(null);
+  const [near, setNear] = useState(false);
+
+  useEffect(() => {
+    if (near) return;
+    const el = ref.current;
+    if (!el || typeof IntersectionObserver === 'undefined') return setNear(true);
+    const io = new IntersectionObserver((entries) => entries.some((e) => e.isIntersecting) && setNear(true), { rootMargin: '240px' });
+    io.observe(el);
+    return () => io.disconnect();
+  }, [near]);
+
+  if (!near || src === undefined) return <div ref={ref} className="docstream-asset-pending" data-slot="replay-file" aria-busy="true" />;
+  return <ReplayPreview source={{ kind: 'events-url', url: src }} chrome="browser" {...options} />;
+}
+
+const RRWEB = /\.rrweb(?:[?#]|$)/i;
+
+/** True for an rrweb recording file: a URL whose path ends in `.rrweb`. */
+export function isRrwebUrl(url: string): boolean {
+  return RRWEB.test(url.trim());
+}

package/src/replay/ReplayPlayer.tsx

@@ -294,11 +294,18 @@ export function ReplayPlayer({
 
 /* ── parts ───────────────────────────────────────────────────────────────────────── */
 
-export function BrowserBar({ href, trafficLights, loading }: { href: string; trafficLights: boolean; loading: boolean }) {
+/** Splits an address for the URL bar: the host, and the path + query + hash after it. */
+export function splitReplayAddress(href: string): { host: string; path: string } {
   const shown = href.replace(/^https?:\/\//, '')
-  const slash = shown.indexOf('/')
-  const host = slash < 0 ? shown : shown.slice(0, slash)
-  const path = slash < 0 ? '' : shown.slice(slash)
+  const cut = shown.search(/[/?#]/)
+  return cut < 0 ? { host: shown, path: '' } : { host: shown.slice(0, cut), path: shown.slice(cut) }
+}
+
+export function BrowserBar({ href, trafficLights, loading }: { href: string; trafficLights: boolean; loading: boolean }) {
+  const { host, path } = splitReplayAddress(href)
+  // Once the recording is past the site root, where it is (path, query, hash) is what matters:
+  // it leads and keeps its room, and the host dims and gives way first.
+  const primary = path && path !== '/' ? 'path' : 'host'
   return (
     <div data-slot="replay-preview-bar">
       {trafficLights ? (
@@ -310,9 +317,9 @@ export function BrowserBar({ href, trafficLights, loading }: { href: string; tra
         <span data-slot="replay-preview-lock" aria-hidden="true">
           {loading ? <span data-slot="replay-preview-spinner" /> : <Lock size={10} strokeWidth={2.5} />}
         </span>
-        <span data-slot="replay-preview-url" title={href}>
-          <span>{host}</span>
-          <span>{path}</span>
+        <span data-slot="replay-preview-url" data-primary={primary} title={href}>
+          <span data-part="host">{host}</span>
+          {path ? <span data-part="path">{path}</span> : null}
         </span>
       </div>
       {trafficLights ? <span aria-hidden="true" data-slot="replay-preview-lights-spacer" /> : null}

package/src/replay/index.ts

@@ -18,4 +18,6 @@ export type { ReplayMarker, ReplayMarkerKind, ReplayMeta, ReplayPointerPoint, Re
 export { ReplayEventType, ReplayIncrementalSource, ReplayMouseInteraction } from './types';
 export type { ReplayEvent } from './types';
 export { isReplayQaUrl, normalizeReplayEmbedUrl } from './url';
+export { ReplayFile, isRrwebUrl } from './ReplayFile';
+export type { ReplayFileProps } from './ReplayFile';
 export { sanitizeReplayEvent } from './sanitize';

package/src/styles.css

@@ -443,6 +443,25 @@
   margin: 4px 0 6px;
 }
 
+/* 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 +1731,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;
@@ -3718,18 +3855,29 @@
   }
 
   :where([data-slot="replay-preview-url"]) {
+    display: flex;
     min-width: 0;
     overflow: hidden;
-    text-overflow: ellipsis;
     white-space: nowrap;
   }
 
-  :where([data-slot="replay-preview-url"] > :first-child) {
+  :where([data-slot="replay-preview-url"] > span) {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    color: var(--muted-foreground, #71717a);
+  }
+
+  /* The primary part is full strength; when space runs out the other one gives way first. */
+  :where([data-slot="replay-preview-url"][data-primary="host"] > [data-part="host"]),
+  :where([data-slot="replay-preview-url"][data-primary="path"] > [data-part="path"]) {
+    flex-shrink: 1;
     color: var(--foreground, #18181b);
   }
 
-  :where([data-slot="replay-preview-url"] > :last-child) {
-    color: var(--muted-foreground, #71717a);
+  :where([data-slot="replay-preview-url"][data-primary="host"] > [data-part="path"]),
+  :where([data-slot="replay-preview-url"][data-primary="path"] > [data-part="host"]) {
+    flex-shrink: 10000;
   }
 
   :where([data-slot="replay-preview-spinner"]) {

package/src/vite/index.ts

@@ -10,6 +10,11 @@ export interface DocstreamSourceMount {
   root: string
   /** Allow PUT requests to edit files in this mount. Defaults to true. */
   writable?: boolean
+  /**
+   * Reload the page after a PUT. Defaults to true. Turn it off for content files whose importers
+   * hot-update themselves (an editor autosaving Markdown), so a save doesn't reload the editor.
+   */
+  reloadOnWrite?: boolean
 }
 
 export interface DocstreamSourcesOptions {
@@ -22,6 +27,7 @@ interface ResolvedMount {
   name: string
   root: string
   writable: boolean
+  reloadOnWrite: boolean
 }
 
 const VIRTUAL_ID = "virtual:docstream-sources"
@@ -38,10 +44,14 @@ function requestUrl(request: IncomingMessage): URL {
   return new URL(request.url ?? "/", "http://docstream.local")
 }
 
-async function requestBody(request: IncomingMessage): Promise<string> {
+async function requestBytes(request: IncomingMessage): Promise<Buffer> {
   const chunks: Buffer[] = []
   for await (const chunk of request) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
-  return Buffer.concat(chunks).toString("utf8")
+  return Buffer.concat(chunks)
+}
+
+async function requestBody(request: IncomingMessage): Promise<string> {
+  return (await requestBytes(request)).toString("utf8")
 }
 
 function normalizeRelativePath(value: string): string {
@@ -113,10 +123,21 @@ function installMiddleware(server: ViteDevServer, apiBase: string, viteBase: str
         await fs.writeFile(absolutePath, parsed.content, "utf8")
         const stat = await fs.stat(absolutePath)
         server.watcher.add(absolutePath)
-        server.ws.send({ type: "full-reload", path: "*" })
+        if (mount.reloadOnWrite) server.ws.send({ type: "full-reload", path: "*" })
         return send(response, 200, JSON.stringify({ content: parsed.content, provenance: provenance(url, mount, relativePath, absolutePath, stat.mtimeMs) }))
       }
 
+      if (request.method === "POST") {
+        // Upload: create (or replace) a file with the raw request body, e.g. a dropped .rrweb recording.
+        if (!mount.writable) return send(response, 403, `Source mount ${mount.name} is read-only`, "text/plain; charset=utf-8")
+        const bytes = await requestBytes(request)
+        await fs.mkdir(path.dirname(absolutePath), { recursive: true })
+        await fs.writeFile(absolutePath, bytes)
+        const stat = await fs.stat(absolutePath)
+        server.watcher.add(absolutePath)
+        return send(response, 201, JSON.stringify({ size: stat.size, provenance: provenance(url, mount, relativePath, absolutePath, stat.mtimeMs) }))
+      }
+
       return send(response, 405, "Method not allowed", "text/plain; charset=utf-8")
     } catch (error) {
       const status = error && typeof error === "object" && "code" in error && (error as { code?: string }).code === "ENOENT" ? 404 : 400
@@ -129,6 +150,9 @@ function installMiddleware(server: ViteDevServer, apiBase: string, viteBase: str
  * Mount real source directories behind safe Vite dev-server endpoints.
  * Markdown references import live modules from these files, and editor writes
  * go back to disk so Vite's normal watcher/HMR pipeline remains authoritative.
+ *
+ * `GET {apiBase}/source?mount=&path=` reads a file, `PUT` (JSON `{ content }`) edits an existing one,
+ * and `POST` (raw body) creates or replaces one — uploads such as `.rrweb` recordings.
  */
 export function docstreamSources(options: DocstreamSourcesOptions): Plugin {
   const apiBase = `/${(options.apiBase ?? "/@docstream").replace(/^\/+|\/+$/g, "")}`
@@ -148,6 +172,7 @@ export function docstreamSources(options: DocstreamSourcesOptions): Plugin {
           name: mount.name,
           root: path.resolve(config.root, mount.root),
           writable: mount.writable !== false,
+          reloadOnWrite: mount.reloadOnWrite !== false,
         }
       })
     },