inflowDocsLearning path

Interface-control developer guide

This guide explains how to build, test, package and ship an Inflow interface control: a browser control that interface authors place in the designer like a built-in one. It is task-oriented. For every field, type and limit, see the generated SDK and manifest reference. For a first walk-through, follow the tutorial first.

Every example here comes from a complete, buildable project. Each one is a sample in Studio's developer kit (Authorization → Plugins → Developer kit): an administrator downloads its exact ZIP and gives it to you with the SHA-256 Studio shows, as in the tutorial. The examples are:

Sample Developer kit row (ZIP) Shows
Region picker (starter) UI-only starter (interface-control-starter-1.0.4.zip) typed properties, member labels, dynamic choices from an expression, an editable output, an event, theme tokens, right to left, an accessible listbox, the playground, the debugger and tests
Service visits map Google Maps sample (interface-control-google-maps-1.0.6.zip) a record-list property, a real external provider loaded only when admitted, browser configuration, an offline mode, an accessible list alternative to a map, 1,000 markers
Service distance (mixed) Mixed sample (UI and Java) (interface-control-mixed-sample-1.0.4.zip) one package with a Java expression function and a browser control (--merge-jar), exact DECIMAL values

The Google Maps sample is optional in a build: if Studio does not list it, ask the administrator for a build that includes it. The sample (service-visit-maps, publisher "Example Org") is not the Google Maps control that every Inflow deployment already includes. That one is the Inflow plugin inflow-google-maps. Version 1.0.0 was built from the same source with Inflow's identity. Since 2.0.0 (SCRUM-5150) it has its own source, a general maps control with categories, grouping, picking and address search. It cannot be replaced or uploaded over. To change map behaviour for your organization, build and upload your own plugin under your own identifier. Inflow maintainers find the same projects under examples/interface-controls/ in the Inflow repository.

Contents

Versions and compatibility

Artifact Version Notes
@inflowai/control-sdk 1.1.3 lifecycle ABI 1, control contract 1
@inflowai/control-test-kit 1.0.2 needs SDK ^1.1.0; a mocked host
@inflowai/control-tools 1.0.2 the inflow-control packaging and validation CLI
Inflow plugin platform 0.1.0 accepts control contract 1 and SDK major 1

In plugin.json, declare "requires": "0.1.0" and, in interfaceControls, "contractVersion": 1 and "sdk": "^1.1.0". The host refuses a newer requires (PLUGIN_HOST_VERSION_UNSUPPORTED), a contract it does not implement (PLUGIN_CONTROL_CONTRACT_UNSUPPORTED) and an SDK major it does not provide (PLUGIN_CONTROL_SDK_UNSUPPORTED). When it loads your module, it also checks the lifecycle ABI the module reports. The full matrix is in Versions and compatibility.

Package kinds

Inflow decides the kind from the manifest:

Kind Manifest Built with Runs
UI-only interfaceControls, no pluginClass Node and npm only in the browser; the API serves its files; the plugin runner never loads it
Mixed interfaceControls and a pluginClass npm for the browser half, Maven for the Java half, merged with --merge-jar browser half as UI-only; Java half in the isolated plugin runner
Legacy Java pluginClass, no interfaceControls Maven the plugin runner (see the plugin developer guide)

Start with UI-only unless you need server code. A UI-only package can be upgraded in place; mixed and Java packages keep one active version (see Versions and upgrades).

Project structure

A control project is an ordinary npm project. The starter's layout:

Path Purpose
plugin.json The reviewed declaration: identity and interfaceControls. Never lists assets.
package.json Scripts, dependencies, and "inflowControl": { "distDir": "dist" }, where the packaging tool finds the build.
package-lock.json Required. The packaging tool checks every shipped dependency against it.
src/index.ts The module the host loads: export default defineControl({ controlKey, mount }).
src/ExampleControl.tsx The view and its styles.
src/generated/controlTypes.ts Generated from plugin.json by npm run types. Never edited by hand.
scripts/generate-types.mjs The generator. --check fails when the generated file is stale.
vite.config.ts One configuration for the playground, the tests and the library build.
playground/, index.html The local playground (npm run dev).
tests/ Behaviour tests and contract tests.
assets/ Files declared in plugin.json, such as the toolbox icon.
vendor/ The vendored SDK, test kit and packaging tool.
.vscode/ Launch configurations and the recommended Vitest extension.
LICENSE, THIRD-PARTY-NOTICES.md, README.md Copied into the archive. NOTICE is too, when present.

The build output

Each control's entry must be one self-contained ES module: your code, the SDK and every runtime dependency in one file, with no import left in it. The host loads it from a blob: URL, where imports cannot resolve. The starter uses Vite's library mode for this:

// vite.config.ts in the starter (excerpt)
build: {
  outDir: 'dist',
  sourcemap: true,
  lib: { entry: 'src/index.ts', formats: ['es'], fileName: () => 'control.js' },
  rollupOptions: { output: { inlineDynamicImports: true } },
},

Any bundler works if it produces that shape. The packaging tool refuses an entry that still imports something (PLUGIN_PACKAGE_ENTRY_NOT_SELF_CONTAINED). Source maps may ship, but must not contain absolute paths (PLUGIN_PACKAGE_PRIVATE_PATH).

Asset files may be JavaScript, CSS, JSON, source maps, PNG, SVG or WOFF2. Declared paths are relative, with no .. segment.

The manifest

plugin.json is what the administrator reviews. Nothing in it grants a permission: properties, outputs, events and providers are declarations the host checks your control against.

Identity

