@things-factory/figure-ui 10.1.271 → 10.1.272

package/tutorial/humanoid/README.md

@@ -0,0 +1,22 @@
+# Humanoid walk/run tutorial — recorder
+
+The lesson itself lives in operato-figure: `helps/figure/tutorial-humanoid(.ko).html`, with its videos in
+`helps/figure/media/humanoid/`. This folder re-records those videos whenever the modeller's screens change.
+
+- `chapters.mjs` — the eight chapters, one per section of the lesson, in the order a person works. Values here and in
+  the lesson's tables must stay the same.
+- `lib.mjs` — the "hands": finds a button or field by the words on the screen, moves a drawn pointer there and clicks
+  or types with the real mouse and keyboard. Nothing reaches into the editor's state.
+- `record.mjs` — opens the modeller and plays the chapters, one WebM per chapter plus its last screen as PNG.
+- `encode.mjs` — WebM → MP4 (H.264) and PNG → poster JPG for the lesson.
+
+```bash
+# 1. a modeller page that opens an empty figure in Korean (the recordings show the Korean interface)
+# 2. a dry run without video: every chapter must pass
+node tutorial/humanoid/record.mjs --url http://localhost:5179/?fresh --out ./recordings --no-video
+# 3. record at lesson pace, then encode into the lesson's media folder
+node tutorial/humanoid/record.mjs --url http://localhost:5179/?fresh --out ./recordings --pace 1.2
+node tutorial/humanoid/encode.mjs ./recordings ../../../operato-application/packages/operato-figure/helps/figure/media/humanoid
+```
+
+A chapter that fails leaves `<id>-failed.png` showing where the hands stopped. ffmpeg must be on the PATH.

package/tutorial/humanoid/chapters.mjs

