@erclx/canon 5.20.0 → 5.21.0

package/src/slides/convert/master.ts

@@ -0,0 +1,195 @@
+import type PptxGenJS from 'pptxgenjs'
+import {
+  BAND_SLOTS,
+  type Band,
+  type BandSlot,
+  type DeckConfig,
+} from '@/slides/convert/deck'
+import { fontFace } from '@/slides/convert/shapes'
+
+/**
+ * The deck's master, built from the project's own tokens as the page computed
+ * them rather than from the toolkit's design module. A slide that hides or
+ * overrides a band takes a master without that band, so editing the footer
+ * once in PowerPoint reaches every slide still on the master's own.
+ */
+
+export interface DeckTheme {
+  readonly background: string
+  readonly ink: string
+  readonly muted: string
+  readonly accent: string
+  readonly face: string
+}
+
+/** What the first slide computed, read in the page by `readTheme`. */
+export interface ThemeReading {
+  /** Each role's `--color-*` value as hex, absent where none is declared. */
+  readonly tokens: {
+    readonly background?: string
+    readonly text?: string
+    readonly muted?: string
+    readonly accent?: string
+  }
+  readonly body: { readonly background: string; readonly color: string }
+  readonly fontFamily: string
+  /** Every declared `--color-*` property in sheet order, for chart series. */
+  readonly roles: readonly { readonly name: string; readonly hex: string }[]
+}
+
+export interface MasterBands {
+  readonly header: boolean
+  readonly footer: boolean
+}
+
+/** Intrinsic pixel size, which sets the mark's aspect inside its box. */
+export interface MarkSize {
+  readonly width: number
+  readonly height: number
+}
+
+const SLIDE_W = 13.333
+const MARGIN = 0.5
+const BAND_H = 0.4
+const HEADER_Y = 0.2
+const FOOTER_Y = 7.5 - 0.2 - BAND_H
+const SLOT_W = (SLIDE_W - 2 * MARGIN) / 3
+const NUMBER_W = 1
+const MARK_BOX = { w: 1.2, h: BAND_H }
+const BAND_PT = 10
+
+/**
+ * A missing role falls back to what the slide's body computed, never to the
+ * toolkit's palette, which would put Canon's colors on another project's deck.
+ */
+export function deckTheme(reading: ThemeReading): {
+  readonly theme: DeckTheme
+  readonly notices: readonly string[]
+} {
+  const { tokens, body } = reading
+  const missing = (
+    [
+      ['background', tokens.background],
+      ['text', tokens.text],
+      ['muted', tokens.muted],
+      ['accent', tokens.accent],
+    ] as const
+  )
+    .filter(([, value]) => value === undefined)
+    .map(([role]) => `--color-${role}`)
+  return {
+    theme: {
+      background: tokens.background ?? body.background,
+      ink: tokens.text ?? body.color,
+      muted: tokens.muted ?? body.color,
+      accent: tokens.accent ?? body.color,
+      face: fontFace(reading.fontFamily),
+    },
+    notices:
+      missing.length === 0
+        ? []
+        : [
+            `no ${missing.join(' or ')} token, so the deck master takes the slide body ${missing.length === 1 ? 'color for it' : 'color for them'}`,
+          ],
+  }
+}
+
+export function masterName(bands: MasterBands): string {
+  const parts = [bands.header && 'header', bands.footer && 'footer'].filter(
+    Boolean,
+  )
+  return parts.length === 0 ? 'canon-bare' : `canon-${parts.join('-')}`
+}
+
+const SLOT_ALIGN: Record<BandSlot, PptxGenJS.HAlign> = {
+  left: 'left',
+  center: 'center',
+  right: 'right',
+}
+
+/**
+ * One text object per filled slot. The master draws these for a band it
+ * carries, and a slide overriding a band draws its own through the same call.
+ */
+export function bandTexts(
+  band: Omit<Band, 'show'>,
+  kind: 'header' | 'footer',
+  theme: DeckTheme,
+  options: { readonly hasMark?: boolean } = {},
+): { readonly text: string; readonly options: PptxGenJS.TextPropsOptions }[] {
+  return BAND_SLOTS.flatMap((slot, index) => {
+    const text = band[slot]
+    if (!text) return []
+    const isMarkSlot = kind === 'header' && slot === 'right' && options.hasMark
+    return [
+      {
+        text,
+        options: {
+          x: MARGIN + index * SLOT_W,
+          y: kind === 'header' ? HEADER_Y : FOOTER_Y,
+          w: SLOT_W - (isMarkSlot ? MARK_BOX.w + 0.1 : 0),
+          h: BAND_H,
+          margin: 0,
+          align: SLOT_ALIGN[slot],
+          valign: 'middle',
+          fontFace: theme.face,
+          fontSize: BAND_PT,
+          color: kind === 'header' ? theme.ink : theme.muted,
+        },
+      },
+    ]
+  })
+}
+
+/** The right of the footer, which `deck.json` keeps free while numbers show. */
+export function slideNumberProps(theme: DeckTheme): PptxGenJS.SlideNumberProps {
+  return {
+    x: SLIDE_W - MARGIN - NUMBER_W,
+    y: FOOTER_Y,
+    w: NUMBER_W,
+    h: BAND_H,
+    margin: 0,
+    align: 'right',
+    valign: 'middle',
+    fontFace: theme.face,
+    fontSize: BAND_PT,
+    color: theme.accent,
+  }
+}
+
+function markImage(path: string, size: MarkSize): PptxGenJS.ImageProps {
+  const scale = Math.min(MARK_BOX.w / size.width, MARK_BOX.h / size.height)
+  const w = Math.round(size.width * scale * 1000) / 1000
+  const h = Math.round(size.height * scale * 1000) / 1000
+  return { path, x: SLIDE_W - MARGIN - w, y: HEADER_Y, w, h }
+}
+
+export function buildMaster(
+  deck: DeckConfig,
+  theme: DeckTheme,
+  bands: MasterBands,
+  markSize: MarkSize = { width: 1, height: 1 },
+): PptxGenJS.SlideMasterProps {
+  const hasHeader = bands.header && deck.header.show
+  const hasFooter = bands.footer && deck.footer.show
+  const hasMark = deck.mark !== undefined
+  const objects: NonNullable<PptxGenJS.SlideMasterProps['objects']> = [
+    ...(deck.mark ? [{ image: markImage(deck.mark, markSize) }] : []),
+    ...(hasHeader
+      ? bandTexts(deck.header, 'header', theme, { hasMark }).map((text) => ({
+          text,
+        }))
+      : []),
+    ...(hasFooter
+      ? bandTexts(deck.footer, 'footer', theme).map((text) => ({ text }))
+      : []),
+  ]
+  return {
+    title: masterName(bands),
+    background: { color: theme.background },
+    objects,
+    ...(hasFooter && deck.slideNumbers
+      ? { slideNumber: slideNumberProps(theme) }
+      : {}),
+  }
+}