{
  "id": "starter-region-controls",
  "version": "1.0.0",
  "provider": "Example Org",
  "description": "Starter interface control: …",
  "requires": "0.1.0",
  "dependencies": [],
  "capabilities": [],
  "interfaceControls": { "contractVersion": 1, "sdk": "^1.1.0", "controls": [ … ] }
}
  • id: lowercase letters, digits and hyphens. A server installs each id once; later versions are upgrades.
  • version: semantic version. Every new build you hand out needs a new version: a server refuses the same version with different bytes (PLUGIN_VERSION_CONFLICT).
  • A UI-only package has no pluginClass and needs no dependencies or capabilities.

A control

{
  "controlKey": "starter-region-picker",
  "displayName": "Region picker (starter)",
  "description": "Choose a service region. Shows the choices as a keyboard-operable list.",
  "category": "Starter",
  "icon": "assets/control-icon.svg",
  "entry": "control.js",
  "properties": [ … ],
  "outputs": [ … ],
  "events": [ … ]
}

controlKey is the stable machine key (^[a-z][a-z0-9-]{0,63}$). Your module's controlKey must equal it. Authors search the toolbox by display name, key, plugin id, publisher, category and description.

Properties

{
  "key": "region",
  "label": "Region",
  "description": "The chosen region. Bind it to form data to let people change it.",
  "valueType": { "kind": "ENUM", "enumValues": ["north", "south", "east", "west"], "nullable": true },
  "sourceModes": ["LITERAL", "EXPRESSION", "BINDING"],
  "dynamicOptions": ["EXPRESSION"],
  "memberLabels": { "north": "North", "south": "South", "east": "East", "west": "West" }
}
  • valueType is the canonical platform value type. AUTO_NUMBER and BINARY are not allowed. RECORD and RECORD_REF need a schemaRef. The dynamic properties guide shows what each kind looks like when it reaches your control.

  • sourceModes lists how an author may set the property: LITERAL (Value in the designer), EXPRESSION, and BINDING (Data). Allow all three unless there is a reason not to.

  • restrictionReason is required whenever sourceModes has fewer than three entries. Authors see it. Write it for them: "A heading is presentation text, never form data."

  • default is a literal default, written in its canonical form. The designer saves it as the property's Value when an author places the control. It must fit valueType.

    The host does not fill in a default later. A property is unset in two cases, and your control then applies the declared default itself:

    • it was never set, so it is absent from context.properties and has no state;
    • an author chose Use default (which clears the setting) on a control that is already showing. The update then delivers the property's value as undefined, with the state { status: 'ready' }.

    A failed expression or binding is also absent from properties, but its state is error, invalid or loading. Its reason must be shown, never replaced by the default.

    A binding to data that holds no value yet (for example a Local without a default) is absent with the state unavailable, identically in the designer Preview and the published form. That is not a failure: a setting with a declared default may treat it as unset, as the Google Maps sample does for its map settings (SCRUM-5087). Whatever you choose, decide it the same way in preview and runtime, so the Preview shows what the published form will. On the design canvas (design mode) there is no running form, so every Expression or Data property is absent with the state unavailable, and an Expression or stored-data choice list is unavailable too (SCRUM-5073): show the unset state, never a loading message that cannot finish. An explicit empty value ('') or null from a resolved source is a real value: keep it.

    const state = view.states.heading;
    const value = view.properties.heading;
    const heading = state === undefined || (state.status === 'ready' && value === undefined)
      ? 'Service region'                                             // never set, or Use default: the declared default
      : state.status === 'ready' ? value                             // a resolved value, including '' or null
      : null;                                                        // loading, invalid, error…: show the state instead
    

    Test both cases with the test kit: mount without the property, and send an update that clears a configured heading. Both must show the default.

    The starter 1.0.0 does not do this yet: it uses view.properties.heading ?? 'Service region' and shows states for the region only, so a failed heading expression silently shows "Service region". Use the recipe above in your own control.

    Kind Write the default as Example
    TEXT, ENUM a JSON string "label", "roadmap"
    INTEGER a JSON number 11
    LONG, DECIMAL a JSON string of digits "9007199254740993", "51.5074"
    BOOLEAN true or false false
    DATE, TIME ISO text "2026-11-09", "09:30:00"

    LONG and DECIMAL travel as exact text so that no digit is lost to floating point. Every default is checked against its declared type exactly as the Value it becomes: its form above, then the declared range (minInclusive, maxInclusive), lengths, precision, scale, list sizes, ENUM members and nullable (a null default needs a nullable property; a RECORD default can only be null). Bounds are read as the server reads them: INTEGER as a whole number, LONG as a whole number of any size, DECIMAL as a decimal that may use an exponent ("1e2"), each after removing surrounding spaces; a bound it cannot read is not applied. Temporal defaults follow ISO-8601 as Java reads it (an INSTANT may be 23:59:60 or 24:00:00; year zero is 0000, never -0000), and an ENUM default must be a member exactly as written. Write integer facets (minLength, maxLength, minItems, maxItems, precision, scale) as plain whole numbers that fit a signed 32-bit int: the server ignores a facet written 3.0 or 3e0. inflow-control package, inflow-control validate, the test kit's runConformance and the Inflow upload all refuse a default that does not fit with PLUGIN_CONTROL_DEFAULT_INVALID, naming the control and the property (SCRUM-5076). Before control-tools 1.0.2, a DECIMAL default written as a JSON number passed packaging and upload and then blocked publication of every form that placed the control.

  • readOnly: true marks a computed input the control displays but never writes.

  • dynamicOptions (EXPRESSION, DATA_SOURCE) lets an author configure the choices of a choice property besides its declared members. See Choices.

  • memberLabels gives ENUM members display labels; the member stays the stored value. labels, descriptions and memberLabelsByLocale localize them by BCP-47 tag.

  • group groups properties in the designer, for example "Google Maps". visibleWhen shows a property only while another property's literal value is one of a list.

  • Keys follow ^[a-z][A-Za-z0-9]{0,63}$. Identity words are reserved and refused: id, pluginId, pluginClass, provider, controlKey, version, digest, sha256, entry, assets, capabilities, permissions, contractVersion, sdk.

