@nika-js/onlymap 0.1.0

package/dist/dev-error-panel.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Dev-mode error panel (spec: "Dev-mode error panel (HU4)") — the human-
+ * facing counterpart to the agent feedback loop; a renderer of live
+ * validation output, no new validation logic. Own shadow DOM (style
+ * isolation, like widgets), fixed corner, high z-index, non-blocking (never
+ * intercepts map interaction outside its own small footprint), folds to a
+ * count badge, expands to the full list, click-to-locate flashes the
+ * offending element.
+ */
+import type { ValidationResult } from "./validation";
+export interface ErrorPanelHandle {
+    update(result: ValidationResult): void;
+    destroy(): void;
+}
+export declare function createErrorPanel(mapEl: HTMLElement): ErrorPanelHandle;

package/dist/draw-controller.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Sketch-capture controller (spec: "Manual Drawing", phases D3/D4). The
+ * stateful island that bridges the pure DrawSession (src/draw.ts) into the
+ * runtime: it consumes map click/hover coordinates (routed from the core's
+ * onMapPoint), drives the in-progress preview via the per-frame channel,
+ * pushes committed features into the live `draw:<name>` store, toggles
+ * double-click-zoom while a tool is active, and saves to a local file.
+ *
+ * Owned per <om-map> (the tooltip-overlay WeakMap precedent) and driven by
+ * `draw-*` actions (src/actions.ts) plus keyboard — so the widget stays pure
+ * UI and no "widget injects a layer" capability is needed.
+ */
+import { type DrawMode } from "./draw";
+import type { RuntimeCore } from "./runtime-core";
+export type SaveMode = "download" | "file-system" | "both";
+/** `sketch` → `draw:sketch` (idempotent if already prefixed). */
+export declare function drawUrl(target: string): string;
+export declare class DrawController {
+    private readonly mapEl;
+    private readonly core;
+    private readonly sessions;
+    private readonly autosaveKeys;
+    private active;
+    constructor(mapEl: Element, core: RuntimeCore);
+    /** A draw tool is active — om-map routes points here and suppresses selection. */
+    isCapturing(): boolean;
+    /** Enable localStorage autosave for a target and restore any saved sketch (draw-config action). */
+    configure(target: string, opts: {
+        autosave?: string;
+    }): void;
+    setMode(target: string, mode: DrawMode | null): void;
+    private deactivate;
+    point(coord: [number, number] | null, kind: "click" | "hover"): void;
+    /** Close the in-progress line/polygon — from the double-click DOM event or Enter. */
+    commit(): void;
+    cancel(): void;
+    /** Enter closes the shape, Escape cancels it. */
+    handleKey(key: string): void;
+    /** Remove the most recently drawn shape (v1 "delete last" — no per-feature selection yet). */
+    deleteLast(target: string): void;
+    clear(target: string): void;
+    save(target: string, mode?: SaveMode): Promise<void>;
+    private sessionFor;
+    private renderPreview;
+    private ensurePreviewLayer;
+    private removePreviewLayer;
+}
+/** Get-or-create the controller for a map element. */
+export declare function getDrawController(mapEl: Element, core: RuntimeCore): DrawController;
+/** Peek without creating — om-map's hot onMapPoint/selection paths use this. */
+export declare function peekDrawController(mapEl: Element): DrawController | undefined;

