@mushi-mushi/svelte 0.8.4 → 1.0.0

package/CONTRIBUTING.md

@@ -63,7 +63,7 @@ packages/
   verify/        Fix verification (BSL)
 apps/
   admin/         Admin dashboard (React + Tailwind)
-  docs/          Documentation site (planned)
+  docs/          Documentation site (Nextra — apps/docs)
 tooling/
   eslint-config/ Shared ESLint flat config
   tsconfig/      Shared TypeScript configs
@@ -81,6 +81,28 @@ tooling/
    ```
 6. Open a pull request
 
+### Documentation (docs-as-code)
+
+If your PR changes **user-visible SDK or CLI behavior**, update docs in the **same PR**:
+
+| Surface | When to update |
+| --- | --- |
+| `packages/*/README.md` | npm-facing install/API/config changes for that package |
+| `apps/docs/content/**/*.mdx` | Long-form guides, quickstarts, admin console docs |
+| Root `README.md` | Marketing stats only when counts change — run `pnpm check:docs-stats` |
+
+Guardrails (run locally before pushing):
+
+```bash
+pnpm check:docs-stats          # root README stat badges
+pnpm check:sdk-version-matrix  # apps/docs/content/sdks/index.mdx versions
+pnpm check:internal-doc-links  # dead /foo links in MDX
+pnpm check:bundle-docs         # @mushi-mushi/web size-limit vs README
+pnpm gen:llms-txt              # regenerate apps/docs/public/llms.txt after nav changes
+```
+
+README changes on npm packages only appear on [npmjs.com](https://www.npmjs.com) after the next **Changesets publish**.
+
 ## Changesets
 
 We use [Changesets](https://github.com/changesets/changesets) for versioning. If your PR modifies a published package (`core`, `web`, `react`, `vue`, `svelte`, `angular`, `react-native`, `cli`, `mcp`), add a changeset:

package/README.md

@@ -6,26 +6,50 @@ Svelte SDK for Mushi Mushi bug reporting. **API-only** — captures errors and s
 >
 > **Other frameworks:** [`@mushi-mushi/react`](https://npmjs.com/package/@mushi-mushi/react) · [`@mushi-mushi/vue`](https://npmjs.com/package/@mushi-mushi/vue) · [`@mushi-mushi/angular`](https://npmjs.com/package/@mushi-mushi/angular) · [`@mushi-mushi/react-native`](https://npmjs.com/package/@mushi-mushi/react-native) · [`@mushi-mushi/capacitor`](https://npmjs.com/package/@mushi-mushi/capacitor) · [`@mushi-mushi/web`](https://npmjs.com/package/@mushi-mushi/web) (vanilla JS)
 
+## Install
+
+```bash
+npm install @mushi-mushi/svelte @mushi-mushi/web
+# or: npx mushi-mushi
+```
+
+## Environment variables
+
+| Stack | Project ID | API key |
+| --- | --- | --- |
+| Vite / SvelteKit | `VITE_MUSHI_PROJECT_ID` | `VITE_MUSHI_API_KEY` |
+
+See [Project ID & API keys](https://docs.mushimushi.dev/concepts/credentials).
+
 ## Usage
 
 ```ts
 import { initMushi, getMushi } from '@mushi-mushi/svelte'
 
-initMushi({ projectId: 'proj_xxx', apiKey: 'mushi_xxx' })
+initMushi({
+  projectId: import.meta.env.VITE_MUSHI_PROJECT_ID,
+  apiKey: import.meta.env.VITE_MUSHI_API_KEY,
+})
 
-// Later
 const mushi = getMushi()
 mushi.submitReport({ title: 'broken', description: '...' })
 ```
 
-### With Widget UI
+### With widget UI
 
 ```ts
 import { initMushi } from '@mushi-mushi/svelte'
 import { Mushi } from '@mushi-mushi/web'
 
-initMushi({ projectId: 'proj_xxx', apiKey: 'mushi_xxx' })
-Mushi.init({ projectId: 'proj_xxx', apiKey: 'mushi_xxx' })
+initMushi({
+  projectId: import.meta.env.VITE_MUSHI_PROJECT_ID,
+  apiKey: import.meta.env.VITE_MUSHI_API_KEY,
+})
+
+Mushi.init({
+  projectId: import.meta.env.VITE_MUSHI_PROJECT_ID,
+  apiKey: import.meta.env.VITE_MUSHI_API_KEY,
+})
 ```
 
 ### SvelteKit error handler
@@ -36,7 +60,15 @@ import { createMushiErrorHandler } from '@mushi-mushi/svelte'
 export const handleError = createMushiErrorHandler()
 ```
 