Outputs

An output is a value the control may propose as an edit of one of its own properties:

{ "key": "region", "label": "Chosen region", "valueType": { "kind": "ENUM", "enumValues": ["north", "south", "east", "west"], "nullable": true }, "property": "region" }

The host writes it only when the author bound that property with Data to a declared, non-computed Local or Input of the same type. Only TEXT, UUID, ENUM, INTEGER, BOOLEAN, DATE and TIME values are ever written back. See Bindings and outputs.

Events

{
  "key": "regionConfirmed",
  "label": "Region confirmed",
  "description": "A person confirmed a region (Enter or double-click).",
  "payload": [{ "name": "region", "valueType": { "kind": "ENUM", "enumValues": ["north", "south", "east", "west"] } }]
}

Authors connect events to automations by label, and read the payload as event.<name>. The designer turns an event key into a trigger (regionConfirmed becomes onRegionConfirmed). Keys whose trigger the platform already uses are reserved: signal, click, change, blur, submit, load, mount, destroy, formValidityChange, formDirtyChange, serverCertification, input, enterPress, select, selectionChange, open and close. Such an event is not offered to authors, gets no agent command, publication refuses a handler on it, and emit returns not-declared. Use a domain name such as regionConfirmed or markerSelected. A payload is at most 16 KiB of serialized JSON. A RECORD event payload field is never sent; carry an identifier (TEXT) instead, as the map sample's markerSelected { jobId } does.

Providers

Declare every external service your browser code calls, under interfaceControls.providers. See External providers.

Keep the types in step

The starter generates its TypeScript types from plugin.json:

// src/generated/controlTypes.ts (generated)
export const declaration = { … } as const satisfies ControlDeclaration;
export type Properties = PropertiesOf<typeof declaration>;
export type Outputs = OutputsOf<typeof declaration>;
export type Events = EventsOf<typeof declaration>;

After every edit of plugin.json, run npm run types. typecheck and build fail on stale types, and a contract test checks that the generated declaration equals plugin.json, so the code cannot drift from what the administrator reviews.

The lifecycle

// src/index.ts in the starter (abridged)
export default defineControl<Properties, Outputs, Events>({
  controlKey: declaration.controlKey,
  mount(element, context) {
    context.host.adoptStyles(styles(context.theme));
    const root = createRoot(element);
    // … render from context.properties, context.propertyStates, context.options, context.direction
    return {
      update(change) { /* merge the changed parts, re-render in place */ },
      dispose() { root.unmount(); },
    };
  },
});
  1. Load. The host loads the declared entry of an installed, enabled package, checks it with checkControlModule (ABI, controlKey, mount) and shows the shared Control not available state if the check fails.
  2. Mount. mount(element, context) runs once per mounted generation of a placed control, and may be asynchronous. The same placed control can be disposed and mounted again (see When the host remounts). Render into element. context carries:
    • properties, resolved and typed (never expression text), and propertyStates, one state per property;
    • options, the dynamic choices of choice properties;
    • mode (design, preview or runtime), locale, direction, theme and size;
    • providers and configuration, for admitted providers at runtime only;
    • instanceId, unique per placed instance, for element ids;
    • host, the host services.
  3. Update. update(change) carries only what changed: properties, propertyStates, options, theme, direction or locale. An omitted key is unchanged; a key present with the value undefined is withdrawn, and its content must be cleared, not kept. Re-render in place so the focused element keeps focus. Never call setOutput or emit from update.
  4. Resize. Optional resize(size) reports the host element's new size.
  5. Dispose. dispose() releases everything: listeners, timers, observers, provider objects, DOM. It must be safe to call more than once. After it, the host refuses or ignores every business call the instance makes (setOutput and emit return not-ready); a cleanup registered with onDispose after retirement runs at once.

A change of providers or configuration does not arrive through update: the host disposes the instance and mounts a new one. Read them in mount.

When the host remounts

The host disposes the instance and mounts a new one when any of these changes: the pinned package or entry, the workspace, the authenticated principal, whether the control is shown (a hidden reveal section, an inactive tab panel), which properties its outputs are bound to, or the provider admission and configuration. A new instance starts from context alone, so keep no state that only the previous instance knew: anything a person must not lose belongs in form data through a bound output. Each instance has its own instanceId.

An identity boundary is broader than signing out and back in. It includes a different accepted principal on the same page, a sign-out that clears the principal, another tab signing in as a different person, and the same principal id being accepted as a different actor type. At that boundary the host withdraws the prior catalog, disposes mounted instances, aborts their signals, and retires pending control loads, evaluated modules and record-option answers. A module import that has already begun cannot be undone; if its principal lifetime ends while it is running, its result is discarded and is never mounted or returned to a caller. Server authorization remains required for every catalog, asset and option request.

By contrast, a routine refresh, retry or mutation that keeps the same accepted principal does not itself create a new principal lifetime. Do not use module-level state as a place to retain user-specific state across sign-in boundaries. Put business data in the declared form model and release instance-owned listeners, timers and provider resources from dispose() or onDispose().

