gerbers-renderer 0.1.2 → 0.1.4

package/README.md

@@ -1,178 +1,254 @@
 # gerbers-renderer
 
-Frontend-only Gerber viewer for the web.
-Render PCB Gerbers directly in the browser. No backend. No CAM tools. No DFM.
+Pure frontend Gerber rendering for the web.
+Render PCB Gerber bundles (`.zip`, `.rar`) directly in the browser with zero backend, zero native dependencies.
 
-👉 Upload a gerbers.zip  
-👉 View Top / Bottom copper, mask, silkscreen, drills  
-👉 Pan, zoom, fit, grid  
-👉 Download the original Gerbers ZIP
+Designed for:
 
-## ✨ Features
+- Web apps
+- Browser extensions
+- CI previews
+- Manufacturing portals
+- DFM tools
 
-- Fully client-side (runs in the browser)
-- Accepts standard gerbers.zip exports
-- Automatic layer classification
-- Correct board masking and clipping
-- Top / Bottom view toggle
-- Grid overlay (mm / inch)
-- Designed to embed into any website
-- No framework dependency (not React/Vue/etc.)
+## Features
 
-## 🚀 Installation
+- 🧠 Gerber bundle detection (not just “try and fail”)
+- 📦 Supports `.zip` and `.rar` archives (browser-side)
+- 🎨 2D SVG-based board viewer
+- 🧩 Drop-in viewer that mounts into any DOM node
+- 🧪 Typed, deterministic render results
+- 🧼 No backend, no workers unless needed
+- ⚡ Vite, React, vanilla JS friendly
+
+## Installation
 
-### Install from npm (recommended)
 ```bash
 npm install gerbers-renderer
 ```
 
-### 🌐 CDN Usage (No Build Tools)
-```html
-<script src="https://unpkg.com/gerbers-renderer"></script>
-<script>
-  const { createBoardViewer, renderGerbersZip } = window.GerbersRenderer;
-</script>
+## Quick start (minimal)
+
+```typescript
+import { renderGerbers, createBoardViewer } from "gerbers-renderer";
+
+const viewer = createBoardViewer(document.getElementById("pcb")!);
+
+const file = input.files[0];
+const buffer = await file.arrayBuffer();
+
+const result = await renderGerbers(buffer, {
+  archiveWorkerUrl: "/libarchive-worker-bundle.js", // required for .rar
+});
+
+viewer.setData({
+  boardGeom: result.boardGeom,
+  layers: result.layers,
+});
+viewer.fit();
 ```
 
-Pin a version if needed:
+Always call `result.revoke()` when replacing a render.
+
+## Live demo
 
-```html
-<script src="https://unpkg.com/gerbers-renderer@0.1.0"></script>
+```bash
+git clone https://github.com/asappcb/gerbers-renderer
+npm install
+npm run dev
 ```
 
-## 🧩 Minimal Usage Example
+Open:
+👉 http://localhost:5173/demo/
+
+## Supported input formats
+
+| Format | Supported | Notes |
+|---|---:|---|
+| `.zip` | ✅ | Native via JSZip |
+| `.rar` | ✅ | Via libarchive.js (WASM) |
+| `.7z` | ❌ (future) | Detection works |
+| `.tar` | ❌ (future) | Detection works |
+| Directory | ✅ | Use `renderGerbersFiles` |
+
+## Gerber bundle detection
+
+Before rendering, you can detect whether an input is actually a Gerber bundle.
 
-**HTML**
-```html
-<input type="file" id="file" accept=".zip" />
-<div id="viewer" style="width:100%; height:600px;"></div>
+```typescript
+import { detectGerberBundle } from "gerbers-renderer";
+
+const result = await detectGerberBundle(buffer);
+
+if (!result.isGerber) {
+  console.log("Not a Gerber bundle:", result.reasons);
+}
 ```
 
-**JavaScript / TypeScript**
 ```typescript
