Repository development and verification

This guide is for contributors and agents. SDK users should start with Getting Started and Packages and Tools. Run every command from the repository root.

First checkout

Prepare Git, Node.js and pnpm using your existing version-management tools. .node-version selects the recommended development major (22); the root packageManager selects the exact pnpm version (10.14.0). No personal machine paths or global agent configuration are required.

Package metadata declares Node >=22. Product checks run on Ubuntu/Windows × Node 22/24; documentation and releases use Node 22 from .node-version. Other newer majors satisfy the declared package range but are not continuously verified. Development dependencies can require newer patch releases of Node 22.

pnpm repo:setup

repo:setup initializes submodules at their Git-recorded commits, installs with the frozen lockfile, builds, runs repository-tool tests and runs doctor. It writes dependencies/build output and initializes submodules; it does not rewrite the lockfile, select Node or install global tools. Use repo:setup, not pnpm's built-in setup environment command.

For a dirty checkout, consider an isolated worktree before dependency or documentation work. Do not reset user changes, delete dependencies or regenerate the lockfile to work around an environment problem. Submodule network/TLS failures are acquisition failures, not evidence of a Node or product regression.

Verification entrypoints

Choose one entrypoint for the task, rather than running every command in order. Use check:ci when package-level AGENTS require full checks.

Task	Command	Coverage
First checkout	pnpm repo:setup	Pinned fixtures, installation, build, repository-tool tests and environment diagnosis; ready to start development
Code changes	pnpm check:fast --base origin/next	Lint, typecheck, basic repository-tool tests and guidance checks; build before selected AVA tests. Replace the base with the actual PR target
Ordinary documentation changes	pnpm docs:check	Local links, agent paths/commands, impact-table drift, public source mappings, bilingual entries, Changelog structure and contract drift
Broad changes or full CI reproduction	pnpm check:ci	Fixtures, lint, typecheck, guidance/contracts, build, all repository-tool and AVA tests, tarball consumers and documentation build

Use the same base for preview and execution. --list only prints a plan; it does not run lint, typecheck or builds:

pnpm check:fast --base origin/next --list
pnpm check:fast --base origin/next

Fast checks are not a full regression. Ordinary documentation excludes site configuration and theme code under docs/.vitepress/. Run pnpm docs:build when you need a page preview; it explicitly generates TypeDoc API pages before building VitePress. CI still checks and builds documentation.

Focused checks and environment diagnosis

pnpm test:repo runs built-in Node tests for repository tooling without product builds or external fixtures. pnpm check is the product-check composition used by CI's quality job (fixtures, lint, typecheck, build, repository-tool tests and all AVA tests). For daily work, choose from the table rather than stacking these commands.

pnpm repo:doctor --json reports read-only Node/pnpm, dependency, exported-file, native-image, temporary-directory permission and reference status.

Doctor does not install, download, configure or write files; submodule status queries also disable Git's optional index-refresh writes. Export-file presence does not prove build freshness or Node/Web runtime behavior; pack:check verifies actual consumer boundaries. Sharp checks exercise in-memory PNG/JPEG encoding and pixel decoding, not just version metadata; unavailable or failed codecs warn, without proving real publish/restore workflows. The temporary path must be an accessible directory, but access flags do not prove ACL permissions, free space, later writes or rollback. A non-recommended Node major warns; an unsupported Node version, mismatched pnpm or missing required fixtures/build output fails.

Changed-test selection

agent/impact-map.json is the only mapping source. pnpm test:changed --matrix renders the marked table in root AGENTS, and guidance checks reject drift.

• check:fast requires an explicit --base or PR GITHUB_BASE_REF; if both are missing, it fails with usage guidance. The lower-level test:changed can still fall back to local origin/HEAD. No automatic fetch occurs; the ref must exist locally. An explicitly supplied but unavailable base still selects the full suite.
• The plan combines branch changes since merge-base, staged, unstaged and untracked paths. Renames include old and new paths; deletions are included.
• The first matching rule wins. Core/test-utils cover all downstream packages; functions/backend cover their consumers. CLI owns its bootstrap tests and does not select Backend in reverse.
• Unknown paths, dependency/shared configuration changes, unavailable bases/shallow history and no changes fall back to the entire suite, never an empty success.
• Recognized documentation-only work may use repository-only mode, which still runs tooling tests and guidance checks. check:ci additionally builds the documentation.
• Every selected test group must match files. Listed documents are review prompts, not a demand to rewrite unrelated protocol descriptions.
• Selected AVA tests always follow a workspace build so built CLI/MCP/backend tests cannot load stale dependency output; build failures stop execution. Documentation-only mode and --list/--matrix do not build.
• Tests use pnpm's AVA shim, preserving the environment required by existing isolated-build tests. Do not call AVA's raw JS entrypoint. Direct Node invocation of the selection script supports plan/matrix inspection only.

