@aleph-alpha/chat-kit 6.4.0 → 6.4.2

package/src/components/base/CkCodeEditor/CkCodeEditor.vue

@@ -1,13 +1,14 @@
 <script setup lang="ts">
 import {
   computed,
+  nextTick,
   onBeforeUnmount,
   onMounted,
   ref,
   useTemplateRef,
   watch,
 } from 'vue';
-import { UiButton, UiIcon } from '@aleph-alpha/ui-library';
+import { UiButton, UiFadeMask, UiIcon } from '@aleph-alpha/ui-library';
 import { useChatKitLabels } from '../../../handlers/useChatKitLabels';
 import type { CodeMirrorHandle } from './createCodeMirror';
 import type { CkCodeEditorEmits, CkCodeEditorProps } from './types';
@@ -28,6 +29,9 @@ const props = withDefaults(defineProps<CkCodeEditorProps>(), {
   lineWrapping: false,
   maxHeight: undefined,
   autofocus: false,
+  scrollFade: true,
+  fadeTopBackground: 'secondary',
+  fadeBottomBackground: 'floating',
   badge: undefined,
   writeToClipboard: undefined,
 });
@@ -54,6 +58,66 @@ const copyLabel = computed(() =>
     : (labels.value.codeEditorCopy ?? 'Copy code'),
 );
 
+// Whether there is code hidden above / below the visible area. Each fade is
+// shown only for the direction that can actually scroll, so a document that
+// fits its box shows none.
+const canScrollUp = ref(false);
+const canScrollDown = ref(false);
+let scrollTarget: HTMLElement | undefined;
+let scrollObserver: ResizeObserver | undefined;
+
+// 53px is the band height the design file uses for this mask, rather than
+// `UiFadeMask`'s own 4rem/6rem default, which is sized for page-level surfaces.
+const FADE_HEIGHT = '53px';
+
+function edgeToFade(up: boolean, down: boolean): 'top' | 'bottom' | 'both' {
+  if (up && down) return 'both';
+  return up ? 'top' : 'bottom';
+}
+
+// `UiFadeMask` takes the edges to draw rather than two independent flags, and
+// has no "neither" position, so a document that fits collapses the band to zero
+// height instead. Swapping the wrapper out for a plain `div` on every change
+// would remount the host element and take CodeMirror's DOM with it, so the mask
+// stays mounted for as long as `scrollFade` is on.
+const fadeProps = computed(() => {
+  if (!props.scrollFade) return {};
+  const up = canScrollUp.value;
+  const down = canScrollDown.value;
+  return {
+    position: edgeToFade(up, down),
+    style: {
+      '--ui-fade-mask-height': up || down ? FADE_HEIGHT : '0px',
+      '--ck-code-fade-top': `var(--background-surface-${props.fadeTopBackground})`,
+      '--ck-code-fade-bottom': `var(--background-surface-${props.fadeBottomBackground})`,
+    },
+  };
+});
+
+function syncScrollFades(): void {
+  if (!scrollTarget) return;
+  const { scrollTop, scrollHeight, clientHeight } = scrollTarget;
+  canScrollUp.value = scrollTop > 1;
+  // A pixel of slack: fractional layout sizes otherwise leave the bottom fade
+  // showing when the document is scrolled fully down.
+  canScrollDown.value = scrollTop + clientHeight < scrollHeight - 1;
+}
+
+function watchScrolling(scroller: HTMLElement, content: HTMLElement): void {
+  scrollTarget = scroller;
+  scroller.addEventListener('scroll', syncScrollFades, { passive: true });
+  if (typeof ResizeObserver !== 'undefined') {
+    // Neither of these fires a scroll event. The scroller covers the box being
+    // resized; the content is watched separately because once `maxHeight` caps
+    // the scroller, typing a new line grows only the content, and the bottom
+    // fade would otherwise never appear.
+    scrollObserver = new ResizeObserver(syncScrollFades);
+    scrollObserver.observe(scroller);
+    scrollObserver.observe(content);
+  }
+  syncScrollFades();
+}
+
 let editor: CodeMirrorHandle | undefined;
 let destroyed = false;
 // Last value emitted or applied, so an echo from the parent is not re-applied.
