@cardenelabs/dragon 0.34.0 → 0.35.0

package/src/player-global.ts

@@ -0,0 +1,4 @@
+/**
+ * HTML に書き出した頁へ埋める script の入口。1 file に束ね、`DragonPlayer.mountDiagram` として出す。
+ */
+export { mountDiagram } from "./player";

package/src/player.ts

@@ -0,0 +1,271 @@
+/**
+ * 頁に図を置いて動かす。
+ *
+ * 動きを嫌う設定 (`prefers-reduced-motion: reduce`) は描く前に読み、その人には一瞬も自動再生せず、
+ * 段ごとの止め絵を釦で送る。各段の題と本文は、読み上げの道具が段の順に読める番号付きの一覧として置き、
+ * 図そのものは読み上げから隠して同じ中身を 2 度読ませない。
+ * 見せ方は枠の幅で選び (`view.ts`)、寄って追う時は窓と全体図で描き直す。
+ * 釦と段の一覧の読み上げの名前と全体図の札は、渡した言葉 (`options.lang`、書かなければ日本語) で出す (#3001)。
+ */
+import { FIGURE_TEXT } from "./figure-text";
+import { FONT_VARS, LOOK, paletteVars, resolvePalette, type TextStyle, TYPE } from "./look/values";
+import { drawSvg, type RenderOptions, renderDiagram } from "./render/svg";
+import type { Span } from "./timeline";
+import { chooseView } from "./view";
+
+export interface Player {
+  /** 今の段 (0 から) */
+  readonly step: number;
+  /** 動いているか */
+  readonly playing: boolean;
+  next(): void;
+  prev(): void;
+  play(): void;
+  pause(): void;
+  destroy(): void;
+}
+
+const font = (t: TextStyle): string => `font:${t.weight} ${t.size}px var(--${t.family})`;
+const px = (v: number): string => `${v}px`;
+
+function playerCss(): string {
+  const P = LOOK.player;
+  const hidden = px(P.hidden);
+  return [
+    `.dg-player{display:flex;flex-direction:column;gap:${px(P.gap)};color:var(--ink)}`,
+    `.dg-player .dg-frame{border-radius:${px(P.radius)};overflow:hidden}`,
+    `.dg-bar{display:flex;align-items:flex-start;gap:${px(P.gap)}}`,
+    `.dg-btns{display:flex;gap:${px(P.gap / 2)};flex:none}`,
+    `.dg-btn{width:${px(P.button)};height:${px(P.button)};border-radius:${px(P.radius)};border:${px(LOOK.stroke.hair)} solid var(--hair);background:var(--surf);color:var(--ink);${font(TYPE.button)};cursor:pointer}`,
+    `.dg-btn:focus-visible{outline:${px(P.focus)} solid var(--c-blue);outline-offset:${px(P.focus)}}`,
+    `.dg-say{display:flex;gap:${px(P.gap)};min-width:0}`,
+    `.dg-no{${font(TYPE.stepNo)};color:var(--mute);padding-top:${px(P.focus)}}`,
+    `.dg-tt{${font(TYPE.stepTitle)};margin:0}`,
+    `.dg-tb{${font(TYPE.stepBody)};color:var(--ink2);margin:0;white-space:pre-line}`,
+    `.dg-sr{position:absolute;width:${hidden};height:${hidden};margin:-${hidden};padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0}`,
+  ].join("");
+}
+
+function ensureCss(doc: Document): void {
+  if (doc.getElementById("dragon-player-css")) return;
+  const style = doc.createElement("style");
+  style.id = "dragon-player-css";
+  style.textContent = playerCss();
+  doc.head.appendChild(style);
+}
+
+/** 釦に出す字。HTML に書き出す時は、この字も字の file に残す。 */
+export const BUTTON_TEXT = { prev: "‹", pause: "❚❚", play: "▶", next: "›" } as const;
+
+const pad = (n: number): string => String(n).padStart(2, "0");
+/** 段の番号の札 (`01/12`)。`step` は 0 から数える。 */
+export const stepNo = (step: number, count: number): string => `${pad(step + 1)}/${pad(count)}`;
+
+export function mountDiagram(host: HTMLElement, diagram: unknown, options: RenderOptions = {}): Player {
+  const doc = host.ownerDocument;
+  const win = doc.defaultView;
+  // 描く前に読む。描いた後に読むと、動きを嫌う人にも一瞬だけ流れてしまう
+  const reduce = Boolean(win?.matchMedia?.("(prefers-reduced-motion: reduce)").matches);
+  const rendered = renderDiagram(diagram, options);
+  const lang = options.lang ?? "ja";
+  const words = FIGURE_TEXT[lang];
+  const palette = resolvePalette(rendered.palette);
+  const { timeline } = rendered;
+  const steps = rendered.diagram.steps;
+  const count = steps.length;
+
+  ensureCss(doc);
+  const root = doc.createElement("div");
+  root.className = "dg-player";
+  root.dataset.dragon = "player";
+  root.setAttribute("style", `${FONT_VARS};${paletteVars(palette, rendered.theme)}`);
+
+  const frame = doc.createElement("div");
+  frame.className = "dg-frame";
+  const button = (name: string, label: string, text: string): HTMLButtonElement => {
+    const b = doc.createElement("button");
+    b.type = "button";
+    b.className = "dg-btn";
+    b.dataset.dragon = name;
+    b.setAttribute("aria-label", label);
+    b.textContent = text;
+    return b;
+  };
+  const prevButton = button("prev", words.prev, BUTTON_TEXT.prev);
+  const toggleButton = button("toggle", words.pause, BUTTON_TEXT.pause);
+  const nextButton = button("next", words.next, BUTTON_TEXT.next);
+  const buttons = doc.createElement("div");
+  buttons.className = "dg-btns";
+  // 置いた頁の言葉と違っても、釦の名前を名前の言葉の声で読ませる
+  buttons.setAttribute("lang", lang);
+  buttons.append(prevButton, toggleButton, nextButton);
+
+  // 見える語り。読み上げには下の一覧を読ませるので、こちらは読み上げから隠す
+  const say = doc.createElement("div");
+  say.className = "dg-say";
+  say.setAttribute("aria-hidden", "true");
+  const no = doc.createElement("div");
+  no.className = "dg-no";
+  no.dataset.dragon = "step-no";
+  const text = doc.createElement("div");
+  const title = doc.createElement("p");
+  title.className = "dg-tt";
+  title.dataset.dragon = "step-title";
+  const body = doc.createElement("p");
+  body.className = "dg-tb";
+  body.dataset.dragon = "step-body";
+  text.append(title, body);
+  say.append(no, text);
+  const bar = doc.createElement("div");
+  bar.className = "dg-bar";
+  bar.append(buttons, say);
+
+  // 読み上げの道具が段の順に読む一覧。見た目からは外すが、読み上げからは隠さない
+  const list = doc.createElement("ol");
+  list.className = "dg-sr";
+  list.dataset.dragon = "steps";
+  list.setAttribute("aria-label", words.steps(rendered.diagram.title));
+  for (const step of steps) {
+    const item = doc.createElement("li");
+    const head = doc.createElement("strong");
+    head.textContent = step.title;
+    item.append(head);
+    for (const line of step.body.split("\n")) {
+      const p = doc.createElement("p");
+      p.textContent = line;
+      item.append(p);
+    }
+    list.append(item);
+  }
+
+  root.append(frame, bar, list);
+  host.append(root);
+
+  const frameWidth = (): number => frame.clientWidth || host.clientWidth || rendered.layout.width;
+  let mode = chooseView(rendered, frameWidth()).mode;
+  let width = frameWidth();
+  let svg: SVGSVGElement | null = null;
+  let step = 0;
+  let playing = !reduce;
+  let at = reduce ? (timeline.stills[0] ?? 0) : 0;
+  let born = Date.now();
+
+  /** 動きの変数を付けた図を置き直す。置き直すと動きの時計が最初から数え直される */
+  const place = (markup?: string): void => {
+    let next: SVGSVGElement | null;
+    if (markup !== undefined) {
+      const holder = doc.createElement("div");
+      holder.innerHTML = markup;
+      next = holder.querySelector("svg");
+    } else {
+      next = svg ? (svg.cloneNode(true) as SVGSVGElement) : null;
+    }
+    if (!next) return;
+    next.setAttribute("aria-hidden", "true");
+    next.removeAttribute("role");
+    next.removeAttribute("aria-label");
+    next.style.setProperty("--at", String(at));
+    next.style.setProperty("--play", playing ? "running" : "paused");
+    next.dataset.motion = playing ? "play" : "still";
+    if (svg) svg.replaceWith(next);
+    else frame.append(next);
+    svg = next;
+    born = Date.now();
+  };
+  const markup = (): string => (mode === "follow" ? drawSvg(rendered.diagram, rendered.layout, timeline, palette, rendered.theme, { width, lang }) : rendered.svg);
+
+  const now = (): number => (playing ? (at + (Date.now() - born) / 1000) % timeline.total : at);
+  const stepAt = (t: number): number => {
+    let found = 0;
+    timeline.steps.forEach((span: Span, i) => {
+      if (span.start <= t) found = i;
+    });
+    return found;
+  };
+  const show = (): void => {
+    const current = steps[step];
+    no.textContent = stepNo(step, count);
+    title.textContent = current?.title ?? "";
+    body.textContent = current?.body ?? "";
+    toggleButton.setAttribute("aria-label", playing ? words.pause : words.play);
+    toggleButton.textContent = playing ? BUTTON_TEXT.pause : BUTTON_TEXT.play;
+  };
+  const restart = (t: number, play: boolean): void => {
+    at = t;
+    playing = play;
+    place();
+    show();
+  };
+  const go = (target: number): void => {
+    step = Math.min(count - 1, Math.max(0, target));
+    const span = timeline.steps[step] as Span;
+    restart(playing ? span.start : (timeline.stills[step] ?? span.start), playing);
+  };
+
+  place(markup());
+  show();
+
+  const timer = win?.setInterval(() => {
+    if (!playing) return;
+    const s = stepAt(now());
+    if (s !== step) {
+      step = s;
+      show();
+    }
+  }, 120);
+  const onPrev = (): void => go(step - 1);
+  const onNext = (): void => go(step + 1);
+  const onToggle = (): void => (playing ? restart(now(), false) : restart(at, true));
+  // 段の番号を押すとその段へ移る
+  const onFigure = (event: Event): void => {
+    const target = (event.target as Element | null)?.closest?.("[data-step]");
+    const s = target ? Number(target.getAttribute("data-step")) : Number.NaN;
+    if (Number.isInteger(s)) go(s);
+  };
+  prevButton.addEventListener("click", onPrev);
+  nextButton.addEventListener("click", onNext);
+  toggleButton.addEventListener("click", onToggle);
+  frame.addEventListener("click", onFigure);
+
+  // 枠の幅が変わったら見せ方を選び直す。寄って追う窓は幅で決まるので、幅が変われば描き直す
+  const Observer = (win as (Window & { ResizeObserver?: typeof ResizeObserver }) | null)?.ResizeObserver;
+  const observer = Observer
+    ? new Observer(() => {
+        const w = frameWidth();
+        const chosen = chooseView(rendered, w).mode;
+        if (chosen === mode && (mode === "fixed" || w === width)) return;
+        const t = now();
+        mode = chosen;
+        width = w;
+        at = t;
+        place(markup());
+      })
+    : undefined;
+  observer?.observe(frame);
+
+  return {
+    get step() {
+      return step;
+    },
+    get playing() {
+      return playing;
+    },
+    next: onNext,
+    prev: onPrev,
+    play: () => {
+      if (!playing) restart(at, true);
+    },
+    pause: () => {
+      if (playing) restart(now(), false);
+    },
+    destroy: () => {
+      if (timer !== undefined) win?.clearInterval(timer);
+      observer?.disconnect();
+      prevButton.removeEventListener("click", onPrev);
+      nextButton.removeEventListener("click", onNext);
+      toggleButton.removeEventListener("click", onToggle);
+      frame.removeEventListener("click", onFigure);
+      root.remove();
+    },
+  };
+}

