@villagehq/sdk 0.2.0-beta.1 → 0.2.0-beta.2

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 Put warm introductions in your product: who your users know at a company, and who can introduce them. This page is the whole integration, written for AI coding agents and the developers working with them. Follow it top to bottom.
 
-- Package: `@villagehq/sdk` (SDK version `0.2.0-beta.1`).
+- Package: `@villagehq/sdk` (SDK version `0.2.0-beta.2`).
 - Published at https://docs.village.ai/build (raw: https://docs.village.ai/build.md). The copy in `node_modules/@villagehq/sdk/AGENTS.md` matches your installed version.
 
 ## 1. Quick start
@@ -10,7 +10,7 @@ Put warm introductions in your product: who your users know at a company, and wh
 Build and verify locally first. No Village account, human approval, card, or real network is needed until Going live.
 
 ```bash
-npm install @villagehq/sdk@0.2.0-beta.1
+npm install @villagehq/sdk@0.2.0-beta.2
 ```
 
 Use the demo keys below and follow the chosen mode's code example. If billing is not specified yet, start with the payer `user` demo while asking who pays; local verification can continue without a human response. Render `<village-connect>` and `<village-facepile company="stripe.com">`, click Connect, and verify the synthetic result.
@@ -60,36 +60,46 @@ If the app pays, use **payer `app`**. If each user pays through their Village wo
 
 ```ts
 // lib/village.ts
-'use client';
-
 import { createVillage } from '@villagehq/sdk';
-import { defineVillageElements } from '@villagehq/sdk/elements';
 
 export const village = createVillage({
   publishableKey: process.env.NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY ?? '',
 });
-
-defineVillageElements(village); // does nothing on the server
 ```
 
 ```tsx
 // components/warm-intros.tsx
 'use client';
 
-import type {} from '@villagehq/sdk/react'; // JSX types for <village-*>
-import '@/lib/village'; // registers the elements
+import type { VillagePathSelectDetail } from '@villagehq/sdk/elements';
+import { useVillageElements } from '@villagehq/sdk/react'; // also the JSX types for <village-*>
+import { useState } from 'react';
+
+import { village } from '../lib/village';
+
+function describeIntro({ person, introducer }: VillagePathSelectDetail) {
+  if (!introducer) return `You know ${person.name} directly.`;
+  return `Ask ${introducer.name} to introduce you to ${person.name}.`;
+}
 
 export function WarmIntros({ company }: { company: string }) {
+  const canRenderElements = useVillageElements(village); // registers them after hydration
+  const [selectedPath, setSelectedPath] = useState<VillagePathSelectDetail | null>(null);
+  if (!canRenderElements) return null;
+
   return (
     <section>
       <village-connect />
       <village-facepile company={company} />
-      <village-paths company={company} onvillage-path-select={(event) => askForIntro(event.detail)} />
+      <village-paths company={company} onvillage-path-select={(event) => setSelectedPath(event.detail)} />
+      {selectedPath && <p>{describeIntro(selectedPath)}</p>}
     </section>
   );
 }
 ```
 
+Render `<WarmIntros company="stripe.com" />` from any page. Paths are relative to your project root, or `src/` if you use one. Render the `<village-*>` elements only once `useVillageElements` returns `true`, never from server HTML: React doesn't attach `on*` listeners to custom elements it hydrates, and elements registered before hydration cause a hydration mismatch warning.
+
 Import `village` from `lib/village` wherever you need `village.connect()`, `village.signOut()` or a store. That's the whole integration: no server code. Sessions live in `localStorage` (`village.session.<publishableKey>`), slide for 30 days, and renew on their own. `village.signOut()` disconnects the app; call it when your user signs out.
 
 ### Payer `app`, Next.js App Router
