# Surfaces, layouts, and widgets

A surface is the root of an authored interface. Layout containers such as column, row, grid, stack, dock, overlay, and panel organize semantic widgets without turning the file into pixel-by-pixel drawing code.

Last updated: 2026-09-09

Package: language | Status: candidate

Tags: column, complete-program, cpu, language, layout, panel, row, surface, windows, yeho, yui, yui-start

Start with the smallest surface and one clear layout container. Add nested layout only when it expresses a real visual or interaction relationship.

```yh
surface Name { ... }
column Name { ... }
row Name { ... }
WidgetKind Name { property = value }
```


## Complete native settings application

A maintained YUI application with typed settings state, commands, controls, and a reusable component. All source files are included; Windows runtime qualification remains separate from a type check.

Verification: type checked

```yh
using window
using time
using input.keyboard
using input.mouse
using ui
using frontend.yui
using frontend.yui.host.window
using frontend.yui.host.windows

ApplySettingsDomainAction(yuiAuthoredInteractionRuntime interaction, yuiAuthoredAction action) returns yuiAuthoredInteractionRuntime
{
    if !action.handled
    {
        return interaction
    }
    if action.command == "settings.toggleCompact" and !action.stateChanged
    {
        interaction.Activate("SettingsStudio.Content.Preferences.Compact", "", "shortcut")
    }
    else if action.command == "settings.toggleUpdates" and !action.stateChanged
    {
        interaction.Activate("SettingsStudio.Content.Preferences.Updates", "", "shortcut")
    }
    else if action.command == "settings.save"
    {
        Console.Log(Text.Format("settings.save: name={0}; compact={1}; updates={2}", interaction.authored.StateValue("profile.name"), interaction.authored.StateValue("preferences.compact"), interaction.authored.StateValue("preferences.updates")))
    }
    return interaction
}

SettingsAddDirtyOwner(list of text owners, text ownerId) returns list of text
{
    if Text.Length(ownerId) == 0 { return owners }
    for existing in owners
    {
        if existing == ownerId { return owners }
    }
    owners.Add(ownerId)
    return owners
}

SettingsHasDirtyOwner(list of text owners, text ownerId) returns bool
{
    for existing in owners
    {
        if existing == ownerId { return true }
    }
    return false
}

OpenWindow("YUI authored settings", 1120, 760)
windowHandle mainWindow = CreateWindowHandle(1)
yuiWindowsHostInputAdapter hostInput = CreateYuiWindowsHostInputAdapter(mainWindow)
yuiAuthoredInteractionRuntime interaction = CreateYuiAuthoredInteractionRuntime(BuildSettingsStudioYuiRuntime(), "settings.surface", 6)
yuiThemeDefinition theme = CreateYuiModernDarkTheme()
bool tabWasDown = false
bool leftWasDown = false
bool rightWasDown = false
bool upWasDown = false
bool downWasDown = false
bool enterWasDown = false
bool spaceWasDown = false
bool updatesWasDown = false
bool saveWasDown = false
bool escapeWasDown = false

if !interaction.AddShortcut(CreateYuiCommandBinding("settings-updates", "", "Ctrl+U", "settings.toggleUpdates", "settings")) or !interaction.AddShortcut(CreateYuiCommandBinding("settings-save", "", "Ctrl+S", "settings.save", "settings"))
{
    Console.Error(interaction.diagnostic)
}

Console.Log(interaction.authored.RenderReport())
Console.Log(interaction.authored.RenderAccessibilityReport())
Console.Log("authored-settings-controls: mouse=focus/activate; Tab/arrows=focus; Enter/Space=activate; Ctrl+U=updates; Ctrl+S=save; Escape=close")

yuiCanvasViewport viewport = CreateYuiFluidCanvasViewport(1120, 760)
yuiAuthoredApplicationLayoutPlan plan = ResolveYuiAuthoredApplicationLayout(interaction.authored, 0, 0, viewport.designWidth, viewport.designHeight)
interaction.SyncLayout(plan.placements)
yuiDisplayList display = BuildYuiAuthoredApplicationDisplayList(interaction.authored, theme, plan, interaction.input.hoverNodeId, interaction.input.pressedNodeId, interaction.focus.focusedNodeId)
// Authored applications discover their window target's color capability from
// the live graphics provider. `BuildYuiAuthoredApplicationComposition` is a
// convenience wrapper that declares the legacy encoded-sRGB profile as a
// constant, which does not present on a provider that enforces sRGB; the
// `ForTarget` seam exists precisely so a host can supply the real one.
AuthoredWindowTarget(int width, int height) returns yuiRenderTarget
{
    int targetWidth = width
    int targetHeight = height
    if targetWidth <= 0 { targetWidth = 1 }
    if targetHeight <= 0 { targetHeight = 1 }
    return CreateCurrentYuiCanvasWindowTargetV1("main", targetWidth, targetHeight, "surface.canvas")
}

BuildAuthoredCompositionForCurrentProvider(yuiAuthoredRuntime runtime, yuiAuthoredApplicationLayoutPlan plan, yuiDisplayList display) returns yuiCompositionPlan
{
    yuiRenderTarget target = AuthoredWindowTarget(plan.width, plan.height)
    return BuildYuiAuthoredApplicationCompositionForTarget(runtime, plan, display, target)
}

yuiCompositionPlan composition = BuildAuthoredCompositionForCurrentProvider(interaction.authored, plan, display)
yuiRenderExecution headless = ExecuteYuiHeadlessRenderer(display, composition)
yuiRenderExecution canvasModel = ExecuteYuiCanvasDisplayList(display, composition, false)
bool rendererEquivalent = headless.StructureEquivalent(canvasModel)
Console.Log(RenderYuiCanvasDisplayListAdapterContract())
Console.Log(RenderYuiAuthoredDisplayListReport(interaction.authored, display, composition))
Console.Log(Text.Format("authored-settings-renderer-parity: equivalent={0}", rendererEquivalent))
if headless.diagnostic != "ok" or canvasModel.diagnostic != "ok" or !rendererEquivalent
{
    Process.Exit(41)
}
yuiVisualResolution retainedBackground = theme.Resolve("surface.canvas", "yeho-yui-authored-settings")
yuiAuthoredRetainedScheduler scheduler = SeedYuiAuthoredRetainedScheduler(interaction.authored, plan, display, "settings.initial")
scheduler.ConfigureLowering(interaction.authored, theme)
yuiRetainedFramePlan initialRetainedPlan = scheduler.cache.Plan()
yuiPersistentCanvasExecutionV1 retainedExecution = ExecuteYuiPersistentCanvasStoredRetainedPlanV1(scheduler.resourceStore, initialRetainedPlan, true, retainedBackground.token.colorValue.red, retainedBackground.token.colorValue.green, retainedBackground.token.colorValue.blue, "settings.initial")
bool initialPresented = scheduler.diagnostic == "ok" and retainedExecution.diagnostic == "ok" and retainedExecution.presented
Console.Log(Text.Format("authored-settings-retained-initial: owners={0}; commands={1}; rebuilt={2}; damage={3}; replay={4}; redraw={5}; present={6}; diagnostic={7}/{8}", scheduler.seededOwners, scheduler.seededCommands, initialRetainedPlan.rebuiltOwners, initialRetainedPlan.damageRegionCount, initialRetainedPlan.replayedCommands, initialRetainedPlan.redraw, retainedExecution.presented, scheduler.diagnostic, retainedExecution.diagnostic))
if !initialPresented or !YuiPersistentCanvasRetainedPlanCoversSurfaceV1(initialRetainedPlan, viewport.designWidth, viewport.designHeight) or scheduler.resourceStore.State() != "open" or scheduler.resourceStore.OwnerCount() != scheduler.seededOwners or scheduler.resourceStore.CommandCount() != scheduler.seededCommands or scheduler.resourceStore.EntryCount() == 0
{
    Process.Exit(42)
}

int started = MonotonicMicroseconds()
bool smokeClose = YuiSmokeCloseRequested()
bool verificationEvidenceRequired = Environment.Get("YEHO_YUI_AUTHORED_SETTINGS_VERIFY") == "1"
int previousWidth = viewport.designWidth
int previousHeight = viewport.designHeight
text previousHoverNodeId = interaction.input.hoverNodeId
text previousPressedNodeId = interaction.input.pressedNodeId
text previousFocusedNodeId = interaction.focus.focusedNodeId
bool observedDirtyPresent = false
bool observedIdleSkip = false
bool observedAuthoredOwnerLocal = false
bool observedIdleZero = false
bool verificationMutationInjected = false
int interactionMutationRevision = 1000000
int evidenceBindingsScanned = 0
int evidenceOwnersLowered = 0
int evidenceRebuilt = 0
int evidenceReused = 0
int evidenceDamage = 0
int evidenceReplay = 0
bool evidenceRedraw = false
bool evidencePresent = false
bool running = true
bool closeRequested = false
while running and WindowOpen()
{
    interaction.authored.BeginMutationBatch()
    viewport = CreateYuiFluidCanvasViewport(1120, 760)
    bool sizeChanged = viewport.designWidth != previousWidth or viewport.designHeight != previousHeight
    if sizeChanged
    {
        plan = ResolveYuiAuthoredApplicationLayout(interaction.authored, 0, 0, viewport.designWidth, viewport.designHeight)
        interaction.SyncLayout(plan.placements)
    }

    if verificationEvidenceRequired and observedIdleSkip and !verificationMutationInjected
    {
        yuiAuthoredAction verificationAction = interaction.Activate("SettingsStudio.Content.Preferences.Updates", "", "verification")
        interaction = ApplySettingsDomainAction(interaction, verificationAction)
        verificationMutationInjected = verificationAction.stateChanged
    }

    int sourceX = YuiViewportSourceX(viewport, MouseX())
    int sourceY = YuiViewportSourceY(viewport, MouseY())
    yuiAuthoredInteractionResult pointerMove = interaction.HandlePointer("move", "mouse.primary", sourceX, sourceY)
    yuiWindowsHostInputEvent hostEvent = hostInput.Poll()
    if hostEvent.changed and hostEvent.PointerEdge()
    {
        int eventSourceX = YuiViewportSourceX(viewport, hostEvent.pointer.localX)
        int eventSourceY = YuiViewportSourceY(viewport, hostEvent.pointer.localY)
        text pointerId = Text.Format("pointer.{0}", hostEvent.pointer.pointerId)
        if hostEvent.kind == "pointer-down"
        {
            yuiAuthoredInteractionResult pointerDown = interaction.HandlePointer("down", pointerId, eventSourceX, eventSourceY)
        }
        else if hostEvent.kind == "pointer-up"
        {
            yuiAuthoredInteractionResult pointerUp = interaction.HandlePointer("up", pointerId, eventSourceX, eventSourceY)
            interaction = ApplySettingsDomainAction(interaction, pointerUp.action)
        }
        else if hostEvent.kind == "pointer-cancel"
        {
            yuiAuthoredInteractionResult pointerCancel = interaction.HandlePointer("cancel", pointerId, eventSourceX, eventSourceY)
        }
    }

    bool tabDown = IsKeyDown("tab")
    bool leftDown = IsKeyDown("left")
    bool rightDown = IsKeyDown("right")
    bool upDown = IsKeyDown("up")
    bool downDown = IsKeyDown("down")
    bool enterDown = IsKeyDown("enter")
    bool spaceDown = IsKeyDown("space")
    bool updatesDown = hostEvent.controlDown and IsKeyDown("u")
    bool saveDown = hostEvent.controlDown and IsKeyDown("s")
    bool escapeDown = IsKeyDown("escape")
    if tabDown and !tabWasDown
    {
        text tabKey = "tab"
        if hostEvent.shiftDown
        {
            tabKey = "shift+tab"
        }
        yuiAuthoredInteractionResult tabAction = interaction.HandleKey(tabKey, "")
    }
    else if leftDown and !leftWasDown
    {
        yuiAuthoredInteractionResult leftAction = interaction.HandleKey("left", "")
    }
    else if rightDown and !rightWasDown
    {
        yuiAuthoredInteractionResult rightAction = interaction.HandleKey("right", "")
    }
    else if upDown and !upWasDown
    {
        yuiAuthoredInteractionResult upAction = interaction.HandleKey("up", "")
    }
    else if downDown and !downWasDown
    {
        yuiAuthoredInteractionResult downAction = interaction.HandleKey("down", "")
    }
    else if enterDown and !enterWasDown
    {
        yuiAuthoredInteractionResult enterAction = interaction.HandleKey("enter", "")
        interaction = ApplySettingsDomainAction(interaction, enterAction.action)
    }
    else if spaceDown and !spaceWasDown
    {
        yuiAuthoredInteractionResult spaceAction = interaction.HandleKey("space", "")
        interaction = ApplySettingsDomainAction(interaction, spaceAction.action)
    }
    else if updatesDown and !updatesWasDown
    {
        yuiAuthoredInteractionResult updatesAction = interaction.HandleKey("shortcut", "Ctrl+U")
        interaction = ApplySettingsDomainAction(interaction, updatesAction.action)
    }
    else if saveDown and !saveWasDown
    {
        yuiAuthoredInteractionResult saveAction = interaction.HandleKey("shortcut", "Ctrl+S")
        interaction = ApplySettingsDomainAction(interaction, saveAction.action)
    }
    else if escapeDown and !escapeWasDown
    {
        yuiAuthoredInteractionResult escapeAction = interaction.HandleKey("escape", "")
        closeRequested = true
    }
    tabWasDown = tabDown
    leftWasDown = leftDown
    rightWasDown = rightDown
    upWasDown = upDown
    downWasDown = downDown
    enterWasDown = enterDown
    spaceWasDown = spaceDown
    updatesWasDown = updatesDown
    saveWasDown = saveDown
    escapeWasDown = escapeDown

    bool authoredLayoutDirty = false
    for receipt in interaction.authored.dirtyReceipts
    {
        if receipt.scope == "layout" { authoredLayoutDirty = true }
    }
    if authoredLayoutDirty and !sizeChanged
    {
        plan = ResolveYuiAuthoredApplicationLayout(interaction.authored, 0, 0, viewport.designWidth, viewport.designHeight)
        interaction.SyncLayout(plan.placements)
    }
    bool hoverChanged = interaction.input.hoverNodeId != previousHoverNodeId
    bool pressedChanged = interaction.input.pressedNodeId != previousPressedNodeId
    bool focusChanged = interaction.focus.focusedNodeId != previousFocusedNodeId
    bool fullReseed = sizeChanged or authoredLayoutDirty
    if fullReseed
    {
        display = BuildYuiAuthoredApplicationDisplayList(interaction.authored, theme, plan, interaction.input.hoverNodeId, interaction.input.pressedNodeId, interaction.focus.focusedNodeId)
        composition = BuildAuthoredCompositionForCurrentProvider(interaction.authored, plan, display)
        headless = ExecuteYuiHeadlessRenderer(display, composition)
        canvasModel = ExecuteYuiCanvasDisplayList(display, composition, false)
        rendererEquivalent = rendererEquivalent and headless.StructureEquivalent(canvasModel)
        scheduler = SeedYuiAuthoredRetainedScheduler(interaction.authored, plan, display, "settings.resize-reseed")
        scheduler.ConfigureLowering(interaction.authored, theme)
        yuiRetainedFramePlan reseedPlan = scheduler.cache.Plan()
        retainedExecution = ExecuteYuiPersistentCanvasStoredRetainedPlanV1(scheduler.resourceStore, reseedPlan, true, retainedBackground.token.colorValue.red, retainedBackground.token.colorValue.green, retainedBackground.token.colorValue.blue, "settings.resize-reseed")
        observedDirtyPresent = observedDirtyPresent or retainedExecution.presented
        if headless.diagnostic != "ok" or canvasModel.diagnostic != "ok" or scheduler.diagnostic != "ok" or retainedExecution.diagnostic != "ok" or !retainedExecution.presented or !rendererEquivalent
        {
            Console.Error(Text.Format("authored-settings-renderer-error: headless={0}; canvas={1}; retained={2}/{3}; parity={4}", headless.diagnostic, canvasModel.diagnostic, scheduler.diagnostic, retainedExecution.diagnostic, rendererEquivalent))
            Process.Exit(43)
        }
    }
    else
    {
        if !scheduler.BeginTick(interaction.authored, "settings.owner-update")
        {
            Console.Error(scheduler.diagnostic)
            Process.Exit(43)
        }
        list of text scheduledVisualOwners = []
        int authoredReceiptCount = interaction.authored.dirtyReceipts.count
        if !scheduler.ApplyDirtyBatch(interaction.authored, theme, plan, interaction.input.hoverNodeId, interaction.input.pressedNodeId, interaction.focus.focusedNodeId)
        {
            Console.Error(scheduler.diagnostic)
            Process.Exit(43)
        }
        for receipt in interaction.authored.dirtyReceipts
        {
            if receipt.scope != "semantic"
            {
                scheduledVisualOwners = SettingsAddDirtyOwner(scheduledVisualOwners, receipt.ownerId)
            }
        }
        if authoredReceiptCount > 0
        {
            yuiRetainedFramePlan authoredOnlyPlan = scheduler.cache.Plan()
            observedAuthoredOwnerLocal = scheduler.changedBindingsScanned == interaction.authored.lastMutationBindingsScanned and scheduler.receiptsScheduled == authoredReceiptCount and scheduler.ownersLowered == interaction.authored.lastMutationOwnersAffected and scheduler.resourceValidations == 0 and scheduler.resourcePayloadComparisons == 0 and scheduler.resourceEntriesAdded == 0 and authoredOnlyPlan.touchedOwners == interaction.authored.lastMutationOwnersAffected and authoredOnlyPlan.rebuiltOwners <= scheduler.ownersLowered
            evidenceBindingsScanned = scheduler.changedBindingsScanned
            evidenceOwnersLowered = scheduler.ownersLowered
            evidenceRebuilt = authoredOnlyPlan.rebuiltOwners
            evidenceReused = authoredOnlyPlan.reusedOwners
            evidenceDamage = authoredOnlyPlan.damageRegionCount
            evidenceReplay = authoredOnlyPlan.replayedCommands
            evidenceRedraw = authoredOnlyPlan.redraw
        }
        list of text interactionDirtyOwners = []
        if hoverChanged
        {
            interactionDirtyOwners = SettingsAddDirtyOwner(interactionDirtyOwners, previousHoverNodeId)
            interactionDirtyOwners = SettingsAddDirtyOwner(interactionDirtyOwners, interaction.input.hoverNodeId)
        }
        if pressedChanged
        {
            interactionDirtyOwners = SettingsAddDirtyOwner(interactionDirtyOwners, previousPressedNodeId)
            interactionDirtyOwners = SettingsAddDirtyOwner(interactionDirtyOwners, interaction.input.pressedNodeId)
        }
        if focusChanged
        {
            interactionDirtyOwners = SettingsAddDirtyOwner(interactionDirtyOwners, previousFocusedNodeId)
            interactionDirtyOwners = SettingsAddDirtyOwner(interactionDirtyOwners, interaction.focus.focusedNodeId)
        }
        for ownerId in interactionDirtyOwners
        {
            if scheduler.cache.IndexOf(ownerId) >= 0 and !SettingsHasDirtyOwner(scheduledVisualOwners, ownerId)
            {
                interactionMutationRevision = interactionMutationRevision + 1
                yuiAuthoredDirtyReceipt interactionReceipt = CreateYuiAuthoredDirtyReceipt(ownerId, "interaction.visual", "paint", interactionMutationRevision, "settings.interaction")
                if !scheduler.ApplyReceipt(interaction.authored, theme, plan, interactionReceipt, interaction.input.hoverNodeId, interaction.input.pressedNodeId, interaction.focus.focusedNodeId)
                {
                    Console.Error(scheduler.diagnostic)
                    Process.Exit(43)
                }
                scheduledVisualOwners = SettingsAddDirtyOwner(scheduledVisualOwners, ownerId)
            }
        }
        yuiRetainedFramePlan retainedPlan = scheduler.cache.Plan()
        retainedExecution = ExecuteYuiPersistentCanvasStoredRetainedPlanV1(scheduler.resourceStore, retainedPlan, false, retainedBackground.token.colorValue.red, retainedBackground.token.colorValue.green, retainedBackground.token.colorValue.blue, "settings.owner-update")
        if retainedExecution.diagnostic != "ok"
        {
            Console.Error(Text.Format("authored-settings-retained-error: {0}", retainedExecution.diagnostic))
            Process.Exit(43)
        }
        if retainedPlan.present
        {
            observedDirtyPresent = observedDirtyPresent or retainedExecution.presented
        }
        if authoredReceiptCount > 0 { evidencePresent = retainedExecution.presented }
        if retainedPlan.Idle() and scheduler.changedBindingsScanned == 0 and scheduler.ownersLowered == 0 and scheduler.commandsLowered == 0 and scheduler.resourceValidations == 0 and scheduler.resourceExplicitComparisons == 0 and scheduler.resourcePayloadComparisons == 0 and scheduler.resourceAdmissions == 0 and scheduler.resourceEntriesAdded == 0 and !retainedExecution.rendered and !retainedExecution.presented
        {
            observedIdleSkip = true
            observedIdleZero = true
        }
    }
    previousWidth = viewport.designWidth
    previousHeight = viewport.designHeight
    previousHoverNodeId = interaction.input.hoverNodeId
    previousPressedNodeId = interaction.input.pressedNodeId
    previousFocusedNodeId = interaction.focus.focusedNodeId
    int elapsed = MonotonicMicroseconds() - started
    bool verificationClose = verificationEvidenceRequired and elapsed >= 3000000
    if closeRequested or verificationClose or smokeClose and elapsed >= YuiSmokeCloseAfterMicroseconds()
    {
        running = false
        CloseWindow()
    }
}
Console.Log(Text.Format("authored-settings-retained-owner-evidence: bindings-scanned={0}; owners-lowered={1}; rebuilt={2}; reused={3}; damage={4}; replay={5}; redraw={6}; present={7}; owner-local={8}", evidenceBindingsScanned, evidenceOwnersLowered, evidenceRebuilt, evidenceReused, evidenceDamage, evidenceReplay, evidenceRedraw, evidencePresent, observedAuthoredOwnerLocal))
Console.Log(Text.Format("authored-settings-retained-idle-evidence: scanned=0; lowered=0; rebuilt=0; damage=0; replay=0; redraw=false; present=false; observed={0}", observedIdleZero))
Console.Log(Text.Format("authored-settings-frame-evidence: initial-present={0}; dirty-present={1}; idle-skip={2}; parity={3}; diagnostic={4}", initialPresented, observedDirtyPresent, observedIdleSkip, rendererEquivalent, retainedExecution.diagnostic))
if !initialPresented or !rendererEquivalent or retainedExecution.diagnostic != "ok" or (verificationEvidenceRequired and (!verificationMutationInjected or !observedDirtyPresent or !observedIdleSkip or !observedAuthoredOwnerLocal or !observedIdleZero))
{
    Process.Exit(44)
}

```

