You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Two PostMachine conventions are mentioned in prose but not visually illustrated. Both are subtle enough that a small Mermaid diagram alongside an example would shorten the path from "I read the docs" to "I understand what the graph looks like."
(1) noop — the fall-through pass-through
noop is the "do nothing, advance to the next instruction" command. Visually it's a state with a single [*] → [K]/[S] self-targeting transition to the next instruction's State. Useful when teaching:
The pattern noop(20) as an unconditional jump from any instruction to 20.
How grouping interacts with noop (grouped noop becomes a no-op step in the chain).
Why noop is sometimes preferred over right(20) etc. — when you don't want to mutate the tape.
Suggested addition: short <details>-collapsed Mermaid block in the Commands or Quick start section showing a { 10: noop(30), 30: mark, 40: stop } machine. Pair with an examples.spec.ts test pinning the salient shape (one outgoing [*] arrow, no tape mutation).
(2) Trailing stop doesn't produce its own state node
Currently the Quick start prose hints at this: "The 40: stop instruction is elided — stop halts the machine, so the transition from 30: mark flows straight to halt rather than through an intermediate state."
But the visual consequence isn't pinned with its own diagram. A reader who tries { 10: mark, 20: stop } and inspects the emit might be surprised to see only ONE non-halt state (s10), not two.
Suggested addition: a tiny Mermaid block alongside the prose showing:
Two added <details> blocks + two test assertions in examples.spec.ts.
No code change. Strictly documentation.
Cross-refs
Surfaced during the #85 drop-hopper refactor — while reviewing structural-summary diagrams it became clear other PostMachine conventions deserve similar visual treatment.
Motivation
Two PostMachine conventions are mentioned in prose but not visually illustrated. Both are subtle enough that a small Mermaid diagram alongside an example would shorten the path from "I read the docs" to "I understand what the graph looks like."
(1)
noop— the fall-through pass-throughnoopis the "do nothing, advance to the next instruction" command. Visually it's a state with a single[*] → [K]/[S]self-targeting transition to the next instruction's State. Useful when teaching:noop(20)as an unconditional jump from any instruction to 20.noop(groupednoopbecomes a no-op step in the chain).noopis sometimes preferred overright(20)etc. — when you don't want to mutate the tape.Suggested addition: short
<details>-collapsed Mermaid block in the Commands or Quick start section showing a{ 10: noop(30), 30: mark, 40: stop }machine. Pair with anexamples.spec.tstest pinning the salient shape (one outgoing[*]arrow, no tape mutation).(2) Trailing
stopdoesn't produce its own state nodeCurrently the Quick start prose hints at this: "The
40: stopinstruction is elided —stophalts the machine, so the transition from30: markflows straight to halt rather than through an intermediate state."But the visual consequence isn't pinned with its own diagram. A reader who tries
{ 10: mark, 20: stop }and inspects the emit might be surprised to see only ONE non-halt state (s10), not two.Suggested addition: a tiny Mermaid block alongside the prose showing:
— and an explicit "notice: no
s20for the stop; the engine routes directly tos0" line.Scope
@post-machine-js/machineREADME).<details>blocks + two test assertions inexamples.spec.ts.Cross-refs