PR CI first fetches full Git history and classifies changes against the PR base commit using the existing impact map through test:changed --list. Only a repository-only plan skips quality/consumer jobs; documentation still runs the repository script checks in scripts/repository.test.mjs, docs:check and docs:build. Code, site configuration, scripts, dependencies, unknown paths, no changes or an unavailable comparison base select full checks. A failed scope job also does not silently skip product checks. The workflow remains triggered; only individual jobs are skipped.

Full CI runs check on Ubuntu/Windows × Node 22/24. Ubuntu / Node 22 additionally enforces coverage and uploads its report. Documentation checks and builds separately; consumers run pack:check on Linux/Windows. Documentation and consumers do not download fixtures. Pushes to main and next always run full checks; only runs for the same PR cancel each other. Pages uses workflow_run after successful main push CI, checks out that verified head_sha and skips superseded commits. Remote links, translation meaning and protocol interpretation still require review.

Local check:ci verifies fixtures, formatting/lint, types and guidance, then runs pack:check, repository tests, pnpm test and documentation builds. pnpm test explicitly builds first, including when invoked independently; tests never rebuild shared CLI/MCP output. pack:check independently checks contracts and builds for consumers, so the full pipeline includes two builds. Linux CI uses pnpm check:ci --browser-deps to install Chromium system dependencies.

Release separates a read-only verify job from the privileged publish job. Verification checks the tag, five package versions and matching bilingual CHANGELOG entries, runs full check:ci, verifies the exact tarballs, and uploads them with checksums. Publishing checks out no sources and installs no project dependencies; it downloads and verifies those artifacts. npm 11 installation and tarball publication disable lifecycle scripts. Release notes come from both changelogs instead of generated replacements. Third-party Actions are pinned to commit SHAs; documentation builds have no Pages/OIDC write permissions.

pnpm pack:check builds and installs five tarballs outside the checkout, verifying public entries, types, CLI/MCP, Node examples and real Chromium OPFS edits/save/reload/locks/paths/image bytes. It installs dependencies over the network and downloads the matching browser on first use; successful runs remove their temporary directory, failures preserve it, and --keep preserves successful runs too. Release uses pnpm pack:check --artifacts .release to check the same packed files. See Runnable Examples and Consumer Verification for entrypoints, examples and limits.

Use the repository's .github/pull_request_template.md to identify affected packages, UAM/Backend/MCP/CLI contracts, version handling, documentation and bilingual changelogs, together with the actual tested base, commands and failed/unrun checks. The template records review evidence; checkboxes neither replace CI nor authorize publication or prove verification.

Agent evaluations share that tarball installation. pnpm eval:agent --runner reference runs ten deterministic tasks, including editing, safe stops and separate publish/recovery tasks; these already gate consumer verification. pnpm eval:agent --runner codex --codex codex runs real-model tasks manually, with success rates used only as observations. See Real Agent Task Evaluations for tasks, isolation, Windows executable requirements and reproduction.

Reference evidence

references.json records only public fixture roles and probe files. The three required upstream submodules live under packages/test-utils/test/fixtures/:

Submodule	Authority
FairyGUI-Editor	Current editor UI, settings and plugin API; not the legacy binary exporter
FairyGUI-layabox	Layabox consumption code and paired demo source/published resources
FairyGUI-unity	Unity consumption code and paired example source/published resources

URLs come only from .gitmodules; commits come only from Git gitlinks. pnpm refs:sync retrieves those versions. Builds and tests use these public submodules, the tracked FairyGUI-Experiments project and generated minimal test objects.

pnpm refs:status observes status without failing for missing material; pnpm refs:sync initializes/updates to gitlinks without tracking remote tips or forcing overwrites; pnpm refs:verify strictly checks required fixture commits, working trees and probe files. pnpm refs:grep "literal text" verifies before searching for a case-sensitive literal, returning repository-relative paths and line numbers; exit codes are 0 for matches, 1 for no match and 2 for errors.

