@knowvah/dot-engine 0.1.0

package/src/render/svg-gradient.ts

@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * SVG gradient emitters — ports svg_print_stop, svg_gradstyle, svg_rgradstyle
+ * and get_gradient_points. Separate module to keep svg-helpers.ts < 500 lines (AD5).
+ * @see plugin/core/gvrender_core_svg.c:553 (svg_print_stop)
+ * @see plugin/core/gvrender_core_svg.c:572 (svg_gradstyle)
+ * @see plugin/core/gvrender_core_svg.c:608 (svg_rgradstyle)
+ * @see lib/common/utils.c:1446 (get_gradient_points)
+ */
+
+import type { Point } from '../model/geom.js';
+import type { GVColor } from '../common/color.js';
+import type { RenderJob } from '../gvc/job.js';
+import { escapeXml } from './svg-helpers.js';
+import { cround } from '../common/arith.js';
+
+interface GradientPoints { g0: Point; g1: Point; }
+interface BBox { minX: number; maxX: number; minY: number; maxY: number; }
+
+/** Bounding box for 2-point (center+corner) ellipse input. */
+function bboxFrom2(A: Point[]): BBox {
+  const rx = (A[1] as Point).x - (A[0] as Point).x;
+  const ry = (A[1] as Point).y - (A[0] as Point).y;
+  return {
+    minX: (A[0] as Point).x - rx, maxX: (A[0] as Point).x + rx,
+    minY: (A[0] as Point).y - ry, maxY: (A[0] as Point).y + ry,
+  };
+}
+/** Bounding box by scanning all points. */
+function bboxFromN(A: Point[]): BBox {
+  let minX = (A[0] as Point).x, maxX = (A[0] as Point).x;
+  let minY = (A[0] as Point).y, maxY = (A[0] as Point).y;
+  for (let i = 1; i < A.length; i++) {
+    const p = A[i] as Point;
+    if (p.x < minX) minX = p.x;
+    if (p.x > maxX) maxX = p.x;
+    if (p.y < minY) minY = p.y;
+    if (p.y > maxY) maxY = p.y;
+  }
+  return { minX, maxX, minY, maxY };
+}
+/** Radial points from bbox. isRHS selects native y-up (xdot) vs SVG y-down.
+ * @see lib/common/utils.c:1478 */
+function radialPoints(bb: BBox, cx: number, cy: number, isRHS: boolean): GradientPoints {
+  const outerR = Math.hypot(cx - bb.minX, cy - bb.minY);
+  return { g0: { x: cx, y: isRHS ? cy : -cy }, g1: { x: outerR / 4, y: outerR } };
+}
+/** Linear points from bbox+angle. isRHS selects native y-up (xdot) vs SVG
+ * y-down; mirrors C's isRHS branch (half_y symmetric about center).
+ * @see lib/common/utils.c:1487 */
+function linearPoints(
+  bb: BBox, cx: number, cy: number, angle: number, isRHS: boolean,
+): GradientPoints {
+  const halfX = bb.maxX - cx;
+  const sina = Math.sin(angle), cosa = Math.cos(angle);
+  const gx0 = cx - halfX * cosa, gx1 = cx + halfX * cosa;
+  if (isRHS) {
+    const halfY = bb.maxY - cy;
+    return {
+      g0: { x: gx0, y: cy - halfY * sina },
+      g1: { x: gx1, y: cy + halfY * sina },
+    };
+  }
+  return {
+    g0: { x: gx0, y: -cy + (bb.maxY - cy) * sina },
+    g1: { x: gx1, y: -cy - (cy - bb.minY) * sina },
+  };
+}
+
+/**
+ * Compute gradient endpoints. `isRHS` mirrors C's `flags & 2`: true yields
+ * native y-up (Graphviz) coordinates for the xdot/json device path, false
+ * yields the SVG y-down convention (the default, used by the SVG renderer,
+ * whose top-level `<g transform>` supplies the flip). Linear: g0/g1 =
+ * endpoints. Radial: g0=(cx,±cy), g1=(inner_r,outer_r).
+ * @see lib/common/utils.c:1446 get_gradient_points
+ */
+export function getGradientPoints(
+  A: Point[], angle: number, radial: boolean, isRHS = false,
+): GradientPoints {
+  const bb = A.length === 2 ? bboxFrom2(A) : bboxFromN(A);
+  const cx = bb.minX + (bb.maxX - bb.minX) / 2;
+  const cy = bb.minY + (bb.maxY - bb.minY) / 2;
+  if (radial) return radialPoints(bb, cx, cy, isRHS);
+  return linearPoints(bb, cx, cy, angle, isRHS);
+}
+
+/** Print color for gradient stop; "transparent"→"black" for SVG 1.1 compat.
+ * @see plugin/core/gvrender_core_svg.c:147 svg_print_gradient_color */
+function printGradientColor(job: RenderJob, color: GVColor): void {
+  if (color.type === 'string') {
+    job.write(color.s === 'transparent' ? 'black' : color.s);
+  } else if (color.type === 'rgba') {
+    const rh = Math.round(color.r * 255).toString(16).padStart(2, '0');
+    const gh = Math.round(color.g * 255).toString(16).padStart(2, '0');
+    const bh = Math.round(color.b * 255).toString(16).padStart(2, '0');
+    job.write('#' + rh + gh + bh);
+  }
+}
+/** Emit stop-opacity matching C's svg_print_stop. */
+function emitStopOpacity(job: RenderJob, color: GVColor): void {
+  if (color.type === 'rgba' && Math.round(color.a * 255) < 255) {
+    job.write(String(Math.round(color.a * 255) / 255));
+  } else if (color.type === 'string' && color.s === 'transparent') {
+    job.write('0');
+  } else {
+    job.write('1.');
+  }
+}
+
+/**
+ * Emit one gradient stop. offset: near-0→"0", near-1→"1", else "%.03f".
+ * @see plugin/core/gvrender_core_svg.c:553 svg_print_stop
+ */
+export function emitStop(job: RenderJob, offset: number, color: GVColor): void {
+  if (Math.abs(offset) < 0.0005) {
+    job.write('<stop offset="0" style="stop-color:');
+  } else if (Math.abs(offset - 1) < 0.0005) {
+    job.write('<stop offset="1" style="stop-color:');
+  } else {
+    job.write('<stop offset="' + offset.toFixed(3) + '" style="stop-color:');
+  }
+  printGradientColor(job, color);
+  job.write(';stop-opacity:');
+  emitStopOpacity(job, color);
+  job.write(';\"/>\n');
+}
+
+/**
+ * Gradient element id: [escapeXml(objId)+'_'] + kind+'_'+n.
+ * @see plugin/core/gvrender_core_svg.c:572 svg_gradstyle (id block)
+ */
+export function gradientId(objId: string | null, kind: 'l' | 'r', n: number): string {
+  const prefix = objId !== null ? escapeXml(objId) + '_' : '';
+  return prefix + kind + '_' + String(n);
+}
+
+/** Emit linearGradient coords block (inner helper for emitLinearGradient). */
+function writeLinearGradCoords(job: RenderJob, pts: Point[], id: string, angleDeg: number): void {
+  const { g0, g1 } = getGradientPoints(pts, angleDeg * Math.PI / 180, false);
+  job.write('<defs>\n<linearGradient id="' + id + '"');
+  job.write(' gradientUnits="userSpaceOnUse" ');
+  job.write('x1="'); job.printDouble(g0.x);
+  job.write('" y1="'); job.printDouble(g0.y);
+  job.write('" x2="'); job.printDouble(g1.x);
+  job.write('" y2="'); job.printDouble(g1.y);
+  job.write('" >\n');
+}
+
+/**
+ * Emit `<defs><linearGradient>` + two stops + `</linearGradient></defs>`.
+ * pts in y-up (Graphviz) space. @see plugin/core/gvrender_core_svg.c:572 svg_gradstyle
+ */
+export function emitLinearGradient(job: RenderJob, pts: Point[], id: string): void {
+  const obj = job.obj;
+  if (obj === null) return;
+  writeLinearGradCoords(job, pts, id, obj.gradientAngle);
+  const frac = obj.gradientFrac;
+  emitStop(job, frac > 0 ? frac - 0.001 : 0, obj.fillColor);
+  emitStop(job, frac > 0 ? frac : 1, obj.stopColor);
+  job.write('</linearGradient>\n</defs>\n');
+}
+
+/**
+ * Emit `<defs><radialGradient>` + two stops + `</radialGradient></defs>`.
+ * @see plugin/core/gvrender_core_svg.c:608 svg_rgradstyle
+ */
+export function emitRadialGradient(job: RenderJob, id: string): void {
+  const obj = job.obj;
+  if (obj === null) return;
+  let ifx = 50, ify = 50;
+  if (obj.gradientAngle !== 0) {
+    const angle = obj.gradientAngle * Math.PI / 180;
+    // @see plugin/core/gvrender_core_svg.c:622-623 (round())
+    ifx = cround(50 * (1 + Math.cos(angle)));
+    ify = cround(50 * (1 - Math.sin(angle)));
+  }
+  job.write('<defs>\n<radialGradient id="' + id + '"');
+  job.write(' cx="50%" cy="50%" r="75%"');
+  job.write(' fx="' + String(ifx) + '%" fy="' + String(ify) + '%">\n');
+  emitStop(job, 0, obj.fillColor);
+  emitStop(job, 1, obj.stopColor);
+  job.write('</radialGradient>\n</defs>\n');
+}

