Add Figma support to studio create --from

[chubes4]

Related issues

• Related to SSI #1581.

How AI was used in this PR

OpenAI GPT-5.6 Terra via OpenCode direct run; GPT-6 Astra orchestrated after Chris Huber explicitly authorized bypassing Homeboy.

Proposed Changes

• Adds candidate-gated Figma create-from support, available only with an explicit SSI package override and the native PHP runtime.
• Validates zstd against the configured native PHP package and uses its generated INI configuration for the runtime probe.
• Keeps Figma unavailable for the Playground sandbox until WebAssembly zstd support exists.

Testing Instructions

Focused verification:

npx prettier --write docs/figma-fixture-generator.md
BLOCKS_ENGINE_FIGMA_TRANSFORMER_PATH=/path/to/blocks-engine/figma-transformer \
PHP_BINARY_WITH_ZSTD=/path/to/php \
npm test -- scripts/generate-figma-fixture.test.mjs apps/cli/commands/site/tests/create.test.ts apps/cli/lib/native-php/tests/capabilities.test.ts
npm run cli:build
git diff --check

Temporary isolated-HOME integration evidence

This is not a public runtime selector or default. Public PHP metadata deliberately does not advertise zstd, so a fresh CLI correctly gates before import. This command stages the exact macOS ARM workflow artifact at the configured package location in a disposable HOME; ensurePhpBinaryAvailable uses the staged binary, creates or synchronizes its INI, and the Figma probe uses that INI. The cleanup trap removes the temporary home, runtime, fixture, and site.

Candidate acquisition: follow the documented SSI package build route. It clones SSI 165bf27363a0616c1c2ecb78c687e2bd2f05bc52 and Blocks Engine 573e126b7fc1d95df757e183366384c2d72f691c, runs the SSI development-package build, and distinguishes the historical tested ZIP checksum from locally rebuilt provenance.

The runtime is workflow run 34483685921, job 102892497452, artifact 10155344620 (php-8.5.10-cli-macos-aarch64). The original tested SSI candidate was the full development ZIP from SSI #1581, source commit 165bf27363a0616c1c2ecb78c687e2bd2f05bc52: static-site-importer-dev-165bf27363a0-blocks-engine-573e126b7fc1.zip, SHA-256 7beec605fdc79885e84e6e29688c8aa3490c66847220ac7dca333ee8ece2f751.

Run from the Studio repository root:

# Set SSI_CANDIDATE_ZIP with the documented acquisition procedure above.
npm run cli:build
workdir="$( mktemp -d )"
trap 'rm -rf "$workdir"' EXIT
gh run download 34483685921 --repo Automattic/studio \
  --name php-8.5.10-cli-macos-aarch64 --dir "$workdir/artifact"
mkdir -p "$workdir/home/.studio/php-bin/8.5.10-studio-1"
unzip "$workdir/artifact/php-8.5.10-cli-macos-aarch64.zip" \
  -d "$workdir/home/.studio/php-bin/8.5.10-studio-1"
git clone https://github.com/Automattic/blocks-engine.git "$workdir/blocks-engine"
git -C "$workdir/blocks-engine" checkout 4f56d2dc29bc50d5d03285e5eb0f7e94029e7f1d
"$workdir/home/.studio/php-bin/8.5.10-studio-1/php" scripts/generate-figma-fixture.php \
  --blocks-engine-path="$workdir/blocks-engine/figma-transformer" \
  --output="$workdir/studio-fixture.fig"
HOME="$workdir/home" node apps/cli/dist/cli/main.mjs create \
  --from="$workdir/studio-fixture.fig" \
  --static-site-importer-path="$SSI_CANDIDATE_ZIP" \
  --runtime=native --php=8.5 \
  --name='Studio Fixture' --path="$workdir/studio-figma-fixture" --no-start
test -f "$workdir/home/.studio/php-bin/8.5.10-studio-1/php.ini"

