s-m-r-t
Open the s-m-r-t source on GitHub Switch to dark color scheme

Component system showcase

Interfaces for people. Contracts for agents.

SMRT components stay ordinary, accessible interface elements. Applications can also expose their meaning and operations to a governed agent caller.

01 The person operates

The rendered control keeps labels, state, feedback, focus, and confirmation visible.

02 The agent calls

An adapter discovers stable identities and requests the same allowed operations.

03 The application governs

Application policy owns authorization, validation, consent, persistence, and refusal.

Read the interaction contract See the framework architecture

How to use this page

Two kinds of story, one boundary

An interaction story names what a person sees, what an agent can discover and operate, where confirmation occurs, and how the component refuses unsafe work. A batteries-included story names what a consumer gets from the installed package, how the capability is turned on, and the boundary it enforces.

This page curates the system. Package pages remain the API reference, and the Playground holds standalone interactive previews.

Interaction stories

One boundary for people and agents

Each story names what a person sees, what an agent can discover and operate, where confirmation occurs, and how the component refuses unsafe work.

Shared control contract

Agent-addressable components

A control can publish a stable contract without containing an agent or a model.

An agent is a governed caller of the same component contract that a person uses. The contract keeps meaning, state, consent, and refusal explicit.

Released surfaces

  • createControlInteractionRegistry
  • Form
  • Input
  • Select
  • Switch

Scripted demonstration · released registry

A proposal succeeds. A protected change fails.

This scripted adapter uses real controls, validation, classification, staging, and confirmation policies. No language model runs in this demo.

Small example object

Subject
Profile · 42
Form ID
profile-demo

3–30 characters. Start with a letter.

A stored secret exists. The form and adapter do not receive its value.

Permitted proposal

  1. Find and explainRead stable identity, label, constraints, and policy.
  2. Validate the proposalUse the same rule as the visible form.
  3. Stage separatelyKeep the proposal apart from the live value.
  4. ReviewCompare the live and proposed values.
  5. Confirm and applyA real click supplies the confirmation an agent cannot send.
  6. UndoRestore the previous registry-held value.
Live valueWillow Reed
Proposed valueNot staged
Proposal checkNot checked

Policy refusal

Awareness is not authority

The registry can identify the recovery-key control. Its secret classification removes read and mutation authority.

No request sent The adapter supplies no protected value to this attempt.

Choose the first step to run the permitted proposal.

Person sees

A person sees labels, choices, current state, validation, and controls for staged or live changes.

Agent discovers

An agent can find a control by stable form and control IDs. Metadata describes its meaning, options, constraints, sensitivity, state, and commands.

Agent operates

An adapter can request focus, reveal, highlight, explain, validate, stage, apply, clear, or undo operations. Each request identifies its command source.

Confirmation boundary

An agent can stage a value without changing the live value. An agent apply operation is always refused by default; only a human, through a real local click, can apply it.

Failure behavior

The default policy refuses writes to non-writable, disabled, read-only, or secret controls. Secret controls publish no read or mutation capability.

What this story proves

  • Stable form and control IDs
  • Meaning, options, and constraints
  • Sensitivity and current state
  • Command source records
  • Stage, validate, apply, and undo

Rich input composition

Model-driven forms and rich inputs

Model metadata and field policy can shape one form without weakening its write boundary.

Provider-backed inputs add application state, speech entry, and value-specific behavior. Field policy controls presentation, while the model remains the security authority.

Released surfaces

  • ObjectForm
  • FieldPolicyProvider
  • TextInput
  • MoneyInput
  • DateTimeInput
  • AddressInput
  • FileUpload
  • FormMicButton

Person sees

A person sees the applicable basic and advanced fields, rich value controls, help, validation, and a voice entry point when the application wires one.

Agent discovers

An agent can discover visible control metadata and the resolved field arrangement. The model and field policy remain separate contracts.

Agent operates

An adapter can explain and validate values or stage permitted changes. Provider-backed inputs can connect speech results to the same form state.

Confirmation boundary

A proposed value stays separate until the person confirms it. The form can then apply and validate the value through its registered control.

Failure behavior

A hidden field is not an authorization rule. Secret controls stay redacted, and model write policy must refuse protected fields at the server boundary.

What this story proves

  • Model-aware field definitions
  • Field-policy visibility and defaults
  • Rich value-specific inputs
  • Visible validation
  • Secret value handling
  • Explicit voice entry points

Visible agent work

Chat and tool calls

Chat surfaces keep messages, tool operations, results, errors, and proposed edits visible.

AgentChat composes session state, loading state, messages, tool calls, and field-change review. MessageBubble supplies accessible user, agent, and system message forms.

