aktion-runtime 0.5.5 → 0.5.6

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 (37) hide show
  1. package/README.md +120 -15
  2. package/dist/aktion.iife.js +42 -42
  3. package/dist/aktion.iife.js.map +1 -1
  4. package/dist/aktion.js +12663 -12149
  5. package/dist/aktion.js.map +1 -1
  6. package/dist/aktion.umd.cjs +42 -42
  7. package/dist/aktion.umd.cjs.map +1 -1
  8. package/dist/language.js +1348 -98
  9. package/dist/language.js.map +1 -1
  10. package/dist/plugin.cjs +12 -2
  11. package/dist/plugin.cjs.map +1 -1
  12. package/dist/plugin.js +12 -2
  13. package/dist/plugin.js.map +1 -1
  14. package/dist/system_prompt.txt +40 -8
  15. package/dist/system_prompt_chat.txt +2 -1
  16. package/dist/testing.js +15221 -14527
  17. package/dist/testing.js.map +1 -1
  18. package/dist/types/element.d.ts +0 -1
  19. package/dist/types/language/builtins.d.ts +52 -0
  20. package/dist/types/language/index.d.ts +5 -2
  21. package/dist/types/language-api.d.ts +5 -1
  22. package/dist/types/library/components/helpers.d.ts +0 -5
  23. package/dist/types/library/components/wrappers.d.ts +1 -0
  24. package/dist/types/parser/types.d.ts +0 -1
  25. package/dist/types/runtime/effects.d.ts +1 -18
  26. package/dist/types/runtime/evaluator.d.ts +46 -5
  27. package/dist/types/runtime/http.d.ts +41 -0
  28. package/dist/types/runtime/index.d.ts +2 -1
  29. package/dist/types/runtime/router.d.ts +28 -2
  30. package/dist/types/runtime/toast.d.ts +45 -0
  31. package/dist/types/runtime/util.d.ts +11 -1
  32. package/dist/types/tooling/index.d.ts +6 -0
  33. package/dist/types/tooling/language-service.d.ts +10 -5
  34. package/dist/types/tooling/navigation.d.ts +91 -0
  35. package/dist/types/tooling/semantic-tokens.d.ts +24 -0
  36. package/dist/types/tooling/signature-help.d.ts +21 -0
  37. package/package.json +1 -1
