Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

34.2 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
//
// Geometry, fills and groups: p:sp / p:cxnSp / p:grpSp → OutShape.
//
// The census makes this module's budget clear: the entire preset vocabulary of
// six real decks is 12 names, a:custGeom is ZERO, and rect/roundRect/ellipse/
// line cover 95.9% of 4,927 shapes. So there is no geometry engine here — a
// map for the exact presets, three-and-a-half path generators for the rest
// (chevron 89, upArrowCallout 35, round2SameRect 32, bentConnector2/3/4 27),
// and 'rect' + a report for anything outside the census.
//
// Where the actual work lives, per the spike:
//
//   - 1,727 shapes carry NO local fill: it comes from p:style's a:fillRef into
//     the theme's fillStyleLst with phClr substituted — read only spPr and
//     they render unfilled with no error to notice. Same for a:lnRef strokes.
//   - An EMPTY <a:effectLst/> is an OVERRIDE that cancels an inherited effect;
//     only a chain level with no effectLst at all defers downward. Presence
//     and emptiness are therefore distinguished when walking the chain.
//   - Bento line shapes take their colour from `fill`, not `stroke` (the
//     stroke attr is what morphs tween) — shape 'line' gets BOTH set.
//   - flipH/flipV (68+22 slide-level uses in the re-census) have no bento
//     field. Where the flip is free it is CONSUMED exactly: line endpoints
//     swap, synthesized path coordinates mirror, a flipV triangle becomes a
//     path, a gradient angle mirrors. Only a flip nothing can absorb is
//     reported ('flip-dropped').
//
// ID SCHEME (integrator contract): a shape's element id is
// `s<slideIndex>-<cNvPr id>` — deterministic, so connector a:stCxn/a:endCxn
// refs resolve WITHOUT a lookup table (deps.spIds only validates existence;
// a dangling ref drops that end with a report). A source group's members share
// groupId `s<slideIndex>-g<cNvPr id>`; a filled box with text in it (the
// spike's ~1,000-per-corpus split case) reserves `s<slideIndex>-<spId>-g` —
// see ShapeResult.textGroupId. The morph/identity pass may rewrite ids later;
// within one slide's conversion they are stable.

import { NS, kid, kids, attr, intAttr, textOf, descendants, type XElem } from './xml.ts'
import {
  EMU_PER_PX,
  type InheritCtx, type OutShape, type OutGradient, type OutShadow,
} from './types.ts'
import { resolveColor, resolveFillRef, resolveLnRef, type ColorResult } from './theme.ts'
import { resolveFrame, labeledChain } from './inherit.ts'
import type { Provenance } from './report.ts'

// --- small arithmetic --------------------------------------------------------

/** EMU → px, 1/100px precision (the engine-wide convention media.ts set). */
const px = (emu: number): number => Math.round((emu / EMU_PER_PX) * 100) / 100
const r2 = (v: number): number => Math.round(v * 100) / 100
const pin = (lo: number, v: number, hi: number): number => Math.min(Math.max(v, lo), hi)
const DEG = Math.PI / 180

/** Report `where` — slide plus the shape's authored name. */
function whereOf(sp: XElem, slideIndex: number): string {
  for (const c of kids(sp)) {
    const cnv = kid(c, NS.p, 'cNvPr')
    if (cnv) {
      const name = attr(cnv, 'name')
      return `slide ${slideIndex} / sp ${name ? `"${name}"` : attr(cnv, 'id') ?? '?'}`
    }
  }
  return `slide ${slideIndex} / sp`
}

function cNvPrId(sp: XElem): string {
  for (const c of kids(sp)) {
    const cnv = kid(c, NS.p, 'cNvPr')
    if (cnv) return attr(cnv, 'id') ?? '0'
  }
  return '0'
}

// --- public types ------------------------------------------------------------

/** A frame in EMU + degrees — resolveFrame's shape, minus provenance. */
export interface GroupFrame {
  x: number; y: number; w: number; h: number
  rotation: number
  flipH: boolean
  flipV: boolean
}

export interface ShapeDeps {
  /** 1-based slide position — the id scheme needs it */
  slideIndex: number
  /** cNvPr ids present on the slide; connector refs outside it are dangling */
  spIds?: Set<string>
  /** absolute frame override (EMU) — groupChildren computed it; when set the
   *  placeholder chain walk is skipped */
  frame?: GroupFrame
  /** group membership — groupChildren minted it */
  groupId?: string
}

export interface ShapeResult {
  shape: OutShape
  /**
   * Set when the sp ALSO carries text (the box-with-text split): the
   * integrator must emit the text element with THIS groupId, placed
   * immediately AFTER the shape in the element array — later paints above,
   * so the text sits on the box. The shape's own groupId is already set.
   */
  textGroupId?: string
}

// --- adjust values -----------------------------------------------------------

/** a:avLst gd name→val. An EMPTY <a:avLst/> (the overwhelmingly common form)
 *  reads the same as an absent one: every preset default applies. */
