riddle 딥다이브
— 종이가 잉크를 "마시고" 손글씨로 답한다: e-ink 태블릿을 마법 일기장으로 바꾸는 Rust 앱

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

riddle은 reMarkable Paper Pro라는 전자잉크(e-ink) 태블릿을 위한 "마법 일기장" 앱이다. 스타일러스로 페이지에 글을 쓰고 잠깐(약 2.8초) 손을 멈추면, 앱이 그 잉크를 종이 속으로 흩어 없애고, 화면에 쓰인 손글씨를 이미지 한 장으로 만들어 비전(vision) LLM에게 보낸다. 그러면 모델의 답이 흘림체 손글씨로 한 획씩 종이 위에 나타났다가, 잠시 뒤 다시 스르륵 사라진다.

코드상 라이선스는 관대한 MIT(저작권 2026 Maxime Rivest)이며, 클론 시점 최신 커밋은 2026-07-06, 전체 커밋 11개의 초기 프로젝트다. 언어 구성은 Rust 82% · C 7.7% · C++ 6.1% · Shell 4.2%로, 앱 본체(Rust) 약 2,900줄 + 화면 장악용 C/C++(quill) 약 1,500줄 규모다. TrendShift에는 "New 2026"으로 오늘 Daily 11위에 올라 있다.

2왜 주목받는가

트렌딩 이유와, "그냥 챗봇 쓰기"와의 결정적 차이.

① "또 하나의 챗봇"이 아니라 인터페이스 실험

riddle의 전제는 챗봇을 떠올리게 하는 모든 요소를 지우는 것이다 — 텍스트 상자, 전송 버튼, 메시지 버블, 화면 발광까지. 남는 것은 종이 위의 잉크뿐이다. LLM을 "마법 아날로그 물건"처럼 느끼게 만드는 것이 목표이고, 매체(e-ink+손글씨) 자체가 제품이다. 요즘 쏟아지는 "AI 래퍼" 중에서도 방향이 완전히 다르다.

② 입력도 출력도 '텍스트'가 아니다 — 손글씨 in, 손글씨 out

모델은 내가 타이핑한 글자를 받지 않는다. 내 손글씨를 찍은 PNG 이미지를 비전 모델이 "읽는다". 답 역시 화면에 텍스트로 뿌리는 게 아니라, Dancing Script 폰트를 1픽셀 골격으로 얇게 깎아 획 순서대로 그려 "보이지 않는 손이 쓰는" 것처럼 애니메이션한다. 입출력 양쪽 모두 사람의 필기라는 점이 이 프로젝트의 정체성이다.

③ 지연(latency)을 애니메이션 뒤에 숨긴다

e-ink는 느리고 LLM도 느리다. riddle은 이걸 연출로 가린다. 페이지가 커밋되는 즉시 LLM 요청을 딴 스레드에서 쏘아 놓고, 그동안 "잉크를 마시는" 14단계 용해 + 맥동하는 생각 표시 애니메이션을 돌린다. 응답은 문장 단위로 스트리밍되어, 모델이 답을 다 만들기 전에 이미 첫 문장을 쓰기 시작한다. 체감 지연이 크게 줄어드는 영리한 설계다.

④ 벤더 UI를 우회해 e-ink 파형 엔진을 직접 몬다

가장 빠른 펜-투-글라스 응답을 얻기 위해, riddle의 "takeover(장악)" 모드는 reMarkable 기본 UI(xochitl)를 멈추고 벤더의 독점 e-ink 엔진 libqsgepaper.so를 직접 구동한다. 이를 위해 dlsym(RTLD_NEXT)로 Qt의 QImage 생성자를 가로채 엔진 내부 프레임버퍼를 낚아채는 기법(epfb.cpp)을 쓴다. "리버스 엔지니어링 없이 이 기기에서 얻을 수 있는 가장 낮은 지연의 서드파티 드로잉 경로"라고 저자가 설명할 정도다.

3기술 스택 전체 지도

무엇으로 만들어졌나 — 계층별로. (Cargo.toml·Cargo.lock·build 스크립트에서 실제 확인)

큰 그림 — 두 개의 하위 프로젝트

