seemore 1.1.3 → 1.1.4

package/README.md

@@ -11,6 +11,9 @@
     <a href="https://marketplace.visualstudio.com/items?itemName=arifszn.seemore-vscode">
       <img src="https://img.shields.io/badge/VS_Code-Marketplace-007ACC?logo=visualstudiocode&logoColor=white"/>
     </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>
     <a href="https://github.com/arifszn/seemore/actions/workflows/ci.yml">
       <img src="https://github.com/arifszn/seemore/actions/workflows/ci.yml/badge.svg"/>
     </a>
@@ -48,7 +51,7 @@ seemore points at that folder and renders it as a proper site instead, without y
 Three ways to use it:
 
 - **[In your browser](#view-in-your-browser)**: `npx seemore` serves the folder you're standing in and updates live as you edit.
-- **[In VS Code](#view-in-vs-code)**: an extension puts the same site in a panel next to the file you're editing.
+- **[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.
 
 <p align="center">
@@ -65,9 +68,9 @@ Open a terminal in your folder of Markdown files, run `npx seemore`, and open th
 
 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.
 
-## View in VS Code
+## View in your code editor
 
-Install [seemore for VS Code](https://marketplace.visualstudio.com/items?itemName=arifszn.seemore-vscode) to get the same rendered site as a panel beside your editor. No terminal, no `npx`, no browser tab to manage.
+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.
 
 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**.
@@ -93,28 +96,19 @@ Install [seemore for VS Code](https://marketplace.visualstudio.com/items?itemNam
 npx seemore build  # static export to dist/ for any host
 ```
 
-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 its own file, so deep links and reloads work everywhere without special host rules. seemore also writes the handful of files individual hosts look for:
-
-| File | Read by |
-| --- | --- |
-| `404.html` | GitHub Pages, Netlify, Cloudflare Pages, Vercel, S3 |
-| `_redirects` | Netlify, Cloudflare Pages |
-| `200.html` | Surge |
-| `.nojekyll` | GitHub Pages, so Jekyll doesn't drop every path starting with `_` |
-
-None of these are required for a host that isn't listed above. If your host serves a folder of files, it serves a seemore build.
+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.
 
-**GitHub Pages, one thing to know:** project sites live at `username.github.io/my-repo/`, not at the root. Tell seemore once:
+**On GitHub Pages:** project sites live under `username.github.io/my-repo/`, not the root, so set `base` once:
 
 ```ts
 export default defineConfig({ base: '/my-repo/' });
 ```
 
-or `seemore build --base /my-repo/`. Under GitHub Actions with no `base` set, the build prints the exact line to add.
+(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 VS Code, 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 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:
 
 ```ts
 // seemore.config.ts
@@ -166,7 +160,19 @@ Twelve built-in colour presets: `neutral` (default), `black`, `catppuccin`, `dus
 
 ### Features
 
-A flat list of switches for readers who want fine control. Prefix one with `!` to switch off something that's on by default.
+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 `!`.
+
+```ts
+// seemore.config.ts
+export default defineConfig({
+  features: [
+    'navigation.path',              // off by default → this turns it on
+    '!navigation.instant.prefetch', // on by default → this turns it off
+  ],
+});
+```
+
+Flags you don't mention are left at their default, so you only ever list the ones you're changing.
 
 | Flag | Default | Effect |
 | --- | --- | --- |
@@ -181,6 +187,7 @@ A flat list of switches for readers who want fine control. Prefix one with `!` t
 | `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.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 |
 | `social.cards` | off | Per-page OG images (needs `takumi-js`) |
@@ -189,7 +196,7 @@ Combinations that can't work together raise a config error naming both flags and
 
 ## Content
 
-`.md` and `.mdx` alike, with the format inferred per file, so plain Markdown never needs MDX syntax.
+Supports `.md` and `.mdx` both.
 
 - GitHub Flavoured Markdown, admonitions (note / tip / warning boxes), step-by-step lists, and colour-highlighted code blocks
 - `[[wikilinks]]`, including `[[Page|label]]` and `[[Page#Heading]]`, the easiest way for you or your AI to link pages without relative paths to get right
@@ -198,6 +205,35 @@ Combinations that can't work together raise a config error naming both flags and
 - 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
 
+### Code blocks
+
+Fences are highlighted at build time by [Shiki](https://shiki.style), in the theme's own colours.
+
+Settings go on the fence line, after the language — ` ```ts title="server.ts" lineNumbers `:
+
+| On the fence | Effect |
+| --- | --- |
+| `title="server.ts"` | Filename bar above the block |
+| `lineNumbers` | Numbers down the side; `lineNumbers=5` starts the count at 5 |
+| `noCopy` | No copy button on this one block |
+
+Comments mark individual lines and never reach the page:
+
+| In the code | Effect |
+| --- | --- |
+| `// [!code highlight]` | Marks the line |
+| `// [!code ++]`, `// [!code --]` | Diff lines: green with a `+`, red with a `-` |
+| `// [!code focus]` | Blurs every other line until the pointer is over the block |
+| `// [!code word:needle]` | Marks that word everywhere it appears in the block |
+
+The marker follows the language's own comment syntax, so `# [!code highlight]` in Python and `<!-- [!code highlight] -->` in HTML.
+
+### 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.
+
+Numbered headings — `## 1. Install it`, `## 2. Point it at a folder` — become a numbered sequence.
+
 ### Page addresses
 
 | File | Address |
@@ -214,9 +250,23 @@ Both `/guide` and `/guide/` work on every host.
 
 Pages are ordered by:
 
-1. `meta.json` in the directory
-2. Frontmatter `order`
-3. Alphabetical by title
+1. `meta.json` in the directory — an explicit list, with `...` standing in for anything you didn't name:
+
+   ```json
+   // guide/meta.json
+   { "pages": ["getting-started", "installation", "..."] }
+   ```
+
+2. Frontmatter `order` — lower numbers first:
+
+   ```md
+   ---
+   title: Getting Started
+   order: 1
+   ---
+   ```
+
+3. Alphabetical by title, for anything left unordered by the two above
 
 ## CLI reference
 
@@ -238,7 +288,7 @@ Options
 
 ## Under the hood
 
-[fumadocs](https://fumadocs.vercel.app) provides the interface presets, with [Shiki](https://shiki.style), [Mermaid](https://mermaid.js.org), [D2](https://d2lang.com), [Vite](https://vite.dev) and [React Router](https://reactrouter.com) underneath. The VS Code extension runs the same CLI as a child process it manages. Bug reports and pull requests are welcome at [github.com/arifszn/seemore](https://github.com/arifszn/seemore).
+[fumadocs](https://fumadocs.vercel.app) provides the interface presets, with [Shiki](https://shiki.style), [Mermaid](https://mermaid.js.org), [D2](https://d2lang.com), [Vite](https://vite.dev) and [React Router](https://reactrouter.com) underneath. The code editor extension runs the same CLI as a child process it manages. Bug reports and pull requests are welcome at [github.com/arifszn/seemore](https://github.com/arifszn/seemore).
 
 ## Licence
 

package/package.json

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

package/src/app/entry.prerender.tsx

@@ -1,5 +1,6 @@
-import { StrictMode } from 'react';
-import { renderToString } from 'react-dom/server';
+import { Writable } from 'node:stream';
+import { StrictMode, type ReactNode } from 'react';
+import { renderToPipeableStream } from 'react-dom/server';
 import { RouterProvider, createMemoryRouter } from 'react-router';
 import { config } from 'virtual:seemore/config';
 import { toBasename, withBase } from '../shared/base.js';
@@ -15,7 +16,7 @@ export interface RenderResult {
 /**
  * The prerender driver.
  *
- * The page's module is loaded first, so `use()` resolves synchronously and `renderToString`
+ * The page's module is loaded first, so `use()` resolves synchronously and the renderer
  * emits the complete article rather than a Suspense fallback. No route has a loader, so the
  * memory router is initialised the moment it is created.
  */
@@ -27,15 +28,82 @@ export async function render(url: string): Promise<RenderResult> {
     initialEntries: [withBase(config.base, url)],
   });
 
-  const html = renderToString(
+  const { html, failures } = await renderToHtml(
     <StrictMode>
       <RouterProvider router={router} />
     </StrictMode>,
   );
 
+  // React hands a render error to the nearest Suspense boundary and carries on. Without this
+  // the page would be written out as the loading fallback — an empty shell — and the build
+  // would report it as a success.
+  if (failures.length > 0) throw prerenderError(url, failures[0]);
+
   return { html, head: head(url) };
 }
 
+/**
+ * The whole tree as one string, plus anything that threw while rendering it.
+ *
+ * `renderToString` would be shorter, but it swallows render errors: its own `onError` is
+ * internal and a failed subtree is silently replaced by its Suspense fallback. The streaming
+ * renderer reports them, and piping only once `onAllReady` has fired keeps the output the
+ * same complete markup — no fallbacks, no streaming scripts.
+ */
+function renderToHtml(element: ReactNode): Promise<{ html: string; failures: unknown[] }> {
+  return new Promise((resolve) => {
+    const failures: unknown[] = [];
+    const chunks: Buffer[] = [];
+
+    const sink = new Writable({
+      write(chunk: Buffer, _encoding, done) {
+        chunks.push(Buffer.from(chunk));
+        done();
+      },
+    });
+    sink.on('finish', () => {
+      resolve({ html: Buffer.concat(chunks).toString('utf8'), failures });
+    });
+
+    const stream = renderToPipeableStream(element, {
+      onError(error: unknown) {
+        failures.push(error);
+      },
+      onAllReady() {
+        stream.pipe(sink);
+      },
+      // Nothing was rendered at all: there is no markup to hand back, and `failures` already
+      // holds the reason.
+      onShellError() {
+        resolve({ html: '', failures });
+      },
+    });
+  });
+}
+
+/** Components an MDX file can use without importing anything. */
+const PROVIDED_COMPONENTS = 'Callout, Card, Cards, CodeBlockTabs, Mermaid, D2 and Pdf';
+
+/**
+ * A page that threw, reported the way the rest of the build reports problems: the file it
+ * came from, what went wrong, and — for the common case of an MDX file reaching for a
+ * component that is not there — the fix.
+ */
+function prerenderError(url: string, cause: unknown): Error {
+  const file = findRoute(url)?.file;
+  const message = cause instanceof Error ? cause.message : String(cause);
+  const undefinedComponent = /Expected component `(.+?)` to be defined/.exec(message);
+
+  const hint =
+    undefinedComponent === null
+      ? ''
+      : `\n\n  \`<${undefinedComponent[1]}>\` is not one of the components seemore provides ` +
+        `(${PROVIDED_COMPONENTS}), and a Markdown file has no imports to add one with. ` +
+        `Remove it, or write the markup by hand.`;
+
+  return new Error(`${file ?? url} failed to render.\n\n  ${message}${hint}`, { cause });
+}
+
 export function listRoutes(): string[] {
   return routeEntries().map((entry) => entry.url);
 }

package/src/app/layout/DocsLayout.tsx

@@ -109,6 +109,34 @@ export function NotFound() {
   );
 }
 
+/**
+ * A page whose own markup threw — an `.mdx` file reaching for a component seemore does not
+ * provide, most often. `seemore build` refuses to write such a page at all; here, in the dev
+ * server and on client-side navigation, the reason replaces the article, because React
+ * unmounts the whole app when nothing catches the error and a blank screen says nothing.
+ */
+export function PageError({ message }: { message: string }) {
+  return (
+    <div className="seemore-shell">
+      <Header />
+      <div className="seemore-body">
+        <Sidebar />
+
+        <main className="seemore-main">
+          <article className="seemore-article prose">
+            <h1>This page failed to render</h1>
+            <pre>
+              <code>{message}</code>
+            </pre>
+          </article>
+
+          <SiteFooter />
+        </main>
+      </div>
+    </div>
+  );
+}
+
 /**
  * The generated index: when no `index.md` or root `README.md` claims `/`, the home address
  * lists every page instead of apologising.

package/src/app/router.tsx

@@ -1,7 +1,7 @@
-import { Suspense } from 'react';
+import { Component, Suspense, type ReactNode } from 'react';
 import { useLocation, type RouteObject } from 'react-router';
 import { decodePath } from '../shared/base.js';
-import { DocPage, DocsLayout, NotFound, Overview } from './layout/DocsLayout.js';
+import { DocPage, DocsLayout, NotFound, Overview, PageError } from './layout/DocsLayout.js';
 import { useRouteEntry } from './lib/pages.js';
 
 /** The current route URL: React Router has already removed the basename. */
@@ -13,6 +13,16 @@ export function useRouteUrl(): string {
 
 function Page() {
   const url = useRouteUrl();
+  // Keyed by address, so navigating away from a page that threw starts clean rather than
+  // carrying its error to every page after it.
+  return (
+    <PageErrorBoundary key={url}>
+      <PageContent url={url} />
+    </PageErrorBoundary>
+  );
+}
+
+function PageContent({ url }: { url: string }) {
   const entry = useRouteEntry(url);
   if (entry !== undefined) return <DocPage entry={entry} />;
   // A folder with no `index.md` or root `README.md` still gets a home address: a generated
@@ -20,6 +30,23 @@ function Page() {
   return url === '/' ? <Overview /> : <NotFound />;
 }
 
+/**
+ * The only error boundary in the app. Render errors come from page content — the rest of the
+ * tree is seemore's own — so this sits around the page and nothing else.
+ */
+class PageErrorBoundary extends Component<{ children: ReactNode }, { message: string | undefined }> {
+  override state: { message: string | undefined } = { message: undefined };
+
+  static getDerivedStateFromError(error: unknown): { message: string } {
+    return { message: error instanceof Error ? error.message : String(error) };
+  }
+
+  override render() {
+    if (this.state.message !== undefined) return <PageError message={this.state.message} />;
+    return this.props.children;
+  }
+}
+
 /**
  * One catch-all route, matched against `virtual:seemore/routes` at render time.
  *