x4js 2.3.11 → 2.3.13

package/README.md

@@ -7,7 +7,19 @@ see [X4 home page](https://x4js.org)
 ## API Documentation
 see [GitHib](https://rlibre.github.io/x4/index.html)
 
-see [AI context](./aicontext.md)
+## Using x4js with an AI assistant
+Three files written for AI assistants ship with the package (in `node_modules/x4js/`). Give them to your assistant before asking it to write x4js code:
+
+- [aicontext.md](./aicontext.md): compact API reference, with exact signatures
+- [aiguide.md](./aiguide.md): how to write idiomatic x4js code
+- [aicli.md](./aicli.md): the `x4js` command line and `x4.config.json`
+
+With Claude Code, install the x4js plugin instead: its skill reads these files from your project by itself.
+
+```
+claude plugin marketplace add rlibre/x4
+claude plugin install x4js@rlibre
+```
 
 ---
 

package/aicli.md

@@ -0,0 +1,250 @@
+# x4js command line
+
+`x4js` creates, serves and builds x4js applications. It bundles TypeScript and styles with esbuild; there is nothing else to configure.
+
+```
+x4js create <project> [--template <name>] [--no-install]
+x4js templates
+x4js dev   [--config <file>] [--env <file>] [--host <host>] [--port <port>] [--http|--https] [--open]
+x4js build [--config <file>] [--env <file>] [--debug]
+x4js --help | --version
+```
+
+## Install
+
+The command ships with the `x4js` package. In a project created by `x4js create` it is already a dependency, and the npm scripts use it:
+
+```json
+{
+	"scripts": {
+		"dev": "x4js dev",
+		"build": "x4js build"
+	}
+}
+```
+
+```
+npm run dev
+npm run build
+```
+
+Without a project yet, run it through npx: `npx x4js create my-app`.
+
+### Which x4js runs
+
+There can be two copies on a machine: the one in the project's `node_modules` and a global one (`npm install -g x4js`).
+
+| You type | Copy used |
+|---|---|
+| `npm run dev`, `npx x4js dev` | the project's own copy |
+| `x4js dev` | the global copy |
+
+A global copy older than the project's can behave differently. `dev` and `build` print their version on the first line; check it when something looks wrong.
+
+```
+x4js       2.3.11
+mode       dev
+config     C:\work\my-app\x4.config.json
+outdir     C:\work\my-app\bin
+server     http://127.0.0.1:8000
+```
+
+## Commands
+
+### `x4js create <project>`
+
+Creates a new project in the folder `<project>` from a template.
+
+| Option | Effect |
+|---|---|
+| `--template <name>`, `-t <name>` | Template to use. Default: `app`. |
+| `--no-install` | Do not run `npm install` after creating the files. |
+
+- The project name becomes the package name: lowercase letters, digits, `.`, `_` and `-` only.
+- The target folder must be empty or not exist.
+- Templates are downloaded from the `rlibre/x4-templates` repository on GitHub, so the command needs network access.
+- The `x4js` dependency of the new project is set to the version line of the command that created it (for example `2.3`).
+
+### `x4js templates`
+
+Lists the available templates with a one-line description of each.
+
+### `x4js dev`
+
+Builds the application, serves the output folder and rebuilds on every change.
+
+| Option | Effect |
+|---|---|
+| `--config <file>` | Config file to use. Default: `x4.config.json`. |
+| `--env <file>` | File of variables for `$NAME` in the config (see below). |
+| `--host <host>` | Address to listen on. Default: `127.0.0.1`. |
+| `--port <port>` | Port to listen on. Default: the first free port from 8000. |
+| `--http`, `--https` | Force the protocol, whatever the config says. |
+| `--open` | Open the browser once the server is ready. |
+
+- The page reloads when a source or a copied file changes. A change that only touches CSS is applied without reloading.
+- Build errors and warnings are printed in the terminal.
+- Editing the config file restarts the build. The file given to `--env` is read again at that moment; editing it alone restarts nothing.
+- HTTPS needs a certificate and a key, declared in `dev.tls` (see below).
+
+### `x4js build`
+
+Writes the application to the output folder.
+
+| Option | Effect |
+|---|---|
+| `--config <file>` | Config file to use. Default: `x4.config.json`. |
+| `--env <file>` | File of variables for `$NAME` in the config (see below). |
+| `--debug` | Debug build: not minified, with source maps. |
+
+The output folder is **emptied before each build**. Do not keep hand-written files in it: put them in the sources and list them in `copy`.
+
+| | `dev` | `build --debug` | `build` |
+|---|---|---|---|
+| Minified | no | no | yes |
+| Source maps | separate `.map` files | separate `.map` files | none |
+| `DEBUG_MODE` | `true` | `true` | `false` |
+| Live reload | yes | no | no |
+
+## `x4.config.json`
+
+The file sits at the root of the project. Every key is optional; without the file, the defaults below apply.
+
+```json
+{
+	"entryPoints": ["src/main.ts"],
+	"outdir": "./bin",
+	"copy": [
+		{ "from": "./src/assets", "to": "assets" },
+		{ "from": "./src/index.html", "to": "index.html" }
+	]
+}
+```
+
+| Key | Default | Meaning |
+|---|---|---|
+| `entryPoints` | `["src/main.ts"]` | Files to bundle. `src/main.ts` produces `main.js` and `main.css`. |
+| `outdir` | `"./bin"` | Output folder. It cannot be the project root. |
+| `copy` | `[]` | Files or folders copied to the output after each successful build. `to` is relative to `outdir`. |
+| `external` | `[]` | Module names left out of the bundle. |
+| `define` | `{}` | Constants replaced at build time. Values are JavaScript expressions written as strings, for example `"\"prod\""`. |
+| `dev` | | Dev server settings: `host`, `port`, `https`, `tls`. |
+| `esbuild` | `{}` | Native esbuild options, applied last. They override everything above. |
+
+Relative paths are resolved from the project root. Paths and `define` values accept environment variables, written `$NAME` or `${NAME}`; an undefined variable is an error.
+
+### Environment variables in `define`
+
+A `define` value is a JavaScript expression, so a text is written between escaped double quotes. The variable is read when the command runs: its value ends up in the bundle.
+
+```json
+{
+	"define": {
+		"API_URL": "\"$API_URL\"",
+		"API_PORT": "$API_PORT"
+	}
+}
+```
+
+```ts
+declare const API_URL: string;
+declare const API_PORT: number;
+```
+
+With `API_URL=https://example.com` and `API_PORT=8080`, the code sees the text `"https://example.com"` and the number `8080`. A quote or a backslash in the value of a variable is escaped: use double quotes around `$NAME`, not single ones.
+
+Everything in the bundle is public: do not put a secret in `define`.
+
+### Variables from a file
+
+`--env <file>` reads variables from a file of `NAME=value` lines, for `dev` and `build`:
+
+```
+# .env
+API_URL=https://example.com
+API_PORT=8080
+```
+
+```
+x4js dev --env .env
+```
+
+- The file only serves `$NAME` in the config. Its variables are not given to the application: pass the ones it needs through `define`.
+- A variable already defined in the environment keeps its value: the file only adds the missing ones.
+- A file that does not exist is an error.
+
+This lets the same config work on a machine and on a host that defines the variables itself:
+
+```json
+{
+	"scripts": {
+		"dev": "x4js dev --env .env",
+		"build": "x4js build"
+	}
+}
+```
+
+Keep the file out of Git when it holds values that are not public.
+
+### The HTML page
+
+The command does not generate an HTML page. Write `src/index.html` and copy it with `copy`, as in the example above. It loads the bundle by its output name:
+
+```html
+<!DOCTYPE html>
+<html>
+	<head>
+		<meta charset="utf8">
+		<link rel="stylesheet" href="main.css">
+		<script src="main.js"></script>
+	</head>
+</html>
+```
+
+### HTTPS in dev
+
+```json
+{
+	"dev": {
+		"https": true,
+		"tls": { "cert": "./certs/dev.crt", "key": "./certs/dev.key" }
+	}
+}
+```
+
+## What the build handles
+
+| Import | Result |
+|---|---|
+| `.ts`, `.js` | Bundled into one script per entry point (browser, ES2020). |
+| `.scss`, `.sass`, `.css` | Compiled and bundled into one stylesheet per entry point. |
+| `.less` | Same, if the `less` package is installed in the project (`npm install -D less`). |
+| `.svg` imported from a script | A `data:` URL string, usable as an icon. |
+| `.png`, `.jpg`, `.jpeg`, `.ttf`, `.woff`, `.woff2` | Copied to `assets/` with a hashed name. |
+
+Two constants are always defined:
+
+| Constant | Value |
+|---|---|
+| `DEBUG_MODE` | `true` in `dev` and `build --debug`, `false` in `build`. |
+| `VERSION_ID` | Build date as a number, `YYMMDD`. |
+
+Declare them once in your project to use them from TypeScript:
+
+```ts
+declare const DEBUG_MODE: boolean;
+declare const VERSION_ID: number;
+```
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| `index.html` is missing from the output folder | It is not listed in `copy`, or the command that ran is an older global copy. Compare the version on the first line with the project's. |
+| A file placed in the output folder disappeared | `x4js build` empties the folder. Move the file to the sources and add it to `copy`. |
+| `Cannot find package 'esbuild'` | The dependencies of the `x4js` copy being run are not installed. Run `npm install` in the project. |
+| `Config file not found` | The file given to `--config` does not exist. Without `--config`, a missing `x4.config.json` is not an error. |
+| `Environment variable '…' is not defined` | A path or a `define` value in the config uses `$NAME` and the variable is not set, in the environment or in the file given to `--env`. |
+| `Env file not found` | The file given to `--env` does not exist. |
+| `LESS support requires the "less" package` | A `.less` file is imported and `less` is not installed in the project. |
+| No colors in the terminal, or unwanted ones | Set `FORCE_COLOR=1` to force them, `NO_COLOR=1` to remove them. |

package/aicontext.md

@@ -17,6 +17,7 @@ import { ... } from 'x4js'   // src/x4.ts
 **Archived repository**: https://github.com/rlibre/x4js (read-only since March 2026)
 **License**: MIT
 **Quick start**: `npx x4js create demo` (list the templates with `npx x4js templates`)
+**Claude Code plugin**: `claude plugin marketplace add rlibre/x4` then `claude plugin install x4js@rlibre` (skill that reads these files from the project)
 
 ---
 
@@ -734,6 +735,7 @@ interface SpreadsheetProps extends ComponentProps {
   enterMove?: "down" | "right" | "none"     // selection move after Enter in a cell editor (default "down")
   click?, dblClick?, contextMenu?, selectionChange?
   cellChange?                               // EvCellChange, fired before an edited value is written to the store
+  cellKey?                                  // EvCellKey { key, row, col, uievent }, fired for each key before the default handling
 }
 interface SpreadsheetColumn {               // GridColumn +
   editable?: boolean | ((row, col) => boolean)       // inline edition (off by default), col = column index
@@ -747,7 +749,9 @@ class Spreadsheet extends Component {
 }
 
 // Inline edition: F2 / Enter / double-click / typing starts, Enter / Tab / click elsewhere validates, Escape cancels,
-// Delete clears, editable checkboxes toggle on click or Space. Default editor is an Input matching the column type.
+// Delete clears, editable checkboxes toggle on double-click or Space (a single click only selects).
+// Default editor is an Input matching the column type.
+// cellKey: key hook (function keys...), not fired while a cell is edited; ev.preventDefault() skips the default handling.
 // cellChange: ev.preventDefault() refuses the value, ev.value can be replaced.
 // Select / Combobox in a cell (the store holds the id, use `formatter` to display the text):
 //   { id: 2, title: "Status", width: 120, editable: true,
@@ -1392,6 +1396,7 @@ When creating a new x4js project, use these files as a base.
 
 `x4js dev` runs the dev server, `x4js build` writes `outdir` (add `--debug` for a debug build).
 Both read `x4.config.json` (change the file with `--config <file>`).
+Full reference of the command line (commands, options, config keys, troubleshooting): `aicli.md`.
 
 ### `x4.config.json`
 

package/aiguide.md

@@ -636,6 +636,13 @@ selectLanguage("en");
 // only now build the application components
 ```
 
+Type each additional language after the first one, so the compiler reports a missing text:
+
+```ts
+const app_fr = { app: { open: "Ouvrir", close: "Fermer" } };
+const app_en: typeof app_fr = { app: { open: "Open", close: "Close" } };
+```
+
 ---
 
 ## Final rule

package/cli/build-options.mjs

@@ -27,12 +27,12 @@ export function createBuildOptions(config, mode) {
         charset: "utf8",
         keepNames: true,
         platform: "browser",
-		logLevel: "silent",
+        // Errors and warnings are printed by diagnostic-plugin.mjs.
+        logLevel: "silent",
         format: "iife",
         target: "es2020",
         minify: production,
         sourcemap: production ? false : "linked",
-        logLevel: "info",
         external: config.external,
         assetNames: "assets/[name]-[hash]",
         loader: {

package/cli/build.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import { parseArgs } from "node:util";
 import esbuild from "esbuild";
-import { DEFAULT_CONFIG_FILE, expandEnv, loadConfig } from "./config.mjs";
+import { DEFAULT_CONFIG_FILE, expandEnv, loadConfig, loadEnvFile } from "./config.mjs";
 import { createBuildOptions } from "./build-options.mjs";
 import { info, success } from "./log.mjs";
 import { printBuildError, printWarnings } from "./diagnostic-plugin.mjs";
@@ -11,6 +11,7 @@ export async function build(argv = [], root = process.cwd()) {
         args: argv,
         options: {
             config: { type: "string" },
+            env: { type: "string" },
             debug: { type: "boolean", default: false },
         },
         allowPositionals: true,
@@ -20,12 +21,17 @@ export async function build(argv = [], root = process.cwd()) {
     if (positionals.length)
         throw new Error(`Unexpected argument: ${positionals[0]}`);
 
+    const envFile = values.env ? loadEnvFile(root, values.env) : undefined;
+    const env = envFile?.env ?? process.env;
+
     const configArg = values.config ? expandEnv(values.config) : DEFAULT_CONFIG_FILE;
-    const config = loadConfig(root, configArg, process.env, { explicit: values.config !== undefined });
+    const config = loadConfig(root, configArg, env, { explicit: values.config !== undefined });
     const mode = values.debug ? "debug" : "production";
 
     info("mode", mode);
     info("config", config.configFile);
+    if (envFile)
+        info("env file", envFile.filename);
     info("outdir", config.outdir);
 
     await fs.rm(config.outdir, { recursive: true, force: true });

package/cli/config.mjs

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { parseEnv } from "node:util";
 
 export const DEFAULT_CONFIG_FILE = "x4.config.json";
 
@@ -15,7 +16,7 @@ const DEFAULTS = Object.freeze({
     },
 });
 
-export function expandEnv(value, env = process.env) {
+export function expandEnv(value, env = process.env, escape = (text) => text) {
     if (typeof value !== "string")
         return value;
 
@@ -26,11 +27,18 @@ export function expandEnv(value, env = process.env) {
             const result = env[name];
             if (result === undefined)
                 throw new Error(`Environment variable '${name}' is not defined`);
-            return result;
+            return escape(result);
         },
     );
 }
 
+// A define value is a JavaScript expression, usually a string literal
+// ("\"$NAME\""). The value of the variable is escaped so that a quote or a
+// backslash in it cannot end or corrupt that literal.
+function escapeForDefine(text) {
+    return JSON.stringify(text).slice(1, -1);
+}
+
 export function resolvePath(root, value, env = process.env) {
     const expanded = expandEnv(value, env);
     return path.isAbsolute(expanded)
@@ -42,6 +50,39 @@ export function resolveConfigFile(root, configFile = DEFAULT_CONFIG_FILE, env =
     return resolvePath(root, configFile, env);
 }
 
+/**
+ * Reads the file given to --env.
+ * Returns the environment to expand the config with: the variables of the
+ * file, under those already defined, which win as with `node --env-file`.
+ *
+ * The option is not named --env-file on purpose: node handles that name
+ * itself, even after the script name, before this code runs.
+ */
+export function loadEnvFile(root, file, env = process.env) {
+    const filename = resolvePath(root, file, env);
+
+    let variables;
+    try {
+        variables = parseEnv(fs.readFileSync(filename, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new Error(`Env file not found: ${filename}`);
+        throw new Error(`Cannot read env file '${filename}': ${error.message}`);
+    }
+
+    // Inherit from the environment instead of copying it: process.env has
+    // its own lookup rules (names are case-insensitive on Windows).
+    // defineProperty, because a plain assignment would go through to it.
+    const merged = Object.create(env);
+    for (const [name, value] of Object.entries(variables)) {
+        if (env[name] === undefined)
+            Object.defineProperty(merged, name, { value, enumerable: true });
+    }
+
+    return { filename, env: merged };
+}
+
 function readJson(filename) {
     try {
         return JSON.parse(fs.readFileSync(filename, "utf8"));
@@ -146,7 +187,9 @@ export function loadConfig(root = process.cwd(), configFile = DEFAULT_CONFIG_FIL
             to: path.normalize(item.to),
         })),
         external: [...external],
-        define: { ...define },
+        define: Object.fromEntries(
+            Object.entries(define).map(([name, value]) => [name, expandEnv(value, env, escapeForDefine)]),
+        ),
         dev: {
             host,
             port,

package/cli/dev.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import esbuild from "esbuild";
-import { DEFAULT_CONFIG_FILE, expandEnv, loadConfig, resolveConfigFile, resolveTls } from "./config.mjs";
+import { DEFAULT_CONFIG_FILE, expandEnv, loadConfig, loadEnvFile, resolveConfigFile, resolveTls } from "./config.mjs";
 import { createBuildOptions } from "./build-options.mjs";
 import { info, success, failure } from "./log.mjs";
 
@@ -60,6 +60,7 @@ export async function dev(argv = [], root = process.cwd()) {
         args: argv,
         options: {
             config: { type: "string" },
+            env: { type: "string" },
             host: { type: "string" },
             port: { type: "string" },
             http: { type: "boolean", default: false },
@@ -86,7 +87,16 @@ export async function dev(argv = [], root = process.cwd()) {
     let restartChain = Promise.resolve();
     let browserOpened = false;
 
-    async function start(config) {
+    // Read again on each (re)start, so an edited env file is taken into
+    // account when the config is reloaded.
+    function load() {
+        const envFile = values.env ? loadEnvFile(root, values.env) : undefined;
+        const env = envFile?.env ?? process.env;
+        const config = loadConfig(root, configArg, env, { explicit: explicitConfig });
+        return { config, env, envFile };
+    }
+
+    async function start({ config, env, envFile }) {
         const host = values.host ?? config.dev.host;
         const port = values.port === undefined ? config.dev.port : Number(values.port);
         if (port !== undefined && (port < 0 || port > 65535))
@@ -101,7 +111,7 @@ export async function dev(argv = [], root = process.cwd()) {
         if (port !== undefined)
             serveOptions.port = port;
         if (useHttps)
-            Object.assign(serveOptions, resolveTls(config));
+            Object.assign(serveOptions, resolveTls(config, env));
 
         const next = await esbuild.context(createBuildOptions(config, "dev"));
         try {
@@ -113,6 +123,8 @@ export async function dev(argv = [], root = process.cwd()) {
             const url = serverUrl(actualHost, result.port, useHttps);
             info("mode", "dev");
             info("config", config.configFile);
+            if (envFile)
+                info("env file", envFile.filename);
             info("outdir", config.outdir);
             success("server", url);
 
@@ -128,12 +140,12 @@ export async function dev(argv = [], root = process.cwd()) {
     }
 
     async function reload() {
-        let config;
+        let loaded;
         try {
-            config = loadConfig(root, configArg, process.env, { explicit: explicitConfig });
-            protocolConfig(config, values);
-            if (values.https || (!values.http && config.dev.https))
-                resolveTls(config);
+            loaded = load();
+            protocolConfig(loaded.config, values);
+            if (values.https || (!values.http && loaded.config.dev.https))
+                resolveTls(loaded.config, loaded.env);
         }
         catch (error) {
             failure(`config: ${error.message}`);
@@ -146,7 +158,7 @@ export async function dev(argv = [], root = process.cwd()) {
             await previous.dispose();
 
         try {
-            await start(config);
+            await start(loaded);
             success("config", "reloaded");
         }
         catch (error) {
@@ -161,8 +173,7 @@ export async function dev(argv = [], root = process.cwd()) {
         }, 150);
     }
 
-    const initialConfig = loadConfig(root, configArg, process.env, { explicit: explicitConfig });
-    await start(initialConfig);
+    await start(load());
 
     const watchDir = path.dirname(watchedConfigFile);
     const watchName = path.basename(watchedConfigFile);

package/cli/main.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { failure } from "./log.mjs";
+import { failure, info } from "./log.mjs";
 
 const cliDir = path.dirname(fileURLToPath(import.meta.url));
 const packageFile = path.join(cliDir, "..", "package.json");
@@ -21,11 +21,12 @@ function printHelp(version) {
 Usage:
   x4js create <project> [--template <name>] [--no-install]
   x4js templates
-  x4js dev [--config <file>] [--host <host>] [--port <port>] [--http|--https] [--open]
-  x4js build [--config <file>] [--debug]
+  x4js dev [--config <file>] [--env <file>] [--host <host>] [--port <port>] [--http|--https] [--open]
+  x4js build [--config <file>] [--env <file>] [--debug]
 
 Options:
   --config <file>  Config file (default: x4.config.json)
+  --env <file>     File of NAME=value lines, for $NAME in the config
   -h, --help       Show help
   -v, --version    Show version`);
 }
@@ -46,11 +47,13 @@ try {
             break;
         }
         case "dev": {
+            info("x4js", version);
             const { dev } = await import("./dev.mjs");
             await dev(argv);
             break;
         }
         case "build": {
+            info("x4js", version);
             const { build } = await import("./build.mjs");
             await build(argv);
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x4js",
-  "version": "2.3.11",
+  "version": "2.3.13",
   "type": "module",
   "main": "src/x4.ts",
   "module": "src/x4.ts",
@@ -21,6 +21,7 @@
     "src",
     "bin",
     "cli",
+    "aicli.md",
     "aicontext.md",
     "aiguide.md",
     "README.md",

package/src/components/spreadsheet/spreadsheet.ts

@@ -72,6 +72,18 @@ export interface EvCellChange extends ComponentEvent {
 	oldValue: any;
 }
 
+/**
+ * fired for each key pressed on the grid (not while a cell is edited), before the default handling
+ * call preventDefault to handle the key yourself
+ */
+
+export interface EvCellKey extends ComponentEvent {
+	key: string;				// "F2", "Enter", "a"...
+	row: number;				// selected cell, undefined if none
+	col: number;				// column index
+	uievent: KeyboardEvent;		// UI event that fire this event
+}
+
 interface CellEdit extends CellRef {
 	editor: Component;
 	initial?: string;	// text of the editor at start
@@ -214,6 +226,7 @@ export interface SpreadsheetEvents extends ComponentEvents {
 	contextMenu?: EvContextMenu;
 	selectionChange?: EvSelectionChange;
 	cellChange?: EvCellChange;
+	cellKey?: EvCellKey;
 }
 
 export interface SpreadsheetProps extends ComponentProps {
@@ -226,6 +239,7 @@ export interface SpreadsheetProps extends ComponentProps {
 	enterMove?: "down" | "right" | "none";
 
 	cellChange?: EventCallback<EvCellChange>;
+	cellKey?: EventCallback<EvCellKey>;
 	click?: EventCallback<EvClick>;
 	dblClick?: EventCallback<EvDblClick>;
 	contextMenu?: EventCallback<EvContextMenu>;
@@ -323,7 +337,7 @@ export class Spreadsheet<P extends SpreadsheetProps = SpreadsheetProps, E extend
 
 		this._columns = props.columns.map(x => x);
 
-		this.mapPropEvents(props, "click", "dblClick", "contextMenu", "selectionChange", "cellChange");
+		this.mapPropEvents(props, "click", "dblClick", "contextMenu", "selectionChange", "cellChange", "cellKey");
 
 		this.lock(true);
 		this.setAttribute("tabindex", 0);
@@ -365,6 +379,17 @@ export class Spreadsheet<P extends SpreadsheetProps = SpreadsheetProps, E extend
 			return;
 		}
 
+		// the application first
+		const cur = this._curCell( );
+		const kev: EvCellKey = { key: ev.key, row: cur?.row, col: cur?.col, uievent: ev };
+		this.fire( "cellKey", kev );
+
+		if( kev.defaultPrevented ) {
+			ev.preventDefault();
+			ev.stopPropagation();
+			return;
+		}
+
 		switch (ev.key) {
 			case "ArrowDown": {
 				this.navigate(kbNav.next);
@@ -1148,8 +1173,6 @@ export class Spreadsheet<P extends SpreadsheetProps = SpreadsheetProps, E extend
 					this._clearSelection( false );
 					this._addSelection(ref.ref,true);
 				}
-
-				this._toggleCell( ref.row, ref.col );
 			}
 		});
 
@@ -1170,7 +1193,8 @@ export class Spreadsheet<P extends SpreadsheetProps = SpreadsheetProps, E extend
 				const dev: EvDblClick = { context: { row: ref.row, col: ref.col } };
 				this.fire( "dblClick", dev );
 
-				if( !dev.defaultPrevented ) {
+				// checkboxes are toggled, other cells are edited
+				if( !dev.defaultPrevented && !this._toggleCell( ref.row, ref.col ) ) {
 					this.editCell( ref.row, ref.col );
 				}
 			}

package/src/core/core_router.ts

@@ -143,7 +143,13 @@ export class Router extends EventSource< RouterEvents > {
 		window.addEventListener('popstate', (event) => {
 			const url = this._getLocation( );
 			const found = this._find(url);
-		
+
+			if( found.handlers.length==0 ) {
+				console.log( 'route not found: '+url );
+				this.fire( "error", {code: 404, message: "route not found" } );
+				return;
+			}
+
 			found.handlers.forEach(h => {
 				h(found.params,url);
 			});
@@ -173,11 +179,17 @@ export class Router extends EventSource< RouterEvents > {
 
 
 	init() {
-		this.navigate( this._getLocation() );
+		// the page is already in the history: replace its entry instead of adding one
+		this.navigate( this._getLocation(), true, true );
 	}
 
 	private _getLocation( ) {
-		return this.m_useHash ? '/'+document.location.hash.substring(1) : document.location.pathname;
+		if( !this.m_useHash ) {
+			return document.location.pathname;
+		}
+
+		// "#home" and "#/home" are the same route
+		return '/'+document.location.hash.substring(1).replace( /^\/+/, '' );
 	}
 
 	/**