function adjOf(geom: XElem | undefined): Map<string, number> {
  const out = new Map<string, number>()
  const av = geom && kid(geom, NS.a, 'avLst')
  if (!av) return out
  for (const gd of kids(av, NS.a, 'gd')) {
    const name = attr(gd, 'name')
    const fmla = attr(gd, 'fmla') ?? ''
    const m = /^val (-?\d+)$/.exec(fmla)
    if (name && m) out.set(name, parseInt(m[1], 10))
  }
  return out
}

// --- path synthesis ----------------------------------------------------------

// Paths are synthesized at the element's REAL px size (pathBox = [0,0,w,h])
// rather than a fixed 100×100: preset guides scale by min(w,h), so a fixed
// box would bake the wrong aspect into every non-square shape. pathBox
// stretches on later resize, exactly like any bento path.

type Seg =
  | { c: 'M' | 'L'; x: number; y: number }
  | { c: 'A'; r: number; x: number; y: number }
  | { c: 'Z' }

/** Serialize, baking flips into the coordinates. Mirroring across ONE axis
 *  reverses arc orientation, so the sweep flag toggles with flipH xor flipV. */
function serializeSegs(segs: Seg[], w: number, h: number, flipH: boolean, flipV: boolean): string {
  const fx = (x: number) => r2(flipH ? w - x : x)
  const fy = (y: number) => r2(flipV ? h - y : y)
  const sweep = flipH !== flipV ? 0 : 1
  return segs
    .map((s) => s.c === 'Z' ? 'Z'
      : s.c === 'A' ? `A${r2(s.r)} ${r2(s.r)} 0 0 ${sweep} ${fx(s.x)} ${fy(s.y)}`
        : `${s.c}${fx(s.x)} ${fy(s.y)}`)
    .join(' ')
}

/** The preset generators. Guides transcribed from ECMA-376's
 *  presetShapeDefinitions (ss = min(w,h), pin = the spec's pin). */
function presetSegs(prst: string, w: number, h: number, adj: Map<string, number>): Seg[] | undefined {
  const ss = Math.min(w, h)
  const a = (name: string, dflt: number) => adj.get(name) ?? dflt
  switch (prst) {
    case 'chevron': {
      const x1 = ss * pin(0, a('adj', 50000), (100000 * w) / ss) / 100000
      return [
        { c: 'M', x: 0, y: 0 }, { c: 'L', x: w - x1, y: 0 }, { c: 'L', x: w, y: h / 2 },
        { c: 'L', x: w - x1, y: h }, { c: 'L', x: 0, y: h }, { c: 'L', x: x1, y: h / 2 },
        { c: 'Z' },
      ]
    }
    case 'upArrowCallout': {
      const a2 = pin(0, a('adj2', 25000), (50000 * w) / ss)
      const a1 = pin(0, a('adj1', 25000), a2 * 2)
      const a3 = pin(0, a('adj3', 25000), (100000 * h) / ss)
      const a4 = pin(0, a('adj4', 64977), 100000 - (a3 * ss) / h)
      const dx1 = (ss * a2) / 100000, dx2 = (ss * a1) / 200000
      const y1 = (ss * a3) / 100000, y2 = h - (h * a4) / 100000
      const hc = w / 2
      return [
        { c: 'M', x: 0, y: y2 }, { c: 'L', x: hc - dx2, y: y2 }, { c: 'L', x: hc - dx2, y: y1 },
        { c: 'L', x: hc - dx1, y: y1 }, { c: 'L', x: hc, y: 0 }, { c: 'L', x: hc + dx1, y: y1 },
        { c: 'L', x: hc + dx2, y: y1 }, { c: 'L', x: hc + dx2, y: y2 }, { c: 'L', x: w, y: y2 },
        { c: 'L', x: w, y: h }, { c: 'L', x: 0, y: h }, { c: 'Z' },
      ]
    }
    case 'round2SameRect': {
      // top pair rounded by adj1, bottom pair by adj2 (default square)
      const r1 = r2((ss * pin(0, a('adj1', 16667), 50000)) / 100000)
      const rb = r2((ss * pin(0, a('adj2', 0), 50000)) / 100000)
      const segs: Seg[] = [{ c: 'M', x: r1, y: 0 }, { c: 'L', x: w - r1, y: 0 }]
      if (r1 > 0) segs.push({ c: 'A', r: r1, x: w, y: r1 })
      segs.push({ c: 'L', x: w, y: h - rb })
      if (rb > 0) segs.push({ c: 'A', r: rb, x: w - rb, y: h })
      segs.push({ c: 'L', x: rb, y: h })
      if (rb > 0) segs.push({ c: 'A', r: rb, x: 0, y: h - rb })
      segs.push({ c: 'L', x: 0, y: r1 })
      if (r1 > 0) segs.push({ c: 'A', r: r1, x: r1, y: 0 })
      segs.push({ c: 'Z' })
      return segs
    }
    case 'bentConnector2':
      return [{ c: 'M', x: 0, y: 0 }, { c: 'L', x: w, y: 0 }, { c: 'L', x: w, y: h }]
    case 'bentConnector3': {
      const x1 = (w * a('adj1', 50000)) / 100000
      return [
        { c: 'M', x: 0, y: 0 }, { c: 'L', x: x1, y: 0 },
        { c: 'L', x: x1, y: h }, { c: 'L', x: w, y: h },
      ]
    }
    case 'bentConnector4': {
      const x1 = (w * a('adj1', 50000)) / 100000
      const y1 = (h * a('adj2', 50000)) / 100000
      return [
        { c: 'M', x: 0, y: 0 }, { c: 'L', x: x1, y: 0 }, { c: 'L', x: x1, y: y1 },
        { c: 'L', x: w, y: y1 }, { c: 'L', x: w, y: h },
      ]
    }
    default:
      return undefined
  }
}

