Private/Runtime.ps1

# NativeHTMLKit.UI 0.1: language-native UI state and public-SDK-only document adapter.
# PowerShell 5.1 and 7.2+ compatible. No C# helper, Core protocol, or separate event pump.
#
# Scoping rule for this module: never hand a scriptblock made with .GetNewClosure() to code that
# must call this module's private functions. GetNewClosure() binds the block to a NEW dynamic
# module whose parent is the global scope, so private helpers are not visible inside it.
# Internal callbacks are therefore module-bound literals that receive their context as an argument,
# and the one closure handed to the SDK (document events) re-enters this module explicitly.

# Depth of nested State.Set calls on this runspace and the UIs that have pending writes. A change
# that cascades through computed states is written once, when the outermost Set returns.
$script:NHKUiSetDepth = 0
$script:NHKUiDirty = New-Object System.Collections.ArrayList

function New-NHKUiState {
    [CmdletBinding()] param([AllowNull()]$Value)
    $s = [pscustomobject]@{ Value = $Value; Listeners = (New-Object System.Collections.ArrayList) }
    $s.PSObject.TypeNames.Insert(0, 'NativeHTMLKit.UI.State')
    $s | Add-Member -MemberType ScriptMethod -Name Set -Value {
        param($Next)
        if ([object]::Equals($this.Value, $Next)) { return }
        $this.Value = $Next
        $script:NHKUiSetDepth++
        try {
            foreach ($subscription in @($this.Listeners.ToArray())) {
                if ($subscription.Active) { $null = & $subscription.Callback $Next $subscription.Context }
            }
        } finally {
            $script:NHKUiSetDepth--
            if ($script:NHKUiSetDepth -eq 0 -and $script:NHKUiDirty.Count -gt 0) { Sync-NHKUiDirty }
        }
    }
    $s | Add-Member -MemberType ScriptMethod -Name Subscribe -Value {
        # The callback receives ($newValue, $Context).
        param([scriptblock]$Callback, $Context)
        $subscription = [pscustomobject]@{ Callback = $Callback; Context = $Context; Active = $true }
        [void]$this.Listeners.Add($subscription)
        return $subscription
    }
    $s | Add-Member -MemberType ScriptMethod -Name Unsubscribe -Value {
        param($Subscription)
        if ($null -eq $Subscription) { return }
        $Subscription.Active = $false
        [void]$this.Listeners.Remove($Subscription)
    }
    return $s
}

function Test-NHKUiState {
    param($Value)
    return ($null -ne $Value -and $Value -is [psobject] -and $Value.PSObject.TypeNames[0] -eq 'NativeHTMLKit.UI.State')
}

function New-NHKUiComputed {
    <# Explicit dependencies avoid PowerShell AST/proxy instrumentation. #>
    [CmdletBinding()] param(
        [Parameter(Mandatory)][scriptblock]$Compute,
        [Parameter(Mandatory)][object[]]$DependsOn,
        [AllowNull()]$Data
    )
    foreach ($dep in $DependsOn) {
        if (-not (Test-NHKUiState $dep)) { throw 'DependsOn must contain only NativeHTMLKit.UI.State objects' }
    }
    $s = New-NHKUiState -Value (& $Compute $Data)
    $tokens = New-Object System.Collections.ArrayList
    $context = [pscustomobject]@{ Computed = $s; Compute = $Compute; Data = $Data; Busy = $false }
    $recompute = {
        param($ignored, $ctx)
        if ($ctx.Busy) { throw 'Circular computed-state dependency' }
        $ctx.Busy = $true
        try { $ctx.Computed.Set((& $ctx.Compute $ctx.Data)) } finally { $ctx.Busy = $false }
    }
    foreach ($dep in $DependsOn) {
        $sub = $dep.Subscribe($recompute, $context)
        [void]$tokens.Add([pscustomobject]@{ State = $dep; Token = $sub })
    }
    $s | Add-Member -NotePropertyName DependencyTokens -NotePropertyValue $tokens
    $s | Add-Member -MemberType ScriptMethod -Name Dispose -Value {
        foreach ($entry in @($this.DependencyTokens.ToArray())) {
            $entry.State.Unsubscribe($entry.Token)
        }
        $this.DependencyTokens.Clear()
    }
    return $s
}

