@notedge/panduck 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notedge/panduck",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Panduck document conversion bindings (Node-API + TypeScript)",
   "type": "module",
   "license": "MPL-2.0",
@@ -19,6 +19,7 @@
   "files": [
     "bin",
     "locales",
+    "readme.md",
     "src"
   ],
   "engines": {
@@ -29,16 +30,16 @@
     "test:e2e": "tsx --test tests/**/*.test.ts"
   },
   "dependencies": {
+    "@notedge/panduck-unknown-wasm32": "0.0.2",
     "@vmz/commander": "^0.2.0",
     "jiti": "^2.4.2"
   },
   "optionalDependencies": {
-    "@notedge/panduck-darwin-arm64": "0.0.1",
-    "@notedge/panduck-darwin-x64": "0.0.1",
-    "@notedge/panduck-linux-arm64": "0.0.1",
-    "@notedge/panduck-linux-x64": "0.0.1",
-    "@notedge/panduck-win32-x64": "0.0.1",
-    "@notedge/panduck-unknown-wasm32": "0.0.1"
+    "@notedge/panduck-darwin-arm64": "0.0.2",
+    "@notedge/panduck-darwin-x64": "0.0.2",
+    "@notedge/panduck-linux-arm64": "0.0.2",
+    "@notedge/panduck-linux-x64": "0.0.2",
+    "@notedge/panduck-win32-x64": "0.0.2"
   },
   "repository": {
     "type": "git",

package/readme.md

@@ -1,5 +1,89 @@
 # @notedge/panduck
 
-TypeScript loader for Panduck Node-API bindings under the `@notedge` scope.
+Node 20+ package for Panduck: CLI commands, `loadPanduckNode()`, and WASM format discovery. Use it when you need to convert a local file between supported formats and read a `panduck.report/v1` JSON result.
 
-Build native artifacts first: `pnpm run build:napi` at the repo root.
+File conversion runs through the native binding on Node. The WASM export lists formats and version metadata only—do not expect `convertDocument` in the browser build for this release.
+
+## 🤖 Agent instructions
+
+`@notedge/panduck-skills` teaches coding agents to check routes before converting. It installs instructions, not this runtime.
+
+```bash
+npx @notedge/panduck-skills
+```
+
+## 📦 Install
+
+```bash
+npm install @notedge/panduck
+npx panduck doctor
+```
+
+Platform `.node` binaries install through optional dependencies (`@notedge/panduck-win32-x64`, `@notedge/panduck-linux-x64`, `@notedge/panduck-darwin-arm64`, and siblings).
+
+## 🔄 Convert one file
+
+Always write to a **new** path and keep the source unchanged:
+
+```bash
+npx panduck plan ./draft.docx --to markdown
+npx panduck convert ./draft.docx --to markdown -o ./draft.md --report ./draft.report.json
+```
+
+Check what the binding actually supports:
+
+```bash
+npx panduck formats --json
+```
+
+## 🔌 Node API
+
+```ts
+import { loadPanduckNode } from "@notedge/panduck/node";
+
+const panduck = loadPanduckNode();
+if (!panduck.supportsConversion?.("docx", "markdown")) {
+  throw new Error("route not available on this build");
+}
+const result = panduck.convertDocument!("docx", "markdown", "./draft.docx");
+console.log(result.reportJson);
+```
+
+Exports:
+
+- `@notedge/panduck` — package metadata
+- `@notedge/panduck/node` — `loadPanduckNode()`
+- `@notedge/panduck/wasm` — format discovery (no file conversion here)
+- `@notedge/panduck/cli` — programmatic CLI builder
+
+## 📊 Read the report
+
+Open `panduck.report/v1` JSON for `status`, `coverage`, `losses`, `diagnostics`, and `outputs`. A successful exit can still be `success_with_loss`—read losses before publishing converted content.
+
+`panduck inspect` helps audit container structure (for example DOCX package index) without promising a full semantic read.
+
+## ✅ Verified routes (native)
+
+When `supportsConversion(from, to)` is true:
+
+| From | To |
+|------|-----|
+| `docx` | `markdown`, `docx` |
+| `markdown` | `markdown`, `docx` |
+| `notedown` | `markdown` |
+| `epub` | `markdown` |
+
+Registered format names beyond these pairs may read or list without a working writer. Plan before batch jobs.
+
+## 🔧 Troubleshooting
+
+| Symptom | Check |
+|---------|-------|
+| `Unsupported platform for Panduck native bindings` | OS/CPU mismatch or missing optional platform package |
+| `conversion pipeline is not wired yet` | Route not implemented—use `plan` / `supportsConversion` |
+| Output exists but quality is wrong | Report `losses` for tables, footnotes, images |
+| Browser bundle cannot convert | Use Node native path for file conversion |
+
+Repository: https://github.com/notedge/panduck
+
+License: MPL-2.0

package/src/index.ts

@@ -1,6 +1,6 @@
 export type { PanduckBindings, PanduckWasmOptions } from "./types.js";
 export { loadPanduckNative, loadPanduckNode } from "./node/index.js";
-export { loadPanduckWasm } from "./wasm/index.js";
+export { loadPanduckWeb, loadPanduckWasm } from "./wasm/index.js";
 export { buildPanduckCli, runCli, getFormatRegistry, ExitCode, REPORT_SCHEMA_VERSION } from "./cli/index.js";
 export type { FormatRecord, PanduckReport, CapabilityState } from "./cli/index.js";
 

package/src/wasm/index.ts

@@ -1,2 +1,14 @@
+import { loadPanduckWasm } from "./load.js";
+
 export type { PanduckBindings, PanduckWasmOptions } from "../types.js";
 export { loadPanduckWasm } from "./load.js";
+
+let cached: Promise<import("../types.js").PanduckBindings> | undefined;
+
+/** Cached WASM binding loader. */
+export function loadPanduckWeb(): Promise<import("../types.js").PanduckBindings> {
+    if (!cached) {
+        cached = loadPanduckWasm();
+    }
+    return cached;
+}

package/src/wasm/load.ts

@@ -1,23 +1,25 @@
 import type { PanduckBindings, PanduckWasmOptions } from "../types.js";
 
-type WasmModule = {
+const ARTIFACT_PACKAGE = "@notedge/panduck-unknown-wasm32";
+
+type WasmBinding = {
     default: (input?: { module_or_path?: string | URL }) => Promise<unknown>;
     panduckVersion: () => string;
     supportedFormats: () => string[];
     isSupportedFormat: (name: string) => boolean;
 };
 
-/** Load `@notedge/panduck-unknown-wasm32` and return the Panduck binding surface. */
+/** Load the WASM artifact from `@notedge/panduck-unknown-wasm32`. */
 export async function loadPanduckWasm(options: PanduckWasmOptions = {}): Promise<PanduckBindings> {
-    const wasm = (await import("@notedge/panduck-unknown-wasm32")) as WasmModule;
+    const binding = (await import(ARTIFACT_PACKAGE)) as WasmBinding;
     if (options.url) {
-        await wasm.default({ module_or_path: options.url });
+        await binding.default({ module_or_path: options.url });
     } else {
-        await wasm.default();
+        await binding.default();
     }
     return {
-        panduckVersion: () => wasm.panduckVersion(),
-        supportedFormats: () => wasm.supportedFormats(),
-        isSupportedFormat: (name) => wasm.isSupportedFormat(name),
+        panduckVersion: () => binding.panduckVersion(),
+        supportedFormats: () => binding.supportedFormats(),
+        isSupportedFormat: (name) => binding.isSupportedFormat(name),
     };
 }

package/src/wasm/panduck_wasm.d.ts

@@ -1,6 +0,0 @@
-declare module '@notedge/panduck-unknown-wasm32' {
-    export default function init(input?: { module_or_path?: string | URL }): Promise<unknown>;
-    export function panduckVersion(): string;
-    export function supportedFormats(): string[];
-    export function isSupportedFormat(name: string): boolean;
-}