mosage 0.2.0 → 0.8.0

package/src/app/components/design-panel/use-design.ts

@@ -0,0 +1,85 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { DesignSystem } from '../../lib/design';
+
+type FetchedState = {
+  design: DesignSystem | null;
+  exists: boolean;
+  warning: string | null;
+  loaded: boolean;
+};
+
+export type UseDesignReturn = FetchedState & {
+  refresh: () => Promise<void>;
+  save: (patch: Partial<DesignSystem>) => Promise<{ ok: boolean; error?: string }>;
+  reset: () => Promise<{ ok: boolean; error?: string }>;
+};
+
+const INITIAL: FetchedState = { design: null, exists: false, warning: null, loaded: false };
+
+export function useDesign(docId: string): UseDesignReturn {
+  const [state, setState] = useState<FetchedState>(INITIAL);
+  const docIdRef = useRef(docId);
+  docIdRef.current = docId;
+
+  const refresh = useCallback(async () => {
+    const id = docIdRef.current;
+    if (!id) return;
+    try {
+      const res = await fetch(`/__design?docId=${encodeURIComponent(id)}`);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const body = (await res.json()) as {
+        design: DesignSystem;
+        exists: boolean;
+        warning: string | null;
+      };
+      setState({ design: body.design, exists: body.exists, warning: body.warning, loaded: true });
+    } catch (err) {
+      setState((s) => ({ ...s, warning: String((err as Error).message), loaded: true }));
+    }
+  }, []);
+
+  useEffect(() => {
+    setState(INITIAL);
+    void refresh();
+  }, [refresh]);
+
+  const save = useCallback(async (patch: Partial<DesignSystem>) => {
+    const id = docIdRef.current;
+    if (!id) return { ok: false, error: 'no document id' };
+    try {
+      const res = await fetch(`/__design?docId=${encodeURIComponent(id)}`, {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ patch }),
+      });
+      const body = (await res.json()) as { ok?: boolean; error?: string; design?: DesignSystem };
+      if (!res.ok || !body.ok) return { ok: false, error: body.error ?? `HTTP ${res.status}` };
+      if (body.design) {
+        setState((s) => ({ ...s, design: body.design ?? s.design, exists: true, warning: null }));
+      }
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: String((err as Error).message) };
+    }
+  }, []);
+
+  const reset = useCallback(async () => {
+    const id = docIdRef.current;
+    if (!id) return { ok: false, error: 'no document id' };
+    try {
+      const res = await fetch(`/__design/reset?docId=${encodeURIComponent(id)}`, {
+        method: 'POST',
+      });
+      const body = (await res.json()) as { ok?: boolean; error?: string; design?: DesignSystem };
+      if (!res.ok || !body.ok) return { ok: false, error: body.error ?? `HTTP ${res.status}` };
+      if (body.design) {
+        setState((s) => ({ ...s, design: body.design ?? s.design, exists: true, warning: null }));
+      }
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: String((err as Error).message) };
+    }
+  }, []);
+
+  return { ...state, refresh, save, reset };
+}

package/src/app/components/diagram.tsx

@@ -0,0 +1,76 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { LabelKind } from '../lib/labels';
+import { Figure } from './numbering';
+
+export type DiagramSource = {
+  svg: string;
+  width: number;
+  height: number;
+};
+
+export type DiagramProps = {
+  /** The compiled module from `import chart from './architecture.mmd'`. */
+  chart: DiagramSource;
+  /** Caption text. Given one, the drawing is numbered like any other figure. */
+  caption?: ReactNode;
+  captionText?: string;
+  kind?: LabelKind;
+  id?: string;
+  /**
+   * Drawn width in CSS px. Defaults to the diagram's natural size, capped to
+   * the column — a diagram wider than the text block is a layout fault, and
+   * `mosage check` would report it as one.
+   */
+  width?: number;
+  align?: 'left' | 'center';
+  style?: CSSProperties;
+  className?: string;
+};
+
+/**
+ * A diagram compiled from Mermaid-flavoured text at build time. The SVG is
+ * inlined rather than referenced through `<img>` so it inherits the document's
+ * theme variables — an `<img src="data:…">` would be painted in a document of
+ * its own, with none of this one's colours or faces.
+ */
+export function Diagram({
+  chart,
+  caption,
+  captionText,
+  kind = 'figure',
+  id,
+  width,
+  align = 'center',
+  style,
+  className,
+}: DiagramProps) {
+  const drawing = (
+    <div
+      className={caption ? undefined : className}
+      style={{
+        width: width ?? chart.width,
+        maxWidth: '100%',
+        marginLeft: align === 'center' ? 'auto' : undefined,
+        marginRight: align === 'center' ? 'auto' : undefined,
+        ...(caption ? undefined : style),
+      }}
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: the SVG is produced by this package's own renderer at build time, never from document input at runtime
+      dangerouslySetInnerHTML={{ __html: chart.svg }}
+    />
+  );
+
+  if (!caption) return drawing;
+
+  return (
+    <Figure
+      {...(id ? { id } : {})}
+      caption={caption}
+      {...(captionText ? { captionText } : {})}
+      kind={kind}
+      className={className}
+      {...(style ? { style } : {})}
+    >
+      {drawing}
+    </Figure>
+  );
+}

