@knowvah/dot-engine 0.1.0

package/src/gvc/edge-labels.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: EPL-2.0
+//
+// Edge label emission with per-label `<a>` hot spots — the SVG-relevant half of
+// emit_edge's emit_edge_label calls. Each of the center label, xlabel, head
+// label, and tail label is wrapped in its own anchor when it carries a url or
+// an explicit tooltip (siblings of the whole-edge anchor, not nested).
+//
+// @see lib/common/emit.c:emit_edge (3010-3025)
+// @see lib/common/emit.c:emit_edge_label (2882)
+
+import type { Edge } from '../model/edge.js';
+import type { TextlabelT } from '../common/types.js';
+import type { RendererPlugin } from './context.js';
+import type { RenderJob } from './job.js';
+import { EmitState } from './job.js';
+import { openAnchorWith } from './anchor.js';
+import { renderOneLabel, transformPoint } from './device.js';
+import { dotneatoClosest } from '../common/spline-midpoint.js';
+import { mapbool } from '../layout/dot/rank.js';
+import type { Spline } from '../model/geom.js';
+
+/**
+ * Emit all four edge label slots in C order: label, xlabel, head, tail. Must
+ * run inside the edge group, after the path and arrow polygons.
+ * @see lib/common/emit.c:emit_end_edge (3010-3025)
+ */
+export function renderEdgeLabels(e: Edge, renderer: RendererPlugin, job: RenderJob): void {
+  const obj = job.obj;
+  // C passes ED_spl to the label/xlabel emits when decorate=true, and
+  // emit_attachment then draws the label-to-spline polyline.
+  // @see lib/common/emit.c:3013-3017
+  const spl = mapbool(e.attrs.get('decorate') ?? 'false') ? e.info.spl : undefined;
+  if (obj === null) {
+    renderOneLabel(e.info.label as TextlabelT | undefined, renderer, job);
+    if (spl) emitAttachment(e.info.label as TextlabelT | undefined, spl, renderer, job);
+    renderOneLabel(e.info.xlabel as TextlabelT | undefined, renderer, job);
+    if (spl) emitAttachment(e.info.xlabel as TextlabelT | undefined, spl, renderer, job);
+    renderOneLabel(e.info.head_label, renderer, job);
+    renderOneLabel(e.info.tail_label, renderer, job);
+    return;
+  }
+  const id = obj.id ?? '';
+  const labelHs: LabelHotspot =
+    { url: obj.labelUrl, tooltip: obj.labelTooltip, target: obj.labelTarget, explicit: obj.explicitLabelTooltip };
+  // @see lib/common/emit.c:emit_edge (3010-3025) — per-label hot spots.
+  emitEdgeLabel(e.info.label as TextlabelT | undefined, `${id}-label`, labelHs, renderer, job, spl);
+  emitEdgeLabel(e.info.xlabel as TextlabelT | undefined, `${id}-label`, labelHs, renderer, job, spl);
+  emitEdgeLabel(e.info.head_label as TextlabelT | undefined, `${id}-headlabel`,
+    { url: obj.headUrl, tooltip: obj.headTooltip, target: obj.headTarget, explicit: obj.explicitHeadTooltip },
+    renderer, job, undefined, EmitState.HLabel);
+  emitEdgeLabel(e.info.tail_label as TextlabelT | undefined, `${id}-taillabel`,
+    { url: obj.tailUrl, tooltip: obj.tailTooltip, target: obj.tailTarget, explicit: obj.explicitTailTooltip },
+    renderer, job, undefined, EmitState.TLabel);
+}
+
+/** Per-label hot-spot fields, mirroring the emit_edge_label args. */
+interface LabelHotspot {
+  url: string | null;
+  tooltip: string | null;
+  target: string | null;
+  explicit: boolean;
+}
+
+/**
+ * Emit one edge label, wrapping it in its own `<a>` hot spot when the label has
+ * a url or an explicit tooltip. The label's baseline emission is unchanged; only
+ * the anchor wrap is added. id is the full anchor id (`<edgeId>-label`).
+ * @see lib/common/emit.c:emit_edge_label (2882)
+ */
+function emitEdgeLabel(
+  lp: TextlabelT | undefined,
+  id: string,
+  hs: LabelHotspot,
+  renderer: RendererPlugin,
+  job: RenderJob,
+  spl?: Spline,
+  emitState?: EmitState,
+): void {
+  if (!lp?.set) return; // emit_edge_label: lbl == NULL || !lbl->set
+  const open = hs.url !== null || hs.explicit;
+  if (open) openAnchorWith(renderer, job, hs.url, hs.tooltip, hs.target, id);
+  // Head/tail labels route to EMIT_HLABEL/EMIT_TLABEL (→ _hldraw_/_tldraw_);
+  // the center label keeps its default EMIT_ELABEL. @see emit.c:emit_edge
+  const savedOverride = job.labelEmitOverride;
+  if (emitState !== undefined) job.labelEmitOverride = emitState;
+  try {
+    renderOneLabel(lp, renderer, job);
+  } finally {
+    job.labelEmitOverride = savedOverride;
+  }
+  if (spl) emitAttachment(lp, spl, renderer, job); // emit.c:2918
+  if (open) renderer.endAnchor?.(job);
+}
+
+/**
+ * Label-to-spline attachment polyline (decorate=true): from the label's
+ * bottom-right corner, along the bottom edge to bottom-left, then to the
+ * closest point on the spline. Skipped for all-whitespace label text. Drawn
+ * with the DEFAULT line style and the label's fontcolor, not the edge style.
+ * @see lib/common/emit.c:emit_attachment (1870-1894)
+ */
+function emitAttachment(
+  lp: TextlabelT | undefined,
+  spl: Spline,
+  renderer: RendererPlugin,
+  job: RenderJob,
+): void {
+  if (!lp?.set) return;
+  if (!/\S/.test(lp.text ?? '')) return; // C: skip all-whitespace text
+  const sz = lp.dimen;
+  const a0 = { x: lp.pos.x + sz.x / 2, y: lp.pos.y - sz.y / 2 };
+  const a1 = { x: a0.x - sz.x, y: a0.y };
+  const a2 = dotneatoClosest(spl, lp.pos);
+  const pts = [a0, a1, a2].map((pt) => transformPoint(pt, job));
+  renderer.attachmentPolyline?.(pts, lp.fontcolor || 'black', job);
+}

