Shared render publication

The Worker path uses one bounded RenderWorker.PublicationQueue per emulated process. OpenGL, Direct3D immediate-mode batches and Glide use the same storage ownership, ordering, wake-up and failure rules. API encoders and execution adapters remain distinct.

GL encoder -------- immutable command bytes ----+
Glide encoder ----- immutable packet bytes -----+--> shared publication ring
D3D encoder ------- leased-buffer descriptor ---+          |
                                                   coalesced notification
                                                          |
                                                   page admission
                                                          |
                                               existing render-worker queue
                                                          |
                                               API decoder / GPU or software

The ring is a separate 4 MiB shared buffer plus a 64-byte control header. It does not change the WASM region layout. A short producer lock establishes process-wide packet order. The producer writes a complete record and payload, then atomically publishes its write cursor. The single consumer reads committed bytes and advances the read cursor only after the API adapter accepts them. Unsigned cursor differences permit wraparound. A full ring applies backpressure; failed consumers or shutdown wake parked producers with an error.

Wake-ups are coalesced while the consumer is active. Clearing the wake flag and rechecking the cursor closes the empty-queue race; the drain finalizer also covers publication while an earlier drain promise is settling. Page-side work never waits on the producer lock.

allocateProducerId() reserves a process-wide producer incarnation in shared control word9. Zero is reserved for the page producer; positive IDs never recycle when a guest thread slot is reused, and exhaustion fails instead of wrapping. DrawProducer({producerId}) includes this identity in its texture keys. These resource identities are distinct from the routing slot in a publication header.

Large neutral snapshots use publishSnapshot rather than copying an arbitrarily large command into the 4 MiB ring. The adapter supplies a private data-only snapshot and its charged size (currently D3DCommandStream.copyPayload). A structured-clone/transfer message carries the owned value; an 8-byte {id,bytes} reference in the common ring establishes execution order. Control words10/11 bound outstanding payloads to 64 MiB and 256 messages per process; word12 issues nonrecycled snapshot IDs. Credits retire only after adapter admission. The payload-copy preparation is outside these pending-publication credits, and this route still copies data; it is not a zero-copy performance claim.

SnapshotInbox awaits missing payload messages without blocking the page. This matters when a second producer's wake arrives before the first producer's payload: later GL/Glide/D3D work must not overtake that reference. Duplicate, stale and mismatched references fail the process queue; transport failure wakes credit waiters and rejects pending payload waits. Worker links verify the message's owner against their routing slot.

API4 references route to Bridge.submitSnapshot for D3D9 DRAW/CLEAR commands and owned rectangular color RESOURCE_UPDATE commands. The receiving bridge checks device generation/liveness and consumes any pending admission token before releasing snapshot credit. Color creation can accompany an operation; color/depth retirement also publishes owned API4 commands. Device teardown, queries, reset and presentation still use the broker. A test drives the actual publication broker and neutral execution path with a payload larger than its test ring, a delayed consumer, source mutation and stale-device rejection. Guarded D3D9 clears and draws now capture in the guest Worker and publish owned API4 commands. The first call establishes the endpoint through the broker. Named color targets and render-target texture aliases use shared owner-admission metadata once their storage exists. Unseen color resources carry owned initial definitions alongside draws, clears and uploads. Unavailable lifecycle state and missing guards retain ordered broker handling; device creation and device teardown publication remain open.

captureNativeColorDefinition shares canonical pixel capture between the page and guest producer. The native guard protects identity, dimensions, format, lock state and pixels during capture; the complete operation and definitions are copied and charged before publication. The serial API4 receiver creates each color ID once per device epoch before submitting its dependent operation. Duplicate definitions are ignored, including their initial pixels: they must never overwrite renderer-owned content. Registry collisions can therefore cause redundant capture, but not resource replacement. A full neutral queue drains before retrying creation; ordinary creation needs no preceding drain. Release follows prior publications and invalidates the registry. Startup still needs the broker and delivery of its endpoint channel before this path becomes eligible.

