create-syncular-app 0.3.1 → 0.4.1

package/README.md

@@ -18,14 +18,13 @@ bunx create-syncular-app my-app --template web
 |---|---|
 | `minimal` | Server + a terminal two-client convergence demo (no browser) — migrations + manifest + `generate` wiring. Copy-evolved from `examples/quickstart`. The smallest honest starting point. |
 | `web` | Hono server + WebSocket realtime + a single-pane browser todo app whose whole client core runs in a Web Worker on OPFS. Derived from `apps/demo`, slimmed to one pane (no conflict simulator, no blob attachments) — the minimal browser app a real user starts from. |
+| `tauri` | One React codebase, web + desktop (RFC 0002 §4.1): the `web` template's server plus a shared React tree behind the `__TAURI_INTERNALS__` engine seam (`src/frontend/engine.ts`) — worker core on OPFS in the browser, native Rust core in a `src-tauri/` host (`tauri-plugin-syncular` from crates.io, `native-transport`). Derived from `bindings/tauri/example` + the [web+desktop guide](../../apps/docs/src/content/guide-web-desktop.md). |
 
-> **Third-template candidate: `react`.** [`apps/demo-react`](../../apps/demo-react)
-> is the ready-made source for a hooks-based template — `@syncular/react`
-> (`SyncProvider` + `useQuery` + `useRawSql` + `useMutation` + `useSyncStatus` +
-> `useWindow`) over the same worker + OPFS core, with the named-query read
-> tier wired. Slim it the way `web` slims `apps/demo` (drop the three-list
-> seed to one, keep one hook of each kind) and add it here when a React
-> template is wanted. Not built yet — noted so the shape is on record.
+> **Next-template candidate: `react` (web-only).** [`apps/demo-react`](../../apps/demo-react)
+> is the ready-made source for a hooks-based web-only template — the `tauri`
+> template already carries the hook surface for the two-host story. Slim
+> demo-react the way `web` slims `apps/demo` when a web-only React template
+> is wanted. Not built yet — noted so the shape is on record.
 
 Each template ships its own `README.md` (run steps, what to edit first),
 `.gitignore` (as `gitignore` — see below), a working `tsconfig.json`, and a
@@ -80,3 +79,12 @@ The in-tree template `*.test.ts` files are excluded from the root `bun test`
 sweep (`--path-ignore-patterns '**/create-app/template/**'` in the root `test`
 script) — they can only resolve their deps inside a scaffolded, linked copy,
 which the tier test above provides.
+
+The `tauri` template's desktop half (`src-tauri/`) is deliberately outside
+both tiers: compiling it needs the Rust toolchain, the Tauri system
+libraries, and the crates.io registry. Its compile proof is a local
+`cargo check` in a scaffolded app (documented in the template README) plus
+the tauri-bindings CI job, which builds the same plugin wiring from the
+in-tree path dep — the honest scoping the tauri/RN binding gates already
+use. The webview side (engine seam, React tree, `build-frontend.ts`) rides
+the always-run tier like any other template file.

package/dist/cli.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 /**
- * `create-syncular-app [project-name] [--template <minimal|web>] [--local]`
+ * `create-syncular-app [project-name] [--template <minimal|web|tauri>]
+ * [--local]`
  *
  * Runnable as `bun create syncular-app my-app` or `bunx create-syncular-app
  * my-app`. Prompts for anything a flag did not supply. Scaffolds one of the
- * two templates (see `./scaffold`).
+ * templates (see `./scaffold`).
  */
 import { relative } from 'node:path';
 import { createInterface } from 'node:readline/promises';
