apex-ruby 1.0.30 → 1.0.32

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

@@ -1,161 +0,0 @@
-# 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

@@ -1,184 +0,0 @@
-# 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

@@ -1,211 +0,0 @@
-# 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.