package/src/app/components/doc-assets.tsx

@@ -0,0 +1,129 @@
+import { Check, Copy, FileIcon, Loader2 } from 'lucide-react';
+import { useCallback, useEffect, useState } from 'react';
+import {
+  type Asset,
+  formatBytes,
+  GLOBAL_SCOPE,
+  importSnippet,
+  isPreviewable,
+  listAssets,
+} from '../lib/assets';
+import { cn } from '../lib/utils';
+
+type Group = { scope: string; label: string; assets: Asset[] };
+
+/**
+ * The images this document can reach, without leaving it: its own `assets/`
+ * folder plus the shared project folder. Clicking one gives the import line to
+ * paste into the source.
+ */
+export function DocAssets({ docId }: { docId: string }) {
+  const [groups, setGroups] = useState<Group[] | null>(null);
+  const [selected, setSelected] = useState<Asset | null>(null);
+  const [copied, setCopied] = useState(false);
+
+  const load = useCallback(async () => {
+    const [own, global] = await Promise.all([listAssets(docId), listAssets(GLOBAL_SCOPE)]);
+    setGroups([
+      { scope: docId, label: 'This document', assets: own.ok ? own.value : [] },
+      { scope: GLOBAL_SCOPE, label: 'Project', assets: global.ok ? global.value : [] },
+    ]);
+  }, [docId]);
+
+  useEffect(() => {
+    setGroups(null);
+    void load();
+    if (!import.meta.hot) return;
+    const handler = () => void load();
+    import.meta.hot.on('mosage:files-changed', handler);
+    return () => {
+      import.meta.hot?.off('mosage:files-changed', handler);
+    };
+  }, [load]);
+
+  const copyImport = async (asset: Asset) => {
+    try {
+      await navigator.clipboard.writeText(importSnippet(asset));
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1200);
+    } catch {}
+  };
+
+  if (groups === null) {
+    return (
+      <div className="grid flex-1 place-items-center">
+        <Loader2 className="size-4 animate-spin text-muted-foreground" />
+      </div>
+    );
+  }
+
+  const empty = groups.every((group) => group.assets.length === 0);
+
+  return (
+    <div className="flex-1 overflow-y-auto px-3 pb-6">
+      {empty && (
+        <p className="px-1 py-2 text-muted-foreground text-xs leading-relaxed">
+          No assets yet. Drop files into <code className="font-mono">docs/{docId}/assets/</code> or
+          upload them from the Assets page.
+        </p>
+      )}
+
+      {groups.map((group) =>
+        group.assets.length === 0 ? null : (
+          <section key={group.scope} className="mb-4">
+            <h3 className="mb-1.5 px-1 text-[10px] text-muted-foreground uppercase tracking-wider">
+              {group.label}
+            </h3>
+            <div className="grid grid-cols-2 gap-1.5">
+              {group.assets.map((asset) => (
+                <button
+                  key={`${group.scope}/${asset.name}`}
+                  type="button"
+                  title={asset.name}
+                  onClick={() => setSelected(asset)}
+                  className={cn(
+                    'grid h-16 place-items-center overflow-hidden rounded border bg-muted p-1 transition-colors',
+                    selected?.url === asset.url
+                      ? 'border-foreground'
+                      : 'border-border hover:border-foreground/40',
+                  )}
+                >
+                  {isPreviewable(asset.mime) ? (
+                    <img
+                      src={asset.url}
+                      alt={asset.name}
+                      className="max-h-full max-w-full object-contain"
+                    />
+                  ) : (
+                    <FileIcon className="size-4 text-muted-foreground" />
+                  )}
+                </button>
+              ))}
+            </div>
+          </section>
+        ),
+      )}
+
+      {selected && (
+        <div className="sticky bottom-0 rounded-md border border-border bg-background p-2">
+          <p className="truncate font-medium text-[11px]">{selected.name}</p>
+          <p className="mt-0.5 text-[10px] text-muted-foreground">
+            {formatBytes(selected.size)}
+            {selected.unused ? ' · unused' : ''}
+          </p>
+          <code className="mt-1.5 block truncate rounded bg-muted px-1.5 py-1 font-mono text-[10px]">
+            {selected.importPath}
+          </code>
+          <button
+            type="button"
+            onClick={() => copyImport(selected)}
+            className="mt-1.5 flex w-full items-center justify-center gap-1 rounded border border-border px-2 py-1 text-[11px] transition-colors hover:bg-accent"
+          >
+            {copied ? <Check className="size-3" /> : <Copy className="size-3" />}
+            {copied ? 'Copied' : 'Copy import'}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/app/components/doc-search.tsx

@@ -0,0 +1,248 @@
+/**
+ * Find text in the document.
+ *
+ * Matches are drawn with the CSS Custom Highlight API, which paints ranges held
+ * beside the DOM instead of wrapping anything in it. Wrapping would mean editing
+ * a tree React owns: the next render throws the marks away, or keeps them and
+ * loses the reader's place. Neither is recoverable from inside a highlighter.
+ *
+ * A browser without the API still gets working navigation — the view scrolls to
+ * each hit — it just cannot tint it. That is worth having; refusing to search at
+ * all because it cannot be coloured is not.
+ */
+
+import { ChevronDown, ChevronUp, Search, X } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+const ALL = 'od-search';
+const ACTIVE = 'od-search-active';
+
+type Hit = { range: Range; page: number };
+
+/* Case-insensitive, and accent-insensitive where the browser can be: a reader
+   searching for "resume" means the word, not the spelling with accents. Defined
+   outside the component so it is one function, not a new one every render —
+   which is also what stops it having to appear in a dependency list. */
+const fold = (value: string): string => value.normalize('NFKD').toLowerCase();
+
+const highlightsSupported = (): boolean =>
+  typeof CSS !== 'undefined' && 'highlights' in CSS && typeof Highlight !== 'undefined';
+
+function clearHighlights(): void {
+  if (!highlightsSupported()) return;
+  CSS.highlights.delete(ALL);
+  CSS.highlights.delete(ACTIVE);
+}
+
+/**
+ * Every text node under `root`, in document order.
+ *
+ * Script and style hold text that is not the document's text; matching inside
+ * them would send the reader to a hit they cannot see.
+ */
+function textNodes(root: HTMLElement): Text[] {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+    acceptNode(node) {
+      const parent = node.parentElement;
+      if (!parent) return NodeFilter.FILTER_REJECT;
+      if (parent.closest('script,style,[data-od-search-skip]')) return NodeFilter.FILTER_REJECT;
+      return node.nodeValue?.trim() ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT;
+    },
+  });
+  const out: Text[] = [];
+  let node = walker.nextNode();
+  while (node) {
+    out.push(node as Text);
+    node = walker.nextNode();
+  }
+  return out;
+}
+
+function pageOf(node: Node, frames: Element[]): number {
+  const element = node.parentElement;
+  if (!element) return 0;
+  for (let i = 0; i < frames.length; i++) {
+    if (frames[i]?.contains(element)) return i + 1;
+  }
+  return 0;
+}
+
+export function DocSearch({
+  scrollRef,
+  pagesRef,
+  onFoundPage,
+}: {
+  scrollRef: React.RefObject<HTMLElement | null>;
+  pagesRef: React.RefObject<HTMLElement | null>;
+  onFoundPage?: (page: number) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const [hits, setHits] = useState<Hit[]>([]);
+  const [at, setAt] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const supported = useMemo(highlightsSupported, []);
+
+  const search = useCallback(
+    (text: string) => {
+      const root = pagesRef.current;
+      if (!root || text.trim() === '') {
+        clearHighlights();
+        setHits([]);
+        setAt(0);
+        return;
+      }
+
+      const needle = fold(text);
+      const frames = Array.from(root.children);
+      const found: Hit[] = [];
+
+      for (const node of textNodes(root)) {
+        const haystack = fold(node.nodeValue ?? '');
+        let from = haystack.indexOf(needle);
+        while (from !== -1) {
+          const range = document.createRange();
+          try {
+            range.setStart(node, from);
+            range.setEnd(node, from + needle.length);
+            found.push({ range, page: pageOf(node, frames) });
+          } catch {
+            /* Folding can change length, which puts the offset past the node.
+               Skipping that hit is better than throwing away the whole search. */
+          }
+          from = haystack.indexOf(needle, from + needle.length);
+        }
+      }
+
+      setHits(found);
+      setAt(found.length > 0 ? 1 : 0);
+    },
+    [pagesRef],
+  );
+
+  /* Painting is a side effect of the hits and the cursor, not of typing —
+     otherwise the active hit stays tinted after the reader moves off it. */
+  useEffect(() => {
+    if (!supported) return;
+    if (hits.length === 0) {
+      clearHighlights();
+      return;
+    }
+    const active = hits[at - 1];
+    CSS.highlights.set(ALL, new Highlight(...hits.map((hit) => hit.range)));
+    if (active) CSS.highlights.set(ACTIVE, new Highlight(active.range));
+    return clearHighlights;
+  }, [hits, at, supported]);
+
+  const go = useCallback(
+    (step: number) => {
+      if (hits.length === 0) return;
+      const next = ((at - 1 + step + hits.length) % hits.length) + 1;
+      setAt(next);
+      const hit = hits[next - 1];
+      if (!hit) return;
+      const target = hit.range.startContainer.parentElement;
+      const root = scrollRef.current;
+      if (target && root) {
+        const offset = target.getBoundingClientRect().top - root.getBoundingClientRect().top;
+        root.scrollTo({ top: root.scrollTop + offset - 120, behavior: 'smooth' });
+      }
+      if (hit.page > 0) onFoundPage?.(hit.page);
+    },
+    [at, hits, scrollRef, onFoundPage],
+  );
+
+  const close = useCallback(() => {
+    setOpen(false);
+    setQuery('');
+    clearHighlights();
+    setHits([]);
+    setAt(0);
+  }, []);
+
+  /* No ⌘F: that is the browser's own find, and taking it would replace a
+     control the reader already trusts with one that only searches this pane. */
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') close();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [open, close]);
+
+  useEffect(() => () => clearHighlights(), []);
+
+  if (!open) {
+    return (
+      <button
+        type="button"
+        aria-label="Find in document"
+        title="Find in document"
+        onClick={() => {
+          setOpen(true);
+          requestAnimationFrame(() => inputRef.current?.focus());
+        }}
+        className="flex size-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+      >
+        <Search className="size-3.5" />
+      </button>
+    );
+  }
+
+  return (
+    <div className="flex items-center gap-1 rounded-md border border-border px-1.5 py-0.5 focus-within:border-foreground/40">
+      <Search className="size-3.5 flex-none text-muted-foreground" />
+      <input
+        ref={inputRef}
+        value={query}
+        onChange={(event) => {
+          setQuery(event.target.value);
+          search(event.target.value);
+        }}
+        onKeyDown={(event) => {
+          if (event.key === 'Enter') {
+            event.preventDefault();
+            go(event.shiftKey ? -1 : 1);
+          }
+        }}
+        placeholder="Find"
+        aria-label="Find in document"
+        className="w-28 bg-transparent text-xs outline-none placeholder:text-muted-foreground"
+      />
+      <span className="flex-none font-mono text-[11px] text-muted-foreground tabular-nums">
+        {query === '' ? '' : hits.length === 0 ? '0' : `${at}/${hits.length}`}
+      </span>
+      <button
+        type="button"
+        aria-label="Previous match"
+        title="Previous match (⇧⏎)"
+        onClick={() => go(-1)}
+        disabled={hits.length === 0}
+        className="flex size-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:opacity-40"
+      >
+        <ChevronUp className="size-3.5" />
+      </button>
+      <button
+        type="button"
+        aria-label="Next match"
+        title="Next match (⏎)"
+        onClick={() => go(1)}
+        disabled={hits.length === 0}
+        className="flex size-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:opacity-40"
+      >
+        <ChevronDown className="size-3.5" />
+      </button>
+      <button
+        type="button"
+        aria-label="Close search"
+        title="Close search (Esc)"
+        onClick={close}
+        className="flex size-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+      >
+        <X className="size-3.5" />
+      </button>
+    </div>
+  );
+}

package/src/app/components/doc-sidebar.tsx

@@ -0,0 +1,162 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { DesignSystem } from '../lib/design';
+import type { OutlineEntry } from '../lib/outline';
+import type { PageGeometry } from '../lib/sdk';
+import type { ExpandedPage } from '../lib/use-doc-pages';
+import { cn } from '../lib/utils';
+import { DocAssets } from './doc-assets';
+import { PageFrame } from './page-frame';
+
+const THUMB_WIDTH = 116;
+
+type Tab = 'pages' | 'outline' | 'assets';
+
+type Props = {
+  docId: string;
+  pages: ExpandedPage[];
+  geometry: PageGeometry;
+  design?: DesignSystem;
+  currentPage: number;
+  entries: OutlineEntry[];
+  activeId: string | null;
+  onSelectPage: (page: number) => void;
+  onSelectEntry: (entry: OutlineEntry) => void;
+};
+
+export function DocSidebar({
+  docId,
+  pages,
+  geometry,
+  design,
+  currentPage,
+  entries,
+  activeId,
+  onSelectPage,
+  onSelectEntry,
+}: Props) {
+  const [tab, setTab] = useState<Tab>('pages');
+  const railRef = useRef<HTMLDivElement>(null);
+  // The assets panel talks to the dev API, so it has nothing to show in a
+  // static build.
+  const tabs = useMemo<Tab[]>(
+    () => (import.meta.env.DEV ? ['pages', 'outline', 'assets'] : ['pages', 'outline']),
+    [],
+  );
+
+  // Follow the reader: keep the active thumbnail in view as the main pane scrolls.
+  useEffect(() => {
+    if (tab !== 'pages') return;
+    const rail = railRef.current;
+    const active = rail?.querySelector<HTMLElement>(`[data-thumb-page="${currentPage}"]`);
+    if (!rail || !active) return;
+    const top = active.offsetTop;
+    const bottom = top + active.offsetHeight;
+    if (top < rail.scrollTop || bottom > rail.scrollTop + rail.clientHeight) {
+      rail.scrollTo({ top: top - rail.clientHeight / 3, behavior: 'smooth' });
+    }
+  }, [currentPage, tab]);
+
+  return (
+    <aside className="hidden w-56 flex-none flex-col border-border border-r bg-background md:flex">
+      <div className="flex flex-none gap-1 p-2">
+        {tabs.map((value) => (
+          <button
+            key={value}
+            type="button"
+            onClick={() => setTab(value)}
+            className={cn(
+              'flex-1 rounded-md px-2 py-1 text-[11px] capitalize transition-colors',
+              tab === value
+                ? 'bg-accent font-medium text-foreground'
+                : 'text-muted-foreground hover:bg-accent/60',
+            )}
+          >
+            {value}
+          </button>
+        ))}
+      </div>
+
+      {tab === 'assets' ? (
+        <DocAssets docId={docId} />
+      ) : tab === 'pages' ? (
+        <div ref={railRef} className="flex-1 overflow-y-auto px-3 pb-6">
+          <div className="flex flex-col items-center gap-3">
+            {pages.map((entry, index) => {
+              const page = index + 1;
+              return (
+                <button
+                  key={entry.key}
+                  type="button"
+                  data-thumb-page={page}
+                  onClick={() => onSelectPage(page)}
+                  className="flex flex-col items-center gap-1"
+                >
+                  <div
+                    className={cn(
+                      'overflow-hidden rounded-sm ring-1 transition-shadow',
+                      page === currentPage
+                        ? 'ring-2 ring-foreground'
+                        : 'ring-border hover:ring-foreground/40',
+                    )}
+                    style={{
+                      width: THUMB_WIDTH,
+                      height: geometry.height * (THUMB_WIDTH / geometry.width),
+                    }}
+                  >
+                    <PageFrame
+                      index={index}
+                      total={pages.length}
+                      geometry={geometry}
+                      scale={THUMB_WIDTH / geometry.width}
+                      design={design}
+                      flat
+                    >
+                      {entry.content}
+                    </PageFrame>
+                  </div>
+                  <span
+                    className={cn(
+                      'font-mono text-[10px] tabular-nums',
+                      page === currentPage ? 'text-foreground' : 'text-muted-foreground',
+                    )}
+                  >
+                    {page}
+                  </span>
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      ) : (
+        <nav className="flex-1 overflow-y-auto px-2 pb-6">
+          {entries.length === 0 ? (
+            <p className="px-2 py-1 text-muted-foreground text-xs leading-relaxed">
+              No headings yet. Add an <code className="font-mono">h1</code>/
+              <code className="font-mono">h2</code> to a page and it shows up here.
+            </p>
+          ) : (
+            entries.map((entry) => (
+              <button
+                key={entry.id}
+                type="button"
+                onClick={() => onSelectEntry(entry)}
+                className={cn(
+                  'flex w-full items-baseline gap-2 rounded-md px-2 py-1.5 text-left text-[13px] transition-colors hover:bg-accent',
+                  entry.id === activeId
+                    ? 'bg-accent font-medium text-foreground'
+                    : 'text-muted-foreground',
+                )}
+                style={{ paddingLeft: 8 + (entry.level - 1) * 12 }}
+              >
+                <span className="line-clamp-2 flex-1">{entry.text}</span>
+                <span className="font-mono text-[10px] text-muted-foreground tabular-nums">
+                  {entry.page}
+                </span>
+              </button>
+            ))
+          )}
+        </nav>
+      )}
+    </aside>
+  );
+}