@rwoll/canvas-kit 0.0.0-stage → 0.1.1

package/templates/canvas/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "__NAME__",
+  "private": true,
+  "version": "0.1.0",
+  "description": "__DESCRIPTION__",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "e2e": "playwright test",
+    "playwright:install": "playwright install chromium"
+  },
+  "dependencies": {
+    "@rwoll/canvas-kit": "",
+    "react": "",
+    "react-dom": ""
+  },
+  "devDependencies": {
+    "@playwright/test": "",
+    "@types/node": "",
+    "@types/react": "",
+    "@types/react-dom": "",
+    "typescript": "",
+    "vite": "",
+    "vitest": ""
+  }
+}

package/templates/canvas/playwright.config.ts

@@ -0,0 +1,5 @@
+import { defineCanvasConfig } from '@rwoll/canvas-kit/playwright'
+
+// Runs e2e/*.spec.ts against the built canvas (`pnpm build` first) in light,
+// dark, and high-contrast Chromium.
+export default defineCanvasConfig()

package/templates/canvas/server/canvas.test.ts

@@ -0,0 +1,22 @@
+import { createTestCanvas } from '@rwoll/canvas-kit/testing'
+import { afterEach, describe, expect, it } from 'vitest'
+import canvas from './canvas.ts'
+
+describe('__TITLE__ canvas', () => {
+  let close: (() => Promise<void>) | undefined
+  afterEach(() => close?.())
+
+  it('counts and resets', async () => {
+    const harness = await createTestCanvas(canvas)
+    close = harness.close
+    await harness.open('test')
+    expect(harness.state('test')).toEqual({ count: 0 })
+
+    await harness.invoke('test', 'increment', { by: 2 })
+    await harness.invoke('test', 'increment', {}, 'ui')
+    expect(harness.state('test')).toEqual({ count: 3 })
+
+    await harness.invoke('test', 'reset')
+    expect(await harness.invoke('test', 'get_state')).toEqual({ count: 0 })
+  })
+})

package/templates/canvas/server/canvas.ts

@@ -0,0 +1,27 @@
+import { defineCanvas, z } from '@rwoll/canvas-kit'
+
+export default defineCanvas({
+  id: '__CANVAS_ID__',
+  title: '__TITLE__',
+  description: '__DESCRIPTION__',
+  // State shared with the UI. It is validated on every change.
+  state: z.object({
+    count: z.number().int().min(0),
+  }),
+  // Optional open input, validated before init():
+  // input: z.object({ path: z.string() }),
+  init: () => ({ count: 0 }),
+  // Optional private persistence keyed by domain identity:
+  // persist: { key: ({ input }) => input.path },
+  actions: ({ action }) => ({
+    increment: action({
+      description: 'Increase the counter shown in the canvas.',
+      input: z.object({ by: z.number().int().min(1).max(100).default(1) }),
+      run: (ctx, { by }) => ctx.setState((state) => ({ count: state.count + by })),
+    }),
+    reset: action({
+      description: 'Reset the counter to zero.',
+      run: (ctx) => ctx.setState({ count: 0 }),
+    }),
+  }),
+})

package/templates/canvas/src/App.css

@@ -0,0 +1,21 @@
+main {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 16px;
+  max-width: 40rem;
+  margin: 0 auto;
+}
+
+h1 {
+  margin: 0;
+}
+
+p {
+  margin: 0;
+}
+
+.connection {
+  color: var(--muted);
+  font-size: 0.85rem;
+}

package/templates/canvas/src/App.tsx

@@ -0,0 +1,31 @@
+import { createCanvasHooks } from '@rwoll/canvas-kit/react'
+import type canvas from '../server/canvas.ts'
+import './App.css'
+
+const { useCanvas, useAction } = createCanvasHooks<typeof canvas>()
+
+const TITLE = '__TITLE__'
+
+function App() {
+  const { state, status } = useCanvas()
+  const [increment, { pending, error }] = useAction('increment')
+
+  return (
+    <main>
+      <h1>{TITLE}</h1>
+      <p>
+        Edit <code>src/App.tsx</code> for the UI and <code>server/canvas.ts</code> for state and
+        actions.
+      </p>
+      <button type="button" disabled={pending} onClick={() => increment()}>
+        Count is {state.count}
+      </button>
+      {error && <p role="alert">{error.message}</p>}
+      <p className="connection" role="status">
+        {status === 'live' ? 'Live' : status === 'connecting' ? 'Connecting…' : 'Offline'}
+      </p>
+    </main>
+  )
+}
+
+export default App

package/templates/canvas/src/index.css

@@ -0,0 +1,3 @@
+body {
+  padding: 24px;
+}

package/templates/canvas/src/main.tsx