-import { CLI_BIN, CREATE_BIN, PRODUCT_NAME } from './constants.js';
+import { CREATE_BIN, PRODUCT_NAME } from './constants.js';
 import { isTemplateName, scaffoldApp, TEMPLATES, } from './scaffold.js';
 function usage() {
     return `usage: ${CREATE_BIN} [project-name] [options]
@@ -19,6 +20,9 @@ templates:
   minimal   server + a terminal two-client convergence demo (no browser)
   web       Hono server + WebSocket + a single-pane browser todo app
             (worker core on OPFS)
+  tauri     one React codebase, web + desktop: the web template's server
+            plus a src-tauri host running the native core
+            (tauri-plugin-syncular from crates.io)
 
 options:
   --template <name>   one of: ${TEMPLATES.join(', ')} (prompts if omitted)

package/dist/constants.d.ts

@@ -19,7 +19,7 @@ export declare const PRODUCT_NAME = "syncular";
  * documentation, not a gate — but it keeps the "what does a template pull in"
  * question answerable from one spot.
  */
-export declare const WORKSPACE_PACKAGES: readonly ["@syncular/core", "@syncular/server", "@syncular/server-hono", "@syncular/client", "@syncular/typegen"];
+export declare const WORKSPACE_PACKAGES: readonly ["@syncular/core", "@syncular/server", "@syncular/server-hono", "@syncular/client", "@syncular/react", "@syncular/tauri", "@syncular/typegen"];
 export declare const PUBLISHED_DEPENDENCY_RANGE: string;
 /** Placeholder tokens substituted verbatim during scaffold (dumb + greppable). */
 export declare const PLACEHOLDER: {

package/dist/constants.js

@@ -25,6 +25,8 @@ export const WORKSPACE_PACKAGES = [
     `${PACKAGE_SCOPE}/server`,
     `${PACKAGE_SCOPE}/server-hono`,
     `${PACKAGE_SCOPE}/client`,
+    `${PACKAGE_SCOPE}/react`,
+    `${PACKAGE_SCOPE}/tauri`,
     `${PACKAGE_SCOPE}/typegen`,
 ];
 /**

package/dist/scaffold.d.ts

@@ -1,5 +1,5 @@
-/** The two templates this rung ships. */
-export declare const TEMPLATES: readonly ["minimal", "web"];
+/** The templates this rung ships. */
+export declare const TEMPLATES: readonly ["minimal", "web", "tauri"];
 export type TemplateName = (typeof TEMPLATES)[number];
 export declare function isTemplateName(value: string): value is TemplateName;
 /** Absolute path to `template/` inside this package (works for src or dist). */

package/dist/scaffold.js

@@ -7,8 +7,8 @@ import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSyn
 import { basename, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { PACKAGE_SCOPE, PLACEHOLDER, PUBLISHED_DEPENDENCY_RANGE, } from './constants.js';
-/** The two templates this rung ships. */
-export const TEMPLATES = ['minimal', 'web'];
+/** The templates this rung ships. */
+export const TEMPLATES = ['minimal', 'web', 'tauri'];
 export function isTemplateName(value) {
     return TEMPLATES.includes(value);
 }
@@ -66,7 +66,12 @@ function substitutePlaceholders(body, projectName) {
  * skipped per-template) — substitution stays dumb and auditable rather than
  * scanning every file. Paths are relative + POSIX-joined below.
  */
-const SUBSTITUTE_FILES = ['README.md', 'src/frontend/index.html'];
+const SUBSTITUTE_FILES = [
+    'README.md',
+    'src/frontend/index.html',
+    'src/frontend/main.tsx',
+    'src-tauri/tauri.conf.json',
+];
 function directoryIsEmpty(path) {
     return readdirSync(path).length === 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-syncular-app",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Scaffold a new Syncular app: `create-syncular-app`",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -49,6 +49,6 @@
     "!dist/**/*.test.d.ts"
   ],
   "devDependencies": {
-    "@syncular/typegen": "0.2.1"
+    "@syncular/typegen": "0.4.1"
   }
 }

package/src/cli.ts

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 /**
- * `create-syncular-app [project-name] [--template <minimal|web>] [--local]`
+ * `create-syncular-app [project-name] [--template <minimal|web|tauri>]
+ * [--local]`
  *
  * Runnable as `bun create syncular-app my-app` or `bunx create-syncular-app
  * my-app`. Prompts for anything a flag did not supply. Scaffolds one of the
- * two templates (see `./scaffold`).
+ * templates (see `./scaffold`).
  */
 import { relative } from 'node:path';
 import { createInterface } from 'node:readline/promises';
-import { CLI_BIN, CREATE_BIN, PRODUCT_NAME } from './constants';
+import { CREATE_BIN, PRODUCT_NAME } from './constants';
 import {
   isTemplateName,
   scaffoldApp,
@@ -32,6 +33,9 @@ templates:
   minimal   server + a terminal two-client convergence demo (no browser)
   web       Hono server + WebSocket + a single-pane browser todo app
             (worker core on OPFS)
+  tauri     one React codebase, web + desktop: the web template's server
+            plus a src-tauri host running the native core
+            (tauri-plugin-syncular from crates.io)
 
 options:
   --template <name>   one of: ${TEMPLATES.join(', ')} (prompts if omitted)

package/src/constants.ts

@@ -31,6 +31,8 @@ export const WORKSPACE_PACKAGES = [
   `${PACKAGE_SCOPE}/server`,
   `${PACKAGE_SCOPE}/server-hono`,
   `${PACKAGE_SCOPE}/client`,
+  `${PACKAGE_SCOPE}/react`,
+  `${PACKAGE_SCOPE}/tauri`,
   `${PACKAGE_SCOPE}/typegen`,
 ] as const;
 

package/src/scaffold.ts

@@ -19,8 +19,8 @@ import {
   PUBLISHED_DEPENDENCY_RANGE,
 } from './constants';
 
-/** The two templates this rung ships. */
-export const TEMPLATES = ['minimal', 'web'] as const;
+/** The templates this rung ships. */
+export const TEMPLATES = ['minimal', 'web', 'tauri'] as const;
 export type TemplateName = (typeof TEMPLATES)[number];
 
 export function isTemplateName(value: string): value is TemplateName {
@@ -106,7 +106,12 @@ export interface ScaffoldResult {
  * skipped per-template) — substitution stays dumb and auditable rather than
  * scanning every file. Paths are relative + POSIX-joined below.
  */
-const SUBSTITUTE_FILES = ['README.md', 'src/frontend/index.html'] as const;
+const SUBSTITUTE_FILES = [
+  'README.md',
+  'src/frontend/index.html',
+  'src/frontend/main.tsx',
+  'src-tauri/tauri.conf.json',
+] as const;
 
 function directoryIsEmpty(path: string): boolean {
   return readdirSync(path).length === 0;

package/template/tauri/README.md

@@ -0,0 +1,91 @@
+# __PROJECT_NAME__
+
+A [syncular](https://github.com/bkniffler/syncular) "one codebase, web +
+desktop" app: one React tree that runs in the browser (the whole client core
+in a Web Worker on OPFS) **and** in a Tauri window (a native Rust core with a
+real file database in the host process). Every hook, component, and query is
+identical — the only host-aware code is the ~50-line engine seam in
+`src/frontend/engine.ts`.
+
+## Run the web half
+
+```sh
+bun install
+bun run generate          # syncular.json + migrations → src/syncular.generated.ts
+bun run dev               # http://localhost:8787 — sync server + web app
+```
+
+Open the URL, add todos, open a second window to watch them converge over the
+realtime socket. `bun test` runs a server-level convergence smoke test.
+
+## Run the desktop half
+
+With the dev server still running (the native core syncs against it):
+
+```sh
+cd src-tauri
+cargo tauri dev
+```
+
+`cargo tauri dev` builds the frontend (`bun run build-frontend` → `dist/`),
+compiles the Rust host, and opens the window. Edit todos in the browser and
+the desktop window side by side — same server, two radically different hosts,
+converging live.
+
+Prerequisites: [Rust](https://rustup.rs) and the
+[Tauri v2 system dependencies](https://v2.tauri.app/start/prerequisites/);
+`cargo install tauri-cli` for the `cargo tauri` subcommand. The
+`tauri-plugin-syncular` dependency comes from crates.io.
+
+> `dist/` ships with a placeholder page so a direct `cargo build` works
+> before the first frontend build (`tauri::generate_context!` hard-fails on
+> a missing `frontendDist` directory). Any `cargo tauri dev`/`build`
+> replaces it via `beforeDevCommand`.
+
+## Layout
+
+| File | What it is |
+|---|---|
+| `syncular.json` + `migrations/` | The schema manifest and SQL — typegen's input |
+| `src/syncular.generated.ts` | Generated by `syncular generate` (committed) |
+| `src/server.ts` | Sync server + WebSocket + the web frontend, one Bun process |
+| `src/frontend/engine.ts` | **The seam**: picks worker core vs native core |
+| `src/frontend/main.tsx` | The shared React tree (host-agnostic) |
+| `src/frontend/worker.ts` | The sync worker (web half only) |
+| `build-frontend.ts` | Bundles the frontend to `dist/` for the Tauri window |
+| `src-tauri/` | The desktop host: plugin registration, config, capability |
+| `src/smoke.test.ts` | Server-level convergence smoke test (`bun test`) |
+
+## How the seam works
+
+`createEngine()` detects a Tauri webview (`__TAURI_INTERNALS__`) and
+dynamic-imports either `createTauriSyncClient` (`@syncular/tauri` — an RPC
+bridge to the native core the plugin hosts) or `createSyncClientHandle`
+(`@syncular/client` — the worker core on OPFS). Both satisfy the one
+structural interface the hooks target, `SyncClientLike`, so a single
+`<SyncProvider>` serves both hosts. The dynamic imports keep each host's
+machinery out of the other's bundle.
+
+On desktop, the plugin owns the database path and the transport — see
+`src-tauri/src/lib.rs` (`SyncularConfig { base_url, db_path, .. }`) and the
+`syncular:default` permission in `src-tauri/capabilities/syncular.json`.
+
+## What to edit first
+
+1. **`src/server.ts` → `resolveScopes`** — the whole authorization story. The
+   starter returns `['*']`; a real one returns the scope values the
+   authenticated actor may see.
+2. **`src/server.ts` → `authenticate`** — plug in your real session/token
+   check; return `{ actorId, partition }` or `null` for a 401.
+3. **`src-tauri/src/lib.rs` → `base_url`** — point the native core at your
+   deployed sync endpoint (rotating auth goes through `client.setHeaders`).
+4. **`src/frontend/main.tsx`** — the UI. Everything under `<SyncProvider>` is
+   shared code; grow it into your app.
+5. **`migrations/` + `syncular.json`** — add tables and scopes, then
+   `bun run generate`.
+
+## Next
+
+- One codebase, web + desktop guide: https://syncular.dev/guide-web-desktop/
+- Tauri plugin reference: https://syncular.dev/platform-tauri/
+- React hooks: https://syncular.dev/platform-react/

package/template/tauri/build-frontend.ts

@@ -0,0 +1,47 @@
+/**
+ * Bundle the React frontend to `dist/` — the `frontendDist` the Tauri window
+ * loads (`src-tauri/tauri.conf.json` runs this as `beforeDevCommand` /
+ * `beforeBuildCommand`).
+ *
+ * Dependency-light on purpose: no Vite, no webpack. Bun's bundler transpiles
+ * the TSX (automatic JSX runtime) and bundles React + the syncular packages
+ * into one `dist/app.js`; `index.html` is copied verbatim (it references
+ * `/app.js`). `@tauri-apps/api` is bundled too, so the `@syncular/tauri`
+ * bridge's dynamic import resolves inside the webview.
+ *
+ * The web half never runs this — `src/server.ts` builds its own bundles at
+ * startup (including the worker; the Tauri webview has no worker to build).
+ *
+ * Run: `bun run build-frontend`.
+ */
+import { copyFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const root = import.meta.dir;
+const frontend = join(root, 'src', 'frontend');
+const dist = join(root, 'dist');
+
+await rm(dist, { recursive: true, force: true });
+await mkdir(dist, { recursive: true });
+
+const build = await Bun.build({
+  entrypoints: [join(frontend, 'main.tsx')],
+  outdir: dist,
+  target: 'browser',
+  // Workspace packages resolve their `bun` condition (TS source) so the
+  // build works without a compiled dist (the published `browser` condition
+  // points at compiled output for external bundlers).
+  conditions: ['bun'],
+  minify: true,
+  sourcemap: 'linked',
+  naming: { entry: 'app.js' },
+  define: { 'process.env.NODE_ENV': '"production"' },
+});
+
+if (!build.success) {
+  for (const log of build.logs) console.error(log);
+  throw new Error('frontend build failed');
+}
+
+await copyFile(join(frontend, 'index.html'), join(dist, 'index.html'));
+console.log(`frontend built → ${dist}`);

package/template/tauri/gitignore

@@ -0,0 +1,11 @@
+node_modules/
+*.log
+.DS_Store
+*.sqlite
+*.sqlite-*
+# built frontend (materialized by `bun run build-frontend`; a placeholder
+# ships with the scaffold so a direct `cargo build` works before the first
+# frontend build)
+dist/
+src-tauri/target/
+src-tauri/gen/

package/template/tauri/migrations/0001_initial/up.sql

@@ -0,0 +1,11 @@
+-- Your schema, one table to start. typegen reads this to derive the schema
+-- SHAPE (column types, primary key); the server manages its own sync_* tables
+-- and never runs this migration.
+CREATE TABLE todos (
+  id TEXT PRIMARY KEY,
+  list_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  done BOOLEAN NOT NULL,
+  position INTEGER NOT NULL,
+  updated_at_ms INTEGER NOT NULL
+);

package/template/tauri/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "__PROJECT_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun run src/server.ts",
+    "build-frontend": "bun run build-frontend.ts",
+    "generate": "syncular generate --manifest-dir .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
+    "@syncular/core": "workspace:*",
+    "@syncular/server": "workspace:*",
+    "@syncular/server-hono": "workspace:*",
+    "@syncular/client": "workspace:*",
+    "@syncular/react": "workspace:*",
+    "@syncular/tauri": "workspace:*",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@syncular/typegen": "workspace:*",
+    "@tauri-apps/api": "^2.0.0",
+    "@types/bun": "latest",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "typescript": "^5.9.0"
+  }
+}

package/template/tauri/src/frontend/engine.ts

@@ -0,0 +1,72 @@
+/**
+ * The engine seam — the ONE file that knows about hosts.
+ *
+ * Everything in `@syncular/react` targets one structural interface,
+ * `SyncClientLike`. The browser worker handle implements it, the Tauri
+ * bridge implements it, and `SyncProvider` normalizes either one — the
+ * hooks never see the difference. This file picks the client:
+ *
+ * - Inside a Tauri webview (Tauri v2 injects `__TAURI_INTERNALS__`), the
+ *   NATIVE Rust core runs in the host process — the webview is a thin RPC
+ *   proxy. The plugin owns the database path and the transport
+ *   (see `src-tauri/src/lib.rs`).
+ * - In a plain browser, the whole TypeScript core runs in a Web Worker on a
+ *   persistent OPFS database; the first tab leads, further tabs follow over
+ *   a BroadcastChannel.
+ *
+ * The dynamic imports keep each host's machinery out of the other's bundle:
+ * the web build never ships the Tauri bridge, and the Tauri webview never
+ * loads sqlite-wasm.
+ */
+import type { SyncClientLike } from '@syncular/react';
+import { schema } from '../syncular.generated';
+
+/**
+ * What the app gets back: the hook surface (`SyncClientLike`) plus the
+ * lifecycle both concrete clients share — enough for the boot sequence in
+ * `main.tsx`, still fully host-agnostic.
+ */
+export interface Engine extends SyncClientLike {
+  subscribe(input: {
+    readonly id: string;
+    readonly table: string;
+    readonly scopes: Record<string, readonly string[]>;
+  }): Promise<unknown>;
+  connectRealtime(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** Tauri v2 injects this into every webview it hosts. */
+const isTauri = () => '__TAURI_INTERNALS__' in window;
+
+/** A stable per-browser client id (the native side persists its own db). */
+function clientId(): string {
+  const KEY = 'syncular-client-id';
+  const existing = localStorage.getItem(KEY);
+  if (existing !== null) return existing;
+  const id = crypto.randomUUID();
+  localStorage.setItem(KEY, id);
+  return id;
+}
+
+export async function createEngine(): Promise<Engine> {
+  if (isTauri()) {
+    // Desktop: the native Rust core in the Tauri process.
+    const { createTauriSyncClient } = await import('@syncular/tauri');
+    return createTauriSyncClient({ clientId: clientId(), schema });
+  }
+  // Web: the whole core in a worker, persisted on OPFS.
+  const { createSyncClientHandle } = await import('@syncular/client');
+  const WS = location.protocol === 'https:' ? 'wss' : 'ws';
+  return createSyncClientHandle({
+    worker: () => new Worker('/worker.js', { type: 'module' }),
+    schema,
+    clientId: clientId(),
+    database: { mode: 'persistent', name: 'app' },
+    endpoints: {
+      syncUrl: '/sync',
+      segmentsUrl: '/segments',
+      realtimeUrl: `${WS}://${location.host}/realtime?clientId={clientId}`,
+    },
+  });
+}

