+
+
+ {message.authorName || actorUsername(message.authorId)}
+
+ @{domain}
+
+
+
+ {message.body}
+Count: {count}
; -} -``` diff --git a/.agents/skills/shopify/SKILL.md b/.agents/skills/shopify/SKILL.md deleted file mode 100644 index 9e37360a..00000000 --- a/.agents/skills/shopify/SKILL.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: shopify -description: Use whenever the scope of your task touches the shopify package or its uses anywhere in the project. ---- - -This project uses Shopify headless. `@acme/shopify` is configured so that GraphQL queries written inside the package will have TypeScript types generated for them. - -As you are working on any Shopify/GraphQL code in this project, make sure you STRICTLY adhere to the principles listed below. If you think there might actually be a valid use case for breaking them, pause and confirm first with the user. - -## Principles - -- Since the Shopify package generates types for the GraphQL queries written in it, you should ALWAYS write GraphQL queries inside the shopify package. Writing them directly in the app code will not result in generated types and will therefore not give you any type safety. -- You should always rely on type inference for getting the types of the data returned from GraphQL queries. You should NEVER have to use generics or type casting on the GraphQL operations being called from the app code. -- **AVOID AT ALL COSTS** normalizing the data returned from the GraphQL queries. You should not need to write custom functions to transform the data returned from them into a custom shape defined in the app code. You should ALWAYS rely on the types generated from the shopify package. - -## Required Actions - -After creating or modifying any GraphQL queries in the shopify package, you must always run: - -`pnpm --filter @acme/shopify run build` diff --git a/.agents/skills/typescript/SKILL.md b/.agents/skills/typescript/SKILL.md deleted file mode 100644 index 9f6b5c6b..00000000 --- a/.agents/skills/typescript/SKILL.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -name: typescript -description: TypeScript coding standards for this project. Use when writing or modifying TypeScript files. ---- - -# TypeScript - -These are the TypeScript standards for this project. Follow them when writing or modifying any TypeScript code. - -## Const Assertions - -Use `as const` to preserve exact literal types and `readonly`. This is the one acceptable use of `as` since it tightens types rather than loosening them. - -- Use on configuration objects, lookup maps, and any data that defines a fixed set of values. -- Use on arrays that represent a known set of options, then derive union types: `type Status = (typeof STATUS)[number]`. -- Prefer `as const` over manually writing literal union types when the source of truth is an array or object. -- Pair with `satisfies` when you need both exact literal types and structural validation. - -```typescript -const STATUS = ["idle", "loading", "success", "error"] as const; -type Status = (typeof STATUS)[number]; - -const PLAN_LIMITS = { - free: { projects: 3, storage: 500 }, - pro: { projects: 50, storage: 10_000 }, -} as const satisfies Record- -
-
-
-
+Vera is the reference application and current incubator for decentralized
+Convex: a small toolkit for building applications whose data and realtime
+subscriptions span independently hosted Convex deployments.
-A great starting point for building agentic applications for the web.
+The current branch proves one private, reactive conversation across two PDSs.
+It is intentionally a vertical slice, not a production messaging product yet.
-For more information, head over to the [docs](https://docs.vera.chat)
+## Start here
-
-
+Read these files in order to follow one request end to end: -[x.com/bentsignal](https://x.com/bentsignal) +1. `packages/decentralized-convex-messages/protocol.ts` defines the typed + Messages API and its dependency on Accounts. +2. `services/backend/convex/convex.config.ts` installs the PDS auth adapter, + Accounts, and Messages in one validated PDS app. +3. `services/backend/convex/pds.ts` exposes the canonical public dispatcher. +4. `packages/decentralized-convex-messages/dispatcher.ts` implements the + Messages operations inside its Component. +5. `apps/web/src/features/conversation/useConversation.ts` shows the complete + client API used for reactive reads and writes. -
+The longer explanation is in [docs/architecture.md](docs/architecture.md). +The lockstep `0.1.0` release and upgrade rules are in +[docs/versioning.md](docs/versioning.md). -
+## The default setup
+
+A PDS installs ordinary third-party Components and decentralized-convex
+plugins declaratively:
+
+```ts
+import accounts from "@decentralized-convex/accounts/convex.config";
+import messages from "@decentralized-convex/messages/convex.config";
+import { definePdsApp } from "@decentralized-convex/server";
+import { pdsAuth } from "../pds-auth";
+
+export default definePdsApp({
+ auth: pdsAuth,
+ plugins: [accounts, messages],
+});
+```
+
+Messages declares an exact dependency on Accounts at the shared ecosystem
+version. Removing Accounts or
+installing an incompatible version fails type-checking. The normal
+`convex dev`, `convex deploy`, and `convex codegen` commands remain unchanged.
+
+The common client path uses the application's own TanStack hooks:
+
+```ts
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { pdsMutation, pdsQuery } from "@decentralized-convex/tanstack-query";
+import { pds } from "@vera/backend/pds";
+
+const messages = useQuery(
+ pdsQuery({
+ args: { conversationId },
+ query: pds.messages.list,
+ }),
+);
+const sendMessage = useMutation(
+ pdsMutation({ mutation: pds.messages.send }),
+);
+```
+
+The backend's `pds` export derives its plugin names, versions, operations, and
+types from the same `definePdsApp` declaration. The web app never repeats the
+installed plugin list, and the discovery manifest derives its capabilities
+from the same protocol tuple.
+
+The query starts at the signed-in account's home PDS, reads routing identities
+stored with the conversation, discovers their current deployments, and merges
+live results. Mutations automatically target home. Ordinary TanStack options,
+connection factories, explicit lower-level federation, and destination-aware
+authentication remain available when an application needs control.
+
+## Workspace
+
+- `packages/decentralized-convex-plugin` — operation protocols and dependency
+ graph validation
+- `packages/decentralized-convex-core` — the single ecosystem version and
+ last-changed release metadata
+- `packages/decentralized-convex-server` — PDS installation, root dispatch,
+ Component dispatch, and discovery descriptors
+- `packages/decentralized-convex-auth-better-auth` — Better Auth adapter for
+ the public PDS auth protocol
+- `packages/decentralized-convex-client` — discovery, connections, typed calls,
+ federation, and subscriptions
+- `packages/decentralized-convex-react` — client provider
+- `packages/decentralized-convex-tanstack-query` — native TanStack option builders
+- `packages/decentralized-convex-accounts` and `-messages` — first-party plugins
+- `services/backend` — Vera's thin Better Auth PDS host
+- `apps/web` — the Vera reference client
+- `legacy` — the archived centralized Vera application
+
+## Development
+
+```sh
+pnpm install
+pnpm --filter @vera/web dev
+```
+
+The web app runs at `https://www.vera.localhost`.
diff --git a/apps/web/.env.example b/apps/web/.env.example
new file mode 100644
index 00000000..bc86437f
--- /dev/null
+++ b/apps/web/.env.example
@@ -0,0 +1,4 @@
+VITE_HOME_A_CONVEX_URL=https://your-a-deployment.convex.cloud
+VITE_HOME_A_SITE_URL=https://your-a-deployment.convex.site
+VITE_HOME_B_CONVEX_URL=https://your-b-deployment.convex.cloud
+VITE_HOME_B_SITE_URL=https://your-b-deployment.convex.site
diff --git a/apps/web/README.md b/apps/web/README.md
new file mode 100644
index 00000000..5469f7df
--- /dev/null
+++ b/apps/web/README.md
@@ -0,0 +1,98 @@
+# Vera web
+
+A TanStack Start messaging client that reads one private conversation across
+independent Convex PDS deployments.
+
+## Code tour
+
+- `features/account/AccountEntry.tsx` discovers a PDS from `username@domain`.
+- `features/account/AccountSession.tsx` owns the local auth session and creates
+ the decentralized client.
+- `features/pds/auth.ts` is the replaceable Better Auth federation adapter.
+- `features/pds/model.ts` contains the explicitly temporary two-home fixture.
+- `features/conversation/useConversation.ts` is the complete data path.
+- `features/conversation/Conversation.tsx` is presentation only.
+
+```sh
+pnpm --filter @vera/web dev
+```
+
+Open `https://www.vera.localhost` and:
+
+1. Enter a full Vera address such as `alice@a.vera.chat`.
+2. Create or sign into that account on its discovered home PDS.
+3. Send messages. Vera reads the conversation from both development PDSs with
+ the one home login.
+
+Home discovery happens before sign-in. The address entry screen resolves the
+account domain and keeps that verified descriptor as `home`; both auth and the
+decentralized client use the same value:
+
+```ts
+const home = assertPdsCompatibility(
+ await discoverPds("alice@a.vera.chat"),
+ pds,
+);
+
+const authClient = createHomeAuthClient(home);
+const client = new DecentralizedConvexClient({
+ getAuthToken,
+ pds: { home },
+});
+```
+
+Signing in creates the authenticated session on that already-discovered home.
+It does not produce or replace the `home` value.
+
+Each signup and outgoing message is stored only on the selected home
+deployment. Each home keeps its own isolated Better Auth and Messages Component
+data. The home PDS issues a short-lived, destination-bound identity proof; the
+other PDS verifies it through discovery and returns a local Convex credential.
+The selected account stores its conversation routing identities on its own PDS.
+The client first subscribes there, discovers the current participant PDSs from
+that response, then opens authenticated subscriptions and reconciles the
+results through TanStack Query.
+
+The account address uses the PDS's public account domain, never its internal
+`convex.cloud` transport hostname. Better Auth is Vera's current host adapter,
+not a dependency of the reusable decentralized Convex packages.
+
+The checked-in `.env.example` documents the deployment configuration. Deploy
+the same `convex/` backend to each target and set `SITE_URL` and
+`FEDERATION_DOMAIN` on each deployment. Publish the single `_pds` TXT discovery
+record described in the backend README. Free and Pro Convex deployments use the
+same discovery flow; Convex custom domains are optional.
+
+The web app imports the typed `pds` API derived from Vera's backend app
+definition. It does not declare a second plugin list or import either
+deployment's generated message API; both homes expose the same canonical
+`pds:dispatchQuery` and `pds:dispatchMutation` functions.
+
+The common read and write paths use the PDS query adapter with the
+application's TanStack Query instance:
+
+```ts
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { pdsMutation, pdsQuery } from "@decentralized-convex/tanstack-query";
+import { pds } from "@vera/backend/pds";
+
+const messages = useQuery(
+ pdsQuery({
+ query: pds.messages.list,
+ args: { conversationId },
+ }),
+);
+
+if (messages.data.status === "success") {
+ messages.data.result; // Message[]
+}
+
+messages.data.federation.sources;
+
+const sendMessage = useMutation(pdsMutation({ mutation: pds.messages.send }));
+```
+
+PDS reads hide partial results for `500ms` by default while participant homes
+deliver their first snapshots. Set `options.revealPartialResultsAfter` in
+`pdsQuery` to override the delay. Complete data returns immediately, and a
+temporary disconnect retains the affected PDS's last known data.
diff --git a/apps/web/eslint.config.ts b/apps/web/eslint.config.ts
new file mode 100644
index 00000000..d9d8cf1b
--- /dev/null
+++ b/apps/web/eslint.config.ts
@@ -0,0 +1,11 @@
+import { defineConfig } from "eslint/config";
+
+import { baseConfig, strictConfig } from "@acme/eslint-config/base";
+import { reactConfig } from "@acme/eslint-config/react";
+
+export default defineConfig(
+ { ignores: ["src/routeTree.gen.ts"] },
+ baseConfig,
+ strictConfig,
+ reactConfig,
+);
diff --git a/apps/web/index.html b/apps/web/index.html
deleted file mode 100644
index 9b390577..00000000
--- a/apps/web/index.html
+++ /dev/null
@@ -1,208 +0,0 @@
-
-
-
-
-
-
-
-
- -
+Read these files in order to follow one request end to end: -[x.com/bentsignal](https://x.com/bentsignal) +1. `packages/decentralized-convex-messages/protocol.ts` defines the typed + Messages API and its dependency on Accounts. +2. `services/backend/convex/convex.config.ts` installs the PDS auth adapter, + Accounts, and Messages in one validated PDS app. +3. `services/backend/convex/pds.ts` exposes the canonical public dispatcher. +4. `packages/decentralized-convex-messages/dispatcher.ts` implements the + Messages operations inside its Component. +5. `apps/web/src/features/conversation/useConversation.ts` shows the complete + client API used for reactive reads and writes. -
+The longer explanation is in [docs/architecture.md](docs/architecture.md). +The lockstep `0.1.0` release and upgrade rules are in +[docs/versioning.md](docs/versioning.md). -
+
+ Vera
+Sign in with your address on any compatible PDS.
+Could not connect to the conversation
+{federation.error.message}
+ +Connecting to {home.domain}
+
+
+ {isSignUp ? "Create account" : "Sign in"}
+{props.home.domain}
+
+
+ Prototype conversation
+{description}
+
+
+
+ {live}/{sources.length} connected
+
+
+
+
+ );
+}
+
+function MessageList({
+ home,
+ messages,
+}: {
+ home: HomePds;
+ messages: {
+ data: PdsQueryDataDebug
+
+ Connections
+
+
+ {sources.map((source) => (
+
+
+
+
+ ))}
+ {new URL(source.target.url).hostname}
+ {source.status}
+ -
+
- Write target +
- {home.domain} +
- Local auth +
- Better Auth +
- Remote reads +
- Authenticated per home server +
+
+
+
+
+
+
+ {messages.data.status === "partial" ? (
+
+ ) : null}
+ {messages.data.status === "loading" ? (
+
+ );
+}
+
+function Message({ message }: { message: ChatMessage }) {
+ const domain = message.authorId.split("@")[1] ?? message.authorId;
+ return (
+ Connecting to participant servers…
+ ) : null} + {messages.data.status === "error" ? ( +{messages.data.error.message}
+ ) : null} + {(messages.data.status === "partial" || + messages.data.status === "success") && + messages.data.result.length === 0 ? ( +
+ #
+ No messages yet
+
+ ) : null}
+ {messages.data.status === "partial" || messages.data.status === "success"
+ ? messages.data.result.map((message) => (
+ Start the conversation from {home.domain}.
+