@erclx/canon 5.18.0 → 5.20.0

package/src/serve/live.ts

@@ -0,0 +1,113 @@
+import { type FSWatcher, watch } from 'node:fs'
+import { SERVE_HOST } from '@/serve/static'
+
+/**
+ * How long a burst of watch events for one path waits before it is sent. One
+ * editor save raises several, and each would otherwise reach a reader again.
+ */
+const SETTLE_MS = 40
+
+export interface LiveOptions<T> {
+  /**
+   * Turns a changed path, relative to the watched directory, into what a change
+   * carries, or into undefined to drop it, such as a write's staging file.
+   */
+  readonly map: (path: string) => T | undefined
+  /**
+   * Takes each settled change in place of the clients. A caller that has work
+   * to do before a reader may look, such as regenerating pages, sends its own
+   * payload through `send` once that work lands.
+   */
+  readonly onChange?: (payload: T) => void
+}
+
+/**
+ * Whether a request names this server by a loopback name and its own port.
+ * The bind keeps other machines out, and this keeps out a page the operator
+ * visits whose domain was rebound to 127.0.0.1, which reaches the socket with
+ * its own name in the Host header.
+ */
+export function isLoopbackHost(host: string | null, port: number): boolean {
+  return host === `${SERVE_HOST}:${port}` || host === `localhost:${port}`
+}
+
+/**
+ * Watches a directory and fans each settled change out as a server-sent event
+ * to every open client, or to `onChange` when the caller takes changes itself.
+ */
+export class LiveStream<T> {
+  private readonly clients = new Set<ReadableStreamDefaultController<string>>()
+  private readonly pending = new Map<string, ReturnType<typeof setTimeout>>()
+  private readonly watcher: FSWatcher
+
+  constructor(
+    dir: string,
+    private readonly options: LiveOptions<T>,
+  ) {
+    this.watcher = watch(dir, { recursive: true }, (_event, filename) => {
+      if (filename) this.queue(filename.toString())
+    })
+  }
+
+  private queue(path: string): void {
+    const payload = this.options.map(path)
+    if (payload === undefined) return
+    clearTimeout(this.pending.get(path))
+    this.pending.set(
+      path,
+      setTimeout(() => {
+        this.pending.delete(path)
+        if (this.options.onChange) this.options.onChange(payload)
+        else this.send(payload)
+      }, SETTLE_MS),
+    )
+  }
+
+  send(payload: unknown): void {
+    const frame = `data: ${JSON.stringify(payload)}\n\n`
+    for (const client of this.clients) client.enqueue(frame)
+  }
+
+  open(): Response {
+    let self: ReadableStreamDefaultController<string> | undefined
+    const stream = new ReadableStream<string>({
+      start: (controller) => {
+        self = controller
+        this.clients.add(controller)
+        controller.enqueue(': open\n\n')
+      },
+      cancel: () => {
+        if (self) this.clients.delete(self)
+      },
+    })
+    return new Response(stream, {
+      headers: {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-store',
+      },
+    })
+  }
+
+  /** Opens a stream for a request naming this server, and refuses any other. */
+  answer(request: Request, port: number): Response {
+    if (isLoopbackHost(request.headers.get('host'), port)) return this.open()
+    return new Response('Forbidden\n', {
+      status: 403,
+      headers: { 'content-type': 'text/plain; charset=utf-8' },
+    })
+  }
+
+  close(): void {
+    this.watcher.close()
+    for (const timer of this.pending.values()) clearTimeout(timer)
+    this.pending.clear()
+    for (const client of this.clients) {
+      try {
+        client.close()
+      } catch {
+        /* Already closed by the browser going away. */
+      }
+    }
+    this.clients.clear()
+  }
+}

package/src/serve/static.ts

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs'
 import { join, resolve, sep } from 'node:path'
