kakitori

char

char handles a single character. You can render it as a static SVG, mount an interactive writer that checks each stroke, or check strokes headlessly without a DOM.

import { char } from "@k1low/kakitori";

// Mount an interactive writer that checks each stroke.
const target = document.getElementById("writer")!;
const c = char.create("学");
c.mount(target, {
  size: 300,
  onCorrectStroke: (data) => console.log("OK", data.strokeNum),
  onMistake: (data) => console.log("NG", data.strokeNum),
  onComplete: ({ totalMistakes }) => console.log("done", totalMistakes),
});
c.start();

// Static SVG render with no interaction.
char.render(document.getElementById("preview")!, "学", { size: 80 });

Live example. Pick any character from the gallery below to start a practice session. The slot row shows the expected stroke ending (tome / hane / harai) for each stroke, and is updated to OK / NG after each stroke is checked.

Examples

Five common mount configurations. Each example has its own writer instance — Restart re-arms the writer from scratch (clears the canvas + starts a fresh practice session). The chip row below each cell colors green / red as strokes are checked.

const c = char.create("学");
c.mount(target, { size: 160 });
c.start();

const c = char.create("学");
c.mount(target, { size: 160, showGrid: false });
c.start();

const c = char.create("学");
c.mount(target, { size: 160, showOutline: false });
c.start();

const c = char.create("学");
c.mount(target, { size: 160, correction: "per-char" });
c.start();

const c = char.create("学");
c.mount(target, {
  size: 160,
  retainStrokes: true,
  showAcceptedStroke: false,
});
c.start();

CharResult

c.result() returns a CharResult. This is the leaf type used across the whole stack. The same shape comes back from headless Char.checkStroke() and from the mounted interactive path.

interface CharResult {
  character: string;
  complete: boolean;   // every logical stroke has been observed
  matched: boolean;    // every observed stroke matched
  perStroke: CharStrokeResult[];
  mistakes?: number;             // guided-only
  strokeEndingMistakes?: number; // guided-only
  similarity?: number;           // free / annotation only
  candidate?: string;            // free / annotation only
  // The two fields below are populated when a CharResult comes through
  // a Block / Page result tree (undefined for standalone char.result()).
  source?: "guided" | "free" | "annotation";
  mode?: "write" | "show";
}

interface CharStrokeResult {
  matched: boolean;
  similarity: number;
  strokeEnding?: StrokeEndingResult;
  points?: TimedPoint[];      // raw drawn samples with timestamps
  mistakesOnStroke?: number;  // guided write only
  isBackwards?: boolean;      // guided write only
}

block

block represents one practice problem: a row of cells plus an optional furigana annotation strip. Cells can be guided (one specific character to write or show), free (any of an expected string, matched freehand), or blank (visual placeholder).

import { block } from "@k1low/kakitori/block";

const target = document.getElementById("block-host")!;
const b = block.create(target, {
  spec: {
    cells: [
      { kind: "guided", char: "学", mode: "write" },
      { kind: "guided", char: "校", mode: "write" },
    ],
    annotations: [
      { cellRange: [0, 1], expected: "がっこう", mode: "write" },
    ],
  },
  cellSize: 140,
  onCellComplete: (index, kind, chars) => { /* per cell finished */ },
  onBlockComplete: (result) => { /* this problem finished */ },
});

// Get the structured result tree at any time.
const result = b.result();

Live example. The selector switches between use cases that mix guided / free cells with and without furigana.

Examples

Five common block configurations. Each example has its own block instance — Restart re-creates the block from scratch. The chip row below each block colors green / red per cell as onCellComplete fires.

const b = block.create(target, {
  spec: {
    cells: [
      { kind: "guided", char: "学", mode: "write" },
      { kind: "guided", char: "校", mode: "write" },
    ],
  },
  cellSize: 140,
});

const b = block.create(target, {
  spec: {
    cells: [
      { kind: "guided", char: "学", mode: "show" },
      { kind: "guided", char: "校", mode: "write" },
    ],
  },
  cellSize: 140,
});

const b = block.create(target, {
  spec: {
    cells: [
      { kind: "free", expected: "学校", mode: "write", span: 3 },
    ],
  },
  cellSize: 140,
});

const b = block.create(target, {
  spec: {
    cells: [
      { kind: "guided", char: "学", mode: "write" },
      { kind: "guided", char: "校", mode: "write" },
    ],
    annotations: [
      { cellRange: [0, 1], expected: "がっこう", mode: "write" },
    ],
  },
  cellSize: 140,
});

const b = block.create(target, {
  spec: {
    cells: [
      { kind: "guided", char: "学", mode: "write" },
      { kind: "guided", char: "校", mode: "write" },
    ],
  },
  cellSize: 140,
  correction: "per-block",
});

BlockResult

