@notis_ai/cli 0.2.15 → 0.2.17

package/src/runtime/app-dev-server.js

@@ -12,9 +12,20 @@
  */
 
 import { createServer } from 'node:http';
-import { spawn } from 'node:child_process';
-import { existsSync, readFileSync, statSync, watch as fsWatch } from 'node:fs';
+import { execFileSync, spawn } from 'node:child_process';
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  watch as fsWatch,
+} from 'node:fs';
+import { freemem, loadavg, totalmem } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 
 import {
@@ -32,6 +43,7 @@ import {
   linkAppDevSessionTarget,
   readAppDevSessions,
 } from './app-dev-sessions.js';
+import { captureDesktopWatcherOwnership } from './app-dev-process-identity.js';
 
 const CONTENT_TYPES = {
   '.js': 'application/javascript; charset=utf-8',
@@ -44,6 +56,115 @@ const CLI_ROOT = resolve(RUNTIME_DIR, '../..');
 const REPO_ROOT = resolve(RUNTIME_DIR, '../../../..');
 const HARNESS_TEMPLATE_PATH = join(CLI_ROOT, 'template', '.harness', 'index.html.tmpl');
 const FALLBACK_REACT_VERSION = '19.0.0';
+const BUILD_PROCESS_STOP_GRACE_MS = 1_000;
+const DEV_DIAGNOSTIC_INTERVAL_MS = 30_000;
+const DEV_DIAGNOSTIC_MAX_BYTES = 20 * 1024 * 1024;
+
+function processGroupIsRunning(pid, signalProcess = process.kill) {
+  try {
+    signalProcess(-pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== 'ESRCH';
+  }
+}
+
+function readProcessGroupRssBytes(groupPids) {
+  if (process.platform === 'win32' || groupPids.size === 0) return new Map();
+  try {
+    const output = execFileSync('ps', ['-axo', 'pgid=,rss='], {
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const rssByGroup = new Map();
+    for (const line of output.split('\n')) {
+      const [rawGroupPid, rawRssKiB] = line.trim().split(/\s+/, 2);
+      const groupPid = Number.parseInt(rawGroupPid, 10);
+      if (!groupPids.has(groupPid)) continue;
+      const rssKiB = Number.parseInt(rawRssKiB, 10);
+      if (!Number.isFinite(rssKiB)) continue;
+      rssByGroup.set(groupPid, (rssByGroup.get(groupPid) || 0) + (rssKiB * 1024));
+    }
+    return rssByGroup;
+  } catch {
+    return new Map();
+  }
+}
+
+/**
+ * Stop the npm wrapper and every Vite/esbuild descendant it launched.
+ *
+ * Killing only the npm PID leaves its watch process alive after a Desktop host
+ * restart. Each watcher therefore owns a separate POSIX process group. Windows
+ * uses taskkill's tree mode for the equivalent cleanup.
+ */
+export async function terminateBuildProcessTree(child, {
+  platform = process.platform,
+  signalProcess = process.kill,
+  spawnProcess = spawn,
+  graceMs = BUILD_PROCESS_STOP_GRACE_MS,
+} = {}) {
+  const pid = child?.pid;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return;
+
+  if (platform === 'win32') {
+    await new Promise((resolvePromise) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        resolvePromise();
+      };
+      try {
+        const killer = spawnProcess('taskkill.exe', ['/pid', String(pid), '/t', '/f'], {
+          stdio: 'ignore',
+          windowsHide: true,
+        });
+        killer.once('error', () => {
+          try {
+            child.kill('SIGTERM');
+          } catch {
+            // The wrapper already exited.
+          }
+          finish();
+        });
+        killer.once('exit', finish);
+        setTimeout(finish, graceMs).unref?.();
+      } catch {
+        try {
+          child.kill('SIGTERM');
+        } catch {
+          // The wrapper already exited.
+        }
+        finish();
+      }
+    });
+    return;
+  }
+
+  try {
+    signalProcess(-pid, 'SIGTERM');
+  } catch (error) {
+    if (error?.code === 'ESRCH') return;
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      return;
+    }
+  }
+
+  const deadline = Date.now() + graceMs;
+  while (processGroupIsRunning(pid, signalProcess) && Date.now() < deadline) {
+    await delay(25);
+  }
+  if (!processGroupIsRunning(pid, signalProcess)) return;
+  try {
+    signalProcess(-pid, 'SIGKILL');
+  } catch (error) {
+    if (error?.code !== 'ESRCH') throw error;
+  }
+}
 
 function extFor(pathname) {
   const idx = pathname.lastIndexOf('.');
@@ -246,10 +367,11 @@ function buildHarnessDescriptor({ state, manifest, appConfig, route, scenario =
       icon: route.icon || null,
       parentSlug: route.parentSlug || null,
       default: Boolean(route.default),
+      resourceDeepLinks: route.resourceDeepLinks === true,
       collection: route.collection || null,
     },
     databases,
-    context: { collectionItem: null, screenshotScenario: scenario },
+    context: { collectionItem: null, resourceId: null, screenshotScenario: scenario },
     tools,
   };
 }
@@ -300,7 +422,7 @@ function renderHarnessHtml({ state, manifest, appConfig, route, harnessOptions,
 /**
  * Start the dev server for one or more apps.
  *
- * @param {{apps: Array<{slug: string, projectDir: string, appId?: string, targetAppId?: string, userId?: string, profileKey?: string, sessionId?: string, mountNonce?: string}>, port: number, watch?: boolean, sessionsFilePath?: string, harness?: { mode?: string, apiBase?: string, jwt?: string }, log?: (m: string) => void, logError?: (m: string) => void}} options
+ * @param {{apps: Array<{slug: string, projectDir: string, appId?: string, targetAppId?: string, userId?: string, profileKey?: string, sessionId?: string, mountNonce?: string}>, port: number, watch?: boolean, sessionsFilePath?: string, harness?: { mode?: string, apiBase?: string, jwt?: string }, diagnosticsFile?: string | null, desktopOwnerId?: string | null, desktopOwnerScope?: string | null, terminateBuildProcess?: typeof terminateBuildProcessTree, log?: (m: string) => void, logError?: (m: string) => void}} options
  */
 export async function startAppDevServer({
   apps,
@@ -308,6 +430,10 @@ export async function startAppDevServer({
   watch = true,
   sessionsFilePath,
   harness = {},
+  diagnosticsFile = process.env.NOTIS_DEV_DIAGNOSTICS_FILE || null,
+  desktopOwnerId = process.env.NOTIS_APPS_DEV_DESKTOP_OWNER_ID || null,
+  desktopOwnerScope = process.env.NOTIS_APPS_DEV_DESKTOP_OWNER_SCOPE || null,
+  terminateBuildProcess = terminateBuildProcessTree,
   log = (msg) => process.stdout.write(`${msg}\n`),
   logError = (msg) => process.stderr.write(`${msg}\n`),
 }) {
@@ -316,6 +442,9 @@ export async function startAppDevServer({
   }
 
   const appState = new Map();
+  let diagnosticsTimer = null;
+  let diagnosticWriteFailed = false;
+  let serverClosing = false;
   // Sidebar reconciliation needs one stream for the shared host, not one
   // long-lived HTTP/1.1 connection per discovered app. Keeping a stream per
   // app exhausts Chromium's per-origin connection pool and can indefinitely
@@ -344,17 +473,68 @@ export async function startAppDevServer({
       prepareTimer: null,
       reloadTimer: null,
       buildProcess: null,
+      watcherOwnership: null,
       lastMtimeMs: 0,
       watchPollTimer: null,
       bundleReady: false,
       bundleReadyPromise,
       resolveBundleReady,
+      buildProcessStopPromise: null,
     };
   };
   for (const app of apps) {
     appState.set(app.slug, createAppState(app));
   }
 
+  function writeDevDiagnostic(event) {
+    if (!diagnosticsFile) return;
+    const memory = process.memoryUsage();
+    const watcherPids = new Set(
+      [...appState.values()]
+        .map((state) => state.buildProcess?.pid)
+        .filter((pid) => Number.isSafeInteger(pid) && pid > 0),
+    );
+    const watcherGroupRss = readProcessGroupRssBytes(watcherPids);
+    const record = {
+      at: new Date().toISOString(),
+      event,
+      host_pid: process.pid,
+      parent_pid: process.ppid,
+      rss_bytes: memory.rss,
+      heap_used_bytes: memory.heapUsed,
+      heap_total_bytes: memory.heapTotal,
+      external_bytes: memory.external,
+      system_free_bytes: freemem(),
+      system_total_bytes: totalmem(),
+      load_average_1m: loadavg()[0],
+      watcher_groups_rss_bytes: [...watcherGroupRss.values()].reduce((total, rss) => total + rss, 0),
+      apps: [...appState.values()].map((state) => ({
+        slug: state.slug,
+        project_dir: state.projectDir,
+        watcher_pid: state.buildProcess?.pid || null,
+        watcher_exit_code: state.buildProcess?.exitCode ?? null,
+        watcher_signal: state.buildProcess?.signalCode ?? null,
+        watcher_group_rss_bytes: watcherGroupRss.get(state.buildProcess?.pid) ?? null,
+        bundle_ready: state.bundleReady,
+      })),
+    };
+    try {
+      mkdirSync(dirname(diagnosticsFile), { recursive: true, mode: 0o700 });
+      if (existsSync(diagnosticsFile) && statSync(diagnosticsFile).size >= DEV_DIAGNOSTIC_MAX_BYTES) {
+        const previous = `${diagnosticsFile}.previous`;
+        rmSync(previous, { force: true });
+        renameSync(diagnosticsFile, previous);
+      }
+      appendFileSync(diagnosticsFile, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+      diagnosticWriteFailed = false;
+    } catch (error) {
+      if (!diagnosticWriteFailed) {
+        diagnosticWriteFailed = true;
+        logError(`[notis apps dev] persistent diagnostics failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+
   function broadcastReload(slug) {
     const state = appState.get(slug);
     if (!state) return;
@@ -827,16 +1007,39 @@ export async function startAppDevServer({
       watchManifestInputs(state);
       pollForBundleAndWatch(state);
 
-      state.buildProcess = spawn('npm', ['run', 'build', '--', '--watch'], {
+      const buildProcess = spawn('npm', ['run', 'build', '--', '--watch'], {
         cwd: state.projectDir,
+        detached: process.platform !== 'win32',
         stdio: 'inherit',
         env: { ...process.env, NOTIS_DEV: '1' },
       });
+      state.buildProcess = buildProcess;
+      for (let attempt = 0; attempt < 5 && !state.watcherOwnership; attempt += 1) {
+        state.watcherOwnership = captureDesktopWatcherOwnership({
+          pid: buildProcess.pid,
+          projectDir: state.projectDir,
+          desktopOwnerId,
+          desktopOwnerScope,
+        });
+        if (!state.watcherOwnership && attempt < 4) await delay(10);
+      }
 
-      state.buildProcess.on('exit', (code) => {
+      buildProcess.on('exit', (code) => {
         if (code !== 0 && code !== null) {
           logError(`[notis apps dev] ${state.slug}: vite build --watch exited with code ${code}`);
         }
+        if (!serverClosing) {
+          if (state.buildProcess === buildProcess) state.buildProcess = null;
+          const stopPromise = terminateBuildProcess(buildProcess).catch((error) => {
+            logError(`[notis apps dev] ${state.slug}: watcher cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+          });
+          state.buildProcessStopPromise = stopPromise;
+          void stopPromise.finally(() => {
+            if (state.buildProcessStopPromise === stopPromise) {
+              state.buildProcessStopPromise = null;
+            }
+          });
+        }
       });
     } else {
       updateBundleDir(state, resolveBundleDir(state));
@@ -845,6 +1048,12 @@ export async function startAppDevServer({
     log(`[notis apps dev] ${state.slug}: serving bundle at http://127.0.0.1:${port}/a/${state.slug}/bundle/app.js`);
   }
 
+  writeDevDiagnostic('started');
+  if (diagnosticsFile) {
+    diagnosticsTimer = setInterval(() => writeDevDiagnostic('sample'), DEV_DIAGNOSTIC_INTERVAL_MS);
+    diagnosticsTimer.unref?.();
+  }
+
   return {
     port,
     updateApp(slug, updates = {}) {
@@ -866,7 +1075,19 @@ export async function startAppDevServer({
       if (!state) return Promise.reject(new Error(`unknown app: ${slug}`));
       return state.bundleReadyPromise;
     },
+    getWatcherOwnership(slug) {
+      const state = appState.get(slug);
+      if (!state) throw new Error(`unknown app: ${slug}`);
+      return state.watcherOwnership ? { ...state.watcherOwnership } : null;
+    },
     async close() {
+      serverClosing = true;
+      if (diagnosticsTimer) {
+        clearInterval(diagnosticsTimer);
+        diagnosticsTimer = null;
+      }
+      writeDevDiagnostic('stopping');
+      const buildProcessStops = [];
       for (const state of appState.values()) {
         if (state.prepareTimer) clearTimeout(state.prepareTimer);
         if (state.reloadTimer) clearTimeout(state.reloadTimer);
@@ -894,10 +1115,16 @@ export async function startAppDevServer({
           }
         }
         state.sseClients.clear();
-        if (state.buildProcess && state.buildProcess.exitCode === null) {
-          state.buildProcess.kill('SIGTERM');
+        if (state.buildProcessStopPromise) {
+          buildProcessStops.push(state.buildProcessStopPromise);
+        }
+        if (state.buildProcess) {
+          const buildProcess = state.buildProcess;
+          state.buildProcess = null;
+          buildProcessStops.push(terminateBuildProcess(buildProcess));
         }
       }
+      await Promise.allSettled(buildProcessStops);
       for (const res of hostSseClients) {
         try {
           res.end();
@@ -907,6 +1134,7 @@ export async function startAppDevServer({
       }
       hostSseClients.clear();
       await new Promise((resolvePromise) => server.close(() => resolvePromise()));
+      writeDevDiagnostic('stopped');
     },
   };
 }

package/src/runtime/app-platform.js

@@ -680,6 +680,9 @@ function validateConfiguredRoutes(routes) {
     if (route.default) {
       defaultCount += 1;
     }
+    if (route.resourceDeepLinks !== undefined && typeof route.resourceDeepLinks !== 'boolean') {
+      throw usageError(`Route "${route.slug}" resourceDeepLinks must be a boolean.`);
+    }
   }
 
   if (defaultCount !== 1) {
@@ -799,6 +802,7 @@ export function generateManifest(appConfig, projectDir) {
       icon: route.icon || null,
       parentSlug: route.parentSlug || null,
       default: route.default || false,
+      resourceDeepLinks: route.resourceDeepLinks === true,
       export_name: route.exportName || route.export_name || exportNameFromPath(route.path),
       collection: route.collection || null,
     };
@@ -902,6 +906,24 @@ export function generateManifest(appConfig, projectDir) {
   };
 }
 
+/**
+ * Keep the persisted app row's presentation metadata aligned with the bundle
+ * manifest. The app slug remains the stable identity; title/name is only the
+ * user-facing label.
+ */
+export function appRowFieldsFromManifest(manifest) {
+  const app = manifest?.app && typeof manifest.app === 'object' ? manifest.app : {};
+  const displayName = typeof app.title === 'string' && app.title.trim()
+    ? app.title.trim()
+    : typeof app.name === 'string' && app.name.trim()
+      ? app.name.trim()
+      : null;
+  return {
+    ...(displayName ? { name: displayName } : {}),
+    accent: app.accent ?? null,
+  };
+}
+
 export function normalizeAppToolBindings(bindings) {
   return (Array.isArray(bindings) ? bindings : [])
     .map((binding) => {
@@ -2818,7 +2840,7 @@ async function updateAppVersion(supabaseUrl, supabaseKey, appId, newVersion, man
     },
     body: JSON.stringify({
       manifest: { ...manifest, version: newVersion },
-      accent: manifest?.app?.accent ?? null,
+      ...appRowFieldsFromManifest(manifest),
       updated_at: new Date().toISOString(),
     }),
   });

package/src/runtime/profiles.js

@@ -485,10 +485,15 @@ export function updateConfig(updater) {
 }
 
 /**
- * Remove only worktree-owned profiles without normalizing the rest of the
- * shared file. Archive cleanup can run before a packaged Desktop upgrade has
- * migrated its legacy `jwt`; preserving unknown/raw fields here keeps that
- * migrate-then-strip handoff intact.
+ * Remove every profile owned by one worktree, plus stale localhost stubs that
+ * use one of that worktree's generated profile names. Older builds sometimes
+ * lost `dev_workspace_root`, so requiring the ownership marker alone leaves a
+ * dead local profile behind after archive.
+ *
+ * Do this without normalizing the rest of the shared file. Archive cleanup can
+ * run before a packaged Desktop upgrade has migrated its legacy `jwt`;
+ * preserving unknown/raw fields here keeps that migrate-then-strip handoff
+ * intact.
  */
 export function removeOwnedDevProfiles(profileNames, workspaceRoot) {
   return withConfigWriteLock((configFile) => {
@@ -502,16 +507,19 @@ export function removeOwnedDevProfiles(profileNames, workspaceRoot) {
       return [];
     }
 
+    const generatedNames = new Set(profileNames);
     const removed = [];
-    for (const name of profileNames) {
-      const profile = Object.hasOwn(raw.profiles, name) ? raw.profiles[name] : null;
-      if (
-        !profile
-        || typeof profile !== 'object'
-        || profile.dev_workspace_root !== workspaceRoot
-      ) {
+    for (const [name, profile] of Object.entries(raw.profiles)) {
+      if (!profile || typeof profile !== 'object') {
         continue;
       }
+
+      const ownedByWorkspace = profile.dev_workspace_root === workspaceRoot;
+      const staleGeneratedLocalProfile = generatedNames.has(name)
+        && !profile.dev_workspace_root
+        && isLocalApiBase(profile.api_base);
+      if (!ownedByWorkspace && !staleGeneratedLocalProfile) continue;
+
       delete raw.profiles[name];
       removed.push(name);
       if (raw.current_profile === name) raw.current_profile = DEFAULT_PROFILE;

package/src/runtime/sync-skills.js

@@ -84,6 +84,25 @@ async function writeLockOwnerAtomically(lockDirectory, owner) {
   await rename(temporaryOwnerPath, ownerPath);
 }
 
+async function releaseOwnedLock(lockDirectory, ownerId) {
+  const owner = await lockSnapshot(lockDirectory);
+  if (owner?.id !== ownerId) return;
+
+  const quarantineRoot = join(dirname(lockDirectory), '.stale-operation-locks');
+  const releasedDirectory = join(quarantineRoot, `released.${ownerId}`);
+  await mkdir(quarantineRoot, { recursive: true, mode: 0o700 });
+  try {
+    // Moving the owned directory releases the shared pathname atomically.
+    // Delete only the private destination so a waiter can safely acquire a new
+    // lock without racing this owner's recursive cleanup.
+    await rename(lockDirectory, releasedDirectory);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return;
+    throw error;
+  }
+  await rm(releasedDirectory, { recursive: true, force: true });
+}
+
 /** Serialize Desktop and terminal skill sync across processes on one Mac. */
 export async function withSkillSyncLock(callback, {
   home = homedir(),
@@ -174,10 +193,7 @@ export async function withSkillSyncLock(callback, {
     heartbeatStopped = true;
     clearInterval(heartbeat);
     await heartbeatInFlight;
-    const owner = await lockSnapshot(lockDirectory);
-    if (owner?.id === ownerId) {
-      await rm(lockDirectory, { recursive: true, force: true });
-    }
+    await releaseOwnedLock(lockDirectory, ownerId);
   }
 }
 

package/template/packages/sdk/src/components/MultiSelectActionBar.tsx

@@ -49,10 +49,12 @@ const containerBaseStyle: CSSProperties = {
 };
 
 const countStyle: CSSProperties = {
+  flexShrink: 0,
   padding: '0 0.5rem',
   fontSize: '12px',
   fontWeight: 500,
   fontVariantNumeric: 'tabular-nums',
+  whiteSpace: 'nowrap',
   color: 'color-mix(in srgb, hsl(var(--background)) 70%, transparent)',
 };
 
@@ -64,6 +66,7 @@ const dividerStyle: CSSProperties = {
 };
 
 const baseButtonStyle: CSSProperties = {
+  flexShrink: 0,
   display: 'inline-flex',
   alignItems: 'center',
   gap: '0.375rem',
@@ -75,6 +78,7 @@ const baseButtonStyle: CSSProperties = {
   cursor: 'pointer',
   fontSize: '13px',
   fontFamily: 'inherit',
+  whiteSpace: 'nowrap',
   transition: 'background-color 120ms ease, color 120ms ease',
 };
 
@@ -188,7 +192,9 @@ function ActionButton({ action }: { action: MultiSelectAction }) {
       onBlur={() => setHover(false)}
       style={buttonStyle}
     >
-      {action.icon ? <span aria-hidden style={iconSlotStyle}>{action.icon}</span> : null}
+      {!action.shortcut && action.icon ? (
+        <span aria-hidden style={iconSlotStyle}>{action.icon}</span>
+      ) : null}
       {display ? <kbd aria-hidden style={keycapStyle}>{display}</kbd> : null}
       <span>{action.pending ? `${action.label}…` : action.label}</span>
     </button>

package/template/packages/sdk/src/config.ts

@@ -40,6 +40,12 @@ export interface NotisRouteConfig {
   icon?: string;
   parentSlug?: string | null;
   default?: boolean;
+  /**
+   * Allow the host to address an app-owned resource on this route through the
+   * canonical `?resource=<id>` deep link. Read the incoming id with
+   * `useNotis().resourceId`.
+   */
+  resourceDeepLinks?: boolean;
   exportName?: string;
   collection?: {
     database: string;

package/template/packages/sdk/src/hooks/useCollectionInteractions.ts

@@ -64,8 +64,8 @@ export interface CollectionKeyboardShortcuts {
   clear: string | false;
   selectAll: string | false;
   toggle: string | false;
-  extendNext: string | false;
-  extendPrevious: string | false;
+  extendNext: string | string[] | false;
+  extendPrevious: string | string[] | false;
   next: string | string[] | false;
   previous: string | string[] | false;
   up: string | false;
@@ -158,8 +158,8 @@ const DEFAULT_SHORTCUTS: CollectionKeyboardShortcuts = {
   clear: 'Escape',
   selectAll: 'Mod+A',
   toggle: 'X',
-  extendNext: 'Shift+ArrowDown',
-  extendPrevious: 'Shift+ArrowUp',
+  extendNext: ['Shift+ArrowDown', 'Shift+ArrowRight'],
+  extendPrevious: ['Shift+ArrowUp', 'Shift+ArrowLeft'],
   next: 'J',
   previous: 'K',
   up: 'ArrowUp',
@@ -169,6 +169,16 @@ const DEFAULT_SHORTCUTS: CollectionKeyboardShortcuts = {
   activate: 'Enter',
 };
 
+function filterShortcutKeys(
+  keys: string | string[] | false,
+  predicate: (key: string) => boolean,
+): string | string[] | false {
+  if (!keys) return false;
+  const filtered = (Array.isArray(keys) ? keys : [keys]).filter(predicate);
+  if (filtered.length === 0) return false;
+  return filtered.length === 1 ? filtered[0] : filtered;
+}
+
 function setsEqual(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
   if (a.size !== b.size) return false;
   for (const id of a) if (!b.has(id)) return false;
@@ -442,14 +452,20 @@ export function useCollectionInteractions<T>(
       if (!keys) return;
       definitions.push({ id, label, keys, onTrigger });
     };
+    const extendRight = filterShortcutKeys(keyboard.extendNext, (key) => key.toLowerCase().endsWith('arrowright'));
+    const extendDown = filterShortcutKeys(keyboard.extendNext, (key) => !key.toLowerCase().endsWith('arrowright'));
+    const extendLeft = filterShortcutKeys(keyboard.extendPrevious, (key) => key.toLowerCase().endsWith('arrowleft'));
+    const extendUp = filterShortcutKeys(keyboard.extendPrevious, (key) => !key.toLowerCase().endsWith('arrowleft'));
     add('collection.clear', 'Clear selection', keyboard.clear, clear);
     add('collection.select-all', 'Select all visible items', selectionMode === 'none' ? false : keyboard.selectAll, selectAll);
     add('collection.toggle', 'Toggle active item', selectionMode === 'none' ? false : keyboard.toggle, () => {
       const id = activeIdRef.current ?? anchorIdRef.current;
       if (id) toggle(id);
     });
-    add('collection.extend-next', 'Extend selection down', selectionMode !== 'multiple' ? false : keyboard.extendNext, () => moveActive('down', true));
-    add('collection.extend-previous', 'Extend selection up', selectionMode !== 'multiple' ? false : keyboard.extendPrevious, () => moveActive('up', true));
+    add('collection.extend-down', 'Extend selection down', selectionMode !== 'multiple' ? false : extendDown, () => moveActive('down', true));
+    add('collection.extend-right', 'Extend selection right', selectionMode !== 'multiple' ? false : extendRight, () => moveActive('right', true));
+    add('collection.extend-up', 'Extend selection up', selectionMode !== 'multiple' ? false : extendUp, () => moveActive('up', true));
+    add('collection.extend-left', 'Extend selection left', selectionMode !== 'multiple' ? false : extendLeft, () => moveActive('left', true));
     add('collection.next', 'Next item', keyboard.next, () => moveActive('next'));
     add('collection.previous', 'Previous item', keyboard.previous, () => moveActive('previous'));
     add('collection.up', 'Move up', keyboard.up, () => moveActive('up'));
@@ -634,6 +650,7 @@ export function useCollectionInteractions<T>(
     },
     onKeyDown: (event: ReactKeyboardEvent) => {
       if (event.key !== ' ' || event.metaKey || event.ctrlKey || event.altKey) return;
+      if (event.target !== event.currentTarget) return;
       event.preventDefault();
       if (selectionMode === 'none') activate(id);
       else toggle(id);

package/template/packages/sdk/src/hooks/useNotis.ts

@@ -12,6 +12,8 @@ interface NotisContext {
   databases: DatabaseDescriptor[];
   /** Selected collection item for the current route, when applicable. */
   collectionItem: CollectionItemDetail | null;
+  /** Resource requested through this route's canonical deep link. */
+  resourceId: string | null;
   /** Whether the runtime is loaded and available. */
   ready: boolean;
 }
@@ -29,6 +31,7 @@ export function useNotis(): NotisContext {
     route: runtime?.route ?? null,
     databases: runtime?.databases ?? [],
     collectionItem: runtime?.context?.collectionItem ?? null,
+    resourceId: runtime?.context?.resourceId ?? null,
     ready: runtime !== null,
   };
 }

package/template/packages/sdk/src/hooks/useNotisNavigation.ts

@@ -5,7 +5,7 @@ import { useNotisRuntime } from '../provider';
 
 interface NavigationActions {
   /** Navigate to a route within the app by its path. */
-  toRoute: (path: string) => void;
+  toRoute: (path: string, options?: { resourceId?: string | null }) => void;
   /** Navigate to a document detail view. */
   toDocument: (documentId: string, title?: string | null) => void;
   /** Navigate to the app's default route. */
@@ -25,11 +25,14 @@ interface NavigationActions {
 export function useNotisNavigation(): NavigationActions {
   const runtime = useNotisRuntime();
 
-  const toRoute = useCallback((path: string) => {
+  const toRoute = useCallback((path: string, options?: { resourceId?: string | null }) => {
     if (runtime?.navigate) {
-      runtime.navigate({ kind: 'route', path });
+      runtime.navigate({ kind: 'route', path, resourceId: options?.resourceId ?? null });
     } else if (typeof window !== 'undefined') {
-      window.location.href = path;
+      const url = new URL(path, window.location.href);
+      if (options?.resourceId) url.searchParams.set('resource', options.resourceId);
+      else url.searchParams.delete('resource');
+      window.location.href = url.toString();
     }
   }, [runtime]);
 

package/template/packages/sdk/src/interactions/shortcuts.tsx

@@ -182,7 +182,13 @@ export function isEditableShortcutEvent(event: Event): boolean {
     if (!(target instanceof HTMLElement)) return false;
     if (target.isContentEditable || target.getAttribute('contenteditable') === 'true') return true;
     const tag = target.tagName;
-    return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || tag === 'BUTTON' || tag === 'SUMMARY') {
+      return true;
+    }
+    if (tag === 'A' && target.hasAttribute('href')) return true;
+    return ['button', 'link', 'menuitem', 'switch', 'tab'].includes(
+      target.getAttribute('role') || '',
+    );
   });
 }