From a9dda975424313ac2c4fd41fd54f7e67881925ba Mon Sep 17 00:00:00 2001
From: Chris Huber <chubes@extrachill.com>
Date: Sat, 27 Jun 2026 21:04:03 -0400
Subject: [PATCH] Add generic runtime-island package producer to
 php-transformer

Adds RuntimeIslandPackageBuilder: a generic, product-neutral producer that
projects compiled-site runtime-island metadata into an actionable carry-forward
envelope (schema blocks-engine/php-transformer/runtime-island-package/v1). Per
preserved island it carries a stable id, the verbatim source markup, the
associated script assets (external src + scoped inline JS, resolved against the
artifact), a generic enqueue handle hint, a preserve-vs-rebuild signal, and a
role classification so telemetry/analytics scripts are dropped rather than
carried. Wired into ArtifactCompiler::compile() alongside the existing
runtime_islands report; emitted only when islands exist.

Preserve-vs-rebuild (#224): runtime islands carry verbatim markup, so their JS
may be carried verbatim (js_handling=preserve_verbatim). Transformed regions are
not islands and never reach this package. Telemetry scripts get disposition=drop
and per-script droppable=true.

Upstream fix: inline <script> islands carried no JS because safeFallbackHtml()
strips script bodies from source_snippet. FallbackEmitter::captureScriptFallback
now preserves the bounded verbatim inline body on the script island
(script_body/body_bytes/body_truncated), mirroring how template islands carry
template_body, so inline script islands are no longer lossy.

The package is intentionally product-neutral: it names no consumer, plugin, or
host product. A downstream consumer maps it to its own materialization payload.

Adds a contract fixture (tests/fixtures/contract/runtime-island-package.json)
and contract-test coverage for the three representative island shapes: a
verbatim-preserved first-party inline script island, a dropped telemetry
external script, and a canvas island carrying both an external (materialized)
and an inline script. composer test + composer parity green (128 parity
fixtures).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/ArtifactCompiler/ArtifactCompiler.php |   4 +
 .../RuntimeIslandPackageBuilder.php           | 393 ++++++++++++++++++
 .../Diagnostics/FallbackEmitter.php           |  18 +-
 php-transformer/tests/contract/run.php        |  91 ++++
 .../contract/runtime-island-package.json      |  68 +++
 5 files changed, 571 insertions(+), 3 deletions(-)
 create mode 100644 php-transformer/src/ArtifactCompiler/RuntimeIslandPackageBuilder.php
 create mode 100644 php-transformer/tests/fixtures/contract/runtime-island-package.json

diff --git a/php-transformer/src/ArtifactCompiler/ArtifactCompiler.php b/php-transformer/src/ArtifactCompiler/ArtifactCompiler.php
index b26e0537..bffb9c4d 100644
--- a/php-transformer/src/ArtifactCompiler/ArtifactCompiler.php
+++ b/php-transformer/src/ArtifactCompiler/ArtifactCompiler.php
@@ -83,6 +83,10 @@ public function compile(array $artifact): TransformerResult
         $sourceReports['runtime_dependency_parity'] = ( new RuntimeDependencyParityReport() )->fromArtifact($normalized['files'], $html, $serializedBlocks, $entryPath, $entryBlocks['runtime_islands'], $referenceReports['asset_references'], $entryBlocks['interaction_candidates']);
         if ( array() !== $entryBlocks['runtime_islands'] ) {
             $sourceReports['runtime_islands'] = $entryBlocks['runtime_islands'];
+            $runtimeIslandPackage = ( new RuntimeIslandPackageBuilder() )->fromRuntimeIslands($entryBlocks['runtime_islands'], $normalized['files'], $entryPath);
+            if ( array() !== $runtimeIslandPackage ) {
+                $sourceReports['runtime_island_package'] = $runtimeIslandPackage;
+            }
         }
         $provenance = array(
             array(
diff --git a/php-transformer/src/ArtifactCompiler/RuntimeIslandPackageBuilder.php b/php-transformer/src/ArtifactCompiler/RuntimeIslandPackageBuilder.php
new file mode 100644
index 00000000..b613bde5
--- /dev/null
+++ b/php-transformer/src/ArtifactCompiler/RuntimeIslandPackageBuilder.php
@@ -0,0 +1,393 @@
+<?php
+declare(strict_types=1);
+
+namespace Automattic\BlocksEngine\PhpTransformer\ArtifactCompiler;
+
+use Automattic\BlocksEngine\PhpTransformer\Path\ArtifactPath;
+
+/**
+ * Generic, product-neutral producer for the runtime-island package.
+ *
+ * The HTML transformer preserves DOM regions it cannot losslessly convert to
+ * native blocks as "runtime islands" — verbatim source markup plus the script
+ * assets and behavior metadata that drive them (see
+ * {@see \Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Diagnostics\FallbackEmitter}).
+ * That data is preserved as measurement/diagnostic metadata; nothing packages it
+ * into an actionable carry-forward envelope.
+ *
+ * This class is that seam. It projects the compiled-site runtime-island data
+ * into a generic package a downstream materializer can map to its own runtime:
+ * per island it carries a stable id, the verbatim markup, the associated script
+ * assets (external src + scoped inline JS), a preserve-vs-rebuild signal, and a
+ * role classification so telemetry scripts can be dropped rather than carried.
+ *
+ * Boundary: this package is intentionally product-neutral. It names no consumer,
+ * no plugin, no host product. A downstream consumer maps this generic data to its
+ * own materialization payload — per-block render + scoped script enqueue — on its
+ * own side. Keeping product semantics out of the engine is a hard rule.
+ *
+ * Preserve-vs-rebuild (blocks-engine #224): runtime islands carry verbatim source
+ * markup, so the JS associated with them may be carried verbatim too
+ * (`js_handling = preserve_verbatim`). Transformed regions are NOT islands — they
+ * became native blocks and their original JS is dropped by the transformer — so
+ * they never reach this package. Telemetry/analytics scripts are classified by
+ * role and marked droppable: their disposition is `drop`, not `preserve`.
+ */
+final class RuntimeIslandPackageBuilder
+{
+    public const SCHEMA = 'blocks-engine/php-transformer/runtime-island-package/v1';
+
+    /**
+     * Generic third-party telemetry/analytics signals. Matched against script
+     * src and inline body so analytics beacons can be dropped rather than carried
+     * into the materialized site. These are generic vendor signals, not
+     * host-product names.
+     *
+     * @var array<int, string>
+     */
+    private const TELEMETRY_SIGNALS = array(
+        'googletagmanager',
+        'google-analytics',
+        'gtag',
+        'gtm.js',
+        'analytics.js',
+        'ga.js',
+        'doubleclick',
+        'segment.com',
+        'segment.io',
+        'mixpanel',
+        'hotjar',
+        'fullstory',
+        'amplitude',
+        'plausible',
+        'matomo',
+        'piwik',
+        'fbevents',
+        'facebook.net',
+        'fbq(',
+        'clarity.ms',
+        'newrelic',
+        'nr-data',
+        'rum',
+        'sentry',
+        'datadog',
+        'cdn.heapanalytics',
+    );
+
+    /**
+     * Build the runtime-island package from preserved runtime-island metadata.
+     *
+     * @param array<int, array<string, mixed>> $runtimeIslands Preserved islands from the compiled result.
+     * @param array<int, array<string, mixed>> $files          Normalized artifact files (resolve external scripts).
+     * @param string                           $sourcePath     Source document path (resolve relative script src).
+     * @return array<string, mixed> Empty array when there are no runtime islands.
+     */
+    public function fromRuntimeIslands(array $runtimeIslands, array $files = array(), string $sourcePath = ''): array
+    {
+        $islands = array();
+        foreach ( $runtimeIslands as $runtimeIsland ) {
+            if ( ! is_array($runtimeIsland) ) {
+                continue;
+            }
+            $island = $this->buildIsland($runtimeIsland, $files, $sourcePath);
+            if ( array() !== $island ) {
+                $islands[] = $island;
+            }
+        }
+
+        if ( array() === $islands ) {
+            return array();
+        }
+
+        return array(
+            'schema'  => self::SCHEMA,
+            'islands' => $islands,
+            'totals'  => $this->totals($islands),
+        );
+    }
+
+    /**
+     * @param array<string, mixed>             $runtimeIsland One preserved runtime island.
+     * @param array<int, array<string, mixed>> $files
+     * @return array<string, mixed>
+     */
+    private function buildIsland(array $runtimeIsland, array $files, string $sourcePath): array
+    {
+        $kind = is_scalar($runtimeIsland['kind'] ?? null) ? (string) $runtimeIsland['kind'] : '';
+        $selector = is_scalar($runtimeIsland['selector'] ?? null) ? (string) $runtimeIsland['selector'] : '';
+        $markup = is_scalar($runtimeIsland['source_snippet'] ?? null) ? (string) $runtimeIsland['source_snippet'] : '';
+        if ( '' === $kind && '' === $selector && '' === $markup ) {
+            return array();
+        }
+
+        $scripts = $this->scriptsForIsland($kind, $runtimeIsland, $files, $sourcePath);
+        $disposition = $this->disposition($kind, $scripts);
+
+        $island = array(
+            'id'                  => $this->islandId($kind, $selector, $markup),
+            'kind'                => $kind,
+            'selector'            => $selector,
+            'tag'                 => is_scalar($runtimeIsland['tag'] ?? null) ? (string) $runtimeIsland['tag'] : '',
+            'markup'              => $markup,
+            'markup_truncated'    => (bool) ($runtimeIsland['source_truncated'] ?? false),
+            'markup_fidelity'     => 'verbatim',
+            'preservation_reason' => is_scalar($runtimeIsland['preservation_reason'] ?? null) ? (string) $runtimeIsland['preservation_reason'] : '',
+            'runtime_requirement' => is_scalar($runtimeIsland['runtime_requirement'] ?? null) ? (string) $runtimeIsland['runtime_requirement'] : '',
+            'disposition'         => $disposition,
+            'js_handling'         => 'drop' === $disposition ? 'drop' : 'preserve_verbatim',
+            'handle_hint'         => $this->handleHint($kind, $selector, $markup),
+            'attributes'          => is_array($runtimeIsland['attributes'] ?? null) ? $runtimeIsland['attributes'] : array(),
+            'scripts'             => $scripts,
+        );
+
+        return array_filter($island, static fn (mixed $value): bool => '' !== $value && array() !== $value || is_bool($value));
+    }
+
+    /**
+     * Resolve the script assets associated with an island.
+     *
+     * For a `script` island the island element IS the script — one entry built
+     * from its attributes (external src) and verbatim inline body. For other
+     * island kinds (canvas, form, template, control, ...) the associated scripts
+     * are the transformer-recorded `required_scripts` references.
+     *
+     * @param array<string, mixed>             $runtimeIsland
+     * @param array<int, array<string, mixed>> $files
+     * @return array<int, array<string, mixed>>
+     */
+    private function scriptsForIsland(string $kind, array $runtimeIsland, array $files, string $sourcePath): array
+    {
+        $scripts = array();
+
+        if ( 'script' === $kind ) {
+            $attributes = is_array($runtimeIsland['attributes'] ?? null) ? $runtimeIsland['attributes'] : array();
+            $sourceKind = is_scalar($runtimeIsland['script_source_kind'] ?? null) ? (string) $runtimeIsland['script_source_kind'] : '';
+            if ( '' === $sourceKind ) {
+                $sourceKind = '' !== trim((string) ($attributes['src'] ?? '')) ? 'external' : 'inline';
+            }
+            $scriptRole = is_scalar($runtimeIsland['script_role'] ?? null) ? (string) $runtimeIsland['script_role'] : 'runtime';
+            $inline = '';
+            if ( 'inline' === $sourceKind ) {
+                // The island carries the verbatim inline body directly (see
+                // FallbackEmitter::captureScriptFallback); fall back to parsing
+                // the bounded snippet only if an older island shape omits it.
+                $inline = is_scalar($runtimeIsland['script_body'] ?? null) ? trim((string) $runtimeIsland['script_body']) : '';
+                if ( '' === $inline ) {
+                    $inline = $this->inlineScriptBody((string) ($runtimeIsland['source_snippet'] ?? ''));
+                }
+            }
+
+            $scripts[] = $this->buildScript($sourceKind, $attributes, $scriptRole, $inline, $files, $sourcePath);
+
+            return $this->dedupeRows($scripts);
+        }
+
+        $required = is_array($runtimeIsland['required_scripts'] ?? null) ? $runtimeIsland['required_scripts'] : array();
+        foreach ( $required as $requiredScript ) {
+            if ( ! is_array($requiredScript) ) {
+                continue;
+            }
+            $attributes = is_array($requiredScript['attributes'] ?? null) ? $requiredScript['attributes'] : array();
+            $sourceKind = is_scalar($requiredScript['script_source_kind'] ?? null) ? (string) $requiredScript['script_source_kind'] : '';
+            if ( '' === $sourceKind ) {
+                $sourceKind = '' !== trim((string) ($attributes['src'] ?? '')) ? 'external' : 'inline';
+            }
+            $scriptRole = is_scalar($requiredScript['script_role'] ?? null) ? (string) $requiredScript['script_role'] : 'runtime';
+            $scripts[] = $this->buildScript($sourceKind, $attributes, $scriptRole, '', $files, $sourcePath);
+        }
+
+        return $this->dedupeRows($scripts);
+    }
+
+    /**
+     * @param array<string, mixed>             $attributes
+     * @param array<int, array<string, mixed>> $files
+     * @return array<string, mixed>
+     */
+    private function buildScript(string $sourceKind, array $attributes, string $scriptRole, string $inline, array $files, string $sourcePath): array
+    {
+        $src = trim((string) ($attributes['src'] ?? ''));
+        $script = array(
+            'source_kind' => '' !== $sourceKind ? $sourceKind : ('' !== $src ? 'external' : 'inline'),
+            'script_role' => '' !== $scriptRole ? $scriptRole : 'runtime',
+            'attributes'  => $attributes,
+        );
+
+        if ( 'external' === $script['source_kind'] && '' !== $src ) {
+            $script['src'] = $src;
+            $resolved = ArtifactPath::resolveRelativePath($src, $sourcePath);
+            $content = $this->externalScriptContent($src, $resolved, $files);
+            if ( '' !== $resolved ) {
+                $script['resolved_path'] = $resolved;
+            }
+            $script['materialized'] = null !== $content;
+            if ( null !== $content ) {
+                $script['content'] = $content;
+            }
+        } elseif ( '' !== $inline ) {
+            $script['content'] = $inline;
+        }
+
+        $role = $this->scriptRole($scriptRole, $src, (string) ($script['content'] ?? ''));
+        $script['role'] = $role;
+        if ( 'telemetry' === $role ) {
+            $script['droppable'] = true;
+        }
+
+        return array_filter($script, static fn (mixed $value): bool => '' !== $value && array() !== $value || is_bool($value));
+    }
+
+    /**
+     * Locate the verbatim content of an external script that was materialized as
+     * an artifact file. Returns null when the script is third-party / not carried
+     * (so the consumer knows to reference the original src instead of inlining).
+     *
+     * @param array<int, array<string, mixed>> $files
+     */
+    private function externalScriptContent(string $src, string $resolved, array $files): ?string
+    {
+        $candidates = array_filter(array($resolved, ltrim($src, '/')), static fn (string $value): bool => '' !== $value);
+        foreach ( $files as $file ) {
+            if ( ! is_array($file) || ! empty($file['binary']) ) {
+                continue;
+            }
+            $path = is_scalar($file['path'] ?? null) ? (string) $file['path'] : '';
+            if ( '' === $path || ! in_array($path, $candidates, true) ) {
+                continue;
+            }
+            if ( is_scalar($file['content'] ?? null) ) {
+                return (string) $file['content'];
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Extract the verbatim inline JS body from a bounded `<script>` snippet. When
+     * the snippet was truncated the closing tag may be absent, so fall back to
+     * everything after the opening tag.
+     */
+    private function inlineScriptBody(string $snippet): string
+    {
+        if ( 1 === preg_match('/<script\b[^>]*>(.*)<\/script>/is', $snippet, $matches) ) {
+            return trim((string) $matches[1]);
+        }
+        if ( 1 === preg_match('/<script\b[^>]*>(.*)$/is', $snippet, $matches) ) {
+            return trim((string) $matches[1]);
+        }
+
+        return '';
+    }
+
+    /**
+     * Classify a script's role so telemetry can be dropped. `data` scripts
+     * (JSON-LD, importmap, speculation rules) carried by the transformer keep
+     * their data role; everything else is first-party unless it matches a generic
+     * telemetry signal.
+     */
+    private function scriptRole(string $scriptRole, string $src, string $content): string
+    {
+        if ( 'data' === $scriptRole ) {
+            return 'data';
+        }
+
+        $haystack = strtolower($src . "\n" . substr($content, 0, 4000));
+        foreach ( self::TELEMETRY_SIGNALS as $signal ) {
+            if ( str_contains($haystack, $signal) ) {
+                return 'telemetry';
+            }
+        }
+
+        return 'first_party';
+    }
+
+    /**
+     * The island disposition: drop a telemetry-only `script` island, otherwise
+     * preserve the verbatim island. Non-script islands always preserve their
+     * markup; their individual telemetry scripts are marked droppable per entry.
+     *
+     * @param array<int, array<string, mixed>> $scripts
+     */
+    private function disposition(string $kind, array $scripts): string
+    {
+        if ( 'script' === $kind && array() !== $scripts ) {
+            foreach ( $scripts as $script ) {
+                if ( 'telemetry' !== ($script['role'] ?? '') ) {
+                    return 'preserve';
+                }
+            }
+
+            return 'drop';
+        }
+
+        return 'preserve';
+    }
+
+    /**
+     * Stable, content-addressed island id so a consumer can key per-island state
+     * deterministically across runs.
+     */
+    private function islandId(string $kind, string $selector, string $markup): string
+    {
+        return 'island_' . substr(hash('sha256', $kind . '|' . $selector . '|' . $markup), 0, 16);
+    }
+
+    /**
+     * Stable generic enqueue-handle hint so a consumer can name a scoped script
+     * deterministically without inventing a scheme. Product-neutral.
+     */
+    private function handleHint(string $kind, string $selector, string $markup): string
+    {
+        return 'runtime-island-' . substr(hash('sha256', $kind . '|' . $selector . '|' . $markup), 0, 12);
+    }
+
+    /**
+     * @param array<int, array<string, mixed>> $islands
+     * @return array<string, mixed>
+     */
+    private function totals(array $islands): array
+    {
+        $byDisposition = array();
+        $byKind = array();
+        foreach ( $islands as $island ) {
+            $disposition = (string) ($island['disposition'] ?? '');
+            if ( '' !== $disposition ) {
+                $byDisposition[$disposition] = ($byDisposition[$disposition] ?? 0) + 1;
+            }
+            $kind = (string) ($island['kind'] ?? '');
+            if ( '' !== $kind ) {
+                $byKind[$kind] = ($byKind[$kind] ?? 0) + 1;
+            }
+        }
+
+        return array_filter(
+            array(
+                'islands'         => count($islands),
+                'by_disposition'  => $byDisposition,
+                'by_kind'         => $byKind,
+            ),
+            static fn (mixed $value): bool => 0 !== $value && array() !== $value
+        );
+    }
+
+    /**
+     * @param array<int, array<string, mixed>> $rows
+     * @return array<int, array<string, mixed>>
+     */
+    private function dedupeRows(array $rows): array
+    {
+        $seen = array();
+        $deduped = array();
+        foreach ( $rows as $row ) {
+            $key = json_encode($row, JSON_UNESCAPED_SLASHES);
+            if ( ! is_string($key) || isset($seen[$key]) ) {
+                continue;
+            }
+            $seen[$key] = true;
+            $deduped[] = $row;
+        }
+
+        return $deduped;
+    }
+}
diff --git a/php-transformer/src/HtmlToBlocks/Diagnostics/FallbackEmitter.php b/php-transformer/src/HtmlToBlocks/Diagnostics/FallbackEmitter.php
index 1362df5a..9ee67c4e 100644
--- a/php-transformer/src/HtmlToBlocks/Diagnostics/FallbackEmitter.php
+++ b/php-transformer/src/HtmlToBlocks/Diagnostics/FallbackEmitter.php
@@ -176,11 +176,23 @@ public function captureScriptFallback(DOMElement $element, array &$fallbacks, ar
         $boundedHtml = $this->boundedFallbackHtml($this->safeFallbackHtml($element));
         $boundedBody = $this->boundedFallbackText(trim($element->textContent ?? ''));
         $scriptRole = $this->scriptRole($element);
-        $this->recordRuntimeIsland($element, 'script', 'script_requires_runtime', 'client_script_execution', array(
+        $scriptSourceKind = '' !== trim($this->attr($element, 'src')) ? 'external' : 'inline';
+        $scriptIslandMetadata = array(
             'attributes'         => $this->safeScriptAttributes($element),
             'script_role'        => $scriptRole,
-            'script_source_kind' => '' !== trim($this->attr($element, 'src')) ? 'external' : 'inline',
-        ), $runtimeIslands);
+            'script_source_kind' => $scriptSourceKind,
+        );
+        if ( 'inline' === $scriptSourceKind ) {
+            // safeFallbackHtml() strips <script> bodies from source_snippet for
+            // safety, so an inline script island would otherwise carry no JS.
+            // Preserve the verbatim inline body (bounded) so a downstream
+            // consumer can carry the script forward (issue #224: verbatim JS on
+            // verbatim island markup).
+            $scriptIslandMetadata['script_body']    = $boundedBody['text'];
+            $scriptIslandMetadata['body_bytes']     = $boundedBody['bytes'];
+            $scriptIslandMetadata['body_truncated'] = $boundedBody['truncated'];
+        }
+        $this->recordRuntimeIsland($element, 'script', 'script_requires_runtime', 'client_script_execution', $scriptIslandMetadata, $runtimeIslands);
         $fallbacks[] = FallbackDiagnostic::build(array(
             'type'            => 'html',
             'reason'          => 'script_requires_runtime',
diff --git a/php-transformer/tests/contract/run.php b/php-transformer/tests/contract/run.php
index bb97eeea..5fab8848 100644
--- a/php-transformer/tests/contract/run.php
+++ b/php-transformer/tests/contract/run.php
@@ -1844,6 +1844,97 @@ public function match(DOMElement $element, PatternContext $context): ?array
 )->toArray();
 $assert(! array_key_exists('companion_plugin_payload', $companionAbsent['source_reports']), 'companion_plugin_payload is absent when no generated blocks exist');
 
+// Runtime-island package producer (issue #491 slice 2): preserved runtime
+// islands are packaged into a generic, product-neutral envelope a downstream
+// materializer maps to its own runtime. The package names no host product.
+$runtimeIslandPackageBuilder = new \Automattic\BlocksEngine\PhpTransformer\ArtifactCompiler\RuntimeIslandPackageBuilder();
+$assert('blocks-engine/php-transformer/runtime-island-package/v1' === \Automattic\BlocksEngine\PhpTransformer\ArtifactCompiler\RuntimeIslandPackageBuilder::SCHEMA, 'runtime-island package uses a generic, product-neutral schema');
+$assert(! str_contains(strtolower(\Automattic\BlocksEngine\PhpTransformer\ArtifactCompiler\RuntimeIslandPackageBuilder::SCHEMA), 'static-site') && ! str_contains(strtolower(\Automattic\BlocksEngine\PhpTransformer\ArtifactCompiler\RuntimeIslandPackageBuilder::SCHEMA), 'companion'), 'runtime-island package schema carries no consumer/product name');
+$assert(array() === $runtimeIslandPackageBuilder->fromRuntimeIslands(array()), 'runtime-island package is empty when there are no islands');
+
+$runtimeIslandFixture = json_decode((string) file_get_contents(dirname(__DIR__) . '/fixtures/contract/runtime-island-package.json'), true);
+$assert('blocks-engine/php-transformer/runtime-island-package-fixture/v1' === ($runtimeIslandFixture['schema'] ?? ''), 'runtime-island package fixture exposes its schema');
+
+$findIslandByKind = static function (array $package, string $kind): array {
+    foreach ( $package['islands'] ?? array() as $island ) {
+        if ( ($island['kind'] ?? '') === $kind ) {
+            return $island;
+        }
+    }
+    return array();
+};
+$findIslandByScriptRole = static function (array $package, string $role, string $kind = ''): array {
+    foreach ( $package['islands'] ?? array() as $island ) {
+        if ( '' !== $kind && ($island['kind'] ?? '') !== $kind ) {
+            continue;
+        }
+        foreach ( $island['scripts'] ?? array() as $script ) {
+            if ( ($script['role'] ?? '') === $role ) {
+                return $island;
+            }
+        }
+    }
+    return array();
+};
+
+foreach ( $runtimeIslandFixture['cases'] as $runtimeIslandCase ) {
+    $caseName = (string) ($runtimeIslandCase['name'] ?? '');
+    $compiled = $compiler->compile($runtimeIslandCase['artifact'])->toArray();
+    $package = $compiled['source_reports']['runtime_island_package'] ?? array();
+    $assert(is_array($package) && array() !== $package, 'runtime-island package is produced for fixture case ' . $caseName);
+    $assert('blocks-engine/php-transformer/runtime-island-package/v1' === ($package['schema'] ?? ''), 'runtime-island package stamps the generic schema for case ' . $caseName);
+
+    $expect = $runtimeIslandCase['expect_island'];
+    if ( isset($expect['select_by_role']) ) {
+        $island = $findIslandByScriptRole($package, (string) $expect['select_by_role'], (string) ($expect['kind'] ?? ''));
+    } else {
+        $island = $findIslandByKind($package, (string) ($expect['select_by_kind'] ?? $expect['kind']));
+    }
+    $assert(array() !== $island, 'runtime-island package exposes the expected island for case ' . $caseName);
+    $assert(($expect['kind'] ?? null) === ($island['kind'] ?? ''), 'island kind matches for case ' . $caseName);
+    $assert(($expect['disposition'] ?? null) === ($island['disposition'] ?? ''), 'island disposition matches for case ' . $caseName);
+    $assert(($expect['js_handling'] ?? null) === ($island['js_handling'] ?? ''), 'island js_handling matches for case ' . $caseName);
+    $assert(($expect['markup_fidelity'] ?? null) === ($island['markup_fidelity'] ?? ''), 'island markup is tagged verbatim for case ' . $caseName);
+    $assert(isset($island['id']) && str_starts_with((string) $island['id'], 'island_'), 'island exposes a stable id for case ' . $caseName);
+    $assert(isset($island['handle_hint']) && str_starts_with((string) $island['handle_hint'], 'runtime-island-'), 'island exposes a generic enqueue handle hint for case ' . $caseName);
+
+    if ( isset($expect['markup_contains']) ) {
+        $assert(str_contains((string) ($island['markup'] ?? ''), (string) $expect['markup_contains']), 'island carries verbatim markup for case ' . $caseName);
+    }
+
+    if ( isset($expect['script_source_kind']) ) {
+        $script = $island['scripts'][0] ?? array();
+        $assert(($expect['script_source_kind'] ?? null) === ($script['source_kind'] ?? ''), 'island script source kind matches for case ' . $caseName);
+        $assert(($expect['script_role'] ?? null) === ($script['role'] ?? ''), 'island script role classification matches for case ' . $caseName);
+        if ( isset($expect['content_contains']) ) {
+            $assert(str_contains((string) ($script['content'] ?? ''), (string) $expect['content_contains']), 'island preserves verbatim inline JS for case ' . $caseName);
+        }
+        if ( array_key_exists('materialized', $expect) ) {
+            $assert(($expect['materialized']) === ($script['materialized'] ?? null), 'island external script materialization flag matches for case ' . $caseName);
+        }
+        if ( true === ($expect['droppable'] ?? null) ) {
+            $assert(true === ($script['droppable'] ?? null), 'telemetry island script is marked droppable for case ' . $caseName);
+        }
+        if ( false === ($expect['droppable'] ?? null) ) {
+            $assert(! array_key_exists('droppable', $script), 'first-party island script is not marked droppable for case ' . $caseName);
+        }
+    }
+
+    if ( isset($expect['has_external_script']) ) {
+        $externalScripts = array_values(array_filter($island['scripts'] ?? array(), static fn (array $s): bool => 'external' === ($s['source_kind'] ?? '')));
+        $inlineScripts = array_values(array_filter($island['scripts'] ?? array(), static fn (array $s): bool => 'inline' === ($s['source_kind'] ?? '')));
+        $assert(array() !== $externalScripts, 'island carries an external script for case ' . $caseName);
+        $assert(array() !== $inlineScripts, 'island carries an inline script for case ' . $caseName);
+        $external = $externalScripts[0];
+        if ( true === ($expect['external_materialized'] ?? null) ) {
+            $assert(true === ($external['materialized'] ?? null), 'island external script is materialized for case ' . $caseName);
+            $assert(str_contains((string) ($external['content'] ?? ''), (string) ($expect['external_content_contains'] ?? '')), 'island external script carries materialized content for case ' . $caseName);
+        }
+        $firstParty = array_values(array_filter($island['scripts'] ?? array(), static fn (array $s): bool => 'first_party' === ($s['role'] ?? '')));
+        $assert(count($firstParty) >= (int) ($expect['first_party_scripts_min'] ?? 0), 'island carries the expected first-party scripts for case ' . $caseName);
+    }
+}
+
 $normalized = $compiler->compile(
     array(
         'entry'   => 'public/index.html',
diff --git a/php-transformer/tests/fixtures/contract/runtime-island-package.json b/php-transformer/tests/fixtures/contract/runtime-island-package.json
new file mode 100644
index 00000000..ae8df428
--- /dev/null
+++ b/php-transformer/tests/fixtures/contract/runtime-island-package.json
@@ -0,0 +1,68 @@
+{
+  "schema": "blocks-engine/php-transformer/runtime-island-package-fixture/v1",
+  "cases": [
+    {
+      "name": "first-party-inline-script-island",
+      "artifact": {
+        "entrypoint": "index.html",
+        "files": {
+          "index.html": "<main><div id=\"app\">Interactive app</div><script>document.getElementById(\"app\").addEventListener(\"click\", function () { window.toggleApp(); });</script></main>"
+        }
+      },
+      "expect_island": {
+        "kind": "script",
+        "select_by_role": "first_party",
+        "disposition": "preserve",
+        "js_handling": "preserve_verbatim",
+        "markup_fidelity": "verbatim",
+        "script_source_kind": "inline",
+        "script_role": "first_party",
+        "content_contains": "window.toggleApp()",
+        "droppable": false
+      }
+    },
+    {
+      "name": "telemetry-external-script-dropped",
+      "artifact": {
+        "entrypoint": "index.html",
+        "files": {
+          "index.html": "<main><h1>Home</h1><script src=\"https://www.googletagmanager.com/gtag/js?id=GA123\"></script></main>"
+        }
+      },
+      "expect_island": {
+        "kind": "script",
+        "select_by_role": "telemetry",
+        "disposition": "drop",
+        "js_handling": "drop",
+        "markup_fidelity": "verbatim",
+        "script_source_kind": "external",
+        "script_role": "telemetry",
+        "materialized": false,
+        "droppable": true
+      }
+    },
+    {
+      "name": "canvas-island-external-and-inline-scripts",
+      "artifact": {
+        "entrypoint": "index.html",
+        "files": {
+          "index.html": "<main><canvas id=\"chart\" class=\"chart\">fallback</canvas><script src=\"js/chart.js\"></script><script>const ctx = document.getElementById(\"chart\").getContext(\"2d\"); ctx.fillRect(0, 0, 10, 10);</script></main>",
+          "js/chart.js": "const c = document.getElementById(\"chart\").getContext(\"2d\"); c.strokeRect(0, 0, 5, 5);"
+        }
+      },
+      "expect_island": {
+        "kind": "canvas",
+        "select_by_kind": "canvas",
+        "disposition": "preserve",
+        "js_handling": "preserve_verbatim",
+        "markup_fidelity": "verbatim",
+        "markup_contains": "<canvas id=\"chart\"",
+        "has_external_script": true,
+        "external_materialized": true,
+        "external_content_contains": "strokeRect",
+        "has_inline_script": true,
+        "first_party_scripts_min": 2
+      }
+    }
+  ]
+}