레포는 두 부분으로 나뉜다. riddle/(Rust)는 앱 본체 — 입력·상태기계·LLM·손글씨 합성·그리기를 담당한다. quill/(C/C++·Qt6)는 "화면 장악" 백엔드 — 벤더 e-ink 엔진을 감싸 libquill.so를 만든다. Rust 앱은 창(windowed) 모드에선 quill 없이도 돌지만, 최저 지연의 takeover 모드에선 quill을 FFI로 부른다.

riddle 앱 — Rust (edition 2021), 의존성 극단적 최소화

quill 백엔드 — C / C++ (Qt 6)

대상 하드웨어 & 배포

4아키텍처 심화 분석

펜 입력 → LLM → 손글씨 출력까지, 하나의 이벤트 루프로.

전체 그림 — 상태기계 하나가 전부를 돌린다

앱 전체는 riddle/src/main.rs의 단일 이벤트 루프이고, enum State로 표현된 유한 상태기계(FSM)가 흐름을 지휘한다. 무거운 작업(LLM)은 별도 스레드에서 돌고, 결과는 std::sync::mpsc 채널로 루프에 되돌아온다.

① 잉크 잡기 — Qt가 아니라 커널에서 직접

펜은 벤더 UI를 거치지 않고 커널 입력 장치를 날것으로 읽는다. 64비트에서 각 input_event는 24바이트(타임스탬프 16 + type 2 + code 2 + value 4)이고, SYN_REPORT 프레임 사이의 값을 모아 한 샘플로 방출한다:

for chunk in buf[..n].chunks_exact(24) {
    let etype = u16::from_le_bytes(chunk[16..18].try_into().unwrap());
    let code  = u16::from_le_bytes(chunk[18..20].try_into().unwrap());
    let value = i32::from_le_bytes(chunk[20..24].try_into().unwrap());
    match (etype, code) {
        (EV_ABS, ABS_PRESSURE)    => { self.pressure = value; }
        (EV_KEY, BTN_TOOL_RUBBER) => { self.tool = if value==1 {Eraser} else {Pen}; }
        (EV_SYN, SYN_REPORT)      => { /* 원좌표 → 화면좌표 스케일 후 방출 */
            x: raw_x * (SCREEN_W - 1) / DIGI_MAX_X, ... }
        _ => {}
    }
}

장치는 ioctl(fd, EVIOCGRAB, 1)로 독점(grab)해, 기본 UI가 같은 펜에 이중 반응하지 않게 막는다. 붓 반지름은 압력에 비례한다: let r = 2 + pressure * 3 / MAX_PRESSURE;

② "잉크를 마시는" 용해 효과 — 결정적 픽셀 해시

잉크가 사라지는 연출은 난수가 아니라 좌표 기반 해시로 만든다. 각 단계마다 "해시값이 현재 단계 이하인" 잉크 픽셀만 지우므로, 14패스에 걸쳐 안정적인 얼룩 패턴으로 증발한다:

fn px_hash(x: i32, y: i32) -> u32 {
    let mut h = (x as u32).wrapping_mul(0x9E3779B1)
              ^ (y as u32).wrapping_mul(0x85EBCA6B);
    h ^= h >> 13; h = h.wrapping_mul(0xC2B2AE35); h ^ (h >> 16)
}
// dissolve_pass: stage/stages 진행도에 따라 픽셀을 흰색으로
if surf.luma(x, y) < 250 && px_hash(x, y) % stages <= stage {
    surf.put_px(x, y, WHITE);   // 이 픽셀 지금 증발
}

③ 페이지를 모델로 — 크롭 후 축소한 흑백 PNG

이미지 픽셀 수가 비전 토큰 비용·지연을 좌우하므로, 잉크 bbox로 자른 뒤 긴 변이 800px 이하가 되도록 박스 다운스케일한다. 인코딩은 파일 크기보다 속도 우선(Compression::Fast, 그레이스케일):

let f = ((x1 - x0).max(y1 - y0)).div_ceil(800).max(2);  // 축소 배율
// f×f 블록의 휘도를 평균 → 8비트 그레이스케일 버퍼
enc.set_color(png::ColorType::Grayscale);
enc.set_compression(png::Compression::Fast);