@@ -88,7 +152,6 @@ onMounted(async () => {
     badge: props.badge,
     onChange: handleChange,
     onFocus: () => emit('focus'),
-    onBlur: () => emit('blur'),
   });
 
   // Unmounted while the grammar was loading.
@@ -100,6 +163,7 @@ onMounted(async () => {
   editor = handle;
   // Props may have moved on while the grammar loaded; catch up.
   if (props.modelValue !== initialCode) handle.setCode(props.modelValue);
+  watchScrolling(handle.view.scrollDOM, handle.view.contentDOM);
   isReady.value = true;
   if (props.autofocus) handle.focus();
 });
@@ -110,6 +174,7 @@ watch(
     if (next === lastKnownCode) return;
     lastKnownCode = next;
     editor?.setCode(next);
+    void nextTick(syncScrollFades);
   },
 );
 
@@ -138,6 +203,9 @@ watch(
 onBeforeUnmount(() => {
   destroyed = true;
   clearTimeout(copyTimer);
+  scrollTarget?.removeEventListener('scroll', syncScrollFades);
+  scrollObserver?.disconnect();
+  scrollTarget = undefined;
   editor?.destroy();
   editor = undefined;
 });
@@ -163,8 +231,9 @@ function isInsideRoot(target: EventTarget | null): boolean {
   return target instanceof Node && (rootRef.value?.contains(target) ?? false);
 }
 
-// CodeMirror reports focus on its own content; the header's copy button is
-// outside that, so only a move out of the whole component counts as a blur.
+// The single source of `blur`. CodeMirror reports focus loss on its own
+// content, which would fire for a move to the header's copy button; only a move
+// out of the whole component counts, and only the root can see that.
 function onFocusOut(event: FocusEvent): void {
   if (!isInsideRoot(event.relatedTarget)) emit('blur');
 }
@@ -184,7 +253,7 @@ defineExpose({ focus, getCode });
   <div
     ref="rootRef"
     :class="[
-      'ck-code-editor ck-code-surface border-border-surface-default min-w-0 overflow-hidden rounded-lg border',
+      'ck-code-editor ck-code-surface border-border-surface-default bg-background-input-default min-w-0 overflow-hidden rounded-xl border',
       isReady && 'ck-code-editor--ready',
       isLocked && 'ck-code-editor--readonly',
       disabled && 'ck-code-editor--disabled',
@@ -210,30 +279,98 @@ defineExpose({ focus, getCode });
       </UiButton>
     </div>
 
-    <div
-      ref="hostRef"
-      class="ck-code-editor__host"
-      :style="maxHeight ? { '--ck-code-max-height': maxHeight } : undefined"
-    />
+    <component
+      :is="scrollFade ? UiFadeMask : 'div'"
+      v-bind="fadeProps"
+      class="ck-code-editor__body min-w-0"
+    >
+      <div
+        ref="hostRef"
+        class="ck-code-editor__host"
+        :style="maxHeight ? { '--ck-code-max-height': maxHeight } : undefined"
+      />
+    </component>
   </div>
 </template>
 
 <style scoped>
-/* The editor fills the panel; `:deep` is needed because CodeMirror builds its
- * own DOM, which scoped styles do not reach. */
-.ck-code-editor__host :deep(.cm-editor) {
-  background: var(--ck-cm-bg);
-  color: var(--ck-cm-foreground);
+/* The body follows the design-system field rather than `UiCodeBlock`: body
+ * text in the primary content colour on the input surface, with muted mono
+ * line numbers. Only the syntax colours stay shared with `UiCodeBlock` (see
+ * `helpers/codemirror/code-palette.css`). The overrides live here, not in
+ * `theme.ts`, because `CkMilkdownEditor`'s code blocks use that theme too and
+ * must keep matching the rendered block. */
+.ck-code-editor {
+  /* `theme.ts` paints the editor from these; transparent lets the root's
+   * input surface show through. */
+  --ck-cm-bg: transparent;
+  --ck-cm-foreground: oklch(var(--content-on-surface-primary));
+  --ck-cm-line-number: oklch(var(--content-on-surface-muted));
 }
 
+/* `:deep` is needed below because CodeMirror builds its own DOM, which scoped
+ * styles do not reach. Same declarations as the `body-14-regular` typography utility. */
 .ck-code-editor__host :deep(.cm-scroller) {
   max-height: var(--ck-code-max-height, none);
+  font-family: Saans, sans-serif;
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1.25rem;
 }
 
-/* Nothing is being edited, so the active-line band would only be noise. */
-.ck-code-editor--readonly .ck-code-editor__host :deep(.cm-activeLine),
-.ck-code-editor--readonly .ck-code-editor__host :deep(.cm-activeLineGutter) {
-  background: transparent;
+/* 12px below the header, 16px above the bottom edge, and a 20px right inset,
+ * as in the design. */
+.ck-code-editor__host :deep(.cm-content) {
+  padding: 0.75rem 1.25rem 1rem 1rem;
+}
+
+/* The number column already carries the 1rem left inset, so the code must not
+ * pay for it a second time. The sibling selector only matches while the gutter
+ * is mounted, which is exactly when `showLineNumbers` is on. */
+.ck-code-editor__host :deep(.cm-gutters ~ .cm-content) {
+  padding-left: 0;
+}
+
+/* Numbers stay monospaced so the column does not jitter as digits change; the
+ * 12px right padding is the gap before the code. */
+.ck-code-editor__host :deep(.cm-lineNumbers .cm-gutterElement) {
+  min-width: 0;
+  padding: 0 0.75rem 0 1rem;
+  /* `CODE_FONT_FAMILY` from `theme.ts`, repeated because importing it here
+   * would pull CodeMirror out of its lazy chunk. */
+  font-family:
+    ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono',
+    monospace;
+  font-weight: 500;
+}
+
+.ck-code-editor__host :deep(.cm-placeholder) {
+  color: oklch(var(--content-on-surface-muted));
+}
+
+/* Each band fades into its own surface (`fadeTopBackground` /
+ * `fadeBottomBackground`), whereas `UiFadeMask`'s `background` sets one for
+ * both and only knows `primary` and `secondary`. The gradient, edges and band
+ * height stay the mask's own. `[data-background]` outranks the mask's
+ * per-surface rule regardless of stylesheet order. */
+.ck-code-editor__body
+  :deep(.ui-fade-mask__band[data-background][data-position='top']) {
+  --ui-fade-mask-surface: var(--ck-code-fade-top);
+  /* The mask turns its top band opaque halfway down on desktop, which left a
+   * solid strip under the header; mirror the bottom band's stops instead. */
+  --ui-fade-mask-stop: 20%;
+}
+
+.ck-code-editor__body
+  :deep(.ui-fade-mask__band[data-background][data-position='bottom']) {
+  --ui-fade-mask-surface: var(--ck-code-fade-bottom);
+}
+
+@media (min-width: 768px) {
+  .ck-code-editor__body
+    :deep(.ui-fade-mask__band[data-background][data-position='top']) {
+    --ui-fade-mask-stop: 100%;
+  }
 }
 
 .ck-code-editor--disabled {

package/src/components/base/CkCodeEditor/badgeDecoration.ts

@@ -23,8 +23,8 @@ export interface CkCodeEditorBadgeContent {
   /** Native tooltip, useful for showing the underlying reference. */
   title?: string;
   /**
-   * Classes replacing the default pill styling, which mirrors `UiBadge`'s
-   * `outline` variant at `small` size.
+   * Classes replacing the default pill styling, which is the secondary badge
+   * the ChatKit design file specifies.
    */
   class?: string;
 }

package/src/components/base/CkCodeEditor/createCodeMirror.ts

@@ -39,8 +39,12 @@ export interface CreateCodeMirrorOptions {
   badge?: CkCodeEditorBadgeRule;
   /** Called synchronously whenever the document changes. */
   onChange: (value: string) => void;
+  /**
+   * Called when the editing area takes focus. There is deliberately no `onBlur`
+   * counterpart: losing focus to the header's copy button is not leaving the
+   * editor, and only the component around this view can tell the difference.
+   */
   onFocus: () => void;
-  onBlur: () => void;
 }
 
 /** Imperative surface `CkCodeEditor` drives; keeps CodeMirror out of the SFC. */
@@ -89,6 +93,22 @@ export async function resolveLanguage(
   }
 }
 
+/**
+ * Pick the line ending a document already uses.
+ *
+ * CodeMirror splits on `\n`, `\r\n` and `\r` alike, but `doc.toString()` always
+ * joins with `\n`. Left alone, opening a file with Windows line endings and
+ * typing one character would silently rewrite every line ending in it. Telling
+ * the editor which separator this document uses keeps it intact, both when
+ * reading the value back and when the user presses Enter.
+ */
+export function detectLineSeparator(doc: string): string {
+  const crlf = (doc.match(/\r\n/g) ?? []).length;
+  if (crlf === 0) return '\n';
+  const bareLf = (doc.match(/(?<!\r)\n/g) ?? []).length;
+  return crlf >= bareLf ? '\r\n' : '\n';
+}
+
 // `readOnly` rejects edits while keeping the text selectable; `editable`
 // additionally drops `contenteditable`, which hides the caret and keeps the
 // editor out of the tab order.
@@ -96,6 +116,11 @@ function readonlyState(readonly: boolean): Extension {
   return [EditorState.readOnly.of(readonly), EditorView.editable.of(!readonly)];
 }
 
+/** The document as text, with the line endings it came in with. */
+function readDoc(state: EditorState): string {
+  return state.doc.sliceString(0, state.doc.length, state.lineBreak);
+}
+
 function baseExtensions(options: CreateCodeMirrorOptions): Extension[] {
   return [
     // Deliberately not CodeMirror's `basicSetup`: it also brings autocomplete,
@@ -116,11 +141,8 @@ function baseExtensions(options: CreateCodeMirrorOptions): Extension[] {
       ...(options.ariaLabel ? { 'aria-label': options.ariaLabel } : {}),
     }),
     EditorView.updateListener.of((update) => {
-      if (update.docChanged) options.onChange(update.state.doc.toString());
-      if (update.focusChanged) {
-        if (update.view.hasFocus) options.onFocus();
-        else options.onBlur();
-      }
+      if (update.docChanged) options.onChange(readDoc(update.state));
+      if (update.focusChanged && update.view.hasFocus) options.onFocus();
     }),
     ...(options.placeholder ? [placeholderExt(options.placeholder)] : []),
   ];
@@ -140,8 +162,11 @@ export async function createCodeMirror(
   const lineNumbersSlot = new Compartment();
   const wrappingSlot = new Compartment();
   const badgeSlot = new Compartment();
+  const lineSeparatorSlot = new Compartment();
 
   const support = await resolveLanguage(options.language);
+  // Guards against out-of-order grammar loads; see `setLanguage` below.
+  let languageRequestId = 0;
 
   const view = new EditorView({
     parent: options.parent,
@@ -154,6 +179,9 @@ export async function createCodeMirror(
         lineNumbersSlot.of(options.showLineNumbers ? lineNumbers() : []),
         wrappingSlot.of(options.lineWrapping ? EditorView.lineWrapping : []),
         badgeSlot.of(options.badge ? badgeExtension(options.badge) : []),
+        lineSeparatorSlot.of(
+          EditorState.lineSeparator.of(detectLineSeparator(options.doc)),
+        ),
       ],
     }),
   });
@@ -164,9 +192,14 @@ export async function createCodeMirror(
 
   return {
     view,
-    getCode: () => view.state.doc.toString(),
+    getCode: () => readDoc(view.state),
     setCode: (value) => {
-      if (value === view.state.doc.toString()) return;
+      if (value === readDoc(view.state)) return;
+      // New content may use different line endings from what is loaded.
+      const separator = detectLineSeparator(value);
+      if (separator !== view.state.lineBreak) {
+        reconfigure(lineSeparatorSlot, EditorState.lineSeparator.of(separator));
+      }
       // Replacing the whole document would otherwise send the cursor home
       // whenever a parent echoes the value back; clamp it to the new length.
       const cursor = Math.min(view.state.selection.main.head, value.length);
@@ -176,7 +209,11 @@ export async function createCodeMirror(
       });
     },
     setLanguage: async (language) => {
+      // Grammars load over the network and out of order, so a slow one must not
+      // land on top of a language chosen after it.
+      const request = ++languageRequestId;
       const next = await resolveLanguage(language);
+      if (request !== languageRequestId) return;
       reconfigure(languageSlot, next ? [next] : []);
     },
     setReadonly: (readonly) => {

package/src/components/base/CkCodeEditor/types.ts

@@ -6,14 +6,24 @@ export type {
   CkCodeEditorBadgeRule,
 } from './badgeDecoration';
 
+/**
+ * Opaque design-system surfaces the scroll fade can dissolve into, each naming
+ * a `background-surface-*` token. Translucent surfaces are left out: the fade
+ * gradient needs a solid colour to end on.
+ */
+export type CkCodeEditorFadeSurface =
+  | 'primary'
+  | 'secondary'
+  | 'floating'
+  | 'modal';
+
 /**
  * Single-document code editor built on [CodeMirror 6](https://codemirror.net/).
- * Its surface is the one `UiCodeBlock` renders for fenced code inside
- * {@link CkMarkdownRenderer}: the same bordered, rounded panel, the same muted
- * header carrying the language and a copy button, the same monospace metrics,
- * and syntax colours approximating Shiki's `github-light` / `github-dark`. A
- * snippet therefore looks the same whether it is being read in a reply or
- * edited here.
+ * It shares `UiCodeBlock`'s muted header, carrying the language and a copy
+ * button, and its syntax colours approximating Shiki's `github-light` /
+ * `github-dark`, so highlighted code keeps its colours between a reply and the
+ * editor. The body follows the design-system input field: body text on the
+ * input surface, with muted monospace line numbers.
  *
  * Use it wherever a whole document *is* code — a snippet field, a config or
  * template editor, a "create skill" form. For prose that merely contains code,
@@ -102,6 +112,32 @@ export interface CkCodeEditorProps {
    * `'24rem'`. Unset, the editor grows with its content.
    */
   maxHeight?: string;
+  /**
+   * Fade the code out at the top and bottom edges when there is more of it
+   * scrolled out of view, so a clipped document reads as continuing rather than
+   * stopping mid-line.
+   *
+   * Each edge appears only when that direction can actually scroll, so a
+   * document that fits shows no fade at all. Relevant mainly alongside
+   * `maxHeight`, which is what makes the editor scroll in the first place.
+   *
+   * @default true
+   */
+  scrollFade?: boolean;
+  /**
+   * Surface the top scroll fade dissolves into, as a `background-surface-*`
+   * token name. The gradient itself is `UiFadeMask`'s; only its colour changes.
+   *
+   * @default 'secondary'
+   */
+  fadeTopBackground?: CkCodeEditorFadeSurface;
+  /**
+   * Surface the bottom scroll fade dissolves into, as a `background-surface-*`
+   * token name. The gradient itself is `UiFadeMask`'s; only its colour changes.
+   *
+   * @default 'floating'
+   */
+  fadeBottomBackground?: CkCodeEditorFadeSurface;
   /**
    * Move focus into the editor once it has been created.
    *

package/src/components/base/CkMarkdownRenderer/CkMarkdownRenderer.spec.ts

@@ -470,3 +470,43 @@ describe('CkMarkdownRenderer', () => {
     });
   });
 });
+
+describe('breaks', () => {
+  it('collapses a single newline into one line by default', () => {
+    const { container } = render(CkMarkdownRenderer, {
+      props: { content: 'line one\nline two' },
+    });
+
+    expect(container.querySelectorAll('p')).toHaveLength(1);
+    expect(container.querySelector('br')).toBeNull();
+  });
+
+  it('keeps a single newline as a line break when `breaks` is set', () => {
+    const { container } = render(CkMarkdownRenderer, {
+      props: { content: 'line one\nline two', breaks: true },
+    });
+
+    expect(container.querySelectorAll('p')).toHaveLength(1);
+    expect(container.querySelectorAll('br')).toHaveLength(1);
+    expect(container.querySelector('p')?.textContent).toContain('line one');
+    expect(container.querySelector('p')?.textContent).toContain('line two');
+  });
+
+  it('still starts a new paragraph on a blank line', () => {
+    const { container } = render(CkMarkdownRenderer, {
+      props: { content: 'one\n\ntwo', breaks: true },
+    });
+
+    expect(container.querySelectorAll('p')).toHaveLength(2);
+  });
+
+  it('leaves newlines inside fenced code alone', () => {
+    const { container } = render(CkMarkdownRenderer, {
+      props: { content: '```\nfirst\nsecond\n```', breaks: true },
+    });
+
+    const code = container.querySelector('pre code');
+    expect(code?.textContent).toBe('first\nsecond\n');
+    expect(code?.querySelector('br')).toBeNull();
+  });
+});

package/src/components/base/CkMarkdownRenderer/CkMarkdownRenderer.stories.ts

@@ -139,6 +139,17 @@ const plugins = [uppercasePlugin];
   <CkMarkdownRenderer :content="content" :plugins="plugins" />
 </template>`;
 
+const withLineBreaksTemplateSource = `<script setup lang="ts">
+import { CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+
+// Typed in an editor as three separate lines.
+const content = 'Roses are red\\nViolets are blue\\nMarkdown collapses these';
+</script>
+
+<template>
+  <CkMarkdownRenderer :content="content" breaks />
+</template>`;
+
 /**
  * Renders inline Markdown with bold, italic, and inline code. Use as the
  * default way to display assistant prose replies.
@@ -553,3 +564,23 @@ export const WithUnsupportedAndCodeMarkers: Story = {
       '<CkMarkdownRenderer :content="content" :citations="citations" />',
   }),
 };
+
+/**
+ * `breaks` keeps single newlines as line breaks. Without it CommonMark treats a
+ * lone newline as whitespace, so lines typed separately in an editor run
+ * together. A blank line still starts a new paragraph either way, and newlines
+ * inside fenced code are never touched.
+ */
+export const WithLineBreaks: Story = {
+  args: {
+    content: [
+      'Roses are red',
+      'Violets are blue',
+      'These three lines were typed separately.',
+      '',
+      'This is a new paragraph.',
+    ].join('\n'),
+    breaks: true,
+  },
+  parameters: { docs: { source: { code: withLineBreaksTemplateSource } } },
+};

package/src/components/base/CkMarkdownRenderer/CkMarkdownRenderer.vue

@@ -14,6 +14,7 @@ import {
   defaultChatKitLabels,
   useChatKitLabels,
 } from '../../../handlers/useChatKitLabels';
+import { remarkBreaks } from '../../../helpers/unified/remarkBreaks';
 import { useCitationRendering } from './useCitationRendering';
 import type { CkCitationSource } from '../CkCitation';
 import type { CkMarkdownElementClasses } from './types';
@@ -100,6 +101,7 @@ export default defineComponent({
       default: () => ({}),
     },
     plugins: { type: Array as PropType<PluggableList>, default: undefined },
+    breaks: { type: Boolean, default: false },
     citations: {
       type: Array as PropType<CkCitationSource[]>,
       default: undefined,
@@ -123,6 +125,7 @@ export default defineComponent({
 
     const effectivePlugins = computed<PluggableList>(() => [
       ...(props.plugins ?? []),
+      ...(props.breaks ? [remarkBreaks] : []),
       ...citationPlugins.value,
     ]);
 

package/src/components/base/CkMarkdownRenderer/types.ts

@@ -49,6 +49,19 @@ export interface CkMarkdownRendererProps {
    * generated HTML elements (e.g. `h1`, `p`, `ul`).
    */
   classes?: CkMarkdownElementClasses;
+  /**
+   * Treat a single newline as a line break, so two lines typed in an editor
+   * render as two lines.
+   *
+   * Off by default, because CommonMark says a lone newline is only whitespace
+   * and existing content may rely on that. Turn it on wherever people type the
+   * markdown themselves and expect their line breaks to survive; a blank line
+   * still starts a new paragraph either way, and newlines inside code spans and
+   * fenced blocks are never affected.
+   *
+   * @default false
+   */
+  breaks?: boolean;
   /** Extra [unified](https://unifiedjs.com/) plugins to extend parsing. */
   plugins?: PluggableList;
   /**

package/src/components/base/CkMilkdownEditor/milkdown-theme.css

@@ -412,9 +412,12 @@
   .milkdown-code-block
   .cm-lineNumbers
   .cm-gutterElement {
-  min-width: 2.25rem;
-  padding: 0 0.75rem 0 1rem;
-  color: oklch(var(--content-on-surface-muted));
+  /* Geometry and colour come from `theme.ts`, which matches `UiCodeBlock`'s
+   * gutter; this rule only exists because Crepe's own code-block styles would
+   * otherwise win on specificity. */
+  min-width: 4rem;
+  padding: 0 1rem;
+  color: var(--ck-cm-line-number);
   text-align: right;
 }
 

package/src/components/base/index.ts

@@ -90,5 +90,6 @@ export { CkCodeEditor } from './CkCodeEditor';
 export type {
   CkCodeEditorEmits,
   CkCodeEditorExposed,
+  CkCodeEditorFadeSurface,
   CkCodeEditorProps,
 } from './CkCodeEditor';

package/src/components/index.ts

@@ -73,6 +73,7 @@ export type {
   CkMilkdownEditorProps,
   CkCodeEditorEmits,
   CkCodeEditorExposed,
+  CkCodeEditorFadeSurface,
   CkCodeEditorProps,
 } from './base';
 

package/src/helpers/codemirror/code-palette.css

@@ -15,11 +15,23 @@
  * Exact parity is not achievable for every token: Shiki classifies with
  * TextMate grammars and CodeMirror with Lezer, and the two disagree at the
  * edges. The mapping in `theme.ts` targets the classes that actually occur in
- * everyday code.
+ * everyday code. Where one Lezer tag covers cases the GitHub themes colour
+ * differently, the mapping follows the more common one, which leaves a few
+ * known gaps: YAML keys and plain scalars both arrive as tags that mean
+ * something else in JavaScript, so they stay unhighlighted; `typeName` is blue
+ * here because that is right for TypeScript's primitives, though Rust and Go
+ * would want purple and red; and a fenced code block inside a Markdown
+ * document is not highlighted in its own language the way Shiki's embedded
+ * grammars do it.
  */
 
 .ck-code-surface {
-  --ck-cm-bg: #ffffff;
+  /* Held as bare oklch components, not a hex, because that is the form both
+   * `oklch()` and `UiFadeMask`'s surface variable need in order to fade the
+   * colour out to zero alpha. `--ck-cm-bg` is derived from it so there is one
+   * source of truth. */
+  --ck-cm-bg-components: 100% 0 89.88;
+  --ck-cm-bg: oklch(var(--ck-cm-bg-components));
   --ck-cm-foreground: #24292e;
   --ck-cm-keyword: #d73a49;
   --ck-cm-string: #032f62;
@@ -34,10 +46,18 @@
   --ck-cm-tag: #22863a;
   --ck-cm-error: #b31d28;
   --ck-cm-selection: oklch(var(--background-accent-soft));
+  /* Line numbers. `UiCodeBlock` draws its gutter as the code foreground at
+   * 40% opacity rather than as a colour of its own, so this is derived from
+   * `--ck-cm-foreground` and needs no dark-mode counterpart. */
+  --ck-cm-line-number: color-mix(
+    in oklab,
+    var(--ck-cm-foreground) 40%,
+    transparent
+  );
 }
 
 html.dark .ck-code-surface {
-  --ck-cm-bg: #24292e;
+  --ck-cm-bg-components: 27.81% 0.0117 248.25;
   --ck-cm-foreground: #e1e4e8;
   --ck-cm-keyword: #f97583;
   --ck-cm-string: #9ecbff;