PR: Cherry-pick common-v8 from upstream (#22)

* Clarify ESLint 'Unsafe...' troubleshooting

* Migrate to monorepo Vitest config

Introduce a root vitest.config.ts and split package test configs into unit and browser projects (packages/common/vitest.unit.config.ts, packages/common/vitest.browser.config.ts). Remove the old combined common vitest config and migrate per-package coverage/test settings into the central config. Update package.json scripts to run Vitest from the repo root, remove per-package Vitest deps where appropriate, and add browser/playwright-related devDeps at the root. Adjust tsconfigs (add root tsconfig.json and include vitest.*.config.ts in packages/common) and simplify turbo.json task entries. Also add a README link to the Vitest VS Code extension.

* Expand TDD guidance and add Vitest examples

Replace the brief Test-driven development note with an expanded TDD section that explains how to run tests, test file locations, and filtering by test name. Add subsections on test structure, type testing (expectTypeOf), and inline snapshot usage with Vitest code examples. Remove the previous Vitest filtering CLI snippets and some commit-message examples to streamline the guidance and surface more actionable testing patterns for contributors.

* Update TreeShaking.test.ts

* Use 'observability' term in error comment

* Rename vitest config to .mts and add scripts tests

Rename vitest.config.ts → vitest.config.mts (switch to .mts/ESM), update tsconfig include to reference vitest.config.mts, and add a new "scripts" test project in the Vitest config to include tests matching scripts/**/*.test.mts. Also simplify package.json "verify" script by removing the generic "pnpm test" step.

* Add createQueryBuilder, replace createQuery usage

Introduce a standalone createQueryBuilder(Schema) to build typed Kysely queries without an Evolu instance. The createQuery implementation was moved into packages/common/src/local-first/Schema.ts and exported from index.ts; Evolu.createQuery was removed from the Evolu interface/instance. Updated usages across playgrounds to call createQuery(...) (created via createQueryBuilder) and adjusted types/docs in Query.ts. Added a changeset noting the API migration and guidance to replace evolu.createQuery with createQueryBuilder(Schema).

* chore: format

* update: minors

* fix: missing dependencies and verified build

* chore: Update Biome to version 2.3.14 and reflect this change in documentation and configuration schema.

* Update packages/common/src/local-first/Evolu.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Miccy <code@miccy.dev>

* Update packages/common/src/local-first/Evolu.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Miccy <code@miccy.dev>

* Revert EvoluMinimalExample.tsx to working implementation (#24)

* Initial plan

* Revert EvoluMinimalExample.tsx to working state from 13fab62

Co-authored-by: miccy <9729864+miccy@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: miccy <9729864+miccy@users.noreply.github.com>

* Fix CI: generate docs before typedoc-plugin tests (#23)

* Initial plan

* Update all examples to use createQueryBuilder instead of evolu.createQuery

Co-authored-by: miccy <9729864+miccy@users.noreply.github.com>

* Fix CI: add build:docs before typedoc-plugin tests in verify script

Co-authored-by: miccy <9729864+miccy@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: miccy <9729864+miccy@users.noreply.github.com>

* Fix CI: Exclude typedoc test from regular test run (#27)

* fix: Correct `Uint8Array` type signature in `exportDatabase` and related callbacks.

* chore: Update Angular and Svelte dependencies and enable documentation tests in the verify script.

* refactor: improve schema difference calculation for columns and use a local constant for current schema.

---------

Signed-off-by: Miccy <code@miccy.dev>
Signed-off-by: Miccy <support@miccy.dev>
Co-authored-by: Daniel Steigerwald <daniel@steigerwald.cz>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>

Author: 4 people

.ai/knowledge/02-dependencies.md

@@ -22,7 +22,7 @@ bunx <package>       # Execute packages
 
 ### Development
 - **Turbo** 2.8.1 - Monorepo build orchestration
-- **Biome** 2.3.13 - Linting and formatting
+- **Biome** 2.3.14 - Linting and formatting
 - **Vitest** ^4.0.18 - Testing framework
 - **TypeDoc** ^0.28.16 - API documentation
 

.ai/tasks/archive/cherry-pick-common-v8-SUPERSEDED.md

@@ -22,7 +22,7 @@ Migrating changes from `upstream/common-v8` to our fork, while preserving our st
 | Tool    | Before | After  | Status           |
 | ------- | ------ | ------ | ---------------- |
 | Bun     | 1.3.6  | 1.3.8  | ✅ Done           |
-| Biome   | 2.3.13 | 2.3.13 | ✅ Current        |
+| Biome   | 2.3.14 | 2.3.14 | ✅ Current        |
 | Turbo   | 2.8.1  | 2.8.1  | ✅ Current        |
 | Node.js | >=24   | >=24   | ✅ LTS 24 correct |
 

.changeset/create-query-builder.md

@@ -0,0 +1,16 @@
+---
+"@evolu/common": major
+---
+
+Replaced `evolu.createQuery` with standalone `createQueryBuilder` function
+
+Queries are now created using a standalone `createQueryBuilder` function instead of `evolu.createQuery` method. This enables query creation without an Evolu instance, improving code organization and enabling schema-first development.
+
+```ts
+// Before
+const todosQuery = evolu.createQuery((db) => db.selectFrom("todo").selectAll());
+
+// After
+const createQuery = createQueryBuilder(Schema);
+const todosQuery = createQuery((db) => db.selectFrom("todo").selectAll());
+```

.github/copilot-instructions.md

@@ -71,11 +71,6 @@ apps/
 
 Follow these specific conventions and patterns:
 
-## Test-driven development
-
-- Write a failing test before implementing a new feature or fixing a bug
-- Keep test code cleaner than production code — good tests let you refactor production code; nothing protects messy tests
-
 ## Code organization & imports
 
 - **Use named imports only** - avoid default exports and namespace imports
@@ -498,6 +493,68 @@ const processTask: Task<void, ParseError | TimeoutError> = async (run) => {
 const result = await sleep("1s")(run);
 ```
 
+## Test-driven development
+
+- Write a failing test before implementing a new feature or fixing a bug
+- Run tests using the `runTests` tool with the test file path
+- Test files are in `packages/*/test/*.test.ts`
+- Use `testNames` parameter to run specific tests by name
+- Run related tests after making code changes to verify correctness
+
+### Test structure
+
+- Use `describe` blocks to group related tests by feature or function
+- Use `test` or `it` for individual test cases (both are equivalent)
+- Test names should be descriptive phrases: `"returns true for non-empty array"`
+- Use nested `describe` for sub-categories
+
+```ts
+import { describe, expect, expectTypeOf, test } from "vitest";
+
+describe("arrayFrom", () => {
+  test("creates array from iterable", () => {
+    const result = arrayFrom(new Set([1, 2, 3]));
+    expect(result).toEqual([1, 2, 3]);
+  });
+
+  test("returns input unchanged if already an array", () => {
+    const input = [1, 2, 3];
+    const result = arrayFrom(input);
+    expect(result).toBe(input);
+  });
+});
+```
+
+### Type testing
+
+Use `expectTypeOf` from Vitest for compile-time type assertions:
+
+```ts
+import { expectTypeOf } from "vitest";
+
+test("returns readonly array", () => {
+  const result = arrayFrom(2, () => "x");
+  expectTypeOf(result).toEqualTypeOf<ReadonlyArray<string>>();
+});
+
+test("NonEmptyArray requires at least one element", () => {
+  const _valid: NonEmptyArray<number> = [1, 2, 3];
+  // @ts-expect-error - empty array is not a valid NonEmptyArray
+  const _invalid: NonEmptyArray<number> = [];
+});
+```
+
+### Inline snapshots
+
+Use `toMatchInlineSnapshot` for readable test output directly in the test file:
+
+```ts
+test("Buffer", () => {
+  const buffer = createBuffer([1, 2, 3]);
+  expect(buffer.unwrap()).toMatchInlineSnapshot(`uint8:[1,2,3]`);
+});
+```
+
 ## Testing
 
 - **Create deps per test** - use `testCreateDeps()` from `@evolu/common` for test isolation
@@ -564,18 +621,6 @@ bun run test --filter @evolu/common -- -t "yields and returns ok"
 - **No prefixes** - avoid `feat:`, `fix:`, `feature:` etc.
 - **Be descriptive** - explain what the change does
 
-```bash
-# Good
-Add support for custom error formatters
-Fix memory leak in WebSocket reconnection
-Update schema validation to handle edge cases
-
-# Avoid
-feat: add support for custom error formatters
-fix: memory leak in websocket reconnection
-Update schema validation to handle edge cases.
-```
-
 ## Changesets
 
 - **Write in past tense** - describe what was done, not what will be done

AGENTS.md

@@ -12,13 +12,13 @@
 
 ## 📊 Quick Context
 
-| Aspect | Value |
-|--------|-------|
-| Package Manager | Bun 1.3.8 |
-| Node.js | >=24.0.0 |
-| Linter/Formatter | Biome 2.3.13 |
-| Test Framework | Vitest |
-| Upstream | evoluhq/evolu |
+| Aspect           | Value         |
+| ---------------- | ------------- |
+| Package Manager  | Bun 1.3.8     |
+| Node.js          | >=24.0.0      |
+| Linter/Formatter | Biome 2.3.14  |
+| Test Framework   | Vitest        |
+| Upstream         | evoluhq/evolu |
 
 ## 🗂️ Repository Structure
 
@@ -92,13 +92,13 @@ bun run verify
 
 ## 📍 Related Resources
 
-| Resource | Location |
-|----------|----------|
-| Issues | `../knowledge/05-Issues/` |
-| Roadmap | `../knowledge/05-Issues/roadmap.md` |
-| Architecture | `../knowledge/02-Architecture/` |
-| Bench Suite | `../bench-suite/` (sibling repo) |
-| Upstream | https://github.com/evoluhq/evolu |
+| Resource     | Location                            |
+| ------------ | ----------------------------------- |
+| Issues       | `../knowledge/05-Issues/`           |
+| Roadmap      | `../knowledge/05-Issues/roadmap.md` |
+| Architecture | `../knowledge/02-Architecture/`     |
+| Bench Suite  | `../bench-suite/` (sibling repo)    |
+| Upstream     | https://github.com/evoluhq/evolu    |
 
 ## 🤖 For AI Agents
 

README.md

@@ -73,6 +73,7 @@ Linting
 Testing
 
 - `bun run test` - Run tests
+- [Vitest VS Code extension](https://github.com/vitest-dev/vscode)
 
 Release
 

apps/web/package.json

@@ -61,7 +61,7 @@
     "@evolu/tsconfig": "workspace:*",
     "@types/mdx": "^2.0.13",
     "@types/node": "^24.10.9",
-    "@types/react": "~19.2.10",
+    "@types/react": "~19.2.11",
     "@types/react-dom": "~19.2.3",
     "@types/react-highlight-words": "^0.20.1",
     "@types/rss": "^0.0.32",

apps/web/src/app/(playgrounds)/playgrounds/full/EvoluFullExample.tsx

@@ -5,6 +5,7 @@ import {
   createEvolu,
   createFormatTypeError,
   createObjectURL,
+  createQueryBuilder,
   FiniteNumber,
   id,
   idToIdBytes,
@@ -99,6 +100,8 @@ const Schema = {
   },
 };
 
+const createQuery = createQueryBuilder(Schema);
+
 const deps = createEvoluDeps();
 
 const evolu = createEvolu(deps)(Schema, {
@@ -212,7 +215,7 @@ const App: FC = () => {
   );
 };
 
-const projectsWithTodosQuery = evolu.createQuery(
+const projectsWithTodosQuery = createQuery(
   (db) =>
     db
       .selectFrom("project")
@@ -409,7 +412,7 @@ const HomeTabProjectSectionTodoItem: FC<{
 
   // Demonstrate history tracking. Evolu automatically tracks all changes
   // in the evolu_history table, making it easy to build audit logs or undo features.
-  const titleHistoryQuery = evolu.createQuery((db) =>
+  const titleHistoryQuery = createQuery((db) =>
     db
       .selectFrom("evolu_history")
       .select(["value", "timestamp"])
@@ -503,7 +506,7 @@ const HomeTabProjectSectionTodoItem: FC<{
   );
 };
 
-const projectsQuery = evolu.createQuery((db) =>
+const projectsQuery = createQuery((db) =>
   db
     .selectFrom("project")
     .select(["id", "name", "fooJson"])
@@ -716,7 +719,7 @@ const AccountTab: FC = () => {
   );
 };
 
-const deletedProjectsQuery = evolu.createQuery((db) =>
+const deletedProjectsQuery = createQuery((db) =>
   db
     .selectFrom("project")
     .select(["id", "name", "updatedAt"])
@@ -728,7 +731,7 @@ const deletedProjectsQuery = evolu.createQuery((db) =>
 
 type DeletedProjectsRow = typeof deletedProjectsQuery.Row;
 
-const deletedTodosQuery = evolu.createQuery((db) =>
+const deletedTodosQuery = createQuery((db) =>
   db
     .selectFrom("todo")
     .select(["id", "title", "isCompleted", "projectId", "updatedAt"])

apps/web/src/app/(playgrounds)/playgrounds/multitenant/EvoluMultitenantExample.tsx

@@ -23,6 +23,9 @@ const Schema = {
 
 const deps = createEvoluDeps();
 
+// Create a typed query builder from the schema
+const createQuery = Evolu.createQueryBuilder(Schema);
+
 deps.evoluError.subscribe(() => {
   const error = deps.evoluError.get();
   if (!error) return;
@@ -73,7 +76,7 @@ export const EvoluMultitenantExample: FC = () => (
 );
 
 // Evolu uses Kysely for type-safe SQL (https://kysely.dev/).
-const todosQuery = evolu.createQuery((db) =>
+const todosQuery = createQuery((db) =>
   db
     // Type-safe SQL: try autocomplete for table and column names.
     .selectFrom("todo")

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.3.14/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",