package/dist/draw.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Manual drawing — sketch-capture state machine (spec: "Manual Drawing —
+ * Sketch Capture", phase D1). PURE and render-free: it turns a sequence of
+ * map clicks + mode transitions into RFC 7946 GeoJSON features. The widget
+ * (D3) feeds it pointer/keyboard events; the live source (D2) reads its
+ * FeatureCollection and pushes commits through the streaming channel. No
+ * deck.gl, no DOM, no GL — so the whole capture contract is unit-testable
+ * with synthetic coordinates.
+ */
+export type DrawMode = "point" | "line" | "polygon";
+/** [lng, lat] — the map's own coordinate order, same as every accessor. */
+export type Position = [number, number];
+export interface PointGeometry {
+    type: "Point";
+    coordinates: Position;
+}
+export interface LineGeometry {
+    type: "LineString";
+    coordinates: Position[];
+}
+export interface PolygonGeometry {
+    type: "Polygon";
+    coordinates: Position[][];
+}
+export type DrawGeometry = PointGeometry | LineGeometry | PolygonGeometry;
+export interface DrawFeature {
+    type: "Feature";
+    geometry: DrawGeometry;
+    /** RFC 7946 top-level id — the same slot findRowIndexById / anchors read. */
+    id: string;
+    properties: {
+        drawMode: DrawMode;
+    };
+}
+export interface FeatureCollection {
+    type: "FeatureCollection";
+    features: DrawFeature[];
+}
+/** The in-progress shape, for the runtime-internal preview layer (D4). */
+export interface DrawPreview {
+    mode: DrawMode;
+    /** Committed-so-far vertices of the current shape. */
+    vertices: Position[];
+    /** The live cursor position, for the rubber-band segment (null before first move). */
+    cursor: Position | null;
+}
+export interface DrawSessionOpts {
+    /** Injectable id generator — a deterministic counter by default (tests assert structure, not entropy). */
+    idGen?: () => string;
+    /** Fired whenever the COMMITTED feature set changes (commit / delete / clear / seed) — D2 wires this to the store push. */
+    onChange?: (fc: FeatureCollection) => void;
+}
+/**
+ * One sketch session. Owns the committed features and the single in-progress
+ * shape. Every mutation that changes the committed set fires `onChange` once.
+ */
+export declare class DrawSession {
+    private mode;
+    private pending;
+    private cursor;
+    private features;
+    private readonly nextId;
+    private readonly onChange?;
+    constructor(opts?: DrawSessionOpts);
+    /** Switch tool (or `null` to deactivate). Discards any in-progress shape. */
+    setMode(mode: DrawMode | null): void;
+    getMode(): DrawMode | null;
+    /**
+     * A map click. Point commits immediately (the tool stays active for the
+     * next point); line/polygon append a vertex. Returns the committed feature
+     * when this click finalized one (point only), else null.
+     */
+    click(pos: Position): DrawFeature | null;
+    /** Cursor moved — updates the rubber-band target. No committed-set change. */
+    move(pos: Position): void;
+    /**
+     * Finalize the in-progress line/polygon (from double-click / Enter). A
+     * trailing duplicate vertex — the second click of a double-click — is
+     * dropped first. No-op (shape kept pending) if there aren't enough
+     * distinct vertices yet. Returns the committed feature or null.
+     */
+    commit(): DrawFeature | null;
+    /** Esc — discard the in-progress shape, keep the tool active. */
+    cancel(): void;
+    /** Delete one committed feature by id. Returns whether anything was removed. */
+    delete(id: string): boolean;
+    /** Remove the most recently committed feature — the toolbar's "delete last" (v1 has no per-feature selection). */
+    deleteLast(): boolean;
+    /** Remove every committed feature and any in-progress shape. */
+    clear(): void;
+    /** Load an existing FeatureCollection to append to (autosave restore / seed `data`). */
+    seed(fc: FeatureCollection | {
+        features?: unknown;
+    } | null | undefined): void;
+    toFeatureCollection(): FeatureCollection;
+    /** The in-progress shape for the preview layer, or null when nothing is pending. */
+    preview(): DrawPreview | null;
+    private finalize;
+    /** Re-key a seeded feature to this session's id space, preserving its geometry. */
+    private adopt;
+    private emit;
+}

package/dist/effects.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Effect runner (spec: "Map Stories / Effect verbs", Phase C) — drives the
+ * per-frame channel for the verbs that need a clock (`trace`, `pulse`).
+ * `fade` is NOT here: it's pure attribute mechanics (opacity + transition),
+ * which keeps it DOM-visible and scrub-capturable.
+ *
+ * One active effect per (core, layer): starting a new one cancels the old
+ * (last-write-wins, the library-wide action rule). prefers-reduced-motion
+ * jumps straight to the final frame — same contract as camera animation.
+ */
+import type { RuntimeCore } from "./runtime-core";
+/** Pure easing/oscillation math — unit-testable without a clock. */
+export declare function traceProgress(t01: number, t0: number, t1: number): number;
+/** Oscillates 1 → low → 1 per cycle (cosine), ending exactly at 1 for whole cycles. */
+export declare function pulseOpacity(t01: number, cycles: number, low?: number): number;
+export interface LayerEffect {
+    /** t01 ∈ [0, 1] → the plain-prop patch for this frame. */
+    frame(t01: number): Record<string, unknown>;
+    /** What to do at the end: hold the final frame's patch, or clear it. */
+    end: "hold" | "clear";
+    /** Runs after the end state is applied — phase chaining (trace: draw → reveal → dissolve). */
+    onDone?(): void;
+}
+/**
+ * Per-feature trace geometry (spec: "Effect verbs / per-feature trace") —
+ * pure: a GeoJSON-ish feature (or bare geometry / flat row) → the outline
+ * path with CUMULATIVE-DISTANCE timestamps, so the draw speed is uniform
+ * around the perimeter regardless of vertex spacing. Polygon → outer ring;
+ * MultiPolygon → first polygon's outer ring; LineString → the line itself.
+ * Returns null for untraceable geometry (points, missing geometry).
+ */
+export declare function buildTraceOutline(feature: unknown): {
+    path: [number, number][];
+    timestamps: number[];
+    total: number;
+} | null;
+export declare function cancelLayerEffect(core: RuntimeCore, layerId: string): void;
+export declare function cancelAllLayerEffects(core: RuntimeCore): void;
+export declare function runLayerEffect(core: RuntimeCore, layerId: string, durationMs: number, effect: LayerEffect): void;

package/dist/elements/om-behavior.d.ts

@@ -0,0 +1,13 @@
+/**
+ * <om-behavior> — a config element (spec: "Behavior Engine" — "Declarative
+ * event->action wiring"), not a rendered one, same role as <om-layer>: its
+ * attributes are read by OmMapElement's pick/lifecycle dispatch, not by
+ * this class itself. `on`/`layer`/`action` are the wiring; every OTHER
+ * attribute becomes an extra fixed payload key (kebab->camel, like data-emit)
+ * merged with the pick-derived payload — e.g. `target`/`anchor-offset` for
+ * show-overlay, `template` for show-tooltip.
+ */
+import { HTMLElementBase } from "../env";
+export declare class OmBehaviorElement extends HTMLElementBase {
+    connectedCallback(): void;
+}

package/dist/elements/om-layer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * <om-layer> — a config/data element, not a rendered one. Its attributes
+ * are read directly by parse-manifest.ts on each reconcile; this class only
+ * needs to exist so the browser upgrades the tag and keeps it out of layout.
+ * (Phase 3+ gives this a real connectedCallback for the per-element registry
+ * described in Q5; Phase 1's naive reconciler re-queries the DOM each time.)
+ */
+import { HTMLElementBase } from "../env";
+export declare class OmLayerElement extends HTMLElementBase {
+    connectedCallback(): void;
+}

package/dist/elements/om-map.d.ts

@@ -0,0 +1,168 @@
+/**
+ * <om-map> — spec: "Manifest Format / Core elements", "Architecture Layers",
+ * "Runtime Context API", "Reactivity — the watch declaration".
+ * Light DOM (spec: "DOM Model — Shadow vs. Light"): hosts the deck.gl canvas
+ * (inside an internal mount div) and the <om-layer>/<om-widget> children
+ * as normal siblings.
+ *
+ * Reconciler: full reparse per reconcile (still no diff-skipping of unchanged
+ * DOM — accessor-level memoization/fingerprinting does the real work, see
+ * attribute-resolution.ts / runtime-core.ts), microtask-batched (spec:
+ * "MutationObserver burst batching") so N mutations in one synchronous burst
+ * collapse into a single reconcile. No basemap adapter yet (Phase 6).
+ *
+ * Phase 4: also the widget pub-sub hub — maintains the live layer-IR
+ * registry (for ctx.layers/data/stats), the current selection, and notifies
+ * registered widgets per their `watch` tokens (spec: "Reactivity"). This
+ * internal registration API (registerWidgetInternal/unregisterWidgetInternal/
+ * emit) is consumed by OmWidgetElement, not part of the public package API.
+ */
+import { HTMLElementBase } from "../env";
+import { type RuntimeContext } from "../ctx";
+import type { LayerIR } from "../ir";
+import type { Selection } from "../selection";
+import type { MapViewport } from "../basemap";
+interface OverlayHost {
+    updatePosition(viewport: MapViewport | undefined, selection: Selection | null): void;
+}
+export declare class OmMapElement extends HTMLElementBase {
+    private core;
+    private observer;
+    private keydownHandler?;
+    private dblclickHandler?;
+    private contextmenuHandler?;
+    private mount;
+    private reconcilePending;
+    private layerIRs;
+    private selection;
+    private widgets;
+    private overlays;
+    private overlayFlushPending;
+    private errorPanel;
+    private runtimeErrors;
+    private readyFired;
+    private resolveReady;
+    readonly ready: Promise<void>;
+    private firstReconcileDone;
+    private rendererLoadPending;
+    private loadDispatched;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    registerWidgetInternal(el: Element, watch: string[], notify: (ctx: RuntimeContext) => void): void;
+    unregisterWidgetInternal(el: Element): void;
+    registerOverlayInternal(overlay: OverlayHost): void;
+    unregisterOverlayInternal(overlay: OverlayHost): void;
+    /**
+     * rAF-batched (spec: "Overlay Renderer" — the callback only stores the
+     * latest state and schedules one requestAnimationFrame; every overlay's
+     * `viewport.project()` + DOM write happens in that one flush, coalescing
+     * multiple viewport/selection changes per frame into one DOM pass).
+     */
+    private scheduleOverlayFlush;
+    emit(event: string, payload?: Record<string, unknown>): void;
+    /** Recenters (and optionally rezooms) the map — instant, not an animated fly. */
+    flyTo(coords: [number, number], zoom?: number, opts?: {
+        duration?: number;
+        curve?: boolean;
+    }): void;
+    setLayerVisible(id: string, visible: boolean): void;
+    /** A snapshot of the current layer IRs — the same shape `ctx.layers` is built from. */
+    getLayers(): readonly LayerIR[];
+    private notifyWidgets;
+    private buildCurrentCtx;
+    /** Picked object, normalized to flat — GeoJSON properties lifted; columnar rows materialized from columns at the pick index. */
+    private resolvePickedObject;
+    /**
+     * The single selection path — deck.gl's real picks (via RuntimeCore's
+     * onSelectionChange callback) and synthetic harness picks
+     * (injectPickInternal) both land here, so flattening, columnar row
+     * materialization, widget notification, overlay flush, and behavior
+     * dispatch are same-path by construction.
+     *
+     * Flattening happens here (not in toSelection()) — this is the one place
+     * with access to the picked layer's shape, needed for GeoJSON `{{field}}`
+     * template interpolation against ctx.selection.object (spec: "Because the
+     * picked object is already normalized to flat..."). Columnar layers pick
+     * with no object at all (deck.gl's non-iterable data path only reports the
+     * index) — materialized here, the one place with both the index and the
+     * layer's columns.
+     */
+    private handleSelectionChange;
+    /**
+     * The single drag-pick path — deck.gl's continuous drag picks (via
+     * RuntimeCore's onDragPick callback) and synthetic harness drags
+     * (injectDragPickInternal) both land here. Deliberately does NOT touch
+     * ctx.selection (spec: a widget watching `selection` shouldn't re-render
+     * on every drag-move) — it only dispatches `on="drag"` behaviors.
+     */
+    private handleDragPick;
+    /**
+     * Synthetic pick entries for the test harness (spec: "Consumer Testing
+     * Surface") — internal-suffix API like registerWidgetInternal, consumed
+     * by mountForTest's pick()/clearSelection(), not part of the public
+     * authoring surface.
+     */
+    injectPickInternal(selection: Selection | null): void;
+    injectDragPickInternal(selection: Selection): void;
+    /** Harness setView (spec: "Consumer Testing Surface") — the one path that reaches pitch/bearing. */
+    setViewInternal(partial: {
+        longitude?: number;
+        latitude?: number;
+        zoom?: number;
+        pitch?: number;
+        bearing?: number;
+    }): void;
+    /** Cancels all channel-driven effects (trace/pulse), clears their per-frame patches, and removes runtime temp trace layers — story scrub restore. */
+    clearEffectsInternal(): void;
+    /** A layer's current per-frame channel patch (tests/e2e assert trace progress through this). */
+    getAnimatedPropsInternal(layerId: string): Record<string, unknown> | undefined;
+    /** Current camera state (story initial-state capture) — internal-suffix API. */
+    getViewStateInternal(): {
+        longitude: number;
+        latitude: number;
+        zoom: number;
+        pitch: number;
+        bearing: number;
+    } | undefined;
+    /** Projects a lng/lat through the current viewport (harness pixel derivation) — undefined before the viewport resolves. */
+    projectInternal(lngLat: [number, number]): [number, number] | undefined;
+    /** Renderer finished async init — defer to the first reconcile if it hasn't run yet (see the field comment). */
+    private handleRendererLoad;
+    private dispatchRendererLoad;
+    /** Fires `om-map-ready` / resolves `.ready` once the first reconcile ran, the renderer is up, and no declared data URL is still loading. */
+    private checkReady;
+    private pickPayload;
+    /**
+     * Dispatches to every `<om-behavior on="eventName">` (live-queried, like
+     * the toggle-layer action's own `<om-layer>` lookups — behaviors are
+     * static config, not something worth maintaining a registry for). Every
+     * attribute besides `on`/`layer`/`action` becomes an extra fixed payload
+     * key (kebab->camel), merged with the pick-derived payload — e.g.
+     * `target`/`anchor-offset` for show-overlay, `template` for show-tooltip.
+     */
+    private dispatchToBehaviors;
+    /**
+     * Microtask-coalesced reconcile (spec: "MutationObserver burst batching").
+     * Any number of calls within one synchronous block collapse into a single
+     * reconcile() — an LLM streaming several attribute edits in one script
+     * shouldn't trigger a reconcile per edit.
+     */
+    private scheduleReconcile;
+    private reconcile;
+    /**
+     * Re-runs on every reconcile when the `validate` attribute is present —
+     * live editing feedback, not just the `OmMap.validate(htmlString)`
+     * pre-flight (which calls `validateManifest` directly, standalone).
+     * Runtime errors (the error boundary) are folded in too, so the agent
+     * sees one consistent stream regardless of origin. `validate="silent"`
+     * still runs validation and fires the event, just skips the on-page panel
+     * (spec: "for teams building their own error UI").
+     */
+    private publishValidation;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "om-map": OmMapElement;
+    }
+}
+export {};

package/dist/elements/om-overlay.d.ts

@@ -0,0 +1,82 @@
+/**
+ * <om-overlay> — sparse, rich geo-anchored HTML (spec: "Module Breakdown /
+ * Overlay Renderer", "Overlay System — Three-Way Split"). Rendered in
+ * shadow DOM for style isolation, same as <om-widget>. Inline-only by
+ * design — no `type` resolution, no `registerOverlay` (see spec's own
+ * rationale: a `<template>` shared across maps, or the future React
+ * component, already serve reuse).
+ *
+ * Positioning is centrally rAF-batched by OmMapElement (one flush handles
+ * every registered overlay's `viewport.project()` + DOM write per frame,
+ * "coalescing multiple events per frame into one DOM pass") — this class
+ * never schedules its own rAF, just exposes `updatePosition()` for the map
+ * to call.
+ */
+import { HTMLElementBase } from "../env";
+import type { MapViewport } from "../basemap";
+import type { Selection } from "../selection";
+export declare class OmOverlayElement extends HTMLElementBase {
+    private root;
+    private mapEl;
+    private content;
+    /** The authored light-DOM markup, captured once, before any interpolation — the source every interpolation pass re-runs against. */
+    private template;
+    /**
+     * The last selection-derived anchor this overlay actually used — only
+     * meaningful (and only ever updated) when a `layer` attribute scopes this
+     * overlay to one layer's selections. Without scoping, multiple overlays
+     * all sharing the one global `ctx.selection` (a click-shown popup on one
+     * layer, a hover-shown tooltip on another) fight over the same value: the
+     * MOST RECENT selection wins regardless of which overlay it was meant
+     * for, so a click on layer A yanks layer B's already-open overlay to the
+     * click point (and vice versa) — visible as the overlay jumping to the
+     * wrong place, then fighting deck.gl's own picking for the pointer
+     * underneath it. With `layer` set, a non-matching selection (including a
+     * null one — hover-out elsewhere) is treated as "not my concern" and
+     * simply doesn't update this remembered anchor; only a matching
+     * selection moves it, and only an explicit `visible="false"` hides it.
+     */
+    private lastAnchor;
+    /** Memoized feature anchor — recomputed only when the layer's data reference or the target id changes (live layers swap data). */
+    private featureAnchorCache;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Replaces the overlay's content template (used by the internal, runtime-
+     * managed tooltip overlay the `show-tooltip` action drives — see
+     * actions.ts — which clones a different author-referenced `<template>`
+     * per call rather than being authored once like a normal `<om-overlay>`).
+     */
+    setContent(html: string): void;
+    /**
+     * `anchor-layer="regions" anchor-feature-id="mission"` — anchored to a
+     * FEATURE (bbox center for polygons/lines, the point itself for flat
+     * rows) instead of a hardcoded coordinate, so the overlay follows the
+     * data. Resolved against the layer's live IR on each flush, memoized by
+     * data reference; empty data (still loading) resolves quietly and
+     * retries on the next flush.
+     */
+    private resolveFeatureAnchor;
+    /**
+     * Overlays with no interactive content default to `pointer-events: none`
+     * — there's nothing in them to click/hover, so letting them sit on top of
+     * the deck.gl canvas would only ever cost picking, never gain anything.
+     * That matters most for a hover-anchored overlay (any `anchor-from=
+     * "selection"` overlay shown from a hover behavior, like the built-in
+     * tooltip mechanism): it renders directly over the hovered point, and
+     * without this, moving the cursor toward the overlay hands mouse events
+     * to this DOM element instead of the canvas underneath — deck.gl loses
+     * the hover pick, the overlay hides, the canvas is exposed again, the
+     * same pick re-fires, and the cycle repeats as a visible flicker. An
+     * overlay WITH interactive content (a `data-emit` close button, say)
+     * keeps normal pointer-events so that content stays clickable.
+     */
+    private updatePointerEvents;
+    /**
+     * Called by OmMapElement's batched flush on every viewport/selection
+     * change. Resolves the anchor coordinate (`anchor-from="selection"` or a
+     * static `anchor="[lng,lat]"`), culls off-screen/behind-camera anchors,
+     * and re-interpolates `{{field}}` tokens against the current selection.
+     */
+    updatePosition(viewport: MapViewport | undefined, selection: Selection | null): void;
+}

