Add React/Next frontend reference architecture

[punk6529]

Summary

Closes #402.

This PR adds the INT-007 React/Next frontend reference architecture as a docs-only integration slice. It gives 6529.io-style frontend teams a conservative architecture for consuming release artifacts, address books, ABIs, event catalogs, metadata, wallet state, transactions, and indexer data without adding a maintained frontend app package or generated SDK to this contracts repo.

What changed

• Added docs/integrations/frontend-reference-architecture.md covering maturity boundaries, source-of-truth artifacts, artifact import flow, environment separation, client layering, query/cache boundaries, transaction orchestration, wallet/signature handling, metadata rendering, indexer reconciliation, telemetry, security/no-secret handling, and testing strategy.
• Added docs/integrations/examples/react-viem.md with non-runnable pseudocode for artifact loading, contract clients, query keys, transaction orchestration, public env guards, and event-driven invalidation.
• Added scripts/check_react_next_reference.py and scripts/test_react_next_reference.py to keep the guide traceable.
• Wired the new check into CI, make check, scripts/check.sh, scripts/check.ps1, integration README checks, release-readiness checks, release-manifest generation, and release artifacts docs.
• Refreshed release-artifacts/latest/ risk-register, release-manifest, bytecode-proof, and checksum outputs.
• Reconciled autonomous/backlog state after PR [codex] Add metadata rendering integration guide #401 and recorded the current StreamCore bytecode posture: materially improved from the old EIP-170 blocker, but still below the 512-byte warning threshold.

Maturity and non-goals

This remains a pre-audit local baseline. It is not production-ready and is not a security claim. The new guide does not add React, Next, viem, wagmi, TanStack Query, WalletConnect, Electron, mobile packages, a reference app, or a generated SDK. It also explicitly excludes private keys, signer-service credentials, admin credentials, privileged RPC credentials, raw signatures, and unreleased payloads from browser and NEXT_PUBLIC_* configuration.

Local validation

• python -m py_compile scripts/check_react_next_reference.py scripts/test_react_next_reference.py scripts/check_integrations_readme.py scripts/test_integrations_readme.py scripts/check_release_readiness.py scripts/test_release_readiness.py scripts/generate_release_manifest.py scripts/test_release_manifest.py
• python scripts/test_react_next_reference.py
• python scripts/check_react_next_reference.py
• python scripts/test_integrations_readme.py
• python scripts/check_integrations_readme.py
• python scripts/test_release_readiness.py
• python scripts/check_release_readiness.py
• python scripts/test_release_manifest.py
• python scripts/generate_release_manifest.py --check
• python scripts/test_bytecode_release_proof.py
• python scripts/generate_bytecode_release_proof.py --check
• python scripts/test_release_checksums.py
• python scripts/generate_release_checksums.py --check
• python scripts/check_changelog.py
• make react-next-reference-check
• bash -n scripts/check.sh
• PowerShell parser check for scripts/check.ps1
• git diff --check (only the normal Windows line-ending warning for scripts/check.ps1)
• make check
• powershell -ExecutionPolicy Bypass -File scripts\check.ps1

Notes

The Foundry gates continue to emit the existing warning noise already present on main (for example selfdestruct in tests and known parser warnings during deployment rehearsal traces). No Solidity code changes are included.

[coderabbitai]

Warning

Review limit reached

@punk6529, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 48 minutes and 32 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e72be126-b2a6-4026-8240-607160cbc271

📥 Commits

Reviewing files that changed from the base of the PR and between 642c552 and 4c6416a.

📒 Files selected for processing (25)

• .github/workflows/ci.yml
• CHANGELOG.md
• Makefile
• docs/integrations/README.md
• docs/integrations/examples/react-viem.md
• docs/integrations/frontend-reference-architecture.md
• docs/release-readiness.md
• ops/AUTONOMOUS_RUN.md
• ops/EXECUTION_BACKLOG.md
• release-artifacts/README.md
• release-artifacts/latest/SHA256SUMS
• release-artifacts/latest/bytecode-release-proof.json
• release-artifacts/latest/release-checksums.json
• release-artifacts/latest/release-manifest.json
• release-artifacts/latest/risk-register.json
• scripts/check.ps1
• scripts/check.sh
• scripts/check_integrations_readme.py
• scripts/check_react_next_reference.py
• scripts/check_release_readiness.py
• scripts/generate_release_manifest.py
• scripts/test_integrations_readme.py
• scripts/test_react_next_reference.py
• scripts/test_release_manifest.py
• scripts/test_release_readiness.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/react-next-reference-architecture

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[punk6529]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[6529bot]

6529bot crypto security analysis - 79e2c82

Verdict: No security findings.

This PR is documentation and tooling only: a new React/Next reference architecture guide, pseudocode examples, a Python checker/test pair, CI/Makefile wiring, and regenerated release-artifact hashes. No Solidity, signing logic, auth flow, or runtime web3 code is changed.

I reviewed the wallet/signature, transaction, secret-handling, and metadata-rendering guidance for incorrect security advice that could propagate to integrators, and the guidance is sound:

• assertNoSecretsInPublicEnv + NEXT_PUBLIC_* boundary and server-only field separation are correct (docs/integrations/examples/react-viem.md:107-127, docs/integrations/frontend-reference-architecture.md Environment/Security sections).
• Chain-id/domain/address-book mismatch is required to halt before any signature or tx prompt; replay protection is explicitly attributed to on-chain consumed/cancelled/signer-epoch state rather than EIP-712 encoding alone (frontend-reference-architecture.md Wallet And Signature Boundaries).
• DropAuthorization/tokenData immutability, read-after-event reconciliation, confirmation depth, and reorg handling are stated correctly.
• Animation animation_url is treated as untrusted with sandboxed iframe isolation from wallet/storage state; allow-scripts is scoped to the sandbox boundary.
• The checker's normalize_repo_path rejects path escapes and link-label/target mismatches, which is a reasonable guard for the doc tooling.

The regenerated release-manifest.json, bytecode-release-proof.json, release-checksums.json, SHA256SUMS, and risk-register.json hashes are internally consistent with the new doc sizes (e.g. release-manifest 95458→95865 bytes reflected everywhere it is referenced). No hardcoded mainnet addresses or secret-shaped values were introduced.

No realistic exploit path exists in the changed code.

[6529bot]

6529bot general PR review - 79e2c82

Verdict: Good to merge

This is a documentation-only PR (new INT-007 guide plus checker/test scaffolding and regenerated release artifacts). No production code, contract logic, or runtime behavior is changed. The checker/test wiring follows the established INT-00x pattern, and the regenerated manifest/checksum/risk-register hashes are internally consistent (release-manifest size 95458→95865, matching the new doc entries and the SHA256SUMS/release-checksums/bytecode-proof updates).

Nice-to-have

• docs/integrations/examples/react-viem.md:142 — The assertNoSecretsInPublicEnv pseudocode uses key.includes(marker), but the loop only inspects keys already prefixed with NEXT_PUBLIC_. None of the forbidden markers (e.g. PRIVATE_KEY, MNEMONIC) carry that prefix, so as written this guard never matches a realistic NEXT_PUBLIC_* variable and silently passes. Since readers may copy this shape, consider stripping the prefix before matching (e.g. check key.slice("NEXT_PUBLIC_".length)) or matching on the suffix, so the illustrative guard actually demonstrates the intended behavior.

• scripts/check_react_next_reference.py:REQUIRED_PHRASES — The phrase list is large and brittle (e.g. "signed \DropAuthorization` fields", "bytecode-to-release proof"`). This is consistent with prior INT guides, so not a blocker, but each exact-substring requirement is a future maintenance trap when the doc is reworded. Not introduced by this PR alone; flagging only as a pattern note.

No correctness, security, or data-integrity issues found in the changed surface.

[6529bot]

6529bot follow-up commit review - 4c6416a

Verdict: No new findings

Resolved since last review

• docs/integrations/examples/react-viem.md:142 — The prior nice-to-have about assertNoSecretsInPublicEnv using key.includes(marker) against the still-prefixed key is fixed. The guard now strips the prefix (const publicName = key.slice("NEXT_PUBLIC_".length)) and matches on publicName, so the illustrative check behaves as intended.

The remaining changes (manifest/checksum/risk-register hash regeneration to 95865 bytes, CI/Makefile/wrapper wiring for react-next-reference-check, and the checker's REQUIRED_PHRASES updated for the new prefix-stripping example) are internally consistent and follow the established INT-00x pattern. No new correctness, security, or data-integrity issues in the changed surface.