@spectastic/render 0.1.0-pre.25

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Corbin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The Playwright-backed `Renderer` port implementation (spec 106-visual-render,
+ * T-113, FR-003/NFR-001).
+ *
+ * This is the only file in the repo that knows what a browser is —
+ * `@spectastic/core` declares the `Renderer` shape (`packages/core/src/types.ts`)
+ * and never imports this package, enforced by the `no-core-to-render`
+ * dependency-cruiser rule. This file re-declares the same shape structurally
+ * rather than importing `@spectastic/core`, so this package builds and tests
+ * standalone with no core in its dependency graph — the same boundary the
+ * ports-and-adapters decision (design.html D-003) calls for.
+ *
+ * NFR-001: at most one browser process per run — `render()` launches
+ * Chromium exactly once and captures every labelled artboard from that one
+ * session, however many the source declares.
+ */
+interface RenderCapture {
+    /** The artboard's own declared label, unmodified — naming/slugging is the
+     *  caller's job (render-naming.ts), not this port's. */
+    label: string;
+    bytes: Uint8Array;
+    consoleErrors: string[];
+}
+interface RenderRunResult {
+    captures: RenderCapture[];
+}
+interface Renderer {
+    checkEgress(): Promise<boolean>;
+    render(location: string): Promise<RenderRunResult>;
+}
+declare function playwrightRenderer(): Renderer;
+
+export { type RenderCapture, type RenderRunResult, type Renderer, playwrightRenderer };

package/dist/index.js

