@erclx/canon 5.15.0 → 5.16.0

package/src/commands/canvas.ts

@@ -8,8 +8,12 @@ import {
   canvasDir,
   DEFAULT_FRAME,
   listPages,
+  moveFrame,
+  readPage,
+  readSelection,
   renamePage,
 } from '@/canvas/content'
+import { captureCanvas } from '@/canvas/capture'
 import { CANVAS_PORT, startCanvas } from '@/canvas/server'
 import { resolveFrameTokens } from '@/canvas/tokens'
 import { displayPath, parsePort, waitForInterrupt } from '@/serve/report'
@@ -34,7 +38,11 @@ interface RootOptions {
 
 interface Refused {
   readonly ok: false
-  readonly reason: ContentRefused['reason'] | 'no-root'
+  readonly reason:
+    | ContentRefused['reason']
+    | 'no-root'
+    | 'no-server'
+    | 'capture-failed'
   readonly detail: string
 }
 
@@ -94,7 +102,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)',
+      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, capture)',
     )
     .addHelpText(
       'after',
@@ -108,6 +116,9 @@ export function register(program: Command): void {
         '  canon canvas serve',
         '  canon canvas page add drafts',
         '  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 capture drafts/hero',
         '  canon canvas list --json',
         '',
       ].join('\n'),
@@ -212,7 +223,7 @@ export function register(program: Command): void {
   const frame = canvas
     .command('frame')
     .helpOption('-h, --help', 'Show this help message')
-    .description('Add a frame to a page')
+    .description('Add a frame to a page, or move one')
 
   withRoot(
     frame
@@ -256,6 +267,192 @@ export function register(program: Command): void {
       outro()
     },
   )
+
+  withRoot(
+    frame
+      .command('move')
+      .description('Move a frame, keeping its size')
+      .argument('<page>', 'Page the frame is on')
+      .argument('<name>', 'Frame name')
+      .option('--x <px>', 'New x, defaulting to where the frame is')
+      .option('--y <px>', 'New y, defaulting to where the frame is'),
+  ).action(
+    async (
+      pageName: string,
+      name: string,
+      opts: RootOptions & { x?: string; y?: string },
+    ) => {
+      const resolved = await resolveRoot(opts)
+      if (!resolved.ok) {
+        process.exitCode = refuse(resolved, opts.json ?? false)
+        return
+      }
+      const { root } = resolved
+      const current = readPage(root, pageName)?.frames.find(
+        (candidate) => candidate.name === name,
+      )
+      const outcome = moveFrame(root, pageName, name, {
+        x: parsePosition(opts.x, current?.x ?? 0),
+        y: parsePosition(opts.y, current?.y ?? 0),
+      })
+      if (!outcome.ok) {
+        process.exitCode = refuse(outcome, opts.json ?? false)
+        return
+      }
+      if (opts.json) writeJson(outcome)
+      intro(BANNER)
+      logAdd(`${outcome.page}/${outcome.file}`)
+      logInfo(`at ${outcome.box.x}, ${outcome.box.y}`)
+      outro()
+    },
+  )
+
+  withRoot(
+    canvas
+      .command('selection')
+      .description(
+        'Report the frame, or the element in it, the operator selected',
+      ),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reports none when nothing is selected or when the selected frame has',
+        'since been removed. Read this when the operator says "this one".',
+        '',
+        'An element is named by its index in document order, with the tag,',
+        'classes, and text it had when picked. stale is true once the frame',
+        'file changed since, since the index may then name another element.',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RootOptions) => {
+      const resolved = await resolveRoot(opts)
+      if (!resolved.ok) {
+        process.exitCode = refuse(resolved, opts.json ?? false)
+        return
+      }
+      const { root } = resolved
+      const selected = readSelection(root)
+      if (opts.json) {
+        writeJson({
+          ok: true,
+          selection: selected
+            ? {
+                ...selected,
+                path: resolve(canvasDir(root), selected.page, selected.file),
+              }
+            : null,
+        })
+      }
+      intro(BANNER)
+      if (!selected) {
+        logStep('Nothing selected')
+      } else {
+        logStep(`${selected.page}/${selected.frame}`)
+        const { box, element } = selected
+        logInfo(`${box.width} × ${box.height} at ${box.x}, ${box.y}`)
+        if (element) {
+          const classes = element.classes.map((name) => `.${name}`).join('')
+          logInfo(
+            `<${element.tag}${classes}> at index ${element.index}: ${element.text}`,
+          )
+          if (element.stale) {
+            logWarn('The frame changed since, so the index may have moved')
+          }
+        }
+      }
+      outro()
+    })
+
+  withRoot(
+    canvas
+      .command('capture')
+      .description('Capture a frame, or every frame of a page, as a PNG')
+      .argument('<target>', '<page>/<frame> for one frame, <page> for all')
+      .option(
+        '-o, --out <path>',
+        'The PNG for a frame, or the folder for a page; defaults to session scratch',
+      ),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Serves the canvas for the call and captures through that address, so',
+        'the injected tokens are in the PNG and each frame renders at its own',
+        'width. The raw file on disk is never captured.',
+        '',
+        'Exit codes:',
+        '  0  every frame rendered',
+        '  1  refused or a frame failed, with the reason on stderr or in the JSON record',
+        '',
+      ].join('\n'),
+    )
+    .action(async (target: string, opts: RootOptions & { out?: string }) => {
+      const resolved = await resolveRoot(opts)
+      if (!resolved.ok) {
+        process.exitCode = refuse(resolved, opts.json ?? false)
+        return
+      }
+      let outcome: Awaited<ReturnType<typeof captureCanvas>>
+      try {
+        outcome = await captureCanvas(
+          resolved.root,
+          target,
+          opts.out ? resolve(process.cwd(), opts.out) : undefined,
+        )
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error)
+        process.exitCode = refuse(
+          { ok: false, reason: 'capture-failed', detail },
+          opts.json ?? false,
+        )
+        return
+      }
+      if (!outcome.ok) {
+        process.exitCode = refuse(outcome, opts.json ?? false)
+        return
+      }
+
+      const rows = outcome.captures.map(({ target: item, result }) =>
+        result.status === 'rendered'
+          ? {
+              page: item.page,
+              frame: item.frame,
+              status: result.status,
+              path: result.pngPath,
+              width: result.width,
+              height: result.height,
+            }
+          : {
+              page: item.page,
+              frame: item.frame,
+              status: result.status,
+              reason: result.reason,
+            },
+      )
+      const failed = rows.some((row) => row.status === 'failed')
+      if (opts.json) writeJson({ ok: !failed, captures: rows })
+      intro(BANNER)
+      for (const row of rows) {
+        if (row.status === 'rendered') {
+          logAdd(`${row.page}/${row.frame}`)
+          logInfo(`${displayPath(row.path)} ${row.width}x${row.height}`)
+        } else {
+          logError(`${row.page}/${row.frame}: ${row.reason}`)
+        }
+      }
+      outro()
+      if (failed) process.exitCode = 1
+    })
+}
+
+/** NaN for a value that is not a number, which the content module refuses. */
+function parsePosition(raw: string | undefined, fallback: number): number {
+  if (raw === undefined) return fallback
+  return raw.trim() === '' ? Number.NaN : Number(raw)
 }
 
 async function runServe(

package/src/commands/migrate.ts

@@ -1222,7 +1222,7 @@ export function register(program: Command): void {
         '',
         'The changelog is never rewritten. Its entries record what shipped',
         'under the old name, and GitHub redirects the links they carry.',
-        'aitk-sandbox is a separate repository and is left alone.',
+        'aitk-sandbox, the old name of erclx/canon-sandbox, is left alone.',
         '',
         'Examples:',
         '  canon migrate rename',

package/src/migrate/rename.ts

@@ -168,10 +168,11 @@ const AITK_ARTICLE = /\b([Aa])n(\s+`?)(canon|CANON|Canon)(?![A-Za-z])/g
 /**
  * The `aitk` to `canon` rename.
  *
- * `aitk-sandbox` is a separate repository that is not being renamed. It has to
- * win against the bare token, and it also has to win against the owner-scoped
- * spelling, since `erclx/aitk-sandbox` would otherwise rewrite to
- * `erclx/canon-sandbox` and name a repository that does not exist.
+ * `aitk-sandbox` is the retired spelling of a repository that was later renamed
+ * `canon-sandbox`, and GitHub still resolves the old name through a redirect.
+ * It has to win against the bare token, and it also has to win against the
+ * owner-scoped spelling, so a consumer's text naming `erclx/aitk-sandbox` keeps
+ * the form that resolves rather than being rewritten.
  *
  * Case is carried in the map rather than derived, because the uppercase form
  * is an environment variable prefix and the title-case form is a heading word,

package/src/teach/browser/compile.ts

@@ -0,0 +1,44 @@
+type BrowserFunction = (...args: never[]) => unknown
+
+const transpiler = new Bun.Transpiler({ loader: 'ts' })
+
+const MODULE_SYNTAX = /^\s*(import|export)\b/m
+
+/**
+ * `</script>` inside a serialized argument would end the block early, and
+ * `<` is the same character to the JavaScript parser.
+ */
+function serialize(args: readonly unknown[]): string {
+  return JSON.stringify(args).slice(1, -1).replace(/</g, '\\u003c')
+}
+
+/**
+ * Turns a browser module's function into the `<script>` a page carries. The
+ * transpiler does not bundle, so a module is self-contained: whatever it
+ * calls but does not define arrives as a named function in `helpers`, and a
+ * value it needs arrives in `args`. Output holding module syntax throws, since
+ * a script block with an `import` fails in the browser with nothing in the
+ * type checker to say so.
+ */
+export function compileScript(
+  run: BrowserFunction,
+  args: readonly unknown[] = [],
+  helpers: readonly BrowserFunction[] = [],
+): string {
+  const source = helpers.length
+    ? `(function () {\n${helpers.map(String).join('\n')}\nreturn ${run};\n})()`
+    : String(run)
+  // A bare expression statement is dead code to the transpiler and comes back
+  // empty, so the source rides an export that it must keep.
+  const code = transpiler
+    .transformSync(`export default ${source}`)
+    .trim()
+    .replace(/^export default /, '')
+    .replace(/;$/, '')
+
+  if (MODULE_SYNTAX.test(code)) {
+    throw new Error(`Browser module ${run.name} left import or export syntax`)
+  }
+
+  return `<script>(${code})(${serialize(args)})</script>`
+}

package/src/teach/browser/dismiss.ts

@@ -0,0 +1,76 @@
+export function dismiss(): void {
+  var MENUS = 'details.jump[open], details.sb-ws[open]'
+
+  function close(except: Element | null) {
+    document.querySelectorAll<HTMLDetailsElement>(MENUS).forEach(function (d) {
+      if (d !== except) d.open = false
+    })
+  }
+  document.addEventListener('click', function (e) {
+    var inside = (e.target as Element).closest('details.jump, details.sb-ws')
+    close(inside)
+  })
+  document.addEventListener('keydown', function (e) {
+    if (e.key !== 'Escape') return
+    var open = document.querySelector<HTMLDetailsElement>(MENUS)
+    if (!open) return
+    open.open = false
+    var s = open.querySelector('summary')
+    if (s) s.focus()
+  })
+
+  /* Hover intent on the breadcrumb only. The sidebar's workspace switcher stays
+     click-only on purpose: its panel opens directly over the lesson list, which
+     is where the pointer is headed, so hovering it would cover the thing
+     being reached for. The breadcrumb's panel drops over body text instead. */
+  var OPEN = 120,
+    SHUT = 260
+
+  document
+    .querySelectorAll<HTMLDetailsElement>('details.jump')
+    .forEach(function (d) {
+      var host = d.closest('.crumb-item') || d
+      var timer: ReturnType<typeof setTimeout> | undefined
+      var openedByHover = false
+
+      function arm(want: boolean) {
+        clearTimeout(timer)
+        timer = setTimeout(
+          function () {
+            if (want) close(d)
+            d.open = want
+          },
+          want ? OPEN : SHUT,
+        )
+      }
+
+      host.addEventListener('mouseenter', function () {
+        if (!d.open) openedByHover = true
+        arm(true)
+      })
+      host.addEventListener('mouseleave', function () {
+        openedByHover = false
+        arm(false)
+      })
+      /* Keeps it open while the pointer is inside the panel, without cancelling a
+       pending open, which is what silently disabled this on one of two menus. */
+      d.addEventListener('mouseenter', function () {
+        if (d.open) clearTimeout(timer)
+      })
+
+      /* Hover and click were wired to one disclosure and fought: hover opened the
+       panel, then the summary's native click toggled what hover had already
+       opened, so reaching for an item shut it. A click on a panel hover opened
+       keeps it open, and a second click closes. The click path stays live for
+       touch, where no hover exists, and for the keyboard, where Enter is the
+       only way in. */
+      var summary = d.querySelector('summary')
+      if (summary)
+        summary.addEventListener('click', function (e) {
+          if (d.open && openedByHover) {
+            e.preventDefault()
+            openedByHover = false
+          }
+        })
+    })
+}

package/src/teach/browser/focus-line.ts

@@ -0,0 +1,19 @@
+/**
+ * The outline rail's focus-line ramp. It runs from near the top at scroll 0 to
+ * the viewport's bottom edge at max scroll, so the last heading is reachable
+ * however little content trails it. A ramp ending 120px short of the edge left
+ * a heading with under 120px after it permanently unmarked, since its top never
+ * fell below the line even at max scroll.
+ *
+ * The sidebar script embeds this function's own source, so a test exercises
+ * what the browser runs.
+ */
+export function focusLine(
+  scrollY: number,
+  max: number,
+  innerHeight: number,
+): number {
+  if (max <= 0) return innerHeight
+  var progress = Math.min(1, Math.max(0, scrollY / max))
+  return 120 + progress * Math.max(0, innerHeight - 120)
+}

package/src/teach/browser/glossary-filter.ts

@@ -0,0 +1,44 @@
+export function glossaryFilter(): void {
+  var input = document.getElementById('gfilter') as HTMLInputElement | null
+  var list = document.getElementById('gloss')
+  var count = document.getElementById('gloss-count')
+  if (!input || !list) return
+  var field = input
+  var terms = list
+  function updateGroups() {
+    terms.querySelectorAll('.gloss-group').forEach(function (heading) {
+      var el = heading.nextElementSibling as HTMLElement | null
+      var any = false
+      while (el && !el.classList.contains('gloss-group')) {
+        if (el.style.display !== 'none') any = true
+        el = el.nextElementSibling as HTMLElement | null
+      }
+      ;(heading as HTMLElement).style.display = any ? '' : 'none'
+    })
+  }
+  field.addEventListener('input', function () {
+    var q = field.value.toLowerCase()
+    var n = 0
+    terms.querySelectorAll<HTMLElement>('.gterm').forEach(function (entry) {
+      var match = (entry.textContent as string).toLowerCase().includes(q)
+      entry.style.display = match ? '' : 'none'
+      if (match) n++
+    })
+    terms.classList.toggle('none', n === 0)
+    updateGroups()
+    if (count) {
+      var total = terms.querySelectorAll('.gterm').length
+      count.textContent =
+        (n === total ? total : n + ' of ' + total) +
+        (total === 1 ? ' term' : ' terms')
+    }
+  })
+  var clear = terms.querySelector('.clear')
+  if (clear) {
+    clear.addEventListener('click', function () {
+      field.value = ''
+      field.dispatchEvent(new Event('input'))
+      field.focus()
+    })
+  }
+}

package/src/teach/browser/head.ts

@@ -0,0 +1,30 @@
+/**
+ * The panel's state, settled before the first paint rather than after it. An
+ * arm that set the narrow default afterwards slid the panel in and back out on
+ * every load, and a restored custom width animated in from the default.
+ *
+ * A listing page starts shut because the body already lists what the panel
+ * would, and a lesson starts open because there the panel is the only
+ * cross-lesson navigation on the page. A stored preference beats both. A count
+ * threshold on its own was built and reverted, since it hides the panel on a
+ * lesson too.
+ */
+export function head(page: 'index' | 'lesson', breakpoint: number): void {
+  var r = document.documentElement
+  var s: string | null = null
+  r.dataset.page = page
+  if (matchMedia('(max-width: ' + breakpoint + 'px)').matches) {
+    r.classList.add('sb-shut')
+    return
+  }
+  try {
+    s = localStorage.getItem('teach-sb')
+  } catch (e) {}
+  var idx = r.dataset.page === 'index'
+  if (s === 'shut' || (s === null && idx)) r.classList.add('sb-shut')
+  var w: string | null = null
+  try {
+    w = localStorage.getItem('teach-sb-w')
+  } catch (e) {}
+  if (w) r.style.setProperty('--sb-w', w + 'px')
+}

package/src/teach/browser/quiz.ts

@@ -0,0 +1,19 @@
+/**
+ * What reveals feedback in a lesson written with button options. The radio
+ * shape needs none of it.
+ */
+export function quiz(): void {
+  document.querySelectorAll<HTMLElement>('.q').forEach(function (q) {
+    var f = q.querySelector('.fb') as HTMLElement
+    q.querySelectorAll<HTMLElement>('.opt').forEach(function (b) {
+      b.addEventListener('click', function () {
+        if (f.classList.contains('show')) return
+        q.querySelectorAll<HTMLElement>('.opt').forEach(function (o) {
+          o.dataset.state =
+            o.dataset.a === '1' ? 'right' : o === b ? 'chosen' : 'wrong'
+        })
+        f.classList.add('show')
+      })
+    })
+  })
+}