CONTRACT: enclose diagram groups and honor scene origins

[schlessera]

Refs #2228

What changed

Fit diagrams now enclose computed groups, painted borders and headings while preserving authored node coordinates. Fixed/narrow frames report clipped group information. Client, static and flattened SVG, annotations, legends and native export sizing honor nonzero viewBox origins.

Why this shape

This follows #2228 and the module-renderers decision: geometry computes the complete frame without moving authored nodes or dropping groups. Previously accepted clipped fixed/narrow inputs now fail validation; the CONTRACT update, API report and minor changeset record this compatibility change.

Proof

Original implementation local base: 0d780605fe1ea9a281cce947b1f0074f3f3e7acc. Original candidate: 42c83eb2a2d6ba77dc5fc6fe74909a7e822420f9, tree 264fe52701e057412c1fbe5f6abf1256081b7a6e. Local browser/mutation receipts describe the source bytes committed here; their working checkout HEAD was the base, not a hosted synthetic merge checkout.

• Restoring only the old frame calculation makes the exact origin-group case fail ALL_SCENE_LEFT: -16.5 is outside a frame starting at zero. Restored geometry passes seven bounds/routing cases, including opposite groups, fixed/narrow headings and authored scope borders.
• Restoring the three old painter implementations makes all four Chromium/WebKit cases fail NONZERO_SCENE_ORIGIN with zero instead of a negative origin. The candidate painters were restored.
• Initial candidate Chromium/WebKit: four cases passed with loaded fonts, native text floor, client/static/flat parity, group/node coordinates and optional annotations.
• Restored Chromium/WebKit: all four cases passed with screenshot captures. Visually reviewed all four; group/heading, authored node, complete notes and footer remain visible. A capture-selector failure was diagnosed: replaying an SVG omitted the ancestor required by the selector. Using the established figure selector fixed the capture, retaining the original deadlines and zero-request replay guard.
• Full diagrams suite: 174 passed / 347,028 assertions. Initial preflight: 549 fast tests and 166 import-graph affected tests passed, plus all lint/leakage/metadata gates. The exact committed candidate also passed bun run check:pr --base origin/main: 549 fast tests / 2,459 assertions and 166 affected tests / 346,893 assertions, plus all gates.
• Real pinned offline Chromium CLI exports the negative-origin input as SVG, 640×240 PNG (320×120 CSS pixels at the renderer’s source-defined 2× scale), and one-page PDF. Signatures, byte counts and viewBox were asserted; PNG visually reviewed. The initial manual probe had a 1× pixel assertion; that failure remains separate from the corrected assertion.
• Complete selected hosted proof is pending; no queued or incomplete job is claimed green.
• Base assessment: main advanced after local proof to 498270fbdc4ef2788fdd3babb259b647d77f6c77 via CONTRACT: fix(ui-sdk): qualify separate-UID native maintenance inputs #2361. Its native maintenance, identity-probe and server-startup changes do not change diagram geometry, painters, browser test inputs or the UI client entry. Local receipts retain base 0d780605; they are not proof of this newer combined tree. The draft merge checkout is 50c1bb81b6b96d7fc2d6cb92936dfa5b97f3253b, with exact parents 498270fbdc4ef2788fdd3babb259b647d77f6c77 and 42c83eb2a2d6ba77dc5fc6fe74909a7e822420f9, tree 651c4b0acc7eb3081401b3829fbf967bcc1fbda0. Fresh ready-candidate hosted proof must qualify the actual combined candidate. No rebase is needed for this compatible advancement.
• Full strict TypeScript passed. Pending changeset names and the complete release plan assemble; npm latest is 0.43.1 and the issue milestone is 0.44.0.
• Same-class audit covered frame/endpoint routing checks, callout placement/bands, legend/frame painting, both SVG serializers and native export height. No moved code citations were found for the changed module source files.

Earlier receipts remain failed: syntax-invalid test, incomplete painter imports, temporary-storage/source-preparation errors and one invalid added containment fixture. The corrected fixture and current behavioral receipts are separate evidence.

Document-binding correction after failed confirmation