b.result() returns a BlockResult. Each cell exposes its CharResult[] (one entry per expected character); each annotation does the same. mode: "show" entries are display-only and always come back complete: true with an empty perStroke.

interface BlockResult {
  id?: string;        // echoed from PageBlockEntry.id when generated by Page
  complete: boolean;  // all writable chars completed
  matched: boolean;   // no observed failures
  cells: BlockCellResult[];
  annotations: BlockAnnotationResult[];
}

interface BlockCellResult {
  kind: "guided" | "free" | "blank";
  chars: CharResult[]; // guided=1, free=expected length, blank=0
}

interface BlockAnnotationResult {
  chars: CharResult[]; // one entry per expected character
}

page

page lays out multiple blocks on a vertical-rl grid (Japanese practice-sheet style). Blocks flow column-by-column. A block that crosses a column boundary is split per-cell automatically, even when it carries a furigana annotation, and strokes drawn across split surfaces are checked from a shared buffer.

import { page } from "@k1low/kakitori/page";

const target = document.getElementById("page-host")!;
const p = page.create(target, {
  writingMode: "vertical-rl",
  columns: 5,
  cellsPerColumn: 8,
  cellSize: 96,
  blocks: [
    {
      id: "q1",
      spec: {
        cells: [
          { kind: "guided", char: "学", mode: "write" },
          { kind: "guided", char: "校", mode: "write" },
        ],
        annotations: [
          { cellRange: [0, 1], expected: "がっこう", mode: "show" },
        ],
      },
    },
    { id: "q2", spec: { cells: [{ kind: "guided", char: "山", mode: "write" }] } },
    // ...
  ],
  onBlockComplete: (blockIndex, result) => { /* one problem done */ },
  onPageComplete: (result) => { /* whole sheet done */ },
});

Live example. Notice block q9 (図書館 + としょかん) crossing a column boundary, and block q10 rendering as a 5-cell visual blank.

PageResult

p.result() returns a PageResult. Each block carries a BlockResult directly, with the original id echoed back so a caller can correlate results against the input blocks.

interface PageResult {
  complete: boolean;
  matched: boolean;
  blocks: BlockResult[]; // each entry mirrors the order of opts.blocks
}

// Flatten + filter all CharResult leaves across a result tree.
import { collectCharResults } from "@k1low/kakitori";

const scored = collectCharResults(p.result(), {
  sources: ["guided"],
  modes: ["write"],
  completedOnly: true,
});

sizing

Three values control how a cell looks on screen and what comes back as data. They live in deliberately different units so callers can change one without dragging the others along.

• size (display px): the cell side length. The character is scaled to fit.
• drawingWidth (display px): the pen thickness. Size-independent, so a 6px pen draws as 6px ink in a 80px cell or in a 280px cell.
• result.points (internal coords): always returned in hanzi-writer's 1024-scale system (Y-up; the character region occupies x ∈ [0, 1024], y ∈ [-124, 900]). The numbers do not depend on size, so a saved stroke replays into any cell or layers over the reference paths from @k1low/hanzi-writer-data-jp without rescaling.

// All three cells use the same drawingWidth, expressed in display px.
const c = char.create("永");
c.mount(target, { size: 80,  drawingWidth: 6, /* ...same for 160 and 280 */ });
c.start();

draw a stroke to populate this panel.

// The captured points come back in the same numeric range regardless of cell size.
char.create("一").mount(target, {
  size: 200,           // display px
  retainStrokes: true,
  showOutline: false,
  showCharacter: false,
  correction: "per-char",
  maxRetries: 0,
  onCorrectStroke: ({ points }) => console.log(points), // {x, y, t} in internal coords
  onMistake:       ({ points }) => console.log(points),
}).start();

leniency

leniency tunes the stroke matcher's tolerance. The default (1.0) is hanzi-writer's baseline; lower values are stricter (sloppy strokes get rejected), higher values are more permissive. The same option exists at char.create, block.create (block-wide), and page.create (page-wide); per-cell overrides.leniency wins over block/page-wide defaults.

const c = char.create("学", { leniency: 1.0 });
c.mount(target, {
  size: 240,
  retainStrokes: true,
  showAcceptedStroke: false,
});
c.start();

restore

Because CharResult.perStroke[].points stays in the 1024-scale internal coordinate system, a saved CharResult can be redrawn anywhere later via char.restore. No Char instance, no matcher, no quiz lifecycle. Just data going back into pixels.

// `result` was captured from a prior writing session
// (e.g. via onComplete / Char.result()). char.restore renders it back
// without needing a Char instance or any matcher state.
char.restore(target, result, { size: 160 });

block.restore(target, blockResult, {
  cellSize: 60,
});

page.restore(target, pageResult, {
  columns: 3,
  cellsPerColumn: 3,
  cellSize: 100,
});