Add keyboard layout selector (QWERTY/Colemak/Colemak-DH/Dvorak/Workman)

[Olson3R]

Summary

Cosmos has been QWERTY-only: letterForKeycap() baked QWERTY into every alpha key as it was generated, and FLIPPED_KEY mirrored those letters for the left half. This PR adds layout selection — QWERTY, Colemak, Colemak-DH, Dvorak, Workman — and threads it through the alpha-letter generation path so swapping the layout updates both keycap legends and ZMK/QMK firmware output.

This is Phase 1 of a planned three-phase rollout — letter-swap layouts only. Layers, mod-tap/layer-tap, Miryoku, and a general-purpose layer editor are scoped for follow-up PRs. See docs/LAYOUT_PHASES.md for the full plan.

Design

Layout is not stored on the config — it's a pure function of the alpha-key labels, derived the same way as clusterAngle / clusterSeparation / row curvature. detectLayout(kbd) inspects every finger cluster and returns LAYOUT.QWERTY / LAYOUT.COLEMAK / etc. when the alpha block matches one-for-one, or LAYOUT.CUSTOM when it doesn't. The dropdown reads this on every render; picking a named option mutates the keys via applyLayoutToKeys. No kbd.layout field, no state to keep in sync, no proto field.

This means custom edits in expert mode and per-key letter edits via the 3D viewer's Letter input both auto-flip the dropdown to Custom — without any reactive state-management.

What's included

Layout registry — src/lib/layouts/

Const-keyed registry exposing LAYOUT.QWERTY, LAYOUT.COLEMAK, LAYOUT.COLEMAK_DH, LAYOUT.DVORAK, LAYOUT.WORKMAN, plus LAYOUT.CUSTOM. Each named layout carries right-row letters for rows 2/3/4 and a flipMap for split-half mirroring. flipLetter, rightSideLetter, getLayout, isLayoutId, isNamedLayoutId are the public helpers.

Layout-aware letter generation

letterForKeycap, cosmosFingers, keycapInfo, flippedKey, and mirrorCluster all accept an optional layout (default: QWERTY for back-compat). Editor callers thread the keyboard's detected layout through. Number row, F-row, and outer-punctuation keys stay layout-independent — only rows 2/3/4 of the alpha block move.

Editor UI

• Layout dropdown — SelectThingy placed after Keycaps in VisualEditor2.svelte. Each option's hover popup includes a one-line description and a small ortholinear keyboard preview rendered with the layout's letters. Custom is text-only.
• Auto-detect — the dropdown's value is detectLayout($protoConfig) on every render. Editing a single alpha key, deleting a column, or shrinking the cluster size flips it to Custom automatically.
• Mirror-form letter editing — when the user clicks a virtual left-half key, the Letter input flips through the layout's flipMap so typing q writes p to the underlying right-cluster key.
• Expert→basic transition — setMode runs detectLayout on the freshly-derived cosmos config so the basic-mode dropdown reflects the post-edit layout (instead of always showing QWERTY).

Alert system

New popover-based alert framework (src/lib/store.ts + src/lib/presentation/Alert*.svelte):

• Anchored to the right of the field that triggered the alert, with a tail/arrow pointing back at the anchor. Falls back to below-anchor on narrow viewports.
• Single pink style, "Dismiss" text link, 10s auto-dismiss with a progress bar at the bottom; pause-on-hover stops both the timer and the bar animation.
• Used in two places by this PR:
  1. Dropdown into Custom — info hint explaining how to edit a single key's legend.
  2. Dropdown out of Custom blocked — when the keyboard is missing alpha keys the target layout needs, the alert lists every missing letter (across both halves of split keyboards) and refuses the switch until the user adds them back.

Auto-flip safety: missingKeysFor enumerates both halves

For mirrored splits (only the right cluster stored), the synthesized left side is checked too. Deleting the visible-left q on a mirrored split surfaces both p and q as missing, not just the right-cluster's p. Non-mirror splits check each stored cluster independently.

Files touched

