RFC: Composable Architecture — The "Android" of React Grab

[aidenybai]

Summary

An architectural RFC proposing how to make React Grab fully composable and hackable — every layer replaceable, from the copy pipeline to the UI overlay.

The Problem

React Grab today is polished and opinionated but the walls are high:

• Monolithic init() (~4,200 lines) wires store, plugins, events, copy, and renderer in one shot
• Fixed Solid.js overlay — can't replace toolbar, labels, or go headless
• Single instance (hasInited singleton)
• Hooks-based plugin system can observe/transform, but can't restructure flows
• Core primitives (element detection, bounds, fiber walking) are locked inside init()

Proposed Architecture

Kernel + Userland split:

• Kernel (react-grab/kernel): Fiber introspection, element detection, bounds calculation, DOM freeze, clipboard — the hard stuff that stays opinionated
• Userland (react-grab/modules): Copy pipeline, overlay, toolbar, context menu, history, agent bridge — all swappable

Key concepts:

1. Everything is a Module — createGrab({ modules: [...] }) replaces monolithic init()
2. Typed Event Bus — replaces ad-hoc hook calling with discoverable, interceptable, pipeline-native events
3. Middleware for Pipelines — Express/Koa-style use() for the copy flow and other pipelines
4. Headless Mode & Renderer Injection — UI is optional and replaceable
5. Multi-Instance & Scoping — remove the singleton, allow per-subtree configs
6. Backwards Compatible — init() becomes createGrab(defaultPreset(options))

Migration Path

1. Extract kernel primitives from init() without changing public API
2. Expose react-grab/kernel for power users
3. Add react-grab/modules and createGrab()
4. Community builds modules (custom renderers, copy formats, integrations)

What This Unlocks

Plugin authors can replace entire pipelines, not just hook into them. Enterprise users can scope configs, add company-specific formats, build compliance plugins. The core team gets faster iteration, easier testing, and smaller bundles via tree-shaking.

See RFC-COMPOSABLE-ARCHITECTURE.md for the full proposal including API examples, event bus design, module contract, and open questions.

  

---

Summary by cubic

Adds an RFC proposing a composable architecture for React Grab with a react-grab/kernel + react-grab/modules split and a typed event bus. It enables middleware-based pipelines, headless or custom renderers, multi-instance scoping, and keeps init() working via presets.

• Migration
  • Phase 1: Extract kernel primitives from init() without breaking the API.
  • Phase 2: Expose react-grab/kernel for low-level access.
  • Phase 3: Add createGrab() and map plugins to modules in react-grab/modules.
  • Phase 4: Ship presets and support community modules.

^{Written for commit eacc1ce. Summary will update on new commits.}

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
react-grab-website	Ready	Preview, Comment	Mar 20, 2026 10:42am

[pkg-pr-new]

Open in StackBlitz

@react-grab/cli

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/cli@258

grab

npm i https://pkg.pr.new/aidenybai/react-grab/grab@258

@react-grab/amp

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/amp@258

@react-grab/claude-code

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/claude-code@258

@react-grab/codex

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/codex@258

@react-grab/copilot

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/copilot@258

@react-grab/cursor

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/cursor@258

@react-grab/droid

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/droid@258

@react-grab/gemini

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/gemini@258

@react-grab/opencode

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/opencode@258

react-grab

npm i https://pkg.pr.new/aidenybai/react-grab@258

@react-grab/relay

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/relay@258

@react-grab/utils

npm i https://pkg.pr.new/aidenybai/react-grab/@react-grab/utils@258

commit: eacc1ce