package/src/slides/convert/shapes.ts

@@ -150,7 +150,7 @@ const PT_PER_PX = 0.75
 const inches = (px: number): number => px / PX_PER_INCH
 const points = (px: number): number => px * PT_PER_PX
 
-function position(box: Rect): PptxGenJS.PositionProps {
+export function position(box: Rect): PptxGenJS.PositionProps {
   return {
     x: inches(box.x),
     y: inches(box.y),

package/src/slides/convert/walk.ts

@@ -1,3 +1,5 @@
+import type { ChartRecord } from '@/slides/convert/chart'
+import type { ThemeReading } from '@/slides/convert/master'
 import type {
   BoxStyle,
   ElementRecord,
@@ -9,10 +11,34 @@ import type {
   TextRun,
 } from '@/slides/convert/shapes'
 
+/** How one slide treats a band the deck master draws. */
+export type BandOverride =
+  | { readonly kind: 'master' }
+  | { readonly kind: 'off' }
+  | {
+      readonly kind: 'override'
+      readonly left?: string
+      readonly center?: string
+      readonly right?: string
+    }
+
+/** What a slide declares about itself on `<body>` and in its notes. */
+export interface SlideMeta {
+  readonly notes?: string
+  readonly section?: string
+  readonly isHidden: boolean
+  readonly header: BandOverride
+  readonly footer: BandOverride
+  /** The `--color-text` the slide's `<body>` computes, as hex. */
+  readonly textToken?: string
+}
+
 /** What one laid-out slide hands back across `page.evaluate`. */
 export interface WalkedSlide {
   readonly background: Rgba
   readonly records: ElementRecord[]
+  readonly charts: ChartRecord[]
+  readonly meta: SlideMeta
 }
 
 /** Set on every walked element, so a screenshot finds the one a record names. */
@@ -27,7 +53,8 @@ export const ID_ATTRIBUTE = 'data-canon-id'
  * Text gathers along the inline flow. A block holding text takes every run its
  * inline descendants carry, so `<strong>` inside `<p>` is one shape with two
  * runs, while a block-level child is walked on its own. Images, SVGs, and
- * tables consume their whole subtree.
+ * tables consume their whole subtree. Speaker notes in `<aside class="notes">`
+ * and a chart's `<figure data-chart>` are read whole and never drawn as shapes.
  *
  * Each walked element is tagged with `idAttribute` set to its record id.
  */
@@ -293,10 +320,41 @@ export function walkSlide(idAttribute: string): WalkedSlide {
 
   const SKIPPED = new Set(['script', 'style', 'template', 'noscript', 'link'])
 
+  const cellText = (element: Element): string =>
+    (element.textContent ?? '').replace(/\s+/g, ' ').trim()
+
+  /** One line per block, so a paragraph break survives and no tag does. */
+  const notesText = (element: Element): string => {
+    const clone = element.cloneNode(true)
+    if (!(clone instanceof Element)) return ''
+    for (const br of Array.from(clone.querySelectorAll('br'))) {
+      br.replaceWith('\n')
+    }
+    for (const block of Array.from(
+      clone.querySelectorAll('p, li, div, blockquote, h1, h2, h3, h4, h5, h6'),
+    )) {
+      block.append('\n')
+    }
+    return (clone.textContent ?? '')
+      .split('\n')
+      .map((line) => line.replace(/\s+/g, ' ').trim())
+      .filter(Boolean)
+      .join('\n')
+  }
+
+  const notes: string[] = []
+  const charts: ChartRecord[] = []
+
   for (const element of Array.from(document.body.querySelectorAll('*'))) {
     if (consumed.has(element)) continue
     const tag = element.tagName.toLowerCase()
     if (SKIPPED.has(tag)) continue
+    if (tag === 'aside' && element.classList.contains('notes')) {
+      consumeSubtree(element)
+      const text = notesText(element)
+      if (text) notes.push(text)
+      continue
+    }
     if (!element.checkVisibility({ visibilityProperty: true })) continue
 
     const id = records.length + 1
@@ -313,6 +371,27 @@ export function walkSlide(idAttribute: string): WalkedSlide {
     ids.set(element, id)
     element.setAttribute(idAttribute, String(id))
 
+    if (tag === 'figure' && element.hasAttribute('data-chart')) {
+      consumeSubtree(element)
+      records.push({ ...base, kind: 'box' })
+      const table = element.querySelector('table')
+      const caption = element.querySelector('figcaption')
+      const title = caption ? cellText(caption) : ''
+      charts.push({
+        selector: base.selector,
+        box: bounds,
+        type: element.getAttribute('data-chart') ?? '',
+        hasLabels: element.hasAttribute('data-labels'),
+        ...(title ? { title } : {}),
+        rows: table
+          ? Array.from(table.rows).map((row) =>
+              Array.from(row.cells).map(cellText),
+            )
+          : [],
+      })
+      continue
+    }
+
     if (element instanceof HTMLImageElement) {
       records.push({
         ...base,
@@ -440,5 +519,111 @@ export function walkSlide(idAttribute: string): WalkedSlide {
         ? htmlGround
         : { hex: 'FFFFFF', alpha: 1 }
 
-  return { background, records }
+  const body = document.body
+  const band = (kind: 'header' | 'footer'): BandOverride => {
+    if (body.getAttribute(`data-${kind}`) === 'off') return { kind: 'off' }
+    const slots: { left?: string; center?: string; right?: string } = {}
+    for (const slot of ['left', 'center', 'right'] as const) {
+      const value = body.getAttribute(`data-${kind}-${slot}`)
+      if (value !== null) slots[slot] = value
+    }
+    return Object.keys(slots).length > 0
+      ? { kind: 'override', ...slots }
+      : { kind: 'master' }
+  }
+  const section = body.getAttribute('data-section')?.trim()
+  const textValue = getComputedStyle(body)
+    .getPropertyValue('--color-text')
+    .trim()
+  const meta: SlideMeta = {
+    ...(textValue ? { textToken: rgba(textValue).hex } : {}),
+    ...(notes.length > 0 ? { notes: notes.join('\n\n') } : {}),
+    ...(section ? { section } : {}),
+    isHidden:
+      body.hasAttribute('data-hidden') &&
+      body.getAttribute('data-hidden') !== 'false',
+    header: band('header'),
+    footer: band('footer'),
+  }
+
+  return { background, records, charts, meta }
+}
+
+/**
+ * Runs inside the laid-out page and reads the colors and face the deck master
+ * takes. Tokens come from `<html>`'s computed style, so a slide that switches
+ * theme on its own `<body>`, such as a dark cover, leaves the master on the
+ * project's root theme. The body supplies the fallback colors and the face.
+ * Serialized to source like `walkSlide`, so its helpers sit in its own body.
+ */
+export function readTheme(): ThemeReading {
+  const canvas = document.createElement('canvas')
+  canvas.width = 1
+  canvas.height = 1
+  const context = canvas.getContext('2d', { willReadFrequently: true })
+  const hex = (value: string): string | undefined => {
+    if (!context || !value || value === 'transparent') return undefined
+    context.clearRect(0, 0, 1, 1)
+    context.fillStyle = '#000000'
+    context.fillStyle = value
+    context.fillRect(0, 0, 1, 1)
+    const [r = 0, g = 0, b = 0, a = 0] = context.getImageData(0, 0, 1, 1).data
+    if (a === 0) return undefined
+    return [r, g, b]
+      .map((channel) => channel.toString(16).padStart(2, '0'))
+      .join('')
+      .toUpperCase()
+  }
+
+  const style = getComputedStyle(document.body)
+  const rootStyle = getComputedStyle(document.documentElement)
+  const token = (name: string): string | undefined => {
+    const value = rootStyle.getPropertyValue(name).trim()
+    return value ? hex(value) : undefined
+  }
+
+  const names: string[] = []
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRuleList
+    try {
+      rules = sheet.cssRules
+    } catch {
+      continue
+    }
+    for (const rule of Array.from(rules)) {
+      if (!(rule instanceof CSSStyleRule)) continue
+      for (const name of Array.from(rule.style)) {
+        if (name.startsWith('--color-') && !names.includes(name)) {
+          names.push(name)
+        }
+      }
+    }
+  }
+
+  const tokens: {
+    background?: string
+    text?: string
+    muted?: string
+    accent?: string
+  } = {}
+  for (const role of ['background', 'text', 'muted', 'accent'] as const) {
+    const value = token(`--color-${role}`)
+    if (value) tokens[role] = value
+  }
+
+  return {
+    tokens,
+    body: {
+      background:
+        hex(style.backgroundColor) ??
+        hex(getComputedStyle(document.documentElement).backgroundColor) ??
+        'FFFFFF',
+      color: hex(style.color) ?? '000000',
+    },
+    fontFamily: style.fontFamily,
+    roles: names.flatMap((name) => {
+      const value = token(name)
+      return value ? [{ name, hex: value }] : []
+    }),
+  }
 }

package/src/tasks/record.ts

@@ -512,12 +512,18 @@ export async function recordPlan(
  * line, so the merge of an earlier slice cannot archive the task in the window
  * before this branch's own number is recorded. A rerun that ticks nothing adds
  * no marker, since its branch has already recorded or is already listed.
+ *
+ * `branchPulls` holds the pull request numbers the branch's own head carries.
+ * One already on the task's `Pull request:` line means the branch recorded its
+ * number, so a marker would outlive the branch with nothing left to clear it.
+ * An absent or empty list keeps the marker, which is the first slice's case.
  */
 export async function closeOutcomes(
   root: string,
   selector: RecordSelector,
   positions: readonly number[],
   branch?: string,
+  branchPulls: readonly number[] = [],
 ): Promise<CloseOutcome> {
   const opened = await openTask(root, selector)
   if ('ok' in opened) return opened
@@ -541,8 +547,12 @@ export async function closeOutcomes(
     )
   }
 
+  const recorded = readPullRequest(result.text).some((number) =>
+    branchPulls.includes(number),
+  )
+
   const text =
-    result.closed.length > 0 && branch
+    result.closed.length > 0 && branch && !recorded
       ? writePendingBranch(result.text, branch).text
       : result.text
 

package/src/tasks/validate.ts

@@ -6,6 +6,7 @@ import {
   declinedDir,
   isReservedStem,
   readOutcomes,
+  readPendingBranches,
   readPlanTargets,
   readPullRequest,
   resolveLivePlan,
@@ -1065,6 +1066,10 @@ function nothing(): CitedResult {
  * about, and a task naming none leaves the row untested rather than settled,
  * because the only local signal left is the checkbox that produced the defect.
  *
+ * A task still carrying a pending branch is untested whatever its recorded
+ * pull request says, since a slice is in flight that has recorded no number yet
+ * and the landed one may belong to an earlier slice.
+ *
  * The outcome list comes off `readOutcomes` rather than a pattern of its own,
  * so this check cannot disagree with the archive and outcome verbs about which
  * checkboxes are outcomes and which sit inside a block a task displays.
@@ -1114,6 +1119,15 @@ async function checkCitedTask(
   const { open, closed } = readOutcomes(text)
   if (open.length > 0 || closed.length === 0) return nothing()
 
+  const pending = readPendingBranches(text)
+  if (pending.length > 0) {
+    return untestedRow(
+      group,
+      subject,
+      `waits on ${cited}, which closed every outcome but holds a pending branch (${pending.join(', ')}) that has yet to record its pull request.`,
+    )
+  }
+
   // The last number is the newest slice, and an earlier one closed without
   // merging never lands, so only the last says whether the work reached trunk.
   const pullRequest = readPullRequest(text).at(-1)

package/standards/tasks.md

@@ -141,7 +141,7 @@ One plan per task, or one per slice, which the board check reads as distinct pla
 
 `Pull request:` records which pull requests carry the task's work, each as a bare `#NNN` the way `Issue:` does. It lists every pull request that shipped part of the task, oldest first and separated by commas, as in `Pull request: #NNN, #NNN`, and a task shipped whole lists one. It is not an origin, so a task without one is well-formed. `git-pr` appends to it when a pull request opens.
 
-The line is what lets a merge close its own task. `canon tasks archive --pull-request <n>` finds the task by any number the line lists and archives it only on the last. One pull request, one task: two tasks naming the same number refuse to archive rather than both moving. `Pending branch: <branch>` holds that merge back while a branch that ticked an outcome waits on its own number, since `canon tasks outcome` writes it and `canon tasks pull-request` clears it.
+The line is what lets a merge close its own task. `canon tasks archive --pull-request <n>` finds the task by any number the line lists and archives it only on the last. One pull request, one task: two tasks naming the same number refuse to archive rather than both moving. `Pending branch: <branch>` holds that merge back while a branch that ticked an outcome waits on its own number, since `canon tasks outcome` writes it and `canon tasks pull-request` clears it. `canon tasks outcome` skips the write when the branch's own pull request is already on the line.
 
 ## What goes in
 

package/tooling/astro/configs/card-src/pages/og-card.astro

@@ -20,12 +20,12 @@
  * `scripts/check-card-exclusion.sh` fails a build that carries the marker
  * below, which is what keeps the route out of the published site.
  */
-import '@/styles/global.css'
 
-// Retarget the import above when this project keeps its global stylesheet
+// Point the import below at this project's global stylesheet when it lives
 // somewhere else. An unresolved path refuses the card server by name, which is
 // the loud direction: a card captured against no stylesheet renders as an
 // unstyled box and reports success.
+import '@/styles/global.css'
 ---
 
 <html lang="en">

package/claude/skills/docs-fold/REQUIREMENT.md

@@ -1,25 +0,0 @@
----
-name: docs-fold
-description: Why a pointer answers under the fold skill's old name, and the test that retires it
----
-
-# Docs fold requirement
-
-## Gap
-
-Without this skill, a person typing the old name after the rename to `context-fold` meets an unknown command with nothing naming where the skill went. A target that has not run `canon migrate skill-names` still holds files telling someone to type it, and a live gitignored record written before the rename still names it, since the sweep reads the tracked listing only.
-
-## Must
-
-- Name `context-fold` as the skill to run, so a typed invocation of the old name reaches the new one in one step
-- Carry `disable-model-invocation: true`, so routing never matches the old description against a request the new skill owns
-
-## Must not
-
-- Carry any part of the fold procedure, which would give one behavior two bodies that drift apart
-- Retire on a release number. Retire it when `canon migrate skill-names --json` reports zero citations in every target the rollout reaches and no live `.canon/` record names the old name, since a release number retires it on a date nothing measured.
-
-## Out of scope
-
-- The fold itself, which `context-fold` owns
-- Rewriting a stale citation, which `canon migrate skill-names` owns in a tracked file and the controlling session owns on the board

package/claude/skills/docs-fold/SKILL.md

@@ -1,9 +0,0 @@
----
-name: docs-fold
-description: Renamed to `context-fold`. Answers a typed invocation of the old name by pointing at the new one.
-disable-model-invocation: true
----
-
-# Docs fold
-
-This skill is now `context-fold`. Run `/canon:context-fold` instead, and change any file that still names this one.

package/claude/skills/standards-audit/REQUIREMENT.md

@@ -1,33 +0,0 @@
----
-name: standards-audit
-description: What the standards audit is for, the gaps it closes, and the fixing it deliberately refuses
----
-
-# Standards audit requirement
-
-## Gap
-
-Without this skill, markdown ships unchecked against the authoring standards it was written under. A session fresh from writing prose does not reopen the standard it was meant to follow, banned punctuation survives because it reads fine, and the mapping from a file to the standards governing it gets re-derived by guess on every pass.
-
-## Must
-
-- Scope the audit to markdown the project hand-authors, so a generated file is not reported against a standard nobody applies to it
-- Decide which standards govern each changed file, rather than auditing every file against every standard
-- Grep for the violations a standard makes mechanically detectable, because reading alone misses occurrences
-- Report each finding with a file and a line, grouped so one file is one fix pass
-
-## Must not
-
-- Fix a violation, or propose the fix inline. The cheap swap satisfies the grep and breaks the rule the grep was standing in for.
-- Enumerate specific rules or tokens from a standard. The standard is the list, and a copy of it here drifts the moment the standard changes.
-
-## Guards
-
-- No markdown changed since main: stop with a pass, not an error
-- No installed standards to audit against: stop and say where they come from
-
-## Out of scope
-
-- Code style and structure, which `.claude/rules/` governs and Claude Code loads directly
-- Whether a standard is itself correct. A finding against the corpus is an argument to change the standard, and that is a standards edit rather than an audit result.
-- Persisting a report. The diff is the living state and the audit is a check against it at a moment.