Extend copy context past shared-UI wrappers and add maxContextLines option

[aidenybai]

Problem

Closes #471.

In large apps (especially shadcn/Next), grabbing a wrapper/layout-ish element produces a trace that points at a UI wrapper instead of the meaningful surface — "the useful context is a few levels around it." The context-extension introduced in #446 only helps when the wrapper chain is in node_modules: those frames are surfaced "for free" and don't spend the compact 3-line budget. But shadcn-style apps render through app-owned wrappers (components/ui/sidebar.tsx, a monorepo packages/ui, headless primitives), which do spend the budget, so the trace caps out before reaching the actual feature source.

There was also a broken contract: the CLI (init / configure / transform) already writes grab({ maxContextLines: N }) into users' code, but the library had maxContextLines removed as dead code (commits edb969ce / 87e71cd0). So the option was silently ignored — and would fail typecheck in typed configs. This PR re-wires it.

Fix

Two parts — a better default, plus the (now actually functional) opt-in.

Better default: treat shared-UI frames as low-signal

The budget logic now distinguishes "is app source" (for selector-hint suppression) from "consumes budget" (high-signal feature source). App-owned shared-UI / design-system frames — files under a ui/, design-system(s)/, or primitives/ segment — are detected by a new is-shared-ui-source-path util and treated like node_modules frames: still shown with their path, but exempt from the compact budget.

Because low-signal frames are still shown, the only effect of marking more frames as free is that the trace reaches deeper (bounded by the existing hard cap of 20). A plain leaf element stays compact; a wrapper-heavy element automatically digs through its UI primitives to the real surface — no config required.

Restored opt-in: maxContextLines

maxContextLines is re-added to Options and threaded from Options → plugin registry → copy flow and the getStackContext API, and parsed from the script data-options attribute. This makes the CLI's existing grab({ maxContextLines: N }) output actually take effect.

grab({ maxContextLines: 8 });

Changes

• utils/is-shared-ui-source-path.ts (+ SHARED_UI_SOURCE_PATH_SEGMENTS): segment-based detection of reusable UI directories.
• core/context.ts: StackFrameLine exposes isAppSource / consumesBudget; shared-UI app frames (and a shared-UI leading source) are free.
• core/copy.ts, core/index.tsx, core/plugin-registry.ts, types.ts, utils/get-script-options.ts: thread maxContextLines through.
• cli/commands/configure.ts: align the option description with its restored semantics.
• Docs: new "Context line budget" section in docs/architecture.md.

Testing

• New unit tests for isSharedUiSourcePath and budget behavior.
• build, typecheck, lint, react-grab unit tests (29), CLI tests (211), and element-context + selection Playwright suites (51) all pass.

Known follow-up (not in this PR)

Edit/CSS prompts (format-edit-prompt.ts) still emit only filePath:line + CSS, with no component/stack context — the issue's editPromptContext: "detailed" ask. Adding element context there could reduce "agent edits the wrong item," but it changes the carefully-tuned style prompt (#452), so it warrants a separate, deliberate change.

  

---

Summary by cubic

Extends copied stack context to dig past app-owned shared-UI/design-system wrappers and restores a hardened maxContextLines for deeper traces. Collapses consecutive duplicate lines and excludes Next’s app/ui from shared-UI detection; addresses #471.

• New Features

  • Treat shared-UI/design-system frames as low-signal: shown and deduped, but they don’t spend the compact budget; leading shared-UI sources are also free.
  • Narrow shared-UI detection to real primitives: matches components/ui/, packages/ui/, design-system(s)/, and primitives/; excludes bare ui/ so Next’s app/ui/* feature code isn’t misclassified.
  • Add maxContextLines to raise the soft budget; threaded through Options, plugin registry, copy flow, and getStackContext; settable via script data-options and at runtime via setOptions. Input is hardened (NaN/Infinity → default, negatives clamp to 0, fractions floor).

• Migration

  • Optional: set maxContextLines (e.g., 8–12) in init, setOptions, or script data-options to include more app-source lines in the copied context.

^{Written for commit 0e3f5b6. 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-storybook	Ready	Preview, Comment	Jun 18, 2026 7:43am
react-grab-website	Ready	Preview, Comment	Jun 18, 2026 7:43am

[pkg-pr-new]

Open in StackBlitz

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

npm i https://pkg.pr.new/grab@478

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

commit: 0e3f5b6