@erclx/canon 5.33.0 → 5.34.0

package/src/canvas/fit.ts

@@ -0,0 +1,238 @@
+import {
+  type Box,
+  type ContentRefused,
+  readPage,
+  resizeFrame,
+} from '@/canvas/content'
+import {
+  type CaptureDeps,
+  resolveCaptureTargets,
+  type ServeRefused,
+  serveCanvas,
+} from '@/canvas/capture'
+import { resolveFrameTokens, servedFamilies } from '@/canvas/tokens'
+
+/** What the capture browser read off one frame at its box width. */
+export interface Measured {
+  readonly page: string
+  readonly frame: string
+  readonly box: Box
+  readonly contentHeight: number
+  readonly contentWidth: number
+  /**
+   * The lowest edge of any element in the body moved when the viewport
+   * height changed, so a viewport unit is sizing something and the content
+   * measure is not the height a viewer draws.
+   */
+  readonly viewportBound: boolean
+  /** The first family of the body text, unquoted. */
+  readonly family: string
+}
+
+export interface FitRow {
+  readonly page: string
+  readonly frame: string
+  /** The box height now. */
+  readonly height: number
+  /** The content's height, which is what the box should be. */
+  readonly fitted: number
+  /** The content is wider than the box, which fit reports and never widens. */
+  readonly wide: boolean
+  /** The first family is not one the canvas serves, so the height may not hold. */
+  readonly font: boolean
+  /**
+   * The document height depends on the viewport, as a height in `vh` does, so
+   * the content measure is not the height a viewer draws and nothing is written.
+   */
+  readonly viewport: boolean
+  readonly family: string
+}
+
+/**
+ * Turns measurements into rows. The box width is the frame's declared render
+ * width, so an overflow in it is a finding and never a resize. `served` is the
+ * set of families the served sheet carries a face for.
+ *
+ * A frame whose elements moved with the viewport height is sized by a unit
+ * such as `vh`, so the row keeps its height and reports `viewport`. Scroll
+ * height cannot show it alone, since a single `100vh` section reads as short
+ * content drawn in a taller viewport.
+ */
+export function planFit(
+  measured: readonly Measured[],
+  served: ReadonlySet<string>,
+): FitRow[] {
+  return measured.map((item) => {
+    const content = Math.max(1, Math.ceil(item.contentHeight))
+    const viewport = item.viewportBound
+    return {
+      page: item.page,
+      frame: item.frame,
+      height: item.box.height,
+      fitted: viewport ? item.box.height : content,
+      wide: item.contentWidth > item.box.width,
+      font: !served.has(item.family),
+      viewport,
+      family: item.family,
+    }
+  })
+}
+
+/** Whether a row asks anything of the operator or the session. */
+export function isOwed(row: FitRow): boolean {
+  return row.fitted !== row.height || row.wide || row.font || row.viewport
+}
+
+export type FitOutcome =
+  | {
+      readonly ok: true
+      readonly rows: readonly FitRow[]
+      /** Whether heights were written, which is false under a check. */
+      readonly written: boolean
+    }
+  | ContentRefused
+  | ServeRefused
+
+export interface FitDeps extends Pick<CaptureDeps, 'start'> {
+  /** What a test stands in for, which the command never passes. */
+  readonly measure?: (targets: readonly MeasureTarget[]) => Promise<Measured[]>
+}
+
+export interface MeasureTarget {
+  readonly page: string
+  readonly frame: string
+  readonly url: string
+  readonly box: Box
+}
+
+/**
+ * Loads each frame at its box width through the served address, which is what
+ * injects the tokens and the faces, and reads the document once fonts and the
+ * load event have settled, the moment a capture waits for. The content is read
+ * at a one pixel tall viewport, since a document shorter than the viewport
+ * reports the viewport and a frame could then never shrink. The lowest element
+ * edge is then read at the box height and at twice it, and an edge that moved
+ * is a height set in viewport units.
+ */
+async function measureInBrowser(
+  targets: readonly MeasureTarget[],
+): Promise<Measured[]> {
+  const { chromium } = await import('playwright-core')
+  const browser = await chromium.launch()
+  try {
+    const measured: Measured[] = []
+    for (const target of targets) {
+      const page = await browser.newPage({
+        viewport: { width: target.box.width, height: 1 },
+      })
+      try {
+        await page.goto(target.url, { waitUntil: 'load' })
+        const read = await page.evaluate(async () => {
+          await document.fonts.ready
+          const root = document.documentElement
+          const family = getComputedStyle(document.body).fontFamily
+          return {
+            contentHeight: root.scrollHeight,
+            contentWidth: root.scrollWidth,
+            family,
+          }
+        })
+        const lowestEdge = () =>
+          page.evaluate(() => {
+            let bottom = 0
+            for (const element of document.body.querySelectorAll('*')) {
+              bottom = Math.max(
+                bottom,
+                element.getBoundingClientRect().bottom + window.scrollY,
+              )
+            }
+            return Math.ceil(bottom)
+          })
+        const heights = [target.box.height, target.box.height * 2]
+        const edges: number[] = []
+        for (const height of heights) {
+          await page.setViewportSize({ width: target.box.width, height })
+          edges.push(await lowestEdge())
+        }
+        measured.push({
+          page: target.page,
+          frame: target.frame,
+          box: target.box,
+          contentHeight: read.contentHeight,
+          contentWidth: read.contentWidth,
+          viewportBound: edges[0] !== edges[1],
+          family: firstFamily(read.family),
+        })
+      } finally {
+        await page.close()
+      }
+    }
+    return measured
+  } finally {
+    await browser.close()
+  }
+}
+
+/** The first entry of a computed `font-family` list, without its quotes. */
+export function firstFamily(list: string): string {
+  const first = list.split(',')[0] ?? ''
+  return first.trim().replace(/^["']|["']$/g, '')
+}
+
+/**
+ * Measures the frames `spec` names and, unless `write` is false, sets each
+ * box's height to its content through `resizeFrame`, the writer the operator's
+ * drags share. Serves the canvas for the call, so it needs no running board.
+ */
+export async function fitCanvas(
+  root: string,
+  spec: string,
+  write: boolean,
+  deps: FitDeps = {},
+): Promise<FitOutcome> {
+  const early = resolveCaptureTargets(root, spec, '')
+  if (!early.ok) return early
+
+  const served = await serveCanvas(root, deps.start, async (base) => {
+    const resolved = resolveCaptureTargets(root, spec, base)
+    if (!resolved.ok) return resolved
+    const frames = readPage(root, resolved.targets[0]?.page ?? '')?.frames ?? []
+
+    const targets: MeasureTarget[] = []
+    for (const item of resolved.targets) {
+      const frame = frames.find((candidate) => candidate.name === item.frame)
+      if (!frame) continue
+      targets.push({
+        page: item.page,
+        frame: item.frame,
+        url: item.url,
+        box: {
+          x: frame.x,
+          y: frame.y,
+          width: frame.width,
+          height: frame.height,
+        },
+      })
+    }
+    const measure = deps.measure ?? measureInBrowser
+    return { ok: true as const, targets, measured: await measure(targets) }
+  })
+  if (!served.ok) return served
+
+  const rows = planFit(
+    served.measured,
+    servedFamilies(resolveFrameTokens(root).css),
+  )
+  if (!write) return { ok: true, rows, written: false }
+
+  for (const row of rows.filter((item) => item.fitted !== item.height)) {
+    const target = served.targets.find((item) => item.frame === row.frame)
+    if (!target) continue
+    const outcome = resizeFrame(root, row.page, row.frame, {
+      ...target.box,
+      height: row.fitted,
+    })
+    if (!outcome.ok) return outcome
+  }
+  return { ok: true, rows, written: true }
+}

package/src/canvas/tokens.ts

@@ -10,7 +10,6 @@ import {
 import {
   type DroppedFace,
   inlineProjectFaces,
-  namedFamilies,
   projectSheets,
 } from '@/design/project-fonts'
 import { isOwnCheckout } from '@/roots/project'
@@ -31,7 +30,7 @@ export type FrameTokens =
       /** Project faces left out of the sheet, present only when one was. */
       readonly dropped?: readonly DroppedFace[]
     }
-  | { readonly source: 'none'; readonly css: ''; readonly notice: string }
+  | { readonly source: 'none'; readonly css: string; readonly notice: string }
 
 export interface TokenOptions {
   /** Overrides the checkout test, which reads this package's own name. */
@@ -124,6 +123,21 @@ export function tokenGroups(css: string): TokenGroup[] {
   })
 }
 
+/**
+ * The families a served sheet declares a face for, so a caller reads what the
+ * frames carry from the same sheet the server builds rather than from a list
+ * of its own.
+ */
+export function servedFamilies(css: string): Set<string> {
+  const families = new Set<string>()
+  for (const [, family] of css.matchAll(
+    /@font-face\s*{[^}]*?font-family:\s*["']?([^"';}]+)/g,
+  )) {
+    if (family) families.add(family.trim())
+  }
+  return families
+}
+
 /** The installed files in cascade order: the base first, then each override. */
 function installedFiles(root: string): string[] {
   const base = join(DESIGN_INSTALL_DIR, BASE_FILE)
@@ -134,14 +148,14 @@ function installedFiles(root: string): string[] {
 }
 
 /**
- * The vendored faces the installed sheets name and no project rule already
- * declares, so a target renders the base's families on a machine that never
- * installed them, and a project face of the same family wins outright.
+ * The vendored faces no project rule already declares, so a frame naming
+ * `Geist Variable` renders the same face in the capture and in any browser
+ * whether or not a sheet names it, and a project face of the same family wins
+ * outright.
  */
-function toolkitFaces(css: string, declared: ReadonlySet<string>): FontFace[] {
-  const named = namedFamilies(css)
+function toolkitFaces(declared: ReadonlySet<string>): FontFace[] {
   return [...FONT_FACES, ...HAND_DRAWN_FONT_FACES].filter(
-    (face) => named.has(face.family) && !declared.has(face.family),
+    (face) => !declared.has(face.family),
   )
 }
 
@@ -190,7 +204,7 @@ export function resolveFrameTokens(
   const files = installedFiles(root)
   if (files.length > 0) {
     const { css, dropped, declared } = installedSheets(root, files)
-    const faces = toolkitFaces(css, declared)
+    const faces = toolkitFaces(declared)
     return {
       source: 'installed',
       css: faces.length > 0 ? `${fontFaceBlock(faces)}\n${css}` : css,
@@ -199,5 +213,9 @@ export function resolveFrameTokens(
     }
   }
 
-  return { source: 'none', css: '', notice: NONE_NOTICE }
+  return {
+    source: 'none',
+    css: fontFaceBlock(toolkitFaces(new Set())),
+    notice: NONE_NOTICE,
+  }
 }

package/src/capture/frame-values.ts

@@ -31,15 +31,9 @@ const GLOB_WIDTH = 44
 /** A refusal the script prints as `regen-hero: <message>` and exits 1 on. */
 export class FrameError extends Error {}
 
-export interface StandardRow {
-  readonly name: string
-  readonly appliesTo?: readonly string[]
-}
-
 export interface FrameCatalogs {
   readonly skills: readonly string[]
   readonly gov: GovCatalog
-  readonly standards: readonly StandardRow[]
   readonly toolingStacks: readonly StackSummary[]
   readonly commandCount: number
   readonly tokenCss: string
@@ -63,7 +57,7 @@ const escape = (value: string): string =>
 /**
  * Even spacing across the sorted catalog rather than its first N, so a column
  * whose names share a prefix does not read as a narrower catalog than the one
- * that ships. Rules and standards sample. Skills do not, because the even step
+ * that ships. Rules sample. Skills do not, because the even step
  * lands on the entries closest to commodity and on none of the workflow the
  * toolkit exists to carry.
  */
@@ -186,7 +180,7 @@ function faviconUri(markSvg: string, tokenCss: string): string {
  * rather than shipping a frame claiming the domain has nothing in it.
  */
 export function buildFrameValues(catalogs: FrameCatalogs): FrameValues {
-  const { gov, toolingStacks, standards, skills } = catalogs
+  const { gov, toolingStacks, skills } = catalogs
   const markSvg = catalogs.markSvg.trim()
   if (!markSvg) {
     throw new FrameError(
@@ -207,12 +201,10 @@ export function buildFrameValues(catalogs: FrameCatalogs): FrameValues {
   const stacked = new Set(gov.stacks.flatMap((stack) => stack.rules))
   const deliveredEntries = gov.rules.filter((entry) => stacked.has(entry.name))
   const deliveredRules = deliveredEntries.map((entry) => slug(entry.name))
-  const standardNames = standards.map((entry) => entry.name)
 
   for (const [label, list] of [
     ['skills', skills],
     ['rules', rules],
-    ['standards', standardNames],
     ['tooling stacks', toolingStacks],
     ['gov stacks', gov.stacks],
     ['stack-delivered rules', deliveredRules],
@@ -251,23 +243,6 @@ export function buildFrameValues(catalogs: FrameCatalogs): FrameValues {
     })
     .join('\n')
 
-  // A standard either governs an artifact by path or is opened by name when a
-  // session decides it needs it. Naming the second is the contrast, since
-  // nothing else tells a reader the corpus installs into no project.
-  const standardRows = sample(standards)
-    .map((entry) => {
-      const applies = entry.appliesTo ?? []
-      const governs =
-        applies.length > 0
-          ? clip(applies.join(' '), GLOB_WIDTH)
-          : 'read by name'
-      return frameRow(
-        `<span class="name">${escape(pad(entry.name, 18))}</span>` +
-          `<span class="muted">${escape(governs)}</span>`,
-      )
-    })
-    .join('\n')
-
   // A tooling stack is counted rather than listed, because what it lays down is
   // dev dependencies, run scripts, and ignore groups rather than named entries.
   // The inheritance is the part worth showing, since it is why a stack carrying
@@ -286,7 +261,6 @@ export function buildFrameValues(catalogs: FrameCatalogs): FrameValues {
   for (const [label, rows] of [
     ['governance stack rows', govStackRows],
     ['governance rule rows', govRuleRows],
-    ['standard rows', standardRows],
     ['tooling stack rows', toolingStackRows],
   ] as const) {
     if (rows === '') {
@@ -300,11 +274,9 @@ export function buildFrameValues(catalogs: FrameCatalogs): FrameValues {
     TOKENS: tokenCss,
     GOV_STACK_ROWS: govStackRows,
     GOV_RULE_ROWS: govRuleRows,
-    STANDARD_ROWS: standardRows,
     TOOLING_STACK_ROWS: toolingStackRows,
     SKILL_COUNT: String(skills.length),
     RULE_COUNT: String(rules.length),
-    STANDARD_COUNT: String(standardNames.length),
     GOV_STACK_COUNT: String(gov.stacks.length),
     TOOLING_STACK_COUNT: String(toolingStacks.length),
     COMMAND_COUNT: String(catalogs.commandCount),
@@ -312,10 +284,8 @@ export function buildFrameValues(catalogs: FrameCatalogs): FrameValues {
     FAVICON: faviconUri(markSvg, tokenCss),
     SKILL_ENTRIES: markup(featured(skills, FEATURED_SKILLS)),
     RULE_ENTRIES: markup(sample(deliveredRules)),
-    STANDARD_ENTRIES: markup(sample(standardNames)),
     SKILL_MORE: remaining(skills),
     RULE_MORE: remaining(rules),
-    STANDARD_MORE: remaining(standardNames),
   }
 
   const light = lightTokens(tokenCss)

package/src/commands/canvas.ts

@@ -9,12 +9,15 @@ import {
   DEFAULT_FRAME,
   listPages,
   moveFrame,
+  pruneLayout,
   readPage,
   readSelection,
   renamePage,
   resizeFrame,
 } from '@/canvas/content'
+import { planArrange } from '@/canvas/arrange'
 import { captureCanvas, captureComposite } from '@/canvas/capture'
+import { fitCanvas, isOwed } from '@/canvas/fit'
 import {
   type EditRefused,
   editFrameAtIndex,
@@ -148,7 +151,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, edit, editing, capture)',
+      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, edit, editing, capture, fit, arrange)',
     )
     .addHelpText(
       'after',
@@ -167,6 +170,8 @@ export function register(program: Command): void {
         "  canon canvas edit drafts/hero --element 4 --set 'color=var(--color-accent)'",
         '  canon canvas editing drafts/hero',
         '  canon canvas capture drafts/hero',
+        '  canon canvas fit drafts/hero --json',
+        '  canon canvas arrange drafts --check',
         '  canon canvas list --json',
         '',
       ].join('\n'),
@@ -728,6 +733,179 @@ export function register(program: Command): void {
       outro()
       if (failed) process.exitCode = 1
     })
+
+  withRoot(
+    canvas
+      .command('fit')
+      .description("Set each frame's height to its content")
+      .argument('<target>', '<page>/<frame> for one frame, <page> for all')
+      .option('--check', 'Report what is owed and write nothing'),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Measures each frame in the capture browser at its box width, through',
+        'the served address, so the faces the canvas serves are the ones read.',
+        'The height is the content height rounded up, with no margin. A',
+        'content wider than the box is reported and the box is never widened.',
+        'A frame whose body text names a family the canvas does not serve is',
+        'reported as font, since its height may not hold in another browser.',
+        '',
+        'Run canvas arrange after a fit that grew a frame, since rows below',
+        'do not move on their own.',
+        '',
+        'Exit codes:',
+        '  0  written, or nothing owed under --check',
+        '  1  refused or the browser failed',
+        '  2  --check found a height off, a wide frame, or a font',
+        '',
+      ].join('\n'),
+    )
+    .action(async (target: string, opts: FitOptions) => {
+      process.exitCode = await runFit(target, opts)
+    })
+
+  withRoot(
+    canvas
+      .command('arrange')
+      .description('Re-lay a page in rows on the frame gap')
+      .argument('<page>', 'Page to arrange')
+      .option('--check', 'Report what is owed and write nothing'),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Keeps the rows the frames already sit in, orders each left to right on',
+        'the frame gap, stacks the rows on their tallest frame, and drops',
+        'layout entries whose frame file is gone.',
+        '',
+        'Exit codes:',
+        '  0  written, or nothing owed under --check',
+        '  1  refused',
+        '  2  --check found frames to move or entries to drop',
+        '',
+      ].join('\n'),
+    )
+    .action(async (pageName: string, opts: FitOptions) => {
+      process.exitCode = await runArrange(pageName, opts)
+    })
+}
+
+interface FitOptions extends RootOptions {
+  readonly check?: boolean
+}
+
+async function runFit(target: string, opts: FitOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const resolved = await resolveRoot(opts)
+  if (!resolved.ok) return refuse(resolved, emitJson)
+
+  const check = opts.check ?? false
+  let outcome: Awaited<ReturnType<typeof fitCanvas>>
+  try {
+    outcome = await fitCanvas(resolved.root, target, !check)
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    return refuse({ ok: false, reason: 'capture-failed', detail }, emitJson)
+  }
+  if (!outcome.ok) return refuse(outcome, emitJson)
+
+  const frames = outcome.rows.map((row) => ({ ...row, owed: isOwed(row) }))
+  const owed = frames.some((row) => row.owed)
+  if (emitJson) writeJson({ ok: true, written: outcome.written, frames })
+  intro(BANNER)
+  for (const row of frames) {
+    const name = `${row.page}/${row.frame}`
+    if (row.fitted === row.height) logInfo(`${name} fits at ${row.height}`)
+    else if (outcome.written) logAdd(`${name} ${row.height} to ${row.fitted}`)
+    else logStep(`${name} owes ${row.height} to ${row.fitted}`)
+    if (row.wide) logWarn(`${name} is wider than its box, so widen the box`)
+    if (row.viewport) {
+      logWarn(
+        `${name} sets a height in viewport units, so its height was not written and a fixed height fits it`,
+      )
+    }
+    if (row.font) {
+      logWarn(
+        `${name} sets ${row.family}, which the canvas does not serve, so its height may not hold in another browser`,
+      )
+    }
+  }
+  outro()
+  return check && owed ? 2 : 0
+}
+
+async function runArrange(pageName: string, opts: FitOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const resolved = await resolveRoot(opts)
+  if (!resolved.ok) return refuse(resolved, emitJson)
+  const { root } = resolved
+
+  const page = readPage(root, pageName)
+  if (!page) {
+    return refuse(
+      {
+        ok: false,
+        reason: 'no-page',
+        detail: `page ${pageName} does not exist`,
+      },
+      emitJson,
+    )
+  }
+  if (page.layoutIssue) {
+    return refuse(
+      {
+        ok: false,
+        reason: 'malformed-layout',
+        detail: `${pageName}/layout.json does not parse`,
+      },
+      emitJson,
+    )
+  }
+
+  const check = opts.check ?? false
+  const pruned = pruneLayout(root, pageName, !check)
+  if (!pruned.ok) return refuse(pruned, emitJson)
+
+  const moves = planArrange(page.frames)
+  if (!check) {
+    for (const move of moves) {
+      const outcome = resizeFrame(root, pageName, move.name, move.to)
+      if (!outcome.ok) return refuse(outcome, emitJson)
+    }
+  }
+
+  if (emitJson) {
+    writeJson({
+      ok: true,
+      page: pageName,
+      written: !check,
+      moved: moves.map((move) => ({
+        frame: move.name,
+        from: { x: move.from.x, y: move.from.y },
+        to: { x: move.to.x, y: move.to.y },
+      })),
+      dropped: pruned.dropped,
+    })
+  }
+  intro(BANNER)
+  for (const move of moves) {
+    const text = `${pageName}/${move.name} ${move.from.x}, ${move.from.y} to ${move.to.x}, ${move.to.y}`
+    if (check) logStep(`${text} is owed`)
+    else logAdd(text)
+  }
+  for (const name of pruned.dropped) {
+    logWarn(
+      `${pageName}/${name} has no frame file, so its entry is ${check ? 'owed a drop' : 'dropped'}`,
+    )
+  }
+  if (moves.length === 0 && pruned.dropped.length === 0) {
+    logInfo(`${pageName} is already laid out`)
+  }
+  outro()
+  return check && (moves.length > 0 || pruned.dropped.length > 0) ? 2 : 0
 }
 
 interface CaptureOptions extends RootOptions {