package/src/render/svg-graph.ts

@@ -0,0 +1,415 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * SVG document prologue and graph group open/close helpers.
+ * Split from svg-helpers.ts to keep that module under the size cap.
+ *
+ * NOTE: no ${...} template literals here — Lizard bug #2 (see
+ * svg-helpers.ts file header).
+ *
+ * @see plugin/core/gvrender_core_svg.c:svg_begin_graph
+ * @see plugin/core/gvrender_core_svg.c:svg_begin_page
+ */
+
+import type { Graph } from '../model/graph.js';
+import type { Box, Point } from '../model/geom.js';
+import type { RenderJob } from '../gvc/job.js';
+import { createObjState, ObjType } from '../gvc/job.js';
+import { FillType } from '../gvc/context.js';
+import { escapeXml, escapeXmlTitle } from './svg-helpers.js';
+import { resolveRenderColor, colorPaint } from './color-resolve.js';
+import { svgGraphId, svgGraphClass } from './svg-id.js';
+import { parseGradientSpec } from '../common/htmltable-emit-fill.js';
+import { findStopColor, parseStyleFlags } from '../common/style-resolve.js';
+import { cround } from '../common/arith.js';
+import {
+  emitLinearGradient,
+  emitRadialGradient,
+  gradientId,
+} from './svg-gradient.js';
+
+const SVG_XML_DECL =
+  '<?xml version="1.0" encoding="UTF-8" standalone="no"?>\n';
+const SVG_DOCTYPE =
+  '<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"\n' +
+  ' "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">\n';
+const SVG_GENERATOR_COMMENT = '<!-- Generated by graphviz-ts -->\n';
+
+/** Sentinel meaning "emit no background polygon" (bgcolor=transparent on SVG). */
+const BGCOLOR_TRANSPARENT = '\x00transparent';
+
+/**
+ * Resolved gradient spec for a two-color bgcolor.
+ * Groups the fields that emitGradientBackground needs beyond bb+job.
+ * @see lib/common/emit.c:emit_background:1503
+ */
+interface BgGradientSpec {
+  fillColor: string;
+  stopColor: string;
+  frac: number;
+  angle: number;
+  radial: boolean;
+}
+
+/**
+ * Reproduce C's `%g` (6 significant digits, trailing zeros trimmed) used for
+ * the group scale. `1` → "1", `0.12319530…` → "0.123195".
+ * @see plugin/core/gvrender_core_svg.c:314 gvprintf("%g %g", …)
+ */
+function formatG(n: number): string {
+  return String(parseFloat(n.toPrecision(6)));
+}
+
+/**
+ * Emit SVG tag. Group translate absorbs bb.ll + pad + margin/Z offset
+ * (svgBeginPage). ViewBox starts at (round(margin.x), round(margin.y)) --
+ * (0,0) only in the common no-margin case.
+ */
+export function emitSvgTag(job: RenderJob): void {
+  const bb = job.bb;
+  // Size-fitted, UNROUNDED page-oriented view extent (init_job_pagination's
+  // local `imageSize`/`pageSize`, emit.c:1198-1246): sz = bb extent plus pad,
+  // scaled by Z (job.scale, D4). Kept unrounded here so the later
+  // "+ 2*margin" / "+ margin" sums round ONCE, matching C's single
+  // `ROUND((pageSize + 2*margin) * dpi/72)` -- rounding szx/szy first would
+  // double-round and diverge from C at half-integer boundaries.
+  const szx = bb.ur.x - bb.ll.x + 2 * job.pad.x;
+  const szy = bb.ur.y - bb.ll.y + 2 * job.pad.y;
+  const viewX = szx * job.scale.x;
+  const viewY = szy * job.scale.y;
+  // Landscape rotation swaps the view into page orientation (init_job_pagination's
+  // early `imageSize = exch_xyf(imageSize)`, emit.c:1201-1202); job.margin is
+  // read UNSWAPPED in both the width/height and viewBox-UR formulas below,
+  // matching C's `job->width = ROUND(pageSize.x + 2*margin.x)` where `margin`
+  // there is the as-entered graph attribute, never exch_xyf'd before this use.
+  const rotated = job.rotation !== 0;
+  const pageX = rotated ? viewY : viewX;
+  const pageY = rotated ? viewX : viewY;
+  // job->width/job->height (emit.c:1249-1250, dpi=72 so *dpi/72 is a no-op).
+  const w = cround(pageX + 2 * job.margin.x);
+  const h = cround(pageY + 2 * job.margin.y);
+  job.write('<svg width="' + String(w) + 'pt" height="' + String(h) + 'pt"\n');
+  // job->pageBoundingBox (canvasBox.LL = margin+centering, canvasBox.UR = LL +
+  // imageSize, then ROUND -- emit.c:1282-1293). C's rotation-branch double
+  // exch_xy/exch_xyf (canvasBox construction, then the final device-units
+  // swap-back, emit.c:1275-1298) cancels for LL (always plain margin) but NOT
+  // for UR, which ends up paired with the page-oriented (rotation-swapped)
+  // view extent -- i.e. the same `pageX`/`pageY` used for width/height above.
+  const vbLLx = cround(job.margin.x);
+  const vbLLy = cround(job.margin.y);
+  const vbURx = cround(job.margin.x + pageX);
+  const vbURy = cround(job.margin.y + pageY);
+  job.write('     viewBox="' + String(vbLLx) + '.00 ' + String(vbLLy) + '.00 ' +
+    String(vbURx) + '.00 ' + String(vbURy) + '.00"\n');
+  job.write('     xmlns="http://www.w3.org/2000/svg"');
+  job.write(' xmlns:xlink="http://www.w3.org/1999/xlink">\n');
+}
+
+/**
+ * Emit the graph `<g>` open tag with y-flip transform.
+ *
+ * translate(PAD, contentH+PAD) maps graphviz origin (0,0) to the
+ * bottom-left corner of the padded viewport.  Combined with devscale.y=-1,
+ * a node at graphviz (x,y) appears at SVG (x+PAD, h-PAD-y).
+ *
+ * @see plugin/core/gvrender_core_svg.c:svg_begin_page
+ */
+export function emitGraphGroupOpen(
+  graphId: string,
+  classStr: string,
+  tx: number,
+  ty: number,
+  job: RenderJob,
+): void {
+  // Group carries the size= zoom (D4): C's svg_begin_page prints job->scale.x/y
+  // (= zoom for dpi=72). %g, not gvprintdouble (its comment: 2 digits
+  // insufficient); parseFloat(toPrecision(6)) reproduces %g. Z=1 → "1".
+  const sx = formatG(job.scale.x);
+  const sy = formatG(job.scale.y);
+  // rotate(-job->rotation): 0 for portrait (byte-unchanged), -90 for landscape
+  // (orientation=land). @see gvrender_core_svg.c:svg_begin_page
+  const rot = String(-job.rotation);
+  // Escape the assembled id (DOT `id` attr + user-controlled layer prefix) the
+  // way C's svg_print_id_class does via gvputs_xml.
+  job.write('<g id="' + escapeXmlTitle(graphId) + '" ' + classStr +
+    ' transform="scale(' + sx + ' ' + sy + ') rotate(' + rot + ') translate(');
+  job.printDouble(tx);
+  job.write(' ');
+  job.printDouble(ty);
+  job.write(')">\n');
+}
+
+/**
+ * Conditionally emit `<title>` for user-visible graph names.
+ * @see plugin/core/gvrender_core_svg.c:svg_begin_page
+ */
+export function emitGraphTitle(g: Graph, job: RenderJob): void {
+  if (g.name.length > 0 && g.name[0] !== '%') {
+    job.write('<title>' + escapeXmlTitle(g.name) + '</title>\n');
+  }
+}
+
+/**
+ * Resolve the graph bgcolor attribute to the color string to use for the
+ * background polygon, or the BGCOLOR_TRANSPARENT sentinel to suppress it.
+ *
+ * Precedence mirrors emit_background (lib/common/emit.c:1476-1530):
+ *   - absent/empty → "white" (default white paper)
+ *   - "transparent" → BGCOLOR_TRANSPARENT sentinel (SVG is truecolor)
+ *   - gradient "c1:c2" → first solid color (AD3)
+ *   - else → the literal color string
+ *
+ * @see lib/common/emit.c:emit_background:1476
+ */
+export function resolveGraphBgcolor(bgcolorAttr: string | undefined): string {
+  if (!bgcolorAttr || bgcolorAttr.length === 0) return 'white';
+  if (bgcolorAttr === 'transparent') return BGCOLOR_TRANSPARENT;
+  const grad = parseGradientSpec(bgcolorAttr);
+  const solid = grad !== null ? grad[0] : bgcolorAttr;
+  // Canonicalize through the standard resolve path (lowercase #rrggbb, X11-only
+  // names → #rrggbb) exactly as C's emit_background does via
+  // gvrender_resolve_color before painting the background.
+  // @see lib/gvc/gvrender.c:188 gvrender_resolve_color
+  return colorPaint(resolveRenderColor(solid));
+}
+
+/**
+ * Emit background polygon covering the full padded content area.
+ *
+ * Omits the polygon entirely when resolvedColor is the transparent sentinel.
+ * Coordinates are in the group's local frame (y-flipped via devscale.y=-1):
+ *   x: [bb.ll.x - PAD, bb.ur.x + PAD]
+ *   y (flipped): [-(bb.ur.y + PAD), -(bb.ll.y - PAD)]
+ *
+ * @see plugin/core/gvrender_core_svg.c:svg_begin_page
+ * @see lib/common/emit.c:emit_background:1476
+ */
+export function emitGraphBackground(bb: Box, resolvedColor: string, job: RenderJob): void {
+  if (resolvedColor === BGCOLOR_TRANSPARENT) return;
+  const left   = bb.ll.x - job.pad.x;
+  const right  = bb.ur.x + job.pad.x;
+  const top    = -(bb.ur.y + job.pad.y);
+  const bottom = -(bb.ll.y - job.pad.y);
+  const corners: [number, number][] = [
+    [left, bottom], [left, top], [right, top], [right, bottom], [left, bottom],
+  ];
+  job.write('<polygon fill="' + resolvedColor + '" stroke="none" points="');
+  corners.forEach(([px, py], i) => {
+    if (i > 0) job.write(' ');
+    job.printDouble(px);
+    job.write(',');
+    job.printDouble(py);
+  });
+  job.write('"/>\n');
+}
+
+/**
+ * Compute the 4 background-polygon corner points in graphviz (y-up) space.
+ * Passed to getGradientPoints inside emitLinearGradient.
+ * @see lib/common/emit.c:emit_background:1517 (gvrender_box with clip)
+ */
+function bgGradientPts(bb: Box, pad: Point): Point[] {
+  const left   = bb.ll.x - pad.x;
+  const right  = bb.ur.x + pad.x;
+  const bottom = bb.ll.y - pad.y;
+  const top    = bb.ur.y + pad.y;
+  return [
+    { x: left,  y: bottom },
+    { x: left,  y: top    },
+    { x: right, y: top    },
+    { x: right, y: bottom },
+  ];
+}
+
+/**
+ * Write background polygon element with gradient fill url reference.
+ * Coords identical to emitGraphBackground; only fill changes.
+ * @see plugin/core/gvrender_core_svg.c:svg_polygon:686
+ */
+function writeGradientPolygon(bb: Box, id: string, job: RenderJob): void {
+  const left   = bb.ll.x - job.pad.x;
+  const right  = bb.ur.x + job.pad.x;
+  const top    = -(bb.ur.y + job.pad.y);
+  const bottom = -(bb.ll.y - job.pad.y);
+  const corners: [number, number][] = [
+    [left, bottom], [left, top], [right, top], [right, bottom], [left, bottom],
+  ];
+  job.write('<polygon fill="url(#' + id + ')" stroke="none" points="');
+  corners.forEach(([px, py], i) => {
+    if (i > 0) job.write(' ');
+    job.printDouble(px);
+    job.write(',');
+    job.printDouble(py);
+  });
+  job.write('"/>\n');
+}
+
+/**
+ * Emit the gradient background for a graph with a two-color bgcolor.
+ * Pushes a temporary ObjState, emits the <defs> gradient, writes the polygon.
+ *
+ * The gradient id is prefixed "graph0_" to match C's svg_gradstyle behaviour
+ * when obj->id is set: graph0_l_0 / graph0_r_0.
+ *
+ * @see lib/common/emit.c:emit_background:1503-1519
+ * @see plugin/core/gvrender_core_svg.c:svg_gradstyle:572
+ * @see plugin/core/gvrender_core_svg.c:svg_rgradstyle:608
+ */
+function emitGradientBackground(bb: Box, spec: BgGradientSpec, job: RenderJob): void {
+  const obj = createObjState(ObjType.RootGraph);
+  obj.id = 'graph0';
+  obj.fillColor = resolveRenderColor(spec.fillColor);
+  obj.stopColor = resolveRenderColor(spec.stopColor);
+  obj.gradientFrac = spec.frac;
+  obj.gradientAngle = spec.angle;
+  obj.fill = spec.radial ? FillType.Radial : FillType.Linear;
+  job.pushObj(obj);
+  let gid: string;
+  if (spec.radial) {
+    gid = gradientId('graph0', 'r', job.radialGradId++);
+    emitRadialGradient(job, gid);
+  } else {
+    gid = gradientId('graph0', 'l', job.linearGradId++);
+    emitLinearGradient(job, bgGradientPts(bb, job.pad), gid);
+  }
+  job.popObj();
+  writeGradientPolygon(bb, gid, job);
+}
+
+/**
+ * Resolve BgGradientSpec from graph attrs when bgcolor is a two-color spec.
+ * Returns null when bgcolor is not a gradient.
+ * @see lib/common/emit.c:emit_background:1503-1516
+ */
+function resolveBgGradientSpec(g: Graph, bgcolorAttr: string): BgGradientSpec | null {
+  const stop = findStopColor(bgcolorAttr);
+  if (stop === null) return null;
+  const flags = parseStyleFlags(g.attrs.get('style'));
+  const angleStr = g.attrs.get('gradientangle');
+  const angle = angleStr ? (parseInt(angleStr, 10) || 0) : 0;
+  return { fillColor: stop.fillColor, stopColor: stop.stopColor, frac: stop.frac, angle, radial: flags.radial };
+}
+
+/**
+ * Resolve and emit the background — gradient or solid/transparent.
+ * Separated to keep svgBeginGraph under the 30-line body limit.
+ * @see lib/common/emit.c:emit_background:1476
+ */
+function emitBgcolorBackground(g: Graph, bb: Box, bgcolorAttr: string | undefined, job: RenderJob): void {
+  if (!bgcolorAttr || bgcolorAttr.length === 0 || bgcolorAttr === 'transparent') {
+    emitGraphBackground(bb, resolveGraphBgcolor(bgcolorAttr), job);
+    return;
+  }
+  const spec = resolveBgGradientSpec(g, bgcolorAttr);
+  if (spec !== null) {
+    emitGradientBackground(bb, spec, job);
+    return;
+  }
+  emitGraphBackground(bb, resolveGraphBgcolor(bgcolorAttr), job);
+}
+
+/**
+ * Emit SVG prologue, padded `<svg>` tag, graph `<g>` with y-flip transform,
+ * and background polygon (color resolved from bgcolor attr).
+ *
+ * Y-axis: Graphviz y-up vs SVG y-down.  devscale.y=-1 negates all y coords
+ * before renderer callbacks; the graph `<g>` translate(PAD, contentH+PAD)
+ * places the Graphviz origin at the bottom-left of the padded viewport.
+ *
+ * @see plugin/core/gvrender_core_svg.c:svg_begin_graph
+ * @see plugin/core/gvrender_core_svg.c:svg_begin_page
+ * @see lib/common/emit.c:emit_background:1476
+ */
+export function svgBeginGraph(g: Graph, job: RenderJob): void {
+  job.devscale = { x: 1, y: -1 };
+  job.directed = g.kind === 'directed' || g.kind === 'strict-directed';
+  // GD_drawing(root)->id — used as the `<gid>_` prefix for non-root object ids.
+  job.drawingId = g.attrs.get('id') ?? '';
+  job.write(SVG_XML_DECL);
+  // C svg_begin_job emits the stylesheet PI (raw href) between the XML
+  // declaration and the DOCTYPE when the graph has a `stylesheet` attribute.
+  // @see plugin/core/gvrender_core_svg.c:svg_begin_job
+  const stylesheet = g.attrs.get('stylesheet');
+  if (stylesheet !== undefined && stylesheet.length > 0) {
+    // Code review: the `stylesheet` attribute is written raw into the
+    // processing instruction (matches upstream gvrender_core_svg.c:svg_begin_job,
+    // which also does gvputs raw). Revisit if untrusted DOT can set `stylesheet`
+    // and the SVG is embedded inline — a `"?>` sequence breaks out of the PI.
+    // Left faithful to the oracle; hardening is the "origins/CSP" discussion.
+    job.write('<?xml-stylesheet href="' + stylesheet + '" type="text/css"?>\n');
+  }
+  job.write(SVG_DOCTYPE);
+  job.write(SVG_GENERATOR_COMMENT);
+  emitSvgTag(job);
+}
+
+/**
+ * Per-page content: the graph group, title, and background — re-emitted per
+ * layer. The group id carries the layer prefix (e.g. `pvt_graph0`).
+ * @see plugin/core/gvrender_core_svg.c:svg_begin_page
+ */
+export function svgBeginPage(g: Graph, job: RenderJob): void {
+  const bb = job.bb;
+  // gvPostprocess zeroes bb.ll before render; tx is simply the padding.
+  // Landscape (ADR-3): setup_page's rotation branch (SVG = GVRENDER_Y_GOES_DOWN)
+  // gives translation.x = -(focus.x + pageSize.x/2) = -(bb.ur.x + PAD) in the
+  // zeroed-bb frame; translation.y is unchanged (focus.y + pageSize.y/2 =
+  // bb.ur.y + PAD). pageSize = imageSize/zoom is Z-independent (outer scale
+  // carries Z), so the formula holds for any size= fit. Pinned to b68 native
+  // translate(-634 208.5). @see emit.c:setup_page; gvrender_core_svg.c:svg_begin_page
+  //
+  // margin (F6): setup_page adds `canvasBox.LL / job->zoom` on top of the
+  // pad-only formula above -- canvasBox.LL is the FINAL (post swap-cancel)
+  // margin, unswapped regardless of rotation, so both branches use
+  // job.margin.x/y directly. job->zoom is real-C's Z; this port carries Z in
+  // job.scale (job.zoom stays fixed at 1, D4/ADR-2), so divide by job.scale.x
+  // here to reproduce the same "/ job->zoom" C performs. Sign differs by
+  // rotation branch only for x (portrait: +margin.x/Z; landscape: -margin.x/Z);
+  // y is always +margin.y/Z in both branches (C computes translation.y with a
+  // single un-branched formula for GVRENDER_Y_GOES_DOWN renderers).
+  // @see lib/common/emit.c:1566-1582 setup_page (CAUTION comment there)
+  const z = job.scale.x;
+  const tx = job.rotation !== 0
+    ? -(bb.ur.x + job.pad.x) - job.margin.x / z
+    : job.pad.x + job.margin.x / z;
+  const ty = bb.ur.y + job.pad.y + job.margin.y / z;
+  emitGraphGroupOpen(
+    job.idLayerPrefix() + svgGraphId(g, job),
+    svgGraphClass(g),
+    tx, ty, job,
+  );
+  emitGraphTitle(g, job);
+}
+
+/**
+ * Emit the page background polygon. Split out of svg_begin_page so the
+ * device-layer page loop can wrap the background (and the graph label) in the
+ * graph's `<a>` anchor, matching C where emit_background is separate from
+ * gvrender_begin_page.
+ * @see lib/common/emit.c:emit_page (emit_background after begin_page)
+ */
+export function svgPageBackground(g: Graph, job: RenderJob): void {
+  emitBgcolorBackground(g, job.bb, g.attrs.get('bgcolor'), job);
+}
+
+/** Close the graph `<g>` group. @see svg_end_page */
+export function svgEndPage(job: RenderJob): void {
+  job.write('</g>\n');
+}
+
+/** `<g id="<layer>" class="layer">` — only emitted when numLayers > 1. */
+export function svgBeginLayer(name: string, job: RenderJob): void {
+  job.write('<g id="' + escapeXml(name) + '" class="layer">\n');
+}
+
+export function svgEndLayer(job: RenderJob): void {
+  job.write('</g>\n');
+}
+
+/**
+ * Close the graph `<g>` group and the `<svg>` element.
+ * @see plugin/core/gvrender_core_svg.c:svg_end_graph
+ */
+export function svgEndGraph(job: RenderJob): void {
+  job.write('</svg>\n');
+}