@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/map/map.d.ts

@@ -1,5 +1,4 @@
 import { type TemplateResult, type PropertyValues } from 'lit';
-import type { Map as MaplibreMap, StyleSpecification } from 'maplibre-gl';
 import { LyraElement } from '../../internal/lyra-element.js';
 import '../skeleton/skeleton.js';
 export interface LegendEntry {
@@ -30,20 +29,34 @@ export interface MapMarker {
     /**
      * Rendered as the marker's popup content via maplibre-gl's
      * `Popup.setHTML()` -- parsed as raw markup, inline event handlers
-     * included. Only ever pass trusted content; sanitize anything derived
-     * from user input before assigning it here.
+     * included. This is the library's one explicit unsafe-HTML escape hatch:
+     * only ever pass trusted content, and sanitize anything derived from user
+     * input before assigning it here. Prefer `label` (rendered via the safe
+     * `Popup.setText()`) whenever the content is plain text.
      */
-    html?: string;
+    unsafeHtml?: string;
 }
 /**
  * `<lyra-map>` — a maplibre-gl wrapper with a declarative legend and
  * choropleth GeoJSON layer, plus a raw `map` escape hatch. Requires the
  * optional peer dep `maplibre-gl` (consumers also import its CSS once).
  *
+ * The underlying `maplibregl.Map` — and the WebGL context it opens — isn't
+ * constructed until this element is first visible in the viewport (tracked
+ * via `IntersectionObserver`), even once the `maplibre-gl` peer dependency
+ * has finished loading. Browsers hard-cap concurrent WebGL contexts per
+ * page, so a grid/dashboard of many `<lyra-map>` instances only constructs
+ * the ones actually on-screen instead of racing to exhaust that budget the
+ * instant each one mounts. `map` stays `undefined` (and `lyra-map-load`
+ * doesn't fire) until construction actually happens.
+ *
  * @customElement lyra-map
  * @event lyra-map-load - Fired once the underlying maplibregl.Map loads.
  * @event lyra-map-click - `detail: { lngLat, feature? }`.
- * @csspart base, container, legend, legend-swatch
+ * @csspart base - The map wrapper.
+ * @csspart container - The maplibre container.
+ * @csspart legend - The map legend.
+ * @csspart legend-swatch - A legend color swatch.
  *
  * ⚠️ The default `mapStyle` (when unset) uses OpenStreetMap's demo tile
  * server, which is not suitable for production traffic — see the
@@ -54,12 +67,14 @@ export declare class LyraMap extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
     center: [number, number];
     zoom: number;
-    mapStyle: StyleSpecification | string;
+    mapStyle: import('maplibre-gl').StyleSpecification | string;
     legend: LegendEntry[];
     choropleth?: ChoroplethLayer;
     markers: MapMarker[];
     /** True until the lazy-loaded `maplibre-gl` peer dependency has settled (success or failure). */
     private loading;
+    private visible;
+    private intersectionObserver?;
     private containerEl?;
     private _map?;
     private _styleLoaded;
@@ -67,11 +82,21 @@ export declare class LyraMap extends LyraElement {
     private _appliedFillLayerId?;
     private _maplibreModule?;
     private _markerInstances;
+    private _markerColors;
     private _connectGeneration;
     /** The raw `maplibregl.Map` instance — escape hatch for anything this wrapper doesn't expose. */
-    get map(): MaplibreMap | undefined;
+    get map(): import('maplibre-gl').Map | undefined;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * Constructs the underlying `maplibregl.Map` — called once both the
+     * lazy-loaded `maplibre-gl` module has resolved and this element has been
+     * observed intersecting the viewport, whichever settles last. Idempotent
+     * (a no-op once `_map` already exists), so it's safe to call from both the
+     * `connectedCallback()` load path and the visibility path in `updated()`
+     * below without risking a double construction.
+     */
+    private tryConstructMap;
     protected updated(changed: PropertyValues): void;
     private applyChoropleth;
     /** Removes whatever choropleth layer/source is currently applied, if any. */

package/dist/components/map/map.js

@@ -65,10 +65,22 @@ function sanitizeSwatchColor(color) {
  * choropleth GeoJSON layer, plus a raw `map` escape hatch. Requires the
  * optional peer dep `maplibre-gl` (consumers also import its CSS once).
  *
+ * The underlying `maplibregl.Map` — and the WebGL context it opens — isn't
+ * constructed until this element is first visible in the viewport (tracked
+ * via `IntersectionObserver`), even once the `maplibre-gl` peer dependency
+ * has finished loading. Browsers hard-cap concurrent WebGL contexts per
+ * page, so a grid/dashboard of many `<lyra-map>` instances only constructs
+ * the ones actually on-screen instead of racing to exhaust that budget the
+ * instant each one mounts. `map` stays `undefined` (and `lyra-map-load`
+ * doesn't fire) until construction actually happens.
+ *
  * @customElement lyra-map
  * @event lyra-map-load - Fired once the underlying maplibregl.Map loads.
  * @event lyra-map-click - `detail: { lngLat, feature? }`.
- * @csspart base, container, legend, legend-swatch
+ * @csspart base - The map wrapper.
+ * @csspart container - The maplibre container.
+ * @csspart legend - The map legend.
+ * @csspart legend-swatch - A legend color swatch.
  *
  * ⚠️ The default `mapStyle` (when unset) uses OpenStreetMap's demo tile
  * server, which is not suitable for production traffic — see the
@@ -85,6 +97,14 @@ export class LyraMap extends LyraElement {
         this.markers = [];
         /** True until the lazy-loaded `maplibre-gl` peer dependency has settled (success or failure). */
         this.loading = true;
+        // Gates the actual `new mod.Map(...)` construction (see `tryConstructMap()`)
+        // -- starts `false` so a `<lyra-map>` mounted off-screen doesn't open a
+        // WebGL context before it's ever seen, and only flips `true` once the
+        // IntersectionObserver below reports this element actually intersecting
+        // the viewport. Defaults `true` outright when `IntersectionObserver` isn't
+        // available at all (fail open, matching `lyra-chart`'s own fallback)
+        // rather than gating construction on an observer that will never fire.
+        this.visible = typeof IntersectionObserver === 'undefined';
         // Tracks whether the style has fired its initial 'load' (i.e. addSource/
         // addLayer/setPaintProperty are now safe to call), rather than re-querying
         // `this._map.isStyleLoaded()`: that also reflects in-flight *tile* loading
@@ -93,6 +113,14 @@ export class LyraMap extends LyraElement {
         // choropleth updates from ever re-running.
         this._styleLoaded = false;
         this._markerInstances = new Map();
+        // The installed maplibre-gl's `Marker` class has no `setColor()` (verified
+        // against its shipped `.d.ts` -- `color` is only ever consumed by the
+        // constructor), so an id-matched marker whose `color` changes can't be
+        // mutated in place; it has to be torn down and reconstructed instead. This
+        // tracks the color each currently-live marker instance was last
+        // constructed with, keyed the same as `_markerInstances`, so `applyMarkers`
+        // can detect that mismatch without re-deriving it from the DOM.
+        this._markerColors = new Map();
         // Bumped on every connectedCallback and captured by value in its
         // loadMaplibre().then() closure below. A disconnect immediately followed
         // by a reconnect (fast remounts, route/tab switches, etc.) before that
@@ -113,6 +141,17 @@ export class LyraMap extends LyraElement {
     connectedCallback() {
         super.connectedCallback();
         const generation = ++this._connectGeneration;
+        // A reconnect always tears the map down in disconnectedCallback() below,
+        // so it needs its own fresh visibility read rather than trusting
+        // whatever `visible` was left at from before the previous disconnect.
+        this.visible = typeof IntersectionObserver === 'undefined';
+        if (typeof IntersectionObserver !== 'undefined') {
+            this.intersectionObserver = new IntersectionObserver((entries) => {
+                if (entries[0]?.isIntersecting)
+                    this.visible = true;
+            });
+            this.intersectionObserver.observe(this);
+        }
         void loadMaplibre().then(async (mod) => {
             // A newer connectedCallback (disconnect + reconnect) already
             // superseded this attempt while loadMaplibre()'s cached promise was
@@ -136,28 +175,7 @@ export class LyraMap extends LyraElement {
             // cycle that happened during the `await` above.
             if (generation !== this._connectGeneration || !this.containerEl || !this.isConnected)
                 return;
-            this._map = new mod.Map({
-                container: this.containerEl,
-                style: this.mapStyle,
-                center: this.center,
-                zoom: this.zoom,
-            });
-            this._map.on('load', () => {
-                this._styleLoaded = true;
-                this.applyChoropleth();
-                this.applyMarkers();
-                this.emit('lyra-map-load');
-            });
-            this._map.on('click', (e) => {
-                const fillLayerId = this._appliedFillLayerId;
-                const features = fillLayerId && this._map.getLayer(fillLayerId)
-                    ? this._map.queryRenderedFeatures(e.point, { layers: [fillLayerId] })
-                    : [];
-                this.emit('lyra-map-click', {
-                    lngLat: [e.lngLat.lng, e.lngLat.lat],
-                    feature: features[0],
-                });
-            });
+            this.tryConstructMap();
         });
     }
     disconnectedCallback() {
@@ -167,15 +185,59 @@ export class LyraMap extends LyraElement {
         this._styleLoaded = false;
         this._appliedChoroplethSourceId = undefined;
         this._appliedFillLayerId = undefined;
+        this.intersectionObserver?.disconnect();
+        this.intersectionObserver = undefined;
         for (const marker of this._markerInstances.values())
             marker.remove();
         this._markerInstances.clear();
+        this._markerColors.clear();
+    }
+    /**
+     * Constructs the underlying `maplibregl.Map` — called once both the
+     * lazy-loaded `maplibre-gl` module has resolved and this element has been
+     * observed intersecting the viewport, whichever settles last. Idempotent
+     * (a no-op once `_map` already exists), so it's safe to call from both the
+     * `connectedCallback()` load path and the visibility path in `updated()`
+     * below without risking a double construction.
+     */
+    tryConstructMap() {
+        if (this._map || !this._maplibreModule || !this.containerEl || !this.visible || !this.isConnected)
+            return;
+        const mod = this._maplibreModule;
+        this._map = new mod.Map({
+            container: this.containerEl,
+            style: this.mapStyle,
+            center: this.center,
+            zoom: this.zoom,
+        });
+        this._map.on('load', () => {
+            this._styleLoaded = true;
+            this.applyChoropleth();
+            this.applyMarkers();
+            this.emit('lyra-map-load');
+        });
+        this._map.on('click', (e) => {
+            const fillLayerId = this._appliedFillLayerId;
+            const features = fillLayerId && this._map.getLayer(fillLayerId)
+                ? this._map.queryRenderedFeatures(e.point, { layers: [fillLayerId] })
+                : [];
+            this.emit('lyra-map-click', {
+                lngLat: [e.lngLat.lng, e.lngLat.lat],
+                feature: features[0],
+            });
+        });
     }
     updated(changed) {
         if (this.loading)
             this.setAttribute('aria-busy', 'true');
         else
             this.removeAttribute('aria-busy');
+        // Became visible after the maplibre-gl module had already loaded (the
+        // reverse order — module loads first, visibility follows — is the
+        // common case and is instead handled at the end of the
+        // `loadMaplibre().then()` chain in connectedCallback() above).
+        if (changed.has('visible') && this.visible)
+            this.tryConstructMap();
         if (changed.has('mapStyle') && this._map) {
             // A style change wipes every layer/source maplibre-gl knows about, so
             // the previously-applied choropleth bookkeeping is stale the instant
@@ -224,7 +286,16 @@ export class LyraMap extends LyraElement {
             existingSource.setData(geojson);
         }
         else {
-            this._map.addSource(sourceId, { type: 'geojson', data: geojson, promoteId: 'id' });
+            // No `promoteId` -- maplibre-gl falls back to its own default id
+            // resolution (the standard top-level GeoJSON `Feature.id`, when
+            // present). A hardcoded `promoteId: 'id'` here would instead require
+            // every feature to *also* duplicate its id inside `properties.id`,
+            // silently discarding the real top-level `id` otherwise and breaking
+            // `feature.id` on `lyra-map-click` for the common case. Nothing in this
+            // component actually needs feature-state promotion today; if that's
+            // added later it should be driven by an explicit, documented
+            // `ChoroplethLayer` option (e.g. `idField`), not a silent default.
+            this._map.addSource(sourceId, { type: 'geojson', data: geojson });
         }
         this._appliedChoroplethSourceId = sourceId;
         // An `interpolate` expression needs at least one [value, color] stop pair
@@ -281,31 +352,57 @@ export class LyraMap extends LyraElement {
         if (!map || !mod)
             return;
         const visible = new Set();
+        // Markers with no `id` used to key solely by `lngLat`, so two different
+        // id-less markers placed at the exact same coordinates collided onto one
+        // `_markerInstances` entry. An occurrence index (reset per render, per
+        // coordinate) makes same-coordinate id-less markers distinct while
+        // staying stable/consistent across re-renders as long as their relative
+        // order in `this.markers` doesn't change.
+        const coordCounts = new Map();
         for (const m of this.markers) {
-            const key = m.id ?? `${m.lngLat[0]},${m.lngLat[1]}`;
+            let key = m.id;
+            if (key == null) {
+                const coordKey = `${m.lngLat[0]},${m.lngLat[1]}`;
+                const occurrence = coordCounts.get(coordKey) ?? 0;
+                coordCounts.set(coordKey, occurrence + 1);
+                key = `${coordKey}#${occurrence}`;
+            }
             visible.add(key);
-            const existing = this._markerInstances.get(key);
+            let existing = this._markerInstances.get(key);
+            if (existing && this._markerColors.get(key) !== m.color) {
+                // `color` is baked into the marker's SVG at construction time with
+                // no way to mutate it afterwards -- fall through to the "no existing
+                // marker" branch below to reconstruct it instead. Note: this closes
+                // any popup the user currently has open on this marker (a fresh,
+                // closed Popup is built for the new instance) -- an accepted, narrow
+                // side effect of the reconstruction fallback, not a bug.
+                existing.remove();
+                this._markerInstances.delete(key);
+                this._markerColors.delete(key);
+                existing = undefined;
+            }
             if (!existing) {
                 const marker = new mod.Marker(m.color ? { color: m.color } : undefined).setLngLat(m.lngLat);
-                if (m.html || m.label) {
+                if (m.unsafeHtml || m.label) {
                     const popup = new mod.Popup({ offset: 12 });
-                    if (m.html)
-                        popup.setHTML(m.html);
+                    if (m.unsafeHtml)
+                        popup.setHTML(m.unsafeHtml);
                     else if (m.label)
                         popup.setText(m.label);
                     marker.setPopup(popup);
                 }
                 marker.addTo(map);
                 this._markerInstances.set(key, marker);
+                this._markerColors.set(key, m.color);
             }
             else {
                 existing.setLngLat(m.lngLat);
                 const popup = existing.getPopup();
-                if (m.html) {
+                if (m.unsafeHtml) {
                     if (popup)
-                        popup.setHTML(m.html);
+                        popup.setHTML(m.unsafeHtml);
                     else
-                        existing.setPopup(new mod.Popup({ offset: 12 }).setHTML(m.html));
+                        existing.setPopup(new mod.Popup({ offset: 12 }).setHTML(m.unsafeHtml));
                 }
                 else if (m.label) {
                     if (popup)
@@ -322,6 +419,7 @@ export class LyraMap extends LyraElement {
             if (!visible.has(key)) {
                 marker.remove();
                 this._markerInstances.delete(key);
+                this._markerColors.delete(key);
             }
         }
     }
@@ -372,6 +470,9 @@ __decorate([
 __decorate([
     state()
 ], LyraMap.prototype, "loading", void 0);
+__decorate([
+    state()
+], LyraMap.prototype, "visible", void 0);
 __decorate([
     query('[part="container"]')
 ], LyraMap.prototype, "containerEl", void 0);

package/dist/components/markdown/markdown-loader.d.ts

@@ -0,0 +1,58 @@
+import type * as MarkedModule from 'marked';
+import type DOMPurifyApi from 'dompurify';
+/**
+ * The two optional peers `<lyra-markdown>` needs, loaded independently (see
+ * `loadMarkdownAndSanitizer()`). Either half can be `undefined` on its own —
+ * a consumer who only installs `marked` (having explicitly opted out of
+ * sanitization via `sanitize="false"`) is a valid, supported combination.
+ */
+export interface MarkdownDeps {
+    marked: typeof MarkedModule | undefined;
+    DOMPurify: typeof DOMPurifyApi | undefined;
+}
+/**
+ * Independently loads the optional peer dependencies `marked` (Markdown
+ * parsing) and `dompurify` (HTML sanitizing), mirroring `chart-loader.ts`'s
+ * `loadChartAndZoom()` shape for two independent optional peers. A partial
+ * install — most usefully `marked` alone, for a consumer who has explicitly
+ * set `sanitize="false"` and doesn't need `dompurify` at all — degrades to
+ * "that one half is missing" rather than failing outright. Exported (in
+ * addition to the cached `loadMarkdownDeps()` below) so both failure paths —
+ * and the real caught error each one logs — are directly testable without
+ * needing to actually uninstall either package.
+ */
+export declare function loadMarkdownAndSanitizer(importMarked?: () => Promise<typeof MarkedModule>, importDompurify?: () => Promise<{
+    default: typeof DOMPurifyApi;
+}>): Promise<MarkdownDeps>;
+/**
+ * Lazily loads `marked` + `dompurify` once per page (see
+ * `loadMarkdownAndSanitizer()` for why each is loaded and caught
+ * independently). Cached the same way `chart-loader.ts`/`map-loader.ts`
+ * cache their promise, so every `<lyra-markdown>` instance on a page shares
+ * one load.
+ *
+ * The dynamic `import()` inside `loadMarkdownAndSanitizer()` is always
+ * asynchronous — even when both peers are already installed and resolve
+ * without error — so every `<lyra-markdown>` that calls this from
+ * `connectedCallback()` paints its plain-text fallback (`data-fallback` on
+ * the `content` part) for at least one microtask before the real rendered
+ * output replaces it. That window is unconditional, not just a failure
+ * path: it ends only once this promise settles. A consumer that wants to
+ * skip it can set `eager-load` on `<lyra-markdown>`, which calls
+ * `getMarkdownDepsIfLoaded()` below instead of awaiting this function —
+ * see that property's doc for what "already warm" means in practice.
+ */
+export declare function loadMarkdownDeps(): Promise<MarkdownDeps>;
+/**
+ * Synchronous companion to `loadMarkdownDeps()`: returns the same
+ * module-level cached `MarkdownDeps` if some earlier call to
+ * `loadMarkdownDeps()` — from any `<lyra-markdown>` instance on the page, or
+ * a consumer priming it directly at startup — has already settled by the
+ * time this is called, or `undefined` if the cache isn't warm yet (nothing
+ * has called `loadMarkdownDeps()` before, or it's still in flight). Used by
+ * `eager-load` to skip the dynamic `import()`'s async hop in the common case
+ * where the peers are already loaded; it cannot make the *very first*
+ * `<lyra-markdown>` on a page synchronous, since that first call is what
+ * populates the cache in the first place.
+ */
+export declare function getMarkdownDepsIfLoaded(): MarkdownDeps | undefined;

package/dist/components/markdown/markdown-loader.js

@@ -0,0 +1,77 @@
+let deps;
+// Populated the instant `deps` settles (inside `loadMarkdownDeps()` below) so
+// `getMarkdownDepsIfLoaded()` can hand one back synchronously -- the whole
+// point of that function, since `deps` itself is a Promise and awaiting it
+// always costs at least one microtask, even once already resolved.
+let resolvedDeps;
+/**
+ * Independently loads the optional peer dependencies `marked` (Markdown
+ * parsing) and `dompurify` (HTML sanitizing), mirroring `chart-loader.ts`'s
+ * `loadChartAndZoom()` shape for two independent optional peers. A partial
+ * install — most usefully `marked` alone, for a consumer who has explicitly
+ * set `sanitize="false"` and doesn't need `dompurify` at all — degrades to
+ * "that one half is missing" rather than failing outright. Exported (in
+ * addition to the cached `loadMarkdownDeps()` below) so both failure paths —
+ * and the real caught error each one logs — are directly testable without
+ * needing to actually uninstall either package.
+ */
+export async function loadMarkdownAndSanitizer(importMarked = () => import('marked'), importDompurify = () => import('dompurify')) {
+    let marked;
+    try {
+        marked = await importMarked();
+    }
+    catch (err) {
+        console.warn('<lyra-markdown> needs the optional peer dependency `marked` to parse Markdown — install it with `pnpm add marked`:', err);
+    }
+    let DOMPurify;
+    try {
+        DOMPurify = (await importDompurify()).default;
+    }
+    catch (err) {
+        console.warn('<lyra-markdown> needs the optional peer dependency `dompurify` to sanitize rendered HTML — install it ' +
+            'with `pnpm add dompurify`. Until then, content only renders when `sanitize="false"` is explicitly set:', err);
+    }
+    return { marked, DOMPurify };
+}
+/**
+ * Lazily loads `marked` + `dompurify` once per page (see
+ * `loadMarkdownAndSanitizer()` for why each is loaded and caught
+ * independently). Cached the same way `chart-loader.ts`/`map-loader.ts`
+ * cache their promise, so every `<lyra-markdown>` instance on a page shares
+ * one load.
+ *
+ * The dynamic `import()` inside `loadMarkdownAndSanitizer()` is always
+ * asynchronous — even when both peers are already installed and resolve
+ * without error — so every `<lyra-markdown>` that calls this from
+ * `connectedCallback()` paints its plain-text fallback (`data-fallback` on
+ * the `content` part) for at least one microtask before the real rendered
+ * output replaces it. That window is unconditional, not just a failure
+ * path: it ends only once this promise settles. A consumer that wants to
+ * skip it can set `eager-load` on `<lyra-markdown>`, which calls
+ * `getMarkdownDepsIfLoaded()` below instead of awaiting this function —
+ * see that property's doc for what "already warm" means in practice.
+ */
+export function loadMarkdownDeps() {
+    if (!deps) {
+        deps = loadMarkdownAndSanitizer().then((resolved) => {
+            resolvedDeps = resolved;
+            return resolved;
+        });
+    }
+    return deps;
+}
+/**
+ * Synchronous companion to `loadMarkdownDeps()`: returns the same
+ * module-level cached `MarkdownDeps` if some earlier call to
+ * `loadMarkdownDeps()` — from any `<lyra-markdown>` instance on the page, or
+ * a consumer priming it directly at startup — has already settled by the
+ * time this is called, or `undefined` if the cache isn't warm yet (nothing
+ * has called `loadMarkdownDeps()` before, or it's still in flight). Used by
+ * `eager-load` to skip the dynamic `import()`'s async hop in the common case
+ * where the peers are already loaded; it cannot make the *very first*
+ * `<lyra-markdown>` on a page synchronous, since that first call is what
+ * populates the cache in the first place.
+ */
+export function getMarkdownDepsIfLoaded() {
+    return resolvedDeps;
+}

package/dist/components/markdown/markdown.d.ts

@@ -0,0 +1,119 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+/**
+ * `<lyra-markdown>` — sanitized Markdown-to-HTML rendering (GFM tables,
+ * fenced code blocks, links, blockquotes) built on the optional peer
+ * dependencies `marked` (parsing) and `dompurify` (sanitizing), both
+ * lazy-loaded via `markdown-loader.ts` on first connect.
+ *
+ * Rendering never ships unsanitized or broken markup silently:
+ * - If `marked` fails to load, or throws while parsing malformed input, the
+ *   component falls back to plain text (`white-space: pre-wrap`, no HTML
+ *   parsing at all) and fires `lyra-render-error`.
+ * - If `sanitize` is `true` (the default) and `dompurify` fails to load, the
+ *   component *also* falls back to plain text + `lyra-render-error` — it
+ *   never renders marked's raw HTML output when sanitization was requested
+ *   (or defaulted to) but is unavailable, even though `marked` itself loaded
+ *   fine.
+ * - If `sanitize` is explicitly `false`, marked's raw output renders as-is
+ *   regardless of whether `dompurify` is installed — the consumer opted out
+ *   of sanitization, so `dompurify`'s absence is irrelevant to that path.
+ *
+ * That same plain-text fallback rendering (`data-fallback` on the `content`
+ * part) is also, unconditionally and by default, a brief *transient* state on
+ * every connect, not just a failure path: `connectedCallback()`'s dynamic
+ * `import()` of `marked`/`dompurify` (see `markdown-loader.ts`) is
+ * asynchronous, so the very first paint of any `<lyra-markdown>` on a page
+ * shows plain text for at least one microtask — even when both peers are
+ * already installed and load without error — until that import resolves and
+ * a second render replaces it with the real Markdown output. Set
+ * `eager-load` to skip that window once the shared dependency cache is
+ * already warm; see that property's doc for exactly what "warm" requires.
+ *
+ * `heading`/`code`/`blockquote`/`table`/`link`/`image` tokens are rendered
+ * through a `marked` renderer override that injects `part="..."` attributes
+ * directly into the produced HTML — a single pass, not a second DOM walk
+ * after insertion.
+ *
+ * @customElement lyra-markdown
+ * @event lyra-link-click - Fired (and the click prevented) when a rendered
+ *   link's `href` starts with `internal-link-prefix`. `detail: { href:
+ *   string, internal: true }`. Ordinary external links navigate normally
+ *   (in `link-target`) and never fire this event.
+ * @event lyra-render-error - Fired whenever rendering falls back to plain
+ *   text. `detail: { error: unknown }`.
+ * @csspart content - The wrapper around the rendered (or plain-text
+ *   fallback) output.
+ * @csspart heading - Every rendered `<h1>`–`<h6>` (shifted by
+ *   `heading-offset`).
+ * @csspart code-block - Every rendered fenced/indented `<pre>`.
+ * @csspart link - Every rendered `<a>`.
+ * @csspart table - Every rendered `<table>`.
+ * @csspart blockquote - Every rendered `<blockquote>`.
+ * @csspart img - Every rendered `<img>`.
+ */
+export declare class LyraMarkdown extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** The Markdown source to render. */
+    content: string;
+    /** Sanitize marked's HTML output with DOMPurify before rendering. See the
+     *  class doc for what happens when this is `true` (the default) but the
+     *  `dompurify` peer isn't installed. */
+    sanitize: boolean;
+    /** Enable GitHub-flavored Markdown (tables, strikethrough, autolinks, task lists). */
+    gfm: boolean;
+    /** `target` applied to every rendered `<a>`, with `rel="noopener
+     *  noreferrer"` always added alongside it whenever a `target` is emitted.
+     *  `'_blank'` (the default) preserves today's exact output. Set to `null`
+     *  (or the empty string, e.g. via the `link-target=""` attribute) to omit
+     *  `target`/`rel` entirely, so rendered links open in the same tab. */
+    linkTarget: string | null;
+    /** When set, a rendered link whose `href` starts with this prefix is
+     *  treated as internal — its click is intercepted and reported via
+     *  `lyra-link-click` instead of navigating. Empty (the default) means
+     *  every link is treated as external. */
+    internalLinkPrefix: string;
+    /** Added to every rendered heading's source `token.depth` before emitting
+     *  `<h${depth}>` — e.g. `heading-offset="2"` renders a source `#` as
+     *  `<h3>` and a source `##` as `<h4>`. The result is clamped to `[1, 6]`
+     *  (a source `######` with a positive offset stays at `<h6>` rather than
+     *  overflowing past the HTML heading levels; the floor at `1` is
+     *  defensive, since this property is meant to be additive-only). `0`
+     *  (the default) preserves today's exact `<h${token.depth}>` output. */
+    headingOffset: number;
+    /** When `true`, `connectedCallback()` skips awaiting `loadMarkdownDeps()`'s
+     *  dynamic `import()` if the shared `marked`/`dompurify` module cache (see
+     *  `markdown-loader.ts`'s `getMarkdownDepsIfLoaded()`) has *already*
+     *  resolved — e.g. because an earlier `<lyra-markdown>` instance on the
+     *  page already finished loading, or the consumer primed the cache
+     *  directly by calling `loadMarkdownDeps()` themselves at startup — and
+     *  renders synchronously instead. When the cache isn't warm yet (most
+     *  notably: the very first `<lyra-markdown>` ever connected on a page,
+     *  since nothing has called `loadMarkdownDeps()` before it), this still
+     *  falls back to the normal async path — a dynamic `import()` can't be
+     *  made synchronous, so this is a fast path for the common "already warm"
+     *  case, not a hard guarantee. `false` (the default) is byte-identical to
+     *  today: always the async `import()`, fallback-text window included. */
+    eagerLoad: boolean;
+    /** Forward-compatible hint for a dedicated streaming renderer expected to
+     *  build on this component later (coalescing partial tokens as they
+     *  arrive) — setting it has no rendering effect yet. Reflects so a
+     *  consumer can already target `lyra-markdown[streaming]` in CSS ahead of
+     *  that behavior landing. */
+    streaming: boolean;
+    private renderedHtml;
+    private deps?;
+    connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(): void;
+    private renderMarkdown;
+    private applyFallback;
+    private parseMarkdown;
+    private onContentClick;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-markdown': LyraMarkdown;
+    }
+}