What
When combining multiple surfaces in a single sideshow publish, the order the surfaces appear in the post is determined by a fixed hardcoded sequence in the command body — not by the order the --md / --code / --diff / --terminal / --mermaid / --json / --image flags are passed on the command line.
The fixed order is: html → markdown → mermaid → diff → terminal → json → code → image.
So these two invocations produce identical surface order (html, markdown, code):
sideshow publish card.html --code app.py --md notes.md # → [html, markdown, code]
sideshow publish card.html --md notes.md --code app.py # → [html, markdown, code] (same)
Where
bin/sideshow.js, the publish command — the surfaces are pushed in a fixed if-ladder regardless of flags/positionals order:
https://github.com/modem-dev/sideshow/blob/main/bin/sideshow.js (the publish handler, ~line 821 onward)
const parts = [htmlPart];
if (flags.md !== undefined) parts.push({ kind: "markdown", ... });
if (flags.mermaid !== undefined) parts.push({ kind: "mermaid", ... });
if (flags.diff !== undefined) parts.push({ kind: "diff", ... });
if (flags.terminal !== undefined) parts.push({ kind: "terminal", ... });
if (flags.json !== undefined) parts.push({ kind: "json", ... });
if (flags.code !== undefined) parts.push({ kind: "code", ... });
if (flags.image !== undefined) parts.push({ kind: "image", ... });Why it matters
Surfaces render top-to-bottom in the card, so order is user-visible. An agent (or human) authoring a multi-surface post reasonably expects the visual order to match the order they wrote the flags — the current fixed order silently reorders their intent. This is easy to hit by accident and hard to discover (the only signal is the rendered card).
Observed while
Adding CLI test coverage for the core publish loop. The test publish combines html with --md, --code, --terminal, --mermaid surfaces in test/cli.test.ts pins the current fixed order.
Possible directions
- Honor flag order. Walk
process.argv (or the parsed tokens) and append surfaces in the order their flags first appear. Most intuitive; matches how most CLIs treat repeated/combined optional inputs.
- Document the fixed order in
--help and the guide, and keep the current behavior. Lowest-risk, but still surprising.
- Keep fixed order, but make it the documented canonical order and have
--help state it explicitly.
Flagging as a UX consideration rather than a correctness bug — no data is lost, surfaces just land in an order the author didn't ask for.
What
When combining multiple surfaces in a single
sideshow publish, the order the surfaces appear in the post is determined by a fixed hardcoded sequence in the command body — not by the order the--md/--code/--diff/--terminal/--mermaid/--json/--imageflags are passed on the command line.The fixed order is:
html → markdown → mermaid → diff → terminal → json → code → image.So these two invocations produce identical surface order (
html, markdown, code):Where
bin/sideshow.js, thepublishcommand — the surfaces are pushed in a fixedif-ladder regardless offlags/positionalsorder:https://github.com/modem-dev/sideshow/blob/main/bin/sideshow.js (the
publishhandler, ~line 821 onward)Why it matters
Surfaces render top-to-bottom in the card, so order is user-visible. An agent (or human) authoring a multi-surface post reasonably expects the visual order to match the order they wrote the flags — the current fixed order silently reorders their intent. This is easy to hit by accident and hard to discover (the only signal is the rendered card).
Observed while
Adding CLI test coverage for the core publish loop. The test
publish combines html with --md, --code, --terminal, --mermaid surfacesintest/cli.test.tspins the current fixed order.Possible directions
process.argv(or the parsed tokens) and append surfaces in the order their flags first appear. Most intuitive; matches how most CLIs treat repeated/combined optional inputs.--helpand the guide, and keep the current behavior. Lowest-risk, but still surprising.--helpstate it explicitly.Flagging as a UX consideration rather than a correctness bug — no data is lost, surfaces just land in an order the author didn't ask for.