-## Peer Dependencies
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `initMushi(config)` | Initialize once at app startup |
+| `getMushi()` | Access the SDK instance |
+| `createMushiErrorHandler()` | SvelteKit `handleError` integration |
+
+## Peer dependencies
 
 - `svelte` >= 4
 

package/dist/index.cjs

@@ -22,24 +22,23 @@ var index_exports = {};
 __export(index_exports, {
   createMushiErrorHandler: () => createMushiErrorHandler,
   getMushi: () => getMushi,
-  initMushi: () => initMushi
+  initMushi: () => initMushi,
+  mushiHandleError: () => mushiHandleError
 });
 module.exports = __toCommonJS(index_exports);
 var import_web = require("@mushi-mushi/web");
-function toCoreConfig(config) {
-  return {
-    projectId: config.projectId,
-    apiKey: config.apiKey,
-    ...config.endpoint ? { apiEndpoint: config.endpoint } : {},
-    ...config.capture !== void 0 ? { capture: config.capture } : {}
-  };
-}
+var isBrowser = () => typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined";
 function initMushi(config) {
-  return import_web.Mushi.init(toCoreConfig(config));
+  if (!isBrowser()) return null;
+  return import_web.Mushi.init(config);
 }
 function getMushi() {
   const instance = import_web.Mushi.getInstance();
-  if (!instance) throw new Error("Call initMushi() first");
+  if (!instance) {
+    throw new Error(
+      "Mushi not initialised \u2014 call initMushi() in src/hooks.client.ts or a top-level +layout.svelte onMount."
+    );
+  }
   return instance;
 }
 function createMushiErrorHandler() {
@@ -54,9 +53,29 @@ function createMushiErrorHandler() {
     }
   };
 }
+function mushiHandleError(opts = {}) {
+  return (input) => {
+    const { error, event, status, message } = input;
+    const instance = import_web.Mushi.getInstance();
+    if (instance) {
+      instance.captureException(error, {
+        source: "sveltekit-handle-error",
+        metadata: {
+          route: event?.url?.pathname,
+          method: event?.request?.method,
+          status,
+          message
+        }
+      }).catch(() => {
+      });
+    }
+    return opts.format?.(error, event);
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createMushiErrorHandler,
   getMushi,
-  initMushi
+  initMushi,
+  mushiHandleError
 });

package/dist/index.d.cts

@@ -1,22 +1,38 @@
-import { MushiSDKInstance } from '@mushi-mushi/core';
+import { MushiSDKInstance, MushiConfig } from '@mushi-mushi/core';
+export { MushiConfig, MushiReportCategory, MushiSDKInstance } from '@mushi-mushi/core';
 
 /**
  * FILE: packages/svelte/src/index.ts
- * PURPOSE: Svelte SDK for Mushi Mushi — delegates entirely to @mushi-mushi/web
- *          so offline queue, PII scrubber, breadcrumb buffer, and rate limiter
- *          are all inherited automatically. Mirrors the React provider pattern.
+ * PURPOSE: Svelte / SvelteKit SDK for Mushi Mushi — delegates entirely
+ *          to @mushi-mushi/web so offline queue, PII scrubber, breadcrumb
+ *          buffer, rate limiter, INP capture, beforeSendFeedback, and
+ *          onCrashedLastRun are all inherited automatically.
+ *
+ * Round 8 (2026-05-21):
+ *   - `MushiConfig` is now the canonical core type. Consumers get the
+ *     full Round 7 surface (theme, position, locale, beforeSendFeedback,
+ *     onCrashedLastRun, …) with no narrow re-shape.
+ *   - SSR guard around `initMushi` so SvelteKit's first server-render
+ *     doesn't reach for `window`.
+ *   - `mushiHandleError` is the SvelteKit-shaped server-hook helper
+ *     for `src/hooks.server.ts` — it returns `App.Error | void` to fit
+ *     the SvelteKit type contract.
  */
 
-interface MushiConfig {
-    projectId: string;
-    apiKey: string;
-    endpoint?: string;
-    capture?: {
-        discoverInventory?: boolean;
-    };
-}
-declare function initMushi(config: MushiConfig): MushiSDKInstance;
+/**
+ * Initialise the Mushi SDK. SSR-safe: returns `null` when run on the
+ * server (SvelteKit's hooks.server.ts) so the runner can skip wiring
+ * up on the wrong side. Mount this from `src/hooks.client.ts`'s
+ * `init` export, or from a top-level `+layout.svelte`'s `onMount`.
+ */
+declare function initMushi(config: MushiConfig): MushiSDKInstance | null;
 declare function getMushi(): MushiSDKInstance;