@@ -0,0 +1,59 @@
+import { chromium } from 'playwright';
+
+// src/index.ts
+var RUNTIME_CDN = "https://unpkg.com";
+async function reachable(url, timeoutMs = 5e3) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { method: "HEAD", signal: controller.signal });
+    return response.status < 500;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var ARTBOARD_SELECTOR = "[data-screen-label]";
+function playwrightRenderer() {
+  return {
+    async checkEgress() {
+      return reachable(RUNTIME_CDN);
+    },
+    async render(location) {
+      const browser = await chromium.launch();
+      try {
+        const page = await browser.newPage();
+        let pending = [];
+        page.on("console", (msg) => {
+          if (msg.type() === "error") pending.push(msg.text());
+        });
+        page.on("pageerror", (err) => {
+          pending.push(String(err));
+        });
+        await page.goto(location, { waitUntil: "networkidle" });
+        const artboards = page.locator(ARTBOARD_SELECTOR);
+        const labels = await artboards.evaluateAll(
+          (elements) => elements.map((el) => el.getAttribute("data-screen-label") ?? "")
+        );
+        const captures = [];
+        for (let i = 0; i < labels.length; i++) {
+          pending = [];
+          const bytes = await artboards.nth(i).screenshot();
+          captures.push({
+            label: labels[i],
+            bytes: new Uint8Array(bytes),
+            consoleErrors: [...pending]
+          });
+        }
+        return { captures };
+      } finally {
+        await browser.close();
+      }
+    }
+  };
+}
+
+export { playwrightRenderer };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AA4CA,IAAM,WAAA,GAAc,mBAAA;AAEpB,eAAe,SAAA,CAAU,GAAA,EAAa,SAAA,GAAY,GAAA,EAAwB;AACxE,EAAA,MAAM,UAAA,GAAa,IAAI,eAAA,EAAgB;AACvC,EAAA,MAAM,QAAQ,UAAA,CAAW,MAAM,UAAA,CAAW,KAAA,IAAS,SAAS,CAAA;AAC5D,EAAA,IAAI;AACF,IAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,GAAA,EAAK,EAAE,QAAQ,MAAA,EAAQ,MAAA,EAAQ,UAAA,CAAW,MAAA,EAAQ,CAAA;AAG/E,IAAA,OAAO,SAAS,MAAA,GAAS,GAAA;AAAA,EAC3B,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,KAAA;AAAA,EACT,CAAA,SAAE;AACA,IAAA,YAAA,CAAa,KAAK,CAAA;AAAA,EACpB;AACF;AAMA,IAAM,iBAAA,GAAoB,qBAAA;AAEnB,SAAS,kBAAA,GAA+B;AAC7C,EAAA,OAAO;AAAA,IACL,MAAM,WAAA,GAAc;AAClB,MAAA,OAAO,UAAU,WAAW,CAAA;AAAA,IAC9B,CAAA;AAAA,IAEA,MAAM,OAAO,QAAA,EAA4C;AACvD,MAAA,MAAM,OAAA,GAAU,MAAM,QAAA,CAAS,MAAA,EAAO;AACtC,MAAA,IAAI;AACF,QAAA,MAAM,IAAA,GAAO,MAAM,OAAA,CAAQ,OAAA,EAAQ;AAMnC,QAAA,IAAI,UAAoB,EAAC;AACzB,QAAA,IAAA,CAAK,EAAA,CAAG,SAAA,EAAW,CAAC,GAAA,KAAQ;AAC1B,UAAA,IAAI,GAAA,CAAI,MAAK,KAAM,OAAA,UAAiB,IAAA,CAAK,GAAA,CAAI,MAAM,CAAA;AAAA,QACrD,CAAC,CAAA;AACD,QAAA,IAAA,CAAK,EAAA,CAAG,WAAA,EAAa,CAAC,GAAA,KAAQ;AAC5B,UAAA,OAAA,CAAQ,IAAA,CAAK,MAAA,CAAO,GAAG,CAAC,CAAA;AAAA,QAC1B,CAAC,CAAA;AAMD,QAAA,MAAM,KAAK,IAAA,CAAK,QAAA,EAAU,EAAE,SAAA,EAAW,eAAe,CAAA;AAEtD,QAAA,MAAM,SAAA,GAAY,IAAA,CAAK,OAAA,CAAQ,iBAAiB,CAAA;AAChD,QAAA,MAAM,MAAA,GAAS,MAAM,SAAA,CAAU,WAAA;AAAA,UAAY,CAAC,QAAA,KAC1C,QAAA,CAAS,GAAA,CAAI,CAAC,OAAO,EAAA,CAAG,YAAA,CAAa,mBAAmB,CAAA,IAAK,EAAE;AAAA,SACjE;AAEA,QAAA,MAAM,WAA4B,EAAC;AACnC,QAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,MAAA,CAAO,QAAQ,CAAA,EAAA,EAAK;AACtC,UAAA,OAAA,GAAU,EAAC;AAGX,UAAA,MAAM,QAAQ,MAAM,SAAA,CAAU,GAAA,CAAI,CAAC,EAAE,UAAA,EAAW;AAChD,UAAA,QAAA,CAAS,IAAA,CAAK;AAAA,YACZ,KAAA,EAAO,OAAO,CAAC,CAAA;AAAA,YACf,KAAA,EAAO,IAAI,UAAA,CAAW,KAAK,CAAA;AAAA,YAC3B,aAAA,EAAe,CAAC,GAAG,OAAO;AAAA,WAC3B,CAAA;AAAA,QACH;AAEA,QAAA,OAAO,EAAE,QAAA,EAAS;AAAA,MACpB,CAAA,SAAE;AACA,QAAA,MAAM,QAAQ,KAAA,EAAM;AAAA,MACtB;AAAA,IACF;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * The Playwright-backed `Renderer` port implementation (spec 106-visual-render,\n * T-113, FR-003/NFR-001).\n *\n * This is the only file in the repo that knows what a browser is —\n * `@spectastic/core` declares the `Renderer` shape (`packages/core/src/types.ts`)\n * and never imports this package, enforced by the `no-core-to-render`\n * dependency-cruiser rule. This file re-declares the same shape structurally\n * rather than importing `@spectastic/core`, so this package builds and tests\n * standalone with no core in its dependency graph — the same boundary the\n * ports-and-adapters decision (design.html D-003) calls for.\n *\n * NFR-001: at most one browser process per run — `render()` launches\n * Chromium exactly once and captures every labelled artboard from that one\n * session, however many the source declares.\n */\n\nimport { chromium } from 'playwright';\n\nexport interface RenderCapture {\n  /** The artboard's own declared label, unmodified — naming/slugging is the\n   *  caller's job (render-naming.ts), not this port's. */\n  label: string;\n  bytes: Uint8Array;\n  consoleErrors: string[];\n}\n\nexport interface RenderRunResult {\n  captures: RenderCapture[];\n}\n\nexport interface Renderer {\n  checkEgress(): Promise<boolean>;\n  render(location: string): Promise<RenderRunResult>;\n}\n\n/**\n * The CDN a Claude Design export's own runtime loads from. Named here\n * because design.html D-001's spike found a blocked `unpkg.com` yields four\n * unexpanded template labels rather than a clean failure — a healthy-looking\n * page that lied. Hard-coding it is a recorded tradeoff (design.html\n * Consequences): it is the design tool's own choice of host, not this\n * verb's, and could change under us.\n */\nconst RUNTIME_CDN = 'https://unpkg.com';\n\nasync function reachable(url: string, timeoutMs = 5000): Promise<boolean> {\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), timeoutMs);\n  try {\n    const response = await fetch(url, { method: 'HEAD', signal: controller.signal });\n    // Any response at all (even a 4xx from a HEAD the CDN doesn't like) means\n    // the host was reached — only a network failure means it wasn't.\n    return response.status < 500;\n  } catch {\n    return false;\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/** Selector every artboard declares itself under — the same\n *  `[data-screen-label]` convention the two-artboards fixture\n *  (packages/render/test/fixtures/two-artboards.html) and design.html §9\n *  name. */\nconst ARTBOARD_SELECTOR = '[data-screen-label]';\n\nexport function playwrightRenderer(): Renderer {\n  return {\n    async checkEgress() {\n      return reachable(RUNTIME_CDN);\n    },\n\n    async render(location: string): Promise<RenderRunResult> {\n      const browser = await chromium.launch();\n      try {\n        const page = await browser.newPage();\n\n        // Errors are attributed to the artboard capturing when they fire —\n        // reset before each capture, read after it. FR-009's manifest wiring\n        // (T-310/T-311) is what actually reports these; this port's job is\n        // only to not let them fall on the floor between browser and caller.\n        let pending: string[] = [];\n        page.on('console', (msg) => {\n          if (msg.type() === 'error') pending.push(msg.text());\n        });\n        page.on('pageerror', (err) => {\n          pending.push(String(err));\n        });\n\n        // 'networkidle' rather than 'load': design.html's own grounding row\n        // (\"Artboards exist only after the runtime executes\") found a design\n        // export's labels are template placeholders until its own script has\n        // run and settled, which 'load' alone does not wait for.\n        await page.goto(location, { waitUntil: 'networkidle' });\n\n        const artboards = page.locator(ARTBOARD_SELECTOR);\n        const labels = await artboards.evaluateAll((elements) =>\n          elements.map((el) => el.getAttribute('data-screen-label') ?? ''),\n        );\n\n        const captures: RenderCapture[] = [];\n        for (let i = 0; i < labels.length; i++) {\n          pending = [];\n          // Each artboard's OWN bounds, never the page (FR-003) — a locator\n          // screenshot crops to the matched element's box.\n          const bytes = await artboards.nth(i).screenshot();\n          captures.push({\n            label: labels[i]!,\n            bytes: new Uint8Array(bytes),\n            consoleErrors: [...pending],\n          });\n        }\n\n        return { captures };\n      } finally {\n        await browser.close();\n      }\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@spectastic/render",
+  "version": "0.1.0-pre.25",
+  "description": "Playwright-backed Renderer port implementation for spectastic's visual render verb. Isolates the browser dependency behind a package boundary so @spectastic/core never imports one.",
+  "keywords": [
+    "spectastic",
+    "playwright",
+    "render",
+    "screenshot"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "homepage": "https://github.com/spectastic/spectastic#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spectastic/spectastic.git",
+    "directory": "packages/render"
+  },
+  "bugs": {
+    "url": "https://github.com/spectastic/spectastic/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "playwright": "1.62.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}