Released surfaces

  • AgentChat
  • MessageBubble
  • ToolCallDisplay
  • MessageList
  • MessageInput

Person sees

A person sees message roles, session status, loading state, tool progress, tool details, and field-change differences before any suggested edit is applied.

Agent discovers

An agent can receive the active session, allowed tool list, message context, and host callbacks that the application supplies.

Agent operates

The UI can display pending, running, successful, and failed tool calls. Each display can show arguments, results, errors, and duration.

Confirmation boundary

Suggested markdown displays an Apply control only when the host supplies an onapplychange callback. The callback keeps the final edit application-owned.

Failure behavior

An inactive session disables message submission. A failed tool call keeps its error visible instead of presenting a successful result.

What this story proves

  • User, agent, system, and tool roles
  • Tool name and status
  • Arguments, results, and errors
  • Duration and loading state
  • Field-change differences
  • Explicit Apply callback
  • Session status

The live site shell

Application shell and navigation

This documentation site is the live AdminShell example. The story does not nest or imitate another shell.

The application bar holds primary navigation and site actions. The contextual application panel holds section navigation, and route content uses the shell main area.

Released surfaces

  • AdminShell
  • ShellState
  • useAdminShell
  • tenantNavFromManifest
  • ActivityList
  • ShellSettingsPanel

Live site contract

Active ShellState

This readout uses the documentation shell context. It does not create a nested shell or copy its navigation.

Application panel collapsed
Application
App bar, documentation panel, and route content
Tenant
Hidden because this site has no tenant workspace
Focus
Available to routes that register focused tools
System
Hidden because this site has no system panel

Person sees

A visitor uses the application bar, search, site actions, contextual documentation panel, responsive navigation, focus restoration, and shell-owned scroll area on every docs route.

Agent discovers

An integrated component can read the active ShellState from context. An application can derive permitted tenant navigation from its manifest.

Agent operates

A route can operate the active panel state and register focus tools or activities. Each registration returns a cleanup function for route unmount.

Confirmation boundary

Shell settings are user-owned preferences. Domain operations still use their own permission and confirmation rules.

Failure behavior

Unused tenant, focus, and system edges stay hidden on this site. A hidden edge does not imply that its application capability is active.

What this story proves

  • Application bar and application panel
  • Active ShellState context
  • Manifest-derived tenant navigation
  • Session and permission context
  • Activities and focus tools
  • User-owned settings
  • Route-scoped cleanup

Explicit browser capability

Voice and browser AI

Browser AI starts with capability detection and explicit adapter configuration.

Speech and local-model components show readiness, initialization, listening, generation, errors, and download progress. The application chooses and wires each adapter.

Released surfaces

  • VoiceInput
  • CapabilityGate
  • DownloadProgress
  • AILoadingOverlay
  • useSTT
  • useTTS
  • useLLM

Person sees

A person sees whether the capability is available, initializing, ready, listening, speaking, generating, downloading, or in an error state.

Agent discovers

An agent can discover the capability and current adapter state that the Provider exposes. Availability does not grant microphone or mutation authority.

Agent operates

The application can initialize speech or model adapters, start or stop speech, stream model tokens, and keep initialized adapters in a warm cache.

Confirmation boundary

The browser and application own microphone consent. A speech result still enters the applicable control staging and confirmation policy.

Failure behavior

CapabilityGate can withhold unsupported UI. Initialization errors and download state remain visible, and no adapter is selected without application configuration.

What this story proves

  • Capability detection
  • Speech input and output
  • Model readiness
  • Download progress
  • Warm adapter cache
  • Explicit adapter wiring

State that stays visible

Feedback and focused work

Feedback components identify progress, interruption, confirmation, and failure without hiding the active task.

Alerts, toasts, progress, meters, dialogs, drawers, disclosure, and focus tools use shared state, focus, keyboard, motion, and theme conventions.

Released surfaces

  • Alert
  • ToastViewport
  • Progress
  • Meter
  • ConfirmDialog
  • Drawer
  • Disclosure
  • ShellDockTool

Person sees

A person sees task status, progress, errors, available actions, and the focused work surface. Keyboard focus follows the open overlay or tool.

Agent discovers

An agent can discover declared status, progress, available actions, and the subject of a registered focus tool or shell activity.

Agent operates

Application code can update an activity, open a focus tool, show feedback, or request a confirmation through the matching component contract.

Confirmation boundary

ConfirmDialog keeps a destructive decision explicit. The final operation remains in the application callback and its authorization boundary.

Failure behavior

