@qikbar/qikbar 0.0.25 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +121 -0
  3. package/bin/qikbar.mjs +203 -0
  4. package/dist/ai/agent.d.ts +42 -0
  5. package/dist/ai/byok.d.ts +29 -0
  6. package/dist/ai/embeddings.d.ts +51 -0
  7. package/dist/ai/index.d.ts +12 -0
  8. package/dist/ai/mcp.d.ts +84 -0
  9. package/dist/ai/providers.d.ts +82 -0
  10. package/dist/ai/sse.d.ts +9 -0
  11. package/dist/ai.js +54 -0
  12. package/dist/ai.js.map +7 -0
  13. package/dist/chunks/bar-P3SCR4SJ.js +2555 -0
  14. package/dist/chunks/bar-P3SCR4SJ.js.map +7 -0
  15. package/dist/chunks/chunk-5FI7DNG7.js +271 -0
  16. package/dist/chunks/chunk-5FI7DNG7.js.map +7 -0
  17. package/dist/chunks/chunk-INTEVQYK.js +108 -0
  18. package/dist/chunks/chunk-INTEVQYK.js.map +7 -0
  19. package/dist/chunks/chunk-JHQAIXM7.js +458 -0
  20. package/dist/chunks/chunk-JHQAIXM7.js.map +7 -0
  21. package/dist/chunks/chunk-MPTP2EWW.js +8 -0
  22. package/dist/chunks/chunk-MPTP2EWW.js.map +7 -0
  23. package/dist/chunks/chunk-MRHKJ2FZ.js +419 -0
  24. package/dist/chunks/chunk-MRHKJ2FZ.js.map +7 -0
  25. package/dist/chunks/chunk-N4Y2Z6YD.js +69 -0
  26. package/dist/chunks/chunk-N4Y2Z6YD.js.map +7 -0
  27. package/dist/chunks/chunk-OLXZNYZ4.js +193 -0
  28. package/dist/chunks/chunk-OLXZNYZ4.js.map +7 -0
  29. package/dist/chunks/chunk-PQEHV3D4.js +124 -0
  30. package/dist/chunks/chunk-PQEHV3D4.js.map +7 -0
  31. package/dist/chunks/chunk-R2AY6LRL.js +575 -0
  32. package/dist/chunks/chunk-R2AY6LRL.js.map +7 -0
  33. package/dist/chunks/chunk-TIM4VBM4.js +98 -0
  34. package/dist/chunks/chunk-TIM4VBM4.js.map +7 -0
  35. package/dist/chunks/chunk-YCVJQ7U3.js +52 -0
  36. package/dist/chunks/chunk-YCVJQ7U3.js.map +7 -0
  37. package/dist/chunks/launcher-B5MGOPEQ.js +37 -0
  38. package/dist/chunks/launcher-B5MGOPEQ.js.map +7 -0
  39. package/dist/core/define.d.ts +40 -0
  40. package/dist/core/frecency.d.ts +16 -0
  41. package/dist/core/hotkeys.d.ts +39 -0
  42. package/dist/core/labels.d.ts +98 -0
  43. package/dist/core/launcher.d.ts +8 -0
  44. package/dist/core/lazy.d.ts +60 -0
  45. package/dist/core/search.d.ts +42 -0
  46. package/dist/core/storage.d.ts +5 -0
  47. package/dist/core/types.d.ts +737 -0
  48. package/dist/element/index.d.ts +56 -0
  49. package/dist/element.js +146 -0
  50. package/dist/element.js.map +7 -0
  51. package/dist/extensions/index.d.ts +30 -0
  52. package/dist/extensions/math.d.ts +14 -0
  53. package/dist/extensions.js +476 -0
  54. package/dist/extensions.js.map +7 -0
  55. package/dist/index.d.ts +31 -0
  56. package/dist/index.js +85 -0
  57. package/dist/index.js.map +7 -0
  58. package/dist/locales/index.d.ts +24 -0
  59. package/dist/locales.js +810 -0
  60. package/dist/locales.js.map +7 -0
  61. package/dist/qikbar.global.js +302 -0
  62. package/dist/qikbar.global.js.map +7 -0
  63. package/dist/react/index.d.ts +66 -0
  64. package/dist/react.js +121 -0
  65. package/dist/react.js.map +7 -0
  66. package/dist/server/index.d.ts +66 -0
  67. package/dist/server.js +129 -0
  68. package/dist/server.js.map +7 -0
  69. package/dist/solid/index.d.ts +42 -0
  70. package/dist/solid.js +93 -0
  71. package/dist/solid.js.map +7 -0
  72. package/dist/styles.css +253 -0
  73. package/dist/svelte/index.d.ts +58 -0
  74. package/dist/svelte.js +55 -0
  75. package/dist/svelte.js.map +7 -0
  76. package/dist/theme.d.ts +5 -0
  77. package/dist/theme.js +20 -0
  78. package/dist/theme.js.map +7 -0
  79. package/dist/ui/bar.d.ts +338 -0
  80. package/dist/ui/dom.d.ts +21 -0
  81. package/dist/ui/icons.d.ts +93 -0
  82. package/dist/ui/markdown.d.ts +10 -0
  83. package/dist/ui/nav.d.ts +8 -0
  84. package/dist/ui/styles.d.ts +6 -0
  85. package/dist/ui/themes.d.ts +27 -0
  86. package/dist/ui/views.d.ts +156 -0
  87. package/dist/ui/webmcp.d.ts +33 -0
  88. package/dist/utils.d.ts +10 -0
  89. package/dist/utils.js +50 -0
  90. package/dist/utils.js.map +7 -0
  91. package/dist/vue/index.d.ts +74 -0
  92. package/dist/vue.js +122 -0
  93. package/dist/vue.js.map +7 -0
  94. package/package.json +129 -43
  95. package/dist/qikbar.es.js +0 -8748
  96. package/dist/qikbar.umd.js +0 -113
  97. package/dist/types/boot.d.ts +0 -72
  98. package/dist/types/index.d.ts +0 -1
  99. package/dist/types/init.d.ts +0 -2
  100. package/dist/types/main.d.ts +0 -4
  101. package/dist/types/shared/AsyncRoot.d.ts +0 -5
  102. package/dist/types/shared/CommandFooter.d.ts +0 -5
  103. package/dist/types/shared/Crumbs.d.ts +0 -6
  104. package/dist/types/shared/Details.d.ts +0 -3
  105. package/dist/types/shared/ErrorBoundary.d.ts +0 -15
  106. package/dist/types/shared/Icon.d.ts +0 -4
  107. package/dist/types/shared/List.d.ts +0 -30
  108. package/dist/types/shared/Qikbar.d.ts +0 -5
  109. package/dist/types/shared/Root.d.ts +0 -4
  110. package/dist/types/shared/Search.d.ts +0 -1
  111. package/dist/types/shared/commandContext.d.ts +0 -8
  112. package/dist/types/shared/useDebounce.d.ts +0 -1
  113. package/dist/types/utils/liquid.d.ts +0 -4
  114. package/dist/types/vite-env.d.ts +0 -1