package/dist/elements/om-step.d.ts

@@ -0,0 +1,12 @@
+/**
+ * <om-step> — a config element (spec: "Map Stories / Grammar"), the same
+ * citizenship class as <om-behavior>: its attributes are read by the
+ * parent <om-story>'s timeline build, never by this class itself. Steps
+ * REFERENCE layers/overlays by id and are only valid inside <om-story>;
+ * a step that CONTAINS elements is a validation error (the
+ * reference-never-contain rule, enforced mechanically).
+ */
+import { HTMLElementBase } from "../env";
+export declare class OmStepElement extends HTMLElementBase {
+    connectedCallback(): void;
+}

package/dist/elements/om-story.d.ts

@@ -0,0 +1,67 @@
+/**
+ * <om-story> — the storyboard element (spec: "Map Stories"). A story is a
+ * time-sequenced action dispatcher: where <om-behavior> maps event →
+ * action, a story maps time → action, through the exact same action-payload
+ * contract (mapEl.emit). It owns the clock; nothing owns the story — the
+ * player widget is optional chrome that emits story-play/pause/seek.
+ *
+ * Composability guarantee (spec): steps reference layers/overlays by id and
+ * never contain them; delete the story and the map is byte-for-byte the
+ * same map.
+ *
+ * Scrub model (spec, v1): seek(T) = restore captured initial state, then
+ * re-fire the FINAL state of every step starting ≤ T (instant — payload
+ * duration overridden to 0). Step-granularity; mid-step interpolation is
+ * deferred. Initial state is captured on first play from the attributes the
+ * built-in-action steps will touch (statically computable from payloads)
+ * plus the camera; custom-action steps are replay-only (warned once).
+ */
+import { HTMLElementBase } from "../env";
+export type StoryState = "idle" | "playing" | "paused" | "ended";
+export declare class OmStoryElement extends HTMLElementBase {
+    private mapEl;
+    private steps;
+    private timeline;
+    private fired;
+    private elapsed;
+    private stateValue;
+    private raf;
+    private lastTimestamp;
+    /** Set by the test harness (advanceInternal): the clock is driven manually, never by rAF. */
+    private manualClock;
+    private captured;
+    private capturedCamera;
+    private warnedCustomActions;
+    private readonly onUserGesture;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    get state(): StoryState;
+    get currentTime(): number;
+    get duration(): number;
+    play(): void;
+    pause(): void;
+    seek(ms: number): void;
+    /**
+     * Test-harness clock drive (spec: "Consumer Testing Surface" +
+     * "Map Stories"): switches this story to a manual clock permanently and
+     * advances it deterministically — rAF never runs for a manual story, so
+     * headless tests are exact.
+     */
+    advanceInternal(ms: number): void;
+    private startClock;
+    private stopClock;
+    private advanceBy;
+    private fireDueSteps;
+    /** Steps and the timeline are (re)built lazily when idle — mid-play DOM edits apply on the next play/seek. */
+    private ensureBuilt;
+    private ensureCaptured;
+    private restoreInitial;
+    private attachInterruptListeners;
+    private detachInterruptListeners;
+    private tick;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "om-story": OmStoryElement;
+    }
+}

