Inflow.aiDocs

Interface-control SDK and manifest reference (SDK 1.1.3)

This is the reference for building a browser interface control. It covers:

  • the interfaceControls section of plugin.json;
  • the @inflowai/control-sdk lifecycle ABI;
  • the @inflowai/control-test-kit mocked host;
  • the versions, limits, refusal codes, licensing and trust rules that apply to them.

Most of this page is generated by inflow-control-sdk/scripts/reference.mjs. It reads the manifest schema, the reviewed public API baselines, the host's Java contract constants and the enforced limits directly, so the reference cannot drift from what ships.

Two commands keep it honest, both part of npm run verify in inflow-control-sdk:

  • npm run reference:check fails when this page is stale.
  • npm run reference:examples packs the SDK and test kit and installs them into a clean project. It then compiles every example below and validates the example manifest with the packaging tool.

Guides for first-time developers (IDE setup, recipes, testing, packaging, troubleshooting) are listed in the documentation index.

Versions and compatibility

Artifact Version Contract facts
@inflowai/control-sdk 1.1.3 lifecycle ABI 1; targets control contract 1; Node >=22.22.0 for building
@inflowai/control-test-kit 1.0.2 requires @inflowai/control-sdk ^1.1.0; a mocked host, never platform acceptance
@inflowai/control-tools 1.0.2 packages and validates exactly as the host admits
Inflow host (plugin platform) 0.1.0 accepts control contract 1; accepts SDK major 1 in interfaceControls.sdk; a manifest whose requires is newer than 0.1.0 is refused

A module built with SDK 1.1.3 reports ABI 1; the host refuses a module whose ABI differs. Declare "contractVersion": 1 and "sdk": "^1.1.3" (or a lower 1.x caret) in interfaceControls.

Compatibility rules:

  • Control contract (interfaceControls.contractVersion): the meaning of the declaration and of the host services. A host refuses a contract version it does not implement. It never silently drops the section.
  • SDK range (interfaceControls.sdk): the caret range of the browser SDK your bundle was built with. A host accepts only the SDK majors it provides. Minor versions add API, so a module built with an older minor still loads.
  • Lifecycle ABI: checked when the module loads. The module's default export must be the frozen value returned by defineControl, carrying the ABI this host implements.
  • requires: the minimum Inflow plugin platform version. A newer value is refused before anything loads.

Lifecycle

A control is an ES module whose default export is defineControl({ controlKey, mount }).

  1. Load. The entry must be one self-contained ES module with no imports: bundle your code, the SDK and every dependency into it. The host loads it from a blob: URL, where imports cannot resolve. The host lazily loads the declared entry asset of an active (uploaded and enabled) package and checks the module with checkControlModule. If the check fails, or the module's controlKey differs from the declaration, the host shows the shared unavailable state.
  2. Mount. mount(element, context) runs once per placed instance and returns the instance. context carries:
    • the resolved, typed properties and their propertyStates;
    • options, theme tokens, direction, locale, mode and size;
    • the admitted providers and their browser-public configuration;
    • the host services.
  3. Update. update(change) delivers changed properties, states, options, theme, direction or locale. Re-render in place, and never emit from update.
  4. Resize. resize(size) is optional. It delivers the host element's new size.
  5. Dispose. dispose() must be safe to call more than once. It releases every listener, timer, observer and provider object. Pass context.host.signal to anything that accepts an AbortSignal: it aborts on dispose. A change of providers or configuration remounts the control.

A control proposes edits with host.setOutput(key, value) and reports genuine user interactions with host.emit(key, payload). Both return a HostResult; the control must not assume success. host.reportError shows the shared error state.

The other host services are listed in the API below: setBusy, announce, searchOptions, adoptStyles and onDispose.

A complete control

The declaration is the control's reviewed plugin.json entry. It is kept in TypeScript as const, so the property, output and event types are derived from it.

import type { ControlDeclaration } from '@inflowai/control-sdk';

export const declaration = {
  controlKey: 'region-picker',
  displayName: 'Region picker',
  entry: 'control.js',
  properties: [
    { key: 'region', label: 'Region', valueType: { kind: 'ENUM', enumValues: ['north', 'south'], nullable: true },
      sourceModes: ['LITERAL', 'EXPRESSION', 'BINDING'] },
    { key: 'heading', label: 'Heading', valueType: { kind: 'TEXT', maxLength: 80 }, sourceModes: ['LITERAL', 'EXPRESSION'],
      restrictionReason: 'A heading is presentation text, never form data.' },
  ],
  outputs: [
    { key: 'region', label: 'Chosen region', valueType: { kind: 'ENUM', enumValues: ['north', 'south'], nullable: true },
      property: 'region' },
  ],
  events: [
    { key: 'confirmed', label: 'Region confirmed',
      payload: [{ name: 'region', valueType: { kind: 'ENUM', enumValues: ['north', 'south'] } }] },
  ],
} as const satisfies ControlDeclaration;
import { defineControl, type EventsOf, type OutputsOf, type PropertiesOf } from '@inflowai/control-sdk';
import { declaration } from './declaration.js';

type Props = PropertiesOf<typeof declaration>;
// The control's own copy of the current values, which it updates as changes arrive.
type Current = { -readonly [K in keyof Props]?: Props[K] };

export default defineControl<Props, OutputsOf<typeof declaration>, EventsOf<typeof declaration>>({
  controlKey: declaration.controlKey,
  mount(element, context) {
    const doc = element.ownerDocument;
    // Theme tokens are CSS custom-property references (for example `var(--ink)`): build the styles from them.
    const { spaceSmall = '8px', text = 'inherit' } = context.theme;
    context.host.adoptStyles(`.picker { display: flex; gap: ${spaceSmall}; color: ${text}; }`);
    const group = element.appendChild(doc.createElement('div'));
    group.className = 'picker';
    group.setAttribute('role', 'group');
    const heading = group.appendChild(doc.createElement('span'));
    // The current values and states. A key the host sends as `undefined` is withdrawn: its content is cleared, never kept.
    const values: Current = { ...context.properties };
    const states = { ...context.propertyStates };
    const buttons = (['north', 'south'] as const).map((region) => {
      const button = group.appendChild(doc.createElement('button'));
      button.type = 'button';
      button.textContent = region === 'north' ? 'North' : 'South';
      button.addEventListener('click', () => {
        const edit = context.host.setOutput('region', region);
        // A refused edit changed nothing: say so, and confirm nothing.
        if (!edit.accepted && edit.reason !== 'unchanged') {
          context.host.announce('The region could not be changed.');
          return;
        }
        const sent = context.host.emit('confirmed', { region });
        if (!sent.accepted) context.host.announce('The region was not confirmed.');
      }, { signal: context.host.signal });
      return { region, button };
    });
    const status = (key: keyof Props) => states[key]?.status ?? 'ready';
    const render = () => {
      // Only a ready property shows its value; any other state shows none.
      heading.textContent = status('heading') === 'ready' ? values.heading ?? '' : '';
      for (const { region, button } of buttons) {
        // Choosing stays possible in every state but loading: the host accepts a first or corrective choice for an
        // unset, empty or no-longer-offered value, and its HostResult says when it does not.
        button.disabled = status('region') === 'loading';
        button.setAttribute('aria-pressed', String(status('region') === 'ready' && values.region === region));
      }
      group.setAttribute('aria-label', heading.textContent || 'Region');
    };
    render();
    return {
      update(change) {
        // Own keys only: an omitted key is unchanged, a key present as `undefined` is withdrawn.
        for (const key of Object.keys(change.properties ?? {}) as (keyof Props)[]) values[key] = change.properties![key] as never;
        Object.assign(states, change.propertyStates ?? {});
        render();
      },
      dispose() { element.replaceChildren(); },
    };
  },
});

The manifest

This is the package's source plugin.json. The source never lists assets: the packaging tool (inflow-control package) computes them, with each asset's hash and size, from the build output.

{
  "id": "region-controls",
  "version": "1.0.0",
  "provider": "Example Org",
  "description": "A region picker for service forms.",
  "requires": "0.1.0",
  "dependencies": [],
  "capabilities": [],
  "interfaceControls": {
    "contractVersion": 1,
    "sdk": "^1.1.0",
    "controls": [
      {
        "controlKey": "region-picker",
        "displayName": "Region picker",
        "entry": "control.js",
        "properties": [
          { "key": "region", "label": "Region", "valueType": { "kind": "ENUM", "enumValues": ["north", "south"], "nullable": true },
            "sourceModes": ["LITERAL", "EXPRESSION", "BINDING"] },
          { "key": "heading", "label": "Heading", "valueType": { "kind": "TEXT", "maxLength": 80 }, "sourceModes": ["LITERAL", "EXPRESSION"],
            "restrictionReason": "A heading is presentation text, never form data." }
        ],
        "outputs": [
          { "key": "region", "label": "Chosen region", "valueType": { "kind": "ENUM", "enumValues": ["north", "south"], "nullable": true },
            "property": "region" }
        ],
        "events": [
          { "key": "confirmed", "label": "Region confirmed",
            "payload": [{ "name": "region", "valueType": { "kind": "ENUM", "enumValues": ["north", "south"] } }] }
        ]
      }
    ]
  }
}

