kasaframe 0.1.1 → 0.1.4

package/themes/kawaii-sticker/variants/sage-sky.json

@@ -0,0 +1,107 @@
+{
+  "id": "sage-sky",
+  "world": "kawaii-sticker",
+  "name": "Sage Sky",
+  "desc": "세이지 바탕에 하늘색 강조 · 종이 결",
+  "params": {
+    "scheme": "light",
+    "bgL": 0.9765,
+    "tint": {
+      "h": 150.4162,
+      "c": 0.0155
+    },
+    "inkL": 0.3433,
+    "hue": 238.8173,
+    "chroma": 0.8767,
+    "fonts": "base",
+    "texture": {
+      "kind": "paper",
+      "amount": 0.8
+    },
+    "stroke": 0.97,
+    "radius": 33,
+    "tempo": 1.09,
+    "density": 1
+  },
+  "style": {
+    "scheme": "light",
+    "colors": {
+      "bg": "#F0FAF2",
+      "surface": "#FFFFFF",
+      "raised": "#EFEFED",
+      "line": "#BFE3F5",
+      "ink": "#004148",
+      "inkSoft": "#24626A",
+      "dim": "#3F767C",
+      "accent": "#3AB6FC",
+      "accentSoft": "#C0E7FD",
+      "accentText": "#0079B2",
+      "onAccent": "#004148",
+      "mint": "#EBB98F",
+      "lavender": "#5DCEB5",
+      "sky": "#C1D398",
+      "lemon": "#FFD8F3",
+      "peach": "#C1C4FE",
+      "success": "#3CBF9A",
+      "danger": "#E5537A",
+      "warning": "#F2A93B",
+      "sheet": "#E0EDF9",
+      "tape": "rgba(193, 211, 152, 0.82)",
+      "shadow": "rgba(0, 65, 72, 0.28)"
+    },
+    "radius": {
+      "sm": 19,
+      "md": 33,
+      "lg": 52,
+      "pill": 999
+    },
+    "look": {
+      "texture": {
+        "kind": "paper",
+        "amount": 0.8
+      },
+      "stroke": 0.97,
+      "tempo": 1.09
+    }
+  },
+  "tags": {
+    "mood": [
+      "귀여운",
+      "발랄한",
+      "친근한",
+      "가벼운",
+      "밝은",
+      "차가운",
+      "아날로그"
+    ],
+    "light": "light",
+    "use": [
+      "소개",
+      "이벤트",
+      "캐릭터",
+      "앱",
+      "일상",
+      "광고"
+    ],
+    "dims": "2D"
+  },
+  "check": {
+    "ok": true,
+    "at": "2026-10-11",
+    "colors": {
+      "ink": 10.64,
+      "inkSoft": 6.51,
+      "dim": 4.81,
+      "accentText": 4.5,
+      "accent": 2.13,
+      "onAccent": 5,
+      "success~danger": 0.07,
+      "success~warning": 0.107,
+      "danger~warning": 0.162,
+      "accent~danger": 0.187,
+      "accent~ink": 0.4
+    },
+    "frame": "kf check 통과 — 표준 장면 0–4초",
+    "pattern": "hook-number.roll"
+  }
+}

package/themes/lab-notebook/THEME.md