Area	File
Layout registry	src/lib/layouts/index.ts
Layout detection	src/lib/worker/config.cosmos.ts (detectLayout, missingKeysFor, alphaColumns, mirrorCluster)
Letter generation	src/lib/worker/config.ts, src/lib/geometry/keycaps.ts
Editor UI	src/routes/beta/lib/editor/VisualEditor2.svelte, visualEditorHelpers.ts
Alert system	src/lib/store.ts, src/lib/presentation/Alert.svelte, src/lib/presentation/AlertPopover.svelte
Mirror callers	src/routes/beta/lib/editor/toCode.ts, src/routes/beta/lib/dialogs/HandFitView.svelte
Firmware (export)	src/routes/beta/lib/firmware/zmk.ts, src/routes/beta/lib/firmware/qmk.ts (export keycode for tests)
Plan doc	docs/LAYOUT_PHASES.md

Test plan

• src/lib/layouts/layouts.test.ts — all 5 layouts × rightSideLetter, flipLetter bidirectionality, registry helpers.
• src/lib/layouts/layoutEndToEnd.test.ts — applyLayoutToKeys updates alpha rows / preserves number rows; ZMK/QMK keycode mapping per layout; end-to-end home-row contract.
• src/lib/layouts/missingKeys.test.ts — missingKeysFor covers shrunk-cluster, single-key-deleted, mirror-form-both-halves, non-mirror-split-left-only, expert-mode duplicate-letter, and round-trip flip-to-Custom scenarios.
• Full suite: 58/58 pass (bun test).
• npm run check — 0 errors.
• Manual: open editor → switch Layout dropdown → verify 3D legends update for both halves.
• Manual: export ZMK and QMK keymaps under each layout → verify keycodes match.
• Manual: load an existing shared URL → verify it still decodes with QWERTY legends.
• Manual: delete a single alpha key → dropdown silently flips to Custom; pick a layout that needs that key → blocked alert lists both halves' letters.

Notes

• Per-key letter overrides are supported by the data model (the stored keycap.letter wins) but no UI yet — that lands with the layer editor in Phase 3.
• An earlier draft persisted layout as proto field 33; that was removed once the design became "layout is derived from labels," so existing shared URLs are unaffected by definition (no new field, no parser change).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cosmos-keyboards	Ready	Preview	May 7, 2026 6:15am

[rianadon]

Thanks for the PR! Took a quick look at the code and no major problems stood out.

Briefly played with these and writing up UI notes so far:

• Layout should get its own icon (Its own icon would be great, but my best idea is reuse the Letter icon)
• The dropdown menu for layout should use the fancier dropdown keycaps/switches use. When you hover over a layout the popup should give an explanation on the layout and a rendering of the layout on a split ortholinear keyboard. I don't expect many people to know what all these layouts are or which is best for them.
• There's a bug when switching from qwerty to colemak on the default model. The bottom keys ([ and ]) change to duplicates of the two keys above them.
• Add a "Custom" option. We should detect when a user implements their own layout (i.e. changes any of the alpha keys) and change layout to "Custom". If someone manually switches the layout from qwerty to custom, show a dialog that shows them how to manually edit key legends (ideally show an image or video of how to do it, but linking to here is good enough for now).
  • Things to should switch to custom:
    • Changing an alpha key
    • Deleting a column with alpha keys
  • Things that should not switch to custom:
    • Adding an alpha key anywhere outside the ones the qwerty/colemak/etc layout uses
    • Adding a new key anywhere
• The layout needs to be correctly computed when going from expert mode to basic mode. Right now it's always qwerty. Instead, if it one for one matches a layout (use homing key assignments to get your bearings), use that layout. Otherwise, "custom".
• If you deleted a column of alpha keys, you're now on Custom layout. Unless you add back those keys, the site should prevent you from switching layouts. Probably a dialog that appears when you try to switch that tells you which keys you're missing.

[Olson3R]

@rianadon I think this one is good again.

[rianadon]

I've noticed that on the editor I'm having trouble using the back button to undo. This logic looks very suspicious to me. The only things that should trigger a protoconfig update are UI interactions, not protoconfig updating. The cleaner way would be to extract this into a function, and call it in Viewer3D. The two places you should need to do it are when a key/column is deleted (removeKey) and a legend is changed (setLetter).

[rianadon]

More comments:

