seemore 1.12.18 → 1.12.21

package/README.md

@@ -2,11 +2,14 @@
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/arifszn/seemore/main/assets/logo.png" alt="seemore" width="280">
-  <h4 align="center">Let AI write the Markdown. Let seemore show it better — zero config documentation framework.</h4>
+  <h4 align="center">Zero config documentation tool - Let AI write the Markdown. Let seemore show it better.</h4>
   <p align="center">
     <a href="https://www.npmjs.com/package/seemore">
       <img src="https://img.shields.io/npm/v/seemore"/>
     </a>
+    <a href="https://arifszn.github.io/seemore/download">
+      <img src="https://img.shields.io/badge/Desktop-macOS%20%C2%B7%20Windows%20%C2%B7%20Linux-111111"/>
+    </a>
     <a href="https://open-vsx.org/extension/arifszn/seemore-vscode">
       <img src="https://img.shields.io/badge/Open_VSX-Registry-C160EF?logo=eclipseide&logoColor=white"/>
     </a>
@@ -34,16 +37,22 @@
 
 AI tools write Markdown fast. They write specs, notes, guides, READMEs, and whole folders of files. No person can read that much Markdown at that speed.
 
-A folder of `.md` files has no order. You cannot click a link between files. You cannot search across them.
-
 **seemore** points at that folder and renders it as a real site. Other docs frameworks need a project first: a scaffold, a config file, a `docs/` layout, and a build step in your repo. seemore needs only a folder that already exists. It does not move your files, and it does not need any code. If you stop using seemore, your files stay where they are.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/site/assets/home.png" alt="The seemore site: a terminal typing npx seemore to serve a folder of notes at localhost:4040, with an arrow pointing to the browser preview" width="640"/>
+  <video src="https://github.com/user-attachments/assets/10f105c9-924e-4a89-bcba-4d46eefe928d" width="640" controls muted></video>
 </p>
 
 ## Quick start
 