@@ -0,0 +1,56 @@
+# 실험 노트 `lab-notebook`
+
+**비유: 요청 한 번이 실험 한 번이 되어 노트 한 쪽에 적힌다 — 시료(모델)를 같은 장치(한 주소)에 넣은 시행이 표 한 줄씩 손으로 적히고, 측정값은 출력해 테이프로 붙이고, 틀린 값은 지우지 않고 줄을 그어 빨간 펜으로 고쳐 쓴다.** 화면은 모눈 노트 한 쪽이고, 마디마다 쪽을 넘긴다.
+
+| 기술 개념 | 이 세계에서 |
+|---|---|
+| 요청 | 시행 한 번 — 표의 한 줄(No.) |
+| 모델 | 시료 — 시행 줄의 시료 칸 |
+| 공급자(회사) | 공급처 — 시약 회사 이름 |
+| 게이트웨이 한 주소 | 장치 하나 — 첫 줄에만 /v1, 아래 줄은 같음표(〃): 같은 장치 |
+| 형식 | 시료를 넣는 두 방식 — 두 화살표가 같은 장치로 |
+| 비용 | 시약 값 — 정가에 두 줄을 긋고 빨간 펜으로 밤값을 고쳐 쓴다(`strikeFix`) |
+| 지연 | 측정 시간(ms) — 출력한 점 그래프(`plotPoints`) |
+| 캐시 | 「→ 앞 쪽 참조」 메모 — 다시 재지 않고 지난 결과를 쓴다(`arrowNote`) |
+| 폴백 | 재시험 줄 — 같은 시행을 다른 시료로 다시 |
+| 한도 | 그래프 축의 측정 범위 |
+| 드롭·결과 | 빨간 고무 도장(`resultStamp`)과 빨간 동그라미(`ruleLine` 에 `ellipsePts`) |
+
+## 맞는 내용·용도
+
+- 실측·벤치마크·가격 비교·변경 기록·「해 봤더니」류 — 숫자를 재고 고치고 견주는 내용. 설명·쇼츠·리포트·개발 일지.
+- 용도: 설명(explainer)·쇼츠(shorts)·홍보(promo)·피드(square). 마디마다 쪽 하나, 드롭에 도장.
+- 화면 글은 손글씨(나눔손글씨 펜·개구) — 제목·회사 이름·모델 ID·숫자·짧은 메모. 출력물 안은 Courier Prime.
+
+## 금지
+
+- 지우기·덮어쓰기 — 틀린 값은 남기고 줄을 긋는다(`strikeFix`). 사라지는 글 금지.
+- 반듯한 디지털 도형 — 선은 자 대고 긋거나(`ruleLine`) 손으로(`hand`), 출력물만 반듯하다.
+- 색 남발 — 파란 볼펜(적는 글)·연필(선·메모)·빨간 펜(고친 값·결과)·형광펜 하나·테이프. 그 밖의 색 금지.
+- 바탕 흐름·떠다니는 종이 조각. 노트는 책상에 놓여 있고, 움직임은 펜·자·테이프·도장에서만.
+- 「실험 성공!」 같은 감탄·슬로건.
+
+## 움직임
+
+- 쉬지 않는다: 쓰는 펜(`penTrack`)이 늘 움직인다 — 글을 따라 쓰고(초당 18자 안팎), 선을 긋고, 다음 자리로 옮겨 간다. 손글씨 획만으로는 화면 차가 작아 0.1초 정지에 걸리니 펜을 꼭 둔다. 끝 카드는 로고를 마커로 끝 프레임까지 따라 그린다.
+- 구도는 마디마다 바꾼다: 쪽을 넘긴다(새 쪽이 드러난다) — 공급처 표 → 장치 → 시행 표 → 형식 → 결과 도장 → 하루 값 그래프 → 값 고치기 → 측정 표 → 끝 카드.
+- 박마다 큰 사건 하나: 회사 셋이 적히고, 표 줄이 그어지고, 출력물이 붙고, 형광펜·동그라미가 짚고, 값에 줄이 그어진다.
+
+## 효과
+
+같은 레포 안에서는 `effects.ts` 를 바로, 프로젝트에서는 `fx("lab-notebook")`. layer 는 `build` 에서 만들고 `(t) => …` 에서 부른다. 손 떨림 선·타원·캔버스는 `kit.ts`(`handPath`·`strokeHand`·`ellipsePts` — 빨간 동그라미는 `ruleLine` 에 `ellipsePts` 를). 장면 하나는 보통 `gridPaper`(맨 아래) → 글·선·출력물 → 쪽 넘김 → `penTrack`(맨 위) 순서로 쌓는다.
+
+| 효과 | 꼴 | 하는 일 |
+|---|---|---|
+| `gridPaper` | layer | 모눈 노트 종이 — 5mm 칸·다섯 칸마다 진한 줄·빨간 여백 줄, 서 있다 |
+| `penWrite` | layer | 펜 글씨 — 펜 끝을 따라 왼쪽부터 드러나고 펜촉 점이 앞서 간다, 줄마다 조금 기운다 |
+| `ruleLine` | layer | 자 대고 긋는 선(표 칸·밑줄·상자) — hand 면 손으로 긋듯 흔들린다 |
+| `strikeFix` | layer | 틀린 값에 두 줄을 긋고 빨간 펜으로 옆에 고쳐 쓴다(지우지 않는다) |
+| `penTrack` | layer | 쓰는 펜 — 볼펜 한 자루가 다른 효과가 내보낸 획을 차례로 따라가고, 획 사이엔 들어 올려 옮긴다(쉬지 않는 몫) |
+| `highlighter` | layer | 형광펜 띠가 왼쪽부터 칠해진다(곱하기라 글이 비친다) |
+| `tapeOn` | layer | 흰 출력물이 위에서 내려와 놓이고 마스킹 테이프 두 조각이 붙는다 — 안은 build 로 |
+| `plotPoints` | layer | 출력 그래프 — 축·눈금이 찍혀 있고 점이 하나씩 동그라미로 찍히며 선(계단)이 이어진다 |
+| `arrowNote` | layer | 여백 메모 — 손으로 그은 휜 화살표와 빨간 펜 메모 |
+| `resultStamp` | layer | 드롭 — 빨간 고무 도장이 쾅 찍힌다(이중 테·잉크 덜 묻은 결), 흔들림을 돌려준다 |
+
+견본: `sample/` — 공통 주제 「OpenGateway 소개 15초」, kawaii-friends 4.0–19.0초(드롭 7.34초). 날짜와 공급처 아홉을 적고 → 모델 수를 적고 출력 막대 그래프를 붙이고 OpenAI 41 에 형광펜·동그라미 → 쪽을 넘겨 장치(apis.opengateway.ai/v1)를 상자로 → 시행 표, 시료(모델 ID) 다섯 줄의 장치 칸은 /v1 과 같음표 → 두 형식이 같은 /v1 로 → 드롭에 빨간 102 도장 → 하루 값 계단 그래프와 00:00~10:00 형광펜, -90% 화살표 → deepseek 정가에 줄 긋고 밤값 고쳐 쓰기 → 첫 토큰 표와 점 그래프, 18번 합 동그라미 → OG 로고를 마커로 따라 그리고 opengateway.ai 두 줄 밑줄.

