@kestack/web-platform 0.0.0-stage → 0.0.0

package/src/components/viewers/source-viewer/source-viewer.tsx

@@ -0,0 +1,437 @@
+import {
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import githubDark from '@shikijs/themes/github-dark';
+import githubLight from '@shikijs/themes/github-light';
+import {
+  createHighlighterCore,
+  type HighlighterCore,
+  type LanguageInput,
+} from 'shiki/core';
+import { createOnigurumaEngine } from 'shiki/engine/oniguruma';
+
+import { cn } from '#lib/utils';
+import { scrollbarStyles } from '#lib/scrollStyles';
+
+export interface SourceViewerRange {
+  readonly startLine: number;
+  readonly endLine: number;
+}
+
+export interface SourceViewerSection {
+  readonly id: string;
+  readonly range: SourceViewerRange;
+}
+
+export interface SourceViewerLine {
+  readonly status: 'add' | 'remove' | 'context' | 'meta' | 'empty';
+  readonly number?: number;
+}
+
+export interface SourceViewerProps {
+  readonly filePath: string;
+  readonly content: string;
+  readonly range?: SourceViewerRange | null;
+  readonly sections?: readonly SourceViewerSection[];
+  readonly lineStatuses?: readonly SourceViewerLine[];
+  readonly onSectionClick?: (sectionId: string) => void;
+  readonly scrollRequestId?: number;
+  readonly wrap?: boolean;
+  readonly lineOffset?: number;
+  readonly showHeader?: boolean;
+  readonly showLineNumbers?: boolean;
+  readonly autoHeight?: boolean;
+  readonly actions?: ReactNode;
+  readonly className?: string;
+}
+
+type SourceLanguage =
+  | 'css'
+  | 'html'
+  | 'javascript'
+  | 'json'
+  | 'jsx'
+  | 'markdown'
+  | 'text'
+  | 'tsx'
+  | 'typescript'
+  | 'yaml';
+
+const languageByExtension: Readonly<Record<string, SourceLanguage>> = {
+  cjs: 'javascript',
+  css: 'css',
+  html: 'html',
+  js: 'javascript',
+  json: 'json',
+  jsx: 'jsx',
+  md: 'markdown',
+  mjs: 'javascript',
+  mts: 'typescript',
+  ts: 'typescript',
+  tsx: 'tsx',
+  yaml: 'yaml',
+  yml: 'yaml',
+};
+
+const highlighter = createHighlighterCore({
+  themes: [githubLight, githubDark],
+  langs: [],
+  engine: createOnigurumaEngine(import('shiki/wasm')),
+});
+
+const languageLoaders: Record<
+  Exclude<SourceLanguage, 'text'>,
+  () => LanguageInput
+> = {
+  css: () => import('@shikijs/langs/css'),
+  html: () => import('@shikijs/langs/html'),
+  javascript: () => import('@shikijs/langs/javascript'),
+  json: () => import('@shikijs/langs/json'),
+  jsx: () => import('@shikijs/langs/jsx'),
+  markdown: () => import('@shikijs/langs/markdown'),
+  tsx: () => import('@shikijs/langs/tsx'),
+  typescript: () => import('@shikijs/langs/typescript'),
+  yaml: () => import('@shikijs/langs/yaml'),
+};
+
+const loadingLanguages = new Map<SourceLanguage, Promise<void>>();
+
+function loadLanguage(instance: HighlighterCore, language: SourceLanguage) {
+  if (language === 'text' || instance.getLoadedLanguages().includes(language)) {
+    return Promise.resolve();
+  }
+  const loading =
+    loadingLanguages.get(language) ??
+    instance.loadLanguage(languageLoaders[language]());
+  loadingLanguages.set(language, loading);
+  return loading;
+}
+
+function paintSourceLine(line: HTMLElement, hovered = false) {
+  const depth = Number(line.dataset.sourceDepth ?? 0);
+  const focused = line.dataset.sourceFocused === 'true';
+  if (depth === 0 && !focused) {
+    line.style.backgroundColor = '';
+    line.style.borderInlineStartColor = '';
+    line.style.boxShadow = '';
+    return;
+  }
+  const fillAlpha = Math.min(
+    focused ? 0.18 : 0.12,
+    (focused ? 0.12 : 0.02) +
+      Math.max(0, depth - 1) * 0.025 +
+      (hovered ? 0.045 : 0),
+  );
+  const borderAlpha = Math.min(
+    1,
+    (focused ? 0.85 : 0.2) + Math.max(0, depth - 1) * 0.1 + (hovered ? 0.2 : 0),
+  );
+  const color = focused ? '59 130 246' : '56 189 248';
+  line.style.backgroundColor = `rgb(${color} / ${fillAlpha})`;
+  line.style.borderInlineStartColor = `rgb(${color} / ${borderAlpha})`;
+  line.style.boxShadow = focused
+    ? [
+        'inset 3px 0 rgb(59 130 246 / 0.85)',
+        'inset -1px 0 rgb(59 130 246 / 0.35)',
+        'inset 0 0 14px rgb(59 130 246 / 0.06)',
+        line.dataset.sourceFocusFirst === 'true'
+          ? 'inset 0 1px rgb(59 130 246 / 0.55)'
+          : '',
+        line.dataset.sourceFocusLast === 'true'
+          ? 'inset 0 -1px rgb(59 130 246 / 0.55)'
+          : '',
+      ]
+        .filter(Boolean)
+        .join(', ')
+    : '';
+}
+
+export function SourceViewer({
+  filePath,
+  content,
+  range,
+  sections = [],
+  lineStatuses,
+  onSectionClick,
+  scrollRequestId,
+  wrap = false,
+  lineOffset = 0,
+  showHeader = true,
+  showLineNumbers = true,
+  autoHeight = false,
+  actions,
+  className,
+}: SourceViewerProps) {
+  const viewportRef = useRef<HTMLDivElement>(null);
+  const handledScrollRequestRef = useRef<number | undefined>(undefined);
+  const hoveredSectionRef = useRef<string | null>(null);
+  const focusedLinesRef = useRef<readonly HTMLElement[]>([]);
+  const [rendered, setRendered] = useState<{
+    readonly content: string;
+    readonly language: SourceLanguage;
+    readonly lineOffset: number;
+    readonly lineStatuses: readonly SourceViewerLine[] | undefined;
+    readonly html: string;
+  } | null>(null);
+  const language = useMemo(() => {
+    const extension = filePath.split('.').pop()?.toLowerCase() ?? '';
+    return languageByExtension[extension] ?? 'text';
+  }, [filePath]);
+  const html =
+    rendered?.content === content &&
+    rendered.language === language &&
+    rendered.lineOffset === lineOffset &&
+    rendered.lineStatuses === lineStatuses
+      ? rendered.html
+      : '';
+
+  useEffect(() => {
+    let active = true;
+    void highlighter
+      .then(async (instance) => {
+        await loadLanguage(instance, language);
+        return instance.codeToHtml(content, {
+          lang: language,
+          themes: { light: 'github-light', dark: 'github-dark' },
+          defaultColor: false,
+          transformers: [
+            {
+              span(node) {
+                this.addClassToHast(node, 'shiki-token');
+              },
+              line(node, line) {
+                node.properties['data-line'] = line + lineOffset;
+                this.addClassToHast(node, 'source-line');
+                const status = lineStatuses?.[line - 1];
+                if (status === undefined) return;
+                node.properties['data-line-number'] = status.number ?? '';
+                this.addClassToHast(node, `source-line-${status.status}`);
+              },
+            },
+          ],
+        });
+      })
+      .then((next) => {
+        if (active) {
+          setRendered({
+            content,
+            language,
+            lineOffset,
+            lineStatuses,
+            html: next,
+          });
+        }
+      });
+    return () => {
+      active = false;
+    };
+  }, [content, language, lineOffset, lineStatuses]);
+
+  useLayoutEffect(() => {
+    if (!html) return;
+    hoveredSectionRef.current = null;
+    const viewport = viewportRef.current;
+    const lines = viewport?.querySelectorAll<HTMLElement>('[data-line]');
+    lines?.forEach((line) => {
+      const lineNumber = Number(line.dataset.line);
+      const matchingRanges = new Set(
+        sections.flatMap(({ range: sectionRange }) =>
+          lineNumber >= sectionRange.startLine &&
+          lineNumber <= sectionRange.endLine
+            ? [`${sectionRange.startLine}:${sectionRange.endLine}`]
+            : [],
+        ),
+      );
+      const depth = matchingRanges.size;
+      const section = depth > 0;
+      line.dataset.sourceDepth = String(depth);
+      line.classList.toggle('source-line-section', section);
+      line.classList.remove('source-line-section-hovered');
+      paintSourceLine(line);
+    });
+  }, [filePath, html, sections]);
+
+  // The highlighted HTML is injected into the DOM. Reapply focus after every
+  // render because settings changes can refresh those nodes without changing
+  // the source text or requested range.
+  useLayoutEffect(() => {
+    if (!html) return;
+    for (const line of focusedLinesRef.current) {
+      line.dataset.sourceFocused = 'false';
+      line.dataset.sourceFocusFirst = 'false';
+      line.dataset.sourceFocusLast = 'false';
+      line.classList.remove('source-line-focused');
+      paintSourceLine(line);
+    }
+    const viewport = viewportRef.current;
+    const focusedLines: HTMLElement[] = [];
+    if (range) {
+      for (
+        let lineNumber = range.startLine;
+        lineNumber <= range.endLine;
+        lineNumber++
+      ) {
+        const line = viewport?.querySelector<HTMLElement>(
+          `[data-line="${lineNumber}"]`,
+        );
+        if (!line) continue;
+        line.dataset.sourceFocused = 'true';
+        line.classList.add('source-line-focused');
+        focusedLines.push(line);
+      }
+    }
+    const firstFocusedLine = focusedLines[0];
+    const lastFocusedLine = focusedLines.at(-1);
+    if (firstFocusedLine) firstFocusedLine.dataset.sourceFocusFirst = 'true';
+    if (lastFocusedLine) lastFocusedLine.dataset.sourceFocusLast = 'true';
+    for (const line of focusedLines) paintSourceLine(line);
+    focusedLinesRef.current = focusedLines;
+
+    if (
+      !range ||
+      scrollRequestId === undefined ||
+      handledScrollRequestRef.current === scrollRequestId
+    ) {
+      return;
+    }
+    if (!viewport || !firstFocusedLine || !lastFocusedLine) return;
+    const viewportBounds = viewport.getBoundingClientRect();
+    const firstBounds = firstFocusedLine.getBoundingClientRect();
+    const lastBounds = lastFocusedLine.getBoundingClientRect();
+    const selectionTop =
+      viewport.scrollTop + firstBounds.top - viewportBounds.top;
+    const selectionBottom =
+      viewport.scrollTop + lastBounds.bottom - viewportBounds.top;
+    const selectionHeight = selectionBottom - selectionTop;
+    const padding = 16;
+    const desiredTop =
+      selectionHeight <= viewport.clientHeight - padding * 2
+        ? selectionTop - (viewport.clientHeight - selectionHeight) / 2
+        : selectionTop - padding;
+    const target = Math.max(
+      0,
+      Math.min(viewport.scrollHeight - viewport.clientHeight, desiredTop),
+    );
+    viewport.scrollLeft = 0;
+    viewport.scrollTop = target;
+    handledScrollRequestRef.current = scrollRequestId;
+  });
+
+  const sectionAtTarget = (target: EventTarget) => {
+    if (!(target instanceof Element)) return undefined;
+    const line = target.closest<HTMLElement>('[data-line]');
+    if (!line) return undefined;
+    const lineNumber = Number(line.dataset.line);
+    return sections
+      .filter(
+        ({ range: sectionRange }) =>
+          lineNumber >= sectionRange.startLine &&
+          lineNumber <= sectionRange.endLine,
+      )
+      .sort(
+        (left, right) =>
+          left.range.endLine -
+          left.range.startLine -
+          (right.range.endLine - right.range.startLine),
+      )[0];
+  };
+
+  const setHoveredSection = (sectionId: string | null) => {
+    if (hoveredSectionRef.current === sectionId) return;
+    hoveredSectionRef.current = sectionId;
+    const section = sections.find((candidate) => candidate.id === sectionId);
+    viewportRef.current
+      ?.querySelectorAll<HTMLElement>('[data-line]')
+      .forEach((line) => {
+        const lineNumber = Number(line.dataset.line);
+        line.classList.toggle(
+          'source-line-section-hovered',
+          Boolean(
+            section &&
+            lineNumber >= section.range.startLine &&
+            lineNumber <= section.range.endLine,
+          ),
+        );
+        paintSourceLine(
+          line,
+          Boolean(
+            section &&
+            lineNumber >= section.range.startLine &&
+            lineNumber <= section.range.endLine,
+          ),
+        );
+      });
+  };
+
+  const handleSectionClick = (target: EventTarget) => {
+    if (!onSectionClick) return;
+    const section = sectionAtTarget(target);
+    if (section) onSectionClick(section.id);
+  };
+
+  return (
+    <section
+      className={cn(
+        'flex flex-col bg-background',
+        autoHeight ? 'h-auto' : 'h-full min-h-0',
+        className,
+      )}
+      aria-label={`Source: ${filePath}`}
+    >
+      {showHeader && (
+        <header className="flex h-11 shrink-0 items-center gap-3 border-b border-border px-3">
+          <span
+            className="min-w-0 flex-1 truncate font-mono text-xs"
+            title={filePath}
+          >
+            {filePath}
+          </span>
+          {actions}
+        </header>
+      )}
+      <div
+        ref={viewportRef}
+        style={{ counterReset: `line ${lineOffset}` }}
+        className={cn(
+          'source-viewer',
+          'min-h-0 flex-1 bg-background font-mono text-[13px] [&_.shiki]:bg-transparent! [&_.shiki]:py-3 [&_code]:flex [&_code]:flex-col [&_.source-line]:relative [&_.source-line]:box-border [&_.source-line]:block [&_.source-line]:min-h-[1.375rem] [&_.source-line]:border-s-2 [&_.source-line]:border-transparent [&_.source-line]:pe-6 [&_.source-line]:leading-[1.375rem] [&_.source-line]:transition-colors [&_.source-line]:duration-100 [&_.source-line-section]:cursor-pointer [&_.source-line-focused]:cursor-pointer',
+          autoHeight
+            ? 'overflow-visible [&_.shiki]:min-h-0'
+            : cn(
+                'overflow-y-scroll overscroll-contain [scrollbar-gutter:stable] [&_.shiki]:min-h-full',
+                scrollbarStyles,
+              ),
+          showLineNumbers
+            ? cn(
+                '[&_.source-line]:ps-14 [&_.source-line]:before:absolute [&_.source-line]:before:start-0 [&_.source-line]:before:w-11 [&_.source-line]:before:pe-3 [&_.source-line]:before:text-end [&_.source-line]:before:text-[11px] [&_.source-line]:before:text-muted-foreground/35',
+                lineStatuses === undefined
+                  ? '[&_.source-line]:[counter-increment:line] [&_.source-line]:before:content-[counter(line)]'
+                  : '[&_.source-line]:before:content-[attr(data-line-number)]',
+              )
+            : '[&_.source-line]:ps-4',
+          wrap
+            ? 'overflow-x-hidden [&_.shiki]:w-full [&_.shiki]:min-w-0 [&_code]:w-full [&_.source-line]:break-words [&_.source-line]:whitespace-pre-wrap'
+            : cn(
+                // Lines must span the scrollable width, not the visible width,
+                // or their backgrounds stop short once scrolled sideways.
+                '[&_.shiki]:min-w-max [&_code]:w-max [&_code]:min-w-full',
+                // autoHeight hands scrolling to the parent, so it must not also
+                // scroll here: a nested overflow-x forces overflow-y to scroll.
+                !autoHeight && 'overflow-x-auto',
+              ),
+        )}
+        onClick={(event) => handleSectionClick(event.target)}
+        onPointerMove={(event) =>
+          setHoveredSection(sectionAtTarget(event.target)?.id ?? null)
+        }
+        onPointerLeave={() => setHoveredSection(null)}
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    </section>
+  );
+}

package/src/cosmos.decorator.tsx

@@ -0,0 +1,38 @@
+import { Moon, Sun } from 'lucide-react';
+import type { ReactNode } from 'react';
+import { createTheme } from './theme';
+import './theme/css/global.css';
+
+const themeController = createTheme();
+
+export default function CosmosDecorator({ children }: { children: ReactNode }) {
+  const { theme, toggleTheme } = themeController.useTheme();
+
+  return (
+    <>
+      <div className="bg-background text-foreground min-h-svh">{children}</div>
+      <button
+        onClick={toggleTheme}
+        aria-label="Toggle theme"
+        style={{
+          position: 'fixed',
+          bottom: 16,
+          right: 16,
+          zIndex: 9999,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          width: 36,
+          height: 36,
+          borderRadius: '50%',
+          border: '1px solid #444',
+          background: theme === 'dark' ? '#1a1a1a' : '#f5f5f5',
+          color: theme === 'dark' ? '#fff' : '#000',
+          cursor: 'pointer',
+        }}
+      >
+        {theme === 'dark' ? <Sun size={16} /> : <Moon size={16} />}
+      </button>
+    </>
+  );
+}

package/src/css.d.ts

@@ -0,0 +1 @@
+declare module '*.css';

package/src/define/index.ts

@@ -0,0 +1,26 @@
+// What an app writes before `createApp`: its APIs, its device Backend over
+// the device's Storage, and its Session. Nothing here loads the browser app,
+// so a Worker and a test can import it.
+export {
+  Api,
+  type ApiClient,
+  type ApiClients,
+  type Apis,
+  type DeviceBackend,
+  type DeviceBackends,
+  type RpcsOf,
+  type Transport,
+} from '../app/apis/index.ts';
+export type { Backend, Storage } from '../app/host/index.ts';
+export {
+  defineSession,
+  keepSyncs,
+  type Run,
+  SessionClosed,
+  type SessionContext,
+  type SessionDef,
+  type SessionOf,
+  type SessionStatus,
+  type StdSync,
+  syncName,
+} from '../app/session/index.ts';

package/src/feedback/index.ts

@@ -0,0 +1 @@
+export { play, type SoundName } from './sound.ts';

package/src/feedback/sound.ts

@@ -0,0 +1,167 @@
+/**
+ * The app's sounds, made by the browser as they play: no files to load,
+ * each under 150 ms and quiet, so they confirm rather than announce.
+ */
+export type SoundName =
+  /** One step through a list. */
+  | 'tick'
+  /** A Command is ready to run when the finger lifts. */
+  | 'arm'
+  /** A Command ran. */
+  | 'confirm'
+  /** A gesture's Command ran: softer than confirm. */
+  | 'success'
+  /** A sheet opened. */
+  | 'open'
+  /** A sheet closed. */
+  | 'close'
+  /** Nothing to do that way. */
+  | 'wrong'
+  /** The theme changed. */
+  | 'theme'
+  /** Money saved. */
+  | 'coin';
+
+type Voice = (context: AudioContext, out: AudioNode, at: number) => void;
+
+// One tone: a frequency gliding to `to`, rising fast and fading.
+const tone =
+  (options: {
+    readonly from: number;
+    readonly to?: number;
+    readonly type?: OscillatorType;
+    readonly length: number;
+    readonly gain: number;
+    readonly delay?: number;
+  }): Voice =>
+  (context, out, now) => {
+    const at = now + (options.delay ?? 0);
+    const end = at + options.length;
+    const oscillator = context.createOscillator();
+    const gain = context.createGain();
+    oscillator.type = options.type ?? 'sine';
+    oscillator.frequency.setValueAtTime(options.from, at);
+    if (options.to !== undefined) {
+      oscillator.frequency.exponentialRampToValueAtTime(options.to, end);
+    }
+    gain.gain.setValueAtTime(0.0001, at);
+    gain.gain.exponentialRampToValueAtTime(options.gain, at + 0.006);
+    gain.gain.exponentialRampToValueAtTime(0.0001, end);
+    oscillator.connect(gain).connect(out);
+    oscillator.start(at);
+    oscillator.stop(end + 0.02);
+  };
+
+// A breath of filtered noise, its filter sweeping from `from` to `to` Hz.
+const air =
+  (options: {
+    readonly from: number;
+    readonly to: number;
+    readonly length: number;
+    readonly gain: number;
+  }): Voice =>
+  (context, out, at) => {
+    const length = Math.ceil(context.sampleRate * options.length);
+    const buffer = context.createBuffer(1, length, context.sampleRate);
+    const data = buffer.getChannelData(0);
+    for (let i = 0; i < length; i++) data[i] = Math.random() * 2 - 1;
+    const source = context.createBufferSource();
+    source.buffer = buffer;
+    const filter = context.createBiquadFilter();
+    filter.type = 'bandpass';
+    filter.Q.value = 1.4;
+    filter.frequency.setValueAtTime(options.from, at);
+    filter.frequency.exponentialRampToValueAtTime(
+      options.to,
+      at + options.length,
+    );
+    const gain = context.createGain();
+    gain.gain.setValueAtTime(0.0001, at);
+    gain.gain.exponentialRampToValueAtTime(
+      options.gain,
+      at + options.length * 0.35,
+    );
+    gain.gain.exponentialRampToValueAtTime(0.0001, at + options.length);
+    source.connect(filter).connect(gain).connect(out);
+    source.start(at);
+  };
+
+const both =
+  (...voices: ReadonlyArray<Voice>): Voice =>
+  (context, out, at) => {
+    for (const voice of voices) voice(context, out, at);
+  };
+
+const VOICES: Readonly<Record<SoundName, Voice>> = {
+  tick: tone({ from: 1850, to: 1400, length: 0.025, gain: 0.12 }),
+  arm: tone({
+    from: 1180,
+    to: 1320,
+    type: 'triangle',
+    length: 0.05,
+    gain: 0.12,
+  }),
+  confirm: both(
+    tone({ from: 660, length: 0.07, gain: 0.14, type: 'triangle' }),
+    tone({
+      from: 990,
+      length: 0.09,
+      gain: 0.12,
+      type: 'triangle',
+      delay: 0.05,
+    }),
+  ),
+  success: tone({ from: 1320, to: 1760, length: 0.07, gain: 0.07 }),
+  open: air({ from: 500, to: 2400, length: 0.12, gain: 0.16 }),
+  close: air({ from: 2200, to: 450, length: 0.11, gain: 0.14 }),
+  wrong: both(
+    tone({ from: 190, to: 120, type: 'square', length: 0.09, gain: 0.05 }),
+    tone({
+      from: 140,
+      to: 95,
+      type: 'square',
+      length: 0.12,
+      gain: 0.04,
+      delay: 0.06,
+    }),
+  ),
+  theme: both(
+    tone({ from: 880, length: 0.12, gain: 0.08 }),
+    tone({ from: 1320, length: 0.14, gain: 0.06, delay: 0.03 }),
+    tone({ from: 1760, length: 0.15, gain: 0.04, delay: 0.06 }),
+  ),
+  coin: both(
+    tone({ from: 1568, length: 0.06, gain: 0.1, type: 'triangle' }),
+    tone({
+      from: 2093,
+      length: 0.12,
+      gain: 0.09,
+      type: 'triangle',
+      delay: 0.055,
+    }),
+  ),
+};
+
+let context: AudioContext | undefined;
+let master: GainNode | undefined;
+
+// The browser lets sound start only after the user touched or typed, so the
+// context is made on the first sound, which always follows one.
+const output = () => {
+  if (typeof AudioContext === 'undefined') return undefined;
+  if (context === undefined) {
+    context = new AudioContext();
+    master = context.createGain();
+    master.gain.value = 0.9;
+    master.connect(context.destination);
+  }
+  if (context.state === 'suspended') void context.resume();
+  return { context, out: master! };
+};
+
+/** Plays one sound now. Whether a sound is wanted is the caller's to say. */
+export const play = (name: SoundName) => {
+  const audio = output();
+  if (audio === undefined) return;
+  VOICES[name](audio.context, audio.out, audio.context.currentTime);
+};