inkoxide 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eddie Roman
+
+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/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# inkoxide
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native PDF engine: a declarative document tree (JSON or MessagePack) in,
+PDF bytes out.
+
+```sh
+npm install inkoxide
+```
+
+Prebuilt binaries ship as per-platform packages that npm installs
+automatically (as optional dependencies) for the current platform:
+
+| Platform              | Package                     |
+| --------------------- | --------------------------- |
+| Linux x64 (glibc)     | `@inkoxide/linux-x64-gnu`   |
+| Linux x64 (musl)      | `@inkoxide/linux-x64-musl`  |
+| Linux arm64 (glibc)   | `@inkoxide/linux-arm64-gnu` |
+| macOS arm64           | `@inkoxide/darwin-arm64`    |
+| macOS x64             | `@inkoxide/darwin-x64`      |
+| Windows x64           | `@inkoxide/win32-x64-msvc`  |
+
+Linux glibc builds need glibc 2.35 or newer. Node.js 18 or newer.
+Other platforms: build from source with `scripts/build-node.sh`, which
+puts `inkoxide.<platform>.node` next to the loader.
+
+```js
+import { readFileSync, writeFileSync } from 'node:fs';
+import { registerFont, render, validate, InkoxideError } from 'inkoxide';
+
+// Once at startup: fonts live in a process-wide cache.
+registerFont('Inter-Regular', readFileSync('fonts/Inter-Regular.ttf'));
+
+const doc = {
+  version: 1,
+  fonts: [{ id: 'Inter-Regular', family: 'Inter' }],
+  pages: [{ size: { width: 595.28, height: 841.89 }, margin: { top: 48, right: 48, bottom: 48, left: 48 },
+            children: [{ type: 'text', runs: [{ text: 'Hello', font: 'Inter-Regular', size: 24 }] }] }],
+};
+
+try {
+  // Runs on the libuv pool; the event loop keeps running.
+  const pdf = await render(JSON.stringify(doc), { images: { logo: readFileSync('logo.jpg') } });
+  writeFileSync('out.pdf', pdf);
+} catch (e) {
+  if (!(e instanceof InkoxideError)) throw e;
+  // e.code: 'UNKNOWN_FONT', 'INVALID_VALUE', …, 'INVALID_ARGUMENT' or 'INTERNAL'
+  // e.path: 'pages[0].children[0].runs[0].font' ('' when not tied to a location)
+  console.error(e.code, e.path, e.message);
+}
+
+// All problems at once, without rendering: [{ code, path, message }, …]
+console.log(validate(JSON.stringify(doc)));
+```
+
+Options, defaults and error codes are typed in `index.d.ts` and described
+in `docs/API.md`. Schema reference: `docs/SCHEMA.md` and `schema/EXAMPLES.md`.

package/index.d.ts

