@erclx/canon 5.16.0 → 5.18.0

package/src/canvas/edit.ts

@@ -0,0 +1,360 @@
+import { readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  countElements,
+  type ElementAddress,
+  isRawText,
+  resolveAddress,
+  sourceElements,
+} from '@/canvas/address'
+import {
+  type ContentRefusal,
+  canvasDir,
+  contentHash,
+  readPage,
+  readSelection,
+  TEMP_SUFFIX,
+  withFileLock,
+  writeSelection,
+} from '@/canvas/content'
+
+/**
+ * The basic set an operator edits by hand. Each is a CSS property written into
+ * the element's inline style, except `text`, which replaces its text.
+ */
+export const STYLE_PROPERTIES = [
+  'color',
+  'background-color',
+  'font-size',
+  'font-weight',
+  'width',
+  'height',
+  'padding',
+  'gap',
+  'flex-direction',
+] as const
+
+export type StyleProperty = (typeof STYLE_PROPERTIES)[number]
+
+export type EditProperty = StyleProperty | 'text'
+
+export interface EditChange {
+  readonly property: string
+  /** Empty drops a style property, and sets an element's text to nothing. */
+  readonly value: string
+}
+
+export type EditRefusal = ContentRefusal | 'invalid-edit' | 'not-text-only'
+
+export interface EditRefused {
+  readonly ok: false
+  readonly reason: EditRefusal
+  readonly detail: string
+}
+
+export type AppliedEdit = { readonly ok: true; readonly html: string }
+
+export type FrameEdit =
+  | {
+      readonly ok: true
+      readonly page: string
+      readonly frame: string
+      readonly file: string
+      /** The file's hash after the edit, which the next edit is made from. */
+      readonly hash: string
+    }
+  | EditRefused
+
+const MAX_VALUE_LENGTH = 200
+
+/** Anything that would end the declaration and start another. */
+const DECLARATION_BREAK = /[;{}<>\n\r]/
+
+const BOM = ''
+
+function refuse(reason: EditRefusal, detail: string): EditRefused {
+  return { ok: false, reason, detail }
+}
+
+function isStyleProperty(property: string): property is StyleProperty {
+  return (STYLE_PROPERTIES as readonly string[]).includes(property)
+}
+
+export function isEditProperty(property: string): property is EditProperty {
+  return property === 'text' || isStyleProperty(property)
+}
+
+function checkChange(change: EditChange): EditRefused | undefined {
+  if (!isEditProperty(change.property)) {
+    return refuse(
+      'invalid-edit',
+      `${change.property} is not editable here. Edit one of text, ${STYLE_PROPERTIES.join(', ')}`,
+    )
+  }
+  if (change.value.length > MAX_VALUE_LENGTH) {
+    return refuse(
+      'invalid-edit',
+      `the value runs past ${MAX_VALUE_LENGTH} characters`,
+    )
+  }
+  if (change.property !== 'text' && DECLARATION_BREAK.test(change.value)) {
+    return refuse(
+      'invalid-edit',
+      `${change.property} takes one value, with no ; { } < > or line break`,
+    )
+  }
+  return undefined
+}
+
+/**
+ * Splits a style attribute at each semicolon outside parentheses and quotes,
+ * keeping every segment's own spacing so an untouched one is written back as
+ * it was.
+ */
+function declarations(style: string): string[] {
+  const segments: string[] = []
+  let depth = 0
+  let quote: string | undefined
+  let start = 0
+  for (let at = 0; at < style.length; at += 1) {
+    const char = style[at]
+    if (quote) {
+      if (char === quote) quote = undefined
+    } else if (char === '"' || char === "'") quote = char
+    else if (char === '(') depth += 1
+    else if (char === ')') depth = Math.max(0, depth - 1)
+    else if (char === ';' && depth === 0) {
+      segments.push(style.slice(start, at))
+      start = at + 1
+    }
+  }
+  segments.push(style.slice(start))
+  return segments
+}
+
+function propertyOf(segment: string): string {
+  return segment.split(':', 1)[0]?.trim().toLowerCase() ?? ''
+}
+
+/**
+ * Sets one property in a style attribute, or drops it on an empty value. The
+ * first declaration of it is replaced in place and any later one dropped, so
+ * nothing further in the attribute overrides the edit. Undefined means no
+ * style is left.
+ */
+export function setDeclaration(
+  style: string,
+  property: StyleProperty,
+  value: string,
+): string | undefined {
+  const segments = declarations(style)
+  const matches = segments.filter((segment) => propertyOf(segment) === property)
+  const declaration = `${property}: ${value.trim()}`
+
+  let next: string[]
+  if (value.trim() === '') {
+    next = segments.filter((segment) => propertyOf(segment) !== property)
+  } else if (matches.length > 0) {
+    let isReplaced = false
+    next = segments.flatMap((segment) => {
+      if (propertyOf(segment) !== property) return [segment]
+      if (isReplaced) return []
+      isReplaced = true
+      const lead = segment.match(/^\s*/)?.[0] ?? ''
+      return [`${lead}${declaration}`]
+    })
+  } else {
+    const kept = style.replace(/[\s;]*$/, '')
+    return kept === '' ? declaration : `${kept}; ${declaration}`
+  }
+
+  if (next.every((segment) => segment.trim() === '')) return undefined
+  return next.join(';').replace(/^[\s;]+/, '')
+}
+
+/**
+ * Whether the element at an index holds text alone, so replacing its text
+ * flattens no nested markup. An element closed only by implication stays open
+ * to the end and reads as holding everything after it, which refuses.
+ */
+function holdsTextAlone(html: string, index: number): boolean {
+  let isOpen = false
+  let hasChild = false
+  countElements(new HTMLRewriter(), (_element, at) => {
+    if (isOpen) hasChild = true
+    if (at !== index) return undefined
+    isOpen = true
+    return () => {
+      isOpen = false
+    }
+  }).transform(html)
+  return !hasChild
+}
+
+/**
+ * Applies one change to the element the address names and leaves every other
+ * byte of the file as it was. The address is checked against the file first,
+ * the same way a pick is.
+ */
+export function applyEdit(
+  source: string,
+  address: ElementAddress,
+  change: EditChange,
+): AppliedEdit | EditRefused {
+  const invalid = checkChange(change)
+  if (invalid) return invalid
+
+  /* The rewriter drops a leading byte order mark, so it is put back after. */
+  const bom = source.startsWith(BOM) ? BOM : ''
+  const html = source.slice(bom.length)
+
+  const check = resolveAddress(html, address)
+  if (!check.ok) return refuse(check.reason, check.detail)
+
+  const { property, value } = change
+  if (property === 'text') {
+    if (isRawText(address.tag) || !holdsTextAlone(html, address.index)) {
+      return refuse(
+        'not-text-only',
+        `<${address.tag}> holds other elements or raw content, so its text is not edited as one string`,
+      )
+    }
+  }
+
+  let voidRefused = false
+  const rewritten = countElements(new HTMLRewriter(), (element, at) => {
+    if (at !== address.index) return undefined
+    if (property === 'text') {
+      if (!element.canHaveContent || element.selfClosing) {
+        voidRefused = true
+        return undefined
+      }
+      element.setInnerContent(value, { html: false })
+      return undefined
+    }
+    if (!isStyleProperty(property)) return undefined
+    const style = setDeclaration(
+      element.getAttribute('style') ?? '',
+      property,
+      value,
+    )
+    if (style === undefined) element.removeAttribute('style')
+    else element.setAttribute('style', style)
+    return undefined
+  }).transform(html)
+
+  if (voidRefused) {
+    return refuse('not-text-only', `<${address.tag}> cannot hold text`)
+  }
+  return { ok: true, html: `${bom}${rewritten}` }
+}
+
+/**
+ * Edits one element of a frame file under the file's lock. An address carrying
+ * a hash the file no longer has is refused rather than applied at an index the
+ * change may have shifted. A selection that was fresh before the edit is
+ * restamped after it, since the edit moves no element.
+ */
+export function editFrame(
+  root: string,
+  page: string,
+  frame: string,
+  address: ElementAddress,
+  change: EditChange,
+): FrameEdit {
+  const invalid = checkChange(change)
+  if (invalid) return invalid
+
+  const onPage = readPage(root, page)
+  if (!onPage) return refuse('no-page', `page ${page} does not exist`)
+  const found = onPage.frames.find((candidate) => candidate.name === frame)
+  if (!found) {
+    return refuse('no-frame', `frame ${frame} does not exist on ${page}`)
+  }
+
+  const path = join(canvasDir(root), page, found.file)
+  return withFileLock(path, (): FrameEdit => {
+    const bytes = readFileSync(path)
+    if (address.hash !== undefined && address.hash !== contentHash(bytes)) {
+      return refuse(
+        'stale-address',
+        `${page}/${frame} changed after this edit was made, so nothing was written`,
+      )
+    }
+    const before = readSelection(root)
+    const isSelectionFresh =
+      before?.page === page &&
+      before.frame === frame &&
+      before.element !== undefined &&
+      !before.element.stale
+
+    const applied = applyEdit(bytes.toString('utf8'), address, change)
+    if (!applied.ok) return applied
+
+    const temp = `${path}.${process.pid}${TEMP_SUFFIX}`
+    writeFileSync(temp, applied.html)
+    renameSync(temp, path)
+
+    if (isSelectionFresh && before.element) {
+      writeSelection(root, {
+        page,
+        frame,
+        element: {
+          index: before.element.index,
+          tag: before.element.tag,
+          count: sourceElements(applied.html).length,
+        },
+      })
+    }
+    return {
+      ok: true,
+      page,
+      frame,
+      file: found.file,
+      hash: contentHash(applied.html),
+    }
+  })
+}
+
+/**
+ * Edits the element at an index of the file as it stands, for a caller that
+ * holds no served frame to take an address from. The address it builds
+ * carries the hash it read, so a write landing between the read and the lock
+ * still refuses.
+ */
+export function editFrameAtIndex(
+  root: string,
+  page: string,
+  frame: string,
+  index: number,
+  change: EditChange,
+): FrameEdit {
+  const onPage = readPage(root, page)
+  if (!onPage) return refuse('no-page', `page ${page} does not exist`)
+  const found = onPage.frames.find((candidate) => candidate.name === frame)
+  if (!found) {
+    return refuse('no-frame', `frame ${frame} does not exist on ${page}`)
+  }
+
+  const bytes = readFileSync(join(canvasDir(root), page, found.file))
+  const elements = sourceElements(bytes.toString('utf8'))
+  const element = Number.isInteger(index) ? elements[index] : undefined
+  if (!element) {
+    return refuse(
+      'invalid-address',
+      `${page}/${frame} holds elements 0 to ${elements.length - 1}, so ${index} names none`,
+    )
+  }
+  return editFrame(
+    root,
+    page,
+    frame,
+    {
+      index,
+      tag: element.tag,
+      count: elements.length,
+      hash: contentHash(bytes),
+    },
+    change,
+  )
+}

