What's wrong
The published API reference lists a large number of members that are engine internals — and separately, the emitted .d.ts offers them in consumers' autocomplete. These are two different leaks with two different causes, and a member can hit either or both.
@ignore hides a member from the docs (typedoc).
@internal is what scripts/strip-internal.ts removes from the emitted .d.ts.
A member tagged only @ignore stays in the published types. A member with no tag at all appears in both.
The script's own header names the goal exactly: "engine internals (pass lifecycle, texture retirement, …) would otherwise surface in consumers' autocomplete."
Scope
Counting only the unambiguous cases — underscore-prefixed fields, internal by this codebase's own convention, carrying no doc tag:
| class |
untagged _ fields |
Renderer |
4 |
WebGLRenderer |
22 |
WebGPURenderer |
7 |
Examples: _litPipelineWarned, _whitePixel, _activeTextureUnit, _effectPassDepth, _frameTexture, _currentGradient, _compressedTextureFormats, and the eight _advancedBlend* fields (duplicated across both GPU backends).
Alongside them, untagged internal methods are documented as public API: setBatcher, addBatcher, blitEffect, deleteMeshGeometry, setLightUniforms, clearRenderTarget, enableScissor / disableScissor.
Non-underscore internal fields were not counted, and there are more — lightUniformsScratch, maskDepthWarned, savedBlendMode, stubTextureView are all in the reference today. CanvasRenderer was not audited.
Why it matters
The reference is what someone reads to learn the engine, and the types are what their editor suggests while writing. Both currently present pass-lifecycle plumbing and one-shot warning flags as things to use. It also makes the genuinely public surface harder to find: the useful methods are buried among dozens that are not.
Fix
Tag internals @ignore and @internal — the pattern already used in ~65 places. Mechanical, but it wants a member-by-member judgement call about what is genuinely public, so it should not be bundled into a feature PR.
Worth doing in one sweep across Renderer, WebGLRenderer, WebGPURenderer and CanvasRenderer, then extending to other classes: the renderers were audited because that is where this surfaced, not because they are unique.
Already done
#1635 tagged the twelve methods and four fields it introduced, and verified they strip from the published types while flushTransparent and flushGroundShadows correctly remain. That is the pattern to follow; this issue is the rest of the surface.
What's wrong
The published API reference lists a large number of members that are engine internals — and separately, the emitted
.d.tsoffers them in consumers' autocomplete. These are two different leaks with two different causes, and a member can hit either or both.@ignorehides a member from the docs (typedoc).@internalis whatscripts/strip-internal.tsremoves from the emitted.d.ts.A member tagged only
@ignorestays in the published types. A member with no tag at all appears in both.The script's own header names the goal exactly: "engine internals (pass lifecycle, texture retirement, …) would otherwise surface in consumers' autocomplete."
Scope
Counting only the unambiguous cases — underscore-prefixed fields, internal by this codebase's own convention, carrying no doc tag:
_fieldsRendererWebGLRendererWebGPURendererExamples:
_litPipelineWarned,_whitePixel,_activeTextureUnit,_effectPassDepth,_frameTexture,_currentGradient,_compressedTextureFormats, and the eight_advancedBlend*fields (duplicated across both GPU backends).Alongside them, untagged internal methods are documented as public API:
setBatcher,addBatcher,blitEffect,deleteMeshGeometry,setLightUniforms,clearRenderTarget,enableScissor/disableScissor.Non-underscore internal fields were not counted, and there are more —
lightUniformsScratch,maskDepthWarned,savedBlendMode,stubTextureVieware all in the reference today.CanvasRendererwas not audited.Why it matters
The reference is what someone reads to learn the engine, and the types are what their editor suggests while writing. Both currently present pass-lifecycle plumbing and one-shot warning flags as things to use. It also makes the genuinely public surface harder to find: the useful methods are buried among dozens that are not.
Fix
Tag internals
@ignoreand@internal— the pattern already used in ~65 places. Mechanical, but it wants a member-by-member judgement call about what is genuinely public, so it should not be bundled into a feature PR.Worth doing in one sweep across
Renderer,WebGLRenderer,WebGPURendererandCanvasRenderer, then extending to other classes: the renderers were audited because that is where this surfaced, not because they are unique.Already done
#1635 tagged the twelve methods and four fields it introduced, and verified they strip from the published types while
flushTransparentandflushGroundShadowscorrectly remain. That is the pattern to follow; this issue is the rest of the surface.