Worked example — two people, one open tab. Alice opens the published form and the host loads its pinned control. She signs out, then Bob signs in without closing the tab. The old instance is disposed and its signal is aborted; a request or import still settling for Alice is not delivered to Bob. If Bob is authorized to use the form, the host checks and loads the form's published control again in Bob's principal lifetime. If he is not authorized, the server refuses the route and the shared neutral unavailable page is shown. Alice's module cache is never the source of Bob's control.

These boundaries have focused failing-first regression coverage. The separate live principal-switch journey is still IMPLEMENTED / NOT VERIFIED pending the recording and playback gate recorded in the T035 certification; that status does not change the control-author contract above.

Modes

context.mode Where Outputs and events
design the designer canvas suppressed
preview the designer's Preview, which runs a test form routed to the preview's session values and automation steps, never saved
runtime a published form written to the form's draft and routed to automations

Providers and their configuration reach only runtime. Do not decide from mode whether to call setOutput or emit: call them from the person's interaction and handle the HostResult. Use mode for provider loading and for wording, for example "Previews never contact Google".

Host services

Service Use
setOutput(key, value) Propose a person's edit of a declared output. Returns a HostResult.
emit(event, payload) Report a person's interaction as a declared event. Returns a HostResult.
searchOptions(key, text) Ask for server-searched choices narrowed by text (see Choices).
adoptStyles(css) Install the control's CSS, scoped to this instance (see Theme).
announce(message) Intended to speak through the host's live region. Currently silent in Studio: the published and designer hosts do not connect it to a live region yet. Until they do, also render the message in your control (for example a role="status" element).
setBusy(busy) Show the host's loading state, for example while a provider library loads.
reportError({ code, message }) Give up: the host shows the shared error state. Never put secrets or payloads in it.
onDispose(cleanup) Register cleanup, run once at dispose in reverse order.
signal An AbortSignal aborted at dispose. Pass it to every listener, timer and request that accepts one.

setOutput, emit, searchOptions and adoptStyles return a HostResult: { accepted: true } or { accepted: false, reason }. reportError, setBusy, announce and onDispose return nothing. The reasons:

Reason Meaning
not-ready The instance is loading, hidden, frozen or disposed, or the bound value is still loading.
not-declared The key is not declared.
invalid-value The value does not fit the declared type, or a payload is too large.
suppressed No business effect here: the design canvas or a preview without a running form, a property that is not bound to writable form data, or an event without a person's interaction.
unchanged The output equals the current value (the echo guard). Not an edit.

Never assume success. The starter announces a refused edit, except for unchanged and suppressed (in Studio that announcement is currently silent; see announce above, so show the message in the control as well):

const result = host.setOutput('region', choice.value);
if (!result.accepted && result.reason !== 'unchanged' && result.reason !== 'suppressed') host.announce('The region could not be changed.');

Property states

Each property has a state: ready, loading, empty, invalid (with a reason), error (with a reason) or unavailable. A failed property (loading, error, or an invalid value that does not fit) is withheld: show its state and reason, never a value or a guess. One invalid state is different: "This choice is no longer offered." keeps the selected value in properties. Show that value marked as invalid, with the reason, beside choices the person can use to correct it.

Two states must still let a person choose, because the host accepts the write:

  • unavailable for an unset binding: the first choice is a lawful write.
  • invalid with the reason "This choice is no longer offered.": the bound value is not among the current choices, and a corrective choice is accepted.

The starter keeps its choices operable in both, and its tests prove it (lets a person make the first choice for an unset binding, keeps the choices operable when the bound choice is no longer offered).

Only genuine input may change data

Your control must call setOutput and emit only for a person's own interaction. The host enforces part of that rule, and the review of your code covers the rest.

What the host enforces

  • emit is refused (suppressed) while the host is calling into your control (mount, update, resize), and unless the page's latest pointer or key input landed inside your control within the last 5000 ms. A programmatic .click() or a synthetic input or change event does not count. Replacing the clicked element in your handler is fine.
  • The design canvas, and a preview without a running form, suppress outputs and events (suppressed).
  • An output that repeats the delivered value is unchanged, so echoing a pushed value never makes a form dirty.
  • Every output is checked for declaration, binding, writability and type, as described in Bindings and outputs.

What the host does not enforce

  • setOutput has no interaction check. A ready control that calls it from update, a timer or a provider callback, with a valid value that differs from the current one, changes the person's form draft. Not doing so is your obligation: never write from mount, update, resize or a timer the person did not start. The test kit's runConformance fails a control that sets outputs or emits events without a person's interaction, so keep it in your tests, and administrators review it.

In tests, a synthetic event is not trusted input either, so the kit records interactions explicitly: harness.interact(element) before a click, or harness.press('Enter') for a key. Each recorded call carries afterInteraction.

Agent commands. While your control is ready in a running form, Inflow registers each declared output as <agentId>.output.<key> and each event as <agentId>.event.<key>. They take the same route and checks as your own calls, except the interaction check: an agent command is itself the accepted interaction, so an event command does not need a pointer or key input. Events whose key is reserved (see Events) get no command. Give outputs and events clear labels: they are the commands' titles.

Theme and right to left

context.theme maps token names to CSS custom-property references. The vocabulary:

Token Value
surface, surfaceRaised var(--surface), var(--surface-2)
text, textMuted, textSubtle var(--ink), var(--ink-2), var(--ink-3)
border, borderSubtle var(--border), var(--border-subtle)
accent, accentSoft var(--accent), var(--accent-soft)
danger, warning var(--danger), var(--warn)
radius var(--r-control)
spaceSmall, spaceMedium var(--space-2), var(--space-3)

Build your CSS from these values; do not write the variable names yourself, and do not use raw colours. Light and dark deliver the same references: the page redefines the variables, so your control follows a theme change without an update. The starter's styles(theme) does this:

