apex-ruby 1.0.17 → 1.0.20

data/ext/apex_ext/apex_src/docs/superpowers/specs/2026-07-12-toc-output-format-design.md

@@ -0,0 +1,161 @@
+# Design: `-t toc` Output Format
+
+**Date:** 2026-07-12  
+**Status:** Approved for implementation
+
+## Summary
+
+Add a `toc` output format that emits nothing but a Markdown unordered list of document headings, each linked to its header ID. Depth defaults to `#`–`###`, overridable via a single `--toc-min-max` option that also seeds HTML TOC markers when they do not specify their own range.
+
+## Goals
+
+- `-t toc` / `--to toc` outputs only a nested Markdown TOC.
+- Header IDs match `--id-format` (and manual IDs from `{#id}` / IAL).
+- Default depth is levels 1–3.
+- One CLI flag `--toc-min-max=MIN,MAX` controls defaults for both `-t toc` and marker-based HTML TOC.
+- Marker-specific min/max still overrides the defaults for that marker.
+- Headings with `.no_toc` are excluded (same as HTML TOC).
+
+## Non-Goals
+
+- Changing the HTML TOC markup shape (`<nav class="toc">` / nested `<ul>`).
+- Adding separate `--toc-min` / `--toc-max` flags.
+- Emitting HTML, JSON, or terminal-styled TOC from `-t toc`.
+- Auto-inserting a TOC into documents that have no marker when using `-t html`.
+
+## Behavior
+
+### Output shape
+
+Given:
+
+```markdown
+# Introduction
+## Getting Started
+### Installation
+#### Too Deep
+## Configuration
+# API
+{: .no_toc}
+```
+
+With defaults (`1,3`), `-t toc` produces:
+
+```markdown
+- [Introduction](#introduction)
+  - [Getting Started](#getting-started)
+    - [Installation](#installation)
+  - [Configuration](#configuration)
+```
+
+Notes:
+
+- `#### Too Deep` omitted (above max).
+- `# API` omitted (`.no_toc`).
+- Links use `[Title](#id)` where `id` is generated with the active `--id-format`, or taken from a manual heading ID when present.
+- Nesting is relative to the filtered min level: the shallowest included level is flush (`- `); each deeper included level adds two spaces of indent.
+- No document body, no `<nav>`, no metadata dump.
+- If there are no matching headings, output is empty (no list items). Prefer a single trailing newline only if that matches existing Apex empty-output conventions for other formats; otherwise empty string is fine.
+
+### Depth: `--toc-min-max`
+
+- CLI: `--toc-min-max=MIN,MAX` and `--toc-min-max MIN,MAX`.
+- Defaults: `toc_min = 1`, `toc_max = 3`.
+- Validation: `1 ≤ min ≤ max ≤ 6`. Invalid values are a CLI error.
+- Optional metadata key with the same semantics: `toc-min-max: 2,4`.
+- Applies to:
+  - `-t toc` always (no marker involved).
+  - HTML TOC markers (`{{TOC}}`, `<!--TOC-->`, `{:toc}`, etc.) when the marker does **not** specify its own min/max.
+- Marker override examples that win over options defaults:
+  - `{{TOC:2-5}}`
+  - `<!--TOC max5 min2-->`
+  - `{:toc max=5}` (and existing IAL/marker variants already supported)
+
+**Default change for HTML markers:** markers with no explicit range currently behave as 1–6. After this change they use option defaults (1–3 unless `--toc-min-max` / metadata overrides). Explicit marker ranges are unchanged. This is intentional and should be noted in docs/changelog as a behavior change for unspecified markers.
+
+## Architecture
+
+### Approach
+
+Early-exit output format + shared heading collection (Approach A).
+
+1. Parse markdown and run the same AST prep used for other non-HTML early exits (filters, IAL, manual header IDs).
+2. When `output_format == APEX_OUTPUT_TOC`, collect headings and emit Markdown TOC; return without HTML/terminal/man rendering.
+3. Refactor `src/extensions/toc.c` so HTML marker TOC and Markdown TOC share collection / ID assignment / `no_toc` filtering.
+
+### Options / API surface
+
+| Piece | Change |
+|-------|--------|
+| `apex_output_format_t` | Add `APEX_OUTPUT_TOC` |
+| `apex_options` | Add `toc_min`, `toc_max` (defaults 1, 3) |
+| CLI (`cli/main.c`) | `-t toc`, `--toc-min-max`; help text |
+| Metadata | Parse `toc-min-max` into options when present |
+| `toc.h` / `toc.c` | Public Markdown TOC helper; thread default min/max into `apex_process_toc` |
+| Tests | Defaults, flag, `no_toc`, id-format, marker override, empty doc |
+| Man page / wiki | Document `-t toc` and `--toc-min-max` |
+
+### Suggested public helpers
+
+```c
+/* Emit nested Markdown list of headings in [min,max], excluding .no_toc */
+char *apex_generate_toc_markdown(cmark_node *document, int id_format,
+                                 int min_level, int max_level);
+
+/* Existing HTML marker processor, extended to accept defaults when
+ * the marker does not specify min/max */
+char *apex_process_toc(const char *html, cmark_node *document, int id_format,
+                       int default_min, int default_max);
+```
+
+Exact signature may vary slightly for ABI/call-site convenience, but callers in `src/apex.c` must pass `options->toc_min` / `options->toc_max`.
+
+### Nesting rules
+
+Match current HTML TOC nesting semantics relative to the filtered range:
+
+- Skip headings outside `[min_level, max_level]`.
+- Indent depth for an included heading is `(level - min_level)` (two spaces per step).
+- Closing / nesting of list levels follows the same open/close pattern as `generate_toc_html` so Markdown and HTML stay structurally aligned.
+
+### ID consistency
+
+- Prefer an existing manual ID on the heading (`user_data` / IAL / `{#id}`) when present.
+- Otherwise call `apex_generate_header_id(text, id_format)`.
+- `-t toc` must use the same ID rules as HTML header ID injection so links resolve when the same document is rendered to HTML with the same `--id-format`.
+
+## Pipeline placement
+
+In `apex_markdown_to_html()` (name retained historically), add an early return beside the markdown / JSON-filtered / terminal / man branches—after IAL and manual header ID processing, before HTML render.
+
+Do not run HTML postprocessors (pretty HTML, image captions, etc.) for `-t toc`.
+
+## Testing
+
+Add coverage for:
+
+1. Default `-t toc` includes levels 1–3 only.
+2. `--toc-min-max=2,4` filters correctly.
+3. `.no_toc` headings excluded.
+4. `--id-format gfm|mmd|kramdown` changes href slugs as expected.
+5. Manual `{#custom-id}` appears in the link target.
+6. HTML marker with no range uses option defaults (1,3 or overridden flag).
+7. HTML marker with explicit range overrides option defaults.
+8. Document with no headings / no matching levels yields empty (or newline-only) output.
+9. Invalid `--toc-min-max` rejected by CLI.
+
+## Documentation
+
+- Man page (`man/apex.1.md`): add `toc` to `-t` list; document `--toc-min-max`.
+- Wiki: Command-Line-Options (and any TOC-related page) updated similarly.
+- Changelog via usual `@new` / `@changed` labels when committing the feature.
+
+## Open decisions (resolved)
+
+| Question | Decision |
+|----------|----------|
+| Default depth | `#`–`###` (1,3) |
+| Depth flag shape | Single `--toc-min-max=MIN,MAX` |
+| Flag scope | Both `-t toc` and HTML markers; marker can override |
+| `.no_toc` | Excluded |
+| Implementation approach | Early-exit format + shared TOC builder |

