Studio previews

The optional dsh-harmony-react/studio entry lets a compatible dsh-webui-studio Draft expose explicit Elements and editable variables.

Registrations delegate to a browser registry injected only in Studio Preview. The same calls are no-ops during a normal dsh web session.

Register an Element

Associate the Element with a SurfaceHost or SurfaceBoundary from dsh-ui-container by using the same surfaceId and path:

import { registerStudioElement } from 'dsh-harmony-react/studio'

let accent = '#245fd6'
const listeners = new Set<() => void>()

const dispose = registerStudioElement({
  owner: 'my-harmony-plugin',
  element: {
    id: 'settings-card',
    label: 'Settings card',
    boundary: { surfaceId: 'settings', path: ['appearance', 'card'] },
    source: { file: 'src/SettingsCard.tsx', line: 12 },
    variables: [{ id: 'accent', label: 'Accent', control: 'color' }],
  },
  bindings: {
    accent: {
      get: () => accent,
      set(value) {
        accent = String(value)
        for (const listener of listeners) listener()
      },
      subscribe(listener) {
        listeners.add(listener)
        return () => listeners.delete(listener)
      },
    },
  },
})

Call the returned disposer from the client plugin or component lifecycle. Use registerStudioVariables for plugin-wide controls that do not belong to one Element.

Registration contract

• Source paths are normalized, Draft-relative POSIX paths.
• Variable controls support color, length, number, boolean, enum, and string values.
• Bindings are the only live write surface: Studio serializes an update, calls set, then publishes the current get() value.
• subscribe is optional and returns its own disposer.

Trace boundary

An Element boundary proves that the Draft owns the registered subtree contract. Preview trace wrappers generated by React factories may add candidate metadata for the selected render path: owner, declaration, target, and effect.

That metadata is not exact node authorship. Another provider may modify an ancestor, transform props, or contribute a node without a direct counterpart in the registered source. Raw Source Patches without trace intent remain visible only through target-level Harmony inspection.