spiceflow React framework. RSC stack based on @vitejs/plugin-rsc

.changeset/pre.json

@@ -0,0 +1,12 @@
+{
+  "mode": "pre",
+  "tag": "rsc",
+  "initialVersions": {
+    "openapi-schema-diff": "0.0.1",
+    "spiceflow": "1.6.1",
+    "nodejs-example": "0.1.0"
+  },
+  "changesets": [
+    "five-toes-learn"
+  ]
+}

.gitignore

@@ -20,4 +20,5 @@ debug
 .last-run.json
 .react-router
 opensrc
+/di
 tmp

.gitmodules

@@ -1,3 +0,0 @@
-[submodule "openapi-schema-diff"]
-	path = openapi-schema-diff
-	url = https://github.com/remorses/openapi-schema-diff.git

AGENTS.md

@@ -1,20 +1,19 @@
-
 # package manager: pnpm with workspace
 
 This project uses pnpm workspaces to manage dependencies. Important scripts are in the root package.json or various packages package.json
 
 try to run commands inside the package folder that you are working on. for example you should never run `pnpm test` from the root
 
-
 # typescript
 
 Try to use object arguments for new typescript functions if the function would accept more than one argument, this way you can use the object as a sort of named argument feature, where order of arguments does not matter and it's easier to discover parameters.
 
+Always run `pnpm tsc --noEmit` from the package you changed after code edits, and fix any reported issues before finishing.
+
 do not add useless comments if the code is self descriptive. only add comments if requested or if this was a change that i asked for, meaning it is not obvious code and needs some inline documentation.
 
 try to use early returns and breaks, try nesting code as little as possible, follow the go best practice of if statements: avoid else, nest as little as possible, use top level ifs. minimize nesting.
 
-
 # testing
 
 Use vitest to run tests. Tests should be run from the current package directory and not root, try using the test script instead of vitest directly. Additional vitest flags can be added at the end, like --run to disable watch mode or -u to update snapshots.
@@ -29,6 +28,112 @@ Sometimes tests work directly on database data, using prisma. To run these tests
 
 Never write tests yourself that call prisma or interact with database or emails. For these asks the user to write them for you.
 