function New-NHKUi {
    [CmdletBinding()] param(
        [string]$Title = 'NativeHTMLKit UI', [ValidateRange(100,8192)][int]$Width = 940,
        [ValidateRange(100,8192)][int]$Height = 660,
        [ValidateSet('cobalt','graphite','daylight')][string]$Theme = 'cobalt',
        [ValidateSet('compact','regular','comfortable')][string]$Density = 'compact',
        [string]$ExtraCss = ''
    )
    $ui = [pscustomobject]@{
        Title = $Title; Width = $Width; Height = $Height; Theme = $Theme; Density = $Density
        ExtraCss = $ExtraCss; Prefix = ('nhkui-' + [guid]::NewGuid().ToString('N').Substring(0,12))
        NextId = 0; Root = $null; Stack = (New-Object System.Collections.ArrayList)
        Bindings = (New-Object System.Collections.ArrayList)
        Handlers = @{}; Pending = (New-Object System.Collections.Specialized.OrderedDictionary)
        Subscriptions = (New-Object System.Collections.ArrayList)
        Window = $null; Document = $null; Application = $null
        InEvent = 0; Syncing = $false; Disposed = $false; LastError = $null; DomUncertain = $false
        Errors = [long]0; Updates = [long]0; Operations = [long]0; Discarded = [long]0
        OwnerRunspaceId = $null
    }
    $ui.PSObject.TypeNames.Insert(0, 'NativeHTMLKit.UI.App')
    $ui.NextId++
    $ui.Root = [pscustomobject]@{
        Tag='main'; Id=($ui.Prefix + '-' + $ui.NextId); Attrs=@{ class='nhk-app' }
        Children=(New-Object System.Collections.ArrayList); Text=$null; Raw=$null
    }
    [void]$ui.Stack.Add($ui.Root)
    return $ui
}

function Assert-NHKUiOwner {
    param($UI)
    if ($UI.Disposed) { throw 'NativeHTMLKit UI has been disposed' }
    if ($UI.OwnerRunspaceId -and [runspace]::DefaultRunspace.InstanceId -ne $UI.OwnerRunspaceId) {
        throw 'UI updates must run on the SDK owning runspace (use SDK task completion callbacks)'
    }
}

function Add-NHKUiElementInternal {
    param($UI, [string]$Tag, [hashtable]$Attrs=@{}, [AllowNull()]$Text=$null, [AllowNull()]$Raw=$null)
    Assert-NHKUiOwner $UI
    if ($null -ne $UI.Document) { throw 'The UI tree is already mounted; change State rather than adding components' }
    if ($Tag -notin @('div','section','main','header','footer','article','nav','aside','p','span',
                     'h1','h2','h3','h4','button','label','input','select','option','ul','li',
                     'table','thead','tbody','tr','th','td','dialog','pre','code','small','strong')) {
        throw "Unsupported element '$Tag'; use Add-NHKUiHtml for trusted custom markup"
    }
    $UI.NextId++
    $node = [pscustomobject]@{
        Tag = $Tag; Id = ($UI.Prefix + '-' + $UI.NextId); Attrs = $Attrs
        Children = (New-Object System.Collections.ArrayList); Text = $Text; Raw = $Raw
    }
    $parent = $UI.Stack[$UI.Stack.Count-1]
    [void]$parent.Children.Add($node)
    return $node
}

function Move-NHKUiNodeBefore {
    # Reorders two siblings so that $Node comes directly before $Before (labels precede controls).
    param($Parent, $Node, $Before)
    $Parent.Children.Remove($Node)
    $Parent.Children.Insert($Parent.Children.IndexOf($Before), $Node)
}

# Runs on the state's owner when a bound State changes; $ctx = @{UI; Binding}.
$script:NHKUiBindingChanged = {
    param($ignored, $ctx)
    $ui = $ctx.UI
    if ($ui.Disposed) { return }
    Assert-NHKUiOwner $ui
    $b = $ctx.Binding
    $ui.Pending[$b.Key] = $b
    if ($null -ne $ui.Document -and $ui.InEvent -eq 0 -and -not $script:NHKUiDirty.Contains($ui)) {
        [void]$script:NHKUiDirty.Add($ui)  # written when the outermost State.Set returns
    }
}

