`@spotpatch/next`

English

Warning

This package is a 0.x public preview, not a formally supported Next.js integration. Its peer dependency range must not be interpreted as a completed compatibility or production-support claim.

The preview connects SpotPatch's element picker, source-aware context, evidence-first component data flow, bilingual multi-target requests, and optional review-gated AI Agent to a Next.js development server.

Component dataFlow uses the same compiler, analyzer, recorder, merger, protocol, and panel as Vite; Next owns only the bundler and Sidecar integration. Browser Client Components support the fetch, Axios, React Query/TanStack Query, and experimental tRPC evidence described by the shared Beta guide. RSC, Server Actions, and Route Handlers can contribute statically proven declared-not-observed evidence, but their server-side dispatch is not observable in the browser.

Implemented preview path

withSpotPatch() composes an existing next.config without evaluating it twice.
spotpatch-next dev owns the loopback-only Next child process and Sidecar lifecycle.
Development-only Turbopack and webpack Loader paths atomically register source/data-flow anchors, inject JSX/TSX markers, and instrument eligible browser .js/.jsx/.ts/.tsx modules.
@spotpatch/next/client installs the React hook and dispatch-only data-flow prelude from instrumentation-client, then bootstraps one Runtime and the shared data-flow panel.
Private API rewrites use a randomized loopback Sidecar origin and per-launch secrets.
Production configuration aliases both browser entries to a side-effect-free no-op and does not add the Loader, recorder, panel, Sidecar, source registry, or private rewrite.
spotpatch-next init previews and applies supported integration edits with rollback on failure.
spotpatch-next init also initializes a private, revocable project grant for isolated snapshot writes and audited/validated application. Use spotpatch-next bridge init on an already-integrated project to leave integration files unchanged. No later dev-terminal yes prompt is needed; Codex login and compatibility checks still apply.
spotpatch-next check diagnoses the package graph and generated integration without starting development.

Public preview integration

Install the single framework entry package. Its required SpotPatch internal packages are resolved automatically; do not install them individually.

pnpm add --save-dev @spotpatch/next
pnpm exec spotpatch-next init
pnpm exec spotpatch-next check
pnpm dev

The supported initializer result has three parts. The TypeScript example below enables the in-page Review / Trusted direct selector and preserves the discovered TypeScript check for Review; a JavaScript-only project remains on withSpotPatch() and review mode. Trusted direct itself does not expose run_check or run project checks.

// next.config.ts
import type { NextConfig } from "next";
import { withSpotPatch } from "@spotpatch/next";

const nextConfig: NextConfig = {};

export default withSpotPatch({
  dataFlow: {},
  trustedFastMode: true,
})(nextConfig);

// instrumentation-client.ts
// Use src/instrumentation-client.ts when the router lives under src.
import "@spotpatch/next/client";

{
  "scripts": {
    "dev": "spotpatch-next dev"
  }
}

Start development through the package script, not a direct next dev command. A successful startup prints one line beginning with [spotpatch:next] ready; the page then mounts one spotpatch-root Shadow DOM host with the Select element / 选择元素 action.

External Agent handoff (local validation)

Enable the development-only handoff UI explicitly in the same wrapper options:

export default withSpotPatch({ externalAgent: true })(nextConfig);

Run setup and active commands from the exact canonical project root that owns the running spotpatch-next dev session. Setup is a dry run without --write:

pnpm exec spotpatch-next bridge setup --client claude --scope project --mode active --write
MCP_PROTOCOL_NEGOTIATION=legacy claude --dangerously-load-development-channels server:spotpatch

pnpm exec spotpatch-next connect codex --allow-workspace-write

pnpm exec spotpatch-next bridge setup --client cursor --scope project --write

The active command forms support an explicit session when bridge sessions --json reports multiple sessions for that exact root:

spotpatch-next bridge channel claude [--session <opaque-id>]
spotpatch-next connect codex --allow-workspace-write [--session <opaque-id>]

The Claude legacy environment belongs on the Claude host process. Claude Channels are a Research Preview, work only while the Channel-enabled session is running, and provide no completion acknowledgement; completion depends on Claude calling the SpotPatch result tool. Codex active mode is zero-setup: the Connector injects the project-local SpotPatch MCP entry into its App Server thread and does not create or modify .codex/config.toml. Codex can still load other MCP servers already enabled by the user's normal Codex configuration. Stable Codex versions from 0.149.0 onward must pass per-executable generated-schema validation plus the live protocol and security preflight; SpotPatch does not install or update Codex. bridge setup --client codex ... remains available only for optional Inbox use; Cursor and all generic MCP hosts remain Inbox-only.

This path is local-validation, not part of the Next public-support promise. Automated fake-host and two-handoff tests exist, and a consecutive two-revision Codex flow has been manually validated on the recorded macOS/Next.js/Codex 0.149.0 environment. Real Claude Code consecutive delivery, repeatable real-host automation, and Windows process-tree cleanup remain not-tested; Cursor remains Inbox-only. See the external Agent design and exact status.

Current evidence and remaining gates

The public preview has passed:

package build, type publication, Publint, and Are The Types Wrong checks;
formal unit and HTTP boundary tests;
a locked Loader POC covering selected Next 15/React 18 and Next 16/React 19 combinations;
one private Next 16 App Router host with Turbopack and webpack development startup;
authenticated Runtime bootstrap, source registration, source-context lookup, and Runtime singleton checks in that host;
shared data-flow compiler/runtime/HTTP unit gates, atomic Next registration, React 19 registration-only identity policy, cross-module renderer discovery, and browser/server Loader partitioning;
one packed Next 16 App Router/Turbopack browser report showing direct fetch plus Axios/TanStack Query transitive static evidence;
one packed Next 16 App Router webpack development build preserving "use client" and excluding .next/node_modules before the Loader;
Turbopack and webpack Fast Refresh in the private Runtime POC;
webpack production isolation in the private host;
a clean packed Next 16 App Router/Turbopack production build/start with page 200, private bootstrap 404, and no executable SpotPatch data-flow residue in business output.

Formal public support remains blocked on the complete required Next/React/router/Node/OS matrix, Pages and hybrid router coverage, broader RSC navigation cases, a final React 19 identity browser recheck, complex rewrite/base path fixtures, and webpack/Turbopack production scans for Pages, standalone, static export, and multiple operating systems.

Read the implementation status and required release matrix before drawing compatibility conclusions.

Declared peer range

Dependency	Package range	What it means
Node.js	`>=20.19.0`	Package engine requirement.
Next.js	`>=15.3.0 <17.0.0`	Candidate range for the preview matrix, not a support guarantee.
React / React DOM	`^18.2.0` or `^19.0.0`	Installable candidate range; React 19 Fiber semantics still degrade in controlled cases.

The first preview accepts only loopback development hosts and rejects allowLan: true. Complex CommonJS next.config files, mixed root/src routers, conflicting Loader rules, and conflicting private-prefix rewrites fail closed or require manual integration.

Production behavior

Use ordinary Next.js production commands:

pnpm exec next build
pnpm exec next start

spotpatch-next intentionally proxies only dev. Production use is not supported by the 0.x preview; validation must continue proving that production output contains no data-spotpatch-source, spotpatch-root, Runtime bootstrap state, private API prefix, or internal configuration and registration secrets.

Hydration warning from browser extensions

If React reports only a removed body attribute such as cz-shortcut-listen="true", a browser extension changed the document before hydration. That warning is independent of SpotPatch initialization; test in a clean browser profile before treating it as an adapter defect.

简体中文

Warning

本包是 0.x 公共预览版，不是正式支持的 Next.js 接入。peer dependency 范围不能解释成兼容矩阵或生产支持已经完成。

当前预览把 SpotPatch 的元素选择、源码上下文、证据优先的组件数据链路、中英文多目标修改要求和可选审阅式 AI Agent 接入 Next.js 开发服务器。

组件 dataFlow 复用 Vite 的同一 compiler、analyzer、recorder、merger、协议和面板；Next 只承载构建器与 Sidecar。浏览器 Client Component 支持共享 Beta 指南列出的 fetch、Axios、React Query/TanStack Query 和实验性 tRPC 证据；RSC、Server Action、Route Handler 只能提供静态可证明的 declared-not-observed 关系，浏览器不能观测其服务端 dispatch。

