@tanishqkancharla/diffmap 0.2.0 → 0.4.0

package/README.md

@@ -75,16 +75,48 @@ import {
 | Fence info string                              | Viewer                                                                                            |
 | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | `mermaid`                                      | Beautiful Mermaid                                                                                 |
+| `services`                                     | Animated service diagram you can play or step through                                             |
 | `callstack` or `diff` containing `└──` / `├──` | Interactive stack rows, no file header                                                            |
 | `diff` or `diff:path` with a file path         | Pierre patch with Pierre’s file header                                                            |
 | `diff` with no path                            | Pierre patch, no file header                                                                      |
 | `changes` with a commit, range, or empty body  | Files changed card with a Review button; empty means uncommitted changes                          |
 | `start:end:path`                               | Pierre file excerpt with Pierre’s file header                                                     |
 | `html`                                         | Trusted HTML from this file. diffmap does not sanitize it. Only use it for local files you wrote. |
-| other langs                                    | Maui `CodeBlock`                                                                                  |
+| other langs                                    | Highlighted code with optional [line highlights and notes](#highlight-lines-and-add-notes)        |
 
 Fences keep whitespace. Use them for mermaid, call stacks, and diffs.
 
+### Highlight lines and add notes
+
+In a code fence, `{2,4-6}` after the language highlights those lines. Comment
+lines at the bottom of the fence add notes that show on hover or keyboard focus:
+
+````md
+```ts {2-3}
+function requestHandler(record: RecordInput) {
+  const error = validateInput(record);
+  if (error) return error;
+  return existingService(record);
+}
+// [!note validateInput] Returns an error when `name` is blank, otherwise undefined.
+// [!note L3] Early return, so storage never sees an invalid record.
+```
+````
+
+- `[!note L3]` or `[!note L3-L5]` notes a line range. Any other target is a
+  symbol, and the note covers every whole-word occurrence in the fence.
+- Start note lines with `//`, `#`, or `--`. The viewer removes them, so line
+  numbers count only the code above. Backticks in a note render as code.
+- A symbol that does not appear, overlapping line notes, or a line number
+  outside the fence is a parse error. A note line above other code stays code.
+
+Call stacks take the same highlights and notes, counting rows from the first.
+Write their notes with `#`. A symbol note matches the row text you see, not
+hidden references. Inside a linked row, symbol notes show on hover only; the
+row itself keeps keyboard focus.
+
+Run `npx @tanishqkancharla/diffmap fixtures/code-notes.md` for an example.
+
 ## MDC
 
 md4x Comark components map to the same views:
@@ -154,9 +186,17 @@ A `changes` fence shows a commit's files as a card. Each row shows the file name
 and +N −M. **Review** opens the Diff panel on all files; a row focuses that file.
 An empty body (or `working`) means uncommitted changes.
 
+Lines after the rev list the files to review, in order. The card shows those
+first and folds the rest under a dimmed **N other files** row that expands and
+collapses. Review opens the Diff panel in the same order. `serve` and `share`
+fail if a listed file is not changed in that commit. With no list, the card
+shows every file.
+
 ````md
 ```changes
 a1b2c3d
+src/request.ts
+src/validate.ts
 ```
 ````
 
@@ -170,9 +210,16 @@ Malformed references produce a parse error.
 
 On a GitHub-hosted spec, commit diffs come from the GitHub API. It returns patch
 hunks only, so only lines near changes are reachable, and the Diff button opens
-the pull request's full diff. `diffmap share` saves every referenced commit to a
-`diffmap-changes.json` file in the gist. Uncommitted references only work in a
-local viewer.
+the pull request's full diff.
+
+A shared gist is a snapshot taken when you run `diffmap share`. It saves every
+referenced commit and every `changes` card, including uncommitted ones, to
+`diffmap-changes.json`. It saves the current contents of every file that a file
+excerpt or a reference without a commit reads to `diffmap-files.json`. In the
+gist, those references open the saved file; symbols resolve to their first
+matching line, and Cmd-click definitions only work in a local viewer. Commit
+your work and point references at the commit before sharing, so the gist shows
+the diff instead of a bare file.
 
 Cmd-click (or Ctrl-click) a TypeScript or JavaScript symbol in the source panel
 to open its definition. Use Back to retrace navigation and return to the reference.
@@ -181,6 +228,62 @@ Resolution uses the workspace's TypeScript configuration and current files.
 Run `npx @tanishqkancharla/diffmap fixtures/annotations.md` for an example
 with commit references, multiple files, and unchanged context.
 
+## Animated service diagrams
+
+A `services` fence shows services, their state, and the events they send each
+other, then replays those events step by step. Readers press **Play**, step with
+the arrow buttons or ← and →, or click the progress bar to jump to a step.
+
+````md
+```services
+service Browser "login page"
+  state cookie = none
+service API "HTTP server" [[src/api.ts]]
+  > Receives every request and routes it to a service.
+  service Auth
+    state attempts = 0
+      > Failures since the last success. Five locks the account.
+
+step "The browser submits the form"
+  Browser -> API: POST /login
+step "The API asks Auth to verify"
+  API -> Auth: verify(alice) [[src/api.ts#login]]
+    > Sends the username and the password from the form.
+  Auth.attempts = 1
+    > Counted before the check, so a crash still counts as a failure.
+step "The API sets the session cookie"
+  API -> Browser: 200 Set-Cookie
+  Browser.cookie = sid=s_81f
+```
+````
+
+- `service <Name> "label"` declares a service. Indent a `service` line under
+  another to nest it. Names are unique within the diagram.
+- `state <key> = <value>` declares a value and its initial state. Indent it under
+  its service.
+- `step "caption"` starts a step at column 0. The caption is required: a
+  sentence that says what happens, shown under the controls. Indented lines
+  under it are `From -> To: label` events and `Service.key = value` updates.
+  Every event in a step travels at once, and the updates land when the events
+  arrive.
+- A `>` line adds text to the line above it. Indent it further than that line;
+  consecutive `>` lines join.
+  - Under a service or state, it is a description: the name gets a dotted
+    underline and the text shows in a tooltip on hover or focus.
+  - Under a step, it explains the step and shows under the caption.
+  - Under an event or update, it is a note for that step. Notes appear in a
+    column beside the diagram once the step's events land, each joined by a
+    line to its event label or state row.
+- `%%` starts a comment line.
+- Append `[[reference]]` to a `service` line or an event to link it to source.
+
+Services must be declared before the first step, and updates may only change
+declared state. [ELK](https://eclipse.dev/elk/) lays the services out left to
+right, or top to bottom when that fits the column better, and routes one
+connection between each pair of services that talk. A request and its reply
+share that connection. Indentation is significant, so `services` has no MDC form.
+See [the runnable examples](fixtures/services.md).
+
 ## Link Mermaid nodes and edges
 
 Inside a Mermaid fence, add `%% ref node:<id> [[reference]]` to link a node or

package/index.html

@@ -48,6 +48,12 @@
       })();
     </script>
     <title>diffmap</title>
+    <!-- A + over a −, like a diff. -->
+    <link
+      rel="icon"
+      type="image/svg+xml"
+      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%2318181b'/%3E%3Crect x='14.25' y='5.5' width='3.5' height='11' rx='1.75' fill='%233fb950'/%3E%3Crect x='10.5' y='9.25' width='11' height='3.5' rx='1.75' fill='%233fb950'/%3E%3Crect x='10.5' y='21.25' width='11' height='3.5' rx='1.75' fill='%23f85149'/%3E%3C/svg%3E"
+    />
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanishqkancharla/diffmap",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Serve a spec or code walkthrough as a local page",
   "license": "MIT",
   "author": "Tanishq Kancharla",
@@ -44,9 +44,10 @@
     "@pierre/diffs": "1.6.1",
     "@vitejs/plugin-react": "^6.1.1",
     "beautiful-mermaid": "^1.1.3",
+    "elkjs": "^0.11.1",
     "errore": "^0.14.1",
     "incur": "^0.4.20",
-    "maui": "npm:@tanishqkancharla/maui@0.0.47",
+    "maui": "npm:@tanishqkancharla/maui@0.0.62",
     "md4x": "^0.0.29",
     "motion": "^13.4.0",
     "purse-styles": "^0.2.3",

package/src/changes.ts

@@ -156,9 +156,30 @@ export type Changes = {
   files: ChangedFile[];
 };
 
+/**
+ * Splits files into the ones to review, in `review` order, and the rest in
+ * their original order. An empty `review` means every file is to be reviewed.
+ */
+export function orderForReview(files: ChangedFile[], review: string[]) {
+  if (review.length === 0) return { reviewed: files, other: [] };
+  const reviewed = review.flatMap(
+    (path) => files.find((file) => file.path === path) ?? [],
+  );
+  return {
+    reviewed,
+    other: files.filter((file) => !reviewed.includes(file)),
+  };
+}
+
 /** Gist file holding the changes a shared spec references, keyed by rev. */
 export const GIST_CHANGES_FILE = "diffmap-changes.json";
 
+/**
+ * Gist file holding the current contents of files a shared spec reads live,
+ * keyed by path: file excerpts and references without a commit.
+ */
+export const GIST_FILES_FILE = "diffmap-files.json";
+
 export type ChangesResponse = { changes?: Changes; error?: string };
 
 /** jsdiff's default lines of context around each change. */

package/src/codeNotes.ts

@@ -0,0 +1,123 @@
+export type CodeNote = {
+  target:
+    | { kind: "lines"; start: number; end: number }
+    | { kind: "symbol"; symbol: string };
+  text: string;
+};
+
+/** A symbol note's match on one line: `[start, end)` columns. */
+export type SymbolMatch = { start: number; end: number; note: CodeNote };
+
+const notePrefix = /^\s*(?:\/\/|#|--)\s*\[!note\b/;
+const notePattern = /^\s*(?:\/\/|#|--)\s*\[!note\s+([^\]]+?)\s*\]\s*(.*?)\s*$/;
+const linesPattern = /^L(\d+)(?:-L(\d+))?$/;
+const identifierChar = /[\w$]/;
+
+/**
+ * Splits trailing `// [!note target] text` lines off a code fence. Blank
+ * lines between notes are allowed; note-like lines above other code stay
+ * code, so fences that document this syntax render unchanged.
+ */
+export function parseCodeNotes(source: string) {
+  const lines = source.split("\n");
+  let end = lines.length;
+  while (
+    end > 0 &&
+    (lines[end - 1]!.trim() === "" || notePrefix.test(lines[end - 1]!))
+  )
+    end--;
+  const notes = lines.slice(end).flatMap((line) => {
+    if (line.trim() === "") return [];
+    const match = notePattern.exec(line);
+    if (match === null || match[2] === "")
+      return [{ target: { kind: "symbol", symbol: "" }, text: line } as const];
+    const lineRange = linesPattern.exec(match[1]!);
+    const target: CodeNote["target"] =
+      lineRange === null
+        ? { kind: "symbol", symbol: match[1]! }
+        : {
+            kind: "lines",
+            start: Number(lineRange[1]),
+            end: Number(lineRange[2] ?? lineRange[1]),
+          };
+    return [{ target, text: match[2]! }];
+  });
+  return { code: lines.slice(0, end).join("\n"), notes };
+}
+
+/** Why a fence's highlights or notes are invalid, or undefined. `lines` is the rendered text of each line or row. */
+export function notesProblem(fence: {
+  lines: string[];
+  highlights: number[];
+  notes: CodeNote[];
+}) {
+  const lines = fence.lines;
+  const highlight = fence.highlights.find((n) => n < 1 || n > lines.length);
+  if (highlight !== undefined)
+    return `Highlighted line ${highlight} is outside the ${lines.length}-line code fence`;
+  const covered = new Set<number>();
+  for (const note of fence.notes) {
+    const target = note.target;
+    if (target.kind === "symbol") {
+      if (target.symbol === "")
+        return `Invalid note "${note.text.trim()}". Use // [!note symbol] text or // [!note L3-L5] text`;
+      if (!lines.some((line) => symbolMatches(line, target.symbol).length > 0))
+        return `Note target "${target.symbol}" does not appear in its code fence`;
+      continue;
+    }
+    if (
+      target.start < 1 ||
+      target.end < target.start ||
+      target.end > lines.length
+    )
+      return `Note lines L${target.start}-L${target.end} are outside the ${lines.length}-line code fence`;
+    for (let n = target.start; n <= target.end; n++) {
+      if (covered.has(n)) return `Line notes overlap at line ${n}`;
+      covered.add(n);
+    }
+  }
+  return undefined;
+}
+
+/** Non-overlapping symbol note matches on one line, left to right. */
+export function lineSymbolMatches(line: string, notes: CodeNote[]) {
+  const matches = notes
+    .flatMap((note) =>
+      note.target.kind === "symbol"
+        ? symbolMatches(line, note.target.symbol).map((start) => ({
+            start,
+            end:
+              start +
+              (note.target.kind === "symbol" ? note.target.symbol.length : 0),
+            note,
+          }))
+        : [],
+    )
+    .toSorted((a, b) => a.start - b.start || b.end - a.end);
+  const kept: SymbolMatch[] = [];
+  for (const match of matches) {
+    const last = kept.at(-1);
+    if (last === undefined || match.start >= last.end) kept.push(match);
+  }
+  return kept;
+}
+
+/** Start columns of `symbol` in `line`, as a whole word where it starts or ends with an identifier character. */
+function symbolMatches(line: string, symbol: string) {
+  const starts: number[] = [];
+  for (
+    let at = line.indexOf(symbol);
+    at !== -1;
+    at = line.indexOf(symbol, at + 1)
+  ) {
+    const before = line[at - 1];
+    const after = line[at + symbol.length];
+    const wordStart = identifierChar.test(symbol[0]!);
+    const wordEnd = identifierChar.test(symbol.at(-1)!);
+    if (wordStart && before !== undefined && identifierChar.test(before))
+      continue;
+    if (wordEnd && after !== undefined && identifierChar.test(after)) continue;
+    starts.push(at);
+  }
+  return starts;
+}

package/src/errors.ts

@@ -20,6 +20,11 @@ export class DiffmapMermaidError extends errore.createTaggedError({
   message: "diffmap could not parse mermaid in $path ($where): $reason",
 }) {}
 
+export class DiffmapServicesError extends errore.createTaggedError({
+  name: "DiffmapServicesError",
+  message: "diffmap could not parse services in $path ($where): $reason",
+}) {}
+
 export class DiffmapParseError extends errore.createTaggedError({
   name: "DiffmapParseError",
   message: "diffmap could not parse markdown",

package/src/gist/GistApp.tsx

@@ -13,6 +13,7 @@ import { ViewerApp } from "../viewer/ViewerApp.tsx";
 import { loadGistMarkdown, type GistDocument } from "./fetchGist.ts";
 import { GistPinContext } from "./pin.ts";
 import { HostHome } from "../host/HostHome.tsx";
+import { HostFilesContext } from "../host/files.ts";
 import { GistLoading, GistStatus } from "./GistStatus.tsx";
 import {
   gistPath,
@@ -166,26 +167,28 @@ export function GistApp() {
         htmlUrl: view.gist.htmlUrl,
       }}
     >
-      <ChangesLoaderContext.Provider value={view.loadChanges}>
-        <ViewerApp
-          key={`${view.gist.id}:${view.file}`}
-          document={view.document}
-          mode="gist"
-          headerActions={
-            <GistHeader
-              gistId={view.gist.id}
-              htmlUrl={view.gist.htmlUrl}
-              files={view.gist.files}
-              current={view.file}
-              onSelect={(file) => {
-                const next = gistPath(view.gist.id, file);
-                window.history.pushState({}, "", next);
-                setRoute(parseGistPath(next));
-              }}
-            />
-          }
-        />
-      </ChangesLoaderContext.Provider>
+      <HostFilesContext.Provider value={view.gist.sourceFiles}>
+        <ChangesLoaderContext.Provider value={view.loadChanges}>
+          <ViewerApp
+            key={`${view.gist.id}:${view.file}`}
+            document={view.document}
+            mode="gist"
+            headerActions={
+              <GistHeader
+                gistId={view.gist.id}
+                htmlUrl={view.gist.htmlUrl}
+                files={view.gist.files}
+                current={view.file}
+                onSelect={(file) => {
+                  const next = gistPath(view.gist.id, file);
+                  window.history.pushState({}, "", next);
+                  setRoute(parseGistPath(next));
+                }}
+              />
+            }
+          />
+        </ChangesLoaderContext.Provider>
+      </HostFilesContext.Provider>
     </GistPinContext.Provider>
   );
 }

package/src/gist/fetchGist.ts

@@ -1,4 +1,10 @@
-import { GIST_CHANGES_FILE, type Changes, type Rev } from "../changes.ts";
+import {
+  GIST_CHANGES_FILE,
+  GIST_FILES_FILE,
+  type Changes,
+  type Rev,
+} from "../changes.ts";
+import type { HostFiles } from "../host/files.ts";
 import { githubGistUrl, markdownFileNames, pickMarkdownFile } from "./route.ts";
 
 export type GistMarkdownFile = {
@@ -11,8 +17,10 @@ export type GistDocument = {
   htmlUrl: string;
   files: GistMarkdownFile[];
   chosen: GistMarkdownFile;
-  /** Snapshot `diffmap share` saved for each commit the spec references. */
+  /** Snapshot `diffmap share` saved for each commit and changes card the spec references. */
   changes: Record<Rev, Changes>;
+  /** Files excerpts and references without a commit read, as they were when shared. */
+  sourceFiles: HostFiles;
 };
 
 export type GistLoadResult =
@@ -98,23 +106,21 @@ export async function loadGistMarkdown(
     return { status: "missing-file", htmlUrl, files };
   }
 
-  const snapshotFile = apiFiles[GIST_CHANGES_FILE];
-  const snapshot =
-    snapshotFile === undefined
-      ? "{}"
-      : await readGistFile(snapshotFile, signal);
-  if (snapshot instanceof Error) {
-    return { status: "error", message: snapshot.message };
+  // SAFETY: diffmap share writes this file from readDocumentChanges.
+  const changes = (await readSnapshot(apiFiles, GIST_CHANGES_FILE, signal)) as
+    | Record<Rev, Changes>
+    | Error;
+  if (changes instanceof Error) {
+    return { status: "error", message: changes.message };
   }
-  let changes: Record<Rev, Changes>;
-  try {
-    // SAFETY: diffmap share writes this file from readDocumentChanges.
-    changes = JSON.parse(snapshot) as Record<Rev, Changes>;
-  } catch {
-    return {
-      status: "error",
-      message: `${GIST_CHANGES_FILE} is not valid JSON.`,
-    };
+  // SAFETY: diffmap share writes this file as path to contents.
+  const sourceFiles = (await readSnapshot(
+    apiFiles,
+    GIST_FILES_FILE,
+    signal,
+  )) as HostFiles | Error;
+  if (sourceFiles instanceof Error) {
+    return { status: "error", message: sourceFiles.message };
   }
 
   return {
@@ -125,10 +131,28 @@ export async function loadGistMarkdown(
       files,
       chosen,
       changes,
+      sourceFiles,
     },
   };
 }
 
+/** A JSON file `diffmap share` wrote, or `{}` when the gist predates it. */
+async function readSnapshot(
+  apiFiles: Record<string, GistApiFile>,
+  name: string,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  const file = apiFiles[name];
+  if (file === undefined) return {};
+  const text = await readGistFile(file, signal);
+  if (text instanceof Error) return text;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return new Error(`${name} is not valid JSON.`);
+  }
+}
+
 async function readGistFile(file: GistApiFile, signal?: AbortSignal) {
   const name = file.filename ?? "file";
   if (file.truncated !== true && typeof file.content === "string") {

package/src/git.test.ts

@@ -249,7 +249,7 @@ test("readDocumentChanges rejects unchanged files and ranges past the end", asyn
     const sha = (await git("rev-parse", "HEAD")).slice(0, 7);
     const check = (reference: { path: string; start?: number; end?: number }) =>
       readDocumentChanges(root, {
-        changeRevs: [],
+        changeCards: [],
         references: [{ kind: "file", rev: sha, ...reference }],
       });
 
@@ -269,6 +269,18 @@ test("readDocumentChanges rejects unchanged files and ranges past the end", asyn
       unchanged instanceof Error ? unchanged.message : "",
       /gone\.ts is not changed/,
     );
+
+    const review = (paths: string[]) =>
+      readDocumentChanges(root, {
+        changeCards: [{ rev: sha, review: paths }],
+        references: [],
+      });
+    assert.equal((await review(["keep.ts"])) instanceof Error, false);
+    const missing = await review(["keep.ts", "gone.ts"]);
+    assert.match(
+      missing instanceof Error ? missing.message : "",
+      /lists gone\.ts to review, but it is not changed/,
+    );
   });
 });
 

package/src/git.ts

@@ -462,10 +462,13 @@ function totals(entries: NumstatEntry[]) {
  */
 export async function readDocumentChanges(
   root: string,
-  document: Pick<ViewerDocument, "references" | "changeRevs">,
+  document: Pick<ViewerDocument, "references" | "changeCards">,
 ): Promise<Map<Rev, Changes> | DiffmapGitError> {
   // Uncommitted revs are read live; only commits are checked and snapshotted.
-  const revs = new Set<Rev>(document.changeRevs.filter(isCommitRev));
+  const commitCards = document.changeCards.filter((card) =>
+    isCommitRev(card.rev),
+  );
+  const revs = new Set<Rev>(commitCards.map((card) => card.rev));
   for (const reference of document.references) {
     if (reference.kind === "changes" || reference.rev !== undefined)
       revs.add(reference.rev!);
@@ -476,6 +479,16 @@ export async function readDocumentChanges(
     if (changes instanceof Error) return changes;
     loaded.set(rev, changes);
   }
+  for (const card of commitCards) {
+    const files = loaded.get(card.rev)!.files;
+    const missing = card.review.find(
+      (reviewPath) => !files.some((file) => file.path === reviewPath),
+    );
+    if (missing !== undefined)
+      return new DiffmapGitError({
+        reason: `changes ${card.rev} lists ${missing} to review, but it is not changed in ${card.rev}.`,
+      });
+  }
   for (const reference of document.references) {
     if (reference.kind !== "file" || reference.rev === undefined) continue;
     const file = loaded

package/src/host/HostHome.tsx

@@ -12,10 +12,18 @@ import {
 } from "../viewer/changesSource.ts";
 import { HostFilesContext } from "./files.ts";
 import homeSource from "./home.md?raw";
-import cliSource from "../cli.ts?raw";
 import shareSource from "../share.ts?raw";
-import parseViewerSource from "../parseViewer.ts?raw";
-import githubRouteSource from "../github/route.ts?raw";
+import serveSource from "../serve.ts?raw";
+import gitSource from "../git.ts?raw";
+import fetchRepoSource from "../github/fetchRepo.ts?raw";
+import fenceSource from "../viewer/Fence.tsx?raw";
+import callStackSource from "../viewer/CallStackDiff.tsx?raw";
+import sourceNavigationSource from "../viewer/sourceNavigation.ts?raw";
+import sourceDiffPanelSource from "../viewer/SourceDiffPanel.tsx?raw";
+import viewerAppSource from "../viewer/ViewerApp.tsx?raw";
+import parseFenceSource from "../parseFence.ts?raw";
+import annotationsSource from "../annotations.ts?raw";
+import hostFilesSource from "./files.ts?raw";
 
 let parserReady: Promise<void> | undefined;
 
@@ -25,10 +33,18 @@ function readyHostParser() {
 }
 
 const hostFiles = {
-  "src/cli.ts": cliSource,
   "src/share.ts": shareSource,
-  "src/parseViewer.ts": parseViewerSource,
-  "src/github/route.ts": githubRouteSource,
+  "src/serve.ts": serveSource,
+  "src/git.ts": gitSource,
+  "src/github/fetchRepo.ts": fetchRepoSource,
+  "src/viewer/Fence.tsx": fenceSource,
+  "src/viewer/CallStackDiff.tsx": callStackSource,
+  "src/viewer/sourceNavigation.ts": sourceNavigationSource,
+  "src/viewer/SourceDiffPanel.tsx": sourceDiffPanelSource,
+  "src/viewer/ViewerApp.tsx": viewerAppSource,
+  "src/parseFence.ts": parseFenceSource,
+  "src/annotations.ts": annotationsSource,
+  "src/host/files.ts": hostFilesSource,
 };
 
 /** The homepage walks through diffmap's own commits, read from GitHub. */

package/src/host/files.ts

@@ -1,6 +1,10 @@
 import { createContext, useContext } from "react";
 
-/** Bundled files for the hosted homepage. `[[path]]` reads these, not GitHub. */
+/**
+ * Files a hosted viewer has without a server: the homepage's bundled sources,
+ * or the files `diffmap share` saved in a gist. `[[path]]` and file excerpts
+ * read these, not GitHub.
+ */
 export type HostFiles = Record<string, string>;
 
 export const HostFilesContext = createContext<HostFiles | undefined>(undefined);