function Sync-NHKUiDirty {
    $uis = @($script:NHKUiDirty.ToArray())
    $script:NHKUiDirty.Clear()
    $failure = $null
    foreach ($ui in $uis) {
        if ($ui.Disposed -or $ui.InEvent -gt 0) { continue }
        try { Sync-NHKUi -UI $ui } catch { if ($null -eq $failure) { $failure = $_ } }
    }
    if ($null -ne $failure) { throw $failure }
}

function Invoke-NHKUiBatch {
    <#
    .SYNOPSIS
    Runs a scriptblock and writes all resulting UI changes once at the end (one batched update).
    .DESCRIPTION
    Event callbacks are batched automatically. Use this for many State changes made outside a
    callback (for example in a loop after a task completed). Runs on the owning runspace.
    #>

    [CmdletBinding()] param([Parameter(Mandatory)]$UI, [Parameter(Mandatory)][scriptblock]$ScriptBlock)
    Assert-NHKUiOwner $UI
    $UI.InEvent++
    try { & $ScriptBlock }
    finally {
        $UI.InEvent--
        if (-not $UI.Disposed -and $UI.InEvent -eq 0) { Sync-NHKUi -UI $UI }
    }
}

function Add-NHKUiBindingInternal {
    param($UI, $Node, $State, [string]$Kind, [string]$Name='')
    if (-not (Test-NHKUiState $State)) {
        throw "A -Bind argument must be created with New-NHKUiState or New-NHKUiComputed"
    }
    $binding = [pscustomobject]@{
        Id = $Node.Id; Kind = $Kind; Name = $Name; State = $State; Key = ($Node.Id + '|' + $Kind + '|' + $Name)
        Last = $State.Value; Subscription = $null
    }
    $binding.Subscription = $State.Subscribe($script:NHKUiBindingChanged, [pscustomobject]@{ UI = $UI; Binding = $binding })
    [void]$UI.Bindings.Add($binding)
    return $binding
}

function ConvertTo-NHKUiEncoded {
    param([AllowNull()][object]$Value)
    if ($null -eq $Value) { return '' }
    return [System.Net.WebUtility]::HtmlEncode([string]$Value)
}

function ConvertTo-NHKUiListMarkup {
    param([AllowNull()]$Value)
    $result = New-Object System.Text.StringBuilder
    if ($null -eq $Value) { return '' }
    foreach ($entry in @($Value)) {
        [void]$result.Append('<li>')
        [void]$result.Append((ConvertTo-NHKUiEncoded $entry))
        [void]$result.Append('</li>')
    }
    return $result.ToString()
}

function ConvertTo-NHKUiNodeHtml {
    param($Node)
    $builder = New-Object System.Text.StringBuilder
    [void]$builder.Append('<').Append($Node.Tag)
    $attrs = @{}; foreach ($key in $Node.Attrs.Keys) { $attrs[[string]$key] = $Node.Attrs[$key] }
    $attrs.id = $Node.Id
    foreach ($name in ($attrs.Keys | Sort-Object)) {
        if ($name -cnotmatch '^[A-Za-z_:][A-Za-z0-9_:.-]*$' -or $name -match '^(?i:on)') {
            throw "Unsafe HTML attribute name '$name'"
        }
        $value = $attrs[$name]
        if ($null -eq $value -or ($value -is [bool] -and -not $value)) { continue }
        if ($value -is [bool]) { [void]$builder.Append(' ').Append($name) }
        else {
            [void]$builder.Append(' ').Append($name).Append('="')
            [void]$builder.Append((ConvertTo-NHKUiEncoded $value)).Append('"')
        }
    }
    [void]$builder.Append('>')
    if ($Node.Tag -eq 'input') { return $builder.ToString() }
    if ($null -ne $Node.Raw) { [void]$builder.Append($Node.Raw) }
    elseif ($null -ne $Node.Text) { [void]$builder.Append((ConvertTo-NHKUiEncoded $Node.Text)) }
    foreach ($child in $Node.Children) { [void]$builder.Append((ConvertTo-NHKUiNodeHtml $child)) }
    [void]$builder.Append('</').Append($Node.Tag).Append('>')
    return $builder.ToString()
}