/** Bent connectors are open stroked polylines — never filled, no tip markers
 *  (render.ts only puts markers on shape 'line'). */
const OPEN_PATHS = new Set(['bentConnector2', 'bentConnector3', 'bentConnector4'])

// --- fills -------------------------------------------------------------------

const FILL_LOCALS = new Set(['solidFill', 'gradFill', 'blipFill', 'pattFill', 'grpFill', 'noFill'])

/** First fill element up the placeholder chain — a nearer noFill is a real
 *  declaration, so ANY fill child stops the walk. */
function chainFill(sp: XElem, ctx: InheritCtx): { el: XElem; from: Provenance } | undefined {
  for (const link of labeledChain(sp, ctx)) {
    const spPr = kid(link.el, NS.p, 'spPr')
    const f = spPr && kids(spPr, NS.a).find((k) => FILL_LOCALS.has(k.local))
    if (f) return { el: f, from: link.from }
  }
  return undefined
}

/** First p:style up the chain (a layout placeholder can carry one too). */
function chainStyle(sp: XElem, ctx: InheritCtx): XElem | undefined {
  for (const link of labeledChain(sp, ctx)) {
    const st = kid(link.el, NS.p, 'style')
    if (st) return st
  }
  return undefined
}

/**
 * The phClr a style ref substitutes, as the '#RRGGBB' resolveFillRef requires.
 * Style ref colours with alpha do not occur in the census (theme.ts's note);
 * if one shows up the alpha is stripped and reported rather than failing the
 * whole fill.
 */
