apex-ruby 1.0.30 → 1.0.31

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

@@ -1,829 +0,0 @@
-# Bear Image Attribute Comments 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:** Render allowlisted Bear JSON image metadata on inline and reference
-images while preserving the source comment and existing HTML safety.
-
-**Architecture:** Add a private, dependency-free parser for adjacent Bear
-comments, then feed its normalized key/value results into the existing image
-attribute preprocessor. Inline and per-use attributes use indexed image
-entries; definition attributes use the existing reference expansion path.
-
-**Tech Stack:** C99, cmark-gfm, Apex image attribute preprocessing, CMake,
-and the existing C test runner.
-
-## Global Constraints
-
-- Recognize metadata in CommonMark, GFM, MultiMarkdown, and Unified-family
-  modes, but not Kramdown.
-- Accept only same-line comments separated from the image or definition by
-  zero or more spaces or tabs.
-- Preserve the exact comment when raw HTML is allowed.
-- Keep existing safe-HTML behavior, including `<!-- raw HTML omitted -->`.
-- Allow only `width`, `height`, `style`, `class`, `id`, `rel`, and `title`.
-- Accept numbers or strings for `width` and `height`; other allowed values
-  must be strings.
-- Ignore unsupported keys and unsupported value types without applying them.
-- Reject a malformed or non-object JSON payload as a whole.
-- Do not add a JSON dependency or modify vendored cmark-gfm.
-- Definition metadata is the baseline; per-use metadata wins for one image.
-- Per-use metadata supports only explicit `![alt][id]` references.
-- Definition metadata applies to full, collapsed, and shortcut image refs.
-- Comments after reference definitions render exactly once.
-
----
-
-## File Structure
-
-- Create `src/extensions/bear_image_attrs.h`: private parser data types and
-  function declarations.
-- Create `src/extensions/bear_image_attrs.c`: bounded JSON comment parser,
-  allowlist, scalar conversion, and memory cleanup.
-- Modify `src/extensions/ial.c`: merge parsed Bear values into inline,
-  reference-definition, and per-use image attribute entries.
-- Modify `src/apex.c`: run image preprocessing in CommonMark and GFM.
-- Modify `CMakeLists.txt`: compile the parser and focused test suite.
-- Create `tests/test_bear_image_attrs.c`: parser and end-to-end behavior.
-- Modify `tests/test_runner.c`: register the focused test suite.
-- Create `tests/fixtures/images/bear_image_attributes.md`: representative
-  inline and reference syntax.
-
-### Task 1: Private Bear Comment Parser
-
-**Files:**
-
-- Create: `src/extensions/bear_image_attrs.h`
-- Create: `src/extensions/bear_image_attrs.c`
-- Modify: `CMakeLists.txt:109-157,343-365`
-- Create: `tests/test_bear_image_attrs.c`
-- Modify: `tests/test_runner.c:27-87,101-163`
-
-**Interfaces:**
-
-- Produces:
-  `bool apex_parse_bear_image_comment(const char *, const char *,
-  const char **, apex_bear_image_attrs *)`
-- Produces:
-  `void apex_free_bear_image_attrs(apex_bear_image_attrs *)`
-- Consumes: no Apex parser internals and no external JSON library.
-
-- [ ] **Step 1: Add failing parser tests and register the suite**
-
-Create the test suite with direct parser assertions:
-
-```c
-#include "test_helpers.h"
-#include "extensions/bear_image_attrs.h"
-
-#include <string.h>
-
-static const char *bear_value(const apex_bear_image_attrs *attrs,
-                              const char *key) {
-    for (size_t i = 0; i < attrs->count; i++) {
-        if (strcmp(attrs->items[i].key, key) == 0) {
-            return attrs->items[i].value;
-        }
-    }
-    return NULL;
-}
-
-void test_bear_image_attributes(void) {
-    int failures = suite_start();
-    print_suite_title("Bear Image Attribute Tests", false, true);
-
-    const char *input = "<!-- {\"width\":259,\"title\":\"A & B\"} -->";
-    const char *end = input + strlen(input);
-    const char *comment_end = NULL;
-    apex_bear_image_attrs attrs = {0};
-
-    bool ok = apex_parse_bear_image_comment(
-        input, end, &comment_end, &attrs);
-    test_result(ok, "Bear parser accepts a flat JSON object");
-    assert_option_string(
-        bear_value(&attrs, "width"), "259", "Numeric width is normalized");
-    assert_option_string(
-        bear_value(&attrs, "title"), "A & B", "String value is decoded");
-    test_result(comment_end == end, "Parser returns the comment end");
-    apex_free_bear_image_attrs(&attrs);
-
-    const char *unsafe =
-        "<!-- {\"width\":259,\"onclick\":\"alert(1)\","
-        "\"data-x\":\"bad\"} -->";
-    end = unsafe + strlen(unsafe);
-    attrs = (apex_bear_image_attrs){0};
-    ok = apex_parse_bear_image_comment(
-        unsafe, end, &comment_end, &attrs);
-    test_result(ok, "Unsupported keys do not invalidate metadata");
-    test_result(
-        attrs.count == 1, "Only allowlisted attributes are returned");
-    apex_free_bear_image_attrs(&attrs);
-
-    const char *nested =
-        "<!-- {\"width\":259,\"title\":{\"nested\":true}} -->";
-    end = nested + strlen(nested);
-    attrs = (apex_bear_image_attrs){0};
-    ok = apex_parse_bear_image_comment(
-        nested, end, &comment_end, &attrs);
-    test_result(ok, "Unsupported nested values are skipped");
-    test_result(attrs.count == 1, "Supported sibling value is retained");
-    apex_free_bear_image_attrs(&attrs);
-
-    const char *bad = "<!-- {\"width\":259,} -->";
-    end = bad + strlen(bad);
-    attrs = (apex_bear_image_attrs){0};
-    test_result(
-        !apex_parse_bear_image_comment(
-            bad, end, &comment_end, &attrs),
-        "Malformed JSON is rejected");
-
-    bool had_failures = suite_end(failures);
-    print_suite_title("Bear Image Attribute Tests", had_failures, false);
-}
-```
-
-Add `tests/test_bear_image_attrs.c` to the `apex_test_runner` sources in
-`CMakeLists.txt`, declare `test_bear_image_attributes()` in
-`tests/test_runner.c`, and register:
-
-```c
-{ "bear_image_attributes", test_bear_image_attributes },
-```
-
-- [ ] **Step 2: Run the focused test and verify it fails**
-
-Run:
-
-```bash
-cmake -S . -B build
-cmake --build build --target apex_test_runner
-./build/apex_test_runner bear_image_attributes
-```
-
-Expected: compilation fails because `extensions/bear_image_attrs.h` does not
-exist.
-
-- [ ] **Step 3: Define the private parser interface**
-
-Create `src/extensions/bear_image_attrs.h`:
-
-```c
-#ifndef APEX_BEAR_IMAGE_ATTRS_H
-#define APEX_BEAR_IMAGE_ATTRS_H
-
-#include <stdbool.h>
-#include <stddef.h>
-
-#define APEX_BEAR_IMAGE_ATTR_CAPACITY 7
-
-typedef struct {
-    char *key;
-    char *value;
-} apex_bear_image_attr;
-
-typedef struct {
-    apex_bear_image_attr items[APEX_BEAR_IMAGE_ATTR_CAPACITY];
-    size_t count;
-} apex_bear_image_attrs;
-
-bool apex_parse_bear_image_comment(
-    const char *comment_start,
-    const char *line_end,
-    const char **comment_end,
-    apex_bear_image_attrs *attrs);
-
-void apex_free_bear_image_attrs(apex_bear_image_attrs *attrs);
-
-#endif
-```
-
-- [ ] **Step 4: Implement strict flat-object parsing**
-
-Create `src/extensions/bear_image_attrs.c`. Implement these private helpers:
-
-```c
-static void skip_json_ws(const char **cursor, const char *end);
-static bool parse_json_string(
-    const char **cursor, const char *end, char **value);
-static bool parse_json_number(
-    const char **cursor, const char *end, char **value);
-static bool skip_json_value(
-    const char **cursor, const char *end, unsigned depth);
-static bool is_allowed_key(const char *key);
-static bool key_accepts_number(const char *key);
-static bool set_attr(
-    apex_bear_image_attrs *attrs, char *key, char *value);
-```
-
-The implementation must:
-
-1. Require `<!--`, find `-->` before `line_end`, and trim JSON whitespace.
-2. Require one complete object and no non-whitespace after its closing `}`.
-3. Decode JSON strings, including standard escapes and UTF-16 `\uXXXX`
-   surrogate pairs converted to UTF-8.
-4. Validate the full JSON number grammar before copying its source spelling.
-5. Recursively validate and skip unsupported arrays and objects with a
-   maximum nesting depth of 32.
-6. Validate and skip `true`, `false`, and `null`.
-7. Store only allowlisted scalar values of an accepted type.
-8. Replace an earlier duplicate allowed key so the final JSON member wins.
-9. Free partial results and return false on malformed JSON or allocation
-   failure.
-10. Set `comment_end` one byte after `-->` only on success.
-
-Add `src/extensions/bear_image_attrs.c` after `src/extensions/ial.c` in
-`APEX_LIB_SOURCES`.
-
-- [ ] **Step 5: Run the parser tests**
-
-Run:
-
-```bash
-cmake --build build --target apex_test_runner
-./build/apex_test_runner bear_image_attributes
-```
-
-Expected: all parser assertions pass.
-
-- [ ] **Step 6: Commit the parser**
-
-```bash
-git add CMakeLists.txt src/extensions/bear_image_attrs.c \
-  src/extensions/bear_image_attrs.h tests/test_bear_image_attrs.c \
-  tests/test_runner.c
-git commit -m "$(cat <<'EOF'
-Add Bear image metadata parser
-
-Parse and validate adjacent flat JSON metadata without adding a dependency.
-EOF
-)"
-```
-
-### Task 2: Inline Images and Mode Integration
-
-**Files:**
-
-- Modify: `src/extensions/ial.c:604-800,2653-3015`
-- Modify: `src/apex.c:5065-5082`
-- Modify: `tests/test_bear_image_attrs.c`
-
-**Interfaces:**
-
-- Consumes: `apex_parse_bear_image_comment()` from Task 1.
-- Produces: Bear attributes merged into indexed inline `image_attr_entry`
-  values.
-
-- [ ] **Step 1: Add failing inline and mode tests**
-
-Append a renderer helper and inline assertions:
-
-```c
-static char *render_bear(
-    const char *markdown, apex_mode_t mode, bool unsafe) {
-    apex_options opts = apex_options_for_mode(mode);
-    opts.unsafe = unsafe;
-    return apex_markdown_to_html(markdown, strlen(markdown), &opts);
-}
-
-static void test_bear_inline_modes(void) {
-    const char *md =
-        "![](emperor-1.jpg)<!-- {\"width\":259} -->";
-    const apex_mode_t modes[] = {
-        APEX_MODE_COMMONMARK,
-        APEX_MODE_GFM,
-        APEX_MODE_MULTIMARKDOWN,
-        APEX_MODE_UNIFIED
-    };
-
-    for (size_t i = 0; i < sizeof(modes) / sizeof(modes[0]); i++) {
-        char *html = render_bear(md, modes[i], true);
-        assert_contains(html, "width=\"259\"", "Bear width is applied");
-        assert_contains(
-            html,
-            "<!-- {\"width\":259} -->",
-            "Bear comment is preserved");
-        apex_free_string(html);
-    }
-
-    char *safe = render_bear(md, APEX_MODE_COMMONMARK, false);
-    assert_contains(safe, "width=\"259\"", "Safe mode applies Bear width");
-    assert_contains(
-        safe, "raw HTML omitted", "Safe mode keeps raw HTML policy");
-    apex_free_string(safe);
-
-    char *spaced = render_bear(
-        "![](x.jpg) \t<!-- {\"width\":\"50%\",\"height\":\"20px\"} -->",
-        APEX_MODE_UNIFIED,
-        true);
-    assert_contains(
-        spaced, "height=\"20\"", "Pixel height uses an HTML attribute");
-    assert_contains(
-        spaced, "style=\"width: 50%\"", "Percent width uses style");
-    apex_free_string(spaced);
-}
-```
-
-Call `test_bear_inline_modes()` from `test_bear_image_attributes()`.
-
-- [ ] **Step 2: Run the suite and verify behavior is missing**
-
-Run:
-
-```bash
-cmake --build build --target apex_test_runner
-./build/apex_test_runner bear_image_attributes
-```
-
-Expected: parser tests pass; renderer assertions fail because Bear metadata
-is not attached and preprocessing does not run in CommonMark or GFM.
-
-- [ ] **Step 3: Add Bear-to-Apex attribute conversion**
-
-Include `bear_image_attrs.h` from `ial.c` and add:
-
-```c
-static apex_attributes *attributes_from_bear(
-    const apex_bear_image_attrs *bear) {
-    apex_attributes *attrs = create_attributes();
-    if (!attrs) return NULL;
-
-    for (size_t i = 0; i < bear->count; i++) {
-        add_attribute(
-            attrs, bear->items[i].key, bear->items[i].value);
-    }
-    return attrs;
-}
-```
-
-Add a small detector that skips only spaces and tabs, calls the parser, and
-returns both parsed attributes and the end of the comment:
-
-```c
-static apex_attributes *parse_adjacent_bear_attrs(
-    const char *after_construct,
-    const char *line_end,
-    const char **comment_start,
-    const char **comment_end);
-```
-
-It must leave `comment_start` null when no valid Bear object is present.
-
-- [ ] **Step 4: Merge Bear values after inline IAL values**
-
-In the inline-image branch of `apex_preprocess_image_attributes()`, call
-`parse_adjacent_bear_attrs()` after the closing parenthesis and optional IAL.
-Merge with `merge_attributes(existing, bear)` in source order. Do not advance
-the main read cursor over spaces or the comment, so cmark receives them
-byte-for-byte.
-
-Set `do_image_attrs` to:
-
-```c
-bool do_image_attrs =
-    apex_mode_is_unified_family(mode) ||
-    mode == APEX_MODE_MULTIMARKDOWN ||
-    mode == APEX_MODE_GFM ||
-    mode == APEX_MODE_COMMONMARK;
-```
-
-In `src/apex.c`, extend the preprocessing gate:
-
-```c
-if (apex_mode_is_unified_family(options->mode) ||
-    options->mode == APEX_MODE_MULTIMARKDOWN ||
-    options->mode == APEX_MODE_KRAMDOWN ||
-    options->mode == APEX_MODE_GFM ||
-    options->mode == APEX_MODE_COMMONMARK) {
-```
-
-Kramdown still enters the preprocessor for URL encoding, but
-`do_image_attrs` remains false for that mode.
-
-- [ ] **Step 5: Prevent Bear string values from injecting HTML**
-
-Before adding Bear values to `apex_attributes`, encode `&`, `"`, `<`, and
-`>` as `&amp;`, `&quot;`, `&lt;`, and `&gt;`. Keep width and height
-classification based on the decoded value before encoding.
-
-Add this assertion:
-
-```c
-char *escaped = render_bear(
-    "![](x.jpg)<!-- {\"title\":\"x\\\" onerror=\\\"boom\"} -->",
-    APEX_MODE_UNIFIED,
-    true);
-assert_contains(
-    escaped,
-    "title=\"x&quot; onerror=&quot;boom\"",
-    "Bear values are HTML attribute escaped");
-assert_not_contains(
-    escaped, " onerror=\"boom\"", "Bear values cannot inject attributes");
-apex_free_string(escaped);
-```
-
-- [ ] **Step 6: Run focused and existing image tests**
-
-Run:
-
-```bash
-cmake --build build --target apex_test_runner
-./build/apex_test_runner bear_image_attributes
-./build/apex_test_runner image_width_height_conversion
-./build/apex_test_runner multimarkdown_image_attributes
-```
-
-Expected: all three suites pass.
-
-- [ ] **Step 7: Commit inline support**
-
-```bash
-git add src/apex.c src/extensions/ial.c tests/test_bear_image_attrs.c
-git commit -m "$(cat <<'EOF'
-Render Bear attributes on inline images
-
-@new **Bear image attributes** Apply safe JSON metadata while preserving its comment.
-EOF
-)"
-```
-
-### Task 3: Reference-Definition Metadata
-
-**Files:**
-
-- Modify: `src/extensions/ial.c:2551-2561,3076-3594,3775-3917`
-- Modify: `tests/test_bear_image_attrs.c`
-- Create: `tests/fixtures/images/bear_image_attributes.md`
-
-**Interfaces:**
-
-- Consumes: Task 1 parser and Task 2 conversion helper.
-- Produces: normalized reference entries whose attributes expand into every
-  matching full, collapsed, or shortcut image reference.
-
-- [ ] **Step 1: Add failing definition tests**
-
-Add:
-
-```c
-static void test_bear_reference_definitions(void) {
-    const char *md =
-        "![One][Emperor]\n\n"
-        "![Emperor][]\n\n"
-        "![Emperor]\n\n"
-        "[ emperor ]: emperor.jpg "
-        "<!-- {\"width\":259,\"title\":\"Ruler\"} -->";
-    char *html = render_bear(md, APEX_MODE_UNIFIED, true);
-
-    const char *cursor = html;
-    int widths = 0;
-    while ((cursor = strstr(cursor, "width=\"259\"")) != NULL) {
-        widths++;
-        cursor += strlen("width=\"259\"");
-    }
-    test_result(widths == 3, "Definition metadata applies to every use");
-    assert_contains(
-        html,
-        "<!-- {\"width\":259,\"title\":\"Ruler\"} -->",
-        "Definition comment is preserved once");
-
-    cursor = html;
-    int comments = 0;
-    while ((cursor = strstr(cursor, "<!-- {\"width\":259")) != NULL) {
-        comments++;
-        cursor++;
-    }
-    test_result(comments == 1, "Definition comment renders exactly once");
-    apex_free_string(html);
-}
-```
-
-Use reference labels whose casing and internal whitespace differ between
-definition and use in an additional assertion.
-
-- [ ] **Step 2: Run the suite and verify it fails**
-
-Run:
-
-```bash
-cmake --build build --target apex_test_runner
-./build/apex_test_runner bear_image_attributes
-```
-
-Expected: definition metadata is not applied, and cmark consumes or rejects
-the trailing comment as part of the definition.
-
-- [ ] **Step 3: Reuse normalized reference matching**
-
-Move `reference_id_matches()` above `find_image_attr_by_ref()` or add a
-forward declaration. Change reference lookup from `strcmp()` to:
-
-```c
-if (entry->ref_name &&
-    reference_id_matches(
-        entry->ref_name, ref_name, strlen(ref_name))) {
-    return entry;
-}
-```
-
-Use the same matcher for full, collapsed, and shortcut expansion.
-
-- [ ] **Step 4: Parse definition comments before attribute tails**
-
-In the reference-definition branch:
-
-1. Find an adjacent Bear comment after URL, title, or IAL processing.
-2. Use its start as the effective end of title/MMD attribute parsing.
-3. Merge Bear attributes after existing definition attributes.
-4. Create a reference entry whenever the definition has Bear attributes.
-5. Mark that definition for reference-image expansion.
-
-When an attribute-bearing definition is removed, write the original comment
-and its original leading spaces to the output buffer before copying the
-line ending. Do not copy the definition itself. This leaves one standalone
-raw HTML comment for cmark to render or suppress according to safe mode.
-
-- [ ] **Step 5: Expand every reference image form**
-
-Extend the second pass to identify:
-
-```markdown
-![alt][id]
-![id][]
-![id]
-```
-
-For collapsed and shortcut forms, use the alt text as the reference label.
-Do not treat `![alt](url)` as a shortcut reference. Expand a reference only
-when `find_image_attr_by_ref()` returns an attribute-bearing definition.
-
-Continue producing `![alt](url attributes)` so the existing post-expansion
-scan creates indexed entries and avoids URL-based attribute leakage.
-
-- [ ] **Step 6: Add the representative fixture**
-
-Create `tests/fixtures/images/bear_image_attributes.md`:
-
-```markdown
-# Bear image attributes
-
-![](inline.jpg)<!-- {"width":259} -->
-
-![First][shared]
-![Second][shared]
-
-![Override][shared]<!-- {"width":320} -->
-
-[shared]: shared.jpg <!-- {"width":200,"height":100} -->
-```
-
-- [ ] **Step 7: Run focused and reference regression tests**
-
-Run:
-
-```bash
-cmake --build build --target apex_test_runner
-./build/apex_test_runner bear_image_attributes
-./build/apex_test_runner multimarkdown_image_attributes
-./build/apex_test_runner ial
-```
-
-Expected: all suites pass; the new definition assertions find one preserved
-comment and attributes on every reference form.
-
-- [ ] **Step 8: Commit definition support**
-
-```bash
-git add src/extensions/ial.c tests/test_bear_image_attrs.c \
-  tests/fixtures/images/bear_image_attributes.md
-git commit -m "$(cat <<'EOF'
-Apply Bear attributes from image references
-
-@new **Reference metadata** Apply attributes to every matching image.
-EOF
-)"
-```
-
-### Task 4: Per-Use Reference Overrides
-
-**Files:**
-
-- Modify: `src/extensions/ial.c:3775-4074`
-- Modify: `tests/test_bear_image_attrs.c`
-
-**Interfaces:**
-
-- Consumes: normalized reference definitions from Task 3.
-- Produces: merged indexed attributes for one explicit `![alt][id]`
-  occurrence without mutating the shared definition entry.
-
-- [ ] **Step 1: Add failing per-use tests**
-
-Add:
-
-```c
-static void test_bear_reference_overrides(void) {
-    const char *md =
-        "![Default][shared]\n\n"
-        "![Wide][shared]<!-- {\"width\":320,\"title\":\"Wide\"} -->\n\n"
-        "![Default again][shared]\n\n"
-        "[shared]: shared.jpg <!-- {\"width\":200,\"height\":100} -->";
-    char *html = render_bear(md, APEX_MODE_UNIFIED, true);
-
-    const char *cursor = html;
-    int defaults = 0;
-    while ((cursor = strstr(cursor, "width=\"200\"")) != NULL) {
-        defaults++;
-        cursor += strlen("width=\"200\"");
-    }
-    test_result(defaults == 2, "Sibling references retain definition width");
-    test_result(
-        strstr(html, "width=\"320\"") != NULL,
-        "Per-use metadata overrides the definition width");
-    assert_contains(
-        html, "title=\"Wide\"", "Per-use title is applied");
-
-    cursor = html;
-    int inherited_heights = 0;
-    while ((cursor = strstr(cursor, "height=\"100\"")) != NULL) {
-        inherited_heights++;
-        cursor += strlen("height=\"100\"");
-    }
-    test_result(
-        inherited_heights == 3,
-        "Per-use metadata inherits the definition height");
-
-    assert_contains(
-        html,
-        "<!-- {\"width\":320,\"title\":\"Wide\"} -->",
-        "Per-use comment is preserved");
-    apex_free_string(html);
-
-    char *unresolved = render_bear(
-        "![Missing][none]<!-- {\"width\":999} -->",
-        APEX_MODE_UNIFIED,
-        true);
-    assert_not_contains(
-        unresolved, "<img", "Unresolved reference remains unresolved");
-    assert_contains(
-        unresolved,
-        "<!-- {\"width\":999} -->",
-        "Unresolved metadata comment is preserved");
-    apex_free_string(unresolved);
-}
-```
-
-- [ ] **Step 2: Run the suite and verify sibling leakage**
-
-Run:
-
-```bash
-cmake --build build --target apex_test_runner
-./build/apex_test_runner bear_image_attributes
-```
-
-Expected: the override assertion fails or all shared references receive the
-same width because no local merge exists yet.
-
-- [ ] **Step 3: Detect metadata on explicit reference uses**
-
-During the second-pass `![alt][ref]` scan:
-
-1. Set `after_use` to one byte after the reference closing bracket.
-2. Call `parse_adjacent_bear_attrs(after_use, line_end, ...)`.
-3. Leave collapsed and shortcut references ineligible for local metadata.
-4. If the reference is unresolved, copy the original use and comment.
-
-- [ ] **Step 4: Merge without mutating the definition**
-
-Add a deep-copy helper:
-
-```c
-static apex_attributes *copy_attributes(const apex_attributes *source);
-```
-
-For an explicit resolved use, copy `def_entry->attrs`, merge the local Bear
-attributes into the copy, and pass only the copy to
-`attributes_to_markdown()`. Free it after writing the expanded image.
-
-Set `read2 = ref_end + 1`, not `comment_end`, after expansion. The normal
-copy loop must preserve all spaces and the exact per-use comment.
-
-- [ ] **Step 5: Run focused and image regression tests**
-
-Run:
-
-```bash
-cmake --build build --target apex_test_runner
-./build/apex_test_runner bear_image_attributes
-./build/apex_test_runner image_width_height_conversion
-./build/apex_test_runner multimarkdown_image_attributes
-```
-
-Expected: all suites pass; two siblings retain width 200 and only the local
-image receives width 320.
-
-- [ ] **Step 6: Commit per-use support**
-
-```bash
-git add src/extensions/ial.c tests/test_bear_image_attrs.c
-git commit -m "$(cat <<'EOF'
-Support per-image Bear reference metadata
-
-@new **Per-image reference attributes** Override shared metadata on one image.
-EOF
-)"
-```
-
-### Task 5: Full Regression and Final Review
-
-**Files:**
-
-- Modify only files required by failures directly caused by this feature.
-
-**Interfaces:**
-
-- Consumes: all previous tasks.
-- Produces: a warning-clean build and passing complete test suite.
-
-- [ ] **Step 1: Build with project warnings enabled**
-
-Run:
-
-```bash
-cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
-cmake --build build
-```
-
-Expected: build succeeds without new warnings from Bear parser or image
-preprocessing files.
-
-- [ ] **Step 2: Run focused suites**
-
-Run:
-
-```bash
-./build/apex_test_runner bear_image_attributes
-./build/apex_test_runner image_width_height_conversion
-./build/apex_test_runner multimarkdown_image_attributes
-./build/apex_test_runner ial
-./build/apex_test_runner unsafe_mode
-./build/apex_test_runner processor_modes
-```
-
-Expected: every suite reports zero failures.
-
-- [ ] **Step 3: Run the complete test suite**
-
-Run:
-
-```bash
-ctest --test-dir build --output-on-failure
-```
-
-Expected: `100% tests passed, 0 tests failed`.
-
-- [ ] **Step 4: Run memory diagnostics when available**
-
-Run:
-
-```bash
-cmake -S . -B build-asan -DCMAKE_BUILD_TYPE=Debug \
-  -DCMAKE_C_FLAGS="-fsanitize=address,undefined"
-cmake --build build-asan --target apex_test_runner
-ASAN_OPTIONS=detect_leaks=1 \
-  ./build-asan/apex_test_runner bear_image_attributes
-```
-
-Expected: all assertions pass with no AddressSanitizer, UndefinedBehavior
-Sanitizer, or leak report.
-
-- [ ] **Step 5: Review the final diff**
-
-Run:
-
-```bash
-git diff --check
-git status --short
-git diff --stat
-```
-
-Expected: no whitespace errors; only planned source, test, build-list, and
-fixture files are changed.
-
-- [ ] **Step 6: Commit any test-only corrections**
-
-Skip this step if Task 5 required no changes. Otherwise:
-
-```bash
-git add tests/test_bear_image_attrs.c \
-  tests/fixtures/images/bear_image_attributes.md
-git commit -m "$(cat <<'EOF'
-Strengthen Bear image metadata coverage
-
-Cover safe rendering, malformed JSON, and reference attribute isolation.
-EOF
-)"
-```