function Get-NHKUiHtml {
    [CmdletBinding()] param([Parameter(Mandatory)]$UI)
    if ($UI.Stack.Count -ne 1) { throw 'UI contains an unclosed container' }
    $cssFile = Join-Path $script:NHKUiModuleRoot 'assets/ui.css'
    $css = [IO.File]::ReadAllText($cssFile, [Text.Encoding]::UTF8)
    return ('<!doctype html><html lang="en"><head><meta charset="utf-8">' +
        '<meta name="viewport" content="width=device-width,initial-scale=1">' +
        '<title>' + (ConvertTo-NHKUiEncoded $UI.Title) + '</title><style>' + $css + "`n" +
        $UI.ExtraCss + '</style></head><body class="nhk-theme-' + $UI.Theme +
        ' nhk-density-' + $UI.Density + '">' + (ConvertTo-NHKUiNodeHtml $UI.Root) + '</body></html>')
}

function Register-NHKUiActionInternal {
    param($UI, $Node, [string]$Kind, [scriptblock]$Callback, [AllowNull()]$Data)
    if ($Kind -notin @('click','input','change','keydown','submit','auxclick','contextmenu')) {
        throw "Unsupported event type '$Kind'"
    }
    if (-not $UI.Handlers.ContainsKey($Kind)) { $UI.Handlers[$Kind] = @{} }
    $UI.Handlers[$Kind][$Node.Id] = [pscustomobject]@{ Callback = $Callback; Data = $Data }
}

function Get-NHKUiEventField {
    # Event objects are PSCustomObjects from the SDK's JSON reader; tolerate missing members.
    param($EventObject, [string]$Name)
    if ($null -eq $EventObject) { return $null }
    if ($EventObject -is [System.Collections.IDictionary]) { return $EventObject[$Name] }
    $property = $EventObject.PSObject.Properties[$Name]
    if ($null -eq $property) { return $null }
    return $property.Value
}

function Invoke-NHKUiEventInternal {
    param($UI, [string]$Kind, $EventObject)
    if ($UI.Disposed) { return }
    Assert-NHKUiOwner $UI
    $handlers = $UI.Handlers[$Kind]
    if ($null -eq $handlers) { return }
    $path = New-Object System.Collections.ArrayList
    $target = [string](Get-NHKUiEventField $EventObject 'element')
    if ($target) { [void]$path.Add($target) }
    foreach ($item in @(Get-NHKUiEventField $EventObject 'path')) { if ($item) { [void]$path.Add([string]$item) } }
    foreach ($id in $path) {
        if ($handlers.ContainsKey([string]$id)) {
            $UI.InEvent++
            try {
                $entry = $handlers[[string]$id]
                $null = & $entry.Callback $EventObject $entry.Data
            } catch {
                $UI.Errors++
                $UI.LastError = $_.Exception.Message
                throw
            } finally {
                $UI.InEvent--
                if (-not $UI.Disposed -and $UI.InEvent -eq 0) { Sync-NHKUi -UI $UI }
            }
            break  # nearest registered element on the route, like a delegated handler
        }
    }
}

function Test-NHKUiStaleError {
    # True when an SDK call failed because the window/document is no longer current (closed,
    # replaced, or app.shutdown): the SDK's documented NativeHTMLKit.StaleObjectException.
    param($ErrorRecordOrException)
    $e = $ErrorRecordOrException
    if ($e -is [System.Management.Automation.ErrorRecord]) { $e = $e.Exception }
    while ($null -ne $e) {
        $type = $e.GetType().FullName
        if ($type -eq 'NativeHTMLKit.StaleObjectException') { return $true }
        # Definite host rejections (not outcome-unknown): -32004 window/document gone, -32008 the
        # application is shutting down (protocol v1 section 5). The write was not applied.
        if ($type -eq 'NativeHTMLKit.RpcException' -and $null -ne $e.PSObject.Properties['Code'] -and
            (@(-32004, -32008) -contains [int]$e.Code)) { return $true }
        $e = $e.InnerException
    }
    return $false
}

