@shibayama/pdgkit 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,214 @@
+import { Lang, DiagramKind, Diagnostic } from './core.cjs';
+export { Bilingual, Box, Containment, Doc, Edge, EdgeOp, LabelPlacement, LaidOut, LaidOutEdge, LaidOutNode, Node, OP_TABLE, PATTERN_LABEL, PATTERN_SOURCE, PatternId, RenderOptions, SAMPLES, SAMPLE_ORDER, SampleId, Shape, chooseLabelPlacement, estimateTextWidth, layout, parse, refsToCsv, refsToMarkdown, render, splitBilingual, stripComment } from './core.cjs';
+
+/**
+ * Minimal, zero-dependency SVG DOM shim. Implements the few element operations the
+ * renderer needs (createElementNS, setAttribute, appendChild, textContent) and
+ * serializes the tree to XML. `withShimDocument()` scopes the shim around a render
+ * call, so rendering also works in a real browser without altering the page's document.
+ */
+/** A serializable SVG node. The shape `render()` actually produces and consumes. */
+interface SvgNode {
+    readonly nodeType: 'element';
+    tagName: string;
+    namespaceURI: string;
+    /** Attribute names in insertion order, mapped to string values. */
+    attrs: Map<string, string>;
+    children: SvgNode[];
+    /** Text content, or null when the element holds child elements instead. */
+    text: string | null;
+    setAttribute(name: string, value: string): void;
+    getAttribute(name: string): string | null;
+    removeAttribute(name: string): void;
+    appendChild(child: SvgNode): SvgNode;
+    set textContent(value: string);
+    get textContent(): string;
+}
+/**
+ * Install the shim as `globalThis.document`, idempotently, but only when no DOM
+ * with `createElementNS` is already present. In a real browser this is a no-op,
+ * so the same code path serves both environments.
+ */
+declare function installDomShim(): void;
+/**
+ * Serialize a shim element tree to an XML string. Produces self-closing tags for
+ * empty elements and correctly escapes attribute values and text content.
+ */
+declare function serializeSvg(node: SvgNode): string;
+
+/**
+ * Compute the tight content bounding box of a rendered SVG tree analytically
+ * (without `getBBox`), by walking the element tree and measuring each primitive;
+ * text width reuses {@link estimateTextWidth}. Used to crop exports to the drawn
+ * extent. Also provides raster and display dimension helpers.
+ */
+
+interface ViewBox {
+    minX: number;
+    minY: number;
+    width: number;
+    height: number;
+}
+/**
+ * Compute the tight content bounding box of a rendered SVG tree, padded by `bleed`
+ * (default 3 units).
+ */
+declare function computeContentBox(root: SvgNode, bleed?: number): ViewBox;
+/**
+ * Display dimensions for a viewBox so the long side is at least `targetSide` px
+ * (browser default: 1600). Mirrors `svgDisplayDimensionsForViewBox()`.
+ */
+declare function svgDisplayDimensions(viewBox: Pick<ViewBox, 'width' | 'height'>, targetSide?: number): {
+    width: number;
+    height: number;
+    scale: number;
+};
+
+/**
+ * Headless SVG rendering: `.pdg` source -> standalone SVG string.
+ * Crops to the real drawn extent (bleed 3) and sizes the document so the long side
+ * is at least `targetSide` px (default 1600).
+ */
+
+interface RenderToSvgOptions {
+    /** Display language: 'ja' (default), 'en', or 'both' (bilingual two-line labels). */
+    lang?: Lang;
+    /** Crop to the real drawn extent (default true). When false, uses the full canvas. */
+    crop?: boolean;
+    /** Padding added around the content box, in user units (default 3). */
+    bleed?: number;
+    /** Minimum long-side length in px for the width/height attributes (default 1600). */
+    targetSide?: number;
+    /** Prepend an `<?xml ... ?>` declaration (default true). */
+    xmlDeclaration?: boolean;
+}
+interface RenderToSvgResult {
+    /** The serialized standalone SVG document. */
+    svg: string;
+    /** The diagram kind inferred from the source. */
+    kind: DiagramKind;
+    /** The viewBox used (content box when cropped). */
+    viewBox: ViewBox;
+    /** Display width in px (the `width` attribute). */
+    width: number;
+    /** Display height in px (the `height` attribute). */
+    height: number;
+}
+/**
+ * Render `.pdg` source to a standalone SVG string. Synchronous and dependency-free.
+ */
+declare function renderToSvg(source: string, opts?: RenderToSvgOptions): RenderToSvgResult;
+
+/**
+ * Validation for AI authoring. Runs the core parser and adds a kind assertion and
+ * friendly lints, returning all diagnostics.
+ *
+ *   - Kind assertion: an optional `#! kind: block|flow|state|seq` directive (written
+ *     in a comment) is checked against the kind inferred from structure; a mismatch
+ *     is reported as an error. Guards against producing the wrong diagram type.
+ *   - Lints: clearer hints for chained connections (`A -> B -> C`) and operators
+ *     without surrounding spaces (`11-12`).
+ *
+ * Run on AI-generated `.pdg` and feed the diagnostics back until there are no errors.
+ */
+
+interface ValidateResult {
+    /** True when there are no error-severity diagnostics. */
+    ok: boolean;
+    /** The diagram kind inferred from the source structure. */
+    kind: DiagramKind;
+    /** The diagram kind the author declared via directive, or null if none. */
+    declaredKind: DiagramKind | null;
+    /** Whether the declared kind matches the inferred kind (null if not declared). */
+    kindMatches: boolean | null;
+    /** All diagnostics (parser + pdgkit lints), sorted by line then column. */
+    diagnostics: Diagnostic[];
+    counts: {
+        errors: number;
+        warnings: number;
+        infos: number;
+    };
+}
+/**
+ * Validate a `.pdg` source string. Pure and synchronous — safe to call in any
+ * environment, including a hot AI authoring loop.
+ */
+declare function validate(source: string): ValidateResult;
+
+/**
+ * Raster output (PNG / JPEG) via `@resvg/resvg-js`, with the bundled IPAex Gothic
+ * font embedded and a white background. Default scale is 8x the content box (capped
+ * to 24000 px/side and 1e8 px total). Native dependencies are imported lazily.
+ */
+
+interface RasterOptions {
+    lang?: Lang;
+    /** Resolution multiplier applied to the cropped content box (default 8). */
+    scale?: number;
+    /** Padding around the content box, in user units (default 3). */
+    bleed?: number;
+}
+/** Render `.pdg` source to a PNG (8× by default, white background). */
+declare function renderToPng(source: string, opts?: RasterOptions): Promise<Uint8Array>;
+/** Render `.pdg` source to a JPEG (8× by default, white background). */
+declare function renderToJpeg(source: string, opts?: RasterOptions): Promise<Uint8Array>;
+
+/**
+ * PDF output (A4, IPAex font embedded). Vector by default (jsPDF + svg2pdf.js under
+ * jsdom, with analytic getBBox / getComputedTextLength shims), falling back to a
+ * high-resolution raster PDF if the vector path fails. The figure is centered with
+ * a 10 mm margin and the page orientation follows its aspect ratio.
+ */
+
+interface PdfOptions {
+    lang?: Lang;
+    /** Padding around the content box, in user units (default 3). */
+    bleed?: number;
+    /** Prefer vector output; fall back to raster on failure (default true). */
+    vector?: boolean;
+    /** Raster resolution multiplier for the raster path (default 8). */
+    scale?: number;
+}
+/** Render `.pdg` source to a PDF (A4, IPAex font, vector preferred). */
+declare function renderToPdf(source: string, opts?: PdfOptions): Promise<Uint8Array>;
+
+/**
+ * PPTX output: `.pdg` → PowerPoint presentation (one 16:9 slide).
+ *
+ *   - image mode (default): the figure is rasterized (resvg) and placed as a
+ *     centered picture — highest visual fidelity.
+ *   - editable mode (`editable: true`): every SVG primitive is converted to an
+ *     editable PowerPoint shape / connector / text box, for later tweaking.
+ */
+
+interface PptxOptions {
+    lang?: Lang;
+    /** Emit editable PowerPoint shapes instead of a single image (default false). */
+    editable?: boolean;
+    /** Raster resolution multiplier for image mode (default 8). */
+    scale?: number;
+    /** Padding around the content box, in user units (default 3). */
+    bleed?: number;
+}
+/** Render `.pdg` source to a PPTX (image by default, or editable shapes). */
+declare function renderToPptx(source: string, opts?: PptxOptions): Promise<Uint8Array>;
+
+/**
+ * pdgkit Node API — the browser-free rendering surface a host tool calls.
+ *
+ * Implemented: SVG, PNG, JPEG, PDF, PPTX (image + editable), validation, and the
+ * reference-sign table exporters. All run with no browser.
+ */
+
+/** The pdgkit package version. Keep in sync with package.json. */
+declare const VERSION = "0.1.0";
+/** Convenience: render to SVG and return just the string. */
+declare function toSvgString(source: string, lang?: Lang): string;
+/**
+ * Read the bundled AI authoring guide (docs/ai-authoring-guide.md) as a string.
+ * Inject this into an LLM's system prompt so it can write valid `.pdg`, instead of
+ * pasting the guide by hand.
+ */
+declare function loadAuthoringGuide(): string;
+
+export { Diagnostic, DiagramKind, Lang, type PdfOptions, type PptxOptions, type RasterOptions, type RenderToSvgOptions, type RenderToSvgResult, type SvgNode, VERSION, type ValidateResult, type ViewBox, computeContentBox, installDomShim, loadAuthoringGuide, renderToJpeg, renderToPdf, renderToPng, renderToPptx, renderToSvg, serializeSvg, svgDisplayDimensions, toSvgString, validate };