+import type { LiveStream } from '@/serve/live'
 
 /**
  * The loopback interface, never a wildcard bind. A preview serves whatever
@@ -78,11 +79,25 @@ export interface ServeStarted {
 
 export type ServeOutcome = ServeStarted | ServeRefused
 
+/** The route a live page's script opens its event stream on. */
+export const LIVE_EVENTS_PATH = '/__live'
+
+export interface LiveServe {
+  readonly stream: Pick<LiveStream<unknown>, 'answer'>
+  /**
+   * The `<script>` element spliced into every page served, built by the caller
+   * so this module stays free of what a reload means to any one surface.
+   */
+  readonly script: string
+}
+
 export interface ServeOptions {
   readonly port?: number
   readonly entry?: string
   /** Answers a directory request with no index page by listing it. Off by default. */
   readonly index?: boolean
+  /** Answers the events route and splices a script into each page. Off by default. */
+  readonly live?: LiveServe
 }
 
 function escapeHtml(text: string): string {
@@ -253,16 +268,59 @@ export function bindFirstFree(
   return undefined
 }
 
+/**
+ * Splices the script in before the last closing body tag of a page. A page
+ * carrying none goes out as the bytes on disk, since guessing a place for it
+ * risks breaking markup the author wrote. The splice happens per response and
+ * never on disk, so a page the reader saves or commits carries no hook.
+ */
+export async function injectLive(
+  response: Response,
+  script: string,
+): Promise<Response> {
+  const type = response.headers.get('content-type') ?? ''
+  if (response.status !== 200 || !type.startsWith('text/html')) return response
+
+  const bytes = new Uint8Array(await response.arrayBuffer())
+  const html = new TextDecoder().decode(bytes)
+  /*
+   * Searched in the original rather than a lowercased copy, since lowercasing
+   * changes the length of some characters, such as İ, and an index read off
+   * the copy would cut the original inside the tag.
+   */
+  const at = [...html.matchAll(/<\/body>/gi)].at(-1)?.index
+  const init = { status: response.status, headers: response.headers }
+  if (at === undefined) return new Response(bytes, init)
+  return new Response(`${html.slice(0, at)}${script}${html.slice(at)}`, init)
+}
+
 function listen(
   root: string,
   first: number,
   index: boolean,
+  live: LiveServe | undefined,
 ): { server: BoundServer; port: number } | undefined {
+  if (!live) {
+    return bindFirstFree(first, (port) =>
+      Bun.serve({
+        hostname: SERVE_HOST,
+        port,
+        fetch: (request) => respond(root, request, index),
+      }),
+    )
+  }
   return bindFirstFree(first, (port) =>
     Bun.serve({
       hostname: SERVE_HOST,
       port,
-      fetch: (request) => respond(root, request, index),
+      /* The event stream stays open for as long as the page does. */
+      idleTimeout: 0,
+      fetch: async (request, server) => {
+        if (new URL(request.url).pathname === LIVE_EVENTS_PATH) {
+          return live.stream.answer(request, server.port ?? 0)
+        }
+        return injectLive(await respond(root, request, index), live.script)
+      },
     }),
   )
 }
@@ -378,7 +436,7 @@ export function startServer(
    */
   let bound: ReturnType<typeof listen>
   try {
-    bound = listen(root, first, options.index ?? false)
+    bound = listen(root, first, options.index ?? false, options.live)
   } catch (error) {
     const code = (error as NodeJS.ErrnoException).code ?? 'unknown'
     return refuse(

package/src/slides/convert/export.ts

@@ -0,0 +1,323 @@
+import { copyFileSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import JSZip from 'jszip'
+import type { Browser, Page } from 'playwright-core'
+import PptxGenJS from 'pptxgenjs'
+import { isBrowserMissing, isEngineMissing } from '@/browser/engine'
+import { resolveFrameTokens } from '@/canvas/tokens'
+import {
+  type DrawOp,
+  type Fallback,
+  planSlide,
+  type RefusedLink,
+} from '@/slides/convert/shapes'
+import {
+  ID_ATTRIBUTE,
+  type WalkedSlide,
+  walkSlide,
+} from '@/slides/convert/walk'
+
+/**
+ * Turns a folder of HTML slides into one editable deck. Chromium lays each
+ * slide out at 1280 by 720 in the project's tokens, `walkSlide` reads what it
+ * placed, `planSlide` maps the records onto shapes, and an element whose CSS has
+ * no mapping lands as a screenshot of itself.
+ *
+ * Every browser reference this feature adds lives here, and the command reaches
+ * it through a dynamic import so no other command resolves the engine.
+ */
+
+export const SLIDE_WIDTH = 1280
+export const SLIDE_HEIGHT = 720
+
+/** Device pixels per CSS pixel in every screenshot, so a picture stays sharp. */
+const SCREENSHOT_SCALE = 2
+
+/** English Metric Units per inch, the unit a slide's XML measures in. */
+const EMU_PER_INCH = 914400
+
+export interface SlideFallback extends Fallback {
+  readonly slide: number
+}
+
+export interface SlideRefusedLink extends RefusedLink {
+  readonly slide: number
+}
+
+export type ExportRefusal =
+  | 'empty-source'
+  | 'engine-missing'
+  | 'browser-missing'
+  | 'export-failed'
+
+export type ExportResult =
+  | {
+      readonly status: 'written'
+      readonly pptxPath: string
+      readonly mirrorPath?: string
+      readonly slideCount: number
+      readonly fallbacks: readonly SlideFallback[]
+      readonly refusedLinks: readonly SlideRefusedLink[]
+    }
+  | {
+      readonly status: 'refused'
+      readonly reason: ExportRefusal
+      readonly message: string
+    }
+
+export interface ExportOptions {
+  /** The project whose tokens the slides are laid out in. */
+  readonly root: string
+  readonly mirror?: string
+}
+
+function refused(reason: ExportRefusal, message: string): ExportResult {
+  return { status: 'refused', reason, message }
+}
+
+/** Every `.html` file directly in the folder, in filename order. */
+export function slideFiles(sourceDir: string): string[] {
+  return readdirSync(sourceDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.html'))
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+    .map((name) => join(sourceDir, name))
+}
+
+/** A picture whose bytes the post-write pass replaces or whose corners it rounds. */
+interface Patch {
+  readonly slide: number
+  readonly name: string
+  readonly png?: Buffer
+  readonly radius?: number
+}
+
+export async function exportHtmlDeck(
+  sourceDir: string,
+  outDir: string,
+  options: ExportOptions,
+): Promise<ExportResult> {
+  const files = slideFiles(sourceDir)
+  if (files.length === 0) {
+    return refused('empty-source', `${sourceDir} holds no .html slides`)
+  }
+
+  let chromium: typeof import('playwright-core').chromium
+  try {
+    ;({ chromium } = await import('playwright-core'))
+  } catch (error) {
+    if (!isEngineMissing(error)) throw error
+    return refused('engine-missing', 'playwright-core is not installed')
+  }
+
+  let browser: Browser
+  try {
+    browser = await chromium.launch()
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return refused(
+      isBrowserMissing(error) ? 'browser-missing' : 'export-failed',
+      message,
+    )
+  }
+
+  const tokens = resolveFrameTokens(options.root).css
+  const pptx = new PptxGenJS()
+  pptx.layout = 'LAYOUT_WIDE'
+  const fallbacks: SlideFallback[] = []
+  const refusedLinks: SlideRefusedLink[] = []
+  const patches: Patch[] = []
+
+  try {
+    const page = await browser.newPage({
+      viewport: { width: SLIDE_WIDTH, height: SLIDE_HEIGHT },
+      deviceScaleFactor: SCREENSHOT_SCALE,
+    })
+    for (const [index, file] of files.entries()) {
+      const slideNumber = index + 1
+      const walked = await layOut(page, file, tokens)
+      const plan = planSlide(walked.records, { slideCount: files.length })
+      fallbacks.push(
+        ...plan.fallbacks.map((each) => ({ ...each, slide: slideNumber })),
+      )
+      refusedLinks.push(
+        ...plan.refusedLinks.map((each) => ({ ...each, slide: slideNumber })),
+      )
+      const slide = pptx.addSlide()
+      slide.background = { color: walked.background.hex }
+      for (const [opIndex, op] of plan.ops.entries()) {
+        const name = `canon-${slideNumber}-${opIndex + 1}`
+        await draw(page, slide, { slide: slideNumber, name }, op, patches)
+      }
+    }
+  } catch (error) {
+    return refused(
+      'export-failed',
+      error instanceof Error ? error.message : String(error),
+    )
+  } finally {
+    await browser.close().catch(() => undefined)
+  }
+
+  const written = await pptx.write({ outputType: 'nodebuffer' })
+  if (!(written instanceof Uint8Array)) {
+    return refused('export-failed', 'pptxgenjs returned no buffer')
+  }
+  const deck = await applyPatches(written, patches)
+
+  mkdirSync(outDir, { recursive: true })
+  const fileName = `${basename(sourceDir)}.pptx`
+  const pptxPath = join(outDir, fileName)
+  writeFileSync(pptxPath, deck)
+
+  let mirrorPath: string | undefined
+  if (options.mirror) {
+    mkdirSync(options.mirror, { recursive: true })
+    mirrorPath = join(options.mirror, fileName)
+    copyFileSync(pptxPath, mirrorPath)
+  }
+
+  return {
+    status: 'written',
+    pptxPath,
+    mirrorPath,
+    slideCount: files.length,
+    fallbacks,
+    refusedLinks,
+  }
+}
+
+/**
+ * The tokens go in ahead of the slide's own styles, so a slide reads
+ * `var(--color-*)` from the project and can still override any of it.
+ */
+async function layOut(
+  page: Page,
+  file: string,
+  tokens: string,
+): Promise<WalkedSlide> {
+  await page.goto(pathToFileURL(file).href, { waitUntil: 'load' })
+  if (tokens) {
+    await page.evaluate((css) => {
+      const style = document.createElement('style')
+      style.textContent = css
+      document.head.prepend(style)
+    }, tokens)
+  }
+  await page.evaluate(() => document.fonts.ready.then(() => undefined))
+  return page.evaluate(walkSlide, ID_ATTRIBUTE)
+}
+
+async function screenshot(page: Page, id: number): Promise<Buffer> {
+  return page
+    .locator(`[${ID_ATTRIBUTE}="${id}"]`)
+    .screenshot({ omitBackground: true, animations: 'disabled' })
+}
+
+function imageSource(src: string): Pick<PptxGenJS.ImageProps, 'path' | 'data'> {
+  if (src.startsWith('data:')) return { data: src.slice('data:'.length) }
+  if (src.startsWith('file:')) return { path: fileURLToPath(src) }
+  return { path: src }
+}
+
+const base64 = (bytes: Buffer | string): string =>
+  Buffer.from(bytes).toString('base64')
+
+async function draw(
+  page: Page,
+  slide: PptxGenJS.Slide,
+  target: { readonly slide: number; readonly name: string },
+  op: DrawOp,
+  patches: Patch[],
+): Promise<void> {
+  if (op.kind === 'shape') {
+    slide.addShape(op.shape, op.options)
+  } else if (op.kind === 'text') {
+    slide.addText(op.runs, op.options)
+  } else if (op.kind === 'table') {
+    slide.addTable(op.rows, op.options)
+  } else if (op.kind === 'image') {
+    slide.addImage({
+      ...op.options,
+      ...imageSource(op.src),
+      objectName: target.name,
+    })
+    if (op.radius > 0) patches.push({ ...target, radius: op.radius })
+    if (op.frame) slide.addShape(op.radius > 0 ? 'roundRect' : 'rect', op.frame)
+  } else if (op.kind === 'svg') {
+    slide.addImage({
+      ...op.options,
+      data: `image/svg+xml;base64,${base64(op.markup)}`,
+      objectName: target.name,
+    })
+    patches.push({ ...target, png: await screenshot(page, op.id) })
+  } else {
+    const png = await screenshot(page, op.id)
+    slide.addImage({ ...op.options, data: `image/png;base64,${base64(png)}` })
+  }
+}
+
+/**
+ * Two things pptxgenjs cannot write, fixed in the package it wrote. An SVG's
+ * PNG fallback comes out as the SVG's own bytes under a `.png` name in Node, so
+ * a viewer that cannot draw SVG gets a broken image, and a picture takes no
+ * corner radius. Each patched picture is found by the object name `draw` gave
+ * it, which is the only handle the written XML keeps.
+ */
+async function applyPatches(
+  deck: Uint8Array,
+  patches: readonly Patch[],
+): Promise<Buffer> {
+  const zip = await JSZip.loadAsync(deck)
+  const bySlide = Map.groupBy(patches, (patch) => patch.slide)
+  for (const [slideNumber, slidePatches] of bySlide) {
+    const slidePath = `ppt/slides/slide${slideNumber}.xml`
+    const relsPath = `ppt/slides/_rels/slide${slideNumber}.xml.rels`
+    let xml = (await zip.file(slidePath)?.async('string')) ?? ''
+    const rels = (await zip.file(relsPath)?.async('string')) ?? ''
+    for (const patch of slidePatches) {
+      const pic = pictureXml(xml, patch.name)
+      if (!pic) continue
+      if (patch.png) {
+        const rId = /<a:blip r:embed="(rId\d+)"/.exec(pic)?.[1]
+        const target = rId
+          ? new RegExp(`Id="${rId}"[^>]*Target="\\.\\./([^"]+)"`).exec(
+              rels,
+            )?.[1]
+          : undefined
+        if (target) zip.file(`ppt/${target}`, patch.png)
+      }
+      if (patch.radius) {
+        xml = xml.replace(pic, roundCorners(pic, patch.radius))
+      }
+    }
+    zip.file(slidePath, xml)
+  }
+  return zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' })
+}
+
+function pictureXml(xml: string, name: string): string | undefined {
+  const start = xml.indexOf(`name="${name}"`)
+  if (start < 0) return undefined
+  const open = xml.lastIndexOf('<p:pic>', start)
+  const close = xml.indexOf('</p:pic>', start)
+  return open < 0 || close < 0
+    ? undefined
+    : xml.slice(open, close + '</p:pic>'.length)
+}
+
+/** The adjust value is the radius over the shorter side, out of 100000. */
+function roundCorners(pic: string, radius: number): string {
+  const extent = /<a:ext cx="(\d+)" cy="(\d+)"\/>/.exec(pic)
+  const shorter = extent ? Math.min(Number(extent[1]), Number(extent[2])) : 0
+  if (shorter === 0) return pic
+  const adjust = Math.min(
+    50000,
+    Math.round((radius * EMU_PER_INCH * 100000) / shorter),
+  )
+  return pic.replace(
+    /<a:prstGeom prst="rect"><a:avLst\/><\/a:prstGeom>/,
+    `<a:prstGeom prst="roundRect"><a:avLst><a:gd name="adj" fmla="val ${adjust}"/></a:avLst></a:prstGeom>`,
+  )
+}