@aceshooting/lyra-ui 2.0.0 → 2.1.0

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
@@ -121,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
@@ -144,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() {
@@ -175,16 +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
@@ -233,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
@@ -408,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

@@ -30,5 +30,29 @@ export declare function loadMarkdownAndSanitizer(importMarked?: () => Promise<ty
  * 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

@@ -1,4 +1,9 @@
 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
@@ -34,10 +39,39 @@ export async function loadMarkdownAndSanitizer(importMarked = () => import('mark
  * 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();
+        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

@@ -19,10 +19,21 @@ import { LyraElement } from '../../internal/lyra-element.js';
  *   regardless of whether `dompurify` is installed — the consumer opted out
  *   of sanitization, so `dompurify`'s absence is irrelevant to that path.
  *
- * `heading`/`code`/`blockquote`/`table`/`link` 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.
+ * 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
@@ -33,11 +44,13 @@ import { LyraElement } from '../../internal/lyra-element.js';
  *   text. `detail: { error: unknown }`.
  * @csspart content - The wrapper around the rendered (or plain-text
  *   fallback) output.
- * @csspart heading - Every rendered `<h1>`–`<h6>`.
+ * @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[];
@@ -49,14 +62,39 @@ export declare class LyraMarkdown extends LyraElement {
     sanitize: boolean;
     /** Enable GitHub-flavored Markdown (tables, strikethrough, autolinks, task lists). */
     gfm: boolean;
-    /** `target` applied to every rendered `<a>`; `rel="noopener noreferrer"` is
-     *  always added alongside it regardless of this value. */
-    linkTarget: string;
+    /** `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

package/dist/components/markdown/markdown.js

@@ -9,7 +9,7 @@ import { property, state } from 'lit/decorators.js';
 import { unsafeHTML } from 'lit/directives/unsafe-html.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
-import { loadMarkdownDeps } from './markdown-loader.js';
+import { loadMarkdownDeps, getMarkdownDepsIfLoaded } from './markdown-loader.js';
 import { styles } from './markdown.styles.js';
 const HTML_ESCAPES = {
     '&': '&',
@@ -22,22 +22,22 @@ function escapeHtml(text) {
     return text.replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch] ?? ch);
 }
 /**
- * Mirrors marked's own default `link()` renderer's defensive href guard: a
- * malformed percent-escape or lone UTF-16 surrogate in the raw href throws
- * inside `encodeURI`, and marked's default renderer responds by dropping the
- * anchor (rendering the link text alone) rather than emitting a broken
- * `href`. `encodeURI`'s *return value* is discarded on purpose, not applied —
- * calling it a second time on an already-percent-encoded URL (the common
- * case for a real markdown link) would double-encode every existing `%XX`
- * escape.
+ * Mirrors marked's own default `link()` renderer's `cleanUrl()`: a malformed
+ * percent-escape or lone UTF-16 surrogate in the raw href throws inside
+ * `encodeURI`, and marked's default renderer responds by dropping the anchor
+ * (rendering the link text alone) rather than emitting a broken `href` —
+ * returning `null` here lets the caller do the same. The
+ * `.replace(/%25/g, '%')` compensates for `encodeURI` re-escaping the `%` of
+ * an href that was already percent-encoded (the common case for a real
+ * markdown link) — without it, every existing `%XX` escape would become
+ * `%25XX`, double-encoding it.
  */
-function isValidHref(href) {
+function cleanHref(href) {
     try {
-        encodeURI(href);
-        return true;
+        return encodeURI(href).replace(/%25/g, '%');
     }
     catch {
-        return false;
+        return null;
     }
 }
 /**
@@ -59,10 +59,21 @@ function isValidHref(href) {
  *   regardless of whether `dompurify` is installed — the consumer opted out
  *   of sanitization, so `dompurify`'s absence is irrelevant to that path.
  *
- * `heading`/`code`/`blockquote`/`table`/`link` 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.
+ * 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
@@ -73,11 +84,13 @@ function isValidHref(href) {
  *   text. `detail: { error: unknown }`.
  * @csspart content - The wrapper around the rendered (or plain-text
  *   fallback) output.
- * @csspart heading - Every rendered `<h1>`–`<h6>`.
+ * @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 class LyraMarkdown extends LyraElement {
     constructor() {
@@ -90,14 +103,39 @@ export class LyraMarkdown extends LyraElement {
         this.sanitize = true;
         /** Enable GitHub-flavored Markdown (tables, strikethrough, autolinks, task lists). */
         this.gfm = true;
-        /** `target` applied to every rendered `<a>`; `rel="noopener noreferrer"` is
-         *  always added alongside it regardless of this value. */
+        /** `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. */
         this.linkTarget = '_blank';
         /** 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. */
         this.internalLinkPrefix = '';
+        /** 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. */
+        this.headingOffset = 0;
+        /** 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. */
+        this.eagerLoad = false;
         /** 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
@@ -133,7 +171,29 @@ export class LyraMarkdown extends LyraElement {
     static { this.styles = [LyraElement.styles, styles]; }
     connectedCallback() {
         super.connectedCallback();
+        if (this.eagerLoad) {
+            // Only takes this synchronous path when the shared module cache has
+            // *already* settled (see getMarkdownDepsIfLoaded()'s doc) -- otherwise
+            // falls through to the same async path as the default below, since a
+            // dynamic import() can't be made synchronous from scratch.
+            const alreadyLoaded = getMarkdownDepsIfLoaded();
+            if (alreadyLoaded) {
+                this.deps = alreadyLoaded;
+                this.renderMarkdown();
+                return;
+            }
+        }
         void loadMarkdownDeps().then((resolved) => {
+            // The (module-cached, page-lifetime) loadMarkdownDeps() promise can
+            // resolve after this instance was removed from the DOM -- e.g. an
+            // <lyra-markdown> inside a conditionally-rendered chat message or a
+            // virtualized list. Without this guard, a detached instance would
+            // still have its `deps` set and renderMarkdown() called, mutating the
+            // @state() renderedHtml property and scheduling a Lit update no one
+            // will ever see. Mirrors chart.ts's own connectedCallback() guard for
+            // the identical race.
+            if (!this.isConnected)
+                return;
             this.deps = resolved;
             this.renderMarkdown();
         });
@@ -149,7 +209,11 @@ export class LyraMarkdown extends LyraElement {
             // whatever property values are current at that time.
             return;
         }
-        if (changed.has('content') || changed.has('sanitize') || changed.has('gfm') || changed.has('linkTarget')) {
+        if (changed.has('content') ||
+            changed.has('sanitize') ||
+            changed.has('gfm') ||
+            changed.has('linkTarget') ||
+            changed.has('headingOffset')) {
             this.renderMarkdown();
         }
     }
@@ -203,16 +267,27 @@ export class LyraMarkdown extends LyraElement {
         this.emit('lyra-render-error', { error });
     }
     parseMarkdown(marked) {
-        const linkTarget = this.linkTarget || '_blank';
+        // Falsy (`null` or `''`) means the consumer explicitly opted out of
+        // target="..."/rel="..." on rendered links -- see the linkTarget doc.
+        // The default '_blank' is already truthy, so this preserves today's
+        // exact output when the property is left unset.
+        const linkTarget = this.linkTarget;
+        const headingOffset = this.headingOffset;
         const instance = new marked.Marked();
         // A fresh renderer per parse (rather than a shared/cached one) so it
-        // always closes over the *current* `linkTarget` — this property can
-        // change between renders, and marked's `.use()` otherwise persists
-        // whatever renderer it was given for the lifetime of the instance.
+        // always closes over the *current* `linkTarget`/`headingOffset` — these
+        // properties can change between renders, and marked's `.use()` otherwise
+        // persists whatever renderer it was given for the lifetime of the
+        // instance.
         instance.use({
             renderer: {
                 heading(token) {
-                    return `<h${token.depth} part="heading">${this.parser.parseInline(token.tokens)}</h${token.depth}>\n`;
+                    // Clamped to [1, 6]: a positive offset can never push a heading
+                    // past <h6> (there is no <h7>), and the floor at 1 is defensive
+                    // since headingOffset is meant to be additive-only (0 is the only
+                    // documented non-positive value).
+                    const depth = Math.min(6, Math.max(1, token.depth + headingOffset));
+                    return `<h${depth} part="heading">${this.parser.parseInline(token.tokens)}</h${depth}>\n`;
                 },
                 code(token) {
                     const lang = (token.lang ?? '').trim().split(/\s+/)[0] ?? '';
@@ -225,9 +300,17 @@ export class LyraMarkdown extends LyraElement {
                     return `<blockquote part="blockquote">\n${this.parser.parse(token.tokens)}</blockquote>\n`;
                 },
                 table(token) {
+                    // Built directly here (rather than delegating to the inherited
+                    // tablecell()) so a scope="col" can be added -- marked's own
+                    // default tablecell() never emits it, and without it a screen
+                    // reader can't reliably associate a data cell with its column
+                    // header beyond the simplest table.
                     let headerRow = '';
-                    for (const cell of token.header)
-                        headerRow += this.tablecell(cell);
+                    for (const cell of token.header) {
+                        const text = this.parser.parseInline(cell.tokens);
+                        const alignAttr = cell.align ? ` align="${cell.align}"` : '';
+                        headerRow += `<th scope="col"${alignAttr}>${text}</th>`;
+                    }
                     let bodyRows = '';
                     for (const row of token.rows) {
                         let rowHtml = '';
@@ -241,11 +324,27 @@ export class LyraMarkdown extends LyraElement {
                 },
                 link(token) {
                     const text = this.parser.parseInline(token.tokens);
-                    if (!isValidHref(token.href))
+                    const href = cleanHref(token.href);
+                    if (href === null)
                         return text;
                     const titleAttr = token.title ? ` title="${escapeHtml(token.title)}"` : '';
-                    return (`<a part="link" href="${escapeHtml(token.href)}"${titleAttr} ` +
-                        `target="${escapeHtml(linkTarget)}" rel="noopener noreferrer">${text}</a>`);
+                    const targetAttr = linkTarget
+                        ? ` target="${escapeHtml(linkTarget)}" rel="noopener noreferrer"`
+                        : '';
+                    return `<a part="link" href="${escapeHtml(href)}"${titleAttr}${targetAttr}>${text}</a>`;
+                },
+                image(token) {
+                    // Mirrors marked's own default image() renderer (alt text
+                    // re-rendered through the plain textRenderer so nested emphasis/
+                    // strong/etc. inside the alt collapses to plain text, href run
+                    // through the same cleanHref() the link() override above uses)
+                    // with a part="img" added.
+                    const altText = this.parser.parseInline(token.tokens, this.parser.textRenderer);
+                    const href = cleanHref(token.href);
+                    if (href === null)
+                        return escapeHtml(altText);
+                    const titleAttr = token.title ? ` title="${escapeHtml(token.title)}"` : '';
+                    return `<img part="img" src="${escapeHtml(href)}" alt="${escapeHtml(altText)}"${titleAttr}>`;
                 },
             },
         });
@@ -275,6 +374,12 @@ __decorate([
 __decorate([
     property({ attribute: 'internal-link-prefix' })
 ], LyraMarkdown.prototype, "internalLinkPrefix", void 0);
+__decorate([
+    property({ type: Number, attribute: 'heading-offset' })
+], LyraMarkdown.prototype, "headingOffset", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'eager-load' })
+], LyraMarkdown.prototype, "eagerLoad", void 0);
 __decorate([
     property({ type: Boolean, reflect: true })
 ], LyraMarkdown.prototype, "streaming", void 0);

package/dist/components/markdown/markdown.styles.js

@@ -37,7 +37,7 @@ export const styles = css `
     font-family: var(--lyra-markdown-font-mono);
     font-size: 0.875em;
     background: var(--lyra-color-brand-quiet);
-    border-radius: 0.1875rem;
+    border-radius: calc(var(--lyra-radius) * 0.5);
     padding: 0.125rem 0.3125rem;
   }
   [part='code-block'] {
@@ -57,6 +57,12 @@ export const styles = css `
     color: var(--lyra-color-brand);
     text-underline-offset: 0.125rem;
   }
+  /* Keeps an oversized source image from overflowing the content wrapper --
+     matches the overflow-wrap: break-word guard on [part='content'] above,
+     which only covers text, not replaced elements like <img>. */
+  [part='img'] {
+    max-width: 100%;
+  }
   [part='blockquote'] {
     margin-block: 0 var(--lyra-space-s);
     margin-inline: 0;