data/ext/apex_ext/apex_src/docs/superpowers/specs/2026-07-18-bear-image-attributes-design.md

@@ -0,0 +1,184 @@
+# Bear Image Attribute Comments
+
+## Goal
+
+Interpret Bear-style JSON metadata comments following Markdown images or
+reference definitions and apply supported values as HTML image attributes.
+
+Input:
+
+```markdown
+![](emperor-1.jpg)<!-- {"width":259} -->
+```
+
+Unsafe HTML output:
+
+```html
+<p><img src="emperor-1.jpg" alt="" width="259"><!-- {"width":259} --></p>
+```
+
+The metadata comment remains part of the document. Existing safe-HTML
+behavior is unchanged.
+
+## Supported syntax
+
+A metadata comment may follow any of these forms:
+
+```markdown
+![alt](url)<!-- {"width":259} -->
+![alt][id]<!-- {"width":259} -->
+[id]: url <!-- {"width":259} -->
+```
+
+An inline-image or reference-use comment applies only to that image
+occurrence. A reference-definition comment supplies baseline attributes to
+every image using that definition.
+
+Per-use metadata is supported on the explicit `![alt][id]` form. Collapsed
+and shortcut per-use forms are out of scope because they do not provide the
+explicit identifier shown in the requested syntax. Definition metadata still
+applies to every image form that resolves through that definition.
+
+A metadata comment qualifies only when:
+
+- It is on the same source line as the image or reference definition.
+- It touches the preceding construct or is separated by spaces or tabs.
+- Its trimmed body is a valid JSON object.
+
+A comment on a later line is not image metadata. Reference identifiers use
+the same case folding and whitespace normalization as cmark references.
+
+## Modes and HTML safety
+
+Bear image metadata is recognized in CommonMark, GFM, MultiMarkdown, and
+Unified-family modes.
+
+The feature does not weaken HTML safety:
+
+- When raw HTML is allowed, the original comment is rendered verbatim.
+- In a safe-HTML configuration, attributes are applied, but the comment is
+  handled like other raw HTML and may become `<!-- raw HTML omitted -->`.
+
+## Parsing and attribute policy
+
+The image-attribute preprocessor recognizes adjacent comments while scanning
+inline images, reference image uses, and reference definitions. It parses
+the JSON without changing the rendered comment.
+
+Comments after inline images and reference uses remain in place in the
+Markdown passed to cmark. A definition comment must be detached from the
+definition internally so cmark can parse the reference, then emitted
+byte-for-byte at the same source position. It appears once in rendered
+output; it is not repeated for every reference use.
+
+Only flat JSON objects are accepted. The allowlist is `width`, `height`,
+`style`, `class`, `id`, `rel`, and `title`, matching the user-facing image
+attributes recognized by the existing IAL/MultiMarkdown path. Internal Apex
+marker attributes, `data-*` attributes, event-handler attributes, and all
+other keys are ignored. JSON arrays, nested objects, booleans, and null
+values are not converted to attributes.
+
+`width` and `height` accept JSON numbers or strings. The other allowed keys
+accept strings only. Existing image conversion behavior remains
+authoritative; for example:
+
+- `{"width":259}` becomes `width="259"`.
+- `{"width":"300px"}` becomes `width="300"`.
+- `{"width":"50%"}` becomes `style="width: 50%"`.
+
+Attribute names and values must be safely encoded before HTML rendering. A
+malformed payload applies no attributes and leaves the comment untouched.
+
+## Data flow
+
+1. `apex_preprocess_image_attributes()` detects inline images, reference
+   image uses, and reference definitions.
+2. After processing existing attributes, it skips spaces and tabs and checks
+   for a complete HTML comment.
+3. If the trimmed body is a valid JSON object, allowed entries become an
+   `apex_attributes` value.
+4. Inline-image attributes merge into that image's indexed attribute entry.
+5. Definition attributes merge into the reference-name entry used for all
+   instances.
+6. A reference use with local metadata is expanded through the existing
+   per-occurrence inline-image path. It inherits definition attributes, then
+   merges its local attributes.
+7. Image-use comments remain untouched. Definition comments are detached
+   from reference syntax and re-emitted once so cmark does not consume them.
+8. `apex_apply_image_attributes()` attaches the merged attributes to each
+   image node, and the existing renderer emits them on `<img>`.
+
+## Merge precedence
+
+Reference-definition attributes form the baseline for every use. Attributes
+on a specific reference image override the definition for that occurrence
+only. Other occurrences retain the definition value.
+
+Within each construct, source order determines precedence. When a key
+appears in standard image attributes, a trailing IAL, and then Bear
+metadata, the Bear value wins. Unrelated attributes are merged.
+
+This follows existing behavior for successively merged image attribute
+sources and makes adjacent Bear metadata authoritative for Bear exports.
+
+## Error handling
+
+Recognition is fail-closed:
+
+- Invalid or truncated JSON applies nothing.
+- A non-object JSON value applies nothing.
+- Unsupported keys or value types are ignored individually.
+- A comment that is not adjacent on the same line applies nothing.
+- An unresolved reference-use comment applies nothing to other images.
+- Failure never removes, normalizes, or rewrites the comment.
+
+No conversion error is surfaced because the syntax is optional metadata in
+an ordinary HTML comment.
+
+## Implementation boundaries
+
+The preferred implementation extends the existing image-attribute
+preprocessing and application pipeline in `src/extensions/ial.c`. It should
+not add another renderer-specific attribute system or modify vendored
+cmark-gfm parsing.
+
+Reference-definition comments should reuse the existing reference-name entry
+and URL-based application path. Per-use reference comments should reuse the
+existing second-pass expansion of attribute-bearing reference images so each
+occurrence receives an index and can override definition attributes without
+affecting sibling uses.
+
+Mode gating in `src/apex.c` must invoke image-attribute preprocessing for
+CommonMark and GFM as well as the already supported modes. Each mode keeps
+its existing raw-HTML safety options.
+
+Any small JSON helper should be private to the image-attribute extension and
+cover only the flat object subset required here. No new public API is needed.
+
+## Tests
+
+Add focused conversion tests covering:
+
+- Numeric width (`259`) produces `width="259"`.
+- Width and height are both applied.
+- String pixel and percentage values use existing conversion rules.
+- Spaces or tabs between image and comment are accepted.
+- The original comment is preserved when unsafe HTML is enabled.
+- CommonMark safe mode applies attributes and retains raw-HTML omission.
+- Existing and Bear attributes merge, with Bear winning conflicts.
+- Definition metadata applies to every reference image using that definition.
+- Per-use metadata applies only to the explicit `![alt][id]` occurrence.
+- Per-use metadata overrides definition metadata without changing siblings.
+- A definition comment is rendered once, not once per image occurrence.
+- Reference matching follows cmark case and whitespace normalization.
+- Unresolved or link-only references do not receive image attributes.
+- Unknown, internal, and event-handler keys are ignored.
+- Attribute-breaking JSON strings cannot inject HTML.
+- Malformed JSON, nested values, and non-object payloads apply nothing.
+- A comment on the following line does not apply to the image.
+- Ordinary adjacent HTML comments remain unchanged.
+- Existing reference titles, IAL/MultiMarkdown attributes, and image
+  expansion behavior do not regress.
+
+Add a representative fixture under `tests/fixtures/images/` as well as
+unit-level assertions in the existing image attribute test suites.

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

