ump-plugin-observers

Web-spec IntersectionObserver and ResizeObserver for UMP apps, backed by the C++ RenderTree observer registry.

Install

npm install ump-plugin-observers

Peer dependencies (must already be installed in your app):

• ump-core
• ump-native

Usage

Importing the plugin (or its barrel) installs ResizeObserver and IntersectionObserver on globalThis (only when not already provided by the host) and exports them as named ES modules.

import { ResizeObserver, IntersectionObserver } from 'ump-plugin-observers';

// ResizeObserver — fires on layout-rect change of the target node.
const ro = new ResizeObserver((entries) => {
    for (const entry of entries) {
        console.log('size now', entry.contentRect);
    }
});
ro.observe(nodeRef);          // numeric node id, or { current: { __umpNodeId } }, or { __umpNodeId }
// ro.unobserve(nodeRef);
// ro.disconnect();

// IntersectionObserver — fires when the target crosses a threshold.
const io = new IntersectionObserver((entries) => {
    for (const entry of entries) {
        if (entry.isIntersecting) {
            console.log('visible', entry.intersectionRatio);
        }
    }
}, { threshold: [0.25, 0.5, 0.75] });
io.observe(nodeRef);

Target shape

Same as Gesture: numeric nativeNodeId, the React-style { current: { __umpNodeId } } ref shape, or a bare { __umpNodeId }. Targets that don't yet resolve to a numeric id are accepted but observe() is a no-op until the consumer re-observes after the ref populates.

Spec deviations (v1)

• IntersectionObserver:
  • root is ignored (always viewport).
  • rootMargin is parsed but not applied.
  • For an array threshold, the C++ side is registered against the minimum threshold; multi-threshold transition firing is approximate.
• ResizeObserver entries report contentRect only — borderBoxSize / contentBoxSize arrays are not synthesized.
• Scroll offsets do NOT re-trigger intersection in v1; child intersection ratios update only on layout-rect change of the target itself.

Migration from ump-native

In ump-native 0.1.x, ResizeObserver and IntersectionObserver were bundled with the main package. Starting 0.2.x, they ship as this separate plugin.

- import { ResizeObserver, IntersectionObserver } from 'ump-native';
+ import { ResizeObserver, IntersectionObserver } from 'ump-plugin-observers';

No API changes. Note: MutationObserver is not part of this plugin and remains in ump-native for now.