Validation: 21 immutable snapshot cases include held publication, two different initial images before admission, post-capture source reuse, and release followed by re-creation. Generated public x86 COM tests assert that named color creation actually crosses API4, then check exact geometry and writable-unlock readback pixels on WebGL and software, normal and compatibility WASM, diagnostics off/on. Evidence: scratch/runs/20261109-d3d-color-create-final-{webgl,software}/test-result.json. The earlier -webgl-owned fixture failed the new publication assertion because it did not yield to receive the endpoint channel; adding a public Sleep after the initial clear exercises the intended path. No gameplay FPS claim follows from these correctness tests.

captureNativeRetirement owns color/depth IDs and complete texture color-set IDs under the same native state guard. Native collection requires the final external reference and binding to be gone; surface serials are nonrecycled. The guest can therefore free/reuse its record after publication without changing the queued retirement identity. The receiver accepts only color, color-set and depth release kinds, consumes the neutral result, and invalidates color admission metadata in publication order. It waits and retries on a full queue rather than dropping retirement. No guest writes the shared admission registry; the page remains its single writer. Missing endpoint state or guard still uses the broker.

Retirement validation: 23 immutable snapshot cases include delayed record reuse, cube mip identity capture, wrong-owner rejection and an actually full queue held behind a draw. Native direct/Worker color-surface lifetime tests pass. Public COM browser tests restore the implicit target and release the final named target; the receiver must observe an API4 retirement. WebGL/software, normal/compatibility WASM and diagnostics off/on all pass with exact preceding geometry/upload pixels. Evidence: scratch/runs/20261109-d3d-retire-{webgl,software}/test-result.json. These do not prove gameplay performance or the remaining cross-API lifetimes.

Color/depth retirement does not call glFinish in either the local or Worker WebGL executor. Ordered GL object deletion preserves references needed by preceding commands; it does not require a CPU-visible completion boundary (WebGL deletion semantics). Context-loss detection remains, as do explicit fences, readbacks, reset and device-teardown completion. The local/Worker protocol test verifies these boundaries separately. test-d3d9-queued-texture-residency-web.js queues a draw sampling a color resource and then deletes that resource (including its sampled texture composition) before readback. WebGL1 and WebGL2 both retain the expected pixels and record no added GPU finish between draw and retirement. Public COM normal/compatibility WASM checks also pass; evidence: scratch/runs/20261109-d3d-retire-no-finish/test-result.json. This removes a forced synchronization point; gameplay FPS impact has not been measured.

Native copy publication is active. d3d9_color_stretch captures an invocation-owned 112-byte packet and dispatches opcode0x30019. The common page/guest decoder owns resource identities, rectangles and filter selection; unseen resources carry initial definitions through the same publication path. There is no source readback, CPU resampling or canonical destination write. The invocation retains its packet across a broker park and nested calls restore the parent packet. Completion does not touch native resource dirty counters; the renderer updates its destination revision for texture alias sampling. CPU LockRect/GetDC reads still wait and materialize renderer-owned contents.

D3DCommandStream.colorCopy validates and owns distinct source/destination identities, bounded top-left rectangles and point/linear filter selection; null denotes the implicit backbuffer. The initial contract matches existing native StretchRect support: A8R8G8B8/X8R8G8B8 targets, no same-resource feedback. WebGL executes a textured rectangle against renderer-owned color storage. It explicitly samples source pixel centers, clamps interpolation to the source subrectangle, preserves untouched destination pixels and forces alpha for X8 copies. It works on WebGL1 and WebGL2 and performs no CPU readback or GPU finish. Software uses the same contract and invokes the existing native d3d9_stretch_pixels scaler through the new d3d_software_copy_color export, with a bounded renderer-owned temporary packet; it does not implement a second JS resampler. Both executors retain the actual implicit format across reset. Previously software collapsed X8 to A8, which loses required copy alpha semantics.

