@aceshooting/lyra-ui 1.2.0 → 2.0.0

package/dist/components/code-block/code-block.js

@@ -0,0 +1,317 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing } from 'lit';
+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 { nextId } from '../../internal/a11y.js';
+import { chevronIcon } from '../../internal/icons.js';
+import { loadShikiHighlighter, loadShikiLanguage, SHIKI_THEMES } from './code-loader.js';
+import { styles } from './code-block.styles.js';
+import '../skeleton/skeleton.js';
+/** How long the copy button's confirmation state lasts before reverting. */
+const COPY_CONFIRM_MS = 1500;
+/**
+ * Rewrites shiki's generated `<pre>`/`<code>` hast nodes so they carry this
+ * component's own `part="pre"`/`part="code"` hooks — the same single-pass
+ * "inject part attributes while rendering, not a second DOM walk after
+ * insertion" approach `<lyra-markdown>`'s renderer override uses, applied
+ * here via shiki's own transformer API instead of a custom marked renderer.
+ * Also strips shiki's own default `tabindex="0"` from the `<pre>` — this
+ * component's `[part="body"]` wrapper (see `render()`) is the single
+ * scrollable/focusable region for the code area, and leaving shiki's own
+ * tabindex in place would add a second, redundant tab stop over the same
+ * scrollable content.
+ */
+const partTransformer = {
+    name: 'lyra-code-block-parts',
+    pre(node) {
+        node.properties.part = ['pre'];
+        delete node.properties.tabindex;
+    },
+    code(node) {
+        node.properties.part = ['code'];
+    },
+};
+/**
+ * `<lyra-code-block>` — fenced code display with optional lazy syntax
+ * highlighting and a copy button. No highlighting grammar ships in this
+ * component itself: it lazy-loads the optional peer dependency `shiki` (see
+ * `code-loader.ts`) for the actual tokenizing, and degrades to a plain
+ * `<pre><code>` when that peer isn't installed or `language` is unset/
+ * unrecognized — the exact same optional-peer shape `<lyra-markdown>` and
+ * `<lyra-chart>` already establish. That fallback is the *default* rendering
+ * path, not a degraded one: unhighlighted code is perfectly usable, and it's
+ * what every instance renders at zero extra bytes until shiki resolves.
+ *
+ * A `<lyra-skeleton>` placeholder stands in only while shiki itself is
+ * loading for the very first time on the page (cached — see
+ * `loadShikiHighlighter()`) and `language` is set. It's deliberately *not*
+ * shown again for a subsequent per-language grammar load (e.g. a second
+ * `<lyra-code-block>` requesting a language no earlier instance has used
+ * yet) — that grammar fetch is typically fast, and the plain-text fallback
+ * is already a perfectly readable placeholder for it, so a second
+ * loading-chrome state would add complexity for little practical benefit.
+ *
+ * @customElement lyra-code-block
+ * @event lyra-copy - The copy button was activated. `detail: { text }` is
+ *   always the raw `code` value (never the highlighted HTML), and always
+ *   fires regardless of whether the actual OS clipboard write succeeded —
+ *   same convention as `<lyra-json-viewer>`'s own copy button.
+ * @csspart base - The outer container.
+ * @csspart header - The row above the code (filename/language/copy/toggle),
+ *   present whenever there's anything to put in it.
+ * @csspart filename - The `filename` text, when set.
+ * @csspart language - The `language` badge, when set, so the language is
+ *   exposed to assistive tech as visible text rather than only a `language`
+ *   attribute a screen reader would never announce.
+ * @csspart copy-button - The copy-to-clipboard button, when `copyable`.
+ * @csspart toggle - The collapse/expand chevron button, when `collapsible`.
+ * @csspart body - The scrollable region wrapping the code (or the loading
+ *   skeleton); respects `max-height`, `hidden` while `collapsible` and
+ *   `collapsed`.
+ * @csspart pre - The rendered `<pre>` — shiki's own in the highlighted path,
+ *   this component's own plain one in the fallback path.
+ * @csspart code - The rendered `<code>`, same split as `pre` above.
+ */
+export class LyraCodeBlock extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** The raw source text. */
+        this.code = '';
+        /** A shiki-recognized language id or alias (e.g. `"javascript"`,
+         *  `"python"`, `"json"`). When unset, or when shiki doesn't recognize it,
+         *  the code renders as plain unhighlighted text regardless of whether
+         *  shiki itself is available. */
+        this.language = '';
+        /** Shown in the header above the code, when set. */
+        this.filename = '';
+        /** Whether the code region can be collapsed via a header toggle. */
+        this.collapsible = false;
+        /** Whether the code region is currently hidden. Only has a visible effect
+         *  while `collapsible` is also true. */
+        this.collapsed = false;
+        /** Shows a copy-to-clipboard button in the header. */
+        this.copyable = true;
+        /** A CSS length (e.g. `"20rem"`); once set, the code scrolls internally
+         *  past this height instead of growing the page. */
+        this.maxHeight = '';
+        // `null` covers every reason the plain-text fallback is showing: shiki
+        // isn't installed, `language` is unset, or `language` isn't shiki-
+        // recognized -- `render()` doesn't need to (and can't usefully) tell these
+        // apart, same rationale as <lyra-markdown>'s identically-shaped field.
+        this.highlightedHtml = null;
+        // Becomes true once the shared shiki-loading promise has settled, whether
+        // or not it actually resolved to a highlighter -- gates the skeleton (see
+        // the class doc's second paragraph), not the highlighting itself.
+        this.shikiReady = false;
+        this.justCopied = false;
+        // Guards the async per-language load in syncHighlight() against a
+        // `code`/`language` change that arrives before a previous load resolves --
+        // only the result matching the *current* token is ever applied.
+        this.highlightToken = 0;
+        this.bodyId = nextId('code-block-body');
+        this.copy = () => {
+            this.writeClipboard(this.code);
+            this.emit('lyra-copy', { text: this.code });
+            this.justCopied = true;
+            clearTimeout(this.copyTimeoutId);
+            this.copyTimeoutId = setTimeout(() => {
+                this.justCopied = false;
+            }, COPY_CONFIRM_MS);
+        };
+        this.toggleCollapsed = () => {
+            this.collapsed = !this.collapsed;
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    connectedCallback() {
+        super.connectedCallback();
+        void loadShikiHighlighter().then((hl) => {
+            this.highlighter = hl;
+            this.shikiReady = true;
+            this.syncHighlight();
+        });
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        clearTimeout(this.copyTimeoutId);
+    }
+    // Mutating `highlightedHtml` here (rather than in `updated()`) absorbs the
+    // synchronous case -- language already loaded, see `syncHighlight()` --
+    // into this same update cycle instead of scheduling a second one, Lit's
+    // documented pattern for deriving one reactive property from a change to
+    // others (same approach <lyra-markdown>'s `willUpdate` takes).
+    willUpdate(changed) {
+        if (this.shikiReady && (changed.has('code') || changed.has('language'))) {
+            this.syncHighlight();
+        }
+    }
+    updated() {
+        const showingSkeleton = !this.shikiReady && !!this.language;
+        if (showingSkeleton)
+            this.setAttribute('aria-busy', 'true');
+        else
+            this.removeAttribute('aria-busy');
+    }
+    syncHighlight() {
+        const hl = this.highlighter;
+        const lang = this.language;
+        if (!hl || !lang) {
+            this.highlightedHtml = null;
+            return;
+        }
+        if (hl.getLoadedLanguages().includes(lang)) {
+            this.highlightedHtml = this.tokenize(hl, lang);
+            return;
+        }
+        // Grammar not loaded yet -- show the plain-text fallback in the
+        // meantime rather than leaving a *previous* code/language value's stale
+        // highlighted markup on screen while this one loads.
+        this.highlightedHtml = null;
+        const token = ++this.highlightToken;
+        void loadShikiLanguage(hl, lang).then((ok) => {
+            if (token !== this.highlightToken)
+                return; // superseded by a newer code/language change
+            this.highlightedHtml = ok ? this.tokenize(hl, lang) : null;
+        });
+    }
+    tokenize(hl, lang) {
+        try {
+            return hl.codeToHtml(this.code, {
+                lang,
+                // shiki's generated per-token colors are theme-specific inline
+                // styles/CSS variables (from SHIKI_THEMES's github-light/github-dark
+                // theme data), not this library's --lyra-* design tokens -- the one
+                // deliberate exception to every other color in this component being
+                // a --lyra-* token. See the dark-mode override in
+                // code-block.styles.ts for how the dark half of this activates.
+                themes: SHIKI_THEMES,
+                transformers: [partTransformer],
+            });
+        }
+        catch {
+            // Malformed input for this grammar, or any other shiki-internal
+            // failure -- fall back to plain text rather than a blank code block.
+            return null;
+        }
+    }
+    writeClipboard(text) {
+        try {
+            // navigator.clipboard is absent in insecure contexts / older browsers,
+            // and some engines throw synchronously rather than rejecting -- either
+            // way this is best-effort; copy() below always emits lyra-copy
+            // regardless of whether the OS clipboard was actually reached. Same
+            // precedent as <lyra-json-viewer>'s own copy button.
+            void navigator.clipboard?.writeText(text)?.catch(() => { });
+        }
+        catch {
+            // see above
+        }
+    }
+    renderHeader() {
+        return html `
+      <div part="header">
+        ${this.collapsible
+            ? html `
+              <button
+                part="toggle"
+                type="button"
+                aria-expanded=${this.collapsed ? 'false' : 'true'}
+                aria-controls=${this.bodyId}
+                aria-label=${this.collapsed ? 'Expand code' : 'Collapse code'}
+                @click=${this.toggleCollapsed}
+              >
+                <span class="chevron" aria-hidden="true">${chevronIcon()}</span>
+              </button>
+            `
+            : nothing}
+        ${this.filename ? html `<span part="filename">${this.filename}</span>` : nothing}
+        ${this.language ? html `<span part="language">${this.language}</span>` : nothing}
+        ${this.copyable
+            ? html `
+              <button
+                part="copy-button"
+                type="button"
+                aria-label=${this.justCopied ? 'Copied to clipboard' : 'Copy code'}
+                @click=${this.copy}
+              >
+                ${this.justCopied ? 'Copied!' : 'Copy'}
+              </button>
+            `
+            : nothing}
+      </div>
+    `;
+    }
+    // `[part="body"]` is `tabindex="0"` because it's the scrollable region for
+    // arbitrarily-wide/tall code (max-height, plus horizontal overflow from
+    // long lines) -- a scrollable region with no other focusable content of
+    // its own is otherwise unreachable by keyboard, same reasoning
+    // lyra-virtual-list's own `[part="base"]` documents for its identical
+    // tabindex. `role="group"` (rather than e.g. `region`, a page landmark
+    // role) plus `aria-label` gives it an accessible name without claiming
+    // landmark/navigation significance for what is, structurally, just one
+    // small piece of a larger document.
+    render() {
+        const hasHeader = !!this.filename || !!this.language || this.copyable || this.collapsible;
+        const showSkeleton = !this.shikiReady && !!this.language;
+        const bodyHidden = this.collapsible && this.collapsed;
+        const bodyLabel = this.filename || (this.language ? `${this.language} code` : 'Code');
+        return html `
+      <div part="base">
+        ${hasHeader ? this.renderHeader() : nothing}
+        <div
+          part="body"
+          id=${this.bodyId}
+          role="group"
+          aria-label=${bodyLabel}
+          tabindex="0"
+          ?hidden=${bodyHidden}
+          style=${this.maxHeight ? `--lyra-code-block-max-height:${this.maxHeight}` : nothing}
+        >
+          ${showSkeleton
+            ? html `<lyra-skeleton variant="rect"></lyra-skeleton>`
+            : this.highlightedHtml !== null
+                ? unsafeHTML(this.highlightedHtml)
+                : html `<pre part="pre"><code part="code">${this.code}</code></pre>`}
+        </div>
+      </div>
+    `;
+    }
+}
+__decorate([
+    property()
+], LyraCodeBlock.prototype, "code", void 0);
+__decorate([
+    property()
+], LyraCodeBlock.prototype, "language", void 0);
+__decorate([
+    property()
+], LyraCodeBlock.prototype, "filename", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraCodeBlock.prototype, "collapsible", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraCodeBlock.prototype, "collapsed", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraCodeBlock.prototype, "copyable", void 0);
+__decorate([
+    property({ attribute: 'max-height' })
+], LyraCodeBlock.prototype, "maxHeight", void 0);
+__decorate([
+    state()
+], LyraCodeBlock.prototype, "highlightedHtml", void 0);
+__decorate([
+    state()
+], LyraCodeBlock.prototype, "shikiReady", void 0);
+__decorate([
+    state()
+], LyraCodeBlock.prototype, "justCopied", void 0);
+defineElement('code-block', LyraCodeBlock);