package/src/gvc/emit-walk.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Node/edge emission walk for the device renderer — C's `emit_view` body.
+ * Split from device.ts to keep that file under the size cap.
+ *
+ * The output order follows the `outputorder` graph attr (chkOrder): `nodesfirst`
+ * → all nodes then all edges (EMIT_SORTED), `edgesfirst` → the reverse
+ * (EMIT_EDGE_SORTED), otherwise C's breadth-first graph walk (emit each node,
+ * then its out-edges' heads + edges).
+ *
+ * @see lib/common/emit.c:emit_view
+ * @see lib/common/emit.c:chkOrder
+ */
+
+import type { Graph } from '../model/graph.js';
+import type { Node } from '../model/node.js';
+import type { Edge } from '../model/edge.js';
+import { buildOutEdgeIndex } from '../model/node.js';
+import type { RendererPlugin } from './context.js';
+import type { RenderJob } from './job.js';
+import { type LayerInfo, nodeInLayer, edgeInLayer } from '../common/layers.js';
+import { renderNode, renderEdge } from './device.js';
+
+/** Whether a node is shown in the current layer (always true off-layer). */
+function nodeShown(info: LayerInfo | undefined, job: RenderJob, n: Node, g: Graph): boolean {
+  return info === undefined || job.numLayers <= 1 || nodeInLayer(info, job.layerNum, n, g);
+}
+
+/** Whether an edge is shown in the current layer (always true off-layer). */
+function edgeShown(info: LayerInfo | undefined, job: RenderJob, e: Edge): boolean {
+  return info === undefined || job.numLayers <= 1 || edgeInLayer(info, job.layerNum, e);
+}
+
+/**
+ * Output order from the `outputorder` graph attr, mirroring C's chkOrder:
+ * `nodesfirst` → EMIT_SORTED, `edgesfirst` → EMIT_EDGE_SORTED, else breadth-first.
+ * @see lib/common/emit.c:chkOrder
+ */
+function chkOrder(g: Graph): 'nodesfirst' | 'edgesfirst' | 'default' {
+  const p = g.attrs.get('outputorder');
+  if (p === 'nodesfirst') return 'nodesfirst';
+  if (p === 'edgesfirst') return 'edgesfirst';
+  return 'default';
+}
+
+/** Emit every node (id order), then every edge. C's EMIT_SORTED branch. */
+function emitNodesThenEdges(
+  g: Graph, renderer: RendererPlugin, job: RenderJob, outIdx: Map<Node, Edge[]>, info?: LayerInfo,
+): void {
+  const done = new Set<Node>();
+  for (const n of g.nodes.values()) {
+    if (nodeShown(info, job, n, g)) renderNode(n, renderer, job, done);
+  }
+  for (const n of g.nodes.values()) {
+    for (const e of outIdx.get(n) ?? []) {
+      if (edgeShown(info, job, e)) renderEdge(e, renderer, job);
+    }
+  }
+}
+
+/** Emit every edge, then every node. C's EMIT_EDGE_SORTED branch. */
+function emitEdgesThenNodes(
+  g: Graph, renderer: RendererPlugin, job: RenderJob, outIdx: Map<Node, Edge[]>, info?: LayerInfo,
+): void {
+  const done = new Set<Node>();
+  for (const n of g.nodes.values()) {
+    for (const e of outIdx.get(n) ?? []) {
+      if (edgeShown(info, job, e)) renderEdge(e, renderer, job);
+    }
+  }
+  for (const n of g.nodes.values()) {
+    if (nodeShown(info, job, n, g)) renderNode(n, renderer, job, done);
+  }
+}
+
+/**
+ * Render nodes and edges per the graph's `outputorder`.
+ * @see lib/common/emit.c:emit_view
+ */
+export function walkNodesAndEdges(g: Graph, renderer: RendererPlugin, job: RenderJob, info?: LayerInfo): void {
+  // One out-edge index instead of n.outEdges(g) per node (O(N·E) → O(E log E));
+  // emission only writes the render device, never g.edges, and the index keeps
+  // outEdges' sorted order so element emission order is unchanged.
+  const outIdx = buildOutEdgeIndex(g);
+  const order = chkOrder(g);
+  if (order === 'nodesfirst') { emitNodesThenEdges(g, renderer, job, outIdx, info); return; }
+  if (order === 'edgesfirst') { emitEdgesThenNodes(g, renderer, job, outIdx, info); return; }
+  // Default: breadth-first graph walk (emit each node, then its out-edges' heads + edges).
+  const done = new Set<Node>();
+  for (const n of g.nodes.values()) {
+    if (nodeShown(info, job, n, g)) renderNode(n, renderer, job, done);
+    for (const e of outIdx.get(n) ?? []) {
+      if (nodeShown(info, job, e.head, g)) renderNode(e.head, renderer, job, done);
+      if (edgeShown(info, job, e)) renderEdge(e, renderer, job);
+    }
+  }
+}

