Release Notes

This is a big one! We have made some great quality-of-life improvements to our SDK. It is simpler to work with and more reliable. However, that also comes with a large number of breaking changes.

Breaking changes

• The stylesheet has been removed. You should no longer import @roughapp/feature/style.css. We now automatically handle loading the stylesheet for you.
• The getRoughFeatures function has been renamed to subscribeToRoughFeatures, a more accurate description of what it does. The callback method has also been renamed from onFeatures to onChange.

// before
getRoughFeatures({ client, surface, onFeatures })

// after
subscribeToRoughFeatures({ client, surface, onChange })

• The way to create a new feature with the Feature Builder has also changed. The function openRoughCreate has been replaced with two separate function calls:
  1. createRoughFeature: create a new Rough Feature
  2. openRoughBuilder: open the Feature Builder for a specific feature
• This is more modular, meaning you can use the same openRoughBuilder function to edit existing features or newly created ones.

// before
openRoughCreate({ client, surface })

// after
const feature = await createRoughFeature({ client, surface })
openRoughBuilder({ client, surface, featureId: feature.id })

• The function createRoughClient has been renamed to startRoughClient. We changed it to start to minimise confusion with the verb create also being used with createRoughFeature.
• Starting a new Rough Client now requires two new properties:
  • externalUserId: the ID of the currently logged-in user. Must match the JWT sub field.
  • externalAccountId: the ID of the account that the user is logged into. Must match the JWT rough.account.id field.
• Note: both of these are your app's identifiers, and must match the values you specify in the JWT returned by fetchUserToken.
• There is also a new onError callback you can subscribe to be notified of any authentication errors.

// before
const client = createRoughClient({
  projectId: 'my-rough-project-123',
  fetchUserToken: () => { ... }
})

// after
const client = startRoughClient({
  projectId: 'my-rough-project-123',
  externalUserId: localSession.userId,
  externalAccountId: localSession.accountId,
  fetchUserToken: () => { ... },
  onError: (error) => {
    console.error(error)
  }
})

• The whenRoughClientReady function has been removed. This is no longer necessary, as the Rough Client is now synchronous and can be used immediately.
• We have removed the <rough-feature> Web Component and <RoughFeature> Svelte components from the SDK. These were difficult to work with (especially if you are not using Svelte as your framework) and have been replaced with a vanilla JS function, mountRoughFeature. The buildId property is now optional if you want to display the currently published version of the feature.

// before
const element = document.createElement('rough-feature')
element.client = client
element.surface = surface
element.featureId = feature.id
element.buildId = feature.publishedSpriteBuildId
container.append(element)

// after
const element = mountRoughFeature(container, {
  client,
  surface,
  featureId: feature.id
})

• We have also removed all other Web Components that were previously being registered:
  • <rough-create-modal>: call createRoughFeature and openRoughBuilder instead
  • <rough-edit-modal>: call openRoughBuilder instead
  • <rough-edit-button>: call openRoughBuilder instead
• We have also removed all other Svelte components, including:
  • <RoughCreateModal>: call createRoughFeature and openRoughBuilder instead
  • <RoughEditButton>: call openRoughBuilder instead
• When calling defineRoughSurface, the deprecated tools property has been removed. You must use toolList (see the v0.6.0 release notes for more details).

Added

• The Feature Builder now lets you choose whether to use a dark or light theme! When calling openRoughBuilder, you can now pass theme: "dark" to use the dark theme (it defaults to the light theme).
• We have finally got a good way to display Rough Features on your app: mountRoughFeature. This is a vanilla JS function that is very easy to work with. Just pass it a client, surface, a featureId, and an HTML Element to mount it inside of. It has an update method allowing you to update the props and an unmount method to remove it from the page. You no longer need to pass a buildId - the currently published version will be displayed by default - but if you do want to display a particular version, you can specify the buildId.

Changed

• Now that startRoughClient has access to the externalUserId and externalAccountId, it can immediately load previously cached data, substantially reducing startup times.
• We have fixed an issue with the Feature Builder UI being affected by global CSS rules. We now mount the Feature Builder inside a Shadow Root, so that we can guarantee it looks good on any website. We also now bundle a webfont, so it looks good on any computer.
• The subscribeToRoughFeatures function will only call onChange when the list of features actually changes. Previously, we were seeing issues with this callback happening more frequently than necessary, sometimes causing re-rendering issues.

We have been tidying up our codebase this week and renaming some internal components to be more consistent. We have tried to minimise the number of breaking changes, but there are a few minor adjustments you will need to make in your apps. Surfaces now use toolList (previously tools) and we have removed the custom error classes to keep things simple. On the new features side, you can now specify a custom prompt for your Rough Project, which can guide how Rough builds Features, helping them feel even more at home in your product!

Breaking changes

