Files
artcraft/frontend
Tanish Mankuandbflatastic e3f48033f9 Keybind settings: New menu and revamped keybind support (#1699)
## 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>
2026-08-25 00:34:26 -07:00
..
2026-03-12 15:49:24 +07:00
2026-06-10 09:28:25 -04:00

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 a node_modules/.pnpm directory — npm installs will fail (typically with ENOTEMPTY rename 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