aktion-runtime 0.5.9 → 0.5.11

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 (60) hide show
  1. package/README.md +216 -36
  2. package/dist/aktion.iife.js +920 -144
  3. package/dist/aktion.iife.js.map +1 -1
  4. package/dist/aktion.js +17025 -10815
  5. package/dist/aktion.js.map +1 -1
  6. package/dist/aktion.umd.cjs +920 -144
  7. package/dist/aktion.umd.cjs.map +1 -1
  8. package/dist/devtools.js +554 -20
  9. package/dist/devtools.js.map +1 -1
  10. package/dist/language.js +7042 -2455
  11. package/dist/language.js.map +1 -1
  12. package/dist/plugin.cjs +2 -2
  13. package/dist/plugin.cjs.map +1 -1
  14. package/dist/plugin.js +2 -2
  15. package/dist/plugin.js.map +1 -1
  16. package/dist/system_prompt.txt +292 -41
  17. package/dist/system_prompt_chat.txt +14 -14
  18. package/dist/testing.js +16223 -7977
  19. package/dist/testing.js.map +1 -1
  20. package/dist/types/devtools/panel.d.ts +32 -0
  21. package/dist/types/devtools/styles.d.ts +1 -1
  22. package/dist/types/element.d.ts +26 -0
  23. package/dist/types/icons/index.d.ts +10 -0
  24. package/dist/types/library/components/_internal.d.ts +18 -0
  25. package/dist/types/library/components/a11y.d.ts +5 -0
  26. package/dist/types/library/components/canvas.d.ts +3 -0
  27. package/dist/types/library/components/extras.d.ts +15 -0
  28. package/dist/types/library/components/feedback.d.ts +1 -0
  29. package/dist/types/library/components/forms-shared.d.ts +55 -0
  30. package/dist/types/library/components/layout-motion.d.ts +14 -0
  31. package/dist/types/library/components/layout.d.ts +1 -0
  32. package/dist/types/library/components/marketing.d.ts +35 -0
  33. package/dist/types/library/components/new-components.d.ts +1 -0
  34. package/dist/types/library/components/scheduling.d.ts +2 -0
  35. package/dist/types/library/components/wave3.d.ts +6 -0
  36. package/dist/types/library/highlight.d.ts +21 -0
  37. package/dist/types/library/qr.d.ts +12 -0
  38. package/dist/types/library/responsive-style.d.ts +51 -0
  39. package/dist/types/library/sx.d.ts +51 -0
  40. package/dist/types/library/types.d.ts +50 -0
  41. package/dist/types/library/utils.d.ts +28 -0
  42. package/dist/types/library/validate.d.ts +2 -2
  43. package/dist/types/runtime/env.d.ts +33 -0
  44. package/dist/types/runtime/evaluator.d.ts +38 -0
  45. package/dist/types/runtime/http.d.ts +37 -1
  46. package/dist/types/runtime/index.d.ts +2 -0
  47. package/dist/types/runtime/namespaces-extra.d.ts +73 -0
  48. package/dist/types/runtime/realtime.d.ts +46 -0
  49. package/dist/types/runtime/router.d.ts +42 -4
  50. package/dist/types/runtime/ssr.d.ts +29 -0
  51. package/dist/types/runtime/util.d.ts +65 -0
  52. package/dist/types/testing/index.d.ts +35 -0
  53. package/dist/types/theme/fonts.d.ts +30 -0
  54. package/dist/types/theme/index.d.ts +31 -0
  55. package/dist/types/theme/styles.d.ts +1 -1
  56. package/dist/types/tooling/html-import.d.ts +19 -0
  57. package/dist/types/tooling/index.d.ts +3 -0
  58. package/dist/types/tooling/schema.d.ts +58 -0
  59. package/dist/types/tooling/signature-help.d.ts +35 -0
  60. package/package.json +1 -1
