@roughapp/feature 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,66 @@ All notable changes to `@roughapp/feature`.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This package is pre-1.0, so a minor version bump can contain breaking changes.
 
+## 0.3.0 - 2026-08-10
+
+**This release has breaking API changes.** Rough now uses an explicit client for
+each project instead of global initialization. Apps can safely show features
+from multiple Rough projects at the same time, and each client has a clear,
+awaitable lifecycle.
+
+### Added
+
+- **`createRoughClient({ projectId, baseUrl?, fetchUserToken })`** creates and
+  starts a client for one project. Keep the client for as long as your app needs
+  that project, then call `await client.destroy()`.
+- **`whenRoughClientReady({ client })`** lets you wait for startup or handle a
+  startup error.
+- **`openRoughCreate({ target })`** lets you attach the create modal inside the
+  element that scopes your Rough theme. It defaults to `document.body`.
+
+### Changed
+
+- **All stateful functions and components now take a client.** Pass `client` and
+  `surface` to `getRoughFeatures()`, `openRoughCreate()`, `<rough-surface>`,
+  `<rough-feature>`, `<rough-edit-button>` and the modal elements.
+- **Cleanup methods are asynchronous and safe to call more than once.** Await
+  `client.destroy()`, `subscription.unsubscribe()` and `modal.close()` when you
+  need to know that cleanup has finished.
+- **Create one client and share it for each signed-in person and project.** A
+  second client for the same `baseUrl`, `projectId` and person fails with
+  `RoughReplicacheIdentityConflictError`. Clients for different projects or
+  different signed-in people can run together.
+- **`openRoughCreate()` no longer requires a mounted Rough component.** You can
+  open it directly with a client and surface.
+
+### Removed
+
+- **`initRough()` has been removed.** There is no default or global client.
+- **`defineSurface()` has been replaced by `defineRoughSurface()`.** Rename
+  `toolList` to `tools` when updating your surface definitions.
+- **`registerSurfaceEntry` has been removed.** You no longer need to register a
+  surface before using it.
+
+### Migrating
+
+```ts
+// Before
+initRough({ projectId, fetchUserToken })
+const surface = defineSurface({ key, name, description, toolList })
+const unsubscribe = getRoughFeatures(surface, onFeatures)
+openRoughCreate(surface, { projectId })
+
+// After
+const client = createRoughClient({ projectId, fetchUserToken })
+const surface = defineRoughSurface({ key, name, description, tools })
+const subscription = getRoughFeatures({ client, surface, onFeatures })
+const modal = await openRoughCreate({ client, surface })
+
+await modal.close()
+await subscription.unsubscribe()
+await client.destroy()
+```
+
 ## 0.2.1 - 2026-08-05
 
 Add `CHANGELOG.md` to the published package.

package/README.md

@@ -10,16 +10,14 @@ of custom elements (including `<rough-surface>`).
 ## Install
 
 ```bash
-pnpm add @roughapp/feature
+pnpm add @roughapp/feature zod
 ```
 
 This package targets **npm + a modern bundler** (Vite, Webpack, Rspack, …). It
 is ESM-only and does not support direct `<script>`/CDN usage in this release.
 
-`svelte`, `zod`, `capnweb`, `@andypf/json-viewer`, and
-`@stayradiated/error-boundary` are installed automatically as runtime
-dependencies — you do not need to add them yourself, though you can import `zod`
-directly (see below).
+Install `zod` directly because your tool definitions import it. The package
+installs its other runtime dependencies automatically.
 
 ## Import the stylesheet
 
@@ -40,14 +38,19 @@ A surface describes a place in your product where Rough features appear, plus
 the tools the feature can call. Import `z` from `zod` directly for tool schemas:
 
 ```ts
-import { defineSurface, Query, Mutation, Subscription } from '@roughapp/feature'
+import {
+  defineRoughSurface,
+  Query,
+  Mutation,
+  Subscription,
+} from '@roughapp/feature'
 import { z } from 'zod'
 
-export const inboxSurface = defineSurface({
+export const inboxSurface = defineRoughSurface({
   key: 'inbox',
   name: 'Inbox',
   description: 'The main message inbox.',
-  toolList: [
+  tools: [
     new Query({
       id: 'listMessages',
       name: 'List Messages',
@@ -60,7 +63,8 @@ export const inboxSurface = defineSurface({
         return []
       },
     }),
-    // Mutation and Subscription take the same options shape.
+    // Mutation uses the same fields. A Subscription implementation receives
+    // a callback before the input.
   ],
 })
 ```