package/template/tauri/src/frontend/index.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__PROJECT_NAME__</title>
+    <style>
+      :root { color-scheme: light dark; font-family: ui-sans-serif, system-ui, sans-serif; }
+      body { margin: 0; padding: 1.5rem; max-width: 40rem; margin-inline: auto; }
+      header { display: flex; align-items: baseline; gap: 0.75rem; margin-bottom: 1rem; flex-wrap: wrap; }
+      header h1 { font-size: 1.15rem; margin: 0; }
+      .status { margin-left: auto; display: flex; gap: 0.4rem; }
+      .badge { font-size: 0.72rem; padding: 0.1rem 0.5rem; border-radius: 999px; border: 1px solid currentColor; opacity: 0.85; }
+      .badge.ok { color: #16a34a; }
+      .badge.warn { color: #d97706; }
+      input, button { font: inherit; }
+      form.add { display: flex; gap: 0.5rem; margin-bottom: 0.75rem; }
+      form.add input { flex: 1; padding: 0.4rem 0.5rem; }
+      ul.todos { list-style: none; padding: 0; margin: 0; }
+      ul.todos li { display: flex; align-items: center; gap: 0.5rem; padding: 0.35rem 0.25rem; border-top: 1px solid color-mix(in srgb, currentColor 15%, transparent); }
+      ul.todos li.done .title { text-decoration: line-through; opacity: 0.55; }
+      li .title { flex: 1; }
+      button.del { cursor: pointer; }
+      .empty { opacity: 0.6; font-size: 0.9rem; padding: 0.5rem 0; }
+      .error { color: #dc2626; font-size: 0.85rem; padding: 0.35rem 0; }
+      footer { margin-top: 1.25rem; font-size: 0.78rem; opacity: 0.65; line-height: 1.5; }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/app.js"></script>
+  </body>
+</html>