DEV Community: ruixuan jiang

Your Agent's Free-Text Output Is an API You Never Designed

ruixuan jiang — Fri, 25 Sep 2026 02:40:58 +0000

Most agent demos fail in the same place, and it is not the model.

It is the boundary where the model's output leaves the model and enters your program. Up to that point it is a string. Strings do not have a schema.

So you end up with code like this:

const reply = await llm.complete(prompt);

// please work
if (reply.toLowerCase().includes("approve")) {
  await merge();
} else {
  await requestChanges();
}

This works until the model writes "I would not approve this yet" and your substring check matches approve. Now a change that should have been blocked got merged.

The hidden interface

Any time you parse meaning out of generated text, you have declared an API. You just did not write it down.

That interface has properties you probably did not intend:

It is not versioned. Change the prompt and the contract silently changes.
It is not validated. There is no error when the shape is wrong, only a wrong branch.
It cannot be logged as a decision. You can log a paragraph, but you cannot log "the model chose X from a set of three."

The fix is not a better prompt. Prompt engineering narrows the failure rate; it does not remove the parser.

Ask for a decision, not a paragraph

An agent step usually needs two different outputs, and they should not be the same output:

A description for humans — what it noticed, what surprised it, what it is unsure about.
A decision for the program — a value the host can validate and branch on.

The decision should come from a closed set that your code already understands:

type ReviewDecision = {
  status: "pass" | "review" | "fail";
  confidence: "low" | "medium" | "high";
  findings: Array<{ file: string; note: string; severity: "info" | "warn" | "block" }>;
};

Now the failure modes separate cleanly:

What broke	Where to look
`status` came back as `"probably fine"`	Contract violation — reject before acting
`status` was valid but wrong	Judgment problem — improve evidence or prompt
`status` was right but the wrong branch ran	Implementation bug in your own code

Without the typed boundary, all three look like "the AI did something weird," and you have no way to tell them apart.

Validate before you act

The important part is not the schema. It is that the schema is checked before anything changes.

const ALLOWED = new Set(["pass", "review", "fail"]);

function assertDecision(value: unknown): ReviewDecision {
  if (typeof value !== "object" || value === null) {
    throw new Error("Decision is not an object");
  }
  const d = value as Record<string, unknown>;
  if (typeof d.status !== "string" || !ALLOWED.has(d.status)) {
    throw new Error(`Illegal status: ${String(d.status)}`);
  }
  if (!Array.isArray(d.findings)) {
    throw new Error("findings must be an array");
  }
  return {
    status: d.status as ReviewDecision["status"],
    confidence: d.confidence === "high" || d.confidence === "medium" ? d.confidence : "low",
    findings: d.findings as ReviewDecision["findings"],
  };
}

A thrown error is a feature here. It is a loud, recoverable failure that happens before a merge, a payment, or a deploy — instead of a silent wrong branch.

This is the pattern behind structured judgment tools, like the Choice and Score interfaces exposed over MCP in this case: the model supplies the judgment, the typing layer fixes its shape, and the calling program gets a value it can compare or gate on instead of prose it has to interpret.

Keep the evidence with the decision

A typed result is not automatically trustworthy. status: "pass" with no support is just a shorter guess.

So the decision record should carry:

the inputs the model actually saw (or a hash and a reference)
the allowed output space
the chosen value
the evidence behind it
an identifier and a timestamp

That gives you a replayable record. When a bad decision ships, you can tell whether the right evidence was missing, the wrong rule was applied, or the validation layer was too loose.

What this does not fix

Typing the output does not:

make the model correct
make a subjective label objective
replace tests, permissions, review, or rollback
turn an experiment into a production control

It solves one narrow problem: the host no longer has to guess a control signal out of decorative prose.

That is worth a lot. It is much easier to reason about a system where you can see the allowed choices, the selected choice, the evidence, and the resulting action.

A short checklist

Before an agent step is allowed to change state, I want answers to these:

What is the model allowed to decide?
What is the program allowed to execute?
Are those represented separately?
Can an invalid decision be rejected before any action runs?
Is the evidence visible without reading the whole transcript?
Is there a pause or rollback path when confidence is low?

If those are all "no," the demo can still look impressive. It is just not yet an instrument.

Disclosure: I maintain JevCases, an independent index of Jev use cases and experiments. It is not affiliated with TypeSafe.

A No-Repeat Random Draw Looks Trivial Until Round 70