+You can use seemore in two ways.
+
+### Desktop app
+
+Download the app for macOS, Windows or Linux from the [download page](https://arifszn.github.io/seemore/download). Open a folder or a `.md` file, and it opens as a site.
+
+### Command line
+
 seemore needs [Node.js](https://nodejs.org) 20 or newer.
 
 ```bash
@@ -55,11 +64,11 @@ npx seemore   # renders this folder at http://localhost:4040
 
 The [seemore website](https://arifszn.github.io/seemore) is a folder of Markdown, rendered by seemore. Your own folder will look the same way.
 
-<details open>
+<details>
 <summary><strong>Or ask an AI agent to set it up</strong></summary>
 <br/>
 
-If you do not want to use a terminal, use the [agent skill](https://github.com/arifszn/seemore-skill) instead. It does the setup for you.
+If you work with an AI agent, the [agent skill](https://github.com/arifszn/seemore-skill) does the setup for you.
 
 ### Claude Code (Plugin Marketplace)
 
@@ -98,10 +107,6 @@ Or call the skill by name:
 
 </details>
 
-<p align="center">
-  <video src="https://github.com/user-attachments/assets/dd8280d2-fc8a-47c9-b2db-b1a1ccde81ce" width="640" controls muted></video>
-</p>
-
 ## What you get
 
 Point seemore at any Markdown you already have: AI-written notes, project docs, RFCs, API references, specs, or an engineering handbook. You get:
@@ -109,6 +114,7 @@ Point seemore at any Markdown you already have: AI-written notes, project docs,
 - **Zero config**: no config file, no code, no files to move
 - **Live preview**: files appear, disappear and reorder as you edit them
 - **Edit in place**: double-click any block in the preview to fix its Markdown
+- **Desktop app**: for macOS, Windows and Linux, with an integrated terminal
 - **Editor integration**: one extension covers VS Code, Cursor, Antigravity and other VS Code-compatible editors, including remote workspaces
 - **Documentation framework**: `seemore build` renders the whole site to HTML, ready to deploy on any host
 - **Password protection**: protect the built site with one shared password, with no server required
@@ -128,6 +134,18 @@ The preview is also an editor. Double-click any paragraph, heading, list item, q
 
 Inline editing works only for local previews.
 
+## Open with the desktop app
+
+Download the app from the [download page](https://arifszn.github.io/seemore/download). It opens a folder or a `.md` file as a site in its own window, with an integrated terminal.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/site/assets/desktop-app.png" alt="The seemore desktop app in the black theme, showing a folder of research notes as a site: a paragraph's Markdown source open in the inline editor above a flowchart, and the integrated terminal listing the folder's Markdown files" width="640"/>
+</p>
+
+- **Open a folder**: use **File > Open Folder**, or drag the folder onto the app.
+- **Open a file**: double-click a `.md` file, or use **File > Open File**.
+- **Use the integrated terminal**: it opens in the site's folder, so you can run an AI agent, git or a script next to the pages it changes.
+
 ## 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). You get the same rendered site as a panel beside your editor, with no terminal and no browser tab to manage. The extension bundles the CLI, so nothing downloads and nothing goes on your PATH.
@@ -214,7 +232,7 @@ The [themes page](https://arifszn.github.io/seemore/themes) shows all twelve.
 
 ## Content
 
-Works with both `.md` and `.mdx`. **[Mermaid](https://mermaid.js.org)** and **[D2](https://d2lang.com)** diagrams render live in the browser, straight from a ` ```mermaid ` or ` ```d2 ` code fence:
+Works with `.md`, `.markdown` and `.mdx`. **[Mermaid](https://mermaid.js.org)** and **[D2](https://d2lang.com)** diagrams render live in the browser, straight from a ` ```mermaid ` or ` ```d2 ` code fence:
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/site/assets/diagrams.png" alt="A mermaid code fence on the Diagrams page, with the flowchart it produces below: folder of .md into seemore, then a live site and static HTML" width="640"/>

package/dist/cli/index.js

@@ -201,7 +201,7 @@ function withBase(base, href) {
 // src/node/content/slug.ts
 import { slug as slugify } from "github-slugger";
 var INDEX_NAMES = /* @__PURE__ */ new Set(["index", "readme"]);
-var CONTENT_EXT = /\.mdx?$/i;
+var CONTENT_EXT = /\.(?:mdx?|markdown)$/i;
 function toPosix(file) {
   return file.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
 }
@@ -672,6 +672,14 @@ function toMap(input) {
   return Object.fromEntries(set);
 }
 
+// src/node/config/names.ts
+var CONFIG_NAMES = [
+  "seemore.config.ts",
+  "seemore.config.mts",
+  "seemore.config.js",
+  "seemore.config.mjs"
+];
+
 // src/node/config/schema.ts
 import { z } from "zod";
 var THEMES = [
@@ -756,7 +764,6 @@ var configSchema = z.object({
 });
 
 // src/node/config/load.ts
-var CONFIG_NAMES = ["seemore.config.ts", "seemore.config.mts", "seemore.config.js", "seemore.config.mjs"];
 function resolveConfig(input, options) {
   const parsed = parseOrThrow(input, options.configFile);
   const search = parsed.search === "static" ? { provider: "static" } : parsed.search;
@@ -883,7 +890,7 @@ function explain(issue) {
 
 // src/node/content/links.ts
 import { slug as slugify2 } from "github-slugger";
-var CONTENT_EXT2 = /\.mdx?$/i;
+var CONTENT_EXT2 = /\.(?:mdx?|markdown)$/i;
 function createLinkResolver(pages, base) {
   const byPath = /* @__PURE__ */ new Map();
   const byName = /* @__PURE__ */ new Map();
@@ -1050,7 +1057,7 @@ var metaSchema = z4.object({
 function scan(options) {
   const contentRoot = resolve3(options.contentRoot);
   const find = (patterns, keep) => findFiles(contentRoot, patterns, keep, options.exclude ?? [], options.include ?? []);
-  const contentFiles = find(["**/*.md", "**/*.mdx"], /\.mdx?$/);
+  const contentFiles = find(["**/*.md", "**/*.markdown", "**/*.mdx"], /\.(?:mdx?|markdown)$/);
   const metaFiles = find(["**/meta.json"], /(?:^|\/)meta\.json$/);
   const { routes, errors, warnings } = resolveRoutes(contentFiles);
   const pages = [];
@@ -1121,7 +1128,7 @@ function synthesiseOrderMeta(pages, metaDirs) {
   for (const [dir, dirPages] of byDir) {
     if (metaDirs.has(dir)) continue;
     if (!dirPages.some((p) => typeof p.data.order === "number" || p.isIndex)) continue;
-    const ordered = [...dirPages].sort(compareForOrder).map((p) => basename(p.file).replace(/\.mdx?$/i, ""));
+    const ordered = [...dirPages].sort(compareForOrder).map((p) => basename(p.file).replace(/\.(?:mdx?|markdown)$/i, ""));
     out.push({
       type: "meta",
       path: dir === "." ? "meta.json" : `${dir}/meta.json`,
@@ -1489,7 +1496,7 @@ function rehypeSeemoreRawHtml() {
   const transform = rehypeRaw({ passThrough: [...MDX_NODE_TYPES] });
   return (tree, file) => {
     const path = file.path ?? "";
-    if (!/\.md(?:$|\?)/.test(path)) return tree;
+    if (!/\.(?:md|markdown)(?:$|\?)/.test(path)) return tree;
     return transform(tree, file);
   };
 }
@@ -1741,7 +1748,7 @@ function createRehypePlugins(options) {
 }
 
 // src/node/vite/plugin.ts
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "fs";
 import { createRequire as createRequire2 } from "module";
 import { dirname as dirname8 } from "path";
 
@@ -1936,6 +1943,28 @@ function seemorePlugin({ ctx, serveSearch = false }) {
         res.setHeader("Content-Type", "application/json");
         res.end(JSON.stringify({ url: withBase(ctx.config.base, page.url) }));
       });
+      devServer.middlewares.use((req, res, next) => {
+        const [path = "", query = ""] = (req.url ?? "").split("?");
+        if (path !== "/__seemore/page") return next();
+        const url = new URLSearchParams(query).get("url");
+        if (url === null) return send(res, 400, { error: 'Missing "url" query parameter.' });
+        const route = routeOf(url, ctx.config.base);
+        const page = ctx.pages().find((p) => p.url === route);
+        if (page === void 0) return send(res, 404, { error: `No page is served at ${url}.` });
+        return send(res, 200, { file: page.absPath });
+      });
+      devServer.middlewares.use((req, res, next) => {
+        const path = (req.url ?? "").split("?")[0] ?? "";
+        if (path !== "/__seemore/site") return next();
+        const configFile = ctx.config.configFile;
+        void loadConfig({
+          root: ctx.contentRoot,
+          configPath: configFile !== void 0 && existsSync5(configFile) ? configFile : void 0
+        }).then(
+          ({ config }) => send(res, 200, { base: config.base, pageActions: config.pageActions, auth: config.auth !== void 0 }),
+          (error) => send(res, 500, { error: error instanceof Error ? error.message : String(error) })
+        );
+      });
       if (ctx.config.features["content.edit"]) {
         devServer.middlewares.use((req, res, next) => {
           const path = (req.url ?? "").split("?")[0] ?? "";
@@ -1957,10 +1986,29 @@ function seemorePlugin({ ctx, serveSearch = false }) {
     }
   };
 }
+function routeOf(url, base) {
+  let path;
+  try {
+    path = decodeURIComponent(new URL(url, "http://localhost").pathname);
+  } catch {
+    return url;
+  }
+  if (base !== "/") {
+    if (path === base.slice(0, -1)) path = "/";
+    else if (path.startsWith(base)) path = path.slice(base.length - 1);
+  }
+  return path.length > 1 ? path.replace(/\/+$/, "") : path;
+}
 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);
+  if (req.method === "PUT") {
+    const origin = req.headers.origin;
+    if (origin !== void 0 && origin !== `http://${req.headers.host ?? ""}`) {
+      return send(res, 403, { error: "Writes are only accepted from this site's own pages." });
+    }
+    return handleSourceWrite(ctx, req, res);
+  }
   res.setHeader("Allow", "GET, PUT");
   return send(res, 405, { error: `${req.method ?? "This method"} is not allowed here.` });
 }