function Sync-NHKUi {
    <# Apply only changed bound properties. Call from the owning runspace. #>
    [CmdletBinding()] param([Parameter(Mandatory)]$UI)
    if ($UI.Disposed) { return }
    Assert-NHKUiOwner $UI
    if ($null -eq $UI.Document) { return }
    if ($UI.DomUncertain) { throw 'UI DOM state is uncertain after a failed operation; do not continue managed updates' }
    # An SDK RPC wait outside a callback pumps host messages, so a document event (and its state
    # changes) can run while this function is writing. Such a nested call only queues; the outer
    # loop below applies its changes afterwards, so an older value never overwrites a newer one.
    if ($UI.Syncing) { return }
    $UI.Syncing = $true
    try {
        while ($UI.Pending.Count -gt 0 -and -not $UI.Disposed) {
            $pending = @($UI.Pending.Values)
            $UI.Pending.Clear()
            Invoke-NHKUiWrites -UI $UI -Pending $pending
        }
    } finally { $UI.Syncing = $false }
}

function Invoke-NHKUiWrites {
    param($UI, [object[]]$Pending)
    $ops = New-Object System.Collections.ArrayList
    $special = New-Object System.Collections.ArrayList
    foreach ($b in $Pending) {
        $next = $b.State.Value
        if ([object]::Equals($next, $b.Last)) { continue }
        $b.Last = $next
        switch ($b.Kind) {
            'text' { [void]$ops.Add(@{op='set_text';element=$b.Id;text=[string]$next}) }
            'visible' {
                $op = if ([bool]$next) { 'remove_class' } else { 'add_class' }
                [void]$ops.Add(@{op=$op;element=$b.Id;name='nhk-hidden'})
            }
            'disabled' {
                if ([bool]$next) { [void]$ops.Add(@{op='set_attribute';element=$b.Id;name='disabled';value=''}) }
                else { [void]$ops.Add(@{op='remove_attribute';element=$b.Id;name='disabled'}) }
            }
            'list' { [void]$ops.Add(@{op='replace_children_html';element=$b.Id;html=(ConvertTo-NHKUiListMarkup $next)}) }
            default { [void]$special.Add([pscustomobject]@{Binding=$b;Value=$next}) }
        }
    }
    if ($ops.Count -eq 0 -and $special.Count -eq 0) { return }
    $UI.Updates++
    # Failed or outcome-unknown writes are never retried or ignored: the DOM may differ from state.
    try {
        for ($i=0; $i -lt $ops.Count; $i+=128) {
            $len = [Math]::Min(128, $ops.Count-$i)
            $block = New-Object 'object[]' $len
            for ($j=0; $j -lt $len; $j++) { $block[$j] = $ops[$i+$j] }
            Invoke-NativeHTMLKitBatch -Document $UI.Document -Operations $block
            $UI.Operations += $len
        }
        foreach ($entry in $special) {
            switch ($entry.Binding.Kind) {
                'value' { Set-NativeHTMLKitDocumentValue -Document $UI.Document -Element $entry.Binding.Id -Value ([string]$entry.Value) }
                'checked' { Set-NativeHTMLKitChecked -Document $UI.Document -Element $entry.Binding.Id -Checked ([bool]$entry.Value) }
            }
            $UI.Operations++
        }
    } catch {
        if (Test-NHKUiStaleError $_) {
            # A closed window, replaced document or shut-down application ends managed updates
            # quietly: no DOM is left to keep in sync, so this is disposal, not an uncertain state.
            # (A timeout or disconnect is different: its outcome is unknown and is reported below.)
            $UI.Discarded++
            Stop-NHKUi -UI $UI
            return
        }
        $UI.DomUncertain = $true
        $UI.Errors++
        $UI.LastError = $_.Exception.Message
        throw
    }
}

function Get-NHKUiDiagnostics {
    [CmdletBinding()] param([Parameter(Mandatory)]$UI)
    return [pscustomobject]@{
        DomUncertain = [bool]$UI.DomUncertain
        LastError = $UI.LastError
        Errors = [long]$UI.Errors
        PendingUpdates = [int]$UI.Pending.Count
        Updates = [long]$UI.Updates
        Operations = [long]$UI.Operations
        Subscriptions = [int]$UI.Subscriptions.Count
        DiscardedAfterClose = [long]$UI.Discarded
        Disposed = [bool]$UI.Disposed
    }
}