+# e2e testing (integration-tests)
+
+E2e tests live in `integration-tests/e2e/` and use Playwright (chromium only). The dev server starts automatically via the `webServer` config in `playwright.config.ts`.
+
+## running e2e tests
+
+These are the integration test commands for the RSC app in `integration-tests/`:
+
+- `pnpm test-e2e` runs the Playwright suite against the dev server, so it covers dev-only behavior like HMR and middleware behavior during development.
+- `pnpm test-e2e-start` runs the same Playwright suite against the production start server, so it catches build-only regressions that do not show up in dev.
+- Run both commands when validating an integration change, because they exercise different environments and one passing does not imply the other passes.
+
+```bash
+# run from integration-tests directory, never from root
+cd integration-tests
+
+# run all e2e tests
+pnpm test-e2e
+
+# filter by test name
+pnpm test-e2e --grep "SSR error"
+
+# run against production build
+pnpm test-e2e-start
+```
+
+Tests tagged `@dev` are skipped during start runs; tests tagged `@build` are skipped during dev runs (controlled by `grepInvert` in `integration-tests/playwright.config.ts`).
+
+## rebuild dist before testing
+
+The Vite SSR middleware imports from `spiceflow/dist/` (the compiled package), NOT from source. If you modify files in `spiceflow/src/`, you must rebuild before e2e tests will pick up the changes:
+
+```bash
+cd spiceflow
+pnpm tsc --noCheck   # --noCheck skips pre-existing type errors
+```
+
+This is the most common reason e2e tests fail after code changes — stale dist files.
+
+## writing e2e tests
+
+- The base URL and port are defined at the top of `basic.test.ts`:
+  ```ts
+  const port = Number(process.env.E2E_PORT || 6174)
+  const baseURL = `http://localhost:${port}`
+  ```
+- Use `page.goto("/path")` for browser-based tests that need rendering, JS execution, or DOM interaction.
+- Use Node.js `fetch(baseURL + "/path")` directly (not `page.evaluate`) when you need to control HTTP headers like `Origin` — browsers restrict forbidden headers.
+- Use `page.getByTestId()`, `page.getByText()`, `page.getByRole()` for locators. Prefer test-ids for stability.
+- When a `data-testid` matches multiple elements (e.g. multiple counter components on a page), use `.filter({ hasText: "..." })` to disambiguate:
+  ```ts
+  const clientCounter = page
+    .getByTestId('client-counter')
+    .filter({ hasText: 'Client counter' })
+  await clientCounter.getByRole('button', { name: '+' }).click()
+  ```
+- If a locator's text changes during the test (e.g. HMR edits), do NOT use it through a pre-filtered variable — query the page directly for the new text.
+
+## adding test routes
+
+To add a route for e2e testing, add it in `integration-tests/src/main.tsx` using the spiceflow API:
+
+```ts
+.page("/my-test-route", async () => {
+    return <MyComponent />;
+})
+```
+
+Client components used in tests should be created in `integration-tests/src/app/` with a `"use client"` directive.
+
+## HMR tests
+
+- `createEditor("src/app/file.tsx")` from `e2e/helper.ts` edits a file and auto-reverts on dispose.
+- Always call `file[Symbol.dispose]()` or use `try/finally` to restore files after edits.
+- When editing files, make sure the `replace()` string actually exists in the source. For example, `client.tsx` has `name = "Client"` as a default prop — the literal string "Client counter" does NOT exist in the file, so `replace("Client counter", ...)` would be a no-op and the HMR test would silently fail.
+- **Client HMR preserves state**: editing a client component triggers React Fast Refresh without a server re-render. Client state is preserved. Vite's SSR environment logs `page reload` internally but the browser does not actually reload — Fast Refresh handles it.
+- **Server HMR preserves server state**: editing a server component triggers RSC HMR. Server-side state (e.g. counters stored in module scope) is preserved. Client state is NOT preserved — `router.refresh()` re-fetches the full RSC payload, and React reconciliation remounts client components with fresh state.
+- The home page has a `serverRenderCount` counter (`data-testid="server-render-count"`) that increments on each RSC render. Use it in tests to verify whether a server re-render happened.
+- To detect full page reloads in tests, set a window sentinel before the edit and check it after: `await page.evaluate((s) => { window.__hmrSentinel = s }, sentinel)` — if the sentinel is gone after the edit, a full reload happened.
+
+## debugging unwanted full page reloads in vite
+
+When HMR triggers a full page reload instead of a hot update, the cause is a `{type:"full-reload"}` WebSocket message sent to the browser. To find who sends it, patch `hot.send` on every Vite environment with `console.trace` in a temporary plugin:
+
+```ts
+{
+  name: 'debug-full-reload',
+  configureServer(server) {
+    for (const envName of Object.keys(server.environments)) {
+      const env = server.environments[envName]
+      const origSend = env.hot.send.bind(env.hot)
+      env.hot.send = function (...args) {
+        if (args[0]?.type === 'full-reload') {
+          console.trace(`[full-reload] env=${envName} payload=${JSON.stringify(args[0])}`)
+        }
+        return origSend(...args)
+      }
+    }
+  },
+},
+```
+
+The stack trace reveals exactly which plugin and hook is responsible. Common culprits:
+- `@tailwindcss/vite` hotUpdate sending bare `{type:"full-reload"}` for server-only files it scans for class names
+- Vite's dep optimizer (`runOptimizer` → `fullReload`) when deps change — usually harmless, triggers once
+- `updateModules` in Vite core when `propagateUpdate` hits a dead end (no HMR boundary found)
 
 # website
 
@@ -58,25 +163,44 @@ For example if the current file is `src/routes/home.tsx` you can import `import
 
 always use tailwind for styling, prefer using simple styles using flex and gap. Try to use the built in tailwind colors like gray, red, green, etc. Margins should be avoided, instead use flexbox gaps, grid gaps, or separate spacing divs.
 
