The shell API

Beyond its props, a module can reach three capabilities and their types, and nothing else.

What a module can call

Everything below is exported from content/shell/src/modules/shellApi.ts, the one runtime file on the module import allowlist.

None of them lets a module reach another module. Publishing is write-only into a sink the shell owns, the bridge only ever resolves against the module registry, and a sweep hands the shell a function and learns nothing back.

Publishing what the operator is looking at

usePublishScreenContext(detail: ScreenDetail | null): void

ScreenDetail is Record<string, ScreenValue>, and ScreenValue is the whole JSON grammar — strings, numbers, booleans, null, arrays, nested objects. Not a flat string map: the assistant's submit mutation round-trips nested structures to the model verbatim, so flattening would only lose information.

Call it wherever the answer actually lives — the workspace that knows the view, or the view that knows the row count — as many times as you like. The shell merges every live entry, keyed by useId(), and a later mount wins a key clash, which is the right precedence: the view knows more than the workspace hosting it. Pass null to publish nothing.

The value is keyed by its own JSON, so an inline object literal is fine and needs no memoising — re-publishing happens only when the content changes.

Five modules publish today: livechat, deals, bookings, flow-builder and automations.

Reading and moving the app

useShellBridge(): ShellBridge | null

ShellBridge has two methods.

snapshot(): ScreenSnapshot answers { moduleId, moduleTitle, url, params, detail, destinations } — the address bar verbatim (the model quotes it back and it has to be real), this module's params, the merged detail from every live publish, and where else the app could be sent. It is read at call time through a ref, so a snapshot taken ten minutes after the bridge was built is still current.

run(action: ShellAction): ShellActionResult takes { actionType, parameters } — free strings on the wire, because the vocabulary is the server's — and answers { ok, label, undo? }. Four outcomes:

undo is always available on a successful move, because everything the bridge can do is a route change and a route change is reversible — which is also why executing one needs no approval gate. Anything that changes account data is a server-side tool and goes through the server's own manual-approval batch instead.

The vocabulary run accepts

pathKey is a named destination, never a URL. resolveDestination normalises both sides (lowercase, non-alphanumerics stripped) and matches title first, then id, then an alias table — title first because the model has only ever seen the product's page names, id because that is what somebody writing the parameters by hand reaches for. First match in registry order wins, which is the order the rail shows.

Those are Chatfuel's own page names for things this shell calls something else. Names the model uses that exist in neither the table nor the registry — Billing, API, teammates — resolve to nothing and are reported as not being in this dashboard, which is the truth.

parameters.params becomes the URL query, capped on both axes: at most 12 keys, each value truncated to 200 characters. Objects, arrays, null and undefined are dropped rather than stringified. This is model output landing in the address bar and a module reads it as its own deep link.

Dropping what a module keeps on the device

registerDeviceCache(sweep: CacheSweep): () => void

A module that caches its data in localStorage so a screen paints before the network answers has a copy that belongs to one signed-in person looking at one bot — and nothing in the browser retires it. Signing out ends the session, switching bots changes the subject, and the copy outlives both. The flow builder is the case: it keeps whole flows there, message texts and WhatsApp templates included.

Register the sweep from the module's descriptor module, which is loaded whether or not the screen behind it ever opens — the cache outlives the screen, so the thing that registers has to as well.

The shell calls clearDeviceCaches() in three places: on sign-out, before the server call; when the topbar's stored bot changes; and when the auth session moves to another bot. A sweep that throws is swallowed and its answer is not read — one module's cache is not worth another module's sign-out, and storage itself throws where site data is switched off.

The deployment's own settings

src/config/ holds what is true of this deployment rather than of the product. defaults.ts declares the shape and the upstream values; app.ts holds the overrides and is yours — the wizard writes it once and records it as generated, which is what makes update skip it for the life of the app. Leaving a setting out of app.ts is how you keep getting the upstream's improvements to it.

The file is short on purpose. A value is a setting only when the code cannot work it out and the person using the app should not have to; the week's first day is a preference and falls back to the locale, a specialist's working hours are edited in the bookings UI, and which attribute holds a deal's amount is bound against what the bot really carries.

src/config/index.ts merges the two and freezes the result, so nothing that reads a setting can also set one. config/ sits outside every module subtree, so a module reads ../shellConfig, which re-exports APP_CONFIG and the AppConfig type.

The shell's own half

Three files implement the hooks and the bridge. None of them is on the import allowlist, so a module that reaches for one fails the boundary pass rather than compiling.

botSelection answers from three sources in this order of authority: what the person last chose (localStorage, under chatfuel.workspace and chatfuel.bot), what the wizard wrote as the starting point (VITE_CHATFUEL_WORKSPACE_ID), and what the account actually has right now — the last being the referee, so a stored id whose bot has since been deleted is a stale note to drop rather than an error to show. With no stored workspace, the remembered bot names where it lives now, because a bot can be moved between workspaces and following it is the more faithful restore.

workspaceOptions exists because Chatfuel does not require workspace titles to be unique and makes them collide by itself: creating a bot without naming a workspace leaves a throwaway "My Workspace" behind. Same-named entries get their bots appended, and identical-all-the-way-down ones get the last six characters of the id.

Both localStorage calls are wrapped: a browser with site data switched off throws on the property access itself, and losing the memory of a choice is not worth a blank screen. A workspace holding no bots is still remembered; an empty bot id is removed rather than written, so the next visit does not read it back as a real one.

The fourth file on the allowlist, content/shell/src/modules/testClient.ts, is not an API at all — it is an inert ModuleClient for the render smoke tests, where effects never run. A request made from it never answers, rather than answering with a lie.