④ LLM 호출 — SDK 없이 손으로 쓴 스트리밍 요청

기본 백엔드 HttpOracle는 손글씨 PNG를 base64 data-URI로 실어 /chat/completions에 스트리밍(SSE) 요청을 보낸다. 본문은 serde 없이 포맷 문자열로 직접 조립한다:

let body = format!(concat!(
  "{{\"model\":{},\"stream\":true,\"max_tokens\":{},",
  "\"messages\":[{{\"role\":\"system\",\"content\":{}}},",
  "{{\"role\":\"user\",\"content\":[",
  "{{\"type\":\"text\",\"text\":{}}},",
  "{{\"type\":\"image_url\",\"image_url\":{{\"url\":",
  "\"data:image/png;base64,{}\"}}}}]}}]}}"),
  json_quote(&model), max_tokens,
  json_quote(PERSONA), json_quote("Reply to what is written in the diary."), img);

let resp = ureq::post(&format!("{base}/chat/completions"))
    .set("Authorization", &format!("Bearer {key}"))
    .send_string(&body);          // SSE 라인(data: {...})을 한 줄씩 파싱

SSE 델타에서 choices[0].delta.content를 뽑고, sentence_cut()으로 한 문장이 완성될 때마다 채널로 넘겨 quill이 일찍 쓰기 시작하게 한다. 페르소나는 두 백엔드가 공유한다:

const PERSONA: &str = "You are the memory of Tom Marvolo Riddle,
preserved in this enchanted diary for fifty years. ...
Keep replies SHORT: one to three sentences, like ink appearing on a page.
Never mention images, photos, models or AI; you only ever perceive words
written in the diary. ... Always answer in the language the writer used.";

대안 백엔드 PiOracle는 Node 프로세스(pi --mode rpc)를 계속 띄워둔 채 stdin/stdout으로 JSONL 이벤트를 주고받아, 매 턴 모델 지연만 지불한다(구독 인증 재사용).

⑤ 이 레포의 꽃 — 손글씨 합성 파이프라인

script.rs는 답변 텍스트를 그릴 수 있는 펜 경로로 바꾼다. 3단계다:

1) rasterize_line : ab_glyph로 Dancing Script 글리프를 채운 마스크(cov > 0.5)
2) thin           : Zhang-Suen 세선화 → 글자를 1픽셀 두께 골격으로
   //  이웃 흑점 수 b가 2..=6, 0→1 전이 a==1, 두 조건 c1·c2를 만족하면 제거
   if !(2..=6).contains(&b) { continue; }
   if a != 1 { continue; }
   if c1 && c2 { to_clear.push(idx(x, y)); }   // 두 위상 반복 → 골격만 남김
3) trace          : 골격을 순서 있는 폴리라인(획)으로 추적, 왼→오 정렬

그런 다음 main.rs::plan_reply()가 획을 화면 좌표로 매핑하며 줄마다 미세한 jitter()/흔들림을 더해 "사람이 쓴 듯"하게 만들고, State::Replying이 틱마다 약 26점씩 brush_line으로 그린다. 스트리밍으로 나중에 온 문장은 append_reply()가 그리는 도중에 아래로 이어 붙인다.

⑥ 가장 영리한 트릭 — 벤더 버퍼 가로채기(quill)

e-ink 엔진 libqsgepaper.so는 프레임버퍼를 내부 QImage로만 갖고 있어 공개 접근자가 없다. quill/src/epfb.cpp는 dlsym(RTLD_NEXT)로 Qt의 QImage 생성자(맹글된 심볼)를 가로채, 초기화 구간에 엔진이 만드는 QImage들을 픽셀 포맷 인자로 구분해 기록한다:

extern "C" void _ZN6QImageC1EPhiixNS_6FormatE...(QImage *that, ...) {
    ORG(...);                 // 진짜 생성자를 먼저 호출
    org(that, ...);
    if (state != 1) return;
    if (param_5 == 4 || param_5 == 7) pointerTracker[that] = SWTCON_TypeA; // 보조 FB
    else if (param_5 == 0x18)         pointerTracker[that] = SWTCON_TypeB; // 메인 FB
}