package/themes/lab-notebook/effects.ts

@@ -0,0 +1,423 @@
+import { clamp, ease, rand, type SceneCtx } from "@kasaframe/core";
+import { dropBurst, type DropBurstState } from "@kasaframe/motion";
+import { areaCanvas, boundsOf, color, handPath, type Pt, strokeHand } from "./kit.ts";
+
+// 실험 노트는 손이 쓰는 속도로 찬다 — 글은 펜 끝을 따라 왼쪽부터 드러나고, 선은 자를 대고 긋거나 손으로 돌린다.
+// 지우지 않는다: 틀린 값은 줄을 긋고 빨간 펜으로 옆에 고쳐 쓴다. 출력한 그래프는 테이프로 붙인다
+
+/** 모눈 종이 — 5mm 칸(파랑), 다섯 칸마다 진한 줄, 왼쪽 빨간 여백 줄. 서 있다 */
+export function gridPaper(el: HTMLElement, o: { ctx: SceneCtx; cell?: number; margin?: number | null }): (t: number) => void {
+  const { ctx } = o;
+  const W = ctx.meta.width;
+  const H = ctx.meta.height;
+  const { g } = areaCanvas(el, 0, 0, W, H);
+  const cell = o.cell ?? Math.round(Math.min(W, H) / 30);
+  g.fillStyle = color(ctx, "bg");
+  g.fillRect(0, 0, W, H);
+  for (let i = 0; i * cell <= Math.max(W, H); i++) {
+    g.fillStyle = color(ctx, i % 5 === 0 ? "gridBold" : "grid");
+    const w = i % 5 === 0 ? 2 : 1;
+    if (i * cell <= W) g.fillRect(i * cell, 0, w, H);
+    if (i * cell <= H) g.fillRect(0, i * cell, W, w);
+  }
+  const m = o.margin === null ? null : (o.margin ?? cell * 4);
+  if (m !== null) {
+    g.fillStyle = color(ctx, "margin");
+    g.fillRect(m, 0, 3, H);
+  }
+  return () => {};
+}
+
+export interface PenOpts {
+  ctx: SceneCtx;
+  text: string;
+  x: number;
+  y: number;
+  size?: number;
+  at?: number;
+  /** 다 쓰는 데 걸리는 초 — 없으면 글자 수 ÷ 초당 18자 */
+  dur?: number;
+  tone?: string;
+  font?: "sans" | "display" | "mono";
+  /** 손으로 쓴 줄은 조금 기운다(도) — 없으면 시드로 ±1° */
+  tilt?: number;
+  until?: number;
+}
+
+/** 펜이 지나는 획 하나 — 이 시각부터 dur 초에 path 를 따라간다(penTrack 이 펜을 그 자리에 둔다) */
+export interface Stroke {
+  at: number;
+  dur: number;
+  path: Pt[];
+  /** 글씨면 펜촉이 위아래로 오르내린다 */
+  writing?: boolean;
+}
+
+/** 획을 내보내는 그리기 — penTrack 에 넘기면 펜이 그 획들을 차례로 따라간다 */
+export type Traced = ((t: number) => void) & { strokes: Stroke[] };
+
+const traced = (paint: (t: number) => void, strokes: Stroke[]): Traced => Object.assign(paint, { strokes });
+
+/** 펜 글씨 — 펜 끝을 따라 왼쪽부터 드러난다, 줄마다 조금 기운다. 쓰는 동안의 펜은 penTrack 이 그린다 */
+export function penWrite(el: HTMLElement, o: PenOpts): Traced {
+  const { ctx } = o;
+  const size = o.size ?? 48;
+  const d = el.ownerDocument.createElement("div");
+  d.textContent = o.text;
+  const tilt = o.tilt ?? (rand(`pen:${o.text}`, 1) - 0.5) * 2;
+  const font = `400 ${size}px ${ctx.style.fonts[o.font ?? "display"]}`;
+  d.style.cssText = `position:absolute;left:${o.x}px;top:${o.y}px;font:${font};line-height:1.15;white-space:pre;color:${color(ctx, o.tone ?? "ink")};transform:rotate(${tilt.toFixed(2)}deg);transform-origin:0 50%;`;
+  el.append(d);
+  // 폭은 짓을 때 잰다 — 글꼴은 장면을 짓기 전에 다 받아 두고, 펜 자리가 화면을 언제 처음 봤는지에 따라 달라지지 않게
+  const probe = el.ownerDocument.createElement("canvas").getContext("2d")!;
+  probe.font = font;
+  const width = probe.measureText(o.text).width;
+  const at = o.at ?? 0;
+  const dur = o.dur ?? Math.max(0.12, [...o.text].length / 18);
+  const base = o.y + size * 0.72;
+  const slope = Math.tan((tilt * Math.PI) / 180);
+  const paint = (t: number) => {
+    const on = t >= at && t < (o.until ?? Infinity);
+    d.style.display = on ? "" : "none";
+    if (!on) return;
+    const p = clamp((t - at) / dur);
+    d.style.clipPath = p >= 1 ? "" : `inset(-20% ${((1 - p) * 100).toFixed(2)}% -20% 0)`;
+  };
+  return traced(paint, [{ at, dur, path: [[o.x, base], [o.x + width, base + slope * width]], writing: true }]);
+}
+
+/** 자 대고 긋는 선 — 꺾은선을 앞에서부터 dur 초에 긋는다(표 칸·밑줄·상자). hand 면 손으로 긋듯 더 흔들린다 */
+export function ruleLine(el: HTMLElement, o: { ctx: SceneCtx; points: Pt[]; at?: number; dur?: number; tone?: string; width?: number; hand?: boolean; seed?: string; until?: number }): Traced {
+  const { ctx } = o;
+  const w = o.width ?? 3;
+  const [bx, by, bw, bh] = boundsOf(o.points, 12);
+  const { c, g, clear } = areaCanvas(el, bx, by, bw, bh);
+  const path = handPath(o.points, { seed: o.seed ?? `rule:${o.points.flat().join(",")}`, wobble: o.hand ? 2.4 : 0.7 });
+  const at = o.at ?? 0;
+  const dur = o.dur ?? 0.25;
+  let last = -1;
+  const paint = (t: number) => {
+    const on = t >= at && t < (o.until ?? Infinity);
+    c.style.display = on ? "" : "none";
+    if (!on) return;
+    const p = clamp((t - at) / dur);
+    if (p === last) return;
+    last = p;
+    clear();
+    strokeHand(g, path, p, { color: color(ctx, o.tone ?? "pencil"), width: w });
+  };
+  return traced(paint, [{ at, dur, path }]);
+}
+
+/**
+ * 고쳐 쓰기 — 틀린 값(그 자리의 글)에 두 줄을 긋고, 빨간 펜으로 옆(또는 위)에 맞는 값을 쓴다. 지우지 않는다.
+ * x·y·w 는 그을 글의 자리(줄은 y 에서), fix 는 고쳐 쓸 글
+ */
+export function strikeFix(el: HTMLElement, o: { ctx: SceneCtx; x: number; y: number; w: number; at: number; fix: string; fixX?: number; fixY?: number; size?: number; tone?: string }): Traced {
+  const { ctx } = o;
+  const lines = [0, 1].map((k) =>
+    ruleLine(el, { ctx, points: [[o.x - 6, o.y + k * 10 - 5], [o.x + o.w + 6, o.y + k * 10 - 8]], at: o.at + k * 0.08, dur: 0.12, tone: o.tone ?? "accent", width: 4, hand: true, seed: `strike:${o.fix}:${k}` }),
+  );
+  const pen = penWrite(el, { ctx, text: o.fix, x: o.fixX ?? o.x + o.w + 28, y: o.fixY ?? o.y - (o.size ?? 64) * 0.62, size: o.size ?? 64, at: o.at + 0.2, tone: o.tone ?? "accent" });
+  const paint = (t: number) => {
+    for (const l of lines) l(t);
+    pen(t);
+  };
+  return traced(paint, [...lines.flatMap((l) => l.strokes), ...pen.strokes]);
+}
+
+/**
+ * 쓰는 펜 — 볼펜 한 자루가 받은 획들을 차례로 따라간다. 획 안에선 펜촉이 획 위에(글씨면 위아래로 오르내리며), 획 사이엔 들어 올려
+ * 다음 획 첫머리로 옮겨 간다. 노트에서 움직이는 것은 쓰는 손이다 — 이 펜이 쉬지 않는 몫을 진다
+ */
+export function penTrack(el: HTMLElement, o: { ctx: SceneCtx; from: Traced[] | Stroke[]; rest?: Pt; until?: number }): (t: number) => void {
+  const { ctx } = o;
+  const strokes = (o.from as (Traced | Stroke)[]).flatMap((x) => ("strokes" in x ? x.strokes : [x as Stroke])).sort((a, b) => a.at - b.at);
+  const rest: Pt = o.rest ?? [ctx.meta.width * 0.86, ctx.meta.height * 0.9];
+  const pen = el.ownerDocument.createElement("div");
+  // 펜촉이 원점 — 몸통은 오른쪽 위로 뻗는다. 그림자는 종이에서 떨어진 만큼 비켜 난다
+  pen.style.cssText = "position:absolute;left:0;top:0;width:0;height:0;pointer-events:none;";
+  const shadow = el.ownerDocument.createElement("div");
+  const body = el.ownerDocument.createElement("div");
+  const barrel = `position:absolute;left:0;top:-14px;width:440px;height:28px;transform-origin:0 50%;transform:rotate(-52deg);`;
+  shadow.style.cssText = `${barrel}background:rgba(40,40,50,0.22);border-radius:14px;filter:blur(6px);`;
+  body.style.cssText = `${barrel}`;
+  body.innerHTML = `<div style="position:absolute;left:0;top:9px;width:0;height:0;border-top:5px solid transparent;border-bottom:5px solid transparent;border-right:34px solid ${color(ctx, "pencil")};transform:translateX(-2px)"></div><div style="position:absolute;left:30px;top:0;width:60px;height:28px;background:${color(ctx, "raised")};border-radius:4px 0 0 4px"></div><div style="position:absolute;left:88px;top:0;width:330px;height:28px;background:${color(ctx, "ink")};border-radius:0 14px 14px 0"></div><div style="position:absolute;left:380px;top:-6px;width:18px;height:40px;background:${color(ctx, "inkSoft")};border-radius:4px"></div>`;
+  pen.append(shadow, body);
+  el.append(pen);
+  const at = (s: Stroke, p: number): Pt => {
+    const pts = s.path;
+    if (pts.length < 2) return pts[0] ?? rest;
+    const seg = pts.slice(1).map((q, i) => Math.hypot(q[0] - pts[i][0], q[1] - pts[i][1]));
+    const total = seg.reduce((a, b) => a + b, 0) || 1;
+    let left = clamp(p) * total;
+    for (let i = 0; i < seg.length; i++) {
+      if (left <= seg[i] || i === seg.length - 1) {
+        const k = seg[i] ? Math.min(1, left / seg[i]) : 0;
+        return [pts[i][0] + (pts[i + 1][0] - pts[i][0]) * k, pts[i][1] + (pts[i + 1][1] - pts[i][1]) * k];
+      }
+      left -= seg[i];
+    }
+    return pts[pts.length - 1];
+  };
+  const first = (s: Stroke): Pt => s.path[0] ?? rest;
+  const last = (s: Stroke): Pt => s.path[s.path.length - 1] ?? rest;
+  return (t) => {
+    const on = t < (o.until ?? Infinity);
+    pen.style.display = on ? "" : "none";
+    if (!on) return;
+    let x = rest[0];
+    let y = rest[1];
+    let lift = 1;
+    const cur = strokes.find((s) => t >= s.at && t < s.at + s.dur);
+    if (cur) {
+      const p = (t - cur.at) / cur.dur;
+      [x, y] = at(cur, p);
+      if (cur.writing) y -= Math.abs(Math.sin(p * cur.path.length * 9 + (t - cur.at) * 38)) * 14;
+      lift = 0;
+    } else {
+      const prev = [...strokes].reverse().find((s) => s.at + s.dur <= t);
+      const next = strokes.find((s) => s.at > t);
+      const a: Pt = prev ? last(prev) : rest;
+      const b: Pt = next ? first(next) : rest;
+      const t0 = prev ? prev.at + prev.dur : 0;
+      const t1 = next ? next.at : Math.max(t0 + 0.4, t);
+      const u = ease.inOutCubic(clamp((t - t0) / Math.max(1e-3, t1 - t0)));
+      x = a[0] + (b[0] - a[0]) * u;
+      y = a[1] + (b[1] - a[1]) * u;
+      lift = Math.sin(Math.PI * u);
+    }
+    const h = 18 + lift * 40;
+    pen.style.transform = `translate(${x.toFixed(1)}px, ${(y - lift * 26).toFixed(1)}px)`;
+    shadow.style.transform = `translate(${(h * 0.6).toFixed(1)}px, ${(h * 0.9).toFixed(1)}px) rotate(-52deg)`;
+  };
+}
+
+/** 형광펜 — 노란 띠가 왼쪽부터 칠해진다(곱하기라 아래 글이 비친다). 가장자리는 조금 거칠다 */
+export function highlighter(el: HTMLElement, o: { ctx: SceneCtx; x: number; y: number; w: number; h: number; at: number; dur?: number; tone?: string }): (t: number) => void {
+  const { ctx } = o;
+  const { c, g, clear } = areaCanvas(el, o.x - 10, o.y - 10, o.w + 20, o.h + 20);
+  c.style.mixBlendMode = "multiply";
+  const dur = o.dur ?? 0.25;
+  let last = -1;
+  return (t) => {
+    c.style.display = t >= o.at ? "" : "none";
+    if (t < o.at) return;
+    const p = clamp((t - o.at) / dur);
+    if (p === last) return;
+    last = p;
+    clear();
+    g.fillStyle = color(ctx, o.tone ?? "highlight");
+    g.globalAlpha = 0.85;
+    g.beginPath();
+    const end = o.x + o.w * p;
+    const steps = 24;
+    g.moveTo(o.x, o.y + 3);
+    for (let i = 0; i <= steps; i++) g.lineTo(o.x + ((end - o.x) * i) / steps, o.y + rand(`hl:${o.x}`, i) * 5);
+    for (let i = steps; i >= 0; i--) g.lineTo(o.x + ((end - o.x) * i) / steps, o.y + o.h - rand(`hl:${o.y}`, i) * 5);
+    g.closePath();
+    g.fill();
+    g.globalAlpha = 1;
+  };
+}
+
+export interface TapeOpts {
+  ctx: SceneCtx;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  at: number;
+  /** 붙인 각(도) — 손으로 붙여 조금 비뚤다 */
+  rot?: number;
+  /** 출력물 안을 짓는다 — 돌려준 그리기는 카드가 놓인 뒤 장면 시각을 받는다 */
+  build?(card: HTMLElement): (t: number) => void;
+}
+
+/** 출력물 붙이기 — 흰 출력 종이가 위에서 내려와 놓이고, 마스킹 테이프 두 조각이 모서리에 차례로 붙는다 */
+export function tapeOn(el: HTMLElement, o: TapeOpts): (t: number) => void {
+  const { ctx } = o;
+  const box = el.ownerDocument.createElement("div");
+  const rot = o.rot ?? (rand(`tape:${o.x}`, 0) - 0.5) * 3;
+  box.style.cssText = `position:absolute;left:${o.x}px;top:${o.y}px;width:${o.w}px;height:${o.h}px;transform-origin:50% 0;display:none;`;
+  el.append(box);
+  const card = el.ownerDocument.createElement("div");
+  card.style.cssText = `position:absolute;inset:0;background:${color(ctx, "print")};box-shadow:0 2px 0 ${color(ctx, "raised")}, 6px 10px 18px rgba(30,30,40,0.18);overflow:hidden;`;
+  box.append(card);
+  const inner = o.build?.(card) ?? (() => {});
+  const tapes = [0, 1].map((k) => {
+    const s = el.ownerDocument.createElement("div");
+    const tw = Math.round(Math.min(160, o.w * 0.28));
+    s.style.cssText = `position:absolute;top:-22px;${k ? "right" : "left"}:-34px;width:${tw}px;height:46px;background:${color(ctx, "tape")};opacity:0.82;transform:rotate(${k ? 38 : -38}deg);clip-path:polygon(0 8%, 6% 0, 12% 10%, 18% 0, 82% 4%, 88% 0, 94% 9%, 100% 2%, 100% 92%, 94% 100%, 88% 90%, 82% 100%, 18% 96%, 12% 100%, 6% 91%, 0 98%);display:none;`;
+    box.append(s);
+    return s;
+  });
+  return (t) => {
+    const on = t >= o.at;
+    box.style.display = on ? "" : "none";
+    if (!on) return;
+    const p = ease.outCubic(clamp((t - o.at) / 0.22));
+    box.style.transform = `translateY(${((1 - p) * -60).toFixed(1)}px) rotate(${(rot + (1 - p) * 4).toFixed(2)}deg)`;
+    tapes.forEach((s, k) => {
+      const ta = o.at + 0.2 + k * 0.08;
+      s.style.display = t >= ta ? "" : "none";
+      s.style.opacity = String(t >= ta + 0.04 ? 0.82 : 0.5);
+    });
+    inner(t);
+  };
+}
+
+export interface PlotOpts {
+  ctx: SceneCtx;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /** 점 — 값 축 기준 */
+  points: [number, number][];
+  xMax: number;
+  yMax: number;
+  at: number;
+  /** 초당 찍는 점 */
+  rate?: number;
+  /** 점 옆 글(출력 글꼴) */
+  labels?: string[];
+  /** 점을 잇는 선 — step 이면 계단 */
+  line?: "none" | "line" | "step";
+  ticks?: { x?: [number, string][]; y?: [number, string][] };
+  tone?: string;
+}
+
+/** 출력 그래프 — 축과 눈금이 찍혀 있고, 점이 하나씩 동그라미로 찍히며 선이 이어진다(점 옆에 값). 테이프로 붙인 카드 안에 */
+export function plotPoints(el: HTMLElement, o: PlotOpts): (t: number) => void {
+  const { ctx } = o;
+  const { g, clear } = areaCanvas(el, o.x - 70, o.y - 30, o.w + 110, o.h + 80);
+  const X = (v: number) => o.x + (v / o.xMax) * o.w;
+  const Y = (v: number) => o.y + o.h - (v / o.yMax) * o.h;
+  const ink = color(ctx, "printInk");
+  const tone = color(ctx, o.tone ?? "printInk");
+  const font = `500 22px ${ctx.style.fonts.mono}`;
+  const rate = o.rate ?? 30;
+  let last = -1;
+  return (t) => {
+    const n = t < o.at ? 0 : Math.min(o.points.length, Math.floor((t - o.at) * rate + 1e-6) + 1);
+    if (n === last) return;
+    last = n;
+    clear();
+    if (t < o.at) return;
+    g.strokeStyle = ink;
+    g.lineWidth = 2;
+    g.beginPath();
+    g.moveTo(o.x, o.y);
+    g.lineTo(o.x, o.y + o.h);
+    g.lineTo(o.x + o.w, o.y + o.h);
+    g.stroke();
+    g.fillStyle = ink;
+    g.font = font;
+    g.textAlign = "center";
+    g.textBaseline = "top";
+    for (const [v, s] of o.ticks?.x ?? []) {
+      g.fillRect(X(v) - 1, o.y + o.h, 2, 8);
+      g.fillText(s, X(v), o.y + o.h + 12);
+    }
+    g.textAlign = "right";
+    g.textBaseline = "middle";
+    for (const [v, s] of o.ticks?.y ?? []) {
+      g.fillRect(o.x - 8, Y(v) - 1, 8, 2);
+      g.fillText(s, o.x - 12, Y(v));
+    }
+    const pts = o.points.slice(0, n);
+    if ((o.line ?? "line") !== "none" && pts.length > 1) {
+      g.strokeStyle = tone;
+      g.lineWidth = 3;
+      g.beginPath();
+      pts.forEach(([px, py], i) => {
+        if (i === 0) g.moveTo(X(px), Y(py));
+        else if (o.line === "step") {
+          g.lineTo(X(px), Y(pts[i - 1][1]));
+          g.lineTo(X(px), Y(py));
+        } else g.lineTo(X(px), Y(py));
+      });
+      g.stroke();
+    }
+    g.textAlign = "left";
+    g.textBaseline = "bottom";
+    pts.forEach(([px, py], i) => {
+      g.strokeStyle = tone;
+      g.fillStyle = color(ctx, "print");
+      g.lineWidth = 3;
+      g.beginPath();
+      g.arc(X(px), Y(py), 7, 0, Math.PI * 2);
+      g.fill();
+      g.stroke();
+      const s = o.labels?.[i];
+      if (s) {
+        g.fillStyle = ink;
+        g.fillText(s, X(px) + 10, Y(py) - 8);
+      }
+    });
+  };
+}
+
+/** 여백 메모 — 손으로 그은 휜 화살표가 메모에서 짚을 곳으로 뻗고, 메모 글이 빨간 펜으로 적힌다 */
+export function arrowNote(el: HTMLElement, o: { ctx: SceneCtx; from: Pt; to: Pt; text?: string; textAt?: Pt; at: number; dur?: number; tone?: string; bend?: number; size?: number }): Traced {
+  const { ctx } = o;
+  const [x0, y0] = o.from;
+  const [x1, y1] = o.to;
+  const bend = o.bend ?? 0.25;
+  const mx = (x0 + x1) / 2 - (y1 - y0) * bend;
+  const my = (y0 + y1) / 2 + (x1 - x0) * bend;
+  const curve: Pt[] = Array.from({ length: 21 }, (_, i) => {
+    const u = i / 20;
+    return [(1 - u) ** 2 * x0 + 2 * (1 - u) * u * mx + u * u * x1, (1 - u) ** 2 * y0 + 2 * (1 - u) * u * my + u * u * y1];
+  });
+  const path = handPath(curve, { seed: `arrow:${x0}:${y0}`, wobble: 1.6 });
+  const a = Math.atan2(y1 - curve[18][1], x1 - curve[18][0]);
+  const head: Pt[][] = [-0.5, 0.5].map((da) => [[x1 - Math.cos(a + da) * 26, y1 - Math.sin(a + da) * 26], [x1, y1]]);
+  const [bx, by, bw, bh] = boundsOf([...path, ...head.flat()], 16);
+  const { c, g, clear } = areaCanvas(el, bx, by, bw, bh);
+  const pen = o.text ? penWrite(el, { ctx, text: o.text, x: (o.textAt ?? o.from)[0], y: (o.textAt ?? o.from)[1], size: o.size ?? 56, at: o.at + (o.dur ?? 0.25), tone: o.tone ?? "accent" }) : null;
+  const dur = o.dur ?? 0.25;
+  let last = -1;
+  const paint = (t: number) => {
+    c.style.display = t >= o.at ? "" : "none";
+    pen?.(t);
+    if (t < o.at) return;
+    const p = clamp((t - o.at) / dur);
+    if (p === last) return;
+    last = p;
+    clear();
+    const ink = color(ctx, o.tone ?? "accent");
+    strokeHand(g, path, p, { color: ink, width: 4 });
+    if (p >= 1) for (const h of head) strokeHand(g, h, 1, { color: ink, width: 4 });
+  };
+  return traced(paint, [{ at: o.at, dur, path }, ...(pen?.strokes ?? [])]);
+}
+
+/**
+ * 드롭 — 빨간 고무 도장. 도장이 크게 들렸다가 드롭 박에 쾅 찍혀 앉는다(이중 테 · 잉크가 덜 묻은 결). 흔들림·한 번 튐을 돌려준다
+ */
+export function resultStamp(el: HTMLElement, o: { ctx: SceneCtx; drop?: number; x: number; y: number; text: string; size?: number; tone?: string; rot?: number }): (t: number) => DropBurstState {
+  const { ctx } = o;
+  const size = o.size ?? 200;
+  const box = el.ownerDocument.createElement("div");
+  const tone = color(ctx, o.tone ?? "accent");
+  box.textContent = o.text;
+  // 잉크가 고르게 안 묻은 고무 도장 — 바탕색 반점을 위에 덮는다(시드 고정)
+  const specks = Array.from({ length: 18 }, (_, i) => `radial-gradient(circle at ${(rand("stamp", i) * 100).toFixed(1)}% ${(rand("stamp", i + 40) * 100).toFixed(1)}%, ${color(ctx, "bg")} 0 ${(2 + rand("stamp", i + 80) * 5).toFixed(1)}px, transparent ${(3 + rand("stamp", i + 80) * 5).toFixed(1)}px)`).join(",");
+  box.style.cssText = `position:absolute;left:${o.x}px;top:${o.y}px;transform:translate(-50%,-50%) rotate(${o.rot ?? -6}deg);font:400 ${size}px ${ctx.style.fonts.display};line-height:1;color:${tone};padding:${Math.round(size * 0.12)}px ${Math.round(size * 0.3)}px;border:${Math.round(size * 0.05)}px solid ${tone};outline:${Math.round(size * 0.025)}px solid ${tone};outline-offset:${Math.round(size * 0.05)}px;white-space:pre;display:none;background-image:${specks};mix-blend-mode:multiply;`;
+  el.append(box);
+  return (t) => {
+    const s = dropBurst(t, { beats: ctx.beats, drop: o.drop ?? 0, rules: ctx.style.motion, scene: ctx.id, source: "resultStamp" });
+    const local = t - ctx.beats.drop(o.drop ?? 0);
+    // 드롭 0.15초 앞에 도장이 들린 채 나타난다 — 찍히는 순간이 박
+    const lead = 0.15;
+    box.style.display = local >= -lead ? "" : "none";
+    if (local < -lead) return s;
+    const k = local < 0 ? 1 + 0.5 * (-local / lead) : 1 + 0.08 * Math.exp(-local / 0.05);
+    const op = local < 0 ? 0.35 : 1;
+    box.style.transform = `translate(-50%,-50%) rotate(${o.rot ?? -6}deg) scale(${k.toFixed(4)})`;
+    box.style.opacity = String(op);
+    return s;
+  };
+}

