fix(nft): address review findings before 0.10.0

[kalwalt]

Fixes three findings Qodo raised on the release PR #79, before tagging 0.10.0. All three are in code that came with #76.

Summary

• a49cb73 – trackingInitMain null check: after threadGetArg() the guard re-tested threadHandle, so a NULL trackingInitHandle was dereferenced on the worker thread.

• faa50a6 – cap the decompressed .zft size: inflateAll() grew its buffer without bound, so a small archive with a huge expansion ratio could exhaust memory. Archives expanding past MARKER_DECOMPRESS_MAX_SIZE (128 MB, overridable with -D) now return -1. Real markers are a few MB. markerDecompress.h now documents the return values, and that outTemp should name new files.

• dd3e7d8 – AR2_CAPABLE_ADAPTIVE_TEMPLATE: the Mod tracking path never supported adaptive templates; with the option on, trackingMod2d.c did not compile. trackingMod.h now stops the build with an explicit #error, and trackingMod2d.c includes it. The option is 0 in config.h, so default builds are unaffected.

• 7506d59 – limit edge cases (Qodo on this PR): the initial buffer is capped at the limit, so limits below 4 MB are enforced; at the limit zlib gets one spare byte to finish the stream, so an archive of exactly the limit is accepted. New webarkit_nft_limit_test (markerDecompress built with a 1 MB limit), run in CI.

Not changed, with reasons in the review threads on #79:

• overwriting an existing marker set on a failed extraction: callers extract to fresh temporary paths; documented instead
• NUL bytes in archive data: .zft payloads are hex text, so an archive with a NUL is malformed and -1 is correct

Test plan

• Native (Ubuntu 24.04, GCC 13): webarkit_nft_test 13/13 (new: ArchiveExpandingPastTheLimitReturnsError), webarkit_test 28/28
• webarkit_nft_limit_test 3/3 (2 of them fail on dd3e7d8)
• With AR2_CAPABLE_ADAPTIVE_TEMPLATE 1: trackingMod.c and trackingMod2d.c stop at the #error
• Emscripten 4.0.17: WebARKitNFT builds with and without threads
• examples/DataNFT/zft/pinball.zft output still byte-identical to the original implementation
• jsartoolkitNFT examples against this branch (refactor: use the NFT helpers from WebARKitLib (#453) jsartoolkitNFT#687)

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Fix NFT tracking guards and bound .zft decompression

🐞 Bug fix 🧪 Tests 📝 Documentation 🕐 20-40 Minutes

AI Description

• Prevent a null worker-thread argument from being dereferenced.
• Reject .zft archives that expand beyond a configurable 128 MB limit.
• Clearly reject unsupported adaptive-template builds and document marker extraction failure
 behavior.

Diagram

graph TD
  Z["ZFT archive"] --> D["decompressMarkers"] --> I["Bounded inflate"] --> L{"Within size limit?"} --> P["Parse markers"] --> F["Marker files"]
  L -- "No" --> E["Return -1"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Stream decompression and extraction

• ➕ Could reduce peak memory use by avoiding a complete inflated buffer.
• ➖ Requires incremental parsing and more complex partial-file cleanup.
• ➖ Is a substantially broader change than these release fixes.

Recommendation: Keep the bounded-buffer approach for this release: it addresses excessive expansion while preserving the existing extraction flow. Streaming extraction is worth considering separately if ordinary marker sizes or peak memory use warrant it.

Files changed (6) +67 / -8

Bug fix (5) +30 / -3

markerDecompress.hExpose the decompression limit and document extraction failures +11/-0

Expose the decompression limit and document extraction failures

• Defines an overridable 128 MB maximum for inflated .zft data. Documents return values and warns that failed extraction does not preserve marker files already at the output path.

WebARKit/WebARKitTrackers/WebARKitNFT/include/WebARKitTrackers/WebARKitNFT/markerDecompress.h

trackingMod.hReject unsupported adaptive-template builds explicitly +4/-0

Reject unsupported adaptive-template builds explicitly

• Adds a compile-time error when adaptive templates are enabled for the Mod tracking path, replacing less clear compilation failures.

WebARKit/WebARKitTrackers/WebARKitNFT/include/WebARKitTrackers/WebARKitNFT/trackingMod.h

markerDecompress.cCap inflated .zft data before extraction +13/-2

Cap inflated .zft data before extraction

• Stops buffer growth at the configured limit and returns an error if inflation needs more space. This prevents highly compressible archives from driving unbounded allocation.

WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c

trackingMod2d.cApply the Mod tracking declaration and compile-time guard +1/-0

Apply the Mod tracking declaration and compile-time guard

• Includes the public Mod tracking header so this translation unit receives the unsupported-option error and the function declaration.

WebARKit/WebARKitTrackers/WebARKitNFT/trackingMod2d.c

trackingSub.cCheck the worker-thread argument before dereferencing it +1/-1

Check the worker-thread argument before dereferencing it

• Corrects the post-threadGetArg guard to test trackingInitHandle rather than rechecking threadHandle.

WebARKit/WebARKitTrackers/WebARKitNFT/trackingSub.c

Tests (1) +37 / -5

webarkit_nft_test.ccCover rejection of oversized .zft archives +37/-5

Cover rejection of oversized .zft archives

• Generates a highly compressible archive whose expanded payload exceeds the limit, then checks that extraction fails without creating an .iset file. Moves the file-existence helper alongside the other test helpers.

tests/webarkit_nft_test.cc

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Smaller archive limits can be bypassed ✓ Resolved

Description

inflateAll() starts with a fixed 4 MiB output buffer and checks inflate_max only when that
buffer fills. If MARKER_DECOMPRESS_MAX_SIZE is configured below 4 MiB, an archive that expands
past the configured limit but stays within the initial buffer can be extracted successfully.

Code

WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[45]

+            if (cap >= inflate_max) {

Evidence

The new header allows a build-time limit override. The implementation allocates 4 MiB before
consulting that limit, offers the entire buffer to zlib, and passes successfully inflated data to
extraction.

WebARKit/WebARKitTrackers/WebARKitNFT/include/WebARKitTrackers/WebARKitNFT/markerDecompress.h[6-9]
WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[29-31]
WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[43-60]
WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[116-121]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A configured decompression limit below 4 MiB is not enforced because inflation starts with a 4 MiB buffer.
## Fix Focus Areas
- WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[17-54]
## Recommended Fix
Initialize output capacity no larger than the configured limit, validate the limit, and add a test using an override below 4 MiB.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Archives at the size limit can fail ✓ Resolved

Description

inflateAll() rejects whenever its output buffer is full at inflate_max, before allowing zlib to
finish reading the stream. A valid stream that produces exactly the permitted number of bytes but
still has an empty final block or trailer to process returns an error rather than extracting its
markers.

Code

WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[R45-48]

+            if (cap >= inflate_max) {
+                ARLOGe("Error: .zft data expands past %zu bytes\n", inflate_max);
+                ret = Z_MEM_ERROR;
+                break;

Evidence

The header specifies that archives larger than the limit are rejected. The new check instead rejects
a full buffer before another inflate call can process a stream ending that emits no further output.

WebARKit/WebARKitTrackers/WebARKitNFT/include/WebARKitTrackers/WebARKitNFT/markerDecompress.h[6-8]
WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[41-64]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A stream producing exactly the configured maximum can be rejected if zlib has not yet processed its end marker when the output buffer fills.
## Fix Focus Areas
- WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[43-64]
## Recommended Fix
When output reaches the limit, permit zlib to finish using at most one additional output byte; reject only if it produces output beyond the maximum. Test a valid stream that produces exactly the limit before its final block.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