Shared Components¶

Lumiverse's first-party React components — model pickers, form atoms, searchable selects, pagination, collapsible sections — are exposed to extensions via ctx.components.*. The host renders the real component into a DOM node you control. You never need to depend on React, ship the component CSS, or replicate the look in plain HTML.

Mounted components automatically inherit the active Lumiverse theme (accent color, glass mode, dark/light, density), so they visually match the rest of the host UI without any styling work on your part. Shared components are inert by default: they add no DOM or UI until an extension explicitly mounts one through ctx.components.* into an extension-owned target under a registered placement root.

import type { SpindleFrontendContext } from 'lumiverse-spindle-types'

export function setup(ctx: SpindleFrontendContext) {
  const tab = ctx.ui.registerDrawerTab({ id: 'demo', title: 'Demo' })

  const wrap = document.createElement('div')
  wrap.style.cssText = 'display:flex;flex-direction:column;gap:12px;padding:12px'
  tab.root.appendChild(wrap)

  const labelEl = document.createElement('div')
  wrap.appendChild(labelEl)

  const modelSlot = document.createElement('div')
  wrap.appendChild(modelSlot)

  const enabledSlot = document.createElement('div')
  wrap.appendChild(enabledSlot)

  // Mount a model picker bound to the user's active LLM connection
  const model = ctx.components.mountModelCombobox(modelSlot, {
    value: '',
    connection: { kind: 'llm' },
    appearance: 'standard',
    onChange: (m) => { labelEl.textContent = `Selected: ${m}` },
  })

  // Mount a switch
  const toggle = ctx.components.mountSwitch(enabledSlot, {
    checked: true,
    onChange: (on) => ctx.sendToBackend({ type: 'set_enabled', value: on }),
  })

  return () => {
    model.destroy()
    toggle.destroy()
    tab.destroy()
  }
}

How mounting works¶

Every mountX(target, options) call:

1. Resolves the target — pass either an HTMLElement or a CSS selector string. Selectors are evaluated across the current extension's live registered placement roots, including roots temporarily detached while their tab or panel is inactive; the selector must resolve exactly one target. An HTMLElement in a newly constructed, unowned detached subtree is accepted provisionally so you can mount a component before appending its containing card or panel. That subtree must be appended under one of your live registered roots synchronously, before the current JavaScript task completes, or the host destroys the mount.
2. Renders the real component into that element.
3. Returns a handle with update(), destroy(), and component-specific helpers such as getValue() where documented.

The handle is the only thing you need to keep alive. A registered root may be temporarily detached without losing mounted component state; any body-ported component UI is hidden and made inert until the root is attached again. Removing or reparenting the target, or unregistering its placement root, destroys the mount. The host also destroys mounts when your extension is disabled or unloaded — but you should still call destroy() yourself when you reuse the target for something else, to avoid leaking memory.

Shared handle shape¶

Every handle implements SpindleMountedComponent<TOptions>:

Form components add getValue() so you can read the current value at any time:

const handle = ctx.components.mountTextInput(target, { value: 'hello' })
console.log(handle.getValue())     // → 'hello'
handle.update({ value: 'world' })  // programmatic value change
handle.update({ disabled: true })  // any partial option works

Controlled vs. auto-controlled¶

Components are auto-controlled by the host. You supply an initial value and an onChange callback — the host owns internal state across user interactions. To force the value from your code, call handle.update({ value }). To read the current value, call handle.getValue().

You do not need to mirror state into your own variables and call update() on every change — that's already happening inside the host.

onChange ordering and detached snapshots¶

For form components, the host commits the next value before invoking onChange, so handle.getValue() inside the callback already returns that next value. If the callback calls handle.update({ value }), that programmatic update is applied afterward and wins. Callback return values — including false or a thenable that resolves to false — are notifications only and never roll state back. Synchronous throws and rejected thenables are logged without undoing the committed value. Values passed to callbacks and returned by getValue() are detached snapshots; mutating a mutable array (for example, a multiselect value) or a Loom editor snapshot cannot mutate host state.

Component catalog¶

Loom block editor¶

ctx.components.mountLoomBlockEditor(target, options) mounts the native Loom block editor into an extension-owned element. It is permission-free, but the target must still follow the same ownership rules as every shared component. A registered placement root may be temporarily detached while its tab or panel is inactive. A new unowned detached subtree may be mounted provisionally only when it is synchronously appended under a live registered root; an arbitrary detached element with only an ownership attribute is not a valid target.

The public value is deliberately closed:

