@erclx/canon 5.25.0 → 5.26.0

package/src/canvas/client/inspector.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource preact */
 import type { JSX } from 'preact'
 import { addressOf, elementAt, excerpt, isRawText } from '@/canvas/address'
+import { ColorField } from '@/canvas/client/inspector/color-field'
 import {
   Field,
   ReadOnlyField,
@@ -10,6 +11,7 @@ import { Section } from '@/canvas/client/inspector/section'
 import {
   clampScrub,
   displayValue,
+  parseColor,
   toCssValue,
 } from '@/canvas/client/inspector/values'
 import {
@@ -75,15 +77,10 @@ const TYPE_FIELDS: readonly StyleField[] = [
   { label: 'weight', glyph: 'Wt', property: 'font-weight' },
 ]
 
-const FILL_FIELDS: readonly StyleField[] = [
-  { label: 'color', glyph: 'Fg', property: 'color' },
-  {
-    label: 'background',
-    glyph: 'Bg',
-    property: 'background-color',
-    placeholder: 'None',
-  },
-]
+const FILL_FIELDS = [
+  { label: 'color', property: 'color' },
+  { label: 'background', property: 'background-color' },
+] as const
 
 function inlineValue(element: Element, property: string): string {
   return 'style' in element
@@ -127,8 +124,10 @@ function isRawInline(element: Element, property: string): boolean {
  * an edit starts from what the operator sees.
  */
 function currentValue(element: Element, property: string): string {
-  const inline = inlineValue(element, property)
-  if (inline) return inline
+  return inlineValue(element, property) || computedValue(element, property)
+}
+
+function computedValue(element: Element, property: string): string {
   return (
     element.ownerDocument.defaultView
       ?.getComputedStyle(element)
@@ -136,6 +135,19 @@ function currentValue(element: Element, property: string): string {
   )
 }
 
+/**
+ * The color a token paints in the frame, read off a probe rather than the
+ * token's text, since a token's value may itself be a `var()` or a mix.
+ */
+function tokenPaint(doc: Document, name: string): string {
+  const probe = doc.createElement('span')
+  probe.style.setProperty('color', `var(${name})`)
+  ;(doc.body ?? doc.documentElement).append(probe)
+  const painted = computedValue(probe, 'color')
+  probe.remove()
+  return painted
+}
+
 function holdsTextAlone(element: Element): boolean {
   const tag = element.tagName.toLowerCase()
   return element.children.length === 0 && !VOID.has(tag) && !isRawText(tag)
@@ -146,46 +158,6 @@ function elementName(element: Element): string {
   return [tag, ...element.classList].join('.')
 }
 
-interface TokenPickerProps {
-  readonly label: string
-  readonly initial: string
-  readonly isBusy: boolean
-  readonly onCommit: (value: string) => void
-}
-
-function TokenPicker({
-  label,
-  initial,
-  isBusy,
-  onCommit,
-}: TokenPickerProps): JSX.Element | null {
-  const colors =
-    tokens.value?.groups?.find((group) => group.kind === 'color')?.tokens ?? []
-  if (colors.length === 0) return null
-  return (
-    <select
-      class="token-picker"
-      aria-label={`${label} token`}
-      title="Pick a project token"
-      value={
-        colors.some((token) => initial === `var(${token.name})`) ? initial : ''
-      }
-      disabled={isBusy}
-      onChange={(event) => {
-        const { value } = event.currentTarget
-        if (value !== '' && value !== initial) onCommit(value)
-      }}
-    >
-      <option value="">Token</option>
-      {colors.map((token) => (
-        <option key={token.name} value={`var(${token.name})`}>
-          {token.name}
-        </option>
-      ))}
-    </select>
-  )
-}
-
 function ElementFields({
   node,
   doc,
@@ -206,6 +178,10 @@ function ElementFields({
   const rect = node.getBoundingClientRect()
   const font = currentValue(node, 'font-family')
   const text = node.textContent ?? ''
+  const colorTokens =
+    tokens.value?.groups
+      ?.find((group) => group.kind === 'color')
+      ?.tokens.map((token) => token.name) ?? []
 
   /**
    * Previews into the frame's own inline style and writes through the same
@@ -272,25 +248,26 @@ function ElementFields({
       </Section>
       <Section title="Fill">
         {FILL_FIELDS.map((field) => {
-          const initial = currentValue(node, field.property)
+          const painted = computedValue(node, field.property)
+          const inline = inlineValue(node, field.property)
+          /*
+           * An inline value the picker cannot read stays as written. Reading
+           * the computed color in its place would show a token-following
+           * value as a literal, and an opacity edit would freeze it.
+           */
           return (
-            <div key={field.property} class="fill-row is-wide">
-              {styleField(field)}
-              {isRawInline(node, field.property) ? (
-                <span
-                  class="raw"
-                  title="Set as a raw value, so it will not follow the theme. Pick a token to fix it"
-                >
-                  raw
-                </span>
-              ) : null}
-              <TokenPicker
-                label={field.label}
-                initial={initial}
-                isBusy={isBusy}
-                onCommit={commit(field.property)}
-              />
-            </div>
+            <ColorField
+              key={field.property}
+              label={field.label}
+              color={parseColor(inline || painted)}
+              text={inline || painted}
+              painted={painted}
+              tokens={colorTokens}
+              paint={(name) => tokenPaint(doc, name)}
+              isRaw={isRawInline(node, field.property)}
+              isBusy={isBusy}
+              onCommit={commit(field.property)}
+            />
           )
         })}
       </Section>

package/src/capture/render.ts

@@ -2,9 +2,13 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, dirname } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { chromium } from 'playwright-core'
-import type { Browser, Page } from 'playwright-core'
+import type { Browser, Locator, Page } from 'playwright-core'
 import type { CaptureSource } from '@/capture/sources'
-import { primaryFontFamily, resolveCaptureSources } from '@/capture/sources'
+import {
+  isGenericFamily,
+  resolveCaptureSources,
+  textFamilies,
+} from '@/capture/sources'
 import { formatStamp, hashSource, stampPath } from '@/capture/stamp'
 
 /**
@@ -97,15 +101,22 @@ async function captureOne(
     }
 
     await page.evaluate(() => document.fonts.ready.then(() => undefined))
-    const family = primaryFontFamily(
-      await element.evaluate((node) => getComputedStyle(node).fontFamily),
-    )
-    if (family && !(await resolvesFont(page, family))) {
+    const declarations = await renderedTextFamilies(element)
+    const generic = declarations.find(isGenericFamily)
+    if (generic !== undefined) {
       return failed(
         source,
-        `${family} is not installed, so the capture would rewrap against a fallback`,
+        `${generic.split(',')[0]?.trim()} is a generic family that resolves differently per machine, so name a real font`,
       )
     }
+    for (const family of textFamilies(declarations)) {
+      if (!(await resolvesFont(page, family))) {
+        return failed(
+          source,
+          `${family} is not installed, so the capture would rewrap against a fallback`,
+        )
+      }
+    }
 
     mkdirSync(dirname(source.pngPath), { recursive: true })
     const png = await element.screenshot({ omitBackground: true })
@@ -170,6 +181,33 @@ function failed(source: CaptureSource, reason: string): CaptureResult {
   return { status: 'failed', source: sourceIdentifier(source), reason }
 }
 
+/**
+ * The computed families of the captured element and of each element under it
+ * holding a non-blank text node of its own that draws a box, which is the text
+ * the screenshot shows. Testing the text node's box rather than the element's
+ * keeps out `<style>`, `<script>`, `<title>`, and anything hidden, whose
+ * computed family is the browser default and would refuse every source that
+ * styles a descendant rather than the root, and keeps in text directly inside a
+ * `display: contents` element, which draws no box of its own.
+ *
+ * Returns nothing when no element holds text, since a font cannot rewrap text
+ * that is not there, so a container of iframes skips the probe.
+ */
+async function renderedTextFamilies(element: Locator): Promise<string[]> {
+  return element.evaluate((root) => {
+    const range = document.createRange()
+    const holdsText = (node: Element): boolean =>
+      [...node.childNodes].some((child) => {
+        if (child.nodeType !== Node.TEXT_NODE) return false
+        if ((child.textContent ?? '').trim() === '') return false
+        range.selectNodeContents(child)
+        return range.getClientRects().length > 0
+      })
+    const texts = [root, ...root.querySelectorAll('*')].filter(holdsText)
+    return texts.map((node) => getComputedStyle(node).fontFamily)
+  })
+}
+
 /**
  * Compares the family's text metrics against a family that cannot exist. Equal
  * widths mean the browser fell through to its default for both, which is the

package/src/capture/sources.ts

@@ -66,3 +66,46 @@ export function primaryFontFamily(declaration: string): string {
   const first = declaration.split(',')[0]?.trim() ?? ''
   return first.replace(/^['"]|['"]$/g, '')
 }
+
+/**
+ * The CSS generic family keywords. A generic names no font, so each machine
+ * maps it to whatever it has, and a capture measured against one cannot
+ * reproduce on another.
+ */
+export const GENERIC_FAMILIES: ReadonlySet<string> = new Set([
+  'serif',
+  'sans-serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'ui-serif',
+  'ui-sans-serif',
+  'ui-monospace',
+  'ui-rounded',
+  'math',
+  'emoji',
+  'fangsong',
+])
+
+/**
+ * Whether the first family of a computed `font-family` is a generic keyword.
+ * Takes the raw declaration rather than `primaryFontFamily`'s result, since
+ * quoting is what separates the keyword from a family that happens to share its
+ * name, and the stripped form has lost it. Keywords match case-insensitively.
+ */
+export function isGenericFamily(declaration: string): boolean {
+  const first = declaration.split(',')[0]?.trim() ?? ''
+  return GENERIC_FAMILIES.has(first.toLowerCase())
+}
+
+/**
+ * Reduces the computed `font-family` of each rendered text element to the
+ * distinct families a capture has to prove resolved, in document order, so a
+ * frame that sets its font on any ancestor of its text is checked against the
+ * face the text actually draws in.
+ */
+export function textFamilies(declarations: readonly string[]): string[] {
+  const families = declarations.map(primaryFontFamily).filter(Boolean)
+  return [...new Set(families)]
+}

package/src/census/count.ts

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises'
 import { extname, join } from 'node:path'
-import { isBinary } from '@/binary'
+import { isBinary } from '@/sweep/binary'
 import { listRepositoryFiles } from '@/git-files'
 
 export type CensusRefusal = 'no-git'

package/src/claude/cases/workflow.ts

@@ -146,6 +146,11 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
       'Which of our docs have gone stale, grown too long, or ended up in the wrong file?',
     expect: 'document-health',
   },
+  {
+    prompt:
+      'Are our requirements and architecture docs still true, and when were they last reviewed?',
+    expect: 'document-health',
+  },
   {
     prompt: 'Open a new entry on the task board for this piece of work.',
     expect: 'task-board',

package/src/claude/seeds.ts

@@ -3,7 +3,7 @@ import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 import { copyPreservingMode } from '@/copy'
 import { creationRel, isRecordEntry } from '@/record-root'
-import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
+import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
 import { SURFACE_ENTRIES, surfaceDir } from '@/surface-root'
 
 const SEEDS_DIR = join('tooling', 'claude', 'seeds')

package/src/claude/skills-audit.ts

@@ -40,6 +40,21 @@ export const PRACTICE_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'code-craft'),
   join(SHIPPED_CORPUS, 'build-in-slices'),
   join(SHIPPED_CORPUS, 'deprecation-migration'),
+  join(SHIPPED_CORPUS, 'search-craft'),
+  join(SHIPPED_CORPUS, 'video-craft'),
+]
+
+/**
+ * Every skill carrying the source ledger, being the practice skills and the
+ * skills that teach a craft without the practice closing sections. Kept apart
+ * from `PRACTICE_SKILLS` so citing sources never forces those sections onto a
+ * skill whose body is not shaped around a practice a session cuts short.
+ */
+export const LEDGER_SKILLS: readonly string[] = [
+  ...PRACTICE_SKILLS,
+  join(SHIPPED_CORPUS, 'design-taste'),
+  join(SHIPPED_CORPUS, 'write-human'),
+  join(SHIPPED_CORPUS, 'test-first'),
 ]
 
 /** The closing H2s a practice skill carries, matched exactly outside fences. */
@@ -52,6 +67,16 @@ export const PRACTICE_SECTIONS: readonly string[] = [
 /** The source ledger every practice skill carries beside its body. */
 export const PRACTICE_LEDGER = join('references', 'adopted.md')
 
+/**
+ * The line count past which a reference opens with a contents list, from
+ * Anthropic's skill authoring guidance. Counted over the whole file the way
+ * `wc -l` counts it, so "over 100" holds at 101 and not at 100.
+ */
+export const CONTENTS_THRESHOLD = 100
+
+/** The H2 a long reference opens with, matched exactly outside fences. */
+export const CONTENTS_SECTION = 'Contents'
+
 /**
  * The one reason this audit refuses. A project carrying neither corpus is the
  * ordinary state of a target that has not adopted either skills convention,
@@ -102,6 +127,7 @@ export interface SkillsAudit {
   readonly requirementSections: readonly SkillFinding[]
   readonly datedProvenance: readonly SkillFinding[]
   readonly practiceShape: readonly SkillFinding[]
+  readonly referenceContents: readonly SkillFinding[]
 }
 
 interface SkillSource {
@@ -126,6 +152,7 @@ interface SkillSource {
 interface SkillText {
   readonly rel: string
   readonly text: string
+  readonly isReference: boolean
 }
 
 /**
@@ -177,6 +204,9 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
       ),
       ...sources.flatMap(practiceFindings),
     ],
+    referenceContents: sources.flatMap((source) =>
+      source.bodies.flatMap(contentsFindings),
+    ),
   }
 }
 
@@ -233,16 +263,14 @@ async function readSkill(
     description: declared(readField(fields, 'description')),
     requirementHeadings:
       requirement === undefined ? undefined : headings(requirement),
-    sections: bodyLines(body)
-      .filter((line) => !line.fenced)
-      .map((line) => SECTION.exec(line.text)?.[1])
-      .filter((text): text is string => text !== undefined),
+    sections: sectionsOf(body),
     hasLedger: existsSync(join(skillDir, PRACTICE_LEDGER)),
     bodies: [
-      { rel: join(skillRel, 'SKILL.md'), text: body },
+      { rel: join(skillRel, 'SKILL.md'), text: body, isReference: false },
       ...references.map((path, index) => ({
         rel: join(skillRel, path),
         text: referenceTexts[index] ?? '',
+        isReference: true,
       })),
     ],
   }
@@ -257,6 +285,14 @@ function declared(value: string | undefined): string | undefined {
   return trimmed === undefined || trimmed === '' ? undefined : trimmed
 }
 
+/** Every H2 outside a fence, the one level both exact-section checks read. */
+function sectionsOf(source: string): string[] {
+  return bodyLines(source)
+    .filter((line) => !line.fenced)
+    .map((line) => SECTION.exec(line.text)?.[1])
+    .filter((text): text is string => text !== undefined)
+}
+
 function headings(source: string): string[] {
   return source
     .split('\n')
@@ -311,7 +347,7 @@ function missingPracticeSkills(
 ): SkillFinding[] {
   if (!hasShippedCorpus) return []
   const found = new Set(sources.map((source) => source.rel))
-  return PRACTICE_SKILLS.filter((rel) => !found.has(rel)).map((rel) => ({
+  return LEDGER_SKILLS.filter((rel) => !found.has(rel)).map((rel) => ({
     rel,
     detail: 'missing skill: no folder under the shipped corpus',
   }))
@@ -323,14 +359,15 @@ function missingPracticeSkills(
  * standard never names.
  */
 function practiceFindings(source: SkillSource): SkillFinding[] {
-  if (!PRACTICE_SKILLS.includes(source.rel)) return []
-
-  const sections = PRACTICE_SECTIONS.filter(
-    (section) => !source.sections.includes(section),
-  ).map((section) => ({
-    rel: source.rel,
-    detail: `missing section: ${section}`,
-  }))
+  if (!LEDGER_SKILLS.includes(source.rel)) return []
+
+  const isPractice = PRACTICE_SKILLS.includes(source.rel)
+  const sections = (isPractice ? PRACTICE_SECTIONS : [])
+    .filter((section) => !source.sections.includes(section))
+    .map((section) => ({
+      rel: source.rel,
+      detail: `missing section: ${section}`,
+    }))
   const ledger = source.hasLedger
     ? []
     : [{ rel: source.rel, detail: `missing ledger: ${PRACTICE_LEDGER}` }]
@@ -338,6 +375,23 @@ function practiceFindings(source: SkillSource): SkillFinding[] {
   return [...sections, ...ledger]
 }
 
+/**
+ * Reads references alone, since `SKILL.md` carries its own length checkpoint
+ * and no contents rule. Frontmatter counts toward the length, so the count a
+ * finding names is the one `wc -l` prints beside it.
+ */
+function contentsFindings(source: SkillText): SkillFinding[] {
+  if (!source.isReference) return []
+
+  const lines = source.text.replace(/\n$/, '').split('\n').length
+  if (lines <= CONTENTS_THRESHOLD) return []
+  if (sectionsOf(source.text).includes(CONTENTS_SECTION)) return []
+
+  return [
+    { rel: source.rel, detail: `${lines} lines, no ## ${CONTENTS_SECTION}` },
+  ]
+}
+
 /**
  * A date inside a fence or a code span is example data a reader is shown, such
  * as a sample frontmatter block, so only prose outside both is read.

package/src/client-commands.ts

@@ -1,4 +1,4 @@
-import { escapeForPattern, isMarked } from '@/exempt-marker'
+import { escapeForPattern, isMarked } from '@/sweep/exempt-marker'
 
 /**
  * A client command this repository quotes, with the argument spelling every

package/src/commands/claude.ts

@@ -24,8 +24,11 @@ import { listSeeds, readSeedContents } from '@/claude/seeds-list'
 import {
   auditExitCode,
   auditSkills,
+  CONTENTS_SECTION,
+  CONTENTS_THRESHOLD,
   CORPORA,
   DESCRIPTION_LIMIT,
+  LEDGER_SKILLS,
   PRACTICE_LEDGER,
   PRACTICE_SECTIONS,
   PRACTICE_SKILLS,
@@ -1398,6 +1401,7 @@ async function runSkillsAudit(
     reportRequirementShape(report)
     reportProvenance(report)
     reportPracticeShape(report)
+    reportReferenceContents(report)
     reportUnmeasured()
     outro()
   }
@@ -1421,13 +1425,16 @@ async function runSkillsAudit(
           requirementSections: report.requirementSections,
           datedProvenance: report.datedProvenance,
           practiceShape: report.practiceShape,
+          referenceContents: report.referenceContents,
         },
         checkpoints: {
           descriptionLimit: DESCRIPTION_LIMIT,
           requirementSections: REQUIREMENT_SECTIONS,
           corpora: CORPORA,
           practiceSkills: PRACTICE_SKILLS,
+          ledgerSkills: LEDGER_SKILLS,
           practiceSections: PRACTICE_SECTIONS,
+          contentsThreshold: CONTENTS_THRESHOLD,
         },
       })}\n`,
     )
@@ -1626,10 +1633,10 @@ function reportProvenance(report: SkillsAudit): void {
 function reportPracticeShape(report: SkillsAudit): void {
   logStep('Practice shape')
   logInfo(
-    `A listed practice skill closes with ${PRACTICE_SECTIONS.map((section) => `## ${section}`).join(', ')}, and carries ${PRACTICE_LEDGER}.`,
+    `A listed practice skill closes with ${PRACTICE_SECTIONS.map((section) => `## ${section}`).join(', ')}, and every skill on the wider ledger list carries ${PRACTICE_LEDGER}.`,
   )
   logInfo(
-    `The list is kept here and names ${plural(PRACTICE_SKILLS.length, 'shipped skill')}, so a skill outside ${SHIPPED_CORPUS} is never read.`,
+    `Both lists are kept here and name ${plural(PRACTICE_SKILLS.length, 'practice skill')} and ${plural(LEDGER_SKILLS.length, 'ledger skill')}, so a skill outside ${SHIPPED_CORPUS} is never read.`,
   )
 
   if (report.practiceShape.length === 0) {
@@ -1643,6 +1650,24 @@ function reportPracticeShape(report: SkillsAudit): void {
   reportFindings(report.practiceShape)
 }
 
+/** Reports without failing the run, the same judgment the practice shape is. */
+function reportReferenceContents(report: SkillsAudit): void {
+  logStep('Reference contents')
+  logInfo(
+    `A reference over ${CONTENTS_THRESHOLD} lines opens with a ## ${CONTENTS_SECTION} list, matched exactly outside fences.`,
+  )
+
+  if (report.referenceContents.length === 0) {
+    logInfo('Every long reference opens with a contents list.')
+    return
+  }
+
+  logWarn(
+    `${plural(report.referenceContents.length, 'long reference')} with no contents list`,
+  )
+  reportFindings(report.referenceContents)
+}
+
 /**
  * Stated on every run, including the run where everything above passed. A
  * report that lists only what it measured reads as a verdict on the standard

package/src/commands/feedback.ts

@@ -7,11 +7,11 @@ import {
   deriveTitle,
   missingField,
   missingFieldMessage,
-} from '@/commands/feedback-format'
+} from '@/feedback/body'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { creationRel } from '@/record-root'
-import { createGithubIssue } from '@/github'
-import { issueFailureMessage } from '@/github-format'
+import { createGithubIssue } from '@/feedback/github'
+import { issueFailureMessage } from '@/feedback/github-format'
 import { frameError, frameSuccess, logWarn, palette } from '@/ui'
 
 function readStdin(): Promise<string> {