@svatah/yam-screens

The headless screen model: one set of screens, actions and keys behind the app, yam ui, the SDK and the CLI

• Source: packages/screens · README: packages/screens/README.md
• Install: npm install @svatah/yam-screens
• Version 0.1.0 · Apache-2.0

Exports

Export	Kind	Signature
Action	interface	export interface Action	One action (LLD §13.7).
ActionArgs	interface	export interface ActionArgs extends ScreenParams	What an action was given: the screen's params, plus whatever the row supplied.
actionById	function	export function actionById(id: string): Action | undefined	One action by id, or undefined. The renderers and the SDK both use this.
ActionInput	interface	export interface ActionInput	One thing an action must be given before it runs.
ActionOutcome	interface	export interface ActionOutcome	What an action answered with. Renderers show message; agents read the rest.
ACTIONS	variable	ACTIONS: readonly Action[] = [...ACTIONS_ONLY, ...GO_TO]	Every action, in palette order: Actions first, then Go to (LLD §13.7).
actionsForScreen	function	export function actionsForScreen(screen: ScreenId): readonly Action[]	The actions a screen offers, in registry order.
AgentsState	interface	export interface AgentsState extends ScreenStateBase
ago	function	export function ago(at: string | undefined, now: number): string | undefined	"run 22 min ago", from an ISO timestamp and the moment now.
ApiRequestResponse	interface	export interface ApiRequestResponse
ApiRequestRow	interface	export interface ApiRequestRow
apiResponseView	function	export function apiResponseView(value: unknown): ApiResponseView | undefined	A response object → what the screen shows of it.
ApiResponseView	interface	export interface ApiResponseView	What POST /api/request answered, when one has been sent on this screen.
ApiState	interface	export interface ApiState extends ScreenStateBase
applyEvent	function	export function applyEvent(state: RunState, event: ServiceEventLike): RunState	Fold one event into a run's state (LLD §13.5's stream, §13.7's live screen).
applyHealEvent	function	export function applyHealEvent(state: HealState, event: ServiceEventLike): HealState	Fold one event into the Heal screen's state (LLD §13.5's stream).
applyRecordEvent	function	export function applyRecordEvent<T extends RecordView>(state: T, event: ServiceEventLike): T	Fold one event into the Record screen's state (LLD §13.5's stream).
AuditResponse	interface	export interface AuditResponse	One audit.jsonl line (LLD §3.4, REQ-AUTO-6).
AuditRow	interface	export interface AuditRow
AUTHORING_SCREENS	variable	AUTHORING_SCREENS = [
BindingCandidate	interface	export interface BindingCandidate
BindingFileResponse	interface	export interface BindingFileResponse	GET /bindings/:id, parsed: the YAML yam bindings show prints.
BindingInspector	interface	export interface BindingInspector	What the inspector shows about the selected binding (the Bindings artboard).
BindingListRow	interface	export interface BindingListRow	GET /bindings — the list, which is ids and file paths and nothing else.
BindingRow	interface	export interface BindingRow
BindingsState	interface	export interface BindingsState extends ScreenStateBase
CompileResponse	interface	export interface CompileResponse
DataResponse	interface	export interface DataResponse
DataRow	interface	export interface DataRow
DataState	interface	export interface DataState extends ScreenStateBase
defaultScreenOf	function	export function defaultScreenOf(section: SectionId): ScreenId	The screen a section opens on: the first row of its sub-rail.
DESKTOP_HOLDER	variable	DESKTOP_HOLDER = "Yam desktop"	How this desktop names itself when it takes a target (SF-13, T16).
Diagnostic	interface	export interface Diagnostic
dotted	variable	dotted = (...parts: ReadonlyArray<string | undefined>): string =>	["a", "b"] → "a · b", dropping the empties. The mockups' subtitle style.
envelopeError	function	export function envelopeError(value: unknown): string | undefined	The error.message of a failed/refused envelope, when it carries one.
EVERY_SCREEN_IS_MODELLED	variable	EVERY_SCREEN_IS_MODELLED: boolean = SCREEN_IDS.every((id) =>	Every screen id has exactly one screen. The renderers rely on it; so does --json.
FakeCall	interface	export interface FakeCall	What the fake was asked, in order. A test asserts on the screen rule with it.
FakeNotFound	class	export class FakeNotFound extends Error	A route the fixtures have no answer for. Screens treat it as an empty screen.
FakeResponses	interface	export interface FakeResponses	Every response the fake can give, keyed the way the fixtures file is.
fakeService	function	export function fakeService(responses: FakeResponses = {}): FakeService
FakeService	interface	export interface FakeService extends ScreenService
FlowLine	interface	export interface FlowLine	One line of the editor, with what the plan and the last run say about it.
FlowRow	interface	export interface FlowRow	One row of the flow list (the Main artboard's left column).
flowsScreen	variable	flowsScreen: Screen<FlowsState>
FlowsState	interface	export interface FlowsState extends ScreenStateBase
HealProposal	interface	export interface HealProposal	One repair the healer proposes: before, after, and why (REQ-HEAL-2).
HealState	interface	export interface HealState extends ScreenStateBase
importResultView	function	export function importResultView(value: unknown): ImportState["result"]	POST /migrate's answer → the rows the screen shows.
ImportState	interface	export interface ImportState extends ScreenStateBase
loadRecord	function	export async function loadRecord(	Load the record mode's half of a Session (TV-M04).
loadSurface	function	export async function loadSurface(	Load the do mode's half of a Session (TV-M04).
modeFrom	function	export function modeFrom(value: unknown): SessionMode	--mode, validated against the model's own list; do when unsaid.
needsProject	function	export function needsProject(screen: ScreenId): boolean
outcomeOf	function	export function outcomeOf(summary: SummaryResponse): Pill	How a summary's outcome reads, in one place (T10.4 added stopped).
parseBinding	function	export function parseBinding(text: string): BindingFileResponse | undefined	One binding file's YAML → the shape a screen reads, or undefined.
Pill	interface	export interface Pill	A pill: a word, and the tone that colours it. The word is never omitted.
PlanResponse	interface	export interface PlanResponse
PlanStep	interface	export interface PlanStep	One compiled step, as the Plan tab and the editor's gutter read it.
PlanStory	interface	export interface PlanStory
platformGroups	function	export function platformGroups(	Adapters and targets → the platform-family groups the screen draws.
plural	variable	plural = (n: number, one: string, many = ${one}s): string =>	1/2 → "1 story"/"2 stories".
policyText	function	export function policyText(policy: string | { compensate?: string } | undefined): string | undefined	An onFailure policy as one phrase (REQ-AUTO-4).
problemFor	function	export function problemFor(code: string | undefined, message: string): SurfaceProblem | undefined	A domain error code → the state it puts the inspector in, and the way out.
ProjectResponse	interface	export interface ProjectResponse	What the service's answers look like, as far as a screen reads them.
RAIL	variable	RAIL: ReadonlyArray<
RecordDecision	interface	export interface RecordDecision	One grounding waiting on a reviewer (REQ-ADE-4, the record.decision event).
RecordLoad	typealias	export type RecordLoad = RecordView & Omit<ScreenStateBase, "screen">;	The view, plus the provenance the loader collected for it.
RecordView	interface	export interface RecordView	What the record mode of Session is about (TV-M04).
RunInspector	interface	export interface RunInspector
runScreen	variable	runScreen: Screen<RunState>
RunsFilters	interface	export interface RunsFilters	The filter chips the artboard shows. all is not a filter.
RunsInspector	interface	export interface RunsInspector	What the inspector shows about the selected run (the artboard's right column).
RunsRow	interface	export interface RunsRow
RunsState	interface	export interface RunsState extends ScreenStateBase
RunState	interface	export interface RunState extends ScreenStateBase
runStateFrom	function	export function runStateFrom(	Build the whole state from a summary, its results and its audit.
RunStepRow	interface	export interface RunStepRow
RunStoryRow	interface	export interface RunStoryRow
SaidSentence	interface	export interface SaidSentence	One sentence the person said, and what became of it.
SayView	interface	export interface SayView	The say mode's own state (TV-15).
Screen	interface	export interface Screen<S extends ScreenStateBase = ScreenStateBase>	One screen (LLD §13.7).
SCREEN_IDS	variable	SCREEN_IDS = [	The twelve screens (LLD §13.7).
screenById	function	export function screenById(id: ScreenId): Screen<ScreenStateBase>	One screen by id. Throws rather than answering undefined: ids are a union.
ScreenId	typealias	export type ScreenId = (typeof SCREEN_IDS)[number];
ScreenParams	interface	export interface ScreenParams	What a screen was asked to show: which flow, which run, which binding.
SCREENS	variable	SCREENS: readonly Screen<ScreenStateBase>[] = [	Every screen, in rail order (LLD §13.7's information architecture).
ScreenService	interface	export interface ScreenService	A screen asks for what it renders and gets unknown; it parses with @svatah/yam-schema.
ScreenStateBase	interface	export interface ScreenStateBase	Every screen's state carries these, so a renderer's chrome is written once.
SECONDARY_SCREENS	variable	SECONDARY_SCREENS = [
Section	interface	export interface Section
SectionId	typealias	export type SectionId = "session" | "automations" | "activity" | "settings";	The four destinations (SF-16, REQ-ADE-11).
sectionOf	function	export function sectionOf(screen: ScreenId): SectionId
SECTIONS	variable	SECTIONS: readonly Section[] = [
ServiceConnectionInfo	interface	export interface ServiceConnectionInfo	Where the connection is, for the renderers' chrome and for --json.
ServiceEventLike	interface	export interface ServiceEventLike	One line of the event stream, as far as a screen cares.
SESSION_MODES	variable	SESSION_MODES = ["record", "say", "do"] as const	Session's three modes (REQ-ADE-14, Draft 2.27).
SessionMode	typealias	export type SessionMode = (typeof SESSION_MODES)[number];
sessionScreen	variable	sessionScreen: Screen<SessionState>
SessionState	interface	export interface SessionState extends ScreenStateBase
SettingsState	interface	export interface SettingsState extends ScreenStateBase
Sources	class	export class Sources	Collects the endpoints a load touched and the first thing that went wrong.
stamp	function	export function stamp(at: string | undefined, startedAt: string | undefined): string	2026-09-05T09:13:42.896Z and the run's start → 08.451, the mockup's stamp.
StatusTone	typealias	export type StatusTone = "pass" | "fail" | "skip" | "healed" | "abort" | "info" | "neutral";	A status word with the colour token beside it (LLD §13.7: never colour alone).
StepInspector	interface	export interface StepInspector	What the inspector shows about the selected step.
StepResultResponse	interface	export interface StepResultResponse
SummaryResponse	interface	export interface SummaryResponse
SurfaceActionField	interface	export interface SurfaceActionField	One field of an action's form, as the catalogue describes it.
SurfaceActionOffer	interface	export interface SurfaceActionOffer	One action this surface can perform, with what it needs.
SurfaceAdapterRow	interface	export interface SurfaceAdapterRow	One adapter the service reported, with its readiness and, when not, why.
SurfaceAgentSetup	interface	export interface SurfaceAgentSetup	What a generic MCP client needs to reach the same sessions (SF-07, T16).
SurfaceElementView	interface	export interface SurfaceElementView	What describe said about the selected control.
SurfaceLoad	typealias	export type SurfaceLoad = SurfaceView & Omit<ScreenStateBase, "screen">;	The view, plus the provenance the loader collected for it.
surfaceOutcomeView	function	export function surfaceOutcomeView(value: unknown): SurfaceOutcomeView | undefined	What an act and its postcondition came to (SF-11, T15).
SurfaceOutcomeView	interface	export interface SurfaceOutcomeView	What an act (and its optional postcondition) came to (SF-11).
SurfacePlatformGroup	interface	export interface SurfacePlatformGroup	A platform family, with its adapters and any targets discovered under it.
SurfaceProblem	interface	export interface SurfaceProblem
SurfaceProblemKind	typealias	export type SurfaceProblemKind	A state the inspector is in that is not "ready" (SF-17).
SurfaceSessionRow	interface	export interface SurfaceSessionRow	One open session, an agent's or a person's (SF-05, SF-13).
SurfaceSessionView	interface	export interface SurfaceSessionView	The session the inspector is about.
SurfaceTargetRow	interface	export interface SurfaceTargetRow	One target the service discovered — an adapter, or a URL through one.
SurfaceTreeLine	interface	export interface SurfaceTreeLine	One line of the semantic tree, as the inspector draws it.
SurfaceView	interface	export interface SurfaceView	What the do mode of Session is about (TV-M04).
ToolsResponse	interface	export interface ToolsResponse	GET /tools — { tools: { tools, refused }, invocations }.
TREE_MAX_NODES	variable	TREE_MAX_NODES = 200	How many nodes the inspector's tree asks for. Bounded, and it says when it truncated.
treeLines	function	export function treeLines(	A snapshot's flat nodes → the indented lines the tree pane draws.