Validation: shared independent color fixtures perform 1,120 checks per route (software direct/Worker and WebGL1/2), including point/linear up/downscaling, one-pixel edge expansion, preserved destination regions, explicit/implicit roundtrips and alpha. Filtered GPU pixels permit one byte of rounding tolerance; roundtrip ownership/orientation checks are exact. Separate X8 tests assert exact opaque alpha. A real WebGL1/2 Worker queues COPY, sampled draw and color-set retirement before readback, retaining exact pixels with no intervening finish. 24 snapshot/contract tests, software backend regressions, existing native StretchRect/suspend/nested-call tests and the full normal/compat build pass. The initial tests caught an unsupported 2f uniform setter (the helper now uses the existing 4f contract) and an incorrect test assumption about default A8 backbuffer alpha. Build reconciliation reviewed the earlier DrawProducer factory addition to guest-worker and updated only its stale callback census hash/review; callback ownership remains pending. Evidence and source patch are recorded in scratch/runs/20261109-d3d-copy-executors/.

Activation validation additionally checks descriptor mutation before delayed publication, nested pending calls and absence of readback/upload host opcodes. The public x86 COM browser fixture copies each rendered geometry target before checking pixels and requires three published copies per run. WebGL and software run both WASM builds with diagnostics off/on; evidence is recorded under scratch/runs/20261109-d3d-copy-activation-{webgl,software}/test-result.json. No gameplay FPS improvement is claimed for this change.

ColorFill (native opcode0x30014) uses RenderClear.captureNativeColorFill in both the guest producer and page bridge. It names its destination explicitly, owns its rectangle/color, and ignores draw viewport, scissor, channel mask and depth attachment. It publishes ordinary API4 CLEAR commands, including an initial color definition when needed; startup fills also deliver the endpoint channel for subsequent publication. Invalid captures keep the broker's error path. Delayed-publication tests mutate the descriptor before admission and verify original pixels/rectangle metadata and scissor independence. The public x86 geometry fixture uses three ColorFill backgrounds and requires exactly three published clears before checking its readback pixels on both renderers and both WASM builds, diagnostics off/on. Evidence: scratch/runs/20261109-d3d-colorfill-{webgl,software}/test-result.json. Native direct/Worker ColorFill tests cover bound-target independence, subrects, invalid extents, locks and RGB565 destinations. No new performance claim.

DrawProducer.captureNativeColorUpdate is the common page/guest decoder for the native UpdateSurface upload descriptor (opcode0x30015). It validates destination bounds, format, source stride/range and allocation budget, then owns only the requested rows with padding removed. The guest publishes under the native state guard and checks the endpoint epoch again after capture. The receiver consumes the neutral update result before retiring its publication reference. Subsequent readbacks remain ordered behind the upload. Invalid or unadmitted uploads fall back before publication; an accepted upload never carries a borrowed guest-memory view.

Validation includes a held-consumer Worker upload with immediate source reuse, padded32-bit and RGB565 rows, invalid extents/ranges and allocation budget. Generated x86 public-COM tests (--color-upload) upload one pixel, overwrite the source, and check the original destination via LockRect alongside the independent geometry oracle. WebGL named-target and software implicit-backbuffer cases pass on normal/compat modules, diagnostics on/off, with nonzero actual upload-publication counters. Evidence is under scratch/runs/20261108-d3d-upload-webgl and scratch/runs/20261108-d3d-upload-software-format (test-result.json). The first software fixture rejected UpdateSurface because its hard-coded source format differed from the implicit destination; the fixture now uses public GetDesc to select the matching source format. Failed attempts are retained in the corresponding -software and -software-diagnostic evidence folders. Native direct/Worker color surface and shared GL protocol regressions also pass. These tests establish ownership and ordering, not a gameplay FPS improvement.

Writable surface UnlockRect uploads (opcode0x30011) now use the same owned RESOURCE_UPDATE publication path. captureNativeSurfaceUpload shares native identity/range validation between the broker and guest producer and packs full surface rows without padding. Only this upload resolver permits a locked native record: the native unlock handler holds the D3D guard and clears its lock after the import has captured/published the bytes. Draw and clear resolvers still reject locked resources. Read locks/readbacks retain their synchronous broker result, fenced behind all previous publications. Unadmitted surfaces retain the existing broker behavior, and a native read-only unlock issues no upload.