@@ -0,0 +1,737 @@
1
+ /**
2
+ * Public types for Qikbar.
3
+ *
4
+ * Everything in Qikbar is plain data: commands, items, actions and views are
5
+ * objects you can create in any framework (or none) and that an AI model can
6
+ * reason about.
7
+ */
8
+ import type { Labels } from './labels.js';
9
+ export type { Labels } from './labels.js';
10
+ export type Awaitable<T> = T | Promise<T>;
11
+ /**
12
+ * What `run`, actions and form submissions may return:
13
+ * a `View` to push it, `false` to keep the bar open, anything else to close.
14
+ */
15
+ export type RunResult = View | false | void | undefined | null | (object & {});
16
+ /**
17
+ * An icon. Strings are interpreted as:
18
+ * - a built-in icon name (`"search"`, `"settings"`, …, see `icons`)
19
+ * - an image URL (`https://…`, `/…`, `./…`, `data:…`)
20
+ * - inline SVG markup (`<svg …>`; treated as trusted HTML)
21
+ * - anything else is rendered as text (emoji, a letter, …)
22
+ *
23
+ * Pass a DOM `Node` (or a function returning one) for full control.
24
+ */
25
+ export type Icon = string | Node | (() => Node) | {
26
+ url: string;
27
+ alt?: string;
28
+ } | {
29
+ color: string;
30
+ icon?: string;
31
+ };
32
+ export type Color = 'default' | 'gray' | 'blue' | 'green' | 'yellow' | 'orange' | 'red' | 'purple' | 'pink' | (string & {});
33
+ export interface Accessory {
34
+ text?: string;
35
+ icon?: Icon;
36
+ /** Rendered as a colored pill. */
37
+ tag?: string | {
38
+ value: string;
39
+ color?: Color;
40
+ };
41
+ /** Rendered as keyboard keys, e.g. `"mod+shift+p"`. */
42
+ kbd?: string;
43
+ /** Rendered relative ("3h ago"). */
44
+ date?: Date | number | string;
45
+ tooltip?: string;
46
+ }
47
+ /** Context available to every `run`, action and dynamic view. */
48
+ export interface Context {
49
+ /** The Qikbar instance. */
50
+ readonly bar: QikbarInstance;
51
+ /** Current search text of the active view. */
52
+ readonly query: string;
53
+ /** Aborted when the view is popped, the bar closes or the query changes. */
54
+ readonly signal: AbortSignal;
55
+ /** Values from the extension's `preferences` (empty for app commands). */
56
+ readonly preferences: Record<string, any>;
57
+ /** Values entered for the command's `arguments`. */
58
+ readonly arguments: Record<string, string>;
59
+ /** Namespaced persistent storage (localStorage by default). */
60
+ readonly storage: ScopedStorage;
61
+ /** The configured AI client, if any. */
62
+ readonly ai: AIClient | undefined;
63
+ /** Push a view onto the navigation stack. */
64
+ push(view: View): void;
65
+ /** Go back one view. */
66
+ pop(): void;
67
+ /** Replace the current view (use to re-render a view with new data). */
68
+ render(view: View): void;
69
+ /** Close the bar. */
70
+ close(): void;
71
+ /** Navigate within your app using the configured router. */
72
+ navigate(href: string, options?: {
73
+ newTab?: boolean;
74
+ }): void;
75
+ /** Open an external URL in a new tab. */
76
+ openUrl(url: string): void;
77
+ /** Copy text to the clipboard. Resolves to `true` on success. */
78
+ copy(text: string): Promise<boolean>;
79
+ /** Show a toast. Shown in the footer while open, or as a floating HUD when closed. */
80
+ toast(options: ToastOptions | string): ToastHandle;
81
+ /** Ask the user to confirm something. */
82
+ confirm(options: ConfirmOptions | string): Promise<boolean>;
83
+ /** Set the search text. */
84
+ setQuery(query: string): void;
85
+ /** Items the user marked in a `multiSelect` list (empty otherwise). */
86
+ readonly selection: Item[];
87
+ /** The bar's labels (after `labels` overrides), for translated messages. */
88
+ readonly labels: Labels;
89
+ }
90
+ export interface ToastOptions {
91
+ title: string;
92
+ message?: string;
93
+ style?: 'success' | 'failure' | 'loading' | 'info';
94
+ /** Milliseconds before the toast hides. `0` keeps it. Default 2600, or 6000 with an action (loading toasts persist). */
95
+ duration?: number;
96
+ /** A button in the toast, e.g. "View" or "Retry". */
97
+ action?: ToastAction;
98
+ /** Shorthand for an "Undo" action bound to ⌘Z / Ctrl+Z while the toast is visible. */
99
+ undo?: () => Awaitable<void>;
100
+ }
101
+ export interface ToastAction {
102
+ title: string;
103
+ /** Shortcut that triggers the action while the toast is visible, e.g. `"mod+z"`. */
104
+ shortcut?: string;
105
+ run(): Awaitable<void>;
106
+ }
107
+ export interface ToastHandle {
108
+ update(options: Partial<ToastOptions>): void;
109
+ hide(): void;
110
+ }
111
+ export interface ConfirmOptions {
112
+ title: string;
113
+ message?: string;
114
+ confirmLabel?: string;
115
+ cancelLabel?: string;
116
+ destructive?: boolean;
117
+ }
118
+ export interface Action {
119
+ id?: string;
120
+ title: string;
121
+ icon?: Icon;
122
+ /** Shortcut that triggers the action while the bar is open, e.g. `"mod+c"`. */
123
+ shortcut?: string;
124
+ /** Groups actions in the action panel. */
125
+ section?: string;
126
+ style?: 'default' | 'destructive';
127
+ /**
128
+ * Called when the action runs. Return a `View` to push it.
129
+ * By default the bar closes afterwards; return `false` (or set `keepOpen`) to keep it open.
130
+ */
131
+ run(ctx: Context): Awaitable<RunResult>;
132
+ keepOpen?: boolean;
133
+ /**
134
+ * Run the action on several items at once. When the user has marked items in a
135
+ * `multiSelect` list, only actions with `runMany` are offered.
136
+ */
137
+ runMany?(items: Item[], ctx: Context): Awaitable<RunResult>;
138
+ /** @internal Label used for the title of built-in actions, so `labels` can translate it. */
139
+ labelKey?: keyof Labels;
140
+ }
141
+ /** A row in a list or grid, or a command at the root. */
142
+ export interface Item {
143
+ id?: string;
144
+ title: string;
145
+ subtitle?: string;
146
+ /** Longer description. Shown in detail panes and given to AI models. */
147
+ description?: string;
148
+ icon?: Icon;
149
+ /** Extra search terms. */
150
+ keywords?: string[];
151
+ /** Section heading the item is grouped under. */
152
+ section?: string;
153
+ accessories?: Accessory[];
154
+ /** Image URL used by grid views. */
155
+ image?: string;
156
+ /** Markdown shown in the side panel when the list has `detail: true`. */
157
+ detail?: string | (() => Awaitable<string>);
158
+ /** Shorthand primary action: navigate to an in-app route. */
159
+ href?: string;
160
+ /** Shorthand primary action: open an external URL in a new tab. */
161
+ url?: string;
162
+ /** Shorthand primary action: run code. Return a `View` to push it. */
163
+ run?: (ctx: Context) => Awaitable<RunResult>;
164
+ /** Shorthand primary action: push a view. */
165
+ view?: View | ((ctx: Context) => Awaitable<View>);
166
+ /** Additional actions. The first action is the primary action (↵), the second is secondary (⌘↵). */
167
+ actions?: Action[];
168
+ /** Global keyboard shortcut that runs this item even when the bar is closed, e.g. `"mod+shift+d"` or `"g s"`. */
169
+ shortcut?: string;
170
+ /** Hide the item unless this returns true (evaluated on open). */
171
+ when?: () => boolean;
172
+ /** Only show this item when the user has typed something. */
173
+ searchOnly?: boolean;
174
+ /** Ranking boost (0–1). */
175
+ priority?: number;
176
+ /** Arguments asked for inline before running (like Raycast arguments). */
177
+ arguments?: Argument[];
178
+ /** Disable frecency tracking for this item. */
179
+ noHistory?: boolean;
180
+ }
181
+ /** Commands are items that live at the root of the bar. */
182
+ export type Command = Item;
183
+ export interface Argument {
184
+ name: string;
185
+ placeholder?: string;
186
+ type?: 'text' | 'password' | 'dropdown';
187
+ required?: boolean;
188
+ options?: {
189
+ title: string;
190
+ value: string;
191
+ }[];
192
+ }
193
+ export interface LoadArgs {
194
+ query: string;
195
+ signal: AbortSignal;
196
+ ctx: Context;
197
+ }
198
+ export type ItemsLoader = (args: LoadArgs) => Awaitable<Item[]> | AsyncIterable<Item[]>;
199
+ interface BaseView {
200
+ /** Shown in the breadcrumb. */
201
+ title?: string;
202
+ /** Placeholder for the search input. */
203
+ placeholder?: string;
204
+ /** Actions available for every item in this view. */
205
+ actions?: Action[];
206
+ /** Called when the view is removed. */
207
+ onClose?: () => void;
208
+ }
209
+ export interface EmptyView {
210
+ title: string;
211
+ description?: string;
212
+ icon?: Icon;
213
+ }
214
+ export interface ListView extends BaseView {
215
+ type: 'list';
216
+ /** Static items, or a loader called with the search text (debounced). */
217
+ items: Item[] | ItemsLoader;
218
+ /**
219
+ * Fuzzy-filter items locally. Defaults to `true` for static arrays and `false`
220
+ * for loaders (the loader is expected to filter on `query`).
221
+ */
222
+ filter?: boolean;
223
+ /** Debounce for loaders, in ms. Default 120. */
224
+ debounce?: number;
225
+ /** Show a markdown side panel for the selected item (`item.detail`). */
226
+ detail?: boolean;
227
+ emptyView?: EmptyView;
228
+ /** Initial search text. */
229
+ query?: string;
230
+ /**
231
+ * Let the user mark several items (Shift/⌘-click, Shift+↑↓, or "Select" in the
232
+ * action panel) and run an action with `runMany` on all of them.
233
+ */
234
+ multiSelect?: boolean;
235
+ }
236
+ export interface GridView extends Omit<ListView, 'type' | 'detail'> {
237
+ type: 'grid';
238
+ columns?: number;
239
+ /** Aspect ratio of each cell, e.g. `"1"`, `"16/9"`. Default `"1"`. */
240
+ aspectRatio?: string;
241
+ /** How images fill their cell. */
242
+ fit?: 'cover' | 'contain';
243
+ }
244
+ export interface MetadataEntry {
245
+ label: string;
246
+ value?: string;
247
+ icon?: Icon;
248
+ href?: string;
249
+ tag?: string | {
250
+ value: string;
251
+ color?: Color;
252
+ };
253
+ }
254
+ export interface DetailView extends BaseView {
255
+ type: 'detail';
256
+ /** Markdown. Pass an async iterable (e.g. an AI stream) to stream text in. */
257
+ markdown: string | AsyncIterable<string> | (() => Awaitable<string | AsyncIterable<string>>);
258
+ metadata?: MetadataEntry[];
259
+ }
260
+ export interface FormField {
261
+ name: string;
262
+ label?: string;
263
+ type?: 'text' | 'textarea' | 'password' | 'number' | 'email' | 'url' | 'checkbox' | 'select' | 'date';
264
+ placeholder?: string;
265
+ description?: string;
266
+ required?: boolean;
267
+ defaultValue?: string | number | boolean;
268
+ options?: {
269
+ title: string;
270
+ value: string;
271
+ }[];
272
+ /** Return an error message to block submission. */
273
+ validate?: (value: any, values: Record<string, any>) => string | undefined | void;
274
+ }
275
+ export interface FormView extends BaseView {
276
+ type: 'form';
277
+ fields: FormField[];
278
+ submitLabel?: string;
279
+ onSubmit(values: Record<string, any>, ctx: Context): Awaitable<RunResult>;
280
+ }
281
+ export interface ChatView extends BaseView {
282
+ type: 'chat';
283
+ /** First user message, sent immediately. */
284
+ prompt?: string;
285
+ /** Override the system prompt. */
286
+ system?: string;
287
+ /** Let the model run app commands and tools. Default `true`. */
288
+ tools?: boolean;
289
+ }
290
+ export type View = ListView | GridView | DetailView | FormView | ChatView;
291
+ /** A dynamic provider of root search results (records from your API, docs, …). */
292
+ export interface Source {
293
+ id: string;
294
+ /** Section heading for results. */
295
+ title?: string;
296
+ search(args: LoadArgs): Awaitable<Item[]>;
297
+ /** Minimum query length before `search` runs. Default 1. */
298
+ minQueryLength?: number;
299
+ /** Debounce in ms. Default 150. */
300
+ debounce?: number;
301
+ /** Maximum results shown. Default 8. */
302
+ limit?: number;
303
+ /** Re-rank returned items with the local fuzzy matcher. Default `false`. */
304
+ filter?: boolean;
305
+ /** Show results above (`"top"`) or below (`"bottom"`, default) matching commands. */
306
+ position?: 'top' | 'bottom';
307
+ }
308
+ export interface Preference {
309
+ name: string;
310
+ title: string;
311
+ description?: string;
312
+ type: 'text' | 'password' | 'checkbox' | 'select' | 'number';
313
+ required?: boolean;
314
+ default?: string | number | boolean;
315
+ placeholder?: string;
316
+ options?: {
317
+ title: string;
318
+ value: string;
319
+ }[];
320
+ }
321
+ export interface ExtensionCommand extends Omit<Item, 'id'> {
322
+ /** Unique within the extension. */
323
+ name: string;
324
+ }
325
+ /** A function the AI model may call. */
326
+ export interface Tool<Args = any> {
327
+ name: string;
328
+ description: string;
329
+ /** JSON schema for the arguments object. */
330
+ parameters?: JSONSchema;
331
+ /** Ask the user before running. */
332
+ confirm?: boolean | ((args: Args) => string);
333
+ run(args: Args, ctx: Context): Awaitable<unknown>;
334
+ }
335
+ export type JSONSchema = {
336
+ type?: string | string[];
337
+ properties?: Record<string, JSONSchema>;
338
+ required?: string[];
339
+ items?: JSONSchema;
340
+ enum?: unknown[];
341
+ description?: string;
342
+ [key: string]: unknown;
343
+ };
344
+ export interface Extension {
345
+ /** Unique id, e.g. `"github"`. */
346
+ name: string;
347
+ title: string;
348
+ description?: string;
349
+ icon?: Icon;
350
+ author?: string;
351
+ version?: string;
352
+ /** Settings the extension needs. Missing required values are asked for on first run. */
353
+ preferences?: Preference[];
354
+ commands?: ExtensionCommand[];
355
+ sources?: Source[];
356
+ tools?: Tool[];
357
+ /** Called once when the extension is installed. Return a cleanup function. */
358
+ setup?(ctx: ExtensionSetupContext): void | (() => void);
359
+ }
360
+ export interface ExtensionSetupContext {
361
+ bar: QikbarInstance;
362
+ preferences: Record<string, any>;
363
+ storage: ScopedStorage;
364
+ }
365
+ export interface AIToolCall {
366
+ id: string;
367
+ name: string;
368
+ args: Record<string, unknown>;
369
+ /** Set when the model produced arguments that could not be parsed. The call is not executed. */
370
+ error?: string;
371
+ }
372
+ export interface AIMessage {
373
+ role: 'user' | 'assistant' | 'tool';
374
+ content: string;
375
+ toolCalls?: AIToolCall[];
376
+ /** For `role: 'tool'`. */
377
+ toolCallId?: string;
378
+ toolName?: string;
379
+ isError?: boolean;
380
+ /** Provider-native payload, replayed verbatim on the next request (e.g. thinking blocks). */
381
+ raw?: {
382
+ provider: string;
383
+ data: unknown;
384
+ };
385
+ }
386
+ export interface AIToolDefinition {
387
+ name: string;
388
+ description: string;
389
+ parameters: JSONSchema;
390
+ }
391
+ export interface AIRequest {
392
+ messages: AIMessage[];
393
+ system?: string;
394
+ tools?: AIToolDefinition[];
395
+ signal?: AbortSignal;
396
+ maxTokens?: number;
397
+ }
398
+ export type AIEvent = {
399
+ type: 'text';
400
+ text: string;
401
+ } | {
402
+ type: 'tool_call';
403
+ call: AIToolCall;
404
+ } | {
405
+ type: 'done';
406
+ message: AIMessage;
407
+ stopReason?: string;
408
+ } | {
409
+ type: 'error';
410
+ error: string;
411
+ };
412
+ /** Implement this to plug in any model. */
413
+ export interface AIProvider {
414
+ readonly id: string;
415
+ readonly model?: string;
416
+ /** Whether the provider supports tool calling. Default true. */
417
+ readonly tools?: boolean;
418
+ stream(request: AIRequest): AsyncIterable<AIEvent>;
419
+ }
420
+ export interface AIClient {
421
+ readonly provider: AIProvider;
422
+ /** Ask a one-shot question and get the full answer. */
423
+ ask(prompt: string, options?: {
424
+ system?: string;
425
+ signal?: AbortSignal;
426
+ }): Promise<string>;
427
+ /** Ask a one-shot question and stream the answer. */
428
+ stream(prompt: string, options?: {
429
+ system?: string;
430
+ signal?: AbortSignal;
431
+ }): AsyncIterable<string>;
432
+ }
433
+ export interface StorageAdapter {
434
+ getItem(key: string): string | null;
435
+ setItem(key: string, value: string): void;
436
+ removeItem(key: string): void;
437
+ }
438
+ export interface ScopedStorage {
439
+ get<T = unknown>(key: string): T | undefined;
440
+ set(key: string, value: unknown): void;
441
+ remove(key: string): void;
442
+ }
443
+ export interface ThemeVars {
444
+ font?: string;
445
+ fontMono?: string;
446
+ fontSize?: string;
447
+ bg?: string;
448
+ bgElevated?: string;
449
+ fg?: string;
450
+ fgMuted?: string;
451
+ fgSubtle?: string;
452
+ border?: string;
453
+ selection?: string;
454
+ selectionFg?: string;
455
+ hover?: string;
456
+ accent?: string;
457
+ accentFg?: string;
458
+ highlight?: string;
459
+ overlay?: string;
460
+ backdropBlur?: string;
461
+ shadow?: string;
462
+ radius?: string;
463
+ radiusItem?: string;
464
+ width?: string;
465
+ listHeight?: string;
466
+ rowHeight?: string;
467
+ sectionHeight?: string;
468
+ inputHeight?: string;
469
+ inputFontSize?: string;
470
+ top?: string;
471
+ kbdBg?: string;
472
+ kbdFg?: string;
473
+ danger?: string;
474
+ success?: string;
475
+ warning?: string;
476
+ /** Any other custom property, without the `--qb-` prefix. */
477
+ [key: string]: string | undefined;
478
+ }
479
+ export type ThemePresetName = 'light' | 'dark' | 'raycast' | 'linear' | 'vercel' | 'github' | 'nord' | 'dracula' | 'catppuccin' | 'tokyo-night' | 'rose-pine' | 'solarized' | 'midnight' | 'paper';
480
+ export interface ThemeConfig {
481
+ /** Preset to start from. */
482
+ preset?: ThemePresetName;
483
+ /** Variable overrides for both appearances. */
484
+ vars?: ThemeVars;
485
+ /** Overrides for light appearance. */
486
+ light?: ThemeVars;
487
+ /** Overrides for dark appearance. */
488
+ dark?: ThemeVars;
489
+ }
490
+ export type Appearance = 'light' | 'dark' | 'auto' | (() => 'light' | 'dark');
491
+ export type ClassNameSlot = 'root' | 'overlay' | 'dialog' | 'header' | 'input' | 'list' | 'section' | 'item' | 'footer' | 'actions' | 'detail' | 'form' | 'grid' | 'chat' | 'toast';
492
+ export interface Route {
493
+ path: string;
494
+ title: string;
495
+ subtitle?: string;
496
+ icon?: Icon;
497
+ keywords?: string[];
498
+ section?: string;
499
+ shortcut?: string;
500
+ }
501
+ export type Navigate = (href: string, options: {
502
+ newTab: boolean;
503
+ }) => void;
504
+ export interface QikbarConfig {
505
+ /** Commands shown at the root. */
506
+ commands?: Command[];
507
+ /** Routes in your app; each becomes a "go to" command. */
508
+ routes?: Route[];
509
+ /** Dynamic search providers. */
510
+ sources?: Source[];
511
+ /** Installed extensions. */
512
+ extensions?: (Extension | [Extension, Record<string, any>])[];
513
+ /** Items shown at the bottom when the query has no good matches. `{query}` is replaced in titles. */
514
+ fallbacks?: Item[];
515
+ /** Your router's navigate function. Defaults to clicking a matching link (works with most frameworks). */
516
+ navigate?: Navigate;
517
+ /** Hotkey that toggles the bar. Default `"mod+k"`. Set `false` to disable. */
518
+ hotkey?: string | string[] | false;
519
+ /** Hotkey that opens the action panel for the selected item. Default `"mod+."`. */
520
+ actionsHotkey?: string;
521
+ /** Enable items' global `shortcut`s while the bar is closed. Default true. */
522
+ shortcuts?: boolean;
523
+ placeholder?: string;
524
+ /** Show "Recent" items at the top when the query is empty. Default true. */
525
+ recents?: boolean | number;
526
+ /** Index links in your page automatically (`nav a`, `[data-qikbar]`). */
527
+ autoIndex?: boolean | AutoIndexOptions;
528
+ /** AI provider. Unlocks Ask AI, natural-language commands and `ctx.ai`. */
529
+ ai?: AIProvider | AIOptions;
530
+ /** Functions the AI may call, in addition to running commands. */
531
+ tools?: Tool[];
532
+ theme?: ThemePresetName | ThemeConfig;
533
+ appearance?: Appearance;
534
+ /** Extra classes per UI slot (works great with Tailwind). */
535
+ classNames?: Partial<Record<ClassNameSlot, string>>;
536
+ /** Don't inject default styles. */
537
+ unstyled?: boolean;
538
+ /** CSP nonce for the injected `<style>` tag. */
539
+ nonce?: string;
540
+ /** Render into this element instead of a modal (always open). */
541
+ inline?: HTMLElement | string;
542
+ /** Where the modal is mounted. Default `document.body`. */
543
+ container?: HTMLElement;
544
+ /** Namespace for persistent storage. Default `"qikbar"`. */
545
+ namespace?: string;
546
+ storage?: StorageAdapter;
547
+ /** Text direction. */
548
+ dir?: 'ltr' | 'rtl';
549
+ /** Show the "Powered by qikbar" footer mark. Default false. */
550
+ branding?: boolean;
551
+ /** Footer hint shown at the left when idle. */
552
+ footer?: string;
553
+ /** Translate or reword the UI. See `@qikbar/qikbar/locales` for ready-made translations. */
554
+ labels?: Partial<Labels>;
555
+ /** Let users pin commands to the top and give them aliases. Default true. */
556
+ personalize?: boolean;
557
+ /** Search by meaning as well as by spelling, with embeddings you provide. */
558
+ semantic?: SemanticOptions;
559
+ /** Touch-friendly layout: hides keyboard hints and enables long-press. Default `"auto"` (detects touch screens). */
560
+ touch?: boolean | 'auto';
561
+ /** A floating button that opens the bar, for touch devices and mouse users. */
562
+ launcher?: boolean | 'touch' | LauncherOptions;
563
+ /** Expose your commands to AI agents in the browser through WebMCP (`document.modelContext`). */
564
+ webmcp?: boolean | WebMCPOptions;
565
+ onOpen?: () => void;
566
+ onClose?: () => void;
567
+ /** Called whenever an item or action runs. Useful for analytics. */
568
+ onRun?: (item: Item, action: Action) => void;
569
+ /** Usage events (open, search, run, no results, …) for analytics. */
570
+ onEvent?: (event: QikbarEvent) => void;
571
+ }
572
+ export interface SemanticOptions {
573
+ /** Turn texts into embedding vectors. Use `openaiEmbeddings()`, `ollamaEmbeddings()` or your own. */
574
+ embed(texts: string[], options: {
575
+ signal: AbortSignal;
576
+ }): Promise<number[][]>;
577
+ /** Minimum cosine similarity for a result (0–1). Default 0.35. */
578
+ threshold?: number;
579
+ /** Maximum "Related" results. Default 5. */
580
+ limit?: number;
581
+ /** Minimum query length. Default 3. */
582
+ minQueryLength?: number;
583
+ /** Debounce in ms. Default 250. */
584
+ debounce?: number;
585
+ /** Also embed results from sources. Default false (only commands, routes and extension commands). */
586
+ sources?: boolean;
587
+ }
588
+ export interface LauncherOptions {
589
+ /** Default `"bottom-right"`. */
590
+ position?: 'bottom-right' | 'bottom-left';
591
+ /** Accessible label. Default `labels.openCommandBar`. */
592
+ label?: string;
593
+ /** Only show on touch devices. Default false. */
594
+ touchOnly?: boolean;
595
+ /** Icon name or SVG. Default `"search"`. */
596
+ icon?: string;
597
+ /** Distance from the edges in px. Default 20. */
598
+ offset?: number;
599
+ }
600
+ export interface WebMCPOptions {
601
+ /** Prefix for tool names. Default `"qikbar"`. */
602
+ prefix?: string;
603
+ /** Also expose `ai.tools` and extension tools. Default true. */
604
+ tools?: boolean;
605
+ /** Let agents run commands (otherwise only search/list). Default true. */
606
+ run?: boolean;
607
+ }
608
+ /** A usage event, for analytics. Item details are limited to id, title and section. */
609
+ export type QikbarEvent = {
610
+ type: 'open';
611
+ } | {
612
+ type: 'close';
613
+ } | {
614
+ type: 'search';
615
+ query: string;
616
+ results: number;
617
+ view: string;
618
+ } | {
619
+ type: 'no_results';
620
+ query: string;
621
+ view: string;
622
+ } | {
623
+ type: 'run';
624
+ item: EventItem;
625
+ action: string;
626
+ via: 'keyboard' | 'click' | 'shortcut' | 'panel' | 'ai' | 'agent';
627
+ count?: number;
628
+ } | {
629
+ type: 'ask_ai';
630
+ prompt: string;
631
+ } | {
632
+ type: 'pin' | 'unpin';
633
+ item: EventItem;
634
+ } | {
635
+ type: 'alias';
636
+ item: EventItem;
637
+ alias: string | null;
638
+ } | {
639
+ type: 'undo';
640
+ title: string;
641
+ } | {
642
+ type: 'error';
643
+ message: string;
644
+ };
645
+ export interface EventItem {
646
+ id: string;
647
+ title: string;
648
+ section?: string;
649
+ }
650
+ export interface AutoIndexOptions {
651
+ /** CSS selector for links to index. Default `"nav a[href], header a[href], aside a[href], [data-qikbar-index] a[href]"`. */
652
+ links?: string | false;
653
+ /** Index elements with a `data-qikbar` attribute as commands that click them. Default true. */
654
+ elements?: boolean;
655
+ /** Section title for indexed links. Default `"Pages"`. */
656
+ section?: string;
657
+ }
658
+ export interface AIOptions {
659
+ provider: AIProvider;
660
+ /** System prompt prepended to every conversation. */
661
+ system?: string;
662
+ /** Show the "Ask AI" fallback when the query has text. Default true. */
663
+ fallback?: boolean;
664
+ /** Let the AI run commands/navigate/tools from chat. Default true. */
665
+ tools?: boolean;
666
+ /** Name shown in the UI. Default "AI". */
667
+ name?: string;
668
+ /** Max tool-calling steps per message. Default 6. */
669
+ maxSteps?: number;
670
+ /** Example prompts shown in an empty chat. */
671
+ suggestions?: string[];
672
+ /** Remote tools from MCP servers, e.g. `[mcp({ url: '/api/mcp' })]`. */
673
+ mcp?: ToolProvider[];
674
+ /** Let the AI read the current page's text when asked about it. Default true. */
675
+ pageContext?: boolean;
676
+ }
677
+ export interface QikbarState {
678
+ open: boolean;
679
+ query: string;
680
+ depth: number;
681
+ loading: boolean;
682
+ }
683
+ export interface QikbarEvents {
684
+ open: void;
685
+ close: void;
686
+ change: QikbarState;
687
+ run: {
688
+ item: Item;
689
+ action: Action;
690
+ };
691
+ event: QikbarEvent;
692
+ }
693
+ /** Something that supplies AI tools asynchronously, like an MCP server. */
694
+ export interface ToolProvider {
695
+ readonly name: string;
696
+ /** Load (or reload) the tools. Called before each chat turn; cache inside. */
697
+ tools(signal?: AbortSignal): Promise<Tool[]>;
698
+ }
699
+ export interface QikbarInstance {
700
+ open(options?: {
701
+ query?: string;
702
+ view?: View;
703
+ }): void;
704
+ close(): void;
705
+ toggle(): void;
706
+ readonly isOpen: boolean;
707
+ /** Register commands. Returns an unregister function. */
708
+ register(commands: Command | Command[]): () => void;
709
+ /** Add a source. Returns a remove function. */
710
+ addSource(source: Source): () => void;
711
+ /** Install an extension. Returns an uninstall function. */
712
+ use(extension: Extension, preferences?: Record<string, any>): () => void;
713
+ /** Update configuration. */
714
+ configure(config: Partial<QikbarConfig>): void;
715
+ push(view: View): void;
716
+ pop(): void;
717
+ setQuery(query: string): void;
718
+ readonly query: string;
719
+ toast(options: ToastOptions | string): ToastHandle;
720
+ /** Run an AI chat with an optional prompt. */
721
+ ask(prompt?: string): void;
722
+ readonly ai: AIClient | undefined;
723
+ /** Every root command currently registered (after `when` filtering). */
724
+ commands(): Item[];
725
+ on<K extends keyof QikbarEvents>(event: K, handler: (payload: QikbarEvents[K]) => void): () => void;
726
+ /** Load the UI ahead of time (it otherwise loads when the browser is idle). */
727
+ preload(): Promise<void>;
728
+ /** Pinned item ids, most recent first. */
729
+ pins(): string[];
730
+ /** Pin or unpin an item by id. */
731
+ pin(id: string, pinned?: boolean): void;
732
+ /** Aliases, as `{ alias: itemId }`. */
733
+ aliases(): Record<string, string>;
734
+ /** Set (or with `null`, remove) the alias for an item. */
735
+ setAlias(id: string, alias: string | null): void;
736
+ destroy(): void;
737
+ }