Testing with the kit

The test kit is a mocked host. It is useful for development and CI, but passing it never shows that a control works on the platform. Only platform acceptance on a real server shows that.

import { MOCKED_BOUNDARY, mountForTest, runConformance } from '@inflowai/control-test-kit';
import control from './control.js';
import { declaration } from './declaration.js';

export async function check(): Promise<string[]> {
  const problems: string[] = [];
  const harness = await mountForTest(control, { declaration, properties: { region: 'north', heading: 'Region' } });
  const pressed = () => [...harness.element.querySelectorAll('button')].filter((b) => b.getAttribute('aria-pressed') === 'true').length;
  // Withdrawn values disappear, and come back on recovery.
  harness.update({ properties: { heading: undefined, region: undefined }, propertyStates: { heading: { status: 'error', reason: 'Unavailable.' }, region: { status: 'unavailable' } } });
  if (harness.element.textContent?.includes('Region') || pressed() > 0) problems.push('withdrawn values are still shown');
  harness.update({ properties: { heading: 'Region', region: 'south' }, propertyStates: { heading: { status: 'ready' }, region: { status: 'ready' } } });
  if (pressed() !== 1) problems.push('recovered values are not shown');
  harness.dispose();
  // A first or corrective choice is possible where the host accepts it: an unset binding and a no-longer-offered choice.
  for (const state of [{ status: 'unavailable' }, { status: 'invalid', reason: 'This choice is no longer offered.' }] as const) {
    const writable = await mountForTest(control, { declaration, properties: { heading: 'Region' }, propertyStates: { region: state } });
    const choice = [...writable.element.querySelectorAll('button')].find((b) => b.textContent === 'South')!;
    writable.interact(choice);
    choice.click();
    if (!writable.calls.some((call) => call.service === 'setOutput' && call.result?.accepted)) problems.push(`no choice could be made while ${state.status}`);
    writable.dispose();
  }
  // A refused edit confirms nothing: while the region is loading, the host refuses the edit.
  const loading = await mountForTest(control, { declaration, properties: { region: 'north', heading: 'Region' }, propertyStates: { region: { status: 'loading' } } });
  const south = [...loading.element.querySelectorAll('button')].find((b) => b.textContent === 'South')!;
  south.disabled = false; // as if a stale state let the click through
  loading.interact(south);
  south.click();
  if (loading.calls.some((call) => call.service === 'emit')) problems.push('a refused edit still emitted an event');
  loading.dispose();
  const report = await runConformance(control, declaration);
  problems.push(...report.checks.filter((c) => !c.passed).map((c) => `${c.id}: ${c.problems.join('; ')}`));
  return report.boundary === MOCKED_BOUNDARY ? problems : ['unexpected boundary'];
}

Limits

Limit Value Enforced by
Package archive (compressed) 5 MiB host admission (PluginArchiveValidator) and inflow-control package
Package expanded size 50 MiB host admission (PluginArchiveValidator) and inflow-control package
One archive entry 10 MiB host admission (PluginArchiveValidator) and inflow-control package
plugin.json 64 KiB host admission (PluginArchiveValidator) and inflow-control package
Archive entries 2048 host admission (PluginArchiveValidator) and inflow-control package
Compression ratio 100:1 host admission (PluginArchiveValidator) and inflow-control package
Event payload (serialized JSON) 16 KiB the host refuses a larger emit with invalid-value
Interaction window for emit 5000 ms after a real pointer or key input inside the control the host refuses an emit without one with suppressed
Record option page 50 items (hasMore signals more) host option reads
Option search debounce 250 ms host.searchOptions
Option read timeout 10000 ms, then an error option state host option reads

Declaration bounds (controls per package, properties per control, string lengths, list sizes) are in the manifest reference of docs/plugins/interface-controls/sdk-reference.md.

Refusal codes

Code When the host refuses
PLUGIN_HOST_VERSION_UNSUPPORTED The manifest's requires names a plugin platform version newer than this host.
PLUGIN_UI_ONLY_NOT_JVM A UI-only package was offered to an entry point that only understands Java plugins.
PLUGIN_UI_ONLY_NOT_RUNNABLE The plugin runner was asked to describe or load a UI-only package.
PLUGIN_CONTROL_CONTRACT_UNSUPPORTED The manifest names a control-contract version this host does not implement.
PLUGIN_CONTROL_SDK_UNSUPPORTED The manifest requires a browser SDK major version this host does not provide.
PLUGIN_CONTROLS_INVALID The section is schema-valid but internally inconsistent (duplicates, dangling references, conflicts).
PLUGIN_MANIFEST_INVALID plugin.json does not match the schema (an unknown field, a bound or a pattern).
PLUGIN_CONTROL_DEFAULT_INVALID A property's default does not fit its declared value type exactly as a literal: its canonical shape (INTEGER a JSON whole number; LONG and DECIMAL digits written as text), its declared facets or its nullability. Studio places the default as the property's literal source, so the package and the upload refuse it rather than every publication.

Value kinds a control may not declare: AUTO_NUMBER, BINARY. Canonical value kinds a control may not declare, each for a stated reason. AUTO_NUMBER is generated by the platform only, never authored by a control. BINARY has no bounded browser transport in contract version 1.

Reserved keys (never a property, output or event payload field, ignoring case): id, pluginId, pluginClass, provider, controlKey, version, digest, sha256, entry, assets, capabilities, permissions, contractVersion, sdk.

Licensing

Artifact License Notices
@inflowai/control-sdk UNLICENSED LICENSE and NOTICE ship inside the package
@inflowai/control-test-kit UNLICENSED LICENSE and NOTICE ship inside the package
@inflowai/control-tools UNLICENSED LICENSE and NOTICE ship inside the package

Each package also lists its third-party notices in NOTICE.

For a package you build, inflow-control package requires a package-lock.json (lockfile version 2 or 3). Every dependency that ships must:

  • resolve from the public registry;
  • declare a license;
  • be listed in your THIRD-PARTY-NOTICES.md.

Your LICENSE, NOTICE, THIRD-PARTY-NOTICES.md and README.md are packaged when present.

Trust

Trust: controls are trusted browser code that a plugin administrator verified and uploaded (an upload is live at once; there is no approval step). They run with the browser privileges of the page that hosts them. This typed API is a contract, not a sandbox. It deliberately offers no network, credential, session or storage capability: everything a control may do to the platform goes through HostServices, and the host re-checks current authority for every effect.

This typed contract is not a sandbox. The host keeps adopted styles visually contained and re-authorizes every effect at its service boundary. It cannot undo third-party requests or browser actions that trusted code has already made. Untrusted code and a public marketplace are out of scope for this release.

Manifest reference

Generated from tools/interface-control-plugins/schema/plugin-manifest.schema.json. The host, the packaging tool and Studio all validate against this schema, so these bounds are exactly what admission enforces.

Schema fingerprint (SHA-256 of its text without insignificant whitespace): 81689defbd99a0684edc3bc3749d959b88c8eccc1daaf563fda87460d3d4b2b3. Any change to the schema changes it, so the reference must be regenerated with the schema.

plugin.json (fields used by control packages)

Field Type Required Bounds Meaning
id string yes max length 100; pattern ^[a-z0-9\-]+$ A stable lowercase alphanumeric slug with hyphens.
version string yes max length 64; pattern ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ Semantic versioning representation.
provider string yes min length 1; max length 200
description string no max length 2000
requires string yes pattern ^[0-9]+\.[0-9]+\.[0-9]+$ Minimum platform/SDK version required by the plugin.
pluginClass string no pattern ^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$ Fully qualified class name of the plugin wrapper.
dependencies array of string yes max items 100; unique items; each: min length 1; max length 200
capabilities array of string yes max items 100; unique items; each: pattern ^[a-z][a-z0-9._-]{0,99}$
interfaceControls interfaceControls no

A package must declare at least one of pluginClass or interfaceControls.

When pluginClass is absent, processNode and hostFunctions must be absent. SCRUM-4847: a package without a Java plugin class (UI-only) cannot declare server-side sections.

The manifest also accepts hostFunctions and processNode: server-side sections of a package with a Java plugin, not part of an interface-control declaration, so they are not listed above.

No other fields are accepted.

interfaceControls

SCRUM-4846: browser interface controls this package contributes (contract version 1). With no pluginClass the package is UI-only and carries no Java; with one it is mixed. Every declaration here is reviewed by an administrator and requests nothing: controls, events and providers grant no permission. First release admits reviewed trusted browser code only; this typed contract is not a sandbox.

