FluidDocs

Getting Started UI

A hands-on tour of window.__fluiddocs — the JavaScript interface injected on every hosted FluidDocs page. Click Run ▶ on each card to call the API and see a visible result. Every example runs in-place; no copy-paste required.

This page focuses only on the frontend SDK. For REST endpoints see REST API docs; for the terminal client see the CLI guide (fld).

__fluiddocs onReady storage credits

How it works: When your HTML is served by FluidDocs, the platform injects window.__fluiddocs before your scripts run. Use the event bus to talk to the dashboard, the store for reactive state, storage for per-user collections, and floating zones for overlay UI.

Live event feed

This page registers a global listen handler on load. Every dispatch (including from the examples below) appears here in real time.

Event bus monitor

Waiting for events…

Event bus

Publish/subscribe channel shared between your page and the surrounding FluidDocs shell.

dispatch(event)

API dispatch({ type, payload })

Emit a custom event. Watch it appear in the live feed above.

type

payload

fd.dispatch({ type: 'gsui.demo.ping', payload: { hello: 'world' } });

listen(handler, label?)

API listen(handler, label?) → unsubscribe

Subscribe to the next matching event, then auto-unsubscribe. Dispatches a trigger event immediately.

filter type

const unsub = fd.listen((e) => { ...; unsub(); }, 'gs-ui-demo');
fd.dispatch({ type: 'gsui.demo.listen-test', payload: { ts: Date.now() } });

sendMessage(target, message)

API sendMessage('viewer' | 'builder', message)

Shorthand for viewer.chat.send_message or builder.chat.send_message. On a published page this opens/sends to the viewer chatbot when enabled.

target

message

fd.sendMessage('viewer', 'Summarize this page in one sentence.');

Store

Reactive snapshot of page context and view settings. Subscribe for live updates.

getState()

Store getState() → FluidDocsStore

Read the full store snapshot. Key fields: pageContext, view, libraries.

Store subscribe(listener) → unsubscribe

First click starts a live subscription. Tick store patches demo data and the output updates automatically.

_patchState(partial)

Store _patchState(partial)

Deep-merge a partial update. Internal API — libraries and platform code use this. Demo writes to view.content.gsuiDemo.

note

Builder panels

Open left and right sidebar panels in the FluidDocs preview / builder shell. From a content page pass content: null — the dashboard renders the panel chrome; your page only controls title, width, and tab slots.

Visible in preview: When this page runs inside the dashboard preview iframe, panel calls squish the iframe and show sidebars. On a standalone published URL the events still fire (see the live feed) but there is no surrounding builder chrome.

setPanel(config)

Panel setPanel({ side, title?, width?, id?, content })

Open or update a panel on the left or right. Use id to add tabs on the same side.

side

title

width

tab id

fd.setPanel({ side: 'right', title: 'GS UI Panel', width: 360, content: null });

closePanel(side, tabId?)

Panel closePanel('left' | 'right', tabId?)

Close an entire side, or one tab when tabId is set.

side

tab id

showPanelTab(side, tabId)

Panel showPanelTab(side, tabId)

Opens two tabs on the right, then switches to the second tab. Watch the preview sidebar tabs change.

clearPanels()

Panel clearPanels()

Closes all panels on both sides.

showToast(message, opts?)

UI showToast(message, { variant?, actionLabel?, actionUrl? })

Show a toast in the dashboard chrome. In preview, look at the top of the builder window — not inside the page iframe.

message

variant

fd.showToast('Saved!', { variant: 'success' });

Floating zones

Mount DOM elements into named overlay zones on the page canvas.

Zone addFloatingElement · removeFloatingElement · moveFloatingElement

Adds an orange pill to the page. Move it between zones or dismiss it. Look at the page corners while running these.

zone

No floating pill mounted.

Storage

Per-user collection CRUD via fd.storage. Entries are scoped to the current visitor unless you pass { sudo: true } (doc owner / org member only).

storage.set(id, data)

Storage storage.set(null, data) → entry

Create or update a collection entry. Pass null as id to create.

text

storage.list(filter?)

Storage storage.list({ type }) → entries[]

List your entries for this page. Results render below and populate the get/delete picker.

storage.get(id)

Storage storage.get(id) → entry

entry id

storage.delete(id)

Storage storage.delete(id)

entry id

Frontend tools

Register tools the builder or visitor chatbot can invoke in the browser. Use registerTools("builder", …) for owner preview chat and registerTools("viewer", …) for the visitor widget.

registerTools(target, tools)

Tools registerTools("viewer", [{ name, handler, … }])

Registers an echo visitor tool, then simulates a handler call so you see the result on the event bus.

getViewerTools()

Tools getViewerTools() → tools[]

Tools subscribeViewerTools(listener) → unsubscribe

Starts a subscription, then registers a new tool so the listener fires.

Chat channels

Register an extra builder chat tab from library code (preview iframe → parent admin panel). Frontend tools use registerTools above — not this API.

registerChatChannel(config)

Chat registerChatChannel({ id, label, jobsBase, … })

In preview mode, forwards registration to the parent frame via postMessage. On a standalone published page the call completes without error.

getRegisteredChats()

Chat getRegisteredChats() → configs[]

On content pages, registrations are forwarded to the parent — this list is usually empty here. Useful in standalone / dashboard contexts.

Lifecycle

onReady(callback)

Lifecycle onReady(callback) → unsubscribe

hasCreditsAvailable()

Lifecycle hasCreditsAvailable() → boolean

Returns whether the doc owner has AI credits. Used to gate chat features on published pages.

Scripts & libraries

addScript(libId, url)

Scripts addScript(libId, url)

Loads a script tag. Demo uses an inline blob URL that sets window.__GSUI_SCRIPT_LOADED.

loadScripts(scripts)

Scripts loadScripts({ libId: [urls] })

Batch-load scripts from the store's view.scripts shape. Demo loads the same blob script under gs-ui-demo.

onLibUpdate(name, handler)

Scripts onLibUpdate(name, handler)

Subscribe to library config changes, then fire a demo update via _dispatchLibUpdate.

Dashboard-only helpers

Not on content pages: getListeners() and getEventLog() are available in the dashboard DevPanel console (labeled listeners + event log). Hosted pages use simple listeners without IDs. sendMessage is primarily a dashboard shorthand — content pages can dispatch viewer.chat.send_message directly (as shown above).

Method	Available on	Notes
`getListeners()`	Dashboard	Snapshot of labeled listeners for debugging
`getEventLog()`	Dashboard	Last 200 dispatched events
`React / ReactDOM / components`	Dashboard	Injected for library config modules