seemore 1.1.5 → 1.2.0

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { z } from 'zod';
  * Types shared by the node pipeline and the browser app. This file ships as source, next to
  * `src/app`, so both halves agree on the shape of the virtual modules.
  */
-declare const FEATURES: readonly ["navigation.instant.prefetch", "navigation.instant.preview", "navigation.footer", "navigation.top", "navigation.path", "navigation.sections", "navigation.prune", "toc.follow", "toc.integrate", "content.code.copy", "content.action.edit", "content.image.zoom", "search.suggest", "search.highlight", "social.cards"];
+declare const FEATURES: readonly ["navigation.instant.prefetch", "navigation.instant.preview", "navigation.footer", "navigation.top", "navigation.path", "navigation.sections", "navigation.prune", "toc.follow", "toc.integrate", "content.code.copy", "content.action.edit", "content.edit", "content.image.zoom", "search.suggest", "search.highlight", "social.cards"];
 type Feature = (typeof FEATURES)[number];
 /** What a user may write in `features`: a flag, or `!flag` to switch a default-on flag off. */
 type FeatureFlag = Feature | `!${Feature}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seemore",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "Let AI write the Markdown. Let seemore show it better — zero config documentation framework.",
   "license": "MIT",
   "type": "module",

package/src/app/features/edit.tsx

@@ -0,0 +1,285 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { RouteEntry } from '../../shared/types.js';
+
+/**
+ * Editing a block of a page from the browser.
+ *
+ * What is edited is the block's **Markdown source**, not its rendered HTML. A rehype plugin
+ * stamped every editable block with its `start:end` offsets into the file, so a save replaces
+ * exactly those characters and every other byte of the file is left alone — no HTML-to-
+ * Markdown round trip to mangle a table, a fence or a link reference, and no whole-file
+ * reflow in the diff.
+ *
+ * Nothing here re-renders the page. The dev server writes the file, the watcher notices, and
+ * the page hot-reloads through the same path an edit made in an editor takes.
+ */
+
+const ENDPOINT = '/__seemore/source';
+
+interface Editing {
+  element: HTMLElement;
+  start: number;
+  end: number;
+  /**
+   * The slice exactly as the server sent it, kept out of the DOM.
+   *
+   * A textarea reports its value with `\n` whatever was put into it, so a CRLF file's block
+   * cannot be compared against the copy that came back through the editor. This is the copy
+   * the server checks the file against.
+   */
+  original: string;
+  top: number;
+  left: number;
+  width: number;
+}
+
+export function InlineEditor({ entry }: { entry: RouteEntry }) {
+  const layer = useRef<HTMLDivElement | null>(null);
+  const textarea = useRef<HTMLTextAreaElement | null>(null);
+  const [editing, setEditing] = useState<Editing | undefined>(undefined);
+  /** Read inside the dblclick listener, which is bound once and would capture stale state. */
+  const editingRef = useRef<Editing | undefined>(undefined);
+  const [error, setError] = useState<string | undefined>(undefined);
+  const [saving, setSaving] = useState(false);
+  /**
+   * Set when a save was refused, which in practice means the file moved under the offsets
+   * this editor is holding. It disarms the automatic save-on-blur: the text on screen is
+   * stale by definition, and leaving blur armed means a later click — or navigating away —
+   * silently commits it the moment the file happens to match `original` again.
+   */
+  const [refused, setRefused] = useState(false);
+
+  const close = useCallback(() => {
+    setEditing((current) => {
+      current?.element.classList.remove('seemore-editing');
+      return undefined;
+    });
+    setError(undefined);
+    setRefused(false);
+  }, []);
+
+  // The article is this layer's own parent, so there is no ref to thread down from the layout.
+  const article = () => layer.current?.parentElement ?? undefined;
+
+  useEffect(() => {
+    const host = article();
+    if (host === undefined) return;
+
+    const onDoubleClick = (event: MouseEvent) => {
+      const target = event.target as HTMLElement | null;
+      if (target === null) return;
+      // A link would have navigated on the first of the two clicks. Leave it alone; the rest
+      // of the paragraph around it still opens the editor.
+      if (target.closest('a') !== null) return;
+
+      const block = target.closest<HTMLElement>('[data-seemore-pos]');
+      if (block === null || !host.contains(block)) return;
+
+      // An editor is already open. Moving to another block is fine while nothing has been
+      // typed, but with unsaved text it would discard the edit without asking — so leave it
+      // where it is and let Save or Cancel decide.
+      const field = textarea.current;
+      if (field !== null && editingRef.current !== undefined) {
+        const original = editingRef.current.original;
+        if (field.value.replace(/\r\n/g, '\n') !== original.replace(/\r\n/g, '\n')) return;
+      }
+
+      const [start, end] = (block.dataset['seemorePos'] ?? '').split(':').map(Number);
+      if (!Number.isInteger(start) || !Number.isInteger(end)) return;
+
+      event.preventDefault();
+      void open(block, start as number, end as number);
+    };
+
+    const open = async (block: HTMLElement, start: number, end: number) => {
+      const query = new URLSearchParams({ file: entry.absPath, start: String(start), end: String(end) });
+      let original: string;
+      try {
+        const response = await fetch(`${ENDPOINT}?${query.toString()}`);
+        const body = (await response.json()) as { text?: string; error?: string };
+        if (!response.ok || typeof body.text !== 'string') {
+          setError(body.error ?? 'Could not read this block from the file.');
+          return;
+        }
+        original = body.text;
+      } catch {
+        setError('Could not reach the dev server.');
+        return;
+      }
+
+      // Measured against the article, which is the positioning context of the layer.
+      const host = article();
+      if (host === undefined) return;
+      const bounds = host.getBoundingClientRect();
+      const rect = block.getBoundingClientRect();
+
+      block.classList.add('seemore-editing');
+      setError(undefined);
+      setRefused(false);
+      setEditing({
+        element: block,
+        start,
+        end,
+        original,
+        top: rect.top - bounds.top,
+        left: rect.left - bounds.left,
+        width: rect.width,
+      });
+    };
+
+    host.addEventListener('dblclick', onDoubleClick);
+    return () => host.removeEventListener('dblclick', onDoubleClick);
+  }, [entry.absPath]);
+
+  useEffect(() => {
+    editingRef.current = editing;
+  }, [editing]);
+
+  // The block is hidden rather than removed while it is edited, so the page does not jump.
+  // If this component goes away mid-edit — a navigation, a hot reload — put it back.
+  useEffect(() => () => editing?.element.classList.remove('seemore-editing'), [editing]);
+
+  const save = useCallback(async () => {
+    const current = editing;
+    const field = textarea.current;
+    if (current === undefined || field === null || saving || refused) return;
+
+    // Both sides normalised: a textarea reports `\n` even for the `\r\n` a CRLF file gave it,
+    // so comparing raw would make every no-op edit on Windows look like a change and rewrite
+    // the file — same bytes, but a fresh mtime and a pointless reload.
+    if (field.value.replace(/\r\n/g, '\n') === current.original.replace(/\r\n/g, '\n')) {
+      close();
+      return;
+    }
+
+    setSaving(true);
+    try {
+      const response = await fetch(ENDPOINT, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          file: entry.absPath,
+          start: current.start,
+          end: current.end,
+          expected: current.original,
+          text: field.value,
+        }),
+      });
+      if (!response.ok) {
+        const body = (await response.json().catch(() => ({}))) as { error?: string };
+        setError(body.error ?? 'The edit could not be saved.');
+        setRefused(true);
+        return;
+      }
+      // The watcher takes it from here: the file changed, so the page reloads its own module.
+      close();
+    } catch {
+      setError('Could not reach the dev server.');
+      setRefused(true);
+    } finally {
+      setSaving(false);
+    }
+  }, [editing, entry.absPath, close, saving, refused]);
+
+  return (
+    <div className="seemore-editor-layer" ref={layer}>
+      {editing === undefined ? undefined : (
+        <div
+          className="seemore-editor"
+          // `nearest` scrolls only when the box does not already fit, so opening an editor on
+          // a block that is comfortably in view does not move the page under the reader.
+          ref={(node) => node?.scrollIntoView({ block: 'nearest' })}
+          style={{ top: editing.top, left: editing.left, width: editing.width }}
+        >
+          <textarea
+            ref={(node) => {
+              textarea.current = node;
+              if (node === null) return;
+              node.focus();
+              node.setSelectionRange(node.value.length, node.value.length);
+              resize(node);
+              requestAnimationFrame(() => resize(node));
+            }}
+            className="seemore-editor-input"
+            // One row, so `height: auto` in `resize` collapses to the content rather than to
+            // the two-row default a textarea otherwise floors itself at.
+            rows={1}
+            defaultValue={editing.original}
+            spellCheck={false}
+            disabled={saving}
+            onInput={(event) => resize(event.currentTarget)}
+            onKeyDown={(event) => {
+              if (event.key === 'Escape') {
+                event.preventDefault();
+                close();
+                return;
+              }
+              // `metaKey` on macOS, `ctrlKey` everywhere else — accept either rather than
+              // sniffing the platform.
+              if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+                event.preventDefault();
+                void save();
+              }
+            }}
+          />
+          <div className="seemore-editor-actions">
+            <span className="seemore-editor-status">
+              {saving ? 'Saving…' : refused ? 'Not saved — copy your text, then reload the page' : undefined}
+            </span>
+            {/*
+              `onMouseDown` is prevented on both buttons so focus never leaves the textarea.
+              Taking focus would fire its blur handler, which saves — so a click on Cancel
+              would commit the very edit it is meant to discard.
+            */}
+            <button
+              type="button"
+              className="seemore-editor-button"
+              onMouseDown={(event) => event.preventDefault()}
+              onClick={close}
+            >
+              Cancel
+            </button>
+            <button
+              type="button"
+              className="seemore-editor-button seemore-editor-button-primary"
+              onMouseDown={(event) => event.preventDefault()}
+              onClick={() => void save()}
+              disabled={saving || refused}
+            >
+              Save
+            </button>
+          </div>
+        </div>
+      )}
+
+      {error === undefined ? undefined : (
+        <p
+          className="seemore-editor-error"
+          role="alert"
+          title="Dismiss"
+          onClick={() => setError(undefined)}
+        >
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Grow with the content: the Markdown behind a block is rarely the height of the block.
+ *
+ * Capped at part of the window, because a block whose source runs longer than the viewport
+ * would otherwise push Save and Cancel off the bottom of the screen. Past the cap the
+ * textarea scrolls inside itself and the action bar stays put.
+ */
+function resize(node: HTMLTextAreaElement): void {
+  const cap = Math.max(MIN_EDITOR_HEIGHT, Math.round(window.innerHeight * 0.55));
+  node.style.height = 'auto';
+  const wanted = node.scrollHeight;
+  node.style.height = `${Math.min(wanted, cap)}px`;
+  node.style.overflowY = wanted > cap ? 'auto' : 'hidden';
+}
+
+/** Floor for the cap, so a very short window still shows a usable amount of text. */
+const MIN_EDITOR_HEIGHT = 160;

package/src/app/index.html

@@ -4,8 +4,11 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <!-- Default icon so a zero-config folder does not 404 on /favicon.ico. A favicon from
-         the config is injected at the marker below, after this link, and the last one wins. -->
-    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%236D5EF5'/%3E%3Cpath d='M10 11h12M10 16h12M10 21h7' stroke='%23f5f5f5' stroke-width='2.5' stroke-linecap='round'/%3E%3C/svg%3E" />
+         the config is injected at the marker below, after this link, and the last one wins.
+         This is seemore's own mark, inlined from assets/icon.svg at the repo root — the same
+         artwork the editor extension ships as its icon. Inlined rather than linked so the
+         built site needs no extra request and no file in the user's folder. -->
+    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 128 128'%3E%3Crect width='128' height='128' rx='28' fill='%236D5EF5'/%3E%3Crect x='30' y='26' width='52' height='68' rx='8' fill='%23ffffff' opacity='0.35' transform='rotate(-8 56 60)'/%3E%3Crect x='38' y='22' width='52' height='68' rx='8' fill='%23ffffff' opacity='0.6' transform='rotate(-3 64 56)'/%3E%3Crect x='46' y='24' width='52' height='72' rx='8' fill='%23ffffff'/%3E%3Cg stroke-linecap='round'%3E%3Cline x1='56' y1='42' x2='82' y2='42' stroke='%236D5EF5' stroke-width='6'/%3E%3Cline x1='56' y1='56' x2='88' y2='56' stroke='%23C6C8E6' stroke-width='4'/%3E%3Cline x1='56' y1='66' x2='80' y2='66' stroke='%23C6C8E6' stroke-width='4'/%3E%3Cline x1='56' y1='76' x2='88' y2='76' stroke='%236D5EF5' stroke-width='4'/%3E%3Cline x1='56' y1='86' x2='74' y2='86' stroke='%23C6C8E6' stroke-width='4'/%3E%3C/g%3E%3C/svg%3E" />
     <!--seemore-head-->
   </head>
   <body>

package/src/app/layout/DocsLayout.tsx

@@ -13,6 +13,7 @@ import { usePrefetch } from '../features/prefetch.js';
 import { PagePreview } from '../features/preview.js';
 import { useSearchHighlight } from '../features/highlight.js';
 import { useHashScroll } from '../features/anchors.js';
+import { InlineEditor } from '../features/edit.js';
 import { SeemoreProvider } from './Provider.js';
 import { Header } from './Header.js';
 import { Sidebar } from './Sidebar.js';
@@ -52,6 +53,9 @@ export function DocPage({ entry }: { entry: RouteEntry }) {
   useHashScroll();
 
   const integrated = feature('toc.integrate');
+  // Dev only, and off unless asked for: the editor writes to the user's files, and a static
+  // build has no server to write through. `import.meta.env.DEV` also keeps it out of the bundle.
+  const editable = import.meta.env.DEV && feature('content.edit');
 
   return (
     <TocProvider toc={page.toc ?? []}>
@@ -62,8 +66,9 @@ export function DocPage({ entry }: { entry: RouteEntry }) {
 
           <main className="seemore-main">
             {feature('navigation.path') ? <Breadcrumb /> : undefined}
-            <article className="seemore-article prose">
+            <article className={editable ? 'seemore-article prose seemore-editable' : 'seemore-article prose'}>
               <Content components={mdxComponents} />
+              {editable ? <InlineEditor key={entry.url} entry={entry} /> : undefined}
             </article>
 
             {config.editLink !== undefined && feature('content.action.edit') ? (

package/src/app/styles/globals.css

@@ -292,6 +292,70 @@
     @apply my-6 rounded-lg border border-fd-border p-4 text-sm text-fd-muted-foreground;
   }
 
+  /* Inline editing (dev only, `content.edit`). The article is the positioning context for
+     the editor layer, which sits over the block being edited. */
+  .seemore-editable {
+    @apply relative;
+  }
+
+  .seemore-editable [data-seemore-pos]:hover {
+    @apply cursor-text rounded-sm bg-fd-muted/40;
+    box-shadow: 0 0 0 4px var(--color-fd-muted);
+  }
+
+  .seemore-editable .seemore-editing {
+    @apply invisible;
+  }
+
+  .seemore-editor-layer {
+    @apply pointer-events-none absolute inset-0;
+  }
+
+  /* `scroll-mt-20` clears the sticky header: without it, scrolling a tall editor into view
+     tucks its first lines underneath the header bar. */
+  .seemore-editor {
+    @apply pointer-events-auto absolute z-20 scroll-mt-20 rounded-lg border border-fd-primary/40 bg-fd-background shadow-lg;
+  }
+
+  .seemore-editor-input {
+    @apply block w-full resize-none bg-transparent p-3 font-mono text-sm leading-relaxed text-fd-foreground outline-none;
+  }
+
+  .seemore-editor-actions {
+    @apply flex items-center justify-end gap-2 border-t border-fd-border px-2.5 py-2;
+  }
+
+  .seemore-editor-status {
+    @apply me-auto ps-0.5 text-xs text-fd-muted-foreground;
+  }
+
+  .seemore-editor-button {
+    @apply rounded-md border border-fd-border px-3 py-1 text-xs font-medium text-fd-foreground transition-colors;
+  }
+
+  .seemore-editor-button:hover:not(:disabled) {
+    @apply bg-fd-accent text-fd-accent-foreground;
+  }
+
+  .seemore-editor-button:disabled {
+    @apply cursor-not-allowed opacity-50;
+  }
+
+  .seemore-editor-button-primary {
+    @apply border-transparent bg-fd-primary text-fd-primary-foreground;
+  }
+
+  .seemore-editor-button-primary:hover:not(:disabled) {
+    @apply bg-fd-primary/90 text-fd-primary-foreground;
+  }
+
+  /* Anchored to the viewport, not to the layer: the layer is `absolute inset-0` over the
+     article, so a `sticky` child of it renders at the article's top and lands on the
+     heading. A conflict is rare and worth reading, so it sits out of the content's way. */
+  .seemore-editor-error {
+    @apply pointer-events-auto fixed bottom-6 left-1/2 z-50 max-w-[min(32rem,calc(100vw-2rem))] -translate-x-1/2 cursor-pointer rounded-lg border border-fd-border bg-fd-background px-4 py-2.5 text-sm text-fd-foreground shadow-xl;
+  }
+
   .seemore-pdf {
     @apply my-6 block;
   }

package/src/shared/types.ts

@@ -17,6 +17,7 @@ export const FEATURES = [
   'toc.integrate',
   'content.code.copy',
   'content.action.edit',
+  'content.edit',
   'content.image.zoom',
   'search.suggest',
   'search.highlight',