@aexol/spectral 0.9.69 → 0.9.71

package/dist/extensions/pdf/config.d.ts

@@ -0,0 +1,3 @@
+import type { PdfConfig } from "./types.js";
+export declare function loadPdfConfig(): PdfConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/extensions/pdf/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/extensions/pdf/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAA6B,MAAM,YAAY,CAAC;AAyBvE,wBAAgB,aAAa,IAAI,SAAS,CAczC"}

package/dist/extensions/pdf/config.js

@@ -0,0 +1,37 @@
+import { join } from "node:path";
+function envBool(key, def) {
+    const v = process.env[key];
+    if (v === undefined)
+        return def;
+    return v === "1" || v.toLowerCase() === "true" || v.toLowerCase() === "yes";
+}
+function envInt(key, def) {
+    const v = process.env[key];
+    if (v === undefined)
+        return def;
+    const n = Number.parseInt(v, 10);
+    return Number.isNaN(n) ? def : n;
+}
+function envFormat(key, def) {
+    const v = process.env[key];
+    return v === "Letter" || v === "A4" ? v : def;
+}
+function envOrientation(key, def) {
+    const v = process.env[key];
+    return v === "landscape" || v === "portrait" ? v : def;
+}
+export function loadPdfConfig() {
+    return {
+        outputDir: process.env.SPECTRAL_PDF_OUTPUT_DIR ?? join(".spectral", "pdf"),
+        renderTimeoutMs: envInt("SPECTRAL_PDF_RENDER_TIMEOUT_MS", 30_000),
+        allowRemoteAssets: envBool("SPECTRAL_PDF_ALLOW_REMOTE_ASSETS", false),
+        defaultFormat: envFormat("SPECTRAL_PDF_DEFAULT_FORMAT", "A4"),
+        defaultOrientation: envOrientation("SPECTRAL_PDF_DEFAULT_ORIENTATION", "portrait"),
+        defaultMargin: {
+            top: process.env.SPECTRAL_PDF_MARGIN_TOP ?? "18mm",
+            right: process.env.SPECTRAL_PDF_MARGIN_RIGHT ?? "16mm",
+            bottom: process.env.SPECTRAL_PDF_MARGIN_BOTTOM ?? "18mm",
+            left: process.env.SPECTRAL_PDF_MARGIN_LEFT ?? "16mm",
+        },
+    };
+}

package/dist/extensions/pdf/index.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "../../sdk/coding-agent/index.js";
+export default function pdfExtension(ext: ExtensionAPI): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/pdf/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/pdf/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAOpE,wBAA8B,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAY3E"}

package/dist/extensions/pdf/index.js

