seemore 1.1.5 → 1.2.0

package/README.md

@@ -1,7 +1,7 @@
 <br/>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/vscode/assets/icon.png" alt="seemore" width="40" height="40">
+  <img src="https://raw.githubusercontent.com/arifszn/seemore/main/assets/icon.png" alt="seemore" width="40" height="40">
   <h1 align="center">seemore</h1>
   <h4 align="center">Let AI write the Markdown. Let seemore show it better — zero config documentation framework.</h4>
   <p align="center">
@@ -42,11 +42,9 @@
   </p>
 </p>
 
-AI tools write Markdown — specs, notes, guides, READMEs, whole folders of it, faster than
-anyone can read. A pile of `.md` files is write-only memory: nothing to click, nothing to
-search, no order.
+AI tools write Markdown — specs, notes, guides, READMEs, whole folders of it, faster than anyone can read. A pile of `.md` files is write-only memory: nothing to click, nothing to search, no order.
 
-seemore points at that folder and renders it as a proper site instead, without you moving a single file or writing any code.
+**seemore** points at that folder and renders it as a proper site instead, without you moving a single file or writing any code.
 
 Three ways to use it:
 
@@ -54,26 +52,39 @@ Three ways to use it:
 - **[In your code editor](#view-in-your-code-editor)**: an extension puts the same site in a panel next to the file you're editing — VS Code and VS Code-compatible editors like Cursor and Antigravity.
 - **[As a static site](#publish-it-to-the-web)**: `npx seemore build` exports plain HTML you can host anywhere, so it doubles as a docs framework, not just a preview tool.
 
+And whichever preview is open, the page is also an editor: **double-click any paragraph to fix its Markdown in place**, and the change is written straight back to the file.
+
 <p align="center">
-  <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/site/assets/themes/neutral.png" alt="seemore rendering a folder of Markdown in the browser, neutral theme" width="640"/>
+  <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/site/assets/inline-editor.png" alt="seemore rendering a folder of Markdown in the browser, with a paragraph's Markdown source open in the inline editor" width="640"/>
 </p>
 
+## Features
+
+- **Zero config** — no config file, no code, no files to move; a plain folder of Markdown works in the browser, in your editor, and as a static build
+- **Live preview** — add, rename, retitle or delete a file and the site updates immediately, navigation and search included
+- **Edit in place** — double-click any block in the preview to fix its Markdown; saves are surgical, so `git diff` shows the sentence you changed and nothing else
+- **Static export** — `seemore build` prerenders every page to its own HTML file, `404.html` included, and adds the conventions individual hosts look for (`_redirects`, `200.html`, `.nojekyll`)
+- **Search built in** — static, zero-setup full-text search out of the box, with shareable highlighted results; [Algolia](https://algolia.com) and [Orama Cloud](https://orama.com) for hosted indexes
+- **12 themes** — dark and light follow the system, with a toggle that remembers your choice; your own CSS always wins
+- **Rich Markdown** — GitHub Flavoured Markdown, admonitions, steps, `[[wikilinks]]`, [Mermaid](https://mermaid.js.org) and [D2](https://d2lang.com) diagrams, click-to-zoom images, embedded PDFs
+- **First-class code blocks** — build-time [Shiki](https://shiki.style) highlighting in the theme's own colours, with titles, line numbers, diff markers and focus
+- **MDX components** — `<Callout>`, `<Card>`, `<CodeBlockTabs>` and friends, with no imports to write
+- **Editor integration** — one extension covers VS Code, Cursor, Antigravity and other VS Code-compatible editors, remote workspaces included
+
 ## View in your browser
 
 ```bash
 npx seemore     # view the current folder in your browser, live, no setup
 ```
 
-Open a terminal in your folder of Markdown files, run `npx seemore`, and open the address it prints (`http://localhost:4040` by default). From there it's live: add, rename, retitle or delete a file and the site updates immediately, navigation included.
-
-With no folder given, seemore serves the folder you're standing in. Point it at a subfolder with `npx seemore docs` if that's where your files live.
+Run it in your folder of Markdown files (Node.js 20 or newer) and open the address it prints — `http://localhost:4040` by default. From there it's live: add, rename, retitle or delete a file and the site updates immediately. Point it at a subfolder with `npx seemore docs` if that's where your files live.
 
 ## View in your code editor
 
-Install seemore from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=arifszn.seemore-vscode) or [Open VSX](https://open-vsx.org/extension/arifszn/seemore-vscode) to get the same rendered site as a panel beside your editor. No terminal, no `npx`, no browser tab to manage. Open VSX also covers VS Code-compatible editors — Cursor, Antigravity, and others.
+Install **seemore** from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=arifszn.seemore-vscode) or [Open VSX](https://open-vsx.org/extension/arifszn/seemore-vscode) to get the same rendered site as a panel beside your editor — no terminal, no `npx`, no browser tab to manage. The extension bundles the CLI, so nothing is downloaded or put on your PATH. Open VSX also covers VS Code-compatible editors — Cursor, Antigravity, and others.
 
 1. Open any Markdown file.
-2. Click the seemore icon in the editor's title bar, or right-click a folder in the explorer and choose **Open Folder in seemore**.
+2. Click the **seemore** icon in the editor's title bar, or right-click a folder in the explorer and choose **Open Folder in seemore**.
 3. The rendered site opens beside your editor, scoped to that file's folder.
 
 ### Commands
@@ -88,27 +99,37 @@ Install seemore from the [VS Code Marketplace](https://marketplace.visualstudio.
 
 | Setting | Default | Effect |
 | --- | --- | --- |
-| `seemore.path` | *(bundled copy)* | Path to a `seemore` CLI entry point to use instead of the version bundled with the extension. Leave empty unless you're developing seemore itself. |
+| `seemore.path` | *(bundled copy)* | Path to a `seemore` CLI entry point to use instead of the version bundled with the extension. Leave empty unless you're developing **seemore** itself. |
 
-## Publish it to the web
+## Edit your files from the browser
 
-```bash
-npx seemore build  # static export to dist/ for any host
+The preview is not just for reading — it is the fastest way to fix what you are reading. Double-click any paragraph, heading, list item, quote or table cell and it opens in a small editor holding that block's **Markdown source**: `**bold**` stays `**bold**`, links stay links, tables stay tables. Fix the text and hit **Save** and the change is written to the file on disk. Nothing is written until you say so: clicking away leaves the editor open rather than saving behind your back. It works the same in the VS Code panel, which runs the same dev server.
+
+Inline editing is for local previews only — `seemore build` output is static, so nothing is emitted there. It is on by default in dev; switch it off with the `!` prefix:
+
+```ts
+export default defineConfig({
+  features: ['!content.edit'],
+});
 ```
 
-The result is a `dist/` folder of plain web files: drop it on [Netlify](https://netlify.com), [Surge](https://surge.sh), [Cloudflare Pages](https://pages.cloudflare.com) or [GitHub Pages](https://pages.github.com), or hand it to any web host.
+> [!NOTE]
+> The dev server binds to localhost, so only your machine can reach the endpoint that writes. If you serve the site to your network with `--host`, anyone who can open the site can also edit your files — pass `features: ['!content.edit']` when you do that.
 
-**On GitHub Pages:** project sites live under `username.github.io/my-repo/`, not the root, so set `base` once:
+## Publish it to the web
 
-```ts
-export default defineConfig({ base: '/my-repo/' });
+```bash
+npx seemore build  # static export to dist/ for any host
 ```
 
-(or `--base /my-repo/` on the CLI). Building under GitHub Actions without it set prints the exact line to add.
+The result is a `dist/` folder of plain web files: drop it on [Netlify](https://netlify.com), [Surge](https://surge.sh), [Cloudflare Pages](https://pages.cloudflare.com) or [GitHub Pages](https://pages.github.com), or hand it to any web host. Every page is prerendered to its own `index.html`, next to a `404.html` that every static host honours. On top of that, the small conventions individual hosts look for — `_redirects` for Netlify and Cloudflare Pages, `200.html` for Surge, `.nojekyll` for GitHub Pages — are written for you.
+
+> [!TIP]
+> Project sites on GitHub Pages live under `username.github.io/my-repo/`, not the root, so set `base` once: `defineConfig({ base: '/my-repo/' })` (or `--base /my-repo/` on the CLI). Building under GitHub Actions without it set prints the exact line to add.
 
 ## Configuration
 
-Optional. A folder with no config file builds correctly in the browser, in your code editor, and when built for publishing. If you want to adjust things, create `seemore.config.ts` next to your content:
+Optional — a folder with no config file builds correctly everywhere. To adjust things, create `seemore.config.ts` next to your content:
 
 ```ts
 // seemore.config.ts
@@ -130,6 +151,10 @@ export default defineConfig({
 });
 ```
 
+### Search
+
+The default `search: 'static'` needs no setup, no server and no account: the index is built from your Markdown and queried in the browser, in a Web Worker. `search.suggest` completes your query inline, and `search.highlight` carries the query onto the page you land on (`?h=…`), so search-result links are shareable. Hosted indexes are a drop-in swap whenever you want one: [Orama Cloud](https://orama.com) (`@orama/core`) or [Algolia](https://algolia.com) (`algoliasearch`), each needing nothing but its SDK installed.
+
 ### Themes
 
 Twelve built-in colour presets: `neutral` (default), `black`, `catppuccin`, `dusk`, `ocean`, `purple`, `ruby`, `solar`, `aspen`, `emerald`, `vitepress`, `shadcn`. For anything else, put your own CSS in `css`; it's appended last, so it wins. Dark and light follow your system setting, with a toggle that remembers your choice — `black` is built for dark mode, shown below with the toggle on.
@@ -160,7 +185,7 @@ Twelve built-in colour presets: `neutral` (default), `black`, `catppuccin`, `dus
 
 ### Features
 
-A flat list of switches for readers who want fine control, set as an array on the `features` key in `seemore.config.ts`. To turn on something that's off by default, add its flag name. To turn off something that's on by default, add its flag name prefixed with `!`.
+A flat list of switches for fine control, set as an array on the `features` key. Turn something on by adding its flag name, turn something off with the `!` prefix; flags you don't mention keep their default.
 
 ```ts
 // seemore.config.ts
@@ -172,8 +197,6 @@ export default defineConfig({
 });
 ```
 
-Flags you don't mention are left at their default, so you only ever list the ones you're changing.
-
 | Flag | Default | Effect |
 | --- | --- | --- |
 | `navigation.instant.prefetch` | on | Load the target page on hover |
@@ -187,6 +210,7 @@ Flags you don't mention are left at their default, so you only ever list the one
 | `toc.integrate` | off | Merge the table of contents into the sidebar |
 | `content.code.copy` | on | Copy button on code blocks |
 | `content.action.edit` | on with `editLink` | Edit-this-page link |
+| `content.edit` | on (dev only) | Double-click a block to edit its Markdown in place |
 | `content.image.zoom` | on | Click-to-zoom on content images |
 | `search.suggest` | on | Inline query completion |
 | `search.highlight` | on | Highlight the query on the page you land on |
@@ -202,8 +226,8 @@ Supports `.md` and `.mdx` both.
 - `[[wikilinks]]`, including `[[Page|label]]` and `[[Page#Heading]]`, the easiest way for you or your AI to link pages without relative paths to get right
 - Relative `.md` links are resolved to working links automatically
 - **[Mermaid](https://mermaid.js.org)** and **[D2](https://d2lang.com)** diagrams, both rendered live in the browser straight from a ` ```mermaid ` or ` ```d2 ` code fence
-- Sibling images inlined as hashed assets, sibling PDFs open in the browser's own viewer
-- Frontmatter (the `key: value` block at the top of a file) is validated, with errors that name the file and the field
+- Sibling images inlined as hashed assets with click-to-zoom, sibling PDFs open in the browser's own viewer
+- Frontmatter keys are validated
 
 ### Code blocks
 
@@ -230,7 +254,7 @@ The marker follows the language's own comment syntax, so `# [!code highlight]` i
 
 ### Components
 
-An `.mdx` file can use `<Callout>`, `<Card>`, `<Cards>`, `<CodeBlockTabs>`, `<Mermaid>`, `<D2>` and `<Pdf>` without importing anything. The set is deliberately small: Markdown has no imports, so every component is one seemore ships to every site whether it is used or not, and these are the ones that pair with something Markdown already expresses. Anything else — fumadocs' `<Tabs>`, `<Accordions>`, `<Files>` among them — fails the build, naming the file and the component. In a plain `.md` file a tag is not JSX at all: it is dropped and its text kept, so components need the `.mdx` extension. The [Content page](https://arifszn.github.io/seemore/content) has the details.
+An `.mdx` file can use `<Callout>`, `<Card>`, `<Cards>`, `<CodeBlockTabs>`, `<Mermaid>`, `<D2>` and `<Pdf>` without importing anything. Anything else fails the build, naming the file and the component. In a plain `.md` file a tag is not JSX at all: it is dropped and its text kept, so components need the `.mdx` extension. The [Content page](https://arifszn.github.io/seemore/content) has the full syntax for each.
 
 Numbered headings — `## 1. Install it`, `## 2. Point it at a folder` — become a numbered sequence.
 
@@ -244,8 +268,6 @@ Numbered headings — `## 1. Install it`, `## 2. Point it at a folder` — becom
 | `guide/index.md` | `/guide` |
 | `guide/Deep Dive.md` | `/guide/deep-dive` |
 
-Both `/guide` and `/guide/` work on every host.
-
 ### Ordering
 
 Pages are ordered by:

package/dist/cli/index.js

@@ -75,7 +75,7 @@ import { parseArgs } from "util";
 import pc4 from "picocolors";
 
 // src/cli/build.ts
-import { mkdirSync as mkdirSync3, mkdtempSync, readFileSync as readFileSync5, rmSync, writeFileSync as writeFileSync4 } from "fs";
+import { mkdirSync as mkdirSync3, mkdtempSync, readFileSync as readFileSync5, rmSync, writeFileSync as writeFileSync5 } from "fs";
 import { createRequire as createRequire3 } from "module";
 import { tmpdir as tmpdir2 } from "os";
 import { isAbsolute as isAbsolute2, join as join8, relative as relative2, resolve as resolve5 } from "path";
@@ -124,6 +124,7 @@ var FEATURES = [
   "toc.integrate",
   "content.code.copy",
   "content.action.edit",
+  "content.edit",
   "content.image.zoom",
   "search.suggest",
   "search.highlight",
@@ -144,6 +145,10 @@ var FEATURE_DEFAULTS = {
   "content.code.copy": true,
   // Implicitly on when `editLink` is configured; there is nothing to link to otherwise.
   "content.action.edit": false,
+  // On by default, but only ever active in dev: the stamping that makes a block editable is
+  // not emitted by `seemore build`, and the endpoint that writes is registered only by the
+  // dev server. Switch it off with '!content.edit'.
+  "content.edit": true,
   "content.image.zoom": true,
   "search.suggest": true,
   "search.highlight": true,
@@ -965,6 +970,22 @@ function virtualPath(contentRoot, file) {
   return toPosix(relative(contentRoot, file.path));
 }
 
+// src/node/vite/positions.ts
+import { visit as visit2 } from "unist-util-visit";
+var POSITION_ATTRIBUTE = "data-seemore-pos";
+var EDITABLE = /* @__PURE__ */ new Set(["p", "h1", "h2", "h3", "h4", "h5", "h6", "li", "blockquote", "td", "th"]);
+function rehypeSeemorePositions() {
+  return (tree) => {
+    visit2(tree, "element", (node) => {
+      if (!EDITABLE.has(node.tagName)) return;
+      const { start, end } = node.position ?? {};
+      if (start?.offset === void 0 || end?.offset === void 0) return;
+      node.properties ??= {};
+      node.properties[POSITION_ATTRIBUTE] = `${start.offset}:${end.offset}`;
+    });
+  };
+}
+
 // src/node/vite/mdx.ts
 function createRemarkPlugins(options) {
   return [
@@ -997,18 +1018,21 @@ function createRemarkPlugins(options) {
     () => remarkSeemoreLinks(options)
   ];
 }
-function createRehypePlugins() {
+function createRehypePlugins(options = {}) {
   return [
     // A fence in a language Shiki has no grammar for (anything an AI dreamt up) is plain code
     // on the page, not a dead one: `plaintext` is special-cased by Shiki and never needs
     // loading.
     [rehypeCode, { fallbackLanguage: "plaintext" }],
-    rehypeToc
+    rehypeToc,
+    // After `rehype-code`, so a fence Shiki rebuilt is passed over rather than stamped with
+    // the position of whatever it replaced.
+    ...options.positions === true ? [rehypeSeemorePositions] : []
   ];
 }
 
 // src/node/vite/plugin.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
 import { createRequire } from "module";
 import { dirname as dirname6 } from "path";
 
@@ -1066,6 +1090,33 @@ function formatBytes(bytes) {
 
 // src/node/vite/plugin.ts
 init_paths();
+
+// src/node/content/edit.ts
+function spliceSource(content, request) {
+  const { start, end, expected, text } = request;
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start || end > content.length) {
+    return { ok: false, status: 400, error: "The edited range is not inside this file." };
+  }
+  if (content.slice(start, end) !== expected) {
+    return {
+      ok: false,
+      status: 409,
+      error: "This file changed since the page was rendered. Reload and try the edit again."
+    };
+  }
+  return { ok: true, content: content.slice(0, start) + withEol(text, dominantEol(content)) + content.slice(end) };
+}
+function dominantEol(content) {
+  const crlf = content.match(/\r\n/g)?.length ?? 0;
+  const lf = (content.match(/\n/g)?.length ?? 0) - crlf;
+  return crlf > lf ? "\r\n" : "\n";
+}
+function withEol(text, eol) {
+  const normalised = text.replace(/\r\n/g, "\n");
+  return eol === "\n" ? normalised : normalised.replace(/\n/g, "\r\n");
+}
+
+// src/node/vite/plugin.ts
 var VIRTUAL = {
   tree: "virtual:seemore/tree",
   routes: "virtual:seemore/routes",
@@ -1165,6 +1216,13 @@ function seemorePlugin({ ctx, serveSearch = false }) {
         res.setHeader("Content-Type", "application/json");
         res.end(JSON.stringify({ url: withBase(ctx.config.base, page.url) }));
       });
+      if (ctx.config.features["content.edit"]) {
+        devServer.middlewares.use((req, res, next) => {
+          const path = (req.url ?? "").split("?")[0] ?? "";
+          if (path !== SOURCE_ENDPOINT && path !== withBase(ctx.config.base, SOURCE_ENDPOINT)) return next();
+          void handleSource(ctx, req, res).catch(next);
+        });
+      }
     },
     /** Called by the watcher after a rescan. */
     api: {
@@ -1179,6 +1237,63 @@ function seemorePlugin({ ctx, serveSearch = false }) {
     }
   };
 }
+var SOURCE_ENDPOINT = "/__seemore/source";
+async function handleSource(ctx, req, res) {
+  if (req.method === "GET") return handleSourceRead(ctx, req, res);
+  if (req.method === "PUT") return handleSourceWrite(ctx, req, res);
+  res.setHeader("Allow", "GET, PUT");
+  return send(res, 405, { error: `${req.method ?? "This method"} is not allowed here.` });
+}
+function handleSourceRead(ctx, req, res) {
+  const query = new URLSearchParams((req.url ?? "").split("?")[1] ?? "");
+  const page = resolvePage(ctx, query.get("file"));
+  if (page === void 0) return send(res, 404, { error: "That file is not part of this site." });
+  const start = Number(query.get("start"));
+  const end = Number(query.get("end"));
+  const content = readFileSync4(page.absPath, "utf8");
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start || end > content.length) {
+    return send(res, 400, { error: "The requested range is not inside this file." });
+  }
+  return send(res, 200, { text: content.slice(start, end) });
+}
+async function handleSourceWrite(ctx, req, res) {
+  let body;
+  try {
+    body = JSON.parse(await readBody(req));
+  } catch {
+    return send(res, 400, { error: "The request body was not valid JSON." });
+  }
+  const page = resolvePage(ctx, body.file);
+  if (page === void 0) return send(res, 404, { error: "That file is not part of this site." });
+  if (typeof body.expected !== "string" || typeof body.text !== "string") {
+    return send(res, 400, { error: "Both `expected` and `text` are required." });
+  }
+  const content = readFileSync4(page.absPath, "utf8");
+  const result = spliceSource(content, {
+    start: body.start,
+    end: body.end,
+    expected: body.expected,
+    text: body.text
+  });
+  if (!result.ok) return send(res, result.status, { error: result.error });
+  writeFileSync3(page.absPath, result.content, "utf8");
+  return send(res, 200, { ok: true });
+}
+function resolvePage(ctx, file) {
+  if (typeof file !== "string" || file === "") return void 0;
+  const absFile = canonicalise(file);
+  return ctx.pages().find((page) => page.absPath === absFile);
+}
+async function readBody(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+function send(res, status, payload) {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(payload));
+}
 function hotStoreModule(suffix, value) {
   return `const state = import.meta.hot
   ? (import.meta.hot.data.seemore${suffix} ||= { listeners: new Set() })
@@ -1341,7 +1456,7 @@ function createViteConfig({ ctx, mode, outDir, ssrOutDir }) {
       getResolver: () => ctx.resolver(),
       onWarning: (message) => ctx.warnings.add(message)
     }),
-    rehypePlugins: createRehypePlugins(),
+    rehypePlugins: createRehypePlugins({ positions: mode === "dev" && ctx.config.features["content.edit"] }),
     // MDX compiles its own JSX. Vite's builtin transform infers a file's language from its
     // extension and does not know `.md`/`.mdx`, so leaving JSX in the output would fail to
     // parse. Fast Refresh is unaffected: it is a separate transform, applied to these files
@@ -1464,7 +1579,7 @@ async function loadPrerenderModule(ctx, ssrOutDir) {
 }
 
 // src/node/social/cards.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
 import { dirname as dirname7, join as join7 } from "path";
 
 // src/shared/og.ts
@@ -1490,7 +1605,7 @@ async function generateSocialCards(ctx, outDir) {
     if (png === void 0) continue;
     const target = join7(outDir, ogImagePath(page.url));
     mkdirSync2(dirname7(target), { recursive: true });
-    writeFileSync3(target, png);
+    writeFileSync4(target, png);
     written++;
   }
   return written;
@@ -1558,7 +1673,7 @@ async function runBuild(options) {
     if (config.search.provider === "static") {
       const index = await buildSearchIndex(ctx);
       mkdirSync3(join8(outDir, "api"), { recursive: true });
-      writeFileSync4(join8(outDir, "api", "search.json"), index, "utf8");
+      writeFileSync5(join8(outDir, "api", "search.json"), index, "utf8");
       const size = measureIndex(index);
       console.log(pc2.dim(`seemore  search index ${formatBytes(size.gzipped)} gzipped`));
       if (size.warning !== void 0) ctx.warnings.add(size.warning);