@pajh/buldng 0.0.3 → 0.0.4

package/package.json

@@ -1,19 +1,23 @@
 {
   "name": "@pajh/buldng",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
-  "main": "dist/buldng-lib.js",
-  "files": ["dist"],
+  "main": "./src/buldng-lib.js",
+  "files": [
+    "src"
+  ],
   "scripts": {
-    "build": "node build.js"
+    "check": "tsc --noEmit",
+    "build": "npm run check"
   },
   "dependencies": {
-   "esbuild": "^0.28.1",
-   "typescript": "^7.0.2"
+    "esbuild": "^0.28.2"
   },
   "devDependencies": {
-   "stylelint": "^17.14.1",
-   "stylelint-config-standard": "^40.0.0"
-}
-
+    "typescript": "^6.0.3"
+  },
+  "exports": {
+    ".": "./src/buldng-lib.js",
+    "./web": "./src/buldng-web.ts"
+  }
 }

package/src/buldng-dev-errors.js

@@ -0,0 +1,84 @@
+// Development-only error overlay installed by the local preview server.
+// The production build never references this file from its HTML.
+
+window.__buldngErrorOverlay = true;
+
+let shown = false;
+
+window.addEventListener("error", (event) => {
+  showError(event.error ?? event.message, "error");
+});
+
+window.addEventListener("unhandledrejection", (event) => {
+  showError(event.reason, "unhandledrejection");
+});
+
+function showError(reason, type) {
+  if (shown) return;
+  shown = true;
+
+  const message = getMessage(reason);
+  const stack = getStack(reason);
+  const overlay = document.createElement("aside");
+  overlay.id = "buldng-dev-error-overlay";
+  overlay.style.cssText = [
+    "position: fixed",
+    "z-index: 2147483647",
+    "left: 1rem",
+    "right: 1rem",
+    "bottom: 1rem",
+    "max-height: 70vh",
+    "overflow: auto",
+    "padding: 1rem 1.25rem",
+    "border: 2px solid #d33",
+    "border-radius: 8px",
+    "background: #240b0b",
+    "color: #fff",
+    "font: 16px/1.4 monospace",
+    "box-shadow: 0 4px 24px #0008",
+  ].join(";");
+
+  const close = document.createElement("button");
+  close.type = "button";
+  close.textContent = "Close";
+  close.style.cssText = "float:right; padding:.35rem .6rem; cursor:pointer";
+  close.addEventListener("click", () => overlay.remove());
+
+  const title = document.createElement("strong");
+  title.textContent = "BULDR preview: something broke";
+
+  const hint = document.createElement("p");
+  hint.textContent = `(${type}) Check the DevTools console for the full mapped stack.`;
+
+  const text = document.createElement("p");
+  text.textContent = message;
+
+  overlay.append(close, title, hint, text);
+  if (stack) {
+    const details = document.createElement("details");
+    const summary = document.createElement("summary");
+    summary.textContent = "Raw stack";
+    const pre = document.createElement("pre");
+    pre.textContent = stack;
+    pre.style.cssText = "white-space:pre-wrap; overflow-wrap:anywhere";
+    details.append(summary, pre);
+    overlay.appendChild(details);
+  }
+
+  document.body?.appendChild(overlay);
+}
+
+function getMessage(reason) {
+  if (reason instanceof Error && reason.message) return reason.message;
+  if (typeof reason === "string" && reason) return reason;
+  try {
+    const text = JSON.stringify(reason);
+    return text || "Unknown error";
+  } catch {
+    return String(reason) || "Unknown error";
+  }
+}
+
+function getStack(reason) {
+  return reason && typeof reason.stack === "string" ? reason.stack : "";
+}

package/{dist → src}/buldng-lib.js