package/themes/lab-notebook/kit.ts

@@ -0,0 +1,84 @@
+import { noise1, type SceneCtx } from "@kasaframe/core";
+
+// effects.ts 의 이름 있는 내보내기는 theme.json 효과 목록과 같아야 해서, 효과가 아닌 도구(색·캔버스·손 떨림 선)는 여기 둔다
+
+export type Pt = [number, number];
+
+export const color = (ctx: SceneCtx, key: string): string => ctx.style.colors[key] ?? key;
+
+/** 화면 좌표를 그대로 쓰는 캔버스 — 그리는 자리만큼만 */
+export function areaCanvas(el: HTMLElement, x: number, y: number, w: number, h: number): { c: HTMLCanvasElement; g: CanvasRenderingContext2D; clear(): void } {
+  const X = Math.floor(x);
+  const Y = Math.floor(y);
+  const W = Math.max(1, Math.ceil(w));
+  const H = Math.max(1, Math.ceil(h));
+  const c = el.ownerDocument.createElement("canvas");
+  c.width = W;
+  c.height = H;
+  c.style.cssText = `position:absolute;left:${X}px;top:${Y}px;width:${W}px;height:${H}px;pointer-events:none;`;
+  el.append(c);
+  const g = c.getContext("2d")!;
+  g.translate(-X, -Y);
+  return { c, g, clear: () => g.clearRect(X, Y, W, H) };
+}
+
+/** 점들을 감싸는 상자(여백 pad) */
+export function boundsOf(pts: readonly Pt[], pad: number): [number, number, number, number] {
+  const xs = pts.map((p) => p[0]);
+  const ys = pts.map((p) => p[1]);
+  return [Math.min(...xs) - pad, Math.min(...ys) - pad, Math.max(...xs) - Math.min(...xs) + pad * 2, Math.max(...ys) - Math.min(...ys) + pad * 2];
+}
+
+/**
+ * 손으로 그은 선 — 꺾은선을 잘게 나눠 시드 고정 잡음으로 옆으로 조금씩 흔든다(wobble px). 같은 시드면 늘 같은 떨림.
+ * p 는 앞에서부터 그은 비율
+ */
+export function handPath(pts: readonly Pt[], o: { seed: string; wobble?: number; step?: number }): Pt[] {
+  const out: Pt[] = [];
+  const step = o.step ?? 6;
+  const wob = o.wobble ?? 1.6;
+  let s = 0;
+  for (let i = 1; i < pts.length; i++) {
+    const [x0, y0] = pts[i - 1];
+    const [x1, y1] = pts[i];
+    const len = Math.hypot(x1 - x0, y1 - y0) || 1;
+    const nx = -(y1 - y0) / len;
+    const ny = (x1 - x0) / len;
+    const n = Math.max(1, Math.ceil(len / step));
+    for (let k = i === 1 ? 0 : 1; k <= n; k++) {
+      const u = k / n;
+      const d = noise1(o.seed, (s + u * len) / 60) * wob;
+      out.push([x0 + (x1 - x0) * u + nx * d, y0 + (y1 - y0) * u + ny * d]);
+    }
+    s += len;
+  }
+  return out;
+}
+
+/** 손 선을 비율 p 까지 긋는다 — 펜 압력처럼 끝이 조금 가늘어진다 */
+export function strokeHand(g: CanvasRenderingContext2D, path: readonly Pt[], p: number, o: { color: string; width: number; alpha?: number }): void {
+  const n = Math.floor(Math.max(0, Math.min(1, p)) * (path.length - 1));
+  if (n < 1) return;
+  g.save();
+  g.strokeStyle = o.color;
+  g.globalAlpha = o.alpha ?? 1;
+  g.lineCap = "round";
+  g.lineJoin = "round";
+  g.lineWidth = o.width;
+  g.beginPath();
+  g.moveTo(path[0][0], path[0][1]);
+  for (let i = 1; i <= n; i++) g.lineTo(path[i][0], path[i][1]);
+  g.stroke();
+  g.restore();
+}
+
+/** 타원 한 바퀴 남짓 — 손으로 그린 동그라미(시작과 끝이 겹치며 조금 비켜 간다) */
+export function ellipsePts(cx: number, cy: number, rx: number, ry: number, turns: number, seed: string): Pt[] {
+  const n = Math.ceil(64 * turns);
+  const a0 = -Math.PI * 0.6 + noise1(seed, 3) * 0.4;
+  return Array.from({ length: n + 1 }, (_, i) => {
+    const a = a0 + (i / n) * Math.PI * 2 * turns;
+    const k = 1 + (i / n) * 0.06;
+    return [cx + Math.cos(a) * rx * k, cy + Math.sin(a) * ry * k] as Pt;
+  });
+}