package/src/printer.ts

@@ -0,0 +1,76 @@
+/**
+ * 図の原本の JSON を、人が書く記法へ書き戻す。
+ *
+ * 並べ方は決まった形に整える。JSON の欄の並び順は見ず、欄の名前で読むので、
+ * 同じ内容の JSON からは毎回同じ文字列になる。書き手の行の並べ方とコメントは保たない。
+ * 段の中で起きることは JSON の並び順 (起きる順) のまま書く。
+ *
+ * 語は渡した言葉で書く (#2997)。渡さなければ日本語で書く。
+ * 英語では添え書きと下の字と書き換えの字を `"…"` で囲み、名前か字に `"` を含む物だけ「」で囲む。
+ * 英語の語の file でも「」は読めるので、読み直すと同じ JSON に戻る。
+ */
+import type { Box, Carry, Diagram, DiagramEvent, Region } from "./schema";
+import { type NotationLang, type WORDS, wordOf } from "./words";
+
+type AttrKey = keyof typeof WORDS.attr;
+
+export interface PrintOptions {
+  /** 記法の語の言葉。既定は日本語 */
+  lang?: NotationLang;
+}
+
+/** 名前の後ろに `text` を囲んで付ける。`text` が無ければ何も付けない */
+function quoted(name: string, text: string | undefined, lang: NotationLang): string {
+  if (text === undefined) return "";
+  if (lang === "en" && !name.includes('"') && !text.includes('"')) return ` "${text}"`;
+  return `「${text}」`;
+}
+
+export function printNotation(diagram: Diagram, options: PrintOptions = {}): string {
+  const lang = options.lang ?? "ja";
+  const attrs = (pairs: [AttrKey, string | undefined][]): string =>
+    pairs
+      .filter((pair): pair is [AttrKey, string] => pair[1] !== undefined)
+      .map(([key, value]) => ` [${wordOf("attr", key, lang)} ${value}]`)
+      .join("");
+
+  const region = (r: Region): string =>
+    `${wordOf("head", "region", lang)} ${r.id} = ${r.name}${quoted(r.name, r.note, lang)}${attrs([["color", r.color], ["icon", r.icon]])}`;
+  const box = (b: Box): string =>
+    `${b.id} = ${b.name}${quoted(b.name, b.sub, lang)}${attrs([["color", b.color], ["icon", b.icon], ["region", b.region]])}`;
+
+  const carry = (c: Carry): string => {
+    if (c.kind === "envelope") return "";
+    if (c.kind === "tag") return ` [${wordOf("carry", "tag", lang)} ${c.text}]`;
+    return ` [${wordOf("carry", c.kind, lang)}]`;
+  };
+
+  const event = (e: DiagramEvent): string => {
+    switch (e.type) {
+      case "edge":
+        return `${e.from} -> ${e.to}${e.label === undefined ? "" : ` : ${e.label}`}${carry(e.carry)}${e.labelSide ? ` [${wordOf("attr", "label", lang)} ${wordOf("side", e.labelSide, lang)}]` : ""}`;
+      case "action":
+        return `${e.box} : ${e.label}`;
+      case "swap":
+        return `${e.box}${quoted("", e.text, lang)}`;
+      case "strip":
+        return `${wordOf("head", "strip", lang)} ${e.field}${e.value === undefined ? "" : ` = ${e.value}`}${e.tag === undefined ? "" : ` [${e.tag}]`}`;
+    }
+  };
+
+  const head = [
+    ...(diagram.view ? [`${wordOf("head", "view", lang)} ${wordOf("view", diagram.view, lang)}`] : []),
+    ...(diagram.regions ?? []).map(region),
+    ...diagram.boxes.map(box),
+    ...(diagram.strip ? [`${wordOf("head", "strip", lang)} ${diagram.strip.title} = ${diagram.strip.fields.join(", ")}`] : []),
+  ];
+  const steps = diagram.steps.map((step) =>
+    [
+      `# ${step.title}`,
+      ...step.body.split("\n").map((line) => `> ${line}`),
+      ...(step.code === undefined ? [] : [`\`${step.code}\``]),
+      ...step.events.map(event),
+    ].join("\n"),
+  );
+  return [`${wordOf("kind", diagram.kind, lang)} ${diagram.title}`, head.join("\n"), ...steps].join("\n\n") + "\n";
+}