package/dist/components/code-block/code-block.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/code-block/code-block.styles.js

@@ -0,0 +1,187 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: block;
+    /* Consumer-tunable scroll cap -- 'none' means the block grows with its
+       content, matching every other block-level component in this library
+       until a caller opts in via the max-height attribute (same convention
+       as --lyra-json-viewer-max-height). */
+    --lyra-code-block-max-height: none;
+    /* Contained here rather than left as a bare font-family literal so a
+       host page can retheme it -- same rationale as --lyra-markdown-font-mono
+       and --lyra-json-viewer-font, no shared --wa-*/--lyra-* monospace token
+       exists to resolve through. */
+    --lyra-code-block-font: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: 0.8125rem;
+  }
+  [part='base'] {
+    border: 1px solid var(--lyra-color-border);
+    border-radius: var(--lyra-radius);
+    background: var(--lyra-color-surface);
+    overflow: hidden;
+  }
+  [part='header'] {
+    display: flex;
+    align-items: center;
+    gap: var(--lyra-space-xs);
+    padding: var(--lyra-space-xs) var(--lyra-space-s);
+    border-block-end: 1px solid var(--lyra-color-border);
+    /* --lyra-color-surface (not -brand-quiet) -- pairing
+       --lyra-color-text-quiet (the toggle/copy-button color below) against
+       --lyra-color-brand-quiet fails WCAG AA contrast in this token
+       palette; --lyra-color-surface is the same header background
+       lyra-json-viewer's own toolbar already uses with that same text
+       color. */
+    background: var(--lyra-color-surface);
+    font-family: var(--lyra-font);
+  }
+  [part='toggle'] {
+    /* Deliberately smaller than the shared --lyra-icon-button-size (2.5rem,
+       meant for a standalone icon-only button) -- this sits inline in a
+       dense header row, same reasoning as lyra-json-viewer's own toggle. */
+    inline-size: 1.25rem;
+    block-size: 1.25rem;
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+    border: none;
+    background: none;
+    color: var(--lyra-color-text-quiet);
+    border-radius: var(--lyra-radius);
+    cursor: pointer;
+  }
+  [part='toggle']:hover {
+    background: var(--lyra-color-brand-quiet);
+    color: var(--lyra-color-brand);
+  }
+  [part='toggle'] .chevron {
+    display: inline-flex;
+    transition: transform var(--lyra-transition-fast);
+  }
+  /* Chevron points at the content: rotated (pointing down) while expanded,
+     resting (pointing right) while collapsed -- same rotation direction as
+     lyra-thinking-panel's and lyra-json-viewer's own toggles. */
+  :host(:not([collapsed])) [part='toggle'] .chevron {
+    transform: rotate(90deg);
+  }
+  [part='filename'] {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-family: var(--lyra-code-block-font);
+    font-size: 0.75rem;
+    font-weight: 600;
+    color: var(--lyra-color-text);
+  }
+  [part='language'] {
+    flex: 0 0 auto;
+    padding: 0.0625rem 0.4375rem;
+    border-radius: 999px;
+    /* --lyra-color-brand + -brand-quiet (not -text-quiet + -surface) --
+       this pill needs to read as distinct from the [part="header"]
+       background it sits on (also -surface as of the comment above), and
+       -brand on -brand-quiet is a pairing already relied on elsewhere in
+       this library (e.g. hover states below) that passes contrast, unlike
+       -text-quiet on -brand-quiet. */
+    background: var(--lyra-color-brand-quiet);
+    color: var(--lyra-color-brand);
+    font-size: 0.6875rem;
+    line-height: 1.4;
+    text-transform: uppercase;
+    letter-spacing: 0.02em;
+  }
+  /* Pushed to the end of the header whether or not filename/language
+     precede it -- margin-inline-start:auto works whether this is the first
+     flex child (copyable alone) or the last of several. */
+  [part='copy-button'] {
+    flex: 0 0 auto;
+    margin-inline-start: auto;
+    border: none;
+    background: none;
+    color: var(--lyra-color-text-quiet);
+    font: inherit;
+    font-size: 0.75rem;
+    line-height: 1;
+    padding: 0.1875rem var(--lyra-space-xs);
+    border-radius: var(--lyra-radius);
+    cursor: pointer;
+  }
+  [part='copy-button']:hover {
+    background: var(--lyra-color-brand-quiet);
+    color: var(--lyra-color-brand);
+  }
+  [part='toggle']:focus-visible,
+  [part='copy-button']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+  [part='body'] {
+    display: block;
+    max-block-size: var(--lyra-code-block-max-height);
+    overflow: auto;
+  }
+  [part='body'][hidden] {
+    display: none;
+  }
+  [part='body']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    /* Negative (inward) so the ring isn't clipped by this element's own
+       overflow:auto -- same reasoning as lyra-virtual-list's [part="base"]. */
+    outline-offset: calc(-1 * var(--lyra-focus-ring-offset));
+  }
+  [part='body'] lyra-skeleton {
+    display: block;
+    padding: var(--lyra-space-s) var(--lyra-space-m);
+    --lyra-skeleton-w: 100%;
+    --lyra-skeleton-h: 8rem;
+  }
+  [part='pre'] {
+    margin: 0;
+    padding: var(--lyra-space-s) var(--lyra-space-m);
+    /* A default background so the plain-fallback path still reads as a
+       proper code block -- shiki's own inline background-color (part of the
+       generated-token-colors exception documented in code-block.ts's
+       tokenize()) silently overrides this the moment highlighting succeeds,
+       since an element's own style attribute always wins over an external
+       stylesheet rule at equal or lower specificity. */
+    background: var(--lyra-color-surface);
+    font-family: var(--lyra-code-block-font);
+    font-size: inherit;
+    line-height: 1.5;
+    white-space: pre;
+  }
+  [part='code'] {
+    font-family: inherit;
+  }
+  /*
+   * Activates shiki's "dual themes" dark variant. codeToHtml() (see
+   * tokenize() in code-block.ts) renders every token with its *light* color
+   * as a plain inline color/background-color and its *dark* color stashed in
+   * the --shiki-dark/--shiki-dark-bg custom properties shiki itself defines
+   * inline on the same elements -- shiki's own documented pattern for
+   * toggling them is exactly this: an external stylesheet rule that
+   * reassigns color/background-color from those variables. This requires
+   * !important because an inline style="..." attribute always outranks an
+   * external stylesheet at any selector specificity short of !important --
+   * there's no other way for a page-level rule to override an element's own
+   * style attribute. This is the one legitimate exception to "every color is
+   * a --lyra-* token" in this file: these values come from shiki's theme
+   * data, not this library's design tokens.
+   */
+  @media (prefers-color-scheme: dark) {
+    [part='pre'],
+    [part='pre'] span {
+      color: var(--shiki-dark, inherit) !important;
+      background-color: var(--shiki-dark-bg, transparent) !important;
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    [part='toggle'] .chevron {
+      transition: none !important;
+    }
+  }
+`;

package/dist/components/code-block/code-loader.d.ts

@@ -0,0 +1,44 @@
+import type { Highlighter, BundledTheme } from 'shiki';
+/** Re-exported under a component-scoped name so importers don't need their
+ *  own `import type { Highlighter } from 'shiki'`. */
+export type ShikiHighlighter = Highlighter;
+/**
+ * The two bundled themes every highlighter instance is seeded with, so a
+ * single `codeToHtml()` call can emit a light *and* dark rendering at once
+ * (shiki's "dual themes" feature — https://shiki.style/guide/dual-themes —
+ * rather than maintaining two separately-highlighted copies). `github-light`/
+ * `github-dark` are well-known, reasonably neutral, and already part of
+ * shiki's bundled theme set, so picking them costs no extra install. See the
+ * `prefers-color-scheme` block in `code-block.styles.ts` for how the dark
+ * variant actually activates.
+ */
+export declare const SHIKI_LIGHT_THEME: BundledTheme;
+export declare const SHIKI_DARK_THEME: BundledTheme;
+/** Passed directly as `codeToHtml()`'s `themes` option — see `tokenize()` in `code-block.ts`. */
+export declare const SHIKI_THEMES: Record<'light' | 'dark', BundledTheme>;
+/**
+ * Lazily loads the optional peer dependency `shiki` once per page and builds
+ * (and caches) a single `Highlighter` instance seeded with `SHIKI_THEMES` and
+ * *zero* language grammars. Creating the highlighter — compiling its regex
+ * engine, parsing the seed themes — is the expensive part, not the dynamic
+ * `import()` itself, so the created instance is what's cached here rather
+ * than just the resolved module (one level deeper than `map-loader.ts`'s
+ * single-dependency cached-promise shape, which this otherwise mirrors).
+ * Resolves to `null` (with a one-time `console.warn`) if shiki isn't
+ * installed — `<lyra-code-block>` falls back to plain unhighlighted text in
+ * that case, which is a fully supported default, not a degraded mode. No
+ * language grammar is loaded up front; `loadShikiLanguage()` below loads each
+ * one incrementally the first time a `language` value actually requests it.
+ */
+export declare function loadShikiHighlighter(): Promise<ShikiHighlighter | null>;
+/**
+ * Ensures `lang` is loaded into `hl`, loading it on demand the first time
+ * it's requested rather than bundling every possible grammar up front —
+ * shiki supports this incrementally via `Highlighter.loadLanguage()`, which
+ * is what keeps this lazy instead of defeating the point of lazy-loading the
+ * peer at all. Resolves `false` (and remembers not to retry) when `lang`
+ * isn't a shiki-recognized grammar id or alias at all, so a caller can fall
+ * back to plain-text rendering instead of retrying an id that can never
+ * succeed on every future render.
+ */
+export declare function loadShikiLanguage(hl: ShikiHighlighter, lang: string): Promise<boolean>;

package/dist/components/code-block/code-loader.js

@@ -0,0 +1,79 @@
+/**
+ * The two bundled themes every highlighter instance is seeded with, so a
+ * single `codeToHtml()` call can emit a light *and* dark rendering at once
+ * (shiki's "dual themes" feature — https://shiki.style/guide/dual-themes —
+ * rather than maintaining two separately-highlighted copies). `github-light`/
+ * `github-dark` are well-known, reasonably neutral, and already part of
+ * shiki's bundled theme set, so picking them costs no extra install. See the
+ * `prefers-color-scheme` block in `code-block.styles.ts` for how the dark
+ * variant actually activates.
+ */
+export const SHIKI_LIGHT_THEME = 'github-light';
+export const SHIKI_DARK_THEME = 'github-dark';
+/** Passed directly as `codeToHtml()`'s `themes` option — see `tokenize()` in `code-block.ts`. */
+export const SHIKI_THEMES = {
+    light: SHIKI_LIGHT_THEME,
+    dark: SHIKI_DARK_THEME,
+};
+let highlighter;
+/** Language ids that have already failed `loadLanguage()` once — avoids
+ *  retrying (and re-throwing on) the same unrecognized `language` value on
+ *  every re-render of every `<lyra-code-block>` that requests it. Shared
+ *  across every highlighter instance the page ever creates (there's only
+ *  ever one, see `loadShikiHighlighter()` below), so this never needs
+ *  resetting alongside it. */
+const unsupportedLanguages = new Set();
+/**
+ * Lazily loads the optional peer dependency `shiki` once per page and builds
+ * (and caches) a single `Highlighter` instance seeded with `SHIKI_THEMES` and
+ * *zero* language grammars. Creating the highlighter — compiling its regex
+ * engine, parsing the seed themes — is the expensive part, not the dynamic
+ * `import()` itself, so the created instance is what's cached here rather
+ * than just the resolved module (one level deeper than `map-loader.ts`'s
+ * single-dependency cached-promise shape, which this otherwise mirrors).
+ * Resolves to `null` (with a one-time `console.warn`) if shiki isn't
+ * installed — `<lyra-code-block>` falls back to plain unhighlighted text in
+ * that case, which is a fully supported default, not a degraded mode. No
+ * language grammar is loaded up front; `loadShikiLanguage()` below loads each
+ * one incrementally the first time a `language` value actually requests it.
+ */
+export function loadShikiHighlighter() {
+    if (!highlighter) {
+        highlighter = import('shiki')
+            .then((mod) => mod.createHighlighter({ themes: [SHIKI_LIGHT_THEME, SHIKI_DARK_THEME], langs: [] }))
+            .catch((err) => {
+            console.warn('<lyra-code-block> needs the optional peer dependency `shiki` for syntax highlighting — install it ' +
+                'with `pnpm add shiki`. Code still renders, just unhighlighted, without it:', err);
+            return null;
+        });
+    }
+    return highlighter;
+}
+/**
+ * Ensures `lang` is loaded into `hl`, loading it on demand the first time
+ * it's requested rather than bundling every possible grammar up front —
+ * shiki supports this incrementally via `Highlighter.loadLanguage()`, which
+ * is what keeps this lazy instead of defeating the point of lazy-loading the
+ * peer at all. Resolves `false` (and remembers not to retry) when `lang`
+ * isn't a shiki-recognized grammar id or alias at all, so a caller can fall
+ * back to plain-text rendering instead of retrying an id that can never
+ * succeed on every future render.
+ */
+export async function loadShikiLanguage(hl, lang) {
+    if (hl.getLoadedLanguages().includes(lang))
+        return true;
+    if (unsupportedLanguages.has(lang))
+        return false;
+    try {
+        await hl.loadLanguage(lang);
+        return true;
+    }
+    catch {
+        // Not a shiki-recognized grammar id/alias, or the grammar failed to
+        // load for some other reason — either way, <lyra-code-block> treats an
+        // unrecognized language the same as an unset one (plain text), and
+        // there's nothing more specific a caller could do with the reason.
+        unsupportedLanguages.add(lang);
+        return false;
+    }
+}