@mpgd/cli 0.46.1 → 0.48.0

package/native-tools/windows-msix/WindowsMsixAcceptance.psm1

@@ -0,0 +1,333 @@
+# Reusable isolated Windows MSIX acceptance. Game policy belongs to the caller.
+Set-StrictMode -Version Latest
+
+function Get-PeMachine {
+    param([Parameter(Mandatory = $true)][string]$Path)
+    $bytes = [IO.File]::ReadAllBytes($Path)
+    if ($bytes.Length -lt 64 -or $bytes[0] -ne 0x4D -or $bytes[1] -ne 0x5A) {
+        throw "Not a PE image: $Path"
+    }
+    $offset = [BitConverter]::ToInt32($bytes, 0x3C)
+    if ($offset -lt 64 -or $offset -gt $bytes.Length - 6 -or
+        $bytes[$offset] -ne 0x50 -or $bytes[$offset + 1] -ne 0x45 -or
+        $bytes[$offset + 2] -ne 0 -or $bytes[$offset + 3] -ne 0) {
+        throw "Invalid PE header: $Path"
+    }
+    return [BitConverter]::ToUInt16($bytes, $offset + 4)
+}
+
+function Test-PathWithin {
+    param([string]$Path, [string]$Root)
+    $prefix = [IO.Path]::GetFullPath($Root).TrimEnd('\', '/') + [IO.Path]::DirectorySeparatorChar
+    return [IO.Path]::GetFullPath($Path).StartsWith($prefix, [StringComparison]::OrdinalIgnoreCase)
+}
+
+function Assert-MsixPayload {
+    param([string]$Directory, [string]$Identity, [string]$Publisher,
+          [ValidateSet('x64', 'ARM64')][string]$Architecture)
+    [xml]$manifest = Get-Content -LiteralPath (Join-Path $Directory 'AppxManifest.xml') -Raw
+    $packageIdentity = $manifest.Package.Identity
+    if ($packageIdentity.Name -cne $Identity -or $packageIdentity.Publisher -cne $Publisher -or
+        $packageIdentity.ProcessorArchitecture -ine $Architecture) {
+        throw 'MSIX identity, publisher or architecture does not match the selected game.'
+    }
+    $applications = @($manifest.Package.Applications.Application)
+    if ($applications.Count -ne 1) { throw 'Expected one packaged native application.' }
+    $application = $applications[0]
+    $executable = [string]$application.Executable
+    if (-not $executable.EndsWith('.exe', [StringComparison]::OrdinalIgnoreCase) -or
+        [IO.Path]::IsPathRooted($executable) -or $executable -match '(^|[\\/])\.\.([\\/]|$)') {
+        throw 'The manifest does not name a safe relative native executable.'
+    }
+    $executablePath = Join-Path $Directory $executable
+    if (-not (Test-PathWithin $executablePath $Directory)) { throw 'Executable escapes the package.' }
+    $machine = @{ x64 = 0x8664; ARM64 = 0xAA64 }[$Architecture]
+    if ((Get-PeMachine $executablePath) -ne $machine) { throw 'Wrong native executable architecture.' }
+    $appRoot = Split-Path -Parent $executablePath
+    foreach ($name in @('hostfxr.dll', 'hostpolicy.dll', 'coreclr.dll', 'System.Private.CoreLib.dll')) {
+        if (-not (Test-Path -LiteralPath (Join-Path $appRoot $name) -PathType Leaf)) {
+            throw "Missing bundled runtime file: $name"
+        }
+    }
+    if ((Get-PeMachine (Join-Path $appRoot 'coreclr.dll')) -ne $machine) {
+        throw 'The package contains another architecture''s .NET runtime.'
+    }
+    $processName = [IO.Path]::GetFileNameWithoutExtension($executable)
+    $runtime = Get-Content -LiteralPath (Join-Path $appRoot "$processName.runtimeconfig.json") -Raw | ConvertFrom-Json
+    $options = $runtime.runtimeOptions
+    $included = $options.PSObject.Properties['includedFrameworks']
+    if ($null -ne $options.PSObject.Properties['framework'] -or
+        $null -ne $options.PSObject.Properties['frameworks'] -or $null -eq $included -or
+        @($included.Value | Where-Object { $_.name -eq 'Microsoft.NETCore.App' }).Count -eq 0) {
+        throw 'The native package is framework-dependent or does not include Microsoft.NETCore.App.'
+    }
+    return @{
+        Identity = [string]$packageIdentity.Name; Publisher = [string]$packageIdentity.Publisher
+        Version = [string]$packageIdentity.Version; Architecture = $Architecture
+        AppId = [string]$application.Id; Executable = $executable; ProcessName = $processName
+    }
+}
+
+function Get-DescendantProcesses {
+    param([int]$RootProcessId, [object[]]$Processes)
+    $ids = [Collections.Generic.HashSet[int]]::new()
+    [void]$ids.Add($RootProcessId)
+    do {
+        $changed = $false
+        foreach ($process in $Processes) {
+            if ($ids.Contains([int]$process.ParentProcessId) -and $ids.Add([int]$process.ProcessId)) {
+                $changed = $true
+            }
+        }
+    } while ($changed)
+    return @($Processes | Where-Object {
+        [int]$_.ProcessId -ne $RootProcessId -and $ids.Contains([int]$_.ProcessId)
+    })
+}
+
+function Read-AtomicJson {
+    param([string]$Path)
+    # Permit the host's atomic rename while this sample reads the previous file.
+    $stream = [IO.File]::Open($Path, [IO.FileMode]::Open, [IO.FileAccess]::Read,
+        ([IO.FileShare]::ReadWrite -bor [IO.FileShare]::Delete))
+    $reader = [IO.StreamReader]::new($stream)
+    try { return ($reader.ReadToEnd() | ConvertFrom-Json) }
+    finally { $reader.Dispose() }
+}
+function Assert-MsixAcceptanceSource {
+    param([Parameter(Mandatory = $true)]$Source)
+    if ($Source.GitSha -cnotmatch '^[a-f0-9]{40}$' -or [string]$Source.RunId -notmatch '^[0-9]{1,20}$' -or
+        $Source.Owner -cnotmatch '^[a-z0-9][a-z0-9-]{0,63}$' -or [string]::IsNullOrWhiteSpace($Source.Workflow)) {
+        throw 'Native acceptance requires a full source SHA, run ID, owner and workflow.'
+    }
+}
+function Copy-MsixAdditionalEvidence {
+    param($Receipt, [hashtable]$Fields, [string[]]$Reserved)
+    foreach ($key in $Fields.Keys) {
+        if ($Reserved -icontains [string]$key) {
+            throw 'Additional evidence cannot overwrite native acceptance evidence.'
+        }
+        $Receipt[$key] = $Fields[$key]
+    }
+}
+
+function Complete-MsixAcceptanceEvidence {
+    param($Receipt, $Installed, [string]$OutputDirectory, [hashtable]$Fields,
+          [string[]]$Reserved, [scriptblock]$Collector)
+    if ($null -ne $Collector) {
+        & $Collector $Installed $OutputDirectory $Fields | Out-Null
+        Copy-MsixAdditionalEvidence $Receipt $Fields $Reserved
+    }
+    # Evidence collection must finish before an invocation can pass.
+    $Receipt.status = 'passed'
+}
+
+function Invoke-MsixNativeAcceptance {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)][string]$PackageDirectory,
+        [Parameter(Mandatory = $true)][string]$OutputDirectory,
+        [Parameter(Mandatory = $true)][string]$Identity,
+        [Parameter(Mandatory = $true)][string]$Publisher,
+        [Parameter(Mandatory = $true)][ValidateSet('x64', 'ARM64')][string]$Architecture,
+        [Parameter(Mandatory = $true)]$Source,
+        [ValidateRange(10, 120)][int]$ObserveSeconds = 30,
+        [hashtable]$ReceiptFields = @{},
+        [scriptblock]$InspectPayload,
+        [scriptblock]$TestReadiness,
+        [scriptblock]$CollectEvidence
+    )
+    $ErrorActionPreference = 'Stop'
+    if ($env:GITHUB_ACTIONS -ne 'true' -or $env:OS -ne 'Windows_NT') {
+        throw 'Native MSIX acceptance runs on an isolated GitHub Windows runner.'
+    }
+    $cpu = @(Get-CimInstance Win32_Processor)[0].Architecture
+    $expectedCpu = @{ x64 = 9; ARM64 = 12 }[$Architecture]
+    if ($cpu -ne $expectedCpu) { throw "Native $Architecture acceptance requires a matching Windows runner." }
+
+    New-Item -ItemType Directory -Force -Path $OutputDirectory | Out-Null
+    Assert-MsixAcceptanceSource $Source
+    $receipt = [ordered]@{
+        schemaVersion = 1; game = $Source.Owner; architecture = $Architecture; status = 'failed'
+        sourceRunId = $Source.RunId; sourceGitSha = $Source.GitSha
+        sourceWorkflow = $Source.Workflow
+        acceptanceGitSha = $env:GITHUB_SHA
+        acceptanceRun = "https://github.com/$env:GITHUB_REPOSITORY/actions/runs/$env:GITHUB_RUN_ID"
+        startedAt = [DateTime]::UtcNow.ToString('o'); observeSeconds = $ObserveSeconds
+        packageIdentityVerified = $false; selfContainedRuntimeVerified = $false
+        nativeInstallationVerified = $false; nativeLaunchVerified = $false
+        packagedCoreClrVerified = $false; winUiLoaded = $false; windowObserved = $false
+        webViewRendererObserved = $false
+        gameplayAcceptance = 'not-run'; loginPurchaseAcceptance = 'not-run'; storeUploaded = $false
+        cleanupErrors = @()
+    }
+    $reserved = @($receipt.Keys) + @('packageSha256', 'packageFile', 'identity', 'packageVersion',
+        'processId', 'loadedCoreClr', 'loadedWinUi', 'failure', 'finishedAt')
+    $extraEvidence = @{}
+    foreach ($key in $ReceiptFields.Keys) { $extraEvidence[$key] = $ReceiptFields[$key] }
+    Copy-MsixAdditionalEvidence $receipt $extraEvidence $reserved
+    $temporary = Join-Path $env:RUNNER_TEMP ('native-msix-' + [Guid]::NewGuid().ToString('N'))
+    New-Item -ItemType Directory -Path $temporary | Out-Null
+    $installed = $null
+    $certificate = $null
+    $installAttempted = $false
+    $hostProcess = $null
+    $metadata = $null
+    $started = Get-Date
+    $failure = $null
+
+    try {
+        $packages = @(Get-ChildItem -LiteralPath $PackageDirectory -Filter *.msix -File -Recurse)
+        if ($packages.Count -ne 1) { throw 'Expected exactly one native MSIX artifact for this architecture.' }
+        $original = $packages[0].FullName
+        $originalHash = (Get-FileHash -LiteralPath $original -Algorithm SHA256).Hash
+        $receipt.packageSha256 = $originalHash.ToLowerInvariant()
+        $receipt.packageFile = $packages[0].Name
+        $sdkRoot = Join-Path ([Environment]::GetEnvironmentVariable('ProgramFiles(x86)')) 'Windows Kits\10\bin'
+        $tools = @(Get-ChildItem -Path (Join-Path $sdkRoot '*\*\MakeAppx.exe') -File |
+            Where-Object { $_.Directory.Name -in @($Architecture.ToLowerInvariant(), 'x64') } |
+            Sort-Object @{ Expression = { [version]$_.Directory.Parent.Name }; Descending = $true },
+                        @{ Expression = { $_.Directory.Name -eq $Architecture.ToLowerInvariant() }; Descending = $true })
+        if ($tools.Count -eq 0) { throw 'Windows SDK MakeAppx was not found.' }
+        $makeAppx = $tools[0].FullName
+        $signTool = Join-Path $tools[0].DirectoryName 'signtool.exe'
+        if (-not (Test-Path -LiteralPath $signTool -PathType Leaf)) { throw 'Windows SDK SignTool was not found.' }
+        $inspection = Join-Path $temporary 'inspection'
+        & $makeAppx unpack /p $original /d $inspection /o
+        if ($LASTEXITCODE -ne 0) { throw 'MakeAppx could not inspect the package.' }
+        $metadata = Assert-MsixPayload $inspection $Identity $Publisher $Architecture
+        if ($null -ne $InspectPayload) {
+            & $InspectPayload $inspection $extraEvidence | Out-Null
+            Copy-MsixAdditionalEvidence $receipt $extraEvidence $reserved
+        }
+        $receipt.packageIdentityVerified = $true
+        $receipt.selfContainedRuntimeVerified = $true
+        $receipt.identity = $metadata.Identity
+        $receipt.packageVersion = $metadata.Version
+
+        # Refuse to replace any pre-existing installation, including another version.
+        if (@(Get-AppxPackage -Name $metadata.Identity).Count -ne 0) {
+            throw 'The selected game is already installed; this is not a clean acceptance runner.'
+        }
+        $copy = Join-Path $temporary 'test-signed.msix'
+        Copy-Item -LiteralPath $original -Destination $copy
+        $certificate = New-SelfSignedCertificate -Type Custom -Subject $metadata.Publisher -KeyUsage DigitalSignature -CertStoreLocation 'Cert:\CurrentUser\My' -TextExtension @('2.5.29.37={text}1.3.6.1.5.5.7.3.3', '2.5.29.19={text}')
+        & $signTool sign /fd SHA256 /sha1 $certificate.Thumbprint $copy
+        if ($LASTEXITCODE -ne 0) { throw 'Could not test-sign the package copy.' }
+        $publicCertificate = Join-Path $temporary 'test-signing.cer'
+        Export-Certificate -Cert $certificate -FilePath $publicCertificate | Out-Null
+        Import-Certificate -FilePath $publicCertificate -CertStoreLocation 'Cert:\LocalMachine\TrustedPeople' | Out-Null
+        $installAttempted = $true
+        Add-AppxPackage -Path $copy
+        $matches = @(Get-AppxPackage -Name $metadata.Identity)
+        if ($matches.Count -ne 1 -or $matches[0].Version.ToString() -cne $metadata.Version) {
+            throw 'Installed package differs from the inspected artifact.'
+        }
+        $installed = $matches[0]
+        $receipt.nativeInstallationVerified = $true
+        $hostLog = Join-Path $env:LOCALAPPDATA "Packages\$($installed.PackageFamilyName)\LocalState\host-error.log"
+        $expectedExecutable = Join-Path $installed.InstallLocation $metadata.Executable
+        $started = Get-Date
+        Start-Process -FilePath "shell:AppsFolder\$($installed.PackageFamilyName)!$($metadata.AppId)" -WindowStyle Hidden
+        $clock = [Diagnostics.Stopwatch]::StartNew()
+        $readyAt = $null
+        while ($clock.Elapsed.TotalSeconds -lt (60 + $ObserveSeconds)) {
+            Start-Sleep -Seconds 1
+            if (Test-Path -LiteralPath $hostLog) { throw 'The installed host recorded a startup exception.' }
+            $candidates = @(Get-Process -Name $metadata.ProcessName -ErrorAction SilentlyContinue | Where-Object {
+                $_.StartTime -ge $started -and $_.MainModule.FileName -ieq $expectedExecutable
+            })
+            if ($candidates.Count -gt 1) { throw 'Multiple newly activated native host processes were found.' }
+            if ($candidates.Count -eq 0) {
+                if ($null -ne $readyAt -or $clock.Elapsed.TotalSeconds -gt 60) { throw 'The installed native host exited or never started.' }
+                continue
+            }
+            $hostProcess = $candidates[0]
+            $modules = @($hostProcess.Modules)
+            $core = @($modules | Where-Object { $_.ModuleName -ieq 'coreclr.dll' })
+            $xaml = @($modules | Where-Object { $_.ModuleName -ieq 'Microsoft.UI.Xaml.dll' })
+            $receipt.packagedCoreClrVerified = $core.Count -eq 1 -and (Test-PathWithin $core[0].FileName $installed.InstallLocation)
+            $receipt.winUiLoaded = $xaml.Count -eq 1 -and (Test-PathWithin $xaml[0].FileName $installed.InstallLocation)
+            $receipt.windowObserved = $hostProcess.MainWindowHandle -ne [IntPtr]::Zero
+            $children = @(Get-DescendantProcesses $hostProcess.Id @(Get-CimInstance Win32_Process))
+            $renderers = @($children | Where-Object {
+                $_.Name -ieq 'msedgewebview2.exe' -and $_.CommandLine -match '(^|\s)--type=renderer(\s|$)'
+            })
+            $receipt.webViewRendererObserved = $renderers.Count -gt 0
+            $applicationReady = $true
+            if ($null -ne $TestReadiness) {
+                $applicationReady = & $TestReadiness $installed $extraEvidence
+                if ($applicationReady -isnot [bool]) { throw 'Application readiness callback must return one Boolean.' }
+                Copy-MsixAdditionalEvidence $receipt $extraEvidence $reserved
+            }
+            $ready = $receipt.packagedCoreClrVerified -and $receipt.winUiLoaded -and $receipt.windowObserved -and $receipt.webViewRendererObserved -and $applicationReady
+            if (-not $ready) {
+                if ($null -ne $readyAt -or $clock.Elapsed.TotalSeconds -gt 60) {
+                    throw 'The installed host did not sustain packaged CLR, WinUI, a native window and a WebView2 renderer.'
+                }
+                continue
+            }
+            if ($null -eq $readyAt) {
+                $readyAt = $clock.Elapsed.TotalSeconds
+                $receipt.processId = $hostProcess.Id
+                $receipt.loadedCoreClr = $core[0].FileName
+                $receipt.loadedWinUi = $xaml[0].FileName
+            }
+            if ($clock.Elapsed.TotalSeconds - $readyAt -ge $ObserveSeconds) { break }
+        }
+        if ($null -eq $readyAt -or $clock.Elapsed.TotalSeconds - $readyAt -lt $ObserveSeconds) {
+            throw 'Native readiness was not observed for the required duration.'
+        }
+        if ((Get-FileHash -LiteralPath $original -Algorithm SHA256).Hash -cne $originalHash) {
+            throw 'The original unsigned Store artifact changed during acceptance.'
+        }
+        if (Test-Path -LiteralPath $hostLog) { throw 'The installed host recorded a startup exception.' }
+        $receipt.nativeLaunchVerified = $true
+        Complete-MsixAcceptanceEvidence $receipt $installed $OutputDirectory $extraEvidence $reserved $CollectEvidence
+    } catch {
+        $failure = $_.Exception.Message
+        $receipt.failure = $failure
+        if ($null -ne $installed) {
+            $log = Join-Path $env:LOCALAPPDATA "Packages\$($installed.PackageFamilyName)\LocalState\host-error.log"
+            if (Test-Path -LiteralPath $log) { Copy-Item -LiteralPath $log -Destination (Join-Path $OutputDirectory 'host-error.log') }
+        }
+        $events = @()
+        foreach ($name in @('Application', 'Microsoft-Windows-AppModel-Runtime/Admin', 'Microsoft-Windows-AppXDeploymentServer/Operational')) {
+            $events += @(Get-WinEvent -FilterHashtable @{ LogName = $name; StartTime = $started; Level = 1, 2, 3 } -ErrorAction SilentlyContinue |
+                Select-Object -First 10 TimeCreated, ProviderName, Id, LevelDisplayName, Message)
+        }
+        ConvertTo-Json -InputObject $events -Depth 6 | Set-Content -LiteralPath (Join-Path $OutputDirectory 'windows-events.json') -Encoding UTF8
+    } finally {
+        # Clean up only this invocation's package/process and exact generated certificate.
+        if ($null -ne $hostProcess) {
+            $current = Get-Process -Id $hostProcess.Id -ErrorAction SilentlyContinue
+            if ($null -ne $current -and $current.StartTime -eq $hostProcess.StartTime) {
+                Stop-Process -Id $current.Id -ErrorAction SilentlyContinue
+            }
+        }
+        if ($installAttempted -and $null -ne $metadata) {
+            try {
+                foreach ($package in @(Get-AppxPackage -Name $metadata.Identity)) {
+                    if ($package.Version.ToString() -ceq $metadata.Version) {
+                        Remove-AppxPackage -Package $package.PackageFullName -ErrorAction Stop
+                    }
+                }
+            } catch { $receipt.cleanupErrors += $_.Exception.Message }
+        }
+        if ($null -ne $certificate) {
+            try {
+                $trustPath = "Cert:\LocalMachine\TrustedPeople\$($certificate.Thumbprint)"
+                if (Test-Path -LiteralPath $trustPath) { Remove-Item -LiteralPath $trustPath -ErrorAction Stop }
+                Remove-Item -LiteralPath "Cert:\CurrentUser\My\$($certificate.Thumbprint)" -DeleteKey -ErrorAction Stop
+            } catch { $receipt.cleanupErrors += $_.Exception.Message }
+        }
+        if ($receipt.cleanupErrors.Count -gt 0) { $receipt.status = 'failed' }
+        $receipt.finishedAt = [DateTime]::UtcNow.ToString('o')
+        $receipt | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath (Join-Path $OutputDirectory 'native-smoke-receipt.json') -Encoding UTF8
+    }
+    if ($receipt.status -ne 'passed') { throw "Native MSIX acceptance failed: $failure; cleanup errors: $($receipt.cleanupErrors.Count)" }
+    Write-Output "Installed $Identity ($Architecture): packaged CLR, WinUI window, WebView2 and application readiness sustained for $ObserveSeconds seconds."
+
+}
+
+Export-ModuleMember -Function Get-PeMachine, Test-PathWithin, Assert-MsixPayload, Get-DescendantProcesses, Read-AtomicJson, Assert-MsixAcceptanceSource, Invoke-MsixNativeAcceptance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.46.1",
+  "version": "0.48.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,10 @@
   "type": "module",
   "sideEffects": false,
   "exports": {
+    "./windows-native-tools": {
+      "types": "./dist/windows-native-tools.d.ts",
+      "default": "./dist/windows-native-tools.js"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
@@ -34,6 +38,7 @@
   },
   "files": [
     "dist",
+    "native-tools/windows-msix",
     "templates"
   ],
   "bin": {
@@ -58,9 +63,13 @@
     "undici": "^7.29.1",
     "vite": "8.1.3",
     "yauzl": "3.4.0",
-    "@mpgd/catalog": "0.9.3",
+    "parse5": "7.3.0",
+    "postcss": "8.5.28",
+    "postcss-value-parser": "4.2.0",
+    "@mpgd/catalog": "0.10.0",
     "@mpgd/phaser-assets": "0.9.0",
-    "@mpgd/target-config": "0.22.1"
+    "@mpgd/platform": "0.23.0",
+    "@mpgd/target-config": "0.23.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -68,17 +77,18 @@
     "@types/yauzl": "3.4.0",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
-    "@mpgd/adapter-ait": "0.15.2",
-    "@mpgd/adapter-capacitor": "0.9.2",
-    "@mpgd/adapter-browser": "0.10.2",
-    "@mpgd/adapter-devvit": "0.10.1",
-    "@mpgd/adapter-verse8": "0.6.0",
-    "@mpgd/analytics": "0.4.8",
-    "@mpgd/bridge": "0.12.3",
-    "@mpgd/game-services": "0.22.0",
-    "@mpgd/game-runtime": "0.6.5",
-    "@mpgd/platform": "0.22.0",
-    "@mpgd/i18n": "0.6.13"
+    "@mpgd/adapter-ait": "0.17.0",
+    "@mpgd/adapter-browser": "0.11.0",
+    "@mpgd/adapter-capacitor": "0.10.0",
+    "@mpgd/adapter-devvit": "0.12.0",
+    "@mpgd/analytics": "0.4.9",
+    "@mpgd/adapter-verse8": "0.7.0",
+    "@mpgd/capacitor-play-billing": "0.3.0",
+    "@mpgd/bridge": "0.13.0",
+    "@mpgd/capacitor-storekit": "0.3.0",
+    "@mpgd/game-services": "0.24.0",
+    "@mpgd/game-runtime": "0.7.0",
+    "@mpgd/i18n": "0.6.14"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/templates/lite-overlay/.agents/skills/use-mpgd-kit/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: use-mpgd-kit
+description: Route lite Canvas2D game development, platform integration, target builds, acceptance, and release work through this generated game's mpgd-kit contracts.
+---
+
+# Use mpgd-kit
+
+Read `AGENTS.md`, `agent/game-manifest.json`, and `docs/MPGD_KIT_WORKFLOWS.md` before editing.
+
+1. Identify capability ownership and configured targets from the manifest.
+2. Keep deterministic rules in `src/game` and Canvas2D rendering/input in `src/lite` through `@mpgd/lite-shell`.
+3. Use `PlatformGateway`; keep SDK calls in adapters or target wrappers.
+4. Use backend ledger or verifier APIs before mutating durable purchases, rewarded grants, or verified scores.
+5. Keep runtime, presentation, recovery, and audio ownership above renderer lifetimes; preserve durable encrypted journals and late observers.
+6. Update the manifest, brief, and acceptance guidance when capabilities or handoff contracts change.
+7. Run focused checks, then `pnpm check`, `pnpm build`, and `pnpm accept` for target handoffs.
+8. Preserve generated JSON/Markdown acceptance and release evidence.
+
+Read a target skill declared in the manifest before changing its release flow.
+Use official target documentation or the configured MCP for SDK and submission requirements.
+Keep the lite game free of Phaser, preserve native scrolling and history restoration, and verify Devvit inline budget.
+Do not commit tokens, credentials, signing material, personal MCP configuration, or platform login state.

package/templates/lite-overlay/AGENTS.md

@@ -0,0 +1,27 @@
+# Generated Lite Game Agent Instructions
+
+This is a Canvas2D game generated with the mpgd lite template.
+
+## Start here
+
+- Read `agent/game-manifest.json`, `agent/brief.md`, and `agent/acceptance.md`.
+- Use `.agents/skills/use-mpgd-kit/SKILL.md` for platform, target, acceptance, and release work.
+- Read `docs/MPGD_KIT_WORKFLOWS.md` for capability ownership.
+
+## Boundaries
+
+- Keep deterministic rules in `src/game`; rendering and input belong in `src/lite`.
+- Use `@mpgd/lite-shell` and Canvas2D. Keep the lite template free of Phaser.
+- Put platform SDK imports in adapters or target wrappers; use `PlatformGateway` from game code.
+- Keep pure game packages free of DOM, network calls, and SDK imports.
+- Purchases and rewarded-ad callbacks are evidence; backend ledger grants precede durable state changes.
+- Create one game runtime above renderer lifetimes. Renderer disposal must not release another owner's native presentation or audio.
+- Keep safe-area geometry reserved once and preserve native scrolling in Devvit inline mode.
+- Do not commit secrets, signing keys, personal MCP configuration, or platform authentication state.
+
+## Tooling and checks
+
+- Use `ttsx`, `ttsc`, and `@ttsc/lint`; do not add `tsx`, ESLint, or Prettier.
+- Run focused checks, then `pnpm check` and `pnpm build`.
+- Run `pnpm accept` for a target handoff; preserve its generated evidence.
+- Keep the manifest, brief, and acceptance guidance aligned with material changes.

package/templates/lite-overlay/README.md

@@ -0,0 +1,37 @@
+# __GAME_TITLE__
+
+Standalone Canvas2D lite game generated by `@mpgd/create-game --template lite --workspace`.
+It uses `@mpgd/lite-shell`, `PlatformGateway`, and the shared mpgd game runtime.
+
+## Start
+
+```sh
+pnpm install
+pnpm dev
+pnpm check
+pnpm build
+pnpm accept
+```
+
+The lite-shell package is private until its initial npm registration. Create lite games with `--workspace` and a local kit checkout.
+The CLI supports the canvas renderer; DOM and SVG renderers are planned.
+
+## Ownership
+
+- `src/game/state.ts`: deterministic state.
+- `src/lite/tapGame.ts`: Canvas2D renderer and input.
+- `src/runtime/createGame.ts`: mount, audio binding, and teardown.
+- `src/platform`: gateway selection and authoritative services.
+- `mpgd.targets.json`: configured target build and feature ownership.
+
+Read `AGENTS.md`, `agent/brief.md`, `agent/acceptance.md`, and `docs/MPGD_KIT_WORKFLOWS.md` before material edits.
+Use generated icon, localization, build/smoke, and acceptance commands; preserve their evidence.
+Keep SDK calls outside game and renderer code. Backend ledger grants precede durable commerce or rewarded changes.
+Never commit platform credentials or signing material.
+
+## Devvit and browser behavior
+
+Inline and expanded entries both use the lite renderer. Preserve feed scrolling and browser touch gestures.
+Verify static imports, preloads, and CSS imports against the inline budget; defer optional engines only through explicit dynamic imports.
+Returning through browser history must retain a persisted game. Verify resize, DPR, safe areas, lifecycle, and native presentation ownership on configured targets.
+Target smoke verifies build artifacts; real SDK and device acceptance is required for platform release evidence.

package/templates/lite-overlay/agent/acceptance.md

@@ -0,0 +1,27 @@
+# Lite Game Acceptance
+
+Use `agent/game-manifest.json` and `.agents/skills/use-mpgd-kit/SKILL.md` to select configured target checks.
+Run `pnpm check`, `pnpm build`, `pnpm icons:generate`, `pnpm icons:verify`, and `pnpm accept`.
+Preserve the generated JSON and Markdown in `artifacts/acceptance` or the target release-output directory.
+
+- Confirm the first screen is playable and uses Canvas2D without a Phaser dependency or scene imports.
+- Resize the game, verify DPR handling, and reserve safe-area geometry exactly once.
+- Check pause/resume, browser history restoration, and audio ownership. A persisted `pagehide` must retain the game.
+- Use the game-owned driver for gameplay and performance acceptance; unit tests do not certify live SDK behavior.
+- Verify renderer teardown removes its own listeners and never updates a replacement view from an old promise.
+- Purchases and rewarded-ad callbacks never grant locally; verify authoritative ledger grants and durable reconciliation before release.
+- Keep unknown native outcomes and late recovery observers; closing one lease must not release another owner's presentation or audio.
+
+## Reddit Devvit
+
+Keep SDK calls in the adapter or `apps/target-devvit`. Verify both inline and expanded game modes, preserve feed scrolling, and run the configured inline build budget.
+The inline first load must reject forbidden modules and include static imports, preloads, and CSS imports. Only declared dynamic imports can be deferred.
+Run login/init/playtest for a real Devvit handoff after platform setup. Artifact smoke is not deployed-platform evidence.
+
+## Other configured targets
+
+Use the configured official MCP or SDK documentation before SDK or submission changes. Keep target secrets and signing material outside source control.
+ONE play requires issued IDs, authenticated issuer routes, signed SSV/PNS, purchase verification, ledger-before-finalization, and atomic cancellation fencing.
+Verse8 server records require authenticated senders and a game-specific completion verifier.
+Apps in Toss and native Store builds require real-app identity, lifecycle, and SDK acceptance; generic fixtures do not certify live commerce or ads.
+Uploading and deployment follow the target's release procedure after acceptance.

package/templates/lite-overlay/agent/brief.md

@@ -0,0 +1,17 @@
+# __GAME_TITLE__ Brief
+
+Build a Canvas2D game using `@mpgd/lite-shell` and the mpgd platform boundary.
+Read `AGENTS.md`, the agent manifest, and the `use-mpgd-kit` router before editing.
+
+- Deterministic rules and state belong in `src/game/state.ts`.
+- Rendering and input belong in `src/lite/tapGame.ts`; mounting belongs in `src/runtime/createGame.ts`.
+- Use `PlatformGateway` for identity, storage, commerce, ads, lifecycle, and host presentation.
+- Keep SDK calls in adapters or target wrappers and use backend ledger APIs before durable grants.
+- Create one `createGamePlatformRuntime` during bootstrap. Bind audio through `bindGameAudio` with the game-owned execution scope.
+- Keep recovery above renderer lifetimes; reconcile existing operations on startup and resume without opening SDK UI.
+- Rewarded v2 needs an application-owned durable encrypted journal. An in-memory store is not recovery evidence.
+- Reserve safe-area geometry once and preserve feed scrolling and browser touch gestures.
+
+Run `pnpm dev`, `pnpm check`, `pnpm build`, and `pnpm accept`.
+Devvit inline and expanded entries both use the lite renderer. Keep optional engines behind explicit dynamic import boundaries and verify the inline budget.
+Production commerce and ads remain unavailable until authenticated backend, issued IDs, durable stores, and real-platform acceptance are configured.