@@ -0,0 +1,123 @@
+// Public contract of the `inkoxide` npm package. Hand-written; keep in
+// sync with crates/node/src/lib.rs and npm/index.js.
+
+/**
+ * Codes of document problems, from `validate` and from a failed `render`
+ * (mirrors Rust `ValidationCode`). New codes may be added in minor
+ * versions; handle unknown strings.
+ */
+export type ValidationCode =
+  | 'PARSE_ERROR'
+  | 'UNSUPPORTED_VERSION'
+  | 'UNKNOWN_FIELD'
+  | 'MISSING_FIELD'
+  | 'INVALID_TYPE'
+  | 'INVALID_VALUE'
+  | 'OUT_OF_RANGE'
+  | 'DUPLICATE_ID'
+  | 'UNKNOWN_FONT'
+  | 'FONT_NOT_REGISTERED'
+  | 'UNKNOWN_IMAGE'
+  | 'INVALID_IMAGE'
+  | 'IMAGE_TOO_LARGE'
+  | 'STYLE_NOT_APPLICABLE'
+  | 'INVALID_TABLE'
+  | 'INVALID_NODE'
+  | 'UNKNOWN_ANCHOR';
+
+/**
+ * Every `InkoxideError.code`: a document problem, a resource failure
+ * (mirrors Rust `InkoxideError::code`), a JS argument napi could not
+ * convert or that is out of range (`INVALID_ARGUMENT`), or a bug inside
+ * the engine (`INTERNAL`; the process keeps running).
+ */
+export type ErrorCode =
+  | ValidationCode
+  | 'FONT_ERROR'
+  | 'IMAGE_ERROR'
+  | 'LAYOUT_ERROR'
+  | 'PDF_ERROR'
+  | 'HYPHENATION_ERROR'
+  | 'INVALID_ARGUMENT'
+  | 'INTERNAL';
+
+/** Mirrors Rust `RenderOptions` (camelCase), plus the per-render inputs. */
+export interface RenderOptions {
+  /** Input encoding of `doc`. Default `"json"`. */
+  format?: 'json' | 'msgpack';
+  /** Flate-compress page content streams. Default `true`. */
+  compress?: boolean;
+  /** Flate level 0–9, used when `compress` is on. Default `6`. */
+  compressionLevel?: number;
+  /**
+   * RFC 3339 timestamp written as the creation date; overrides
+   * `meta.creationDate`. With neither set no date is written. Default: none.
+   */
+  creationDate?: string;
+  /** Worker threads for this render. Default: all cores. `1` renders on one thread. */
+  threads?: number;
+  /** Embed only the glyphs the document uses. Default `true`; `false` embeds whole fonts. */
+  subsetFonts?: boolean;
+  /**
+   * Write PDF/A-2b (archival): XMP metadata, an sRGB output intent and a
+   * file identifier. CMYK JPEGs are converted to RGB. Default `false`.
+   */
+  pdfA?: boolean;
+  /** Image bytes (JPEG, PNG, GIF, WebP or SVG) by id, for this document only. */
+  images?: Record<string, Uint8Array>;
+}
+
+export interface ValidationError {
+  /** Stable machine-readable code, e.g. `"UNKNOWN_FONT"`. */
+  code: ValidationCode;
+  /** Location in the document, e.g. `"pages[0].children[3].runs[1].font"`. */
+  path: string;
+  /** Human-readable description. */
+  message: string;
+}
+
+/** Thrown (or rejected) by every function on failure. */
+export class InkoxideError extends Error {
+  readonly name: 'InkoxideError';
+  readonly code: ErrorCode;
+  /** Empty for errors that are not tied to a document location. */
+  readonly path: string;
+}
+
+/** Registers (or replaces) a TrueType or CFF OpenType font in the process-wide cache. */
+export function registerFont(id: string, data: Uint8Array): void;
+/** Removes a registered font; returns whether it existed. */
+export function unregisterFont(id: string): boolean;
+/**
+ * Registers (or replaces), for all later renders, TeX hyphenation patterns
+ * for a language: a hyph-utf8 file such as `hyph-en-us.tex` with
+ * `\patterns{…}` and optional `\hyphenation{…}` groups, in UTF-8.
+ * `lang` is a BCP-47 tag (`"en"`, `"en-GB"`); patterns apply to its
+ * language. Registered patterns win over the built-in ones. Throws
+ * `HYPHENATION_ERROR` for malformed patterns.
+ */
+export function registerHyphenationPatterns(lang: string, data: Uint8Array | string): void;
+/** Removes registered patterns; returns whether there were any. */
+export function unregisterHyphenationPatterns(lang: string): boolean;
+/**
+ * Validates a document against the schema and the registered fonts. Image
+ * references are checked only when `images` is given.
+ */
+export function validate(
+  doc: Uint8Array | string,
+  format?: 'json' | 'msgpack',
+  images?: Record<string, Uint8Array>,
+): ValidationError[];
+/** Renders to PDF on the libuv thread pool; never blocks the event loop. */
+export function render(doc: Uint8Array | string, options?: RenderOptions): Promise<Uint8Array>;
+/** Renders on the calling thread (CLIs, tests). */
+export function renderSync(doc: Uint8Array | string, options?: RenderOptions): Uint8Array;
+export interface Version {
+  /** Engine version, e.g. `"0.1.0"`. */
+  engine: string;
+  /** The document `version` this engine reads. */
+  schema: number;
+  /** Commit the native binary was built from (12 hex digits), or `"unknown"`. */
+  gitSha: string;
+}
+export function version(): Version;

package/index.js

