doc: update PORTING.md with ported status and experimental API notes

Mark 17 easy js-native-api tests as Ported (test_dataview as Partial due
to missing experimental SharedArrayBuffer APIs in node-api-headers).

Add "Experimental Node-API Features" section documenting which tests
depend on experimental APIs not yet available in node-api-headers, and
the approach needed to support them. References #26.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: kraenhansen

PORTING.md

@@ -41,36 +41,36 @@ Tests covering the engine-specific part of Node-API, defined in `js_native_api.h
 | Directory                    | Status     | Difficulty |
 | ---------------------------- | ---------- | ---------- |
 | `2_function_arguments`       | Ported     | —          |
-| `3_callbacks`                | Not ported | Easy       |
-| `4_object_factory`           | Not ported | Easy       |
-| `5_function_factory`         | Not ported | Easy       |
+| `3_callbacks`                | Ported     | Easy       |
+| `4_object_factory`           | Ported     | Easy       |
+| `5_function_factory`         | Ported     | Easy       |
 | `6_object_wrap`              | Not ported | Medium     |
-| `7_factory_wrap`             | Not ported | Easy       |
-| `8_passing_wrapped`          | Not ported | Easy       |
-| `test_array`                 | Not ported | Easy       |
-| `test_bigint`                | Not ported | Easy       |
+| `7_factory_wrap`             | Ported     | Easy       |
+| `8_passing_wrapped`          | Ported     | Easy       |
+| `test_array`                 | Ported     | Easy       |
+| `test_bigint`                | Ported     | Easy       |
 | `test_cannot_run_js`         | Not ported | Medium     |
 | `test_constructor`           | Not ported | Medium     |
 | `test_conversions`           | Not ported | Medium     |
-| `test_dataview`              | Not ported | Easy       |
-| `test_date`                  | Not ported | Easy       |
+| `test_dataview`              | Partial    | Easy       |
+| `test_date`                  | Ported     | Easy       |
 | `test_error`                 | Not ported | Medium     |
 | `test_exception`             | Not ported | Medium     |
 | `test_finalizer`             | Not ported | Medium     |
 | `test_function`              | Not ported | Medium     |
 | `test_general`               | Not ported | Hard       |
-| `test_handle_scope`          | Not ported | Easy       |
-| `test_instance_data`         | Not ported | Easy       |
-| `test_new_target`            | Not ported | Easy       |
-| `test_number`                | Not ported | Easy       |
+| `test_handle_scope`          | Ported     | Easy       |
+| `test_instance_data`         | Ported     | Easy       |
+| `test_new_target`            | Ported     | Easy       |
+| `test_number`                | Ported     | Easy       |
 | `test_object`                | Not ported | Hard       |
-| `test_promise`               | Not ported | Easy       |
-| `test_properties`            | Not ported | Easy       |
+| `test_promise`               | Ported     | Easy       |
+| `test_properties`            | Ported     | Easy       |
 | `test_reference`             | Not ported | Medium     |
-| `test_reference_double_free` | Not ported | Easy       |
+| `test_reference_double_free` | Ported     | Easy       |
 | `test_sharedarraybuffer`     | Not ported | Medium     |
 | `test_string`                | Not ported | Medium     |
-| `test_symbol`                | Not ported | Easy       |
+| `test_symbol`                | Ported     | Easy       |
 | `test_typedarray`            | Not ported | Medium     |
 
 ## Runtime-specific (`node-api`)
@@ -106,6 +106,33 @@ Tests covering the runtime-specific part of Node-API, defined in `node_api.h`.
 | `test_worker_terminate`              | Not ported | Hard       |
 | `test_worker_terminate_finalization` | Not ported | Hard       |
 
+## Experimental Node-API Features
+
+Several tests in the upstream Node.js repository use experimental APIs that are guarded behind
+`#ifdef NAPI_EXPERIMENTAL` in Node.js's `js_native_api.h`. The `node-api-headers` package (which
+the CTS uses for compilation) does not currently include any of these experimental API declarations.
+
+When `NAPI_EXPERIMENTAL` is defined in Node.js, `NAPI_VERSION` is set to
+`NAPI_VERSION_EXPERIMENTAL (2147483647)`. The `NAPI_MODULE` macro exports this version, and the
+runtime uses it to decide whether to enable experimental behavior for that addon.
+
+| Feature macro | APIs | Used by |
+|---|---|---|
+| `NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER` | `node_api_is_sharedarraybuffer`, `node_api_create_sharedarraybuffer` | `test_dataview`, `test_sharedarraybuffer` |
+| `NODE_API_EXPERIMENTAL_HAS_CREATE_OBJECT_WITH_PROPERTIES` | `node_api_create_object_with_properties` | `test_object` |
+| `NODE_API_EXPERIMENTAL_HAS_SET_PROTOTYPE` | `node_api_set_prototype` | `test_general` |
+| `NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER` | `node_api_post_finalizer` | `test_general`, `test_finalizer`, `6_object_wrap` |
+
+Tests that depend on these APIs are currently ported without the experimental test cases (marked
+as "Partial" in the status column) or not ported at all. To fully support them, the CTS will need:
+
+1. A mechanism for compiling addons with experimental API access (either from updated
+   `node-api-headers`, CTS-provided forward declarations or copies of headers from the Node.js main repository)
+2. A way for implementors to declare which experimental features their runtime supports
+3. Conditional test execution that skips experimental assertions on runtimes that don't support them
+
+See [#26](https://github.com/nodejs/node-api-cts/issues/26) for the full design discussion.
+
 ## Special Considerations
 
 ### `node_api_post_finalizer` (`6_object_wrap`, `test_finalizer`)