Merge upstream to dev

Author: miccy

.changeset/angry-kings-obey.md

@@ -0,0 +1,12 @@
+---
+"@evolu/react-native": patch
+"@evolu/common": patch
+"@evolu/web": patch
+"@evolu/nodejs": patch
+"@evolu/react": patch
+"@evolu/react-web": patch
+---
+
+Native Base64 ID encoding
+
+Breaking change: Id is encoded into BinaryId via new native algorithm (uses platform Base64 with polyfill). Removed custom Base64Url256 micro-optimization; table & column names now plain strings. Simpler, smaller, more standard code.

.changeset/clever-forks-read.md

@@ -0,0 +1,13 @@
+---
+"@evolu/react-native": patch
+"@evolu/common": patch
+"@evolu/svelte": patch
+"@evolu/web": patch
+---
+
+Fix and improve relay broadcasting
+
+- Enable relay broadcasting for all messages, not just non-sync messages. The previous logic was only working due to a bug and we've normalized this behavior.
+- Remove TimestampDuplicateNodeError and related NodeId collision checks from receiveTimestamp function.
+- Add comprehensive documentation explaining relay broadcasting behavior during migration scenarios and why duplicate messages are safe due to applyMessages idempotency.
+- Update NodeId documentation.

.changeset/common-ads-serve.md

@@ -0,0 +1,9 @@
+---
+"@evolu/react-native": patch
+"@evolu/common": patch
+"@evolu/web": patch
+---
+
+Replace Mnemonic with OwnerSecret
+
+OwnerSecret is the fundamental cryptographic primitive from which all owner keys are derived via SLIP-21. Mnemonic is just a representation of this underlying entropy. This change makes the type system more accurate and the cryptographic relationships clearer.

.changeset/tricky-wings-join.md

@@ -0,0 +1,74 @@
+---
+"@evolu/react-native": patch
+"@evolu/common": patch
+"@evolu/web": patch
+---
+
+# Transport-Based Configuration System
+
+# Transport-Based Configuration System
+
+**BREAKING CHANGE**: Replaced `syncUrl` with flexible `transport` property supporting single transport or array of transports for multiple sync endpoints.
+
+## What Changed
+
+- **Removed** `syncUrl` property from Evolu config
+- **Added** `transport` property accepting a single `Transport` object or array of `Transport` objects
+- **Added** `Transport` type union with initial WebSocket support
+- **Updated** sync system to support Nostr-style relay pools with simultaneous connections
+- **Updated** all examples and documentation to use new transport configuration
+
+## Migration Guide
+
+**Before:**
+
+```ts
+const evolu = createEvolu(deps)(Schema, {
+  syncUrl: "wss://relay.example.com",
+});
+```
+
+**After (single transport):**
+
+```ts
+const evolu = createEvolu(deps)(Schema, {
+  transport: { type: "WebSocket", url: "wss://relay.example.com" },
+});
+```
+
+**After (multiple transports):**
+
+```ts
+const evolu = createEvolu(deps)(Schema, {
+  transport: [
+    { type: "WebSocket", url: "wss://relay1.example.com" },
+    { type: "WebSocket", url: "wss://relay2.example.com" },
+  ],
+});
+```
+
+## Benefits
+
+- **Single or multiple relay support**: Use one transport for simplicity or multiple for redundancy
+- **Intuitive API**: Singular property name that accepts both single item and array
+- **Future extensibility**: Ready for upcoming transport types (FetchRelay, Bluetooth, LocalNetwork)
+- **Nostr-style resilience**: Messages broadcast to all connected relays simultaneously when using arrays
+- **Type safety**: Full TypeScript support for transport configurations
+
+## Future Transport Types
+
+The new system is designed to support upcoming transport types:
+
+- `FetchRelay`: HTTP-based polling for environments without WebSocket support
+- `Bluetooth`: P2P sync for offline collaboration
+- `LocalNetwork`: LAN/mesh sync for local networks
+
+## Technical Details
+
+- Single transports are automatically normalized to arrays internally
+- CRDT messages are sent to all connected transports simultaneously
+- Duplicate message handling relies on CRDT idempotency (no deduplication needed)
+- WebSocket connections auto-reconnect independently
+- Backwards compatibility removed (preview version breaking change)
+
+This change provides an intuitive API that scales from simple single-transport setups to complex multi-transport configurations, positioning Evolu for a more resilient, multi-transport future.