package/dist/elements/om-widget.d.ts

@@ -0,0 +1,29 @@
+/**
+ * <om-widget> — spec: "DOM Model — Shadow vs. Light", "Widget System",
+ * "Runtime Context API", "Reactivity — the watch declaration",
+ * "Wiring DOM events to emits — two layers".
+ *
+ * Three tiers, one registry: `type="legend"` etc. resolve against the
+ * built-in/registered widget registry; no `type` + a `<script type="om/widget">`
+ * child runs as an inline custom widget; no `type` and no script is a purely
+ * static widget (Phase 1 behaviour, unchanged).
+ */
+import { HTMLElementBase } from "../env";
+import { type WidgetHost } from "../widget-registry";
+import type { RuntimeContext } from "../ctx";
+export declare class OmWidgetElement extends HTMLElementBase implements WidgetHost {
+    root: ShadowRoot;
+    state: Record<string, unknown>;
+    /** Set by an inline `<script type="om/widget">` block (`this.watch = [...]`), if present. */
+    watch?: string[];
+    /** Set by an inline `<script type="om/widget">` block (`this.render = (ctx) => {...}`), if present. */
+    render?: (ctx: RuntimeContext) => void | Promise<void>;
+    private mapEl;
+    private renderFn?;
+    private watchTokens;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private setUpRenderer;
+    $(selector: string): Element | null;
+    $$(selector: string): NodeListOf<Element>;
+}