-import { renderGerbersZip, createBoardViewer } from "gerbers-renderer";
+type GerberDetectResult = {
+  isGerber: boolean;
+  archiveType: "zip" | "rar" | "7z" | "tar" | "directory" | "single-file" | "unknown";
+  confidence: number; // 0.0 – 1.0
+  reasons: string[];
+  files?: string[];
+};
+```
 
-const input = document.getElementById("file") as HTMLInputElement;
-const host = document.getElementById("viewer")!;
+## Rendering APIs
 
-const viewer = createBoardViewer(host, {
-  onDownload: () => {
-    if (!lastZip) return;
-    const a = document.createElement("a");
-    const url = URL.createObjectURL(lastZip);
-    a.href = url;
-    a.download = lastZip.name;
-    a.click();
-    URL.revokeObjectURL(url);
+### `renderGerbers(...)` (recommended)
+
+Single high-level entrypoint.
+
+```typescript
+renderGerbers(
+  input: ArrayBuffer | Uint8Array,
+  options?: {
+    archiveWorkerUrl?: string; // required for rar
   }
-});
+): Promise<RenderResult>
+```
 
-let lastRender: any = null;
-let lastZip: File | null = null;
+Handles:
 
-input.addEventListener("change", async () => {
-  const file = input.files?.[0];
-  if (!file) return;
+- Archive detection
+- Unpacking
+- Validation
+- Rendering
 
-  lastZip = file;
-  if (lastRender) lastRender.revoke();
+### `renderGerbersZip(...)`
 
-  const out = await renderGerbersZip(file);
-  lastRender = out;
+Zip-only convenience wrapper.
 
-  viewer.setData({
-    boardGeom: out.boardGeom,
-    layers: out.layers
-  });
-});
+```typescript
+renderGerbersZip(input: File | Blob | ArrayBuffer | Uint8Array)
 ```
 
-That's it. No server. No workers. No build assumptions.
+### `renderGerbersFiles(...)`
 
-## 🧠 Core API
+Lowest-level API if you already have files.
 
-### `renderGerbersZip(file: File)`
+```typescript
+renderGerbersFiles(
+  files: Record<string, Uint8Array>
+)
+```
+
+## Viewer
 
-Parses and renders a Gerbers ZIP entirely in the browser.
+Create a drop-in board viewer:
 
-**Returns:**
 ```typescript
-{
-  boardGeom: {
-    widthMm: number;
-    heightMm: number;
-  },
-  layers: {
-    top_copper?: string;
-    bottom_copper?: string;
-    top_silk?: string;
-    bottom_silk?: string;
-    top_mask?: string;
-    bottom_mask?: string;
-    drills?: string;
-    top_board_mask?: string;
-    bottom_board_mask?: string;
+const viewer = createBoardViewer(container, {
+  onDownload: () => {
+    /* optional */
   },
-  revoke: () => void
-}
+});
+
+viewer.setData({
+  boardGeom,
+  layers,
+});
+
+viewer.setSideMode("top"); // "top" | "bottom"
+viewer.fit();
 ```
 
-Layer values are blob URLs containing SVGs.
+The viewer supports:
 
-Call `revoke()` when replacing or discarding a render.
+- Pan / zoom
+- Layer toggling
+- Top / bottom switching
+- Download hook (original Gerbers)
 
-### `createBoardViewer(host, options?)`
+## Return value
 
-Mounts an interactive PCB viewer into a DOM element.
+All render functions return a deterministic object:
 
 ```typescript
-createBoardViewer(host, {
-  onDownload?: () => void
-});
+type RenderResult = {
+  boardGeom: BoardGeom;
+  layers: ViewerLayers;
+  revoke: () => void; // revoke blob URLs
+};
+```
+
+Always call `revoke()` when replacing a render.
+
+## `.rar` support (important)
+
+To support `.rar` archives, you must host the libarchive worker bundle.
+
+Setup
+
+Copy:
+
+```text
+node_modules/libarchive.js/dist/worker-bundle.js
 ```
 
-The viewer handles:
-- pan / zoom / fit
-- Top / Bottom switching
-- layer visibility
-- board clipping mask
+To:
 
-The viewer is intentionally stateless with respect to parsing.
+```text
+public/libarchive-worker-bundle.js
+```
 
-## 📦 Download Behavior
+Then pass:
+
+```typescript
+renderGerbers(buffer, {
+  archiveWorkerUrl: "/libarchive-worker-bundle.js",
+});
+```
 
-The viewer does not decide what "Download" means.
+ZIP users do not pay this cost.
 
-Instead, you supply a handler via `onDownload`.
+## Error handling
 
-Typical use:
-- download the original gerbers.zip
-- export SVG layers
-- export screenshots
-- pipe into manufacturing workflows
+Errors are typed and structured.
 
-This keeps the viewer reusable across products.
+```typescript
+class GerberError extends Error {
+  code:
+    | "NOT_AN_ARCHIVE"
+    | "UNSUPPORTED_ARCHIVE"
+    | "NOT_GERBER"
+    | "MISSING_LAYERS"
+    | "PARSE_ERROR";
+  details?: any;
+}
+```
 
-## 🧭 Design Philosophy
+Always catch and inspect `error.code` in UI or CI.
 
-- Viewer ≠ parser ≠ renderer
-- Frontend-only by design
-- No assumptions about backend or manufacturing
-- Safe to embed anywhere
-- Easy to extend
+## What this is not
 
-This project is intentionally not a CAM tool or DFM checker.
+- ❌ Not a CAM tool
+- ❌ Not a DRC / DFM engine
+- ❌ Not a backend renderer
 
-## ❌ What This Is Not
+This library is intentionally focused on fast, accurate visualization.
 
-- Not a DFM rules engine
-- Not a fabrication quote system
-- Not a replacement for CAM software
+## Roadmap
 
-It's a fast, embeddable Gerber viewer.
+- 7z / tar unpacking
+- Inner-layer rendering
+- Canvas renderer
+- WASM-only core split
+- Headless CI validation mode
 
-## 📄 License
+## License
 
 MIT
 
-Use it freely in commercial or open-source projects.
+## Why this exists
+
+Most Gerber viewers:
+
+- require servers
+- are untyped
+- break in browsers
+- silently mis-detect archives
+
+gerbers-renderer is designed from first principles for modern web tooling.

package/dist/core/detect.d.ts

@@ -0,0 +1,2 @@
+import { GerberDetectResult } from './types';
+export declare function detectGerberBundle(input: ArrayBuffer | Uint8Array | Record<string, Uint8Array>): Promise<GerberDetectResult>;

package/dist/core/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class GerberError extends Error {
+    code: "NOT_AN_ARCHIVE" | "UNSUPPORTED_ARCHIVE" | "NOT_GERBER" | "MISSING_LAYERS" | "PARSE_ERROR";
+    details?: unknown;
+    constructor(code: GerberError["code"], message: string, details?: unknown);
+}

package/dist/core/list.d.ts

@@ -0,0 +1,2 @@
+import { GerberFileListResult } from './types';
+export declare function listGerberFiles(input: ArrayBuffer | Uint8Array | Record<string, Uint8Array>): Promise<GerberFileListResult>;

package/dist/core/types.d.ts

@@ -0,0 +1,18 @@
+export type GerberBundleType = "zip" | "rar" | "7z" | "tar" | "directory" | "single-file" | "unknown";
+export type GerberDetectResult = {
+    isGerber: boolean;
+    archiveType: GerberBundleType;
+    confidence: number;
+    reasons: string[];
+    files?: string[];
+};
+export type ListedLayer = {
+    filename: string;
+    type: "copper" | "mask" | "silk" | "drill" | "outline" | "unknown";
+    side?: "top" | "bottom" | "inner";
+};
+export type GerberFileListResult = {
+    layers: ListedLayer[];
+    boardOutlinePresent: boolean;
+    drillPresent: boolean;
+};