chore(website): flatten actors docs structure

[NathanFlurry]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-site	Error			Nov 15, 2025 2:22am
rivetkit-serverless	Error			Nov 15, 2025 2:22am

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 15, 2025 2:22am
rivet-inspector	Ignored	Preview		Nov 15, 2025 2:22am

[NathanFlurry]

• chore: create branch for v3 website changes on v2 #3304 : 2 dependent PRs (#3453 , #3472 )
• chore(website): flatten actors docs structure #3280 👈 (View in Graphite)
• chore(rivetkit): switch dynamic node imports to use require #3461 : 1 other dependent PR (#3455 )
• chore(rivetkit-typescript): remove dependency on node modules #3460
• feat(site): add typedoc docs #3446
• chore(rivetkit): remove deprecated packages #3447
• chore(rivetkit): add support for conn params on onRequest and onWebSocket #3445
• feat(rivetkit): add asyncapi spec #3442
• chore(rivetkit): add actor router to the openapi spec #3441
• fix(rivetkit): skip sending RivetKit messages to conns that do not support it #3440
• fix(rivetkit): fix race condition with websocket open events #3439
• fix(rivetkit): standardize error metadata return type #3438
• fix(rivetkit): remove incorrect getEndpoint call in metadata handler #3433 : 1 other dependent PR (#3451 )
• feat(rivetkit): add json protocol support #3432
• chore(rivetkit): add required zod validation for json encoding #3431
• chore(rivetkit): add listing actors by only name to manager api #3430
• refactor(rivetkit): extract WebSocket protocol parsing to shared utility #3429
• refactor(rivetkit): restructure connection lifecycle contexts #3428
• chore(rivetkit): add WebSocketContext and RequestContext #3427
• chore(rivetkit): add conn type #3426
• chore(rivetkit): add connection for raw http #3425
• chore(rivetkit): rename onFetch to onRequest #3424
• refactor(rivetkit): add state manager for conn with symbol-based access #3423
• fix(rivetkit): use loggerWithoutContext for websocket error when actor undefined #3412
• feat(rivetkit): add GET /actors/names #3411
• feat(api-public): expose actor kv api #3410
• chore(rivetkit): auto-generate inspector token for engine driver #3409
• chore(rivetkit): close websockets on out of sequence messages #3404
• fix(rivetkit): properly apply clientEndpoint from metadata lookup #3402
• fix(rivetkit): properly handle msgIndex for hibernatable websocket reconnection #3401
• chore(rivetkit): rename onstart/onstop to onwake/onsleep #3422
• chore(rivetkit): split ActorInstance logic in to multiple classes #3421
• chore(rivetkit): move conns to separate persisted kv keys #3420
• chore(rivetkit): remove deprecated conn tokens & sse support #3419
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Pull Request Review

Summary

This PR refactors the website marketing homepage and documentation structure by flattening the actors docs structure and enhancing the homepage with new sections showcasing use cases and deployment options.

Code Quality & Best Practices

Strengths

• Good component separation with dedicated UseCases and DeploymentOptionsSection components
• Proper TypeScript typing with interfaces
• Good responsive design with Tailwind classes
• Proper semantic HTML and accessibility

Issues Found

1. Typo in self-hosting/index.mdx line 6
applciations should be applications

2. Broken link in DeploymentOptionsSection.tsx line 69
/docs/general/self-hosting should be /docs/self-hosting based on sitemap

3. Grammar in HeroSection.tsx line 26
in to should be into (one word)

4. Commented code in HeroSection.tsx
Multiple blocks of commented hero copy (lines 30-86) should be removed

Potential Bugs

1. UseCases.tsx lines 135-142
Non-null assertions assume use cases exist. If missing, will throw runtime error. Add null checks.

2. UseCases.tsx handleMouseMove
Runs on every mousemove without throttling. Could cause performance issues with multiple cards.

Test Coverage

No tests included for new components. Consider adding unit tests and link validation tests.

Recommendations

High Priority:

1. Fix typo: applciations to applications
2. Fix broken link: /docs/general/self-hosting to /docs/self-hosting
3. Fix grammar: in to to into
4. Add null checks for use case lookups

Medium Priority:

1. Remove commented-out code
2. Add performance optimization for mouse tracking
3. Add tests

Overall Assessment

Solid refactoring with good code quality. Main issues are minor but should be fixed before merging.

Recommendation: Request changes for typo, broken link, and grammar fixes.

[claude]

PR Review: chore(website): flatten actors docs structure

