Material Studio

Material Studio is the ForgeaX material-authoring extension. It owns WGSL editing, WebGPU preview, parameter controls, direct texture baking, safe directory-backed persistence, and deterministic Cook-input export.

Local development

The iframe imports the public @forgeax/extension-platform/transport entry. It derives a trusted parent origin from document.referrer (a matching hostOrigin can only corroborate it), then uses createWindowTransport and createHost for protocol-1 handshake, theme, visibility, surface, and tool messages. It never sends or accepts arbitrary postMessage traffic.

Install the extension's released dependencies and run the complete local gate:

bun install
bun run typecheck
bun run test
bun run build

The backend's material:diagnose tool is deliberately read-only. It proves the manifest → Extension Host → iframe call path before later milestones add model, shader, or material capabilities.

Register the local extension

Studio currently has no package-install command for a project-local extension registered under .forgeax/extensions. Build the actual checkout, then use the local registration command. It atomically swaps only the existing material symlink after a successful build; it prints the former target and never removes that target or another extension.

cd forgeax-ex-material
FORGEAX_STUDIO_ROOT=../forgeax-studio bun run register:local

The command verifies that the registered dist/index.html, dist/main.js, and dist/server/host.js are the same files and bytes as this checkout's fresh build. The source manifest deliberately points to these local runtime artifacts; do not commit dist/ or replace the registration with a copied temporary source tree.

Cook input export (009A)

After saving a WGSL file and its matching .forgeax-material.json, 导出 Cook 输入包 writes one deterministic, engine-neutral bundle through the user-authorized Directory Workspace:

• material-studio.exports/<source-hash>.forgeax-material-cook.json

The single JSON file contains snapshot copies of Surface WGSL, the generated material descriptor, parameters/output snapshot, channel and color-space semantics, target-profile summary, receipt/manifest metadata, and a SHA-256 integrity hash. Large texture inputs are not copied: they are declared as project-relative external inputs with their observed hash and revision so a future host cooker can collect them.

This is deliberately Cook input only, not a ForgeaX MaterialAsset, Pack, Catalog row, runtime receipt, or proof of rendering. It records the real Engine evidence it has (material-cook/1, Pack 2.0.0) and a structured blocker list: the current plugin has no callable Engine source catalog, runtime shader ABI, texture GUID resolver, or Pack cooker.

The browser directory API has no atomic multi-file publish, and read-then-delete rollback would be unsafe against concurrent writers. Therefore no scattered source/sidecar/texture final files are emitted and no final export is deleted automatically. The one file is written through no-overwrite CAS, then read back and hash-verified. A failed verification can leave at most one invalid residual; it is reported, is not a successful export, and must fail bundle schema/integrity validation before any scanner or host cooker accepts it.

When a target project exposes those Engine Host/Build interfaces, that project must compose, cook, validate, and issue its own runtime receipt. This plugin does not publish a copy-pastable cook command or claim runtime readiness before that integration exists.