ruixuan jiang — Fri, 25 Sep 2026 02:40:12 +0000

Drawing numbers without repeats sounds like a beginner exercise. It is also a place where a lot of shipped code has a real defect.

The version most people write

function drawNaive(called: number[]): number {
  let n: number;
  do {
    n = Math.floor(Math.random() * 75) + 1;
  } while (called.includes(n));
  return n;
}

This is rejection sampling. It is correct in the sense that it never returns a duplicate, and it is wrong in two ways that matter.

It degrades as the deck empties. Early on, almost every draw succeeds on the first try. At round 70, only 5 numbers remain, so the expected number of loop iterations per draw is 15. Near the very end it gets worse, and the loop has no upper bound.

It couples randomness to the array. called.includes(n) is O(n), inside a loop that can run an unbounded number of times. The complexity is embarrassing for a game you might run on a projector laptop.

Sample from what is left

The fix is to stop guessing and pick directly from the remaining set:

export const drawNextNumber = (
  called: readonly number[],
  random: () => number = Math.random,
): number | null => {
  const used = new Set(called);
  const remaining = Array.from({ length: 75 }, (_, i) => i + 1)
    .filter((n) => !used.has(n));

  if (remaining.length === 0) return null;

  const index = Math.min(
    Math.floor(random() * remaining.length),
    remaining.length - 1,
  );
  return remaining[index] ?? null;
};

Three things changed:

Set lookup instead of Array.includes inside a loop.
Exactly one random call per draw, always. Cost is O(75) worst case, with no variance.
null when the deck is exhausted, instead of looping forever.

The Math.min(..., remaining.length - 1) clamp is defensive. Math.random() returns values in [0, 1), so the clamp should never fire — but if someone passes a custom random that returns exactly 1, an unclamped version reads past the end of the array and returns undefined. Cheap insurance.

Make the RNG injectable

That random parameter is the highest-value line in the function.

// deterministic in tests
const seq = [0.1, 0.9, 0.5];
let i = 0;
const fakeRandom = () => seq[i++ % seq.length];

expect(drawNextNumber([], fakeRandom)).toBe(8);

Without an injectable source, testing a random draw means either asserting nothing useful or mocking the global Math.random. With it, the shuffle and draw paths become ordinary deterministic functions you can unit test.

The same trick applies to card generation, which needs a real shuffle:

const shuffledRange = (start: number, end: number, random: () => number) => {
  const values = Array.from({ length: end - start + 1 }, (_, i) => start + i);
  for (let i = values.length - 1; i > 0; i -= 1) {
    const j = Math.floor(random() * (i + 1));
    [values[i], values[j]] = [values[j]!, values[i]!];
  }
  return values;
};

A Fisher–Yates shuffle per B-I-N-G-O column, then sort each column ascending so the card reads correctly, then drop the center for the free space.

Do not stop at "unique"

For a batch of cards, "unique" is not enough on its own — you also need the batch to terminate.

const cards: BingoCard[] = [];
const signatures = new Set<string>();
let attempts = 0;

while (cards.length < count && attempts < count * 100) {
  attempts += 1;
  const card = generateBingoCard(random);
  const signature = card.flat().join("-");
  if (!signatures.has(signature)) {
    signatures.add(signature);
    cards.push(card);
  }
}

if (cards.length !== count) {
  throw new Error("Unable to create a unique card batch.");
}

Throwing is the right behavior. A silently short batch is worse than a loud failure: the host prints 20 cards for 24 players and finds out at the door.

Persisted state is untrusted input

The draw is the easy part. The bug that actually bites in production is what happens after you reload the tab.

If game state lives in localStorage, then anything on the origin can write to it, and a user can edit it by hand. Treat the read as a parse of external data:

const called = Array.isArray(record.called)
  ? record.called.filter(
      (n, i, all): n is number =>
        Number.isInteger(n) && n >= 1 && n <= 75 && all.indexOf(n) === i,
    )
  : [];

That single expression does four jobs: type check, integer check, range check, and deduplication. The dedupe matters because a duplicated entry in called corrupts every subsequent "is this used" question.

The same function reconciles the derived status rather than trusting the stored one (abbreviated here; the real version also preserves a running state when the caller explicitly asks for it):

const status =
  called.length === 75 || (called.length > 0 && record.status === "complete")
    ? "complete"
    : "paused";

If all 75 numbers are called, the game is over regardless of what the stored flag says. Derived state should be recomputed, not believed.

Syncing a host console with a display