• Sorry, the A icon was not a good choice. It looks too small compared to the other options. I'll make my own.
• Awesome job on the dropdown menu and previews. My only comment is make the home row pink a slightly lighter pink so that there isn't as much contrast between rows.
• Custom doesn't need a key layout preview. Just text is fine
• There should be an alert when there's not enough keys to switch to a layout and you're stuck on Custom. I've been meaning to add an alerts system to Cosmos, and now's a good time to do it. You should be able to build a popover very similar to the ones I've already implemented for the dropdown menus that will show up next to the layout field. It'll have a dismiss button and also dismiss itself after, say, 10 seconds. There will also be a bar at the bottom that progresses across the alert as those 10 seconds go by.
  
• Speaking of alerts, I think it's better to move the dialog telling you that you've selected custom mode to an alert.

[rianadon]

The logic for changing into custom when the layout changes is very solid. I think it would also make sense to do the same for the other layouts as well. For example, in QWERTY if you change the Q to a Z then back to Q, the layout should switch from QWERTY->Custom->QWERTY. In this case, there's no point having a separate field in the config for layout. It's purely a function of the current keyboard labels. That should also simplify a ton of logic, and you can ignore my comment in VisualEditor2. Since layout isn't part of the config, you won't need to worry about state management.

The layout dropdown would work very similarly to row curvature / column curvature. Those are also fields that aren't tied to a specific config option but instead have their own logic for calculating themselves and updating the config when changed.

[Olson3R]

I believe it is ready to review again.

[rianadon]

Unless there's any design critiques you have (in which case I'd be more than happy to hear them), it would be great if you could tightly match the design in the screenshot, where the alert is to the right of the menus. That way it doesn't cover anything like it's currently doing:

Also please match the colors, which means this alert won't need variants or icons.

It's not necessary to spawn an alert when the key layout changes from anything -> custom. I'd imagine that if you are deleting a key, you understand you are changing the layout. So there's no need to point it out.

However, the wording of the alerts when you switch into custom using the dropdown or try to switch from custom->something else but there are too few keys is good.

My only minor suggestion is you should compute the missing keys for both halves of the split keyboard, taking into account that for a keyboard with mirrored splits, you should show two different keys. Right now if I delete q on a mirrored split then try to switch back, the error message only includes the p key.

[rianadon]

Oh man, the decision to take out the custom field for layout has consequences.

Now if you change the layout to colemak then delete a key, the whole left side changes from colemak keys to qwerty keys. I think we are going to have to bring back a setting for the keyboard layout.

However, I think the best way to go about this is to have a hidden state. Which is dangerous, since there will be no direct way to observe or change the setting. What I'm thinking is that we bring back a global "layout" option for the keyboard that's qwerty, colemak, etc (but never custom), but call it "leftSideLayout". This option is only set for a keyboard when edit jointly is turned on for the board. For keyboards with both a left and a right side cluster in their config, it's null.

Backwards compatibility note: let's consider qwerty the null state for this option, since anything imported pre-this change will have qwerty layout.

The logic for the dropdown will still look the exact same. There will still be all the same options plus "custom", and they'll still operate by checking the entire keyboard layout against the predefined layouts. Hopefully that makes sense?

This means that for keyboards with "edit jointly" turned off (i.e. both a right and left cluster in their cosmosconfig), this new leftSideLayout option will have no effect and be ignored, so the logic will be the exact same as it is now. Then leftSideLayout becomes qwerty just to save some extra space in the url.
For keyboards with it turned on, you can end up in a few odd modes:

• leftSideLayout = a keyboard layout (e.g. colemak), but the dropdown says custom. This is the solution to the original problem where you don't want the layout to change when deleting a key. Basically, this is saying for the keys that are left, use colemak mappings to determine the left side of the keyboard. I think this is fine, and the UI probably won't be in this state for long since if you're trying to put together a minimal keyboard for chording, you'll probably take control over the legends anyways by going into edit separately mode.
• leftSideLayout = a keyboard layout, but the dropdown says a different keyboard layout. Will only happen when you have edit jointly turned off. Which is fine, because leftSideLayout doesn't affect anything in this case. This never happens for edit jointly because leftSideLayout determines the left half keys, which are checked for determining the keyboard layout.

Please let me know if you have any input on this.

[Olson3R]

I like the idea of making it best effort and detecting the closest layout. Maybe have an indicator if it. is complete or show missing letters.
Select the layout that most closely matches. Apply the letters to the keys that exist if they select a new layout.
Custom is an explicit choice.
Do we need Cosmos to be a fully featured layout editor? I feel like they are mainly there to help get a feel for things.