perf: offload async API methods to worker threads via spawn_blocking

[Nebu1eto]

Summary

• Convert async API methods to use tokio::task::spawn_blocking() for CPU-heavy work
• Frees the tokio async runtime threads for other concurrent operations
• open(), openBuffer(), openWithPassword() fully offloaded to blocking thread pool
• save(), saveWithPassword() partially offloaded (disk write + encryption on blocking pool)
• writeBuffer() unchanged (requires &self, documenting the limitation)

Changes

• packages/sheetkit/Cargo.toml: Add tokio = { version = "1", features = ["rt"] } direct dependency
• packages/sheetkit/src/lib.rs: Convert 5 async methods to use spawn_blocking
• packages/sheetkit/binding.d.ts: Regenerated with updated doc comments
• packages/sheetkit/__test__/index.spec.ts: 8 new concurrency and correctness tests

Design Decisions

• spawn_blocking over AsyncTask: Simpler, same result (offload to dedicated thread pool)
• No TypeScript changes: napi interface unchanged, wrapper works as-is
• writeBuffer not offloaded: Requires &self reference, cloning Workbook too expensive
• save partial offload: Serialization needs &self, but disk I/O + encryption offloaded

Test plan

• 8 new tests (async open/save/buffer parity, concurrent ops, error propagation)
• 1,956 Rust tests pass
• 494 Node.js tests pass (486 existing + 8 new)
• clippy clean, fmt clean
• Stacked on Phase 3 (Node decode optimization)

🤖 Generated with Claude Code

[claude]

Code Review - CLAUDE.md Compliance Issues

Found 2 issues that should be addressed:

Issue 1: Misleading documentation for writeBuffer()

Location: packages/sheetkit/src/lib.rs:156-162

The doc comment claims serialization "runs on the tokio runtime thread" but the implementation just calls write_buffer_sync() without spawn_blocking().

CLAUDE.md requires: "Doc comments: Describe inputs, behavior, and outputs concisely."

See:

sheetkit/CLAUDE.md

Lines 56 to 57 in c956513

	- Doc comments (`///` for Rust, `/** */` for TypeScript): Describe inputs, behavior, and outputs concisely.
	- Inline comments: Only for complex logic that is not self-evident from the code.

Issue 2: Verbose doc comments with implementation details

Locations: packages/sheetkit/src/lib.rs (multiple methods)

Doc comments include threading implementation details instead of concisely describing behavior. Async methods should follow same concise style as sync equivalents.

Example - compare:

• openSync: "Open an existing .xlsx file from disk."
• open: Has 3 lines explaining worker threads and event loop

CLAUDE.md requires: "Doc comments: Describe inputs, behavior, and outputs concisely."

See:

sheetkit/CLAUDE.md

Lines 56 to 57 in c956513

	- Doc comments (`///` for Rust, `/** */` for TypeScript): Describe inputs, behavior, and outputs concisely.
	- Inline comments: Only for complex logic that is not self-evident from the code.

[Nebu1eto]

P2: Async save now serializes the entire workbook into memory via save_to_buffer() before writing to disk, while saveSync writes directly through the core save path. This changes memory behavior and can significantly increase peak memory / OOM risk for large workbooks.\n\nCould you either document this as an explicit limitation for async save, or redesign the async path to avoid full in-memory buffering?

[Nebu1eto]

I think the new async encrypted-save memory note is still a bit misleading.

saveWithPassword docs currently imply higher peak memory than saveWithPasswordSync, but the sync encrypted path also buffers ZIP data in memory before encrypt/write (see core implementation around save_with_password).

Could we reword this to avoid implying that the sync encrypted path is lower-memory than async for encryption-specific saves?

[Nebu1eto]

The async save memory caveat was added in native binding docs, but the main public wrapper typings are generated from index.ts (types points to index.d.ts).

Could we mirror the same caveat in the index.ts docs for save / saveWithPassword so users see it in the primary API surface as well?