Skip to content

Docs: engine internals are published in the API reference and in consumers' autocomplete #1637

Description

@obiot

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions