Skip to content

ByteTerrace/Puck / .claude/skills/platform

platform

Verified

Maps Puck's OS seams (Puck.Platform, .Windows, .Linux): native windows, Win32/Wayland/XCB, displays and VRR, precision waits, memory, clipboard, camera and desktop capture, probes, HID transports.

Platform

A map of where Puck meets the operating system. Three projects, one shape:

  • Puck.Platform holds the OS-neutral contracts and the pieces that need no OS code: window, clipboard, camera, image-capture and audio-render contracts, camera discovery polling, the unmanaged allocator, probe readings and kernel sockets, null fallbacks and the declining recording factories.
  • Puck.Platform.Windows implements them over Win32, Media Foundation, Windows Graphics Capture, WASAPI, Raw Input, HID, XInput and GameInput.
  • Puck.Platform.Linux implements windows over Wayland and XCB and registers null or declining services for everything else.

A composition root picks one platform per seam with one OperatingSystem.IsWindows() branch (WorldBootComposition, and WindowsPresentationRegistration or LinuxPresentationRegistration in the Puck.Launcher.Windows and .Linux projects). The project READMEs (neutral, Windows, Linux) are the developer reference. When this file and the code disagree, the code wins and this file is corrected in the same change.

Find the owner by what you need

You needOwnerRead
A native window, its events and its surfaceINativeWindow, INativeWindowFactory, INativeWindowBackend; Win32NativeWindow, WaylandNativeWindow, XcbNativeWindow; ConfiguredNativeWindow as the headless stand-inneutral README
Which display kind to open on LinuxNativeDisplayEnvironment, NativeDisplayKindSelector (environment variables only)neutral README
Variable refresh range, display timing, colour space, keeping the display awakeIDisplayTimingInfo on Win32NativeWindow (Win32NativeWindow.Vrr.cs), EdidVariableRefreshParser, Win32DisplayColorSpaceProbe, the display power request in Win32NativeWindow.DisplayPower.cshost pacing
Wait until a deadline without spinning or raising timer resolutionIPrecisionWaiter: Win32HighResolutionWaitableTimer (the window implements it; Win32PrecisionWaiter serves a headless host through AddWindowsPrecisionWaiter), consumed by LauncherHostLoop.WaitUntilbelow
Unmanaged memoryIAllocator, MimallocAllocator, registered by AddPuckAllocatorneutral README
ClipboardIClipboardService: Win32ClipboardService; NullClipboardService on Linuxneutral README
Mouse, keyboard and pointer lock at the OS boundaryWin32NativeWindow messages, Win32RawInput (relative motion per mouse), Win32PointerLock, WindowInputQueuepointer input
Pads and HID devices at the transportWindowsInputTransports.CreateGamepadManager over Win32HidDeviceSource and Win32XboxAcquisitionSource (XInput, GameInput)input
Device lightsILampArrayDevice: Win32LampArrayDeviceabstractions
A webcam's frames, CPU pixels or shared GPU texturesICameraCaptureService (EnumerateDevices, TryOpenPixels, TryOpenShared) → ICameraGraph; Win32MediaFoundationCameraService, Win32CameraGraph's MTA worker, Win32D3D11CameraFrameConverter; discovery polling in CameraDeviceScannercamera capture
A desktop or another window's pixels as a feedINativeImageCaptureService: Win32NativeImageCaptureService, Win32GraphicsCaptureFeedWindows README
A passthrough screen that forwards input to a desktop windowWin32DesktopPassthrough, Win32PassthroughWindowdevice input
A probe: a kernel over camera, strobe or rendered framesProbeReading, ProbeReadingRing, IProbeKernelHost, ProbeKernelRequest; Win32ProbeKernelBench, Win32RenderedProbeKernelHost; ProbeTrackPlayer replays recorded readingsneutral README
The audio output deviceIAudioRenderDeviceFactory: WasapiAudioRenderDeviceFactory; none on Linuxmedia
Video encoders, loopback and microphone captureIVideoEncoderFactory, IAudioCaptureSourceFactory: MediaFoundationVideoEncoderFactory, WasapiAudioCaptureSourceFactory; declining factories on Linuxmedia

Registration shape

  • PlatformWindowingServiceRegistration.AddPlatformWindowing registers only the neutral pieces (display probe, platform support, window factory). Each platform package adds one method per seam: WindowsPlatformServiceRegistration.AddWindowsPlatformWindowing, AddWindowsCameraCapture, AddWindowsRecordingPlatform, AddWindowsAudioRender, AddWindowsPrecisionWaiter, and the Linux equivalents on LinuxPlatformServiceRegistration (AddLinuxPlatformWindowing, AddLinuxCameraCapture, which registers the null camera and image-capture services today, AddLinuxRecordingPlatform). A new backend implements the contract in its platform project and replaces the null service in that platform's registration method.
  • A method that constructs a [SupportedOSPlatform("windows")] type carries the attribute itself, so CA1416 makes the caller guard with OperatingSystem.IsWindows(). The guard lives in the composition root, never inside a platform project.
  • Puck.Platform.Windows stays net11.0, like Puck.Platform, so the annotations keep firing. WindowsCaptureProjection.targets re-declares the WinRT projection at every entry point that references it, on Windows hosts.
  • A seam with no backend registers a null or declining service that answers with a reason (NullCameraCaptureService, DecliningVideoEncoderFactory), never a missing service a caller must guess about.