@@ -0,0 +1,211 @@
+# Apex Node.js npm Package
+
+## Goal
+
+Publish `@apexmarkdown/apex` as a Node.js native binding for the Apex C
+library, so JavaScript projects can convert Markdown to HTML with Apex's
+modes and options without installing a separate CLI or system libraries.
+
+## Repository and layout
+
+Create a new repository at `/Users/ttscoff/Desktop/Code/apex-node`, parallel
+to `apex-ruby`. It is not part of the Apex core tree.
+
+Initial layout:
+
+```text
+apex-node/
+  package.json                 # public package @apexmarkdown/apex
+  README.md
+  LICENSE
+  vendor/apex/                 # pinned Apex git submodule
+  binding/
+    CMakeLists.txt
+    src/addon.cpp              # Node-API entry points
+    src/options.cpp            # JS object -> apex_options
+    src/options.h
+  lib/
+    index.js                   # ESM/CJS loader
+    index.d.ts                 # TypeScript declarations
+  test/
+  scripts/
+    build.js
+    package-prebuild.js
+  .github/workflows/
+    ci.yml
+    publish-prebuilds.yml
+```
+
+Platform binaries ship as optional dependencies:
+
+- `@apexmarkdown/apex-darwin-arm64`
+- `@apexmarkdown/apex-darwin-x64`
+- `@apexmarkdown/apex-linux-arm64`
+- `@apexmarkdown/apex-linux-x64`
+
+Each platform package contains a single `.node` addon for that target.
+
+## Architecture
+
+CMake builds:
+
+1. Vendored `cmark-gfm` from `vendor/apex/vendor/cmark-gfm`
+2. Vendored `libyaml` from `vendor/apex/vendor/libyaml`
+3. The Apex C library from `vendor/apex`
+4. A thin C++ Node-API adapter that links against Apex
+
+The addon exposes a small native surface. Ergonomics live in JavaScript and
+TypeScript declarations.
+
+Distribution:
+
+- Consumers install `@apexmarkdown/apex`.
+- npm installs the matching optional platform package when available.
+- The loader resolves the platform `.node` file at runtime.
+- Unsupported OS/arch combinations throw a clear error naming the detected
+  platform. Local compilation is not required for supported targets.
+
+Supported Node.js: 20 or newer.
+
+Supported first-release platforms: macOS and Linux, x64 and arm64.
+
+## JavaScript API
+
+ESM and CommonJS are both supported, with bundled TypeScript declarations:
+
+```ts
+import { convert, version } from "@apexmarkdown/apex";
+
+const html = convert("# Hello", {
+  mode: "gfm",
+  unsafe: false,
+  generateHeaderIds: true
+});
+```
+
+Primary surface:
+
+```ts
+convert(markdown: string, options?: ApexOptions): string
+version: string
+```
+
+`convert()` is synchronous. Async worker-thread conversion is out of scope
+for v1.
+
+## Options mapping
+
+`ApexOptions` exposes every user-facing serializable field from
+`apex_options` in camelCase. Defaults come from
+`apex_options_for_mode(mode)` (or unified defaults when `mode` is omitted).
+Explicit JavaScript properties overlay those defaults.
+
+Enum fields use string unions rather than C integers:
+
+| JS property | Values |
+| --- | --- |
+| `mode` | `"commonmark"`, `"gfm"`, `"multimarkdown"`, `"kramdown"`, `"unified"`, `"quarto"` |
+| `outputFormat` | `"html"`, `"json"`, `"jsonFiltered"`, `"markdown"`, `"mmd"`, `"commonmark"`, `"kramdown"`, `"gfm"`, `"terminal"`, `"terminal256"`, `"man"`, `"manHtml"`, `"toc"` |
+| `criticMode` | `"markup"`, `"accept"`, `"reject"` |
+| `idFormat` | `"gfm"`, `"mmd"` |
+| `captionPosition` | `"above"`, `"below"` |
+| `wikilinkSpace` | `"dash"`, `"none"`, `"underscore"`, `"space"` |
+
+Array fields accept `string[]`:
+
+- `stylesheetPaths`
+- `bibliographyFiles`
+- `scriptTags`
+- `astFilterCommands`
+
+Path-like and other string options remain caller-owned for the duration of
+the `convert()` call. The binding copies them into conversion-scoped native
+storage before invoking Apex.
+
+### Excluded native-only surfaces
+
+These `apex_options` members are not exposed in JavaScript:
+
+- `plugin_register` / `pluginRegister`
+- `progress_callback` / `progressCallback`
+- `progress_user_data` / `progressUserData`
+- `cmark_init` / `cmarkInit`
+- `cmark_done` / `cmarkDone`
+- `cmark_user_data` / `cmarkUserData`
+- `toc_entries_out` / `tocEntriesOut`
+- `toc_entries_count_out` / `tocEntriesCountOut`
+
+Structured TOC extraction via `apex_markdown_to_toc_entries()` may be added
+later as a separate API; it is not part of v1.
+
+## Data flow
+
+For each `convert()` call:
+
+1. Reject non-string Markdown with `TypeError`.
+2. Validate every supplied option name and type.
+3. Initialize `apex_options` from the selected mode.
+4. Overlay explicit JavaScript options onto that struct.
+5. Copy strings and arrays into conversion-scoped native storage.
+6. Call `apex_markdown_to_html(markdown, len, &options)`.
+7. Copy the returned UTF-8 buffer into a JavaScript string.
+8. Free the Apex buffer with `apex_free_string()`.
+9. Release conversion-scoped native storage.
+
+`version` returns `apex_version_string()` as a static JavaScript string.
+
+## Error handling
+
+| Condition | Behavior |
+| --- | --- |
+| Unknown option name | `TypeError` |
+| Wrong option type | `TypeError` |
+| Invalid enum string | `TypeError` |
+| Non-string Markdown | `TypeError` |
+| Native allocation / conversion failure | `Error` |
+| Unsupported OS / architecture | `Error` naming the detected platform |
+
+No silent ignoring of unknown or invalid options.
+
+## Build and packaging
+
+- CMake is the build system for the native addon and bundled dependencies.
+- `APEX_HAVE_LIBYAML` is enabled so YAML metadata matches the SwiftPM build.
+- Prebuilds are produced in CI for the four supported platforms.
+- The public package lists platform packages as optional dependencies and
+  contains no install-time compile step for supported targets.
+- Source builds remain available to maintainers via CMake; they are not the
+  primary consumer path.
+
+## Testing
+
+Automated tests cover:
+
+- Default conversion and each mode
+- Representative boolean, string, enum, and array options
+- Unknown option and wrong-type rejection
+- Empty input and UTF-8 content
+- `version` string presence
+- Loader failure messaging when the platform package is missing
+
+CI builds and tests each supported platform, then packages the `.node`
+artifact for that target.
+
+## Out of scope for v1
+
+- WebAssembly / browser builds
+- Windows prebuilds
+- Asynchronous / worker-thread conversion APIs
+- Structured TOC JavaScript API
+- JavaScript bridges for C callbacks (`progress`, `cmark_init` / `cmark_done`,
+  plugin registration)
+- Requiring system `cmark-gfm` or `libyaml`
+
+## Success criteria
+
+- `npm install @apexmarkdown/apex` works on macOS and Linux x64/arm64 with
+  no local C toolchain.
+- `convert("# Hi")` returns HTML containing a heading.
+- Mode and option overrides affect output as they do in Apex core.
+- Invalid options throw rather than being ignored.
+- TypeScript consumers get accurate declarations for the public API.

