comark 0.2.1 → 0.3.0

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

@@ -0,0 +1,462 @@
+# Vue Rendering Guide
+
+Complete guide for rendering Comark AST in Vue applications.
+
+## Table of Contents
+
+- [Basic Usage](#basic-usage)
+- [Custom Components](#custom-components)
+- [Dynamic Component Resolution](#dynamic-component-resolution)
+- [Slots Support](#slots-support)
+- [Streaming Mode](#streaming-mode)
+- [Prose Components](#prose-components)
+- [Error Handling](#error-handling)
+- [Props Access](#props-access)
+
+---
+
+## Basic Usage
+
+Use the `Comark` component to render markdown:
+
+```vue
+<template>
+  <Comark>{{ content }}</Comark>
+</template>
+
+<script setup lang="ts">
+import { Comark } from '@comark/vue'
+
+const content = `
+# Hello World
+
+This is **markdown** content.
+
+::alert{type="info"}
+Important message
+::
+`
+</script>
+```
+
+---
+
+## Custom Components
+
+Map custom Vue components to Comark elements:
+
+```vue
+<template>
+  <Comark :components="customComponents">{{ content }}</Comark>
+</template>
+
+<script setup lang="ts">
+import { Comark } from '@comark/vue'
+import CustomHeading from './CustomHeading.vue'
+import CustomAlert from './CustomAlert.vue'
+import CustomCard from './CustomCard.vue'
+
+const customComponents = {
+  h1: CustomHeading,
+  h2: CustomHeading,
+  alert: CustomAlert,
+  card: CustomCard,
+}
+</script>
+```
+
+### Custom Component Example
+
+```vue
+<!-- CustomHeading.vue -->
+<template>
+  <component :is="tag" :id="id" class="custom-heading">
+    <slot />
+  </component>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps<{
+  __node: any  // Comark node
+}>()
+
+const tag = computed(() => props.__node[0])
+const id = computed(() => props.__node[1]?.id)
+</script>
+
+<style scoped>
+.custom-heading {
+  font-family: 'Inter', sans-serif;
+  font-weight: 700;
+  margin-bottom: 1rem;
+}
+</style>
+```
+
+### Alert Component Example
+
+```vue
+<!-- CustomAlert.vue -->
+<template>
+  <div :class="`alert alert-${type}`" role="alert">
+    <div class="alert-icon">
+      <Icon :name="iconName" />
+    </div>
+    <div class="alert-content">
+      <slot />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps<{
+  type?: 'info' | 'warning' | 'error' | 'success'
+  __node?: any
+}>()
+
+const iconName = computed(() => {
+  switch (props.type) {
+    case 'info': return 'info-circle'
+    case 'warning': return 'exclamation-triangle'
+    case 'error': return 'times-circle'
+    case 'success': return 'check-circle'
+    default: return 'info-circle'
+  }
+})
+</script>
+
+<style scoped>
+.alert {
+  display: flex;
+  padding: 1rem;
+  border-radius: 0.5rem;
+  margin-bottom: 1rem;
+}
+
+.alert-info {
+  background-color: #e3f2fd;
+  color: #1976d2;
+}
+
+.alert-warning {
+  background-color: #fff3e0;
+  color: #f57c00;
+}
+</style>
+```
+
+---
+
+## Dynamic Component Resolution
+
+Load components dynamically using `componentsManifest`:
+
+```vue
+<template>
+  <Comark
+    :components-manifest="loadComponent"
+  >{{ content }}</Comark>
+</template>
+
+<script setup lang="ts">
+import { Comark } from '@comark/vue'
+
+const componentMap = {
+  'alert': () => import('./Alert.vue'),
+  'card': () => import('./Card.vue'),
+  'button': () => import('./Button.vue'),
+}
+
+async function loadComponent(name: string) {
+  if (componentMap[name]) {
+    return componentMap[name]()
+  }
+  throw new Error(`Component ${name} not found`)
+}
+</script>
+```
+
+---
+
+## Slots Support
+
+Comark components with slots work seamlessly in Vue:
+
+### Markdown with Slots
+
+```markdown
+::card
+#header
+## Card Title
+
+#content
+Main content here with **markdown** support
+
+#footer
+Footer text
+::
+```
+
+### Custom Component with Slots
+
+```vue
+<!-- Card.vue -->
+<template>
+  <div class="card">
+    <div v-if="$slots.header" class="card-header">
+      <slot name="header" />
+    </div>
+    <div class="card-content">
+      <slot name="content" />
+      <!-- Default slot as fallback -->
+      <slot />
+    </div>
+    <div v-if="$slots.footer" class="card-footer">
+      <slot name="footer" />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.card {
+  border: 1px solid #e5e7eb;
+  border-radius: 0.5rem;
+  overflow: hidden;
+}
+
+.card-header {
+  background-color: #f9fafb;
+  padding: 1rem;
+  border-bottom: 1px solid #e5e7eb;
+}
+
+.card-content {
+  padding: 1rem;
+}
+
+.card-footer {
+  background-color: #f9fafb;
+  padding: 1rem;
+  border-top: 1px solid #e5e7eb;
+}
+</style>
+```
+
+### Nested Slots
+
+```markdown
+::tabs
+#tab1
+### First Tab
+Content for tab 1
+
+#tab2
+### Second Tab
+Content for tab 2
+::
+```
+
+```vue
+<!-- Tabs.vue -->
+<template>
+  <div class="tabs">
+    <div class="tab-headers">
+      <button
+        v-for="(slot, name) in $slots"
+        :key="name"
+        :class="{ active: activeTab === name }"
+        @click="activeTab = name"
+      >
+        {{ name }}
+      </button>
+    </div>
+    <div class="tab-content">
+      <component :is="() => $slots[activeTab]?.()" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const activeTab = ref('tab1')
+</script>
+```
+
+---
+
+## Streaming Mode
+
+The `Comark` component can be used with reactive content for streaming scenarios:
+
+```vue
+<template>
+  <div>
+    <Comark>{{ content }}</Comark>
+    <div v-if="isLoading">Loading...</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Comark } from '@comark/vue'
+
+const content = ref('')
+const isLoading = ref(true)
+
+async function loadContent() {
+  const response = await fetch('/api/content.md')
+  const reader = response.body!.getReader()
+  const decoder = new TextDecoder()
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    content.value += decoder.decode(value)
+  }
+
+  isLoading.value = false
+}
+
+loadContent()
+</script>
+```
+
+---
+
+---
+
+## Prose Components
+
+The `Comark` component uses built-in prose styling automatically. You can override with custom components:
+
+```vue
+<template>
+  <Comark :components="components">{{ content }}</Comark>
+</template>
+
+<script setup lang="ts">
+import { Comark } from '@comark/vue'
+import CustomAlert from './CustomAlert.vue'
+
+const components = {
+  alert: CustomAlert,  // Override or add custom components
+}
+</script>
+```
+
+---
+
+## Error Handling
+
+The `ComarkRenderer` component has built-in error capture via Vue's `onErrorCaptured` hook. Component rendering errors are caught automatically without crashing the application. You can also use Vue's native `onErrorCaptured` in a parent component to handle errors:
+
+```vue
+<template>
+  <Comark :markdown="content" />
+</template>
+
+<script setup lang="ts">
+import { onErrorCaptured } from 'vue'
+import { Comark } from '@comark/vue'
+
+onErrorCaptured((error) => {
+  console.error('Component error:', error)
+  return false // prevent propagation
+})
+</script>
+```
+
+---
+
+## Props Access
+
+Custom components receive the original Comark node and parsed props:
+
+```vue
+<!-- CustomAlert.vue -->
+<template>
+  <div :class="alertClasses" role="alert">
+    <slot />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps<{
+  type?: string        // From {type="info"}
+  bool?: boolean       // From {bool} → :bool="true"
+  count?: number       // From {:count="5"}
+  data?: object        // From {:data='{"key":"val"}'}
+  __node?: any         // Original Comark node
+}>()
+
+const alertClasses = computed(() => [
+  'alert',
+  `alert-${props.type || 'info'}`,
+  { 'alert-important': props.bool }
+])
+</script>
+```
+
+### Property Parsing Rules
+
+- Props starting with `:` are parsed as booleans/JSON
+- Standard HTML attributes work normally
+- `__node` provides access to the raw AST node
+
+### Accessing Node Structure
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{ __node?: any }>()
+
+// Node structure: [tag, props, ...children]
+const tag = computed(() => props.__node?.[0])
+const nodeProps = computed(() => props.__node?.[1] || {})
+const children = computed(() => props.__node?.slice(2) || [])
+</script>
+```
+
+### Working with Complex Props
+
+```vue
+<!-- DataTable.vue -->
+<template>
+  <table>
+    <thead>
+      <tr>
+        <th v-for="col in columns" :key="col">{{ col }}</th>
+      </tr>
+    </thead>
+    <tbody>
+      <slot />
+    </tbody>
+  </table>
+</template>
+
+<script setup lang="ts">
+const props = defineProps<{
+  columns?: string[]  // From {:columns='["Name","Age"]'}
+  sortable?: boolean  // From {sortable}
+  __node?: any
+}>()
+</script>
+```
+
+**Usage in Markdown:**
+
+```markdown
+::data-table{:columns='["Name", "Age", "Email"]' sortable}
+Table content here
+::
+```
+
+---
+
+[← Back to Main Skills Guide](../SKILL.md)

package/skills/skills/migrate-mdc-to-comark/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: migrate-mdc-to-comark
+description: >-
+  Migrate a Nuxt project from @nuxtjs/mdc to Comark. Covers package changes, parse/render API mapping, AST format, Nuxt module config, components, slots, plugins, and Nuxt UI integration.
+---
+
+# Migrate from @nuxtjs/mdc to Comark
+
+`@nuxtjs/mdc` was Nuxt-only. Comark is its successor — the markdown syntax is fully compatible, your `.md` files need no changes. What changes is the JavaScript API.
+
+The migration has two parts: **Core Package** (programmatic API) and **Nuxt Module** (components, slots, config).
+
+## Quick Overview
+
+- **Package**: `@nuxtjs/mdc` → `comark` (core only) or `@comark/nuxt` (Nuxt module)
+- **Parse**: `parseMarkdown()` → `parse()` · factory: `createParse()` (sync, no await)
+- **Render**: `stringifyMarkdown()` → `renderMarkdown()` from `comark/render`
+- **AST**: object tree → compact tuples `['tag', props, ...children]`
+- **Result**: `result.body` / `result.data` → `tree.nodes` / `tree.frontmatter`
+- **Renderer**: `<MDCRenderer :body :data>` → `<ComarkRenderer :tree>`
+- **All-in-one**: `<MDC :value>` → `<Comark :markdown>`
+- **Slots**: `<MDCSlot />` → native `<slot />`
+- **Plugins**: global `nuxt.config` → per-component `defineComarkComponent({ plugins })`
+- **Markdown files**: no changes needed
+
+## Core Package
+
+### API Mapping
+
+| `@nuxtjs/mdc` | `comark` |
+|---|---|
+| `parseMarkdown(md, opts)` | `parse(md, opts)` from `comark` |
+| `createMarkdownParser(opts)` (async) | `createParse(opts)` (sync — no await) |
+| `stringifyMarkdown(body, data)` | `renderMarkdown(tree)` from `comark/render` |
+| `result.body` (`MDCRoot`) | `tree.nodes` (`ComarkNode[]`) |
+| `result.data` | `tree.frontmatter` |
+| `result.data.title` | `tree.frontmatter.title` |
+| `result.toc` | `tree.meta.toc` (requires `toc` plugin) |
+| `result.excerpt` | `tree.meta.summary` (requires `summary` plugin) |
+
+### AST Format
+
+| `@nuxtjs/mdc` | `comark` |
+|---|---|
+| `{ type: 'root', children: MDCNode[] }` | `{ nodes: ComarkNode[], frontmatter: {}, meta: {} }` |
+| `{ type: 'element', tag: 'p', props: {}, children: [] }` | `['p', {}, ...children]` |
+| `{ type: 'text', value: 'hello' }` | `'hello'` (plain string) |
+
+### Parse Options
+
+```typescript
+// Before — MDCParseOptions
+{
+  remark: { plugins: { /* record */ } },
+  rehype: { options: {...}, plugins: { /* record */ } },
+  highlight: { theme: '...', langs: [...] } | false,
+  toc: { depth: 3, searchDepth: 2 } | false,
+}
+
+// After — ParseOptions
+{
+  plugins: ComarkPlugin[],   // ordered array, not a record
+  autoUnwrap: true,          // removes <p> from single-paragraph containers
+  autoClose: true,           // completes incomplete syntax (useful for streaming)
+  html: true,                // parse embedded HTML tags
+}
+```
+
+### Plugins
+
+The `unified`/`remark`/`rehype` pipeline is replaced by Comark's own lighter plugin interface.
+
+| Feature | Before | After |
+|---|---|---|
+| Syntax highlighting | `rehypeHighlight` via `createMarkdownParser` | `highlight()` from `comark/plugins/highlight` |
+| Table of Contents | `parseMarkdown(md, { toc: { depth: 3 } })` | `toc({ depth: 3 })` plugin |
+| Excerpt / Summary | `result.excerpt` (built-in) | `summary()` plugin → `tree.meta.summary` |
+| Emoji | `remark-emoji` (enabled by default) | `emoji()` plugin (opt-in) |
+
+Available plugins: `comark/plugins/toc`, `comark/plugins/highlight`, `comark/plugins/emoji`, `comark/plugins/task-list`, `comark/plugins/summary`, `comark/plugins/security`, `comark/plugins/alert`, `comark/plugins/math`, `comark/plugins/mermaid`, `comark/plugins/punctuation`
+
+## Nuxt Module
+
+### Configuration
+
+```typescript
+// Before
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/mdc'],
+  mdc: { highlight: { ... }, remarkPlugins: { ... } },
+})
+
+// After
+export default defineNuxtConfig({
+  modules: ['@comark/nuxt'],
+  // No plugin config here — plugins are defined per-component
+})
+```
+
+`@comark/nuxt` auto-imports: `Comark`, `ComarkRenderer`, `defineComarkComponent`, `defineComarkRendererComponent`.
+
+### Components
+
+| `@nuxtjs/mdc` | `@comark/nuxt` |
+|---|---|
+| `<MDCRenderer :body :data :components>` | `<ComarkRenderer :tree :components>` |
+| `<MDC :value :parser-options>` | `<Comark :markdown :options>` or `<Comark>{{ md }}</Comark>` |
+| `<MDCSlot />` | `<slot />` |
+| `<MDCSlot unwrap="p" />` | `<slot unwrap="p" />` |
+| `<slot mdc-unwrap="p" />` | `<slot unwrap="p" />` |
+
+For a pre-parsed tree, use `<ComarkRenderer>` directly instead of `<Comark>`.
+
+#### `<ComarkRenderer>` props changes
+
+| MDC `<MDCRenderer>` | Comark `<ComarkRenderer>` | Notes |
+|---|---|---|
+| `body` (`MDCRoot`) | `tree` (`ComarkTree`) | Different AST shape |
+| `data` | — | Frontmatter is in `tree.frontmatter` |
+| `tag` | — | Wrapper is always `<div class="comark-content">` |
+| `prose` | — | `Prose*` resolution is automatic |
+| `unwrap` | — | Use `autoUnwrap` in parse options |
+| `components` | `components` | Same purpose |
+| — | `componentsManifest` | New: dynamic async component resolver |
+| — | `streaming` | New: streaming mode |
+| — | `caret` | New: animated caret for streaming |
+
+#### Summary rendering
+
+```vue
+<!-- Before -->
+<MDCRenderer :body="result.excerpt ?? result.body" :data="result.data" />
+
+<!-- After -->
+<Comark summary>{{ markdown }}</Comark>
+```
+
+### `defineComarkComponent`
+
+Replaces global `mdc: { ... }` config. Define reusable components with their own plugins and component mappings:
+
+```typescript
+import { defineComarkComponent } from '@comark/vue'
+import highlight from 'comark/plugins/highlight'
+import toc from 'comark/plugins/toc'
+
+export const ArticleComark = defineComarkComponent({
+  name: 'ArticleComark',
+  plugins: [highlight({ themes: { light: githubLight, dark: githubDark } }), toc()],
+  components: { alert: CustomAlert },
+})
+```
+
+### Slots
+
+`<MDCSlot />` → native `<slot />`. Named slots work the same (`#slotName` in markdown, `<slot name="slotName">` in component). The `unwrap` attribute (`<slot unwrap="p">`) strips wrapper tags from children.
+
+### Prose Components
+
+Same `Prose*.vue` naming convention in `components/prose/`. Resolution changed from kebab-case (`prose-p`) to PascalCase (`ProseP`) internally — no file changes needed.
+
+### Nuxt UI Integration
+
+When using Nuxt UI, `@comark/nuxt` registers Nuxt UI prose components automatically. Shorthand callout components are available:
+
+```mdc
+::note    — informational
+::tip     — helpful suggestion
+::warning — something to watch out for
+::caution — critical warning
+```
+
+These are **only available with Nuxt UI**. Without it, use `::callout{icon="..." color="..."}`.
+
+## Common Pitfalls
+
+1. **`createParse` is sync** — no `await` needed (unlike `createMarkdownParser`)
+2. **Attribute naming**: Comark uses `attrs.lang`, not `attrs.language`
+3. **Frontmatter**: stored in `tree.frontmatter`, not passed separately
+4. **`renderMarkdown` includes frontmatter** — reads `tree.frontmatter` automatically
+5. **No `unified` pipeline** — `mdc.config.ts` hooks (`pre`, `remark`, `rehype`, `post`) have no equivalent, use `ComarkPlugin` interface instead
+6. **Emoji is opt-in** — not enabled by default like in MDC's `remark-emoji`
+
+## Component Syntax
+
+The MDC block and inline component syntax is identical — no changes needed in `.md` files.
+
+## Unsupported Features
+
+- **Binding syntax** (`{{ variable }}`) — not supported, rendered as plain text
+- **Props binding / data passing** — no equivalent for `parseMarkdown(md, { data: { ... } })`

package/dist/utils/serialized-task.d.ts

@@ -1 +0,0 @@
-export * from '../../src/utils/serialized-task'

package/dist/utils/serialized-task.js

@@ -1 +0,0 @@
-export * from '../../src/utils/serialized-task.ts'