Add captured-data React hydration and browser helpers

.github/workflows/ci.yml

@@ -1,5 +1,8 @@
 name: CI
 
+# Framework compatibility is local-only and must never run in any CI job.
+# Do not restore frameworks.yml. See tests/Frameworks/README.md.
+
 on:
   push:
     branches: [main]

.github/workflows/jsx.yml

@@ -11,6 +11,7 @@ on:
     branches: [main]
     paths:
       - 'src/**'
+      - 'browser/**'
       - 'tests/Jsx/**'
       - 'phpunit.xml.dist'
       - 'composer.json'
@@ -20,6 +21,7 @@ on:
     branches: [main]
     paths:
       - 'src/**'
+      - 'browser/**'
       - 'tests/Jsx/**'
       - 'phpunit.xml.dist'
       - 'composer.json'
@@ -89,3 +91,37 @@ jobs:
         env:
           TZ: UTC
         run: node tests/Jsx/oracle/hydrate.mjs
+
+      - name: Qualify the Composer hydration consumer
+        run: node tests/Jsx/oracle/hydration-contract.mjs
+
+  hydration-runtime:
+    name: Hydration runtime PHP ${{ matrix.php }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        php: ['8.2', '8.3', '8.4']
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: mbstring, bcmath, intl, curl
+          coverage: none
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: tests/Jsx/oracle/package-lock.json
+
+      - name: Install the pinned browser toolchain
+        working-directory: tests/Jsx/oracle
+        run: npm ci --no-audit --no-fund
+
+      # Only the downstream runtime is installed. PHPUnit requires newer PHP
+      # than our supported library minimum and is not a runtime dependency.
+      - name: Qualify the Composer hydration consumer
+        run: node tests/Jsx/oracle/hydration-contract.mjs

.github/workflows/release.yml

@@ -1,5 +1,8 @@
 name: Release
 
+# Framework compatibility must never run in CI and is not a release gate.
+# See tests/Frameworks/README.md for the owner's local-only policy.
+
 on:
   release:
     types: [published]
@@ -13,34 +16,29 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.release.tag_name }}
 
       - uses: shivammathur/setup-php@v2
         with:
           php-version: '8.4'
           extensions: mbstring, bcmath, curl, intl
           tools: composer
 
-      - run: composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader
+      - name: Stage the canonical runtime archive
+        run: |
+          mkdir -p dist/phasis
+          git archive HEAD | tar -x -C dist/phasis
+          composer install --working-dir=dist/phasis --no-dev --no-interaction --prefer-dist --optimize-autoloader
 
       - name: Verify autoloader
         run: |
+          cd dist/phasis
           php -r "require 'vendor/autoload.php'; class_exists('Phasis\\Engine', true) || exit(1); echo 'Autoloader OK';"
           php bin/phasis -e 'console.log(1 + 1)' | grep -q '^2$'
 
       - name: Create release archive
         run: |
-          mkdir -p dist
-          rsync -a --exclude='.git' --exclude='.github' --exclude='.claude' \
-            --exclude='.compat-state' --exclude='.phpunit*' --exclude='.phpstan*' \
-            --exclude='tests' --exclude='test262' --exclude='scenarios' \
-            --exclude='bench' --exclude='docs' --exclude='prds' \
-            --exclude='AGENTS.md' --exclude='CLAUDE.md' --exclude='BENCH.md' --exclude='bench.json' \
-            --exclude='compat.json' --exclude='phpunit.xml*' --exclude='phpcs.xml' \
-            --exclude='phpstan.neon*' \
-            --exclude='bin/compat-*' --exclude='bin/build-*' --exclude='bin/gen-*' \
-            --exclude='bin/test-regression' --exclude='bin/test262' \
-            --exclude='bin/verify-all' \
-            . dist/phasis/
           cd dist && zip -r ../phasis.zip phasis/
 
       - name: Upload release asset

AGENTS.md

@@ -15,9 +15,13 @@ run test oracles, but must never become an execution backend. Explicit
 through `process.execPath` runs the Phasis PHP entry point. New host resources
 must register cleanup with their owning NodeRuntime. Keep original framework
 assertions, report all discovered cases and upstream skips, and retain source
-identity for complete-run claims. Express and Hono support is experimental;
-their CI runners explicitly use `--timeout-scale 10` while performance work is
-deferred. Preserve original timeout values and record effective limits in the
+identity for complete-run claims. Express and Hono support is experimental.
+Framework compatibility suites are local-only and must NEVER run in CI,
+including manual workflow dispatches, pull requests, pushes or release gates.
+Do not restore the removed `frameworks.yml` workflow or dispatch old revisions.
+The owner's 2026-10-25 decision explicitly permits releases without this suite.
+See [the framework policy](tests/Frameworks/README.md). Preserve original
+timeout values and record effective limits in the
 results; a scaled run is a functional compatibility result, not a claim to meet
 upstream performance deadlines. Never relax test262 assertions, coverage or
 timeouts to accommodate framework workloads. Close and reap owned test

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-10-25
+
+### Added
+- `Engine::renderForHydration()` captures public JSON-data props before module execution and returns immutable matched React HTML, script-safe state and root metadata, without changing the existing rendering or callable interop APIs.
+- Explicit hydration entry/build/root identities, named exports, React `createElement` semantics and matching `identifierPrefix` forwarding to native Fizz and the browser.
+- Composer-shipped `browser/hydrate.mjs` and TypeScript declarations. The helper uses the consumer's peer React/React DOM pair, validates the captured transport and identities, rejects duplicate initialization, and preserves server HTML on transport failure.
+- Downstream Composer archive tests covering development/production hydration, node reuse, connected imports/context/state, render-time mutation, safe data shapes and real React diagnostics on PHP 8.2 through 8.5.
+
+### Changed
+- Release download archives use the same export-ignore runtime inventory as Composer before installing their bundled production autoloader.
+- Framework compatibility is local-only and must never run in CI or gate a release. Its GitHub Actions workflow is removed and disabled.
+
+### Fixed
+- Captured data preserves all public JSON keys, including names resembling native slots and leading null bytes. Native metadata readers keep those objects unbranded, so a public `[[PrimitiveValue]]` key cannot make them behave as boxed values.
+
+### Upgrade notes
+- The new helper targets React/React DOM 19.3.1 and element roots. Full-document convenience transport and renderer nonce/CSP options are explicitly unsupported; existing document rendering remains available through `render()`.
+- Only public data belongs in hydration props. Larger exact integers must be strings. WordPress loaders, application context, asset identities and cache policy remain the embedding application's responsibility.
+
 ## [0.9.0] - 2026-10-24
 
 ### Added