quill_c.cpp가 이 보조 QImage의 raw bits()를 quill_buffer()로 노출하고, riddle이 여기에 RGB32를 직접 써넣은 뒤 EPFramebuffer::swapBuffers(rect, Mono, mode, flags)로 화면에 밀어낸다. 파형 모드: 0=최고속(잉크), 3=중간(텍스트/애니), 4=전체 플래시 클리어.

5디렉토리 구조 해부

약 3,000줄이 어디에 어떻게 놓였나. (괄호 안 숫자는 대략 줄 수)

구조가 곧 설명서다. 한 파일 = 한 관심사로 깔끔히 쪼개져 있어(입력=pen/touch/power, 두뇌=main/oracle, 표현=script/surface/ink, 출력=display/qtfb), 3,000줄임에도 어디를 봐야 할지 즉시 안다. ★ 표시한 script.rs(손글씨 합성)와 epfb.cpp(버퍼 가로채기)가 기술적으로 가장 배울 것이 많은 두 파일이다.

6학습 포인트 (기술별)

이 작은 코드베이스에서 훔쳐 배울 수 있는 것들.

① 리눅스 raw 입력 다루기

evdev의 input_event 구조체를 손으로 파싱하고, EVIOCGRAB로 장치를 독점하며, /sys/class/input/*/device/name으로 펜·지우개·터치·전원 장치를 구분한다(pen.rs·touch.rs·power.rs). GUI 프레임워크를 건너뛰고 커널과 직접 대화하는 법의 표본.

② 고전 이미지처리 알고리즘 — 세선화·획 추적

script.rs의 Zhang-Suen 세선화(두 위상 이웃 연결성 판정을 고정점까지 반복)와 골격 → 순서 있는 획 추적은, 그대로 떼어내 어떤 캔버스에도 쓸 수 있는 깔끔한 CS 연습이다. 폰트 커버리지 마스크 → 1픽셀 골격 → 애니메이션 가능한 획으로 이어지는 흐름을 통째로 본다.

③ SDK 없이 스트리밍 LLM 붙이기

OpenAI /chat/completions 비전 요청을 손으로 만들고, SSE 델타를 파싱하고, 문장 단위로 잘라 체감 지연을 줄이며, 두 번째 백엔드는 상주 서브프로세스와 stdio JSONL로 통신한다(oracle.rs). base64/JSON까지 직접 구현해 의존성을 극도로 얇게 유지하는 취향도 배운다.

④ Rust 상태기계 + 채널로 실시간 루프 짜기

enum State 전이, 크로스 스레드 스트리밍을 위한 mpsc, 그리고 "sender를 떨궈 완료를 알리는" 관용을 main.rs에서 실물로 본다. 비동기 런타임 없이 OS 스레드만으로 반응형 UI 루프를 구성하는 미니멀리즘.

⑤ e-ink / 임베디드 디스플레이 내부

파형 모드, 전체 vs 부분 갱신, 더티 렉트 병합, 그리고 하이라이트인 심볼 인터포지션(dlsym(RTLD_NEXT)) 심으로 벤더 라이브러리의 내부 버퍼를 가로채기(epfb.cpp). 고급이지만 주석이 잘 달려 있어 ELF 링킹·심볼 해석을 공부하기에 좋다.

⑥ 안전한 "기기 장악/복원" UX

기본 UI(xochitl)를 멈추고 화면을 뺏는 앱은 잘못되면 태블릿을 먹통으로 만든다. riddle은 transient systemd 유닛으로 분리 실행(런처가 죽어도 살아남게)하고, trap restore EXIT INT TERM으로 무슨 일이 있어도 xochitl을 되살리며, 절전은 커널 성공 카운터로 확인한다. "사용자 기기를 망가뜨리지 않기"라는 안전망 설계를 배운다.

7하드웨어/시스템 요구사항

돌리려면 / 빌드하려면 무엇이 필요한가.

8직접 해볼 수 있는 실습 과제

읽기만 하면 안 남는다 — 대부분 태블릿 없이 데스크톱에서 가능하다.

9관련 기술 심화 학습 로드맵

이 레포를 온전히 읽으려면 — 5주 코스.

10핵심 키워드 사전

문서에 나온 용어를 한 번에.

11참고 링크

더 깊이 파고들 곳.