@erclx/canon 5.78.0 → 5.80.0

package/src/capture/render.ts

@@ -1,11 +1,18 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { basename, dirname } from 'node:path'
+import { basename, dirname, join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { chromium } from 'playwright-core'
 import type { Browser, Locator, Page } from 'playwright-core'
+import {
+  mergeBlocks,
+  preparePage,
+  revealSection,
+  splitBlocks,
+} from '@/capture/sections'
 import type { CaptureSource } from '@/capture/sources'
 import {
   isGenericFamily,
+  isUrlSource,
   resolveCaptureSources,
   textFamilies,
 } from '@/capture/sources'
@@ -141,6 +148,148 @@ async function captureOne(
   }
 }
 
+export interface SectionOptions {
+  outDir: string
+  root?: string
+  width?: number
+  colorScheme?: ColorScheme
+}
+
+export interface SectionShot {
+  readonly index: number
+  readonly path: string
+  readonly top: number
+  readonly height: number
+}
+
+/**
+ * Families the page draws text in that a shot cannot promise to reproduce,
+ * recorded rather than refused, since a reference shows a site as a browser
+ * draws it and most outside sites declare a generic family somewhere.
+ */
+export interface SectionFonts {
+  readonly generic: readonly string[]
+  readonly missing: readonly string[]
+}
+
+export type SectionsResult =
+  | {
+      status: 'captured'
+      source: string
+      sections: SectionShot[]
+      failed: { index: number; reason: string }[]
+      fonts: SectionFonts
+    }
+  | { status: 'failed'; source: string; reason: string }
+
+/**
+ * Shoots one page as one PNG per section, in page order, each with its stamp.
+ * A section that fails to shoot is reported beside the rest rather than
+ * dropping them, and a page that never loads or names no root fails whole.
+ *
+ * Each shot is a document-coordinate clip rather than an element shot, since a
+ * merged section spans several elements and one element cannot frame them.
+ */
+export async function captureSections(
+  sourcePath: string,
+  { outDir, root, width, colorScheme }: SectionOptions,
+): Promise<SectionsResult> {
+  const pageSource: CaptureSource = isUrlSource(sourcePath)
+    ? { kind: 'url', url: sourcePath, pngPath: outDir }
+    : { kind: 'file', htmlPath: sourcePath, pngPath: outDir }
+  const browser = await chromium.launch()
+  try {
+    const page = await browser.newPage({
+      deviceScaleFactor: DEVICE_SCALE_FACTOR,
+      ...(width === undefined
+        ? {}
+        : { viewport: { width, height: DEFAULT_VIEWPORT_HEIGHT } }),
+      ...(colorScheme === undefined ? {} : { colorScheme }),
+    })
+    await page.goto(
+      pageSource.kind === 'url'
+        ? pageSource.url
+        : pathToFileURL(pageSource.htmlPath).href,
+    )
+    if (colorScheme !== undefined) await applyColorScheme(page, colorScheme)
+    await page.evaluate(() => document.fonts.ready.then(() => undefined))
+    await preparePage(page)
+
+    const blocks = await splitBlocks(page, root)
+    if (blocks === null) {
+      return failed(pageSource, `no element matched ${root}`)
+    }
+    if (blocks.length === 0) {
+      return failed(
+        pageSource,
+        `${root ?? 'main, or body without one,'} drew no box to split into sections`,
+      )
+    }
+    const fonts = await unresolvedFonts(page)
+
+    mkdirSync(outDir, { recursive: true })
+    const shots: SectionShot[] = []
+    const misses: { index: number; reason: string }[] = []
+    for (const [offset, section] of mergeBlocks(blocks).entries()) {
+      const index = offset + 1
+      const pngPath = join(
+        outDir,
+        `section-${String(index).padStart(2, '0')}.png`,
+      )
+      try {
+        const clip = await revealSection(page, section)
+        if (clip === null) {
+          misses.push({ index, reason: 'the section drew no box' })
+          continue
+        }
+        const png = await page.screenshot({ clip, fullPage: true })
+        writeFileSync(pngPath, png)
+        writeStamp({ ...pageSource, pngPath }, png)
+        shots.push({ index, path: pngPath, top: clip.y, height: clip.height })
+      } catch (error) {
+        misses.push({
+          index,
+          reason: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
+    return {
+      status: 'captured',
+      source: sourceIdentifier(pageSource),
+      sections: shots,
+      failed: misses,
+      fonts,
+    }
+  } catch (error) {
+    return failed(
+      pageSource,
+      error instanceof Error ? error.message : String(error),
+    )
+  } finally {
+    await browser.close()
+  }
+}
+
+/**
+ * The generic and the absent families among those the page's text draws in,
+ * read once over the whole body, which is the probe single-element capture
+ * refuses on, turned into a record.
+ */
+async function unresolvedFonts(page: Page): Promise<SectionFonts> {
+  const declarations = await renderedTextFamilies(page.locator('body'))
+  const generic = textFamilies(declarations.filter(isGenericFamily))
+  const named = textFamilies(
+    declarations.filter((declaration) => !isGenericFamily(declaration)),
+  )
+  const resolved = await Promise.all(
+    named.map((family) => resolvesFont(page, family)),
+  )
+  return {
+    generic,
+    missing: named.filter((_, index) => !resolved[index]),
+  }
+}
+
 /**
  * Runs inside the render rather than in a wrapper around it, so a capture
  * cannot succeed and leave the provenance unrecorded. A throw here reaches the
@@ -202,7 +351,10 @@ async function applyColorScheme(
   }, scheme)
 }
 
-function failed(source: CaptureSource, reason: string): CaptureResult {
+function failed(
+  source: CaptureSource,
+  reason: string,
+): Extract<CaptureResult, { status: 'failed' }> {
   return { status: 'failed', source: sourceIdentifier(source), reason }
 }
 

package/src/capture/sections.ts

@@ -0,0 +1,257 @@
+import type { Page } from 'playwright-core'
+
+/**
+ * The split, the merge, and the page preparation behind `canon capture
+ * --sections`. The thresholds are the ones track 218 measured on Notion,
+ * Vercel, Linear, and ElevenLabs, and nothing beyond those four sites tuned
+ * them.
+ */
+
+/** A block taller than this many viewports splits into its children. */
+const SPLIT_VIEWPORTS = 1.6
+/** A child shorter than this is decoration rather than a block of its own. */
+const MIN_CHILD_HEIGHT = 120
+/** A child narrower than this share of the viewport is a column, not a band. */
+const MIN_WIDTH_SHARE = 0.6
+/** A block shorter than this joins the section above it. */
+export const MERGE_BELOW_PX = 400
+/** The tallest shot a section takes, in CSS pixels. Taller is cut. */
+export const MAX_SECTION_PX = 2400
+
+const SECTION_ATTRIBUTE = 'data-canon-section'
+const WHEEL_STEP_PX = 600
+const WHEEL_PAUSE_MS = 150
+const SETTLE_MS = 800
+const NETWORK_IDLE_MS = 5_000
+
+/** One block the split found, in document coordinates and page order. */
+export interface Block {
+  readonly index: number
+  readonly top: number
+  readonly height: number
+}
+
+/** One or more adjacent blocks shot as one image. */
+export interface Section {
+  readonly blocks: readonly number[]
+  readonly top: number
+  readonly height: number
+}
+
+/**
+ * Loads what a reader would see by the time they reached each part of the
+ * page, then hides every fixed and sticky layer so none paints into the middle
+ * of a shot. Hiding is how a consent banner leaves, since a click on one
+ * decides something on the operator's behalf.
+ *
+ * Wheeling rather than `scrollTo`, because a lazy loader listening for wheel
+ * or for intersection sees each step, and a jump to the bottom skips them.
+ */
+export async function preparePage(page: Page): Promise<void> {
+  await page
+    .waitForLoadState('networkidle', { timeout: NETWORK_IDLE_MS })
+    .catch(() => undefined)
+  const height = await page.evaluate(
+    () => document.documentElement.scrollHeight,
+  )
+  for (let y = 0; y < height; y += WHEEL_STEP_PX) {
+    await page.mouse.wheel(0, WHEEL_STEP_PX)
+    await page.waitForTimeout(WHEEL_PAUSE_MS)
+  }
+  await page.evaluate(() => window.scrollTo(0, 0))
+  await page.waitForTimeout(SETTLE_MS)
+  await hideFixedLayers(page)
+}
+
+/**
+ * Runs again before every shot as well as once in preparation, since a consent
+ * banner commonly mounts on a timer after load and a single pass misses it.
+ * Starts at the root element rather than the body, since a consent manager
+ * can attach its host straight to `<html>`, and walks into open shadow roots,
+ * where such widgets mount and a document-level query never reaches. A closed
+ * root stays out of reach.
+ */
+async function hideFixedLayers(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const hide = (root: ParentNode): void => {
+      for (const element of root.querySelectorAll<HTMLElement>('*')) {
+        const position = getComputedStyle(element).position
+        if (position === 'fixed' || position === 'sticky') {
+          element.style.setProperty('visibility', 'hidden', 'important')
+        }
+        if (element.shadowRoot) hide(element.shadowRoot)
+      }
+    }
+    hide(document.documentElement)
+  })
+}
+
+/**
+ * Walks down from the root, splitting any block taller than the split
+ * threshold into its full-width children, and tags each block it keeps so a
+ * later step can find it again. Null when the root selector matched nothing.
+ *
+ * With no root named, `main` is tried and then `body`, since track 218 found
+ * `main` on every site it tried and a page without one still has a body.
+ */
+export async function splitBlocks(
+  page: Page,
+  root: string | undefined,
+): Promise<Block[] | null> {
+  return page.evaluate(
+    ({ root, attribute, splitViewports, minChildHeight, minWidthShare }) => {
+      const start = root
+        ? document.querySelector(root)
+        : (document.querySelector('main') ?? document.body)
+      if (!start) return null
+
+      const viewportWidth = window.innerWidth
+      const viewportHeight = window.innerHeight
+      const measure = (element: Element) => {
+        const rect = element.getBoundingClientRect()
+        return {
+          element,
+          top: Math.round(rect.top + window.scrollY),
+          height: Math.round(rect.height),
+          width: Math.round(rect.width),
+        }
+      }
+      type Measured = ReturnType<typeof measure>
+      const split = (element: Element): Measured[] => {
+        const box = measure(element)
+        if (box.height <= viewportHeight * splitViewports) return [box]
+        const children = [...element.children]
+          .map(measure)
+          .filter(
+            (child) =>
+              child.height >= minChildHeight &&
+              child.width >= viewportWidth * minWidthShare,
+          )
+        if (children.length === 0) return [box]
+        return children.flatMap((child) => split(child.element))
+      }
+
+      return split(start)
+        .filter((box) => box.height > 0)
+        .map((box, index) => {
+          box.element.setAttribute(attribute, String(index))
+          return { index, top: box.top, height: box.height }
+        })
+    },
+    {
+      root,
+      attribute: SECTION_ATTRIBUTE,
+      splitViewports: SPLIT_VIEWPORTS,
+      minChildHeight: MIN_CHILD_HEIGHT,
+      minWidthShare: MIN_WIDTH_SHARE,
+    },
+  )
+}
+
+/**
+ * Joins each block shorter than the merge threshold to the section above it,
+ * so a page built of thin bands comes back as the sections a person would
+ * name. A short first block has nothing above it and joins the one below.
+ *
+ * A merge that would carry a section past the shot cap starts a new section
+ * instead, so a run of bands under a tall block is not cut off by the cap.
+ */
+export function mergeBlocks(
+  blocks: readonly Block[],
+  minHeight: number = MERGE_BELOW_PX,
+  maxHeight: number = MAX_SECTION_PX,
+): Section[] {
+  const sections: Section[] = []
+  let leading: Block[] = []
+  for (const block of blocks) {
+    const last = sections.at(-1)
+    if (last === undefined) {
+      if (leading.length && spanOf([...leading, block]).height > maxHeight) {
+        sections.push(spanOf(leading))
+        leading = []
+      }
+      leading.push(block)
+      const span = spanOf(leading)
+      if (span.height >= minHeight) {
+        sections.push(span)
+        leading = []
+      }
+      continue
+    }
+    const merged = spanOf([last, block])
+    if (block.height < minHeight && merged.height <= maxHeight) {
+      sections[sections.length - 1] = {
+        ...merged,
+        blocks: [...last.blocks, block.index],
+      }
+    } else {
+      sections.push(spanOf([block]))
+    }
+  }
+  if (leading.length) sections.push(spanOf(leading))
+  return sections
+}
+
+function spanOf(parts: readonly (Block | Section)[]): Section {
+  const top = Math.min(...parts.map((part) => part.top))
+  const bottom = Math.max(...parts.map((part) => part.top + part.height))
+  const blocks = parts.flatMap((part) =>
+    'blocks' in part ? part.blocks : [part.index],
+  )
+  return { blocks, top, height: bottom - top }
+}
+
+/** The clip a section's shot takes, measured again after it scrolled in. */
+export interface Clip {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+/**
+ * Scrolls a section's first block into view so a reveal-on-view block paints,
+ * waits for it to settle, then measures the union of its blocks in document
+ * coordinates, cut at the shot cap. Measured after the scroll rather than
+ * taken from the split, since content loading above can move it.
+ */
+export async function revealSection(
+  page: Page,
+  section: Section,
+): Promise<Clip | null> {
+  const first = section.blocks[0]
+  if (first === undefined) return null
+  await page
+    .locator(`[${SECTION_ATTRIBUTE}="${first}"]`)
+    .scrollIntoViewIfNeeded()
+    .catch(() => undefined)
+  await page.waitForTimeout(SETTLE_MS)
+  await hideFixedLayers(page)
+  return page.evaluate(
+    ({ attribute, blocks, cap }) => {
+      const rects = blocks
+        .map((index) => document.querySelector(`[${attribute}="${index}"]`))
+        .filter((element): element is Element => element !== null)
+        .map((element) => element.getBoundingClientRect())
+      if (!rects.length) return null
+      const left = Math.min(...rects.map((rect) => rect.left))
+      const right = Math.max(...rects.map((rect) => rect.right))
+      const top = Math.min(...rects.map((rect) => rect.top))
+      const bottom = Math.max(...rects.map((rect) => rect.bottom))
+      const width = Math.round(right - left)
+      const height = Math.round(Math.min(bottom - top, cap))
+      if (width <= 0 || height <= 0) return null
+      return {
+        x: Math.max(0, Math.round(left + window.scrollX)),
+        y: Math.max(0, Math.round(top + window.scrollY)),
+        width,
+        height,
+      }
+    },
+    {
+      attribute: SECTION_ATTRIBUTE,
+      blocks: section.blocks,
+      cap: MAX_SECTION_PX,
+    },
+  )
+}

package/src/claude/cases/misc.ts

@@ -26,6 +26,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Show me a few different treatments for this callout so I can pick one by looking.',
     expect: 'design-pick',
   },
+  {
+    prompt:
+      'Before we draft the landing page, pull references from linear.app so the round has a real site to look at.',
+    expect: 'design-references',
+  },
   {
     prompt:
       'Which layer of this landing page should I settle first, and what has to stay constant across it?',

package/src/claude/cases/setup.ts

@@ -35,6 +35,13 @@ export const SETUP_CASES: readonly SkillCase[] = [
       'Check that the dev server actually starts and the end-to-end suite passes against the scaffold.',
     expect: 'target-setup',
   },
+  // An empty folder has no files for setup's detection to read, which is what
+  // separates starting a project from bootstrapping one that already exists.
+  {
+    prompt:
+      'This folder is empty, start a new astro project in it and get it on the toolkit.',
+    expect: 'target-scaffold',
+  },
   {
     prompt:
       "Before I run this sync, tell me exactly what it's going to overwrite.",

package/src/commands/capture.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs'
+import { existsSync, statSync } from 'node:fs'
 import { relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import {
@@ -32,6 +32,7 @@ const DEFAULT_SOURCE = 'assets'
 type Renderer = typeof import('@/capture/render')
 type CaptureResult = Awaited<ReturnType<Renderer['captureSources']>>[number]
 type ColorScheme = import('@/capture/render').ColorScheme
+type SectionsResult = import('@/capture/render').SectionsResult
 
 const COLOR_SCHEMES: readonly ColorScheme[] = ['light', 'dark']
 
@@ -56,7 +57,15 @@ export function register(program: Command): void {
       '-o, --out <path>',
       'Output directory for a file source, or the destination PNG for a URL source; defaults beside the source',
     )
-    .option('-s, --selector <selector>', 'Element to capture')
+    .option(
+      '-s, --selector <selector>',
+      'Element to capture, or with --sections the root to split, defaulting to main and then body',
+    )
+    .option(
+      '--sections',
+      'Write one PNG per section of one page into the --out folder, in page order',
+    )
+    .option('--json', 'With --sections, print the result as one JSON record')
     .option(
       '--width <px>',
       'Viewport width in pixels, so a media query resolves at that width',
@@ -69,8 +78,8 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'The selector has no default, since the element to crop to belongs to the',
-        'page. Each element holding text inside it must resolve its first font',
+        'Outside --sections the selector has no default, since the element to',
+        'crop to belongs to the page. Each element holding text inside it must resolve its first font',
         'family, and a generic keyword such as monospace or system-ui fails,',
         'since it resolves differently on each machine. The user agent sets',
         'monospace on pre, code, kbd, and samp, so each needs its own',
@@ -81,6 +90,21 @@ export function register(program: Command): void {
         'a light or dark class on the root, so a stylesheet keyed on any of the',
         'three renders that theme. Run it once per scheme with its own --out.',
         '',
+        '--sections takes one HTML file or URL and needs --out naming a folder.',
+        'It wheels down the page so lazy content loads, hides fixed and sticky',
+        'layers, splits any block taller than 1.6 viewports into its children,',
+        'and joins a block under 400px to the one above. Each shot is cut at',
+        '2400px and writes section-NN.png with its stamp. A generic or missing',
+        'font family is recorded rather than refused. --json prints',
+        '{ source, sections: [{ index, path, top, height }], failed: [{ index,',
+        'reason }], fonts: { generic, missing } }, or { source, reason } when',
+        'the page fails whole.',
+        '',
+        'Examples:',
+        '  canon capture assets --selector .window',
+        '  canon capture https://example.com --sections --out refs/example --width 1440',
+        '  canon capture https://example.com --sections --out refs/example --json',
+        '',
       ].join('\n'),
     )
     .action(
@@ -91,8 +115,20 @@ export function register(program: Command): void {
           selector?: string
           width?: string
           colorScheme?: string
+          sections?: boolean
+          json?: boolean
         },
       ): Promise<void> => {
+        if (opts.json && !opts.sections) {
+          frameError('--json applies to --sections. See canon capture --help.')
+          process.exitCode = 1
+          return
+        }
+        if (opts.sections) {
+          await captureSectionsAction(source, opts)
+          return
+        }
+
         /**
          * Refused rather than defaulted, and refused ahead of every other
          * check, so the message names the invocation rather than whatever the
@@ -176,6 +212,115 @@ export function register(program: Command): void {
     )
 }
 
+interface SectionFlags {
+  out?: string
+  selector?: string
+  width?: string
+  colorScheme?: string
+  json?: boolean
+}
+
+/**
+ * Section mode reads `--out` as a folder for every source kind, so it is
+ * required here even for a file source, and a directory source is refused,
+ * since a section run describes one page.
+ */
+async function captureSectionsAction(
+  source: string,
+  opts: SectionFlags,
+): Promise<void> {
+  const width = parseWidth(opts.width)
+  if (Number.isNaN(width)) {
+    frameError(
+      `--width takes a whole number of pixels of 1 or more, got ${opts.width}.`,
+    )
+    process.exitCode = 1
+    return
+  }
+  const colorScheme = parseColorScheme(opts.colorScheme)
+  if (colorScheme === null) {
+    frameError(
+      `--color-scheme takes ${COLOR_SCHEMES.join(' or ')}, got ${JSON.stringify(opts.colorScheme)}.`,
+    )
+    process.exitCode = 1
+    return
+  }
+  if (!opts.out) {
+    frameError('--sections needs --out naming the folder the shots go in.')
+    process.exitCode = 1
+    return
+  }
+
+  const isUrl = isUrlSource(source)
+  const sourcePath = isUrl ? source : resolve(process.cwd(), source)
+  if (!isUrl && !existsSync(sourcePath)) {
+    frameError(`${source} not found`)
+    process.exitCode = 1
+    return
+  }
+  if (!isUrl && statSync(sourcePath).isDirectory()) {
+    frameError(
+      `--sections takes one HTML file or URL, and ${source} is a directory.`,
+    )
+    process.exitCode = 1
+    return
+  }
+
+  const json = opts.json ?? false
+  if (!json) intro('Capture sections')
+  let result: SectionsResult
+  try {
+    const renderer = await import('@/capture/render')
+    result = await renderer.captureSections(sourcePath, {
+      outDir: resolve(process.cwd(), opts.out),
+      root: opts.selector,
+      width,
+      colorScheme,
+    })
+  } catch (error) {
+    if (json) {
+      logError(error instanceof Error ? error.message : String(error))
+    } else {
+      reportInFrame(error)
+    }
+    process.exitCode = 1
+    return
+  }
+
+  if (result.status === 'failed') {
+    if (json) {
+      process.stdout.write(
+        `${JSON.stringify({ source: result.source, reason: result.reason })}\n`,
+      )
+    }
+    logError(`${displayPath(result.source)}: ${result.reason}`)
+    if (!json) outro()
+    process.exitCode = 1
+    return
+  }
+
+  const { source: page, sections, failed, fonts } = result
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify({ source: page, sections, failed, fonts })}\n`,
+    )
+  }
+  for (const shot of json ? [] : sections) {
+    logInfo(`${displayPath(shot.path)} top ${shot.top} height ${shot.height}`)
+  }
+  for (const fault of failed) {
+    logError(`section ${fault.index}: ${fault.reason}`)
+  }
+  if (!json && fonts.generic.length) {
+    logWarn(`generic families drawn: ${fonts.generic.join(', ')}`)
+  }
+  if (!json && fonts.missing.length) {
+    logWarn(`families not installed: ${fonts.missing.join(', ')}`)
+  }
+  if (!json) outro()
+  if (failed.length || !sections.length) process.exitCode = 1
+}
+
 /**
  * Undefined for an absent flag and `NaN` for a value that is not a positive
  * integer, so the caller can tell no width from a bad one.