@@ -0,0 +1,19 @@
+import { loadPdfConfig } from "./config.js";
+import { registerGenerateTool } from "./tools/generate.js";
+import { registerPreviewTool } from "./tools/preview.js";
+import { registerRenderTool } from "./tools/render.js";
+import { registerValidateTool } from "./tools/validate.js";
+export default async function pdfExtension(ext) {
+    const config = loadPdfConfig();
+    try {
+        registerValidateTool(ext, config);
+        registerGenerateTool(ext, config);
+        registerRenderTool(ext, config);
+        registerPreviewTool(ext, config);
+        process.stderr.write(`[pdf] Registered PDF tools. Output dir: ${config.outputDir}.\n`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[pdf] Failed to register PDF tools: ${msg}\n`);
+    }
+}

package/dist/extensions/pdf/tools/generate.d.ts

@@ -0,0 +1,5 @@
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { PdfConfig, PdfManifest } from "../types.js";
+export declare function registerGenerateTool(ext: ExtensionAPI, config: PdfConfig): void;
+export declare function readExistingManifest(manifestPath: string): PdfManifest | null;
+//# sourceMappingURL=generate.d.ts.map

package/dist/extensions/pdf/tools/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../../src/extensions/pdf/tools/generate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAoC,MAAM,oCAAoC,CAAC;AACzG,OAAO,KAAK,EAAE,SAAS,EAAa,WAAW,EAA6B,MAAM,aAAa,CAAC;AAiBhG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAuG/E;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAO7E"}

package/dist/extensions/pdf/tools/generate.js

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createDocumentPaths, ensureDir, toDisplayPath } from "../utils/paths.js";
+import { printCssWarning, validateHtmlDocument } from "../utils/html.js";
+import { renderPdf } from "../utils/renderer.js";
+import { errorResult, textResult } from "./helpers.js";
+const formatEnum = ["A4", "Letter"];
+const orientationEnum = ["portrait", "landscape"];
+function mergeMargin(config, margin) {
+    return { ...config.defaultMargin, ...(margin ?? {}) };
+}
+function writeManifest(path, manifest) {
+    writeFileSync(path, JSON.stringify(manifest, null, 2), "utf-8");
+}
+export function registerGenerateTool(ext, config) {
+    const tool = {
+        name: "pdf_generate",
+        label: "Generate PDF from HTML",
+        description: "Generate a PDF by first saving an editable HTML source file, then rendering it with Chromium. " +
+            "For polished user-facing documents, use designer tools to create/refine the HTML before calling this tool.",
+        promptSnippet: "`pdf_generate { title, html, outputName? }` — save editable HTML and render it to PDF",
+        promptGuidelines: [
+            "Never generate PDFs directly from plain text. First create a complete HTML document, then render it.",
+            "For polished PDFs, use designer_list_systems and designer_get_system before writing the HTML.",
+            "Keep the saved HTML source as the editable artifact; refine it and call pdf_render again for updates.",
+            "Use print CSS with @page, fixed margins, break-inside avoidance, and print-color-adjust: exact.",
+        ],
+        parameters: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Document title." },
+                html: { type: "string", description: "Complete HTML document. Must include doctype, html, head, and body." },
+                outputName: { type: "string", description: "Optional stable filename/folder slug." },
+                format: { type: "string", enum: [...formatEnum], description: "Page format. Default from config: A4." },
+                orientation: { type: "string", enum: [...orientationEnum], description: "Page orientation. Default: portrait." },
+                printBackground: { type: "boolean", description: "Render CSS backgrounds. Default: true." },
+                allowRemoteAssets: { type: "boolean", description: "Allow http/https assets during validation/render. Default: false." },
+                margin: {
+                    type: "object",
+                    properties: {
+                        top: { type: "string" },
+                        right: { type: "string" },
+                        bottom: { type: "string" },
+                        left: { type: "string" },
+                    },
+                },
+            },
+            required: ["title", "html"],
+        },
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            try {
+                const p = params;
+                const allowRemoteAssets = p.allowRemoteAssets ?? config.allowRemoteAssets;
+                validateHtmlDocument(p.html, { allowRemoteAssets });
+                const paths = createDocumentPaths(ctx.cwd, config, p.title, p.outputName);
+                ensureDir(paths.dir);
+                writeFileSync(paths.htmlPath, p.html, "utf-8");
+                const now = new Date().toISOString();
+                const format = p.format ?? config.defaultFormat;
+                const orientation = p.orientation ?? config.defaultOrientation;
+                const margin = mergeMargin(config, p.margin);
+                const manifest = {
+                    id: paths.id,
+                    title: p.title,
+                    htmlPath: toDisplayPath(ctx.cwd, paths.htmlPath),
+                    pdfPath: toDisplayPath(ctx.cwd, paths.pdfPath),
+                    createdAt: now,
+                    updatedAt: now,
+                    page: { format, orientation, margin },
+                    source: "generated",
+                };
+                writeManifest(paths.manifestPath, manifest);
+                const rendered = await renderPdf(config, {
+                    htmlPath: paths.htmlPath,
+                    pdfPath: paths.pdfPath,
+                    format,
+                    orientation,
+                    margin,
+                    printBackground: p.printBackground ?? true,
+                    allowRemoteAssets,
+                    waitUntil: allowRemoteAssets ? "networkidle" : "load",
+                });
+                writeManifest(paths.manifestPath, { ...manifest, updatedAt: new Date().toISOString() });
+                const warning = printCssWarning(p.html);
+                const lines = [
+                    "✓ PDF generated from editable HTML",
+                    `HTML: ${toDisplayPath(ctx.cwd, paths.htmlPath)}`,
+                    `PDF: ${toDisplayPath(ctx.cwd, paths.pdfPath)}`,
+                    `Manifest: ${toDisplayPath(ctx.cwd, paths.manifestPath)}`,
+                    `Size: ${rendered.bytes} bytes`,
+                ];
+                if (warning)
+                    lines.push(`Warning: ${warning}`);
+                return textResult(lines.join("\n"), {
+                    isError: false,
+                    id: paths.id,
+                    htmlPath: toDisplayPath(ctx.cwd, paths.htmlPath),
+                    pdfPath: toDisplayPath(ctx.cwd, paths.pdfPath),
+                    manifestPath: toDisplayPath(ctx.cwd, paths.manifestPath),
+                    bytes: rendered.bytes,
+                    warning,
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(tool);
+}
+export function readExistingManifest(manifestPath) {
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(manifestPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/extensions/pdf/tools/helpers.d.ts

@@ -0,0 +1,4 @@
+import type { AgentToolResult } from "../../../sdk/coding-agent/index.js";
+export declare function textResult(text: string, details?: Record<string, unknown>): AgentToolResult<Record<string, unknown>>;
+export declare function errorResult(message: string, details?: Record<string, unknown>): AgentToolResult<Record<string, unknown>>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/extensions/pdf/tools/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/extensions/pdf/tools/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAExH;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAE5H"}

package/dist/extensions/pdf/tools/helpers.js

@@ -0,0 +1,6 @@
+export function textResult(text, details = {}) {
+    return { content: [{ type: "text", text }], details };
+}
+export function errorResult(message, details = {}) {
+    return { content: [{ type: "text", text: `❌ ${message}` }], details: { isError: true, ...details } };
+}

package/dist/extensions/pdf/tools/preview.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { PdfConfig } from "../types.js";
+export declare function registerPreviewTool(ext: ExtensionAPI, config: PdfConfig): void;
+//# sourceMappingURL=preview.d.ts.map

package/dist/extensions/pdf/tools/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../../src/extensions/pdf/tools/preview.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAoC,MAAM,oCAAoC,CAAC;AACzG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA+C9E"}

package/dist/extensions/pdf/tools/preview.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { assertInsideWorkspace, ensureParent, resolveWorkspacePath, toDisplayPath } from "../utils/paths.js";
+import { validateHtmlDocument } from "../utils/html.js";
+import { renderPreview } from "../utils/renderer.js";
+import { errorResult, textResult } from "./helpers.js";
+export function registerPreviewTool(ext, config) {
+    const tool = {
+        name: "pdf_preview_html",
+        label: "Preview HTML for PDF",
+        description: "Render a PNG preview screenshot for an existing HTML document before PDF export.",
+        promptSnippet: "`pdf_preview_html { htmlPath }` — render PNG preview for PDF HTML",
+        parameters: {
+            type: "object",
+            properties: {
+                htmlPath: { type: "string", description: "Path to an HTML file inside the workspace." },
+                outputPath: { type: "string", description: "Optional PNG output path inside the workspace." },
+                allowRemoteAssets: { type: "boolean", description: "Allow http/https assets during preview. Default: false." },
+            },
+            required: ["htmlPath"],
+        },
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            try {
+                const p = params;
+                const htmlPath = resolveWorkspacePath(ctx.cwd, p.htmlPath);
+                assertInsideWorkspace(ctx.cwd, htmlPath);
+                if (!existsSync(htmlPath))
+                    throw new Error(`HTML file not found: ${p.htmlPath}`);
+                const previewPath = p.outputPath ? resolveWorkspacePath(ctx.cwd, p.outputPath) : join(dirname(htmlPath), "preview.png");
+                assertInsideWorkspace(ctx.cwd, previewPath);
+                ensureParent(previewPath);
+                const allowRemoteAssets = p.allowRemoteAssets ?? config.allowRemoteAssets;
+                validateHtmlDocument(readFileSync(htmlPath, "utf-8"), { allowRemoteAssets });
+                const preview = await renderPreview(config, htmlPath, previewPath, allowRemoteAssets);
+                return textResult([
+                    "✓ HTML preview rendered",
+                    `HTML: ${toDisplayPath(ctx.cwd, htmlPath)}`,
+                    `Preview: ${toDisplayPath(ctx.cwd, previewPath)}`,
+                    `Size: ${preview.bytes} bytes`,
+                ].join("\n"), {
+                    isError: false,
+                    htmlPath: toDisplayPath(ctx.cwd, htmlPath),
+                    previewPath: toDisplayPath(ctx.cwd, previewPath),
+                    bytes: preview.bytes,
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(tool);
+}

package/dist/extensions/pdf/tools/render.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { PdfConfig } from "../types.js";
+export declare function registerRenderTool(ext: ExtensionAPI, config: PdfConfig): void;
+//# sourceMappingURL=render.d.ts.map

package/dist/extensions/pdf/tools/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../../src/extensions/pdf/tools/render.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAoC,MAAM,oCAAoC,CAAC;AACzG,OAAO,KAAK,EAAE,SAAS,EAAqD,MAAM,aAAa,CAAC;AAgBhG,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAsG7E"}

package/dist/extensions/pdf/tools/render.js

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
+import { assertInsideWorkspace, ensureParent, resolveWorkspacePath, toDisplayPath } from "../utils/paths.js";
+import { printCssWarning, validateHtmlDocument } from "../utils/html.js";
+import { renderPdf } from "../utils/renderer.js";
+import { errorResult, textResult } from "./helpers.js";
+function mergeMargin(config, margin) {
+    return { ...config.defaultMargin, ...(margin ?? {}) };
+}
+function defaultPdfPath(htmlPath) {
+    const ext = extname(htmlPath);
+    const name = basename(htmlPath, ext || undefined);
+    return join(dirname(htmlPath), `${name}.pdf`);
+}
+export function registerRenderTool(ext, config) {
+    const tool = {
+        name: "pdf_render",
+        label: "Render HTML to PDF",
+        description: "Render an existing HTML file to PDF. Use this after editing the saved HTML source with designer refinements.",
+        promptSnippet: "`pdf_render { htmlPath, outputPath? }` — render an existing HTML file to PDF",
+        promptGuidelines: [
+            "Use pdf_render after editing an existing HTML artifact. Do not overwrite the HTML unless the user asked for refinements.",
+            "If the PDF needs visual improvement, refine the HTML with designer guidance, then render again.",
+        ],
+        parameters: {
+            type: "object",
+            properties: {
+                htmlPath: { type: "string", description: "Path to the existing HTML file, relative to workspace or absolute inside workspace." },
+                outputPath: { type: "string", description: "Optional PDF output path, relative to workspace or absolute inside workspace." },
+                format: { type: "string", enum: ["A4", "Letter"], description: "Page format. Default: A4." },
+                orientation: { type: "string", enum: ["portrait", "landscape"], description: "Page orientation. Default: portrait." },
+                printBackground: { type: "boolean", description: "Render CSS backgrounds. Default: true." },
+                allowRemoteAssets: { type: "boolean", description: "Allow http/https assets during validation/render. Default: false." },
+                margin: {
+                    type: "object",
+                    properties: {
+                        top: { type: "string" },
+                        right: { type: "string" },
+                        bottom: { type: "string" },
+                        left: { type: "string" },
+                    },
+                },
+            },
+            required: ["htmlPath"],
+        },
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            try {
+                const p = params;
+                const htmlPath = resolveWorkspacePath(ctx.cwd, p.htmlPath);
+                assertInsideWorkspace(ctx.cwd, htmlPath);
+                if (!existsSync(htmlPath))
+                    throw new Error(`HTML file not found: ${p.htmlPath}`);
+                const outputPath = p.outputPath ? resolveWorkspacePath(ctx.cwd, p.outputPath) : defaultPdfPath(htmlPath);
+                assertInsideWorkspace(ctx.cwd, outputPath);
+                ensureParent(outputPath);
+                const html = readFileSync(htmlPath, "utf-8");
+                const allowRemoteAssets = p.allowRemoteAssets ?? config.allowRemoteAssets;
+                validateHtmlDocument(html, { allowRemoteAssets });
+                const format = p.format ?? config.defaultFormat;
+                const orientation = p.orientation ?? config.defaultOrientation;
+                const margin = mergeMargin(config, p.margin);
+                const rendered = await renderPdf(config, {
+                    htmlPath,
+                    pdfPath: outputPath,
+                    format,
+                    orientation,
+                    margin,
+                    printBackground: p.printBackground ?? true,
+                    allowRemoteAssets,
+                    waitUntil: allowRemoteAssets ? "networkidle" : "load",
+                });
+                const now = new Date().toISOString();
+                const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+                const manifest = {
+                    id: basename(dirname(htmlPath)),
+                    title: titleMatch?.[1]?.trim() || basename(htmlPath),
+                    htmlPath: toDisplayPath(ctx.cwd, htmlPath),
+                    pdfPath: toDisplayPath(ctx.cwd, outputPath),
+                    createdAt: now,
+                    updatedAt: now,
+                    page: { format, orientation, margin },
+                    source: "rendered",
+                };
+                const manifestPath = join(dirname(htmlPath), "manifest.json");
+                writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+                const warning = printCssWarning(html);
+                const lines = [
+                    "✓ HTML rendered to PDF",
+                    `HTML: ${toDisplayPath(ctx.cwd, htmlPath)}`,
+                    `PDF: ${toDisplayPath(ctx.cwd, outputPath)}`,
+                    `Manifest: ${toDisplayPath(ctx.cwd, manifestPath)}`,
+                    `Size: ${rendered.bytes} bytes`,
+                ];
+                if (warning)
+                    lines.push(`Warning: ${warning}`);
+                return textResult(lines.join("\n"), {
+                    isError: false,
+                    htmlPath: toDisplayPath(ctx.cwd, htmlPath),
+                    pdfPath: toDisplayPath(ctx.cwd, outputPath),
+                    manifestPath: toDisplayPath(ctx.cwd, manifestPath),
+                    bytes: rendered.bytes,
+                    warning,
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(tool);
+}

package/dist/extensions/pdf/tools/validate.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { PdfConfig } from "../types.js";
+export declare function registerValidateTool(ext: ExtensionAPI, config: PdfConfig): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/extensions/pdf/tools/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/extensions/pdf/tools/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAoC,MAAM,oCAAoC,CAAC;AACzG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAwB7C,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAmD/E"}

package/dist/extensions/pdf/tools/validate.js

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync } from "node:fs";
+import { analyzePdfHtml } from "../utils/validate.js";
+import { assertInsideWorkspace, resolveWorkspacePath, toDisplayPath } from "../utils/paths.js";
+import { errorResult, textResult } from "./helpers.js";
+function issueCounts(issues) {
+    return {
+        errors: issues.filter((issue) => issue.severity === "error").length,
+        warnings: issues.filter((issue) => issue.severity === "warning").length,
+        info: issues.filter((issue) => issue.severity === "info").length,
+    };
+}
+function formatIssues(issues) {
+    if (issues.length === 0)
+        return "No issues found.";
+    return issues
+        .map((issue) => {
+        const icon = issue.severity === "error" ? "✗" : issue.severity === "warning" ? "⚠" : "ℹ";
+        const suggestion = issue.suggestion ? `\n  Suggestion: ${issue.suggestion}` : "";
+        return `${icon} [${issue.severity}] ${issue.code}: ${issue.message}${suggestion}`;
+    })
+        .join("\n");
+}
+export function registerValidateTool(ext, config) {
+    const tool = {
+        name: "pdf_validate_html",
+        label: "Validate PDF HTML",
+        description: "Analyze PDF HTML before rendering. Reports blocking errors and layout-quality warnings for print CSS, remote assets, pagination, images, and metadata.",
+        promptSnippet: "`pdf_validate_html { html | htmlPath }` — validate PDF HTML before render",
+        promptGuidelines: [
+            "Use pdf_validate_html before rendering complex or customer-facing PDFs.",
+            "Fix error-level issues before pdf_generate or pdf_render.",
+            "Treat warnings as design polish tasks; use designer tools to refine the HTML.",
+        ],
+        parameters: {
+            type: "object",
+            properties: {
+                html: { type: "string", description: "Complete HTML document to validate." },
+                htmlPath: { type: "string", description: "Path to an existing HTML file inside the workspace." },
+                allowRemoteAssets: { type: "boolean", description: "Allow http/https assets during validation. Default: false." },
+            },
+        },
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            try {
+                const p = params;
+                if (!p.html && !p.htmlPath)
+                    throw new Error("Provide either html or htmlPath.");
+                let html = p.html;
+                let source = "inline HTML";
+                if (!html && p.htmlPath) {
+                    const htmlPath = resolveWorkspacePath(ctx.cwd, p.htmlPath);
+                    assertInsideWorkspace(ctx.cwd, htmlPath);
+                    if (!existsSync(htmlPath))
+                        throw new Error(`HTML file not found: ${p.htmlPath}`);
+                    html = readFileSync(htmlPath, "utf-8");
+                    source = toDisplayPath(ctx.cwd, htmlPath);
+                }
+                const allowRemoteAssets = p.allowRemoteAssets ?? config.allowRemoteAssets;
+                const issues = analyzePdfHtml(html ?? "", { allowRemoteAssets });
+                const counts = issueCounts(issues);
+                const ok = counts.errors === 0;
+                const text = [
+                    ok ? "✓ PDF HTML validation passed" : "✗ PDF HTML validation failed",
+                    `Source: ${source}`,
+                    `Errors: ${counts.errors} · Warnings: ${counts.warnings} · Info: ${counts.info}`,
+                    "",
+                    formatIssues(issues),
+                ].join("\n");
+                return textResult(text, { isError: !ok, ok, issues, counts, source });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(tool);
+}

package/dist/extensions/pdf/types.d.ts

@@ -0,0 +1,32 @@
+export type PdfFormat = "A4" | "Letter";
+export type PdfOrientation = "portrait" | "landscape";
+export interface PdfMargin {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+}
+export interface PdfConfig {
+    outputDir: string;
+    renderTimeoutMs: number;
+    allowRemoteAssets: boolean;
+    defaultFormat: PdfFormat;
+    defaultOrientation: PdfOrientation;
+    defaultMargin: Required<PdfMargin>;
+}
+export interface PdfManifest {
+    id: string;
+    title: string;
+    htmlPath: string;
+    pdfPath?: string;
+    previewPath?: string;
+    createdAt: string;
+    updatedAt: string;
+    page: {
+        format: PdfFormat;
+        orientation: PdfOrientation;
+        margin: Required<PdfMargin>;
+    };
+    source: "generated" | "rendered";
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/extensions/pdf/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/extensions/pdf/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,QAAQ,CAAC;AACxC,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAEtD,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,aAAa,EAAE,SAAS,CAAC;IACzB,kBAAkB,EAAE,cAAc,CAAC;IACnC,aAAa,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE;QACJ,MAAM,EAAE,SAAS,CAAC;QAClB,WAAW,EAAE,cAAc,CAAC;QAC5B,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;KAC7B,CAAC;IACF,MAAM,EAAE,WAAW,GAAG,UAAU,CAAC;CAClC"}

package/dist/extensions/pdf/types.js

@@ -0,0 +1 @@
+export {};

package/dist/extensions/pdf/utils/html.d.ts

@@ -0,0 +1,6 @@
+export declare function validateHtmlDocument(html: string, opts?: {
+    allowRemoteAssets?: boolean;
+}): void;
+export declare function hasPrintCss(html: string): boolean;
+export declare function printCssWarning(html: string): string | null;
+//# sourceMappingURL=html.d.ts.map

package/dist/extensions/pdf/utils/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../../../src/extensions/pdf/utils/html.ts"],"names":[],"mappings":"AAEA,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAS/F;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG3D"}

package/dist/extensions/pdf/utils/html.js

@@ -0,0 +1,19 @@
+import { analyzePdfHtml, hasBlockingPdfHtmlIssues } from "./validate.js";
+export function validateHtmlDocument(html, opts) {
+    const issues = analyzePdfHtml(html, opts);
+    const firstError = issues.find((issue) => issue.severity === "error");
+    if (firstError) {
+        throw new Error(firstError.message + (firstError.suggestion ? ` ${firstError.suggestion}` : ""));
+    }
+    if (hasBlockingPdfHtmlIssues(issues)) {
+        throw new Error("HTML has blocking PDF validation issues.");
+    }
+}
+export function hasPrintCss(html) {
+    return /@page\s*{/i.test(html) || /@media\s+print/i.test(html);
+}
+export function printCssWarning(html) {
+    if (hasPrintCss(html))
+        return null;
+    return "HTML has no @page or @media print CSS. PDF still rendered, but page layout may need refinement.";
+}

package/dist/extensions/pdf/utils/paths.d.ts

@@ -0,0 +1,19 @@
+import type { PdfConfig } from "../types.js";
+export declare function slugify(input: string): string;
+export declare function uniqueSlug(title: string): string;
+export declare function ensureDir(path: string): void;
+export declare function ensureParent(path: string): void;
+export declare function resolveWorkspacePath(cwd: string, input: string): string;
+export declare function assertInsideWorkspace(cwd: string, targetPath: string): void;
+export declare function resolveOutputDir(cwd: string, config: PdfConfig): string;
+export declare function createDocumentPaths(cwd: string, config: PdfConfig, title: string, outputName?: string): {
+    id: string;
+    dir: string;
+    htmlPath: string;
+    pdfPath: string;
+    manifestPath: string;
+    previewPath: string;
+};
+export declare function pathToFileHref(path: string): string;
+export declare function toDisplayPath(cwd: string, path: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/extensions/pdf/utils/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../../src/extensions/pdf/utils/paths.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS7C;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAO3E;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,MAAM,CAIvE;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG;IACvG,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,CAYA;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/D"}

package/dist/extensions/pdf/utils/paths.js

@@ -0,0 +1,60 @@
+import { mkdirSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+export function slugify(input) {
+    const slug = input
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+    return slug || "document";
+}
+export function uniqueSlug(title) {
+    const base = slugify(title);
+    const suffix = new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
+    return `${base}-${suffix}`;
+}
+export function ensureDir(path) {
+    mkdirSync(path, { recursive: true });
+}
+export function ensureParent(path) {
+    mkdirSync(dirname(path), { recursive: true });
+}
+export function resolveWorkspacePath(cwd, input) {
+    return isAbsolute(input) ? resolve(input) : resolve(cwd, input);
+}
+export function assertInsideWorkspace(cwd, targetPath) {
+    const root = resolve(cwd);
+    const target = resolve(targetPath);
+    const rel = relative(root, target);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error(`Path escapes workspace: ${targetPath}`);
+    }
+}
+export function resolveOutputDir(cwd, config) {
+    const dir = resolveWorkspacePath(cwd, config.outputDir);
+    assertInsideWorkspace(cwd, dir);
+    return dir;
+}
+export function createDocumentPaths(cwd, config, title, outputName) {
+    const id = outputName ? slugify(outputName) : uniqueSlug(title);
+    const baseDir = resolveOutputDir(cwd, config);
+    const dir = join(baseDir, id);
+    return {
+        id,
+        dir,
+        htmlPath: join(dir, `${id}.html`),
+        pdfPath: join(dir, `${id}.pdf`),
+        manifestPath: join(dir, "manifest.json"),
+        previewPath: join(dir, "preview.png"),
+    };
+}
+export function pathToFileHref(path) {
+    return pathToFileURL(path).href;
+}
+export function toDisplayPath(cwd, path) {
+    const rel = relative(resolve(cwd), resolve(path));
+    return rel.startsWith("..") || isAbsolute(rel) ? path : rel;
+}

package/dist/extensions/pdf/utils/renderer.d.ts

@@ -0,0 +1,21 @@
+import type { PdfConfig, PdfFormat, PdfMargin, PdfOrientation } from "../types.js";
+export interface RenderPdfOptions {
+    htmlPath: string;
+    pdfPath: string;
+    format: PdfFormat;
+    orientation: PdfOrientation;
+    margin: Required<PdfMargin>;
+    printBackground: boolean;
+    allowRemoteAssets: boolean;
+    waitUntil: "load" | "networkidle";
+}
+export interface RenderPdfResult {
+    pdfPath: string;
+    bytes: number;
+}
+export declare function renderPdf(config: PdfConfig, opts: RenderPdfOptions): Promise<RenderPdfResult>;
+export declare function renderPreview(config: PdfConfig, htmlPath: string, previewPath: string, allowRemoteAssets: boolean): Promise<{
+    previewPath: string;
+    bytes: number;
+}>;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/extensions/pdf/utils/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../../src/extensions/pdf/utils/renderer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGnF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,CAAC;IAClB,WAAW,EAAE,cAAc,CAAC;IAC5B,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC5B,eAAe,EAAE,OAAO,CAAC;IACzB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,aAAa,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA8BnG;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBzK"}

package/dist/extensions/pdf/utils/renderer.js

@@ -0,0 +1,57 @@
+import { existsSync, statSync } from "node:fs";
+import { chromium } from "playwright";
+import { pathToFileHref } from "./paths.js";
+export async function renderPdf(config, opts) {
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const page = await browser.newPage();
+        page.setDefaultTimeout(config.renderTimeoutMs);
+        if (!opts.allowRemoteAssets) {
+            await page.route("**/*", (route) => {
+                const url = route.request().url();
+                if (url.startsWith("file://") || url.startsWith("data:") || url === "about:blank") {
+                    return route.continue();
+                }
+                return route.abort();
+            });
+        }
+        await page.goto(pathToFileHref(opts.htmlPath), {
+            waitUntil: opts.waitUntil,
+            timeout: config.renderTimeoutMs,
+        });
+        await page.pdf({
+            path: opts.pdfPath,
+            format: opts.format,
+            landscape: opts.orientation === "landscape",
+            printBackground: opts.printBackground,
+            margin: opts.margin,
+        });
+        if (!existsSync(opts.pdfPath))
+            throw new Error("PDF render produced no output file.");
+        return { pdfPath: opts.pdfPath, bytes: statSync(opts.pdfPath).size };
+    }
+    finally {
+        await browser.close();
+    }
+}
+export async function renderPreview(config, htmlPath, previewPath, allowRemoteAssets) {
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const page = await browser.newPage({ viewport: { width: 1240, height: 1754 }, deviceScaleFactor: 1 });
+        page.setDefaultTimeout(config.renderTimeoutMs);
+        if (!allowRemoteAssets) {
+            await page.route("**/*", (route) => {
+                const url = route.request().url();
+                if (url.startsWith("file://") || url.startsWith("data:") || url === "about:blank")
+                    return route.continue();
+                return route.abort();
+            });
+        }
+        await page.goto(pathToFileHref(htmlPath), { waitUntil: "load", timeout: config.renderTimeoutMs });
+        await page.screenshot({ path: previewPath, fullPage: true, type: "png" });
+        return { previewPath, bytes: statSync(previewPath).size };
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/extensions/pdf/utils/validate.d.ts

@@ -0,0 +1,12 @@
+export type PdfValidationSeverity = "error" | "warning" | "info";
+export interface PdfValidationIssue {
+    severity: PdfValidationSeverity;
+    code: string;
+    message: string;
+    suggestion?: string;
+}
+export declare function analyzePdfHtml(html: string, opts?: {
+    allowRemoteAssets?: boolean;
+}): PdfValidationIssue[];
+export declare function hasBlockingPdfHtmlIssues(issues: PdfValidationIssue[]): boolean;
+//# sourceMappingURL=validate.d.ts.map

package/dist/extensions/pdf/utils/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/extensions/pdf/utils/validate.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAoBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,kBAAkB,EAAE,CA8HzG;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAE9E"}

package/dist/extensions/pdf/utils/validate.js

@@ -0,0 +1,148 @@
+const DOCTYPE_RE = /^\s*<!doctype\s+html/i;
+const HTML_RE = /<html[\s>]/i;
+const HEAD_RE = /<head[\s>]/i;
+const BODY_RE = /<body[\s>]/i;
+const REMOTE_SRC_RE = /\b(?:src|href)\s*=\s*["']https?:\/\//gi;
+const PAGE_RE = /@page\s*{/i;
+const PRINT_MEDIA_RE = /@media\s+print/i;
+const PRINT_COLOR_ADJUST_RE = /print-color-adjust\s*:\s*exact|-webkit-print-color-adjust\s*:\s*exact/i;
+const VIEWPORT_RE = /<meta\s+[^>]*name\s*=\s*["']viewport["'][^>]*>/i;
+const TITLE_RE = /<title[^>]*>\s*([^<]+?)\s*<\/title>/i;
+const FIXED_RE = /position\s*:\s*fixed/i;
+const ABSOLUTE_RE = /position\s*:\s*absolute/i;
+const BREAK_INSIDE_RE = /break-inside\s*:\s*avoid|page-break-inside\s*:\s*avoid/i;
+const WIDE_WIDTH_RE = /(?:width|min-width)\s*:\s*(?:[1-9]\d{3,}px|(?:8[5-9]|9\d|\d{3,})vw)/i;
+const IMAGE_RE = /<img\b[^>]*>/gi;
+const WIDTH_ATTR_RE = /\bwidth\s*=\s*["'][^"']+["']/i;
+const HEIGHT_ATTR_RE = /\bheight\s*=\s*["'][^"']+["']/i;
+export function analyzePdfHtml(html, opts) {
+    const issues = [];
+    if (html.length > 5_000_000) {
+        issues.push({
+            severity: "error",
+            code: "html_too_large",
+            message: "HTML is too large. Limit is 5 MB.",
+            suggestion: "Split content or remove embedded assets.",
+        });
+    }
+    if (!DOCTYPE_RE.test(html)) {
+        issues.push({
+            severity: "error",
+            code: "missing_doctype",
+            message: "HTML must start with <!doctype html>.",
+            suggestion: "Add <!doctype html> as the first line.",
+        });
+    }
+    if (!HTML_RE.test(html)) {
+        issues.push({ severity: "error", code: "missing_html", message: "HTML must include <html>." });
+    }
+    if (!HEAD_RE.test(html)) {
+        issues.push({ severity: "error", code: "missing_head", message: "HTML must include <head>." });
+    }
+    if (!BODY_RE.test(html)) {
+        issues.push({ severity: "error", code: "missing_body", message: "HTML must include <body>." });
+    }
+    if (!TITLE_RE.test(html)) {
+        issues.push({
+            severity: "warning",
+            code: "missing_title",
+            message: "HTML has no <title>.",
+            suggestion: "Add a descriptive document title for previews and manifests.",
+        });
+    }
+    if (!VIEWPORT_RE.test(html)) {
+        issues.push({
+            severity: "info",
+            code: "missing_viewport",
+            message: "HTML has no viewport meta tag.",
+            suggestion: "Add <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">.",
+        });
+    }
+    if (!PAGE_RE.test(html)) {
+        issues.push({
+            severity: "warning",
+            code: "missing_page_css",
+            message: "HTML has no @page CSS rule.",
+            suggestion: "Add @page { size: A4; margin: 18mm 16mm; } for predictable PDF pagination.",
+        });
+    }
+    if (!PRINT_MEDIA_RE.test(html)) {
+        issues.push({
+            severity: "info",
+            code: "missing_print_media",
+            message: "HTML has no @media print block.",
+            suggestion: "Add @media print for PDF-only layout tweaks.",
+        });
+    }
+    if (!PRINT_COLOR_ADJUST_RE.test(html)) {
+        issues.push({
+            severity: "warning",
+            code: "missing_print_color_adjust",
+            message: "CSS does not force exact print colors.",
+            suggestion: "Add print-color-adjust: exact and -webkit-print-color-adjust: exact on html/body.",
+        });
+    }
+    if (!BREAK_INSIDE_RE.test(html)) {
+        issues.push({
+            severity: "info",
+            code: "missing_break_avoidance",
+            message: "No break-inside avoidance rule detected.",
+            suggestion: "Use break-inside: avoid on cards, tables, signatures, and key sections.",
+        });
+    }
+    const remoteMatches = [...html.matchAll(REMOTE_SRC_RE)];
+    if (!opts?.allowRemoteAssets && remoteMatches.length > 0) {
+        issues.push({
+            severity: "error",
+            code: "remote_assets_disabled",
+            message: `Remote assets are disabled, but ${remoteMatches.length} remote src/href reference(s) were found.`,
+            suggestion: "Use local ./assets files, data URLs, or pass allowRemoteAssets=true.",
+        });
+    }
+    else if (remoteMatches.length > 0) {
+        issues.push({
+            severity: "warning",
+            code: "remote_assets",
+            message: `${remoteMatches.length} remote src/href reference(s) found.`,
+            suggestion: "Prefer local assets for reproducible PDF renders.",
+        });
+    }
+    if (FIXED_RE.test(html)) {
+        issues.push({
+            severity: "warning",
+            code: "position_fixed",
+            message: "CSS uses position: fixed, which can repeat or overlap across PDF pages.",
+            suggestion: "Use normal flow layout unless fixed headers/footers were intentional and tested.",
+        });
+    }
+    if (ABSOLUTE_RE.test(html)) {
+        issues.push({
+            severity: "info",
+            code: "position_absolute",
+            message: "CSS uses position: absolute.",
+            suggestion: "Check pagination carefully; absolute elements can overlap page breaks.",
+        });
+    }
+    if (WIDE_WIDTH_RE.test(html)) {
+        issues.push({
+            severity: "warning",
+            code: "wide_layout",
+            message: "A very wide width/min-width rule was detected.",
+            suggestion: "Keep printable content within the page width, usually max-width: 180mm for A4 portrait.",
+        });
+    }
+    const images = html.match(IMAGE_RE) ?? [];
+    const imagesWithoutDimensions = images.filter((img) => !WIDTH_ATTR_RE.test(img) || !HEIGHT_ATTR_RE.test(img)).length;
+    if (imagesWithoutDimensions > 0) {
+        issues.push({
+            severity: "info",
+            code: "images_without_dimensions",
+            message: `${imagesWithoutDimensions} image(s) lack width or height attributes.`,
+            suggestion: "Set image dimensions to reduce layout shifts and improve render predictability.",
+        });
+    }
+    return issues;
+}
+export function hasBlockingPdfHtmlIssues(issues) {
+    return issues.some((issue) => issue.severity === "error");
+}

package/dist/sdk/coding-agent/core/extensions/native-extensions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-extensions.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/extensions/native-extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,aAAa,CAAC;IAChD;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAC;IACxB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,uBAAuB,EAiGtD,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAElF;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAI1G;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IAClG,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC,CAUD"}
+{"version":3,"file":"native-extensions.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/extensions/native-extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,aAAa,CAAC;IAChD;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAC;IACxB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,uBAAuB,EA4GtD,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAElF;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAI1G;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IAClG,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC,CAUD"}

package/dist/sdk/coding-agent/core/extensions/native-extensions.js

@@ -107,6 +107,16 @@ export const NATIVE_EXTENSIONS = [
         defaultEnabled: true,
         tags: ["web", "fetch", "reading"],
     },
+    {
+        id: "pdf",
+        label: "PDF Generator",
+        description: "Generates polished PDF documents from editable HTML sources. " +
+            "HTML can be refined with designer tools before rendering or re-rendered after edits.",
+        category: "automation",
+        entryPath: "src/extensions/pdf/index.ts",
+        defaultEnabled: true,
+        tags: ["pdf", "html", "documents", "playwright", "design"],
+    },
 ];
 /**
  * Look up a native extension by id. Returns undefined for unknown ids.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.69",
+  "version": "0.9.71",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,