package/src/canvas/server.ts

@@ -15,7 +15,12 @@ import {
   TEMP_SUFFIX,
   writeSelection,
 } from '@/canvas/content'
-import { resolveFrameTokens, type TokenOptions } from '@/canvas/tokens'
+import { type EditRefused, editFrame } from '@/canvas/edit'
+import {
+  resolveFrameTokens,
+  type TokenOptions,
+  tokenGroups,
+} from '@/canvas/tokens'
 import { buildDesignCss } from '@/design/css'
 import {
   bindFirstFree,
@@ -140,7 +145,9 @@ function json(body: unknown, status = 200): Response {
   })
 }
 
-const REFUSAL_STATUS: Record<ContentRefused['reason'], number> = {
+const REFUSAL_STATUS: Record<EditRefused['reason'], number> = {
+  'invalid-edit': 400,
+  'not-text-only': 409,
   'invalid-name': 400,
   'invalid-size': 400,
   'invalid-position': 400,
@@ -154,7 +161,7 @@ const REFUSAL_STATUS: Record<ContentRefused['reason'], number> = {
   'stale-address': 409,
 }
 
-function refusal(refused: ContentRefused): Response {
+function refusal(refused: ContentRefused | EditRefused): Response {
   return json(refused, REFUSAL_STATUS[refused.reason])
 }
 
@@ -351,11 +358,11 @@ export function startCanvas(
           '/': options.shell,
           '/api/pages': guarded(() => {
             const resolved = resolveFrameTokens(root, tokens)
-            const { css: _css, ...source } = resolved
+            const { css, ...source } = resolved
             const selected = readSelection(root)
             return json({
               pages: listPages(root),
-              tokens: source,
+              tokens: { ...source, groups: tokenGroups(css) },
               selection: selected && {
                 page: selected.page,
                 frame: selected.frame,
@@ -389,6 +396,44 @@ export function startCanvas(
               }),
             ),
           },
+          '/api/frames/edit': {
+            POST: guarded(
+              mutation((body) => {
+                if (
+                  !isRecord(body) ||
+                  typeof body.page !== 'string' ||
+                  typeof body.frame !== 'string' ||
+                  typeof body.property !== 'string' ||
+                  typeof body.value !== 'string'
+                ) {
+                  return badBody(
+                    'send page, frame, element, property, and value',
+                  )
+                }
+                const { element } = body
+                /*
+                 * The hash is what keeps an edit off an element the file has
+                 * since moved, so the shell's edit never goes without it.
+                 */
+                if (!isAddressShape(element) || element.hash === undefined) {
+                  return badBody(
+                    'send an element as index, tag, count, and the hash it was served with',
+                  )
+                }
+                const outcome = editFrame(
+                  root,
+                  body.page,
+                  body.frame,
+                  element,
+                  {
+                    property: body.property,
+                    value: body.value,
+                  },
+                )
+                return outcome.ok ? json(outcome) : refusal(outcome)
+              }),
+            ),
+          },
           '/api/selection': {
             POST: guarded(
               mutation((body) => {

package/src/canvas/tokens.ts

@@ -29,6 +29,88 @@ const BASE_FILE = 'base.css'
 
 const NONE_NOTICE = `No token stylesheet, so frames render unstyled. Run canon design install to add ${join(DESIGN_INSTALL_DIR, BASE_FILE)}, put overrides under ${join(DESIGN_INSTALL_DIR, DESIGN_PROJECT_SUBDIR)}/, or link a stylesheet from the frame.`
 
+export type TokenKind =
+  | 'color'
+  | 'spacing'
+  | 'radius'
+  | 'font-family'
+  | 'font-size'
+  | 'other'
+
+export interface Token {
+  readonly name: string
+  readonly value: string
+  /** The literal a `var()` value ends at, where the sheet defines it. */
+  readonly resolved?: string
+}
+
+export interface TokenGroup {
+  readonly kind: TokenKind
+  readonly tokens: readonly Token[]
+}
+
+const KIND_ORDER: readonly TokenKind[] = [
+  'color',
+  'spacing',
+  'radius',
+  'font-family',
+  'font-size',
+  'other',
+]
+
+/** By the naming the toolkit's module and most token sheets share. */
+function kindOf(name: string): TokenKind {
+  if (name.startsWith('--color-')) return 'color'
+  if (/^--(space|spacing)-/.test(name)) return 'spacing'
+  if (name.startsWith('--radius-')) return 'radius'
+  if (/-family$|^--font-family-/.test(name)) return 'font-family'
+  if (/-size$|^--font-size-|^--text-/.test(name)) return 'font-size'
+  return 'other'
+}
+
+const DECLARATION = /(--[A-Za-z0-9_-]+)\s*:\s*([^;}]*)/g
+
+const REFERENCE = /^var\(\s*(--[A-Za-z0-9_-]+)\s*(?:,[^)]*)?\)$/
+
+/**
+ * The custom properties a token sheet defines, grouped by kind. A property
+ * defined twice keeps its first value, which is the dark theme's in this
+ * toolkit's module and the base's in an installed sheet. Empty groups drop.
+ */
+export function tokenGroups(css: string): TokenGroup[] {
+  const values = new Map<string, string>()
+  for (const [, name, value] of css
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .matchAll(DECLARATION)) {
+    if (name && value !== undefined && !values.has(name)) {
+      values.set(name, value.trim())
+    }
+  }
+
+  const resolve = (value: string, seen: Set<string>): string | undefined => {
+    const reference = value.match(REFERENCE)?.[1]
+    if (!reference) return value
+    const next = values.get(reference)
+    if (next === undefined || seen.has(reference)) return undefined
+    return resolve(next, new Set([...seen, reference]))
+  }
+
+  const grouped = new Map<TokenKind, Token[]>()
+  for (const [name, value] of values) {
+    const resolved = REFERENCE.test(value)
+      ? resolve(value, new Set([name]))
+      : undefined
+    const token =
+      resolved === undefined ? { name, value } : { name, value, resolved }
+    const kind = kindOf(name)
+    grouped.set(kind, [...(grouped.get(kind) ?? []), token])
+  }
+  return KIND_ORDER.flatMap((kind) => {
+    const tokens = grouped.get(kind)
+    return tokens ? [{ kind, tokens }] : []
+  })
+}
+
 /** The installed files in cascade order: the base first, then each override. */
 function installedFiles(root: string): string[] {
   const files: string[] = []

package/src/claude/cases/misc.ts

@@ -104,6 +104,10 @@ export const MISC_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Connect this repo to Cloudflare Pages and set up the deploy.',
-    expect: 'deploy-cloudflare',
+    expect: 'deploy-app',
+  },
+  {
+    prompt: 'Set up a Vercel project for this app and wire up its secrets.',
+    expect: 'deploy-app',
   },
 ]

package/src/commands/canvas.ts

@@ -14,6 +14,11 @@ import {
   renamePage,
 } from '@/canvas/content'
 import { captureCanvas } from '@/canvas/capture'
+import {
+  type EditRefused,
+  editFrameAtIndex,
+  STYLE_PROPERTIES,
+} from '@/canvas/edit'
 import { CANVAS_PORT, startCanvas } from '@/canvas/server'
 import { resolveFrameTokens } from '@/canvas/tokens'
 import { displayPath, parsePort, waitForInterrupt } from '@/serve/report'
@@ -40,6 +45,7 @@ interface Refused {
   readonly ok: false
   readonly reason:
     | ContentRefused['reason']
+    | EditRefused['reason']
     | 'no-root'
     | 'no-server'
     | 'capture-failed'
@@ -102,7 +108,7 @@ export function register(program: Command): void {
     .command('canvas')
     .helpOption('-h, --help', 'Show this help message')
     .description(
-      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, capture)',
+      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, edit, capture)',
     )
     .addHelpText(
       'after',
@@ -118,6 +124,7 @@ export function register(program: Command): void {
         '  canon canvas frame add drafts hero --width 1440 --height 900',
         '  canon canvas frame move drafts hero --x 200 --y 120',
         '  canon canvas selection --json',
+        "  canon canvas edit drafts/hero --element 4 --set 'color=var(--color-accent)'",
         '  canon canvas capture drafts/hero',
         '  canon canvas list --json',
         '',
@@ -366,6 +373,93 @@ export function register(program: Command): void {
       outro()
     })
 
+  withRoot(
+    canvas
+      .command('edit')
+      .description(
+        'Set one property of an element in a frame, the writer the inspector uses',
+      )
+      .argument('<target>', '<page>/<frame>')
+      .requiredOption(
+        '--element <index>',
+        'The element by its index in document order, as canvas selection reports it',
+      )
+      .requiredOption(
+        '--set <property=value>',
+        'The property and its value, where an empty value drops a style property',
+      ),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Properties: text, ${STYLE_PROPERTIES.join(', ')}.`,
+        'A style property is written into the element inline style and',
+        'leaves its other properties as they were. text replaces the text of',
+        'an element holding text alone, and refuses one holding elements.',
+        'Every byte outside the element stays as it was.',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (
+        target: string,
+        opts: RootOptions & { element: string; set: string },
+      ) => {
+        const emitJson = opts.json ?? false
+        const resolved = await resolveRoot(opts)
+        if (!resolved.ok) {
+          process.exitCode = refuse(resolved, emitJson)
+          return
+        }
+        const { root } = resolved
+        const [pageName, frameName, ...rest] = target.split('/')
+        if (!pageName || !frameName || rest.length > 0) {
+          process.exitCode = refuse(
+            {
+              ok: false,
+              reason: 'invalid-name',
+              detail: `${target} is not <page>/<frame>`,
+            },
+            emitJson,
+          )
+          return
+        }
+        const split = opts.set.indexOf('=')
+        if (split <= 0) {
+          process.exitCode = refuse(
+            {
+              ok: false,
+              reason: 'invalid-edit',
+              detail: `${opts.set} is not <property>=<value>`,
+            },
+            emitJson,
+          )
+          return
+        }
+        const property = opts.set.slice(0, split).trim()
+        const value = opts.set.slice(split + 1)
+        const index =
+          opts.element.trim() === '' ? Number.NaN : Number(opts.element)
+        const outcome = editFrameAtIndex(root, pageName, frameName, index, {
+          property,
+          value,
+        })
+        if (!outcome.ok) {
+          process.exitCode = refuse(outcome, emitJson)
+          return
+        }
+        const path = resolve(canvasDir(root), outcome.page, outcome.file)
+        if (emitJson) writeJson({ ...outcome, property, value, path })
+        intro(BANNER)
+        logAdd(`${outcome.page}/${outcome.file}`)
+        logInfo(
+          `element ${index}: ${property} ${value === '' ? 'dropped' : `= ${value}`}`,
+        )
+        outro()
+      },
+    )
+
   withRoot(
     canvas
       .command('capture')