@hraness/slopcamera 3.3.4 → 3.3.6

package/src/drawing-pdf.ts

@@ -0,0 +1,210 @@
+/** A closed adapter for the path-only SVG produced by the pinned resvg renderer. */
+interface SvgNode { readonly tag: string; readonly attrs: Readonly<Record<string, string>>; readonly children: SvgNode[] }
+
+function fail(message: string): never { throw new Error(`Unsupported drawing SVG: ${message}`) }
+const maximumSvgBytes = 2 * 1024 * 1024
+
+function attributes(value: string): Record<string, string> {
+  const attrs: Record<string, string> = {}
+  let rest = value
+  while (rest.trim().length > 0) {
+    const match = /^\s+([A-Za-z][A-Za-z0-9:-]*)="([^"<>]*)"/u.exec(rest)
+    if (match === null) fail("malformed attribute")
+    const name = match[1]!
+    if (Object.hasOwn(attrs, name)) fail("duplicate attribute")
+    attrs[name] = match[2]!
+    rest = rest.slice(match[0].length)
+  }
+  return attrs
+}
+
+function parseSvg(svg: string): SvgNode {
+  if (Buffer.byteLength(svg) > maximumSvgBytes) fail("sheet exceeds byte limit")
+  const roots: SvgNode[] = []
+  const stack: SvgNode[] = []
+  let cursor = 0
+  let count = 0
+  for (const token of svg.matchAll(/<[^>]*>/gu)) {
+    if (svg.slice(cursor, token.index).trim() !== "") fail("text outside a path")
+    cursor = token.index + token[0].length
+    const raw = token[0]
+    const closing = /^<\/([A-Za-z]+)>$/u.exec(raw)
+    if (closing !== null) {
+      if (stack.pop()?.tag !== closing[1]) fail("unbalanced tags")
+      continue
+    }
+    const match = /^<([A-Za-z]+)([\s\S]*?)(\/?)>$/u.exec(raw)
+    if (match === null) fail("unsupported markup")
+    const tag = match[1]!
+    if (!["svg", "defs", "clipPath", "g", "path"].includes(tag)) fail(`element ${tag}`)
+    if (++count > 50_000 || stack.length > 32) fail("tree limit exceeded")
+    const node: SvgNode = { tag, attrs: attributes(match[2]!), children: [] }
+    const parent = stack.at(-1)
+    if (parent === undefined) roots.push(node)
+    else parent.children.push(node)
+    if (match[3] !== "/") stack.push(node)
+  }
+  if (svg.slice(cursor).trim() !== "" || stack.length !== 0 || roots.length !== 1 || roots[0]?.tag !== "svg") fail("invalid document")
+  return roots[0]!
+}
+
+function only(node: SvgNode, allowed: readonly string[]): void {
+  for (const key of Object.keys(node.attrs)) if (!allowed.includes(key)) fail(`${node.tag}.${key}`)
+}
+
+function number(value: string): number {
+  if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/u.test(value)) fail("invalid number")
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed) || Math.abs(parsed) > 10_000_000) fail("number outside bounds")
+  return parsed
+}
+
+const decimal = (value: number): string => Number(value.toFixed(6)).toString()
+
+function pathCommands(data: string): string {
+  const tokens = data.match(/[MLCQZ]|[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/gu) ?? []
+  if (data.replace(/[MLCQZ]|[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?|[\s,]/gu, "") !== "") fail("path command")
+  if (tokens.length > 500_000) fail("path limit")
+  const result: string[] = []
+  let cursor = 0
+  let x = 0
+  let y = 0
+  let startX = 0
+  let startY = 0
+  const take = (): number => {
+    const token = tokens[cursor++]
+    if (token === undefined) fail("truncated path")
+    return number(token)
+  }
+  while (cursor < tokens.length) {
+    const command = tokens[cursor++]!
+    if (command === "M" || command === "L") {
+      x = take(); y = take()
+      if (command === "M") { startX = x; startY = y }
+      result.push(`${decimal(x)} ${decimal(y)} ${command === "M" ? "m" : "l"}`)
+    } else if (command === "C") {
+      const values = [take(), take(), take(), take(), take(), take()]
+      x = values[4]!; y = values[5]!
+      result.push(`${values.map(decimal).join(" ")} c`)
+    } else if (command === "Q") {
+      const qx = take(); const qy = take(); const nextX = take(); const nextY = take()
+      result.push(`${[x + 2 * (qx - x) / 3, y + 2 * (qy - y) / 3, nextX + 2 * (qx - nextX) / 3, nextY + 2 * (qy - nextY) / 3, nextX, nextY].map(decimal).join(" ")} c`)
+      x = nextX; y = nextY
+    } else if (command === "Z") {
+      result.push("h"); x = startX; y = startY
+    } else fail("non-absolute path command")
+  }
+  return result.join("\n")
+}
+
+function color(value: string | undefined): "0" | "1" | undefined {
+  if (value === "none") return undefined
+  if (value === undefined || value === "#000000") return "0"
+  if (value === "#ffffff") return "1"
+  return fail("non-monochrome paint")
+}
+
+function svgStream(svg: string, width: number, height: number): string {
+  const root = parseSvg(svg)
+  only(root, ["width", "height", "viewBox", "xmlns"])
+  if (number((root.attrs.width ?? "").replace(/pt$/u, "")) !== width || number((root.attrs.height ?? "").replace(/pt$/u, "")) !== height || root.attrs.viewBox !== `0 0 ${width} ${height}` || root.attrs.xmlns !== "http://www.w3.org/2000/svg") fail("page geometry")
+  const clips = new Map<string, SvgNode>()
+  for (const defs of root.children.filter(node => node.tag === "defs")) {
+    only(defs, [])
+    for (const clip of defs.children) {
+      only(clip, ["id"])
+      if (clip.tag !== "clipPath" || clip.attrs.id === undefined || clips.has(clip.attrs.id) || clip.children.some(child => child.tag !== "path")) fail("clip definition")
+      clips.set(clip.attrs.id, clip)
+    }
+  }
+  const output: string[] = [`q\n1 0 0 -1 0 ${decimal(height)} cm`]
+  const emit = (node: SvgNode): void => {
+    if (node.tag === "defs") return
+    if (node.tag === "g") {
+      only(node, ["transform", "clip-path"])
+      output.push("q")
+      if (node.attrs.transform !== undefined) {
+        const match = /^matrix\(([^)]+)\)$/u.exec(node.attrs.transform)
+        if (match === null) fail("transform")
+        const values = match[1]!.trim().split(/[\s,]+/u).map(number)
+        if (values.length !== 6) fail("matrix")
+        output.push(`${values.map(decimal).join(" ")} cm`)
+      }
+      if (node.attrs["clip-path"] !== undefined) {
+        const id = /^url\(#([A-Za-z0-9_-]+)\)$/u.exec(node.attrs["clip-path"])?.[1]
+        const clip = id === undefined ? undefined : clips.get(id)
+        if (clip === undefined) fail("missing clip")
+        for (const path of clip.children) {
+          only(path, ["d", "fill", "stroke", "fill-rule", "clip-rule"])
+          if (path.children.length > 0) fail("path children")
+          output.push(pathCommands(path.attrs.d ?? ""))
+        }
+        const rules = new Set(clip.children.map(path => path.attrs["clip-rule"] ?? path.attrs["fill-rule"] ?? "nonzero"))
+        if (rules.size !== 1 || !["nonzero", "evenodd"].includes([...rules][0]!)) fail("clip rule")
+        output.push(rules.has("evenodd") ? "W* n" : "W n")
+      }
+      node.children.forEach(emit)
+      output.push("Q")
+      return
+    }
+    if (node.tag !== "path") fail("nested non-path element")
+    only(node, ["d", "fill", "stroke", "stroke-width", "stroke-linecap", "stroke-linejoin", "stroke-miterlimit", "fill-rule", "paint-order"])
+    if (node.children.length > 0) fail("path children")
+    const fill = color(node.attrs.fill)
+    const stroke = color(node.attrs.stroke ?? "none")
+    const cap = ["butt", "round", "square"].indexOf(node.attrs["stroke-linecap"] ?? "butt")
+    const join = ["miter", "round", "bevel"].indexOf(node.attrs["stroke-linejoin"] ?? "miter")
+    const strokeWidth = number(node.attrs["stroke-width"] ?? "1")
+    const miter = number(node.attrs["stroke-miterlimit"] ?? "4")
+    if (cap < 0 || join < 0 || strokeWidth <= 0 || miter < 1) fail("stroke style")
+    const rule = node.attrs["fill-rule"] ?? "nonzero"
+    if (rule !== "nonzero" && rule !== "evenodd") fail("fill rule")
+    const paintOrder = node.attrs["paint-order"] ?? "normal"
+    if (!["normal", "stroke", "stroke fill", "fill stroke", "stroke fill markers", "fill stroke markers"].includes(paintOrder)) fail("paint order")
+    output.push("q", `${strokeWidth} w`, `${cap} J`, `${join} j`, `${miter} M`)
+    if (fill !== undefined) output.push(`${fill} g`)
+    if (stroke !== undefined) output.push(`${stroke} G`)
+    const path = pathCommands(node.attrs.d ?? "")
+    const fillOperator = rule === "evenodd" ? "f*" : "f"
+    if (paintOrder.startsWith("stroke") && stroke !== undefined && fill !== undefined) output.push(path, "S", path, fillOperator)
+    else output.push(path, fill === undefined ? (stroke === undefined ? "n" : "S") : stroke === undefined ? fillOperator : rule === "evenodd" ? "B*" : "B")
+    output.push("Q")
+  }
+  root.children.forEach(emit)
+  output.push("Q")
+  return output.join("\n")
+}
+
+const pdfString = (value: string): string => `<FEFF${Buffer.from(value, "utf16le").swap16().toString("hex")}>`
+
+export function drawingSheetsPdf(
+  sheets: readonly { readonly svg: string; readonly width: number; readonly height: number }[],
+  metadata: { readonly title: string; readonly sourceSha256: string; readonly rendererVersion: string },
+): Uint8Array {
+  if (sheets.length < 1 || sheets.length > 20 || !/^[a-f0-9]{64}$/u.test(metadata.sourceSha256)) throw new Error("Invalid drawing PDF input")
+  const objects: string[] = ["", ""]
+  const pages: number[] = []
+  for (const sheet of sheets) {
+    const stream = svgStream(sheet.svg, sheet.width, sheet.height)
+    const streamId = objects.push(`<< /Length ${Buffer.byteLength(stream)} >>\nstream\n${stream}\nendstream`)
+    pages.push(objects.push(`<< /Type /Page /Parent 2 0 R /MediaBox [0 0 ${decimal(sheet.width)} ${decimal(sheet.height)}] /Resources << >> /Contents ${streamId} 0 R >>`))
+  }
+  objects[0] = "<< /Type /Catalog /Pages 2 0 R >>"
+  objects[1] = `<< /Type /Pages /Count ${pages.length} /Kids [${pages.map(id => `${id} 0 R`).join(" ")}] >>`
+  const infoId = objects.push(`<< /Title ${pdfString(metadata.title)} /Producer ${pdfString(`Slopcamera ${metadata.rendererVersion}`)} /Subject ${pdfString(`source-sha256:${metadata.sourceSha256}; profile:patent-line-art-v1`)} >>`)
+  const chunks: string[] = ["%PDF-1.7\n%Slopcamera vector drawings\n"]
+  const offsets = [0]
+  let offset = Buffer.byteLength(chunks[0]!)
+  for (const [index, object] of objects.entries()) {
+    offsets.push(offset)
+    const chunk = `${index + 1} 0 obj\n${object}\nendobj\n`
+    chunks.push(chunk); offset += Buffer.byteLength(chunk)
+  }
+  // Each cross-reference entry is exactly 20 bytes, including its line ending.
+  const freeEntry = "0000000000 65535 f".padEnd(19, " ") + "\n"
+  const usedEntries = offsets.slice(1).map(value => `${String(value).padStart(10, "0")} 00000 n`.padEnd(19, " ") + "\n").join("")
+  chunks.push(`xref\n0 ${objects.length + 1}\n${freeEntry}${usedEntries}trailer\n<< /Size ${objects.length + 1} /Root 1 0 R /Info ${infoId} 0 R >>\nstartxref\n${offset}\n%%EOF\n`)
+  const bytes = Buffer.from(chunks.join(""))
+  if (bytes.length > 32 * 1024 * 1024) throw new Error("Drawing PDF exceeds output byte limit")
+  return bytes
+}

package/src/drawing.ts

@@ -0,0 +1,293 @@
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference -- packed source types need Bun asset modules
+/// <reference path="./assets.d.ts" />
+import { createHash } from "node:crypto"
+import { constants } from "node:fs"
+import { mkdir, open, rename, rm, writeFile } from "node:fs/promises"
+import { dirname, isAbsolute, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { Resvg } from "@resvg/resvg-js"
+import bookAsset from "./assets/fonts/nebula-sans/NebulaSans-Book.otf" with { type: "file" }
+import boldAsset from "./assets/fonts/nebula-sans/NebulaSans-Bold.otf" with { type: "file" }
+import { drawingSheetsPdf } from "./drawing-pdf.js"
+import { layoutBoxContent } from "./label-layout.js"
+import { parseDiagramSource, parseDiagramSpec } from "./parse.js"
+import { renderSvg } from "./render.js"
+import type { DiagramConfig, DiagramSource, DiagramSpec, ThemeColors } from "./types.js"
+import { SLOPCAMERA_VERSION } from "./version.js"
+
+export const drawingProfile = "patent-line-art-v1" as const
+export const drawingSourceByteLimit = 1024 * 1024
+export const drawingMinimumGlyphHeightPt = 3.2 * 72 / 25.4
+export type DrawingPaper = "us-letter" | "a4"
+export interface DrawingSource {
+  readonly $schema?: string
+  readonly version: 1
+  readonly name: string
+  readonly title?: string
+  readonly paper: DrawingPaper
+  readonly sheets: readonly { readonly figure: number; readonly diagram: DiagramSource }[]
+}
+export interface DrawingCheckResult {
+  readonly profile: typeof drawingProfile
+  readonly paper: DrawingPaper
+  readonly sheetCount: number
+  readonly minGlyphHeightPt: number
+  readonly findings: readonly []
+}
+export interface DrawingReceipt {
+  readonly version: 1
+  readonly profile: typeof drawingProfile
+  readonly rendererVersion: string
+  readonly sourceSha256: string
+  readonly paper: DrawingPaper
+  readonly minGlyphHeightPt: number
+  readonly sheets: readonly { readonly figure: number; readonly widthPt: number; readonly heightPt: number; readonly sha256: string }[]
+  readonly pdfSha256: string
+}
+export interface DrawingRenderResult {
+  readonly artifacts: { readonly source: string; readonly pdf: string; readonly sheets: readonly string[]; readonly receipt: string }
+  readonly checks: DrawingCheckResult
+  readonly receipt: DrawingReceipt
+}
+export class DrawingValidationError extends Error {
+  constructor(message: string) { super(`Invalid drawing source: ${message}`); this.name = "DrawingValidationError" }
+}
+function fail(message: string): never { throw new DrawingValidationError(message) }
+const sha256 = (value: string | Uint8Array): string => createHash("sha256").update(value).digest("hex")
+const assetPath = (asset: string): string => isAbsolute(asset) ? asset : fileURLToPath(new URL(asset, import.meta.url))
+const fontFiles = [assetPath(bookAsset), assetPath(boldAsset)]
+const monochrome: ThemeColors = {
+  background: "#ffffff", foreground: "#000000", muted: "#000000", stroke: "#000000",
+  tones: Object.fromEntries(["neutral", "blue", "orange", "green", "red", "purple", "yellow"].map(tone => [tone, { fill: "#ffffff", stroke: "#000000", text: "#000000" }])) as ThemeColors["tones"],
+}
+const config: DiagramConfig = {
+  font: { family: "Nebula Sans", files: [{ path: fontFiles[0]!, weight: 400 }, { path: fontFiles[1]!, weight: 700 }] },
+  theme: { light: monochrome },
+}
+const escapeXml = (value: string): string => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;")
+
+export function drawingPageGeometry(paper: DrawingPaper) {
+  if (paper !== "us-letter" && paper !== "a4") fail("paper must be us-letter or a4")
+  const width = paper === "us-letter" ? 612 : 210 * 72 / 25.4
+  const height = paper === "us-letter" ? 792 : 297 * 72 / 25.4
+  const margins = { left: 25 * 72 / 25.4, top: 25 * 72 / 25.4, right: 15 * 72 / 25.4, bottom: 10 * 72 / 25.4 }
+  return { width, height, margins, numberingHeight: 30, body: { x: margins.left, y: margins.top + 30, width: width - margins.left - margins.right, height: height - margins.top - margins.bottom - 60 } }
+}
+
+function record(value: unknown, keys: readonly string[], at: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) fail(`${at} must be an object`)
+  const result = value as Record<string, unknown>
+  for (const key of Object.keys(result)) if (!keys.includes(key)) fail(`${at}.${key} is unsupported`)
+  return result
+}
+
+function checkDiagramEnvelope(value: unknown): void {
+  const diagram = record(value, ["$schema", "version", "name", "canvas", "layout", "shapes", "edges"], "diagram")
+  const bounded = (object: Record<string, unknown>): void => {
+    for (const value of Object.values(object)) {
+      if (typeof value === "number" && (!Number.isFinite(value) || Math.abs(value) > 10_000)) fail("numeric drawing values must be finite and within 10000 points")
+      if (typeof value === "string" && value.length > 1024) fail("drawing strings exceed the bounded text limit")
+    }
+  }
+  bounded(diagram)
+  bounded(record(diagram.canvas, ["width", "height", "padding"], "canvas"))
+  if (diagram.layout !== undefined) bounded(record(diagram.layout, ["type", "direction", "gap", "align"], "layout"))
+  if (!Array.isArray(diagram.shapes) || diagram.shapes.length < 1 || diagram.shapes.length > 100) fail("each sheet needs 1 to 100 shapes")
+  for (const value of diagram.shapes) {
+    const shape = record(value, ["id", "type", "x", "y", "tone", "opacity", "width", "height", "radius", "icon", "iconSize", "strokeWidth", "fill", "label", "labelFontSize", "labelFontFamily", "labelWeight", "labelRows", "labelRowGap", "text", "fontSize", "fontFamily", "weight", "align", "x2", "y2"], "shape")
+    bounded(shape)
+    const common = ["id", "type", "x", "y", "tone", "opacity"]
+    const extras = shape.type === "text" ? ["text", "width", "fontSize", "fontFamily", "weight", "align"] : shape.type === "line" ? ["x2", "y2", "strokeWidth"] : ["width", "height", "radius", "icon", "iconSize", "strokeWidth", "fill", "label", "labelFontSize", "labelFontFamily", "labelWeight", "labelRows", "labelRowGap"]
+    record(value, [...common, ...extras], "shape")
+    if (shape.labelRows !== undefined) {
+      if (!Array.isArray(shape.labelRows) || shape.labelRows.length > 4) fail("labelRows must be bounded")
+      for (const row of shape.labelRows) bounded(record(row, ["text", "fontSize", "fontFamily", "weight"], "label row"))
+    }
+    for (const key of ["label", "text"] as const) if (typeof shape[key] === "string" && shape[key].length > 500) fail("label exceeds text limit")
+  }
+  if (diagram.edges !== undefined) {
+    if (!Array.isArray(diagram.edges) || diagram.edges.length > 150) fail("at most 150 edges are supported")
+    for (const edge of diagram.edges) bounded(record(edge, ["id", "from", "to", "label", "tone", "start", "end", "bend", "arrowhead", "startPosition", "endPosition", "labelFontSize", "labelFontFamily", "labelWeight", "labelPosition", "labelOffset"], "edge"))
+  }
+}
+
+export function parseDrawingSource(value: unknown): DrawingSource {
+  const raw = record(value, ["$schema", "version", "name", "title", "paper", "sheets"], "drawing")
+  if (raw.version !== 1) fail("version must be 1")
+  if (typeof raw.name !== "string" || raw.name.length > 100 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(raw.name)) fail("name must be a bounded lowercase hyphenated name")
+  if (raw.paper !== "us-letter" && raw.paper !== "a4") fail("paper must be us-letter or a4")
+  if (raw.title !== undefined && (typeof raw.title !== "string" || raw.title.length < 1 || Buffer.byteLength(raw.title) > 1024 || /[\u0000-\u001f]/u.test(raw.title))) fail("title must be a bounded metadata string")
+  if (raw.$schema !== undefined && typeof raw.$schema !== "string") fail("$schema must be a string")
+  if (!Array.isArray(raw.sheets) || raw.sheets.length < 1 || raw.sheets.length > 20) fail("sheets must contain 1 to 20 sheets")
+  const sheets = raw.sheets.map((sheet: unknown, index: number) => {
+    const entry = record(sheet, ["figure", "diagram"], `sheets[${index}]`)
+    if (entry.figure !== index + 1) fail("figure numbers must be consecutive beginning at 1")
+    checkDiagramEnvelope(entry.diagram)
+    const diagram = parseDiagramSource(entry.diagram)
+    const spec = parseDiagramSpec(diagram)
+    if (spec.shapes.length < 1 || spec.shapes.length > 100 || (spec.edges?.length ?? 0) > 150) fail("each sheet needs 1 to 100 shapes and at most 150 edges")
+    return { figure: index + 1, diagram }
+  })
+  const source: DrawingSource = { version: 1, name: raw.name, paper: raw.paper, sheets, ...(raw.title === undefined ? {} : { title: raw.title as string }), ...(raw.$schema === undefined ? {} : { $schema: raw.$schema as string }) }
+  if (Buffer.byteLength(JSON.stringify(source)) > drawingSourceByteLimit) fail("source exceeds 1MiB byte limit")
+  return source
+}
+
+function renderer(svg: string): Resvg {
+  return new Resvg(svg, { font: { fontFiles, loadSystemFonts: false, defaultFontFamily: "Nebula Sans" }, logLevel: "off" })
+}
+
+interface InkBounds { readonly x: number; readonly y: number; readonly width: number; readonly height: number }
+function bounds(engine: Resvg): InkBounds {
+  const box = engine.getBBox()
+  if (box === undefined) fail("empty drawing ink")
+  return { x: box.x, y: box.y, width: box.width, height: box.height }
+}
+function inside(ink: InkBounds, box: InkBounds, label: string): void {
+  const epsilon = 0.01
+  if (ink.x < box.x - epsilon || ink.y < box.y - epsilon || ink.x + ink.width > box.x + box.width + epsilon || ink.y + ink.height > box.y + box.height + epsilon) fail(`${label} ink extends beyond its bounds`)
+}
+
+async function sceneSvg(spec: DiagramSpec): Promise<string> {
+  return (await renderSvg(spec, "light", config, { edgeStrokeWidth: 1 })).svg.replace('<rect width="100%" height="100%" fill="#ffffff"/>', "")
+}
+
+function glyphHeight(character: string, fontSize: number, weight: number): number {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="1000"><text x="100" y="500" font-family="Nebula Sans" font-size="${fontSize}" font-weight="${weight}">${escapeXml(character)}</text></svg>`
+  return bounds(renderer(svg)).height
+}
+
+function inspectLabels(spec: DiagramSpec, glyphCache: Map<string, number>): number {
+  let minimum = Infinity
+  const inspect = (text: string, fontSize: number, weight: number, family?: string): void => {
+    if (text.length < 1 || text.length > 500 || !Array.from(text).every(character => /^[A-Z0-9 \n]$/u.test(character) || ".,:;()[]/+=_*'!?%-".includes(character))) fail("visible labels must be uppercase ASCII letters, numbers, spaces, or supported punctuation; labels are never rewritten")
+    if (family !== undefined && family !== "default") fail("only the bundled default font is supported")
+    if (!Number.isFinite(fontSize) || fontSize <= 0 || fontSize > 18) fail("authored font size must be positive and at most 18 points, below the 20 point sheet numbering")
+    for (const character of new Set(text.match(/[A-Z0-9]/gu) ?? [])) {
+      const key = `${character}:${fontSize}:${weight}`
+      const measured = glyphCache.get(key) ?? glyphHeight(character, fontSize, weight)
+      glyphCache.set(key, measured)
+      if (glyphCache.size > 4096) fail("glyph measurement limit exceeded")
+      minimum = Math.min(minimum, measured)
+      if (measured + 0.001 < drawingMinimumGlyphHeightPt) fail(`glyph ${character} has ${measured.toFixed(3)}pt ink height; minimum is ${drawingMinimumGlyphHeightPt.toFixed(3)}pt (3.2mm)`)
+    }
+  }
+  for (const shape of spec.shapes) {
+    if (shape.tone !== undefined && shape.tone !== "neutral") fail("colored tones are unsupported; author monochrome relationships explicitly")
+    if (shape.opacity !== undefined && shape.opacity !== 1) fail("transparency is unsupported")
+    if (shape.type === "rect" || shape.type === "ellipse") {
+      if (shape.icon !== undefined) fail("icons are unsupported")
+      if ((shape.strokeWidth ?? 2) < 0.5 || (shape.strokeWidth ?? 2) > 4) fail("stroke width must be 0.5 to 4 points")
+      for (const row of layoutBoxContent(shape).rows) inspect(row.text, row.fontSize, row.weight, row.fontFamily)
+    } else if (shape.type === "text") inspect(shape.text, shape.fontSize ?? 24, shape.weight ?? 500, shape.fontFamily)
+    else if ((shape.strokeWidth ?? 3) < 0.5 || (shape.strokeWidth ?? 3) > 4) fail("stroke width must be 0.5 to 4 points")
+  }
+  for (const edge of spec.edges ?? []) {
+    if (edge.tone !== undefined && edge.tone !== "neutral") fail("colored edge tones are unsupported")
+    if (edge.label !== undefined) inspect(edge.label, edge.labelFontSize ?? 18, edge.labelWeight ?? 600, edge.labelFontFamily)
+  }
+  return minimum
+}
+
+export async function renderDrawing(input: DrawingSource, sourceSha256?: string): Promise<{
+  readonly sheets: readonly { readonly svg: string; readonly width: number; readonly height: number; readonly figure: number }[]
+  readonly pdf: Uint8Array
+  readonly checks: DrawingCheckResult
+}> {
+  const source = parseDrawingSource(input)
+  const sourceDigest = sourceSha256 ?? sha256(JSON.stringify(source))
+  if (!/^[a-f0-9]{64}$/u.test(sourceDigest)) fail("source SHA-256 is invalid")
+  const geometry = drawingPageGeometry(source.paper)
+  const sheets: { svg: string; width: number; height: number; figure: number }[] = []
+  const cache = new Map<string, number>()
+  let minGlyphHeightPt = Infinity
+  for (const sheet of source.sheets) {
+    const spec = parseDiagramSpec(sheet.diagram)
+    if (spec.canvas.width > geometry.body.width + 0.001 || spec.canvas.height > geometry.body.height + 0.001) fail(`figure ${sheet.figure} canvas exceeds ${geometry.body.width.toFixed(3)} by ${geometry.body.height.toFixed(3)}pt body; no automatic scaling is performed`)
+    minGlyphHeightPt = Math.min(minGlyphHeightPt, inspectLabels(spec, cache))
+    const sourceSvg = await sceneSvg(spec)
+    inside(bounds(renderer(sourceSvg)), { x: 0, y: 0, width: spec.canvas.width, height: spec.canvas.height }, `figure ${sheet.figure}`)
+    for (const shape of spec.shapes) {
+      if ((shape.type === "rect" || shape.type === "ellipse") && (shape.label !== undefined || shape.labelRows !== undefined)) {
+        const inset = (shape.strokeWidth ?? 2) / 2
+        const single = await sceneSvg({ ...spec, shapes: [shape], edges: [] })
+        inside(bounds(renderer(single)), { x: shape.x - inset, y: shape.y - inset, width: shape.width + inset * 2, height: shape.height + inset * 2 }, `shape ${shape.id} label`)
+      }
+    }
+    const diagramBody = sourceSvg.replace(/^<svg[^>]*>/u, "").replace(/<\/svg>$/u, "")
+    const x = geometry.body.x + (geometry.body.width - spec.canvas.width) / 2
+    const counter = `${sheet.figure}/${source.sheets.length}`
+    const figureLabel = source.sheets.length === 1 ? "" : `<text x="${geometry.width / 2}" y="${geometry.height - geometry.margins.bottom - 8}" text-anchor="middle" font-size="20" font-family="Nebula Sans" font-weight="400">FIG. ${sheet.figure}</text>`
+    const page = `<svg xmlns="http://www.w3.org/2000/svg" width="${geometry.width}" height="${geometry.height}" viewBox="0 0 ${geometry.width} ${geometry.height}"><rect width="100%" height="100%" fill="#ffffff"/><text x="${geometry.width / 2}" y="${geometry.margins.top + 21}" text-anchor="middle" font-size="20" font-family="Nebula Sans" font-weight="400">${counter}</text><g transform="translate(${x} ${geometry.body.y})">${diagramBody}</g>${figureLabel}</svg>`
+    const outlined = renderer(page).toString().replace(/width="[^"]+" height="[^"]+" viewBox="[^"]+"/u, `width="${geometry.width}pt" height="${geometry.height}pt" viewBox="0 0 ${geometry.width} ${geometry.height}"`)
+    if (Buffer.byteLength(outlined) > 2 * 1024 * 1024) fail("sheet SVG exceeds output byte limit")
+    sheets.push({ svg: outlined, width: geometry.width, height: geometry.height, figure: sheet.figure })
+  }
+  // Numbering is subject to the same measured-glyph rule as authored content.
+  for (const character of "FIG0123456789") minGlyphHeightPt = Math.min(minGlyphHeightPt, glyphHeight(character, 20, 400))
+  if (minGlyphHeightPt + 0.001 < drawingMinimumGlyphHeightPt) fail("sheet numbering falls below minimum glyph height")
+  const checks: DrawingCheckResult = { profile: drawingProfile, paper: source.paper, sheetCount: source.sheets.length, minGlyphHeightPt, findings: [] }
+  return { sheets, checks, pdf: drawingSheetsPdf(sheets, { title: source.title ?? source.name, sourceSha256: sourceDigest, rendererVersion: SLOPCAMERA_VERSION }) }
+}
+
+export async function readDrawingFile(filePath: string) {
+  const absolutePath = resolve(filePath)
+  if (!absolutePath.endsWith(".drawing.json")) fail("source filename must end in .drawing.json")
+  const descriptor = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  let bytes: Buffer
+  try {
+    const info = await descriptor.stat()
+    if (!info.isFile()) fail("source must be a regular file")
+    if (info.size > drawingSourceByteLimit) fail("source exceeds 1MiB byte limit")
+    const buffer = Buffer.alloc(drawingSourceByteLimit + 1)
+    let cursor = 0
+    while (cursor < buffer.length) {
+      const result = await descriptor.read(buffer, cursor, buffer.length - cursor, cursor)
+      if (result.bytesRead === 0) break
+      cursor += result.bytesRead
+    }
+    if (cursor > drawingSourceByteLimit) fail("source exceeds 1MiB byte limit")
+    bytes = buffer.subarray(0, cursor)
+  } finally { await descriptor.close() }
+  const raw: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes))
+  return { absolutePath, source: parseDrawingSource(raw), sourceSha256: sha256(bytes) }
+}
+export async function checkDrawingFile(options: { readonly filePath: string }): Promise<DrawingCheckResult> {
+  const { source, sourceSha256 } = await readDrawingFile(options.filePath)
+  return (await renderDrawing(source, sourceSha256)).checks
+}
+async function atomicWrite(filePath: string, data: string | Uint8Array): Promise<void> {
+  const temporary = `${filePath}.tmp-${process.pid}-${crypto.randomUUID()}`
+  try { await writeFile(temporary, data); await rename(temporary, filePath) }
+  catch (error) { await rm(temporary, { force: true }); throw error }
+}
+export async function renderDrawingFile(options: { readonly filePath: string; readonly outDirectory?: string }): Promise<DrawingRenderResult> {
+  const { absolutePath, source, sourceSha256 } = await readDrawingFile(options.filePath)
+  const result = await renderDrawing(source, sourceSha256)
+  const outDirectory = resolve(options.outDirectory ?? dirname(absolutePath))
+  const artifacts = { source: absolutePath, pdf: join(outDirectory, `${source.name}.pdf`), sheets: result.sheets.map((_, index) => join(outDirectory, `${source.name}.sheet-${String(index + 1).padStart(3, "0")}.svg`)), receipt: join(outDirectory, `${source.name}.drawing-receipt.json`) }
+  const receipt: DrawingReceipt = { version: 1, profile: drawingProfile, rendererVersion: SLOPCAMERA_VERSION, sourceSha256, paper: source.paper, minGlyphHeightPt: result.checks.minGlyphHeightPt, sheets: result.sheets.map(sheet => ({ figure: sheet.figure, widthPt: sheet.width, heightPt: sheet.height, sha256: sha256(sheet.svg) })), pdfSha256: sha256(result.pdf) }
+  await mkdir(outDirectory, { recursive: true })
+  // Validate every sheet before making any derived output visible; write receipt last.
+  for (const [index, sheet] of result.sheets.entries()) await atomicWrite(artifacts.sheets[index]!, sheet.svg)
+  await atomicWrite(artifacts.pdf, result.pdf)
+  await atomicWrite(artifacts.receipt, `${JSON.stringify(receipt, null, 2)}\n`)
+  return { artifacts, checks: result.checks, receipt }
+}
+
+export function starterDrawingSource(): DrawingSource {
+  return {
+    $schema: "https://raw.githubusercontent.com/hraness/slopcamera/main/schema/drawing.schema.json",
+    version: 1, name: "sensor-control", title: "Fictional sensor and controller drawings", paper: "us-letter",
+    sheets: [
+      { figure: 1, diagram: { version: 1, name: "sensor-system", canvas: { width: 480, height: 500 }, shapes: [
+        { id: "sensor", type: "rect", x: 105, y: 40, width: 280, height: 100, radius: 0, label: "SENSOR 100", labelFontSize: 16 },
+        { id: "controller", type: "rect", x: 105, y: 280, width: 280, height: 100, radius: 0, label: "CONTROLLER 200", labelFontSize: 16 },
+      ], edges: [{ id: "signal", from: "sensor", to: "controller", label: "SIGNAL", labelFontSize: 16 }] } },
+      { figure: 2, diagram: { version: 1, name: "control-flow", canvas: { width: 480, height: 500 }, shapes: [
+        { id: "receive", type: "rect", x: 105, y: 40, width: 280, height: 100, radius: 0, label: "RECEIVE SIGNAL 210", labelFontSize: 16 },
+        { id: "actuate", type: "rect", x: 105, y: 280, width: 280, height: 100, radius: 0, label: "SET OUTPUT 220", labelFontSize: 16 },
+      ], edges: [{ id: "next", from: "receive", to: "actuate" }] } },
+    ],
+  }
+}

package/src/index.ts

@@ -12,6 +12,16 @@ import {
 import { generateSlopcameraIcon } from "./icon.js"
 import { generateSlopcameraImageGallery } from "./image-gallery.js"
 import { builtInIcons } from "./icons.js"
+import {
+  checkDrawingFile,
+  drawingPageGeometry,
+  DrawingValidationError,
+  parseDrawingSource,
+  readDrawingFile,
+  renderDrawing,
+  renderDrawingFile,
+  starterDrawingSource,
+} from "./drawing.js"
 import {
   resolveDiagramSource,
   resolveStackLayout,
@@ -57,6 +67,9 @@ export const slopcameraApi = Object.freeze({
   builtInIcons,
   bundledSkillPath,
   checkDiagramFile,
+  checkDrawingFile,
+  drawingPageGeometry,
+  DrawingValidationError,
   defineSlopcameraWorkflow,
   DiagramValidationError,
   generateSlopcameraImage,
@@ -76,8 +89,12 @@ export const slopcameraApi = Object.freeze({
   mcpSourceByteLimit,
   parseDiagramSource,
   parseDiagramSpec,
+  parseDrawingSource,
   readDiagramFile,
+  readDrawingFile,
   renderDiagramFile,
+  renderDrawing,
+  renderDrawingFile,
   renderPng,
   renderSvg,
   resolveEdge,
@@ -88,6 +105,7 @@ export const slopcameraApi = Object.freeze({
   searchSlopcameraOperations,
   serializeTldr,
   stackLayoutDefaults,
+  starterDrawingSource,
   StackLayoutError,
   SlopcameraWorkflowError,
   vectorizeImage,
@@ -144,6 +162,7 @@ export {
 }
 export * from "./capability-manifest.js"
 export * from "./cloud-errors.js"
+export * from "./drawing.js"
 export * from "./generate.js"
 export * from "./host-resources.js"
 export * from "./icon.js"

package/src/render.ts

@@ -332,7 +332,7 @@ export function resolveEdgeLabel(resolved: ResolvedEdge): {
   }
 }
 
-function edgeSvg(resolved: ResolvedEdge, theme: ThemeColors, families: FontFamilies): string {
+function edgeSvg(resolved: ResolvedEdge, theme: ThemeColors, families: FontFamilies, strokeWidth: number): string {
   const { edge, start, end, control } = resolved
   const toneName = edge.tone ?? "neutral"
   const tone = theme.tones[toneName]
@@ -348,7 +348,7 @@ function edgeSvg(resolved: ResolvedEdge, theme: ThemeColors, families: FontFamil
     edge.label === undefined
       ? ""
       : `<text x="${labelPoint.x}" y="${labelPoint.y}" text-anchor="middle" dominant-baseline="central" fill="${tone.text}" stroke="${theme.background}" stroke-width="6" paint-order="stroke" font-family="${escapeXml(families[edge.labelFontFamily ?? "default"])}" font-size="${edge.labelFontSize ?? 18}" font-weight="${edge.labelWeight ?? 600}">${escapeXml(edge.label)}</text>`
-  return `<g data-edge-id="${escapeXml(edge.id)}"><path d="${path}" fill="none" stroke="${tone.stroke}" stroke-width="3" stroke-linecap="round" marker-end="${marker}"/>${label}</g>`
+  return `<g data-edge-id="${escapeXml(edge.id)}"><path d="${path}" fill="none" stroke="${tone.stroke}" stroke-width="${strokeWidth}" stroke-linecap="round" marker-end="${marker}"/>${label}</g>`
 }
 
 function shapeSvg(
@@ -382,7 +382,10 @@ export async function renderSvg(
   spec: DiagramSpec,
   mode: ColorMode,
   config: DiagramConfig,
+  options: { readonly edgeStrokeWidth?: number } = {},
 ): Promise<RenderedDiagram> {
+  const edgeStrokeWidth = options.edgeStrokeWidth ?? 3
+  if (!Number.isFinite(edgeStrokeWidth) || edgeStrokeWidth < 0.5 || edgeStrokeWidth > 4) throw new Error("Edge stroke width must be between 0.5 and 4")
   const theme = resolveTheme(mode, config)
   const font = config.font ?? defaultFont
   const families: FontFamilies = {
@@ -400,7 +403,7 @@ export async function renderSvg(
     )
     .join("")
   const edgeMarkup = (spec.edges ?? [])
-    .map((edge) => edgeSvg(resolveEdge(spec, edge), theme, families))
+    .map((edge) => edgeSvg(resolveEdge(spec, edge), theme, families, edgeStrokeWidth))
     .join("")
   const shapeMarkup = spec.shapes
     .map((shape) => shapeSvg(shape, theme, families, icons))

package/src/version.ts

@@ -1 +1 @@
-export const SLOPCAMERA_VERSION = "3.3.4" as const
+export const SLOPCAMERA_VERSION = "3.3.6" as const