apex-ruby 1.0.17 → 1.0.20

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

@@ -0,0 +1,829 @@
+# 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
+)"
+```