@@ -0,0 +1,247 @@
+/*
+ * 휴머노이드 걷기·뛰기 튜토리얼의 장(章)들 -- 교재(operato-figure helps의 tutorial-humanoid)의 절과 하나씩 맞물린다.
+ * 한 장은 사람이 하는 그대로의 순서다: 부품을 고르고, 이름과 크기를 넣고, 붙이고, 관절을 넣고, 자세를 기록한다.
+ * 장은 앞 장이 끝난 모습에서 시작하므로 처음부터 차례로 실행한다.
+ */
+
+/* Where a part's fastening dialog is: the attach link of a part not yet fastened, or the change link of one that is. */
+const openAttach = h => h.click('「다른 부품에 붙이기」 or 「바꾸기」', t => t.byWords(['button', 'a'], '다른 부품에 붙이기')[0] || t.byWords(['button', 'a'], '바꾸기')[0])
+const inDialog = (h, words) => h.click(`dialog 「${words}」`, (t, w) => t.byWords(['button', 'span', 'label', 'div', 'text'], w).filter(e => t.inDialog(e) && t.words(e) === w).pop(), words)
+const apply = h => h.click('the dialog\'s 「붙이기」/「적용」', t => t.query('md-filled-button').filter(b => ['붙이기', '적용'].includes(t.words(b))).pop())
+
+async function addPart(h, shape, name, size) {
+  await h.buttonTitled(shape)
+  await h.tab('속성')
+  await h.field('이름', name)
+  await h.tab('크기')
+  if (shape === '구') {
+    await h.field('X·Z · 지름', size[0])
+    await h.field('Y · 지름', size[1])
+  } else {
+    await h.field('X', size[0])
+    await h.field('Y', size[1])
+    await h.field('Z', size[2])
+  }
+  await h.tab('속성')
+}
+
+async function attach(h, target, face) {
+  await openAttach(h)
+  await inDialog(h, target)
+  if (face) await inDialog(h, face)
+}
+
+async function joint(h, name, min, max, pivot) {
+  await h.tab('움직임')
+  await h.field('조작 이름', name)
+  await h.typeInto('range min', t => t.fieldAfter('범위 (deg)', 0) || t.fieldAfter('범위 (도)', 0), min)
+  await h.typeInto('range max', t => t.fieldAfter('범위 (deg)', 1) || t.fieldAfter('범위 (도)', 1), max)
+  /* 회전 중심을 이름으로: 위 끝 · 가운데 · 아래 끝 -- 숫자는 버튼이 채운다. */
+  if (pivot) await h.click(`pivot ${pivot}`, (t, p) => t.query(`md-filter-chip[data-value="${p}"]`)[0], pivot)
+  await h.button('움직임 추가')
+}
+
+/*
+ * A pose, on the pose bar right under the controls: the clip chosen there, its moment typed, the eight controls typed,
+ * then 「현재 자세 기록」 -- no scrolling down to the clip.
+ */
+async function pose(h, clip, seconds, values) {
+  const bar = 'div[pose-bar]'
+  const chosen = await h.page.evaluate((b, c) => {
+    const t = window.__tut
+    const choice = t.all().find(e => e.matches && e.matches(`${b} span[clip-choices] button`) && t.words(e) === c)
+    return !choice || choice.getAttribute('aria-pressed') === 'true'
+  }, bar, clip)
+  if (!chosen) await h.click(`pose bar ${clip}`, (t, b, c) => t.all().find(e => e.matches && e.matches(`${b} span[clip-choices] button`) && t.words(e) === c && t.visible(e)), bar, clip)
+  await h.typeInto(`${clip} time`, (t, b) => t.bring(`${b} input[type=number]`), seconds, bar)
+  for (const [control, value] of Object.entries(values))
+    await h.typeInto(`control ${control}`, (t, c) => t.bring(`input[type=number][aria-label="${c}"]`), value, control)
+  await h.click(`${clip} 「현재 자세 기록」`, (t, b) => t.bring(`${b} button[remember-pose]`), bar)
+}
+
+export const chapters = [
+  {
+    id: '01-pelvis',
+    title: '1. 시작 — 골반',
+    note: '바닥에 서는 피규어를 만들고, 몸의 중심인 골반을 880 mm 띄웁니다',
+    async run(h) {
+      await h.say('어디에 두는 설비인지 고릅니다', '사람은 바닥에 섭니다')
+      await h.click('start 바닥', t => t.byWords(['button'], '바닥')[0])
+      await h.say('첫 부품으로 상자를 놓습니다')
+      await h.click('start box', t => t.query('button[start-shape="box"]')[0])
+      await h.say('이름을 pelvis로 바꿉니다', '이름은 나중에 관절·데이터 연결에 그대로 쓰입니다')
+      await h.field('이름', 'pelvis')
+      await h.say('크기 탭에서 300 × 180 × 200 mm', 'Y가 위쪽입니다')
+      await h.tab('크기')
+      await h.field('X', 300)
+      await h.field('Y', 180)
+      await h.field('Z', 200)
+      await h.tab('속성')
+      await h.say('「바꾸기」 → 세부 → 간격 880 mm', '다리가 들어갈 자리만큼 바닥에서 띄웁니다')
+      await h.button('바꾸기')
+      await h.click('세부', t => t.byWords(['summary'], '세부')[0] || t.byWords(['summary'], '세부 · ').pop())
+      await h.typeInDialog('gap', t => t.query('input[gap]')[0], 880)
+      await apply(h)
+      await h.say('')
+    }
+  },
+  {
+    id: '02-body',
+    title: '2. 몸통과 머리',
+    note: '「다른 부품에 붙이기」로 부품을 쌓습니다',
+    async run(h) {
+      await h.say('상자를 하나 더 놓고 torso라고 이름 붙입니다', '340 × 500 × 200 mm')
+      await addPart(h, '상자', 'torso', [340, 500, 200])
+      await h.say('pelvis에 붙입니다', '비어 있는 윗면 가운데가 기본입니다')
+      await attach(h, 'pelvis')
+      await apply(h)
+      await h.say('구를 놓고 head — 지름 200 × 240', '구는 가로(X·Z) 지름과 세로(Y) 지름 두 가지로 정합니다')
+      await addPart(h, '구', 'head', [200, 240])
+      await attach(h, 'torso')
+      await apply(h)
+      await h.say('')
+    }
+  },
+  {
+    id: '03-left-leg',
+    title: '3. 왼쪽 다리와 관절',
+    note: '허벅지 → 정강이 → 발, 고관절과 무릎',
+    async run(h) {
+      await h.say('l-thigh: 130 × 420 × 140', '왼쪽(−X) 부품은 l- 로 시작합니다 — 대칭 복사가 r- 로 바꿔 줍니다')
+      await addPart(h, '상자', 'l-thigh', [130, 420, 140])
+      await h.say('pelvis에 붙이면 비어 있는 아랫면이 기본입니다')
+      await attach(h, 'pelvis')
+      await h.say('세부 → 좌우 위치 「왼쪽 끝 정렬」', '골반의 왼쪽 가장자리에 맞춥니다')
+      await h.click('세부', t => t.byWords(['summary'], '세부')[0] || t.query('details[fasten-detail] summary')[0])
+      await h.click('왼쪽 끝 정렬', t => t.byWords(['button'], '왼쪽 끝 정렬')[0])
+      await apply(h)
+      await h.say('움직임 탭: 회전 · 축 X, 이름 l-hip, −60 ~ 60°', '다른 부품에 붙은 부품은 「회전」이 기본입니다')
+      await joint(h, 'l-hip', -60, 60)
+      await h.say('l-shin: 110 × 420 × 120 → l-thigh 아랫면')
+      await addPart(h, '상자', 'l-shin', [110, 420, 120])
+      await attach(h, 'l-thigh')
+      await apply(h)
+      await h.say('무릎 l-knee: 0 ~ 130°', '+ 가 뒤로 굽는 방향입니다 (반투명 미리보기로 확인)')
+      await joint(h, 'l-knee', 0, 130)
+      await h.say('l-foot: 110 × 70 × 240 → l-shin 아랫면')
+      await addPart(h, '상자', 'l-foot', [110, 70, 240])
+      await attach(h, 'l-shin')
+      await apply(h)
+      await h.say('')
+    }
+  },
+  {
+    id: '04-left-arm',
+    title: '4. 왼팔과 관절',
+    note: '옆면에 붙이고 위 끝에 맞추기, 회전 중심 옮기기',
+    async run(h) {
+      await h.say('l-upperarm: 90 × 300 × 90')
+      await addPart(h, '상자', 'l-upperarm', [90, 300, 90])
+      await h.say('torso에 붙이면 비어 있는 「왼쪽 면」이 기본입니다')
+      await attach(h, 'torso')
+      await h.say('세부 → 위아래 위치 「위 끝 정렬」', '어깨 높이에 맞춥니다')
+      await h.click('세부', t => t.byWords(['summary'], '세부')[0] || t.query('details[fasten-detail] summary')[0])
+      await h.click('위 끝 정렬', t => t.byWords(['button'], '위 끝 정렬')[0])
+      await apply(h)
+      await h.say('어깨 l-shoulder: −60 ~ 60°, 회전 중심 「위 끝」', '위 끝 정렬로 붙였으니 이미 위 끝이 골라져 있습니다 — 숫자는 버튼이 채웁니다')
+      await joint(h, 'l-shoulder', -60, 60, 'top')
+      await h.say('l-forearm: 80 × 280 × 80 → l-upperarm', '세로로 긴 팔에 붙이면 아랫면이 기본입니다')
+      await addPart(h, '상자', 'l-forearm', [80, 280, 80])
+      await attach(h, 'l-upperarm')
+      await apply(h)
+      await h.say('팔꿈치 l-elbow: −130 ~ 0°', '− 가 앞으로 굽는 방향입니다')
+      await joint(h, 'l-elbow', -130, 0)
+      await h.say('')
+    }
+  },
+  {
+    id: '05-mirror',
+    title: '5. 대칭 복사로 오른쪽',
+    note: '아래 붙은 부품과 관절까지 한 번에',
+    async run(h) {
+      for (const part of ['l-thigh', 'l-upperarm']) {
+        await h.say(`${part} 선택 → 속성 → 더 보기 → 「X 반대편에」`, '이름 앞머리 l- → r- 가 자동으로 채워집니다')
+        await h.click(`list ${part}`, (t, p) => t.all().filter(e => t.visible(e) && e.getBoundingClientRect().left < 220 && [...e.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('').trim() === p)[0], part)
+        await h.tab('속성')
+        await h.click('더 보기', t => t.byWords(['summary', 'button', 'span'], '더 보기')[0])
+        await h.click('X 반대편에', t => t.byWords(['button'], 'X 반대편에')[0])
+        await h.say('「움직임 방향 유지」를 켜면 좌우 관절의 + 방향이 같아집니다', '걷기 자세를 좌우 같은 숫자 규칙으로 넣을 수 있습니다')
+        await h.click('움직임 방향 유지', t => t.byWords(['label'], '움직임 방향 유지')[0])
+        await h.click('X 반대편에 (confirm)', t => t.byWords(['button'], 'X 반대편에').pop())
+      }
+      await h.page.keyboard.press('Escape')
+      await h.say('정면 뷰로 확인합니다')
+      await h.click('Front view', t => t.all().find(e => e.getAttribute && e.getAttribute('title') === 'Front' && t.visible(e)))
+      await h.wait(1500)
+      await h.click('Perspective view', t => t.all().find(e => e.getAttribute && e.getAttribute('title') === 'Perspective' && t.visible(e)))
+      await h.say('')
+    }
+  },
+  {
+    id: '06-walk',
+    title: '6. 걷기 — 자세 4개 기록',
+    note: '시간을 옮기고, 조작값을 넣고, 「현재 자세 기록」',
+    async run(h) {
+      await h.page.keyboard.press('Escape')
+      await h.tab('움직임')
+      await h.say('클립 이름 walk, 길이 1.1초 → 「재생 추가」', '첫 트랙 하나만 만들면 나머지는 자세 기록이 만들어 줍니다')
+      await h.field('clip 이름', 'walk')
+      await h.field('길이 (초)', 1.1)
+      await h.button('재생 추가')
+      const walk = [
+        [0, { 'l-hip': -25, 'r-hip': 15, 'l-knee': 5, 'r-knee': 20, 'l-shoulder': 20, 'r-shoulder': -20, 'l-elbow': -15, 'r-elbow': -30 }, '0초 — 왼발 내딛기'],
+        [0.275, { 'l-hip': -5, 'r-hip': -10, 'l-knee': 10, 'r-knee': 55, 'l-shoulder': 0, 'r-shoulder': 0, 'l-elbow': -20, 'r-elbow': -20 }, '0.275초 — 오른발 지나가기'],
+        [0.55, { 'l-hip': 15, 'r-hip': -25, 'l-knee': 20, 'r-knee': 5, 'l-shoulder': -20, 'r-shoulder': 20, 'l-elbow': -30, 'r-elbow': -15 }, '0.55초 — 오른발 내딛기'],
+        [0.825, { 'l-hip': -10, 'r-hip': -5, 'l-knee': 55, 'r-knee': 10, 'l-shoulder': 0, 'r-shoulder': 0, 'l-elbow': -20, 'r-elbow': -20 }, '0.825초 — 왼발 지나가기']
+      ]
+      for (const [at, values, words] of walk) {
+        await h.say(words, '고관절 − 는 앞으로, 무릎 + 는 뒤로 굽힘. 1.1초(끝)는 0초와 같게 자동으로 맞춰집니다')
+        await pose(h, 'walk', at, values)
+      }
+      await h.say('')
+    }
+  },
+  {
+    id: '07-run',
+    title: '7. 뛰기 — 클립 복사 후 자세 바꾸기',
+    note: '복사하면 걷기·뛰기가 한 동작 그룹이 됩니다',
+    async run(h) {
+      await h.say('walk의 「클립 복사」', '복사본과 함께 동작 그룹이 생깁니다 — 한 번에 하나만 재생')
+      await h.click('copy walk', t => { const top = t.clipTop('walk'); return t.query('button[copy-clip]').find(b => b.getBoundingClientRect().top > top) })
+      await h.say('이름 run, 길이 0.7초', '키 시각은 길이에 맞춰 함께 줄어듭니다')
+      await h.typeInto('walk-copy name', t => { t.clipTop('walk-copy'); return t.all().find(e => e.tagName === 'INPUT' && e.value === 'walk-copy') }, 'run')
+      await h.typeInto('run length', t => { const top = t.clipTop('run'); return t.fieldAfter('길이 (초)', 0, { after: top - 5 }) }, 0.7)
+      const run = [
+        [0, { 'l-hip': -40, 'r-hip': 25, 'l-knee': 20, 'r-knee': 75, 'l-shoulder': 40, 'r-shoulder': -45, 'l-elbow': -90, 'r-elbow': -95 }, '0초 — 왼발 착지, 팔은 90° 굽혀 크게'],
+        [0.175, { 'l-hip': -5, 'r-hip': -45, 'l-knee': 35, 'r-knee': 110, 'l-shoulder': 0, 'r-shoulder': 0, 'l-elbow': -90, 'r-elbow': -90 }, '0.175초 — 오른 무릎 높이 들기'],
+        [0.35, { 'l-hip': 25, 'r-hip': -40, 'l-knee': 75, 'r-knee': 20, 'l-shoulder': -45, 'r-shoulder': 40, 'l-elbow': -95, 'r-elbow': -90 }, '0.35초 — 오른발 착지'],
+        [0.525, { 'l-hip': -45, 'r-hip': -5, 'l-knee': 110, 'r-knee': 35, 'l-shoulder': 0, 'r-shoulder': 0, 'l-elbow': -90, 'r-elbow': -90 }, '0.525초 — 왼 무릎 높이 들기']
+      ]
+      for (const [at, values, words] of run) {
+        await h.say(words)
+        await pose(h, 'run', at, values)
+      }
+      await h.say('')
+    }
+  },
+  {
+    id: '08-preview',
+    title: '8. 미리보기에서 재생',
+    note: '동작 그룹에서 클립을 고르고 배속을 올립니다',
+    async run(h) {
+      await h.button('미리보기')
+      await h.wait(1500)
+      await h.say('「동작」 그룹: 클립 walk, 배속 1', '복사로 만든 그룹은 「동작」이라는 이름으로 생깁니다')
+      await h.click('walk clip', t => t.query('span[clip-choices] button').find(b => t.words(b) === 'walk'))
+      const speed = await h.locate('speed', t => t.query('input[type=range][max="3"]').pop())
+      await h.drag({ x: speed.x - speed.w / 2 + 2, y: speed.y }, { x: speed.x - speed.w / 2 + speed.w / 3, y: speed.y })
+      await h.wait(4000)
+      await h.say('클립 「run」 — 같은 배속으로 바뀌어 뜁니다', '조작값 줄은 「재생 중」으로 잠깁니다')
+      await h.click('run clip', t => t.query('span[clip-choices] button').find(b => t.words(b) === 'run'))
+      await h.wait(4000)
+      await h.say('')
+    }
+  }
+]
+
+export { addPart, attach, apply, joint, pose, openAttach, inDialog }

package/tutorial/humanoid/encode.mjs

@@ -0,0 +1,26 @@
+/*
+ * 녹화한 장(章) 영상을 교재에 싣는 형태로 바꾼다: WebM → MP4(H.264, 웹 재생용 faststart), 장의 마지막 화면 → 포스터 JPG.
+ *
+ *   node tutorial/humanoid/encode.mjs <녹화 폴더> <교재 media 폴더>
+ *
+ * 교재 media 폴더는 operato-figure 의 helps/figure/media/humanoid 이다. ffmpeg 이 PATH 에 있어야 한다.
+ */
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, readdirSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const [from, to] = process.argv.slice(2).map(p => p && resolve(p))
+if (!from || !to) {
+  console.error('usage: node tutorial/humanoid/encode.mjs <recordings> <media folder>')
+  process.exit(1)
+}
+mkdirSync(to, { recursive: true })
+
+for (const name of readdirSync(from).filter(n => n.endsWith('.webm')).sort()) {
+  const id = name.slice(0, -5)
+  const mp4 = join(to, `${id}.mp4`)
+  /* 1280 wide keeps the panels' words legible; crf 28 and no sound keep a chapter to a few MB. */
+  execFileSync('ffmpeg', ['-loglevel', 'error', '-y', '-i', join(from, name), '-vf', 'scale=1280:-2,fps=30', '-c:v', 'libx264', '-preset', 'slow', '-crf', '28', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', '-an', mp4])
+  execFileSync('ffmpeg', ['-loglevel', 'error', '-y', '-i', join(from, `${id}.png`), '-vf', 'scale=1280:-2', '-q:v', '4', join(to, `${id}.jpg`)])
+  console.log(`${id}.mp4 ${(statSync(mp4).size / 1e6).toFixed(1)} MB`)
+}

package/tutorial/humanoid/lib.mjs

@@ -0,0 +1,197 @@
+/*
+ * The tutorial recorder's hands: it finds what a person would look for on the screen -- a button by its words or its
+ * title, a field by the words beside it -- and moves a drawn pointer there before it clicks or types, so a recording
+ * shows where the hand went. Nothing here reaches into the editor's state: every step is a click, a key or a drag.
+ */
+
+/** Everything on the page, shadow roots included, as the page's own function (run in the page). */
+export const PAGE_HELPERS = `
+window.__tut = {
+  all() {
+    const out = []
+    const walk = root => root.querySelectorAll('*').forEach(e => { out.push(e); if (e.shadowRoot) walk(e.shadowRoot) })
+    walk(document)
+    return out
+  },
+  visible(e) {
+    const b = e.getBoundingClientRect()
+    if (b.width <= 0 || b.height <= 0) return false
+    let n = e
+    while (n) {
+      if (n instanceof Element && getComputedStyle(n).visibility === 'hidden') return false
+      n = n.parentElement || (n.getRootNode && n.getRootNode().host)
+    }
+    return b.bottom > 0 && b.right > 0 && b.top < innerHeight && b.left < innerWidth
+  },
+  words(e) { return (e.textContent || '').replace(/\\s+/g, ' ').trim() },
+  /* Elements matching a CSS selector, visible, in page order. */
+  query(selector) { return this.all().filter(e => e.matches && e.matches(selector) && this.visible(e)) },
+  /* The visible element of the given tags whose words are exactly, or end with, the given words (icons come first). */
+  byWords(tags, words, { within } = {}) {
+    const box = within ? within.getBoundingClientRect() : null
+    return this.all().filter(e => tags.includes(e.tagName.toLowerCase()) && this.visible(e)).filter(e => {
+      const w = this.words(e)
+      if (!(w === words || w.endsWith(words))) return false
+      if (!box) return true
+      const b = e.getBoundingClientRect()
+      return b.top >= box.top - 1 && b.bottom <= box.bottom + 1
+    })
+  },
+  /* The field that stands after the given words: the first input or select after a label-like element with them. */
+  fieldAfter(words, nth = 0, { after } = {}) {
+    const all = this.all()
+    const labels = all.filter(e => ['span', 'label', 'strong', 'div'].includes(e.tagName.toLowerCase()) && e.children.length <= 1 && this.words(e) === words && this.visible(e))
+      .filter(e => !after || e.getBoundingClientRect().top > after)
+    for (const label of labels) {
+      const i = all.indexOf(label)
+      const fields = all.slice(i + 1).filter(e => ['input', 'select'].includes(e.tagName.toLowerCase()) && this.visible(e))
+      if (fields[nth]) return fields[nth]
+    }
+    return null
+  },
+  /* The first element matching a selector that has a size, scrolled to the middle of its pane when it stands out of view. */
+  bring(selector) {
+    const e = this.all().find(e => e.matches && e.matches(selector) && e.getBoundingClientRect().width > 0)
+    if (e && !this.visible(e)) e.scrollIntoView({ block: 'center' })
+    return e || null
+  },
+  /* A clip's section, brought into view by its name: its time and 「현재 자세 기록」 stand under it. */
+  clipTop(clip) {
+    const name = this.all().find(e => e.tagName === 'INPUT' && e.type !== 'number' && e.value === clip)
+    if (!name) return -1
+    name.scrollIntoView({ block: 'center' })
+    return name.getBoundingClientRect().top
+  },
+  /* Whether an element stands in the fastening dialog (its drawing, its chips, its buttons). */
+  inDialog(e) {
+    for (let n = e; n; n = n.parentElement || (n.getRootNode && n.getRootNode().host))
+      if (n.tagName === 'FIGURE-FASTEN-DIALOG') return true
+    return false
+  },
+  centre(e) {
+    if (!e) return null
+    e.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+    const b = e.getBoundingClientRect()
+    return { x: b.left + b.width / 2, y: b.top + b.height / 2, w: b.width, h: b.height }
+  }
+}
+`
+
+/** The drawn pointer, the ring of a click and the caption under the screen: what a recording needs to be followed. */
+export const OVERLAY = `
+(() => {
+  if (document.getElementById('tut-overlay')) return
+  const style = document.createElement('style')
+  style.textContent = \`
+    #tut-pointer { position: fixed; z-index: 2147483647; width: 22px; height: 22px; margin: -2px 0 0 -2px; pointer-events: none;
+      background: no-repeat center/contain url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M3 2l7 19 2.6-7.4L20 11z' fill='%23111' stroke='%23fff' stroke-width='1.6' stroke-linejoin='round'/%3E%3C/svg%3E");
+      transition: left .35s ease, top .35s ease; left: 50%; top: 50% }
+    .tut-ring { position: fixed; z-index: 2147483646; width: 34px; height: 34px; margin: -17px 0 0 -17px; border-radius: 50%;
+      border: 3px solid #0d8f86; pointer-events: none; animation: tut-ring .6s ease-out forwards }
+    @keyframes tut-ring { from { transform: scale(.4); opacity: 1 } to { transform: scale(1.4); opacity: 0 } }
+    #tut-caption { position: fixed; z-index: 2147483645; left: 50%; bottom: 18px; transform: translateX(-50%); max-width: 70%;
+      padding: 10px 18px; border-radius: 10px; background: rgba(16, 32, 43, .88); color: #fff; font: 600 17px/1.45 -apple-system, 'Apple SD Gothic Neo', sans-serif;
+      text-align: center; pointer-events: none; box-shadow: 0 6px 20px rgba(0,0,0,.25) }
+    #tut-caption:empty { display: none }
+    #tut-caption small { display: block; font-weight: 500; font-size: 13px; opacity: .8 }
+    #tut-chapter { position: fixed; z-index: 2147483645; left: 50%; top: 40%; transform: translate(-50%, -50%); padding: 22px 34px;
+      border-radius: 14px; background: rgba(16, 32, 43, .92); color: #fff; font: 700 28px/1.4 -apple-system, 'Apple SD Gothic Neo', sans-serif;
+      text-align: center; pointer-events: none }
+    #tut-chapter small { display: block; font-size: 16px; font-weight: 500; opacity: .85; margin-top: 6px }
+    #tut-chapter:empty { display: none }
+  \`
+  document.head.append(style)
+  const pointer = Object.assign(document.createElement('div'), { id: 'tut-pointer' })
+  const caption = Object.assign(document.createElement('div'), { id: 'tut-caption' })
+  const chapter = Object.assign(document.createElement('div'), { id: 'tut-chapter' })
+  const overlay = Object.assign(document.createElement('div'), { id: 'tut-overlay' })
+  document.body.append(overlay, pointer, caption, chapter)
+})()
+`
+
+const sleep = ms => new Promise(done => setTimeout(done, ms))
+
+/**
+ * The hands, bound to a page: each step finds its target the way a person would, moves the drawn pointer to it and acts
+ * with the real mouse and keyboard. `pace` stretches every pause, so the same steps record slower for a lesson.
+ */
+export function handsFor(page, { pace = 1 } = {}) {
+  const wait = ms => sleep(ms * pace)
+  const say = async (text, note = '') => {
+    await page.evaluate((t, n) => {
+      const c = document.getElementById('tut-caption')
+      c.textContent = t
+      if (n) c.append(Object.assign(document.createElement('small'), { textContent: n }))
+    }, text, note)
+  }
+  const title = async (text, note = '') => {
+    await page.evaluate((t, n) => {
+      const c = document.getElementById('tut-chapter')
+      c.textContent = t
+      if (n) c.append(Object.assign(document.createElement('small'), { textContent: n }))
+    }, text, note)
+    await wait(1800)
+    await page.evaluate(() => (document.getElementById('tut-chapter').textContent = ''))
+  }
+  const point = async (x, y) => {
+    await page.evaluate((px, py) => Object.assign(document.getElementById('tut-pointer').style, { left: px + 'px', top: py + 'px' }), x, y)
+    await page.mouse.move(x, y, { steps: 8 })
+    await wait(380)
+  }
+  const ring = (x, y) => page.evaluate((px, py) => {
+    const r = Object.assign(document.createElement('div'), { className: 'tut-ring' })
+    Object.assign(r.style, { left: px + 'px', top: py + 'px' })
+    document.body.append(r)
+    setTimeout(() => r.remove(), 700)
+  }, x, y)
+  /** The centre of what `find` (run in the page, given __tut) returns, or an error naming what was looked for. */
+  /* Found and standing still: a dialog that grows as it is filled moves its buttons, and a click aimed before it settled missed. */
+  const locate = async (what, find, ...args) => {
+    let last = null
+    for (let tries = 0; tries < 30; tries++) {
+      const at = await page.evaluate(new Function('args', `const t = window.__tut; return t.centre((${find})(t, ...args))`), args)
+      if (at && last && Math.abs(at.x - last.x) < 1 && Math.abs(at.y - last.y) < 1) return at
+      last = at
+      await sleep(120)
+    }
+    if (last) return last
+    throw Error(`not found on the screen: ${what}`)
+  }
+  const clickAt = async ({ x, y }, { clicks = 1 } = {}) => {
+    await point(x, y)
+    await ring(x, y)
+    await page.mouse.click(x, y, { clickCount: clicks })
+    await wait(450)
+  }
+  const click = async (what, find, ...args) => clickAt(await locate(what, find, ...args))
+  const typeInto = async (what, find, text, ...args) => typeKeyed(what, find, text, 'Enter', ...args)
+  /* In a dialog Enter applies the dialog: a field there is left by Tab. */
+  const typeInDialog = async (what, find, text, ...args) => typeKeyed(what, find, text, 'Tab', ...args)
+  const typeKeyed = async (what, find, text, key, ...args) => {
+    const at = await locate(what, find, ...args)
+    await clickAt(at, { clicks: 3 })
+    await page.keyboard.down('Meta')
+    await page.keyboard.press('KeyA')
+    await page.keyboard.up('Meta')
+    await page.keyboard.type(String(text), { delay: 60 * pace })
+    await page.keyboard.press(key)
+    await wait(350)
+  }
+  const drag = async (from, to) => {
+    await point(from.x, from.y)
+    await page.mouse.down()
+    await page.mouse.move(to.x, to.y, { steps: 18 })
+    await page.evaluate((px, py) => Object.assign(document.getElementById('tut-pointer').style, { left: px + 'px', top: py + 'px' }), to.x, to.y)
+    await page.mouse.up()
+    await wait(500)
+  }
+
+  /* What a person names on the screen. */
+  const button = words => click(`button 「${words}」`, (t, w) => t.byWords(['button'], w)[0], words)
+  const buttonTitled = title => click(`button titled 「${title}」`, (t, w) => t.query(`button[title="${w}"]`)[0], title)
+  const tab = name => click(`tab 「${name}」`, (t, w) => t.query(`button[tab][aria-label="${w}"]`)[0], name)
+  const field = (label, text, nth = 0) => typeInto(`field after 「${label}」`, (t, l, n) => t.fieldAfter(l, n), text, label, nth)
+  const chip = name => click(`chip 「${name}」`, (t, w) => t.byWords(['button', 'span', 'label'], w).find(e => e.closest('[open], dialog, ox-popup, figure-fasten-dialog') || true), name)
+
+  return { page, wait, say, title, point, click, clickAt, typeInto, typeInDialog, locate, drag, button, buttonTitled, tab, field, chip }
+}

package/tutorial/humanoid/record.mjs

@@ -0,0 +1,65 @@
+/*
+ * 휴머노이드 튜토리얼 녹화기: 모델러를 열고 장(章)마다 사람이 하는 그대로 따라 하며, 장마다 한 편의 영상(WebM)을 남긴다.
+ *
+ *   node tutorial/humanoid/record.mjs --url http://localhost:5179/?fresh --out ./tutorial-videos [--only 01-pelvis] [--no-video] [--pace 1.2]
+ *
+ * --url    모델러 페이지. 빈 피규어로 열리는 곳이어야 한다(로컬 개발 페이지는 ?fresh).
+ * --out    영상과 장마다 마지막 화면(PNG)을 둘 폴더.
+ * --only   한 장만(앞 장들은 영상 없이 먼저 따라 한다).
+ * --pace   쉬는 시간 배율 -- 강의용은 1.2~1.5.
+ *
+ * ffmpeg 이 PATH 에 있어야 영상이 남는다(puppeteer screencast).
+ */
+import { mkdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import puppeteer from 'puppeteer'
+import { handsFor, OVERLAY, PAGE_HELPERS } from './lib.mjs'
+import { chapters } from './chapters.mjs'
+
+const arg = (name, fallback) => {
+  const i = process.argv.indexOf(`--${name}`)
+  return i < 0 ? fallback : (process.argv[i + 1] ?? true)
+}
+const url = arg('url', 'http://localhost:5179/?fresh')
+const out = resolve(arg('out', './tutorial-videos'))
+const only = arg('only', '')
+const video = !process.argv.includes('--no-video')
+const pace = Number(arg('pace', 1))
+const headed = process.argv.includes('--headed')
+mkdirSync(out, { recursive: true })
+
+const browser = await puppeteer.launch({ headless: !headed, args: ['--no-sandbox', '--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--window-size=1600,900'] })
+const page = await browser.newPage()
+await page.setViewport({ width: 1600, height: 900 })
+const errors = []
+page.on('pageerror', e => errors.push(String(e)))
+await page.goto(url, { waitUntil: 'networkidle0' })
+await new Promise(done => setTimeout(done, 2500))
+await page.evaluate(PAGE_HELPERS)
+await page.evaluate(OVERLAY)
+const h = handsFor(page, { pace })
+
+const index = only ? chapters.findIndex(c => c.id === only) : -1
+for (const [i, chapter] of chapters.entries()) {
+  const recording = video && (!only || i === index)
+  if (only && i > index) break
+  const started = Date.now()
+  const recorder = recording ? await page.screencast({ path: join(out, `${chapter.id}.webm`) }) : null
+  if (recording) await h.title(chapter.title, chapter.note)
+  try {
+    await chapter.run(recording ? h : handsFor(page, { pace: 0.2 }))
+  } catch (e) {
+    await page.screenshot({ path: join(out, `${chapter.id}-failed.png`) })
+    await recorder?.stop()
+    console.error(`✗ ${chapter.id}: ${e.message}`)
+    await browser.close()
+    process.exit(1)
+  }
+  await page.evaluate(() => document.querySelector('figure-editor')?.renderRoot?.querySelector('button[data-action="fit"]'))
+  await new Promise(done => setTimeout(done, 600))
+  await page.screenshot({ path: join(out, `${chapter.id}.png`) })
+  await recorder?.stop()
+  console.log(`✓ ${chapter.id} ${((Date.now() - started) / 1000).toFixed(1)}s${recording ? ' (영상)' : ''}`)
+}
+if (errors.length) console.log('page errors:', errors.slice(0, 5).join('\n'))
+await browser.close()