@@ -2088,7 +2136,7 @@ function readIfExists(path) {
 // src/node/vite/watcher.ts
 import { relative as relative3 } from "path";
 import chokidar from "chokidar";
-var CONTENT_FILE = /\.(?:mdx?|json)$/i;
+var CONTENT_FILE = /\.(?:mdx?|markdown|json)$/i;
 var EXCLUDED_DIR = /(?:^|\/)(?:node_modules|dist|build|out|vendor|target|venv|deps|Pods|bower_components|\.[^/]+)(?:$|\/)/;
 var ALWAYS_EXCLUDED_DIR = /(?:^|\/)(?:node_modules|\.git)(?:$|\/)/;
 var GLOB_CHAR = /[*?[\]{}()!]/;
@@ -2152,7 +2200,7 @@ async function handleContentChange(server, ctx, event, path) {
   ctx.warnings.flush((line) => server.config.logger.warn(line));
   await reloadVirtual(server, VIRTUAL.tree);
   await reloadVirtual(server, VIRTUAL.routes);
-  if (event === "change" && /\.mdx?$/i.test(path)) {
+  if (event === "change" && /\.(?:mdx?|markdown)$/i.test(path)) {
     await reloadFile(server, path);
   }
 }
@@ -2261,6 +2309,9 @@ function createViteConfig({ ctx, mode, outDir, ssrOutDir, auth = false }) {
       conditions: mode === "dev" ? ["worker"] : void 0
     },
     server: {
+      // Off rather than Vite's default, which admits every localhost origin: the dev server
+      // has a write endpoint, and its own pages are the only callers it means to answer.
+      cors: false,
       fs: {
         // The content root is normally *outside* the Vite root, and files outside `allow`
         // 404 silently — the single most likely cause of "the watcher does nothing".
@@ -2311,7 +2362,7 @@ function contentHmrPlugin() {
     name: "seemore:content-hmr",
     apply: "serve",
     transform(code, id) {
-      if (!/\.mdx?(?:$|\?)/.test(id)) return null;
+      if (!/\.(?:mdx?|markdown)(?:$|\?)/.test(id)) return null;
       return { code: `${code}
 if (import.meta.hot) import.meta.hot.accept();
 `, map: null };
@@ -2568,8 +2619,8 @@ async function runDev(options) {
 }
 
 // src/cli/export.ts
-import { existsSync as existsSync5, mkdtempSync as mkdtempSync2, readFileSync as readFileSync8, readdirSync as readdirSync2, rmSync as rmSync2, statSync, writeFileSync as writeFileSync8, mkdirSync as mkdirSync4 } from "fs";
-import { basename as basename2, dirname as dirname10, extname, join as join13, relative as relative5, resolve as resolve7 } from "path";
+import { existsSync as existsSync6, mkdtempSync as mkdtempSync2, readFileSync as readFileSync8, readdirSync as readdirSync2, rmSync as rmSync2, statSync, writeFileSync as writeFileSync8, mkdirSync as mkdirSync4 } from "fs";
+import { basename as basename2, dirname as dirname10, extname, isAbsolute as isAbsolute3, join as join13, relative as relative5, resolve as resolve7, sep } from "path";
 import { tmpdir as tmpdir4 } from "os";
 import pc4 from "picocolors";
 import { build as viteBuild2 } from "vite";
@@ -2605,10 +2656,16 @@ var THEME_INIT = `<script>(function () {
 // src/cli/export.ts
 async function runExport(options) {
   const target = resolve7(options.cwd, options.file);
-  if (!existsSync5(target) || !statSync(target).isFile()) {
+  if (!existsSync6(target) || !statSync(target).isFile()) {
     throw new Error(`No such file: ${options.file}`);
   }
-  const contentRoot = resolveContentRoot(options.cwd, dirname10(target));
+  if (options.out !== void 0 && options.outFile !== void 0) {
+    throw new Error("--out and --out-file cannot be combined: --out names a directory, --out-file the exact file.");
+  }
+  const contentRoot = resolveContentRoot(options.cwd, options.root ?? dirname10(target));
+  if (options.root !== void 0 && !isInside(canonicalise(target), contentRoot)) {
+    throw new Error(`${options.file} is not inside the root ${options.root}.`);
+  }
   const loaded = await loadConfig({ root: contentRoot, configPath: resolveConfigPath(options) });
   const config = {
     ...loaded.config,
@@ -2640,9 +2697,9 @@ ${errors.join("\n\n")}`);
     const article = await prerender.renderArticle(page.url);
     const runtime = await bundleRuntime();
     const html = assemble({ article, css, runtime, config, outDir, contentRoot, template });
-    const filename = `${basename2(target).replace(/\.(?:md|mdx)$/i, "")}.html`;
-    const targetPath = options.out === void 0 ? join13(dirname10(target), filename) : join13(resolve7(options.cwd, options.out), filename);
-    if (existsSync5(targetPath)) {
+    const filename = `${basename2(target).replace(/\.(?:md|markdown|mdx)$/i, "")}.html`;
+    const targetPath = options.outFile !== void 0 ? resolve7(options.cwd, options.outFile) : options.out === void 0 ? join13(dirname10(target), filename) : join13(resolve7(options.cwd, options.out), filename);
+    if (existsSync6(targetPath)) {
       console.log(pc4.yellow(`seemore  replacing existing ${relative5(options.cwd, targetPath) || targetPath}`));
     }
     mkdirSync4(dirname10(targetPath), { recursive: true });
@@ -2654,9 +2711,13 @@ ${errors.join("\n\n")}`);
     rmSync2(ssrOutDir, { recursive: true, force: true });
   }
 }
+function isInside(file, dir) {
+  const path = relative5(dir, file);
+  return path !== "" && path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute3(path);
+}
 function readBuiltCss(outDir) {
   const assets = join13(outDir, "assets");
-  const files = existsSync5(assets) ? readdirSync2(assets).filter((file) => file.endsWith(".css")) : [];
+  const files = existsSync6(assets) ? readdirSync2(assets).filter((file) => file.endsWith(".css")) : [];
   if (files.length === 0) throw new Error("The build produced no stylesheet \u2014 the export would be unstyled.");
   return files.map((file) => readFileSync8(join13(assets, file), "utf8")).join("\n");
 }
@@ -2747,7 +2808,7 @@ function resolveAsset(src, base, outDir, contentRoot) {
   const suffix = path.replace(/^\/+/, "");
   for (const root of [outDir, contentRoot]) {
     const candidate = join13(root, suffix);
-    if (existsSync5(candidate) && statSync(candidate).isFile()) return candidate;
+    if (existsSync6(candidate) && statSync(candidate).isFile()) return candidate;
   }
   return void 0;
 }
@@ -2775,7 +2836,7 @@ function dataUriFor(file) {
 function faviconLink(config, contentRoot, template) {
   if (config.favicon !== void 0) {
     const file = join13(contentRoot, config.favicon);
-    if (existsSync5(file)) {
+    if (existsSync6(file)) {
       try {
         return `<link rel="icon" href="${dataUriFor(file)}" />`;
       } catch {
@@ -2839,6 +2900,8 @@ Options
   --json                 print one machine-readable JSON line instead of the summary (dev only)
   --config <path>        path to seemore.config.ts
   --out <dir>            build output directory (default: dist); for export, where the HTML file is written
+  --out-file <path>      export only: the exact file to write, instead of --out
+  --root <dir>           export only: the site the file belongs to (default: the file's folder)
   --base <path>          subpath the site is served from, e.g. /my-repo/
   -h, --help             show this message
   -v, --version          show the version
@@ -2850,6 +2913,7 @@ function normaliseHostFlag(argv) {
   if (next !== void 0 && !next.startsWith("-")) return argv;
   return [...argv.slice(0, index), "--host=", ...argv.slice(index + 1)];
 }
+var servesUntilKilled = false;
 async function main(argv = process.argv.slice(2)) {
   const { values, positionals } = parseArgs({
     args: normaliseHostFlag(argv),
@@ -2862,6 +2926,8 @@ async function main(argv = process.argv.slice(2)) {
       json: { type: "boolean" },
       config: { type: "string" },
       out: { type: "string" },
+      "out-file": { type: "string" },
+      root: { type: "string" },
       base: { type: "string" },
       help: { type: "boolean", short: "h" },
       version: { type: "boolean", short: "v" }
@@ -2891,9 +2957,18 @@ async function main(argv = process.argv.slice(2)) {
   if (isExport) {
     const file = rest[0];
     if (file === void 0) throw new Error("Usage: seemore export <file> \u2014 name the Markdown file to export.");
-    await runExport({ cwd: shared.cwd, file, out: values.out, configPath: values.config, base: values.base });
+    await runExport({
+      cwd: shared.cwd,
+      file,
+      out: values.out,
+      outFile: values["out-file"],
+      root: values.root,
+      configPath: values.config,
+      base: values.base
+    });
     return;
   }
+  servesUntilKilled = true;
   await runDev({
     ...shared,
     port: values.port === void 0 ? void 0 : Number(values.port),
@@ -2902,12 +2977,23 @@ async function main(argv = process.argv.slice(2)) {
     json: values.json === true
   });
 }
-main().catch((error) => {
-  console.error(`
+function exitAfterFlush(code) {
+  process.exitCode = code;
+  process.stdout.write("", () => {
+    process.stderr.write("", () => process.exit(code));
+  });
+}
+main().then(
+  () => {
+    if (!servesUntilKilled) exitAfterFlush(0);
+  },
+  (error) => {
+    console.error(`
 ${pc5.red("seemore")} ${error instanceof Error ? error.message : String(error)}
 `);
-  process.exitCode = 1;
-});
+    exitAfterFlush(1);
+  }
+);
 export {
   main
 };