Save this beside start.yh as project.mech:

```toml
manifestVersion = "2"
package = "api.example.yui_settings"
version = "0.1.0"
languageEdition = "yeho-core-2026.1"

[app]
kind = "frontend"
console = false

[frontend]
kind = "yui"
entry = "ui/app.yui"

[[dependencies]]
package = "frontend.yui"
version = "0.2.0"
path = "../../../yeho/packages/frontend/yui"

[[dependencies]]
package = "frontend.yui.host.window"
version = "0.2.0"
path = "../../../yeho/packages/frontend/yui/host/window"

[[dependencies]]
package = "frontend.yui.host.windows"
version = "0.2.0"
path = "../../../yeho/packages/frontend/yui/host/windows"

[[dependencies]]
package = "graphics.canvas"
version = "0.1.0"
path = "../../../yeho/packages/graphics/canvas"

[[dependencies]]
package = "graphics.image"
version = "0.1.0"
path = "../../../yeho/packages/graphics/image"

[[dependencies]]
package = "graphics.image.processing"
version = "0.1.0"
path = "../../../yeho/packages/graphics/image/processing"

[[dependencies]]
package = "graphics.text"
version = "0.1.0"
path = "../../../yeho/packages/graphics/text"

[[dependencies]]
package = "graphics.text.windows"
version = "0.1.0"
path = "../../../yeho/packages/graphics/text/windows"

[[dependencies]]
package = "host.ui_services"
version = "0.1.0"
path = "../../../yeho/packages/host/ui_services"

[[dependencies]]
package = "host.windows"
version = "0.1.0"
path = "../../../yeho/packages/host/windows"

[[dependencies]]
package = "input.keyboard"
version = "0.1.0"
path = "../../../yeho/packages/input/keyboard"

[[dependencies]]
package = "input.mouse"
version = "0.1.0"
path = "../../../yeho/packages/input/mouse"

[[dependencies]]
package = "input.text"
version = "0.1.0"
path = "../../../yeho/packages/input/text"

[[dependencies]]
package = "time"
version = "0.1.0"
path = "../../../yeho/packages/time"

[[dependencies]]
package = "ui"
version = "0.2.0"
path = "../../../yeho/packages/ui"

[[dependencies]]
package = "window"
version = "0.1.0"
path = "../../../yeho/packages/window"

[[dependencies]]
package = "window.multi"
version = "0.1.0"
path = "../../../yeho/packages/window/multi"

```

