@tanishqkancharla/diffmap 0.6.0 → 0.6.1

package/README.md

@@ -258,7 +258,7 @@ service API "HTTP server" [[src/api.ts]]
       > Failures since the last success. Five locks the account.
 
 start "Alice logs in"
-  > She is signed out.
+  > The API checks her password with Auth, then sets a session cookie.
 step "The browser submits the form"
   Browser -> API: POST /login
 step "The API asks Auth to verify"
@@ -279,13 +279,13 @@ step "The API sets the session cookie"
 - `start "caption"` at column 0, before the first step, captions the whole
   diagram, such as `start "Alice logs in"`. It shows above the diagram until
   the reader steps, and each step's caption replaces it. A `>` line under it
-  can say what the initial state shows. A `services` fence takes no `[Title]`;
-  the start caption is its title.
+  gives an overview of the whole process. A `services` fence takes no
+  `[Title]`; the start caption is its title.
 - `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 step's events travel one after another, in the order written, and the
+  updates land when the last one arrives.
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanishqkancharla/diffmap",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Serve a spec or code walkthrough as a local page",
   "license": "MIT",
   "author": "Tanishq Kancharla",

package/src/host/home.md

@@ -30,70 +30,57 @@ Your agent selects the best diagram for each idea. Each part of the diagram has
 
 A service diagram shows each service and its state. Each step shows one event and the state that the event changes. Thus, you do not have to remember the state.
 
-To see how `diffmap serve` opens a spec, press **Play**. To read about a name with a dotted line, put the pointer on the name:
-
-```services
-service Laptop
-  > This is your computer. diffmap serve reads files here and does not upload them.
-  service Agent "coding agent"
-    > The agent writes the spec and runs diffmap for you.
-  service CLI "diffmap serve" [[src/serve.ts#startServer]]
-    > This small server uses git to read your repository.
-    state url = none
-  service Repo "your repository"
-    > The repository contains the spec and the commits that the spec refers to.
-service Browser
-  service Page "the spec" [[src/viewer/ViewerApp.tsx#ViewerApp]]
-    state page = empty
-  service Panel "Diff panel" [[src/viewer/SourceDiffPanel.tsx#SourceDiffPanel]]
-    > The Diff panel opens next to the spec. It shows the code for the link that you clicked.
-    state shows = none
-
-start "diffmap serve opens a spec in your browser"
-  > The agent has written the spec, but nothing serves it yet.
-
-step "The agent serves the spec"
-  > Your agent runs diffmap serve with the path of the spec.
-  Agent -> CLI: serve specs/search.md
-step "serve examines each commit in the spec"
-  > Before the server starts, it uses git to read each commit and line range that the spec refers to.
-  CLI -> Repo: readDocumentChanges [[src/git.ts#readDocumentChanges]]
-    > If a SHA or a line range is wrong, the command stops here. Thus, the page has no broken links.
-step "serve prints a URL for you"
-  > The server starts on your computer and gives the agent a local URL.
-  CLI -> Agent: localhost URL
-  CLI.url = localhost:4321
-step "You open the page"
-  > Your browser gets the spec from the server and shows it as a page.
-  Page -> CLI: GET /
-  CLI -> Page: spec
-  Page.page = rendered
-step "You click a call stack row"
-  > The Diff panel asks the server for the code that the row refers to.
-  Panel -> CLI: /__diffmap/source
-  CLI -> Repo: git show
-    > The server reads the file from the commit in the row, not from the working tree.
-step "The Diff panel shows the code"
-  > The server sends the lines, and the Diff panel shows them next to the spec.
-  CLI -> Panel: lines
-  Panel.shows = code
+A service diagram can also show a change. Red parts exist only today, and green parts are new. As you step, each value shows today's state crossed out next to the new state.
+
+This change moves login sessions from memory to a database. Press **Play** to step through it:
+
+```services diff
+ service Browser "login page"
+   state cookie = none
+ service API "HTTP server"
+-  service Cache "in-memory sessions"
+-    state sessions = 0
++  service Sessions
+ service Postgres
+-  state sessions = not used
++  state sessions = 0 rows
+
+ start "Sessions move from memory to Postgres"
+   > Alice logs in, and the API stores her session. Today it keeps the session in memory, so a server restart signs her out. After the change, Sessions writes it to Postgres, where it survives a restart.
+
+ step "Alice logs in"
+   Browser -> API: POST /login
+-step "The API keeps the session in memory"
+   API -> Cache: create(alice)
+   Cache.sessions = 1
+     > The server loses this when it restarts.
++step "Sessions writes the session to Postgres"
+   API -> Sessions: create(alice)
+   Sessions -> Postgres: INSERT s_81f
+   Postgres.sessions = 1 row
+     > The row survives a restart.
+ step "The API sets the session cookie"
+   API -> Browser: 200 Set-Cookie
+   Browser.cookie = sid=s_81f
 ```
 
 ### Mermaid diagrams
 
-The page shows Mermaid diagrams. Each node and each arrow can have a link to its code. This diagram shows what occurs when you click a link:
-
-```mermaid
-flowchart LR
-  Click[Click a link] --> Find[useSourceReference]
-  Find -->|diffmap serve| Local[Read the repo with git]
-  Find -->|diffmap.dev| GitHub[fetchPinnedBlob]
-  Local --> Panel[SourceDiffPanel]
-  GitHub --> Panel
-  %% ref node:Find [[src/viewer/sourceNavigation.ts#useSourceReference]]
-  %% ref node:GitHub [[src/github/fetchRepo.ts#fetchPinnedBlob]]
-  %% ref node:Panel [[src/viewer/SourceDiffPanel.tsx#SourceDiffPanel]]
-  %% ref edge:1 [[src/viewer/sourceNavigation.ts#requestSource]]
+The page shows Mermaid diagrams. Each node and each arrow can have a link to its code. A diagram can show a change in one picture: green parts are new, and red parts are removed.
+
+This diagram shows what occurs when you click a link, and what changed when diffmap.dev began to read code from GitHub:
+
+```mermaid diff [diffmap.dev reads linked code from GitHub]
+ flowchart LR
+   Click[Click a link] --> Find[useSourceReference]
+   Find -->|diffmap serve| Local[Read the repo with git]
++  Find -->|diffmap.dev| GitHub[fetchPinnedBlob]
+   Local --> Panel[SourceDiffPanel]
++  GitHub --> Panel
+   %% ref node:Find [[src/viewer/sourceNavigation.ts#useSourceReference]]
+   %% ref node:GitHub [[src/github/fetchRepo.ts#fetchPinnedBlob]]
+   %% ref node:Panel [[src/viewer/SourceDiffPanel.tsx#SourceDiffPanel]]
+   %% ref edge:1 [[src/viewer/sourceNavigation.ts#requestSource]]
 ```
 
 ### Call stacks

package/src/host/home.test.ts

@@ -37,6 +37,17 @@ test("homepage markdown is a real viewer document", async () => {
   const mermaid = fences.find((fence) => fence.kind === "mermaid");
   assert.notEqual(mermaid, undefined);
   if (mermaid?.kind !== "mermaid") return;
+  // The homepage shows diagram diffs, not only call stack diffs.
+  assert.notEqual(mermaid.sides, undefined);
+  assert.equal(
+    fences.some(
+      (fence) =>
+        fence.kind === "services" &&
+        fence.parsed.ok &&
+        fence.parsed.diagram.diff,
+    ),
+    true,
+  );
   assert.equal(
     mermaid.annotations.some((link) =>
       link.annotation.references.some((ref) => ref.kind === "file"),

package/src/services.ts

@@ -2,8 +2,8 @@ import { parseAnnotation, type SourceAnnotation } from "./annotations.js";
 
 /**
  * A `services` fence: services that hold state, nest sub-services, and send
- * each other events. Steps replay the events in order. Every event in a step
- * is in flight at once; the step's state updates land when they arrive.
+ * each other events. Steps replay the events in order. A step's events travel
+ * one after another; its state updates land when the last one arrives.
  */
 export type ServiceDiagram = {
   services: Service[];

package/src/viewer/CallStackDiff.tsx

@@ -128,9 +128,8 @@ const rowSize = defineVars({
 });
 
 const styles = {
-  // Sized like Maui's code block, so stacks and code read as one family.
+  // Sized like Maui's code block, but in the proportional UI font.
   shell: style(text({ size: "xs", fontWeight: 400, color: "highContrast" }), {
-    fontFamily: codeFontFamily,
     margin: 0,
     paddingBlock: "8px",
     overflowX: "hidden",
@@ -172,7 +171,6 @@ const styles = {
         backgroundColor: colors.red[5],
         boxShadow: `inset 3px 0 ${colors.red[9]}`,
       },
-      "&[data-note]": { cursor: "help" },
       // The sign fills the row gutter, so the dot follows the label instead.
       "&[data-note='start'] .stack-label::after": {
         content: '""',

package/src/viewer/CodeBlock.tsx

@@ -190,7 +190,6 @@ const styles = {
     "& .line-note": {
       display: "block",
       position: "relative",
-      cursor: "help",
       outline: "none",
     },
     "& .line-note::before": lineNoteDot,

package/src/viewer/ServiceDiagramBlock.tsx

@@ -92,14 +92,15 @@ function ServicePlayer(props: { diagram: ServiceDiagram } & SourceNavigation) {
   const goTo = (target: number, animate: boolean) =>
     setPosition(positionFor(diagram, target, animate && !reduceMotion));
 
+  // Events travel one after another, so the step settles when the last lands.
   useEffect(() => {
     if (position.phase !== "travel") return;
     const timer = setTimeout(
       () => setPosition({ step: position.step, phase: "settled" }),
-      TRAVEL_MS,
+      TRAVEL_MS * (diagram.steps[position.step - 1]?.events.length ?? 1),
     );
     return () => clearTimeout(timer);
-  }, [position]);
+  }, [position, diagram]);
 
   useEffect(() => {
     if (!playing || position.phase !== "settled") return;

package/src/viewer/ServiceStage.tsx

@@ -536,22 +536,27 @@ function EventMarks(
   const label = props.event.label === "" ? undefined : pillText(props.event);
   const lengths = cumulativeLengths(props.points);
   const total = lengths.at(-1)! || 1;
+  // A step's events leave in order, each when the one before it arrives.
+  const delay = props.phase === "travel" ? (props.index * TRAVEL_MS) / 1000 : 0;
   return (
     <>
       {props.phase === "travel" && (
         <motion.div
           className={packet}
           data-change={props.event.sign}
-          initial={{ x: props.points[0]!.x, y: props.points[0]!.y }}
+          initial={{ x: props.points[0]!.x, y: props.points[0]!.y, opacity: 0 }}
           animate={{
             x: props.points.map((point) => point.x),
             y: props.points.map((point) => point.y),
+            opacity: 1,
           }}
           // Even speed along every segment of the route.
           transition={{
+            delay,
             duration: TRAVEL_MS / 1000,
             ease: "easeInOut",
             times: lengths.map((length) => length / total),
+            opacity: { delay, duration: 0 },
           }}
         />
       )}
@@ -563,6 +568,7 @@ function EventMarks(
           data-event-label={props.index}
           initial={{ opacity: 0 }}
           animate={{ opacity: 1 }}
+          transition={{ delay }}
         >
           {label !== undefined &&
             (annotation === undefined ? (
@@ -911,7 +917,6 @@ const described = {
     textDecorationStyle: "dotted" as const,
     textDecorationColor: colors.gray[8],
     textUnderlineOffset: "3px",
-    cursor: "help",
   },
 };
 
@@ -1002,7 +1007,7 @@ const styles = {
     focusRing(),
     {
       minWidth: 0,
-      "& > [data-described]": described["&[data-described='true']"],
+      "& > [data-described='true']": described["&[data-described='true']"],
     },
   ),
   headerButton: style({

package/src/viewer/notes.tsx

@@ -105,7 +105,6 @@ export function NoteText(props: { text: string }) {
 
 const symbolNoteClass = style(focusRing(), {
   borderRadius: "3px",
-  cursor: "help",
   textDecorationLine: "underline",
   textDecorationStyle: "dotted",
   textDecorationColor: colors.gray[9],