Desktop, widgets & signals

The Living Desktop: layout, themes, signals and the omnibar.

Every schema below is exported from @novaterra/contracts and validated on both sides of the wire. Source: packages/contracts/src/desktop.ts.

WidgetType

string (min 1, max 80, regex)

Widget

Field	Type	Notes
id	Id
beingId	Id
type	WidgetType
title	string	optional
x	number
y	number
w	number
h	number	grid units
config	Record<string, Json>	optional · default {}
visible	boolean	optional · default true
pinned	boolean	optional · default false
order	number	optional · default 0

BackgroundKind

'shader' | 'image' | 'video'

ShaderPack

'aurora' | 'ocean' | 'nebula' | 'forest' | 'dawn' | 'ember' | 'void' | 'windowsill' | 'lowtide' | 'bark' | 'moss' | 'ink'

Theme

Field	Type	Notes
id	Id
beingId	Id
name	string
background	{ kind: BackgroundKind; src: string | null; pack: ShaderPack | null; params: Record<string, number> }
palette	{ primary: string; accent: string; text: string; muted: string; glow: string }
glass	{ blur: number; opacity: number; radius: number }
motion	'calm' | 'alive' | 'still'	optional · default 'alive'
fontDisplay	string	optional · default 'Fraunces'
fontBody	string	optional · default 'Inter'
isActive	boolean	optional · default false

SignalKind

'decision' | 'insight' | 'reminder' | 'alert' | 'question' | 'celebration'

SignalPriority

'low' | 'normal' | 'high' | 'urgent'

SignalStatus

⚠️ expired IS WRITTEN BY NOTHING AND NEVER HAS BEEN. It is left in the enum because rows in the wild may carry it, and because an absent state and a false one are different things — but a signal has never stopped standing by itself, and retracted is the state that was missing. retracted is the difference between a fact that stopped being true and a person who said no. answered and dismissed are both claims about the PERSON: they mean somebody looked. Flipping a contradicted row to either of them puts words in their mouth, and that is what clearRepliesSignal had to do for want of anywhere else to go. A retraction is the RAISER saying its own reason is gone. Council 008’s Margaret’s rule — a thing that leaves leaves a note — is why it is a status and not a DELETE: the row stays, action.retracted records when and why, and GET /api/desktop/signals?status=retracted can still answer for it.

'open' | 'answered' | 'dismissed' | 'expired' | 'retracted'

SignalOption

Field	Type	Notes
id	string
label	string
hint	string	optional

Signal

Field	Type	Notes
id	Id
beingId	Id
kind	SignalKind
title	string
body	string
options	SignalOption[]	optional · default []
answer	string | null	optional · default null
priority	SignalPriority	optional · default 'normal'
status	SignalStatus	optional · default 'open'
source	string	‘twin’ | ‘studio:<projectId>’ | ‘email’ | ‘muse’ | ‘system’
action	Record<string, Json> | null	optional · default null · what to do when answered
dueAt	ISODate | null	optional · default null
createdAt	ISODate

NowResponse

Field	Type	Notes
greeting	string
headline	string	one line: the single most important thing
signals	Signal[]
activeProjects	number
nextRoutine	{ name: string; when: string } | null
mood	string

OmniRequest

Field	Type	Notes
query	string (min 1)

OmniResponse

Field	Type	Notes
intent	'ask' | 'navigate' | 'generate' | 'search' | 'command'
reply	string
action	Record<string, Json> | null	optional · default null · e.g. {navigate:‘/studio’} or {projectId}