Extract the example archive beside the yeho and dolphin checkouts. This example requires those source dependencies and a current developer compiler.

Use the documented Windows YUI launcher and native host; a CPU oracle type check does not qualify that host.


### ui/app.yui

```
import "components/settings-section.yui"

commands SettingsCommands {
    settings.save = command
    settings.toggleCompact = command
    settings.toggleUpdates = command
}

state SettingsState {
    profile.name = "Ari Morgan"
    profile.email = "ari@starfish.local"
    preferences.compact = false
    preferences.updates = true
}

slots SettingsSlots {
    settings.profile = one
    settings.preferences = one
    settings.about = one
}

surface SettingsStudio {
    label = "Settings Studio"
    theme = modern-dark
    density = comfortable
    layout = column

    column Content {
        spacing = 12
        label Eyebrow { text = "YEHO / YUI" }
        label Title { text = "A calmer way to build software" }
        label Subtitle { text = "This entire screen is lowered from modular .yui into one shared runtime tree." }

        SettingsSection Profile {
            heading = "Profile"
            theme = modern-dark
            slot = settings.profile
            slot Content {
                textBox Name { label = "Display name" value = profile.name }
                textBox Email { label = "Email" value = profile.email }
            }
        }

        SettingsSection Preferences {
            heading = "Preferences"
            tone = "interactive"
            slot = settings.preferences
            slot Content {
                toggle Compact { text = "Compact interface" checked = preferences.compact command = settings.toggleCompact }
                toggle Updates { text = "Experimental updates" checked = preferences.updates command = settings.toggleUpdates }
            }
        }

        SettingsSection About {
            heading = "Runtime"
            slot = settings.about
            slot Content {
                label Backend { text = "Kyber-ready, renderer-independent component state" }
            }
        }

        button Save { text = "Save settings" command = settings.save onClick = settings.save }
    }
}

```


### ui/components/settings-section.yui

```
component SettingsSection {
    property heading { type = text required = true }
    property tone { type = text default = "quiet" }
    slot Content { required = true }
}

```


The compiler validates widget names, properties, bindings, commands, and source spans before rendering.

Programmatic definitions and .yui documents lower to the same typed widget model and retained scene.

Source: yeho/docs/teaching/first-yui-app.md; packages/frontend/yui/widget-definitions.inc

AI training permission: https://demonhunterlabs.com/ai-use