Actual run result: the import completed successfully. The isolated staged runtime created php.ini and passed a zstd_uncompress probe. The resulting published page was Studio Fixture Node Changes Fixture with 1,126 bytes of block markup, beginning with Group and Paragraph blocks. This is narrow import-path evidence only; it makes no production fidelity or editability claim.

Build Evidence

• No-publish run 34483685921: Linux x86_64, Linux ARM64, macOS ARM64, and Windows x86_64 passed. macOS x86_64 failed in pinned third-party shivammathur/setup-php before Composer, SPC, or Studio build code.
• No-publish retry 34486883757: the same four platforms passed and macOS x86_64 failed at the same third-party setup step. Both runs used apps_cdn_visibility=none, so neither published artifacts.
• SSI v1.10.0 is the latest published release inspected. Its two release ZIP assets do not establish a repaired full archive, so it is not configured as a default package.

Pre-merge Checklist

• Focused tests pass, including native Figma and sandbox-rejection/no-mutation behavior.
• CLI build and the isolated macOS ARM candidate import pass.
• The artifact, candidate checksum/source, isolated staging command, and cleanup are documented.
• Keep this PR as a draft and Figma default support candidate-gated.
• Do not merge, publish, or claim public availability until a full SSI release archive is verified, an authorized publish-enabled all-platform PHP run succeeds, and the generated metadata PR is reviewed.
• Do not dispatch additional Intel macOS builds for this PR.

Browser Acceptance Status (2026-09-10)

Three real import/design iterations were completed. The selected frame 3b7c6c materialized after Blocks Engine #1655 and #1657; those fixes are implemented, but this acceptance run failed.

• The native terminal receipt was invalid because the complete source_reports.figma.transform response exceeded Studio native WP-CLI's 1 MiB retained-output tail. The bounded SSI receipt/artifact-reference defect is tracked in SSI #1589.
• Browser pixel differences were 50.72% at 1440x900 and 28.65% at 390x844. Observed geometry differences include a missing logo, desktop heading x-position 112 to 224, image y-position 290 to 402 with a changed crop, and document width 1440 to 1664 desktop / 390 to 438 mobile.
• Visual fidelity acceptance therefore remains failed. No public visual-root-cause issue is filed because this run uses private source material and has no sanitized public reproduction.

AI assistance disclosure: GPT-6 Astra via OpenCode performed the read-only diagnosis and tracker evidence update. Chris Huber directed the scope and remains responsible for review.

Port Allocation Fix (2026-09-10)

• The shared allocator now requires every supported literal loopback family to be free before it selects a port for an advertised localhost URL.
• The native PHP proxy owns 127.0.0.1 and, when available, ::1 on the selected port, verifies readiness through each owned listener, and closes both listeners on every lifecycle path.
• Real socket tests use OS-assigned ports to cover occupied IPv4, occupied IPv6 where supported, dual-stack availability, and an advertised localhost fetch that resolves to the owned service rather than a deliberately foreign IPv4 listener.
• Verified with npm test -- packages/common/lib/tests/port-finder.test.ts (7 tests), npm run typecheck, npm run cli:build, and git diff --check.

AI assistance disclosure: OpenAI GPT-5.6 Terra via a direct OpenCode run traced and implemented the port contract; Chris Huber directed scope and reviewed the resulting change.

[wpmobilebot]

📊 Performance Test Results

Comparing 7f7b624 vs trunk

app-size

Metric	trunk	7f7b624	Diff	Change
App Size (Mac)	1456.76 MB	1456.76 MB	+0.00 MB	⚪ 0.0%

site-editor

Metric	trunk	7f7b624	Diff	Change
load	1190 ms	1171 ms	19 ms	⚪ 0.0%

site-startup

Metric	trunk	7f7b624	Diff	Change
siteCreation	7508 ms	7485 ms	23 ms	⚪ 0.0%
siteStartup	2869 ms	3400 ms	+531 ms	🔴 18.5%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)