@roughapp/feature 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# @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>`).
+
+> **Pre-1.0.** The API surface may change between minor versions during the
+> `0.x` series. Pin an exact version if you need stability.
+
+## Install
+
+```bash
+pnpm add @roughapp/feature
+```
+
+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).
+
+## Import the stylesheet
+
+The package does not inject a global CSS reset. Import the stylesheet once, near
+your app entry, to get the Rough theme variables:
+
+```ts
+import '@roughapp/feature/style.css'
+```
+
+Component styles are registered automatically by the custom elements at runtime.
+
+## Recommended API
+
+### 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:
+
+```ts
+import { defineSurface, Query, Mutation, Subscription } from '@roughapp/feature'
+import { z } from 'zod'
+
+export const inboxSurface = defineSurface({
+  key: 'inbox',
+  name: 'Inbox',
+  description: 'The main message inbox.',
+  toolList: [
+    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() })),
+      outputSample: [{ id: 'msg_1', subject: 'Welcome' }],
+      implementation: async ({ limit }) => {
+        /* return messages */
+        return []
+      },
+    }),
+    // Mutation and Subscription take the same options shape.
+  ],
+})
+```
+
+`Query`, `Mutation`, and `Subscription` are re-exported from
+`@roughapp/bridge` for convenience.
+
+### Initialize the SDK
+
+```ts
+import { initRough } from '@roughapp/feature'
+
+initRough({
+  projectId: 'proj_123',
+  fetchUserToken: async () => myAppSession.getRoughToken(),
+  // baseUrl is optional; defaults to the Rough production API.
+})
+```
+
+### Render a surface
+
+Use the `<rough-surface>` custom element, or the `RoughSurface` component
+export. Set the `surface` property to a `defineSurface(...)` result:
+
+```ts
+import '@roughapp/feature'
+
+const el = document.createElement('rough-surface')
+el.surface = inboxSurface
+document.querySelector('#rough-slot')?.append(el)
+```
+
+### List features and open the create flow
+
+```ts
+import { getRoughFeatures, openRoughCreate } from '@roughapp/feature'
+
+// Subscribe to the published features for a surface.
+const unsubscribe = getRoughFeatures(inboxSurface, (features) => {
+  console.log(features)
+})
+
+// Open the "create a feature" modal for a surface.
+openRoughCreate(inboxSurface, { projectId: 'proj_123' })
+```
+
+## Exports
+
+Recommended, stable-ish customer API:
+
+- `initRough`, `defineSurface` (+ `SurfaceDefinition` type)
+- `getRoughFeatures`, `openRoughCreate`
+- `RoughSurface` / `<rough-surface>`
+- `Query`, `Mutation`, `Subscription` (re-exported from `@roughapp/bridge`)
+
+Advanced / incidental exports — these exist but 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`.
+
+## License
+
+`UNLICENSED`. This package is publicly installable but is not open source; use
+is governed by your Rough customer terms.