Earlier correction head: 36b46d1830de30f60ba6d77fb97ee502e1e067c5, tree 4a077d14c07d7bb9ed60152297a3d196950bb975. At correction preflight, fetched main was 498270fbdc4ef2788fdd3babb259b647d77f6c77; the earlier local merge-base remains 0d780605fe1ea9a281cce947b1f0074f3f3e7acc.

Ready run 39074479367, attempt 1, did not qualify the candidate. Unit (2), job 117518971426, failed five document-binding controls (871 passed / 5 failed / 237,071 assertions). Unit (1), job 117518971447, failed COMPLETE_NATIVE_QUALIFICATION_WITHOUT_DOCKER_OR_IMAGE_LOOKUP (764 passed / 1 failed / 110,321 assertions), owned by #2365. Both checked out the original merge identity recorded above. Unit (4), endurance and the aggregate were cancelled; whole-workflow success and complete proof are absent.

The five document controls reproduce locally. Audit covers the exact sink, six literal/source-owned callers, new origin-group fixture and annotations, closed SVG producer/import closure, generated consumer CSS, verified inline fonts and zero-request replay. The scoped declarations now include the scene caller/fixture/flattening dependency and reviewed geometry, annotation and painter deltas. The matching guard, importer inventory, call counts, HTML sink, resource guard and native qualification fingerprints are unchanged. Producer-closure testing now starts from every caller too.

• Full tracked-file importer inventory: both diagram capture and raster comparison declarations bind with no refusal, preserving their complete runtime/byte producers.
• Document controls: 15 passed / 98 assertions after restoration. Existing sink, font, fixture, caller and escaped-command refusals pass; new controls independently cover every changed scene producer, omitted caller and unknown direct/aliased/dynamic caller.
• Removing producer validation fails SCENE_DRIFT_NAMED: changed origin fixture is accepted (undefined refusal) instead of the named stale pin. Removing the declared scene caller fails REVIEWED_DIAGRAM_DOCUMENT_BINDS. Both mutations are restored; all 15 tests pass separately afterward.
• Real pinned Chromium/WebKit rerun: four scene-origin cases pass with client/static/flat bounds, fonts, annotations, captures and zero-request replay. All four captures visually reviewed. This ran before the follow-up commit, with original HEAD and corrected working-tree audit bytes; product source bytes remain those of the original implementation commit.
• The first correction preflight exited 137 / SIGKILL. Its lint child completed all gates clean; this is not a passing preflight. No kernel/cgroup OOM record explains the signal. A single separately logged, supervised diagnostic attempt after native/browser preparation drained passed in 348.29 seconds on committed head 36b46d1830de30f60ba6d77fb97ee502e1e067c5: 956 fast tests / 6,328 assertions and 338 affected tests / 348,434 assertions, plus all lint/leakage/environment/changeset gates. The exact command was bun run check:pr --base origin/main; fetched ref was 498270fbdc4ef2788fdd3babb259b647d77f6c77 and the actual merge-base was 0d780605fe1ea9a281cce947b1f0074f3f3e7acc. This is local source proof, not proof of the then-untested synthetic merge deb35da585d8b90c2a7b0dd075f006e77e763963 (parents that fetched main and current head, tree 490827c03603578656f9ff160f7f99266ab8e525).

Current-base reconciliation

2026-10-18 current-base conflict reconciliation: pushed head 6e721192b7875aa4be68bbab18a2fcd3551b3331, source tree b891694436d65455162c208827f3bc86e73b3ee3; merge parents 4d49e1666f7f9b76d9f76c1f2c74a892dfbc6a68 and integrated main 7f22bb6ac2892360f3a5c4d3a1f93d9997af43e8.

The full seven-commit missing main diff was reviewed. The only conflict was the diagram declaration audit comment. Resolution preserves all six callers and the authoritative origin-group geometry, incorporates delivered #2393's split narrow-callout cases and exact audited pin, and preserves delivered #2241 viewer/font proof. All 15 original product/contract/test files and both viewer tests remain byte-identical to their owning commits. Twenty-seven incoming paths are byte-identical to delivered main; the decision record preserves both independent additions. Delivered #2388's raw-Git frozen producer fixtures remain intact: positive controls use pinned revision 498270fbdc4ef2788fdd3babb259b647d77f6c77, while actual current-source drift requires fresh proof.