@@ -0,0 +1,11 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import '@rwoll/canvas-kit/styles.css'
+import './index.css'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/templates/canvas/tsconfig.app.json

@@ -0,0 +1 @@
+{ "extends": "@rwoll/canvas-kit/tsconfig/canvas.json" }

package/templates/canvas/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

package/templates/canvas/tsconfig.node.json

@@ -0,0 +1 @@
+{ "extends": "@rwoll/canvas-kit/tsconfig/node.json" }

package/templates/canvas/vite.config.ts

@@ -0,0 +1,7 @@
+import { canvasKit } from '@rwoll/canvas-kit/vite'
+import { defineConfig } from 'vite'
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [canvasKit()],
+})

package/templates/ui/README.md

@@ -0,0 +1,18 @@
+# __UI_NAME__
+
+React components and the theme shared by every canvas in this marketplace. Change
+the brand once in `theme.css`, and add components here when two canvases need the
+same UI.
+
+```tsx
+// canvases/<name>/src/main.tsx
+import '@rwoll/canvas-kit/styles.css'
+import '__UI_NAME__/theme.css'
+
+// canvases/<name>/src/App.tsx
+import { Checklist, Header, Markdown, TextButton } from '__UI_NAME__'
+
+<Markdown label="Notes">{state.notes}</Markdown>   // Markdown the agent writes, safely
+```
+
+`canvas-kit new` adds this package to every new canvas.

package/templates/ui/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "__UI_NAME__",
+  "private": true,
+  "version": "0.1.0",
+  "description": "React components and the theme shared by every canvas in this marketplace.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./theme.css": "./theme.css"
+  },
+  "scripts": {
+    "typecheck": "tsc -p ."
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "",
+    "react": "",
+    "typescript": ""
+  }
+}

package/templates/ui/src/Checklist.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react'
+
+export interface ChecklistItem {
+  id: string
+  label: string
+  done: boolean
+  /** Shown at the end of the row, such as a status or a count. */
+  note?: ReactNode
+}
+
+export interface ChecklistProps {
+  /** Accessible name of the list, such as "Blockers". */
+  label: string
+  items: readonly ChecklistItem[]
+  /** Called when a row is checked or unchecked. Without it, the boxes are read-only. */
+  onToggle?: (id: string, done: boolean) => void
+  /** Shown instead of the list when there are no items. */
+  empty?: ReactNode
+}
+
+/** A list of items to check off, shared by every canvas that tracks work. */
+export function Checklist({ label, items, onToggle, empty = 'Nothing here yet.' }: ChecklistProps) {
+  if (items.length === 0) return <p className="ui-empty">{empty}</p>
+  return (
+    <ul className="ui-checklist" aria-label={label}>
+      {items.map((item) => (
+        <li key={item.id} className={item.done ? 'done' : undefined}>
+          <label>
+            <input
+              type="checkbox"
+              checked={item.done}
+              disabled={!onToggle}
+              onChange={(event) => onToggle?.(item.id, event.target.checked)}
+            />
+            <span className="text">{item.label}</span>
+            {item.note && <span className="note">{item.note}</span>}
+          </label>
+        </li>
+      ))}
+    </ul>
+  )
+}

package/templates/ui/src/Header.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react'
+
+export interface HeaderProps {
+  title: string
+  /** A short line under the title, such as the repository and a count. */
+  meta?: ReactNode
+}
+
+/** The title block every canvas starts with. */
+export function Header({ title, meta }: HeaderProps) {
+  return (
+    <header className="ui-header">
+      <h1>{title}</h1>
+      {meta && <p>{meta}</p>}
+    </header>
+  )
+}

package/templates/ui/src/Markdown.tsx