@@ -68,65 +72,137 @@ export const inboxSurface = defineSurface({
 `Query`, `Mutation`, and `Subscription` are re-exported from
 `@roughapp/bridge` for convenience.
 
-### Initialize the SDK
+`defineRoughSurface()` validates and freezes the surface and its tools array.
+The definition holds no client, project id or connection state, so you can hand
+the same value to clients for two different projects at once.
+
+### Create a client
+
+`createRoughClient()` returns synchronously and immediately starts that
+project's authentication, local database and first sync. You own the client
+until you destroy it.
 
 ```ts
-import { initRough } from '@roughapp/feature'
+import { createRoughClient } from '@roughapp/feature'
 
-initRough({
+const client = createRoughClient({
   projectId: 'proj_123',
   fetchUserToken: async () => myAppSession.getRoughToken(),
   // baseUrl is optional; defaults to the Rough production API.
 })
 ```
 
+Create the client at whatever owns the project in your app: a route, a provider
+component, a page controller. Share that one client with everything below it
+rather than creating a second. Within one JavaScript realm, create only one live
+client for each `<baseUrl, projectId, personId>` identity. If you create another,
+its startup fails with `RoughReplicacheIdentityConflictError`.
+
+### Destroy it when you are done
+
+```ts
+await client.destroy()
+```
+
+`destroy()` is the only lifecycle method, and it works everywhere. It is
+idempotent, returns the same promise every time, closes every subscription and
+modal the client still owns, and does not resolve until all of that has
+finished. A framework unmount hook may use `void client.destroy()`; tests and
+controlled route transitions should await it.
+
+The client implements no disposal protocol. Teardown here is genuinely
+asynchronous, and there is one way to ask for it.
+
+Startup runs in the background. If you want to observe it:
+
+```ts
+import { whenRoughClientReady } from '@roughapp/feature'
+
+await whenRoughClientReady({ client })
+```
+
+A client that fails startup keeps that error and replays it from every later
+operation. It is not restarted; destroy it and create a new one.
+
 ### Render a surface
 
 Use the `<rough-surface>` custom element, or the `RoughSurface` component
-export. Set the `surface` property to a `defineSurface(...)` result:
+export. Set both the client and the surface:
 
 ```ts
 import '@roughapp/feature'
 
 const el = document.createElement('rough-surface')
+el.client = client
 el.surface = inboxSurface
 document.querySelector('#rough-slot')?.append(el)
 ```
 
 ### List features and open the create flow
 
+Operations are direct exports and take the client in their options. Neither
+requires anything to have mounted first.
+
 ```ts
 import { getRoughFeatures, openRoughCreate } from '@roughapp/feature'
 
 // Subscribe to the published features for a surface.
-const unsubscribe = getRoughFeatures(inboxSurface, (features) => {
-  console.log(features)
+const subscription = getRoughFeatures({
+  client,
+  surface: inboxSurface,
+  onFeatures: (features) => {
+    console.log(features)
+  },
+  onError: (error) => {
+    console.error(error)
+  },
 })
 
-// Open the "create a feature" modal for a surface.
-openRoughCreate(inboxSurface, { projectId: 'proj_123' })
+// Optional: wait for the first feature batch.
+await subscription.ready
+
+// Open the "create a feature" modal.
+const modal = await openRoughCreate({
+  client,
+  surface: inboxSurface,
+  // Where the modal attaches. Defaults to document.body. Pass the element that
+  // scopes your Rough theme if you scope it to a subtree.
+  target: document.querySelector('#rough-root') ?? undefined,
+})
+
+await modal.close()
+await subscription.unsubscribe()
 ```
 
+Every cleanup handle returns a promise, is safe to call twice, and returns the
+same promise on the second call.
+
 ## Exports
 
 Recommended, stable-ish customer API:
 
-- `initRough`, `defineSurface` (+ `SurfaceDefinition` type)
-- `getRoughFeatures`, `openRoughCreate`
+- `createRoughClient`, `whenRoughClientReady` (+ `RoughClient`,
+  `RoughClientOptions` types)
+- `defineRoughSurface` (+ `RoughSurfaceDefinition` type)
+- `getRoughFeatures` (+ `GetRoughFeaturesOptions`,
+  `RoughFeatureSubscription` types)
+- `openRoughCreate` (+ `OpenRoughCreateOptions`, `RoughModalHandle` types)
 - `RoughSurface` / `<rough-surface>`
 - `Query`, `Mutation`, `Subscription` (re-exported from `@roughapp/bridge`)
+- Errors worth branching on: `RoughClientDestroyedError`,
+  `RoughReplicacheIdentityConflictError`, `RoughSurfaceContractConflictError`,
+  `RoughClientDestroyError`, `RoughInvalidClientError`
 
-Advanced / incidental exports — these exist but are **not** intended as stable
-customer dependencies during the pre-1.0 series:
+Advanced / incidental exports are **not** intended as stable customer
+dependencies during the pre-1.0 series:
 
 - Custom-element components: `RoughCreateModal` (`<rough-create-modal>`),
   `RoughEditButton` (`<rough-edit-button>`), `RoughFeature` (`<rough-feature>`)
   (the `<rough-edit-modal>` element registers transitively).
 - UI building blocks: `PrimaryButton`, `SecondaryButton`, `ResizeHandle`,
   `SpriteBuildMenu`, `SpriteFrame`.
-- `registerSurfaceEntry`.
-- Types: `Sprite`, `SpriteBuild`, `JsonValue`, `SpriteFrameDatastore`,
-  `SpriteFrameDatastoreContext`.
+- Types: `Sprite`, `SpriteBuild`, `JsonValue`, `RoughCleanup`,
+  `FetchUserTokenFn`, `SpriteFrameDatastore`, `SpriteFrameDatastoreContext`.
 
 ## License
 

package/index.d.ts

@@ -307,35 +307,167 @@ type Sprite = {
     publishedSpriteBuildId: SpriteBuildId | null;
 };
 
-type SurfaceDefinition = {
-    key: string;
+/**
+ * An immutable, project-independent surface contract.
+ *
+ * A definition holds no client, project id, server surface id, registration
+ * state, subscription, or lifecycle hook. That is what lets the same value be
+ * handed to two clients for two different projects at once: each resolves it
+ * against its own project and caches the canonical id privately.
+ */
+type RoughSurfaceDefinition<TKey extends string = string, TTools extends readonly AnyTool[] = readonly AnyTool[]> = Readonly<{
+    key: TKey;
     name: string;
     description: string;
-    toolList: readonly AnyTool[];
+    tools: TTools;
+}>;
+type DefineRoughSurfaceOptions<TKey extends string, TTools extends readonly AnyTool[]> = {
+    key: TKey;
+    name: string;
+    description: string;
+    tools: TTools;
 };
-declare const defineSurface: (config: SurfaceDefinition) => SurfaceDefinition;
-
-declare const getRoughFeatures: (surface: SurfaceDefinition, callback: (features: Sprite[]) => void) => (() => void);
+declare const defineRoughSurface: <const TKey extends string, const TTools extends readonly AnyTool[]>(options: DefineRoughSurfaceOptions<TKey, TTools>) => RoughSurfaceDefinition<TKey, TTools>;
 
 type FetchUserTokenFn = () => string | Promise<string>;
 
-type SurfaceEntry = {
-    surfaceId: SurfaceId;
-    toolList: readonly AnyTool[];
-};
-declare const registerSurfaceEntry: (key: string, entry: SurfaceEntry) => (() => void);
-
-type InitRoughOptions = {
-    baseUrl?: string;
+type RoughClientOptions = {
     projectId: string;
+    baseUrl?: string;
     fetchUserToken: FetchUserTokenFn;
 };
-declare const initRough: (options: InitRoughOptions) => void;
+/**
+ * A handle to one project's live Rough runtime.
+ *
+ * The client is an opaque capability: it exposes identity and lifecycle, not
+ * behavior. Behavior lives in the package's function exports, which take the
+ * client in their options.
+ */
+type RoughClient = {
+    readonly projectId: string;
+    destroy: () => Promise<void>;
+};
+/**
+ * Creates and immediately starts a client for one Rough project.
+ *
+ * Returns synchronously so a framework provider can own the value in the same
+ * tick it renders, and so a client whose auth or Replicache startup is still
+ * pending can still be destroyed. Startup runs in the background; observe it
+ * with `whenRoughClientReady({ client })` if you need to.
+ *
+ * The host owns the result until it calls `client.destroy()`. There is no
+ * release, restart, or reuse: a failed client is destroyed and replaced.
+ */
+declare const createRoughClient: (options: RoughClientOptions) => RoughClient;
+/**
+ * Awaits the client's eager startup.
+ *
+ * Rejects with the retained startup error if it failed. Operations do this
+ * internally, so hosts only need it when they want to show startup state or
+ * when a test needs a deterministic point to await.
+ */
+declare const whenRoughClientReady: (options: {
+    client: RoughClient;
+}) => Promise<void>;
+
+/**
+ * Errors that hosts are expected to branch on.
+ *
+ * These are exported from the package root so a host can distinguish "you used
+ * a client you already destroyed" (a programming error) from "another client
+ * already owns this local database" (a coordination error the host fixes by
+ * sharing one client).
+ */
+/** Thrown when an operation is started on a destroying or destroyed client. */
+declare class RoughClientDestroyedError extends Error {
+    readonly name = "RoughClientDestroyedError";
+    constructor(message?: string);
+}
+/**
+ * Thrown during startup when another live client in this JavaScript realm
+ * already owns the `<baseUrl, projectId, personId>` Replicache identity.
+ */
+declare class RoughReplicacheIdentityConflictError extends Error {
+    readonly name = "RoughReplicacheIdentityConflictError";
+    readonly replicacheName: string;
+    constructor(options: {
+        replicacheName: string;
+    });
+}
+/**
+ * Thrown when two concurrent operations disagree about the serialized contract
+ * of one surface key on the same client.
+ */
+declare class RoughSurfaceContractConflictError extends Error {
+    readonly name = "RoughSurfaceContractConflictError";
+    readonly surfaceKey: string;
+    constructor(options: {
+        surfaceKey: string;
+    });
+}
+/**
+ * Rejection value of `client.destroy()` when at least one cleanup stage failed.
+ *
+ * `destroy()` always attempts every stage, so this is reported only after all
+ * of them have settled. `errors` holds one entry per failed stage.
+ */
+declare class RoughClientDestroyError extends Error {
+    readonly name = "RoughClientDestroyError";
+    readonly errors: readonly Error[];
+    constructor(options: {
+        errors: readonly Error[];
+    });
+}
+/** Thrown when a value that is not a Rough client is passed as `client`. */
+declare class RoughInvalidClientError extends Error {
+    readonly name = "RoughInvalidClientError";
+    constructor(message?: string);
+}
+
+/**
+ * Every cleanup handle in the public API has this shape.
+ *
+ * It is a promise rather than `void` on purpose. Un-awaitable teardown is what
+ * lets Replicache closes, store watches, and mounted modals outlive the thing
+ * that owned them, which shows up as work still running during a test
+ * environment teardown long after the assertions passed. Calling a cleanup
+ * twice is always safe: the second call returns the first call's promise.
+ */
+type RoughCleanup = () => Promise<void>;
+
+type GetRoughFeaturesOptions = {
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
+    onFeatures: (features: Sprite[]) => void;
+    onError?: (error: Error) => void;
+    signal?: AbortSignal;
+};
+type RoughFeatureSubscription = {
+    /**
+     * Resolves after the first feature batch is published. Rejects if startup or
+     * surface resolution failed.
+     */
+    readonly ready: Promise<void>;
+    unsubscribe: RoughCleanup;
+};
+/** Subscribes to published features for a surface. */
+declare const getRoughFeatures: (options: GetRoughFeaturesOptions) => RoughFeatureSubscription;
 
 type OpenRoughCreateOptions = {
-    projectId?: string;
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
+    /** Portal target. Use when Rough theme variables are scoped below document.body. */
+    target?: HTMLElement;
+    signal?: AbortSignal;
 };
-declare const openRoughCreate: (surface: SurfaceDefinition, options?: OpenRoughCreateOptions) => void;
+type RoughModalHandle = {
+    close: RoughCleanup;
+};
+/**
+ * Opens the Feature Builder for a surface. Resolves the surface itself, so no
+ * `<RoughSurface>` need be mounted first.
+ */
+declare const openRoughCreate: (options: OpenRoughCreateOptions) => Promise<RoughModalHandle>;
 
 type Props$9 = {
     children?: Snippet;
@@ -377,18 +509,21 @@ declare const ResizeHandle: svelte.Component<Props$8, {}, "">;
 type ResizeHandle = ReturnType<typeof ResizeHandle>;
 
 type Props$7 = {
-    toolList: readonly AnyTool[];
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
     surfaceId: SurfaceId;
-    projectId?: string;
+    /** Portal target; use when Rough theme variables are scoped to a subtree. */
+    portalTarget?: HTMLElement;
     onclose?: () => void;
 };
 declare const RoughCreateModal: svelte.Component<Props$7, {}, "">;
 type RoughCreateModal = ReturnType<typeof RoughCreateModal>;
 
 type Props$6 = {
-    toolList: readonly AnyTool[];
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
+    spriteId: SpriteId;
     label?: string;
-    spriteId: string;
 };
 declare const RoughEditButton: svelte.Component<Props$6, {}, "">;
 type RoughEditButton = ReturnType<typeof RoughEditButton>;
@@ -407,16 +542,18 @@ type SpriteFrameDatastoreContext = {
 };
 
 type Props$5 = {
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
     featureId: SpriteId;
     buildId: SpriteBuildId;
-    surfaceKey: string;
     datastore?: SpriteFrameDatastore;
 };
 declare const RoughFeature: svelte.Component<Props$5, {}, "">;
 type RoughFeature = ReturnType<typeof RoughFeature>;
 
 type Props$4 = {
-    surface: SurfaceDefinition;
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
     getDatastore?: (context: SpriteFrameDatastoreContext) => SpriteFrameDatastore | undefined;
 };
 declare const RoughSurface: svelte.Component<Props$4, {}, "">;
@@ -440,16 +577,16 @@ declare const SecondaryButton: svelte.Component<Props$3, {}, "">;
 type SecondaryButton = ReturnType<typeof SecondaryButton>;
 
 type Props$2 = {
+    client: RoughClient;
     surfaceId: SurfaceId;
     onselect?: (sprite: Sprite, spriteBuild: SpriteBuild) => Promise<void> | void;
 };
 declare const SpriteBuildMenu: svelte.Component<Props$2, {}, "">;
 type SpriteBuildMenu = ReturnType<typeof SpriteBuildMenu>;
 
-type Props$1 = {
+type BaseProps = {
     spriteId: string;
     spriteBuildId: SpriteBuildId;
-    artifactUrl?: string;
     toolList: readonly AnyTool[];
     datastore?: SpriteFrameDatastore;
     isMock?: boolean;
@@ -457,12 +594,23 @@ type Props$1 = {
     minHeight?: number;
     maxHeight?: number;
 };
+/** A client is required unless artifactUrl is provided explicitly. */
+type Props$1 = BaseProps & ({
+    artifactUrl: string;
+    client?: undefined;
+} | {
+    artifactUrl?: undefined;
+    client: RoughClient;
+});
 declare const SpriteFrame: svelte.Component<Props$1, {}, "">;
 type SpriteFrame = ReturnType<typeof SpriteFrame>;
 
 type Props = {
-    toolList: readonly AnyTool[];
-    spriteId: string;
+    client: RoughClient;
+    surface: RoughSurfaceDefinition;
+    spriteId: SpriteId;
+    /** Where the dialog attaches. Decides which `--rough-*` values it inherits. */
+    portalTarget?: HTMLElement;
     onclose?: () => void;
 };
 declare const RoughEditModal: svelte.Component<Props, {}, "">;
@@ -494,5 +642,5 @@ declare global {
     }
 }
 
-export { Mutation, PrimaryButton, Query, ResizeHandle, RoughCreateModal, RoughEditButton, RoughFeature, RoughSurface, SecondaryButton, SpriteBuildMenu, SpriteFrame, Subscription, defineSurface, getRoughFeatures, initRough, openRoughCreate, registerSurfaceEntry };
-export type { JsonValue, RoughCreateModalElement, RoughEditButtonElement, RoughEditModalElement, RoughFeatureElement, RoughSurfaceElement, Sprite, SpriteBuild, SpriteFrameDatastore, SpriteFrameDatastoreContext, SurfaceDefinition };
+export { Mutation, PrimaryButton, Query, ResizeHandle, RoughClientDestroyError, RoughClientDestroyedError, RoughCreateModal, RoughEditButton, RoughFeature, RoughInvalidClientError, RoughReplicacheIdentityConflictError, RoughSurface, RoughSurfaceContractConflictError, SecondaryButton, SpriteBuildMenu, SpriteFrame, Subscription, createRoughClient, defineRoughSurface, getRoughFeatures, openRoughCreate, whenRoughClientReady };
+export type { FetchUserTokenFn, GetRoughFeaturesOptions, JsonValue, OpenRoughCreateOptions, RoughCleanup, RoughClient, RoughClientOptions, RoughCreateModalElement, RoughEditButtonElement, RoughEditModalElement, RoughFeatureElement, RoughFeatureSubscription, RoughModalHandle, RoughSurfaceDefinition, RoughSurfaceElement, Sprite, SpriteBuild, SpriteFrameDatastore, SpriteFrameDatastoreContext };