@coldtea/pr-lens-renderer 0.4.0 → 0.5.0

package/src/render-all.ts

@@ -0,0 +1,195 @@
+import type {
+  Config,
+  GraphDoc,
+  Lens,
+  RenderAsset,
+  RenderManifest,
+  View,
+  WalkthroughAsset,
+} from "@coldtea/pr-lens-schema";
+import { assertNever, MAX_RENDER_ASSETS } from "@coldtea/pr-lens-schema";
+import { PrLensRenderError } from "./errors.js";
+import {
+  assetIdentity,
+  buildManifest,
+  renderAssetFileName,
+  renderAssetId,
+  walkthroughAssetFileName,
+  walkthroughAssetId,
+} from "./manifest.js";
+import { prepare, render, type RenderedSvg } from "./render.js";
+import { flattenViews } from "./scope.js";
+import { isPairTheme, THEME_PAIR } from "./theme.js";
+import {
+  renderWalkthroughEmbed,
+  type WalkthroughEmbed,
+} from "./walkthrough/embed.js";
+import type { WalkthroughIssue } from "./walkthrough/resolve.js";
+import { tileIdForView } from "./walkthrough/tile-ids.js";
+
+/** The pair, one half of it, or neutral. Never all three: the view cap assumes two assets per view. */
+export type RenderThemes =
+  | readonly ["light", "dark"]
+  | readonly ["light"]
+  | readonly ["dark"]
+  | readonly ["neutral"];
+
+export type RenderAllOptions = {
+  config?: Config;
+  /** The pair by default. */
+  themes?: RenderThemes;
+};
+
+export type RenderedAsset = RenderedSvg & { asset: RenderAsset };
+
+export type RenderedWalkthrough = WalkthroughEmbed & {
+  asset: WalkthroughAsset;
+};
+
+/** `absent` for a neutral render too: the embed has no single-image form. */
+export type RenderedWalkthroughs =
+  | { type: "absent" }
+  | { type: "unresolvable"; issues: WalkthroughIssue[] }
+  | { type: "rendered"; assets: RenderedWalkthrough[] };
+
+export type RenderAllResult = {
+  assets: RenderedAsset[];
+  walkthrough: RenderedWalkthroughs;
+  manifest: RenderManifest;
+};
+
+/** Every drill-down section in every theme asked for, or one diagram per lens when there are none. */
+export const renderAll = (
+  doc: GraphDoc,
+  options: RenderAllOptions = {},
+): RenderAllResult => {
+  const prepared = prepare(doc, options.config);
+  const themes = options.themes ?? THEME_PAIR;
+
+  const targets: { lens: Lens; view: View | undefined }[] =
+    prepared.views.length > 0
+      ? flattenViews(prepared.views)
+          .filter((view) => prepared.lenses.includes(view.lens))
+          .map((view) => ({ lens: view.lens, view }))
+      : prepared.lenses
+          .filter((lens) => {
+            switch (lens) {
+              case "architecture":
+                return true;
+              case "data-flow":
+                return prepared.flows.length > 0;
+              case "data-model":
+                return prepared.dataModel !== undefined;
+              default:
+                return assertNever(lens, "Unhandled lens");
+            }
+          })
+          .map((lens) => ({ lens, view: undefined }));
+
+  // Only a hand-built document can reach this: the contract's cap is a refinement, which the type does not carry.
+  if (targets.length * themes.length > MAX_RENDER_ASSETS)
+    throw new PrLensRenderError(
+      "TOO_MANY_ASSETS",
+      `this document asks for ${targets.length * themes.length} pictures across ${targets.length} views ` +
+        `and ${themes.length} themes, and a render manifest carries at most ${MAX_RENDER_ASSETS}`,
+    );
+
+  const assets: RenderedAsset[] = [];
+
+  for (const target of targets)
+    for (const theme of themes) {
+      const rendered = render(prepared, {
+        lens: target.lens,
+        theme,
+        view: target.view?.id,
+      });
+      const address = { lens: target.lens, theme, view: target.view?.id };
+      const identity = assetIdentity(rendered.svg);
+
+      assets.push({
+        ...rendered,
+        asset: {
+          id: renderAssetId(address),
+          lens: target.lens,
+          theme,
+          view: target.view?.id,
+          mediaType: "image/svg+xml",
+          ...identity,
+          width: rendered.width,
+          height: rendered.height,
+          animated: rendered.animated,
+          path: renderAssetFileName(address, identity.contentHash),
+        },
+      });
+    }
+
+  if (assets.length === 0)
+    throw new PrLensRenderError(
+      "NOTHING_TO_RENDER",
+      "this document declares no renderable view",
+    );
+
+  const walkthrough = renderWalkthroughs(prepared, themes, assets);
+  const walkthroughAssets =
+    walkthrough.type === "rendered"
+      ? walkthrough.assets.map(({ asset }) => asset)
+      : [];
+
+  return {
+    assets,
+    walkthrough,
+    manifest: buildManifest(
+      prepared,
+      assets.map(({ asset }) => asset),
+      walkthroughAssets,
+    ),
+  };
+};
+
+/** Hands the views just drawn to the embed, which then draws only flow and whole-model tiles. */
+const renderWalkthroughs = (
+  doc: GraphDoc,
+  themes: RenderThemes,
+  drawn: readonly RenderedAsset[],
+): RenderedWalkthroughs => {
+  const assets: RenderedWalkthrough[] = [];
+
+  for (const theme of themes.filter(isPairTheme)) {
+    const tiles = new Map(
+      drawn.flatMap((asset) =>
+        asset.theme === theme && asset.view !== undefined
+          ? [[tileIdForView(asset.view), asset]]
+          : [],
+      ),
+    );
+    const result = renderWalkthroughEmbed(doc, { theme, tiles });
+    switch (result.type) {
+      case "absent":
+      case "unresolvable":
+        return result;
+      case "rendered": {
+        const identity = assetIdentity(result.embed.svg);
+        assets.push({
+          ...result.embed,
+          asset: {
+            id: walkthroughAssetId(theme),
+            theme,
+            mediaType: "image/svg+xml",
+            ...identity,
+            width: result.embed.width,
+            height: result.embed.height,
+            steps: result.embed.steps,
+            path: walkthroughAssetFileName(theme, identity.contentHash),
+          },
+        });
+        break;
+      }
+      default:
+        return assertNever(result, "Unhandled walkthrough embed result");
+    }
+  }
+
+  return assets.length === 0
+    ? { type: "absent" }
+    : { type: "rendered", assets };
+};

