Sensitive Media Lightbox#

The Misskey-native lightbox is a fullscreen image/video viewer built entirely in Vue. It replaced the third-party PhotoSwipe dependency in PR #17687 (merged 2026-07-12), motivated by UX improvements, deeper integration with Misskey's UI, reduced implementation cost, and better performance.

The viewer is composed of four layers:

The Content Type Contract#

MkLightbox.item.vue exports the Content interface — the sole data contract between MkMediaList and the lightbox:

export type Content = {
  id: string;
  type: 'image' | 'video';
  url: string;
  thumbnailUrl?: string | null;
  width?: number | null;
  height?: number | null;
  filename?: string | null;
  file?: Misskey.entities.DriveFile; // full DriveFile for menus / sensitivity checks
  sourceElement?: HTMLElement | null; // the <img> in the grid, for open/close animation
};

MkMediaList assembles this array and opens the lightbox via os.popupAsyncWithDialog 1. The sourceElement is looked up by a data-marker attribute stamped on each grid <img> 2 and is used by MkLightbox.item to compute the expand/collapse transform animation 3.

Sensitive-Hide State#

Sensitive-hide state is managed independently in two places: the timeline grid thumbnail and the open lightbox item.

In the timeline grid (MkMediaImage)#

MkMediaImage maintains a local hide = ref(true) 4. On mount and whenever the image prop changes, it calls shouldHideFileByDefault to set the initial value 5. The watch is deep so plugin-driven note view interruptors can trigger re-evaluation.

When hidden, clicking calls canRevealFile — an async guard that optionally shows a confirmation dialog when prefer.s.confirmWhenRevealingSensitiveMedia is enabled 6. Only on approval is hide set to false.

When highlightSensitiveMedia is on, a 4 px warning-color inset box-shadow is added via CSS 7.

In the lightbox (MkLightbox.item)#

Each lightbox item has its own hide = ref(true) 8. The shouldHideInGallery function applies the same logic with one important exception: the first sensitive image opened in a gallery session is shown immediately (not hidden) as long as prefer.s.nsfw !== 'force' 9. Subsequent navigation to other sensitive items re-hides them.

The two hide states are independent — revealing an image in the grid does not pre-reveal it in the lightbox, and vice versa.

Utility functions#

Both components share two functions from sensitive-file.ts:

• shouldHideFileByDefault(file, ignoreDataSaver?) — returns true when nsfw === 'force', data-saver is active, or the file is sensitive and nsfw !== 'ignore' 10.
• canRevealFile(file) — async; shows a confirmation dialog if file.isSensitive && confirmWhenRevealingSensitiveMedia; returns false on cancel 11.

Lightbox Architecture#

MkLightbox (container)#

MkLightbox receives a Content[] array and a defaultIndex 12. Items are laid out as a horizontal flex strip; navigation is done by translating the strip with contentsOffset 13. Arrow-key navigation, Esc-to-close, and left/right click buttons are all wired here .

An activatedIndexes set controls lazy rendering: only items that have ever been the active index receive the full content load 16. This prevents preloading all media in the array on open.

The sourceElement of the currently active item is hidden (visibility: hidden) in the grid while the lightbox is open, providing the shared-element illusion 17.

On mount, window.history.pushState(null, '', '#pswp') is called so that the browser back button closes the lightbox 18. The #pswp hash name is kept for backwards compatibility.

MkLightbox.item (per-media pane)#

Each item handles:

• Open/close animation: if sourceElement is provided, the item starts at the source's CSS transform and animates to scale(1) translate(0,0). Without a source element it falls back to a fade-in from scale(0.7) .
• Gesture routing: single pointer events are routed to vertical-swipe-to-close, horizontal-swipe-to-navigate, or pan-while-zoomed; two-pointer events drive pinch zoom 21. See the Gesture Detection KB article for full detail.
• Loading strategy: a thumbnail is shown immediately; the full-resolution image/video is loaded only while the item is activated 22.
• Video control: injects the <video> element via DI token DI.mkLightboxItemVideoEl so child MkVideoControl can access it 23.

Migration from PhotoSwipe#

PR #17687 removed the photoswipe npm package and its Rollup chunk. Previously, opening any media required constructing specific DOM elements for PhotoSwipe; the native implementation accepts a plain Content[] array instead. The #pswp URL hash is retained so existing popstate listeners continue to work; the hash is cleaned up on page load per PR #17696.

Key improvements delivered by the migration:

• Sensitive-media reveal state is now tracked natively (PhotoSwipe had no concept of hidden media).
• Open/close animations use the actual source <img> element position rather than PhotoSwipe's separate thumbnail concept.
• All gesture code lives in a single file rather than being distributed across library internals.
• PR #17696 added video stop, back-button close, and the per-file popup menu.
• PR #17740 fixed a swipe-to-close regression where vertical swipes could be blocked.

Key Files#