If you open a second window for the projector, BroadcastChannel is the least fussy transport:

const channel = new BroadcastChannel("bingo-caller-state-v1");
channel.postMessage(state);

Two details worth copying:

Namespace the storage keys. If you ship more than one locale, bingo-caller-game-v1:de keeps a German host console from picking up an English game.
Keep the keys stable for the default locale. The default path keeps its original key so existing saved games and already-open display windows keep working after a deploy.

The summary

The pattern generalizes past bingo: whenever you have a finite pool, a draw without replacement, and persisted state:

Sample from the remaining pool, not by retrying.
Inject the randomness source.
Bound every retry loop and fail loudly.
Validate and deduplicate persisted state on every read.
Recompute derived values instead of trusting stored ones.

I used this implementation while building Bingo Caller Online, a browser-based caller supporting 75-, 90-, 80-, and 30-ball games. The draw logic and the state sanitizer above are close to what actually ships.

Disclosure: Bingo Caller Online is my own project.

Normalize Units at the Boundary, or Ship a 12x Bug

ruixuan jiang — Fri, 25 Sep 2026 02:39:54 +0000

A user types 3 into a depth field. The label says inches. Your formula assumes feet.

You just shipped a 12x error, and nothing in the type system noticed, because both values are number.

I hit this class of bug repeatedly while building material calculators, so I stopped trusting unit labels and made the conversion a type-level concern instead.

One canonical unit

Pick a single internal unit and convert everything at the edge. For a US-customary-heavy calculator, feet is the natural choice:

export const units = {
  in: 1 / 12,
  ft: 1,
  yd: 3,
  cm: 1 / 30.48,
  m: 1 / 0.3048,
};

export type Unit = keyof typeof units;

The values are conversion factors into the canonical unit. That is the whole trick: downstream code never sees a unit again, so there is exactly one place where a unit can be wrong — and it is a table of five constants you can eyeball.

Notice this also gives you a free Unit type. An invalid unit string is now a type error at the call site instead of a silent NaN at runtime.

Validate the unit, not just the number

The converter should reject an unknown unit and reject a non-positive dimension, and the error should name the field:

const dim = (value: string, unit: Unit, label: string) => {
  if (!(unit in units)) throw new Error(`${prefix}: choose a valid unit.`);
  return number(value, `${prefix} ${label}`) * units[unit];
};

The unit in units check looks redundant when the parameter is typed Unit — but the state being validated comes back from persisted, parsed JSON, where the type annotation is a claim rather than a guarantee.

export function number(value: string, label: string, zero = false): number {
  const n = Number(value);
  if (!value.trim() || !Number.isFinite(n) || (zero ? n < 0 : n <= 0)) {
    throw new Error(
      `${label}: enter a ${zero ? "non-negative" : "positive"} number.`,
    );
  }
  return n;
}

Two things worth stealing here.

!value.trim() catches the empty string. Number("") is 0, which passes Number.isFinite and then silently becomes a zero dimension. An empty field and a genuine zero are different situations, and the form should say so.

The zero flag makes the semantics explicit. A waste allowance may legitimately be 0. A length may not. Encoding that difference in one boolean is clearer than two near-identical validators.

Watch the other quantities

Not every numeric field is a measurement. A count of beds, slabs, or retaining walls is an integer:

const q = number(a.quantity, `${prefix} quantity`);
if (!Number.isSafeInteger(q)) {
  throw new Error(`${prefix} quantity: enter a whole number.`);
}

Number.isSafeInteger also rejects NaN, Infinity, and values past 2^53 — all of which would produce nonsense in a total.

Shapes without a shape library

Once units are normalized, the geometry is short enough to keep inline. Each branch differs by one or two lines:

const surface =
  a.shape === "circle"
    ? Math.PI * (l / 2) ** 2
    : l *
      dim(a.width, a.widthUnit, a.shape === "triangle" ? "perpendicular height" : "width") *
      (a.shape === "triangle" ? 0.5 : 1);

const volume = surface * d * q;

The label switches as the meaning of the input changes — for a circle, length is the diameter; for a triangle, width is the perpendicular height. Reusing the same three fields with different semantics is fine as long as the error messages and the UI labels change with them. Silently keeping the label "width" on a triangle is how users enter the slant height.

The guard after the guard

Floating point and unit conversion can still produce something unusable:

if (!Number.isFinite(volume) || volume <= 0) {
  throw new Error(`${prefix}: dimensions are outside the supported range.`);
}

