comark 0.2.0 → 0.3.0

package/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/comark/AGENTS.md

@@ -0,0 +1,261 @@
+# Comark — AI Agents & LLM Streaming
+
+A guide for using Comark in AI agent and LLM-powered applications where markdown is generated incrementally by a language model.
+
+## Why Comark for AI?
+
+LLMs stream markdown token-by-token. Standard markdown parsers expect complete input — they fail or produce broken output on partial streams. Comark was built to handle exactly this:
+
+- **`autoClose`** (default: `true`) — incomplete syntax like `**bold text` is automatically closed on every parse, so partial tokens always render correctly
+- **Streaming mode** — re-renders efficiently as content arrives
+- **Caret indicator** — shows a live cursor during generation
+- **ANSI rendering** — styled terminal output for CLI agents
+
+---
+
+## Vue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Comark } from '@comark/vue'
+
+const content = ref('')
+const streaming = ref(false)
+
+async function generate(prompt: string) {
+  content.value = ''
+  streaming.value = true
+
+  const res = await fetch('/api/chat', {
+    method: 'POST',
+    body: JSON.stringify({ prompt }),
+  })
+
+  const reader = res.body!.getReader()
+  const decoder = new TextDecoder()
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    content.value += decoder.decode(value, { stream: true })
+  }
+
+  streaming.value = false
+}
+</script>
+
+<template>
+  <Comark :streaming="streaming" caret>{{ content }}</Comark>
+</template>
+```
+
+---
+
+## React
+
+```tsx
+import { useState } from 'react'
+import { Comark } from '@comark/react'
+
+export default function Chat() {
+  const [content, setContent] = useState('')
+  const [streaming, setStreaming] = useState(false)
+
+  async function generate(prompt: string) {
+    setContent('')
+    setStreaming(true)
+
+    const res = await fetch('/api/chat', {
+      method: 'POST',
+      body: JSON.stringify({ prompt }),
+    })
+
+    const reader = res.body!.getReader()
+    const decoder = new TextDecoder()
+
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      setContent(prev => prev + decoder.decode(value, { stream: true }))
+    }
+
+    setStreaming(false)
+  }
+
+  return <Comark streaming={streaming} caret>{content}</Comark>
+}
+```
+
+---
+
+## Svelte
+
+```svelte
+<script lang="ts">
+  import { Comark } from '@comark/svelte'
+
+  let content = $state('')
+  let streaming = $state(false)
+
+  async function generate(prompt: string) {
+    content = ''
+    streaming = true
+
+    const res = await fetch('/api/chat', {
+      method: 'POST',
+      body: JSON.stringify({ prompt }),
+    })
+
+    const reader = res.body!.getReader()
+    const decoder = new TextDecoder()
+
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      content += decoder.decode(value, { stream: true })
+    }
+
+    streaming = false
+  }
+</script>
+
+<Comark markdown={content} {streaming} caret />
+```
+
+---
+
+## Terminal / CLI Agents
+
+Use `@comark/ansi` to render LLM markdown output in terminal-based agents:
+
+```typescript
+import { log } from '@comark/ansi'
+
+// Print a complete LLM response to stdout with ANSI styling
+await log(llmResponse)
+```
+
+For streaming terminal output, use `createLog` with a custom `write` function:
+
+```typescript
+import { createLog } from '@comark/ansi'
+
+const logStream = createLog({
+  write: (s) => process.stdout.write(s),
+})
+
+// Call after each chunk to show partial output
+await logStream(partialMarkdown)
+```
+
+---
+
+## Caret Customization
+
+The `caret` prop appends a blinking cursor to the last text node while `streaming` is `true`. Customize it with a CSS class:
+
+```vue
+<Comark :streaming="streaming" :caret="{ class: 'animate-blink' }">{{ content }}</Comark>
+```
+
+```tsx
+<Comark streaming={streaming} caret={{ class: 'animate-blink' }}>{content}</Comark>
+```
+
+```svelte
+<Comark markdown={content} {streaming} caret={{ class: 'animate-blink' }} />
+```
+
+---
+
+## With Custom Components
+
+If your LLM produces Comark component syntax (e.g., `::alert`), register components before streaming begins:
+
+```vue
+<script setup lang="ts">
+import { Comark } from '@comark/vue'
+import Alert from './Alert.vue'
+import CodeBlock from './CodeBlock.vue'
+</script>
+
+<template>
+  <Comark :components="{ alert: Alert, pre: CodeBlock }" :streaming="streaming" caret>
+    {{ content }}
+  </Comark>
+</template>
+```
+
+---
+
+## With Syntax Highlighting
+
+Syntax highlighting works during streaming — each re-parse will highlight newly completed code blocks:
+
+```vue
+<script setup lang="ts">
+import { Comark } from '@comark/vue'
+import highlight from '@comark/vue/plugins/highlight'
+import githubDark from '@shikijs/themes/github-dark'
+
+const plugins = [highlight({ themes: { light: githubDark, dark: githubDark } })]
+</script>
+
+<template>
+  <Suspense>
+    <Comark :plugins="plugins" :streaming="streaming" caret>{{ content }}</Comark>
+  </Suspense>
+</template>
+```
+
+```tsx
+import { Comark } from '@comark/react'
+import highlight from '@comark/react/plugins/highlight'
+import githubDark from '@shikijs/themes/github-dark'
+
+const plugins = [highlight({ themes: { light: githubDark, dark: githubDark } })]
+
+export default function Chat({ content, streaming }) {
+  return (
+    <Comark plugins={plugins} streaming={streaming} caret>
+      {content}
+    </Comark>
+  )
+}
+```
+
+---
+
+## defineComarkComponent for AI Chat
+
+Pre-configure a Comark component for your AI chat UI once, then reuse it everywhere:
+
+```typescript
+// comark.ts
+import { defineComarkComponent } from '@comark/vue'
+import highlight from '@comark/vue/plugins/highlight'
+import math, { Math } from '@comark/vue/plugins/math'
+import githubDark from '@shikijs/themes/github-dark'
+import Alert from './components/Alert.vue'
+
+export const ChatComark = defineComarkComponent({
+  name: 'ChatComark',
+  plugins: [
+    math(),
+    highlight({ themes: { light: githubDark, dark: githubDark } }),
+  ],
+  components: { Math, alert: Alert },
+  autoClose: true,
+})
+```
+
+```vue
+<template>
+  <ChatComark :streaming="streaming" caret>{{ content }}</ChatComark>
+</template>
+```
+
+---
+
+[← Back to Skills Guide](./SKILL.md)