已实现的预览链路

withSpotPatch() 组合现有 next.config，不会重复执行宿主配置。
spotpatch-next dev 管理只监听 loopback 的 Next 子进程与 Sidecar 生命周期。
仅开发期启用的 Turbopack/webpack Loader 原子注册源码/data-flow anchors、注入 JSX/TSX 标记，并转换符合条件的浏览器 .js/.jsx/.ts/.tsx 模块。
@spotpatch/next/client 从 instrumentation-client 安装 React hook 与 dispatch-only data-flow prelude，再启动唯一 Runtime和共享数据链路面板。
私有 API rewrite 使用随机 loopback Sidecar origin 和每次启动生成的秘密。
生产配置把两个浏览器入口替换为无副作用 no-op，不添加 Loader、recorder、面板、Sidecar、源码注册或私有 rewrite。
spotpatch-next init 预览并应用受支持的接入修改，失败时执行回滚。
spotpatch-next check 在不启动开发服务器的情况下诊断包依赖和接入文件。

公共预览接入

只需安装一个框架入口包，所需 SpotPatch 内部包会自动解析，不要逐个手工安装。

pnpm add --save-dev @spotpatch/next
pnpm exec spotpatch-next init
pnpm exec spotpatch-next check
pnpm dev

受支持的初始化结果包含三部分。下面的 TypeScript 示例会开放页面内“审阅 / 可信极速”选择，并保留自动发现的 TypeScript 校验供审阅模式使用；纯 JavaScript 项目保持 withSpotPatch() 和审阅模式。可信极速模式本身不向模型暴露 run_check，也不执行项目检查。

// next.config.ts
import type { NextConfig } from "next";
import { withSpotPatch } from "@spotpatch/next";

const nextConfig: NextConfig = {};

export default withSpotPatch({
  dataFlow: {},
  trustedFastMode: true,
})(nextConfig);

// instrumentation-client.ts
// Router 位于 src 下时使用 src/instrumentation-client.ts。
import "@spotpatch/next/client";

{
  "scripts": {
    "dev": "spotpatch-next dev"
  }
}

必须通过 package script 启动，而不是直接运行 next dev。成功启动时终端只打印一条以 [spotpatch:next] ready 开头的信息；页面随后挂载唯一 spotpatch-root Shadow DOM，并显示 Select element / 选择元素 操作。

外部 Agent 交接（本地验证）

在同一包装器选项中显式启用仅开发期的交接 UI：

export default withSpotPatch({ externalAgent: true })(nextConfig);

必须在当前 spotpatch-next dev Session 所属的精确 canonical 项目根执行 setup 和主动命令。setup 不带 --write 时只是 dry-run：

pnpm exec spotpatch-next bridge setup --client claude --scope project --mode active --write
MCP_PROTOCOL_NEGOTIATION=legacy claude --dangerously-load-development-channels server:spotpatch

pnpm exec spotpatch-next connect codex --allow-workspace-write

pnpm exec spotpatch-next bridge setup --client cursor --scope project --write

若 bridge sessions --json 报告该精确项目根有多个 Session，主动子命令支持显式选择：

spotpatch-next bridge channel claude [--session <opaque-id>]
spotpatch-next connect codex --allow-workspace-write [--session <opaque-id>]

Claude legacy 环境变量必须设置在 Claude 宿主进程。Claude Channels 仍是 Research Preview，只在已启用 Channel 的会话运行时工作，且没有 completion ACK；完成状态依赖 Claude 调用 SpotPatch 结果 tool。Codex 主动模式为零配置：Connector 只把当前项目的 SpotPatch MCP 配置注入它拥有的 App Server thread，不创建也不修改 .codex/config.toml；Codex 仍可能按用户既有配置启动其他已启用 MCP server。Codex 从稳定版 0.149.0 起必须通过当前 executable 的 generated Schema、真实协议和安全 preflight；SpotPatch 不安装或更新 Codex。bridge setup --client codex ... 仅保留为可选 Inbox 配置；Cursor 和所有普通 MCP 宿主仍为 Inbox-only。

