title: "@stnd/launcher" aliases: [] created: 2026-07-05 07:42 modified: 2026-09-16T17:28:40.341Z last_audited: 2026-07-14 audit_interval_days: 90 next_audit: 2026-10-12 audit_priority: 3 maturity: tree mode: read publish: true status: active tags:

• package
• stnd theme: maker type: package visibility: public garden-url: https://standard.garden/@francis/readme garden-short: https://stnd.gd/wAgx4e permalink: readme

@stnd/launcher

The Universal Command Palette engine for the Standard Framework.

@stnd/launcher provides a centralized interface for command execution, navigation, and view management. It adheres to the “Standard” design philosophy: clean, keyboard-centric, and extensible.

ELI5

Cmd+K on any Standard site — that’s this. A registry holds every command and “view” (a full Svelte panel, like Settings or the file navigator) any loaded module has registered; the palette searches across all of it. A module adds its own command by calling register() once; it shows up in the palette for everyone, no wiring needed on the app’s side.

It’s already on — @stnd/launcher is a Gold Standard module. To add your own command from inside a module:

import { register } from "@stnd/launcher";
register("::my-command", { title: "Do the thing", icon: "star" }, () => doTheThing());

Architecture

The Launcher follows a Reactive Core pattern:

• Engine (launcher.ts): Manages state (registry, palette, views), search logic, and public API.
• UI (Launcher.svelte): A “dumb” view component that subscribes to the engine state and renders the appropriate interface.
• Modules: Extend the launcher by registering commands and views via virtual:stnd/components.

Usage

Import and mount the <Launcher /> component in your layout:

<script>
  import Launcher from "@stnd/launcher/Launcher.svelte";
</script>

<!--
  load: Optional allow-list of commands/views to enable.
  If omitted, all registered commands are loaded.
-->
<Launcher />

Props

| Prop | Type | Default | Description | | :------------ | :------------------------------- | :------ | :----------------------------------------------------- | | load | string \| string[] \| function | null | Accepted for backward compatibility; it has no effect. | | userStore | readable | null | Svelte store containing the current user. | | searchNotes | function | null | Async function to search app content. | | WelcomeView | Component | null | Custom component for the empty state. | | FooterView | Component | null | Custom component for the optional launcher footer. | | footer | Snippet | null | Svelte 5 snippet for custom footer content. | | showFooter | boolean \| "always" | false | Enable built-in footer (navigation hints & info). |

Core Concepts

Registry

The registry holds all available Commands and Views.

• Commands: Executable actions (functions).
• Views: Interactive components rendered within the launcher window.

Sizing

The launcher window adapts to its content.

• Standard: Default command palette size.
• Wide: Extended width for rich content.
• Tall: Extended height for browsing.

Views can request size changes dynamically:

// In your view component
let { setSize } = $props();

// Expand window
setSize({ width: "wide", height: "tall" });

API (launcher.ts)

import {
  initLauncher,
  register,
  launcherView,
  launcherToggle,
  setSize,
} from "@stnd/launcher";

initLauncher(options)

Initialize the engine with app-specific logic.

register(trigger, meta, handler)

Register a new command or view.

• trigger: Unique ID (e.g., ::my-view).
• meta: Configuration object for the command/view.
  • title (string): Display name.
  • desc (string): Short description.
  • icon (string): Icon identifier.
  • size (object): Window dimensions { width, height }.
  • requireAuth (boolean): If true, only shown to authenticated users.
  • requireGuest (boolean): If true, only shown to unauthenticated users.
  • requireRole (string | string[]): Restricts visibility to users with specific roles (e.g., "admin").
  • context (string | string[]): Restricts visibility to specific application states (e.g., "editor").
• handler: Function (action) or Svelte Component (view).

launcherView(view, props)

Switch the active view.

• view: Trigger ID of the view.
• props: Data to pass to the view component.

Keyboard: Esc

The launcher registers Esc with the keyboard module:

• Default behavior: Steps back in browser history when the launcher is closed.
• Custom override (stnd:escape): Before stepping back, the launcher dispatches a cancelable stnd:escape event on window. Any app that wants Esc to navigate elsewhere (e.g. returning to an overview panel instead of browser history) can listen for stnd:escape and call event.preventDefault().
• Production example: The àVélo app intercepts stnd:escape in apps/avelo-stat/modules/core/scripts/shortcuts.ts to return to its station overview.

Data Attributes

The UI listens for clicks on elements with specific data attributes:

• data-launcher-toggle: Toggles the launcher.
• data-launcher-view="::id": Opens a specific view.
• data-launcher-prompt="text": Opens launcher with pre-filled text.

Notes / Observations

(jot down anything noticed here — quirks, gotchas, ideas)

Todo

• [ ] Nothing tracked yet. [priority:: 3] [token_scale:: 3] [created:: 2026-07-14] [area:: framework]