• Full tracked-file importer/source audit: both diagram document declarations bind without refusal. Capture retains six callers with counts 2/1/8/3/1/2, 53 producers and 41 runtime / 18 byte inputs. Raster retains its three-call owner, 56 producers and 35 runtime / 22 byte inputs. Exact HTML sinks, producer closure, fixtures, CSS, fonts and zero-request replay are unchanged. Native binder, full source inventory and qualification hashes are unchanged.
• Focused controls: 42 tests / 712 assertions pass. Restoring the stale pre-2393 callout pin fails REVIEWED_DIAGRAM_DOCUMENT_BINDS as intended; restore is byte-identical and all 15 binding controls / 98 assertions pass. Existing geometry and producer-guard mutation receipts retain their original source identities. One initial preservation-check setup incorrectly compared the combined decision record to bare main, so its attempted negative run was only a passing control; it is excluded from the genuine mutation receipt.
• Pinned offline Chromium/WebKit: all 112 cases across eight renderer/axis/callout/scene project-file pairs pass, including all split narrow geometry/capture cases and four origin cases. Native artifact preparation passes using owned temporary storage. All four scene capture hashes equal their previously visually reviewed bytes. Original case deadlines, font floor, complete populations and network/Worker guards remain intact.
• Committed bun run check:pr --base origin/main passes all gates: 956 fast tests / 6,328 assertions, then 339 affected tests / 348,445 assertions and one snapshot, using actual --changed=7f22bb6ac2892360f3a5c4d3a1f93d9997af43e8. Full pending changeset package validation and release plan pass. This is local source proof; no complete current hosted confirmation is claimed.

Post-push REST base and independent live main agree at 7f22bb6ac2892360f3a5c4d3a1f93d9997af43e8. Immutable Git API and fetched synthetic merge agree: 85e4d51a24e9064c31cc5744c8ca939d037ad083, parents that base and current head, tree b891694436d65455162c208827f3bc86e73b3ee3 (identical to tested local source). This synthetic candidate remains unqualified by hosted proof; no new ready request or metadata BASE_SHA qualification exists. Earlier failed/cancelled run 39074479367 and SIGKILL/EDQUOT/setup receipts remain failed at their original identities.

#2365 and PR #2374 are still open; #2374 remains independently owned at bedb7ba0396df63c3d93a609e1143f1227ca464e. #2369 is now mergeable and remains draft with Refs #2228. Both issue and PR retain milestone 0.44.0. Parent must verify prerequisite delivery/ancestry/closure, reconcile the canonical dependency, reassess live base and REST/synthetic/metadata BASE_SHA, and request complete selected confirmation before matching-head merge and delivered-main reconciliation.

Custody of original claim p1-2228-20261017-b2fe22db returns to the parent campaign. Preserve its assignment, clean branch and worktree for authorized continuation. Parent owns watches and final merge; this worker created no child, watch, merge or change to another worker's branch.

Checklist

• Focused local preflight/behavioral receipts and complete selected hosted proof passed; actual head/base/job checkout evidence is in Proof.
• Acceptance implementation is covered; remaining verification is stated below.
• PR and issue release milestones read back as 0.44.0 (number 58); recheck before merge.
• Minor changeset included and names changed validation/origin behavior.
• Leakage/source gates passed on the candidate diff.
• Integration-contract component and public API report updated.
• Documentation reflects the change.
• Nothing on a provider turn path changed.

Anything left open

Blocked by #2365. PR #2374 remains independently owned and open. This PR stays draft with Refs #2228; no full confirmation is knowingly dispatched against the native self-test prerequisite. After delivery, verify issue closure and squash ancestry, reconcile the canonical dependency, assess/integrate the verified live base if needed, run required preflight, verify REST base and immutable synthetic merge parents against live main/current head and metadata BASE_SHA, then request complete selected candidate confirmation. Parent owns watches and merge, including milestone readbacks, actual job checkout/aggregate checks and delivered-main reconciliation. No acceptance criterion is dropped.

Delivered #2241, #2393 and #2388 are reconciled at the exact head/base/tree recorded above. Current local proof and unqualified synthetic identity are distinct from complete selected hosted confirmation. Parent retains dependency delivery and final merge custody.