feat(scene): add node serialization and batch restoration

[YuchenWell]

Background

Provide the cocos-cli foundation for cross-scene node copying by exporting selected node hierarchies as transferable data and restoring them in a target scene.

Changes

• Add Node.serialize and Node.createBySerializedData, serializing all selected roots together to preserve internal node and component references
• Reuse existing serialization and engine deserialization, with valueReplacer handling parent links, prefab metadata, and external references without modifying source nodes
• Support insertion position, world-transform preservation, and external-reference clearing or resolution
• Generate fresh identities for copies and preserve snapshot identities during Redo
• Record batch creation as one undo operation and roll back nodes and parent prefab metadata if mounting or snapshot capture fails

Scope

• Update Scene services, process proxies, and public type snapshots
• Add coverage for rollback, prefab handling, reference restoration, and Undo/Redo
• PinK clipboard and copy/paste UI integration will follow separately

Test Plan

• Serialize mutually referencing nodes in scene A, then restore them in scene B; internal references should point to the new nodes, while external references are cleared by default
• Restore a complete prefab instance and a separately copied child; the complete instance should retain its association, while the child should detach from the original instance
• Undo and redo batch creation; all roots and their internal references should be removed and restored together
• Inject mounting or snapshot failures; no nodes from the failed batch should remain in the target scene

[knoxHuang]

Three-axis review of head b5e271e9 (merge-base ee94053): repo standards, PR spec, and module design.

Overall the implementation is faithful to the PR description — all five Changes items are verified in code, all four Test Plan bullets have real coverage, the out-of-scope boundary (PinK clipboard / paste UI) is respected, and CI is green.

Findings anchored inline: 1 documented-rule violation (undo snapshot lacks the path fallback required by docs/dev/scene/core/undo-redo.md), 1 file-style inconsistency (the two new API methods miss the bilingual JSDoc used by every sibling), plus judgement-level notes: seam placement (mountSerializedNodes living in the undo-command module), duplicated guard/cleanup code, boolean control coupling (preservePrefab/preserveIdentity), the $nodeReference magic string, SerializedNodeData naming, an exported internal seam with no external consumer, and a redundant double-destroy after rollback.

[YuchenWell]

@knoxHuang's Review (2026-09-11)

The changes are available in 6e644e4. Each of the 14 inline comments has a separate reply.

Changes made:

1. Code cleanup: Added concise Chinese method comments and the pass-back-unchanged contract; aligned the hook implementation with unknown, centralized the reference marker, and removed the unnecessary internal export.
2. Module responsibilities: Moved mounting, parent Prefab snapshots, and rollback into service/node/serialized-node-mount.ts, shared by initial creation and Redo. The mounting tests also dropped two unnecessary mocks.
3. Undo and test documentation: Updated the command inventory, integration table, batch-creation behavior, and feature-specific testcase convention. Added two real-engine regressions ensuring that a same-named replacement cannot take over the original object's Undo/Redo history.
4. Design choices retained: Kept the structured payload and existing public type name, exact UUID/editor-session checks, post-mount snapshot capture, and separate stage options. The engine guards duplicate destroy() requests, so no ineffective plain node.isValid check was added; details are in the inline replies.

Validation: TypeScript checking, compilation, and MCP type generation pass. All 46 outer tests across six relevant suites pass, including a subprocess with 31 passing real-engine checks. ESLint reports no new diagnostics compared with the previous head; the existing one error and two warnings remain. No UI or manual editor acceptance testing was performed.

[knoxHuang]

Re-review at head 6e644e46 (incremental diff b5e271e...6e644e4): every claimed fix verified in code, CI green on the new head.

Confirmed

• mountSerializedNodes + parent-prefab capture/rollback moved to service/node/serialized-node-mount.ts (single-export module); the command now depends on it, not the other way around. node-serialized-creation.test.ts imports from the new path and dropped two now-unneeded mocks; sibling test files updated their mock paths consistently.
• replaceValue type drift fixed (unknown); NODE_REFERENCE_KEY extracted and reused in writer/validator/reader; collectSerializedNodes made module-private; pass-back-unchanged invariant added to the schema describe; Chinese JSDoc added to both new tools.
• docs/dev/scene/core/undo-redo.md synced: command list, integrated-business table, event table, module map, and a createBySerializedData implementation note; the UUID-based structural snapshot now has an explicit documented exception, and rule 12 was revised to allow business-specific *.testcase.ts files loaded by scene.test.ts (which this PR's testcase is).
• Two new real-engine regressions prove the same-name-replacement hazard is rejected on both undo and redo — exactly what the original path-fallback rule guarded against.

Withdrawn (see thread replies): the double-destroy redundancy (engine's ToDestroy flag makes the second destroy() a silent no-op) and the duplicated-guard finding (the two guards encode different session invariants).

Remaining nits

1. The two new it() names in serialized-node-data.engine-test.ts are Chinese while all 21 existing cases are English — consider aligning with the file.
2. This PR amends a previously documented standard (undo-redo.md l.424 boundary rule and rule 12). The rationale and tests are sound, but a standards amendment deserves explicit maintainer sign-off rather than riding along in a feature PR.

(Note: I could not mark the four remaining threads resolved — no permission on this repo; the acceptance replies are posted in-thread.)

[knoxHuang]

Approving at head 6e644e46 (re-verified: OPEN, MERGEABLE/CLEAN, all four checks — check-changes, check-dts, pr-test macOS + windows — completed successfully on this exact head).

Everything raised in my initial 14-comment review is now either fixed and verified in the incremental diff (b5e271e...6e644e4), withdrawn with evidence, or turned into a documented, regression-tested deviation:

• mount/rollback seam moved to service/node/serialized-node-mount.ts with the dependency direction corrected, tests and mocks updated consistently;
• type drift, magic string, exported internal seam, schema invariant, JSDoc, and undo-redo.md sync all addressed;
• the uuid-only structural snapshot now has an explicit documented exception plus two real-engine regressions proving same-name replacement is rejected on both undo and redo.

Remaining nits are non-blocking and can be handled in follow-ups:

1. The two new Chinese it() names in the otherwise-English serialized-node-data.engine-test.ts.
2. The undo-redo.md standards amendment (l.424 exception + rule 12 revision) — rationale and tests are sound; flagging for explicit maintainer visibility since it changes a previously documented rule.