Field Type Required Bounds Meaning
contractVersion integer yes minimum 1; maximum 1000 Control-contract version. The host refuses versions it does not implement.
sdk string yes pattern ^\^(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})$ Caret range of the browser companion SDK the controls were built against, e.g. ^1.0.0.
controls array of interfaceControl yes min items 1; max items 50
assets array of controlAsset yes min items 1; max items 2048
providers array of controlProvider no max items 20

No other fields are accepted.

interfaceControl

Field Type Required Bounds Meaning
controlKey string yes pattern ^[a-z][a-z0-9-]{0,63}$ Stable machine key, unique within the package. Never derived from an expression.
displayName string yes min length 1; max length 120
description string no max length 1000
icon controlRelativePath no
category string no min length 1; max length 80
entry controlRelativePath yes Relative path of the declared JavaScript module asset the host loads. Never derived from an expression.
properties array of controlProperty no max items 100
outputs array of controlOutput no max items 50
events array of controlEvent no max items 50

No other fields are accepted.

controlProperty

Field Type Required Bounds Meaning
key string yes pattern ^[a-z][A-Za-z0-9]{0,63}$; reserved: id, pluginId, pluginClass, provider, controlKey, version, digest, sha256, entry, assets, capabilities, permissions, contractVersion, sdk Stable property key. Package identity and authority facts are reserved and can never be properties.
label string yes min length 1; max length 120
description string no max length 1000
group string no min length 1; max length 80
valueType controlValueType yes
sourceModes array of LITERAL · EXPRESSION · BINDING yes min items 1; max items 3; unique items; each: one of LITERAL · EXPRESSION · BINDING
restrictionReason string no min length 1; max length 300; pattern \S Why fewer than all source modes are allowed. Required whenever the property is restricted.
default any JSON value no Literal default, placed as the property's literal source when the control is added. It must fit valueType exactly as a literal: canonical shape (INTEGER a JSON whole number; LONG and DECIMAL digits written as text), declared facets and nullability. Packaging and upload refuse a default that does not fit with PLUGIN_CONTROL_DEFAULT_INVALID (SCRUM-5076).
readOnly boolean no A computed input the control displays but never writes.
dynamicOptions array of EXPRESSION · DATA_SOURCE no min items 1; max items 2; unique items; each: one of EXPRESSION · DATA_SOURCE Where the option list of a choice property may come from besides its declared enumValues.
labels controlLocalizedText no Localized labels by BCP-47 tag (SCRUM-4858).
memberLabels object no max properties 500; keys: min length 1; max length 200; values: string; min length 1; max length 200 Display labels of an ENUM property's members, by member value (SCRUM-4861). The member stays the stored and delivered value; a label never replaces one. Keys must be declared enumValues.
memberLabelsByLocale object no max properties 40; keys: controlLocaleTag; values: object; max properties 500; keys: min length 1; max length 200; values: string; min length 1; max length 200 Localized member labels by BCP-47 tag, then member value (SCRUM-4861).
descriptions controlLocalizedDescription no Localized descriptions by BCP-47 tag (SCRUM-4858).
visibleWhen object no Declarative designer condition (SCRUM-4858): show this property only while another declared property's literal value is one of in. Never an expression.
visibleWhen.property string yes pattern ^[a-z][A-Za-z0-9]{0,63}$
visibleWhen.in array of string or number or boolean yes min items 1; max items 50
visibleWhen.… — — no other fields

When sourceModes has max items 2 (and sourceModes is present), restrictionReason is required.

No other fields are accepted.

controlOutput

Field Type Required Bounds Meaning
key string yes pattern ^[a-z][A-Za-z0-9]{0,63}$
label string yes min length 1; max length 120
valueType controlValueType yes
property string yes pattern ^[a-z][A-Za-z0-9]{0,63}$ The editable property this output writes back to.

No other fields are accepted.

controlEvent

Field Type Required Bounds Meaning
key string yes pattern ^[a-z][A-Za-z0-9]{0,63}$
label string yes min length 1; max length 120
description string no max length 1000
payload array of object no max items 30
payload[].name string yes pattern ^[a-z][A-Za-z0-9]{0,63}$
payload[].valueType controlValueType yes
payload[].… — — no other fields

No other fields are accepted.

controlLocalizedText

Type: object; max properties 40; keys: pattern ^(([A-Za-z]{2,3}(-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8})(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+)*(-[Xx](-[A-Za-z0-9]{1,8})+)?|[Xx](-[A-Za-z0-9]{1,8})+|[Cc][Ee][Ll]\-[Gg][Aa][Uu][Ll][Ii][Ss][Hh]|[Ii]\-[Ee][Nn][Oo][Cc][Hh][Ii][Aa][Nn]|[Aa][Rr][Tt]\-[Ll][Oo][Jj][Bb][Aa][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]\-[Nn][Aa][Nn]|[Ee][Nn]\-[Gg][Bb]\-[Oo][Ee][Dd]|[Ii]\-[Dd][Ee][Ff][Aa][Uu][Ll][Tt]|[Ii]\-[Kk][Ll][Ii][Nn][Gg][Oo][Nn]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Ff][Rr]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Nn][Ll]|[Ss][Gg][Nn]\-[Cc][Hh]\-[Dd][Ee]|[Ii]\-[Nn][Aa][Vv][Aa][Jj][Oo]|[Zz][Hh]\-[Gg][Uu][Oo][Yy][Uu]|[Zz][Hh]\-[Hh][Aa][Kk][Kk][Aa]|[Zz][Hh]\-[Xx][Ii][Aa][Nn][Gg]|[Ii]\-[Mm][Ii][Nn][Gg][Oo]|[Nn][Oo]\-[Bb][Oo][Kk]|[Nn][Oo]\-[Nn][Yy][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]|[Ii]\-[Aa][Mm][Ii]|[Ii]\-[Bb][Nn][Nn]|[Ii]\-[Hh][Aa][Kk]|[Ii]\-[Ll][Uu][Xx]|[Ii]\-[Pp][Ww][Nn]|[Ii]\-[Tt][Aa][Oo]|[Ii]\-[Tt][Aa][Yy]|[Ii]\-[Tt][Ss][Uu])$; values: string; min length 1; max length 120.

Keys: pattern ^(([A-Za-z]{2,3}(-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8})(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+)*(-[Xx](-[A-Za-z0-9]{1,8})+)?|[Xx](-[A-Za-z0-9]{1,8})+|[Cc][Ee][Ll]\-[Gg][Aa][Uu][Ll][Ii][Ss][Hh]|[Ii]\-[Ee][Nn][Oo][Cc][Hh][Ii][Aa][Nn]|[Aa][Rr][Tt]\-[Ll][Oo][Jj][Bb][Aa][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]\-[Nn][Aa][Nn]|[Ee][Nn]\-[Gg][Bb]\-[Oo][Ee][Dd]|[Ii]\-[Dd][Ee][Ff][Aa][Uu][Ll][Tt]|[Ii]\-[Kk][Ll][Ii][Nn][Gg][Oo][Nn]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Ff][Rr]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Nn][Ll]|[Ss][Gg][Nn]\-[Cc][Hh]\-[Dd][Ee]|[Ii]\-[Nn][Aa][Vv][Aa][Jj][Oo]|[Zz][Hh]\-[Gg][Uu][Oo][Yy][Uu]|[Zz][Hh]\-[Hh][Aa][Kk][Kk][Aa]|[Zz][Hh]\-[Xx][Ii][Aa][Nn][Gg]|[Ii]\-[Mm][Ii][Nn][Gg][Oo]|[Nn][Oo]\-[Bb][Oo][Kk]|[Nn][Oo]\-[Nn][Yy][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]|[Ii]\-[Aa][Mm][Ii]|[Ii]\-[Bb][Nn][Nn]|[Ii]\-[Hh][Aa][Kk]|[Ii]\-[Ll][Uu][Xx]|[Ii]\-[Pp][Ww][Nn]|[Ii]\-[Tt][Aa][Oo]|[Ii]\-[Tt][Aa][Yy]|[Ii]\-[Tt][Ss][Uu])$.

Values: string; min length 1; max length 120.

controlLocalizedDescription

Type: object; max properties 40; keys: pattern ^(([A-Za-z]{2,3}(-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8})(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+)*(-[Xx](-[A-Za-z0-9]{1,8})+)?|[Xx](-[A-Za-z0-9]{1,8})+|[Cc][Ee][Ll]\-[Gg][Aa][Uu][Ll][Ii][Ss][Hh]|[Ii]\-[Ee][Nn][Oo][Cc][Hh][Ii][Aa][Nn]|[Aa][Rr][Tt]\-[Ll][Oo][Jj][Bb][Aa][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]\-[Nn][Aa][Nn]|[Ee][Nn]\-[Gg][Bb]\-[Oo][Ee][Dd]|[Ii]\-[Dd][Ee][Ff][Aa][Uu][Ll][Tt]|[Ii]\-[Kk][Ll][Ii][Nn][Gg][Oo][Nn]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Ff][Rr]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Nn][Ll]|[Ss][Gg][Nn]\-[Cc][Hh]\-[Dd][Ee]|[Ii]\-[Nn][Aa][Vv][Aa][Jj][Oo]|[Zz][Hh]\-[Gg][Uu][Oo][Yy][Uu]|[Zz][Hh]\-[Hh][Aa][Kk][Kk][Aa]|[Zz][Hh]\-[Xx][Ii][Aa][Nn][Gg]|[Ii]\-[Mm][Ii][Nn][Gg][Oo]|[Nn][Oo]\-[Bb][Oo][Kk]|[Nn][Oo]\-[Nn][Yy][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]|[Ii]\-[Aa][Mm][Ii]|[Ii]\-[Bb][Nn][Nn]|[Ii]\-[Hh][Aa][Kk]|[Ii]\-[Ll][Uu][Xx]|[Ii]\-[Pp][Ww][Nn]|[Ii]\-[Tt][Aa][Oo]|[Ii]\-[Tt][Aa][Yy]|[Ii]\-[Tt][Ss][Uu])$; values: string; min length 1; max length 1000.