const t = (token: string, fallback: string) => theme[token] ?? fallback;
// …
.choice { padding-block: ${t('spaceSmall', '8px')}; padding-inline: ${t('spaceMedium', '12px')};
  border: 1px solid ${t('border', 'currentColor')}; border-radius: ${t('radius', '8px')}; … }

Install the CSS with host.adoptStyles(css). The host scopes it to your instance with @scope and removes it at dispose; a new call replaces the previous sheet. It refuses (invalid-value, nothing applied) a sheet over 64 KiB, one whose blocks, comments or strings do not close, and one that uses @import, @namespace, @page, @scope, a named @layer, or defines global names (@keyframes, @font-face, @property, @counter-style). Use transitions instead of keyframes. Never add <style> or <link> elements to the page yourself.

For right to left, use logical CSS properties (padding-inline, margin-inline-start, inset-inline-end) and follow context.direction, which update may change. The starter sets dir on its root from it.

Accessibility

The host gives your control a named region with data-agent-state, and returns focus to that region if your instance disappears while it holds focus. The rest is yours:

  • Name every interactive element, and make every action reachable from the keyboard.
  • Keep focus where the person was when an update arrives: re-render in place, do not replace the focused node.
  • If your primary view is not accessible (a map, a chart, a canvas), also render a list alternative: one named listbox or list, one item per entry with the same name as in the main view, only the selected item aria-selected="true", one tab stop, and arrow keys that reach every item. Keep it in step with the selection both ways. The map sample's job list is one.

runConformance checks the list alternative when you pass listAlternative, and the kit exports accessibleAlternativeProblems and keyboardReachProblems for your own tests.

Testing with the kit

@inflowai/control-test-kit mounts your real module under a simulated host that applies the platform's rules for values, outputs, events, styles and interaction provenance. Results are labelled MOCKED_BOUNDARY: passing them is never evidence that the control works on a server or with a real provider.

Behaviour tests with mountForTest:

// tests/ExampleControl.test.tsx in the starter (excerpt)
const harness = await mountForTest(control, {
  declaration, mode: 'runtime',
  properties: { heading: 'Service region', region: 'south', compact: false },
  sources: { region: { mode: 'BINDING', bind: 'locals:region' } },
});
const east = choices(harness)[2]!;
harness.interact(east);
east.click();
harness.press('Enter', east);
const effects = harness.calls.filter((c) => c.service === 'setOutput' || c.service === 'emit');
expect(effects.map((c) => [c.service, c.args, c.result?.accepted])).toEqual([
  ['setOutput', ['region', 'east'], true],
  ['setOutput', ['region', 'east'], true],
  ['emit', ['regionConfirmed', { region: 'east' }], true],
]);

(mount() in that file wraps mountForTest with these options.) The simulated host does not feed an accepted output back as a new property value, which is why Enter's setOutput is accepted again here; on the platform the bound value changes and a repeat is unchanged.

Useful options: mode, propertyStates, options, sources, palette (light or dark), direction, locale, size, providers and configuration. The harness offers update, resize, setPalette, interact, press, dispose, and the recorded calls, styles, failures and teardownErrors. Fixtures cover every kind (SAMPLE_VALUES, INVALID_VALUES, typeFixtures), every state (PROPERTY_STATES, OPTIONS), an options race (optionsRace), themes (THEME_TOKENS, PALETTES), right to left (RTL) and providers (PROVIDERS).

Conformance with runConformance:

// tests/contract.test.ts in the starter (excerpt)
const report = await runConformance(control, declaration, {
  properties: { heading: 'Service region', region: 'north', compact: false },
  listAlternative: { items: ['North', 'South', 'East', 'West'], selected: 'North' },
});
expect(report.boundary).toBe(MOCKED_BOUNDARY);
expect(report.checks.filter((c) => !c.passed)).toEqual([]);

It checks the ABI, declaration-valid inputs, every mode, no effects without a person (deferred ones too), idempotent disposal in the host's order, every property state, an options race, theme and right to left, focus kept on update, no network without provider admission, agent labels and, when given, the list alternative. A control that draws its choices (a canvas or a map) passes renderedChoices.

Keep the starter's third contract test as well: it validates the manifest with the packaging tool's admission rules (validateManifest from @inflowai/control-tools), so a manifest error fails npm test, not only npm run package.

Tests run in jsdom (environment: 'jsdom' in vite.config.ts). jsdom prints Error: Could not parse CSS stylesheet for the scoped sheet the simulated host installs; it does not fail a test. To check a control in a real browser, serve the test page with the kit's OFFLINE_CONTENT_SECURITY_POLICY.

Packaging

npm run package    # npm run build, then inflow-control package --out package/<id>-<version>.zip
npm run validate   # inflow-control validate package/<id>-<version>.zip

inflow-control package reads plugin.json and the build directory (inflowControl.distDir, default dist), then:

  1. validates the manifest with the host's admission rules;
  2. derives each built file's path, content type, size and SHA-256 and inserts the assets list (your source plugin.json must not have one: PLUGIN_PACKAGE_INVALID);
  3. loads each entry and checks its ABI and controlKey (PLUGIN_PACKAGE_ABI), and refuses leftover imports;
  4. checks the production dependency closure in package-lock.json (lockfile version 2 or 3): every shipped dependency must resolve from the HTTPS registry (--registry, default the public registry), declare a licence, and be listed in THIRD-PARTY-NOTICES.md;
  5. scans every file for credentials and private absolute paths;
  6. writes a deterministic archive with one root plugin.json, the declared files, and LICENSE, NOTICE, THIRD-PARTY-NOTICES.md and README.md when present;
  7. prints the kind, the archive SHA-256 and each asset's SHA-256 and size.