This is not paranoia. 1/30.48 multiplied through several dimensions can land on a denormal or overflow for absurd inputs. A final sanity check costs one comparison.

Why 324 shows up in mulch formulas

If you have ever seen this formula and wondered about the constant:

length(ft) × width(ft) × depth(in) ÷ 324 = cubic yards

It is not arbitrary. It is two conversions folded together:

inches to feet: divide by 12
cubic feet to cubic yards: divide by 27

So 12 × 27 = 324. Once you normalize units at the boundary, you never write 324 again — the constant disappears into the unit table, which is exactly where it belongs.

Validation as a first-class output

The pattern that made these calculators maintainable is that invalid input produces a labeled error, not a zero and not a NaN:

Area 2 depth: enter a positive number.
Area 1 quantity: enter a whole number.

That string is useful in the UI, useful in a test assertion, and useful when someone reports a bug six months later. A function that returns 0 on bad input is a function that will be debugged by reading it line by line.

The checklist

One canonical unit. Convert once, at the edge.
Derive a Unit type from the conversion table.
Reject empty strings explicitly — do not let "" become 0.
Distinguish "may be zero" from "must be positive".
Use Number.isSafeInteger for counts.
Relabel a field when its meaning changes (diameter, perpendicular height).
Sanity-check the final result, not just the inputs.
Throw errors that name the field.

I ended up extracting this into Cubic Yard Tools, a set of material calculators for landscaping and construction that accepts both US customary and metric input. The conversion table and the validator above are the parts I would copy first into any new calculator.

Disclosure: Cubic Yard Tools is my own project. Estimates there are planning aids, not engineering approvals.

Small Calculator, Three Bugs: Input Parsing, Unit Drift, and Stale Results

ruixuan jiang — Fri, 25 Sep 2026 02:39:16 +0000

A calculator with two inputs and one output is the "hello world" of interactive UI. It is also a small minefield.

These are three defects I hit while building bidirectional CPM ↔ CPC conversion, and the fixes are portable to any numeric form.

Bug 1: percentage drift

The formula is simple once you see it. Cost per thousand impressions, divided by clicks per thousand impressions, gives cost per click.

The bug is in the middle term. CTR is stored as a percentage — 2 means 2%. So how many clicks happen per 1,000 impressions?

// wrong: treats 2 as 2 clicks per 1000
const clicksPerThousand = parsedCtr;

// wrong: treats 2 as 2000 clicks per 1000
const clicksPerThousand = parsedCtr * 1000;

// right
const clicksPerThousand = parsedCtr * 10;

Why 10? Because CTR is per hundred impressions (that is what percent means) and CPM is per thousand:

clicks per 1000 = 1000 × (ctr / 100) = ctr × 10

Writing the derivation as a comment next to the constant is worth more than a clever variable name. Off-by-1000 errors in ad math are almost always this line.

Once you have it, both directions are trivial and symmetric:

const convertedValue =
  mode === "cpm-to-cpc"
    ? parsedCost / clicksPerThousand
    : parsedCost * clicksPerThousand;

One division, one multiplication, same intermediate. There is no reason to write two separate formulas and let them drift apart.

Bug 2: validation that lets an empty field through

const parsedCost = Number(cost);
const parsedCtr = Number(ctr);

Number("") is 0. That fails the <= 0 check here, so it happens to be safe — but that is luck, not design. The moment you add an optional field with a legitimate zero (0% CTR as a valid "no clicks" input, or a 0 budget floor), the empty string slides straight through as a real zero.

Be explicit about what is allowed:

if (
  !Number.isFinite(parsedCost) ||
  parsedCost <= 0 ||
  !Number.isFinite(parsedCtr) ||
  parsedCtr <= 0 ||
  parsedCtr > 100
) {
  setResult(null);
  setMessage(
    "Enter a cost above zero and a CTR greater than 0% and no more than 100%.",
  );
  return;
}

Three things this gets right:

Number.isFinite catches NaN and Infinity. Number("abc") is NaN, and NaN > 0 is false, so it would be caught — but Number("1e999") is Infinity, which passes > 0. Explicit finiteness checks stop the whole class.
The upper bound is enforced. A CTR above 100% is impossible under a one-click-per-impression model. If your data source allows multi-count attribution, that assumption changes, and the validation should change with it — but silently accepting 500 as a CTR is worse than rejecting it.
The result is cleared on failure. This is the part people forget, and it is actually Bug 3.