Keys: pattern ^(([A-Za-z]{2,3}(-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8})(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+)*(-[Xx](-[A-Za-z0-9]{1,8})+)?|[Xx](-[A-Za-z0-9]{1,8})+|[Cc][Ee][Ll]\-[Gg][Aa][Uu][Ll][Ii][Ss][Hh]|[Ii]\-[Ee][Nn][Oo][Cc][Hh][Ii][Aa][Nn]|[Aa][Rr][Tt]\-[Ll][Oo][Jj][Bb][Aa][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]\-[Nn][Aa][Nn]|[Ee][Nn]\-[Gg][Bb]\-[Oo][Ee][Dd]|[Ii]\-[Dd][Ee][Ff][Aa][Uu][Ll][Tt]|[Ii]\-[Kk][Ll][Ii][Nn][Gg][Oo][Nn]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Ff][Rr]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Nn][Ll]|[Ss][Gg][Nn]\-[Cc][Hh]\-[Dd][Ee]|[Ii]\-[Nn][Aa][Vv][Aa][Jj][Oo]|[Zz][Hh]\-[Gg][Uu][Oo][Yy][Uu]|[Zz][Hh]\-[Hh][Aa][Kk][Kk][Aa]|[Zz][Hh]\-[Xx][Ii][Aa][Nn][Gg]|[Ii]\-[Mm][Ii][Nn][Gg][Oo]|[Nn][Oo]\-[Bb][Oo][Kk]|[Nn][Oo]\-[Nn][Yy][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]|[Ii]\-[Aa][Mm][Ii]|[Ii]\-[Bb][Nn][Nn]|[Ii]\-[Hh][Aa][Kk]|[Ii]\-[Ll][Uu][Xx]|[Ii]\-[Pp][Ww][Nn]|[Ii]\-[Tt][Aa][Oo]|[Ii]\-[Tt][Aa][Yy]|[Ii]\-[Tt][Ss][Uu])$.

Values: string; min length 1; max length 1000.

controlLocaleTag

A well-formed BCP-47 (RFC 5646) language tag; repeated variants and singletons are refused by the validator.

Type: any JSON value; pattern ^(([A-Za-z]{2,3}(-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8})(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+)*(-[Xx](-[A-Za-z0-9]{1,8})+)?|[Xx](-[A-Za-z0-9]{1,8})+|[Cc][Ee][Ll]\-[Gg][Aa][Uu][Ll][Ii][Ss][Hh]|[Ii]\-[Ee][Nn][Oo][Cc][Hh][Ii][Aa][Nn]|[Aa][Rr][Tt]\-[Ll][Oo][Jj][Bb][Aa][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]\-[Nn][Aa][Nn]|[Ee][Nn]\-[Gg][Bb]\-[Oo][Ee][Dd]|[Ii]\-[Dd][Ee][Ff][Aa][Uu][Ll][Tt]|[Ii]\-[Kk][Ll][Ii][Nn][Gg][Oo][Nn]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Ff][Rr]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Nn][Ll]|[Ss][Gg][Nn]\-[Cc][Hh]\-[Dd][Ee]|[Ii]\-[Nn][Aa][Vv][Aa][Jj][Oo]|[Zz][Hh]\-[Gg][Uu][Oo][Yy][Uu]|[Zz][Hh]\-[Hh][Aa][Kk][Kk][Aa]|[Zz][Hh]\-[Xx][Ii][Aa][Nn][Gg]|[Ii]\-[Mm][Ii][Nn][Gg][Oo]|[Nn][Oo]\-[Bb][Oo][Kk]|[Nn][Oo]\-[Nn][Yy][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]|[Ii]\-[Aa][Mm][Ii]|[Ii]\-[Bb][Nn][Nn]|[Ii]\-[Hh][Aa][Kk]|[Ii]\-[Ll][Uu][Xx]|[Ii]\-[Pp][Ww][Nn]|[Ii]\-[Tt][Aa][Oo]|[Ii]\-[Tt][Aa][Yy]|[Ii]\-[Tt][Ss][Uu])$.

controlValueType

The canonical platform value-type descriptor (spec 489 contracts/value-types.md). AUTO_NUMBER and BINARY are excluded for controls (InterfaceControlContract.EXCLUDED_VALUE_KINDS).

Field Type Required Bounds Meaning
kind TEXT · INTEGER · LONG · DECIMAL · BOOLEAN · DATE · TIME · LOCAL_DATETIME · INSTANT · UUID · JSON · ENUM · DOCUMENT · USER · GROUP · FOLDER · CABINET · LIFECYCLE_REF · FUNCTION_REF · RECORD · RECORD_REF yes
cardinality ONE · MANY no
nullable boolean no
itemNullable boolean no
schemaRef string no min length 1; max length 512
enumValues array of string no max items 500; unique items; each: min length 1; max length 200
minLength integer no minimum 0
maxLength integer no minimum 0
minItems integer no minimum 0
maxItems integer no minimum 0
minInclusive string no max length 64
maxInclusive string no max length 64
precision integer no minimum 1; maximum 1000
scale integer no minimum 0; maximum 1000
referenceMode PRESERVE · CURRENT · PINNED no

When kind is RECORD or RECORD_REF (and kind is present), schemaRef is required.

No other fields are accepted.

controlAsset

Field Type Required Bounds Meaning
path controlRelativePath yes
contentType text/javascript · text/css · application/json · application/source-map · image/png · image/svg+xml · font/woff2 yes
sha256 string yes pattern ^[0-9a-f]{64}$
size integer yes minimum 0; maximum 10485760

No other fields are accepted.

controlProvider

An external service the controls call from the browser. Declared for review and environment configuration; it grants nothing.

Field Type Required Bounds Meaning
key string yes pattern ^[a-z][a-z0-9-]{0,63}$
purpose string yes min length 1; max length 300
origins array of string yes min items 1; max items 20; unique items; each: pattern ^https://([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]([a-z0-9-]{0,61}[a-z0-9])?(:([1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?$
dataCategories array of none · location · address · personal-name · contact · record-identifier · free-text · usage no max items 8; unique items; each: one of none · location · address · personal-name · contact · record-identifier · free-text · usage What the provider receives from the browser, disclosed at review (SCRUM-4871).
configuration array of providerConfiguration no max items 10 Environment configuration the provider needs. browserPublic values are intentionally visible in the browser (a restricted key, a map id); serverSecret values are stored only as vault references and never reach the browser (SCRUM-4871).

No other fields are accepted.

providerConfiguration

Field Type Required Bounds Meaning
key string yes pattern ^[a-z][a-zA-Z0-9]{0,63}$
classification browserPublic · serverSecret yes
label string yes min length 1; max length 120
required boolean no

No other fields are accepted.

controlRelativePath

A relative archive path: no leading slash, no scheme, no backslash and no '.' or '..' segment.

Type: string; pattern ^[A-Za-z0-9_-][A-Za-z0-9._-]{0,127}(/[A-Za-z0-9_-][A-Za-z0-9._-]{0,127}){0,15}$.

SDK API: @inflowai/control-sdk

Generated from inflow-control-sdk/api/control-sdk.api.d.ts, the reviewed public API of @inflowai/control-sdk. Every export is listed.

Export Kind Module
CONTROL_ABI_VERSION const abi
CONTROL_CONTRACT_VERSION const abi
ControlMode type abi
TextDirection type abi
PropertyState type abi
ThemeTokens interface abi
Size interface abi
HostResult type abi
HostRefusal type abi
ControlError interface abi
HostServices interface abi
ControlContext interface abi
ControlUpdate interface abi
ControlInstance interface abi
ControlModule interface abi
ControlDefinition interface abi
defineControl function abi
ControlModuleProblem type abi
checkControlModule function abi
VALUE_KINDS const declaration
ValueKind type declaration
SOURCE_MODES const declaration
SourceMode type declaration
ValueTypeDeclaration interface declaration
PropertyDeclaration interface declaration
OutputDeclaration interface declaration
EventFieldDeclaration interface declaration
EventDeclaration interface declaration
ControlDeclaration interface declaration
JsonValue type declaration
DocumentReference interface declaration
UserReference interface declaration
GroupReference interface declaration
FolderReference interface declaration
CabinetReference interface declaration
LifecycleReference interface declaration
FunctionReference interface declaration
RecordReference interface declaration
RecordValue type declaration
ScalarValueOf type declaration
ValueOf type declaration
PropertiesOf type declaration
OutputsOf type declaration
PayloadOf type declaration
EventsOf type declaration