package/src/render/icons.ts

@@ -0,0 +1,41 @@
+/**
+ * 箱と区画の印の形。どれも (0, 0) を中心に 20 四方へ収める。
+ *
+ * 見本帳 (`docs/design/base/engine.js` の `G`) と同じ形を持つ。`block` だけは見本帳が絵を手で描いていたので、ここで足した。
+ */
+export const ICONS: Readonly<Record<string, string>> = {
+  app: "M -9 -7 h18 a2 2 0 0 1 2 2 v10 a2 2 0 0 1 -2 2 h-18 a2 2 0 0 1 -2 -2 v-10 a2 2 0 0 1 2 -2 z M -11 -2 h22",
+  router: "M -9 -4 h16 M 3 -8 l4 4 l-4 4 M 9 5 h-16 M -3 1 l-4 4 l4 4",
+  on: "M -7 7 L 7 -7 M -1 -7 h8 v8",
+  off: "M -7 -7 L 7 7 M 7 -1 v8 h-8",
+  pool: "M -9 -5 a9 3.5 0 1 0 18 0 a9 3.5 0 1 0 -18 0 M -9 -5 v10 a9 3.5 0 0 0 18 0 v-10 M -9 0 a9 3.5 0 0 0 18 0",
+  db: "M -9 -5 a9 3.5 0 1 0 18 0 a9 3.5 0 1 0 -18 0 M -9 -5 v10 a9 3.5 0 0 0 18 0 v-10 M -9 0 a9 3.5 0 0 0 18 0",
+  exe: "M -5 -8 L 7 0 L -5 8 Z",
+  idx: "M -9 -7 h18 M -9 -2 h18 M -9 3 h18 M -9 8 h11",
+  sign: "M -9 4 c 3 -9 5 -9 6 0 s 3 7 6 -2 s 3 -6 6 0",
+  env: "M -8 -5.5 h16 v11 h-16 z M -8 -5.5 l8 6 l8 -6",
+  lock: "M -5.5 -1 h11 v8 h-11 z M -3.5 -1 v-3 a3.5 3.5 0 0 1 7 0 v3",
+  check: "M -5 0 l3.5 3.5 l6.5 -7",
+  x: "M -5 -5 l10 10 M 5 -5 l-10 10",
+  chain: "M -1.5 4.5 l-2 2 a3.5 3.5 0 0 1 -5 -5 l3 -3 a3.5 3.5 0 0 1 5 0 M 1.5 -4.5 l2 -2 a3.5 3.5 0 0 1 5 5 l-3 3 a3.5 3.5 0 0 1 -5 0 M -2.5 2.5 l5 -5",
+  net: "M -1.3 -4.6 L -5.8 3 M 1.3 -4.6 L 5.8 3 M -4.3 5.5 H 4.3 M -2.2 -7 a 2.2 2.2 0 1 0 4.4 0 a 2.2 2.2 0 1 0 -4.4 0 M -9.2 5.5 a 2.2 2.2 0 1 0 4.4 0 a 2.2 2.2 0 1 0 -4.4 0 M 4.8 5.5 a 2.2 2.2 0 1 0 4.4 0 a 2.2 2.2 0 1 0 -4.4 0",
+  user: "M -4 -4.5 a4 4 0 1 0 8 0 a4 4 0 1 0 -8 0 M -8 9 c0 -5 3.6 -7.5 8 -7.5 s8 2.5 8 7.5",
+  server: "M -9 -8 h18 v7 h-18 z M -9 1 h18 v7 h-18 z M -5 -4.5 h0.01 M -5 4.5 h0.01",
+  key: "M -9 0 a3.5 3.5 0 1 0 7 0 a3.5 3.5 0 1 0 -7 0 M -2 0 h10 M 5 0 v3.5 M 8 0 v2.5",
+  shield: "M 0 -9 l8 3 v5 c0 5 -3.5 8 -8 10 c-4.5 -2 -8 -5 -8 -10 v-5 z",
+  globe: "M -9 0 a9 9 0 1 0 18 0 a9 9 0 1 0 -18 0 M -9 0 h18 M 0 -9 c-4.5 4 -4.5 14 0 18 M 0 -9 c4.5 4 4.5 14 0 18",
+  bolt: "M 2 -9 L -5 1 h5 l-2 8 l7 -10 h-5 z",
+  doc: "M -6 -9 h8 l5 5 v13 h-13 z M 2 -9 v5 h5 M -3 1 h7 M -3 5 h5",
+  box: "M -9 -4.5 l9 -4.5 l9 4.5 v9 l-9 4.5 l-9 -4.5 z M -9 -4.5 l9 4.5 l9 -4.5 M 0 0 v9",
+  truck: "M -10 -6 h11 v10 h-11 z M 1 -2 h5 l3.5 3.5 v2.5 h-8.5 M -7.5 6.5 a1.8 1.8 0 1 0 3.6 0 a1.8 1.8 0 1 0 -3.6 0 M 3 6.5 a1.8 1.8 0 1 0 3.6 0 a1.8 1.8 0 1 0 -3.6 0",
+  card: "M -9 -6.5 h18 a2 2 0 0 1 2 2 v9 a2 2 0 0 1 -2 2 h-18 a2 2 0 0 1 -2 -2 v-9 a2 2 0 0 1 2 -2 z M -11 -2 h22 M -7 3 h5",
+  cart: "M -10 -8 h3 l3 11 h11 l2.5 -8 h-15.5 M -4.5 7.5 a1.5 1.5 0 1 0 3 0 a1.5 1.5 0 1 0 -3 0 M 5 7.5 a1.5 1.5 0 1 0 3 0 a1.5 1.5 0 1 0 -3 0",
+  clock: "M -9 0 a9 9 0 1 0 18 0 a9 9 0 1 0 -18 0 M 0 -5 v5 l3.5 2.5",
+  branch: "M -4 -4.5 v9 M 5 0.5 c0 4 -9 3 -9 6.5 M -6.2 -7 a2.2 2.2 0 1 0 4.4 0 a2.2 2.2 0 1 0 -4.4 0 M -6.2 7 a2.2 2.2 0 1 0 4.4 0 a2.2 2.2 0 1 0 -4.4 0 M 2.8 -2 a2.2 2.2 0 1 0 4.4 0 a2.2 2.2 0 1 0 -4.4 0",
+  cloud: "M -7 6 h13 a4.5 4.5 0 0 0 0.5 -9 a6 6 0 0 0 -11.5 -1 a4.5 4.5 0 0 0 -2 10 z",
+  refresh: "M 7 -3 a7.5 7.5 0 1 0 0.5 5 M 7.5 -8 v5 h-5",
+  layers: "M 0 -8 l9 4.5 l-9 4.5 l-9 -4.5 z M -9 2.5 l9 4.5 l9 -4.5",
+  code: "M -4 -6 l-5 6 l5 6 M 4 -6 l5 6 l-5 6",
+  paint: "M -8 8 c 0 -3 2 -5 4.5 -5 l 9 -9 l 3.5 3.5 l -9 9 c 0 2.5 -2 4.5 -5 4.5 z",
+  block: "M -9 -7 h18 a2 2 0 0 1 2 2 v10 a2 2 0 0 1 -2 2 h-18 a2 2 0 0 1 -2 -2 v-10 a2 2 0 0 1 2 -2 z M -11 -2.5 h22 M -6 2.5 h8",
+};