Bug 3: stale results after an invalid submit

Consider the sequence:

User enters valid values. Result renders: $0.50.
User edits the cost field, leaving it empty.
User submits.
Validation fails, an error message appears — and the old $0.50 is still on screen.

The message says the input is bad. The screen still shows a number. Users read the number.

if (!valid) {
  setResult(null);   // <- the important line
  setMessage("...");
  return;
}

Clearing the result is not cosmetic. It keeps the error state and the displayed state consistent: either there is a valid result, or there is an explanation. Never both.

The same rule applies to switching modes:

const changeMode = (nextMode: Mode) => {
  setMode(nextMode);
  setCost("");
  setCtr("");
  setResult(null);
  setMessage("");
};

If you flip from CPM → CPC to CPC → CPM and leave the old result on screen, you have displayed an output computed under the other mode's formula, next to inputs that no longer mean the same thing.

The formatting is part of the correctness

Formatting a CPC with Intl.NumberFormat and the default two fraction digits throws away the value users need:

const money = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  minimumFractionDigits: 2,
  maximumFractionDigits: 4,
});

const number = new Intl.NumberFormat("en-US", {
  maximumFractionDigits: 2,
});

Two formatters, deliberately. Money gets four fraction digits because low CPC values are legitimately sub-cent: $0.0012 displayed as $0.00 is not a rounding choice, it is a wrong answer. Counts and percentages get two digits, because "1,234.5678 impressions" is noise.

Also note the formatters are created once, at module scope. Constructing an Intl.NumberFormat is not free, and doing it inside a render body on every keystroke is a measurable waste in a form that re-renders on every input change.

Every number needs a label

The most common defect in calculators is not arithmetic. It is an unlabeled number.

0.5 could be a CPC in dollars, a CTR in percent, or a conversion rate. When a user screenshots a result, the label has to travel with the value. Carry the input alongside the output in the result object so the UI can render "at $10 CPM and 2% CTR" beside the number:

type Result = {
  convertedValue: number;
  clicksPerThousand: number;
  inputValue: number;
};

setResult({ convertedValue, clicksPerThousand, inputValue: parsedCost });

This also makes the result testable as data rather than as rendered markup.

The portable checklist

Write the unit derivation next to the constant, not in your head.
Make inverse operations share one intermediate value.
Check Number.isFinite explicitly; do not rely on comparison operators to catch NaN.
Enforce upper bounds that the domain implies, and document the assumption behind the bound.
Clear stale output whenever input becomes invalid or the mode changes.
Use Intl.NumberFormat with enough fraction digits for the smallest meaningful value.
Build formatters once, outside the render path.
Never display a number without its unit and its inputs.

These three fixes came out of Get CPM Calculator, a set of advertising calculators for CPM, CPC, impressions, and break-even ROAS. The arithmetic is the easy part; the state handling is what determines whether people trust the number on the screen.

Disclosure: Get CPM Calculator is my own project. Results are calculations from the values you enter, not platform benchmarks.

What React Flow Doesn't Do For You: Building a Diagram Editor With Domain Rules

ruixuan jiang — Fri, 25 Sep 2026 02:39:03 +0000

I built a diagram editor for genograms. If you have not run into the term: a genogram is a diagram of a family that records more than descent. It uses standardized shapes for people and a set of line conventions for relationships, including emotional ones like closeness, distance, and conflict.

The obvious library choice was React Flow (@xyflow/react). It is a good fit and I would choose it again. But it is worth being precise about what it gives you, because the gap between "React Flow demo" and "editor a professional can use" is where all the work lives.

What you get out of the box

A canvas with pan, zoom, and viewport controls
A node/edge data model with React components for each
Selection, dragging, and connection handles
A store you can subscribe to

That is a lot. It is also entirely structural. React Flow knows nothing about your domain.

What it does not know

Here is the list I had to build on top:

Node rendering rules. A genogram person symbol is not a rounded rectangle. It encodes gender (square or circle), and inside it may sit a marker for a health status such as active, in recovery, or suspected. Custom node components are the answer, rendered as SVG inside the node wrapper.

Edge routing rules. Family relationships need their own geometry. Partners connect with a horizontal line. Children descend from a midpoint on that line. That midpoint changes when partners are added or removed, which means edge geometry is a function of the surrounding nodes, not of the two endpoints.

// conceptually: edges are derived, not stored per pair
const familyEdges = buildFamilyEdges(people, partnerships);