The Inflow SDK must be a development dependency: it is bundled into the entry, and a production file: dependency is refused. Keep React and other runtime libraries as ordinary dependencies from the public registry.

Limits: archive 5 MiB, expanded 50 MiB, one entry 10 MiB, plugin.json 64 KiB, 2,048 entries, compression ratio 100:1. Upload in Studio also accepts at most 5 MB.

validate re-applies the admission rules to an existing archive. A pass is a structural check, not a review or a trust decision. Hand the administrator the exact archive and its SHA-256, and never edit the archive afterwards.

The command reference and exit codes are in the tools README.

Distribution: what ships in the starter

The Inflow packages are not published to npm or any other registry, and there is no separate download for them. Each developer-kit ZIP that an administrator downloads from Studio (Authorization → Plugins → Developer kit) carries them in its vendor/ folder:

"devDependencies": {
  "@inflowai/control-sdk": "file:vendor/inflowai-control-sdk-1.1.3.tgz",
  "@inflowai/control-test-kit": "file:vendor/inflowai-control-test-kit-1.0.2.tgz",
  "@inflowai/control-tools": "file:vendor/inflowai-control-tools-1.0.2.tgz",
  …
}

The mixed sample also carries the Java plugin SDK and test kit, as a local Maven repository under vendor/maven/.

npm ci installs them from those files, checked against the lockfile's integrity. To start a new project, copy the starter (or the sample closest to what you need), keep vendor/ and the lockfile, and change the identity. To move to a newer SDK, ask the administrator for the starter from the developer kit of the newer Inflow build, check its SHA-256, and take its vendor/ folder and lockfile entries; do not mix tarballs from different releases.

The vendored packages are proprietary (UNLICENSED) and carry their own LICENSE and NOTICE. The starter's own LICENSE is terms of use: you may use and modify it to build controls for Inflow, and you support the controls you build; Inflow does not.

Versions and upgrades

  • Give every build you hand out a new version. The archive name in the package and validate scripts follows it.
  • First install of an id: the administrator uploads it on Authorization → Plugins, and it is live as soon as the upload succeeds; there is no approval step. A later upload of the same id is an upgrade for a UI-only plugin and is refused for a Mixed or Java plugin (PLUGIN_ID_ALREADY_INSTALLED).
  • UI-only upgrade: the administrator uploads the new version on Authorization → Plugins and it is live at once (SCRUM-5091) (see Upgrade a UI-only package). The earlier version is kept for the publications that pinned it. New designs get the new version; authors upgrade existing nodes with Review upgrade, then publish again.
  • Mixed or Java package: one active version. Replacing it means uninstall and upload; uploading over it is refused with "Uninstall it first".
  • A version number is used once: PLUGIN_UPGRADE_VERSION_EXISTS for a version already installed or kept, and PLUGIN_VERSION_CONFLICT for the same version with different bytes.

Compatibility for authors' saved settings: a new version may add properties, events and choices. An author's settings are kept as they are and checked against the new version. Settings and automations the new version no longer declares block the upgrade of the node that uses them, and publication refuses them ("This control does not declare a property named '…'", "This custom control does not send this event."). Contract version 1 has no configuration migrations, so keep keys stable.

A published interface records the exact pin: plugin id, control key, contract version, plugin version and archive SHA-256. A release to another server carries only the pin; the receiving server must have the same artifact installed and enabled.

External providers

A provider is an external service your browser code calls: a map, a geocoder, a chart library from a CDN. Declare each one, so the administrator can see it in the plugin's Details and configure it under Providers:

"providers": [
  {
    "key": "google-maps",
    "purpose": "Draws the service-visit map with the Google Maps JavaScript API.",
    "origins": ["https://maps.googleapis.com", "https://maps.gstatic.com", "https://fonts.googleapis.com", "https://fonts.gstatic.com"],
    "dataCategories": ["location", "free-text", "usage"],
    "configuration": [
      { "key": "apiKey", "classification": "browserPublic", "label": "Maps JavaScript API key (referrer-restricted)", "required": false },
      { "key": "mapId", "classification": "browserPublic", "label": "Map ID (for advanced markers)", "required": false }
    ]
  }
]
  • origins: every https:// origin the code contacts, including ones a library contacts on its own. The map sample found that Google Maps also loads fonts from two Google font hosts, and declares them.
  • dataCategories: what the browser sends: none, location, address, personal-name, contact, record-identifier, free-text, usage.
  • configuration: what the provider needs per environment. browserPublic values reach the browser and are public by definition (a referrer-restricted key, a map id). serverSecret values are stored as vault references and never reach the browser; a browser control cannot use one.

Loading rules

Your control may load a provider only when all of these hold:

  1. context.mode is runtime: the form is published and running. Design and preview never receive providers.
  2. context.providers lists the provider's key. That happens only after an administrator uploaded the package and saved the provider's required settings for this environment under Providers (saving turns it on).
  3. Everything else your provider needs is present, for example a key from context.configuration or a property.

Otherwise, render an offline alternative that works without the provider, and say why. The conformance check fails a control that makes any network request without admission. When an administrator turns the provider off, open pages pick it up at their next catalog check (every 15 seconds) and remount your control without it.

Pass context.host.signal to the loader, and release every provider object in dispose. Call host.setBusy(true) while a provider library loads.

The map sample's design