package/src/render.ts

@@ -1,11 +1,10 @@
-import type { Config, GraphDoc, Lens, RenderAsset, RenderManifest, View, ViewScope } from "@coldtea/pr-lens-schema";
-import { assertNever, MAX_RENDER_ASSETS } from "@coldtea/pr-lens-schema";
+import type { Config, GraphDoc, Lens, View, ViewScope } from "@coldtea/pr-lens-schema";
+import { assertNever } from "@coldtea/pr-lens-schema";
 import type { RenderAtlas } from "./atlas.js";
 import { applyCorrections } from "./corrections.js";
 import { PrLensRenderError } from "./errors.js";
-import { buildManifest, contentHash, renderAssetFileName, renderAssetId } from "./manifest.js";
-import { findView, flattenViews, resolveScope, type ScopedGraph } from "./scope.js";
-import { paletteFor, THEME_PAIR, type Theme } from "./theme.js";
+import { findView, resolveScope, type ScopedGraph } from "./scope.js";
+import { paletteFor, type Theme } from "./theme.js";
 import { paintArchitecture } from "./svg/architecture.js";
 import { paintDataFlow } from "./svg/dataflow.js";
 import { paintDataModel } from "./svg/datamodel.js";
@@ -22,6 +21,8 @@ export type RenderOptions = {
 
 export type RenderedSvg = {
   svg: string;
+  /** The painting alone, for a document that nests this picture under its own defs and ground. */
+  body: string;
   width: number;
   height: number;
   lens: Lens;
@@ -34,7 +35,7 @@ export type RenderedSvg = {
 
 const WHOLE_DOCUMENT: ViewScope = { kind: "all" };
 
-const prepare = (doc: GraphDoc, config: Config | undefined): GraphDoc =>
+export const prepare = (doc: GraphDoc, config: Config | undefined): GraphDoc =>
   config === undefined ? doc : applyCorrections(doc, config.map);
 
 const paint = (
@@ -111,6 +112,7 @@ export const render = (doc: GraphDoc, options: RenderOptions): RenderedSvg => {
 
   return {
     svg,
+    body,
     width,
     height,
     lens: options.lens,
@@ -127,113 +129,3 @@ const requireView = (views: readonly View[], id: string): View => {
     throw new PrLensRenderError("UNKNOWN_VIEW", `this document has no view '${id}'`);
   return view;
 };
-
-/**
- * What a render may be asked for: the `<picture>` pair, one half of it, or
- * the single self-contained render.
- *
- * Not `readonly Theme[]`, which would admit all three at once — three assets
- * per view against a view cap derived from two, so a document that validates
- * could produce a manifest that does not. The contract's promise is that if
- * it parses, it renders; this is the boundary that keeps it true.
- */
-export type RenderThemes =
-  | readonly ["light", "dark"]
-  | readonly ["light"]
-  | readonly ["dark"]
-  | readonly ["neutral"];
-
-export type RenderAllOptions = {
-  config?: Config;
-  /** The `<picture>` pair by default; `['neutral']` for a single-image surface. */
-  themes?: RenderThemes;
-};
-
-export type RenderedAsset = RenderedSvg & { asset: RenderAsset };
-
-export type RenderAllResult = {
-  assets: RenderedAsset[];
-  manifest: RenderManifest;
-};
-
-/**
- * Every drill-down section a comment will show, in both themes.
- *
- * A document with no sections still renders: it gets one diagram per lens it
- * declares, which is what a comment falls back to when extraction found
- * nothing worth splitting into a tree.
- */
-export const renderAll = (doc: GraphDoc, options: RenderAllOptions = {}): RenderAllResult => {
-  const prepared = prepare(doc, options.config);
-  const themes = options.themes ?? THEME_PAIR;
-
-  const targets: { lens: Lens; view: View | undefined }[] =
-    prepared.views.length > 0
-      ? flattenViews(prepared.views)
-          .filter((view) => prepared.lenses.includes(view.lens))
-          .map((view) => ({ lens: view.lens, view }))
-      : prepared.lenses
-          .filter((lens) => {
-            switch (lens) {
-              case "architecture":
-                return true;
-              case "data-flow":
-                return prepared.flows.length > 0;
-              case "data-model":
-                return prepared.dataModel !== undefined;
-              default:
-                return assertNever(lens, "Unhandled lens");
-            }
-          })
-          .map((lens) => ({ lens, view: undefined }));
-
-  /**
-   * The contract caps a view tree at the number of views a two-theme render
-   * fits inside a manifest, so a parsed document cannot reach this. A
-   * hand-built one can: the cap lives in a refinement, and a refinement does
-   * not survive into the inferred type. This is a postcondition on what is
-   * about to be produced rather than a re-reading of what came in — the count
-   * depends on how many themes the caller asked for, which no document knows.
-   */
-  if (targets.length * themes.length > MAX_RENDER_ASSETS)
-    throw new PrLensRenderError(
-      "TOO_MANY_ASSETS",
-      `this document asks for ${targets.length * themes.length} pictures across ${targets.length} views ` +
-        `and ${themes.length} themes, and a render manifest carries at most ${MAX_RENDER_ASSETS}`,
-    );
-
-  const assets: RenderedAsset[] = [];
-
-  for (const target of targets)
-    for (const theme of themes) {
-      const rendered = render(prepared, {
-        lens: target.lens,
-        theme,
-        view: target.view?.id,
-      });
-      const address = { lens: target.lens, theme, view: target.view?.id };
-      const hash = contentHash(rendered.svg);
-
-      assets.push({
-        ...rendered,
-        asset: {
-          id: renderAssetId(address),
-          lens: target.lens,
-          theme,
-          view: target.view?.id,
-          mediaType: "image/svg+xml",
-          contentHash: hash,
-          bytes: Buffer.byteLength(rendered.svg, "utf8"),
-          width: rendered.width,
-          height: rendered.height,
-          animated: rendered.animated,
-          path: renderAssetFileName(address, hash),
-        },
-      });
-    }
-
-  if (assets.length === 0)
-    throw new PrLensRenderError("NOTHING_TO_RENDER", "this document declares no renderable view");
-
-  return { assets, manifest: buildManifest(prepared, assets.map(({ asset }) => asset)) };
-};

package/src/svg/datamodel.ts

@@ -35,6 +35,7 @@ import {
   LANE_RADIUS,
   LANE_TOP,
   SUBTITLE_SIZE,
+  TABLE_ROW_HEIGHT,
   TABLE_ROW_TEXT_SIZE,
   TABLE_ROW_TYPE_SIZE,
 } from "../design.js";
@@ -335,6 +336,18 @@ export const paintDataModel = (graph: ScopedGraph, palette: Palette): DataModelP
       ...emptyAtlas(),
       lanes: atlasBoxes(layout.stores.map(({ store, box }) => ({ id: store.id, box })), canvas),
       tables: atlasBoxes(layout.tables.map(({ table, box }) => ({ id: table.id, box })), canvas),
+      columns: Object.fromEntries(
+        layout.tables.map(({ table, box, columns }) => [
+          table.id,
+          atlasBoxes(
+            columns.map(({ column, top }) => ({
+              id: column.name,
+              box: { x: box.x, y: top, width: box.width, height: TABLE_ROW_HEIGHT },
+            })),
+            canvas,
+          ),
+        ]),
+      ),
       edges: atlasBoxes(
         routed.map(({ relation, curve }) => ({ id: relation.id, box: curveBounds(curve) })),
         canvas,

package/src/svg/document.ts

@@ -51,7 +51,8 @@ const TONES = ["added", "modified", "removed", "neutral"] as const satisfies rea
  * fires and forgets. The open head anchors at its tip so the line runs all
  * the way into the point, where a filled head covers its own line end.
  */
-const markers = (palette: Palette): string =>
+/** Exported so a document nesting several pictures can define the arrowheads once. */
+export const markerDefs = (palette: Palette): string =>
   TONES.map(
     (tone) =>
       wrap(
@@ -120,7 +121,7 @@ export const svgDocument = (input: {
       "pattern",
       { id: "dots", width: DOT_PITCH, height: DOT_PITCH, patternUnits: "userSpaceOnUse" },
       tag("circle", { cx: 1.5, cy: 1.5, r: 1, fill: palette.dot }),
-    ) + markers(palette),
+    ) + markerDefs(palette),
   );
 
   return lines([

package/src/theme.ts

@@ -12,6 +12,10 @@ import { assertNever, THEMES, THEME_PAIR, type Theme } from "@coldtea/pr-lens-sc
  */
 export { THEMES, THEME_PAIR, type Theme };
 
+export type PairTheme = (typeof THEME_PAIR)[number];
+
+export const isPairTheme = (theme: Theme): theme is PairTheme => THEME_PAIR.some((half) => half === theme);
+
 /**
  * Every colour the renderer can paint, resolved to a literal before it
  * reaches the document. CSS custom properties would be shorter, but GitHub

package/src/version.ts

@@ -6,4 +6,4 @@
  */
 export const RENDERER_NAME = "@coldtea/pr-lens-renderer";
 
-export const RENDERER_VERSION = "0.4.0";
+export const RENDERER_VERSION = "0.5.0";

package/src/walkthrough/camera.ts

@@ -0,0 +1,142 @@
+import { assertNever } from "@coldtea/pr-lens-schema";
+import type { Box } from "../geometry.js";
+import { MAX_SCALE, MIN_SCALE } from "./layout.js";
+
+/** The canvas and the embed both frame steps here, so a step lands the same way in both. */
+export type FramingPolicy = { kind: "strip" } | { kind: "diagram" } | { kind: "selection" } | { kind: "component" };
+
+export type Flight = { kind: "cut" } | { kind: "smooth"; durationMs: number };
+
+/** The transform a stage applies to the strip. Translate first, then scale. */
+export type Viewport = { x: number; y: number; scale: number };
+
+/** The part of the window the pictures get. */
+export type Stage = { left: number; top: number; width: number; height: number };
+
+type Framing = { maxScale: number; padding: number };
+
+const framing = (policy: FramingPolicy): Framing => {
+  switch (policy.kind) {
+    // A small render is never enlarged to fill the window.
+    case "strip":
+    case "diagram":
+      return { maxScale: 1, padding: 80 };
+    // A selection fills the stage. It is already padded, so it gets less air.
+    case "selection":
+      return { maxScale: 2, padding: 56 };
+    // One component with its neighbours still in view.
+    case "component":
+      return { maxScale: 1, padding: 220 };
+    default:
+      return assertNever(policy, "Unhandled framing policy");
+  }
+};
+
+/** The transform that shows `rect` whole and centred in the stage. */
+export function frame(policy: FramingPolicy, rect: Box, stage: Stage): Viewport {
+  const { maxScale, padding } = framing(policy);
+  // On a stage smaller than the padding, the padding shrinks instead of the picture.
+  const air = Math.min(padding, stage.width / 6, stage.height / 6);
+  const fitted = Math.min(
+    (stage.width - air * 2) / rect.width,
+    (stage.height - air * 2) / rect.height,
+    maxScale,
+  );
+  const scale = Math.min(Math.max(fitted, MIN_SCALE), MAX_SCALE);
+
+  return {
+    x: stage.left + (stage.width - rect.width * scale) / 2 - rect.x * scale,
+    y: stage.top + (stage.height - rect.height * scale) / 2 - rect.y * scale,
+    scale,
+  };
+}
+
+/** Short enough not to feel like a wait, long enough that a jump across the strip reads as travel. */
+const MIN_FLIGHT_MS = 560;
+const MAX_FLIGHT_MS = 1500;
+const MS_PER_UNIT = 420;
+
+export function flightFor(distance: number, reducedMotion: boolean): Flight {
+  if (reducedMotion) return { kind: "cut" };
+  return { kind: "smooth", durationMs: Math.min(Math.max(distance * MS_PER_UNIT, MIN_FLIGHT_MS), MAX_FLIGHT_MS) };
+}
+
+export const easeInOut = (t: number): number => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+
+export const lerpRect = (from: Box, to: Box, t: number): Box => ({
+  x: from.x + (to.x - from.x) * t,
+  y: from.y + (to.y - from.y) * t,
+  width: from.width + (to.width - from.width) * t,
+  height: from.height + (to.height - from.height) * t,
+});
+
+/** A camera as the interpolation sees it: where it looks, and how much world the stage spans. */
+type View = [x: number, y: number, span: number];
+
+const centre = (stage: Stage) => ({ x: stage.left + stage.width / 2, y: stage.top + stage.height / 2 });
+
+const toView = (viewport: Viewport, stage: Stage): View => {
+  const middle = centre(stage);
+  return [
+    (middle.x - viewport.x) / viewport.scale,
+    (middle.y - viewport.y) / viewport.scale,
+    stage.width / viewport.scale,
+  ];
+};
+
+const fromView = (view: View, stage: Stage): Viewport => {
+  const middle = centre(stage);
+  const scale = stage.width / view[2];
+  return { x: middle.x - view[0] * scale, y: middle.y - view[1] * scale, scale };
+};
+
+export type FlightPath = {
+  at: (t: number) => Viewport;
+  /** The path's length in the interpolation's units. It sets the duration. */
+  distance: number;
+};
+
+const cosh = (x: number) => (Math.exp(x) + Math.exp(-x)) / 2;
+const sinh = (x: number) => (Math.exp(x) - Math.exp(-x)) / 2;
+const tanh = (x: number) => {
+  const e = Math.exp(2 * x);
+  return (e - 1) / (e + 1);
+};
+
+const RHO = Math.SQRT2;
+
+/** The van Wijk and Nuij path, as d3-interpolate spells it out: out far enough to see both ends, then back in. */
+export function interpolateFlight(from: Viewport, to: Viewport, stage: Stage): FlightPath {
+  const [ux0, uy0, w0] = toView(from, stage);
+  const [ux1, uy1, w1] = toView(to, stage);
+  const dx = ux1 - ux0;
+  const dy = uy1 - uy0;
+  const d2 = dx * dx + dy * dy;
+  const rho2 = RHO * RHO;
+  const rho4 = rho2 * rho2;
+
+  if (d2 < 1e-12) {
+    const distance = Math.abs(Math.log(w1 / w0) / RHO);
+    return {
+      distance,
+      at: (t) => fromView([ux0 + t * dx, uy0 + t * dy, w0 * Math.exp(RHO * t * (Math.log(w1 / w0) / RHO))], stage),
+    };
+  }
+
+  const d1 = Math.sqrt(d2);
+  const b0 = (w1 * w1 - w0 * w0 + rho4 * d2) / (2 * w0 * rho2 * d1);
+  const b1 = (w1 * w1 - w0 * w0 - rho4 * d2) / (2 * w1 * rho2 * d1);
+  const r0 = Math.log(Math.sqrt(b0 * b0 + 1) - b0);
+  const r1 = Math.log(Math.sqrt(b1 * b1 + 1) - b1);
+  const S = (r1 - r0) / RHO;
+  const c0 = cosh(r0);
+
+  return {
+    distance: Math.abs(S),
+    at: (t) => {
+      const s = t * S;
+      const u = (w0 / (rho2 * d1)) * (c0 * tanh(RHO * s + r0) - sinh(r0));
+      return fromView([ux0 + u * dx, uy0 + u * dy, (w0 * c0) / cosh(RHO * s + r0)], stage);
+    },
+  };
+}

package/src/walkthrough/caption.ts

@@ -0,0 +1,35 @@
+import { measure, type Face } from "../text.js";
+
+export const words = (text: string): string[] => text.split(/\s+/).filter((word) => word.length > 0);
+
+/** Greedy wrapping, which is also the fewest lines any wrapping needs. */
+const wrapAt = (parts: readonly string[], face: Face, size: number, width: number): string[] => {
+  const lines: string[] = [];
+  let line = "";
+  for (const word of parts) {
+    const joined = line === "" ? word : `${line} ${word}`;
+    if (line !== "" && measure(joined, face, size) > width) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = joined;
+    }
+  }
+  return line === "" ? lines : [...lines, line];
+};
+
+/** The fewest lines that fit, evened out by narrowing the column as far as it goes without adding a line. */
+export const balancedLines = (text: string, face: Face, size: number, maxWidth: number): string[] => {
+  const parts = words(text);
+  const widest = wrapAt(parts, face, size, maxWidth);
+  if (widest.length < 2) return widest;
+
+  let low = 1;
+  let high = maxWidth;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (wrapAt(parts, face, size, middle).length === widest.length) high = middle;
+    else low = middle + 1;
+  }
+  return wrapAt(parts, face, size, low);
+};