CONTROL_ABI_VERSION

The lifecycle ABI version this SDK implements. A host refuses modules built for a different ABI.

export declare const CONTROL_ABI_VERSION: 1;

CONTROL_CONTRACT_VERSION

The control-contract version (interfaceControls.contractVersion in plugin.json) this SDK targets.

export declare const CONTROL_CONTRACT_VERSION: 1;

ControlMode

Where the control is running. Design and preview supply synthetic data and suppress business effects.

export type ControlMode = 'design' | 'preview' | 'runtime';

TextDirection

Layout direction of the surrounding interface. Controls must mirror horizontally for rtl.

export type TextDirection = 'ltr' | 'rtl';

PropertyState

Resolution state of one property. invalid and error carry a reason a person can act on. The control renders the shared unavailable state rather than guessing a value.

export type PropertyState = {
    readonly status: 'ready';
} | {
    readonly status: 'loading';
} | {
    readonly status: 'empty';
} | {
    readonly status: 'invalid';
    readonly reason: string;
} | {
    readonly status: 'error';
    readonly reason: string;
} | {
    readonly status: 'unavailable';
};

ThemeTokens

Design tokens the control should use instead of raw colours, so it follows the interface theme. The keys are the platform's public token vocabulary (surface, surfaceRaised, text, textMuted, border, accent, danger, warning, radius, spaceSmall, ...); the values are CSS custom-property references (for example var(--surface)), never literal colours. Light and dark deliver the same references: the page redefines the variables.

export interface ThemeTokens {
    readonly [token: string]: string;
}

Size

A pixel size of the host element.

export interface Size {
    readonly width: number;
    readonly height: number;
}

HostResult

Outcome of a request the host may refuse. The control must not assume success.

export type HostResult = {
    readonly accepted: true;
} | {
    readonly accepted: false;
    readonly reason: HostRefusal;
};

HostRefusal

Why the host refused. not-ready: the instance is loading, hidden, frozen or disposed. not-declared: the key is not in the reviewed declaration. invalid-value: the value does not match the declared type. suppressed: design/preview mode never performs business effects. unchanged: an output equal to the current value is not an edit (echo guard).

export type HostRefusal = 'not-ready' | 'not-declared' | 'invalid-value' | 'suppressed' | 'unchanged';

ControlError

A failure the control reports so the host can show the shared error state. Never include secrets or payloads.

export interface ControlError {
    readonly code: string;
    readonly message: string;
}

HostServices

What the host lets a control do. Every effect is validated by the host against the reviewed declaration and the instance's current lifetime, and every business effect is re-authorized by the platform at its service boundary.

export interface HostServices<Outputs = Record<string, unknown>, Events = Record<string, unknown>> {
    /**
     * Proposes a user edit of a declared editable output. The host validates it and places it in the interface's
     * existing draft (dirty/validation/save/cancel). It never persists anything by itself. Call only for genuine user
     * interaction, never to mirror a value the host just pushed.
     */
    setOutput<K extends keyof Outputs & string>(key: K, value: Outputs[K]): HostResult;
    /**
     * Emits a declared event from a genuine user interaction. The host routes it to the actions the interface author
     * configured. Mounting, rendering and refreshing must never emit events.
     */
    emit<K extends keyof Events & string>(event: K, payload: Events[K]): HostResult;
    /** Reports a failure; the host shows the shared error state and keeps the authored configuration. */
    reportError(error: ControlError): void;
    /** Marks the control busy (for example while a provider library loads) so the host can show a loading state. */
    setBusy(busy: boolean): void;
    /** Announces a short message to assistive technology through the host's live region. */
    announce(message: string): void;
    /**
     * Asks for the choices of a property whose options the server searches (SCRUM-4862), narrowed by `text` (at most 160
     * characters; empty text asks for the first page). The host debounces, bounds and authorizes the read and delivers
     * the result through {@link ControlInstance.update} as that property's `options`. `not-declared` when that
     * property's choices are not searched on the server; `invalid-value` when `text` is not short text.
     */
    searchOptions(key: string, text: string): HostResult;
    /**
     * Adopts the control's own CSS (T020). The host scopes it to this instance's root element with `@scope`, so it styles
     * nothing else on the page, and removes it when the instance is disposed. A new call replaces the previous sheet. At
     * most 64 KiB; anything else is `invalid-value`. Use theme tokens (`context.theme`) rather than literal colours. This is
     * visual containment for trusted code, not a security sandbox: never inject global styles yourself.
     */
    adoptStyles(css: string): HostResult;
    /** Registers a cleanup run exactly once at dispose, in reverse registration order. */
    onDispose(cleanup: () => void): void;
    /** Aborted when the instance is disposed or replaced. Pass it to every timer, listener and request. */
    readonly signal: AbortSignal;
}

ControlContext

Everything the host gives an instance at mount.

export interface ControlContext<Properties = Record<string, unknown>, Outputs = Record<string, unknown>, Events = Record<string, unknown>> {
    /** Stable for the instance's lifetime; distinct for every placed instance, even of the same control. */
    readonly instanceId: string;
    /** Resolved, typed property values. Never expression source text. */
    readonly properties: Readonly<Properties>;
    /** Per-property resolution state. */
    readonly propertyStates: Readonly<Record<keyof Properties & string, PropertyState>>;
    readonly mode: ControlMode;
    readonly locale: string;
    readonly direction: TextDirection;
    readonly theme: ThemeTokens;
    /** Browser-public environment configuration an administrator saved for this package's providers (never secrets). */
    readonly configuration: Readonly<Record<string, string>>;
    /**
     * The keys of the reviewed providers an administrator admitted for real loading in this environment (SCRUM-4871). A
     * control loads a provider only when its key is listed here, whether or not it has configuration values; empty in
     * design and preview, and whenever loading is not admitted (the control shows its offline alternative).
     */
    readonly providers?: readonly string[];
    /** Dynamic option lists by property key, for properties that declare `dynamicOptions` and are configured with one. */
    readonly options?: Readonly<Record<string, PropertyOptions>>;
    readonly size: Size;
    readonly host: HostServices<Outputs, Events>;
}

ControlUpdate

A change the host pushes to a mounted instance. Only changed parts are present.

export interface ControlUpdate<Properties = Record<string, unknown>> {
    readonly properties?: Readonly<Partial<Properties>>;
    readonly propertyStates?: Readonly<Partial<Record<keyof Properties & string, PropertyState>>>;
    readonly options?: Readonly<Record<string, PropertyOptions>>;
    readonly direction?: TextDirection;
    readonly locale?: string;
    readonly theme?: ThemeTokens;
}

ControlInstance

A mounted control instance.

export interface ControlInstance<Properties = Record<string, unknown>> {
    /** Applies pushed changes. Must not emit events or outputs as a result. */
    update(update: ControlUpdate<Properties>): void;
    /** Reacts to a size change of the host element. */
    resize?(size: Size): void;
    /**
     * Releases everything: listeners, timers, provider objects, DOM. Must be idempotent. After dispose the host ignores
     * every call the instance makes.
     */
    dispose(): void;
}

ControlModule

What a control module exports. Build it with defineControl.

export interface ControlModule<Properties = Record<string, unknown>, Outputs = Record<string, unknown>, Events = Record<string, unknown>> {
    readonly abi: typeof CONTROL_ABI_VERSION;
    /** Must equal the `controlKey` of the control's reviewed declaration in plugin.json. */
    readonly controlKey: string;
    mount(element: HTMLElement, context: ControlContext<Properties, Outputs, Events>): ControlInstance<Properties> | Promise<ControlInstance<Properties>>;
}

ControlDefinition

The definition passed to defineControl.

export interface ControlDefinition<Properties, Outputs, Events> {
    readonly controlKey: string;
    mount(element: HTMLElement, context: ControlContext<Properties, Outputs, Events>): ControlInstance<Properties> | Promise<ControlInstance<Properties>>;
}

defineControl

Defines a control module. Use it as the module's default export:

export default defineControl<Props, Outputs, Events>({ controlKey: 'service-visits-map', mount(element, ctx) { ... } });
export declare function defineControl<Properties = Record<string, unknown>, Outputs = Record<string, unknown>, Events = Record<string, unknown>>(definition: ControlDefinition<Properties, Outputs, Events>): ControlModule<Properties, Outputs, Events>;

ControlModuleProblem

Why a value is not a usable control module for this ABI.

export type ControlModuleProblem = 'not-an-object' | 'abi-mismatch' | 'bad-control-key' | 'no-mount' | 'key-mismatch';

