@flareapp/svelte 2.0.0-alpha.0

package/README.md

@@ -0,0 +1,365 @@
+# @flareapp/svelte
+
+Svelte 5 integration for [Flare](https://flareapp.io) error tracking. It provides a native Svelte error boundary and a
+handler factory for custom `<svelte:boundary>` usage. It builds on top of `@flareapp/js`, which still handles the core
+Flare client configuration, global browser errors, manual reports, custom context, and glows.
+
+## Installation
+
+Install both the core Flare client and the Svelte integration:
+
+```bash
+npm install @flareapp/js @flareapp/svelte
+# or
+yarn add @flareapp/js @flareapp/svelte
+# or
+pnpm add @flareapp/js @flareapp/svelte
+```
+
+`@flareapp/svelte` supports Svelte 5.3 and higher.
+
+If your app is bundled for production, also configure sourcemap uploads with `@flareapp/vite` so Flare can show readable
+stack traces and code snippets.
+
+## Setting up the Flare client
+
+Initialize the Flare client as early as possible in your application, typically in `main.ts`:
+
+```ts
+import { flare } from '@flareapp/js';
+import { mount } from 'svelte';
+
+import App from './App.svelte';
+
+if (import.meta.env.PROD) {
+    flare.light('YOUR PROJECT PUBLIC KEY');
+}
+
+mount(App, {
+    target: document.getElementById('app')!,
+});
+```
+
+Use your project's public key from the JavaScript installation section in your Flare project settings.
+
+If you use the sourcemap plugin, you do not need to pass a public key to `flare.light()`. The plugin injects the project
+key during your build.
+
+## Error boundary
+
+`FlareErrorBoundary` wraps Svelte's native `<svelte:boundary>`. It catches errors from the component tree below it,
+reports them to Flare, and can render your fallback snippet.
+
+```svelte
+<script lang="ts">
+    import { FlareErrorBoundary } from '@flareapp/svelte';
+
+    import Root from './Root.svelte';
+</script>
+
+<FlareErrorBoundary>
+    <Root />
+
+    {#snippet failed(error, reset)}
+        <section>
+            <h2>Something went wrong</h2>
+            <p>{error.message}</p>
+            <button onclick={reset}>Try again</button>
+        </section>
+    {/snippet}
+</FlareErrorBoundary>
+```
+
+Without a `failed` snippet, the boundary still catches and reports the error, but it renders nothing for the failed
+subtree.
+
+### Resetting the boundary
+
+Call the `reset` function passed to the `failed` snippet to clear the boundary state and retry rendering the children:
+
+```svelte
+<FlareErrorBoundary>
+    <CheckoutForm />
+
+    {#snippet failed(error, reset)}
+        <p>{error.message}</p>
+        <button onclick={reset}>Retry checkout</button>
+    {/snippet}
+</FlareErrorBoundary>
+```
+
+You can also reset automatically when values in `resetKeys` change. Values are compared by index with `Object.is`, and a
+length change also triggers a reset.
+
+```svelte
+<FlareErrorBoundary
+    resetKeys={[currentRoute, selectedAccountId]}
+    onReset={(error) => {
+        console.log('Recovered from:', error?.message);
+    }}
+>
+    <AccountPage />
+
+    {#snippet failed(error, reset)}
+        <p>{error.message}</p>
+        <button onclick={reset}>Try again</button>
+    {/snippet}
+</FlareErrorBoundary>
+```
+
+`onReset` runs when the user calls `reset` from the fallback snippet or when `resetKeys` changes while the boundary is in
+an error state. It receives the previous error, or `null` if no error was stored.
+
+## Lifecycle callbacks
+
+The boundary exposes three callbacks around the Svelte-specific reporting flow.
+
+```svelte
+<script lang="ts">
+    import { flare } from '@flareapp/js';
+    import { FlareErrorBoundary, type FlareSvelteContext } from '@flareapp/svelte';
+</script>
+
+<FlareErrorBoundary
+    beforeEvaluate={({ error }) => {
+        flare.addContext('feature', 'checkout');
+        flare.addContext('errorMessage', error.message);
+    }}
+    beforeSubmit={({ context }: { context: FlareSvelteContext }) => {
+        return {
+            ...context,
+            svelte: {
+                ...context.svelte,
+                componentHierarchy: context.svelte.componentHierarchy.filter(
+                    (component) => component !== 'ThirdPartyWrapper',
+                ),
+            },
+        };
+    }}
+    afterSubmit={({ error, context }) => {
+        console.error('Reported Svelte error:', error);
+        console.debug('Svelte context:', context);
+    }}
+>
+    <Root />
+</FlareErrorBoundary>
+```
+
+Callback order:
+
+1. `beforeEvaluate` runs after the thrown value is converted to an `Error`, before Svelte context is built.
+2. `beforeSubmit` runs after Svelte context is built. Return the context object that should be attached to the report.
+3. `afterSubmit` runs after Flare reporting is started. The network request is asynchronous.
+
+These callbacks are not wrapped in `try`/`catch`. If one throws, the error can bubble out of the boundary handler.
+
+### Filtering errors
+
+The boundary callbacks are for adding context and running side effects. They do not suppress reports.
+
+To filter, suppress, or modify the final Flare report, use the core JavaScript client hooks:
+
+```ts
+import { flare } from '@flareapp/js';
+
+flare.configure({
+    beforeEvaluate: (error) => {
+        if (error.message.includes('Ignored validation error')) {
+            return false;
+        }
+
+        return error;
+    },
+});
+```
+
+The execution order when both boundary callbacks and core client hooks are configured is:
+
+1. Boundary `beforeEvaluate`
+2. Boundary `beforeSubmit`
+3. Internal `flare.reportSilently()` call
+4. Client `beforeEvaluate` from `flare.configure()`
+5. Client `beforeSubmit` from `flare.configure()`
+6. Report is sent to Flare
+7. Boundary `afterSubmit`
+
+## Svelte context
+
+When the Svelte integration reports an error, it attaches Svelte-specific context under `context.custom.svelte`.
+
+```ts
+interface FlareSvelteContext {
+    svelte: {
+        componentName: string | null;
+        componentHierarchy: string[];
+        errorOrigin: 'render' | 'event' | 'effect' | 'unknown';
+    };
+}
+```
+
+Field details:
+
+| Field                | Description                                                      |
+| -------------------- | ---------------------------------------------------------------- |
+| `componentName`      | Best-effort name of the component closest to the thrown error.   |
+| `componentHierarchy` | Component names ordered from inner component to outer component. |
+| `errorOrigin`        | Best-effort classification of where the error came from.         |
+
+When the same component is mounted in multiple places (e.g. a `Button` inside both `Sidebar` and `Header`),
+`FlareErrorBoundary` disambiguates by matching the error to the instance whose ancestor chain includes the catching
+boundary. Without an ancestor hint (e.g. manual `lookupComponentTree` calls), the first registered instance is returned.
+
+Component context is extracted from `.svelte` stack frames. In production bundles, function names and filenames may be
+minified. Configure sourcemaps so Flare can resolve the original source code on the backend.
+
+## Event handlers and async errors
+
+Svelte boundaries do not catch every kind of browser error. Errors thrown in event handlers and unhandled promise
+rejections are handled by the global listeners installed by `@flareapp/js`, not by `FlareErrorBoundary`.
+
+```svelte
+<button
+    onclick={() => {
+        throw new Error('Clicked button failed');
+    }}
+>
+    Trigger event error
+</button>
+```
+
+The error above is still reported if the core Flare client is initialized, but it will not render the boundary fallback
+UI.
+
+## Custom boundary usage
+
+Use `createFlareErrorHandler()` when you want to wire Flare into your own `<svelte:boundary>` instead of using
+`FlareErrorBoundary`.
+
+```svelte
+<script lang="ts">
+    import { createFlareErrorHandler } from '@flareapp/svelte';
+
+    const reportToFlare = createFlareErrorHandler({
+        afterSubmit: ({ error }) => {
+            console.error('Reported through custom boundary:', error);
+        },
+    });
+</script>
+
+<svelte:boundary onerror={reportToFlare}>
+    <Root />
+
+    {#snippet failed(error, reset)}
+        <p>{error.message}</p>
+        <button onclick={reset}>Retry</button>
+    {/snippet}
+</svelte:boundary>
+```
+
+The returned function matches the Svelte boundary `onerror` signature:
+
+```ts
+(error: unknown, reset: () => void) => void | Promise<void>;
+```
+
+It converts non-`Error` values, builds Svelte context from the stack trace, reports through the core Flare client, and
+runs the lifecycle callbacks described above.
+
+## Manual reports, context, and glows
+
+The Svelte integration builds on the core JavaScript client. Use `@flareapp/js` directly for manual reporting, client
+hooks, custom context, and glows:
+
+```ts
+import { flare } from '@flareapp/js';
+
+flare.addContext('user', { id: '123' });
+flare.glow('checkout', 'Payment method selected');
+
+try {
+    await submitOrder();
+} catch (error) {
+    flare.report(error);
+}
+```
+
+Useful shared documentation:
+
+- [Reporting errors](https://flareapp.io/docs/javascript/errors/reporting-errors)
+- [Client hooks](https://flareapp.io/docs/javascript/errors/client-hooks)
+- [Adding custom context](https://flareapp.io/docs/javascript/data-collection/adding-custom-context)
+- [Adding glows](https://flareapp.io/docs/javascript/data-collection/adding-glows)
+
+## Resolving bundled code
+
+Production Svelte apps are usually minified and bundled, which makes raw stack traces hard to read. Configure sourcemap
+uploads with `@flareapp/vite` so Flare can map stack frames back to your original `.svelte` files.
+
+The Svelte integration uses the same sourcemap plugin as the JavaScript and React clients. See the
+[JavaScript resolving bundled code documentation](https://flareapp.io/docs/javascript/general/resolving-bundled-code)
+for the Vite, Webpack, Laravel Mix, and manual upload setup.
+
+## Verifying your setup
+
+The core client is available as `window.flare` in the browser. Build your app for production and run this in the browser
+console:
+
+```js
+flare.test();
+```
+
+This sends a test error to your Flare project.
+
+If nothing appears in Flare, enable debug mode:
+
+```ts
+flare.light('YOUR PROJECT PUBLIC KEY', true);
+// or
+flare.configure({ debug: true });
+```
+
+If `flare.light()` has not been called, for example because your production guard is false, reports are silently ignored.
+
+## API reference
+
+```ts
+import { FlareErrorBoundary, createFlareErrorHandler } from '@flareapp/svelte';
+
+import type { FlareErrorHandlerOptions, FlareSvelteContext, SvelteErrorOrigin } from '@flareapp/svelte';
+```
+
+Exports:
+
+| Export                    | Description                                                                                                     |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `FlareErrorBoundary`      | Svelte component that catches boundary errors, reports them to Flare, and renders an optional fallback snippet. |
+| `createFlareErrorHandler` | Factory that returns a Svelte boundary `onerror` callback for custom boundary usage.                            |
+
+Types:
+
+| Type                       | Description                                                                                |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `FlareErrorHandlerOptions` | Lifecycle callback options accepted by `createFlareErrorHandler` and `FlareErrorBoundary`. |
+| `FlareSvelteContext`       | Shape of the Svelte context passed to `beforeSubmit` and `afterSubmit`.                    |
+| `SvelteErrorOrigin`        | Union of possible origin values: `'render'`, `'event'`, `'effect'`, and `'unknown'`.       |
+
+### `FlareErrorBoundary` props
+
+| Prop             | Type                                         | Description                                                           |
+| ---------------- | -------------------------------------------- | --------------------------------------------------------------------- |
+| `children`       | `Snippet`                                    | Child snippet rendered inside the boundary.                           |
+| `failed`         | `Snippet<[error: Error, reset: () => void]>` | Optional fallback snippet rendered after an error is caught.          |
+| `resetKeys`      | `unknown[]`                                  | Values that reset the boundary when changed while an error is stored. |
+| `beforeEvaluate` | `({ error }) => void`                        | Runs before Svelte context is built.                                  |
+| `beforeSubmit`   | `({ error, context }) => FlareSvelteContext` | Runs before reporting. Return the context to attach.                  |
+| `afterSubmit`    | `({ error, context }) => void`               | Runs after reporting is started.                                      |
+| `onReset`        | `(error: Error &#124; null) => void`         | Runs when the boundary is reset.                                      |
+
+## SvelteKit
+
+For SvelteKit apps, install `@flareapp/sveltekit` as well. It adds client and server `handleError` helpers, manual
+SvelteKit capture helpers, route context, and re-exports the Svelte boundary component for convenience.
+
+## License
+
+The MIT License (MIT). Please see [License File](../../LICENSE.md) for more information.

package/dist/FlareErrorBoundary.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+    import type { Snippet } from 'svelte';
+
+    import { __flareRegisterComponent, getComponentTreeContext } from './componentTree.js';
+    import { createFlareErrorHandler, type FlareErrorHandlerOptions } from './createFlareErrorHandler.js';
+
+    interface Props {
+        children: Snippet;
+        failed?: Snippet<[error: Error, reset: () => void]>;
+        resetKeys?: unknown[];
+        beforeEvaluate?: FlareErrorHandlerOptions['beforeEvaluate'];
+        beforeSubmit?: FlareErrorHandlerOptions['beforeSubmit'];
+        afterSubmit?: FlareErrorHandlerOptions['afterSubmit'];
+        onReset?: (error: Error | null) => void;
+    }
+
+    let {
+        children,
+        failed: fallbackSnippet,
+        resetKeys,
+        beforeEvaluate,
+        beforeSubmit,
+        afterSubmit,
+        onReset,
+    }: Props = $props();
+
+    let currentError: Error | null = $state(null);
+    let resetBoundary: (() => void) | null = $state(null);
+
+    let previousKeys: unknown[] | undefined;
+    $effect(() => {
+        if (!currentError || !resetKeys) {
+            previousKeys = resetKeys ? [...resetKeys] : undefined;
+            return;
+        }
+
+        const lengthChanged = previousKeys?.length !== resetKeys.length;
+        const valuesChanged = resetKeys.some((key, i) => !Object.is(key, previousKeys?.[i]));
+
+        if (lengthChanged || valuesChanged) {
+            handleReset();
+        }
+
+        previousKeys = [...resetKeys];
+    });
+
+    function handleReset() {
+        const error = currentError;
+        currentError = null;
+        onReset?.(error);
+        resetBoundary?.();
+        resetBoundary = null;
+    }
+
+    const ancestor = __flareRegisterComponent('FlareErrorBoundary', '@flareapp/svelte/FlareErrorBoundary.svelte');
+
+    const handler = $derived(
+        createFlareErrorHandler({ ancestor, beforeEvaluate, beforeSubmit, afterSubmit }),
+    );
+
+    function onerror(rawError: unknown, reset: () => void) {
+        resetBoundary = reset;
+        const error = rawError instanceof Error ? rawError : new Error(String(rawError));
+        currentError = error;
+
+        handler(rawError, reset);
+    }
+</script>
+
+<svelte:boundary {onerror}>
+    {@render children()}
+
+    {#snippet failed(error, reset)}
+        {#if fallbackSnippet}
+            {@render fallbackSnippet(error instanceof Error ? error : new Error(String(error)), handleReset)}
+        {/if}
+    {/snippet}
+</svelte:boundary>

package/dist/FlareErrorBoundary.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from 'svelte';
+import { type FlareErrorHandlerOptions } from './createFlareErrorHandler.js';
+interface Props {
+    children: Snippet;
+    failed?: Snippet<[error: Error, reset: () => void]>;
+    resetKeys?: unknown[];
+    beforeEvaluate?: FlareErrorHandlerOptions['beforeEvaluate'];
+    beforeSubmit?: FlareErrorHandlerOptions['beforeSubmit'];
+    afterSubmit?: FlareErrorHandlerOptions['afterSubmit'];
+    onReset?: (error: Error | null) => void;
+}
+declare const FlareErrorBoundary: import("svelte").Component<Props, {}, "">;
+type FlareErrorBoundary = ReturnType<typeof FlareErrorBoundary>;
+export default FlareErrorBoundary;

package/dist/componentTree.d.ts

@@ -0,0 +1,9 @@
+export interface ComponentTreeNode {
+    name: string;
+    file: string;
+    parent: ComponentTreeNode | null;
+}
+export declare function __flareRegisterComponent(name: string, file: string): ComponentTreeNode;
+export declare function getComponentTreeContext(): ComponentTreeNode | null;
+export declare function lookupComponentTree(fileName: string, ancestor?: ComponentTreeNode | null): string[];
+export declare function findNode(fileName: string, ancestor?: ComponentTreeNode | null): ComponentTreeNode | undefined;

package/dist/componentTree.js

@@ -0,0 +1,99 @@
+import { getContext, onDestroy, setContext } from 'svelte';
+const CONTEXT_KEY = '__flare_component_tree';
+const registry = new Map();
+export function __flareRegisterComponent(name, file) {
+    let parent = null;
+    try {
+        parent = getContext(CONTEXT_KEY) ?? null;
+    }
+    catch {
+        // getContext throws outside component init
+    }
+    const node = { name, file, parent };
+    try {
+        setContext(CONTEXT_KEY, node);
+    }
+    catch {
+        // setContext throws outside component init
+    }
+    let nodes = registry.get(file);
+    if (!nodes) {
+        nodes = new Set();
+        registry.set(file, nodes);
+    }
+    nodes.add(node);
+    try {
+        onDestroy(() => {
+            const set = registry.get(file);
+            if (set) {
+                set.delete(node);
+                if (set.size === 0) {
+                    registry.delete(file);
+                }
+            }
+        });
+    }
+    catch {
+        // onDestroy throws outside component init
+    }
+    return node;
+}
+export function getComponentTreeContext() {
+    try {
+        return getContext(CONTEXT_KEY) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function lookupComponentTree(fileName, ancestor) {
+    const node = findNode(fileName, ancestor);
+    if (!node) {
+        return [];
+    }
+    const hierarchy = [];
+    let current = node;
+    const seen = new Set();
+    while (current && !seen.has(current)) {
+        seen.add(current);
+        hierarchy.push(current.name);
+        current = current.parent;
+    }
+    return hierarchy;
+}
+export function findNode(fileName, ancestor) {
+    const normalizedLookup = normalizePath(fileName);
+    const candidates = [];
+    for (const [registeredFile, nodes] of registry) {
+        const normalizedFile = normalizePath(registeredFile);
+        const match = normalizedLookup === normalizedFile ||
+            normalizedLookup.endsWith(normalizedFile) ||
+            normalizedFile.endsWith(normalizedLookup);
+        if (match) {
+            for (const node of nodes) {
+                candidates.push(node);
+            }
+        }
+    }
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    if (ancestor && candidates.length > 1) {
+        return candidates.find((c) => hasAncestor(c, ancestor)) ?? candidates[0];
+    }
+    return candidates[0];
+}
+function hasAncestor(node, ancestor) {
+    let current = node.parent;
+    const seen = new Set();
+    while (current && !seen.has(current)) {
+        if (current === ancestor)
+            return true;
+        seen.add(current);
+        current = current.parent;
+    }
+    return false;
+}
+function normalizePath(filePath) {
+    return filePath.replace(/\\/g, '/').replace(/^.*?\/src\//, 'src/');
+}

package/dist/contextToAttributes.d.ts

@@ -0,0 +1,3 @@
+import type { Attributes } from '@flareapp/js';
+import type { FlareSvelteContext } from './types.js';
+export declare function contextToAttributes(context: FlareSvelteContext): Attributes;

package/dist/contextToAttributes.js

@@ -0,0 +1,7 @@
+export function contextToAttributes(context) {
+    return {
+        'context.custom': {
+            svelte: context.svelte,
+        },
+    };
+}

package/dist/createFlareErrorHandler.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentTreeNode } from './componentTree.js';
+import type { FlareSvelteContext } from './types.js';
+export interface FlareErrorHandlerOptions {
+    ancestor?: ComponentTreeNode | null;
+    beforeEvaluate?: (params: {
+        error: Error;
+    }) => void;
+    beforeSubmit?: (params: {
+        error: Error;
+        context: FlareSvelteContext;
+    }) => FlareSvelteContext;
+    afterSubmit?: (params: {
+        error: Error;
+        context: FlareSvelteContext;
+    }) => void;
+}
+export declare function createFlareErrorHandler(options?: FlareErrorHandlerOptions): (rawError: unknown, _reset: () => void) => Promise<void>;

package/dist/createFlareErrorHandler.js

@@ -0,0 +1,34 @@
+import { convertToError, flare } from '@flareapp/js';
+import ErrorStackParser from 'error-stack-parser';
+import { contextToAttributes } from './contextToAttributes.js';
+import { extractComponentInfo } from './extractComponentInfo.js';
+import { getErrorOrigin } from './getErrorOrigin.js';
+import { registerSvelteSdkIdentity } from './identify.js';
+registerSvelteSdkIdentity();
+export function createFlareErrorHandler(options) {
+    return async (rawError, _reset) => {
+        const error = convertToError(rawError);
+        options?.beforeEvaluate?.({ error });
+        let frames = [];
+        try {
+            frames = ErrorStackParser.parse(error);
+        }
+        catch {
+            // unparseable stack
+        }
+        const { componentName, componentHierarchy } = extractComponentInfo(frames, options?.ancestor);
+        const errorOrigin = getErrorOrigin(frames);
+        let context = {
+            svelte: {
+                componentName,
+                componentHierarchy,
+                errorOrigin,
+            },
+        };
+        if (options?.beforeSubmit) {
+            context = options.beforeSubmit({ error, context });
+        }
+        flare.reportSilently(error, contextToAttributes(context));
+        options?.afterSubmit?.({ error, context });
+    };
+}

package/dist/extractComponentInfo.d.ts

@@ -0,0 +1,8 @@
+import type ErrorStackParser from 'error-stack-parser';
+import { type ComponentTreeNode } from './componentTree.js';
+interface ComponentInfo {
+    componentName: string | null;
+    componentHierarchy: string[];
+}
+export declare function extractComponentInfo(frames: ErrorStackParser.StackFrame[], ancestor?: ComponentTreeNode | null): ComponentInfo;
+export {};

package/dist/extractComponentInfo.js

@@ -0,0 +1,42 @@
+import { lookupComponentTree } from './componentTree.js';
+export function extractComponentInfo(frames, ancestor) {
+    const svelteFrames = frames.filter((frame) => frame.fileName && frame.fileName.includes('.svelte'));
+    if (svelteFrames.length === 0) {
+        return { componentName: null, componentHierarchy: [] };
+    }
+    // Try the preprocessor-based component tree first.
+    // Walk each .svelte frame until we find one that was registered.
+    for (const frame of svelteFrames) {
+        if (!frame.fileName)
+            continue;
+        const treeHierarchy = lookupComponentTree(frame.fileName, ancestor);
+        if (treeHierarchy.length > 0) {
+            return {
+                componentName: treeHierarchy[0],
+                componentHierarchy: treeHierarchy,
+            };
+        }
+    }
+    // Fallback: extract names from stack frames only (no preprocessor).
+    const names = [];
+    for (const frame of svelteFrames) {
+        const name = extractName(frame);
+        if (name && name !== names[names.length - 1]) {
+            names.push(name);
+        }
+    }
+    return {
+        componentName: names[0] ?? null,
+        componentHierarchy: names,
+    };
+}
+function extractName(frame) {
+    if (frame.functionName && frame.functionName !== '<anonymous>' && !frame.functionName.includes('.')) {
+        return frame.functionName;
+    }
+    if (frame.fileName) {
+        const match = frame.fileName.match(/([^/]+)\.svelte/);
+        return match?.[1] ?? null;
+    }
+    return null;
+}

package/dist/getErrorOrigin.d.ts

@@ -0,0 +1,3 @@
+import type ErrorStackParser from 'error-stack-parser';
+import type { SvelteErrorOrigin } from './types.js';
+export declare function getErrorOrigin(frames: ErrorStackParser.StackFrame[]): SvelteErrorOrigin;

package/dist/getErrorOrigin.js

@@ -0,0 +1,64 @@
+// Heuristic classification of where a Svelte error originated, based on stack frame inspection.
+//
+// Svelte's onMount/beforeUpdate/$effect callbacks, DOM event handlers, and render functions
+// all produce errors that look identical at the catch site (the error boundary sees a plain Error
+// either way). The only distinguishing signal is the stack trace: different origins leave
+// recognizable function names, file names, or DOM API calls in the frames.
+//
+// We check patterns in priority order: event > effect > render > unknown.
+// Priority matters because an event handler inside a Svelte component would match both
+// EVENT_PATTERNS and the .svelte filename check; we want 'event' to win.
+// Inline event handlers (onclick, onsubmit, ...) and DOM event API calls.
+// Browsers compile `onclick={handler}` to `.onclick = ...` or `addEventListener(...)`,
+// so these patterns catch both Svelte's compiled output and manual DOM calls.
+const EVENT_PATTERNS = [
+    /\.onclick\b/i,
+    /\.onsubmit\b/i,
+    /\.onchange\b/i,
+    /\.oninput\b/i,
+    /\.onkeydown\b/i,
+    /\.onkeyup\b/i,
+    /\.onfocus\b/i,
+    /\.onblur\b/i,
+    /\.onmouse/i,
+    /\.onpointer/i,
+    /\.ontouch/i,
+    /addEventListener/,
+    /dispatchEvent/,
+    /EventTarget\./,
+    /HTMLElement\./,
+    /HTMLButtonElement\./,
+    /HTMLInputElement\./,
+    /HTMLFormElement\./,
+];
+// Async side-effects: $effect callbacks, onMount microtasks, promise continuations.
+// Svelte 5 schedules effects via queueMicrotask; promise chains and MutationObserver
+// callbacks are also async side-effects, not render-phase code.
+const EFFECT_PATTERNS = [/queueMicrotask/, /Promise\.then/, /Promise\.catch/, /MutationObserver/];
+// Inspects a parsed stack trace and classifies the error origin into one of:
+//   'event'   - error happened in a DOM event handler
+//   'effect'  - error happened in an async side-effect ($effect, onMount, promise)
+//   'render'  - error happened during Svelte component render (template/script top-level)
+//   'unknown' - no frames or no recognizable pattern
+export function getErrorOrigin(frames) {
+    if (frames.length === 0) {
+        return 'unknown';
+    }
+    // Flatten each frame into a single searchable string so regex matching is straightforward.
+    const frameStrings = frames.map((f) => `${f.functionName ?? ''} ${f.fileName ?? ''} ${f.source ?? ''}`);
+    // Check event patterns first (highest priority).
+    if (frameStrings.some((s) => EVENT_PATTERNS.some((p) => p.test(s)))) {
+        return 'event';
+    }
+    // Then async effect patterns.
+    if (frameStrings.some((s) => EFFECT_PATTERNS.some((p) => p.test(s)))) {
+        return 'effect';
+    }
+    // If any frame originates from a .svelte file but didn't match event/effect,
+    // the error most likely occurred during the synchronous render phase.
+    const hasSvelteFrame = frames.some((f) => f.fileName?.includes('.svelte'));
+    if (hasSvelteFrame) {
+        return 'render';
+    }
+    return 'unknown';
+}

package/dist/identify.d.ts

@@ -0,0 +1 @@
+export declare function registerSvelteSdkIdentity(): void;

package/dist/identify.js

@@ -0,0 +1,10 @@
+import { flare } from '@flareapp/js';
+import { PACKAGE_VERSION } from './version.js';
+let registered = false;
+export function registerSvelteSdkIdentity() {
+    if (registered)
+        return;
+    registered = true;
+    flare.setSdkInfo({ name: '@flareapp/svelte', version: PACKAGE_VERSION });
+    flare.setFramework({ name: 'Svelte' });
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { default as FlareErrorBoundary } from './FlareErrorBoundary.svelte';
+export { createFlareErrorHandler, type FlareErrorHandlerOptions } from './createFlareErrorHandler.js';
+export { __flareRegisterComponent, getComponentTreeContext } from './componentTree.js';
+export { flarePreprocessor, type FlarePreprocessorOptions } from './preprocessor.js';
+export type { FlareSvelteContext, SvelteErrorOrigin } from './types.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+import { registerSvelteSdkIdentity } from './identify.js';
+registerSvelteSdkIdentity();
+export { default as FlareErrorBoundary } from './FlareErrorBoundary.svelte';
+export { createFlareErrorHandler } from './createFlareErrorHandler.js';
+export { __flareRegisterComponent, getComponentTreeContext } from './componentTree.js';
+export { flarePreprocessor } from './preprocessor.js';

package/dist/preprocessor.d.ts

@@ -0,0 +1,5 @@
+import type { PreprocessorGroup } from 'svelte/compiler';
+export interface FlarePreprocessorOptions {
+    exclude?: RegExp;
+}
+export declare function flarePreprocessor(options?: FlarePreprocessorOptions): PreprocessorGroup;

package/dist/preprocessor.js

@@ -0,0 +1,53 @@
+export function flarePreprocessor(options) {
+    const exclude = options?.exclude;
+    return {
+        name: 'flare-component-tree',
+        markup({ content, filename }) {
+            if (!filename?.includes('.svelte')) {
+                return;
+            }
+            if (exclude?.test(filename)) {
+                return;
+            }
+            const hasScript = /<script[\s>]/i.test(content);
+            if (hasScript) {
+                return;
+            }
+            const componentName = extractComponentName(filename);
+            const escapedFile = escapeString(filename);
+            const injection = `<script>\n` +
+                `import { __flareRegisterComponent as __flare_reg__ } from '@flareapp/svelte';\n` +
+                `const __flare_node__ = __flare_reg__('${componentName}', '${escapedFile}');\n` +
+                `</script>\n`;
+            return {
+                code: injection + content,
+            };
+        },
+        script({ content, filename, attributes }) {
+            if (!filename?.includes('.svelte')) {
+                return;
+            }
+            if (exclude?.test(filename)) {
+                return;
+            }
+            if (attributes.context === 'module' || attributes.module != null) {
+                return;
+            }
+            const componentName = extractComponentName(filename);
+            const escapedFile = escapeString(filename);
+            const injection = `import { __flareRegisterComponent as __flare_reg__ } from '@flareapp/svelte';\n` +
+                `const __flare_node__ = __flare_reg__('${componentName}', '${escapedFile}');\n`;
+            return {
+                code: injection + content,
+            };
+        },
+    };
+}
+function extractComponentName(filename) {
+    const normalized = filename.replace(/\\/g, '/');
+    const base = normalized.split('/').pop() ?? filename;
+    return base.replace(/\.svelte$/, '');
+}
+function escapeString(str) {
+    return str.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+export type SvelteErrorOrigin = 'render' | 'event' | 'effect' | 'unknown';
+export interface FlareSvelteContext {
+    svelte: {
+        componentName: string | null;
+        componentHierarchy: string[];
+        errorOrigin: SvelteErrorOrigin;
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const PACKAGE_VERSION = "2.0.0-alpha.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+// generated during release, do not modify
+export const PACKAGE_VERSION = '2.0.0-alpha.0';

package/package.json

@@ -0,0 +1,72 @@
+{
+    "name": "@flareapp/svelte",
+    "version": "2.0.0-alpha.0",
+    "description": "Svelte client for flareapp.io",
+    "homepage": "https://flareapp.io",
+    "bugs": "https://github.com/spatie/flare-client-js/issues",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/spatie/flare-client-js.git"
+    },
+    "license": "MIT",
+    "author": {
+        "name": "Spatie",
+        "email": "info@spatie.be"
+    },
+    "contributors": [
+        "Adriaan Marain <adriaan@spatie.be>",
+        "Alex Vanderbist <alex@spatie.be>",
+        "Dries Heyninck <dries@spatie.be>",
+        "Freek Van der Herten <freek@spatie.be>",
+        "Sebastian De Deyne <sebastian@spatie.be>",
+        "Sébastien Henau <seba@spatie.be>"
+    ],
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "svelte": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "svelte": "./dist/index.js",
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            }
+        },
+        "./preprocessor": {
+            "import": {
+                "types": "./dist/preprocessor.d.ts",
+                "default": "./dist/preprocessor.js"
+            }
+        }
+    },
+    "scripts": {
+        "prepublishOnly": "npm run build",
+        "generate:version": "node ../../scripts/generate-version.mjs .",
+        "build": "npm run generate:version && svelte-package -i src -o dist",
+        "test": "vitest run",
+        "typescript": "tsc --noEmit",
+        "release": "release-it"
+    },
+    "devDependencies": {
+        "@flareapp/js": "file:../js",
+        "@sveltejs/package": "^2.5.7",
+        "@sveltejs/vite-plugin-svelte": "^5.0.0",
+        "@testing-library/svelte": "^5.0.0",
+        "jsdom": "^26.1.0",
+        "svelte": "^5.0.0",
+        "typescript": "^5.7.0",
+        "vitest": "^4.0.0"
+    },
+    "peerDependencies": {
+        "@flareapp/js": "^2.0.0",
+        "svelte": "^5.3.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "error-stack-parser": "^2.1.4"
+    }
+}