@@ -114,11 +124,11 @@ export async function POST(request: Request) {
 The browser asks your route for it. Create the client per signed-in user:
 
 ```tsx
+// components/warm-intros.tsx
 'use client';
 
 import { createVillage } from '@villagehq/sdk';
-import { defineVillageElements } from '@villagehq/sdk/elements';
-import type {} from '@villagehq/sdk/react';
+import { useVillageElements } from '@villagehq/sdk/react';
 import { useState } from 'react';
 
 async function readVillageToken() {
@@ -129,17 +139,17 @@ async function readVillageToken() {
 }
 
 function createUserVillage() {
-  const village = createVillage({
+  return createVillage({
     publishableKey: process.env.NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY ?? '',
     token: readVillageToken,
   });
-  defineVillageElements(village);
-  return village;
 }
 
 // Render with key={user.id}, so another user gets another client.
 export function WarmIntros({ company }: { company: string }) {
-  useState(createUserVillage); // one client for this user, created once
+  const [village] = useState(createUserVillage); // one client for this user, created once
+  const canRenderElements = useVillageElements(village);
+  if (!canRenderElements) return null;
   return (
     <>
       <village-connect />
@@ -155,8 +165,8 @@ The SDK calls `token` once, then refreshes it and retries once after a 401 mappe
 
 ```html
 <script type="module">
-  import { createVillage } from 'https://esm.sh/@villagehq/sdk@0.2.0-beta.1';
-  import { defineVillageElements } from 'https://esm.sh/@villagehq/sdk@0.2.0-beta.1/elements';
+  import { createVillage } from 'https://esm.sh/@villagehq/sdk@0.2.0-beta.2';
+  import { defineVillageElements } from 'https://esm.sh/@villagehq/sdk@0.2.0-beta.2/elements';
 
   const village = createVillage({ publishableKey: 'pk_test_village_demo_user' }); // a publishable key is public
   defineVillageElements(village);
@@ -192,17 +202,18 @@ Run the actual page on localhost with the public demo keys before you say you're
 - [ ] Clicking it connects:
   - payer `user`: the synthetic user connects without a Village login or account;
   - payer `app`: with test keys, no modal opens: the test user connects at once. (On your server, `villageApp.test.connectUser({ id, email })` does the same; the page notices on its next `village.user.get()` or reload.)
-- [ ] `<village-connect>` goes `syncing`, then `ready` within about 10 s.
+- [ ] `<village-connect>` goes `syncing`, then `ready` within about 10 s. The elements wait without asking for paths meanwhile; if your own REST call gets `409 network_not_synced` during this sync, it is recoverable: call again once `GET /v2/user/status` reads `ready`.
 - [ ] No Village account, human approval, card, or real network sync was needed for this demo.
 - [ ] `<village-facepile company="stripe.com">` ends in `found` or `none`. Try 5 domains: the test network has paths for about 70% of them.
 - [ ] Clicking an item in `<village-paths>` fires `village-path-select` with a `person`.
 - [ ] Payer `user`: after `village.signOut()`, the elements go back to `signed_out`.
-- [ ] The browser console has no CSP errors (see the reference) and no `VillageError`.
+- [ ] The browser console has no hydration warning, no CSP errors (see the reference) and no `VillageError`.
 - [ ] `VILLAGE_SECRET_KEY` appears only in server code, and `.env.local` is in `.gitignore`.
 
 A script check for payer `app`:
 
 ```ts
+// scripts/check-village.ts
 import { createVillageApp } from '@villagehq/sdk/server';
 
 const villageApp = createVillageApp({ secretKey: process.env.VILLAGE_SECRET_KEY ?? '' });
@@ -222,7 +233,7 @@ Wrapped SDK calls throw `VillageError` with `code`, `message`, `status`, `reques
 | <a id="errors-signed_out"></a>`signed_out`                       | Payer `user`: no session in this browser                                             | Render a button that calls `village.connect()`                                                     |
 | <a id="errors-app_access_revoked"></a>`app_access_revoked`       | The user removed your app from Village                                               | Same as `signed_out`: the SDK already cleared the session                                          |
 | <a id="errors-not_connected"></a>`not_connected`                 | Payer `app`: the user hasn't linked Village                                          | Call `village.connect()` from a click                                                              |
-| <a id="errors-not_synced"></a>`not_synced`                       | The network has not been synced, or sync is unfinished                               | Connect/sync if needed, then show progress; use `error.syncUrl` when present                       |
+| <a id="errors-not_synced"></a>`not_synced`                       | HTTP 409 `network_not_synced`: the first network sync hasn't finished                | Recoverable. Show progress; stores and elements load on their own once the network is `ready`      |
 | <a id="errors-out_of_credits"></a>`out_of_credits`               | Out of credits. `error.payer` says whose when provided                               | `user`: link `error.topupUrl` if present. `app`: top up in the dashboard; payer can be null        |
 | <a id="errors-unauthorized"></a>`unauthorized`                   | Invalid key or token, or the app is inactive (live keys need a card for payer `app`) | `user`: connect again. `app`: check keys, token route and live billing; callback tokens retry once |
 | <a id="errors-user_required"></a>`user_required`                 | A payer `user` app called Village without a signed-in user                           | Call `village.connect()` first; don't mint tokens for payer `user` apps                            |
@@ -245,7 +256,7 @@ Wrapped SDK calls throw `VillageError` with `code`, `message`, `status`, `reques
 After the local demo passes, create your own Village app:
 
 ```bash
-npx @villagehq/sdk@0.2.0-beta.1 init --name "Acme" --payer user   # or --payer app
+npx @villagehq/sdk@0.2.0-beta.2 init --name "Acme" --payer user   # or --payer app
 ```
 
 `init` defaults to `http://localhost:3000`. If your local app uses another port, pass its actual origin, for example `--origin http://localhost:3010`.
@@ -276,7 +287,7 @@ CLI flags: `--name`, `--origin`, `--payer app|user`, `--yes` (`-y`), `--help` (`
 
 ### Elements
 
-Register once with `defineVillageElements(village)` (from `@villagehq/sdk/elements`).
+Register with `defineVillageElements(village)` (from `@villagehq/sdk/elements`). In React, use `useVillageElements(village)` instead and render the elements once it returns `true`, as in the Next.js code above. Registering another client switches every element on the page to it.
 
 | Element              | Attributes                                                        | Shows                                                                                                 |
 | -------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
@@ -329,7 +340,7 @@ Events (bubbling, composed `CustomEvent`s):
 | `village-connected`   | `{ user }`, after `connect()` leaves the user connected (not when they close the popup or modal without connecting)                                                 |
 | `village-error`       | `{ error }`, when `connect()` fails, e.g. `popup_blocked`                                                                                                           |
 
-**React 19 + Tailwind.** `import type {} from '@villagehq/sdk/react'` adds the JSX types. Events are `on` + the event name:
+**React 19 + Tailwind.** Importing from `@villagehq/sdk/react` (or `import type {} from '@villagehq/sdk/react'`) adds the JSX types. Events are `on` + the event name; they work on elements rendered after `useVillageElements` returns `true`:
 
 ```tsx
 <village-facepile
@@ -378,7 +389,7 @@ What the stores do for you:
 - **Shared**: the same company returns the same store, so 50 badges make one fetch.
 - **Batched**: every `check` asked for in the same tick goes out as one request (100 companies each).
 - **Credit-safe**: a store fetches on its first subscriber and keeps its result after the last one leaves. It never retries on its own; `refresh()` does.
-- **Live**: a `not_synced` store fetches again when the network turns ready; every store resets on sign-out.
+- **Live**: while the first sync runs, a store waits as `not_synced` without asking Village for paths, then fetches once the network turns ready; every store resets on sign-out.
 
 React:
 
@@ -393,7 +404,7 @@ function IntroBadge({ company }: { company: string }) {
 }
 ```
 
-Also `useVillageUser(village)` → `{ user, status, isLoading, error, refresh }`, `useVillageConnect(village)` → `{ connect, isConnecting }`, and `<VillageGate village fallback>`.
+Also `useVillageElements(village)` → `true` once the elements can render (see section 4), `useVillageUser(village)` → `{ user, status, isLoading, error, refresh }`, `useVillageConnect(village)` → `{ connect, isConnecting }`, and `<VillageGate village fallback>`.
 
 Vue:
 

package/README.md

@@ -5,17 +5,54 @@ Start at https://docs.village.ai/build.
 Put Village warm introductions in your product: who your users know at a company, and who can introduce them. The complete guide also ships as [`AGENTS.md`](./AGENTS.md), matching your installed SDK version.
 
 ```bash
-npm install @villagehq/sdk@0.2.0-beta.1
+npm install @villagehq/sdk@0.2.0-beta.2
 ```
 
-Start locally with the public synthetic demo keys from the guide. No Village account, human approval, card, or real network is needed. Follow the chosen payer mode; if it is unclear, ask who pays asynchronously and verify the payer `user` demo while waiting. Run `npx @villagehq/sdk@0.2.0-beta.1 init` when you reach Going live.
+## Demo in two minutes (Next.js App Router)
 
-| Import                    | What                                                                                                              |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `@villagehq/sdk`          | `createVillage`: user status, `connect()`, stores (`village.paths.*`), search, paths, enrichment, the typed `api` |
-| `@villagehq/sdk/elements` | `<village-connect>`, `<village-facepile>`, `<village-paths>` web components                                       |
-| `@villagehq/sdk/react`    | `useVillage(store)`, `useVillageUser`, `useVillageConnect`, `<VillageGate>`, JSX types for the elements           |
-| `@villagehq/sdk/server`   | `createVillageApp({ secretKey })`: tokens, acting as a user, test users                                           |
+Add the public demo key to `.env.local`. It works on `localhost` against a synthetic network, with no account:
+
+```dotenv
+NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY=pk_test_village_demo_user
+```
+
+```tsx
+// components/warm-intros.tsx
+'use client';
+
+import { createVillage } from '@villagehq/sdk';
+import { useVillageElements } from '@villagehq/sdk/react';
+
+const village = createVillage({
+  publishableKey: process.env.NEXT_PUBLIC_VILLAGE_PUBLISHABLE_KEY ?? '',
+});
+
+export function WarmIntros({ company = 'stripe.com' }: { company?: string }) {
+  const canRenderElements = useVillageElements(village); // registers the elements after hydration
+  if (!canRenderElements) return null;
+
+  return (
+    <section>
+      <village-connect />
+      <village-facepile company={company} />
+      <village-paths company={company} />
+    </section>
+  );
+}
+```
+
+Render `<WarmIntros />` in `app/page.tsx`, restart `npm run dev` and open the page. You should see a **Connect Village** button. Click it: no login opens, it shows "Syncing your network…" for about 5 seconds, then "Village connected", a facepile with a strength label, and a list of people who can introduce you. The people are synthetic. About 30% of domains have no paths and show "No warm intros yet". The console stays free of errors.
+
+There is no `Village.init`, `Village.findPaths` or default export, and `@village-ai/sdk` is another package: use `createVillage`, `village.paths.*` and the `<village-*>` elements.
+
+Start locally with the public synthetic demo keys from the guide. No Village account, human approval, card, or real network is needed. Follow the chosen payer mode; if it is unclear, ask who pays asynchronously and verify the payer `user` demo while waiting. Run `npx @villagehq/sdk@0.2.0-beta.2 init` when you reach Going live.
+
+| Import                    | What                                                                                                                          |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `@villagehq/sdk`          | `createVillage`: user status, `connect()`, stores (`village.paths.*`), search, paths, enrichment, the typed `api`             |
+| `@villagehq/sdk/elements` | `<village-connect>`, `<village-facepile>`, `<village-paths>` web components                                                   |
+| `@villagehq/sdk/react`    | `useVillageElements`, `useVillage(store)`, `useVillageUser`, `useVillageConnect`, `<VillageGate>`, JSX types for the elements |
+| `@villagehq/sdk/server`   | `createVillageApp({ secretKey })`: tokens, acting as a user, test users                                                       |
 
 ## Developing
 

package/dist/core/paths-stores.d.ts

@@ -55,29 +55,14 @@ type PathsStoresOptions<PersonPaths, CompanyPathsPage> = {
         company: (page: CompanyPathsPage) => boolean;
     };
     watchUser: () => () => void;
+    isFirstSyncRunning: () => Promise<boolean>;
 };
 export type CompanyPathsStoreOptions = {
     degrees?: Array<1 | 2 | 3>;
     limit?: number;
 };
-export declare function createPathsStores<PersonPaths, CompanyPathsPage>({ payer, checkCompany, personPaths, companyPaths, hasPaths, watchUser, }: PathsStoresOptions<PersonPaths, CompanyPathsPage>): {
-    check: (company: string) => import("./store.js").VillageStore<{
-        kind: "signed_out";
-    } | {
-        kind: "not_connected";
-    } | {
-        kind: "not_synced";
-    } | {
-        kind: "out_of_credits";
-        payer: Payer;
-        topupUrl: string | null;
-    } | LoadingState | NoneState | ErrorState | {
-        kind: "found";
-        people: FacepilePerson[];
-        more: number;
-        strength: number | null;
-        strength_label: string | null;
-    }>;
+export declare function createPathsStores<PersonPaths, CompanyPathsPage>({ payer, checkCompany, personPaths, companyPaths, hasPaths, watchUser, isFirstSyncRunning, }: PathsStoresOptions<PersonPaths, CompanyPathsPage>): {
+    check: (company: string) => import("./store.js").VillageStore<PathsCheckState>;
     person: (personInput: string) => import("./store.js").VillageStore<PathsState<PersonPaths>>;
     company: (companyInput: string, { degrees, limit }?: CompanyPathsStoreOptions) => import("./store.js").VillageStore<PathsState<CompanyPathsPage>>;
     reloadAll: () => void;

package/dist/core/paths-stores.js

@@ -4,6 +4,7 @@ import { createStore } from './store.js';
 const BULK_CHECK_LIMIT = 100;
 const LOADING = { kind: 'loading' };
 const NONE = { kind: 'none' };
+const NOT_SYNCED = { kind: 'not_synced' };
 const BLOCKED_STATE_BY_CODE = {
     signed_out: { kind: 'signed_out' },
     app_access_revoked: { kind: 'signed_out' },
@@ -61,7 +62,7 @@ function toCheckState(check) {
 function waitsForNetwork(state) {
     return state.kind === 'not_synced';
 }
-export function createPathsStores({ payer, checkCompany, personPaths, companyPaths, hasPaths, watchUser, }) {
+export function createPathsStores({ payer, checkCompany, personPaths, companyPaths, hasPaths, watchUser, isFirstSyncRunning, }) {
     const checks = new Map();
     const people = new Map();
     const companies = new Map();
@@ -84,11 +85,17 @@ export function createPathsStores({ payer, checkCompany, personPaths, companyPat
     }
     function check(company) {
         const identifier = toCompanyIdentifier(company);
-        return cached(checks, JSON.stringify(identifier), LOADING, () => checkCompany(identifier).then(toCheckState, toFailureState));
+        return cached(checks, JSON.stringify(identifier), LOADING, async () => {
+            if (await isFirstSyncRunning())
+                return NOT_SYNCED;
+            return checkCompany(identifier).then(toCheckState, toFailureState);
+        });
     }
     function person(personInput) {
         const identifier = toPersonIdentifier(personInput);
         return cached(people, JSON.stringify(identifier), LOADING, async () => {
+            if (await isFirstSyncRunning())
+                return NOT_SYNCED;
             try {
                 const paths = await personPaths(personInput);
                 if (paths === null || !hasPaths.person(paths))
@@ -104,6 +111,8 @@ export function createPathsStores({ payer, checkCompany, personPaths, companyPat
         const identifier = toCompanyIdentifier(companyInput);
         const key = JSON.stringify([identifier, degrees ?? null, limit ?? null]);
         return cached(companies, key, LOADING, async () => {
+            if (await isFirstSyncRunning())
+                return NOT_SYNCED;
             try {
                 const page = await companyPaths(companyInput, { ...(degrees ? { degrees } : {}), ...(limit ? { limit } : {}) });
                 if (page === null || !hasPaths.company(page))

package/dist/core/village.d.ts

@@ -1,5 +1,4 @@
 import type { components, paths } from '../generated/api.js';
-import type { Payer } from './api-types.js';
 import { isVillageError, VillageError } from './errors.js';
 import { type Page } from './pages.js';
 import { type SessionStorage } from './session.js';
@@ -78,30 +77,7 @@ export declare function createVillage(options: VillageOptions): {
     connect: () => Promise<VillageUser>;
     signOut: () => Promise<void>;
     paths: {
-        check: (company: string) => import("./store.js").VillageStore<{
-            kind: "signed_out";
-        } | {
-            kind: "not_connected";
-        } | {
-            kind: "not_synced";
-        } | {
-            kind: "out_of_credits";
-            payer: Payer;
-            topupUrl: string | null;
-        } | {
-            kind: "loading";
-        } | {
-            kind: "none";
-        } | {
-            kind: "error";
-            error: VillageError;
-        } | {
-            kind: "found";
-            people: import("./api-types.js").FacepilePerson[];
-            more: number;
-            strength: number | null;
-            strength_label: string | null;
-        }>;
+        check: (company: string) => import("./store.js").VillageStore<import("./paths-stores.js").PathsCheckState>;
         person: (personInput: string) => import("./store.js").VillageStore<import("./paths-stores.js").PathsState<{
             person: components["schemas"]["PersonInfo"];
             summary: components["schemas"]["PathSummary"];

package/dist/core/village.js

@@ -13,6 +13,7 @@ export { linkedinSlug, linkedinUrl } from './identifiers.js';
 export { openSyncModal } from './sync-modal.js';
 export { isNetworkReady } from './user.js';
 const DEFAULT_APP_URL = 'https://village.ai';
+const DEMO_KEYS_URL = 'https://docs.village.ai/build#2-public-demo-keys';
 const SEARCH_TIMEOUT_MS = 120_000;
 const PATHS_TIMEOUT_MS = 60_000;
 const TEST_MODE = 'test';
@@ -43,7 +44,7 @@ function requirePublishableKey(publishableKey) {
         return publishableKey;
     throw new VillageError({
         code: 'bad_request',
-        message: 'Pass createVillage({ publishableKey }) when users pay, or { token } when your app pays. Run `npx @villagehq/sdk init` to get keys.',
+        message: `Pass createVillage({ publishableKey }) when users pay, or { token } when your app pays. To build locally, use the public demo key pk_test_village_demo_user (no account needed): ${DEMO_KEYS_URL}`,
     });
 }
 function signedOutError() {
@@ -149,6 +150,25 @@ export function createVillage(options) {
         }
     }
     const { store: user, replace: replaceUser } = createUserStore(readUser, handleUserChange);
+    let sharedUserRead = null;
+    // Stores that load together share one status read.
+    function readUserOnce() {
+        sharedUserRead ??= user
+            .get()
+            .catch(() => null)
+            .finally(() => {
+            sharedUserRead = null;
+        });
+        return sharedUserRead;
+    }
+    async function isFirstSyncRunning() {
+        if (isNetworkReady(user.snapshot().user))
+            return false;
+        await readUserOnce();
+        // The snapshot, not this read: a newer read may already have found the network ready.
+        const latest = user.snapshot().user;
+        return latest?.status === 'syncing' && latest.network_updated_at === null;
+    }
     function endSession() {
         replaceUser(SIGNED_OUT_USER);
         pathStores.reloadAll();
@@ -268,6 +288,7 @@ export function createVillage(options) {
         },
         // A fresh listener each time: the user store keeps listeners in a Set.
         watchUser: () => user.subscribe(() => undefined),
+        isFirstSyncRunning,
     });
     async function joinGroup(inviteLink, options) {
         try {

package/dist/elements/elements.js

@@ -132,9 +132,11 @@ function createElementClasses(requireVillage) {
         connectedCallback() {
             this.unbind();
             this.stopWatching = this.watch(requireVillage());
+            connectedElements.add(this);
         }
         disconnectedCallback() {
             this.unbind();
+            connectedElements.delete(this);
         }
         attributeChangedCallback() {
             if (this.stopWatching)
@@ -286,13 +288,16 @@ function createElementClasses(requireVillage) {
     };
 }
 let activeVillage = null;
+const connectedElements = new Set();
 function requireVillage() {
     if (activeVillage)
         return activeVillage;
     throw new Error('Call defineVillageElements(village) before using Village elements.');
 }
 // Safe to import on a server: nothing touches the DOM until this runs in a browser.
+// Call it again with another client (another signed-in user) and every element on the page switches to it.
 export function defineVillageElements(village) {
+    const isNewClient = activeVillage !== null && activeVillage !== village;
     activeVillage = village;
     if (typeof customElements === 'undefined')
         return;
@@ -300,4 +305,7 @@ export function defineVillageElements(village) {
         if (!customElements.get(tag))
             customElements.define(tag, elementClass);
     }
+    if (isNewClient)
+        for (const element of connectedElements)
+            element.connectedCallback();
 }

package/dist/react/react.d.ts

@@ -2,7 +2,14 @@ import { type DetailedHTMLProps, type HTMLAttributes, type ReactNode } from 'rea
 import type { VillageStore } from '../core/store.js';
 import { type VillageUser } from '../core/user.js';
 import type { Village } from '../core/village.js';
-import type { VillageConnectedDetail, VillageErrorDetail, VillagePathSelectDetail } from '../elements/elements.js';
+import { type VillageConnectedDetail, type VillageErrorDetail, type VillagePathSelectDetail } from '../elements/elements.js';
+/**
+ * Registers the Village elements for this client after hydration and returns true once they can
+ * render. Render `<village-*>` only when it does: React doesn't attach `on*` listeners to custom
+ * elements it hydrates from server HTML, an element defined before hydration causes a mismatch
+ * warning, and an element mounted before its client is registered would show the previous client's data.
+ */
+export declare function useVillageElements(village: Village): boolean;
 export declare function useVillage<State>(store: VillageStore<State>): State;
 export declare function useVillageUser(village: Village): {
     user: VillageUser | null;

package/dist/react/react.js

@@ -1,9 +1,24 @@
 'use client';
-import { useCallback, useState, useSyncExternalStore, } from 'react';
+import { useCallback, useEffect, useState, useSyncExternalStore, } from 'react';
 import { isNetworkReady } from '../core/user.js';
+import { defineVillageElements, } from '../elements/elements.js';
 function ignoreFailure() {
     return undefined;
 }
+/**
+ * Registers the Village elements for this client after hydration and returns true once they can
+ * render. Render `<village-*>` only when it does: React doesn't attach `on*` listeners to custom
+ * elements it hydrates from server HTML, an element defined before hydration causes a mismatch
+ * warning, and an element mounted before its client is registered would show the previous client's data.
+ */
+export function useVillageElements(village) {
+    const [registeredVillage, setRegisteredVillage] = useState(null);
+    useEffect(() => {
+        defineVillageElements(village);
+        setRegisteredVillage(village);
+    }, [village]);
+    return registeredVillage === village;
+}
 export function useVillage(store) {
     const subscribe = useCallback((onChange) => store.subscribe(onChange), [store]);
     return useSyncExternalStore(subscribe, store.get, store.get);

package/dist/server/server.d.ts

@@ -1,5 +1,4 @@
 import type { paths } from '../generated/api.js';
-import { VillageError } from '../core/errors.js';
 import { type CallOptions, type TransportOptions } from '../core/transport.js';
 type AppUpdate = NonNullable<paths['/v2/app']['patch']['requestBody']>['content']['application/json'];
 export type TokenGrant = 'full' | 'public';
@@ -23,30 +22,7 @@ export declare function createVillageApp({ secretKey, appUrl, ...transportOption
         connect: () => Promise<import("../core/user.js").VillageUser>;
         signOut: () => Promise<void>;
         paths: {
-            check: (company: string) => import("../core/store.js").VillageStore<{
-                kind: "signed_out";
-            } | {
-                kind: "not_connected";
-            } | {
-                kind: "not_synced";
-            } | {
-                kind: "out_of_credits";
-                payer: import("../core/api-types.js").Payer;
-                topupUrl: string | null;
-            } | {
-                kind: "loading";
-            } | {
-                kind: "none";
-            } | {
-                kind: "error";
-                error: VillageError;
-            } | {
-                kind: "found";
-                people: import("../core/api-types.js").FacepilePerson[];
-                more: number;
-                strength: number | null;
-                strength_label: string | null;
-            }>;
+            check: (company: string) => import("../core/store.js").VillageStore<import("../core/paths-stores.js").PathsCheckState>;
             person: (personInput: string) => import("../core/store.js").VillageStore<import("../core/paths-stores.js").PathsState<{
                 person: import("../generated/api.js").components["schemas"]["PersonInfo"];
                 summary: import("../generated/api.js").components["schemas"]["PathSummary"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@villagehq/sdk",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.2",
   "description": "Put Village warm intros in your app: intro paths, people and company search, drop-in web components, and a setup CLI.",
   "keywords": [
     "village",
@@ -65,6 +65,7 @@
   "devDependencies": {
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.3.0",
     "jsdom": "^26.1.0",
     "openapi-typescript": "^7.10.0",
     "react": "^19.1.0",