refs:grep reuses that registration and verification, searching only tracked text in the three submodules. It skips binaries, untracked/ignored files and files outside the registered scope. Missing, dirty, mismatched or incomplete fixtures and Git search failures prevent partial success; resolve the reported problem without automatic synchronization or overwrites. A path/line match locates evidence; it does not make that source authoritative for legacy exporters. For a particular source or richer queries, first verify its status and role with refs:status, then use native Git/rg in that directory.

Base protocol conclusions on maintained repository documentation, pinned public fixtures and publicly verifiable primary sources. Record sources, applicable versions and test evidence. If decisive evidence for a field or publishing rule is missing, mark that conclusion unverified, stop it and identify the missing material; unrelated work can continue. Public fixture status checks do not establish every protocol rule.

Check output naming and settings against public documentation, source projects and paired published artifacts for the relevant version; establish field ownership through real XML tags. Verify behavior separately for each version; runtime compatibility alone does not establish a project or publishing protocol. Prefer paired semantic binary checks, not a lone package or header Version difference.

Product documentation and repository diagnosis

Installed packages use ofgui docs and ofgui doctor --json without a checkout. pnpm contracts:generate updates contracts and corpus under packages/backend/src/generated/ and Core's transaction payload table under packages/core/src/uam/generated/; package-version, workflow and thin-skill changes also require regeneration and pnpm contracts:check. pnpm pack:check verifies CLI/MCP corpus parity, versions, doctor and the packaged skill. Repository prerequisites still use pnpm repo:doctor; see installed docs.

Contract generation uses Core/Backend/CLI types to update MCP/CLI structures, operations, diagnostic guides, snapshots and bilingual tables. contracts:check checks mappings, formal diagnostic coverage/ownership and generated drift without writing; repository tests separately check CLI command registration coverage. See the contract guide for change entrypoints.

Small glossary

Term	Meaning here
Source Project / Published Package	Editable authoring project versus runtime output; different contracts
UAM / Document	Public declarative authoring model versus mutable low-level property graph; transaction guarantees belong to the UAM entrypoint
Lift / Materialize	Document to UAM / UAM to Document; materialization is not saving or publishing
Session / Revision	Backend editing state and its version; mutations supply expectedRevision
Transaction support / Apply	Support checking and execution are distinct; success does not guarantee saving
Source bytes	Explicitly hydrated binary data, not preserved through JSON cloning
Capability plane	Separate service/host capability scopes; reading does not imply editing, saving or publishing
Semantic round-trip	Preservation of supported meaning, not byte-for-byte XML or binary equality

Root and package AGENTS own package rules and public-contract pointers. The architecture overview explains actual data flows. Do not edit packages/*/dist/, docs/public/api/ or docs/.vitepress/dist/ directly. New key documentation must update both root READMEs and documentation indexes; releases update both Changelogs. Structural checks do not replace semantic review.

See Development Task Recipes for concrete entrypoints, evidence requirements and acceptance checks. It navigates existing implementation, not a second protocol or operation grammar.

Formatting, compilers and coverage

pnpm format formats maintained sources; pnpm lint:ci runs biome ci for formatting and lint. Generated contracts, fixtures, dist and site output are excluded from manual formatting. Node built-ins require the node: prefix; explicit any in src produces warnings.

The package.json toolchain field explains the compiler split: typecheck invokes @typescript/native/bin/tsc (TS7) explicitly, while TypeDoc and contract generation use the stable TS6 Compiler API through the typescript alias. Do not rely on the shared bare tsc shim. Tarball type consumers verify TS6 NodeNext ESM/CJS; TS5 is not a current compatibility commitment.

pnpm coverage builds and runs all AVA tests with c8. Maintained source thresholds are 90% lines/statements/functions and 75% branches, excluding generated code. It emits coverage/lcov.info and a terminal summary. Ubuntu / Node 22 CI enforces these limits and uploads the report. AVA workerThreads: false is declared only in root configuration; at most four test files run concurrently to avoid Windows process-start contention.

Offline verification

With dependencies and pinned fixtures already present, pnpm check:fast --base origin/next and pnpm check do not download browsers or install consumer dependencies. Run these and pnpm docs:check offline. Report missing fixtures using pnpm refs:status; skipped checks are not passes. pnpm check:ci may need network access for consumer installation and browsers and must still pass before release.

Contributing

Start with translation fixes or isolated regression cases. Explain expected behavior and evidence, follow package ownership, and report validation and limitations in the PR. Protocol work needs pinned sources; releases need bilingual notes. Maintainer onboarding requires a reviewed contribution and release rehearsal before permissions.