@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/citation-badge/citation-badge.d.ts

@@ -0,0 +1,113 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+export type CitationBadgeStatus = 'default' | 'high' | 'medium' | 'low' | 'verified' | 'unverified';
+export interface CitationActivateDetail {
+    sourceId: string;
+    index: number;
+}
+export interface CitationOpenDetail {
+    sourceId: string;
+    index: number;
+    href?: string;
+}
+/**
+ * `<lyra-citation-badge>` — an inline `[n]` citation marker with a hover/
+ * focus preview popover and confidence/verification-status coloring. Used
+ * for an agent response's inline citations, each carrying a `source-id`
+ * that matches a corresponding `<lyra-source-card>` shown elsewhere on the
+ * page (a sibling component in this same family — this component doesn't
+ * import or know anything about it, only carries the id through its
+ * events).
+ *
+ * The default slot is *not* the badge's visible content — the badge always
+ * renders `[index]` — it's reserved for optional rich preview content (e.g.
+ * a filename + short excerpt) shown in a floating popover on hover/focus,
+ * positioned with `internal/positioner.js`'s `place()` the same way
+ * `<lyra-tool-call-chip>` positions its own detail tooltip. No popover shows
+ * at all when the slot carries no content, and the popover never traps
+ * focus — it's supplementary preview content, not a modal, so Tab continues
+ * past the badge normally even while it happens to be visible from a mouse
+ * hover.
+ *
+ * Two distinct signals fire from the same badge: `lyra-citation-activate`
+ * (click, or Enter while focused — native `<button>` behavior, no listener
+ * needed for the Enter case) is the lightweight "jump to this source"
+ * signal a host wires to scrolling/highlighting the matching
+ * `<lyra-source-card>`. `lyra-citation-open` (dblclick, or Space while
+ * focused) is a distinct "full preview" signal — `href` in its detail is
+ * `undefined` when the `href` prop isn't set; the consumer decides what
+ * "open" means (a new tab, a dialog, etc). A double-click still fires two
+ * `lyra-citation-activate` events (one per constituent click — standard
+ * browser `dblclick` behavior) in addition to the one `lyra-citation-open`;
+ * a consumer that only cares about the richer signal on a double-click
+ * should ignore the paired activate events in that case.
+ *
+ * Status coloring: `verified`/`high` use the success tones (a claim that's
+ * been checked out, or the model is confident in). `medium`/`low` use
+ * warning (progressively less certain, but still a real citation).
+ * `unverified` uses danger — deliberately distinct from `low`: "hasn't been
+ * checked at all" is a different (arguably riskier) claim than "checked but
+ * uncertain". `default` renders as plain neutral text with no background
+ * tint, for citations that carry no confidence/verification signal at all.
+ *
+ * @customElement lyra-citation-badge
+ * @slot - Rich preview/tooltip content (e.g. a filename + excerpt), shown in
+ * a floating popover on hover/focus. Nothing renders (no hover affordance at
+ * all) when this slot is empty.
+ * @event lyra-citation-activate - The badge was activated (click, or Enter
+ * while focused). `detail: { sourceId, index }`.
+ * @event lyra-citation-open - The badge's "full preview" affordance was
+ * triggered (dblclick, or Space while focused).
+ * `detail: { sourceId, index, href }`.
+ * @csspart base - The clickable badge (`<button>`).
+ * @csspart bracket - Each of the two literal `[`/`]` glyphs.
+ * @csspart index - The citation number.
+ * @csspart popover - The floating preview panel (only meaningful while open).
+ */
+export declare class LyraCitationBadge extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** The citation number shown, e.g. `3` renders as `[3]`. */
+    index: number;
+    /** Confidence/verification state — drives the badge's color and (unless
+     *  `label` is set) part of its accessible name. */
+    status: CitationBadgeStatus;
+    /** Id of a corresponding `<lyra-source-card>` elsewhere on the page —
+     *  echoed back verbatim in both events, never read or validated here. */
+    sourceId: string;
+    /** Optional direct link target for the citation's source. Carried into
+     *  `lyra-citation-open`'s detail as-is; this component never navigates. */
+    href: string;
+    /** Overrides the computed accessible name (`"Citation {index}[, {status}]"`). */
+    label: string;
+    private hasPreviewSlot;
+    private popoverOpen;
+    private buttonEl?;
+    private popoverEl?;
+    private readonly popoverId;
+    private cleanupPositioner?;
+    private hideTimer?;
+    private hovering;
+    private focused;
+    protected willUpdate(): void;
+    protected updated(changed: PropertyValues): void;
+    disconnectedCallback(): void;
+    private get accessibleLabel();
+    private onSlotChange;
+    private showPreview;
+    private scheduleHidePreview;
+    private hidePreviewNow;
+    private onPointerEnter;
+    private onPointerLeave;
+    private onFocusIn;
+    private onFocusOut;
+    private onKeyDown;
+    private onClick;
+    private onDblClick;
+    private emitOpen;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-citation-badge': LyraCitationBadge;
+    }
+}