package/dist/env.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SSR-safe environment guards. The library must be import-safe outside a
+ * browser (Next.js server components, Jest/Vitest in node, agent pipelines
+ * running pre-flight validation server-side) — the research-validated
+ * failure mode is touching browser globals at import time (Mapbox GL's
+ * six-years-open #4593). Two rules keep us clean:
+ *
+ *   1. No module evaluates a browser global at import time. Class
+ *      declarations `extends HTMLElementBase` (below) instead of
+ *      `extends HTMLElement`, and element registration goes through
+ *      `defineElement`, which no-ops outside a browser.
+ *   2. Everything that genuinely needs a DOM (rendering, observers,
+ *      sandbox iframes) touches it inside methods/functions only.
+ *
+ * Outside a browser the custom elements are inert-but-importable: the
+ * classes exist (so types, registries, validation, expression compilation,
+ * and IR snapshots all work), they just never register or upgrade.
+ */
+export declare const isBrowser: boolean;
+/**
+ * Base class for the om-* custom elements. In a browser this IS
+ * HTMLElement; in node it's an empty class so the module can evaluate.
+ * Constructing an element outside a browser is not supported (nothing
+ * registers them there), so the stub never needs real behavior.
+ */
+export declare const HTMLElementBase: typeof HTMLElement;
+/**
+ * `customElements.define`, guarded twice: no-op outside a browser, and
+ * idempotent under double-import (a second `define` of the same name
+ * throws — a real hazard when a CDN tag and a bundled import coexist).
+ */
+export declare function defineElement(name: string, ctor: CustomElementConstructor): void;
+/**
+ * Parses a manifest HTML string into a Document — used by the string-input
+ * surfaces (`OmMap.validate(html)`, `snapshotIR(html)`). Neither needs a
+ * *browser* (no rendering, no custom-element upgrade — they read tags and
+ * attributes), but they do need a DOM implementation for DOMParser. In
+ * plain node, that means a test DOM: vitest/jest with the happy-dom or
+ * jsdom environment both provide it.
+ */
+export declare function parseHtmlDocument(html: string): Document;