Play nice with the host

AGENTS.md's ruling applies here first: Puck uses the host's threads, waits, timers and virtual memory, and never spins in place of a wait or raises process-wide timer resolution. In this area that means:

  • Wait on IPrecisionWaiter. Win32HighResolutionWaitableTimer uses CREATE_WAITABLE_TIMER_HIGH_RESOLUTION, which wakes within about half a millisecond without timeBeginPeriod and without spinning; LauncherHostLoop.WaitUntil re-reads its clock after each wait and falls back to a one-millisecond sleep where no waiter exists. A busy loop on a stopwatch is a defect, however short.
  • Swap-chain waits pace a windowed host (host pacing); the timer only bounds what the swap chain cannot.
  • Camera graphs own their native objects on one MTA worker thread, joined with a bound on disposal; camera scans run at most one at a time on a worker and hand back completed snapshots without blocking the caller.
  • The window holds a display-required power request while open, because a powered-off display stops the compositor retiring presents.

Contracts that bite

  • An empty camera list means no cameras. EnumerateDevices returns empty only when the machine has none; a failed scan throws InvalidOperationException, so a caller never reads a failed scan as every camera unplugged.
  • A successful open is usable. A pixel open has already published a frame from every stream; a shared open has validated native GPU input. A shared ring's consumer acquires a slot until its GPU submission retires, and the camera drops a frame rather than overwrite a texture still being sampled.
  • Relative mouse motion is never integrated into a cursor estimate. Raw Input supplies per-mouse deltas; the system cursor supplies positions and buttons.
  • An agent's World opens no physical device. --devices none drops every OS event before a seat; never inject real input to test (puck-world).
  • A device or OS protocol is independent work. Consult several independent sources (vendor documentation, kernel drivers, other open implementations), cite each and note where they disagree (AGENTS.md).

Where each contract is enforced

ContractEnforced by
Windows-only code runs only behind an OS guardCA1416 over [SupportedOSPlatform] on the registration methods
Puck.Platform.Linux's closure has no Windows dependencythe Puck.Platform.Linux lane profile in build/Architecture.props (puck architecture)
A failed camera scan is distinct from an empty oneICameraCaptureService.EnumerateDevices throwing; CameraDeviceScanner keeping failures apart from empty lists
One waiter per timer, no spinningWin32HighResolutionWaitableTimer (one waiter at a time, re-armed per wait)

Open gaps

  • Linux has no camera, desktop-capture, audio-render, video-encoder, audio-capture or clipboard backend, and its windows hold no display request (Wayland's idle inhibit, X11's screensaver suspend). Windowed Wayland and XCB behaviour has not been run on real Linux hardware.
  • Duplicates recorded in the refactoring packet: camera plane validation and L8/BGRA packing (Win32FaceAuthenticationCameraGraph.cs beside CameraFramePacking), and the latest-value seqlock (ProbeReadingRing beside Puck.Hosting's PublishBuffer<T>) (refactoring campaign).
  • A reading taken while the compositor is not composing still looks like a slow frame (open items).

Verify

  • Build what you touched: dotnet build src/Puck.Platform.Windows -c Release or src/Puck.Platform.Linux; a Linux change also gets the WSL2 build the Linux launcher README gives, and says what it does not prove.
  • Laws: tests/Puck.Platform.Windows.Tests (camera enumeration and pixel delivery skip on a machine with no colour camera), and the host-loop laws in tests/Puck.Launcher.Tests (OffscreenBoundaryLawTests drives a manual IPrecisionWaiter).
  • A window, a display, a camera or pointer lock is a windowed World, a GPU leg (verification); hand it back as a verification request unless your brief grants it.

Look-alikes

  • Host pacing decisions (swap chain, timer grid, catch-up bursts) belong to Puck.Launcher and the hosting reference; this area only supplies the waits and display facts they read.
  • Puck.Input turns transports into InputSignals and binds them (input); this area only acquires devices and window events.
  • Camera capture feeds screens and probes; capture.* records the game (media).

Route adjacent work

SkillRoute there for
inputGamepads, HID protocols, haptics, InputArbiter, window input mapping and bindings.
mediaThe audio device's mixer and director, recording sessions, encoders as the recording graph uses them.
renderingSwap chains, presenters, the frame pacer, shared GPU textures a camera ring feeds, the camera conversion shader.
puck-worldScreens that show a camera or desktop feed, probes rows, booting a windowed World.
dotnet-performanceAllocation and interop cost on a platform hot path.
verificationGPU legs for windowed checks, the private CLI copy.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall