Asyar

https://github.com/xoshbin/asyar
Admin
Asyar is a local-first, cross-platform open-source alternative to Raycast - a fast, extensible...
Tokens:128,023
Snippets:1,345
Trust Score:8.5
Update:4 months ago
Show doc for...
Tokens:
Raw
### Clone Asyar Repository and Setup

Source: https://github.com/xoshbin/asyar/blob/main/README.md

Clone the Asyar repository and run the setup script to install dependencies and configure the development environment. This includes downloading sidecar binaries.

```bash
git clone https://github.com/Xoshbin/asyar.git
cd asyar
node setup.mjs
```

--------------------------------

### Example Script Header

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/script-headers.md

A basic example demonstrating the shebang, title, icon, and argument directives for a script.

```bash
#!/bin/bash
# @asyar.title Search Google
# @asyar.icon 🔍
# @asyar.argument:1 { "name": "query", "type": "text", "placeholder": "Search..." }

open "https://www.google.com/search?q=$1"
```

--------------------------------

### Complete Manifest Example

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/manifest.md

This is a comprehensive example of a manifest file for an extension. It showcases various fields including metadata, background processes, permissions, preferences, and commands.

```json
{
  "id": "com.yourname.note-search",
  "name": "Note Search",
  "version": "2.2.0",
  "description": "Search and preview your local Markdown notes.",
  "author": "Jane Dev",
  "icon": "📝",
  "type": "extension",
  "background": { "main": "dist/worker.js" },
  "searchable": true,
  "asyarSdk": "^2.7.0",
  "minAppVersion": "1.0.0",
  "platforms": ["macos", "linux"],
  "permissions": ["network", "notifications:send"],
  "preferences": [
    {
      "name": "notesDirectory",
      "type": "directory",
      "title": "Notes directory",
      "description": "Root folder to index.",
      "required": true
    },
    {
      "name": "previewFontSize",
      "type": "number",
      "title": "Preview font size",
      "default": 14
    }
  ],
  "actions": [
    {
      "id": "open-settings",
      "title": "Extension Settings",
      "description": "Configure Note Search preferences",
      "icon": "icon:settings",
      "shortcut": "⌘,",
      "category": "System"
    }
  ],
  "commands": [
    {
      "id": "search",
      "name": "Search Notes",
      "description": "Live search your local notes as you type",
      "mode": "view",
      "component": "DetailView",
      "icon": "🔍",
      "actions": [
        {
          "id": "export-note",
          "title": "Export Note",
          "description": "Save the selected note as a file",
          "icon": "icon:download",
          "shortcut": "⌘⇧E",
          "category": "Share"
        }
      ]
    },
    {
      "id": "new-note",
      "name": "New Note",
      "description": "Create a new blank note",
      "mode": "background",
      "icon": "✏️"
    },
    {
      "id": "sync-notes",
      "name": "Sync Notes",
      "description": "Periodically sync notes from remote",
      "mode": "background",
      "schedule": { "intervalSeconds": 300 },
      "preferences": [
        {
          "name": "remoteUrl",
          "type": "textfield",
          "title": "Remote sync URL"
        }
      ]
    }
  ]
}
```

--------------------------------

### Minimal InteropService Usage Example

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/interop-service.md

Demonstrates how to get the InteropService and use launchCommand to open a view or execute a command with arguments in another extension.

```typescript
import type { IInteropService } from 'asyar-sdk';

const interop = context.getService<IInteropService>('interop');

// Open the clipboard-history extension's default view
await interop.launchCommand('org.asyar.clipboard', 'show-clipboard');

// Pass arguments to the target command
await interop.launchCommand('com.example.calc', 'run', { query: '5+3' });
```

--------------------------------

### Starting and Managing a Run

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/run-service.md

Demonstrates how to start a custom run, handle cancellation requests, write output, and signal completion or failure.

```typescript
import type { IRunService } from 'asyar-sdk/contracts';

const runs = context.getService<IRunService>('runs');

const handle = await runs.start({
  label: 'Syncing contacts',
  kind: 'custom',
  cancellable: true,
});

handle.onCancel(() => {
  // Stop your work when the user requests cancellation.
  controller.abort();
});

try {
  await handle.write('Fetching remote data…');
  await doWork(handle);
  await handle.done();
} catch (err) {
  await handle.fail(err instanceof Error ? err.message : String(err));
}
```

--------------------------------

### Install Asyar SDK CLI

Source: https://github.com/xoshbin/asyar/blob/main/asyar-sdk/README.md

Installs the Asyar SDK command-line interface globally. This is typically done once to access the CLI tools.

```bash
npm install -g asyar-sdk   # installs the CLI globally
```

--------------------------------

### Parameterized Permissions Example

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/manifest.md

Demonstrates how to declare a permission and provide specific arguments for it, such as file watch patterns for the `fs:watch` permission.

```json
{
  "permissions": ["fs:watch"],
  "permissionArgs": {
    "fs:watch": ["~/Library/Shortcuts/**", "~/.ssh/config"]
  }
}
```

--------------------------------

### EntitlementService Usage Example

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/entitlement-service.md

Demonstrates how to declare permissions, get the EntitlementService, and use its check and getAll methods in an extension.

```json
// manifest.json
{
  "permissions": ["entitlements:read"]
}
```

```typescript
// main.ts
const entitlements = context.getService<IEntitlementService>('entitlements');

// Check before calling a paid API
if (await entitlements.check('ai:chat')) {
  // proceed with AI call
} else {
  await notifications.notify({
    title: 'Upgrade required',
    body: 'AI chat requires an active subscription.'
  });
}

// Inspect all active entitlements
const all = await entitlements.getAll();
// e.g. ["sync:settings", "ai:chat"]
```

--------------------------------

### Install Extension from Local File

Source: https://github.com/xoshbin/asyar/blob/main/docs/explanation/host-startup-and-installation.md

This describes the user interaction and frontend calls involved when installing an extension from a local .asyar file.

```typescript
calls `show_open_extension_dialog` Tauri command (returns the selected path), then `install_extension_from_file` with that path.
```

--------------------------------

### Manifest Example for Extension and Command IDs

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/interop-service.md

Shows how to find the extensionId and commandId from an extension's manifest.json file.

```json
{
  "id": "com.example.calc",
  "commands": [
    { "id": "run", "name": "Calculate", "description": "…" }
  ]
}
```

--------------------------------

### Register and Run Asyar Project

Source: https://github.com/xoshbin/asyar/blob/main/docs/tutorials/manual-setup.md

Commands to link your project path with Asyar and start the development watcher for automatic rebuilds on save.

```bash
# Register the project path with Asyar (only needed for manually created extensions)
asyar link

# Start the file watcher — rebuild on every save
pnpm dev
```

--------------------------------

### Extension Manifest Example

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/extension-types/extension.md

Defines an extension with background and view commands, permissions, and SDK version.

```json
{
  "id": "com.yourname.pomodoro",
  "name": "Pomodoro",
  "version": "2.1.0",
  "description": "Focus timer with notifications.",
  "author": "Your Name",
  "icon": "🍅",
  "type": "extension",
  "asyarSdk": "^2.1.0",
  "background": { "main": "dist/worker.js" },
  "permissions": ["notifications:send", "timers:schedule", "timers:cancel"],
  "commands": [
    { "id": "open",  "name": "Open Pomodoro", "mode": "view", "component": "PomodoroView", "icon": "🍅" },
    { "id": "start", "name": "Start Focus",   "mode": "background", "icon": "▶️" },
    { "id": "stop",  "name": "Stop Focus",    "mode": "background" },
    { "id": "tick",  "name": "Tick",          "mode": "background", "schedule": { "intervalSeconds": 60 } }
  ]
}
```

--------------------------------

### Rust Processing for Local File Installation

Source: https://github.com/xoshbin/asyar/blob/main/docs/explanation/host-startup-and-installation.md

Details the validation, extraction, and installation steps performed by the Rust backend when handling a local .asyar file.

```rust
- Validates the file has a `.asyar` extension.
- Extracts the ZIP to a temp directory (reuses `extract_zip()` with zip-slip protection).
- Reads and validates `manifest.json` (reuses `read_manifest()` + `validate_compatibility()`).
- Runs `validate_package_structure()`:
  - Required fields: `id`, `name`, `version`, `type`.
  - ID format: alphanumeric, hyphens, dots, underscores — no `..`.
  - Type-specific: `theme` → requires `theme.json`; `view`/`result` → requires `index.html`.
- Runs `validate_theme_json()` for theme packages: validates font file extensions (`.woff2`, `.ttf`, `.otf` only), path traversal, and CSS injection in font family names.
- Version conflict check: same ID + higher version → upgrade; same/lower → error; new ID → fresh install.
- Moves the extracted directory to `$APP_DATA/extensions/{id}/`.
```

--------------------------------

### Declare Extension and Command Preferences

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/preferences.md

Example manifest.json snippet showing how to declare both extension-level and command-level preferences with various types and configurations.

```jsonc
{
  "id": "org.example.weather",
  "preferences": [
    {
      "name": "apiKey",
      "type": "password",
      "title": "OpenWeather API Key",
      "description": "Get one at openweathermap.org/api",
      "required": true
    },
    {
      "name": "units",
      "type": "dropdown",
      "title": "Temperature Units",
      "default": "metric",
      "data": [
        { "value": "metric", "title": "Celsius" },
        { "value": "imperial", "title": "Fahrenheit" }
      ]
    }
  ],
  "commands": [
    {
      "id": "forecast",
      "name": "Show Forecast",
      "description": "Show the 5-day forecast",
      "preferences": [
        {
          "name": "days",
          "type": "number",
          "title": "Forecast days",
          "default": 5
        }
      ]
    }
  ]
}
```

--------------------------------

### Verify Asyar CLI Installation

Source: https://github.com/xoshbin/asyar/blob/main/docs/tutorials/prerequisites.md

Checks the installed version of the Asyar CLI to confirm successful installation. Run this command after installing the asyar-sdk.

```bash
asyar --version
```

--------------------------------

### Run Tauri Development Server

Source: https://github.com/xoshbin/asyar/blob/main/asyar-launcher/README.md

Starts the Tauri application in development mode. Requires the SDK to be pre-built.

```bash
pnpm tauri dev
```

--------------------------------

### Project Structure Overview

Source: https://github.com/xoshbin/asyar/blob/main/docs/tutorials/manual-setup.md

This is the minimum required project structure for a manual Asyar extension setup. Ensure `index.html` is in the root directory.

```text
com.yourname.hello-world/
├── manifest.json
├── index.html
├── package.json
├── vite.config.ts
├── tsconfig.json
└── src/
    ├── main.ts
    ├── index.ts
    └── DefaultView.svelte
```

--------------------------------

### Usage Example: Initializing Resolver in Command Handler

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/user-templates-pattern.md

This example demonstrates how to initialize the template resolver within an extension's command handler. It retrieves necessary services like IClipboardHistoryService and ISelectionService from the ExtensionContext.

```typescript
import type {
  ExtensionContext,
  IClipboardHistoryService,
  ISelectionService,
} from 'asyar-sdk';
import { createTemplateResolver } from './lib/templates';

let resolver: ReturnType<typeof createTemplateResolver>;

export async function initialize(context: ExtensionContext) {
  const clipboard = context.getService<IClipboardHistoryService>('clipboard');
  const selection = context.getService<ISelectionService>('selection');
  resolver = createTemplateResolver(clipboard, selection);
}

export async function openTemplatedUrl(template: string, query: string) {

```

--------------------------------

### Run the Asyar Publish Pipeline

Source: https://github.com/xoshbin/asyar/blob/main/docs/how-to/publishing.md

Execute the main command to start the multi-step publishing process for your Asyar extension. This command is resumable and idempotent.

```bash
asyar publish
```

--------------------------------

### Calculator Tool Return Examples

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/builtin-tools.md

Illustrates the possible scalar JSON values returned by the calculator tool.

```json
42          // integer result
3.14        // float result
"hello"     // string result
true        // boolean result
```

--------------------------------

### LogService Usage Example

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/log-service.md

Demonstrates how to obtain and use the LogService in your application.

```APIDOC
## LogService Usage

### Description
Shows how to retrieve the LogService instance and call its logging methods.

### Usage

```typescript
const log = context.getService<ILogService>('log');

log.debug('Rendering item list');
log.info('Extension initialized');
log.warn('Rate limit approaching');
log.error(new Error('API request failed'));
log.custom('User selected item #3', 'UI', 'cyan', 'MyExtension');
```
```

--------------------------------

### Building the .asyar Package

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/extension-types/theme.md

Command to create a ZIP archive of the theme extension files and then rename it to .asyar. This is the format used for installing theme extensions.

```bash
# Create the ZIP and rename it
zip -r my-dark-theme.zip manifest.json theme.json fonts/
mv my-dark-theme.zip my-dark-theme.asyar
```

--------------------------------

### Making GET and POST Requests with NetworkService

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/network-service.md

Demonstrates how to use the NetworkService to perform GET requests and POST requests with JSON bodies. Includes examples of setting headers and timeouts.

```typescript
const network = context.getService<INetworkService>('network');

// GET request
const res = await network.fetch('https://api.example.com/data');
if (res.ok) {
  const data = JSON.parse(res.body);
}

// POST with JSON
const created = await network.fetch('https://api.example.com/items', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
  body: JSON.stringify({ name: 'My Item', value: 42 }),
  timeout: 10_000,
});

// Handle errors
if (!created.ok) {
  throw new Error(`HTTP ${created.status}: ${created.statusText}`);
}
```

--------------------------------

### View Entry Point Example

Source: https://github.com/xoshbin/asyar/blob/main/asyar-sdk/README.md

Illustrates bootstrapping a view extension using 'asyar-sdk/view'. It registers an icon element, sets the extension ID, and mounts a Svelte component. This snippet is intended for use in a view.html file.

```typescript
// src/main.view.ts — loaded by view.html
import { ExtensionContext, registerIconElement } from 'asyar-sdk/view';
import MyView from './MyView.svelte';
import { mount } from 'svelte';

registerIconElement();

const extensionId = window.location.hostname;
const context = new ExtensionContext();
context.setExtensionId(extensionId);

mount(MyView, { target: document.getElementById('app')!, props: { context } });

window.parent.postMessage({ type: 'asyar:extension:loaded', extensionId, role: 'view' }, '*');
```

--------------------------------

### Add Per-Project Dependencies

Source: https://github.com/xoshbin/asyar/blob/main/docs/tutorials/prerequisites.md

Installs essential dependencies for an Asyar extension project, including the asyar-sdk, Svelte, Vite, and TypeScript. This is required for manual project setup.

```bash
pnpm add asyar-sdk svelte
pnpm add -D vite @sveltejs/vite-plugin-svelte typescript
```

--------------------------------

### CacheService Usage Example

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/cache-service.md

Demonstrates how to use the CacheService to set, get, remove, and clear cache entries, including setting an expiration time for a cache entry.

```typescript
const cache = context.getService<ICacheService>('cache');

// Cache an API response for 1 hour
const oneHourFromNow = new Date(Date.now() + 3600 * 1000);
await cache.set('api_data', JSON.stringify(data), { 
  expirationDate: oneHourFromNow 
});

// Read from cache
const cachedRaw = await cache.get('api_data');
if (cachedRaw) {
  const data = JSON.parse(cachedRaw);
}

// Key automatically becomes inaccessible after oneHourFromNow
// and will be pruned from the database on the next app restart.

// Manually remove a key
await cache.remove('api_data');

// Wipe the entire cache for this extension
await cache.clear();
```

--------------------------------

### SettingsService Usage Example

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/settings-service.md

Demonstrates how to obtain the SettingsService and use its methods to read, write, and subscribe to setting changes. Ensure the service is retrieved using context.getService.

```typescript
const settings = context.getService<ISettingsService>('settings');

// Read a setting (with TypeScript type inference)
const theme = await settings.get<string>('com.yourname.myext', 'theme');
const count = await settings.get<number>('com.yourname.myext', 'itemCount');

// Write a setting
await settings.set('com.yourname.myext', 'theme', 'dark');
await settings.set('com.yourname.myext', 'lastUsed', Date.now());

// Subscribe to changes (reactive — fires when value changes from any source)
const unsubscribe = settings.onChanged<{ theme: string }>(
  'com.yourname.myext',
  (newSettings) => {
    console.log('Theme changed to:', newSettings.theme);
  }
);

// Call the returned function to stop listening
unsubscribe();
```

--------------------------------

### StorageService Usage Example

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/storage-service.md

Demonstrates how to use the StorageService to get, set, delete, and retrieve all stored key-value pairs. Values are stored as strings; complex data should be JSON.stringified.

```typescript
const storage = context.getService<IStorageService>('storage');

// Store a value (values are strings — JSON.stringify complex data)
await storage.set('theme', 'dark');
await storage.set('bookmarks', JSON.stringify(['https://example.com']));

// Read a value
const theme = await storage.get('theme'); // "dark"
const raw = await storage.get('bookmarks');
const bookmarks = raw ? JSON.parse(raw) : [];

// Check if a key exists
const val = await storage.get('nonexistent'); // null

// Delete a single key
const wasDeleted = await storage.delete('theme'); // true

// Get everything
const all = await storage.getAll(); // { "bookmarks": "[\"https://example.com\"]" }

// Nuclear option — delete all your extension's data
const count = await storage.clear(); // number of deleted entries
```

--------------------------------

### Sync Apple Shortcuts as Dynamic Commands

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/dynamic-commands.md

This example demonstrates how to list Apple Shortcuts, sync their names and UUIDs as dynamic commands, and set up file watching to re-sync when shortcuts change. It requires services for shell execution, commands, and file system watching.

```typescript
// extensions/apple-shortcuts/src/worker.ts
import { ExtensionContext as WorkerExtensionContext } from 'asyar-sdk/worker';
import type { ICommandService, IShellService, IFileSystemWatcherService } from 'asyar-sdk/contracts';

const ctx = new WorkerExtensionContext();
const commandsService = ctx.getService<ICommandService>('commands');
const shell = ctx.getService<IShellService>('shell');
const fsWatcher = ctx.getService<IFileSystemWatcherService>('fsWatcher');

async function listShortcuts() {
  const out = await shell.execute({
    command: '/usr/bin/shortcuts',
    args: ['list', '--show-identifiers'],
  });
  // parse `name (uuid)` lines into an array
  return out.stdout.split('\n').flatMap((line) => {
    const m = line.match(/^(.+?)\s+\(.+?\)$/);
    return m ? [{ name: m[1], id: m[2] }] : [];
  });
}

async function syncFromOS() {
  const items = await listShortcuts();
  await commandsService.replaceDynamicCommands(
    items.map((item) => ({
      id: item.id,
      name: item.name,
      arguments: [{ name: 'input', type: 'text', placeholder: 'Optional input' }],
    })),
  );
}

// Initial sync at activate, plus re-sync on every fs change.
await syncFromOS();
await fsWatcher.watch(['~/Library/Shortcuts/'], async () => {
  await syncFromOS();
});
```

--------------------------------

### View Extension Setup

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/extension-types/extension.md

Sets up a view extension by registering its manifest, implementation, and mounting the Svelte component. It also sends a 'loaded' message to the parent window.

```typescript
import { ExtensionContext, extensionBridge, registerIconElement } from 'asyar-sdk/view';
import PomodoroView from './PomodoroView.svelte';
import { mount } from 'svelte';

registerIconElement();

const extensionId = window.location.hostname || 'com.yourname.pomodoro';
const context = new ExtensionContext();
context.setExtensionId(extensionId);
extensionBridge.registerManifest(manifest);
extensionBridge.registerExtensionImplementation(extensionId, { /* ... */ });

mount(PomodoroView, {
  target: document.getElementById('app')!,
  props: { context },
});

window.parent.postMessage({ type: 'asyar:extension:loaded', extensionId, role: 'view' }, '*');
```

--------------------------------

### Translate Selected Text Example

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/selection-service.md

Demonstrates how to use the SelectionService to get selected text and handle potential accessibility permission errors. This pattern is useful for actions that require text input from the user's current selection.

```typescript
import type { ISelectionService, SelectionError } from 'asyar-sdk';

const selection = context.getService<ISelectionService>('selection');
const feedback  = context.getService<IFeedbackService>('feedback');

async function translateSelection() {
  let text: string | null;
  try {
    text = await selection.getSelectedText();
  } catch (err) {
    const sel = err as SelectionError;
    if (sel.code === 'ACCESSIBILITY_PERMISSION_REQUIRED') {
      await feedback.showToast({
        title: 'Accessibility permission required',
        message: 'Grant Asyar access in System Settings to read selected text.',
        style: 'failure',
      });
      return;
    }
    throw err;
  }

  if (!text) {
    await feedback.showHUD('No text selected');
    return;
  }

  const translated = await translate(text);
  await feedback.showToast({ title: translated, style: 'success' });
}
```

--------------------------------

### Using WindowManagementService

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/window-management-service.md

Demonstrates how to obtain the WindowManagementService and use its methods to read current window bounds, move the window, resize it, and enter fullscreen mode.

```typescript
const winService = context.getService<IWindowManagementService>('window');

// Read current bounds
const bounds = await winService.getWindowBounds();
console.log(`Window at (${bounds.x}, ${bounds.y}), size ${bounds.width}×${bounds.height}`);

// Move window right by 50px without changing size
await winService.setWindowBounds({ x: bounds.x + 50, y: bounds.y });

// Resize to 1280×800 without moving
await winService.setWindowBounds({ width: 1280, height: 800 });

// Enter fullscreen
await winService.setFullscreen(true);
```

--------------------------------

### Main Extension Entry Point (TypeScript)

Source: https://github.com/xoshbin/asyar/blob/main/docs/tutorials/bookmarks-example.md

Initializes the extension context, handles messages from the parent window, and mounts the Svelte view. Services like notifications and actions are resolved here.

```typescript
import { mount } from 'svelte';
import BookmarksView from './BookmarksView.svelte';
import {
  ExtensionContext,
  type IActionService,
  type INotificationService,
} from 'asyar-sdk';

const extensionId = window.location.hostname || 'com.yourname.bookmarks';

// 1. Single context — one per iframe lifetime.
const context = new ExtensionContext();
context.setExtensionId(extensionId);

// 2. Signal readiness to the host.
window.parent.postMessage({ type: 'asyar:extension:loaded', extensionId }, '*');

// 3. Forward ⌘K to the host.
window.addEventListener('keydown', (event) => {
  if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
    event.preventDefault();
    window.parent.postMessage({
      type: 'asyar:extension:keydown',
      payload: {
        key: event.key,
        metaKey: event.metaKey,
        ctrlKey: event.ctrlKey,
        shiftKey: event.shiftKey,
        altKey: event.altKey,
      },
    }, '*');
  }
});

// 4. Resolve services once.
const notifService   = context.getService<INotificationService>('notifications');
const actionService  = context.getService<IActionService>('actions');

// 5. Handle no-view command (add-today) invoked by the host.
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'asyar:invoke:command') return;
  const { commandId } = event.data.payload;

  if (commandId === 'add-today') {
    const entry = new Date().toLocaleDateString('en-US', {
      weekday: 'long', year: 'numeric', month: 'long', day: 'numeric',
    });
    const stored: string[] = JSON.parse(localStorage.getItem('bookmarks') ?? '[]');
    stored.unshift(entry);
    localStorage.setItem('bookmarks', JSON.stringify(stored));
    await notifService.send({ title: 'Bookmark Added', body: entry });
  }
});

// 6. Mount the view for the correct ?view= param.
const viewName = new URLSearchParams(window.location.search).get('view') || 'BookmarksView';

if (viewName === 'BookmarksView') {
  mount(BookmarksView, {
    target: document.getElementById('app')!,
    props: { actionService, notifService },
  });
}
```

--------------------------------

### Installed Extension View Rendering (Iframe)

Source: https://github.com/xoshbin/asyar/blob/main/docs/explanation/host-startup-and-installation.md

Details the process of rendering an installed extension view using an iframe, including navigation and protocol handling.

```javascript
<ExtensionIframe extensionId="xyz-plugin" view="xyz-plugin/DefaultView" />
```

```javascript
asyar-extension://xyz-plugin/index.html?view=DefaultView
```

```javascript
<iframe sandbox="allow-scripts allow-same-origin allow-forms allow-popups">
```

--------------------------------

### Start Development Server

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/cli.md

Activates active development mode. It validates the manifest, performs an initial Vite build, creates a symlink to the Asyar extensions directory, and watches for file changes to rebuild automatically.

```bash
asyar dev
```

--------------------------------

### Example Asyar Extension URL

Source: https://github.com/xoshbin/asyar/blob/main/docs/explanation/asyar-extension-protocol.md

Illustrates the format of a URL loaded by Asyar for an extension iframe, including the scheme, extension ID, and an example query parameter.

```plaintext
asyar-extension://com.yourname.hello-world/index.html?view=DefaultView
```

--------------------------------

### Monorepo Root: Development Build and Run

Source: https://github.com/xoshbin/asyar/blob/main/asyar-launcher/README.md

Builds the SDK once and then runs the Tauri development server, enabling SDK watch mode. Execute from the monorepo root.

```bash
# from monorepo root
pnpm dev          # builds SDK once, then runs Tauri dev with SDK watch
```

--------------------------------

### Worker Entry Point Example

Source: https://github.com/xoshbin/asyar/blob/main/asyar-sdk/README.md

Demonstrates bootstrapping a worker extension using 'asyar-sdk/worker'. It sets the extension ID, retrieves a logging service, and registers an RPC handler for 'getStats'. This snippet is intended for use in a worker.html file.

```typescript
// src/main.worker.ts — loaded by worker.html
import { ExtensionContext, extensionBridge } from 'asyar-sdk/worker';
import type { ILogService, INotificationService } from 'asyar-sdk/contracts';

const extensionId = window.location.hostname;
const context = new ExtensionContext();
context.setExtensionId(extensionId);

const log = context.getService<ILogService>('log');
log?.info('Worker bootstrapped');

// view → worker RPC handler (only available on the worker entry).
context.onRequest<{}, { rounds: number }>('getStats', async () => {
  return { rounds: await readRounds() };
});

window.parent.postMessage({ type: 'asyar:extension:loaded', extensionId, role: 'worker' }, '*');
```

--------------------------------

### onApplicationsChanged Subscription

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/application-service.md

Subscribe to changes in the installed application list. This callback is invoked when an application is installed, uninstalled, or when directories in `settings.search.additionalScanPaths` are edited. The host debounces filesystem events, ensuring each callback represents a real change.

```APIDOC
## onApplicationsChanged

### Description
Subscribes to events related to application installations, uninstulations, and changes in scanned directories. This is useful for UIs that need to reflect the current set of installed applications in real-time.

### Method
`app.onApplicationsChanged(callback: (e: ApplicationsChangedEvent) => void): () => void`

### Parameters
#### Callback Function
- `e` (ApplicationsChangedEvent) - An object containing information about the changes.
  - `added` (number) - The number of applications added.
  - `removed` (number) - The number of applications removed.
  - `total` (number) - The total number of applications after the change.

### Returns
- `dispose` (function) - A function that, when called, unsubscribes the listener.

### Usage Example
```typescript
const dispose = app.onApplicationsChanged((e) => {
  console.log(`index changed: +${e.added} / -${e.removed} (total ${e.total})`);
  // Refresh UI or re-fetch application list
});

// To unsubscribe later:
dispose();
```

### When to use
Use this subscription when your extension's UI mirrors the installed-app set and needs to stay accurate without user action. For instance, a launcher list, an "installed apps" picker, or an integration that indexes new apps. A one-shot `listApplications()` call is sufficient if you only need the list once at extension startup and a stale view is acceptable.
```

--------------------------------

### Main TypeScript Entry Point

Source: https://github.com/xoshbin/asyar/blob/main/docs/tutorials/manual-setup.md

Initializes the Asyar extension context, mounts the Svelte component, and handles communication with the parent window, including keydown events.

```typescript
import { mount } from 'svelte';
import DefaultView from './DefaultView.svelte';
import { ExtensionContext, type ILogService } from 'asyar-sdk';

// The hostname of the asyar-extension:// URL is always your extension ID.
const extensionId = window.location.hostname || 'com.yourname.hello-world';

// 1. Create ONE context for the entire iframe lifetime.
//    Do NOT create a second one inside a component.
const context = new ExtensionContext();
context.setExtensionId(extensionId);

// 2. Signal readiness to the host. Without this, the host will not
//    route actions or service calls to this iframe.
window.parent.postMessage({ type: 'asyar:extension:loaded', extensionId }, '*');

// 3. Forward ⌘K to the host so the Action Drawer opens from inside the iframe.
window.addEventListener('keydown', (event) => {
  const isCommandK = (event.metaKey || event.ctrlKey) && event.key === 'k';
  if (isCommandK) {
    event.preventDefault();
    window.parent.postMessage({
      type: 'asyar:extension:keydown',
      payload: {
        key: event.key,
        metaKey: event.metaKey,
        ctrlKey: event.ctrlKey,
        shiftKey: event.shiftKey,
        altKey: event.altKey,
      }
    }, '*');
  }
});

// 4. Resolve the view from the URL query param.
const viewName = new URLSearchParams(window.location.search).get('view') || 'DefaultView';

// 5. Mount the Svelte component, passing services as props.
if (viewName === 'DefaultView') {
  mount(DefaultView, {
    target: document.getElementById('app')!,
    props: {
      logger: context.getService<ILogService>('log'),
    }
  });
}
```

--------------------------------

### ApplicationService Index Push Surface

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/application-service.md

Allows subscribing to events when the installed application index changes.

```APIDOC
## onApplicationsChanged

### Description
Subscribes to an event that fires when changes occur in the installed application index (e.g., app installation or removal).

### Method
SUBSCRIBE (conceptual)

### Endpoint
applicationIndex:onApplicationsChanged

### Parameters
#### Callback Function
- **cb** (function) - Required - A callback function that receives an `ApplicationIndexEvent`.
  - **e** (ApplicationIndexEvent) - The event object detailing the changes.
    - **type**: 'applications-changed'
    - **added**: number - The number of applications newly added since the last event.
    - **removed**: number - The number of applications removed since the last event.
    - **total**: number - The current absolute count of installed applications.

### Response
#### Success Response (200)
- **Disposer** (function) - A function that, when called, unsubscribes the listener.

### Request Example
```typescript
const dispose = context.services.application.onApplicationsChanged((e) => {
  console.log(`Application index changed: Added ${e.added}, Removed ${e.removed}, Total ${e.total}`);
});

// To unsubscribe later:
dispose();
```
```

--------------------------------

### RunService Interface

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/run-service.md

Defines the interface for interacting with the RunService, including starting new runs and managing their lifecycle.

```APIDOC
## RunService Interface

### Description
Provides methods to start and manage long-running tasks displayed in the launcher's UI.

### Methods

#### `start(input: RunStartInput): Promise<RunHandle>`
Starts a new run and returns a `RunHandle` for managing its lifecycle.

##### Parameters

- **input** (`RunStartInput`) - Required - Configuration for the run.
  - **label** (`string`) - Required - A user-friendly label for the run.
  - **kind** (`RunKind`) - Required - The type of run (e.g., 'ai-chat', 'shell-script').
  - **cancellable** (`boolean`) - Optional - Whether the run can be cancelled. Defaults to `false`.

##### Returns

- `Promise<RunHandle>` - A handle to the started run.

### RunHandle Interface

#### Methods

##### `write(line: string): Promise<void>`
Appends a line of output to the run's log.

##### `done(): Promise<void>`
Signals successful completion of the run.

##### `fail(error: string): Promise<void>`
Signals failure of the run with an error message.

##### `cancel(): Promise<void>`
Requests cancellation of the run.

##### `onCancel(cb: () => void): () => void`
Registers a callback to be fired when the run is cancelled. Returns an unsubscribe function.

#### Properties

##### `id: string`
The unique identifier for the run.

##### `cancelled: boolean`
Indicates if the run has been confirmed as cancelled (asynchronous).

### RunStartInput Type

- **label** (`string`) - Required - A user-friendly label for the run.
- **kind** (`RunKind`) - Required - The type of run (e.g., 'ai-chat', 'shell-script').
- **cancellable** (`boolean`) - Optional - Whether the run can be cancelled. Defaults to `false`.

### RunKind Enum

Possible values: `'ai-chat'`, `'shell-script'`, `'agent'`, `'custom'`.

### RunStatus Enum

Possible values: `'pending'`, `'running'`, `'succeeded'`, `'failed'`, `'cancelled'`.

### Run Interface

- **id** (`string`) - Required - Unique identifier for the run.
- **kind** (`RunKind`) - Required - The type of run.
- **label** (`string`) - Required - User-friendly label for the run.
- **status** (`RunStatus`) - Required - Current status of the run.
- **extensionId** (`string`) - Optional - ID of the extension that started the run.
- **startedAt** (`number`) - Required - Unix timestamp (ms) when the run started.
- **endedAt** (`number`) - Optional - Unix timestamp (ms) when the run ended.
- **cancellable** (`boolean`) - Required - Whether the run is cancellable.
- **errorMessage** (`string`) - Optional - Error message if the run failed.
- **subjectId** (`string`) - Optional - Join key linking the run to its originating command.
```

--------------------------------

### Pomodoro Timer Example

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/timers.md

Implements a Pomodoro timer that schedules a notification and allows for a 5-minute snooze by rescheduling the timer.

```typescript
import type { INotificationService, ITimerService } from 'asyar-sdk';

const timers = context.getService<ITimerService>('timers');
const notifications = context.getService<INotificationService>('notifications');

export async function startPomodoro(): Promise<void> {
  const fireAt = Date.now() + 25 * 60 * 1000;
  await timers.schedule({ commandId: 'pomodoro.end', fireAt });
}

export async function pomodoroEnd(args: Record<string, unknown>): Promise<void> {
  await notifications.send({
    title: 'Pomodoro done',
    body: 'Take a break.',
    actions: [
      { id: 'snooze', title: 'Snooze 5 min', commandId: 'pomodoro.start-snooze' },
    ],
  });
}

export async function pomodoroStartSnooze(): Promise<void> {
  const fireAt = Date.now() + 5 * 60 * 1000;
  await timers.schedule({ commandId: 'pomodoro.end', fireAt, args: { fromSnooze: true } });
}
```

--------------------------------

### Minimal ShellService Usage

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/shell-service.md

Demonstrates the basic steps to spawn a process, listen for output chunks, and handle process completion or errors.

```typescript
import type { IShellService } from 'asyar-sdk';

const shell = context.getService<IShellService>('shell');

const handle = shell.spawn({ program: 'git', args: ['status'] });

handle.onChunk(({ stream, data }) => console.log(`[${stream}] ${data}`));
handle.onDone((exitCode) => console.log('Exited:', exitCode));
handle.onError(({ message }) => console.warn('[Shell] spawn failed:', message));
```

--------------------------------

### Manifest Declaration for FileSystemWatcherService

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/file-system-watcher.md

Example manifest JSON for declaring 'fs:watch' permission and specifying watched paths.

```json
{
  "permissions": ["fs:watch"],
  "permissionArgs": {
    "fs:watch": [
      "~/Library/Shortcuts/**",
      "~/.ssh/config"
    ]
  },
  "background": {
    "main": "dist/worker.js"
  }
}
```

--------------------------------

### Basic SearchEngine Usage with Notes

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/search-engine.md

Demonstrates how to initialize SearchEngine for a list of 'Note' objects and perform a search query. Ensure `setItems` is called when data changes.

```typescript
import { SearchEngine } from 'asyar-sdk';

interface Note {
  id: string;
  title: string;
  body: string;
}

const engine = new SearchEngine<Note>({
  getText: (note) => `${note.title} ${note.body}`,
});

// Call setItems() whenever your data changes
engine.setItems(myNotes);

// Search — returns matching notes ranked by relevance
const results = engine.search('qrtly rep');
// Finds notes containing "quarterly report" via subsequence matching
```

--------------------------------

### Extension Bootstrapping and Communication

Source: https://github.com/xoshbin/asyar/blob/main/docs/explanation/host-startup-and-installation.md

Describes how an extension's `index.html` executes its JavaScript, initializes the SDK, and establishes communication with the parent window.

```javascript
new ExtensionContext()
```

--------------------------------

### Asyar CLI Validation Errors

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/background-scheduling.md

Examples of validation errors reported by the Asyar CLI for incorrect schedule configurations.

```text
✗ Command "fast-check": schedule.intervalSeconds must be between 10 and 86400 (got 5)
✗ Command "slow-sync": scheduled commands must have mode "background"
```

--------------------------------

### Run Launcher Vitest Suite

Source: https://github.com/xoshbin/asyar/blob/main/asyar-launcher/README.md

Executes the test suite for the launcher using Vitest.

```bash
pnpm run test
```

--------------------------------

### IRunService Interface

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/run-service.md

Defines the main interface for the RunService, primarily used to start new runs and obtain a RunHandle.

```typescript
export interface IRunService {
  /**
   * Start a new run. Returns a handle that holds a cancel-event subscription.
   * Always resolve the handle by calling exactly one of done(), fail(), or cancel() 
   * to release the subscription.
   */
  start(input: RunStartInput): Promise<RunHandle>;
}
```

--------------------------------

### RunStartInput Interface

Source: https://github.com/xoshbin/asyar/blob/main/docs/reference/sdk/run-service.md

Defines the input structure for starting a new run, specifying its label, kind, and whether it is cancellable.

```typescript
export interface RunStartInput {
  label: string;
  kind: RunKind;
  cancellable?: boolean; // Defaults to false
}
```
Tokens:
Raw