@@ -0,0 +1,33 @@
1
+ import { EvaluationContext } from './evaluator.js';
2
+ export interface EnvManager {
3
+ readonly viewport: {
4
+ width: number;
5
+ height: number;
6
+ };
7
+ readonly breakpoint: {
8
+ width: number;
9
+ active: string;
10
+ sm: boolean;
11
+ md: boolean;
12
+ lg: boolean;
13
+ xl: boolean;
14
+ };
15
+ readonly scroll: {
16
+ x: number;
17
+ y: number;
18
+ progress: number;
19
+ direction: string;
20
+ };
21
+ readonly media: {
22
+ prefersDark: boolean;
23
+ prefersReducedMotion: boolean;
24
+ online: boolean;
25
+ pointer: string;
26
+ portrait: boolean;
27
+ };
28
+ readonly mouse: {
29
+ x: number;
30
+ y: number;
31
+ };
32
+ }
33
+ export declare function createEnvManager(ctx: EvaluationContext): EnvManager;
@@ -4,6 +4,7 @@ import { HttpRuntime, EndpointResource } from './http.js';
4
4
  import { Router } from './router.js';
5
5
  import { ComponentLibrary } from '../library/types.js';
6
6
  import { ToastManager } from './toast.js';
7
+ import { EnvManager } from './env.js';
7
8
  /**
8
9
  * Runtime safety budget — bounds the work a single render can perform
9
10
  * so a partial / accidentally-recursive program (e.g. while the user is
@@ -105,6 +106,14 @@ export interface ComponentNode {
105
106
  * per-instance state attached to the right node.
106
107
  */
107
108
  explicitKey?: unknown;
109
+ /**
110
+ * Universal style/behaviour channel (suggestions-global Part I). Named
111
+ * props (`sx`, `animate`, `id`, `anchor`, `className`, `style`, `aria`,
112
+ * `data`, `tooltip`, `hidden`) that every component implicitly accepts.
113
+ * They match no declared slot, so the evaluator collects them here and
114
+ * the renderer applies them to the rendered element after `render(...)`.
115
+ */
116
+ universal?: Record<string, unknown>;
108
117
  /** Original AST for debugging/introspection. */