Relationship lines beyond descent. A genogram distinguishes emotional relationships from structural ones, and the conventions differ: a triple line for close, a zigzag for conflict, a dotted line for distant. Each is a different edge component with different path geometry and a different legend entry.

That means the domain model has to classify edges before the renderer ever sees them. React Flow will happily draw a custom edge; deciding which edge type a pair of people should have is your problem.

The legend. Any editor that introduces non-obvious notation needs a legend on the canvas. Users cannot be expected to remember that a dashed line means distant. This is a domain requirement with no library support at all.

Persistence is a separate design problem

Two storage modes ended up coexisting:

Local projects use IndexedDB, which immediately raises a concurrency question: what happens when two saves overlap? A debounced autosave, a manual save, and an export path can all write to the same record in the same second.

The fix is to serialize the writes rather than hoping they do not collide:

let operationQueue: Promise<unknown> = Promise.resolve();

function enqueue<T>(operation: () => Promise<T>): Promise<T> {
  const next = operationQueue.then(operation, operation);
  operationQueue = next.then(() => undefined, () => undefined);
  return next;
}

Note the error handling: operationQueue is advanced with handlers that swallow both fulfillment and rejection, so one failed write does not poison every subsequent operation in the chain. The caller still gets the real rejection via next.

The autosave itself is debounced rather than interval-driven — 700 ms after the last change, not every 700 ms. Debouncing means an idle editor writes nothing and a burst of edits produces one write instead of thirty.

Cloud projects are a different code path with the same UI. Keeping the load/save surface identical (loadProject / saveProject regardless of backing store) is what prevents the editor component from filling up with if (isCloud) branches.

Validate what you read, always

Both storage paths return data that arrived from outside the component: IndexedDB, a file the user picked, or an API response. None of them are guaranteed to match the current schema.

export function loadLocalProject(projectKey = LOCAL_PROJECT_KEY): Promise<Project | null> {
  return enqueue(async () => {
    const project = await (await getDatabase()).get(LOCAL_PROJECT_STORE_NAME, projectKey);
    return project ? validateProject(project) : null;
  });
}

Two decisions are embedded in that short function:

Validate on read, not on write. A project saved by an older version of the app will still be in IndexedDB after you ship a schema change. Validating on read lets you migrate or reject it at the only moment you can still do something sensible.
Return null rather than throwing. A missing or invalid project is an expected state — it means "start fresh" — not an exception. Reserve throwing for corrupt-file cases where the user needs to know their data could not be recovered.

Export is its own feature

Exporting a diagram to an image is not canvas.toDataURL(). Your nodes are DOM elements, styled with CSS, possibly with fonts and inline SVG.

html-to-image handles the DOM-to-PNG conversion, but there is still real work:

computing the bounding box across all nodes, not just the visible viewport
deciding a scale factor so the output is legible rather than 1:1 screen pixels
generating a filename
deciding what to do when a node falls outside the computed bounds

If your diagram has a "fit to view" interaction, the export path usually wants the same geometry logic. Sharing that function between the "fit" button and the export saves you from two subtly different definitions of "the whole diagram."

The parts that took the longest

Ranked by how long they actually took, not by how interesting they are:

Edge geometry that responds to node movement. Correct, legible lines between related nodes.
Round-trip fidelity between storage, the editor model, and the file format. Every added field is a migration concern.
Legend and notation consistency. Domain accuracy, not engineering.
Undo/redo and selection semantics. Most of it is state design, not rendering. Snapshotting the project on each mutation and capping the history at 100 entries is the easy half; making sure a drag does not push 60 entries into the history is the hard half.
Actually wiring React Flow up. The least of the problems.

That ordering is the point. React Flow was the fastest part of the project. What took time was deciding what the diagram means and keeping that meaning consistent across the canvas, the store, the export, and the saved file.

If you are starting a similar editor

Use React Flow. It is not the bottleneck.
Write your domain model first, then derive edges from it rather than storing them independently.
Treat every read from storage or the network as untrusted input and validate on read.
Serialize writes if more than one code path can save.
Plan the legend and notation before the visual polish.
Share geometry helpers between "fit to view" and "export".

This is the architecture behind MyGenogramMaker, a browser-based genogram editor with standard family symbols, relationship lines, and editable templates. Projects can be kept locally in the browser or in a cloud project, and the editor runs without requiring an account to start.

Disclosure: MyGenogramMaker is my own project. It is a diagramming tool — not a diagnostic, clinical, or compliance service.