checkControlModule

Checks a loaded module's default export against this ABI without calling it. Hosts and tools use it before mount.

@param expectedControlKey the reviewed declaration's control key, when known

export declare function checkControlModule(candidate: unknown, expectedControlKey?: string): {
    readonly ok: true;
    readonly module: ControlModule;
} | {
    readonly ok: false;
    readonly problem: ControlModuleProblem;
};

VALUE_KINDS

The canonical platform value kinds a control may declare (AUTO_NUMBER and BINARY are excluded for controls). The package's tests pin this list to the host schema.

export declare const VALUE_KINDS: readonly ["TEXT", "INTEGER", "LONG", "DECIMAL", "BOOLEAN", "DATE", "TIME", "LOCAL_DATETIME", "INSTANT", "UUID", "JSON", "ENUM", "DOCUMENT", "USER", "GROUP", "FOLDER", "CABINET", "LIFECYCLE_REF", "FUNCTION_REF", "RECORD", "RECORD_REF"];

ValueKind

One of VALUE_KINDS: the valueType.kind of a declared property, output or event field.

export type ValueKind = (typeof VALUE_KINDS)[number];

SOURCE_MODES

Where a property value may come from.

export declare const SOURCE_MODES: readonly ["LITERAL", "EXPRESSION", "BINDING"];

SourceMode

One of SOURCE_MODES: a typed literal, an expression the host evaluates, or a binding to form data.

export type SourceMode = (typeof SOURCE_MODES)[number];

ValueTypeDeclaration

The canonical platform value type of a property, output or event field (valueType in plugin.json). Facets (lengths, item counts, inclusive bounds, precision and scale) are enforced by the host before a value reaches the control and when the control proposes one. schemaRef is required for RECORD and RECORD_REF.

export interface ValueTypeDeclaration {
    readonly kind: ValueKind;
    readonly cardinality?: 'ONE' | 'MANY';
    readonly nullable?: boolean;
    readonly itemNullable?: boolean;
    readonly schemaRef?: string;
    readonly enumValues?: readonly string[];
    readonly minLength?: number;
    readonly maxLength?: number;
    readonly minItems?: number;
    readonly maxItems?: number;
    readonly minInclusive?: string;
    readonly maxInclusive?: string;
    readonly precision?: number;
    readonly scale?: number;
    readonly referenceMode?: 'PRESERVE' | 'CURRENT' | 'PINNED';
}

PropertyDeclaration

One designer property of a control. The interface author supplies its value as a literal, an expression or a binding (only the declared sourceModes; restricting them requires a restrictionReason). The control receives the resolved, typed value in context.properties[key], never expression text.

export interface PropertyDeclaration {
    readonly key: string;
    readonly label: string;
    readonly description?: string;
    readonly group?: string;
    readonly valueType: ValueTypeDeclaration;
    readonly sourceModes: readonly SourceMode[];
    readonly restrictionReason?: string;
    readonly default?: unknown;
    readonly readOnly?: boolean;
    readonly dynamicOptions?: readonly ('EXPRESSION' | 'DATA_SOURCE')[];
    /** Localized labels and descriptions by BCP-47 tag (for example `ar`, `en-GB`). */
    readonly labels?: Readonly<Record<string, string>>;
    /** Display labels of an ENUM property's members, by member value. The member, never its label, is what a control receives. */
    readonly memberLabels?: Readonly<Record<string, string>>;
    /** Localized member labels by BCP-47 tag, then member value. */
    readonly memberLabelsByLocale?: Readonly<Record<string, Readonly<Record<string, string>>>>;
    readonly descriptions?: Readonly<Record<string, string>>;
    /** Show this property in the designer only while another declared property's literal value is one of `in`. */
    readonly visibleWhen?: {
        readonly property: string;
        readonly in: readonly (string | number | boolean)[];
    };
}

OutputDeclaration

An editable value the control may propose with host.setOutput(key, value). It writes back to the declared property only when that property is bound to form data; the edit lands in the interface's draft, never saved by the control.

export interface OutputDeclaration {
    readonly key: string;
    readonly label: string;
    readonly valueType: ValueTypeDeclaration;
    /** The editable property this output writes back to. */
    readonly property: string;
}

EventFieldDeclaration

One typed field of an event payload. Payload field names may not use reserved keys.

export interface EventFieldDeclaration {
    readonly name: string;
    readonly valueType: ValueTypeDeclaration;
}

EventDeclaration

A user interaction the control may report with host.emit(key, payload). The interface author decides which actions run for it; they run with the current user's authority.

export interface EventDeclaration {
    readonly key: string;
    readonly label: string;
    readonly description?: string;
    readonly payload?: readonly EventFieldDeclaration[];
}

ControlDeclaration

One control of a package (an entry of interfaceControls.controls). controlKey is the stable machine key and entry the declared JavaScript module asset the host loads. Declare it as const to derive typed properties, outputs and events.

export interface ControlDeclaration {
    readonly controlKey: string;
    readonly displayName: string;
    readonly description?: string;
    readonly icon?: string;
    readonly category?: string;
    readonly entry: string;
    readonly properties?: readonly PropertyDeclaration[];
    readonly outputs?: readonly OutputDeclaration[];
    readonly events?: readonly EventDeclaration[];
}

JsonValue

Any JSON value (the JSON kind is explicitly untyped and never a reference authority).

export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
    readonly [key: string]: JsonValue;
};

DocumentReference

A reference to a document, optionally a version (DOCUMENT values). References match the platform's reference JSON objects.

export interface DocumentReference {
    readonly kind: 'document';
    readonly documentId: string;
    readonly versionNumber?: number;
    readonly name?: string;
    readonly mimeType?: string;
    readonly sizeBytes?: number;
}

UserReference

A reference to a platform user (USER values).

export interface UserReference {
    readonly kind: 'user';
    readonly userId: string;
}

GroupReference

A reference to a platform group (GROUP values).

export interface GroupReference {
    readonly kind: 'group';
    readonly groupId: string;
}

FolderReference

A reference to a folder (FOLDER values).

export interface FolderReference {
    readonly kind: 'folder';
    readonly folderId: string;
}

CabinetReference

A reference to a cabinet (CABINET values).

export interface CabinetReference {
    readonly kind: 'cabinet';
    readonly cabinetId: string;
}

LifecycleReference

A reference to a lifecycle definition, optionally pinned to a version (LIFECYCLE_REF values).

export interface LifecycleReference {
    readonly kind: 'lifecycle';
    readonly key: string;
    readonly version?: number;
}

FunctionReference

A reference to a platform function, optionally pinned to a version (FUNCTION_REF values).

export interface FunctionReference {
    readonly kind: 'function';
    readonly key: string;
    readonly version?: number;
}

RecordReference

A reference to a record of the declared schemaRef (RECORD_REF values).

export interface RecordReference {
    readonly kind: 'record';
    readonly schemaRef: string;
    readonly recordId: string;
}

RecordValue

A record value: an object validated by the host against the declared schemaRef.

export type RecordValue = {
    readonly [field: string]: JsonValue | RecordValue | readonly RecordValue[];
};

ScalarValueOf

The single (ONE) value type of a declared kind. LONG and DECIMAL arrive as canonical text, never as JS numbers, so no precision is lost; temporal kinds arrive as ISO text.

export type ScalarValueOf<T extends ValueTypeDeclaration> = T['kind'] extends 'TEXT' | 'LONG' | 'DECIMAL' | 'DATE' | 'TIME' | 'LOCAL_DATETIME' | 'INSTANT' | 'UUID' ? string : T['kind'] extends 'INTEGER' ? number : T['kind'] extends 'BOOLEAN' ? boolean : T['kind'] extends 'JSON' ? JsonValue : T['kind'] extends 'ENUM' ? (T['enumValues'] extends readonly (infer Member)[] ? Member : string) : T['kind'] extends 'DOCUMENT' ? DocumentReference : T['kind'] extends 'USER' ? UserReference : T['kind'] extends 'GROUP' ? GroupReference : T['kind'] extends 'FOLDER' ? FolderReference : T['kind'] extends 'CABINET' ? CabinetReference : T['kind'] extends 'LIFECYCLE_REF' ? LifecycleReference : T['kind'] extends 'FUNCTION_REF' ? FunctionReference : T['kind'] extends 'RECORD' ? RecordValue : T['kind'] extends 'RECORD_REF' ? RecordReference : never;

ValueOf

The full value type: cardinality, item nullability and nullability applied.

export type ValueOf<T extends ValueTypeDeclaration> = (T['cardinality'] extends 'MANY' ? ReadonlyArray<ScalarValueOf<T> | (T['itemNullable'] extends true ? null : never)> : ScalarValueOf<T>) | (T['nullable'] extends true ? null : never);
type Entries<T> = T extends readonly (infer E)[] ? E : never;

PropertiesOf

The resolved property values of a declared control.