@@ -7,7 +7,7 @@ import esbuild from "esbuild";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { readFileSync } from "node:fs";
-
+import { createRequire } from "node:module";
 import { WorkFile } from "./workfile.js";
 import { getDest, setSource, setDest, assertDestWrite, assertSourceRead, getInputs, looksLikeFilename, looksLikeHTML, 
   looksLikeCSS, looksLikeJS, ensureLeadingSlash, ensureWorkFile } from "./buldng-validate.js";
@@ -35,7 +35,8 @@ export default {
   pageHTML,
   buldngHTMLWrapper,
   reg,
-  printHeader
+  printHeader,
+  typescriptCheck
 };
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -57,6 +58,59 @@ export function reg(key, value) {
   return wf;
 }
 
+function findTSC() {
+    const localTSC = path.resolve("node_modules/.bin/tsc");
+
+    if (fs.existsSync(localTSC)) {
+        return localTSC; // Local compiler — correct
+    }
+
+    try {
+        const globalTSC = execSync("which tsc").toString().trim();
+        return globalTSC; // Global compiler — acceptable
+    } catch {
+        return null; // No compiler found
+    }
+}
+
+export function typescriptCheck() {
+    let hasTS = false;
+    const require = createRequire(import.meta.url);
+
+    try {
+        // Detect ANY installed TypeScript (local or global)
+        require.resolve("typescript");
+
+        hasTS = true;
+    } catch {
+        hasTS = false;
+    }
+
+    if (!hasTS) {
+        console.log("TypeScript not found — skipping TS checks");
+        return;
+    }
+
+    const { execSync } = require("node:child_process");
+    const tscPath = findTSC();
+
+    if (!tscPath) {
+        console.error("TypeScript compiler not found (local or global)");
+        process.exit(1);
+    }
+
+    console.log("Using TypeScript compiler:", tscPath);
+
+
+    try {
+        // npx will run local tsc if present, otherwise global tsc
+        execSync(`${tscPath} --noEmit`, { stdio: "inherit" });
+    } catch (err) {
+        throw new Error("TypeScript check failed");
+    }
+}
+
+
 let headerPrinted = false;
 export function printHeader(importMeta) {
   if (headerPrinted) return;
@@ -221,6 +275,9 @@ export function deepCopy(from, to) {
     // 2.5 Save camera.css to the site root (this triggers execution)
     const buldngCSS = new WorkFile("file", { absPath: packageFileAbs("buldng.css") }, []);
     buldngCSS.save("buldng.css");
+
+    const devErrors = new WorkFile("file", { absPath: packageFileAbs("buldng-dev-errors.js") }, []);
+    devErrors.save("buldng-dev-errors.js");
     
     // 3. Wrap project shell in buldng's wrapper.html
     const wrapperWF = new WorkFile("file", { absPath: packageFileAbs("wrapper.html") }, []);

package/{dist → src}/buldng-ops.js

@@ -93,6 +93,12 @@ export function op_compile(config, children) {
     }
 
     const child = children[0];
+    const compileOptions = {
+        minify: config.flags?.minify ?? true,
+        sourcemap: config.flags?.sourcemap ?? true,
+        format: config.flags?.format ?? "esm",
+        target: config.flags?.target ?? "esnext",
+    };
 
     // If child is a file WorkFile, use its absolute path directly
     if (child.op === "file" && child.config.absPath) {
@@ -101,10 +107,7 @@ export function op_compile(config, children) {
         const result = esbuild.buildSync({
             entryPoints: [entry],
             bundle: true,
-            minify: true,
-            sourcemap: true,
-            format: "esm",
-            target: "esnext",
+            ...compileOptions,
             write: false
         });
 
@@ -125,10 +128,7 @@ export function op_compile(config, children) {
             sourcefile: "input.ts"
         },
         bundle: true,
-        minify: true,
-        sourcemap: true,
-        format: "esm",
-        target: "esnext",
+        ...compileOptions,
         write: false
     });
 

package/src/buldng-web.ts

@@ -0,0 +1,267 @@
+// buldng-web.ts
+// Pure runtime API for buldng. The optional renderer only writes text into a caller-owned element.
+
+let errorPage: string | null = null;
+let listenersInstalled = false;
+let redirectStarted = false;
+
+declare global {
+  interface Window {
+    __buldngErrorOverlay?: boolean;
+  }
+}
+
+const ERROR_STORAGE_PREFIX = "buldng:error:";
+
+export type ErrorPayload = {
+  id: string;
+  type: "error" | "unhandledrejection";
+  message: string;
+  stack: string;
+  time: string;
+  url: string;
+  userAgent: string;
+  platform: string;
+  language: string;
+};
+
+/**
+ * Configure the global error handler.
+ * @param url A full URL path like "/error/" or "/fatal/".
+ */
+export function setErrorPage(url: string) {
+  if (typeof url !== "string" || !url.length) {
+    throw new Error("setErrorPage: URL must be a non-empty string");
+  }
+
+  // Normalize: ensure no accidental double slashes
+  errorPage = url.endsWith("/") ? url.slice(0, -1) : url;
+
+  // Install global listeners once. Calling setErrorPage again only changes the destination.
+  installGlobalErrorHandler();
+}
+
+/**
+ * Internal: installs global error + unhandled rejection handlers.
+ */
+function installGlobalErrorHandler() {
+  if (!errorPage || listenersInstalled || isErrorPage() || window.__buldngErrorOverlay) return;
+
+  listenersInstalled = true;
+
+  window.addEventListener("error", (event) => {
+    handleError({
+      type: "error",
+      reason: event.error ?? event.message,
+      fallbackMessage: event.message,
+    });
+  });
+
+  window.addEventListener("unhandledrejection", (event) => {
+    handleError({
+      type: "unhandledrejection",
+      reason: event.reason,
+      fallbackMessage: "Unhandled promise rejection",
+    });
+  });
+}
+
+/**
+ * Read an error payload previously saved by the global handler.
+ * Defaults to the errorId query parameter on the current page.
+ */
+export function readErrorPayload(id = getErrorId()): ErrorPayload | null {
+  if (!id) return null;
+
+  try {
+    const raw = localStorage.getItem(storageKey(id));
+    if (!raw) return null;
+
+    const payload: unknown = JSON.parse(raw);
+    return isErrorPayload(payload) ? payload : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read and remove an error payload. Useful for one-shot error pages.
+ */
+export function consumeErrorPayload(id = getErrorId()): ErrorPayload | null {
+  const payload = readErrorPayload(id);
+  if (id) {
+    try {
+      localStorage.removeItem(storageKey(id));
+    } catch {
+      // Storage may be unavailable or blocked; the payload was still safely read if possible.
+    }
+  }
+  return payload;
+}
+
+/**
+ * Render a payload as safe text inside a caller-owned element.
+ * Returns the payload that was rendered, or null when it was unavailable.
+ */
+export function renderErrorPayload(
+  elementId: string,
+  payload = readErrorPayload()
+): ErrorPayload | null {
+  const container = document.getElementById(elementId);
+  if (!container) return null;
+
+  container.replaceChildren();
+  if (!payload) {
+    const empty = document.createElement("p");
+    empty.textContent = "Error details are no longer available.";
+    container.appendChild(empty);
+    return null;
+  }
+
+  const details: Array<[string, string]> = [
+    ["Type", payload.type],
+    ["Message", payload.message],
+    ["Time", payload.time],
+    ["Page", payload.url],
+    ["User agent", payload.userAgent],
+    ["Platform", payload.platform],
+    ["Language", payload.language],
+  ];
+
+  const list = document.createElement("dl");
+  for (const [label, value] of details) {
+    const term = document.createElement("dt");
+    term.textContent = label;
+    const description = document.createElement("dd");
+    description.textContent = value;
+    list.append(term, description);
+  }
+
+  if (payload.stack) {
+    const stackLabel = document.createElement("h3");
+    stackLabel.textContent = "Stack";
+    const stack = document.createElement("pre");
+    stack.textContent = payload.stack;
+    list.append(stackLabel, stack);
+  }
+
+  container.appendChild(list);
+  return payload;
+}
+
+/**
+ * Return the error record ID from the current URL.
+ */
+export function getErrorId(): string | null {
+  return new URLSearchParams(location.search).get("errorId");
+}
+
+function handleError(info: {
+  type: ErrorPayload["type"];
+  reason: unknown;
+  fallbackMessage: string;
+}) {
+  if (redirectStarted || !errorPage) return;
+  redirectStarted = true;
+
+  const payload = buildPayload(info);
+  const stored = saveErrorPayload(payload);
+  redirect(payload, stored);
+}
+
+function buildPayload(info: {
+  type: ErrorPayload["type"];
+  reason: unknown;
+  fallbackMessage: string;
+}): ErrorPayload {
+  const id = createId();
+  const error = info.reason instanceof Error ? info.reason : null;
+
+  return {
+    id,
+    type: info.type,
+    message: getErrorMessage(info.reason, info.fallbackMessage),
+    stack: error?.stack ?? getErrorStack(info.reason),
+    time: new Date().toISOString(),
+    url: location.href,
+    userAgent: navigator.userAgent,
+    platform: navigator.platform,
+    language: navigator.language,
+  };
+}
+
+/**
+ * Redirect to the configured error page with a storage key, plus a small fallback.
+ */
+function redirect(payload: ErrorPayload, stored: boolean) {
+  if (!errorPage) return;
+
+  const destination = new URL(errorPage, location.href);
+  if (stored) {
+    destination.searchParams.set("errorId", payload.id);
+  } else {
+    destination.searchParams.set("type", payload.type);
+    destination.searchParams.set("message", payload.message.slice(0, 500));
+  }
+
+  window.location.href = destination.href;
+}
+
+function saveErrorPayload(payload: ErrorPayload): boolean {
+  try {
+    localStorage.setItem(storageKey(payload.id), JSON.stringify(payload));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function storageKey(id: string) {
+  return `${ERROR_STORAGE_PREFIX}${id}`;
+}
+
+function createId() {
+  if (typeof crypto.randomUUID === "function") return crypto.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+function isErrorPage() {
+  const destination = new URL(errorPage!, location.href);
+  const destinationPath = destination.pathname.replace(/\/$/, "") || "/";
+  const currentPath = location.pathname.replace(/\/$/, "") || "/";
+  return destination.origin === location.origin && destinationPath === currentPath;
+}
+
+function getErrorMessage(reason: unknown, fallback: string) {
+  if (reason instanceof Error && reason.message) return reason.message;
+  if (typeof reason === "string" && reason) return reason;
+  if (reason !== null && reason !== undefined) {
+    try {
+      const text = JSON.stringify(reason);
+      if (text) return text;
+    } catch {
+      // Fall through to the stable message below.
+    }
+  }
+  return fallback;
+}
+
+function getErrorStack(reason: unknown) {
+  if (!reason || typeof reason !== "object") return "";
+  const stack = (reason as { stack?: unknown }).stack;
+  return typeof stack === "string" ? stack : "";
+}
+
+function isErrorPayload(value: unknown): value is ErrorPayload {
+  if (!value || typeof value !== "object") return false;
+  const payload = value as Partial<ErrorPayload>;
+  return typeof payload.id === "string"
+    && (payload.type === "error" || payload.type === "unhandledrejection")
+    && typeof payload.message === "string"
+    && typeof payload.stack === "string"
+    && typeof payload.time === "string"
+    && typeof payload.url === "string"
+    && typeof payload.userAgent === "string"
+    && typeof payload.platform === "string"
+    && typeof payload.language === "string";
+}