The --surface-upload generated-PE fixture writes through LockRect, unlocks, reuses the old pixel storage, and reads back the original uploaded pixel. Every normal/compat WebGL/software run (diagnostics on/off) records exactly three published writable-unlock uploads, with no read-only unlock uploads. Evidence: scratch/runs/20261109-d3d-unlock-webgl/test-result.json and scratch/runs/20261109-d3d-unlock-software/test-result.json. Transport tests hold consumption during pixel reuse, check packed RGB565 rows, wrong-device rejection and inconsistent native size; all21 snapshot cases and native direct/Worker color-surface regressions pass. No gameplay FPS gain is inferred from these correctness checks.

OpenGL retains native gl_object_leave publication under the shared-object lock. Removing that native flush would break completed cross-thread texture visibility. Instead, its host import can capture the bytes into the ring and return without page admission. Adjacent packets of the same API and producer are combined up to 512 KiB, rebasing captured-pointer offsets. This is a grouping limit, not a minimum amount that must accumulate before rendering starts.

Native GL barriers, unknown operations, borrowed inputs, bitmap/child drawable paths, software GL control metadata and unavailable canonical window ownership retain synchronous handling. Software GL raster batches still use the common D3D encoder publication path. The WebGL Worker path marks the canonical window GPU-owned before publishing. GDI must then fence prior publications and materialize the GL frame before reading pixels. Ownership clearing uses a nonblocking empty-ring guard so an older readback cannot clear a newer producer's dirty mark. Owned snapshots keep their explicit command buffer even when the render adapter chooses synchronous execution for an opcode.

When shared publication is enabled, fallback GL submissions cannot lease native stream slots. Publication lets the producer rotate those slots independently of renderer completion; mixing a leased fallback with copied publications could overwrite the lease. Eligible fallback batches instead take an owned snapshot before acknowledging the producer. The original leased path remains available when shared publication is disabled.

Glide publishes ordinary batch packets; open/close, swap and readback retain their existing synchronous contracts. Each Glide packet's execution boundary is retained, including front-buffer publication. Direct3D publishes descriptors for already-leased buffers; those buffers still retire through its existing completion counters. No extra copy of D3D vertices is introduced. Eligible Direct3D9 draws, clears, color uploads/definitions and resource retirement use API4 snapshots described above; result-bearing lifecycle/readback calls retain their existing synchronous contracts.

Synchronous broker requests with graphics dependencies fence earlier shared publications before dispatch. Publication admission is not GPU completion. Existing render-worker fences still implement queries, readbacks and API completion requirements. The only broker exception currently is get_mouse_position: it checks queue failure but does not wait for render admission. The page still answers the query after preceding async cursor warps have been flushed in FIFO order; clipping and active-event coordinates remain page-owned. A warp invalidates the producer's pointer cache even if the shared input epoch has not changed. The real-Worker test holds a Glide publication while two clipped cursor queries complete, then proves a following graphics-dependent invalidate cannot dispatch until that publication is admitted. Other imports remain conservatively fenced unless separately proven independent of graphics. Normal thread exit publishes buffered D3D draws and fences admission after DLL detach callbacks, before reporting exit to the scheduler. Otherwise a producer's endpoint could retire while its last packets still wait in the publication ring. Forced process cancellation continues to fail the ring and wake blocked writers.

This implementation still copies GL/Glide bytes into the ring and snapshots them for render admission. The reader borrows contiguous ring ranges until admission completes, copying a range only when it crosses the ring boundary. It removes per-command message round trips; it does not claim zero-copy native encoding or direct producer-to-renderer routing. The page remains responsible for drawable routing and presentation metadata.

Validation lives in the existing render lifecycle, GL shared-worker, Glide shared-worker, GL/GDI composition and Direct3D browser tests. Real producers exercise wraparound, tiny-ring backpressure, immutable payloads, query ordering, coalesced wake-ups, cross-API packet ordering, failure wake-ups and dirty-window ownership. Gameplay evidence and limitations are in re-notes/half-life-uplink.md.

Remaining migration and verification

This is not yet a completed migration of every graphics API. The following requirements remain open; a passing GL gameplay run does not discharge them.