The Service visits map (the developer kit's Google Maps sample; read its README.md) is the worked example:

  • The author enters the browser key in the control's Maps API key property (apiKey, Value only, with a restriction reason that says it is public). The provider's apiKey configuration is the environment-wide fallback. The property wins when set. Because the property shares its key with a provider setting, Studio treats it as a provider setting (SCRUM-5123): the designer warns when it holds a non-empty literal value (the value is saved in the form and travels in exported releases). A target release review names the property only when the receiving server serves that exact pinned control; an unavailable control gets the separate unavailable-control result and may block import. Recommend that authors leave the property empty and that administrators configure the provider per environment. The same applies to any control property whose key equals one of your providers' configuration keys.
  • A key in the form alone never loads Google: context.providers must list google-maps.
  • Without admission, a key, or a working load, it shows a provider-free plot captioned "Offline map: not Google Maps", with the reason, and its job list keeps working.
  • A refused or revoked key (gm_authFailure) switches it back to the offline map and releases every marker and listener.
  • Its locations property is a record list (RECORD, cardinality: MANY, at most 1,000) set from data or an expression, for example rule('service_visits_map'), a published MANY QUERY rule over the visit record type whose typed record list feeds the property directly. A form data list delivers at most 200 rows. App Shell application users get that rule only after the application's access review lists and grants it (the rule runs as them, like a Call a rule action; see the designer manual, Application users).
  • A property or choices expression may call any of the seven expression-callable rule kinds. An expression that calls an INTEGRATION, AI_TASK or RECORD_CRUD rule runs that rule on every render and every value change, for every viewer (workspace and application users alike), under that viewer's own rights: it calls the external system or AI model, or writes the records, each time. Keep such calls out of control properties unless that is what you want; use a button action for one-off effects.

Mixed packages: browser and Java

Use a mixed package when the control needs server-side logic that already exists as a Java plugin, for example an expression function. The Service distance sample (the developer kit's Mixed sample (UI and Java)) pairs the serviceDistanceKm(lat1, lng1, lat2, lng2) function with a control that shows its DECIMAL result.

You need JDK 17 and Maven 3.8 or newer for the Java half, and Node 22.22 for the browser half:

mvn -B -f java/pom.xml verify   # builds java/target/mixed-service-distance-1.0.4.jar
npm ci
npm test
npm run typecheck
npm run package                 # npm run build, then inflow-control package --merge-jar java/target/… --out package/…
npm run validate                # must report MIXED

Rules the packaging tool enforces with --merge-jar:

  • The JAR's plugin.json must have the same id, version, provider and requires as the browser plugin.json, and a pluginClass.
  • dependencies and capabilities are declared once, in the JAR.
  • No file may exist in both halves.

Keep pluginClass out of the browser plugin.json. Never add one by hand to make an archive "mixed": without --merge-jar, the tool would build a MIXED archive with no Java in it. Never use --merge-jar to turn a UI-only control into a Java plugin.

The two halves go live on upload, and are enabled and disabled, together. Inflow refuses the whole upload when either half is invalid. A mixed package cannot be upgraded in place.

Trust: what the host does and does not enforce

An uploaded control is trusted browser code. It runs with the browser privileges of the page and the signed-in person. The SDK is a typed contract, not a sandbox.

The host enforces, on its own channels:

  • outputs: declared, typed, bound to writable form data, never saved from the canvas or a preview (not that they come from a person: that is your code's obligation);
  • events: declared, typed, at most 16 KiB, from a person's interaction inside the control;
  • styles: scoped to the instance, bounded, no global rules;
  • files: served only from the installed archive, by exact digest;
  • every business effect: re-authorized by the platform at its service boundary, under the current person's rights.

The host does not enforce:

  • network access. The SDK offers no network API, but nothing stops trusted code from calling fetch. Provider origins are a reviewed declaration, not a browser policy;
  • what a provider does with data already sent, or a key already delivered.

So: call external services only through declared, admitted providers; never put a secret in a control, a property default, a fixture or a test; keep personal data out of what you send to providers unless your agreements allow it.

Troubleshooting

Local commands

Message Cause Fix
src/generated/controlTypes.ts is stale: run npm run types plugin.json changed. npm run types.
npm ci integrity error for vendor/*.tgz The tarball or lockfile was edited, or comes from another release. Restore both from the same starter release.
Error: Could not parse CSS stylesheet, flushSync was called from inside a lifecycle method, or Attempted to synchronously unmount a root while React was already rendering during npm test jsdom cannot parse the scoped sheet; React warns about the playground test's deliberate remount. Nothing, if the command exits with status 0 and reports no failed files, failed tests or unhandled errors. Any other error needs fixing.
A test's click is refused as suppressed No recorded interaction, or mode is design or preview, or the property is not bound. harness.interact(target) first; mount in runtime with sources: { key: { mode: 'BINDING', bind: 'locals:key' } }.
npm run dev stops with Port 5199 is already in use Another playground or program uses the port. Stop it. The port is fixed (strictPort in vite.config.ts) because the Playground in Chrome launch configuration opens it.

Packaging and validation refusals

Each refusal starts with a stable code. These are the messages the tool prints:

Code and example message Fix
PLUGIN_MANIFEST_INVALID: … must have required property 'restrictionReason' A property with fewer than three source modes needs a restrictionReason.
PLUGIN_MANIFEST_INVALID: … /key must NOT be valid The key is reserved (for example version). Rename it.
PLUGIN_MANIFEST_INVALID: … /valueType/kind must be equal to one of the allowed values AUTO_NUMBER, BINARY or a misspelt kind.
PLUGIN_CONTROLS_INVALID: control '…' output '…' names an undeclared property An output's property must be a declared property key.
PLUGIN_CONTROLS_INVALID: control '…' entry 'main.js' is not a declared text/javascript asset entry must name the built file in distDir.
PLUGIN_PACKAGE_INVALID: plugin.json must not list assets; … Remove assets; the tool computes them.
PLUGIN_PACKAGE_ABI: control '…' entry is not an ABI-1 control module (key-mismatch) The module's controlKey differs from the declaration. Run npm run types and rebuild. Other problems: abi-mismatch, no-mount, bad-control-key, not-an-object.
PLUGIN_PACKAGE_ENTRY_NOT_SELF_CONTAINED: … entry imports another module; … Bundle everything into the entry.
PLUGIN_PACKAGE_NOTICE_MISSING: scheduler is not listed in THIRD-PARTY-NOTICES.md List every shipped dependency, transitive ones included, with its licence.
PLUGIN_PACKAGE_DEPENDENCY_SOURCE, PLUGIN_PACKAGE_DEPENDENCY_LICENSE, PLUGIN_PACKAGE_LOCKFILE_REQUIRED, PLUGIN_PACKAGE_LOCKFILE_UNSUPPORTED, PLUGIN_PACKAGE_REGISTRY_INVALID Use a complete lockfile (version 2 or 3) and an HTTPS registry; shipped dependencies need a licence.
PLUGIN_PACKAGE_SDK_MISSING Install @inflowai/control-sdk (from vendor/).
PLUGIN_PACKAGE_CREDENTIAL, PLUGIN_PACKAGE_PRIVATE_PATH Remove the credential or absolute path, including from source maps.
PLUGIN_HOST_VERSION_UNSUPPORTED: requires plugin platform 9.0.0; host provides 0.1.0 Use "requires": "0.1.0".
PLUGIN_CONTROL_CONTRACT_UNSUPPORTED: … (supported: 1) Use "contractVersion": 1.
PLUGIN_CONTROL_SDK_UNSUPPORTED: browser SDK major 2 is not supported Use "sdk": "^1.1.0".
PLUGIN_ARCHIVE_*, PLUGIN_ASSET_* from validate The archive does not match its manifest, exceeds a limit, or was edited. Package it again; never edit an archive.

On the server

Symptom Cause What to do
Upload refused with the same codes as above The server applies the same admission rules. Fix, re-package, re-validate, and give the administrator the new archive.
PLUGIN_KILL_SWITCH_ACTIVE Only a server older than SCRUM-5122 answers this; the global kill switch was removed. Ask the operator to upgrade the server.
PLUGIN_ID_ALREADY_INSTALLED ("A plugin with this identifier is already installed.") / PLUGIN_VERSION_CONFLICT ("This plugin version is already installed with different content. Publish a new version.") Same id uploaded again / same version with different bytes. Studio shows the message. Ask for an upgrade of a UI-only package / bump the version.
No Installed controls group in the toolbox Not installed and enabled (for example disabled, or left Not active by an earlier version), or the author cannot edit the interface. The administrator checks the plugin row.
Control not available on the canvas or in a form Disabled or uninstalled, digest or ABI check failed, or the module threw in mount. Check the plugin row, then the browser console. Fix the module and ship a new version.
An application user's control shows no data from rule('…') (the position answers SCREEN_EXPRESSION_ACCESS_DENIED), or the control is Not available for them only The rule is not in the App Shell's reviewed access for their group yet, or it was published again (or its version pin changed) after the review. Ask an administrator to review and apply the application's access again; the review lists the rule.
A small Not available badge in place of the control, for some people only They are application users (they open the interface through an application with its own runtime access rules), and the server cannot check something this placed control depends on: a property bound directly to stored data (data.…, record.…), an expression that reads another kind of state directly (such as process variables or outputs), or a Local or Input that is itself left out (a computed Local, a Local whose default is a formula, a Local of an unsupported type such as a Record Local, or an undeclared Input). Checkable settings are fixed values, Data bindings to form Locals and Inputs, expressions over form Locals and Inputs, governed constants and literal rule('key') calls (the rule must also be in the application's reviewed access), and choices from an expression, a Local or Input, or stored records filtered by Locals or Inputs (read with the person's own access). Ask the author to use those shapes for this control, and test as an intended application user. See Application users.
The control shows the value but clicks change nothing The property is set by Value or Expression, or bound to a computed Local, a data.… list, a row field or another type. Bind it with Data to a declared Local or Input of the same type.
An automation never runs The event was emitted without a recent interaction inside the control, from update, or with a payload that does not fit the declaration. Emit from the interaction's handler; check the payload against payload.
A provider never loads Not runtime, not admitted in this environment, or missing configuration. Publish and open the form; ask the administrator to check Providers.
ACCESS_POLICY_UNAVAILABLE on a published form Either the request carries only a development proxy actor header without a real sign-in, or the server could not evaluate its runtime access policy. Sign in normally. If you already are, it is a server-side outage: give an operator the time and the form, and do not treat it as a permission denial.
PLUGIN_CONTROL_DEFAULT_INVALID ("control '…' property '…' has a default that does not fit its declared … type: …") A property's default does not have its kind's form (LONG and DECIMAL as digit text, INTEGER as a JSON whole number) or breaks a declared range, length, scale, member or nullability. Fix the default in plugin.json (see the table under default), give the package a new version, re-package and re-validate.
A DECIMAL default blocks publication of a form (packages built before control-tools 1.0.2 and servers before SCRUM-5076) Written as a JSON number. Write it as a string, for example "51.5074", and publish a new package version.

When you report a problem to an administrator, give the plugin id, version, archive SHA-256 and the exact code and message. Never include keys, tokens or customer data.

Inflow documentation · Published 19 November 2026

Screenshot captions retain their recorded build and capture context.

Type to search articles and their contents.