A failed activity keeps an error state. Escape, focus containment, disabled actions, and reduced motion prevent an overlay from becoming an uncontrolled path.

What this story proves

  • Visible progress and errors
  • Keyboard and focus control
  • Explicit destructive confirmation
  • Scoped focus tools
  • Reduced-motion behavior

One component contract

Themes and accessibility

Semantic tokens change presentation without changing component meaning or interaction.

Foundation components share native semantics, visible focus, keyboard behavior, theme tokens, loading and disabled states, and reduced-motion rules. Each preset ships as generated and static stylesheets, with optional self-hosted fonts.

Released surfaces

  • ThemeProvider
  • ThemeSwitcher
  • ColorSchemeToggle
  • generateThemeCSS
  • Button
  • FormGroup
  • DataTable

Person sees

A person can use the same control with a keyboard, pointer, touch target, screen reader, narrow viewport, reduced motion, or another theme.

Agent discovers

An agent can discover semantic role, name, state, constraints, and declared options. Theme values do not change that interaction contract.

Agent operates

The application can select a preset and color scheme through ThemeProvider, or link a static preset stylesheet. Components consume semantic tokens instead of installing private component themes.

Confirmation boundary

Theme preference changes presentation only. A theme action does not confirm a domain operation or grant an agent command.

Failure behavior

Unsupported themes keep token fallbacks, and reduced-motion rules remove nonessential motion. Disabled and invalid states remain explicit in every scheme.

What this story proves

  • Material, Glass, Studio, SMRT, and HappyVertical presets
  • Light and dark color schemes
  • Static preset stylesheets generated from the same tokens
  • Optional self-hosted font files
  • Token names with Material 3 aliases
  • Visible keyboard focus
  • Native control semantics
  • Mobile layouts
  • Reduced motion

Batteries included

What the installed package already includes

Each story names what a consumer gets from the installed package, how the capability is turned on, and the boundary it enforces.

On by default

Staged review for proposed values

Both Form components mount a review surface for values that an agent proposes.

A proposed value waits in the form until a person applies or discards it. The registry records who proposed each value, when, and against which revision.

Released surfaces

  • StagedControlReview
  • Form
  • ControlInteractionRegistry

What ships

Every Form renders the review surface for staged changes. The surface lists each proposed value and offers apply and discard, singly or for the whole batch.

How it is turned on

The stagedReview prop is true on the base Form in smrt-ui and the rich Form in smrt-svelte. Passing false hides the built-in surface, and an application can mount StagedControlReview itself with the same registry and form ID.

Boundary it enforces

An agent can stage a value but cannot confirm it. Apply is accepted only from a trusted browser gesture while its event is dispatching. A serialized confirmed flag is not confirmation. Secret controls never accept staging, and sensitive values stay redacted in the review surface.

What the package includes

  • Mounted by the base Form and the rich Form
  • stagedReview is true by default
  • Provenance, timestamp, and revision per proposal
  • Apply only through a local human gesture
  • Secret controls never accept staging
  • Stale and invalid proposals stay visible

Route components

Whole-page route components

The content package ships complete admin and public pages that a host mounts as routes.

Route components cover authoring, governance, facts, contributions, and the published article. Route metadata carries each page title, description, and default path, and, for the admin pages, a navigation entry.

Released surfaces

  • ContentWorkspaceRoute
  • ContentGovernanceRoute
  • ContentFactsRoute
  • ContentContributionsRoute
  • PublishedArticleRoute
  • CONTENT_ROUTE_META
  • createContentRouteNavigation

What ships

A host renders a workspace, governance admin, fact catalog, contribution inbox, or published article page from one component. The workspace page wraps ContentList with the package defaults.

How it is turned on

The components export from the smrt-content svelte subpath. CONTENT_ROUTE_META names the default path for each page, and createContentRouteNavigation returns navigation items with optional path overrides.

Boundary it enforces

A route component renders the page. The host owns the SvelteKit route file and the load function that supplies data. The published article loads one content record with its public transparency information.

What the package includes

  • One import for every content page
  • Route metadata with titles and default paths
  • Navigation items from one helper
  • Path overrides per route
  • Asset manager and image studio routes in the package workbenches

Component discovery

Module UI registry

A domain package registers its components at import time. A host resolves them by package name and slot ID.

ModuleUIRegistry is one global registry in smrt-ui. Slot IDs are stable strings, so a host can reference a component without importing the package that owns it.

Released surfaces

  • ModuleUIRegistry
  • createModuleUIRegistry
  • SmrtModuleMeta
  • ModuleUISlot
  • ASSETS_UI_SLOTS

What ships

