comark 0.3.2 → 0.4.0

package/dist/utils/helpers.js

@@ -11,9 +11,21 @@ export function createSerializedTask(fn) {
 }
 // #region define plugin
 /**
- * Define a Comark plugin
- * @param fn - The plugin factory function
- * @returns The defined plugin
+ * Define a Comark plugin.
+ *
+ * `TMeta` and `TFrontmatter` declare what the plugin contributes to
+ * `tree.meta` / `tree.frontmatter`. They are inferred from the factory's
+ * return type when set via the `__meta` / `__frontmatter` phantom markers,
+ * or can be passed explicitly. Plugins that don't contribute typed keys can
+ * omit them entirely.
+ *
+ * @example
+ * ```ts
+ * defineComarkPlugin<Options, { toc: Toc }>((opts) => ({
+ *   name: 'toc',
+ *   post(state) { state.tree.meta.toc = ... },
+ * }))
+ * ```
  */
 export function defineComarkPlugin(fn) {
     return fn;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comark",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Components in Markdown (Comark) parser with streaming support for Vue, React, Svelte and HTML",
   "keywords": [
     "markdown",
@@ -25,6 +25,7 @@
     "skills"
   ],
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -52,7 +53,7 @@
     "github-slugger": "^2.0.0",
     "hast-util-to-string": "^3.0.1",
     "minimark": "0.2.0",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.4",
     "twoslash": "^0.3.6",
     "vitest": "^4.1.4"
   },

package/skills/comark/references/rendering-svelte.md

@@ -48,9 +48,9 @@ Map custom Svelte components to Comark elements:
 ```svelte
 <script lang="ts">
   import { Comark } from '@comark/svelte'
-  import CustomHeading from './CustomHeading.svelte'
-  import CustomAlert from './CustomAlert.svelte'
-  import CustomCard from './CustomCard.svelte'
+  import CustomHeading from './components/comark/CustomHeading.svelte'
+  import CustomAlert from './components/comark/CustomAlert.svelte'
+  import CustomCard from './components/comark/CustomCard.svelte'
 
   const customComponents = {
     h1: CustomHeading,
@@ -127,9 +127,9 @@ Load components dynamically using `componentsManifest`:
   import { Comark } from '@comark/svelte'
 
   const componentMap: Record<string, () => Promise<any>> = {
-    'alert': () => import('./Alert.svelte'),
-    'card': () => import('./Card.svelte'),
-    'button': () => import('./Button.svelte'),
+    'alert': () => import('./components/comark/Alert.svelte'),
+    'card': () => import('./components/comark/Card.svelte'),
+    'button': () => import('./components/comark/Button.svelte'),
   }
 
   async function loadComponent(name: string) {
@@ -144,6 +144,50 @@ Load components dynamically using `componentsManifest`:
 <Comark markdown={content} componentsManifest={loadComponent} />
 ```
 
+In SvelteKit projects, keep components rendered from Markdown in a dedicated folder such as `$lib/components/comark/`. This keeps Comark-rendered components separate from normal app UI components and makes `componentsManifest` globs easier to audit.
+
+For SvelteKit SSR with non-eager lazy components, use `ComarkAsync` and a manifest that returns dynamic imports. An explicit map is the easiest option to audit:
+
+```svelte
+<script lang="ts">
+  import { ComarkAsync } from '@comark/svelte/async'
+
+  const componentMap: Record<string, () => Promise<any>> = {
+    'alert': () => import('$lib/components/comark/Alert.svelte'),
+    'lazy-card': () => import('$lib/components/comark/LazyCard.svelte'),
+  }
+
+  const componentsManifest = (name: string) => componentMap[name]?.()
+</script>
+
+<svelte:boundary>
+  <ComarkAsync markdown={content} {componentsManifest} />
+</svelte:boundary>
+```
+
+Use `import.meta.glob` when you want the manifest to cover every Svelte component in a folder:
+
+```svelte
+<script lang="ts">
+  import { ComarkAsync } from '@comark/svelte/async'
+  import { pascalCase } from '@comark/svelte/utils'
+
+  const modules = import.meta.glob('../lib/components/comark/*.svelte')
+
+  const componentsManifest = (name: string) => {
+    return modules[`../lib/components/comark/${pascalCase(name)}.svelte`]?.()
+  }
+</script>
+
+<svelte:boundary>
+  <ComarkAsync markdown={content} {componentsManifest} />
+</svelte:boundary>
+```
+
+Omit the boundary `pending` snippet when you want SvelteKit SSR to wait and include the resolved lazy components in the initial HTML.
+
+Use eager/static components with `ComarkRenderer` when you need stable SSR without Svelte's experimental async support.
+
 ---
 
 ## Slots Support
@@ -319,7 +363,7 @@ Override native HTML elements using the `Prose` prefix:
 
 ## Experimental Async
 
-The `ComarkAsync` component uses Svelte's experimental `await` in `$derived` for a declarative approach. Requires `experimental.async` in your Svelte config:
+The `ComarkAsync` component uses Svelte's experimental `await` in `$derived` for a declarative approach. It can also await async `componentsManifest` entries during SSR, so lazy dynamic imports render into SvelteKit server HTML. Requires `experimental.async` in your Svelte config:
 
 ```js
 // svelte.config.js

package/dist/devtools/index.d.ts

@@ -1 +0,0 @@
-export * from '../../src/devtools/index'

package/dist/devtools/index.js

@@ -1 +0,0 @@
-export * from '../../src/devtools/index.ts'

package/dist/devtools/register.d.ts

@@ -1 +0,0 @@
-export * from '../../src/devtools/register'

package/dist/devtools/register.js

@@ -1 +0,0 @@
-export * from '../../src/devtools/register.ts'

package/dist/devtools/registry.d.ts

@@ -1 +0,0 @@
-export * from '../../src/devtools/registry'

package/dist/devtools/registry.js

@@ -1 +0,0 @@
-export * from '../../src/devtools/registry.ts'

package/dist/devtools/vite.d.ts

@@ -1 +0,0 @@
-export * from '../../src/devtools/vite'

package/dist/devtools/vite.js

@@ -1 +0,0 @@
-export * from '../../src/devtools/vite.ts'

package/dist/internal/stringify/indent.d.ts

@@ -1 +0,0 @@
-export * from '../../../src/internal/stringify/indent'

package/dist/internal/stringify/indent.js

@@ -1 +0,0 @@
-export * from '../../../src/internal/stringify/indent.ts'

package/dist/vite.d.ts

@@ -1 +0,0 @@
-export * from '../src/vite'

package/dist/vite.js

@@ -1 +0,0 @@
-export * from '../src/vite.ts'