chore: add getPagePointer to enable zero-copy memory reads from JS

[MaciejBaj]

Implements the approach suggested in #113: expose a WASM-side function that returns the linear memory pointer for an already-allocated page buffer, letting JS copy bytes directly without any extra WASM allocation.

closes #113

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Direct memory pointer access APIs for efficient, zero-copy reads from WASM memory.

• Documentation

  • Clarified memory-access guidance and pointer API behavior when pages are missing or unreadable.

• Tests

  • Expanded coverage for page access scenarios (missing, reserved, readable, writable, data integrity); added assertion utility to improve test validations.

Walkthrough

This PR adds a zero-copy memory-access API across three layers: Memory.getPagePointer(pageIndex: u32): usize, api-debugger.getPagePointer(page: u32): usize, and pvmGetPagePointer(pvmId: u32, page: u32): usize. Each returns the WASM linear memory pointer (byte offset) for a page's backing buffer or 0 when the page is missing or not readable. Tests for page-pointer behavior were added, and an Assert.isNotEqual helper was introduced for tests. getMemory remains but its docs were updated to recommend the pointer-based approach.

Possibly related PRs

• Added getMemory to api-debugger #92: Modifies assembly/api-debugger.ts with new memory-access APIs; related by changes to debugger-level memory functions.
• Fix getting memory from ananas #112: Changes Memory and debugger APIs for page-aware memory access; related by complementary approaches to non-allocating memory reads.

Suggested reviewers

• tomusdrw
• mateuszsikora
• DrEverr

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: adding getPagePointer to enable zero-copy memory reads from JS, which matches the primary objective of the PR.
Description check	✅ Passed	The description is directly related to the changeset, referencing issue #113 and explaining the implementation of zero-copy memory reads via page pointers.
Linked Issues check	✅ Passed	The PR fully implements the requirements from issue #113: adds getPagePointer functions to enable WASM to return memory pointers for already-allocated pages, allowing JS to read memory without additional WASM allocations.
Out of Scope Changes check	✅ Passed	All changes are in scope. The PR adds getPagePointer implementations in multiple files (api-debugger.ts, api-utils.ts, memory.ts), corresponding tests, and a minor helper method in test.ts for assertion validation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@assembly/memory.test.ts`:
- Around line 242-285: Add a test that covers the branch where a page exists in
the pages map but lacks read permission: use MemoryBuilder.setData with
Access.None at RESERVED_MEMORY to allocate a page with no read access, build the
Memory via new MemoryBuilder().build(), compute pageIndex as RESERVED_MEMORY >>
PAGE_SIZE_SHIFT, call getPagePointer(pageIndex) and assert it equals <usize>0;
this targets the !page.can(Access.Read) branch in getPagePointer.
- Around line 260-273: Rename the test case to match its setup and assertion:
update the test name string in the test that constructs a MemoryBuilder, calls
builder.setData(Access.Read, pageAddress, ...), builds mem, computes pageIndex
and calls mem.getPagePointer(pageIndex) so it reflects that this is verifying a
read-only (or readable) page returns a non-zero pointer (e.g. "getPagePointer
returns non-zero for read-only page"); leave the body and assertion
(assert.isNotEqual(ptr, <usize>0)) unchanged and only change the test name
string to match the intent.

In `@assembly/memory.ts`:
- Around line 132-145: The JS examples in the JSDoc use the signed right-shift
operator (address >> PAGE_SIZE_SHIFT) which yields negative page indices for
addresses >= 0x80000000; update these to the unsigned right-shift (address >>>
PAGE_SIZE_SHIFT) in the snippet in assembly/memory.ts and the equivalent JSDoc
snippets for pvmGetPagePointer (assembly/api-utils.ts) and getPagePointer
(assembly/api-debugger.ts) so page calculations are correct across the full
32-bit address space.

[tomusdrw]

<3

[MaciejBaj]

paiechali

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@assembly/memory.test.ts`:
- Line 301: The assertion uses redundant pointer arithmetic in the test: replace
load<u8>(ptr + 0) with load<u8>(ptr) to remove the unnecessary "+ 0" noise;
update the assertion in assembly/memory.test.ts where the variable ptr and the
call to load<u8> are used so the message and behavior remain the same but the
expression is simplified.

---

Duplicate comments:
In `@assembly/memory.test.ts`:
- Around line 242-259: Add a test that covers the branch where a page exists but
is not readable: use MemoryBuilder to build a Memory, create/insert a Page entry
into the Memory.pages map at a non-reserved index with Access.None (so
page.can(Access.Read) returns false), then call Memory.getPagePointer(pageIndex)
and assert it returns <usize>0; reference MemoryBuilder, Memory.getPagePointer,
the pages map, page.can, and Access.None to locate the code to modify.