Importing a package svelte subpath registers its components. The assets package registers its manager, grid, list, detail, toolbar, action bar, and create modal as slots. The images package registers its gallery, editor, and uploader.

How it is turned on

A host imports the assets svelte subpath for its side effect, then calls ModuleUIRegistry.get with the package name and slot ID. The ui subpath exports the slot declarations, so a host can list them without a hard import of the components.

Boundary it enforces

The registry stores and returns component references. smrt-ui imports no domain package, so registration flows one way, from a domain package into the leaf.

What the package includes

  • One global registry in smrt-ui
  • Registration on import of a package svelte subpath
  • Stable slot IDs per package
  • Slot metadata with label, icon, and category
  • A private registry through createModuleUIRegistry

Message catalogs

Translations and message catalogs

Every package registers English defaults in code. A server snapshot supplies translations, and a lookup never returns blank.

The client reads a per-locale dictionary of templates and fills placeholders itself. The language resolver stays on the server.

Released surfaces

  • useI18n
  • Trans
  • defineMessages
  • renderTemplate
  • buildI18nSnapshot

What ships

Package components already carry their English strings. A component reads a string with t or Trans, and a lookup falls back from the snapshot to the registered default to the key.

How it is turned on

A load function calls buildI18nSnapshot with the request locale, tenant, and database, and passes the result to Provider as the i18n prop. Reassigning that prop switches locale and re-renders every string.

Boundary it enforces

Resolution has no async step, so render never waits on a network call. The languages package is imported only by the server subpath and stays out of the browser bundle.

What the package includes

  • English defaults registered with defineMessages
  • t for attributes and Trans for element bodies
  • Snapshot, then registered default, then the key itself
  • No async step during render
  • Works outside a Provider
  • Server-only buildI18nSnapshot

Operations UI included

Agent admin shells

The agents package ships the admin panel, the settings shell, and a settings form that renders a declared schema.

An agent class declares its admin panels as static uiSlots. A slot with a settingsSchema gets a form without custom component code.

Released surfaces

  • AgentAdminPanel
  • AgentAdminTabs
  • AgentSettingsShell
  • AgentSettingsForm
  • AgentUISlot
  • AgentSettingsSchema

What ships

An agent declares its panels once. Without a registered custom component, AgentSettingsForm renders the declared schema as the settings panel. Dashboard, schedule form, schedule list, and run history components register in the module UI registry.

How it is turned on

The shells import from the smrt-agents svelte admin subpath, which registers nothing on import. The svelte barrel adds the registry registration for the schedule components.

Boundary it enforces

Saved settings merge over file configuration through getMergedConfig, and the database value wins. A persona-backed agent stores settings under its persona ID.

What the package includes

  • Admin shells from a side-effect-free subpath
  • Static uiSlots with id, label, icon, and order
  • A settings schema that carries its version, rendered by AgentSettingsForm
  • Settings owned per agent or per persona
  • Dashboard, schedule, and run-history components in the registry

Sign-in and sessions

Auth and session wiring

One handle hook loads the session, and ready-made handlers cover sign-in, callback, and mobile.

The users package supplies the SvelteKit pieces. A session handler covers hooks.server.ts, cookie helpers cover form actions, and OIDC and mobile handlers cover sign-in.

Released surfaces

  • createSessionHandler
  • createSessionCookie
  • destroySessionCookie
  • switchSessionTenant
  • createOidcLoginHandler
  • createOidcCallbackHandler
  • createMobileAuthHandlers

What ships

After createSessionHandler runs, every request carries the user, membership, permission slugs, tenant ID, and session ID on event.locals. Mobile apps get start, complete, session, and logout handlers plus a bearer guard for app-owned routes.

How it is turned on

hooks.server.ts exports the handle from createSessionHandler with a database, a TTL in seconds, and paths to skip. Form actions call createSessionCookie, destroySessionCookie, or switchSessionTenant, and two server routes export the OIDC login and callback handlers.

Boundary it enforces

A tenant switch is refused unless the user holds an active membership in the target tenant, and a successful switch issues a new session ID. OIDC sign-in refuses an identity that the provider reports as unverified email.

What the package includes

  • event.locals with user, membership, permissions, tenant, and session
  • Cookie helpers for sign-in, sign-out, and tenant switch
  • OIDC login and callback handlers
  • Mobile sessions carried as a bearer token, with the sign-in handshake held by the server
  • Session lifetime set in seconds
  • Tenant switch verifies membership and rotates the session ID

Implementation rule

Keep intelligence out of the primitive

A component exposes meaning, state, and operations. The application supplies the model, adapter, permissions, confirmation rules, and durable side effects.

Continue to the interaction contract