# Internal input/checkbox/select handler; $ctx = @{UI; State; Binding; Target; Kind}.
$script:NHKUiControlChanged = {
    param($eventObject, $ctx)
    $ui = $ctx.UI
    if ($ctx.Kind -eq 'checked') {
        $v = Get-NHKUiEventField $eventObject 'checked'
        if ($null -eq $v) { $v = Get-NativeHTMLKitChecked -Document $ui.Document -Element $ctx.Target }
        $v = [bool]$v
    } else {
        $v = Get-NHKUiEventField $eventObject 'value'
        if ($null -eq $v) { $v = Get-NativeHTMLKitValue -Document $ui.Document -Element $ctx.Target }
        $v = [string]$v
    }
    # Native input is authoritative: record it first so no echo write resets caret/selection/IME.
    $ctx.Binding.Last = $v
    $ctx.State.Set($v)
}

function Start-NHKUi {
    [CmdletBinding()] param([Parameter(Mandatory)]$UI, [Parameter(Mandatory)]$Application, [switch]$NoReady)
    if ($null -ne $UI.Document) { throw 'UI already started' }
    Assert-NHKUiOwner $UI
    if ($UI.Stack.Count -ne 1) { throw 'UI contains an unclosed container' }
    $UI.OwnerRunspaceId = [runspace]::DefaultRunspace.InstanceId
    $UI.Application = $Application
    $html = Get-NHKUiHtml -UI $UI
    # NativeHTMLKit is an installed *SDK*, not an internal Core binding.
    $UI.Window = New-NativeHTMLKitWindow -Application $Application -Title $UI.Title -Width $UI.Width -Height $UI.Height
    try {
        $UI.Document = Open-NativeHTMLKitHtml -Window $UI.Window -Html $html
        foreach ($binding in @($UI.Bindings.ToArray())) {
            if ($binding.Kind -eq 'value') {
                Set-NativeHTMLKitDocumentValue -Document $UI.Document -Element $binding.Id -Value ([string]$binding.Last)
            } elseif ($binding.Kind -eq 'checked') {
                Set-NativeHTMLKitChecked -Document $UI.Document -Element $binding.Id -Checked ([bool]$binding.Last)
            }
        }
        # If a state changed after its markup was constructed, apply it now.
        foreach ($binding in @($UI.Bindings.ToArray())) { $UI.Pending[$binding.Key] = $binding }
        Sync-NHKUi -UI $UI
        $module = $ExecutionContext.SessionState.Module
        foreach ($kind in @($UI.Handlers.Keys)) {
            $localUi = $UI; $localKind = [string]$kind
            # The SDK only passes the event object, so this one callback is a closure; it re-enters
            # this module explicitly because a closure cannot see the module's private functions.
            $callback = {
                param($eventObject)
                & $module Invoke-NHKUiEventInternal -UI $localUi -Kind $localKind -EventObject $eventObject
            }.GetNewClosure()
            $sub = Register-NativeHTMLKitDocumentEvent -Document $UI.Document -Type $localKind -Callback $callback
            [void]$UI.Subscriptions.Add($sub)
        }
        if (-not $NoReady) { Set-NativeHTMLKitReady -Application $Application }
    } catch {
        $UI.LastError = $_.Exception.Message
        Stop-NHKUi -UI $UI
        throw
    }
    return $UI.Window
}

function Stop-NHKUi {
    [CmdletBinding()] param([Parameter(Mandatory)]$UI)
    if ($UI.Disposed) { return }
    $UI.Disposed = $true
    foreach ($sub in @($UI.Subscriptions.ToArray())) {
        try { Unregister-NativeHTMLKitDocumentEvent -Subscription $sub } catch { }
    }
    $UI.Subscriptions.Clear()
    foreach ($binding in @($UI.Bindings.ToArray())) {
        $binding.State.Unsubscribe($binding.Subscription)
    }
    $UI.Pending.Clear()
    # Does not close SDK window/application; the caller controls SDK lifecycle.
}