@roughapp/feature 0.4.0 → 0.4.2

package/README.md

@@ -1,210 +1,301 @@
 # @roughapp/feature
 
-Embeddable Web Components SDK for integrating Rough Features into a host
-product. It ships compiled, minified ESM plus a stylesheet, and registers a set
-of custom elements (including `<rough-surface>`).
+`@roughapp/feature` is the browser SDK for adding Rough Features to your
+product. Your app defines where features can appear (a **surface**) and the
+typed tools available there. The SDK renders published features and opens the
+Feature Builder where users create them.
 
-> **Pre-1.0.** The API surface may change between minor versions during the
-> `0.x` series. Pin an exact version if you need stability.
+The package ships as compiled ESM and Web Components, with TypeScript
+declarations and a separate stylesheet.
+
+> **Pre-1.0:** minor releases may contain breaking changes. Pin
+> `@roughapp/feature` to an exact version if you want to control when you
+> upgrade. Review the hosted [Feature SDK changelog](https://rough.app/docs/changelog)
+> before updating.
+
+## Before you start
+
+You will need:
+
+- a Rough project ID;
+- a Rough signing key, with its private key kept on your server; and
+- a backend endpoint that returns a short-lived Rough identity token for the
+  signed-in user.
+
+Never put the private key in browser code. `fetchUserToken` should call your
+backend, which authenticates the current user and mints the identity token.
 
 ## Install
 
 ```bash
-pnpm add @roughapp/feature zod
+npm install @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.
+The package is ESM-only and expects a modern browser and bundler such as Vite,
+Webpack or Rspack. Direct `<script>` and CDN usage is not supported.
 
-Install `zod` directly because your tool definitions import it. The package
-installs its other runtime dependencies automatically.
+`@roughapp/feature` is browser-only: its root module registers custom elements
+when it is evaluated. In an SSR app, import it and create the client from a
+client-only boundary rather than from server-rendered code.
 
-## Import the stylesheet
+Install `zod` directly because your surface definitions import it. Other
+runtime dependencies are installed with the package.
 
-The package does not inject a global CSS reset. Import the stylesheet once, near
-your app entry, to get the Rough theme variables:
+Import the stylesheet once, near your app entry:
 
 ```ts
 import '@roughapp/feature/style.css'
 ```
 
-Component styles are registered automatically by the custom elements at runtime.
+It provides Rough's theme variables but does not apply a global CSS reset.
+Component styles are registered by the custom elements when the JavaScript
+package loads.
 
-## Recommended API
+## Quick start
 
-### Define a surface
+### 1. Define a surface
 
-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:
+A surface represents one place in your product where Rough Features can appear.
+Give it a stable key and describe the tools a feature may call there.
 
 ```ts
-import {
-  defineRoughSurface,
-  Query,
-  Mutation,
-  Subscription,
-} from '@roughapp/feature'
+import { defineRoughSurface, Query } from '@roughapp/feature'
 import { z } from 'zod'
 
+const Message = z.object({
+  id: z.string(),
+  subject: z.string(),
+})
+
 export const inboxSurface = defineRoughSurface({
   key: 'inbox',
   name: 'Inbox',
-  description: 'The main message inbox.',
+  description: 'The signed-in user’s message inbox.',
   tools: [
     new Query({
       id: 'listMessages',
-      name: 'List Messages',
-      description: 'List messages in the inbox.',
-      inputSchema: z.object({ limit: z.number().default(20) }),
-      outputSchema: z.array(z.object({ id: z.string(), subject: z.string() })),
+      name: 'List messages',
+      description: 'Return the newest messages in the inbox.',
+      inputSchema: z.object({
+        limit: z.number().int().min(1).max(100).default(20),
+      }),
+      outputSchema: z.array(Message),
       outputSample: [{ id: 'msg_1', subject: 'Welcome' }],
       implementation: async ({ limit }) => {
-        /* return messages */
-        return []
+        const response = await fetch(`/api/messages?limit=${limit}`)
+        if (!response.ok) {
+          throw new Error('Unable to load messages')
+        }
+        return response.json()
       },
     }),
-    // Mutation uses the same fields. A Subscription implementation receives
-    // a callback before the input.
   ],
 })
 ```
 
-`Query`, `Mutation`, and `Subscription` are re-exported from
-`@roughapp/bridge` for convenience.
+Tool inputs and outputs are validated against their Zod schemas at runtime.
+`outputSample` should be representative, but must not contain real customer
+data or secrets.
+
+Use `Query` for reads and `Mutation` for writes; both implementations receive
+the parsed input and return a promise. A `Subscription` implementation receives
+an output callback first and the parsed input second, then returns a promise for
+an unsubscribe function. All three classes are exported from
+`@roughapp/feature`.
 
-`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.
+`defineRoughSurface()` validates and freezes the definition. The definition has
+no project or connection state, so the same value can be used with clients for
+different projects. Within one client, a surface key identifies one contract;
+reuse the same definition anywhere that surface is active.
 
-### Create a client
+### 2. 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.
+Create one client at the part of your app that owns the Rough project: a route,
+provider, page controller or similar boundary.
 
 ```ts
 import { createRoughClient } from '@roughapp/feature'
 
-const client = createRoughClient({
+export const roughClient = createRoughClient({
   projectId: 'proj_123',
-  fetchUserToken: async () => myAppSession.getRoughToken(),
-  // baseUrl is optional; defaults to the Rough production API.
+  fetchUserToken: async () => {
+    const response = await fetch('/api/rough/user-token', {
+      method: 'POST',
+      credentials: 'include',
+    })
+
+    if (!response.ok) {
+      throw new Error('Unable to authenticate with Rough')
+    }
+
+    const { token } = (await response.json()) as { token: string }
+    return token
+  },
+  // baseUrl is optional. Omit it when using 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
+`createRoughClient()` returns immediately, then starts authentication, the local
+browser database and the first sync in the background. Operations wait for
+startup themselves. If your UI needs an explicit ready state, use:
 
 ```ts
-await client.destroy()
+import { whenRoughClientReady } from '@roughapp/feature'
+
+await whenRoughClientReady({ client: roughClient })
 ```
 
-`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.
+A failed client is not restarted. Destroy it and create a new one after the
+underlying problem has been handled.
 
-The client implements no disposal protocol. Teardown here is genuinely
-asynchronous, and there is one way to ask for it.
+### 3. Render the surface
 
-Startup runs in the background. If you want to observe it:
+Importing `@roughapp/feature` registers its custom elements. Set the `client`
+and `surface` properties on `<rough-surface>`; these are JavaScript values, not
+HTML attributes.
 
 ```ts
-import { whenRoughClientReady } from '@roughapp/feature'
+import '@roughapp/feature'
+
+const element = document.createElement('rough-surface')
+element.client = roughClient
+element.surface = inboxSurface
 
-await whenRoughClientReady({ client })
+document.querySelector('#rough-slot')?.append(element)
 ```
 
-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.
+The package also exports `RoughSurface` for Svelte apps. As with the custom
+element, import and render it only on the client when the app uses SSR.
 
-### Render a surface
+## Open the Feature Builder
 
-Use the `<rough-surface>` custom element, or the `RoughSurface` component
-export. Set both the client and the surface:
+`openRoughCreate()` opens the create flow without requiring a mounted surface.
+It returns a handle you can close during route teardown.
 
 ```ts
-import '@roughapp/feature'
+import { openRoughCreate } from '@roughapp/feature'
 
-const el = document.createElement('rough-surface')
-el.client = client
-el.surface = inboxSurface
-document.querySelector('#rough-slot')?.append(el)
+const modal = await openRoughCreate({
+  client: roughClient,
+  surface: inboxSurface,
+  // Defaults to document.body. Use a target when your Rough theme is scoped
+  // to a subtree.
+  target: document.querySelector('#rough-root') ?? undefined,
+})
+
+// If the host needs to close it programmatically:
+await modal.close()
 ```
 
-### List features and open the create flow
+The user can also close the modal from the UI. Calling `close()` again is safe.
+
+## Subscribe to published features
 
-Operations are direct exports and take the client in their options. Neither
-requires anything to have mounted first.
+Use `getRoughFeatures()` when you need the feature list rather than the rendered
+`<rough-surface>`. The callback runs with the initial list, even when it is
+empty, and runs again as published features change.
 
 ```ts
-import { getRoughFeatures, openRoughCreate } from '@roughapp/feature'
+import { getRoughFeatures } from '@roughapp/feature'
 
-// Subscribe to the published features for a surface.
 const subscription = getRoughFeatures({
-  client,
+  client: roughClient,
   surface: inboxSurface,
   onFeatures: (features) => {
     console.log(features)
   },
   onError: (error) => {
-    console.error(error)
+    console.error('Unable to load Rough Features', error)
   },
 })
 
-// Optional: wait for the first feature batch.
+// Optional: wait until the first feature list has been delivered.
 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()
+// Later:
 await subscription.unsubscribe()
 ```
 
-Every cleanup handle returns a promise, is safe to call twice, and returns the
-same promise on the second call.
+Both `getRoughFeatures()` and `openRoughCreate()` also accept an `AbortSignal`.
+Their cleanup methods are asynchronous, idempotent and return the same promise
+when called more than once.
 
-## Exports
+## Client lifetime
 
-Recommended, stable-ish customer API:
+Share one client with everything that uses the same Rough project and signed-in
+person. In one JavaScript realm, only one live client may own a given
+`<baseUrl, projectId, personId>` identity. Starting a duplicate client fails
+with `RoughReplicacheIdentityConflictError`.
 
-- `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`
+Destroy the client when its owning route or provider goes away, or before
+replacing it after the user or project changes:
 
-Advanced / incidental exports are **not** intended as stable customer
-dependencies during the pre-1.0 series:
+```ts
+await roughClient.destroy()
+```
+
+`destroy()` closes any subscriptions and modals still owned by the client and
+waits for cleanup to finish. It is safe to call more than once. Framework
+unmount hooks that cannot await cleanup may use `void roughClient.destroy()`;
+tests and controlled transitions should await it.
+
+## Theming
+
+The stylesheet defines a light theme on `:root`. Add `rough-dark` to an
+ancestor to use the bundled dark values:
+
+```html
+<div id="rough-root" class="rough-dark"></div>
+```
+
+Override variables on `:root` or on the subtree containing your Rough elements:
+
+```css
+#rough-root {
+  --rough-primary: oklch(0.52 0.2 264);
+  --rough-primary-foreground: white;
+  --rough-brand: #635bff;
+  --rough-radius: 0.75rem;
+}
+```
 
-- 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`.
-- Types: `Sprite`, `SpriteBuild`, `JsonValue`, `RoughCleanup`,
-  `FetchUserTokenFn`, `SpriteFrameDatastore`, `SpriteFrameDatastoreContext`.
+Common variables include `--rough-background`, `--rough-foreground`,
+`--rough-card`, `--rough-primary`, `--rough-secondary`, `--rough-muted`,
+`--rough-border`, `--rough-ring`, `--rough-brand` and `--rough-radius`.
+
+Create and edit modals attach to `document.body` by default. If your overrides
+live below `body`, pass that themed element as the modal's `target` so the modal
+inherits them.
+
+## Public API
+
+The recommended integration surface is:
+
+- `createRoughClient`, `whenRoughClientReady` and the `RoughClient`,
+  `RoughClientOptions` types;
+- `defineRoughSurface` and the `RoughSurfaceDefinition` type;
+- `getRoughFeatures` and the `GetRoughFeaturesOptions`,
+  `RoughFeatureSubscription` types;
+- `openRoughCreate` and the `OpenRoughCreateOptions`, `RoughModalHandle` types;
+- `RoughSurface` / `<rough-surface>`;
+- `Query`, `Mutation`, `Subscription`; and
+- `RoughClientDestroyedError`, `RoughReplicacheIdentityConflictError`,
+  `RoughSurfaceContractConflictError`, `RoughClientDestroyError` and
+  `RoughInvalidClientError`.
+
+The package also exports lower-level components and data types used to build its
+own UI. During the pre-1.0 series, do not treat these as a stable integration
+surface:
+
+- `RoughCreateModal` (`<rough-create-modal>`), `RoughEditButton`
+  (`<rough-edit-button>`) and `RoughFeature` (`<rough-feature>`). The
+  `<rough-edit-modal>` element is registered transitively.
+- `PrimaryButton`, `SecondaryButton`, `ResizeHandle`, `SpriteBuildMenu` and
+  `SpriteFrame`.
+- `Sprite`, `SpriteBuild`, `JsonValue`, `RoughCleanup`, `FetchUserTokenFn`,
+  `SpriteFrameDatastore` and `SpriteFrameDatastoreContext`.
 
 ## License
 
-`UNLICENSED`. This package is publicly installable but is not open source; use
+`UNLICENSED`. This package is publicly installable but is not open source. Use
 is governed by your Rough customer terms.