@stnd/launcher 1.0.0

package/README.md

@@ -0,0 +1,177 @@
+---
+title: "@stnd/launcher"
+aliases: []
+created: 2026-07-05 07:42
+modified: 2026-07-05 19:23
+last_audited: 2026-07-14
+audit_interval_days: 90
+next_audit: 2026-10-12
+audit_priority: 3
+maturity: tree
+mode: read
+publish: false
+status: active
+tags:
+  - package
+  - stnd
+theme: kernel
+type: package
+visibility: private
+---
+
+# @[stnd](../README)/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:
+
+```javascript
+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:
+
+```svelte
+<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 load={["::navigator", "::search"]} />
+```
+
+### Props
+
+| Prop          | Type                             | Default | Description                               |
+| :------------ | :------------------------------- | :------ | :---------------------------------------- |
+| `load`        | `string \| string[] \| function` | `null`  | Filter specific commands/views to load.   |
+| `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.     |
+
+## 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:
+
+```javascript
+// In your view component
+let { setSize } = $props();
+
+// Expand window
+setSize({ width: "wide", height: "tall" });
+```
+
+## Built-in Views
+
+### `::navigator` (Browser)
+
+The creation of a browser-like experience within the OS.
+
+- **Trigger**: `::navigator`
+- **Behavior**: Starts compact, expands to a full browser window when a URL is loaded.
+- **Usage**:
+
+  ```html
+  <button data-launcher-navigator="https://google.com">Open Google</button>
+  ```
+
+### `::settings` (Complex Layout Example)
+
+A reference implementation of a two-column sidebar layout acting as a *“Settings”* or *“Profile”* page. It demonstrates:
+
+- Sidebar navigation.
+- Dynamic responsive sizing (starts `wide` & `tall`).
+- Mock form controls.
+
+Source: `packages/views/SettingsView.svelte` (shipped by `@stnd/views`)
+
+## API (`launcher.ts`)
+
+```typescript
+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.
+
+## 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-navigator="url"`: Opens the navigator with a URL.
+- `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]