@@ -13,7 +13,6 @@ export declare class AktionElement extends HTMLElement {
13
13
  private library;
14
14
  private readonly http;
15
15
  private readonly effectRunner;
16
- private readonly actionDeclRunner;
17
16
  private renderer;
18
17
  private context;
19
18
  private root;
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Catalog of Aktion's `$`-prefixed builtins — the single source of truth for
3
+ * editor tooling (completions, hover, semantic highlighting, the TextMate
4
+ * grammar generator, and signature help).
5
+ *
6
+ * Aktion's runtime "builtins" are all `$`-prefixed forms. Some are hooks
7
+ * (`$state`, `$memo`, …), some are reactive factories (`$store`, `$http`, …),
8
+ * some register the app / router / theme, and some resolve to a namespace
9
+ * object (`$util.format(...)`, `$storage.local`, …). The legacy `@`-builtin
10
+ * catalog was removed in 0.5; programs use native JavaScript or `$util`.
11
+ *
12
+ * Keep this list in sync with the runtime dispatch in
13
+ * `src/runtime/evaluator.ts` (`evaluateInvoke` for `StateRef` callees) and the
14
+ * namespace implementations in `src/runtime/*`. Anything added here is
15
+ * automatically surfaced to every editor that consumes `aktion-runtime/language`.
16
+ */
17
+ export type BuiltinCategory = "hook" | "effect" | "data" | "app" | "routing" | "theme" | "event" | "namespace";
18
+ export interface BuiltinEntry {
19
+ /** Name WITHOUT the leading `$` sigil (e.g. `"state"`, `"util"`). */
20
+ name: string;
21
+ /** Reference form WITH the sigil (e.g. `"$state"`). */
22
+ sigil: string;
23
+ category: BuiltinCategory;
24
+ /** Completion label / signature skeleton, e.g. `"$state(initial)"`. */
25
+ signature: string;
26
+ /** One-line description for hover popups and completion detail. */
27
+ summary: string;
28
+ /**
29
+ * True when the name resolves to a namespace object whose members are
30
+ * reached via `.` (`$util.format`, `$storage.local`, `$toast.show`, …).
31
+ * Namespaces are NOT necessarily callable.
32
+ */
33
+ namespace?: boolean;
34
+ }
35
+ /**
36
+ * Every `$`-prefixed builtin Aktion exposes, grouped loosely by purpose.
37
+ * The order is the order editors surface them in the after-`$` completion
38
+ * list, so the most common authoring tools (hooks, effects) come first.
39
+ */
40
+ export declare const builtinCatalog: readonly BuiltinEntry[];
41
+ /** Bare builtin names (without the `$` sigil), for O(1) membership tests. */
42
+ export declare const builtinNames: ReadonlySet<string>;
43
+ /** Catalog indexed by the bare name (`"state"`, `"util"`, …). */
44
+ export declare const builtinsByName: Readonly<Record<string, BuiltinEntry>>;
45
+ /**
46
+ * Resolve a `$`-prefixed builtin by its bare name (the value carried on a
47
+ * `StateIdentifier` token, e.g. `"state"` for `$state`). Returns `undefined`
48
+ * for user atoms / hooks that are not part of the runtime catalog.
49
+ */
50
+ export declare function findBuiltin(bareName: string): BuiltinEntry | undefined;
51
+ /** True when `bareName` (no `$`) names a runtime builtin. */
52
+ export declare function isBuiltinName(bareName: string): boolean;
@@ -2,8 +2,9 @@ import { ComponentLibrary } from '../library/types.js';
2
2
  import { grammarSpec, createStreamTokenizer, defaultTagMap, keywordDocs, GrammarSpec, GrammarTokenKind, StreamTokenizer, KeywordDoc } from './grammar.js';
3
3
  import { getComponentCatalog, indexCatalog, ComponentEntry, ComponentParam } from './components.js';
4
4
  import { getSnippets, SnippetEntry } from './snippets.js';
5
- export type { GrammarSpec, GrammarTokenKind, StreamTokenizer, KeywordDoc, ComponentEntry, ComponentParam, SnippetEntry, };
6
- export { grammarSpec, createStreamTokenizer, defaultTagMap, keywordDocs, getComponentCatalog, indexCatalog, getSnippets, };
5
+ import { builtinCatalog, builtinNames, builtinsByName, findBuiltin, isBuiltinName, BuiltinEntry, BuiltinCategory } from './builtins.js';
6
+ export type { GrammarSpec, GrammarTokenKind, StreamTokenizer, KeywordDoc, ComponentEntry, ComponentParam, SnippetEntry, BuiltinEntry, BuiltinCategory, };
7
+ export { grammarSpec, createStreamTokenizer, defaultTagMap, keywordDocs, getComponentCatalog, indexCatalog, getSnippets, builtinCatalog, builtinNames, builtinsByName, findBuiltin, isBuiltinName, };
7
8
  /**
8
9
  * Diagnostic severity buckets that map to common editor lint levels.
9
10
  * Editors typically map: `error` → red squiggle, `warning` → yellow,
@@ -18,6 +19,8 @@ export interface LanguageSpec {
18
19
  tagMap: Record<GrammarTokenKind, string | null>;
19
20
  components: ComponentEntry[];
20
21
  componentsByName: Record<string, ComponentEntry>;
22
+ /** Catalog of `$`-prefixed builtins (hooks, factories, namespaces). */
23
+ builtins: readonly BuiltinEntry[];
21
24
  snippets: readonly SnippetEntry[];
22
25
  /**
23
26
  * Reserved-keyword documentation (definition + syntax + example),
@@ -10,6 +10,10 @@
10
10
  * Node-safe (no DOM access at import time).
11
11
  */
12
12
  export { getDiagnostics, getCompletions, getHoverInfo, type Position, type Diagnostic, type CompletionItem, type HoverInfo, } from './tooling/language-service.js';
13
- export { getLanguageSpec, grammarSpec, keywordDocs, getComponentCatalog, getSnippets, type LanguageSpec, type GrammarSpec, type ComponentEntry, type ComponentParam, type SnippetEntry, type KeywordDoc, } from './language/index.js';
13
+ export { getDefinition, getDefinitionTarget, findDeclaration, getReferences, getDocumentHighlights, getDocumentSymbols, getRenameEdits, type Range, type TextEdit, type RenameResult, type DocumentSymbol, type SymbolKind, type DefinitionTarget, } from './tooling/navigation.js';
14
+ export { getSemanticTokens, semanticTokenTypes, semanticTokenModifiers, type SemanticToken, type SemanticTokenType, type SemanticTokenModifier, } from './tooling/semantic-tokens.js';
15
+ export { getSignatureHelp, type SignatureHelp, type SignatureInfo, type ParameterInfo, } from './tooling/signature-help.js';
16
+ export { getLanguageSpec, grammarSpec, keywordDocs, getComponentCatalog, getSnippets, builtinCatalog, findBuiltin, isBuiltinName, type LanguageSpec, type GrammarSpec, type ComponentEntry, type ComponentParam, type SnippetEntry, type KeywordDoc, type BuiltinEntry, type BuiltinCategory, } from './language/index.js';
17
+ export { formatProgram, type FormatResult } from './tooling/formatter.js';
14
18
  export { defaultLibrary } from './library/index.js';
15
19
  export type { ComponentLibrary } from './library/types.js';
@@ -20,11 +20,6 @@ export declare const Portal: ComponentSpec;
20
20
  * recognises the rendered output and redirects the router immediately.
21
21
  */
22
22
  export declare const Redirect: ComponentSpec;
23
- /**
24
- * `Lazy(loader, fallback?)` — Defer the children until the `loader`
25
- * promise resolves. The `loader` can be either a function returning a
26
- * promise or a promise directly.
27
- */
28
23
  export declare const Lazy: ComponentSpec;
29
24
  /**
30
25
  * `ErrorBoundary(fallback?, onError?, children)` — catches rendering
@@ -4,6 +4,7 @@ export declare const OnMouse: ComponentSpec;
4
4
  export declare const OnKeyboard: ComponentSpec;
5
5
  export declare const OnFocus: ComponentSpec;
6
6
  export declare const OnIntersect: ComponentSpec;
7
+ export declare const OnMount: ComponentSpec;
7
8
  export declare const Link: ComponentSpec;
8
9
  export declare const Css: ComponentSpec;
9
10
  export declare function attachOnChange(element: HTMLElement, callback: unknown, helpers: RenderHelpers, options: {
@@ -325,7 +325,6 @@ export interface ActionDeclaration {
325
325
  kind: "ActionDeclaration";
326
326
  name: string;
327
327
  params: ReadonlyArray<DeclParam>;
328
- optimistic: boolean;
329
328
  body: BlockExpr;
330
329
  /** True when prefixed with `export` (multi-file modules). */
331
330
  exported?: boolean;
@@ -1,4 +1,4 @@
1
- import { ActionDeclaration, EffectDeclaration } from '../parser/types.js';
1
+ import { EffectDeclaration } from '../parser/types.js';
2
2
  import { EvaluationContext, ScopedEffectDecl } from './evaluator.js';
3
3
  import { StateStore } from './state.js';
4
4
  import { EffectEventPayload } from '../devtools/protocol.js';
@@ -59,20 +59,3 @@ export declare class EffectRunner {
59
59
  private emitEffect;
60
60
  private unmount;
61
61
  }
62
- export interface ActionRunnerOptions {
63
- state: StateStore;
64
- notify: () => void;
65
- onEmit?: (eventName: string, detail: unknown) => void;
66
- onAssistantMessage?: (message: string) => void;
67
- }
68
- /**
69
- * Run an `action` declaration. When the declaration is `optimistic` we
70
- * snapshot every state atom touched before the first `await`; if any
71
- * subsequent step throws, the snapshot is restored.
72
- */
73
- export declare class ActionDeclRunner {
74
- private readonly options;
75
- constructor(options: ActionRunnerOptions);
76
- run(decl: ActionDeclaration, callArgs: unknown[], ctx: EvaluationContext): Promise<unknown>;
77
- private runStatement;
78
- }
@@ -1,9 +1,9 @@
1
1
  import { Expression, Program, Statement, ComponentDeclaration, EffectDeclaration, ActionDeclaration, HookDeclaration, DestructuringPattern } from '../parser/types.js';
2
2
  import { StateStore } from './state.js';
3
- import { HttpRuntime } from './http.js';
4
- import { ActionDeclRunner } from './effects.js';
3
+ import { HttpRuntime, EndpointResource } from './http.js';
5
4
  import { Router } from './router.js';
6
5
  import { ComponentLibrary } from '../library/types.js';
6
+ import { ToastManager } from './toast.js';
7
7
  /**
8
8
  * Runtime safety budget — bounds the work a single render can perform
9
9
  * so a partial / accidentally-recursive program (e.g. while the user is
@@ -208,6 +208,17 @@ export type HookCell = {
208
208
  kind: "memo";
209
209
  deps: ReadonlyArray<unknown> | undefined;
210
210
  value: unknown;
211
+ } | {
212
+ kind: "ref";
213
+ box: {
214
+ current: unknown;
215
+ };
216
+ } | {
217
+ kind: "reducer";
218
+ value: unknown;
219
+ } | {
220
+ kind: "id";
221
+ value: string;
211
222
  };
212
223
  /**
213
224
  * Active hook scope — the component instance currently rendering, plus a
@@ -313,12 +324,41 @@ export interface EvaluationContext {
313
324
  stores: Map<string, StoreHandle>;
314
325
  /** HTTP runtime (`Http({...})` calls + interceptor configuration). */
315
326
  http?: HttpRuntime;
316
- /** Action runner for function declarations. */
317
- actionRunner?: ActionDeclRunner;
327
+ /**
328
+ * Shared cache of `$query({...})` resources, keyed by the query's `key`
329
+ * (or a value derived from method + url + query + body). Lets repeated and
330
+ * cross-component queries share one in-flight request / cached result.
331
+ * Lives as long as the program; rebuilt on replan with a fresh context.
332
+ */
333
+ queryCache: Map<string, EndpointResource>;
334
+ /**
335
+ * Lazily-created singleton backing the reserved `$toast` namespace
336
+ * (`$toast.show(...)`, `$toast.items`, …). Created on first reference via
337
+ * `getToastManager`; its auto-dismiss timers are cleared on dispose.
338
+ */
339
+ toastManager?: ToastManager;
318
340
  /** Notify the host that something changed and a re-render is needed. */
319
341
  notify?: () => void;
320
342
  /** Dispatch a custom event from an `emit("name", detail)` call. */
321
343
  onEmit?: (eventName: string, detail: unknown) => void;
344
+ /**
345
+ * Active teardown sink during an effect-body run. When set, a bare
346
+ * `cleanup` identifier resolves to a real bound function that pushes into
347
+ * the running effect's cleanup list — so `cleanup(fn)` keeps working even
348
+ * when aliased (`const c = cleanup; c(fn)`) or used inside a nested block,
349
+ * rather than being detected only by literal callee name (feedback §2.5).
350
+ * Unset outside effect runs, where `cleanup` has no meaning.
351
+ */
352
+ cleanupSink?: ((fn: () => void) => void) | null;
353
+ /**
354
+ * Dev/strict mode (opt-in via the `strict` attribute on `<aktion-app>`).
355
+ * When set, the evaluator surfaces silent failures — currently unknown
356
+ * bare identifiers that would otherwise resolve to `null` — as
357
+ * `console.warn`s. Off by default so production behaviour is unchanged.
358
+ */
359
+ strict?: boolean;
360
+ /** De-dupes strict-mode warnings to one per identifier per program. */
361
+ strictWarned: Set<string>;
322
362
  /**
323
363
  * Cleanup callbacks attached to this context. Populated during
324
364
  * `planProgram` for resources that outlive a single evaluation pass —
@@ -361,9 +401,10 @@ export interface CreateContextOptions {
361
401
  router?: Router;
362
402
  library?: ComponentLibrary;
363
403
  http?: HttpRuntime;
364
- actionRunner?: ActionDeclRunner;
365
404
  notify?: () => void;
366
405
  onEmit?: (eventName: string, detail: unknown) => void;
406
+ /** Enable dev/strict-mode warnings for silent failures. */
407
+ strict?: boolean;
367
408
  /**
368
409
  * Runtime safety budget for this context.
369
410
  * - omitted (default): a fresh budget with `DEFAULT_RUNTIME_BUDGET` limits.
@@ -87,3 +87,44 @@ export declare class HttpRuntime {
87
87
  * is what makes back-to-back refetches and cancels deterministic.
88
88
  */
89
89
  export declare function createHttpResource(config: unknown, ctx: EvaluationContext): EndpointResource;
90
+ /**
91
+ * `$query({ url, key?, ttl?, ... })` — a cached, deduplicated `$http` read.
92
+ *
93
+ * Unlike `$http`, which fires a fresh request on every call, `$query` keys
94
+ * the resource by `key` (or a value derived from method + url + query + body)
95
+ * and reuses the same reactive bag across renders and across components. The
96
+ * first caller creates the request; everyone else with the same key shares
97
+ * the in-flight result (deduplication). Pass `ttl` (ms) to auto-refetch when
98
+ * the cached data is older than the TTL.
99
+ */
100
+ export declare function createQueryResource(config: unknown, ctx: EvaluationContext): EndpointResource;
101
+ /** Reactive bag returned by `$mutation({...})`. Fires only on `mutate()`. */
102
+ export interface MutationResource {
103
+ data: unknown;
104
+ error: unknown;
105
+ loading: boolean;
106
+ status?: number;
107
+ /**
108
+ * Fire the request. Optionally pass an overrides object (shallow-merged
109
+ * over the base config) to set the `body` / `query` / `url` for this call:
110
+ * $save.mutate({ body: { title: $title } })
111
+ * Resolves with the response body (or `undefined` on error / supersede).
112
+ */
113
+ mutate: (overrides?: unknown) => Promise<unknown>;
114
+ /** Clear `data` / `error` / `loading` back to the resting state. */
115
+ reset: () => void;
116
+ /** Optional completion callback; fires once each time a mutation settles. */
117
+ onDone?: (resource: MutationResource) => void;
118
+ }
119
+ /**
120
+ * `$mutation({ url, method?, ... })` — a write that fires only when you call
121
+ * `.mutate(...)`, not on render. The canonical create/update/delete pattern:
122
+ *
123
+ * $save = $mutation({ url: "/todos", method: "POST" })
124
+ * ...
125
+ * Button("Add", { onClick: () => $save.mutate({ body: { title: $title } }) })
126
+ *
127
+ * Method defaults to `POST` when unspecified. The bag exposes reactive
128
+ * `loading` / `error` / `data` plus `reset()` and an `onDone` hook.
129
+ */
130
+ export declare function createMutationResource(baseConfig: unknown, ctx: EvaluationContext): MutationResource;
@@ -6,4 +6,5 @@ export * from './http.js';
6
6
  export * from './i18n.js';
7
7
  export { storage, type CookieOptions, type StorageNamespace, type StorageRoot } from './storage.js';
8
8
  export { consoleNs, type ConsoleNamespace } from './console.js';
9
- export { EffectRunner, ActionDeclRunner, type EffectRunnerOptions, type ActionRunnerOptions, } from './effects.js';
9
+ export { createToastManager, type ToastManager, type ToastItem, type ToastOptions, } from './toast.js';
10
+ export { EffectRunner, type EffectRunnerOptions, } from './effects.js';
@@ -34,6 +34,18 @@ export type RouteListener = (detail: RouteChangeDetail) => void;
34
34
  export interface RouterOptions {
35
35
  /** Initial path when no hash is set. Defaults to `/`. */
36
36
  defaultPath?: string;
37
+ /**
38
+ * URL strategy. `"hash"` (default) keeps everything after `#/…` and works
39
+ * on any static host. `"history"` uses the HTML5 History API (clean
40
+ * `/about` URLs) and requires the server to fall back to `index.html` for
41
+ * unknown paths.
42
+ */
43
+ mode?: "hash" | "history";
44
+ /**
45
+ * Optional base path stripped from / prepended to URLs in `"history"` mode
46
+ * (e.g. `"/app"` when the SPA is served under a sub-directory).
47
+ */
48
+ basePath?: string;
37
49
  }
38
50
  /**
39
51
  * Normalise an arbitrary string into a clean route path.
@@ -68,15 +80,29 @@ export declare class Router {
68
80
  private hashListener;
69
81
  private listeners;
70
82
  private readonly defaultPath;
71
- /** True while we're updating `window.location.hash` ourselves — used to
72
- * filter out the resulting `hashchange` echo. */
83
+ private mode;
84
+ private basePath;
85
+ /** True while we're updating `window.location` ourselves — used to
86
+ * filter out the resulting `hashchange` / `popstate` echo. */
73
87
  private settingHash;
74
88
  constructor(options?: RouterOptions);
89
+ /**
90
+ * Re-configure the URL strategy before `start()` is called. The host
91
+ * element uses this to apply the `router-mode` / `router-base` attributes
92
+ * it reads at connect time. No-op once the router is already enabled.
93
+ */
94
+ configure(options: {
95
+ mode?: "hash" | "history";
96
+ basePath?: string;
97
+ }): void;
98
+ getMode(): "hash" | "history";
75
99
  /**
76
100
  * Attach the `hashchange` listener and synchronise from the current URL.
77
101
  * Safe to call multiple times — it's idempotent.
78
102
  */
79
103
  start(): void;
104
+ /** Read the active path from `window.location` per the current mode. */
105
+ private readLocation;
80
106
  /**
81
107
  * Detach the `hashchange` listener. The current path stays as the last
82
108
  * observed value so a follow-up `start()` resumes cleanly.
@@ -0,0 +1,45 @@
1
+ import { EvaluationContext } from './evaluator.js';
2
+ /** A single live toast tracked by the `$toast` manager. */
3
+ export interface ToastItem {
4
+ id: string;
5
+ message: string;
6
+ title?: string;
7
+ /** Visual accent, mapped onto the `Toast` component's `tone`. */
8
+ tone: string;
9
+ /** Auto-dismiss delay in ms; `0` keeps the toast until dismissed. */
10
+ duration: number;
11
+ /** ms-epoch the toast was shown — handy for ordering / debugging. */
12
+ createdAt: number;
13
+ }
14
+ /** Options accepted by `$toast.show(message, options)` and the shortcuts. */
15
+ export interface ToastOptions {
16
+ title?: string;
17
+ tone?: string;
18
+ duration?: number;
19
+ }
20
+ /** Imperative surface exposed as the reserved `$toast` namespace. */
21
+ export interface ToastManager {
22
+ /** Reactive list of live toasts (newest last). Treat as read-only. */
23
+ items: ToastItem[];
24
+ /** Show a toast; returns its id. `message` is coerced to a string. */
25
+ show: (message: unknown, options?: ToastOptions) => string;
26
+ /** `show` with `tone: "success"`. */
27
+ success: (message: unknown, options?: ToastOptions) => string;
28
+ /** `show` with `tone: "danger"`. */
29
+ error: (message: unknown, options?: ToastOptions) => string;
30
+ /** `show` with `tone: "info"`. */
31
+ info: (message: unknown, options?: ToastOptions) => string;
32
+ /** `show` with `tone: "warning"`. */
33
+ warning: (message: unknown, options?: ToastOptions) => string;
34
+ /** Remove a single toast by id (no-op if already gone). */
35
+ dismiss: (id: string) => void;
36
+ /** Remove every toast. */
37
+ clear: () => void;
38
+ }
39
+ /**
40
+ * Build a context-scoped toast manager. Registers a disposer that clears any
41
+ * pending auto-dismiss timers when the context is torn down (replan /
42
+ * disconnect), so a previous program's toasts can never fire against a stale
43
+ * scope.
44
+ */
45
+ export declare function createToastManager(ctx: EvaluationContext): ToastManager;
@@ -20,7 +20,9 @@
20
20
  * text = Util.plural(items.length, "item")
21
21
  *
22
22
  * Comparators for `filter` / `find` accept the operator strings
23
- * `"=="`, `"!="`, `">"`, `"<"`, `">="`, `"<="`, `"contains"`.
23
+ * `"=="`, `"!="`, `">"`, `"<"`, `">="`, `"<="`, `"contains"`,
24
+ * `"startsWith"`, `"endsWith"`. The string operators (`contains` /
25
+ * `startsWith` / `endsWith`) match case-insensitively.
24
26
  */
25
27
  export declare const Util: {
26
28
  readonly count: (arr: unknown) => number;
@@ -40,6 +42,14 @@ export declare const Util: {
40
42
  readonly range: (start: number, end: number, step?: number) => number[];
41
43
  readonly repeat: <T>(value: T, n: number) => T[];
42
44
  readonly pick: (obj: unknown, keys: unknown) => Record<string, unknown>;
45
+ readonly omit: (obj: unknown, keys: unknown) => Record<string, unknown>;
46
+ readonly chunk: (arr: unknown, size: number) => unknown[][];
47
+ readonly flatten: (arr: unknown, depth?: number) => unknown[];
48
+ readonly zip: (...arrays: unknown[]) => unknown[][];
49
+ readonly partition: (arr: unknown, field?: string, op?: string, value?: unknown) => [unknown[], unknown[]];
50
+ readonly keyBy: (arr: unknown, field?: string) => Record<string, unknown>;
51
+ readonly cloneDeep: <T>(value: T) => T;
52
+ readonly merge: (target: unknown, ...sources: unknown[]) => Record<string, unknown>;
43
53
  /**
44
54
  * Locale-aware number formatter. Modes: `"number"` (default),
45
55
  * `"currency"`, `"percent"`, `"compact"`. Options object:
@@ -24,3 +24,9 @@ export { inspectAST, inspectProgram } from './inspector.js';
24
24
  export type { InspectorBinding, InspectorView } from './inspector.js';
25
25
  export { getDiagnostics, getCompletions, getHoverInfo, } from './language-service.js';
26
26
  export type { Position, Diagnostic, CompletionItem, HoverInfo, } from './language-service.js';
27
+ export { getDefinition, getDefinitionTarget, findDeclaration, getReferences, getDocumentHighlights, getDocumentSymbols, getRenameEdits, } from './navigation.js';
28
+ export type { Range, TextEdit, RenameResult, DocumentSymbol, SymbolKind, DefinitionTarget, } from './navigation.js';
29
+ export { getSemanticTokens, semanticTokenTypes, semanticTokenModifiers, } from './semantic-tokens.js';
30
+ export type { SemanticToken, SemanticTokenType, SemanticTokenModifier, } from './semantic-tokens.js';
31
+ export { getSignatureHelp, } from './signature-help.js';
32
+ export type { SignatureHelp, SignatureInfo, ParameterInfo, } from './signature-help.js';
@@ -43,11 +43,16 @@ export declare function getDiagnostics(source: string, library: ComponentLibrary
43
43
  * intentionally simple — the prompt + the closed schema (§16) make
44
44
  * deep static analysis unnecessary:
45
45
  *
46
- * - Inside `(...)` after a known component name → the spec's prop
47
- * names (filtered to unconsumed props).
48
- * - After `$` → state-tier keywords (`$state`, `$persist`, …).
49
- * - At top of line / inside a block → top-level keywords + the
50
- * full library component list.
46
+ * - After `$` → the reactive-atom hint + the `$`-builtin catalog.
47
+ * - Inside a component call's trailing `{ … }` props object → that
48
+ * component's prop names, FOLLOWED BY the general list (so you can
49
+ * still reference components / atoms / actions in prop values).
50
+ * - Everywhere else (top of line, inside a `[ … ]` children array, a
51
+ * `( … )` argument list) → the general list: author-declared symbols,
52
+ * keywords, and the full component library. Components are ALWAYS
53
+ * offered here — a children array like `Column([ Sidebar() ])` is the
54
+ * most common authoring position, so suppressing components there
55
+ * (the old behaviour) broke the headline autocomplete.
51
56
  */
52
57
  export declare function getCompletions(source: string, position: Position, library: ComponentLibrary): CompletionItem[];
53
58
  /**
@@ -0,0 +1,91 @@
1
+ import { Position } from './language-service.js';
2
+ export interface Range {
3
+ /** 1-indexed inclusive start. */
4
+ start: Position;
5
+ /** 1-indexed exclusive end (column points one past the last character). */
6
+ end: Position;
7
+ }
8
+ export interface TextEdit {
9
+ range: Range;
10
+ newText: string;
11
+ }
12
+ export interface RenameResult {
13
+ edits: TextEdit[];
14
+ /** Set when the rename is rejected (the symbol cannot be renamed safely). */
15
+ error?: string;
16
+ }
17
+ export type SymbolKind = "component" | "action" | "hook" | "state" | "import";
18
+ /**
19
+ * Resolved go-to-definition target. Cross-file navigation lives in the host
20
+ * (it must read the imported file), so the service classifies the cursor:
21
+ *
22
+ * - `local` → a declaration in THIS file (`range` is set).
23
+ * - `import-binding` → an imported name; the host resolves `moduleSource`
24
+ * to a file and looks up `imported` there.
25
+ * - `module` → the module specifier string itself (open the file).
26
+ */
27
+ export interface DefinitionTarget {
28
+ kind: "local" | "import-binding" | "module";
29
+ /** Set for `kind: "local"` — the declaration range in this file. */
30
+ range?: Range;
31
+ /** Set for `kind: "import-binding"` — the name as exported by the module. */
32
+ imported?: string;
33
+ /** Set for `kind: "import-binding"` — whether the binding is a `$state` atom. */
34
+ isState?: boolean;
35
+ /** Set for `import-binding` + `module` — the raw module specifier. */
36
+ moduleSource?: string;
37
+ }
38
+ export interface DocumentSymbol {
39
+ /** Display name — includes the `$` sigil for state atoms / hooks. */
40
+ name: string;
41
+ /** Human-readable category, e.g. `"component"`. */
42
+ detail: string;
43
+ kind: SymbolKind;
44
+ /** Span used for the outline row (here: the name token). */
45
+ range: Range;
46
+ /** Span the editor reveals/selects when the row is picked (the name). */
47
+ selectionRange: Range;
48
+ }
49
+ /**
50
+ * Location of the declaration for the symbol under `position`, or `null` when
51
+ * the cursor is not over a navigable, file-scoped symbol.
52
+ */
53
+ export declare function getDefinition(source: string, position: Position): Range | null;
54
+ /**
55
+ * Classify the go-to-definition target under `position`. Unlike
56
+ * `getDefinition` (which only ever resolves within the current file), this
57
+ * also recognises imported bindings and the module specifier string so a host
58
+ * can perform cross-file navigation. Returns `null` when there is nothing to
59
+ * jump to.
60
+ */
61
+ export declare function getDefinitionTarget(source: string, position: Position): DefinitionTarget | null;
62
+ /**
63
+ * Find the declaration of a top-level `name` in `source` (used by a host to
64
+ * land on an imported symbol's definition in another file). `isState`
65
+ * disambiguates the `$`-namespace from the identifier namespace.
66
+ */
67
+ export declare function findDeclaration(source: string, name: string, isState: boolean): Range | null;
68
+ /**
69
+ * Every occurrence of the symbol under `position`. For a known file-scoped
70
+ * declaration this is precise; for an unrecognised identifier it falls back to
71
+ * same-name, same-kind tokens (handy as document highlights).
72
+ */
73
+ export declare function getReferences(source: string, position: Position, options?: {
74
+ includeDeclaration?: boolean;
75
+ }): Range[];
76
+ /**
77
+ * Highlight all occurrences of the symbol under `position` (the editor paints
78
+ * these when the cursor rests on a name). Always includes the declaration.
79
+ */
80
+ export declare function getDocumentHighlights(source: string, position: Position): Range[];
81
+ /**
82
+ * Rename a file-scoped symbol. Returns the edits to apply, or an `error`
83
+ * explaining why the rename was rejected (unknown symbol, invalid new name).
84
+ * `newName` may be supplied with or without the leading `$`.
85
+ */
86
+ export declare function getRenameEdits(source: string, position: Position, newName: string): RenameResult;
87
+ /**
88
+ * The document outline: every top-level declaration (atoms, components,
89
+ * actions, hooks) and `import` binding, in source order.
90
+ */
91
+ export declare function getDocumentSymbols(source: string): DocumentSymbol[];
@@ -0,0 +1,24 @@
1
+ import { ComponentLibrary } from '../library/types.js';
2
+ /** Token type legend (the host registers these in the same order). */
3
+ export declare const semanticTokenTypes: readonly ["namespace", "class", "function", "variable", "property", "keyword", "number"];
4
+ export type SemanticTokenType = (typeof semanticTokenTypes)[number];
5
+ /** Token modifier legend (a token may carry several). */
6
+ export declare const semanticTokenModifiers: readonly ["declaration", "defaultLibrary"];
7
+ export type SemanticTokenModifier = (typeof semanticTokenModifiers)[number];
8
+ export interface SemanticToken {
9
+ /** 1-indexed line. */
10
+ line: number;
11
+ /** 1-indexed column (start). */
12
+ column: number;
13
+ /** Character length of the token (includes `$` for state identifiers). */
14
+ length: number;
15
+ tokenType: SemanticTokenType;
16
+ tokenModifiers: SemanticTokenModifier[];
17
+ }
18
+ /**
19
+ * Classify every meaningful token in `source`. Unknown lowercase identifiers
20
+ * (locals, params, bare globals) are intentionally left untagged so the
21
+ * TextMate layer keeps colouring them — semantic tokens only fire where we can
22
+ * say something the regex grammar cannot.
23
+ */
24
+ export declare function getSemanticTokens(source: string, library?: ComponentLibrary): SemanticToken[];
@@ -0,0 +1,21 @@
1
+ import { ComponentLibrary } from '../library/types.js';
2
+ import { Position } from './language-service.js';
3
+ export interface ParameterInfo {
4
+ label: string;
5
+ documentation?: string;
6
+ }
7
+ export interface SignatureInfo {
8
+ label: string;
9
+ documentation?: string;
10
+ parameters: ParameterInfo[];
11
+ }
12
+ export interface SignatureHelp {
13
+ signatures: SignatureInfo[];
14
+ activeSignature: number;
15
+ activeParameter: number;
16
+ }
17
+ /**
18
+ * Signature help for the call enclosing `position`, or `null` when the cursor
19
+ * is not inside a recognised call.
20
+ */
21
+ export declare function getSignatureHelp(source: string, position: Position, library?: ComponentLibrary): SignatureHelp | null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aktion-runtime",
3
- "version": "0.5.5",
3
+ "version": "0.5.6",
4
4
  "description": "Aktion is a single web component that turns a compact, streaming-first DSL into a rich, interactive UI inside its shadow DOM. Works in React, Vue, Angular, Svelte, plain HTML — or no framework at all.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",