package/dist/index.d.ts

@@ -0,0 +1,214 @@
+import { Lang, DiagramKind, Diagnostic } from './core.js';
+export { Bilingual, Box, Containment, Doc, Edge, EdgeOp, LabelPlacement, LaidOut, LaidOutEdge, LaidOutNode, Node, OP_TABLE, PATTERN_LABEL, PATTERN_SOURCE, PatternId, RenderOptions, SAMPLES, SAMPLE_ORDER, SampleId, Shape, chooseLabelPlacement, estimateTextWidth, layout, parse, refsToCsv, refsToMarkdown, render, splitBilingual, stripComment } from './core.js';
+
+/**
+ * Minimal, zero-dependency SVG DOM shim. Implements the few element operations the
+ * renderer needs (createElementNS, setAttribute, appendChild, textContent) and
+ * serializes the tree to XML. `withShimDocument()` scopes the shim around a render
+ * call, so rendering also works in a real browser without altering the page's document.
+ */
+/** A serializable SVG node. The shape `render()` actually produces and consumes. */
+interface SvgNode {
+    readonly nodeType: 'element';
+    tagName: string;
+    namespaceURI: string;
+    /** Attribute names in insertion order, mapped to string values. */
+    attrs: Map<string, string>;
+    children: SvgNode[];
+    /** Text content, or null when the element holds child elements instead. */
+    text: string | null;
+    setAttribute(name: string, value: string): void;
+    getAttribute(name: string): string | null;
+    removeAttribute(name: string): void;
+    appendChild(child: SvgNode): SvgNode;
+    set textContent(value: string);
+    get textContent(): string;
+}
+/**
+ * Install the shim as `globalThis.document`, idempotently, but only when no DOM
+ * with `createElementNS` is already present. In a real browser this is a no-op,
+ * so the same code path serves both environments.
+ */
+declare function installDomShim(): void;
+/**
+ * Serialize a shim element tree to an XML string. Produces self-closing tags for
+ * empty elements and correctly escapes attribute values and text content.
+ */
+declare function serializeSvg(node: SvgNode): string;
+
+/**
+ * Compute the tight content bounding box of a rendered SVG tree analytically
+ * (without `getBBox`), by walking the element tree and measuring each primitive;
+ * text width reuses {@link estimateTextWidth}. Used to crop exports to the drawn
+ * extent. Also provides raster and display dimension helpers.
+ */
+
+interface ViewBox {
+    minX: number;
+    minY: number;
+    width: number;
+    height: number;
+}
+/**
+ * Compute the tight content bounding box of a rendered SVG tree, padded by `bleed`
+ * (default 3 units).
+ */
+declare function computeContentBox(root: SvgNode, bleed?: number): ViewBox;
+/**
+ * Display dimensions for a viewBox so the long side is at least `targetSide` px
+ * (browser default: 1600). Mirrors `svgDisplayDimensionsForViewBox()`.
+ */
+declare function svgDisplayDimensions(viewBox: Pick<ViewBox, 'width' | 'height'>, targetSide?: number): {
+    width: number;
+    height: number;
+    scale: number;
+};
+
+/**
+ * Headless SVG rendering: `.pdg` source -> standalone SVG string.
+ * Crops to the real drawn extent (bleed 3) and sizes the document so the long side
+ * is at least `targetSide` px (default 1600).
+ */
+
+interface RenderToSvgOptions {
+    /** Display language: 'ja' (default), 'en', or 'both' (bilingual two-line labels). */
+    lang?: Lang;
+    /** Crop to the real drawn extent (default true). When false, uses the full canvas. */
+    crop?: boolean;
+    /** Padding added around the content box, in user units (default 3). */
+    bleed?: number;
+    /** Minimum long-side length in px for the width/height attributes (default 1600). */
+    targetSide?: number;
+    /** Prepend an `<?xml ... ?>` declaration (default true). */
+    xmlDeclaration?: boolean;
+}
+interface RenderToSvgResult {
+    /** The serialized standalone SVG document. */
+    svg: string;
+    /** The diagram kind inferred from the source. */
+    kind: DiagramKind;
+    /** The viewBox used (content box when cropped). */
+    viewBox: ViewBox;
+    /** Display width in px (the `width` attribute). */
+    width: number;
+    /** Display height in px (the `height` attribute). */
+    height: number;
+}
+/**
+ * Render `.pdg` source to a standalone SVG string. Synchronous and dependency-free.
+ */
+declare function renderToSvg(source: string, opts?: RenderToSvgOptions): RenderToSvgResult;
+
+/**
+ * Validation for AI authoring. Runs the core parser and adds a kind assertion and
+ * friendly lints, returning all diagnostics.
+ *
+ *   - Kind assertion: an optional `#! kind: block|flow|state|seq` directive (written
+ *     in a comment) is checked against the kind inferred from structure; a mismatch
+ *     is reported as an error. Guards against producing the wrong diagram type.
+ *   - Lints: clearer hints for chained connections (`A -> B -> C`) and operators
+ *     without surrounding spaces (`11-12`).
+ *
+ * Run on AI-generated `.pdg` and feed the diagnostics back until there are no errors.
+ */
+
+interface ValidateResult {
+    /** True when there are no error-severity diagnostics. */
+    ok: boolean;
+    /** The diagram kind inferred from the source structure. */
+    kind: DiagramKind;
+    /** The diagram kind the author declared via directive, or null if none. */
+    declaredKind: DiagramKind | null;
+    /** Whether the declared kind matches the inferred kind (null if not declared). */
+    kindMatches: boolean | null;
+    /** All diagnostics (parser + pdgkit lints), sorted by line then column. */
+    diagnostics: Diagnostic[];
+    counts: {
+        errors: number;
+        warnings: number;
+        infos: number;
+    };
+}
+/**
+ * Validate a `.pdg` source string. Pure and synchronous — safe to call in any
+ * environment, including a hot AI authoring loop.
+ */
+declare function validate(source: string): ValidateResult;
+
+/**
+ * Raster output (PNG / JPEG) via `@resvg/resvg-js`, with the bundled IPAex Gothic
+ * font embedded and a white background. Default scale is 8x the content box (capped
+ * to 24000 px/side and 1e8 px total). Native dependencies are imported lazily.
+ */
+
+interface RasterOptions {
+    lang?: Lang;
+    /** Resolution multiplier applied to the cropped content box (default 8). */
+    scale?: number;
+    /** Padding around the content box, in user units (default 3). */
+    bleed?: number;
+}
+/** Render `.pdg` source to a PNG (8× by default, white background). */
+declare function renderToPng(source: string, opts?: RasterOptions): Promise<Uint8Array>;
+/** Render `.pdg` source to a JPEG (8× by default, white background). */
+declare function renderToJpeg(source: string, opts?: RasterOptions): Promise<Uint8Array>;
+
+/**
+ * PDF output (A4, IPAex font embedded). Vector by default (jsPDF + svg2pdf.js under
+ * jsdom, with analytic getBBox / getComputedTextLength shims), falling back to a
+ * high-resolution raster PDF if the vector path fails. The figure is centered with
+ * a 10 mm margin and the page orientation follows its aspect ratio.
+ */
+
+interface PdfOptions {
+    lang?: Lang;
+    /** Padding around the content box, in user units (default 3). */
+    bleed?: number;
+    /** Prefer vector output; fall back to raster on failure (default true). */
+    vector?: boolean;
+    /** Raster resolution multiplier for the raster path (default 8). */
+    scale?: number;
+}
+/** Render `.pdg` source to a PDF (A4, IPAex font, vector preferred). */
+declare function renderToPdf(source: string, opts?: PdfOptions): Promise<Uint8Array>;
+
+/**
+ * PPTX output: `.pdg` → PowerPoint presentation (one 16:9 slide).
+ *
+ *   - image mode (default): the figure is rasterized (resvg) and placed as a
+ *     centered picture — highest visual fidelity.
+ *   - editable mode (`editable: true`): every SVG primitive is converted to an
+ *     editable PowerPoint shape / connector / text box, for later tweaking.
+ */
+
+interface PptxOptions {
+    lang?: Lang;
+    /** Emit editable PowerPoint shapes instead of a single image (default false). */
+    editable?: boolean;
+    /** Raster resolution multiplier for image mode (default 8). */
+    scale?: number;
+    /** Padding around the content box, in user units (default 3). */
+    bleed?: number;
+}
+/** Render `.pdg` source to a PPTX (image by default, or editable shapes). */
+declare function renderToPptx(source: string, opts?: PptxOptions): Promise<Uint8Array>;
+
+/**
+ * pdgkit Node API — the browser-free rendering surface a host tool calls.
+ *
+ * Implemented: SVG, PNG, JPEG, PDF, PPTX (image + editable), validation, and the
+ * reference-sign table exporters. All run with no browser.
+ */
+
+/** The pdgkit package version. Keep in sync with package.json. */
+declare const VERSION = "0.1.0";
+/** Convenience: render to SVG and return just the string. */
+declare function toSvgString(source: string, lang?: Lang): string;
+/**
+ * Read the bundled AI authoring guide (docs/ai-authoring-guide.md) as a string.
+ * Inject this into an LLM's system prompt so it can write valid `.pdg`, instead of
+ * pasting the guide by hand.
+ */
+declare function loadAuthoringGuide(): string;
+
+export { Diagnostic, DiagramKind, Lang, type PdfOptions, type PptxOptions, type RasterOptions, type RenderToSvgOptions, type RenderToSvgResult, type SvgNode, VERSION, type ValidateResult, type ViewBox, computeContentBox, installDomShim, loadAuthoringGuide, renderToJpeg, renderToPdf, renderToPng, renderToPptx, renderToSvg, serializeSvg, svgDisplayDimensions, toSvgString, validate };