ArtPlayer/packages/artplayer-proxy-canvas/ARCHITECTURE.md

Canvas proxy maintenance

Public entry: src/index.ts; public declarations remain in types/artplayer-proxy-canvas.d.ts. The factory accepts the optional drawing callback, then synchronously returns an actual HTMLCanvasElement when registered with ArtPlayer. The root preserves the latest npm 1.1.0 pure factory, optional callback and exact Canvas return extraction. Do not attach a required default member to this type: that breaks assigning an ordinary historical replacement function back to typeof factory. MediaCanvas is an explicit type view, not a narrowed factory result. CommonJS and browser factory.default remain runtime self aliases. Accurate RuntimeFactory lives behind the additive /runtime entry, whose runtime.d.mts/runtime.d.cts bridges distinguish ESM and CommonJS and whose runtime.d.ts supports old Node10 export= resolution. Both entrypoints load the same existing dist files. The old root declaration bridges remain packaged, but root/legacy conditional types deliberately select the original .d.ts module shape. Root NodeNext ESM therefore keeps the published namespace shape; it is not silently made callable. Use /runtime for precise ESM default calls. The package README documents the approved 1.0 export= migration; no JavaScript calls were removed by this type decision. Historical JavaScript falsy callback arguments remain ignored at runtime; the typed public callback remains optional and function-valued.

Module	Ownership and responsibility
index.ts	Host event subscriptions, deferred media forwarding, initialization rollback and terminal disposal
adapter.ts	Preserve native canvas methods; forward only video properties absent from canvas; guard escaped media actions after disposal
subtitles.ts	Supply the initial native metadata track and route the core's actual HTML track insertion into the backing video
media.ts	Connect the backing video before playback and release its source, stream reference and DOM node
geometry.ts	Finite intrinsic dimensions and aspect-fit canvas/padding calculations
renderer.ts	Decoded-frame eligibility, bitmap acquisition/close, callback and draw/error notification order
scheduler.ts	One outstanding draw, coalesced requests, generations and nullable RAF ownership

Only the entry receives ArtPlayer. The renderer has no host/DOM ownership, the scheduler has no media knowledge, and geometry is independent of scheduling. No package imports private core implementation modules.

State and event order

Canvas methods keep their receiver and win over same-named video methods for ordinary Canvas content. appendChild has one intentional subtitle-specific adaptation: active HTML track elements attach to the backing video, where native loading and cuechange work. Other nodes still attach to the Canvas. The initial empty metadata track makes the old core's synchronous textTracks[0] capability check succeed; it is removed before the first actual track is appended. The core owns actual track replacement/removal and subtitle URLs. After destruction, escaped appendChild cannot attach more tracks to the unloaded private video. This fixes the formerly empty subtitle path; a working track's parent is now VIDEO. The initialization is inside the same rollback boundary as host registration.

Media properties remain live enumerable/configurable descriptors. Assigning src/srcObject or invoking load invalidates pending frames; the returned canvas and callback arguments keep their identities. The video is connected before play with absolute positioning, transparent opacity, no focus or pointer interaction, and intrinsic CSS sizing. Do not change it to a 1px square: tested WebKit then reports 1x1 media dimensions and loses the source geometry.

Media forwarding remains deferred until core initialization has installed its event registry. Native events are forwarded as video:<type> with the original Event. Native removal is owned before calling the extensible art.proxy registrar, so partial registration can roll back. Host subscriptions are also owned before art.on, including reentrant destruction during setup.

play starts one draw chain; duplicate play does not start another. resize coalesces a new draw and invalidates an in-flight result. pause/source replacement invalidates pending work and cancels the current RAF, including ID zero. Paused seek requests one fresh frame. After bitmap acquisition, stale results are closed without drawing. Acquired bitmaps are closed in finally even if drawImage throws, and before invoking the public callback. An active callback failure emits the original error; a callback destroying the host cannot emit a subsequent draw event or restart work. Observer failures cannot strand the scheduler busy.

readyState alone does not prove a drawable frame. Seeking or insufficient data suspends drawing. The recorded Chromium first-frame case rejects bitmap acquisition with InvalidStateError at currentTime 0 and zero video frames even at readyState 4; that exact acquisition condition is deferred until another request. A zero frame counter is not a general capability check: tested WebKit draws successfully with that counter at zero. Errors from user callbacks or drawImage are not classified as bitmap acquisition failures.

destroy invalidates generations, clears the deferred timer, removes all host/native subscriptions, pauses and unloads backing video, releases srcObject without stopping consumer-owned tracks, removes the internal video and clears canvas buffers. Cleanup attempts every resource even when one disposer throws. Captured play/load methods and forwarded setters become inert. Native Canvas methods still operate on the same element.

Verification and remaining work

yarn test:canvas runs frozen historical and candidate lifecycle tests. Candidate tests can be run against the frozen workspace with ARTPLAYER_CANVAS_BASELINE=1. Historical inputs come from verified archives/Git via refactor/scripts/canvas-contract.mjs, not current dist.

test/browser/canvas-lifecycle.spec.js tests actual candidate source, native pixels and dimensions, paused seek, source replacement, callback destruction and escaped methods on actual npm core 5.4.0 and the candidate core in three engines. ambilight-proxy.spec.js uses the candidate source loader after module splitting; its palette test proves sampling geometry and is separate from native media pixel acceptance. npm core 5.1.7 has no proxy option and is only a native-player capability control.

yarn test:canvas-types-package installs real archived and candidate packages outside the workspace, verifies installed bytes and checks old/current compiler modes. It preserves the actual old NodeNext direct-import errors and 1.0 export= differences, while testing latest namespace replacements, plain factory bidirectional assignments, runtime self identity and negative statements at their exact lines. No skipLibCheck or strictness relaxation is used. The public declarations also generate the local editor declaration through the semantic generator; the editor root stays plain, with an explicit artplayerProxyCanvas.RuntimeFactory assertion for code needing the runtime self alias. Broader installed artifact contents/deep paths and 8082 demos remain 06. Real Safari/mobile/device scope remains 05; Windows Playwright WebKit is not a device claim. canvas-subtitles.spec.js exercises native VTT load, paused seeking, replacement, single-track ownership, ordinary Canvas child insertion/removal and escaped insertion after destroy on old/new cores. It also belongs to the installed browser scope; keep its bytes and native engine provenance with the lifecycle report. See refactor/canvas-validation.md and the task evidence for actual outcomes and limitations.

canvas-dpip.spec.js follows the same Canvas, backing video and native subtitle track into actual Document PiP windows. It covers playback/draw advancement, paused subtitle seeking and close/native-close/destroy resource ownership. The installed scope requires Document PiP's own verified package bytes as well; a source helper may not fill a missing installed package. Unsupported native APIs are recorded separately and never treated as native playback evidence.