apex-ruby 1.0.18 → 1.0.20

data/ext/apex_ext/apex_src/docs/superpowers/plans/2026-07-19-apex-node-npm.md

@@ -0,0 +1,1148 @@
+# Apex Node.js npm Package Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use
+> superpowers:subagent-driven-development (recommended) or
+> superpowers:executing-plans to implement this plan task-by-task. Steps use
+> checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship `@apexmarkdown/apex` as a Node.js native binding that converts
+Markdown with Apex modes and serializable options on macOS/Linux without
+system C libraries.
+
+**Architecture:** Create a sibling `apex-node` repository that vendors Apex as
+a submodule, builds a CMake Node-API addon linking bundled cmark-gfm and
+libyaml, and distributes platform `.node` binaries as optional npm packages
+selected by a small JavaScript loader.
+
+**Tech Stack:** Node.js 20+, Node-API (`node-addon-api`), CMake, C++17,
+vendored Apex/cmark-gfm/libyaml, npm optionalDependencies, GitHub Actions.
+
+## Global Constraints
+
+- Package name is `@apexmarkdown/apex`.
+- Repository path is `/Users/ttscoff/Desktop/Code/apex-node`.
+- Supported platforms for v1: macOS and Linux, x64 and arm64.
+- Supported Node.js: 20 or newer.
+- Bundle Apex, cmark-gfm, and libyaml; do not require system libraries.
+- Enable `APEX_HAVE_LIBYAML=1`.
+- Public API is synchronous `convert(markdown, options?)` and `version`.
+- Option names are camelCase only.
+- Expose every serializable user-facing `apex_options` field.
+- Exclude callbacks and TOC output pointers.
+- Unknown names or wrong types throw `TypeError`.
+- No WASM, Windows, async workers, or structured TOC API in v1.
+- Work and commits happen in `apex-node`, not in the Apex core tree
+  (except this plan/spec already stored under Apex docs).
+
+---
+
+## File Structure
+
+All paths below are relative to `/Users/ttscoff/Desktop/Code/apex-node`
+unless noted.
+
+- Create `package.json`: public package metadata, scripts, optionalDeps.
+- Create `README.md`, `LICENSE`, `.gitignore`, `.npmrc`.
+- Create `vendor/apex`: Apex git submodule.
+- Create `binding/CMakeLists.txt`: build Apex static lib + Node addon.
+- Create `binding/src/addon.cpp`: Node-API `convert` / `version`.
+- Create `binding/src/options.h` / `options.cpp`: JS object → `apex_options`.
+- Create `lib/index.js`: platform loader and re-exports.
+- Create `lib/index.d.ts`: TypeScript declarations.
+- Create `lib/load-native.js`: resolve platform optional package.
+- Create `test/*.test.js`: conversion, options, loader, errors.
+- Create `scripts/build.js`: cmake-js wrapper for local builds.
+- Create `scripts/package-prebuild.js`: emit a platform package tarball dir.
+- Create `platforms/package.template.json`: template for platform packages.
+- Create `.github/workflows/ci.yml` and `publish-prebuilds.yml`.
+
+### Task 1: Scaffold Repository and Failing Smoke Tests
+
+**Files:**
+
+- Create: `/Users/ttscoff/Desktop/Code/apex-node/` (new git repo)
+- Create: `package.json`
+- Create: `.gitignore`
+- Create: `LICENSE`
+- Create: `test/convert.test.js`
+- Create: `test/options-validation.test.js`
+- Create: `vendor/apex` (submodule)
+
+**Interfaces:**
+
+- Produces: npm package skeleton named `@apexmarkdown/apex` at version
+  `0.1.0`
+- Produces: tests that import `{ convert, version }` from `../lib/index.js`
+- Consumes: Apex submodule at GitHub `ApexMarkdown/apex`
+
+- [ ] **Step 1: Create the repository and submodule**
+
+```bash
+mkdir -p /Users/ttscoff/Desktop/Code/apex-node
+cd /Users/ttscoff/Desktop/Code/apex-node
+git init
+git submodule add https://github.com/ApexMarkdown/apex.git vendor/apex
+git submodule update --init --recursive
+```
+
+Expected: `vendor/apex/include/apex/apex.h` exists and
+`vendor/apex/vendor/cmark-gfm` / `vendor/apex/vendor/libyaml` are populated.
+
+- [ ] **Step 2: Add package metadata and ignore rules**
+
+Create `.gitignore`:
+
+```gitignore
+node_modules/
+build/
+prebuilds/
+*.node
+.DS_Store
+coverage/
+npm-debug.log*
+```
+
+Create `package.json`:
+
+```json
+{
+  "name": "@apexmarkdown/apex",
+  "version": "0.1.0",
+  "description": "Node.js bindings for the Apex unified Markdown processor",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "require": "./lib/index.js",
+      "import": "./lib/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "lib/",
+    "binding/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "test": "node --test test/**/*.test.js",
+    "package:prebuild": "node scripts/package-prebuild.js"
+  },
+  "optionalDependencies": {
+    "@apexmarkdown/apex-darwin-arm64": "0.1.0",
+    "@apexmarkdown/apex-darwin-x64": "0.1.0",
+    "@apexmarkdown/apex-linux-arm64": "0.1.0",
+    "@apexmarkdown/apex-linux-x64": "0.1.0"
+  },
+  "devDependencies": {
+    "cmake-js": "^7.3.0",
+    "node-addon-api": "^8.3.0"
+  }
+}
+```
+
+Create `LICENSE` as MIT, copyright Brett Terpstra.
+
+- [ ] **Step 3: Write failing smoke tests**
+
+Create `test/convert.test.js`:
+
+```js
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const { convert, version } = require("../lib/index.js");
+
+describe("convert", () => {
+  it("renders a heading by default", () => {
+    const html = convert("# Hello");
+    assert.match(html, /<h1[^>]*>Hello<\/h1>/);
+  });
+
+  it("honors gfm mode for strikethrough", () => {
+    const html = convert("~~x~~", { mode: "gfm" });
+    assert.match(html, /<del>x<\/del>/);
+  });
+
+  it("returns empty string for empty input", () => {
+    assert.equal(convert(""), "");
+  });
+
+  it("preserves utf8", () => {
+    const html = convert("café 漢字");
+    assert.match(html, /café 漢字/);
+  });
+});
+
+describe("version", () => {
+  it("exposes a non-empty version string", () => {
+    assert.equal(typeof version, "string");
+    assert.notEqual(version.length, 0);
+  });
+});
+```
+
+Create `test/options-validation.test.js`:
+
+```js
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const { convert } = require("../lib/index.js");
+
+describe("option validation", () => {
+  it("rejects unknown option names", () => {
+    assert.throws(
+      () => convert("# x", { notARealOption: true }),
+      (err) => err instanceof TypeError && /Unknown option/.test(err.message)
+    );
+  });
+
+  it("rejects wrong boolean types", () => {
+    assert.throws(
+      () => convert("# x", { unsafe: "yes" }),
+      (err) => err instanceof TypeError && /unsafe/.test(err.message)
+    );
+  });
+
+  it("rejects invalid mode strings", () => {
+    assert.throws(
+      () => convert("# x", { mode: "pandoc" }),
+      (err) => err instanceof TypeError && /mode/.test(err.message)
+    );
+  });
+
+  it("rejects non-string markdown", () => {
+    assert.throws(
+      () => convert(42),
+      (err) => err instanceof TypeError
+    );
+  });
+});
+```
+
+- [ ] **Step 4: Install deps and confirm tests fail**
+
+```bash
+cd /Users/ttscoff/Desktop/Code/apex-node
+npm install
+npm test
+```
+
+Expected: FAIL because `lib/index.js` does not exist / native addon missing.
+
+- [ ] **Step 5: Commit scaffold**
+
+```bash
+cd /Users/ttscoff/Desktop/Code/apex-node
+git add .
+git commit -m "$(cat <<'EOF'
+Scaffold Apex Node package and failing smoke tests.
+
+@new **Node package scaffold** for @apexmarkdown/apex with Apex submodule and smoke tests.
+
+EOF
+)"
+```
+
+### Task 2: CMake Build and Minimal Native Convert
+
+**Files:**
+
+- Create: `binding/CMakeLists.txt`
+- Create: `binding/src/addon.cpp`
+- Create: `binding/src/options.h`
+- Create: `binding/src/options.cpp` (stub that only accepts empty/undefined options)
+- Create: `scripts/build.js`
+- Create: `lib/load-native.js`
+- Create: `lib/index.js`
+- Create: `lib/index.d.ts` (minimal)
+
+**Interfaces:**
+
+- Produces native exports:
+  - `convert(markdown: string, options?: object): string`
+  - `version: string`
+- Produces:
+  `bool apex_node_options_from_js(Napi::Env, Napi::Value, apex_options *,
+  ApexNodeOptionStorage *, std::string *error)`
+- Produces loader:
+  `function loadNative(): { convert, version }`
+
+- [ ] **Step 1: Add CMake that builds bundled Apex and the addon**
+
+Create `binding/CMakeLists.txt`:
+
+```cmake
+cmake_minimum_required(VERSION 3.15)
+project(apex_node LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+set(APEX_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../vendor/apex")
+
+set(CMARK_TESTS OFF CACHE BOOL "" FORCE)
+set(CMARK_SHARED OFF CACHE BOOL "" FORCE)
+set(CMARK_STATIC ON CACHE BOOL "" FORCE)
+add_subdirectory("${APEX_ROOT}/vendor/cmark-gfm" "${CMAKE_BINARY_DIR}/cmark-gfm")
+
+set(YAML_SRC
+  ${APEX_ROOT}/vendor/libyaml/src/api.c
+  ${APEX_ROOT}/vendor/libyaml/src/dumper.c
+  ${APEX_ROOT}/vendor/libyaml/src/emitter.c
+  ${APEX_ROOT}/vendor/libyaml/src/loader.c
+  ${APEX_ROOT}/vendor/libyaml/src/parser.c
+  ${APEX_ROOT}/vendor/libyaml/src/reader.c
+  ${APEX_ROOT}/vendor/libyaml/src/scanner.c
+  ${APEX_ROOT}/vendor/libyaml/src/writer.c
+)
+add_library(apex_yaml STATIC ${YAML_SRC})
+target_include_directories(apex_yaml PUBLIC
+  ${APEX_ROOT}/vendor/libyaml/include
+  ${APEX_ROOT}/vendor/libyaml/src
+)
+target_compile_definitions(apex_yaml PUBLIC
+  YAML_VERSION_MAJOR=0
+  YAML_VERSION_MINOR=2
+  YAML_VERSION_PATCH=5
+  YAML_VERSION_STRING="0.2.5"
+  HAVE_CONFIG_H=0
+)
+
+set(APEX_LIB_SOURCES
+  ${APEX_ROOT}/src/apex.c
+  ${APEX_ROOT}/src/ast_json.c
+  ${APEX_ROOT}/src/ast_markdown.c
+  ${APEX_ROOT}/src/ast_terminal.c
+  ${APEX_ROOT}/src/ast_man.c
+  ${APEX_ROOT}/src/filters_ast.c
+  ${APEX_ROOT}/src/plugins_env.c
+  ${APEX_ROOT}/src/plugins.c
+  ${APEX_ROOT}/src/plugins_remote.c
+  ${APEX_ROOT}/src/plugin_catalog.c
+  ${APEX_ROOT}/src/html_renderer.c
+  ${APEX_ROOT}/src/extensions/metadata.c
+  ${APEX_ROOT}/src/extensions/wiki_links.c
+  ${APEX_ROOT}/src/extensions/math.c
+  ${APEX_ROOT}/src/extensions/critic.c
+  ${APEX_ROOT}/src/extensions/callouts.c
+  ${APEX_ROOT}/src/extensions/raw_content.c
+  ${APEX_ROOT}/src/extensions/code_fence_attrs.c
+  ${APEX_ROOT}/src/extensions/quarto_diagrams.c
+  ${APEX_ROOT}/src/extensions/quarto_shortcodes.c
+  ${APEX_ROOT}/src/extensions/quarto_polish.c
+  ${APEX_ROOT}/src/extensions/quarto_lists.c
+  ${APEX_ROOT}/src/extensions/includes.c
+  ${APEX_ROOT}/src/extensions/inline_tables.c
+  ${APEX_ROOT}/src/extensions/toc.c
+  ${APEX_ROOT}/src/extensions/abbreviations.c
+  ${APEX_ROOT}/src/extensions/emoji.c
+  ${APEX_ROOT}/src/extensions/special_markers.c
+  ${APEX_ROOT}/src/extensions/ial.c
+  ${APEX_ROOT}/src/extensions/bear_image_attrs.c
+  ${APEX_ROOT}/src/extensions/definition_list.c
+  ${APEX_ROOT}/src/extensions/advanced_footnotes.c
+  ${APEX_ROOT}/src/extensions/advanced_tables.c
+  ${APEX_ROOT}/src/extensions/html_markdown.c
+  ${APEX_ROOT}/src/extensions/fenced_divs.c
+  ${APEX_ROOT}/src/extensions/table_html_postprocess.c
+  ${APEX_ROOT}/src/extensions/inline_footnotes.c
+  ${APEX_ROOT}/src/extensions/highlight.c
+  ${APEX_ROOT}/src/extensions/insert.c
+  ${APEX_ROOT}/src/extensions/sup_sub.c
+  ${APEX_ROOT}/src/extensions/header_ids.c
+  ${APEX_ROOT}/src/extensions/relaxed_tables.c
+  ${APEX_ROOT}/src/extensions/grid_tables.c
+  ${APEX_ROOT}/src/extensions/citations.c
+  ${APEX_ROOT}/src/extensions/index.c
+  ${APEX_ROOT}/src/extensions/syntax_highlight.c
+  ${APEX_ROOT}/src/pretty_html.c
+  ${APEX_ROOT}/src/buffer.c
+  ${APEX_ROOT}/src/parser.c
+  ${APEX_ROOT}/src/renderer.c
+  ${APEX_ROOT}/src/utf8.c
+)
+
+add_library(apex_static STATIC ${APEX_LIB_SOURCES})
+target_include_directories(apex_static PUBLIC
+  ${APEX_ROOT}/include
+  ${APEX_ROOT}/include/apex
+  ${APEX_ROOT}/vendor/cmark-gfm/src
+  ${APEX_ROOT}/vendor/cmark-gfm/extensions
+  ${APEX_ROOT}/vendor/libyaml/include
+)
+target_compile_definitions(apex_static PUBLIC APEX_HAVE_LIBYAML=1)
+target_link_libraries(apex_static PUBLIC
+  libcmark-gfm-extensions_static
+  libcmark-gfm_static
+  apex_yaml
+)
+
+add_library(${PROJECT_NAME} SHARED
+  src/addon.cpp
+  src/options.cpp
+)
+set_target_properties(${PROJECT_NAME} PROPERTIES
+  PREFIX ""
+  SUFFIX ".node"
+)
+target_include_directories(${PROJECT_NAME} PRIVATE
+  ${CMAKE_JS_INC}
+  ${CMAKE_CURRENT_SOURCE_DIR}/src
+)
+target_link_libraries(${PROJECT_NAME} PRIVATE apex_static ${CMAKE_JS_LIB})
+target_compile_definitions(${PROJECT_NAME} PRIVATE NAPI_VERSION=8)
+```
+
+If cmake-js does not inject `CMAKE_JS_INC` / `CMAKE_JS_LIB` correctly on the
+host, pass them explicitly from `scripts/build.js` using
+`require("node-addon-api").include` and Node’s `process.execPath` include
+paths.
+
+- [ ] **Step 2: Implement options stub and addon entry points**
+
+Create `binding/src/options.h`:
+
+```cpp
+#pragma once
+
+#include <napi.h>
+#include <string>
+#include <vector>
+#include "apex/apex.h"
+
+struct ApexNodeOptionStorage {
+  std::vector<std::string> owned_strings;
+  std::vector<std::vector<char>> owned_cstrings;
+  std::vector<const char *> stylesheet_ptrs;
+  std::vector<char *> bibliography_ptrs;
+  std::vector<char *> script_tag_ptrs;
+  std::vector<const char *> ast_filter_ptrs;
+};
+
+bool apex_node_options_from_js(Napi::Env env,
+                               Napi::Value value,
+                               apex_options *out,
+                               ApexNodeOptionStorage *storage,
+                               std::string *error);
+```
+
+Create `binding/src/options.cpp` stub:
+
+```cpp
+#include "options.h"
+
+bool apex_node_options_from_js(Napi::Env env,
+                               Napi::Value value,
+                               apex_options *out,
+                               ApexNodeOptionStorage *storage,
+                               std::string *error) {
+  (void)storage;
+  if (value.IsUndefined() || value.IsNull()) {
+    *out = apex_options_default();
+    return true;
+  }
+  if (!value.IsObject()) {
+    *error = "options must be an object";
+    return false;
+  }
+  Napi::Object obj = value.As<Napi::Object>();
+  Napi::Array names = obj.GetPropertyNames();
+  if (names.Length() > 0) {
+    *error = "Unknown option: " +
+             names.Get(uint32_t(0)).As<Napi::String>().Utf8Value();
+    return false;
+  }
+  *out = apex_options_default();
+  return true;
+}
+```
+
+Create `binding/src/addon.cpp`:
+
+```cpp
+#include <napi.h>
+#include <string>
+#include "apex/apex.h"
+#include "options.h"
+
+static Napi::Value Convert(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "markdown must be a string").ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  std::string markdown = info[0].As<Napi::String>().Utf8Value();
+  ApexNodeOptionStorage storage;
+  apex_options options;
+  std::string error;
+  Napi::Value opts_val = info.Length() >= 2 ? info[1] : env.Undefined();
+  if (!apex_node_options_from_js(env, opts_val, &options, &storage, &error)) {
+    Napi::TypeError::New(env, error).ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  char *html = apex_markdown_to_html(markdown.c_str(), markdown.size(), &options);
+  if (!html) {
+    Napi::Error::New(env, "Apex conversion failed").ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  Napi::String result = Napi::String::New(env, html);
+  apex_free_string(html);
+  return result;
+}
+
+static Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  exports.Set("convert", Napi::Function::New(env, Convert));
+  exports.Set("version", Napi::String::New(env, apex_version_string()));
+  return exports;
+}
+
+NODE_API_MODULE(apex_node, Init)
+```
+
+- [ ] **Step 3: Add build script and development loader**
+
+Create `scripts/build.js`:
+
+```js
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const root = path.join(__dirname, "..");
+const result = spawnSync(
+  "npx",
+  ["cmake-js", "compile", "--directory", "binding"],
+  { cwd: root, stdio: "inherit", shell: process.platform === "win32" }
+);
+process.exit(result.status ?? 1);
+```
+
+Create `lib/load-native.js`:
+
+```js
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+function platformPackageName() {
+  const platform = process.platform;
+  const arch = process.arch;
+  if (platform === "darwin" && arch === "arm64") return "@apexmarkdown/apex-darwin-arm64";
+  if (platform === "darwin" && arch === "x64") return "@apexmarkdown/apex-darwin-x64";
+  if (platform === "linux" && arch === "arm64") return "@apexmarkdown/apex-linux-arm64";
+  if (platform === "linux" && arch === "x64") return "@apexmarkdown/apex-linux-x64";
+  return null;
+}
+
+function loadNative() {
+  const candidates = [];
+  const pkg = platformPackageName();
+  if (pkg) {
+    try {
+      const resolved = require.resolve(`${pkg}/apex.node`);
+      candidates.push(resolved);
+    } catch (_) {
+      // optional dependency may be absent during local development
+    }
+  }
+
+  candidates.push(
+    path.join(__dirname, "..", "build", "Release", "apex_node.node"),
+    path.join(__dirname, "..", "binding", "build", "Release", "apex_node.node")
+  );
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return require(candidate);
+    }
+  }
+
+  const detected = `${process.platform}-${process.arch}`;
+  throw new Error(
+    `Apex native addon is unavailable for ${detected}. ` +
+      `Install a supported optional dependency or run npm run build.`
+  );
+}
+
+module.exports = { loadNative, platformPackageName };
+```
+
+Create `lib/index.js`:
+
+```js
+const { loadNative } = require("./load-native.js");
+const native = loadNative();
+
+module.exports = {
+  convert: native.convert,
+  version: native.version
+};
+```
+
+Create minimal `lib/index.d.ts`:
+
+```ts
+export interface ApexOptions {
+  [key: string]: unknown;
+}
+
+export declare function convert(markdown: string, options?: ApexOptions): string;
+export declare const version: string;
+```
+
+- [ ] **Step 4: Build and run convert smoke tests**
+
+```bash
+cd /Users/ttscoff/Desktop/Code/apex-node
+npm run build
+node --test test/convert.test.js
+```
+
+Expected: PASS for convert/version. Validation tests still FAIL for
+non-empty options because the stub rejects every property.
+
+- [ ] **Step 5: Commit native convert path**
+
+```bash
+git add binding scripts lib
+git commit -m "$(cat <<'EOF'
+Add CMake Node-API convert binding for Apex.
+
+@new **Native convert()** binding that bundles Apex, cmark-gfm, and libyaml.
+
+EOF
+)"
+```
+
+### Task 3: Complete Serializable Options Mapper
+
+**Files:**
+
+- Modify: `binding/src/options.cpp`
+- Modify: `binding/src/options.h` if storage helpers need expansion
+- Modify: `lib/index.d.ts`
+- Modify: `test/options-validation.test.js`
+- Create: `test/options-behavior.test.js`
+
+**Interfaces:**
+
+- Produces complete `apex_node_options_from_js(...)` covering every
+  serializable field listed below
+- Produces typed `ApexOptions` in `lib/index.d.ts`
+
+Serializable camelCase fields to implement (exclude callbacks / TOC outs):
+
+**Booleans:**
+`enablePlugins`, `allowExternalPluginDetection`, `enableTables`,
+`enableFootnotes`, `enableDefinitionLists`, `enableSmartTypography`,
+`enableMath`, `enableCriticMarkup`, `enableWikiLinks`, `enableTaskLists`,
+`enableAttributes`, `enableCallouts`, `enablePyCallouts`,
+`enableQuartoCallouts`, `enableQuartoExtensions`, `enableQuartoRaw`,
+`enableQuartoExampleLists`, `enableQuartoLineBlocks`,
+`enableQuartoRomanLists`, `enableQuartoCodeAttrs`, `enableQuartoDiagrams`,
+`enableQuartoShortcodes`, `enableQuartoStrictLists`, `enableQuartoXrefs`,
+`enableMarkedExtensions`, `enableDivs`, `enableSpans`, `enableGridTables`,
+`stripMetadata`, `enableMetadataVariables`, `enableMetadataTransforms`,
+`enableFileIncludes`, `unsafe`, `validateUtf8`, `githubPreLang`,
+`standalone`, `pretty`, `xhtml`, `strictXhtml`, `paginate`,
+`paginateSymbols`, `terminalInlineImages`, `hardbreaks`, `nobreaks`,
+`generateHeaderIds`, `headerAnchors`, `relaxedTables`, `perCellAlignment`,
+`allowMixedListMarkers`, `allowAlphaLists`, `enableSupSub`,
+`enableStrikethrough`, `enableAutolink`, `obfuscateEmails`, `embedImages`,
+`enableImageCaptions`, `titleCaptionsOnly`, `enableCitations`,
+`suppressBibliography`, `linkCitations`, `showTooltips`, `enableIndices`,
+`enableMmarkIndexSyntax`, `enableTextindexSyntax`,
+`enableLeanpubIndexSyntax`, `suppressIndex`, `groupIndexByLetter`,
+`wikilinkSanitize`, `embedStylesheet`, `enableAria`,
+`enableEmojiAutocorrect`, `codeLineNumbers`, `highlightLanguageOnly`,
+`enableWidont`, `codeIsPoetry`, `enableMarkdownInHtml`,
+`randomFootnoteIds`, `enableHashtags`, `styleHashtags`, `proofreaderMode`,
+`hrPageBreak`, `titleFromH1`, `pageBreakBeforeFootnotes`,
+`astFilterStrict`
+
+**Integers:**
+`maxIncludeDepth`, `terminalWidth`, `terminalImageWidth`, `tocMin`, `tocMax`
+
+**Strings:**
+`baseDirectory`, `documentTitle`, `themeName`, `cslFile`, `nocite`,
+`wikilinkExtension`, `codeHighlighter`, `codeHighlightTheme`,
+`inputFilePath`
+
+**Enums (string unions):**
+`mode`, `outputFormat`, `criticMode`, `idFormat`, `captionPosition`,
+`wikilinkSpace`
+
+**String arrays:**
+`stylesheetPaths` → `stylesheet_paths` + `stylesheet_count`
+`bibliographyFiles` → NULL-terminated `bibliography_files`
+`scriptTags` → NULL-terminated `script_tags`
+`astFilterCommands` → `ast_filter_commands` + `ast_filter_count`
+
+- [ ] **Step 1: Expand validation/behavior tests first**
+
+Append to `test/options-validation.test.js`:
+
+```js
+  it("accepts camelCase mode aliases only as documented strings", () => {
+    assert.doesNotThrow(() => convert("# x", { mode: "unified" }));
+    assert.doesNotThrow(() => convert("# x", { mode: "commonmark" }));
+    assert.doesNotThrow(() => convert("# x", { mode: "quarto" }));
+  });
+
+  it("rejects snake_case option names", () => {
+    assert.throws(
+      () => convert("# x", { enable_tables: true }),
+      TypeError
+    );
+  });
+```
+
+Create `test/options-behavior.test.js`:
+
+```js
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const { convert } = require("../lib/index.js");
+
+describe("option behavior", () => {
+  it("disables header ids when generateHeaderIds is false", () => {
+    const withIds = convert("# Hello", { mode: "gfm", generateHeaderIds: true });
+    const withoutIds = convert("# Hello", { mode: "gfm", generateHeaderIds: false });
+    assert.match(withIds, /id=/);
+    assert.doesNotMatch(withoutIds, /id=/);
+  });
+
+  it("applies criticMode accept", () => {
+    const html = convert("{++added++}", {
+      mode: "unified",
+      enableCriticMarkup: true,
+      criticMode: "accept"
+    });
+    assert.match(html, /added/);
+    assert.doesNotMatch(html, /ins/);
+  });
+
+  it("accepts stylesheetPaths array without throwing", () => {
+    const html = convert("# Hi", {
+      standalone: true,
+      documentTitle: "Doc",
+      stylesheetPaths: []
+    });
+    assert.match(html, /<html/i);
+  });
+});
+```
+
+Run:
+
+```bash
+npm test
+```
+
+Expected: FAIL on unknown-option / unimplemented mapper behavior.
+
+- [ ] **Step 2: Implement table-driven options parsing**
+
+Replace `binding/src/options.cpp` with a complete mapper:
+
+1. Read optional `mode` first.
+2. Initialize with `apex_options_for_mode(mode)` (or
+   `apex_options_default()` when mode omitted).
+3. Iterate `Object.getOwnPropertyNames`.
+4. For each name, look up a handler in a `std::unordered_map`.
+5. Unknown names set `error = "Unknown option: " + name` and return false.
+6. Copy strings into `storage->owned_strings` and point `const char *`
+   fields at `c_str()`.
+7. For arrays, fill pointer vectors and NULL-terminate
+   `bibliography_files` / `script_tags`; set counts for stylesheets and
+   AST filters.
+
+Enum maps:
+
+```cpp
+// mode
+{"commonmark", APEX_MODE_COMMONMARK},
+{"gfm", APEX_MODE_GFM},
+{"multimarkdown", APEX_MODE_MULTIMARKDOWN},
+{"kramdown", APEX_MODE_KRAMDOWN},
+{"unified", APEX_MODE_UNIFIED},
+{"quarto", APEX_MODE_QUARTO}
+
+// outputFormat
+{"html", APEX_OUTPUT_HTML},
+{"json", APEX_OUTPUT_JSON},
+{"jsonFiltered", APEX_OUTPUT_JSON_FILTERED},
+{"markdown", APEX_OUTPUT_MARKDOWN},
+{"mmd", APEX_OUTPUT_MMD},
+{"commonmark", APEX_OUTPUT_COMMONMARK},
+{"kramdown", APEX_OUTPUT_KRAMDOWN},
+{"gfm", APEX_OUTPUT_GFM},
+{"terminal", APEX_OUTPUT_TERMINAL},
+{"terminal256", APEX_OUTPUT_TERMINAL256},
+{"man", APEX_OUTPUT_MAN},
+{"manHtml", APEX_OUTPUT_MAN_HTML},
+{"toc", APEX_OUTPUT_TOC}
+
+// criticMode
+{"markup", 0}, {"accept", 1}, {"reject", 2}
+
+// idFormat
+{"gfm", 0}, {"mmd", 1}
+
+// captionPosition
+{"above", 0}, {"below", 1}
+
+// wikilinkSpace
+{"dash", 0}, {"none", 1}, {"underscore", 2}, {"space", 3}
+```
+
+Leave these C fields unset / NULL always:
+
+`plugin_register`, `progress_callback`, `progress_user_data`,
+`cmark_init`, `cmark_done`, `cmark_user_data`,
+`toc_entries_out`, `toc_entries_count_out`.
+
+- [ ] **Step 3: Write complete TypeScript declarations**
+
+Replace `lib/index.d.ts` with an explicit `ApexOptions` interface listing
+every supported property and the enum string unions from the design spec.
+Do not include an index signature that would allow unknown keys.
+
+- [ ] **Step 4: Rebuild and verify all option tests**
+
+```bash
+npm run build
+npm test
+```
+
+Expected: all tests PASS.
+
+- [ ] **Step 5: Commit options mapper**
+
+```bash
+git add binding/src/options.cpp binding/src/options.h lib/index.d.ts test
+git commit -m "$(cat <<'EOF'
+Map complete camelCase Apex options in the Node binding.
+
+@new **Complete ApexOptions mapping** for serializable camelCase Node options with strict validation.
+
+EOF
+)"
+```
+
+### Task 4: Platform Package Packaging
+
+**Files:**
+
+- Create: `scripts/package-prebuild.js`
+- Create: `platforms/package.template.json`
+- Create: `test/load-native.test.js`
+- Modify: `package.json` scripts if needed
+
+**Interfaces:**
+
+- Produces directory
+  `prebuilds/@apexmarkdown/apex-<platform>-<arch>/` containing:
+  - `package.json`
+  - `apex.node`
+  - `README.md`
+- Produces npm package name matching `platformPackageName()`
+
+- [ ] **Step 1: Add loader unit test for unsupported platforms**
+
+Create `test/load-native.test.js`:
+
+```js
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const { platformPackageName } = require("../lib/load-native.js");
+
+describe("platformPackageName", () => {
+  it("returns a scoped package for the current host when supported", () => {
+    const name = platformPackageName();
+    if (process.platform === "darwin" || process.platform === "linux") {
+      if (process.arch === "arm64" || process.arch === "x64") {
+        assert.match(name, /^@apexmarkdown\/apex-(darwin|linux)-(arm64|x64)$/);
+        return;
+      }
+    }
+    assert.equal(name, null);
+  });
+});
+```
+
+- [ ] **Step 2: Implement package-prebuild script**
+
+Create `platforms/package.template.json`:
+
+```json
+{
+  "name": "@apexmarkdown/apex-PLATFORM_ARCH",
+  "version": "PACKAGE_VERSION",
+  "description": "Apex native addon for PLATFORM_ARCH",
+  "os": ["OS"],
+  "cpu": ["CPU"],
+  "main": "apex.node",
+  "files": ["apex.node", "README.md"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}
+```
+
+Create `scripts/package-prebuild.js`:
+
+```js
+const fs = require("node:fs");
+const path = require("node:path");
+const { platformPackageName } = require("../lib/load-native.js");
+
+const root = path.join(__dirname, "..");
+const pkg = require("../package.json");
+const name = platformPackageName();
+if (!name) {
+  console.error(`Unsupported platform: ${process.platform}-${process.arch}`);
+  process.exit(1);
+}
+
+const addonCandidates = [
+  path.join(root, "build", "Release", "apex_node.node"),
+  path.join(root, "binding", "build", "Release", "apex_node.node")
+];
+const addon = addonCandidates.find((p) => fs.existsSync(p));
+if (!addon) {
+  console.error("Built addon not found; run npm run build first");
+  process.exit(1);
+}
+
+const outDir = path.join(root, "prebuilds", name);
+fs.rmSync(outDir, { recursive: true, force: true });
+fs.mkdirSync(outDir, { recursive: true });
+
+const os = process.platform;
+const cpu = process.arch;
+const rendered = fs
+  .readFileSync(path.join(root, "platforms", "package.template.json"), "utf8")
+  .replaceAll("PLATFORM_ARCH", `${os === "darwin" ? "darwin" : "linux"}-${cpu}`)
+  .replaceAll("PACKAGE_VERSION", pkg.version)
+  .replaceAll("\"OS\"", `"${os}"`)
+  .replaceAll("\"CPU\"", `"${cpu}"`);
+
+fs.writeFileSync(path.join(outDir, "package.json"), rendered);
+fs.copyFileSync(addon, path.join(outDir, "apex.node"));
+fs.writeFileSync(
+  path.join(outDir, "README.md"),
+  `# ${name}\n\nNative Apex addon for ${os}-${cpu}.\n`
+);
+console.log(`Wrote ${outDir}`);
+```
+
+- [ ] **Step 3: Build and package on the current host**
+
+```bash
+npm run build
+npm run package:prebuild
+node -e "console.log(require('./prebuilds/'+require('./lib/load-native').platformPackageName()+'/package.json').name)"
+npm test
+```
+
+Expected: platform directory exists; tests still PASS.
+
+- [ ] **Step 4: Commit packaging scripts**
+
+```bash
+git add scripts/package-prebuild.js platforms test/load-native.test.js
+git commit -m "$(cat <<'EOF'
+Add platform prebuild packaging for optional native deps.
+
+@new **Platform prebuild packaging** for @apexmarkdown/apex optional native packages.
+
+EOF
+)"
+```
+
+### Task 5: CI Workflows and README
+
+**Files:**
+
+- Create: `.github/workflows/ci.yml`
+- Create: `.github/workflows/publish-prebuilds.yml`
+- Create: `README.md`
+- Modify: `package.json` repository/homepage fields
+
+**Interfaces:**
+
+- CI matrix builds and tests:
+  - `macos-14` (arm64)
+  - `macos-13` or `macos-15-intel` equivalent for x64 if available; otherwise
+    document cross-compile/skip with an explicit matrix entry that uses
+    `cmake` targeting `x86_64-apple-darwin` only if reliable
+  - `ubuntu-24.04` (x64)
+  - `ubuntu-24.04-arm` (arm64) when available on the org plan
+- Publish workflow uploads platform package artifacts on tag `v*`
+
+Practical v1 matrix if ARM Linux runners are unavailable:
+
+```yaml
+strategy:
+  matrix:
+    include:
+      - os: macos-14
+        package: "@apexmarkdown/apex-darwin-arm64"
+      - os: macos-13
+        package: "@apexmarkdown/apex-darwin-x64"
+      - os: ubuntu-24.04
+        package: "@apexmarkdown/apex-linux-x64"
+```
+
+If Linux arm64 CI is unavailable at implementation time, keep the optional
+dependency declared, build it manually when needed, and note the gap in
+README. Do not silently drop the package name from `package.json`.
+
+- [ ] **Step 1: Write CI workflow**
+
+Create `.github/workflows/ci.yml` that:
+
+1. Checks out with `submodules: recursive`
+2. Sets up Node 20
+3. Runs `npm ci`
+4. Runs `npm run build`
+5. Runs `npm test`
+6. Runs `npm run package:prebuild`
+7. Uploads `prebuilds/**` as artifacts named by matrix package
+
+- [ ] **Step 2: Write publish workflow**
+
+Create `.github/workflows/publish-prebuilds.yml` triggered on `push: tags: ['v*']`:
+
+1. Build matrix packages
+2. `npm publish` each platform package from its `prebuilds/...` directory
+3. Publish `@apexmarkdown/apex` from the repo root
+
+Require `NPM_TOKEN` repository secret. Use
+`npm publish --access public` for scoped packages.
+
+- [ ] **Step 3: Write README**
+
+Create `README.md` covering:
+
+```md
+# @apexmarkdown/apex
+
+Node.js bindings for [Apex](https://github.com/ApexMarkdown/apex).
+
+## Install
+
+npm install @apexmarkdown/apex
+
+## Usage
+
+const { convert, version } = require("@apexmarkdown/apex");
+const html = convert("# Hello", { mode: "gfm", generateHeaderIds: true });
+
+## Supported platforms
+
+- macOS arm64 / x64
+- Linux arm64 / x64
+- Node.js 20+
+
+No system cmark-gfm or libyaml install is required.
+
+## Options
+
+camelCase options matching Apex's serializable apex_options fields.
+Unknown options throw TypeError.
+```
+
+Also document local development:
+
+```bash
+git submodule update --init --recursive
+npm install
+npm run build
+npm test
+```
+
+- [ ] **Step 4: Fill package repository metadata**
+
+In `package.json` set:
+
+```json
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/ApexMarkdown/apex-node.git"
+},
+"homepage": "https://github.com/ApexMarkdown/apex-node",
+"bugs": {
+  "url": "https://github.com/ApexMarkdown/apex-node/issues"
+}
+```
+
+- [ ] **Step 5: Final verification on the development machine**
+
+```bash
+npm run build
+npm test
+npm run package:prebuild
+node -e "const {convert,version}=require('.'); console.log(version); console.log(convert('**hi**'))"
+```
+
+Expected: version prints, HTML contains `<strong>hi</strong>`.
+
+- [ ] **Step 6: Commit docs and CI**
+
+```bash
+git add .github README.md package.json
+git commit -m "$(cat <<'EOF'
+Add CI, publish workflow, and Node package README.
+
+@new **Node package CI and docs** for building and publishing @apexmarkdown/apex prebuilds.
+
+EOF
+)"
+```
+
+- [ ] **Step 7: Create GitHub repository and push**
+
+```bash
+cd /Users/ttscoff/Desktop/Code/apex-node
+gh repo create ApexMarkdown/apex-node --public --source=. --remote=origin --push
+```
+
+Only run this step when the user asks to publish the repository.
+
+---
+
+## Spec Coverage Checklist
+
+| Spec requirement | Task |
+| --- | --- |
+| Sibling `apex-node` repo + submodule | Task 1 |
+| `@apexmarkdown/apex` package identity | Task 1 |
+| CMake + bundled cmark-gfm/libyaml | Task 2 |
+| Sync `convert` / `version` | Task 2 |
+| Complete serializable camelCase options | Task 3 |
+| Strict TypeError validation | Task 3 |
+| Exclude callbacks / TOC outs | Task 3 |
+| Platform optional packages | Task 4 |
+| macOS/Linux x64/arm64 distribution | Tasks 4–5 |
+| Tests listed in design | Tasks 1, 3, 4 |
+| No WASM / Windows / async / TOC API | Global Constraints |
+
+## Placeholder / Ambiguity Scan
+
+- No TBD/TODO left in task steps.
+- Linux arm64 CI availability is handled with an explicit fallback note,
+  not a silent omission of the package name.
+- cmake-js include/lib injection has an explicit fallback instruction.
+- Repository creation/push is gated on explicit user request.