package/dist/components/citation-badge/citation-badge.js

@@ -0,0 +1,318 @@
+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, query } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { place } from '../../internal/positioner.js';
+import { nextId } from '../../internal/a11y.js';
+import { styles } from './citation-badge.styles.js';
+/** Visible (not just color-coded) status word, folded into the computed
+ *  accessible name — `''` for `default` omits the status clause entirely
+ *  rather than announcing a meaningless "Citation 3, Default". */
+const STATUS_LABEL = {
+    default: '',
+    high: 'High confidence',
+    medium: 'Medium confidence',
+    low: 'Low confidence',
+    verified: 'Verified',
+    unverified: 'Unverified',
+};
+// A short grace period before the popover actually hides on pointer-leave/
+// focus-out, so moving the mouse from the badge into the popover itself (to
+// select/copy its text) doesn't make it vanish mid-move. Cancelled outright
+// if hover or focus returns before it fires. No delay on Escape or explicit
+// keyboard blur — those are intentional dismissals, not transient pointer
+// travel, so they close immediately.
+const HIDE_DELAY_MS = 200;
+// The default slot's preview content is often plain text (see the Statuses
+// story: "No source has confirmed this yet.") with no wrapping element at
+// all, so an Element-only check (e.g. Array.from(children)/assignedElements)
+// never counts it. Mirrors result-field.ts's hasRealContent: a node counts as
+// real preview content if it's an element not assigned to some other named
+// slot, or non-whitespace text.
+function isRealPreviewNode(n) {
+    return n.nodeType === Node.ELEMENT_NODE
+        ? !n.hasAttribute('slot')
+        : (n.textContent ?? '').trim().length > 0;
+}
+/**
+ * `<lyra-citation-badge>` — an inline `[n]` citation marker with a hover/
+ * focus preview popover and confidence/verification-status coloring. Used
+ * for an agent response's inline citations, each carrying a `source-id`
+ * that matches a corresponding `<lyra-source-card>` shown elsewhere on the
+ * page (a sibling component in this same family — this component doesn't
+ * import or know anything about it, only carries the id through its
+ * events).
+ *
+ * The default slot is *not* the badge's visible content — the badge always
+ * renders `[index]` — it's reserved for optional rich preview content (e.g.
+ * a filename + short excerpt) shown in a floating popover on hover/focus,
+ * positioned with `internal/positioner.js`'s `place()` the same way
+ * `<lyra-tool-call-chip>` positions its own detail tooltip. No popover shows
+ * at all when the slot carries no content, and the popover never traps
+ * focus — it's supplementary preview content, not a modal, so Tab continues
+ * past the badge normally even while it happens to be visible from a mouse
+ * hover.
+ *
+ * Two distinct signals fire from the same badge: `lyra-citation-activate`
+ * (click, or Enter while focused — native `<button>` behavior, no listener
+ * needed for the Enter case) is the lightweight "jump to this source"
+ * signal a host wires to scrolling/highlighting the matching
+ * `<lyra-source-card>`. `lyra-citation-open` (dblclick, or Space while
+ * focused) is a distinct "full preview" signal — `href` in its detail is
+ * `undefined` when the `href` prop isn't set; the consumer decides what
+ * "open" means (a new tab, a dialog, etc). A double-click still fires two
+ * `lyra-citation-activate` events (one per constituent click — standard
+ * browser `dblclick` behavior) in addition to the one `lyra-citation-open`;
+ * a consumer that only cares about the richer signal on a double-click
+ * should ignore the paired activate events in that case.
+ *
+ * Status coloring: `verified`/`high` use the success tones (a claim that's
+ * been checked out, or the model is confident in). `medium`/`low` use
+ * warning (progressively less certain, but still a real citation).
+ * `unverified` uses danger — deliberately distinct from `low`: "hasn't been
+ * checked at all" is a different (arguably riskier) claim than "checked but
+ * uncertain". `default` renders as plain neutral text with no background
+ * tint, for citations that carry no confidence/verification signal at all.
+ *
+ * @customElement lyra-citation-badge
+ * @slot - Rich preview/tooltip content (e.g. a filename + excerpt), shown in
+ * a floating popover on hover/focus. Nothing renders (no hover affordance at
+ * all) when this slot is empty.
+ * @event lyra-citation-activate - The badge was activated (click, or Enter
+ * while focused). `detail: { sourceId, index }`.
+ * @event lyra-citation-open - The badge's "full preview" affordance was
+ * triggered (dblclick, or Space while focused).
+ * `detail: { sourceId, index, href }`.
+ * @csspart base - The clickable badge (`<button>`).
+ * @csspart bracket - Each of the two literal `[`/`]` glyphs.
+ * @csspart index - The citation number.
+ * @csspart popover - The floating preview panel (only meaningful while open).
+ */
+export class LyraCitationBadge extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** The citation number shown, e.g. `3` renders as `[3]`. */
+        this.index = 1;
+        /** Confidence/verification state — drives the badge's color and (unless
+         *  `label` is set) part of its accessible name. */
+        this.status = 'default';
+        /** Id of a corresponding `<lyra-source-card>` elsewhere on the page —
+         *  echoed back verbatim in both events, never read or validated here. */
+        this.sourceId = '';
+        /** Optional direct link target for the citation's source. Carried into
+         *  `lyra-citation-open`'s detail as-is; this component never navigates. */
+        this.href = '';
+        /** Overrides the computed accessible name (`"Citation {index}[, {status}]"`). */
+        this.label = '';
+        // A `[part]` always contains a literal `<slot>` child regardless of
+        // assigned content, so `:empty` never matches — real emptiness is tracked
+        // in JS instead, same fix lyra-tool-call-chip's hasDetailSlot/lyra-stat's
+        // hasIcon etc. already establish.
+        this.hasPreviewSlot = false;
+        this.popoverOpen = false;
+        this.popoverId = nextId('citation-badge-popover');
+        // Hover and focus are tracked as independent "keep it open" reasons —
+        // mirrors lyra-toast-item's identical hovering/focused pair — so releasing
+        // one (e.g. the pointer leaving while the badge still has keyboard focus)
+        // doesn't schedule a hide the other modality is still holding open.
+        this.hovering = false;
+        this.focused = false;
+        this.onSlotChange = (e) => {
+            this.hasPreviewSlot = e.target.assignedNodes({ flatten: true }).some(isRealPreviewNode);
+            // The slot can be emptied out from under an already-open popover (e.g. a
+            // consumer clearing preview content asynchronously) — nothing left to
+            // show, so don't leave an empty panel floating open.
+            if (!this.hasPreviewSlot)
+                this.hidePreviewNow();
+        };
+        // Attached to the wrapper (not the button alone) so the popover's own
+        // slotted content counts too — pointerenter/pointerleave/focusin/focusout
+        // fire relative to whichever element they're bound to, not per descendant,
+        // so moving the pointer or focus between the button and the popover panel
+        // within this same wrapper never toggles hovering/focused off and on.
+        this.onPointerEnter = () => {
+            this.hovering = true;
+            this.showPreview();
+        };
+        this.onPointerLeave = () => {
+            this.hovering = false;
+            this.scheduleHidePreview();
+        };
+        this.onFocusIn = () => {
+            this.focused = true;
+            this.showPreview();
+        };
+        // No grace period here, unlike onPointerLeave -- a blur (Tab/Shift+Tab
+        // away, or focus programmatically moved elsewhere) is a deliberate
+        // navigation, not the transient pointer travel the delay exists to survive,
+        // so it closes at once. Still deferred to hover if the pointer happens to
+        // be resting on the badge/popover at the same time.
+        this.onFocusOut = () => {
+            this.focused = false;
+            if (this.hovering)
+                return;
+            this.hidePreviewNow();
+        };
+        // keydown bubbles up from whatever actually holds focus (the button, or a
+        // focusable element inside slotted preview content) — attaching this at
+        // the wrapper, rather than the button alone, is what makes Escape work
+        // "while the popover has focus-within" per the component's contract,
+        // without needing to track focus targets explicitly here.
+        this.onKeyDown = (e) => {
+            if (e.key === 'Escape' && this.popoverOpen) {
+                // Swallow it here rather than letting it bubble to e.g. a containing
+                // lyra-dialog's own Escape-to-close handler — dismissing this
+                // lightweight preview shouldn't also close a surrounding modal.
+                e.stopPropagation();
+                this.hidePreviewNow();
+                return;
+            }
+            // Space normally activates a <button> the same as Enter, but this
+            // component gives the two keys distinct meanings (Enter = activate,
+            // Space = open) — so Space's native click-on-keyup must be pre-empted
+            // here (preventDefault on keydown suppresses it) rather than left to
+            // fire alongside this. Enter deliberately gets no such handling: its
+            // native immediate click already reaches onClick below.
+            if (e.key === ' ' && !e.repeat && e.target === this.buttonEl) {
+                e.preventDefault();
+                this.emitOpen();
+            }
+        };
+        this.onClick = () => {
+            this.emit('lyra-citation-activate', { sourceId: this.sourceId, index: this.index });
+        };
+        this.onDblClick = () => {
+            this.emitOpen();
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    willUpdate() {
+        if (!this.hasUpdated) {
+            this.hasPreviewSlot = Array.from(this.childNodes).some(isRealPreviewNode);
+        }
+    }
+    updated(changed) {
+        if (changed.has('popoverOpen')) {
+            this.cleanupPositioner?.();
+            this.cleanupPositioner = undefined;
+            if (this.popoverOpen && this.buttonEl && this.popoverEl) {
+                this.cleanupPositioner = place(this.buttonEl, this.popoverEl, { placement: 'top-start' });
+            }
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.cleanupPositioner?.();
+        clearTimeout(this.hideTimer);
+    }
+    get accessibleLabel() {
+        if (this.label)
+            return this.label;
+        const statusText = STATUS_LABEL[this.status];
+        return statusText ? `Citation ${this.index}, ${statusText}` : `Citation ${this.index}`;
+    }
+    // Named showPreview/hidePreviewNow (not show/hidePopover) to avoid
+    // colliding with the standard HTML Popover API's own
+    // HTMLElement.prototype.showPopover()/hidePopover() -- this component
+    // renders its own floating panel via internal/positioner.js rather than
+    // the native `popover` attribute, but TS's DOM lib still declares those
+    // method names on every HTMLElement subclass, so reusing them here would
+    // be a same-name-different-signature override error.
+    showPreview() {
+        if (!this.hasPreviewSlot)
+            return;
+        // Cancel any pending hide unconditionally -- including when the popover
+        // is already open -- so hover/focus returning within the grace period
+        // (pointerenter -> pointerleave -> pointerenter before HIDE_DELAY_MS)
+        // actually cancels the scheduled hide instead of leaving it armed to
+        // fire later regardless of the now-restored hover/focus state.
+        clearTimeout(this.hideTimer);
+        this.hideTimer = undefined;
+        if (this.popoverOpen)
+            return;
+        this.popoverOpen = true;
+    }
+    scheduleHidePreview() {
+        if (!this.popoverOpen || this.hovering || this.focused)
+            return;
+        clearTimeout(this.hideTimer);
+        this.hideTimer = setTimeout(() => {
+            this.hideTimer = undefined;
+            this.popoverOpen = false;
+        }, HIDE_DELAY_MS);
+    }
+    hidePreviewNow() {
+        clearTimeout(this.hideTimer);
+        this.hideTimer = undefined;
+        if (this.popoverOpen)
+            this.popoverOpen = false;
+    }
+    emitOpen() {
+        this.emit('lyra-citation-open', {
+            sourceId: this.sourceId,
+            index: this.index,
+            href: this.href || undefined,
+        });
+    }
+    render() {
+        return html `
+      <span
+        class="wrapper"
+        @pointerenter=${this.onPointerEnter}
+        @pointerleave=${this.onPointerLeave}
+        @focusin=${this.onFocusIn}
+        @focusout=${this.onFocusOut}
+        @keydown=${this.onKeyDown}
+      >
+        <button
+          part="base"
+          type="button"
+          aria-label=${this.getAttribute('aria-label') || this.accessibleLabel}
+          aria-describedby=${this.hasPreviewSlot && this.popoverOpen ? this.popoverId : nothing}
+          @click=${this.onClick}
+          @dblclick=${this.onDblClick}
+        >
+          <span part="bracket" aria-hidden="true">[</span><span part="index">${this.index}</span
+          ><span part="bracket" aria-hidden="true">]</span>
+        </button>
+        <div part="popover" id=${this.popoverId} role="tooltip" ?hidden=${!this.popoverOpen}>
+          <slot @slotchange=${this.onSlotChange}></slot>
+        </div>
+      </span>
+    `;
+    }
+}
+__decorate([
+    property({ type: Number })
+], LyraCitationBadge.prototype, "index", void 0);
+__decorate([
+    property({ reflect: true })
+], LyraCitationBadge.prototype, "status", void 0);
+__decorate([
+    property({ attribute: 'source-id' })
+], LyraCitationBadge.prototype, "sourceId", void 0);
+__decorate([
+    property()
+], LyraCitationBadge.prototype, "href", void 0);
+__decorate([
+    property()
+], LyraCitationBadge.prototype, "label", void 0);
+__decorate([
+    state()
+], LyraCitationBadge.prototype, "hasPreviewSlot", void 0);
+__decorate([
+    state()
+], LyraCitationBadge.prototype, "popoverOpen", void 0);
+__decorate([
+    query('[part="base"]')
+], LyraCitationBadge.prototype, "buttonEl", void 0);
+__decorate([
+    query('[part="popover"]')
+], LyraCitationBadge.prototype, "popoverEl", void 0);
+defineElement('citation-badge', LyraCitationBadge);

package/dist/components/citation-badge/citation-badge.styles.d.ts

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

package/dist/components/citation-badge/citation-badge.styles.js

@@ -0,0 +1,96 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: inline-flex;
+    vertical-align: baseline;
+    line-height: 1;
+    /* Per-status accent -- one pair of custom properties swapped by the
+       :host([status]) rules below rather than repeating background/color
+       per part per status. 'default' (and any unrecognized status) stays
+       plain/neutral -- transparent background, quiet text -- rather than
+       inventing a seventh visual tone for "no signal at all". */
+    --lyra-citation-badge-accent: var(--lyra-color-text-quiet);
+    --lyra-citation-badge-bg: transparent;
+    --lyra-citation-badge-border: transparent;
+  }
+
+  :host([status='high']),
+  :host([status='verified']) {
+    --lyra-citation-badge-accent: var(--lyra-color-success);
+    --lyra-citation-badge-bg: var(--lyra-color-success-quiet);
+  }
+  :host([status='medium']),
+  :host([status='low']) {
+    --lyra-citation-badge-accent: var(--lyra-color-warning);
+    --lyra-citation-badge-bg: var(--lyra-color-warning-quiet);
+  }
+  /* Deliberately its own danger tone, not grouped with 'low' -- see the
+     component doc's status-coloring note: "hasn't been checked" reads as a
+     distinct (riskier) claim from "checked but uncertain". */
+  :host([status='unverified']) {
+    --lyra-citation-badge-accent: var(--lyra-color-danger);
+    --lyra-citation-badge-bg: var(--lyra-color-danger-quiet);
+  }
+
+  .wrapper {
+    display: inline-flex;
+  }
+
+  [part='base'] {
+    display: inline-flex;
+    align-items: baseline;
+    box-sizing: border-box;
+    padding: 0 0.3em;
+    border: 1px solid var(--lyra-citation-badge-border);
+    border-radius: calc(var(--lyra-radius) * 0.6);
+    background: var(--lyra-citation-badge-bg);
+    color: var(--lyra-citation-badge-accent);
+    font: inherit;
+    font-size: 0.75em;
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+    line-height: 1.5;
+    cursor: pointer;
+    -webkit-tap-highlight-color: transparent;
+    transition:
+      background-color var(--lyra-transition-fast),
+      border-color var(--lyra-transition-fast);
+  }
+  [part='base']:hover {
+    border-color: var(--lyra-citation-badge-accent);
+  }
+  [part='base']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+
+  [part='bracket'] {
+    opacity: 0.7;
+  }
+
+  /* Positioned by internal/positioner.js's place() -- same fixed/z-index/
+     max-size shape as lyra-tool-call-chip's own [part='tooltip']. No open/
+     close transition, for the same reason that one has none: a preview
+     that tracks the pointer/focus target should appear instantly, not
+     chase a fade. */
+  [part='popover'] {
+    position: fixed;
+    z-index: 900;
+    box-sizing: border-box;
+    max-inline-size: min(90vw, 22rem);
+    padding: var(--lyra-space-s) var(--lyra-space-m);
+    background: var(--lyra-color-surface);
+    border: 1px solid var(--lyra-color-border);
+    border-radius: var(--lyra-radius);
+    box-shadow: var(--lyra-shadow);
+    font-size: 0.8125rem;
+    line-height: 1.4;
+    color: var(--lyra-color-text);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [part='base'] {
+      transition: none !important;
+    }
+  }
+`;

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

@@ -0,0 +1,127 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { type ShikiLanguageInput } from './code-loader.js';
+import '../skeleton/skeleton.js';
+/**
+ * `<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.
+ *
+ * `languages` is an additive, opt-in escape hatch from that default path for
+ * a consumer whose language set is fixed and known ahead of time: a map of
+ * language id to an already-imported shiki grammar module (e.g. `import bash
+ * from 'shiki/langs/bash.mjs'`). When `language` matches a key in `languages`,
+ * this component seeds a fine-grained `createHighlighterCore()` highlighter
+ * with *only* the pre-supplied grammars (see `code-loader.ts`'s
+ * `loadShikiHighlighterCore()`) instead of waiting on `loadShikiHighlighter()`
+ * and its dynamic per-language `loadLanguage()` import. The payoff isn't
+ * runtime cost — the default dynamic-import path is already well-optimized
+ * for that — it's *build output*: shiki's main entry point bundles a dynamic
+ * `import()` per bundled language (~200 of them) because a bundler can't
+ * statically narrow which of those a `loadLanguage(lang: string)` call might
+ * request at runtime, so it conservatively emits a build-output chunk for
+ * every one of them. `shiki/core`'s fine-grained API has no such table — a
+ * bundler only ever sees the exact grammar modules `languages` itself
+ * `import`s, so a consumer who pins its full language set this way trades a
+ * hand-maintained list for a build output scoped to just those languages
+ * instead of shiki's entire bundled set. A language requested but absent
+ * from `languages` still falls back to the ordinary dynamic-import path
+ * unchanged, so this is a partial opt-in, not a replacement for it.
+ *
+ * @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.
+ * @event lyra-toggle - The collapse/expand header button was activated.
+ *   `detail: { collapsed }` — same event name and shape convention as
+ *   `<lyra-thinking-panel>`'s own `lyra-toggle`.
+ * @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 declare class LyraCodeBlock extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** The raw source text. */
+    code: string;
+    /** 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. */
+    language: string;
+    /** Shown in the header above the code, when set. */
+    filename: string;
+    /** Whether the code region can be collapsed via a header toggle. */
+    collapsible: boolean;
+    /** Whether the code region is currently hidden. Only has a visible effect
+     *  while `collapsible` is also true. */
+    collapsed: boolean;
+    /** Shows a copy-to-clipboard button in the header. */
+    copyable: boolean;
+    /** A CSS length (e.g. `"20rem"`); once set, the code scrolls internally
+     *  past this height instead of growing the page. */
+    maxHeight: string;
+    /** A map of language id to an already-imported shiki grammar module's
+     *  default export (e.g. `{ bash: bashGrammar }` where `bashGrammar` came
+     *  from a module-scope `import bash from 'shiki/langs/bash.mjs'`). When
+     *  `language` matches a key here, highlighting for it is seeded from
+     *  exactly this pre-supplied grammar via a fine-grained
+     *  `createHighlighterCore()` highlighter, bypassing the default
+     *  `loadShikiHighlighter()` singleton and its dynamic per-language
+     *  `loadLanguage()` import entirely for that language — see the class doc
+     *  above for the build-output rationale. A `language` value absent from
+     *  this map (or left unset, or when `languages` itself is unset) falls
+     *  back to that default dynamic-import path unchanged. */
+    languages?: Record<string, ShikiLanguageInput>;
+    private highlightedHtml;
+    private shikiReady;
+    private justCopied;
+    private highlighter?;
+    private highlightToken;
+    private copyTimeoutId?;
+    private readonly bodyId;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private preSuppliedGrammar;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(): void;
+    private syncHighlight;
+    private tokenize;
+    private writeClipboard;
+    private copy;
+    private toggleCollapsed;
+    private renderHeader;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-code-block': LyraCodeBlock;
+    }
+}