export type PropertiesOf<C extends ControlDeclaration> = {
    readonly [P in Entries<NonNullable<C['properties']>> as P['key']]: ValueOf<P['valueType']>;
};

OutputsOf

The editable outputs of a declared control, keyed by output key.

export type OutputsOf<C extends ControlDeclaration> = {
    readonly [O in Entries<NonNullable<C['outputs']>> as O['key']]: ValueOf<O['valueType']>;
};

PayloadOf

The payload object of a declared event.

export type PayloadOf<E extends EventDeclaration> = {
    readonly [F in Entries<NonNullable<E['payload']>> as F['name']]: ValueOf<F['valueType']>;
};

EventsOf

The events of a declared control, keyed by event key, with their payloads.

export type EventsOf<C extends ControlDeclaration> = {
    readonly [E in Entries<NonNullable<C['events']>> as E['key']]: PayloadOf<E>;
};
export {};

Test-kit API: @inflowai/control-test-kit

Generated from inflow-control-test-kit/api/control-test-kit.api.d.ts, the reviewed public API of @inflowai/control-test-kit. Every export is listed.

Export Kind Module
PropertyOptions type host
MOCKED_BOUNDARY const host
RecordedCall interface host
MountOptions interface host
TestHarness interface host
mountForTest function host
OFFLINE_CONTENT_SECURITY_POLICY const conformance
ConformanceCheck interface conformance
ConformanceReport interface conformance
ConformanceOptions interface conformance
runConformance function conformance
valueMatches function values
valueProblem function values
PropertySource interface outputs
routeOutput function outputs
SAMPLE_VALUES const fixtures
INVALID_VALUES const fixtures
typeFixtures function fixtures
PROPERTY_STATES const fixtures
OPTIONS const fixtures
optionsRace function fixtures
BINDING_SEQUENCE const fixtures
THEME_TOKENS const fixtures
THEMES const fixtures
PALETTES const fixtures
RTL const fixtures
PROVIDERS const fixtures
accessibleAlternativeProblems function accessibility
keyboardReachProblems function accessibility
incompatibleModules function compatibility
incompatibleDeclarations function compatibility

PropertyOptions

One property's dynamic option list, as the host delivers it in context.options.

export type PropertyOptions = NonNullable<ControlContext['options']>[string];

MOCKED_BOUNDARY

The label every harness carries. The test kit simulates the Inflow host so a control can be developed and checked in isolation; it is a mocked boundary. Passing its checks is never evidence that a control works on the platform, with a real provider, or for real users: that is shown only by the platform's own acceptance on a real server.

export declare const MOCKED_BOUNDARY: 'MOCKED HOST: simulated Inflow host services, not platform or provider acceptance';

RecordedCall

One call a control made to its host, in order, with the lifecycle phase it happened in.

export interface RecordedCall {
    readonly service: 'setOutput' | 'emit' | 'reportError' | 'setBusy' | 'announce' | 'searchOptions' | 'adoptStyles';
    readonly phase: 'mount' | 'update' | 'resize' | 'idle' | 'retired';
    readonly args: readonly unknown[];
    readonly result?: HostResult;
    /** Whether a simulated interaction (`interact` or `press`) on this harness came before the call (review r76). */
    readonly afterInteraction: boolean;
}

MountOptions

How mountForTest mounts a control: its reviewed declaration plus the mode, property values and states, property sources, options, theme and palette, direction, locale, provider configuration, size and document the simulated host supplies.

export interface MountOptions {
    /** The control's reviewed declaration (its plugin.json entry). Outputs, events and value types are checked against it. */
    readonly declaration: ControlDeclaration;
    readonly mode?: ControlMode;
    readonly properties?: Readonly<Record<string, unknown>>;
    readonly propertyStates?: Readonly<Record<string, PropertyState>>;
    /**
     * Where each property's value comes from on the placed node. An output writes only a property bound to form data
     * (`BINDING`). By default every property an output targets is bound (`locals:<key>`) and the others are literals.
     */
    readonly sources?: Readonly<Record<string, PropertySource>>;
    readonly options?: Readonly<Record<string, PropertyOptions>>;
    /** The theme tokens (default: Studio's own vocabulary, `THEME_TOKENS`). */
    readonly theme?: ThemeTokens;
    /** The page palette the tokens resolve to (default `light`): the variables the page defines, see `PALETTES`. */
    readonly palette?: 'light' | 'dark';
    readonly direction?: TextDirection;
    readonly locale?: string;
    /** Browser-public provider configuration, as an administrator would admit it (SDK 1.1). Empty by default. */
    readonly configuration?: Readonly<Record<string, string>>;
    /** Providers admitted for real loading (SDK 1.1). Empty by default: the control must stay offline. */
    readonly providers?: readonly string[];
    readonly size?: Size;
    /** The document to mount into (jsdom, happy-dom or a real browser). Defaults to the global `document`. */
    /** How long an asynchronous mount may take before it fails and is retired (default 10000 ms) (review r139). */
    readonly mountTimeoutMs?: number;
    readonly document?: Document;
}

TestHarness

A mounted control under the simulated host.

export interface TestHarness {
    readonly boundary: typeof MOCKED_BOUNDARY;
    /** The element the host owns and the control renders into (removed when the instance retires). */
    readonly element: HTMLElement;
    readonly context: ControlContext;
    /** The control's own instance, as `mount` returned it (so a test can call `dispose` a second time, for example). */
    readonly instance: ControlInstance;
    /** Every host call, in order. */
    readonly calls: readonly RecordedCall[];
    /** The CSS the control last adopted, as accepted (null when none). */
    readonly styles: string | null;
    /** Whether the instance has retired (disposed, or after `reportError`). */
    readonly disposed: boolean;
    /** Whether the host shows the shared unavailable state (the control reported an error). */
    readonly unavailable: boolean;
    /** Failures the control's own `dispose` or cleanups threw; the host contains them. */
    readonly teardownErrors: readonly unknown[];
    /**
     * Failures the control's `update` or `resize` threw, or an invalid instance `mount` returned. The host contains them
     * and retires the instance with the unavailable state, as the platform does (review r75).
     */
    readonly failures: readonly unknown[];
    /** Pushes a change, as the host does when bindings, options, theme or direction change. */
    update(change: ControlUpdate): void;
    resize(size: Size): void;
    /** Switches the page palette, as the page does on a theme change (the tokens stay the same, as on the platform). */
    setPalette(palette: 'light' | 'dark'): void;
    /**
     * Simulates a person's interaction inside `target` (default: the control's element): it dispatches `pointerdown` and
     * `mousedown` there, for the control's own handlers, and records the interaction as the page's latest. The record is
     * explicit because a synthetic event is not trusted input in a real browser (review r75). As on the platform, the
     * latest interaction anywhere on the page decides: one in another control, or outside every control, takes the
     * licence away from this one.
     */
    interact(target?: Element): void;
    /**
     * Simulates a person pressing `key` on `target` (default: the focused element, else the control's element): the
     * interaction is recorded first, then `keydown` and `keyup` are dispatched there (review r76).
     */
    press(key: string, target?: Element): void;
    /** Retires the instance as the host does: abort the signal, run cleanups newest first, dispose once, remove the root. */
    dispose(): void;
}

mountForTest