package/src/render/motion.ts

@@ -0,0 +1,106 @@
+/**
+ * 時刻の点の並びから CSS の keyframes を組む道具。見本帳の `engine.js` の `kf` / `vis` / `rise` / `pop` / `move` を写す。
+ *
+ * 動きは全て 1 周 `total` 秒の keyframes で、点の時刻は 1 周の中の割合 (%) に直す。
+ * 性質ごとに独立して補間されるので、点ごとに変える性質だけを書く。
+ */
+import { EASE, LOOK, MOTION } from "../look/values";
+
+export type Props = Record<string, string | number>;
+export type Frame = [time: number, props: Props, ease?: string];
+
+const r2 = (v: number): number => Math.round(v * 100) / 100;
+
+export class Motion {
+  readonly frames: string[] = [];
+  private count = 0;
+
+  constructor(
+    private readonly prefix: string,
+    readonly total: number,
+    readonly last: number,
+  ) {}
+
+  private pct(t: number): number {
+    return +((Math.min(Math.max(t, 0), this.total) / this.total) * 100).toFixed(3);
+  }
+
+  /** keyframes を 1 つ足し、その名前を付ける style の字を返す。 */
+  kf(points: Frame[]): string {
+    const name = `${this.prefix}-${this.count++}`;
+    const at = new Map<number, { props: Props; ease?: string }>();
+    for (const [t, props, ease] of [...points].sort((a, b) => a[0] - b[0])) {
+      const p = this.pct(t);
+      const cur = at.get(p) ?? { props: {} };
+      Object.assign(cur.props, props);
+      if (ease) cur.ease = ease;
+      at.set(p, cur);
+    }
+    const body = [...at]
+      .map(([p, { props, ease }]) => {
+        const d = Object.entries(props).map(([k, v]) => `${k}:${v}`);
+        if (ease) d.push(`animation-timing-function:${ease}`);
+        return `${p}%{${d.join(";")}}`;
+      })
+      .join("");
+    this.frames.push(`@keyframes ${name}{${body}}`);
+    return `animation-name:${name}`;
+  }
+
+  /** `a` で出て `b` から消える。`within` を立てると `b` までに消え終わる。 */
+  vis(a: number, b = this.last, o: { f?: number; on?: Props; off?: Props; ein?: string; within?: boolean } = {}): string {
+    const f = o.f ?? MOTION.fade;
+    const on = o.on ?? {};
+    const off = o.off ?? {};
+    const out = o.within ? Math.max(a + f, b - f) : b;
+    return this.kf([
+      [0, { opacity: 0, ...off }],
+      [a, { opacity: 0, ...off }, o.ein ?? EASE.out],
+      [a + f, { opacity: 1, ...on }],
+      [out, { opacity: 1, ...on }, EASE.inOut],
+      [Math.min(out + f, this.total), { opacity: 0, ...off }],
+      [this.total, { opacity: 0, ...off }],
+    ]);
+  }
+
+  /** 少し下から浮いて出る。 */
+  rise(a: number, b = this.last, within = false): string {
+    return this.vis(a, b, { on: { transform: "translateY(0)" }, off: { transform: `translateY(${LOOK.rise}px)` }, within });
+  }
+
+  /** 小さな所から弾んで出る。 */
+  pop(a: number, b = this.last): string {
+    return this.vis(a, b, { f: MOTION.popFade, ein: EASE.pop, on: { transform: "scale(1)" }, off: { transform: `scale(${LOOK.popFrom})` } });
+  }
+
+  /** 初めから出ていて `b` で消える。 */
+  until(b: number): string {
+    const f = MOTION.untilFade;
+    return this.kf([
+      [0, { opacity: 1 }],
+      [b, { opacity: 1 }, EASE.inOut],
+      [b + f, { opacity: 0 }],
+      [this.last, { opacity: 0 }],
+      [this.total, { opacity: 1 }],
+    ]);
+  }
+
+  /** 点を辿って動く。`[時刻, x, y, 大きさ, 次の点までの緩急]` の並び。 */
+  move(points: [number, number, number, number?, string?][], extra: Frame[] = []): string {
+    return this.kf(
+      points.map(([t, x, y, s = 1, ease]): Frame => [t, { transform: `translate(${r2(x)}px,${r2(y)}px) scale(${s})` }, ease]).concat(extra),
+    );
+  }
+
+  /** `a` から `b` まで見え、`fade` 秒で消える。 */
+  blink(a: number, b: number, fade: number): Frame[] {
+    return [
+      [0, { opacity: 0 }],
+      [a - 0.01, { opacity: 0 }],
+      [a, { opacity: 1 }],
+      [b, { opacity: 1 }],
+      [b + fade, { opacity: 0 }],
+      [this.total, { opacity: 0 }],
+    ];
+  }
+}