[Bug]: Annotations within Optional Content Layers are always shown

[faceless2]

Attach (recommended) or Link to PDF file

https://octopdf.com/octopdf-sample.pdf

Web browser and its version

Firefox 144.0.2

Operating system and its version

macOS

PDF.js version

from Firefox 144.0.2

Is the bug present in the latest PDF.js version?

Yes

Is a browser extension

No

Steps to reproduce the problem

Annotations can be assigned to an Optional Content Descriptor too. not just pages. But this isn't currently supported in pdf.js and they are always visible, regardless of which OC layers are visible.

1. Open the PDF, bring up the "layers" tab
2. Disable the "Form" layer

The widgets on page two are within that layer and should disappear, yet they remain visible.

What is the expected behavior?

As described

What went wrong?

As described

Link to a viewer

No response

Additional context

No response

[RoniMaity]

I’ve been able to reproduce this issue on the latest pdf.js build.

Tested using:

• pdf.js master (local build via npx gulp server)
• Viewer: http://localhost:8888/web/viewer.html
• Sample file: https://octopdf.com/octopdf-sample.pdf
• Browser: Chrome on macOS

Behavior observed:
When the “Form” optional content group is disabled in the Layers sidebar, the underlying page content correctly hides, but the form widgets/annotations on page 2 remain visible. These widgets appear to ignore the OCG visibility state.

I’m investigating the annotation pipeline and how OCG membership can be surfaced from annotation dictionaries so the annotation layer can respect OptionalContentConfig visibility. I’ll share findings and propose a patch once I have a clean solution.

[RoniMaity]

Hi, I’ve taken a closer look at this issue and validated the behavior with the latest pdf.js (development build from master).

Findings

• The PDF (octopdf-sample.pdf) displays annotations inside an Optional Content Group (“Form” layer).
• Toggling that layer in the viewer correctly hides the page content, but annotations remain visible, matching the issue description.
• While testing internally, I tried exposing /OC from the annotation dictionary.
  • Several annotations in the sample PDF do not include an /OC entry.
  • Because of that, simply propagating dict.get("OC") through Annotation.data is not sufficient, and in some cases injecting the raw dictionary triggers worker DataCloneError issues.
• This suggests that layer membership for these widgets is applied at the appearance stream/graphics level, not directly on the annotation dictionary.
• pdf.js currently applies Optional Content Group (OCG) visibility to page rendering, but not to annotation appearance rendering, so annotations ignore OCG state entirely.

Conclusion

The bug is reproducible on the latest build.
A correct fix would likely require making the annotation appearance rendering path OCG-aware (similar to how page content already uses OptionalContentConfig).
This would involve changes in the core operator-list / appearance-processing pipeline rather than only viewer-level adjustments.