I've reviewed this PR and found that while the PR title mentions "flatten actors docs structure", the changes are primarily focused on refactoring Node.js module imports in the rivetkit-typescript package to support cross-platform compatibility (likely for edge/browser environments). Here's my detailed feedback:

---

🔴 Critical Issues

1. Security Vulnerability: Timing-Safe Comparison Removed

Location: rivetkit-typescript/packages/rivetkit/src/inspector/utils.ts:23-28

The compareSecrets function has had its timing-safe comparison commented out:

// TODO:
// // Perform timing-safe comparison
// if (!crypto.timingSafeEqual(a, b)) {
// 	return false;
// }
return true;  // This always returns true now!

Impact: This is a critical security vulnerability. The function now always returns true regardless of whether the secrets match, effectively disabling authentication for the inspector endpoint.

Recommendation:

• Either implement a timing-safe comparison without Node.js crypto (using a constant-time comparison loop)
• Or dynamically import and use crypto.timingSafeEqual when available
• Do not merge this PR until this is fixed

Example fix:

export function compareSecrets(providedSecret: string, validSecret: string) {
    if (providedSecret.length !== validSecret.length) {
        return false;
    }
    
    const encoder = new TextEncoder();
    const a = encoder.encode(providedSecret);
    const b = encoder.encode(validSecret);
    
    // Constant-time comparison
    let result = 0;
    for (let i = 0; i < a.length; i++) {
        result |= a[i] ^ b[i];
    }
    return result === 0;
}

---

⚠️ High Priority Issues

2. Error Handling in Dynamic Imports

Location: rivetkit-typescript/packages/rivetkit/src/utils/node.ts:51-58

The error handling logs a warning but doesn't provide guidance on when this is expected vs. problematic:

} catch (err) {
    console.warn(
        "Node.js modules not available, file system driver will not work",
        err,
    );
    throw err;
}

Issues:

• Uses console.warn then immediately throws - this is confusing
• Should use the structured logging pattern from the codebase (tracing)
• Per CLAUDE.md: "Use tracing for logging. Do not format parameters into the main message"

Recommendation:

} catch (err) {
    // Don't warn if in browser/edge environment where this is expected
    throw new Error(
        "Node.js modules not available. File system driver requires Node.js runtime."
    );
}

3. Async Function Not Awaited

Location: rivetkit-typescript/packages/rivetkit/src/registry/mod.ts:209-214

The server start is added to readyPromises but wrapped in an IIFE that may not be awaited correctly:

if (!config.disableDefaultServer) {
    const serverPromise = (async () => {
        const out = await crossPlatformServe(config, hono, undefined);
        upgradeWebSocket = out.upgradeWebSocket;
    })();
    readyPromises.push(serverPromise);
}

Issue: The upgradeWebSocket assignment happens asynchronously but is used synchronously later. This is a potential race condition.

Recommendation: Ensure this promise is properly awaited before the registry is considered "ready".

---

📝 Code Quality Issues

4. Missing Type Safety

Location: rivetkit-typescript/packages/rivetkit/src/registry/serve.ts:13-26

Dynamic imports use any type:

let serve: any;

Recommendation: Add proper type assertions or import types separately.

5. Inconsistent Error Messages

Location: Multiple getNode* functions in src/utils/node.ts

All getter functions have identical error messages. They should specify which module failed:

export function getNodeCrypto(): typeof import("node:crypto") {
    if (!nodeCrypto) {
        throw new Error(
            "Node crypto module not loaded. Ensure importNodeDependencies() has been called.",
        );
    }
    return nodeCrypto;
}

This is good, but could be even better with context about where the call originated.

6. Commented Out Code

Location: rivetkit-typescript/packages/rivetkit/src/inspector/utils.ts:1

// import crypto from "node:crypto";

Recommendation: Remove commented-out imports rather than leaving them in.

7. Unexplained Comment

