## Summary Adds a unified, remappable keyboard-shortcut system (`@storyteller/keybinds`) across the webapp and desktop app, replacing the scattered hardcoded `keydown` listeners in the 3D editor, 2D editor, and moodboard with one registry, two presets (**Gamer** = today's defaults, **Blender-like**), a Settings → Keybinds pane, and a hold-Ctrl / pinnable cheatsheet on every editor surface. This PR was approved in June and then sat behind ~195 commits on `main` (timeline, build/record modes, lucide migration). It has been merged with current `main` and extended to cover the features that landed since. **Nothing changes by default** — the Gamer preset reproduces every existing key exactly. ## Architecture - **Registry of `ActionDef`s** keyed by surface-namespaced ids (`pagescene.timeline.playPause`), bound to physical `event.code`. Resolution: user override → preset delta → base bindings. Persisted in the `artcraft-keybinds` zustand store. - **Five surfaces**: `global`, `pagescene` (3D), `pagedraw` (2D), `moodboard` (canvas), `moodboard-grid` (board library / inspector / presentation). - **Declared availability** — `ActionDef.when(ctx)` gates decide whether a binding is live for the current editor state (`sceneMode`, `encoding`, `timelineExpanded`, `timelineSelection`, …). An unavailable binding falls through *without consuming the event*, which is what lets Space / arrows / Delete / Escape be shared by context-exclusive actions. A sampled-context checker (`actionsCoAvailable`) proves the exclusivity in tests and drives the conflict UI in Settings. - **Global surface is a pure trigger layer**: features register behavior with `useGlobalAction(id, handler)`; a window capture-phase dispatcher fires above the modal key-swallow, and an unregistered binding is inert per host. First inhabitant: Ctrl/Cmd+B sidebar. This is the intended home for the upcoming privacy-blur toggle (one `ActionDef` + one binding + one `useGlobalAction` call). - Cross-surface conflict detection (global ↔ everything, both directions); preset-integrity tests guard every preset against same-surface collisions. - **Video editor keeps its own keybinds system** — deliberate non-goal. ## What's in it **3D editor (pagescene)** - Timeline actions: Space play/pause, ←/→ frame step or keyframe/strip nudge, Home/End, `I` add keyframe (Blender parity), Shift+T expand, Delete/Backspace on a valid timeline selection (exact complement of scene-object delete). - Record mode: Tab toggles build/record, `C` capture still, `R` record video (bare letters — Firefox eats Ctrl+Shift+S/E), Escape cancels an in-flight encode (overlay Cancel button too). Record mode is immutable: all scene-mutating actions gate off, Escape no longer drops out of the render cam. - **Per-edit timeline undo** — every timeline edit is one Ctrl+Z step (`TimelineEditAction` with whole-timeline snapshots; drags and the easing popover coalesce into single steps). Save now only moves the Cancel baseline; Cancel is itself undoable. - The old "Shortcuts" modal is replaced by the live cheatsheet, pinnable from the same button. - Dead code removed: `MouseControls.onkeydown`, `OnboardingHelper`, the hardcoded `Help` view, three unused pagedraw hotkey hooks. **2D editor (pagedraw)** - Tool hotkeys 1–5 with live key badges on the toolbar icons; the shape key cycles rectangle → circle → triangle (submenu-aware). - Ctrl+= / Ctrl+- (and numpad) resize the active tool. The eraser now has its own size (was sharing the brush's) and its own slider popout; also fixes the eraser button never highlighting. **Moodboard** - Canvas keys unchanged (now registry-backed), plus Ctrl+0 reset viewport. - Grid: rate 0–5 / `P` pick / Delete / Escape, inspector and presentation ←/→/Space/Esc — all rebindable. Escape now closes the inspector; arrows no longer navigate while typing in the tag field. **Settings & cheatsheet** - Settings → Keybinds: preset picker, name/key search, per-action rebind with conflict warnings, per-section reset, and a bottom "danger zone" reset-all with a two-step confirm (2 s lockout + visible 5 s auto-disarm). - Cheatsheet: hold Ctrl (⌘) 3 s to peek; **General → "Keep shortcut cheatsheet open"** makes it stick until Esc / click-outside; the 3D "Shortcuts" button pins it. ## Testing - `@storyteller/keybinds` unit tests (29): resolution layering, overrides, per-surface/global reset, conflict detection incl. global↔surface, matcher semantics, and preset integrity across all presets. - Builds green: `keybinds`, `ui-pagescene`, `ui-pagedraw`, `ui-moodboard`, `ui-settings-modal`, `artcraft-webapp`, `artcraft` (desktop). - Manual QA pass completed on the webapp for every area above (settings pane, cheatsheets, Blender modal transforms, timeline/record keys, pagedraw toolbar, global surface, reset UX, pinned cheatsheet, timeline undo, Escape contexts). ## Notes for review - The keybinds store is unversioned-migration-free on purpose — the PR was never merged, so there's no persisted shape to migrate from. - Space-hold pan (moodboard) and held WASD camera movement stay as gestures, resolved from the same store but outside the discrete-action dispatch. --------- Co-authored-by: bflatastic <bombayapirat@gmail.com>
Frontend
This is an nx monorepo that can contain multiple apps and shared libraries.
All commands to run these projects are performed from this directory (except the repo-root launcher scripts noted below).
Requirements
- Node.js 20+ (Nx 21 / Vite 6 requirement). Install via nvm,
nodejs.org, or
brew install node. - npm (ships with Node).
We use npm, not pnpm. pnpm was briefly adopted ("add pnpm to solve build issues") and later removed ("fix(frontend): consume video-editor libs via nx path aliases, drop pnpm"). If you have leftovers from that era — a
pnpm-lock.yaml,pnpm-workspace.yaml, or anode_modules/.pnpmdirectory — npm installs will fail (typically withENOTEMPTYrename errors). See Troubleshooting below.
Install dependencies
npm install
Running the apps in dev mode
From the repository root, the launcher scripts (these preflight your environment, install dependencies, and free the dev port first):
./script/website/unix_frontend_dev.sh # artcraft-website (marketing site), port 4200
./script/website/unix_frontend_webapp_dev.sh # artcraft-webapp (user dashboard), port 4201
./script/artcraft/unix_frontend_dev.sh # artcraft (Tauri app frontend), port 5173
Or directly from this directory:
nx dev artcraft-website
nx dev artcraft-webapp
nx dev artcraft # NB: the Tauri app also needs the Rust dev server running
nx dev editor2d
Building
npx nx build artcraft-website
npx nx build artcraft-webapp
npx nx build artcraft
npx nx build editor2d
Netlify deploys run apps/<app>/script/netlify_build.sh (see each app's
netlify.toml).
Troubleshooting
npm install fails with ENOTEMPTY: directory not empty, rename ...
Your node_modules tree is corrupted — usually an interrupted install, or a
tree written by pnpm back when the repo briefly used it. Fix:
./clean_modules.sh
npm install
Or the manual minimum:
rm -rf node_modules .nx pnpm-lock.yaml pnpm-workspace.yaml
npm install
Stale build state after switching branches
Call this when starting on main or a new branch:
./clean_modules.sh
It removes all dist/ outputs, resets the nx cache, and removes
node_modules.
Import aliases
The names for @frontend and @storyteller come from the package.json file
in the libs folder:
import { Login } from "@frontend/login";
import { api } from "@storyteller/api";
For shared UI components, import from @storyteller/ui-[componentname]:
import { Button } from "@storyteller/ui-button";
import { Modal } from "@storyteller/ui-modal";
Generating a new component library
# 1. Generate the library
npx nx g @nx/react:library libs/components/toaster --import-path=@storyteller/ui-toaster --bundler=vite
npm install
# 2. Import it somewhere in code
# 3. Sync and build
nx sync
nx build