• The Surface tools property has been renamed to toolList. New code should pass toolList to defineRoughSurface(), and read surface.toolList instead. To make this transition easier, the defineRoughSurface() function will continue to accept tools, but we highly recommend that you refactor your code to use toolList, as we will be removing this option in a future version.
  Migration steps…

  1. Replace the tools option in each call to defineRoughSurface() with toolList.
  2. Replace any reads of surface.tools with surface.toolList.
  3. Run your type checks and tests to catch Surface definitions or helpers that still use the old property.

  Scroll to see more →

  // Before
  const surface = defineRoughSurface({
    key: 'dashboard',
    name: 'Dashboard',
    description: 'The main dashboard view',
    tools: [getCurrentUser],
  })
  
  console.log(surface.tools)
  
  // After
  const surface = defineRoughSurface({
    key: 'dashboard',
    name: 'Dashboard',
    description: 'The main dashboard view',
    toolList: [getCurrentUser],
  })
  
  console.log(surface.toolList)

• Our custom error classes have been removed. The SDK now throws plain old Error values. This keeps error handling simpler, but if you were importing one of our custom Rough*Error classes, you will need to change your code.
  Migration steps…

  1. Remove imports of RoughClientDestroyError, RoughClientDestroyedError, RoughInvalidClientError, RoughReplicacheIdentityConflictError, and RoughSurfaceContractConflictError.
  2. Replace instanceof Rough*Error branches with your app's normal error reporting or recovery flow.
  3. Stop reading the removed errors, replicacheName, and surfaceKey fields. Display the regular error message where useful, but do not depend on matching its text for application logic.

  Scroll to see more →

  // Before
  import {
    RoughClientDestroyedError,
    RoughSurfaceContractConflictError,
  } from '@roughapp/feature'
  
  try {
    await openRoughCreate({ client, surface })
  } catch (error) {
    if (error instanceof RoughClientDestroyedError) {
      // ...
    }
  }
  
  // After
  try {
    await openRoughCreate({ client, surface })
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error)
    reportError(message)
  }

Added

• Rough Projects can now have custom prompts! Rough admins can specify a custom system prompt for their Rough Features. This lets you guide how the Features should fit into your product by specifying conventions or particular styles for generated Rough Features.

Users can now upload images to Feature Builder chats, and when embedding a Rough Feature, you can now hide Rough's editing controls. This release also removes the <rough-surface> component and cleans up the styling of the <rough-feature> frame.

Breaking changes

• <rough-surface> has been removed. Instead of using Rough to render a list of surfaces, we encourage you to control how features are rendered. You can use the getRoughFeatures() function to access the feature list, and then render each using <rough-feature>. This gives you full control over how and where features are rendered for a Surface.
  Migration Guide…

  Scroll to see more →

  // Before: <rough-surface> rendered every published feature
  const surfaceElement = document.createElement('rough-surface')
  surfaceElement.client = client
  surfaceElement.surface = surface
  slot.append(surfaceElement)
  
  // After: subscribe and render each feature in host-owned layout
  const subscription = getRoughFeatures({
    client,
    surface,
    onFeatures: (features) => {
      slot.replaceChildren(
        ...features.flatMap((feature) => {
          if (!feature.publishedSpriteBuildId) return []
  
          const featureElement = document.createElement('rough-feature')
          featureElement.client = client
          featureElement.surface = surface
          featureElement.featureId = feature.id
          featureElement.buildId = feature.publishedSpriteBuildId
          return [featureElement]
        }),
      )
    },
  })
  
  // When this part of the UI unmounts
  await subscription.unsubscribe()

• <rough-feature> no longer has visible border styles. This makes it easier to integrate Rough Features into your app aesthetically, allowing you to control how the feature frame looks.

Added

• Users can upload images. Each message can now have up to three GIF, JPEG, PNG, or WebP images attached. These images can be used to influence the feature design or even be integrated and displayed in the feature directly.
• The new isEditable prop hides the Rough Edit button. When isEditable is set to false, users will no longer see the Rough Icon button and will not be able to customise that feature.

The Feature Builder is now conversational: Rough can clarify what to build, inspect the tools available on the surface and start a build when it has enough context. The recommended client and surface APIs are unchanged, so host apps do not need an integration migration.

Added

• Feature Builder chat. Conversations are saved per feature and remain available when the builder is reopened. Follow-up messages can refine the feature before Rough starts another build.
• Markdown responses. Assistant messages render headings, lists, links, tables, blockquotes and code blocks.
• Build cancellation. Pending and in-progress builds have a Stop control. Canceled builds remain in the conversation and build log with the time they ran before stopping.

Changed

• Build and publish updates reach open clients sooner. The SDK uses an authenticated WebSocket when available, so updates no longer wait for the five-second polling interval. Polling remains available as a fallback.
• Abandoned create flows no longer leave empty features behind. Rough creates the feature only after the user sends the first message.
• Advanced consumers of the incidental SpriteBuild export must handle the new CANCELED status. Build records also include cancelRequestedAt: number | null; update exhaustive status switches and test fixtures accordingly.

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.

Breaking changes

The recommended migration is shown below. In summary:

• 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 an error. 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.

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.

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.

Migration

// 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()