+## spiceflow/react exports
+
+All React-facing APIs (components, router, utilities) must be exported from `spiceflow/react` (i.e. `spiceflow/src/react/index.ts`). Never import from `spiceflow/dist/react/...` directly — that's an internal path that breaks when the build output changes. If something is meant for users (like `Head`, `Link`, `ProgressBar`, `router`), it must be in the public export.
+
 ## files
 
 always use kebab case for new filenames. never use uppercase letters in filenames
 
 ## changesets
 
-after you make a change that is noteworthy, add a changeset. these will be used later on to create a changelog for the package. use `pnpm changeset add --empty` to create a changeset file in `.changeset` folder, then write there the changes you made in a single concise paragraph. never run other changeset commands, like `pnpm changeset version` or `pnpm changeset publish`. Notice that sometimes the cwd is missing `.changeset` folder, in that case check the parents directories.
+after you make a change that is noteworthy, add a changeset manually as a markdown file inside the `.changeset` folder. these files are used later on to create the changelog for the package. if the current cwd does not have a `.changeset` folder, check parent directories.
 
 NEVER make breaking changes changesets. our releases are close enough in time that you should never do breaking changes, even if we do one you have nothing to worry about because it's probably a publish so close in time that on one will ever use the current version.
 
 Only add changesets for packages that are not marked as `private` in their `package.json` and have a `version` in the package.json.
 
-Changeset files are structured like this:
+Changeset files should be plain `.md` files with this structure:
 
 ```md
 ---
-'package-name': patch # can also be `minor` or `major`, never use major
+'package-name': patch # can also be `minor`, never use `major`
 ---
 
-markdown describing the changes you made, in present tense, like "add support for X" or "fix bug with Y". Be detailed but concise, and never use bullet points or lists. Always show example code snippets if applicable, and use proper markdown formatting.
-
+markdown describing the changes you made, in present tense, like "add support for X" or "fix bug with Y". write a single concise paragraph, not bullet points or lists. include example code snippets if useful, and use proper markdown formatting.
 ```
+
+## check-entry (bundleability guard)
+
+`pnpm check-entry` in the spiceflow package bundles `src/index.ts` with esbuild using zero externals. It runs automatically during `pnpm build`. This validates that `import { Spiceflow } from 'spiceflow'` works for users who are NOT using the React/RSC features and bundle with esbuild, webpack, or similar — without needing to externalize anything.
+
+If this check fails, it means a Vite-only dependency (like `@vitejs/plugin-rsc`) leaked into the main import path. RSC-only imports must go through the `#rsc-runtime` subpath import (defined in package.json `imports` field) which uses the `react-server` condition to resolve to the real implementation in Vite RSC environments and to an empty fallback everywhere else.
+
+## vite-rsc
+
+the spiceflow vite plugin depends on vite-rsc plugin. you can read its source code with `opensrc vitejs/vite-plugin-react`. inside folder packages/plugin-rsc`. there are also examples there. inside examples folder
+
+we also try to work well with the cloudflare vite plugin. the source code of that is in `https://github.com/cloudflare/workers-sdk/blob/main/packages/vite-plugin-cloudflare`
+
+we have an example `cloudflare-example` that we can use to make sure pnpm dev, build, preview and deployment work well.
+
+Waku (`opensrc dai-shi/waku`, packages/waku/) is another Vite RSC framework we use as reference for Vite integration patterns. It uses the same `@vitejs/plugin-rsc` plugin and has a similar multi-environment setup (client, ssr, rsc). Useful to check how they handle `optimizeDeps`, `resolve.noExternal`, SSR middleware, and RSC environment config. Their Vite plugins live in `packages/waku/src/lib/vite-plugins/`.