figma-transformer: improve FSE responsive parity

docs/contracts/figma-transformer-result.md

@@ -41,6 +41,43 @@ Required parity fields:
 - `diff_summary`: optional compact diff summary such as changed pixels, threshold, or ratio
 - `metrics`: optional runner metrics
 
+## Transform Diagnostics
+
+`source_reports.figma.html.transform_diagnostics` uses schema `blocks-engine/figma-transformer/transform-diagnostics/v1`. It is a development/parity diagnostics envelope, not a rendering contract. It explains source nodes that were decoded but not materially emitted so visual gaps can be triaged without papering over output.
+
+`source_reports.figma.html.visual_node_map` is the aggregate source-to-artifact evidence map. Each emitted visual node entry includes `id`, `rect`, `page_path`, optional `emitted_class`/`emitted_tag`, and multi-page provenance fields `source_page_index` and `source_page_frame_id`. The same traced entries are preserved in each `source_reports.figma.html.pages[].visual_node_map` page report so arbitrary `.fig` scale output can be traced from aggregate JSON to the generated page HTML and shared CSS selector.
+
+Text coverage lives at `transform_diagnostics.text` with schema `blocks-engine/figma-transformer/text-coverage/v1`:
+
+- `decoded_text_node_count`: non-empty decoded text nodes considered for emission.
+- `emitted_text_node_count`: decoded text nodes whose `data-figma-node-id` appears in generated HTML.
+- `missing_emitted_text_node_count`: decoded non-empty text nodes not found in generated HTML.
+- `missing_emitted_text_reason_categories`: stable counts by reason.
+- `missing_emitted_text_nodes[]`: sample nodes with `node_id`, `name`, `type`, `class`, `page_id`, `page_name`, `character_count`, and `reason`.
+
+Asset coverage lives at `transform_diagnostics.images`:
+
+- `node_refs`: raw nodes carrying an explicit asset reference or image paint.
+- `asset_nodes[]`: sample nodes with `node_id`, `name`, `type`, `class`, `emitted`, `reason`, optional `path`, and `refs`.
+- `asset_node_reason_categories`: stable counts by reason.
+- `missing_assets[]`: asset-bearing node samples with no resolved archive asset path.
+
+Initial omission reasons include `hidden`, `zero_area`, `parent_omitted`, `decorative`, `no_archive_asset`, `no_archive_asset_hash`, `clipped_masked`, `converted_to_background`, `converted_to_form_control`, and `not_emitted`.
+
+Positional parity coverage lives at `transform_diagnostics.layout.positional_parity` with schema `blocks-engine/figma-transformer/positional-parity/v1`. It summarizes emitted CSS and layout evidence that can affect arbitrary `.fig` visual parity without changing runtime behavior:
+
+- `full_bleed_viewport_width_count`: emitted `width:100vw` declarations.
+- `full_bleed_breakout_count`: emitted viewport breakout declarations using `left:50%` plus `margin-left:±50vw`.
+- `mirrored_transform_count`: emitted CSS matrix transforms with a negative horizontal or vertical scale component.
+- `reflected_full_bleed_count`: emitted full-bleed reflected nodes using `margin-left:50vw` plus a mirrored matrix.
+- `fixed_over_root_width_underlay_count`: decorative underlay samples whose fixed source width exceeds parent/root width.
+- `fixed_over_root_width_underlays[]`: bounded samples with page, node, parent, geometry, and class evidence.
+- `chrome_overflow_count`: off-canvas visual nodes associated with header/footer chrome.
+- `chrome_overflow_nodes[]`: bounded samples with page, node, parent, geometry, and class evidence.
+- `root_stacking_trace_count`: count of recorded stacking-context decision traces.
+- `root_stacking_reason_counts`: stable stacking/z-index/overlap decision reason counts when present.
+- `decision_trace_samples[]`: bounded positional decision trace samples derived from `decision_traces.samples` for effective geometry, stacking context, transform viewport, and responsive decisions. Samples include stable node/page/class identity plus compact source geometry, emitted CSS geometry, full-bleed/canvas-shell, stacking, transform, or responsive declaration evidence when present.
+
 Status meanings:
 
 - `not_run`: no parity runner has executed for this transform.
@@ -51,6 +88,8 @@ Status meanings:
 
 Arbitrary `.fig` files are not fully decoded by the PHP-native package yet. Current `.fig` support safely opens `.fig` files or wrapper ZIPs, identifies nested `.fig` entries, reports `fig-kiwi` prelude/version/chunk metadata, inventories embedded files/assets, and records compression diagnostics.
 