Mounts a control module under the simulated host (awaiting an asynchronous mount). The host services follow the platform host (Studio's PluginControlHost), using Studio's own vendored rules for values, events, styles and interaction provenance:

  • nothing has an effect before the instance is ready or after it retires (not-ready);
  • an undeclared output or event is not-declared; design and preview suppress them (suppressed);
  • an output writes only a bound, writable, ready property, with a value of its exact declared type; an echo of the delivered value is unchanged;
  • an event needs a person's latest interaction on the page inside this control and never runs while the host is calling into it (suppressed); its payload is plain data of the declared fields, at most 16 KiB;
  • reportError retires the instance and shows the unavailable state;
  • adopted styles are at most 64 KiB (UTF-8) and are rebuilt by the scoped-stylesheet validator, or refused.
export declare function mountForTest(module: unknown, options: MountOptions): Promise<TestHarness>;

OFFLINE_CONTENT_SECURITY_POLICY

The content security policy for running conformance in a real browser (review r84). The kit's offline check intercepts and records the page's network paths, which makes a control's network use visible and fails the check; in a browser, prevention is the policy's job: serve the test page with this header (or the equivalent meta tag) so that nothing a control does reaches any server but the test server itself (connect-src 'self', which browser test runners need). Inline scripts and styles stay allowed for test runners.

export declare const OFFLINE_CONTENT_SECURITY_POLICY: "default-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src data: blob:; font-src data:; connect-src 'self'; frame-src 'none'; worker-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";

ConformanceCheck

One conformance check and what it found.

export interface ConformanceCheck {
    readonly id: string;
    readonly title: string;
    readonly passed: boolean;
    readonly problems: readonly string[];
}

ConformanceReport

The result of runConformance. Always labelled as a mocked boundary.

export interface ConformanceReport {
    readonly boundary: typeof MOCKED_BOUNDARY;
    readonly controlKey: string;
    readonly passed: boolean;
    readonly checks: readonly ConformanceCheck[];
}

ConformanceOptions

How runConformance exercises the control: the property values to mount with, the list alternative and rendered choices to expect, property changes to apply, how long to let effects settle, and the document to use.

export interface ConformanceOptions {
    /** Properties to mount with (default: a declaration-valid sample of each declared property's type). */
    readonly properties?: Readonly<Record<string, unknown>>;
    /** When the primary view is not accessible: the list alternative expected for `properties` (FR-024). */
    readonly listAlternative?: {
        readonly items: readonly string[];
        readonly selected?: string | null;
    };
    /**
     * How the control shows the choices it was given, for the options-race check. By default the check reads the
     * element's text (the latest labels must appear and stale-only labels must not); a control that draws its choices
     * (a canvas, a map) supplies this.
     */
    readonly renderedChoices?: (element: HTMLElement) => readonly string[];
    /**
     * Values to change each property to, in order, for the binding-change scenario (default: generated from the
     * declaration). A property whose domain admits another value must receive at least one real change (review r78).
     */
    readonly changes?: Readonly<Record<string, readonly unknown[]>>;
    /** How long to let deferred work (timers, microtasks) run before evaluating effects, in milliseconds (default 30). */
    readonly settleMs?: number;
    /** How long each asynchronous mount may take before it fails (default 10000 ms) (review r139). */
    readonly mountTimeoutMs?: number;
    readonly document?: Document;
}

runConformance

Runs the interface-control conformance checks against a module under the simulated host (SCRUM-4872): the ABI, declaration-valid inputs, every mode, no effects without a person's interaction (including deferred ones), clean and idempotent disposal in the host's order, every property state, an options race, theme and right-to-left, focus kept on update, offline without provider admission (the network intercepted for the whole run, deferred requests and those after disposal included), automation labels and (when given) the accessible list alternative. Runs are serialized. A mocked boundary: passing is not platform or provider acceptance.

export declare function runConformance(module: unknown, declaration: ControlDeclaration, options?: ConformanceOptions): Promise<ConformanceReport>;

valueMatches

Whether a value fits a declared value type, exactly as the platform's typed boundary decides: this is Studio's own validator (resolvedValueProblem, vendored and kept identical by npm run verify), covering facets, ranges, calendar dates, exact numbers, references, nullability and size limits.

export declare function valueMatches(type: ValueTypeDeclaration | undefined, value: unknown): boolean;

valueProblem

Why a value does not fit a declared value type (null when it fits), in the platform's words.

export declare function valueProblem(type: ValueTypeDeclaration, value: unknown): string | null;

PropertySource

Where a placed property's value comes from: a literal, an expression, or a binding to form data.

export interface PropertySource {
    readonly mode: 'LITERAL' | 'EXPRESSION' | 'BINDING';
    readonly bind?: string;
}

routeOutput

The simulated host's output routing. It follows Studio's routePluginOutput (screens/plugin-controls/pluginOutputs.ts) step by step. Studio's parity test runs both over one matrix and requires the same verdicts:

  • undeclared → not-declared;
  • a read-only property, or one not bound to form data → suppressed;
  • a binding loading → not-ready, and refused or computed states → suppressed;
  • a type that differs from the property's, or a value that does not fit it (Studio's vendored validator) → invalid-value;
  • an echo of the delivered value → unchanged. The platform's destination check is simulated by kind (only TEXT, UUID, ENUM, INTEGER, BOOLEAN, DATE and TIME are ever written); whether the bound path itself is a declared, performer-owned value of that kind needs a real form, so a bound path is taken to be one.
export declare function routeOutput(input: {
    readonly key: unknown;
    readonly value: unknown;
    readonly outputs: readonly {
        readonly key: string;
        readonly property?: unknown;
        readonly valueType?: unknown;
    }[];
    readonly properties: readonly {
        readonly key: string;
        readonly readOnly?: unknown;
        readonly valueType?: unknown;
    }[];
    readonly sources: Readonly<Record<string, PropertySource>>;
    readonly states: Readonly<Record<string, PropertyState>>;
    readonly delivered: Readonly<Record<string, unknown>>;
}): HostResult;

SAMPLE_VALUES

A valid sample of each declared kind, as the host delivers it (LONG and DECIMAL as exact text, temporal as ISO text).

export declare const SAMPLE_VALUES: Readonly<Record<ValueKind, unknown>>;

INVALID_VALUES

A value of the wrong shape for each kind, which the host refuses (invalid-value).

export declare const INVALID_VALUES: Readonly<Record<ValueKind, unknown>>;

typeFixtures

One property declaration per kind, for table-driven type tests.

export declare function typeFixtures(): readonly {
    readonly kind: ValueKind;
    readonly valueType: ValueTypeDeclaration;
    readonly valid: unknown;
    readonly invalid: unknown;
}[];

PROPERTY_STATES

Every property state a control must render (FR-013).

export declare const PROPERTY_STATES: Readonly<Record<PropertyState['status'], PropertyState>>;

OPTIONS

Option lists in each status, the value never the label (FR-016).

export declare const OPTIONS: Readonly<Record<'ready' | 'loading' | 'empty' | 'error' | 'more' | 'unavailable', PropertyOptions>>;

optionsRace

An options race: two searches answer out of order. The host delivers only the latest search's answer (latest), never the stale one; a control must show latest and must not keep stale items.

export declare function optionsRace(): {
    readonly stale: PropertyOptions;
    readonly latest: PropertyOptions;
};

BINDING_SEQUENCE

A binding round trip: the host pushes successive values of a bound property, as the form changes.

export declare const BINDING_SEQUENCE: readonly string[];

THEME_TOKENS

The theme a control receives: Studio's own public token vocabulary (CONTROL_THEME_TOKENS, vendored), whose values are CSS custom-property references such as var(--surface), never literal colours (review r79). Light and dark deliver the same tokens: the page switches theme by redefining the variables (see PALETTES), so a control that styles itself with the tokens follows every theme without an update.

export declare const THEME_TOKENS: ThemeTokens;

THEMES

The token vocabulary in light and in dark: identical by design, as on the platform.

export declare const THEMES: Readonly<Record<'light' | 'dark', ThemeTokens>>;

PALETTES

Representative values of the page variables the tokens reference, in Studio's light and dark themes. The simulated host defines them on the control's root (MountOptions.palette, harness.setPalette), as the page does. They are fixtures: the page owns the real values, and a control must read the tokens, never these colours.

export declare const PALETTES: Readonly<Record<'light' | 'dark', Readonly<Record<string, string>>>>;

RTL

Right-to-left locales a control must mirror for.

export declare const RTL: Readonly<{
    direction: 'rtl';
    locale: "ar";
    label: "الرياض";
}>;

PROVIDERS

Provider admission as an administrator would set it (SDK 1.1). offline is the default everywhere and in design and preview. admitted is simulated configuration for a mocked host only; a real provider is qualified on the platform with real environment configuration, never with these values.

export declare const PROVIDERS: Readonly<{
    offline: {
        providers: readonly string[];
        configuration: Readonly<Record<string, string>>;
    };
    admitted: {
        providers: readonly string[];
        configuration: Readonly<Record<string, string>>;
    };
}>;

accessibleAlternativeProblems

Checks the shape of a control's accessible list alternative under root: exactly one rendered, named list (a listbox, a list, ul or ol, found through shadow roots and slots), one entry per expected item in order, each named as items[i], and only the selected item (if any) marked aria-selected="true". Returns the problems found; an empty array means the shape is right. Pair it with keyboardReachProblems for operability.

export declare function accessibleAlternativeProblems(root: Element, expected: {
    readonly items: readonly string[];
    readonly selected?: string | null;
}): string[];

keyboardReachProblems

The list must be operable, not only shaped right. From its single tab stop, ArrowUp reaches the first item (clamping or wrapping) and ArrowDown then visits every item in order, moving focus. Focus is read right after each key, so a control that moves focus later needs runConformance, which waits after each key. Returns the problems found.

export declare function keyboardReachProblems(root: Element, items: readonly string[], pressKey?: (key: string, target: Element) => void): string[];

incompatibleModules

Deliberately incompatible modules (SCRUM-4872). Each must be refused by the host's ABI check before mount; a test kit or host change that starts accepting one is a compatibility regression. problem is the expected refusal.

export declare function incompatibleModules(controlKey: string): readonly {
    readonly name: string;
    readonly module: unknown;
    readonly problem: 'not-an-object' | 'abi-mismatch' | 'bad-control-key' | 'no-mount' | 'key-mismatch';
}[];

incompatibleDeclarations

Declarations a host refuses to mount against, for negative tests of tooling built on the kit.

export declare function incompatibleDeclarations(base: ControlDeclaration): readonly {
    readonly name: string;
    readonly declaration: ControlDeclaration;
}[];

Try “document generation”, “integrations” or “first form”.