data/ext/apex_ext/apex_src/documentation/app-settings-table.md

@@ -0,0 +1,67 @@
+# Apex App Settings Reference
+
+This document lists all Settings referenced in the app-focused documentation that would need to be implemented in the Apex app.
+
+## Settings Structure
+
+### General
+
+| Setting | Type | Description |
+|---------|------|-------------|
+
+
+### Processor
+
+| Setting | Type | Description |
+|---------|------|-------------|
+| Settings->Processor** | Varies | Configure settings->processor** |
+| Settings->Processor**. | Varies | Configure settings->processor**. |
+| Alpha | Varies | Configure alpha |
+| Autolinks** | Varies | Configure autolinks** |
+| CSL | Varies | Configure csl |
+| Citations** | Varies | Configure citations** |
+| Citations**, | Varies | Configure citations**, |
+| Citations**. | Varies | Configure citations**. |
+| Combine | Varies | Configure combine |
+| Critic | Varies | Configure critic |
+| Fenced | Varies | Configure fenced |
+| Footnotes** | Varies | Configure footnotes** |
+| Generate | Varies | Configure generate |
+| Header | Varies | Configure header |
+| Include | Varies | Configure include |
+| Link | Varies | Configure link |
+| MMD | Varies | Configure mmd |
+| Math | Varies | Configure math |
+| Metadata | Varies | Configure metadata |
+| Mixed | Varies | Configure mixed |
+| Mode**. | Varies | Configure mode**. |
+| Superscript/Subscript**. | Varies | Configure superscript/subscript**. |
+| Suppress | Varies | Configure suppress |
+| Table | Varies | Configure table |
+| Wiki | Varies | Configure wiki |
+
+### Output
+
+| Setting | Type | Description |
+|---------|------|-------------|
+
+
+
+
+
+## Menu Items
+
+| Menu Item | Location | Description |
+|-----------|---------|-------------|
+| Plugins menu | Main menu | Access plugins menu |
+| Help menu | Main menu | Access help menu |
+| About window | Main menu | Access about window |
+
+## Notes
+
+- Settings should be organized in a Settings window with the structure: **Settings->Category->Setting Name**
+- Boolean settings (checkboxes/toggles) should have clear on/off states
+- File selection settings should provide a file picker dialog
+- Text input settings should have appropriate validation
+- Settings should be saved per-document or globally (user preference)
+