function phClrOf(ref: XElem, ctx: InheritCtx, where: string): string {
  const c = resolveColor(ref, ctx.theme)
  if (!c) {
    ctx.report.add('dropped', 'style-color-unresolved', where,
      'p:style reference colour did not resolve — phClr substituted as black')
    return '#000000'
  }
  if (c.css.startsWith('#')) return c.css
  const m = /^rgba\((\d+),(\d+),(\d+),/.exec(c.css)
  if (m) {
    ctx.report.add('approximated', 'phclr-alpha-dropped', where,
      'style reference colour carries alpha — dropped for phClr substitution')
    const h2 = (v: string) => parseInt(v, 10).toString(16).padStart(2, '0').toUpperCase()
    return `#${h2(m[1])}${h2(m[2])}${h2(m[3])}`
  }
  return '#000000'
}

/**
 * a:gradFill → bento GradientFill. ANGLES: OOXML a:lin@ang is 60,000ths of a
 * degree clockwise from 3 o'clock in a y-down space — ang 0 runs left→right,
 * 5400000 (90°) runs top→bottom. Bento/CSS convention (render.ts
 * gradientLineCoords): 0deg = bottom→top, 90deg = left→right, 180deg =
 * top→bottom. Both rotate the same way, offset a quarter turn:
 * css = ooxmlDeg + 90. (The tempting straight read — 5400000 → 90deg CSS —
 * paints every vertical gradient sideways; the rig pins 5400000 → 180.)
 */
function gradientFrom(g: XElem, ctx: InheritCtx, phClr: string | undefined, where: string): OutGradient | undefined {
  const gsLst = kid(g, NS.a, 'gsLst')
  const stops: Array<{ at: number; color: string }> = []
  if (gsLst) {
    for (const gs of kids(gsLst, NS.a, 'gs')) {
      const color = resolveColor(gs, ctx.theme, phClr)
      if (!color) {
        ctx.report.add('dropped', 'gradient-stop-unresolved', where,
          'a gradient stop colour did not resolve and was skipped')
        continue
      }
      stops.push({ at: pin(0, intAttr(gs, 'pos') / 100000, 1), color: color.css })
    }
  }
  stops.sort((s1, s2) => s1.at - s2.at)
  if (stops.length < 2) return undefined

  let angle: number
  const lin = kid(g, NS.a, 'lin')
  if (lin) angle = ((intAttr(lin, 'ang') / 60000 + 90) % 360 + 360) % 360
  else if (kid(g, NS.a, 'path')) {
    ctx.report.add('approximated', 'radial-gradient-linearized', where,
      'radial/path gradient approximated as a vertical linear gradient')
    angle = 180
  } else angle = 90 // no a:lin: OOXML's implicit ang 0, left→right
  return { angle, stops }
}

interface FillOut {
  fill: string
  gradient?: OutGradient
  /** resolution FAILED (reported) — distinct from an intentional noFill; a
   *  failed shape still emits so the report entry has something to point at */
  failed: boolean
}

function resolveShapeFill(sp: XElem, ctx: InheritCtx, style: XElem | undefined, where: string): FillOut {
  const own = chainFill(sp, ctx)
  if (own) {
    switch (own.el.local) {
      case 'noFill':
        ctx.report.trace('fill', own.from)
        return { fill: 'transparent', failed: false }
      case 'solidFill': {
        const c = resolveColor(own.el, ctx.theme)
        if (!c) break
        ctx.report.trace('fill', own.from === 'own' ? c.from : own.from)
        return { fill: c.css, failed: false }
      }
      case 'gradFill': {
        const g = gradientFrom(own.el, ctx, undefined, where)
        if (!g) break
        ctx.report.trace('fill', own.from)
        // solid fallback: the last stop (bento keeps `fill` beneath a gradient)
        return { fill: g.stops[g.stops.length - 1].color, gradient: g, failed: false }
      }
      case 'blipFill':
        ctx.report.add('dropped', 'picture-fill-dropped', where,
          'picture fill on a shape has no bento counterpart — filled transparent')
        return { fill: 'transparent', failed: true }
      default: // pattFill / grpFill: 0/6 in the census
        ctx.report.add('dropped', 'fill-unsupported', where,
          `a:${own.el.local} has no bento counterpart — filled transparent`)
        return { fill: 'transparent', failed: true }
    }
    ctx.report.add('dropped', 'fill-unresolved', where,
      'fill colour did not resolve — filled transparent')
    return { fill: 'transparent', failed: true }
  }

  // no fill element anywhere up the chain: the style matrix (1,727 census
  // shapes live or die on this walk)
  const ref = style && kid(style, NS.a, 'fillRef')
  if (ref) {
    const idx = intAttr(ref, 'idx')
    const got = resolveFillRef(idx, phClrOf(ref, ctx, where), ctx.theme)
    if (!got) {
      ctx.report.add('dropped', 'fill-unresolved', where,
        `a:fillRef idx="${idx}" points outside the theme's fill styles — filled transparent`)
      return { fill: 'transparent', failed: true }
    }
    if (got.kind === 'none') return { fill: 'transparent', failed: false }
    if (got.kind === 'solid') {
      ctx.report.trace('fill', 'theme')
      return { fill: got.color.css, failed: false }
    }
    // 'other': the raw fillStyleLst entry — gradFill here, blipFill never
    // (theme bg image styles are not shape styles in practice)
    if (got.el.local === 'gradFill') {
      const g = gradientFrom(got.el, ctx, got.phClr, where)
      if (g) {
        ctx.report.trace('fill', 'theme')
        return { fill: g.stops[g.stops.length - 1].color, gradient: g, failed: false }
      }
    }
    ctx.report.add('dropped', 'fill-unresolved', where,
      `theme fill style ${idx} (a:${got.el.local}) did not resolve — filled transparent`)
    return { fill: 'transparent', failed: true }
  }

  ctx.report.trace('fill', 'default')
  return { fill: 'transparent', failed: false }
}

// --- strokes -----------------------------------------------------------------

interface LnOut {
  color?: ColorResult
  widthPx: number
  style: 'solid' | 'dashed' | 'dotted'
  start: 'none' | 'arrow' | 'dot' | 'bar'
  end: 'none' | 'arrow' | 'dot' | 'bar'
  failed: boolean
}

const NO_LINE: LnOut = { widthPx: 0, style: 'solid', start: 'none', end: 'none', failed: false }

const dashOf = (v: string | undefined): LnOut['style'] =>
  v === undefined || v === 'solid' ? 'solid' : v === 'dot' || v === 'sysDot' ? 'dotted' : 'dashed'

const tipOf = (v: string | undefined): LnOut['start'] =>
  v === 'triangle' || v === 'arrow' || v === 'stealth' ? 'arrow'
    : v === 'oval' || v === 'diamond' ? 'dot' : 'none'

function chainLn(sp: XElem, ctx: InheritCtx): { el: XElem; from: Provenance } | undefined {
  for (const link of labeledChain(sp, ctx)) {
    const spPr = kid(link.el, NS.p, 'spPr')
    const ln = spPr && kid(spPr, NS.a, 'ln')
    if (ln) return { el: ln, from: link.from }
  }
  return undefined
}

/**
 * The stroke: a local a:ln overrides per-attribute over the lnRef style base
 * (width/dash/tips read local-first), colour precedence local solidFill →
 * lnRef's pre-resolved colour → black (DrawingML's documented line default —
 * an a:ln with no fill child still draws).
 */
function resolveStroke(sp: XElem, ctx: InheritCtx, style: XElem | undefined, where: string): LnOut {
  const own = chainLn(sp, ctx)
  const ref = style && kid(style, NS.a, 'lnRef')
  let styleLn: XElem | undefined
  let styleColor: ColorResult | undefined
  if (ref) {
    const idx = intAttr(ref, 'idx')
    const got = resolveLnRef(idx, phClrOf(ref, ctx, where), ctx.theme)
    if (got === undefined && idx > 0) {
      ctx.report.add('dropped', 'stroke-unresolved', where,
        `a:lnRef idx="${idx}" points outside the theme's line styles — no stroke`)
    } else if (got && got.kind === 'ln') {
      styleLn = got.ln
      styleColor = got.color
      if (!styleColor && kid(got.ln, NS.a, 'gradFill')) {
        const g = gradientFrom(kid(got.ln, NS.a, 'gradFill')!, ctx, got.phClr, where)
        if (g) {
          styleColor = { css: g.stops[0].color, alpha: 1, from: 'theme' }
          ctx.report.add('approximated', 'gradient-stroke-approximated', where,
            'gradient stroke flattened to its first stop colour')
        }
      }
    }
  }
  if (!own && !styleLn) return NO_LINE

  const base = own?.el
  const pick = (name: string): string | undefined =>
    (base && attr(base, name)) ?? (styleLn && attr(styleLn, name))
  const pickKid = (local: string): XElem | undefined =>
    (base && kid(base, NS.a, local)) ?? (styleLn && kid(styleLn, NS.a, local))

  // explicit noFill on the nearest ln = no outline, full stop
  if (base && kid(base, NS.a, 'noFill')) return NO_LINE

  const wAttr = pick('w')
  const widthPx = px(wAttr !== undefined ? parseInt(wAttr, 10) : 9525) // OOXML default: 0.75pt

  let color: ColorResult | undefined
  let failed = false
  const ownFill = base && kid(base, NS.a, 'solidFill')
  if (ownFill) {
    color = resolveColor(ownFill, ctx.theme)
    if (!color) {
      ctx.report.add('dropped', 'stroke-unresolved', where,
        'stroke colour did not resolve — no stroke painted')
      failed = true
    } else ctx.report.trace('stroke', own ? (own.from === 'own' ? color.from : own.from) : 'theme')
  } else if (base && kid(base, NS.a, 'gradFill')) {
    const g = gradientFrom(kid(base, NS.a, 'gradFill')!, ctx, undefined, where)
    if (g) {
      color = { css: g.stops[0].color, alpha: 1, from: 'own' }
      ctx.report.add('approximated', 'gradient-stroke-approximated', where,
        'gradient stroke flattened to its first stop colour')
    } else failed = true
  } else if (styleColor) {
    color = styleColor
    ctx.report.trace('stroke', 'theme')
  } else {
    color = { css: '#000000', alpha: 1, from: 'own' }
    ctx.report.trace('stroke', 'default')
  }

  const dash = pickKid('prstDash')
  const head = pickKid('headEnd')
  const tail = pickKid('tailEnd')
  const out: LnOut = {
    widthPx,
    style: dashOf(dash ? attr(dash, 'val') : undefined),
    start: tipOf(head ? attr(head, 'type') : undefined),
    end: tipOf(tail ? attr(tail, 'type') : undefined),
    failed,
  }
  if (color) out.color = color
  return out
}

// --- effects -----------------------------------------------------------------

/**
 * The chain walk distinguishes PRESENT-BUT-EMPTY from ABSENT (the spike trap):
 * the nearest level carrying an a:effectLst element wins whole — an empty one
 * is an override cancelling an inherited shadow, only a level with no
 * effectLst at all defers to the next.
 */
function resolveShadow(sp: XElem, ctx: InheritCtx, where: string): OutShadow | undefined {
  for (const link of labeledChain(sp, ctx)) {
    const spPr = kid(link.el, NS.p, 'spPr')
    const lst = spPr && kid(spPr, NS.a, 'effectLst')
    if (!lst) continue
    const shdw = kid(lst, NS.a, 'outerShdw')
    for (const other of kids(lst, NS.a)) {
      if (other.local !== 'outerShdw') {
        ctx.report.add('dropped', 'effect-dropped', where,
          `a:${other.local} has no bento counterpart`)
      }
    }
    if (!shdw) return undefined // declared list without outerShdw = no shadow
    const color = resolveColor(shdw, ctx.theme)
    if (!color) {
      ctx.report.add('dropped', 'shadow-color-unresolved', where,
        'outer shadow colour did not resolve — shadow dropped')
      return undefined
    }
    const dist = px(intAttr(shdw, 'dist'))
    const dir = (intAttr(shdw, 'dir') / 60000) * DEG // clockwise from 3 o'clock, y-down — matches CSS offsets
    return {
      x: r2(Math.cos(dir) * dist),
      y: r2(Math.sin(dir) * dist),
      blur: px(intAttr(shdw, 'blurRad')),
      color: color.css,
    }
  }
  return undefined
}

// --- shapeFrom ---------------------------------------------------------------

/** First prstGeom (or custGeom) up the chain — ~513 census shapes carry no
 *  geometry of their own and read the layout placeholder's. */
function chainGeom(sp: XElem, ctx: InheritCtx): XElem | undefined {
  for (const link of labeledChain(sp, ctx)) {
    const spPr = kid(link.el, NS.p, 'spPr')
    const g = spPr && (kid(spPr, NS.a, 'prstGeom') ?? kid(spPr, NS.a, 'custGeom'))
    if (g) return g
  }
  return undefined
}

function hasTextContent(sp: XElem): boolean {
  const tb = kid(sp, NS.p, 'txBody')
  if (!tb) return false
  return textOf(tb).trim() !== '' || descendants(tb, NS.a, 'fld').length > 0
}

/** Mirror a CSS-convention gradient angle: flips a symmetric shape cannot
 *  express still move its gradient, and that part is free to keep exact. */
function mirrorAngle(angle: number, flipH: boolean, flipV: boolean): number {
  let out = angle
  if (flipH) out = (360 - out) % 360
  if (flipV) out = ((180 - out) % 360 + 360) % 360
  return out
}

/**
 * Convert one p:sp or p:cxnSp. Returns undefined for INVISIBLE geometry — the
 * bare text box (noFill, no stroke, no shadow), whose txBody the text module
 * carries alone. A shape whose fill/stroke FAILED to resolve still emits (the
 * report entry needs an element to point at); an intentional noFill does not.
 */
export function shapeFrom(sp: XElem, ctx: InheritCtx, deps: ShapeDeps): ShapeResult | undefined {
  const where = whereOf(sp, deps.slideIndex)
  const spId = cNvPrId(sp)
  const fr = deps.frame ?? resolveFrame(sp, ctx)
  const x = px(fr.x), y = px(fr.y), w = px(fr.w), h = px(fr.h)
  let rotation = r2(fr.rotation)
  let { flipH, flipV } = fr

  const geom = chainGeom(sp, ctx)
  let prst = geom && geom.local === 'prstGeom' ? attr(geom, 'prst') ?? 'rect' : 'rect'
  if (geom && geom.local === 'custGeom') {
    // 0/6 in the census — approximated loudly, never parsed
    ctx.report.add('approximated', 'shape-approximated', where,
      'a:custGeom approximated as a rectangle')
  }
  const adj = adjOf(geom)

  const style = chainStyle(sp, ctx)
  const stroke = resolveStroke(sp, ctx, style, where)

  const shape: OutShape = {
    id: `s${deps.slideIndex}-${spId}`,
    type: 'shape',
    x, y, w, h, rotation,
    opacity: 1,
    shape: 'rect',
    fill: 'transparent',
    stroke: 'transparent',
    strokeWidth: 0,
    radius: 0,
  }

  // ---- line-family presets: bento draws lines horizontally through the box
  // centre and orients by rotation, so the OOXML box diagonal (start at the
  // box's top-left, flips choosing which diagonal) becomes length + angle.
  // Colour-from-fill gotcha: line shapes paint el.fill as the stroke.
  if (prst === 'line' || prst === 'straightConnector1') {
    const color = stroke.color?.css ?? '#000000'
    if (!stroke.color && !stroke.failed) ctx.report.trace('stroke', 'default')
    let p1: [number, number] = [x, y]
    let p2: [number, number] = [x + w, y + h]
    if (flipH) { p1 = [x + w, p1[1]]; p2 = [x, p2[1]] }
    if (flipV) { p1 = [p1[0], y + h]; p2 = [p2[0], y] }
    const len = Math.hypot(w, h)
    const diag = Math.atan2(p2[1] - p1[1], p2[0] - p1[0]) / DEG
    const elH = Math.max(stroke.widthPx, 2)
    shape.shape = 'line'
    shape.x = r2(x + w / 2 - len / 2)
    shape.y = r2(y + h / 2 - elH / 2)
    shape.w = r2(len)
    shape.h = r2(elH)
    shape.rotation = r2(rotation + diag)
    shape.fill = color
    shape.stroke = color
    shape.strokeWidth = stroke.widthPx || 1
    if (stroke.style !== 'solid') shape.strokeStyle = stroke.style
    if (stroke.start !== 'none') shape.lineStart = stroke.start
    if (stroke.end !== 'none') shape.lineEnd = stroke.end
    const lnShadow = resolveShadow(sp, ctx, where)
    if (lnShadow) shape.shadow = lnShadow
    attachConnectorEnds(sp, shape, ctx, deps, where)
    if (deps.groupId) shape.groupId = deps.groupId
    return { shape }
  }

  // ---- fills / effects (everything with an interior)
  const fill = resolveShapeFill(sp, ctx, style, where)
  const shadow = resolveShadow(sp, ctx, where)

  const openPath = OPEN_PATHS.has(prst)
  let flipConsumed = false

  // a flipped triangle cannot stay 'triangle' (bento's points up); its
  // synthesized polygon absorbs the flip exactly
  const kindHint =
    prst === 'rect' || prst === 'roundRect' ? 'rect'
      : prst === 'ellipse' ? 'ellipse'
        : prst === 'triangle' ? (flipV ? 'path' : 'triangle')
          : prst === 'rightArrow' ? 'arrow'
            : undefined

  if (kindHint) {
    shape.shape = kindHint
    if (prst === 'roundRect') {
      const a = pin(0, adj.get('adj') ?? 16667, 50000)
      shape.radius = r2((Math.min(w, h) * a) / 100000)
    }
    if (prst === 'triangle' && flipV) {
      shape.d = serializeSegs(
        [{ c: 'M', x: w / 2, y: 0 }, { c: 'L', x: w, y: h }, { c: 'L', x: 0, y: h }, { c: 'Z' }],
        w, h, flipH, flipV)
      shape.pathBox = [0, 0, w, h]
      flipConsumed = true
    }
    // rect/roundRect/ellipse are mirror-symmetric (and a triangle across its
    // vertical axis): a flip only moves a gradient, and mirroring its angle
    // carries that exactly
    if (kindHint === 'rect' || kindHint === 'ellipse' || kindHint === 'triangle') flipConsumed = true
  } else {
    const segs = presetSegs(prst, w, h, adj)
    if (segs) {
      shape.shape = 'path'
      shape.d = serializeSegs(segs, w, h, flipH, flipV)
      shape.pathBox = [0, 0, w, h]
      flipConsumed = true
      if (openPath && (stroke.start !== 'none' || stroke.end !== 'none')) {
        ctx.report.add('approximated', 'connector-tip-dropped', where,
          'bent-connector arrowheads are not rendered on bento path shapes')
      }
    } else {
      shape.shape = 'rect'
      ctx.report.add('approximated', 'shape-approximated', where,
        `preset "${prst}" approximated as a rectangle`)
    }
  }

  if (fill.gradient && !openPath) {
    shape.fillGradient = { ...fill.gradient, angle: mirrorAngle(fill.gradient.angle, flipH, flipV) }
  }
  if (!openPath) shape.fill = fill.fill
  if (stroke.color && stroke.widthPx > 0) {
    shape.stroke = stroke.color.css
    shape.strokeWidth = stroke.widthPx
    if (stroke.style !== 'solid') shape.strokeStyle = stroke.style
  }
  if (shadow) shape.shadow = shadow

  if ((flipH || flipV) && !flipConsumed) {
    ctx.report.add('approximated', 'flip-dropped', where,
      'flipH/flipV have no bento field and this geometry cannot absorb them — rendered unflipped')
  }

  if (openPath) attachConnectorEnds(sp, shape, ctx, deps, where)

  const fillVisible = shape.fill !== 'transparent' || !!shape.fillGradient
  const strokeVisible = shape.strokeWidth > 0 && shape.stroke !== 'transparent'
  const visible = fillVisible || strokeVisible || !!shadow || openPath || fill.failed || stroke.failed
  if (!visible) return undefined

  const out: ShapeResult = { shape }
  if (deps.groupId) shape.groupId = deps.groupId
  if (hasTextContent(sp)) {
    // the box-with-text split: shape now, text (the text module's element)
    // right after it, welded by groupId so they move as the one object the
    // author had
    const gid = deps.groupId ?? `s${deps.slideIndex}-${spId}-g`
    shape.groupId = gid
    out.textGroupId = gid
  }
  return out
}

/** a:stCxn/a:endCxn → from/to on the converter's deterministic ids. A ref to
 *  a shape that is not on the slide is dropped (its end stays free). */
function attachConnectorEnds(sp: XElem, shape: OutShape, ctx: InheritCtx, deps: ShapeDeps, where: string): void {
  const nv = kids(sp).find((c) => kid(c, NS.p, 'cNvCxnSpPr'))
  const cNv = nv && kid(nv, NS.p, 'cNvCxnSpPr')
  if (!cNv) return
  const end = (local: string): { el: string; side: string } | undefined => {
    const e = kid(cNv, NS.a, local)
    if (!e) return undefined
    const id = attr(e, 'id')
    if (!id) return undefined
    if (deps.spIds && !deps.spIds.has(id)) {
      ctx.report.add('dropped', 'connector-ref-dangling', where,
        'connector references a shape id not present on the slide — end left free')
      return undefined
    }
    return { el: `s${deps.slideIndex}-${id}`, side: 'auto' }
  }
  const from = end('stCxn')
  const to = end('endCxn')
  if (from) shape.from = from
  if (to) shape.to = to
}

// --- groups ------------------------------------------------------------------

export interface GroupChild {
  /** p:sp | p:pic | p:graphicFrame | p:cxnSp — nested p:grpSp recursed away */
  el: XElem
  /** absolute slide-space frame (EMU) — feed it back as deps.frame */
  frame: GroupFrame
  /** shared per source group — feed it back as deps.groupId */
  groupId: string
}

/** The child→parent coordinate map one grpSpPr xfrm defines. */
interface GroupMap {
  sx: number; sy: number
  ox: number; oy: number
  chx: number; chy: number
  rot: number
  flipH: boolean; flipV: boolean
  cx: number; cy: number
}

function applyMap(m: GroupMap, f: GroupFrame): GroupFrame {
  // child space → group space: axis-aligned scale + translate
  let fx = m.ox + (f.x - m.chx) * m.sx
  let fy = m.oy + (f.y - m.chy) * m.sy
  const fw = f.w * m.sx
  const fh = f.h * m.sy
  let rot = f.rotation
  let flipH = f.flipH
  let flipV = f.flipV
  // group flips mirror the child's centre across the group centre, toggle the
  // child's own flags and negate its rotation
  let ccx = fx + fw / 2
  let ccy = fy + fh / 2
  if (m.flipH) { ccx = 2 * m.cx - ccx; flipH = !flipH; rot = -rot }
  if (m.flipV) { ccy = 2 * m.cy - ccy; flipV = !flipV; rot = -rot }
  // group rotation turns the child's centre about the group centre and adds
  // to the child's own angle (clockwise, y-down — same sense as CSS rotate)
  if (m.rot !== 0) {
    const a = m.rot * DEG
    const dx = ccx - m.cx
    const dy = ccy - m.cy
    ccx = m.cx + dx * Math.cos(a) - dy * Math.sin(a)
    ccy = m.cy + dx * Math.sin(a) + dy * Math.cos(a)
    rot += m.rot
  }
  fx = ccx - fw / 2
  fy = ccy - fh / 2
  return { x: fx, y: fy, w: fw, h: fh, rotation: rot, flipH, flipV }
}

function grpXfrm(grpSp: XElem): XElem | undefined {
  const pr = kid(grpSp, NS.p, 'grpSpPr')
  return pr && kid(pr, NS.a, 'xfrm')
}

const MEMBER_LOCALS = new Set(['sp', 'pic', 'graphicFrame', 'cxnSp', 'grpSp'])

/**
 * Flatten one p:grpSp (recursively — 94 census groups, and groups nest) into
 * leaf children with composed ABSOLUTE frames. The caller converts each leaf
 * with its own module, passing frame+groupId back through deps. Every leaf —
 * including members of nested groups — shares the OUTERMOST group's id: bento
 * groupId is single-level, and the outermost group is the selection unit the
 * author actually had. A rotated child inside a non-uniformly scaled group
 * shears in PowerPoint; this frame model cannot say that, so such a child
 * keeps its summed rotation and axis-scaled box (no census sighting).
 */
export function groupChildren(grpSp: XElem, ctx: InheritCtx, deps: ShapeDeps): GroupChild[] {
  const out: GroupChild[] = []
  const groupId = deps.groupId ?? `s${deps.slideIndex}-g${cNvPrId(grpSp)}`

  const walk = (grp: XElem, parent: GroupMap | undefined, nested: boolean): void => {
    const xf = grpXfrm(grp)
    const off = xf && kid(xf, NS.a, 'off')
    const ext = xf && kid(xf, NS.a, 'ext')
    const chOff = xf && kid(xf, NS.a, 'chOff')
    const chExt = xf && kid(xf, NS.a, 'chExt')
    let gFrame: GroupFrame = {
      x: off ? intAttr(off, 'x') : 0,
      y: off ? intAttr(off, 'y') : 0,
      w: ext ? intAttr(ext, 'cx') : 0,
      h: ext ? intAttr(ext, 'cy') : 0,
      rotation: xf ? intAttr(xf, 'rot') / 60000 : 0,
      flipH: xf ? attr(xf, 'flipH') === '1' || attr(xf, 'flipH') === 'true' : false,
      flipV: xf ? attr(xf, 'flipV') === '1' || attr(xf, 'flipV') === 'true' : false,
    }
    if (parent) gFrame = applyMap(parent, gFrame)
    if (nested) {
      ctx.report.add('approximated', 'nested-group-flattened', whereOf(grp, deps.slideIndex),
        'nested group flattened into its outermost group (bento groups are one level)')
    }
    const chW = chExt ? intAttr(chExt, 'cx') : 0
    const chH = chExt ? intAttr(chExt, 'cy') : 0
    const map: GroupMap = {
      sx: chW > 0 ? gFrame.w / chW : 1,
      sy: chH > 0 ? gFrame.h / chH : 1,
      ox: gFrame.x, oy: gFrame.y,
      chx: chOff ? intAttr(chOff, 'x') : 0,
      chy: chOff ? intAttr(chOff, 'y') : 0,
      rot: gFrame.rotation,
      flipH: gFrame.flipH, flipV: gFrame.flipV,
      cx: gFrame.x + gFrame.w / 2, cy: gFrame.y + gFrame.h / 2,
    }
    for (const child of kids(grp, NS.p)) {
      if (!MEMBER_LOCALS.has(child.local)) continue
      if (child.local === 'grpSp') {
        walk(child, map, true)
        continue
      }
      const f = resolveFrame(child, ctx)
      out.push({
        el: child,
        frame: applyMap(map, {
          x: f.x, y: f.y, w: f.w, h: f.h,
          rotation: f.rotation, flipH: f.flipH, flipV: f.flipV,
        }),
        groupId,
      })
    }
  }
  walk(grpSp, undefined, false)
  return out
}