…hub/instructions/copilot.instructions.md .github/copilot-instructions.md.github/instructions/copilot.instructions.md renamed to .github/copilot-instructions.md .github/instructions/copilot.instructions.md renamed to .github/copilot-instructions.md

@@ -37,6 +37,44 @@ interface Example {
 }
 ```
 
+## Documentation & JSDoc
+
+- **Avoid `@param` and `@return` tags** - TypeScript provides type information, focus on describing the function's purpose
+- **Use `### Example` instead of `@example`** - for better markdown rendering and consistency
+- **Write clear descriptions** - explain what the function does, not how to use it
+
+````ts
+// ✅ Good
+/**
+ * Creates a new user with the provided data.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const user = createUser({ name: "John", email: "john@example.com" });
+ * ```
+ */
+export const createUser = (data: UserData): User => {
+  // implementation
+};
+
+// ❌ Avoid
+/**
+ * Creates a new user with the provided data.
+ *
+ * @example
+ *   ```ts
+ *   const user = createUser({ name: "John", email: "john@example.com" });
+ *   ```;
+ *
+ * @param data The user data to create the user with
+ * @returns The created user
+ */
+export const createUser = (data: UserData): User => {
+  // implementation
+};
+````
+
 ## Error Handling with Result
 
 - Use `Result<T, E>` for business/domain errors in public APIs
@@ -150,9 +188,6 @@ assert(NonNegativeInt.is(length), "buffer length should be non-negative");
 // ✅ Good - Non-empty array assertion
 assertNonEmptyArray(items, "Expected items to process");
 
-// ✅ Good - Catch block for promises that shouldn't error
-Promise.resolve().catch((e) => assertNoErrorInCatch("WebSocket retry", e));
-
 // ❌ Avoid - Use Type validation instead
 // Don't use assert for runtime input validation
 ```
@@ -214,21 +249,44 @@ const deps: TimeDep & Partial<LoggerDep> = {
 
 - **Run tests using pnpm** - use `pnpm test` from the project root to run all tests
 - **Run specific test files** - use `pnpm test --filter @evolu/package-name -- test-file-pattern` from project root (e.g., `pnpm test --filter @evolu/common -- Protocol`)
+- **Check compilation** - use `pnpm build` to check TypeScript compilation across all packages
+- **Run linting** - use `pnpm lint` to check code style and linting rules
+- **Leverage `_deps.ts`** - use existing test utilities and mocks from `packages/common/test/_deps.ts` (e.g., `testCreateId`, `testTime`, `testOwner`)
 - Mock dependencies using the same interfaces
 - Create test factories (e.g., `createTestTime`)
 - Never rely on global state
 - Use assertions in tests for conditions that should never fail
 
 ```ts
+import { testCreateId, testTime, testOwner } from "../_deps.js";
+
 const createTestTime = (): Time => ({
   now: () => 1234567890, // Fixed time for testing
 });
 
 test("timeUntilEvent calculates correctly", () => {
-  const deps = { time: createTestTime() };
+  const deps = { time: testTime }; // Use from _deps.ts
   const result = timeUntilEvent(deps)(1234567990);
   assert(result === 100, "Expected result to be 100");
 });
 ```
 
+## Git Commit Messages
+
+- **Write as sentences** - use proper sentence case without trailing period
+- **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.
+```
+
 When suggesting code changes, ensure they follow these patterns and conventions.