该链路当前只是 local-validation，不属于 Next 正式支持承诺。仓库有假宿主和连续两 Handoff 自动化测试，并已在记录的 macOS/Next.js/Codex 0.149.0 环境人工验证连续两个 revision。真实 Claude Code 连续投递、可重复真实宿主自动化和 Windows 进程树清理仍为 not-tested；Cursor 保持 Inbox-only。准确边界见外部 Agent 方案与实现状态。

当前证据与剩余门禁

公共预览已经通过：

包构建、类型发布、Publint 与 Are The Types Wrong；
正式单元测试与 HTTP 边界测试；
锁定范围的 Loader POC，覆盖选定的 Next 15/React 18 和 Next 16/React 19 组合；
一个私有 Next 16 App Router 宿主的 Turbopack 与 webpack 开发启动；
该宿主中的认证 Runtime bootstrap、源码注册、源码上下文读取和 Runtime 单例检查；
共享 data-flow compiler/runtime/HTTP 单测门禁、Next 原子注册、React 19 registration-only 身份策略、跨模块 renderer 发现和 browser/server Loader 分层；
一个 packed Next 16 App Router/Turbopack 浏览器报告，展示直接 fetch 与 Axios/TanStack Query transitive 静态证据；
一个 packed Next 16 App Router webpack development 构建，保持 "use client" 并在 Loader 前排除 .next/node_modules；
私有 Runtime POC 的 Turbopack 与 webpack Fast Refresh；
私有宿主的 webpack 生产隔离；
packed Next 16 App Router/Turbopack 干净 production build/start，页面 200、私有 bootstrap 404，且业务产物无可执行 SpotPatch data-flow 残留。

正式公共支持仍被以下项目阻断：完整 Next/React/router/Node/OS required matrix、Pages 与 hybrid Router、更广泛的 RSC 导航、React 19 身份最终浏览器复验、复杂 rewrite/basePath fixture，以及 Pages/standalone/static export/多操作系统的 webpack/Turbopack 生产扫描。

判断兼容性前必须阅读实现状态与发布 required matrix。

声明的 peer 范围

依赖	Package 范围	准确含义
Node.js	`>=20.19.0`	包的 engine 要求。
Next.js	`>=15.3.0 <17.0.0`	预览兼容矩阵候选范围，不是支持保证。
React / React DOM	`^18.2.0` 或 `^19.0.0`	可安装候选范围；React 19 Fiber 语义仍可能受控降级。

首版预览只接受 loopback 开发主机并拒绝 allowLan: true。复杂 CommonJS next.config、混合 root/src Router、冲突 Loader rule 和占用私有前缀的 rewrite 会安全失败或要求手动接入。

生产行为

生产环境使用普通 Next.js 命令：

pnpm exec next build
pnpm exec next start

spotpatch-next 只代理 dev。0.x 预览版不支持生产使用；验证必须继续证明生产产物中不存在 data-spotpatch-source、spotpatch-root、Runtime bootstrap 状态、私有 API 前缀和内部配置/注册秘密。

浏览器扩展造成的 Hydration 警告

如果 React 只报告类似 cz-shortcut-listen="true" 的 body 属性被移除，说明浏览器扩展在 hydration 前修改了文档。该警告与 SpotPatch 初始化无关；把它归因于适配器之前，应先在干净浏览器 Profile 中复现。

Navigation Menu

`@spotpatch/next`

English

Implemented preview path

Public preview integration

External Agent handoff (local validation)

Current evidence and remaining gates

Declared peer range

Production behavior

Hydration warning from browser extensions

简体中文

已实现的预览链路

公共预览接入

外部 Agent 交接（本地验证）

当前证据与剩余门禁

声明的 peer 范围

生产行为

浏览器扩展造成的 Hydration 警告

Links / 链接

License / 许可证

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

@spotpatch/next

English

Implemented preview path

Public preview integration

External Agent handoff (local validation)

Current evidence and remaining gates

Declared peer range

Production behavior

Hydration warning from browser extensions

简体中文

已实现的预览链路

公共预览接入

外部 Agent 交接（本地验证）

当前证据与剩余门禁

声明的 peer 范围

生产行为

浏览器扩展造成的 Hydration 警告

Links / 链接

License / 许可证

`@spotpatch/next`