checkpoint

Author: elliott-with-the-longest-name-on-github

README.md

@@ -1,58 +1 @@
-# Svelte library
-
-Everything you need to build a Svelte library, powered by [`sv`](https://npmjs.com/package/sv).
-
-Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
-
-## Creating a project
-
-If you're seeing this, you've probably already done this step. Congrats!
-
-```sh
-# create a new project in the current directory
-npx sv create
-
-# create a new project in my-app
-npx sv create my-app
-```
-
-## Developing
-
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
-
-```sh
-npm run dev
-
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
-```
-
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
-
-## Building
-
-To build your library:
-
-```sh
-npm pack
-```
-
-To create a production version of your showcase app:
-
-```sh
-npm run build
-```
-
-You can preview the production build with `npm run preview`.
-
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
-
-## Publishing
-
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
-
-To publish your library to [npm](https://www.npmjs.com):
-
-```sh
-npm publish
-```
+The monorepo for my Markdown-related Svelte stuff! Check out `packages` for the published packages and `apps` for the docs site.

apps/docs/.gitignore

@@ -0,0 +1 @@
+.vercel

apps/docs/package.json

@@ -12,8 +12,7 @@
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
 	},
 	"devDependencies": {
-		"@sejohnson/hardened-svelte-markdown": "workspace:*",
-		"@sejohnson/svelte-markdown": "workspace:*",
+		"sveltedown": "workspace:*",
 		"@shikijs/langs": "catalog:",
 		"@shikijs/rehype": "catalog:",
 		"@shikijs/themes": "catalog:",

apps/docs/src/lib/demo-page.svelte

@@ -4,7 +4,7 @@
 	import remark_toc from 'remark-toc';
 	import rehype_raw from 'rehype-raw';
 	import remark_gfm from 'remark-gfm';
-	import { type Options } from '@sejohnson/svelte-markdown';
+	import { type Options } from 'sveltedown';
 	import rehypeShikiFromHighlighter from '@shikijs/rehype/core';
 	import type { HighlighterCore } from 'shiki/core';
 	import type { Snippet } from 'svelte';

apps/docs/src/routes/docs/+page.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+	import DemoPage from '$lib/demo-page.svelte';
+	import { AppendOnly } from 'sveltedown';
+	import initial_content from './initial-content.md?raw';
+
+	let { data } = $props();
+</script>
+
+<DemoPage highlighter={data.highlighter} {initial_content} title="sveltedown">
+	{#snippet markdown({ content, rehypePlugins, remarkPlugins })}
+		<AppendOnly {content} {rehypePlugins} {remarkPlugins} />
+	{/snippet}
+</DemoPage>

apps/docs/src/routes/hardened-svelte-markdown/+page.svelte

@@ -0,0 +1,38 @@
+# A demo of `sveltedown`'s `AppendOnly` component
+
+This component works identically to the standard `Markdown` export, save that it is optimized for append-only operations like streaming text from a LLM. Under normal circumstances, if you render `Markdown` with some content:
+
+```svelte
+<script lang="ts">
+	let content = $state('');
+</script>
+
+<button onclick={() => (content += '\n# This is another heading')}>Add another heading</button>
+<Markdown {content} />
+```
+
+...every time `content` is modified, the _entire_ string has to be re-processed. This means:
+
+- Parsing from string to `mdast`, the Markdown AST
+- Running `remark` plugins
+- Converting from `mdast` to `hast` (the HTML AST)
+- Running `rehype` plugins
+- Converting from `hast` to the Svelte runtime
+
+This is extremely wasteful when you _know_ content is only ever going to be added to the Markdown document, never modified or removed. Thankfully, we can optimize for this use case. `AppendOnly` will:
+
+- On initial render, process the entire `content` string and save the location of the start of the last block of root content. (Think heading, paragraph, blockquote, etc.)
+- When `content` changes, slice `content` from the saved location to the end. Process only this content
+- Replace the last root block with the first new block, and append any additional root blocks. If we append any additional root blocks, the start of the last one becomes our new "saved location"
+
+> `remark` plugins are run prior to saving the last block start location. `rehype` plugins are run after.
+
+What this means in practice is that the only text we're ever actually processing is the very last block-level content. The efficiency gain of rendering this way grows as the size of the markdown document grows.
+
+## Rules
+
+Because of this, there are rules. Well, only one, really. You **must not** perform any content edits other than appending. The behavior of doing so is undefined (and by undefined, I mean "will definitely break in very strange and unexpected ways). An extension of this rule is that you cannot use `remark` or `rehype` plugins that retroactively modify content -- think things like `remark-toc`, which go back to prior sections to insert nodes based on later nodes.
+
+## Try it out
+
+Add content after this to see it in action. Add content before this block to see how things will fall apart if you don't follow the rules.

apps/docs/src/routes/hardened-svelte-markdown/+page.ts

@@ -1,15 +1,12 @@
 <script lang="ts">
 	import DemoPage from '$lib/demo-page.svelte';
-	import { Markdown } from '@sejohnson/svelte-markdown';
+	import { Markdown } from 'sveltedown';
+	import initial_content from './initial-content.md?raw';
 
 	let { data } = $props();
 </script>
 
-<DemoPage
-	highlighter={data.highlighter}
-	initial_content={data.initial_content}
-	title="@sejohnson/svelte-markdown"
->
+<DemoPage highlighter={data.highlighter} {initial_content} title="sveltedown">
 	{#snippet markdown({ content, rehypePlugins, remarkPlugins })}
 		<Markdown {content} {rehypePlugins} {remarkPlugins} />
 	{/snippet}