Location: rivetkit-typescript/packages/rivetkit/src/engine-process/mod.ts:254

}
//
function resolveTargetTriplet(): { targetTriplet: string; extension: string } {

Random comment should be removed.

---

✅ Positive Changes

1. Good abstraction pattern - The Node.js module abstraction in utils/node.ts is well-structured with:

   • Singleton pattern for imports
   • Clear error messages
   • Proper TypeScript typing for return values
   • Availability checking function

2. Webpack ignore comments - Properly using /* webpackIgnore: true */ to prevent bundling of Node.js modules

3. Proper async/await propagation - Most functions correctly changed to async (e.g., createFileSystemDriver, chooseDefaultDriver)

4. Test updates - Tests properly updated to await the now-async driver creation functions

---

🤔 Questions

1. PR Title Mismatch: The PR is titled "flatten actors docs structure" but the majority of changes are about Node.js module abstraction. Are these unrelated changes bundled together, or is the title incorrect?

2. Website Changes: There are extensive website changes (new SVG icons, component updates) that seem unrelated to the rivetkit changes. Should these be in a separate PR?

3. Biome Configuration: The biome.json changes add extensive import restrictions for Node.js modules. Is this related to the same refactoring effort?

---

📊 Summary

Do Not Merge until the critical security issue (#1) is resolved.

Stats:

• 42 files changed
• 984 additions, 348 deletions
• Mix of infrastructure, security, and website changes

Priority Fixes:

1. 🔴 Fix compareSecrets security vulnerability (CRITICAL)
2. ⚠️ Fix error handling in importNodeDependencies
3. ⚠️ Verify upgradeWebSocket race condition
4. 📝 Clean up commented code and improve type safety

Let me know if you'd like me to elaborate on any of these points or if you need help implementing the fixes!

[claude]

PR Review: Flatten Actors Docs Structure

Summary

This PR updates the Rivet website marketing pages and documentation structure. While the PR title mentions "flatten actors docs structure," the changes are primarily focused on enhancing the marketing homepage with new sections and visual improvements.

---

Code Quality & Best Practices

✅ Strengths

• Good component modularity: New sections like DeploymentOptionsSection and UseCases are well-structured
• Consistent styling: Uses the existing design system with proper Tailwind classes
• Type safety: TypeScript interfaces are properly defined
• Accessibility: Links include proper rel="noopener noreferrer" for external links

⚠️ Issues Found

1. Typo in Documentation (website/src/content/docs/self-hosting/index.mdx:6)

• "applciations" should be "applications"

2. Broken Documentation Link (website/src/app/(v2)/(marketing)/(index)/sections/DeploymentOptionsSection.tsx:69)

• Link points to /docs/general/self-hosting but should be /docs/self-hosting based on the sitemap changes

3. Non-Existent Icon Paths in UseCases Component (website/src/app/(v2)/(marketing)/(index)/sections/UseCases.tsx:145-156)

• Component references icon paths like /use-case-icons/sparkles.svg, but these files are not added in this PR
• Only icons in /images/raw-icon-svgs/ were added

4. Commented Out Code (website/src/app/(v2)/(marketing)/(index)/page.tsx:36-38)

• Consider removing commented-out code or documenting why it is being kept

---

Performance Considerations

Mouse Move Handler in UseCases (website/src/app/(v2)/(marketing)/(index)/sections/UseCases.tsx:27-45)

• The handleMouseMove function queries the DOM on every mouse move event
• Consider using requestAnimationFrame for smoother performance and throttling updates

---

Security Concerns

✅ No security issues identified. External links properly use target="_blank" with rel="noopener noreferrer".

---

Testing

Missing Tests
This is a frontend PR with no test coverage. Consider adding:

• Component tests for new sections
• Visual regression tests for the homepage changes
• Link validation tests to catch broken documentation links

---

Other Observations

1. PR Title Mismatch
The PR is titled "flatten actors docs structure," but the actual docs structure changes are minimal (just removing /docs/api from the sitemap). The bulk of changes are marketing page enhancements.

2. Large Sitemap Changes
The sitemap reorganization is significant but appears well-structured. The new hierarchy makes sense with clear groupings.

3. Icon Management
Multiple icon SVG files were added to /images/raw-icon-svgs/. These should be optimized with SVGO if not already done.

---

Recommendations

High Priority:

1. Fix the typo in self-hosting/index.mdx
2. Fix the broken link in DeploymentOptionsSection.tsx
3. Resolve the icon path mismatch in UseCases.tsx

Medium Priority:
4. Optimize the mouse move handler for better performance
5. Remove commented-out code or document its purpose
6. Update PR title to match actual changes

Low Priority:
7. Add component tests
8. Consider icon optimization strategy

---

Verdict

The code quality is generally good with proper TypeScript usage and component structure. However, there are a few critical issues (broken link, icon path mismatch, typo) that should be addressed before merging. Once these are fixed, this will be a solid enhancement to the marketing pages.

[claude]

PR Review: Website Homepage Restructuring

Summary

This PR restructures the marketing website homepage with new sections for use cases and deployment options. The changes focus on improving the presentation of Rivet's capabilities and deployment flexibility.

Code Quality & Best Practices ✅

Strengths

1. Component Structure: Good separation of concerns with well-defined component boundaries
2. TypeScript Usage: Proper typing with interfaces like DeploymentOptionProps and UseCaseCardProps
3. Accessibility: Uses semantic HTML with proper heading hierarchy and ARIA-compliant markup
4. Responsive Design: Thoughtful grid layouts with responsive breakpoints

Suggestions for Improvement

1. Typo in HeroSection.tsx:26

Line 26 has "in to" which should be "into" (one word):

Rivet Actors merge state and compute into a primitive

2. Duplicate Use Case Definitions in use-cases.ts

The useCases array has duplicate entries:

• Lines 23-28: "AI Agent"
• Lines 90-96: "Agent Orchestration & MCP" (same href: /docs/use-cases/ai-agent)
• Lines 63-69: "Multiplayer Game"
• Lines 97-103: "Multiplayer Apps" (same href: /docs/use-cases/game)

Recommendation: Remove duplicates and consolidate to single, well-named entries.

3. IconWithSpotlight Component - Hardcoded SVG Paths

The getPathData() function at IconWithSpotlight.tsx:7-32 has massive inline SVG path strings. This makes the code hard to read and maintain, increases bundle size, and violates DRY principle.

Recommendation: Import the SVG files directly or extract paths to a separate constants file.

4. UseCases.tsx - Non-null Assertions

Lines 135-141 use non-null assertions (!) which can throw runtime errors if use cases are renamed/removed. Add error handling or use a safer lookup pattern with filtering.

5. Commented-Out Code Cleanup

Multiple files have large blocks of commented code:

• HeroSection.tsx (lines 17-19, 30-86, 91-114)
• page.tsx (line 18, 36-38, 52-54)

Recommendation: Remove commented code before merging.

Performance Considerations ⚡

1. Mouse Move Handler Performance

UseCases.tsx:27-45 implements a handleMouseMove handler that queries the DOM on every mouse move. Consider adding throttling/debouncing for better performance (target ~60fps).

2. Large SVG Path Data

The inline SVG paths in IconWithSpotlight are substantial. Consider using SVG sprites, lazy loading icons, or tree-shaking unused icon paths.

Security Concerns 🔒

✅ External links properly use rel="noopener noreferrer" and target="_blank"
✅ No XSS vulnerabilities detected - all content is static or properly escaped through React JSX

Test Coverage 🧪

Missing: No test files included in this PR.

Recommendations:

1. Add component tests for UseCases, DeploymentOptionsSection
2. Test the mouse move spotlight effect
3. Verify responsive breakpoints
4. Test accessibility with screen readers
5. Validate all internal links resolve correctly

Additional Observations

• ✅ Updated llms-full.txt with clarification about self-hosting vs deployment
• ⚠️ Removed /docs/api from llms.txt - ensure this is intentional
• The hero headline changed messaging - ensure marketing stakeholders have approved this

Summary

Approval Status: ✅ Approve with minor changes recommended

This is a solid PR that improves the website structure and content presentation. The main issues are:

1. Code cleanliness (remove commented code, fix typos)
2. Data integrity (remove duplicate use cases)
3. Maintainability (refactor hardcoded SVG paths)
4. Safety (handle null cases in use case lookups)

None of these issues are blocking, but addressing them will improve code quality and prevent future bugs.

---

🤖 Generated with Claude Code

[claude]

PR Review: Website Marketing Page Updates

Overview

This PR updates the website's marketing homepage with new sections, improved messaging, and better content organization. The title mentions 'flatten actors docs structure' but the changes are primarily focused on the marketing homepage redesign.

Summary of Changes

• New sections added: DeploymentOptionsSection, UseCases section
• Hero section redesign: New tagline 'State + Compute = Less Complexity'
• Content restructuring: Reordered sections for better flow
• Documentation updates: Added clarification about self-hosting vs deployment
• Assets: Added 7 new icon SVG files for use cases

---

Code Quality

Strengths

1. Component Structure: Good separation of concerns with dedicated components
2. TypeScript Types: Proper interface definitions
3. Accessibility: Links include proper rel attributes for external links
4. Responsive Design: Grid layouts with responsive breakpoints
5. Code Organization: Icons properly centralized in IconWithSpotlight component

Issues Found

1. Typo in Documentation (website/src/content/docs/self-hosting/index.mdx:6)

• Fix: 'applciations' should be 'applications'

2. Non-null Assertion Operator Overuse (UseCases.tsx:135-141)

• Risk: If any use case is not found, this will throw a runtime error
• Recommendation: Add defensive checks to handle missing use cases gracefully

3. Commented Code Bloat (HeroSection.tsx)

• Lines 17-86 contain extensive commented-out code
• Recommendation: Remove or move to separate documentation file

4. Mouse event handler performance (UseCases.tsx:27-45)

• Issue: DOM queries on every mousemove event can cause performance issues
• Recommendation: Cache the icon container reference using useRef

5. Inconsistent Icon Path Pattern

• Some icons use /icons/ prefix while others use /use-case-icons/
• Consider standardizing the path structure

---

Security

✅ No critical issues found

• External links properly use target='_blank' with rel='noopener noreferrer'
• No user-generated content rendered without sanitization

---

Test Coverage

⚠️ Missing tests for new components. Consider adding tests for:

1. Component rendering
2. Icon mapping
3. Responsive behavior
4. Accessibility

---

Summary

Overall Assessment: ✅ Approve with minor changes recommended

Must Fix Before Merge:

1. Fix typo: 'applciations' → 'applications'
2. Add defensive checks for .find() operations to prevent runtime errors

Should Fix (can be follow-up PR):
3. Optimize mouse event handler performance
4. Remove commented code bloat
5. Add test coverage
6. Update PR title to match actual changes

Great work on improving the marketing page! The new sections provide much clearer guidance for users on deployment options.

[claude]

PR Review: Website Marketing Page Enhancements

This PR enhances the Rivet website's marketing homepage with new sections showcasing deployment options and use cases.

Code Quality - Strengths

• Clean component structure with proper TypeScript typing
• Good separation of concerns
• Consistent use of Tailwind CSS classes
• Proper use of React hooks and accessibility considerations

Potential Bugs & Issues

1. Duplicate Use Cases in use-cases.ts - Lines 91-96 and 98-103 contain duplicates that point to the same hrefs
2. Type Safety Issue - Non-null assertions in UseCases.tsx could throw runtime errors if titles change
3. Typo in llms-full.txt:6163 - applciations should be applications
4. Missing Error Handling - Empty string defaults in icon path functions not handled gracefully

Performance Considerations

• Mouse move handler queries DOM on every move - consider throttling/debouncing
• Multiple SVG elements with complex paths - monitor bundle size

Recommendations

High Priority:

1. Fix typo: applciations to applications
2. Handle potential null cases in use case lookups
3. Deduplicate use cases in use-cases.ts

Medium Priority:
4. Add error boundaries around new components
5. Optimize mouse move handlers
6. Clean up commented code in HeroSection.tsx

Low Priority:
7. Add unit tests for new components
8. Centralize icon path mappings

Summary

Solid frontend enhancement with clean code and good UX. Main concerns are data duplication, potential runtime errors, and the typo. With high-priority fixes, this should be ready to merge.

Recommendation: Approve with minor changes requested

[claude]

PR Review: Website Documentation Structure Flattening

Summary

This PR updates the marketing website homepage with new sections and content reorganization.

---

Code Quality & Best Practices ✅

Strengths:

• Clean React component architecture
• Good TypeScript usage
• Proper Next.js Link components
• Responsive design with Tailwind

Areas for Improvement:

1. Typo in self-hosting/index.mdx:6

   • applciations → applications

2. Grammar in HeroSection.tsx:26

   • in to → into

3. Non-null Assertions in UseCases.tsx:135-142
   Using ! assumes find() will always succeed. Could throw at runtime.

4. Duplicate Use Cases in use-cases.ts

   • AI Agent vs Agent Orchestration & MCP
   • Multiplayer Game vs Multiplayer Apps

---

Potential Bugs 🐛

1. Non-null assertions could cause runtime errors if titles change
2. Empty string fallback for missing icons needs handling

---

Security ✅

• External links properly secured with rel="noopener noreferrer"
• No XSS risks detected

---

Test Coverage 🧪

No tests added. Consider:

• Visual regression tests
• Unit tests for use case filtering
• Link resolution tests

---

Recommendations

High Priority:

• Fix typo: applciations → applications
• Fix grammar: in to → into
• Add null-safety to use case filtering

Medium Priority:

• Consolidate duplicate use cases
• Remove commented code
• Add ARIA labels

---

Conclusion

Solid PR with good code quality. Minor typos and potential runtime errors need addressing.

Overall: ✅ Approve with minor changes requested