package/src/gvc/image-resolver.ts

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Image byte resolution + browser-safe base64 for inline (data: URI) SVG
+ * image embedding.
+ *
+ * Mirrors `src/gvc/usershape.ts`'s `setImageSizer` pattern (AD3): C resolves
+ * images through a process-global filesystem dictionary
+ * (gvusershape.c ImageDict) that is browser-hostile, so the port exposes a
+ * caller-injected resolver in the same global-registry position instead.
+ * Unlike `ImageSizer` (which only reports intrinsic dimensions for HTML
+ * `<IMG>` layout), `ImageResolver` supplies the actual bytes so the SVG
+ * emitter can inline them as a `data:` URI (AD-1, additive — not a C
+ * behavior; native Graphviz never inlines image bytes).
+ *
+ * @see lib/gvc/gvusershape.c (ImageDict, gvusershape_find/size)
+ */
+
+// ---------------------------------------------------------------------------
+// Resolver registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Caller-supplied image resolver: given a node's `image=`/HTML `<IMG SRC=>`
+ * value, return the raw bytes (optionally with an explicit MIME type), or
+ * `null` when the source cannot be resolved.
+ */
+export type ImageResolver = (
+  src: string,
+) => { bytes: Uint8Array; mime?: string } | Uint8Array | null;
+
+let activeResolver: ImageResolver | null = null;
+
+/**
+ * Register (or clear, with null) the global image resolver consulted when
+ * `RenderOptions.inlineImages` is set. Mirrors gvusershape's process-global
+ * dictionary and `setImageSizer`'s registration shape.
+ */
+export function setImageResolver(fn: ImageResolver | null): void {
+  activeResolver = fn;
+}
+
+// ---------------------------------------------------------------------------
+// MIME inference — @see lib/gvc/gvusershape.c (extension-based format guess)
+// ---------------------------------------------------------------------------
+
+const EXT_MIME: Readonly<Record<string, string>> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+  webp: 'image/webp',
+};
+
+const FALLBACK_MIME = 'application/octet-stream';
+
+/** Infer a MIME type from `src`'s file extension; falls back when unknown. */
+function inferMimeFromSrc(src: string): string {
+  const dot = src.lastIndexOf('.');
+  if (dot < 0 || dot === src.length - 1) return FALLBACK_MIME;
+  const ext = src.slice(dot + 1).toLowerCase();
+  return EXT_MIME[ext] ?? FALLBACK_MIME;
+}
+
+// ---------------------------------------------------------------------------
+// findImageBytes
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve `src` via the registered resolver, normalizing a bare `Uint8Array`
+ * return into `{ bytes, mime }` (inferring `mime` from the `src` extension
+ * when the resolver omits it). Returns `null` when no resolver is set or the
+ * resolver itself returns `null` — the graceful-miss path that keeps the raw
+ * `src` passthrough in `usershape()`.
+ */
+export function findImageBytes(
+  src: string,
+): { bytes: Uint8Array; mime: string } | null {
+  if (activeResolver === null) return null;
+  const result = activeResolver(src);
+  if (result === null) return null;
+  if (result instanceof Uint8Array) {
+    return { bytes: result, mime: inferMimeFromSrc(src) };
+  }
+  return { bytes: result.bytes, mime: result.mime ?? inferMimeFromSrc(src) };
+}
+
+// ---------------------------------------------------------------------------
+// toDataUri — browser-safe base64 (no Buffer, no filesystem)
+// ---------------------------------------------------------------------------
+
+/** Standard base64 alphabet (RFC 4648 §4). */
+const B64_CHARS =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/**
+ * Encode `bytes` as base64 via a manual alphabet table (3 input bytes → 4
+ * output chars per iteration, single pass, no recursion/spread). Chosen over
+ * `btoa` + `String.fromCharCode(...chunk)` so there is no dependency on a
+ * host-global `btoa` (absent in some Worker/CSP-restricted embeds) and no
+ * call-stack risk from spreading large chunks — this loop is O(n) with O(1)
+ * stack depth regardless of input size.
+ */
+function base64Encode(bytes: Uint8Array): string {
+  const len = bytes.length;
+  const out: string[] = [];
+  let i = 0;
+  for (; i + 2 < len; i += 3) {
+    const n = (bytes[i]! << 16) | (bytes[i + 1]! << 8) | bytes[i + 2]!;
+    out.push(
+      B64_CHARS[(n >> 18) & 0x3f]!,
+      B64_CHARS[(n >> 12) & 0x3f]!,
+      B64_CHARS[(n >> 6) & 0x3f]!,
+      B64_CHARS[n & 0x3f]!,
+    );
+  }
+  const remaining = len - i;
+  if (remaining === 1) {
+    const n = bytes[i]! << 16;
+    out.push(B64_CHARS[(n >> 18) & 0x3f]!, B64_CHARS[(n >> 12) & 0x3f]!, '==');
+  } else if (remaining === 2) {
+    const n = (bytes[i]! << 16) | (bytes[i + 1]! << 8);
+    out.push(
+      B64_CHARS[(n >> 18) & 0x3f]!,
+      B64_CHARS[(n >> 12) & 0x3f]!,
+      B64_CHARS[(n >> 6) & 0x3f]!,
+      '=',
+    );
+  }
+  return out.join('');
+}
+
+/** Build a `data:` URI from raw bytes + MIME type. Browser-safe base64. */
+export function toDataUri(bytes: Uint8Array, mime: string): string {
+  return 'data:' + mime + ';base64,' + base64Encode(bytes);
+}