@@ -0,0 +1,126 @@
+'use strict';
+// Loader for the native binding plus the JS-side error type. Hand-written
+// and reviewed together with index.d.ts (the public contract).
+
+const { existsSync } = require('node:fs');
+const { join } = require('node:path');
+
+function isMusl() {
+  if (process.platform !== 'linux') return false;
+  try {
+    const report = process.report && process.report.getReport();
+    return !(report && report.header && report.header.glibcVersionRuntime);
+  } catch {
+    return false;
+  }
+}
+
+function platformTriple() {
+  const { platform, arch } = process;
+  if (platform === 'linux') return `linux-${arch}-${isMusl() ? 'musl' : 'gnu'}`;
+  if (platform === 'win32') return `win32-${arch}-msvc`;
+  return `${platform}-${arch}`;
+}
+
+function loadNative() {
+  const triple = platformTriple();
+  const local = join(__dirname, `inkoxide.${triple}.node`);
+  if (existsSync(local)) return require(local);
+  try {
+    return require(`@inkoxide/${triple}`);
+  } catch (e) {
+    throw new Error(
+      `inkoxide: no native binary for ${triple}. ` +
+        `Build one with scripts/build-node.sh or install @inkoxide/${triple}. (${e.message})`,
+    );
+  }
+}
+
+const native = loadNative();
+
+class InkoxideError extends Error {
+  constructor(code, path, message) {
+    super(path ? `${code} at ${path}: ${message}` : `${code}: ${message}`);
+    this.name = 'InkoxideError';
+    this.code = code;
+    this.path = path;
+    this.detail = message;
+  }
+}
+
+// napi statuses that mean a JS value had the wrong type.
+const ARGUMENT_STATUSES = new Set([
+  'InvalidArg',
+  'ObjectExpected',
+  'StringExpected',
+  'NameExpected',
+  'FunctionExpected',
+  'NumberExpected',
+  'BooleanExpected',
+  'ArrayExpected',
+  'BigintExpected',
+  'DateExpected',
+  'ArrayBufferExpected',
+]);
+
+function engineError(code, path, message, cause) {
+  const err = new InkoxideError(code, path, message);
+  // Keep `message` the engine's text, as documented.
+  Object.defineProperty(err, 'message', { value: message, enumerable: false, writable: true });
+  if (cause) err.cause = cause;
+  return err;
+}
+
+// Every failure surfaces as an InkoxideError: the engine's own codes, or
+// INVALID_ARGUMENT for values napi could not convert, or INTERNAL.
+function wrapError(e) {
+  if (e instanceof InkoxideError) return e;
+  const text = e && typeof e.message === 'string' ? e.message : String(e);
+  if (text.startsWith('{')) {
+    try {
+      const { code, path, message } = JSON.parse(text);
+      return engineError(code, path, message);
+    } catch {
+      /* not ours */
+    }
+  }
+  const code = e && ARGUMENT_STATUSES.has(e.code) ? 'INVALID_ARGUMENT' : 'INTERNAL';
+  return engineError(code, '', text, e);
+}
+
+function call(fn, args) {
+  try {
+    return fn(...args);
+  } catch (e) {
+    throw wrapError(e);
+  }
+}
+
+function toUint8Array(b) {
+  // Buffer is a Uint8Array subclass; hand back a plain view, no copy.
+  return new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
+}
+
+// Plain `exports.x =` assignments so ESM `import { render } from 'inkoxide'`
+// sees named exports.
+exports.InkoxideError = InkoxideError;
+exports.registerFont = (id, data) => call(native.registerFont, [id, data]);
+exports.unregisterFont = (id) => call(native.unregisterFont, [id]);
+exports.registerHyphenationPatterns = (lang, data) =>
+  call(native.registerHyphenationPatterns, [lang, data]);
+exports.unregisterHyphenationPatterns = (lang) =>
+  call(native.unregisterHyphenationPatterns, [lang]);
+exports.validate = (doc, format, images) =>
+  call(native.validate, [doc, format ?? undefined, images ?? undefined]);
+exports.render = async (doc, options) => {
+  try {
+    return toUint8Array(await native.render(doc, options ?? undefined));
+  } catch (e) {
+    throw wrapError(e);
+  }
+};
+exports.renderSync = (doc, options) =>
+  toUint8Array(call(native.renderSync, [doc, options ?? undefined]));
+exports.version = () => call(native.version, []);
+// Test hook (not public API): a panic behind the native boundary.
+Object.defineProperty(exports, '__testPanic', { value: () => call(native.__testPanic, []) });

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "inkoxide",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Native PDF layout and rendering engine: declarative document tree in, PDF bytes out.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eddiesr93/inkoxide.git"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "engines": {
+    "node": ">= 18"
+  },
+  "optionalDependencies": {
+    "@inkoxide/linux-x64-gnu": "0.1.0",
+    "@inkoxide/linux-x64-musl": "0.1.0",
+    "@inkoxide/linux-arm64-gnu": "0.1.0",
+    "@inkoxide/darwin-arm64": "0.1.0",
+    "@inkoxide/darwin-x64": "0.1.0",
+    "@inkoxide/win32-x64-msvc": "0.1.0"
+  }
+}