seemore 1.12.1 → 1.12.3

package/README.md

@@ -33,9 +33,11 @@
   </p>
 </p>
 
-AI tools write Markdown faster than anyone can read it: specs, notes, guides, READMEs, whole folders of it. A folder of `.md` files is a dead end: nothing to click, nothing to search, no order.
+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.
 
-**seemore** points at that folder and renders it as a proper site instead, without you moving a single file or writing any code.
+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. It does not move your files. It does not need any code.
 
 <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"/>
@@ -43,24 +45,24 @@ AI tools write Markdown faster than anyone can read it: specs, notes, guides, RE
 
 ## Quick start
 
-Requires [Node.js](https://nodejs.org) 20 or newer. Nothing to install, no config file, no files to move.
+seemore needs [Node.js](https://nodejs.org) 20 or newer. You do not install anything. You do not write a config file. You do not move any files.
 
 ```bash
 cd my-docs
 npx seemore   # renders this folder at http://localhost:4040
 ```
 
-`npx seemore` runs seemore without adding it to your repository's dependencies.
+`npx seemore` runs seemore without adding it to your project's dependencies.
 
-Open the address it prints. From there it's live: add, rename, retitle or delete a file and the site updates immediately, navigation and search included.
+Open the address it prints. The site stays live after that. Add, rename, retitle, or delete a file, and the site updates at once. Navigation and search update too.
 
-The [seemore website](https://arifszn.github.io/seemore) is itself a folder of Markdown rendered by seemore. That's what your own folder will look like.
+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>
 <summary><strong>Or ask an AI agent to set it up</strong></summary>
 <br/>
 
-Not comfortable in a terminal? There's an [agent skill](https://github.com/arifszn/seemore-skill) that drives all of this for you.
+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.
 
 ### Claude Code (Plugin Marketplace)
 
@@ -74,9 +76,9 @@ Not comfortable in a terminal? There's an [agent skill](https://github.com/arifs
 
 ### Other agents (Codex, OpenCode, Antigravity, Gemini, Cursor, …)
 
-This is a standalone skill that works in any agent supporting the `SKILL.md` format. See **[INSTALL.md](https://github.com/arifszn/seemore-skill/blob/main/INSTALL.md)** for per-agent skills paths and copy-paste commands.
+This skill works in any agent that supports the `SKILL.md` format. See **[INSTALL.md](https://github.com/arifszn/seemore-skill/blob/main/INSTALL.md)** for the skill path and commands for each agent.
 
-Or just tell your agent to install it by pasting this:
+Or paste this to your agent:
 
 ```
 Fetch and follow the install instructions from
@@ -85,13 +87,13 @@ https://raw.githubusercontent.com/arifszn/seemore-skill/refs/heads/main/INSTALL.
 
 ### Usage
 
-Once it's installed, ask for what you want:
+After you install the skill, tell your agent what you want:
 
 ```
 Turn this folder of notes into a docs site I can read in my browser
 ```
 
-Or invoke the skill by name:
+Or call the skill by name:
 
 ```
 /seemore
@@ -101,49 +103,49 @@ Or invoke the skill by name:
 
 ## Three ways to use it
 
-- **[In your browser](#edit-from-the-browser)**: `npx seemore` serves the folder you're standing in and updates live as you edit.
-- **[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, in 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.
+- **[In your browser](#edit-from-the-browser)**: `npx seemore` serves the folder you are in. The site updates live as you edit.
+- **[In your code editor](#view-in-your-code-editor)**: an extension shows the same site in a panel next to your file, in 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. seemore is a docs framework, not only a preview tool.
 
 <p align="center">
-  <video src="https://github.com/user-attachments/assets/0a27b76d-f765-47b7-a3de-4b6f3aefbb74" width="640" controls muted></video>
+  <video src="https://github.com/user-attachments/assets/4238308d-8152-4386-9095-0f135447475f" width="640" controls muted></video>
 </p>
 
 ## What you get
 
-Point seemore at anything already sitting in Markdown (AI-written notes, project docs, RFCs, API references, specs, an engineering handbook) and 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:
 
-- **Zero config**: no config file, no code, no files to move; a plain folder works in the browser, in your editor, and as a static build
-- **Live preview**: files appear, disappear and reorder as you edit them, navigation and search included
+- **Zero config**: no config file, no code, no files to move. A plain folder works in the browser, in your editor, and as a static build
+- **Live preview**: files appear, disappear and reorder as you edit them. Navigation and search update too
 - **Edit in place**: double-click any block in the preview to fix its Markdown
-- **Editor integration**: one extension covers VS Code, Cursor, Antigravity and other VS Code-compatible editors, remote workspaces included
-- **Documentation framework**: `seemore build` prerenders the whole site to HTML, ready to deploy on any host
+- **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
 - **Page actions**: copy a page as Markdown, or export it as one self-contained HTML file to drop into Slack, email or an AI chat
-- **Search built in**: static full-text search with no server and no account, with shareable highlighted results; [Algolia](https://algolia.com) and [Orama Cloud](https://orama.com) drop in when you want a hosted index
+- **Search built in**: static full-text search with no server and no account, with shareable highlighted results. [Algolia](https://algolia.com) and [Orama Cloud](https://orama.com) drop in when you want a hosted index
 - **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
 - **Full MDX**: `.mdx` pages take real JSX, your own React components and CSS
-- **12 themes**: dark and light follow the system, with a toggle that remembers your choice; your own CSS always wins
+- **12 themes**: dark and light follow the system, with a toggle that remembers your choice. Your own CSS always wins
 
-### How it's different
+### How seemore is different
 
-- **Starts where your files already are**: most docs frameworks want a project, with a scaffold, a config file, a `docs/` layout and a build step wired into your repo. seemore wants a folder that already exists.
-- **Preview first, site generator second**: the same content serves locally, renders beside your editor, and builds to static HTML, with no separate setup for each.
-- **Nothing to migrate, nothing to undo**: your files are never moved or rewritten, so walking away costs nothing.
+- **Starts where your files already are**: most docs frameworks need a project, with a scaffold, a config file, a `docs/` layout and a build step wired into your repo. seemore needs only a folder that already exists.
+- **Preview first, site generator second**: the same content serves locally, renders beside your editor, and builds to static HTML. No separate setup is needed for each one.
+- **Nothing to migrate, nothing to undo**: seemore never moves or rewrites your files. You can stop using it at any time, at no cost.
 
 ## Edit from the browser
 
-The preview is also an editor. 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, hit **Save**, and the change is written to the file on disk.
+The preview is also an editor. Double-click any paragraph, heading, list item, quote or table cell. A small editor opens with that block's **Markdown source**: `**bold**` stays `**bold**`, links stay links, tables stay tables. Fix the text, press **Save**, and seemore writes the change to the file on disk.
 
 <p align="center">
   <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>
 
-Inline editing is for local previews only.
+Inline editing works only for local previews.
 
 ## 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, with no terminal, no `npx` and 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 such as Cursor and Antigravity.
+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, no `npx` and no browser tab to manage. The extension bundles the CLI, so nothing downloads and nothing goes on your PATH. Open VSX also covers VS Code-compatible editors such as Cursor and Antigravity.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/site/assets/vscode-extension.png" alt="VS Code with features.md open in the editor and the seemore panel beside it, rendering the same page with a paragraph's Markdown source open in the inline editor" width="640"/>
@@ -159,10 +161,10 @@ Install **seemore** from the [VS Code Marketplace](https://marketplace.visualstu
 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 prerendered to its own `index.html`, next to a `404.html` that every static host honours, and host-specific files (`_redirects`, `200.html`, `.nojekyll`) are written for you.
+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 a separate `index.html`, next to a `404.html` that every static host reads. seemore also writes the files each host needs (`_redirects`, `200.html`, `.nojekyll`).
 
 > [!TIP]
-> Publishing to GitHub Pages? If your site lives at `username.github.io/my-repo/` rather than the root, tell seemore the subpath once with `base: '/my-repo/'`.
+> Do you publish to GitHub Pages at `username.github.io/my-repo/`, not at the root? Set the subpath once with `base: '/my-repo/'`.
 
 ### Password-protect a site
 
@@ -182,27 +184,27 @@ $env:SEEMORE_PASSWORD='a-long-passphrase'; npx seemore build
   <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/site/assets/password-protection.png" alt="The lock screen of a password-protected seemore site: the site's icon and title above a password field and an Unlock button" width="560"/>
 </p>
 
-By default, visitors stay unlocked for one day after their last visit. Change this with `remember`:
+By default, a visitor stays unlocked for one day after their last visit. Change this with `remember`:
 
 ```ts
 auth: { remember: '7d' } // or '12h'
 ```
 
-Password protection works only for `seemore build`. To try the lock screen, build and serve `dist/` on `localhost`.
+Password protection works only for `seemore build`. To test the lock screen, build the site and serve `dist/` on `localhost`.
 
 ### Share a single page to Slack, email
 
-To share a single page instead of a site, the **Actions** button above every page writes one self-contained HTML file (styles inlined, images embedded, diagrams kept) that opens offline from a double-click. The CLI does the same without a browser:
+To share one page instead of a site, use the **Actions** button above the page. It writes one self-contained HTML file (styles inlined, images embedded, diagrams kept) that opens offline from a double-click. The CLI does the same without a browser:
 
 ```bash
 npx seemore export docs/spec.md   # writes spec.html next to the Markdown
 ```
 
-More on all three in [publishing](https://arifszn.github.io/seemore/publishing).
+Read more about all three methods on the [publishing](https://arifszn.github.io/seemore/publishing) page.
 
 ## Configuration
 
-Configuration is optional; a folder with no config file builds correctly everywhere. To adjust things, create `seemore.config.ts` next to your content:
+Configuration is optional. A folder with no config file builds correctly everywhere. To change settings, create `seemore.config.ts` next to your content:
 
 ```ts
 // seemore.config.ts
@@ -225,7 +227,7 @@ export default {
 };
 ```
 
-`features` is a set of switches. Name the ones you want to change; flags you don't mention keep their default.
+`features` is a set of switches. Name only the flags you want to change. Every other flag keeps its default value.
 
 | Flag | Default | Effect |
 | --- | --- | --- |
@@ -246,37 +248,37 @@ export default {
 | `search.highlight` | on | Highlight the query on the page you land on |
 | `social.cards` | off | Per-page OG images (needs `takumi-js`) |
 
-Every config key above is documented on the [configuration](https://arifszn.github.io/seemore/configuration) and [features](https://arifszn.github.io/seemore/features) pages.
+The [configuration](https://arifszn.github.io/seemore/configuration) and [features](https://arifszn.github.io/seemore/features) pages document every key above.
 
 ### Themes
 
-Twelve built-in colour presets: `neutral` (default), `black`, `catppuccin`, `dusk`, `ocean`, `purple`, `ruby`, `solar`, `aspen`, `emerald`, `vitepress`, `shadcn`. Dark and light follow your system setting, with a toggle that remembers your choice. For anything else, put your own CSS in `css`; it's appended last, so it wins.
+seemore has twelve built-in colour presets: `neutral` (default), `black`, `catppuccin`, `dusk`, `ocean`, `purple`, `ruby`, `solar`, `aspen`, `emerald`, `vitepress`, `shadcn`. Dark and light modes follow your system setting, with a toggle that remembers your choice. For anything else, put your own CSS in `css`. seemore appends it last, so it wins.
 
 | `neutral` (default) | `black` |
 | :--- | :--- |
 | <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/site/assets/themes/neutral.png" alt="neutral theme" width="100%"> | <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/site/assets/themes/black.png" alt="black theme" width="100%"> |
 
-All twelve are on the [themes page](https://arifszn.github.io/seemore/themes).
+The [themes page](https://arifszn.github.io/seemore/themes) shows all twelve.
 
 ## Content
 
 Works with both `.md` and `.mdx`.
 
-- GitHub Flavoured Markdown, admonitions (note / tip / warning boxes), step-by-step lists, and colour-highlighted code blocks with optional filenames and line numbers
-- `[[wikilinks]]`, including `[[Page|label]]` and `[[Page#Heading]]`, the easiest way for you or your AI to link pages without relative paths to get right; plain relative `.md` links are resolved automatically too
-- **[Mermaid](https://mermaid.js.org)** and **[D2](https://d2lang.com)** diagrams, rendered live in the browser straight from a ` ```mermaid ` or ` ```d2 ` code fence
-- Sibling images inlined as hashed assets with click-to-zoom, and PDFs opened inline in the browser's own viewer
-- Page order comes from a `meta.json`, a frontmatter `order`, or the title, in that order
+- GitHub Flavoured Markdown, admonitions (note, tip and warning boxes), step-by-step lists, and colour-highlighted code blocks with optional filenames and line numbers
+- `[[wikilinks]]`, including `[[Page|label]]` and `[[Page#Heading]]`. Use these to link pages without getting relative paths right. Plain relative `.md` links also resolve automatically
+- **[Mermaid](https://mermaid.js.org)** and **[D2](https://d2lang.com)** diagrams, rendered live in the browser from a ` ```mermaid ` or ` ```d2 ` code fence
+- Sibling images, inlined as hashed assets with click-to-zoom, and PDFs, opened inline in the browser's own viewer
+- Page order comes from a `meta.json` file, a frontmatter `order` field, or the title, checked in that order
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/arifszn/seemore/main/packages/site/assets/diagrams.png" alt="A mermaid flowchart reading Markdown, seemore, Static site rendered live on the Diagrams page, with a D2 diagram of the same chain below it" width="640"/>
 </p>
 
-Every syntax above, rendered live, is on the [content page](https://arifszn.github.io/seemore/content).
+The [content page](https://arifszn.github.io/seemore/content) renders every syntax above, live.
 
 ### PDF viewer
 
-Reference a PDF with image syntax, a sibling file or a remote URL, and it opens inline with a download link underneath:
+Reference a PDF with image syntax. Use a sibling file or a remote URL. The PDF opens inline, with a download link underneath:
 
 ```md
 ![sample document](./assets/sample.pdf)
@@ -294,31 +296,31 @@ seemore build [dir]     build a static site into dist/
 seemore export <file>   export a page as a standalone HTML file
 ```
 
-Run `seemore --help` for the options, or see the [CLI reference](https://arifszn.github.io/seemore/cli-reference).
+Run `seemore --help` to see the options, or see the [CLI reference](https://arifszn.github.io/seemore/cli-reference) page.
 
 ## FAQ
 
-**Do I have to install anything?** No, just run `npx seemore`.
+**Do I have to install anything?** No. Just run `npx seemore`.
 
 **Does anything leave my machine?** No. The dev server, the build and the export all run locally, with no account and no telemetry. The only network calls are ones you configure yourself, such as a hosted search provider.
 
-**Will it move or rewrite my files?** No. seemore reads your folder where it is. It writes only when you save an inline edit, or when you run `build` or `export`.
+**Does seemore move or rewrite my files?** No. seemore reads your folder in place. It writes to a file only when you save an inline edit, or run `build` or `export`.
 
-**Is the password protection real?** Yes. Site content is encrypted, so a copy of the build cannot be read without the password. There is no per-person access or revocation, and a short password can be guessed offline, so use a long one.
+**Is the password protection real?** Yes. seemore encrypts the site content, so nobody can read a copy of the build without the password. There is no per-person access and no way to revoke one password alone. A short password can be guessed offline, so use a long one.
 
-**Is it a preview tool or a docs framework?** Both, from the same folder: `seemore` previews it, the extension renders it beside your editor, and `seemore build` publishes it.
+**Is seemore a preview tool or a docs framework?** Both, from the same folder: `seemore` previews it, the extension renders it beside your editor, and `seemore build` publishes it.
 
 ## 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 code editor extension runs the same CLI as a child process it manages.
+[fumadocs](https://fumadocs.vercel.app) provides the interface presets. [Shiki](https://shiki.style), [Mermaid](https://mermaid.js.org), [D2](https://d2lang.com), [Vite](https://vite.dev) and [React Router](https://reactrouter.com) run underneath it. The code editor extension runs the same CLI as a child process it manages.
 
 ## Contributing
 
-Bug reports and pull requests are welcome. [CONTRIBUTING.md](https://github.com/arifszn/seemore/blob/main/CONTRIBUTING.md) covers how to get the repo running, the checks to pass before opening a pull request, and how releases work.
+seemore welcomes bug reports and pull requests. [CONTRIBUTING.md](https://github.com/arifszn/seemore/blob/main/CONTRIBUTING.md) covers how to get the repo running, the checks a pull request must pass, and how releases work.
 
 ## Star it
 
-If seemore saved you some time, [give it a star](https://github.com/arifszn/seemore). That is how other people find it.
+If seemore saved you time, [give it a star](https://github.com/arifszn/seemore). A star helps other people find it.
 
 ## Licence
 

package/package.json

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

package/src/app/lib/tree.ts

@@ -1,5 +1,5 @@
 import { useSyncExternalStore } from 'react';
-import { deserializePageTree } from 'fumadocs-core/source/client';
+import { deserializePageTree, type SerializedPageTree } from 'fumadocs-core/source/client';
 import type * as PageTree from 'fumadocs-core/page-tree';
 import { getTree, subscribeTree } from 'virtual:seemore/tree';
 
@@ -12,7 +12,37 @@ import { getTree, subscribeTree } from 'virtual:seemore/tree';
  */
 export function usePageTree(): PageTree.Root {
   const serialized = useSyncExternalStore(subscribeTree, getTree, getTree);
-  return deserializePageTree(serialized);
+  return resolveTree(serialized);
+}
+
+let current: { serialized: SerializedPageTree; content: string; tree: PageTree.Root } | undefined;
+let revision = 0;
+
+/**
+ * The deserialized tree for a payload, with a root `$id` that moves whenever the tree does.
+ *
+ * fumadocs' `TreeContextProvider` memoises its tree on `root.$id`, and the loader always calls
+ * the root "root" — so without a fresh id a created, renamed or retitled page reaches the
+ * store and never the sidebar. The id only moves when the content differs: the store is
+ * replaced on body edits too, and the sidebar list is keyed on that id, so bumping it for
+ * nothing would remount the list and close every folder the reader opened, on every save.
+ * The first tree keeps its id, so prerendered HTML and hydration agree. Exported for the
+ * tree store test.
+ */
+export function resolveTree(serialized: SerializedPageTree): PageTree.Root {
+  if (current?.serialized === serialized) return current.tree;
+
+  // Measured before deserialising: fumadocs rewrites names and icons into elements in place.
+  const content = JSON.stringify(serialized);
+  if (current?.content === content) {
+    current = { ...current, serialized };
+    return current.tree;
+  }
+
+  const tree = deserializePageTree(serialized);
+  if (current !== undefined) tree.$id = `${tree.$id ?? 'root'}:${++revision}`;
+  current = { serialized, content, tree };
+  return tree;
 }
 
 /**