interface SpindleLoomBlockEditorValue {
  blocks: PromptBlockDTO[]
  promptVariableValues: PromptVariableValuesDTO
}

interface SpindleLoomBlockEditorOptions {
  value: SpindleLoomBlockEditorValue
  onChange?: (value: SpindleLoomBlockEditorValue) => void
  readOnly?: boolean
  compact?: boolean
}

value is required. readOnly defaults to false; compact defaults to true (matching the native preset editor's space-efficient layout in extension panels). readOnly disables user edits while still allowing a programmatic update(). Unknown own keys in the value, a block, or the options are rejected. The six host-owned sealed/provenance fields — sealed, sealedKey, sealedSource, sealedOriginPresetId, sealedOriginVersion, and sealedSha256 — are intentionally not part of the public PromptBlockDTO boundary and must not be supplied by an extension. Main keeps those fields in its trusted projection and merges accepted public edits back without exposing or replacing them.

Mounting validates and deep-clones the complete value before rendering. onChange receives a detached clone, and getValue() returns a detached clone, so mutating either snapshot cannot mutate host state. update({ value }) validates and deep-clones the replacement before committing it; an invalid value or option patch is rejected atomically rather than partially applied.

Loom value limits¶

The host applies these limits before cloning or rendering:

Preflight also rejects cyclic graphs, accessors, sparse arrays, and custom object prototypes. Limits apply to both the initial value and later update({ value }) calls; exceeding one rejects the whole operation without changing the current editor value.

maxNodes counts every value visited during preflight, including primitive values, not only object and array nodes.

const editor = ctx.components.mountLoomBlockEditor(slot, {
  value: { blocks: initialBlocks, promptVariableValues: {} },
  compact: true,
  onChange: (next) => {
    console.log('Loom draft changed', next.blocks.length)
  },
})

editor.update({ readOnly: true })
const snapshot = editor.getValue()
await editor.refreshMacros()
editor.destroy()

The editor's macro picker is also intentionally scoped. It displays only core-public macros and macros owned by the current extension; definitions owned by other extensions are filtered out. refreshMacros() refreshes that filtered catalog and serializes refreshes. The filtered catalog is independently bounded to 128 categories, 256 macros per category, 32 arguments per macro, 8,192 nodes, 32,768 entries, a nesting depth of 16, 65,536 units per string, and 4 MiB of UTF-8 string data. A public mount has no contextual preview adapter: it does not resolve macros against a chat, character, persona, or active connection, does not issue preview/generation requests, and does not render the Main-only contextual preview controls.

Loom editor lifecycle¶

• destroy() is idempotent. It unmounts the React tree and releases component/portal resources, but leaves the extension-owned target element in the DOM.
• The host also destroys Loom mounts when the extension is disabled, unloaded, updated, or reloaded; when the relevant permission or placement root is revoked; or when the owned root is removed. A stale handle never remounts or resurrects the component.
• After teardown, update() and getValue() throw COMPONENT_DESTROYED, and refreshMacros() returns a rejected promise with the same lifecycle error. A refresh that was already in flight ignores any late catalog settlement after teardown.

Text inputs¶

const note = ctx.components.mountTextArea(target, {
  value: '',
  rows: 6,
  placeholder: 'Notes…',
  onChange: (text) => ctx.sendToBackend({ type: 'save_note', text }),
})

// Save on a hotkey from elsewhere in your extension
function flush() {
  ctx.sendToBackend({ type: 'save_note', text: note.getValue() })
}

// Programmatically focus
note.focus()

SpindleTextInputOptions / SpindleTextAreaOptions¶

Both handles expose getValue(), focus(), and blur() in addition to the shared methods.

Numeric inputs¶

const temperature = ctx.components.mountNumberStepper(target, {
  value: 0.7,
  min: 0,
  max: 2,
  step: 0.1,
  onChange: (v) => ctx.sendToBackend({ type: 'set_temp', value: v }),
})

SpindleNumericInputOptions¶

SpindleNumberStepperOptions accepts the same fields except integer, and uses step: 1 by default.

Range slider¶

A touch-first slider with horizontal drag. Vertical scroll passes through the slider on mobile (the host does JS direction detection and only claims horizontal gestures), and mid-drag interruptions don't kill the gesture — the slider commits the last live value if the touch is cancelled after movement. The built-in header tracks the live drag value in real time; onCommit only fires once when the gesture ends.

const opacity = ctx.components.mountRangeSlider(target, {
  label: 'Opacity',
  min: 0,
  max: 100,
  step: 5,
  integer: true,
  value: 35,
  format: { suffix: '%' },
  onCommit: (v) => ctx.sendToBackend({ type: 'set_opacity', value: v / 100 }),
})

// Programmatically jump to a value
opacity.update({ value: 80 })

// Read the latest committed value
const current = opacity.getValue()

Omit label to render the bare track without a header — useful when you want to lay out your own label/value display alongside other content. In that case, use onDragValue to mirror the live value into your own UI:

const valueLabel = document.createElement('span')
container.appendChild(valueLabel)

ctx.components.mountRangeSlider(track, {
  min: 0, max: 1, step: 0.05, value: 0.5,
  onDragValue: (v) => { valueLabel.textContent = v === null ? '0.50' : v.toFixed(2) },
  onCommit: (v) => { valueLabel.textContent = v.toFixed(2); ctx.sendToBackend({ type: 'set_strength', value: v }) },
})

SpindleRangeSliderOptions¶

SpindleRangeSliderFormat¶

SpindleRangeSliderHandle¶

In addition to the shared handle methods:

Boolean inputs¶

const showAdvanced = ctx.components.mountCheckbox(target, {
  checked: false,
  label: 'Show advanced controls',
  hint: 'Reveal sampler and routing options',
  onChange: (on) => detailsRow.style.display = on ? 'block' : 'none',
})

SpindleCheckboxOptions¶

SpindleSwitchOptions¶

Selects¶

mountSelect (single) and mountMultiSelect share the same option surface except for value/onChange types. Both support search, grouped options, themed dropdowns, leading cells (icons / avatars / swatches), and portal rendering.

const picker = ctx.components.mountSelect(target, {
  value: '',
  placeholder: 'Pick a tone…',
  searchPlaceholder: 'Search tones…',
  onChange: (v) => ctx.sendToBackend({ type: 'set_tone', value: v }),
  options: [
    { value: 'casual', label: 'Casual', group: 'Conversational' },
    { value: 'witty', label: 'Witty',   group: 'Conversational' },
    { value: 'formal', label: 'Formal', group: 'Professional' },
    { value: 'dry',    label: 'Dry',    group: 'Professional' },
  ],
})

SpindleSelectOption¶

SpindleSelectOptionsBase (shared by single & multi)¶

Single-select also accepts:

Both handles expose getValue(), open(), and close() in addition to the shared methods.

Leading cells: avatars, icons, swatches, initials¶

SpindleSelectOptionLeading is a declarative union for the small slot rendered before each option label (and on the trigger when an option is selected). Use it for persona avatars, provider brand marks, category swatches, or letter bubbles. Extensions describe what they want — no React, no <img> tags, no styling required.

leading: {
  type: 'image',
  src: persona.avatarUrl,
  rounded: true,
  fallback: {
    text: persona.name.charAt(0).toUpperCase(),
    background: 'var(--lumiverse-fill-subtle)',
  },
}

leading: {
  type: 'icon-svg',
  svg: '<svg viewBox="0 0 16 16">...</svg>',
  color: 'var(--lumiverse-accent)',
}

leading: { type: 'icon-url', url: '/icons/openai.png' }

leading: { type: 'swatch', color: '#7e57c2' }

leading: {
  type: 'initial',
  text: 'A',
  background: '#3a3a3a',
  color: '#fff',
}

Full example: persona picker¶

ctx.components.mountSelect(target, {
  value: currentPersonaId,
  triggerLabel: currentPersonaId ? undefined : '+ Choose persona',
  searchPlaceholder: 'Search personas…',
  noResultsMessage: 'No personas match your search.',
  clearable: true,
  clearLabel: 'Unassign',
  options: personas.map((p) => ({
    value: p.id,
    label: p.name,
    sublabel: p.title,
    leading: p.avatarUrl
      ? {
          type: 'image',
          src: p.avatarUrl,
          fallback: { text: p.name.charAt(0).toUpperCase() },
        }
      : { type: 'initial', text: p.name.charAt(0).toUpperCase() },
  })),
  onChange: (id) => ctx.sendToBackend({ type: 'set_persona', personaId: id || null }),
})

Model combobox¶

mountModelCombobox is the same picker Lumiverse uses for selecting LLM, image-gen, and TTS models. It has two operating modes.

Connection-bound mode (recommended)¶

Supply a connection reference and the host wires up everything for you — the model list, the refresh affordance, the loading spinner, and live updates when the user switches their active connection.

ctx.components.mountModelCombobox(target, {
  value: '',
  // Follow the user's currently-active LLM connection
  connection: { kind: 'llm' },
  appearance: 'standard',
  onChange: (model) => ctx.sendToBackend({ type: 'set_model', model }),
})

To pin to a specific connection instead of the active one:

connection: { kind: 'image', id: profileId }

Supported kind values:

The host fetches via Lumiverse's authenticated API on your behalf, so you don't need cors_proxy or any backend wiring for the model list. Call handle.refresh() to force a re-fetch (e.g. after the user adds a new model in your extension's settings).

Manual mode¶

Supply models, loading, and onRefresh yourself when you maintain the catalog. Useful for OpenRouter-style listings, custom proxies, or filtered subsets.

let models: string[] = []
let loading = false

const picker = ctx.components.mountModelCombobox(target, {
  value: '',
  models,
  loading,
  onRefresh: () => {
    loading = true
    picker.update({ loading: true })
    fetchModelsFromBackend().then((next) => {
      loading = false
      picker.update({ models: next, loading: false })
    })
  },
  onChange: (m) => ctx.sendToBackend({ type: 'set_model', model: m }),
})

If both connection and models are supplied, connection wins and the manual fields are ignored.

SpindleModelComboboxOptions¶

The handle exposes refresh() in addition to getValue() and the shared methods.

Folder dropdown¶

ctx.components.mountFolderDropdown(target, {
  folders: ['Personal', 'Work', 'Drafts'],
  value: 'Personal',
  placeholder: 'No folder',
  onChange: (folder) => ctx.sendToBackend({ type: 'move_to', folder }),
  onCreateFolder: (name) => ctx.sendToBackend({ type: 'create_folder', name }),
})

SpindleFolderDropdownOptions¶

Collapsible sections (with host-managed chrome)¶

Unlike other components, mountCollapsibleSection gives you back a body element — the host renders the header/chevron chrome, and you fully own the body contents. Append your own elements to handle.body exactly as you would to a tab.root or panel.root.

const section = ctx.components.mountCollapsibleSection(target, {
  title: 'Advanced',
  iconSvg: '<svg>...</svg>',
  badge: '3',
  defaultExpanded: false,
  onToggle: (open) => console.log('section is now', open ? 'open' : 'closed'),
})

// Build whatever you want into the body
section.body.innerHTML = '<p>Body content owned by the extension.</p>'

// Imperative controls
section.expand()
section.collapse()
section.toggle()
console.log(section.isExpanded())

SpindleCollapsibleSectionOptions¶

SpindleCollapsibleSectionHandle¶

Adds to the shared shape:

Display utilities¶

const status = ctx.components.mountBadge(target, { text: 'Beta', color: 'warning', size: 'pill' })
status.update({ color: 'success', text: 'Ready' })

const spinner = ctx.components.mountSpinner(target, { size: 16 })
spinner.destroy()

const closeBtn = ctx.components.mountCloseButton(target, {
  onClick: () => panel.collapse(),
  size: 'sm',
  variant: 'subtle',
})

SpindleBadgeOptions¶

SpindleSpinnerOptions¶

SpindleCloseButtonOptions¶

Pagination¶

let page = 1

const pager = ctx.components.mountPagination(target, {
  currentPage: page,
  totalPages: 12,
  totalItems: 234,
  perPage: 20,
  perPageOptions: [10, 20, 50],
  onPageChange: (p) => {
    page = p
    pager.update({ currentPage: p })
    ctx.sendToBackend({ type: 'list_page', page: p })
  },
  onPerPageChange: (n) => ctx.sendToBackend({ type: 'set_page_size', size: n }),
})

SpindlePaginationOptions¶

Pagination is fully controlled — call pager.update({ currentPage: next }) after each navigation to keep the UI in sync.

Lifecycle & cleanup¶

Theming & styling¶

You generally do not need to style mounted components. They consume the same CSS variables as Lumiverse's own UI:

• Accent colors via --lumiverse-accent and friends
• Surface/border/text colors via --lumiverse-fill-subtle, --lumiverse-border, --lumiverse-text, --lumiverse-text-dim
• Radius via --lumiverse-radius

If you need to tweak spacing or alignment around a mounted component, do it on the wrapper element you own (the target you passed to mount*). Avoid trying to override component internals with !important rules — those internals are not part of the public contract and can change.

Capacity limits¶

Mounting shared components has no per-extension cap — they are scoped to whatever container you already own (a drawer tab, a dock panel, a modal body, an app mount), and those placements already enforce their own capacity limits.