+/**
+ * Generic error-handler factory — works in any Svelte / SvelteKit
+ * context that surfaces an `{ error, event }` shape. Kept for
+ * backwards compatibility; new code should prefer `mushiHandleError`
+ * which matches SvelteKit's `handleError` server-hook type exactly.
+ */
 declare function createMushiErrorHandler(): ({ error, event }: {
     error: unknown;
     event?: {
@@ -25,5 +41,47 @@ declare function createMushiErrorHandler(): ({ error, event }: {
         };
     };
 }) => void;
+/**
+ * SvelteKit `handleError` server-hook helper. Drop into
+ * `src/hooks.server.ts` and `src/hooks.client.ts`:
+ *
+ * ```ts
+ * // src/hooks.server.ts
+ * import type { HandleServerError } from '@sveltejs/kit'
+ * import { mushiHandleError } from '@mushi-mushi/svelte'
+ *
+ * export const handleError: HandleServerError = mushiHandleError({
+ *   // optional — the default extracts a stable message from the error
+ *   format: (error) => ({ message: 'Internal error', code: 'E_INTERNAL' }),
+ * })
+ * ```
+ *
+ * The returned hook captures the error to Mushi and forwards the
+ * formatted shape to SvelteKit's typed `App.Error` interface so the
+ * +error.svelte page receives a consistent payload.
+ *
+ * Server-side: writes via `Mushi.getInstance()` if `initMushi` was
+ * called from `hooks.server.ts`. Otherwise no-ops gracefully.
+ */
+interface MushiHandleErrorOptions {
+    /** Optional formatter that maps the error to `App.Error`. */
+    format?: (error: unknown, event?: SvelteKitErrorEvent) => Record<string, unknown> | void;
+}
+interface SvelteKitErrorEvent {
+    url?: {
+        pathname?: string;
+    };
+    request?: {
+        method?: string;
+    };
+    status?: number;
+    message?: string;
+}
+declare function mushiHandleError(opts?: MushiHandleErrorOptions): (input: {
+    error: unknown;
+    event?: SvelteKitErrorEvent;
+    status?: number;
+    message?: string;
+}) => Record<string, unknown> | void;
 
-export { type MushiConfig, createMushiErrorHandler, getMushi, initMushi };
+export { type MushiHandleErrorOptions, type SvelteKitErrorEvent, createMushiErrorHandler, getMushi, initMushi, mushiHandleError };

package/dist/index.d.ts

@@ -1,22 +1,38 @@
-import { MushiSDKInstance } from '@mushi-mushi/core';
+import { MushiSDKInstance, MushiConfig } from '@mushi-mushi/core';
+export { MushiConfig, MushiReportCategory, MushiSDKInstance } from '@mushi-mushi/core';
 
 /**
  * FILE: packages/svelte/src/index.ts
- * PURPOSE: Svelte SDK for Mushi Mushi — delegates entirely to @mushi-mushi/web
- *          so offline queue, PII scrubber, breadcrumb buffer, and rate limiter
- *          are all inherited automatically. Mirrors the React provider pattern.
+ * PURPOSE: Svelte / SvelteKit SDK for Mushi Mushi — delegates entirely
+ *          to @mushi-mushi/web so offline queue, PII scrubber, breadcrumb
+ *          buffer, rate limiter, INP capture, beforeSendFeedback, and
+ *          onCrashedLastRun are all inherited automatically.
+ *
+ * Round 8 (2026-05-21):
+ *   - `MushiConfig` is now the canonical core type. Consumers get the
+ *     full Round 7 surface (theme, position, locale, beforeSendFeedback,
+ *     onCrashedLastRun, …) with no narrow re-shape.
+ *   - SSR guard around `initMushi` so SvelteKit's first server-render
+ *     doesn't reach for `window`.
+ *   - `mushiHandleError` is the SvelteKit-shaped server-hook helper
+ *     for `src/hooks.server.ts` — it returns `App.Error | void` to fit
+ *     the SvelteKit type contract.
  */
 
-interface MushiConfig {
-    projectId: string;
-    apiKey: string;
-    endpoint?: string;
-    capture?: {
-        discoverInventory?: boolean;
-    };
-}
-declare function initMushi(config: MushiConfig): MushiSDKInstance;
+/**
+ * Initialise the Mushi SDK. SSR-safe: returns `null` when run on the
+ * server (SvelteKit's hooks.server.ts) so the runner can skip wiring
+ * up on the wrong side. Mount this from `src/hooks.client.ts`'s
+ * `init` export, or from a top-level `+layout.svelte`'s `onMount`.
+ */
+declare function initMushi(config: MushiConfig): MushiSDKInstance | null;
 declare function getMushi(): MushiSDKInstance;
+/**
+ * Generic error-handler factory — works in any Svelte / SvelteKit
+ * context that surfaces an `{ error, event }` shape. Kept for
+ * backwards compatibility; new code should prefer `mushiHandleError`
+ * which matches SvelteKit's `handleError` server-hook type exactly.
+ */
 declare function createMushiErrorHandler(): ({ error, event }: {
     error: unknown;
     event?: {
@@ -25,5 +41,47 @@ declare function createMushiErrorHandler(): ({ error, event }: {
         };
     };
 }) => void;
+/**
+ * SvelteKit `handleError` server-hook helper. Drop into
+ * `src/hooks.server.ts` and `src/hooks.client.ts`:
+ *
+ * ```ts
+ * // src/hooks.server.ts
+ * import type { HandleServerError } from '@sveltejs/kit'
+ * import { mushiHandleError } from '@mushi-mushi/svelte'
+ *
+ * export const handleError: HandleServerError = mushiHandleError({
+ *   // optional — the default extracts a stable message from the error
+ *   format: (error) => ({ message: 'Internal error', code: 'E_INTERNAL' }),
+ * })
+ * ```
+ *
+ * The returned hook captures the error to Mushi and forwards the
+ * formatted shape to SvelteKit's typed `App.Error` interface so the
+ * +error.svelte page receives a consistent payload.
+ *
+ * Server-side: writes via `Mushi.getInstance()` if `initMushi` was
+ * called from `hooks.server.ts`. Otherwise no-ops gracefully.
+ */
+interface MushiHandleErrorOptions {
+    /** Optional formatter that maps the error to `App.Error`. */
+    format?: (error: unknown, event?: SvelteKitErrorEvent) => Record<string, unknown> | void;
+}
+interface SvelteKitErrorEvent {
+    url?: {
+        pathname?: string;
+    };
+    request?: {
+        method?: string;
+    };
+    status?: number;
+    message?: string;
+}
+declare function mushiHandleError(opts?: MushiHandleErrorOptions): (input: {
+    error: unknown;
+    event?: SvelteKitErrorEvent;
+    status?: number;
+    message?: string;
+}) => Record<string, unknown> | void;
 
-export { type MushiConfig, createMushiErrorHandler, getMushi, initMushi };
+export { type MushiHandleErrorOptions, type SvelteKitErrorEvent, createMushiErrorHandler, getMushi, initMushi, mushiHandleError };

package/dist/index.js

@@ -1,19 +1,17 @@
 // src/index.ts
 import { Mushi } from "@mushi-mushi/web";
-function toCoreConfig(config) {
-  return {
-    projectId: config.projectId,
-    apiKey: config.apiKey,
-    ...config.endpoint ? { apiEndpoint: config.endpoint } : {},
-    ...config.capture !== void 0 ? { capture: config.capture } : {}
-  };
-}
+var isBrowser = () => typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined";
 function initMushi(config) {
-  return Mushi.init(toCoreConfig(config));
+  if (!isBrowser()) return null;
+  return Mushi.init(config);
 }
 function getMushi() {
   const instance = Mushi.getInstance();
-  if (!instance) throw new Error("Call initMushi() first");
+  if (!instance) {
+    throw new Error(
+      "Mushi not initialised \u2014 call initMushi() in src/hooks.client.ts or a top-level +layout.svelte onMount."
+    );
+  }
   return instance;
 }
 function createMushiErrorHandler() {
@@ -28,8 +26,28 @@ function createMushiErrorHandler() {
     }
   };
 }
+function mushiHandleError(opts = {}) {
+  return (input) => {
+    const { error, event, status, message } = input;
+    const instance = Mushi.getInstance();
+    if (instance) {
+      instance.captureException(error, {
+        source: "sveltekit-handle-error",
+        metadata: {
+          route: event?.url?.pathname,
+          method: event?.request?.method,
+          status,
+          message
+        }
+      }).catch(() => {
+      });
+    }
+    return opts.format?.(error, event);
+  };
+}
 export {
   createMushiErrorHandler,
   getMushi,
-  initMushi
+  initMushi,
+  mushiHandleError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mushi-mushi/svelte",
-  "version": "0.8.4",
+  "version": "1.0.0",
   "license": "MIT",
   "description": "Svelte SDK for Mushi Mushi — context-based init, SvelteKit error hook integration",
   "main": "./dist/index.js",
@@ -10,8 +10,8 @@
     "svelte": ">=4"
   },
   "dependencies": {
-    "@mushi-mushi/core": "^1.2.0",
-    "@mushi-mushi/web": "^1.2.0"
+    "@mushi-mushi/core": "^1.15.0",
+    "@mushi-mushi/web": "^1.14.1"
   },
   "devDependencies": {
     "eslint": "^10.3.0",