@@ -0,0 +1,140 @@
+import type { ReactNode } from 'react'
+
+export interface MarkdownProps {
+  /** Markdown, such as notes the agent writes. Raw HTML is shown as text, never run. */
+  children: string
+  /** Accessible name. With it, the notes are a labeled region. */
+  label?: string
+}
+
+/**
+ * Markdown the agent writes, in the marketplace's theme: headings, paragraphs,
+ * lists, task lists, quotes, code, rules, bold, italic, strikethrough, inline code,
+ * and http(s) or mailto links. It builds React elements directly, so nothing in
+ * the text can inject HTML.
+ */
+export function Markdown({ children, label }: MarkdownProps) {
+  return (
+    <div className="ui-markdown" role={label ? 'region' : undefined} aria-label={label}>
+      {blocks(children)}
+    </div>
+  )
+}
+
+const FENCE = /^\s*(```|~~~)/
+const HEADING = /^(#{1,6})\s+(.*?)\s*#*\s*$/
+const RULE = /^\s*([-*_])(\s*\1){2,}\s*$/
+const QUOTE = /^\s*>\s?(.*)$/
+const ITEM = /^\s*([-*+]|\d{1,9}[.)])\s+(.*)$/
+const TASK = /^\[([ xX])\]\s+(.*)$/
+
+function blocks(source: string): ReactNode[] {
+  const lines = source.replace(/\r\n?/g, '\n').split('\n')
+  const out: ReactNode[] = []
+  let i = 0
+  const startsBlock = (line: string) => FENCE.test(line) || HEADING.test(line) || RULE.test(line) || QUOTE.test(line) || ITEM.test(line)
+
+  while (i < lines.length) {
+    const line = lines[i]!
+    const key = out.length
+    if (!line.trim()) {
+      i += 1
+    } else if (FENCE.test(line)) {
+      const fence = FENCE.exec(line)![1]!
+      const code: string[] = []
+      for (i += 1; i < lines.length && !lines[i]!.trim().startsWith(fence); i += 1) code.push(lines[i]!)
+      i += 1
+      out.push(
+        <pre key={key}>
+          <code>{code.join('\n')}</code>
+        </pre>,
+      )
+    } else if (HEADING.test(line)) {
+      const [, hashes, text] = HEADING.exec(line)!
+      // The canvas title is the page's h1, so `#` becomes h2.
+      const Tag = `h${Math.min(hashes!.length + 1, 6)}` as 'h2'
+      out.push(<Tag key={key}>{inline(text!)}</Tag>)
+      i += 1
+    } else if (RULE.test(line)) {
+      out.push(<hr key={key} />)
+      i += 1
+    } else if (QUOTE.test(line)) {
+      const quoted: string[] = []
+      for (; i < lines.length && QUOTE.test(lines[i]!); i += 1) quoted.push(QUOTE.exec(lines[i]!)![1]!)
+      out.push(<blockquote key={key}>{blocks(quoted.join('\n'))}</blockquote>)
+    } else if (ITEM.test(line)) {
+      const ordered = /^\d/.test(ITEM.exec(line)![1]!)
+      const items: string[] = []
+      for (; i < lines.length; i += 1) {
+        const next = lines[i]!
+        const item = ITEM.exec(next)
+        if (item && /^\d/.test(item[1]!) === ordered) items.push(item[2]!)
+        // An indented line continues the item above it.
+        else if (items.length > 0 && /^\s{2,}\S/.test(next) && !item) items[items.length - 1] += ` ${next.trim()}`
+        else break
+      }
+      const List = ordered ? 'ol' : 'ul'
+      out.push(
+        <List key={key}>
+          {items.map((text, index) => {
+            const task = TASK.exec(text)
+            if (!task) return <li key={index}>{inline(text)}</li>
+            return (
+              <li key={index} className="task">
+                <input type="checkbox" checked={task[1] !== ' '} readOnly disabled aria-label={task[2]} />
+                <span>{inline(task[2]!)}</span>
+              </li>
+            )
+          })}
+        </List>,
+      )
+    } else {
+      const text: string[] = []
+      for (; i < lines.length && lines[i]!.trim() && !startsBlock(lines[i]!); i += 1) text.push(lines[i]!.trim())
+      out.push(<p key={key}>{inline(text.join(' '))}</p>)
+    }
+  }
+  return out
+}
+
+const INLINE =
+  /(`+)([\s\S]*?[^`])\1(?!`)|\*\*([\s\S]+?)\*\*|(?<![\w])__([\s\S]+?)__(?![\w])|~~([\s\S]+?)~~|\*(?!\s)([\s\S]+?)\*|(?<![\w])_(?!\s)([\s\S]+?)_(?![\w])|\[([^\]]+)\]\(\s*([^)\s]+)\s*\)/g
+
+function inline(text: string): ReactNode[] {
+  const out: ReactNode[] = []
+  let last = 0
+  for (const match of text.matchAll(INLINE)) {
+    const index = match.index
+    if (index > last) out.push(text.slice(last, index))
+    const [whole, ticks, code, bold, bold2, strike, italic, italic2, label, url] = match
+    if (ticks) out.push(<code key={index}>{code!.trim()}</code>)
+    else if (bold ?? bold2) out.push(<strong key={index}>{inline((bold ?? bold2)!)}</strong>)
+    else if (strike) out.push(<del key={index}>{inline(strike)}</del>)
+    else if (italic ?? italic2) out.push(<em key={index}>{inline((italic ?? italic2)!)}</em>)
+    else {
+      const href = safeHref(url!)
+      out.push(
+        href ? (
+          <a key={index} href={href} target="_blank" rel="noreferrer">
+            {inline(label!)}
+          </a>
+        ) : (
+          whole
+        ),
+      )
+    }
+    last = index + whole.length
+  }
+  if (last < text.length) out.push(text.slice(last))
+  return out
+}
+
+/** Only web and mail links; anything else, such as `javascript:`, stays as text. */
+function safeHref(url: string): string | undefined {
+  try {
+    const parsed = new URL(url)
+    return ['http:', 'https:', 'mailto:'].includes(parsed.protocol) ? parsed.href : undefined
+  } catch {
+    return undefined
+  }
+}

package/templates/ui/src/TextButton.tsx

@@ -0,0 +1,6 @@
+import type { ButtonHTMLAttributes } from 'react'
+
+/** A secondary action that reads as a link. */
+export function TextButton({ className, ...props }: ButtonHTMLAttributes<HTMLButtonElement>) {
+  return <button type="button" className={className ? `ui-text-button ${className}` : 'ui-text-button'} {...props} />
+}

package/templates/ui/src/index.ts

@@ -0,0 +1,4 @@
+export { Checklist, type ChecklistItem, type ChecklistProps } from './Checklist.tsx'
+export { Header, type HeaderProps } from './Header.tsx'
+export { Markdown, type MarkdownProps } from './Markdown.tsx'
+export { TextButton } from './TextButton.tsx'

package/templates/ui/theme.css

@@ -0,0 +1,143 @@
+/*
+ * The theme every canvas in this marketplace shares. Each canvas imports it after
+ * @rwoll/canvas-kit/styles.css, so change your brand here once.
+ */
+:root {
+  --accent: #8a2be2;
+  --accent-contrast: #fff;
+  --accent-bg: rgba(138, 43, 226, 0.1);
+  --accent-border: rgba(138, 43, 226, 0.5);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --accent: #c084fc;
+    --accent-contrast: #16171d;
+    --accent-bg: rgba(192, 132, 252, 0.15);
+    --accent-border: rgba(192, 132, 252, 0.5);
+  }
+}
+
+.ui-header h1 {
+  margin: 0;
+}
+
+.ui-header p {
+  margin: 4px 0 0;
+  color: var(--muted);
+}
+
+.ui-checklist {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.ui-checklist li {
+  border-bottom: 1px solid var(--border);
+}
+
+.ui-checklist label {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  padding: 8px 0;
+}
+
+.ui-checklist input {
+  accent-color: var(--accent);
+}
+
+.ui-checklist .done .text {
+  color: var(--muted);
+  text-decoration: line-through;
+}
+
+.ui-checklist .note {
+  margin-left: auto;
+  font-size: 0.85em;
+  color: var(--muted);
+}
+
+.ui-empty {
+  color: var(--muted);
+}
+
+.ui-text-button {
+  align-self: flex-start;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--accent);
+  cursor: pointer;
+}
+
+.ui-text-button:disabled {
+  color: var(--muted);
+}
+
+.ui-markdown > :first-child {
+  margin-top: 0;
+}
+
+.ui-markdown > :last-child {
+  margin-bottom: 0;
+}
+
+.ui-markdown :is(h2, h3, h4, h5, h6) {
+  margin: 1em 0 0.35em;
+  font-size: 1em;
+  color: var(--text-h);
+}
+
+.ui-markdown h2 {
+  font-size: 1.15em;
+}
+
+.ui-markdown :is(p, ul, ol, blockquote, pre) {
+  margin: 0.5em 0;
+}
+
+.ui-markdown :is(ul, ol) {
+  padding-left: 1.4em;
+}
+
+.ui-markdown li.task {
+  display: flex;
+  gap: 0.5em;
+  align-items: baseline;
+  margin-left: -1.4em;
+  list-style: none;
+}
+
+.ui-markdown li.task input {
+  margin: 0;
+  accent-color: var(--accent);
+}
+
+.ui-markdown pre {
+  padding: 0.75em 1em;
+  overflow-x: auto;
+  background: var(--code-bg);
+}
+
+.ui-markdown pre code {
+  padding: 0;
+  background: none;
+}
+
+.ui-markdown blockquote {
+  padding-left: 0.9em;
+  border-left: 2px solid var(--accent-border);
+  color: var(--muted);
+}
+
+.ui-markdown a {
+  color: var(--accent);
+}
+
+.ui-markdown hr {
+  margin: 1em 0;
+  border: 0;
+  border-top: 1px solid var(--border);
+}

package/templates/ui/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "types": [],
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  },
+  "include": ["src"]
+}

package/tsconfig/canvas.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "${configDir}/node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "esnext",
+    "types": ["vite/client", "node"],
+    "allowArbitraryExtensions": true,
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["${configDir}/src", "${configDir}/server"]
+}

package/tsconfig/node.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "${configDir}/node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "module": "nodenext",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["${configDir}/vite.config.ts", "${configDir}/playwright.config.ts", "${configDir}/e2e"]
+}