CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

table-grid-commands

Check that every table insert, remove, merge and split command, and Enter, Backspace, Delete, paste and delete inside and across cells, leaves a table whose cells cover every slot exactly once and puts each cell's content where the Table section of docs/editor-behavior/markdown-editing-spec.md says, on every span layout of up to three rows and three columns. Use before and after changing packages/platejs/src/features/table or another file in its coverage record, when the table-grid step of pnpm check fails, or when fixing a table structure or cell-editing bug a test or a tester found.

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Table grid commands

Handle $ARGUMENTS. check, or no argument, runs the gate. deep runs --all and compares its failures with Findings. lower runs --lower after a fix removes a known finding. case <identity> runs --case=<identity> to print one case's full detail. update brings the verification in line with changed code, as Coverage record says.

The property. A user runs one table command on a table whose cells span rows and columns in any layout. Afterward every slot of the table belongs to exactly one cell, and each cell's content sits where the spec's Table section puts it: an inserted row or column holds only new empty cells, a removed row or column takes only its own cells and shortens the spans that cross it, a merge keeps every merged cell's content in row-major order in one cell, a split leaves the content in the first slot, Enter, Backspace, Delete and paste stay inside their cell, and deleting a cell range or a picked cell clears those cells and keeps the table's shape.

The harm. A broken grid draws cells in the wrong columns or drops them, and content that moves to another cell or disappears is lost work. Table took ten fixes in the two months before 2026-10-24, such as a9919f48f9, and the two Plite fixes d13c7b8765 and 8e107e7413 since then kept cells whole under Enter, paste and range deletes. Tests found each one a case at a time, and grid.spec.ts and mutation.spec.ts in packages/platejs/src/features/table/lib/internal sample about a hundred span layouts.

What it checks

packages/platejs/scripts/table-grid-commands.ts runs the real BaseTablePlugin in a headless editor from platejs, with allowCellSpanEditing on. It checks the TypeScript code itself, not a model of it.

  1. Layouts. Every way to cut a grid of up to --rows rows and --cols columns into rectangles, 411 layouts at the gate. Each cell holds one paragraph with its own letter, a to i in reading order, so content that moves or doubles shows.
  2. Commands. Through editor.plugin(BaseTablePlugin).update: insertRow and insertColumn before and after a cell, removeRow and removeColumn at a cell and over a cell range, split at every spanning cell, and merge over a cell range. Through editorCommands: Enter at both ends of a cell, Backspace at its start, Delete at its end, a paste of an open two-paragraph slice P¶Q at its end, deleteFragment over a text range from one cell to another, and deleteFragment over one cell or a cell range picked as nodes with selection.setNodes. A cell range is the smallest rectangle that holds both cells and that no cell crosses.
  3. Gate and --all. --all runs every command at every cell and every pair of cells. The gate runs each insertion line once, each removed row or column range once, the pair of corner cells of each rectangle no cell crosses once, a range removal only where the rectangle spans the whole table across, and the cell edits and picked deletes only on layouts smaller than three by three.
  4. The oracle. The script lays the stored table out itself and never calls the plugin's compileTableGrid. Each row places each cell at its first free slot, a span must be a whole number of at least 1, a row span must not run past the table, and every slot must hold exactly one cell. It then compares that layout with the law of the command:
    • table-grid: a table whose cells do not cover every slot exactly once, a span that is not a whole number, a row span past the table, a table with no cells, or two tables.
    • table-content: a table that differs from what the law gives. An insertion passes when taking the new line out gives the original table back and every slot on that line belongs to a new empty cell inside the line or to a cell that crosses it. A new cell may copy a neighbor row's column spans, because the spec asks only for empty cells. Every other command must give one exact table: no table when it removes every row or column, and the unchanged table when the plugin refuses a range removal that does not span the whole table.
    • table-throws: a command that throws.
  5. A command that returns false counts in the summary's refused, and its table must still match the law.
  6. It compares the findings with packages/platejs/scripts/table-grid-commands-baseline.json through tooling/scripts/finding-baseline.mjs. Every finding is filed under packages/platejs/src/features/table/lib. An identity names the layout and the command, never the result.

Run it

Run every command from the repository root.

  • pnpm check:table-grid checks the gate: 13,590 cases on 411 layouts. It used 231 CPU-seconds and took 93 s at a load average of 110; on a quiet machine with 16 workers that CPU time predicts about 15 s. It prints one JSON summary line, then each finding the baseline does not list. pnpm check table-grid runs the same step through the check runner, and pnpm check --affected runs it for a change under packages/platejs/src/ or packages/plitejs/src/, to the script, packages/plitejs/scripts/check-harness.ts, config/plite-source-aliases.ts or tooling/scripts/finding-baseline.mjs.
  • --all runs every command at every cell and pair, 48,206 cases, which took 359 s at a load average near 100. --rows and --cols raise the layout bound. A bound other than the gate's, --all or --case skips the baseline and exits 1 on any failure.
  • --case='<identity or part of one>' runs only the cases whose identity contains it and prints each failure's stack, such as '--case=a b | c d :: pick a delete'.
  • --jobs=<n> sets the number of worker processes, the machine's cores up to 16 by default.
  • Exit 0 is a pass and exit 1 a finding. Exit 2 is a bad flag or a crashed worker. At the gate the run also fails when it compares other than 13,590 cases, the GATE_CASES constant, so a change that drops commands cannot shrink the gate while the baseline still matches. Update the constant only with the reason the count moved.
  • After a fix removes a known finding, the gate fails until you run pnpm check:table-grid --lower. The baseline never grows. --init seeds only a rule the baseline lacks, and --lower and --init write nothing when the case count misses GATE_CASES.