109
118
  source?: {
110
119
  line: number;
@@ -273,6 +282,14 @@ export interface EvaluationContext {
273
282
  library?: ComponentLibrary;
274
283
  /** Component declarations (`function Foo() { return ... }` — PascalCase). */
275
284
  componentDecls: Map<string, ComponentDeclaration>;
285
+ /**
286
+ * Names of user component declarations whose bodies are currently being
287
+ * evaluated (innermost last). Inside its own body, a declaration that
288
+ * shadows a library component resolves back to the BUILT-IN, so the
289
+ * wrapper pattern (`function Button(...) { return Button(...) }`) renders
290
+ * the library Button instead of recursing to the depth limit.
291
+ */
292
+ activeComponentDecls: string[];
276
293
  /** Effect declarations (`effect(() => { ... }, [deps])`), keyed by auto-generated name. */
277
294
  effectDecls: Map<string, EffectDeclaration>;
278
295
  /**
@@ -337,8 +354,29 @@ export interface EvaluationContext {
337
354
  * `getToastManager`; its auto-dismiss timers are cleared on dispose.
338
355
  */
339
356
  toastManager?: ToastManager;
357
+ /**
358
+ * Lazily-created singleton backing the reactive environment namespaces
359
+ * (`$viewport`, `$breakpoint`, `$scroll`, `$media`, `$mouse`). Listeners
360
+ * attach on first access and are torn down via `disposers` on replan.
361
+ */
362
+ envManager?: EnvManager;
363
+ /**
364
+ * Per-context `$util` facade (static helpers + reactive env-global getters),
365
+ * built lazily on first `$util` reference and reused across the render.
366
+ */
367
+ utilFacade?: Record<string, unknown>;
340
368
  /** Notify the host that something changed and a re-render is needed. */
341
369
  notify?: () => void;
370
+ /**
371
+ * Program-level error sink registered via `$onError(fn)` (suggestions-global
372
+ * XIII.7). Invoked with `{ error, source }` when a user action body throws,
373
+ * before the default console logging. Lets a program report to a Sentry-style
374
+ * sink or surface a toast without a bad row blanking the page.
375
+ */
376
+ errorHook?: (info: {
377
+ error: unknown;
378
+ source: string;
379
+ }) => void;
342
380
  /** Dispatch a custom event from an `emit("name", detail)` call. */
343
381
  onEmit?: (eventName: string, detail: unknown) => void;
344
382
  /**
@@ -36,6 +36,16 @@ export interface EndpointResource {
36
36
  lastUpdated?: number;
37
37
  refetch: () => Promise<void>;
38
38
  cancel: () => void;
39
+ /**
40
+ * Infinite/paginated query extras (VI.1), present only when the resource was
41
+ * created with `$query({ infinite: {...} })`. `data` holds the flattened
42
+ * items across every loaded page.
43
+ */
44
+ loadMore?: () => Promise<void>;
45
+ hasMore?: boolean;
46
+ loadingMore?: boolean;
47
+ page?: number;
48
+ pages?: unknown[];
39
49
  /**
40
50
  * Optional completion callback. Fires once each time a request settles
41
51
  * (success *or* error) — the initial load and every `refetch()`. It does
@@ -58,8 +68,22 @@ export interface EndpointResource {
58
68
  export declare function isEndpointResource(value: unknown): value is EndpointResource;
59
69
  export declare class HttpRuntime {
60
70
  private interceptors;
71
+ /**
72
+ * Program-level interceptors registered in-program via
73
+ * `$util.onRequest` / `$util.onResponse` (suggestions-global VI.5). Kept in
74
+ * a separate layer from host interceptors so a replan can wipe them without
75
+ * disturbing host glue. Request interceptors run host→program; response
76
+ * interceptors run program→host (inner-to-outer, the usual convention).
77
+ */
78
+ private programInterceptors;
61
79
  /** Merge new interceptors on top of any previously-registered ones. */
62
80
  registerInterceptors(interceptors: HttpInterceptors): void;
81
+ /** Merge in-program interceptors on top of any already registered. */
82
+ registerProgramInterceptors(interceptors: HttpInterceptors): void;
83
+ /** Drop every in-program interceptor (called on replan so they don't leak). */
84
+ clearProgramInterceptors(): void;
85
+ /** Notify both interceptor layers of a request error. */
86
+ private fireError;
63
87
  /**
64
88
  * Resolve a URL. Currently a pass-through — every `Http({ url })` call
65
89
  * is expected to supply an absolute URL. Kept as a hook so request
@@ -69,10 +93,22 @@ export declare class HttpRuntime {
69
93
  resolveUrl(url: string): string;
70
94
  /**
71
95
  * Issue a single HTTP request. Runs through `onRequest`/`onResponse`
72
- * interceptors and surfaces a `retry()` one-shot inside `onResponse`.
96
+ * interceptors (host + program layers) and surfaces a `retry()` one-shot
97
+ * inside each `onResponse`.
73
98
  */
74
99
  request(input: HttpRequest): Promise<HttpResponse>;
75
100
  }
101
+ /**
102
+ * Refetch every cached query whose key contains any of the given substrings
103
+ * (VI.2). Used by `$mutation({ invalidates: [...] })` and `$util.invalidate`.
104
+ *
105
+ * Matching is deliberately SUBSTRING-based: cache keys are derived from the
106
+ * request (url + params), so `invalidates: ["/api/posts"]` refreshes the
107
+ * list, every page of it, and any filtered variant in one go. The trade-off
108
+ * is that a short needle ("post") can over-invalidate ("composting") — use
109
+ * a path-ish needle ("/posts") when precision matters.
110
+ */
111
+ export declare function invalidateQueries(ctx: EvaluationContext, keys: unknown): void;
76
112
  /**
77
113
  * Run a single `Http({...})` call and return the reactive resource bag.
78
114
  *
@@ -4,6 +4,8 @@ export * from './evaluator.js';
4
4
  export * from './router.js';
5
5
  export * from './http.js';
6
6
  export * from './i18n.js';
7
+ export { renderToString, renderToStaticMarkup } from './ssr.js';
8
+ export type { RenderToStringOptions, RenderToStringResult } from './ssr.js';
7
9
  export { storage, type CookieOptions, type StorageNamespace, type StorageRoot } from './storage.js';
8
10
  export { consoleNs, type ConsoleNamespace } from './console.js';
9
11
  export { createToastManager, type ToastManager, type ToastItem, type ToastOptions, } from './toast.js';
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Extra runtime namespaces exposed to Aktion programs (suggestions-global
3
+ * Parts V.2, XIII.2): `$style` (bounded styling helpers) and `$rules`
4
+ * (composable validators). Both are pure — no side effects — and safe to
5
+ * call from any expression / action / effect / lambda.
6
+ */
7
+ export declare const Style: {
8
+ /**
9
+ * Classname helper (clsx-style). Accepts strings, arrays, and objects
10
+ * `{ "is-active": cond }`; returns a space-joined, de-duped class string.
11
+ * Tokens that aren't valid CSS identifiers are dropped.
12
+ */
13
+ readonly cx: (...args: unknown[]) => string;
14
+ /**
15
+ * Build a safe `linear-gradient(...)` from an array of color stops (and an
16
+ * optional angle in degrees). Returns "" if fewer than two valid stops.
17
+ */
18
+ readonly gradient: (stops: unknown, angle?: unknown) => string;
19
+ /** color-mix wrapper: blend a color with transparent at `amount` (0–1). */
20
+ readonly alpha: (color: unknown, amount: unknown) => string;
21
+ /** Build a responsive `clamp(min, preferred, max)` size. */
22
+ readonly clamp: (min: unknown, preferred: unknown, max: unknown) => string;
23
+ /**
24
+ * Resolve a dotted token path to its CSS variable: `style.token("spacing.l")`
25
+ * → `var(--rui-spacing-l)`, `style.token("colors.primary")` →
26
+ * `var(--rui-color-primary)`. Falls back to "" for unknown shapes.
27
+ */
28
+ readonly token: (path: unknown) => string;
29
+ /** Serialize a plain object of CSS declarations to a sanitised style string. */
30
+ readonly toStyle: (obj: unknown) => string;
31
+ };
32
+ export type StyleNamespace = typeof Style;
33
+ /**
34
+ * A validator returns an error message (invalid), null (valid), or a Promise
35
+ * of either — async validators (V.2 `asyncCustom`) resolve server-side checks
36
+ * like username uniqueness.
37
+ */
38
+ type Validator = (value: unknown) => string | null | Promise<string | null>;
39
+ export declare const Rules: {
40
+ readonly required: (message?: string) => Validator;
41
+ readonly email: (message?: string) => Validator;
42
+ readonly url: (message?: string) => Validator;
43
+ readonly min: (n: number, message?: string) => Validator;
44
+ readonly max: (n: number, message?: string) => Validator;
45
+ readonly minLength: (n: number, message?: string) => Validator;
46
+ readonly maxLength: (n: number, message?: string) => Validator;
47
+ readonly pattern: (re: unknown, message?: string) => Validator;
48
+ readonly oneOf: (options: unknown[], message?: string) => Validator;
49
+ readonly matches: (other: unknown, message?: string) => Validator;
50
+ readonly custom: (fn: unknown, message?: string) => Validator;
51
+ /**
52
+ * Async validator (V.2) — `fn(value)` may return a Promise resolving to
53
+ * true/null (valid), false (invalid → `message`), or an error string. Use
54
+ * for server-side checks (e.g. username uniqueness). `$form` awaits these
55
+ * before submitting; a rejected promise counts as invalid.
56
+ */
57
+ readonly asyncCustom: (fn: unknown, message?: string) => Validator;
58
+ /**
59
+ * Run a list of validators against a value; returns the first error
60
+ * message, or null when all pass. Stays fully synchronous for sync
61
+ * validators; returns a Promise only when an async validator is hit.
62
+ */
63
+ readonly validate: (value: unknown, validators: unknown) => string | null | Promise<string | null>;
64
+ /**
65
+ * Validate an object of `{ field: value }` against a schema of
66
+ * `{ field: [validators] }`. Returns `{ field: message }` for failures
67
+ * (empty object when valid) — or a Promise of it when any validator in the
68
+ * schema is async.
69
+ */
70
+ readonly validateAll: (values: unknown, schema: unknown) => Record<string, string> | Promise<Record<string, string>>;
71
+ };
72
+ export type RulesNamespace = typeof Rules;
73
+ export {};
@@ -0,0 +1,46 @@
1
+ import { EvaluationContext } from './evaluator.js';
2
+ export type SocketStatus = "connecting" | "open" | "closed";
3
+ export interface SocketResource {
4
+ /** Convenience boolean — true while `status === "open"`. */
5
+ connected: boolean;
6
+ /** Connection lifecycle: "connecting" | "open" | "closed" (spec VI.3). */
7
+ status: SocketStatus;
8
+ /** Most recent messages (capped to `bufferSize`, newest last). */
9
+ messages: unknown[];
10
+ /** The latest message (or null before the first arrives). */
11
+ last: unknown;
12
+ error: unknown;
13
+ /** Reconnect attempts made so far (resets on a successful open). */
14
+ attempts: number;
15
+ /**
16
+ * Send a message; objects are JSON-stringified. While the socket is still
17
+ * connecting (or briefly reconnecting), messages queue (bounded) and flush
18
+ * on open; once closed for good they are dropped.
19
+ */
20
+ send: (data: unknown) => void;
21
+ /** Close the connection (disables auto-reconnect). */
22
+ close: () => void;
23
+ }
24
+ /**
25
+ * `$socket({ url, protocols?, bufferSize?, onMessage?, reconnect? })` — a
26
+ * reactive WebSocket. Reads of `.status` / `.last` / `.messages` re-render on
27
+ * change. `reconnect: true` retries dropped connections with exponential
28
+ * backoff (a number caps the attempts); `close()` always stops for good.
29
+ */
30
+ export declare function createSocketResource(config: unknown, ctx: EvaluationContext): SocketResource;
31
+ export interface SseResource {
32
+ connected: boolean;
33
+ /** Connection lifecycle: "connecting" | "open" | "closed". */
34
+ status: SocketStatus;
35
+ messages: unknown[];
36
+ last: unknown;
37
+ error: unknown;
38
+ close: () => void;
39
+ }
40
+ /**
41
+ * `$sse({ url, withCredentials?, bufferSize?, event?, onMessage? })` — a
42
+ * reactive Server-Sent Events stream. `event` names a custom event type to
43
+ * listen for (defaults to the unnamed `message` stream). EventSource
44
+ * reconnects natively; `status` reads "connecting" while it does.
45
+ */
46
+ export declare function createSseResource(config: unknown, ctx: EvaluationContext): SseResource;
@@ -31,6 +31,19 @@ export interface RouteChangeDetail {
31
31
  source: "init" | "hashchange" | "navigate" | "external";
32
32
  }
33
33
  export type RouteListener = (detail: RouteChangeDetail) => void;
34
+ /** Payload handed to a navigation guard before a path change commits. */
35
+ export interface NavigationInfo {
36
+ /** The path the user is trying to reach (normalised). */
37
+ to: string;
38
+ /** The path being left (null on the very first navigation). */
39
+ from: string | null;
40
+ }
41
+ /**
42
+ * A navigation guard decides whether a pending navigation may proceed.
43
+ * Return `false` to block it, a path string to redirect, or `true` /
44
+ * `undefined` to allow it.
45
+ */
46
+ export type NavigationGuard = (info: NavigationInfo) => boolean | string | void;
34
47
  export interface RouterOptions {
35
48
  /** Initial path when no hash is set. Defaults to `/`. */
36
49
  defaultPath?: string;
@@ -67,11 +80,21 @@ export declare function normalisePath(raw: string | null | undefined): string;
67
80
  * - mixed wildcard: `/docs/*` (matches everything under `/docs/`)
68
81
  */
69
82
  export declare function matchRoute(pattern: string, path: string): RouteMatch;
83
+ /** Result of a prefix match — the captured params plus the unmatched tail. */
84
+ export interface PrefixMatch {
85
+ matched: boolean;
86
+ params: RouteParams;
87
+ /** The remaining path after the matched prefix, normalised (e.g. `/settings`). */
88
+ rest: string;
89
+ }
70
90
  /**
71
- * Singleton-per-element router. Owns the current path, listens for
72
- * `hashchange` events when enabled, and notifies subscribers when the path
73
- * changes for any reason.
91
+ * Match a route pattern as a PREFIX of `path` (suggestions-global IV.1 — nested
92
+ * routes / layout routes). `/app` prefix-matches `/app`, `/app/x`, `/app/x/y`.
93
+ * Returns the captured `:params` plus the unmatched tail (`rest`) so a nested
94
+ * router can resolve the child route. A pure-segment pattern only matches on
95
+ * segment boundaries (so `/app` does not match `/application`).
74
96
  */
97
+ export declare function matchRoutePrefix(pattern: string, path: string): PrefixMatch;
75
98
  export declare class Router {
76
99
  private currentPath;
77
100
  private currentParams;
@@ -85,6 +108,8 @@ export declare class Router {
85
108
  /** True while we're updating `window.location` ourselves — used to
86
109
  * filter out the resulting `hashchange` / `popstate` echo. */
87
110
  private settingHash;
111
+ /** Optional navigation guard registered via `$util.onNavigate(fn)`. */
112
+ private guard;
88
113
  constructor(options?: RouterOptions);
89
114
  /**
90
115
  * Re-configure the URL strategy before `start()` is called. The host
@@ -121,9 +146,22 @@ export declare class Router {
121
146
  /**
122
147
  * Navigate to the given path. When enabled, this updates the URL hash and
123
148
  * relies on `hashchange` to notify listeners (so browser history works).
124
- * When disabled, the navigation stays in-memory.
149
+ * When disabled, the navigation stays in-memory. A registered navigation
150
+ * guard may block (`false`) or redirect (path string) the change.
125
151
  */
126
152
  navigate(path: string): void;
153
+ /**
154
+ * Register (or clear, with `null`) the navigation guard. The guard runs
155
+ * before every in-app `navigate(...)` and every URL-driven change once the
156
+ * router is started. Set via `$util.onNavigate(fn)`.
157
+ */
158
+ setGuard(guard: NavigationGuard | null): void;
159
+ /** Run the guard for a pending navigation, failing open on error. */
160
+ private runGuard;
161
+ /** Rewind `window.location` to the current path (used when a guard blocks). */
162
+ private restoreUrl;
163
+ /** Commit a navigation after the guard has approved it (with redirect cap). */
164
+ private navigateInternal;
127
165
  subscribe(listener: RouteListener): () => void;
128
166
  /** Replace the current path without going through `window.location`. */
129
167
  private setPath;
@@ -0,0 +1,29 @@
1
+ import { ComponentLibrary } from '../library/types.js';
2
+ export interface RenderToStringOptions {
3
+ /** Component library to render against (defaults to the built-in one). */
4
+ library?: ComponentLibrary;
5
+ /** Initial path for the in-memory router (default "/"). */
6
+ path?: string;
7
+ /** Seed state for SSR — values hydrate over the program's declarations. */
8
+ initialState?: Record<string, unknown>;
9
+ /** Wrap the output in a single container element (default true). */
10
+ container?: boolean;
11
+ }
12
+ export interface RenderToStringResult {
13
+ /** Serialised HTML for the rendered program. */
14
+ html: string;
15
+ /** State snapshot to ship to the client for hydration. */
16
+ state: Record<string, unknown>;
17
+ }
18
+ /**
19
+ * Render an Aktion program to an HTML string + hydration state.
20
+ *
21
+ * Throws when no DOM is available (install `happy-dom`/`jsdom` and register it
22
+ * on `globalThis` in a Node SSR entry).
23
+ */
24
+ export declare function renderToString(program: string, options?: RenderToStringOptions): RenderToStringResult;
25
+ /**
26
+ * Like `renderToString` but returns only the markup (no hydration state) —
27
+ * for fully static pages / SSG (suggestions-global XI.1).
28
+ */
29
+ export declare function renderToStaticMarkup(program: string, options?: RenderToStringOptions): string;
@@ -94,5 +94,70 @@ export declare const Util: {
94
94
  readonly sqrt: (value: unknown) => number;
95
95
  readonly random: () => number;
96
96
  readonly log: (value: unknown) => number;
97
+ readonly slugify: (text: unknown) => string;
98
+ readonly truncate: (text: unknown, length?: unknown, ellipsis?: string) => string;
99
+ readonly initials: (name: unknown, max?: unknown) => string;
100
+ readonly currency: (value: unknown, code?: string, locale?: string) => string;
101
+ readonly percent: (value: unknown, decimals?: unknown) => string;
102
+ readonly bytes: (value: unknown) => string;
103
+ readonly relativeTime: (value: unknown) => string;
104
+ /**
105
+ * Copy text to the clipboard. Resolves `true` only once the async Clipboard
106
+ * API write actually succeeds (permission can deny it), `false` otherwise.
107
+ * `await $util.copy(x)` in an action; plain truthy checks keep working.
108
+ */
109
+ readonly copy: (text: unknown) => Promise<boolean>;
110
+ /** Await a pause: `await $util.sleep(300)`. Capped at 60s. */
111
+ readonly sleep: (ms?: unknown) => Promise<void>;
112
+ readonly uuid: () => string;
113
+ /** Wrap a function so it only fires `wait` ms after the last call. */
114
+ readonly debounceFn: (fn: unknown, wait?: unknown) => ((...args: unknown[]) => void);
115
+ /**
116
+ * Wrap a function so it fires at most once per `wait` ms. Leading edge
117
+ * fires immediately; calls landing inside the window schedule one trailing
118
+ * fire with the latest arguments, so the final value is never dropped.
119
+ */
120
+ readonly throttleFn: (fn: unknown, wait?: unknown) => ((...args: unknown[]) => void);
121
+ /** Trigger device haptics. `pattern` is ms or an array of on/off ms. */
122
+ readonly vibrate: (pattern?: unknown) => boolean;
123
+ /** Native share sheet. `data` = { title?, text?, url? }. Returns a promise. */
124
+ readonly share: (data: unknown) => Promise<boolean>;
125
+ /** Read text from the clipboard (async). Returns "" when unavailable/denied. */
126
+ readonly readClipboard: () => Promise<string>;
127
+ /** Current geolocation as a promise of { lat, lng, accuracy } (or null). */
128
+ readonly geolocate: (options?: unknown) => Promise<{
129
+ lat: number;
130
+ lng: number;
131
+ accuracy: number;
132
+ } | null>;
133
+ /** `true` when the device is currently online. */
134
+ readonly isOnline: () => boolean;
135
+ /** Best-effort device class from the user agent: "mobile" | "tablet" | "desktop". */
136
+ readonly deviceType: () => string;
137
+ /**
138
+ * Run a PURE function off the main thread in a Web Worker, resolving with its
139
+ * result. `fn` is serialised via `toString()`, so it must not close over
140
+ * outer variables (pass everything it needs as arguments). Falls back to
141
+ * running inline (still async) when Workers aren't available.
142
+ * $util.worker((n) => heavyCompute(n), 1000).then(r => $result = r)
143
+ */
144
+ readonly worker: (fn: unknown, ...args: unknown[]) => Promise<unknown>;
145
+ /** Register a service worker. Resolves true on success, false otherwise. */
146
+ readonly registerServiceWorker: (url: unknown, scope?: unknown) => Promise<boolean>;
147
+ /**
148
+ * Build a sanitised Web App Manifest object from a config (XII.2). Use it to
149
+ * inline a manifest (`<link rel="manifest" href="data:...">`) or write one at
150
+ * build time. Unknown/unsafe keys are dropped.
151
+ */
152
+ readonly webManifest: (config: unknown) => Record<string, unknown>;
153
+ /**
154
+ * Detect the native shell the app is running inside (Capacitor / Cordova /
155
+ * Tauri / Electron / React Native WebView), or "web" when it's a plain
156
+ * browser. Lets a program branch on the host (e.g. hide a download button in
157
+ * a native shell, or call a bridge when present).
158
+ */
159
+ readonly nativeShell: () => string;
160
+ /** True when running inside any native shell (not a plain browser). */
161
+ readonly isNativeApp: () => boolean;
97
162
  };
98
163
  export type UtilNamespace = typeof Util;
@@ -199,3 +199,38 @@ export declare function renderComponent(expression: string, options?: ComponentR
199
199
  export declare function cleanup(): void;
200
200
  /** Convenience for building a JSON `MockResult` in a `fetch` handler. */
201
201
  export declare function json(data: unknown, status?: number): MockResult;
202
+ export interface WithinQueries {
203
+ getByText(matcher: Matcher): HTMLElement;
204
+ queryByText(matcher: Matcher): HTMLElement | null;
205
+ getAllByText(matcher: Matcher): HTMLElement[];
206
+ getByRole(role: string, options?: {
207
+ name?: Matcher;
208
+ }): HTMLElement;
209
+ queryByRole(role: string, options?: {
210
+ name?: Matcher;
211
+ }): HTMLElement | null;
212
+ getAllByRole(role: string, options?: {
213
+ name?: Matcher;
214
+ }): HTMLElement[];
215
+ getByTestId(id: string): HTMLElement;
216
+ queryByTestId(id: string): HTMLElement | null;
217
+ }
218
+ /**
219
+ * Scope Testing-Library-style queries to a subtree (XIV.6). Mirror of RTL's
220
+ * `within(node)` — useful for asserting inside one card/row of a list without
221
+ * matching siblings.
222
+ */
223
+ export declare function within(root: Element): WithinQueries;
224
+ export interface A11yViolation {
225
+ rule: string;
226
+ message: string;
227
+ element: string;
228
+ }
229
+ /**
230
+ * Lightweight accessibility audit (XIV.6) — a pragmatic subset of axe-style
231
+ * checks that need no dependency: images without alt, non-decorative SVGs
232
+ * without a label, buttons/links without an accessible name (resolving
233
+ * `aria-labelledby`), inputs without a label, duplicate ids, and positive
234
+ * tabindex. Returns the list of violations (empty = clean).
235
+ */
236
+ export declare function axe(root: Element): A11yViolation[];
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Web-font loading for `$theme({ fonts: { import: [...] } })`
3
+ * (suggestions-global I.7).
4
+ *
5
+ * Accepts a short Google-Fonts shorthand list and injects a single
6
+ * `<link rel="stylesheet">` into `document.head` (once per unique URL).
7
+ * Font faces loaded into the document are visible to shadow roots, so the
8
+ * renderer can reference them via the `font` theme tokens.
9
+ *
10
+ * Shorthand:
11
+ * "Inter:400,700" → family Inter, weights 400 & 700
12
+ * "JetBrains Mono" → family JetBrains Mono, default weight
13
+ * "Inter:400,500i,700" → `i` suffix marks an italic weight
14
+ *
15
+ * Only well-formed family names (letters, digits, spaces) and numeric
16
+ * weights are accepted; anything else is dropped so a hostile value can't
17
+ * smuggle a different origin or CSS payload into the page.
18
+ */
19
+ /**
20
+ * Build a sanitised Google Fonts CSS2 URL from a shorthand list, or "" when
21
+ * no valid family is present.
22
+ */
23
+ export declare function buildFontUrl(list: unknown): string;
24
+ /**
25
+ * Inject the web fonts named in `import` into `document.head` (idempotent).
26
+ * `record` is the `fonts` group from a `$theme({ fonts: {...} })` call; only
27
+ * its `import` array is used here (the `family`/`familyHeading` tokens are
28
+ * applied separately by the normal token flow). Returns the injected URL or "".
29
+ */
30
+ export declare function loadFonts(record: unknown): string;
@@ -84,17 +84,48 @@ export interface ThemeTokens {
84
84
  shadowSm: string;
85
85
  shadowMd: string;
86
86
  shadowLg: string;
87
+ /** Hairline spacing steps below `xs` (optional; default 1px / 2px). */
88
+ spacing3xs?: string;
89
+ spacing2xs?: string;
87
90
  spacingXs: string;
88
91
  spacingS: string;
89
92
  spacingM: string;
90
93
  spacingL: string;
91
94
  spacingXl: string;
95
+ /** Extra-large spacing steps for marketing/section rhythm. */
96
+ spacing2xl: string;
97
+ spacing3xl: string;
98
+ /** Primary brand gradient — used by `fill: "gradient.brand"`, GradientText, etc. */
99
+ gradientBrand: string;
100
+ gradientAccent: string;
101
+ gradientWarm: string;
102
+ gradientCool: string;
103
+ gradientSuccess: string;
104
+ gradientDanger: string;
92
105
  buttonFontWeight: string;
93
106
  buttonTextTransform: string;
94
107
  buttonLetterSpacing: string;
95
108
  buttonPaddingY: string;
96
109
  buttonPaddingX: string;
97
110
  transitionDuration: string;
111
+ /** Motion tokens (I.2) — `$theme({ motion: { fast, base, slow, ease } })`.
112
+ * Optional: components fall back to their built-in timings. */
113
+ motionFast?: string;
114
+ motionBase?: string;
115
+ motionSlow?: string;
116
+ motionEase?: string;
117
+ /** z-index tokens — `$theme({ zIndex: { modal: 2000, ... } })`. Optional:
118
+ * `sx.zIndex` tokens fall back to the documented defaults. */
119
+ zBase?: string;
120
+ zRaised?: string;
121
+ zDropdown?: string;
122
+ zSticky?: string;
123
+ zBanner?: string;
124
+ zOverlay?: string;
125
+ zModal?: string;
126
+ zPopover?: string;
127
+ zToast?: string;
128
+ zTooltip?: string;
98
129
  chart1: string;
99
130
  chart2: string;
100
131
  chart3: string;