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

@@ -22,36 +22,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`)
@@ -87,6 +87,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`)