@roughapp/feature 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,220 @@
+# Changelog
+
+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.
+
+## 0.2.0 - 2026-08-05
+
+**Upgrade from 0.1.0 as soon as you can.** Every read and write 0.1.0 performs
+goes through gateway REST routes that are being deleted. When that lands, a
+0.1.0 install can no longer list, create, build or publish features. 0.2.0 does
+not call any of those routes.
+
+Upgrading needs no configuration change. `initRough` takes the same
+`projectId`, `fetchUserToken` and optional `baseUrl` it always did, and no
+export was added or removed. The work is in the type and theme changes below.
+
+### Changed
+
+- **Breaking: sprite, surface and ping traffic now syncs through Replicache
+  instead of the REST API.** 0.1.0 called ten routes under
+  `/api/v1/project/{projectId}/` to list sprites, fetch a sprite, list and
+  create builds, read a build and its logs, publish, register a surface and
+  ping. 0.2.0 calls none of them. It syncs over
+  `/api/v1/internal/replicache/pull` and `/api/v1/internal/replicache/push`,
+  and the session token exchange at `/api/v1/project/{projectId}/session-token`
+  is the only other request it makes. The ten legacy routes are removed in
+  [#2181](https://github.com/build-great-products/rough.app/pull/2181), which
+  is what makes this upgrade time sensitive.
+
+  One consequence worth planning for: the SDK now keeps a sync loop open and
+  polls for changes every 5 seconds for as long as the page is mounted, where
+  0.1.0 issued one request per call and then went quiet.
+
+- **Breaking: `Sprite` and `SpriteBuild` reference related records by ID
+  instead of nesting them.**
+
+  ```ts
+  // 0.1.0
+  type Sprite = {
+    id: string
+    name: string
+    ownedByPersonId: string
+    publishedSpriteBuild: SpriteBuild | null   // full nested record
+  }
+  type SpriteBuild = {
+    createdByPerson: { id: string; name: string }
+    // ...
+  }
+
+  // 0.2.0
+  type Sprite = {
+    id: SpriteId
+    name: string
+    ownedByPersonId: PersonId
+    publishedSpriteBuildId: SpriteBuildId | null   // ID only
+  }
+  type SpriteBuild = {
+    createdByPersonId: PersonId
+    // ...
+  }
+  ```
+
+  Anything reading `sprite.publishedSpriteBuild.artifactUrl`,
+  `.status` or `.prompt` off a `getRoughFeatures` result must be reworked, and
+  `SpriteBuild` no longer carries the build author's display name. There is no
+  replacement for that name in the public API.
+
+- **Breaking: ID fields are branded string types.** `SpriteId`,
+  `SpriteBuildId`, `SurfaceId` and `PersonId` are now `string & { __brand: … }`
+  rather than `string`, on `RoughFeature`'s `featureId` and `buildId`,
+  `RoughCreateModal`'s and `SpriteBuildMenu`'s `surfaceId`, `SpriteFrame`'s
+  `spriteBuildId`, and `registerSurfaceEntry`'s `surfaceId`.
+
+  Reading is unaffected, because a branded string is still assignable to
+  `string`. Passing one in is not: an ID you hold as a plain `string`, from
+  your own database or a URL parameter, is rejected. The brand types are not
+  themselves exported, so reach them through the types that are:
+
+  ```ts
+  type SpriteId = Sprite['id']
+  type SpriteBuildId = NonNullable<Sprite['publishedSpriteBuildId']>
+  type SurfaceId = RoughCreateModalElement['surfaceId']
+  ```
+
+  IDs that flow straight out of `getRoughFeatures` into a component still
+  typecheck with no cast.
+
+- **Breaking: the stylesheet ships a different set of design tokens.** The
+  Solarized palette was replaced with a ShadCN-style token set, so any host
+  theming Rough through CSS custom properties needs to remap. These eight are
+  gone, with their nearest replacement:
+
+  | Removed in 0.2.0          | Closest 0.2.0 token                            |
+  | ------------------------- | ---------------------------------------------- |
+  | `--rough-text`            | `--rough-foreground`                           |
+  | `--rough-text-secondary`  | `--rough-muted-foreground`                     |
+  | `--rough-surface`         | `--rough-card`                                 |
+  | `--rough-surface-border`  | `--rough-border`                               |
+  | `--rough-background-muted` | `--rough-muted`                               |
+  | `--rough-danger`          | `--rough-destructive`                          |
+  | `--rough-shadow`          | `--rough-shadow-xs`, `-md`, `-lg`              |
+  | `--rough-accent-secondary` | no equivalent; `--rough-brand` is the saturated brand colour |
+
+  Watch `--rough-accent` in particular. The name survived but the meaning did
+  not: it was the primary action colour (Solarized blue) and is now the subtle
+  hover background that ShadCN uses the name for. A host that set it to their
+  brand colour to tint buttons will find it tinting hover states instead.
+  `--rough-primary` is the token that now drives primary actions.
+  `--rough-background` and `--rough-border` also kept their names with new
+  values. Twenty-eight tokens were added, including a `--rough-radius` scale
+  and `--rough-success` variants.
+
+- **`getRoughFeatures` is a live subscription rather than a one-shot fetch.**
+  In 0.1.0 the callback fired once and only fired again when something called
+  `triggerRefresh`. It now re-fires on every relevant change that syncs in, so
+  a feature published in another tab or by another user appears without the
+  host doing anything.
+
+- **A feature becomes visible on a published build rather than on a built
+  artifact.** 0.1.0 listed a sprite only if its published build had an
+  `artifactUrl`; 0.2.0 lists it as soon as a build is marked published. A
+  published build with no artifact, which should not normally occur, now
+  reaches the host and renders an empty frame instead of being filtered out.
+
+- The bundle is roughly three times larger, because the Replicache client is
+  compiled into it: `index.js` goes from 105 kB to 320 kB raw, 27 kB to 77 kB
+  gzipped. The stylesheet grows from 324 B to 5.2 kB with the larger token set.
+
+- The declared `svelte` dependency range moves from `^5.56.4` to `^5.56.8`.
+  Every other runtime dependency is unchanged, `capnweb` included, so the
+  version compatibility required between the two ends of the iframe bridge has
+  not moved.
+
+### Removed
+
+- **`onpublish` is gone from `RoughCreateModal`, `RoughEditButton` and
+  `RoughEditModal`.** Because `getRoughFeatures` is now a live subscription, a
+  publish already reaches the host through that callback, which is what the
+  prop existed to signal. Move any publish handling into the
+  `getRoughFeatures` callback. Note that the prop was optional, so depending on
+  your setup this may fail quietly rather than at compile time.
+
+- **`triggerRefresh` is gone from the `SurfaceEntry` passed to
+  `registerSurfaceEntry`.** It was the manual refresh hook for the old
+  fetch-once model and has nothing to do now. Delete it from the object you
+  pass in; leaving it there is an excess property and will be rejected.
+
+### Added
+
+- A light and dark mode toggle in the Feature Builder. The stylesheet now
+  carries a `.rough-dark` class holding the dark values for every token.
+- The Feature Builder's build log now reports token usage and estimated cost
+  per agent step, formatted in cents below one dollar
+  ([#2187](https://github.com/build-great-products/rough.app/pull/2187)).

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