Read a failure

A finding prints its rule, identity and detail. A table reads row by row, rows split by |, each cell its paragraphs joined by +, ∅ for an empty paragraph, and :r2 or :c2 for its spans:

table-content a b | c d :: pick a delete
  gives b ∅ | c d, not ∅ b | c d

table-grid a :: pick a delete
  the table has no cells

Both are known findings. In the first, the picked cell a is removed, b moves to the first column and a new empty cell fills the end of the row. Run --case on the identity for the stack.

Tell a real bug from a modeling error before you change code:

  • Real bug. A user can run the command on that layout, and the table breaks or a cell's content lands in another place than the spec's Table section says. Fix the table plugin or the Plite command it runs, then run --lower.
  • Modeling error. The law asks for more than the spec says, as when an insertion law once required one-slot cells and the plugin copies the neighbor row's spans. Fix the script with the reason.
  • Intended change. A change to what a command does changes the law too. Change the law and the spec's Table section together. Never weaken a law or add a baseline entry to get green.

Findings

The gate finds 210, all from deleting one cell picked as a node, t_3e344661: 202 table-content and 8 table-grid. When the picked cell shares a row with another cell, deleteFragment removes the cell instead of clearing it, and the row's later cells move left. The table's repair then fills the row's end with a new empty cell, or the table shrinks by a column, as in a b c :: pick a delete, which gives b c. On a table of one cell, whatever its spans, it leaves rows with no cells, the 8 table-grid entries. A picked cell alone in its row, as in a | b :: pick a delete, is cleared as the spec says, and so is every picked cell range.

--all finds 1,526, every one the same class.

What a pass proves

Bugs planted on this tree showed where the gate holds:

  • A mutant where removeRow in packages/platejs/src/features/table/lib/internal/mutation.ts keeps the row span of a cell that crosses the removed rows gives 86 more table-content findings, all removeRow, such as a b c:r2 | d e | f g h :: removeRow d giving a b c:r2 ∅ | f g h. The table's repair fixes the span that runs past the table, so the break shows as content in the wrong place, not as table-grid.
  • t_3e344661's own case, a one-cell table whose picked cell is deleted, fails as table-grid with the table has no cells. The script reports it only because its own layout counts a table with no cells as broken; the plugin's compileTableGrid reports no problem for it.

Coverage record

Synced at test(platejs): check that every table command keeps a valid grid on every small span layout. The verification describes these files as they stand there:

FileWhat the check exercises
packages/platejs/src/features/table/lib/BaseTablePlugin.tsthe update methods, the cell selection each one reads, merge, split and the table's repair after a change
packages/platejs/src/features/table/lib/internal/mutation.tsthe plans for inserting and removing rows and columns
packages/platejs/src/features/table/lib/internal/grid.tsthe plugin's own grid, which the commands read
packages/platejs/src/features/table/lib/internal/selection.tsthe rectangle a cell range selects
packages/plitejs/src/core/editor-commands.tsdeleteFragment, delete, insertBreak and replaceSlice
packages/plitejs/src/core/node-selection.tsdeleting cells picked as nodes
packages/plitejs/src/transforms-text/delete-text-grid.tsdeleting a text range across cells
packages/plitejs/scripts/check-harness.tsthe flags, workers and gate the check shares

To see whether the verification needs another look, find the sync commit with git log --oneline -1 --grep "every table command keeps a valid grid", then run git log --oneline <that commit>..HEAD -- with the table's files and packages/platejs/scripts/table-grid-commands.ts. For each commit it lists, read the diff and confirm three things. A new table command, or a new option of one, is a command in the script or a line in What it does not cover. The laws still compare with the table the script built and laid out itself, never with compileTableGrid or another output of the plugin. A rule added to the spec's Table section that changes what a command does is in its law. Move the sync commit in this file forward, naming its subject, only after that check and a run of pnpm check:table-grid.

What it does not cover

  • Tables larger than three by three, which --rows and --cols reach, two tables, nested tables and a table inside another block, such as Details.
  • Cells that hold their text directly, as in the Plite tables example. d13c7b8765 and 8e107e7413 fixed those cells in Plite, and Plate's tableCell holds paragraphs.
  • Header cells and rows, borders, backgrounds, column widths, row heights, resizing and allowCellSpanEditing off.
  • Paste of copied cells or a table, which EDIT-TABLE-PASTE-EXPAND-001 covers, and a range with one end outside the table, EDIT-TABLE-RANGE-EDGE-001.
  • Where the selection lands after a command, and undo and redo of a table command.
  • Tab and arrow navigation, cell selection by pointer or keyboard, and the browser.

/pstack:maintain-formal-verification-skill brings this verification back in line after changes that did not recheck it.

Repository

udecode/plate

Path

.agents/skills/table-grid-commands/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.