+The bounded Kiwi skipped-field inventory reports skipped fields in `fields`/`summary` and selected decoded paint-variable/interpolation diagnostics in `decoded_fields`/`decoded_summary`. Decoded paint diagnostics currently cover `Paint.colorVar`, `Paint.stopsVar`, color-stop variable bindings, and gradient interpolation/color-space fields so large real files can be audited without full visual rendering.
+
 Next decoder milestones are schema chunk parsing, Zstandard message decoding when supported by the runtime, mapping decoded Kiwi messages into normalized IR, and expanding layout/paint/text/component/asset coverage against external real-file evidence.
 
 ## Fixture Strategy

figma-transformer/README.md

@@ -104,6 +104,19 @@ add_filter(
 
 No pure-PHP Zstandard decoder is bundled today. Unsupported runtimes report `figma_transformer_zstd_extension_missing` or adapter failure diagnostics and continue parsing the rest of the archive metadata.
 
+### Large `.fig` Memory Profiles
+
+Large production `.fig` exports should default to bounded inspection before full scenegraph materialization. Keep the library defaults conservative: the eager Kiwi message decode limit is 16 MB, the selective decode preflight limit is 32 MB, and the zstd inflated chunk limit is 64 MB. With those defaults, oversized modern Kiwi messages are reported with `figma_transformer_kiwi_message_decode_skipped_preflight` instead of risking a PHP fatal.
+
+Recommended operator profiles:
+
+- Archive/gate inspection: run with `--inspect-kiwi-gate`, `--omit-asset-content` when asset bytes are not needed, and a 512 MB PHP memory limit.
+- Skipped-field inventory: run `scripts/figma-kiwi-skipped-field-inventory.php` with an explicit `--zstd-command` when the host lacks `ext-zstd`; 512 MB is expected to be enough for bounded inventory scans.
+- Parser parity dry run: keep `--max-kiwi-message-decode-bytes=1` for the safe preflight/default path. Raise `--max-kiwi-selective-message-decode-bytes` only for an intentional selective decode experiment on a high-memory worker.
+- Full transform: do not raise `--max-kiwi-selective-message-decode-bytes` for untrusted or fatal-scale files unless the process budget has been measured against that file. `--max-nodes` limits normalized output size, but it does not avoid the current cost of decoding and indexing the source graph.
+
+When a real file exceeds the default selective decode ceiling, prefer `--inspect-kiwi-gate` and skipped-field inventory to identify the page/frame scope before allocating a larger transform worker. Treat memory budgets that finish within a few percent of the configured PHP limit as unsafe defaults; use them only for one-off operator runs.
+
 ## Output Contract
 
 Successful transforms produce a static website artifact:

figma-transformer/bin/figma-transformer

@@ -12,13 +12,14 @@ if ( is_readable($autoload) ) {
 
 $path = $argv[1] ?? '';
 if ( '' === $path || '--help' === $path || '-h' === $path ) {
-    fwrite(STDERR, "Usage: figma-transformer <path-to-fig-or-scenegraph-json> [--inspect-frames[=<limit>]] [--multi-page] [--frame-ids=<id,id>] [--entry-frame-id=<id>] [--max-pages=<count>] [--output-dir=<dir>] [--omit-asset-content] [--max-nodes=<count>] [--max-kiwi-message-decode-bytes=<bytes>] [--zstd-command=<path>] [--frame-id=<id>] [--font-css=<css>] [--font-css-file=<path>] [--font-family-css=<family>:<css>] [--font-family-css-file=<family>:<path>] [--render-text-glyph-paths] [--parity-status=<status>] [--parity-report-path=<path>] [--parity-source-screenshot-url=<url>] [--parity-source-screenshot-path=<path>] [--parity-generated-screenshot-artifact=<artifact>] [--parity-diff-image-artifact=<artifact>] [--parity-pixel-mismatch-count=<count>] [--parity-pixel-mismatch-ratio=<ratio>] [--parity-threshold=<ratio>] [--parity-viewport=<width>x<height>] [--parity-dom-boxes-path=<path>] [--parity-layout-report-path=<path>] [--parity-render-evidence-path=<path>] [--parity-layout-mismatch-count=<count>]\n");
+    fwrite(STDERR, "Usage: figma-transformer <path-to-fig-or-scenegraph-json> [--inspect-frames[=<limit>]] [--inspect-kiwi-gate] [--kiwi-gated-decode] [--multi-page] [--frame-ids=<id,id>] [--entry-frame-id=<id>] [--max-pages=<count>] [--output-dir=<dir>] [--omit-asset-content] [--max-canvas-bytes=<bytes>] [--max-nested-fig-bytes=<bytes>] [--max-archive-asset-content-bytes=<bytes>] [--max-zstd-inflated-bytes=<bytes>] [--max-nodes=<count>] [--max-kiwi-message-decode-bytes=<bytes>] [--max-kiwi-selective-message-decode-bytes=<bytes>] [--zstd-command=<path>] [--frame-id=<id>] [--font-css=<css>] [--font-css-file=<path>] [--font-family-css=<family>:<css>] [--font-family-css-file=<family>:<path>] [--render-text-glyph-paths] [--parity-status=<status>] [--parity-report-path=<path>] [--parity-source-screenshot-url=<url>] [--parity-source-screenshot-path=<path>] [--parity-generated-screenshot-artifact=<artifact>] [--parity-diff-image-artifact=<artifact>] [--parity-pixel-mismatch-count=<count>] [--parity-pixel-mismatch-ratio=<ratio>] [--parity-threshold=<ratio>] [--parity-viewport=<width>x<height>] [--parity-dom-boxes-path=<path>] [--parity-layout-report-path=<path>] [--parity-render-evidence-path=<path>] [--parity-layout-mismatch-count=<count>]\n");
     exit(1);
 }
 
 $options = array();
 $zstdCommand = getenv('FIGMA_TRANSFORMER_ZSTD_COMMAND') ?: null;
 $outputDir = null;
+$inspectKiwiGateMode = false;
 foreach ( array_slice($argv, 2) as $argument ) {
     if ( ! str_starts_with($argument, '--') ) {
         continue;
@@ -46,6 +47,17 @@ foreach ( array_slice($argv, 2) as $argument ) {
         continue;
     }
 
+    if ( 'inspect-kiwi-gate' === $name ) {
+        $options['inspect_kiwi_gate'] = true;
+        $inspectKiwiGateMode = true;
+        continue;
+    }
+
+    if ( 'kiwi-gated-decode' === $name ) {
+        $options['inspect_kiwi_gate'] = true;
+        continue;
+    }
+
     if ( 'inspect-frame-limit' === $name ) {
         $options['frame_inspection_limit'] = max(1, (int) $value);
         continue;
@@ -61,6 +73,31 @@ foreach ( array_slice($argv, 2) as $argument ) {
         continue;
     }
 
+    if ( 'max-kiwi-selective-message-decode-bytes' === $name ) {
+        $options['max_kiwi_selective_message_decode_bytes'] = max(0, (int) $value);
+        continue;
+    }
+
+    if ( 'max-canvas-bytes' === $name ) {
+        $options['max_canvas_bytes'] = max(0, (int) $value);
+        continue;
+    }
+
+    if ( 'max-nested-fig-bytes' === $name ) {
+        $options['max_nested_fig_bytes'] = max(0, (int) $value);
+        continue;
+    }
+
+    if ( 'max-archive-asset-content-bytes' === $name ) {
+        $options['max_archive_asset_content_bytes'] = max(0, (int) $value);
+        continue;
+    }
+
+    if ( 'max-zstd-inflated-bytes' === $name ) {
+        $options['max_zstd_inflated_bytes'] = max(0, (int) $value);
+        continue;
+    }
+
     if ( 'max-nodes' === $name ) {
         $options['max_nodes'] = max(0, (int) $value);
         continue;
@@ -195,7 +232,9 @@ if ( isset($options['parity']['render_evidence_path']) && is_scalar($options['pa
 }
 
 $transformer = blocks_engine_figma_transformer_cli_transformer(is_string($zstdCommand) && '' !== $zstdCommand ? $zstdCommand : null);
-if ( true === ($options['inspect_frames'] ?? false) ) {
+if ( $inspectKiwiGateMode && ! str_ends_with(strtolower($path), '.json') ) {
+    $result = $transformer->inspectKiwiGateFile($path, $options);
+} elseif ( true === ($options['inspect_frames'] ?? false) ) {
     if ( str_ends_with(strtolower($path), '.json') ) {
         $decoded = json_decode((string) file_get_contents($path), true);
         $result = $transformer->inspectFramesScenegraph(is_array($decoded) ? $decoded : array(), $options);

figma-transformer/scripts/figma-kiwi-skipped-field-inventory.php

@@ -13,29 +13,25 @@
 } else {
     require_once __DIR__ . '/../figma-transformer.php';
 }
+require_once __DIR__ . '/figma-script-utils.php';
 
 $options = blocks_engine_figma_kiwi_inventory_options($argv);
+if ( blocks_engine_figma_script_bool_option($options['self_check'] ?? false) ) {
+    blocks_engine_figma_script_self_check();
+    exit(0);
+}
 if ( true === ($options['help'] ?? false) || '' === ($options['input'] ?? '') ) {
     blocks_engine_figma_kiwi_inventory_usage(true === ($options['help'] ?? false) ? STDOUT : STDERR);
     exit(true === ($options['help'] ?? false) ? 0 : 1);
 }
 
 $zstdCommand = $options['zstd_command'] ?? (getenv('FIGMA_TRANSFORMER_ZSTD_COMMAND') ?: null);
-$result = blocks_engine_figma_kiwi_inventory((string) $options['input'], is_string($zstdCommand) && '' !== $zstdCommand ? $zstdCommand : null);
-$json = json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n";
-$outputPath = $options['output'] ?? null;
-if ( is_string($outputPath) && '' !== $outputPath ) {
-    if ( false === file_put_contents($outputPath, $json) ) {
-        fwrite(STDERR, "Failed to write skipped-field inventory output to {$outputPath}\n");
-        exit(1);
-    }
-    fwrite(STDOUT, json_encode(array(
-        'schema' => 'blocks-engine/figma-transformer/kiwi-skipped-field-inventory-output/v1',
-        'output' => $outputPath,
-        'summary' => $result['summary'] ?? array(),
-    ), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n");
-} else {
-    fwrite(STDOUT, $json);
+try {
+    $input = blocks_engine_figma_script_require_input_path((string) $options['input']);
+    $result = blocks_engine_figma_kiwi_inventory($input, is_string($zstdCommand) && '' !== $zstdCommand ? $zstdCommand : null);
+    blocks_engine_figma_script_output_json($result, isset($options['output']) ? (string) $options['output'] : null, $result['summary'] ?? array());
+} catch (Throwable $error) {
+    blocks_engine_figma_script_fail($error);
 }
 exit(empty($result['diagnostics']) ? 0 : 0);
 
@@ -62,7 +58,7 @@ function blocks_engine_figma_kiwi_inventory_options(array $argv): array
 
 function blocks_engine_figma_kiwi_inventory_usage(mixed $stream): void
 {
-    fwrite($stream, "Usage: figma-kiwi-skipped-field-inventory.php <path-to-fig> [--zstd-command=/opt/homebrew/bin/zstd] [--output=/tmp/inventory.json]\n");
+    fwrite($stream, "Usage: figma-kiwi-skipped-field-inventory.php <path-to-fig> [--zstd-command=/opt/homebrew/bin/zstd] [--output=/tmp/inventory.json] [--self-check]\n");
 }
 
 /**
@@ -187,16 +183,33 @@ function blocks_engine_figma_kiwi_inventory_payload(string $payload, ZstdCapabil
 function blocks_engine_figma_kiwi_inventory_file_summary(array $inventories): array
 {
     $byRole = array();
+    $decodedByRole = array();
     $fieldCount = 0;
+    $decodedFieldCount = 0;
     $occurrences = 0;
+    $decodedOccurrences = 0;
     foreach ( $inventories as $inventory ) {
         $summary = is_array($inventory['summary'] ?? null) ? $inventory['summary'] : array();
         $fieldCount += (int) ($summary['field_count'] ?? 0);
         $occurrences += (int) ($summary['occurrences'] ?? 0);
         foreach ( is_array($summary['by_role'] ?? null) ? $summary['by_role'] : array() as $role => $count ) {
             $byRole[(string) $role] = ($byRole[(string) $role] ?? 0) + (int) $count;
         }
+        $decodedSummary = is_array($inventory['decoded_summary'] ?? null) ? $inventory['decoded_summary'] : array();
+        $decodedFieldCount += (int) ($decodedSummary['field_count'] ?? 0);
+        $decodedOccurrences += (int) ($decodedSummary['occurrences'] ?? 0);
+        foreach ( is_array($decodedSummary['by_role'] ?? null) ? $decodedSummary['by_role'] : array() as $role => $count ) {
+            $decodedByRole[(string) $role] = ($decodedByRole[(string) $role] ?? 0) + (int) $count;
+        }
     }
     arsort($byRole);
-    return array('field_count' => $fieldCount, 'occurrences' => $occurrences, 'by_role' => $byRole);
+    arsort($decodedByRole);
+    return array(
+        'field_count'         => $fieldCount,
+        'occurrences'         => $occurrences,
+        'by_role'             => $byRole,
+        'decoded_field_count' => $decodedFieldCount,
+        'decoded_occurrences' => $decodedOccurrences,
+        'decoded_by_role'     => $decodedByRole,
+    );
 }