@mushi-mushi/svelte 0.8.4 → 0.9.0

package/CONTRIBUTING.md

@@ -101,6 +101,17 @@ Releases are fully automated. Maintainers don't run `npm publish` by hand.
 
 If GitHub's anti-loop protection suppresses the auto re-fire (the squash merge can be attributed to `github-actions[bot]`), trigger the workflow manually: **Actions → release → Run workflow → master**.
 
+### Known CI/CD quirks and their automatic safeguards
+
+A handful of GitHub-Actions × Changesets edge cases have caused release-pipeline stalls in the past. Each is now caught automatically — keep these in mind when you see the symptom:
+
+| Symptom | Root cause | Automatic safeguard |
+| --- | --- | --- |
+| The `Build & Test` required check never registers on the `chore: version packages` PR — the PR stays "Required check missing" forever | `changeset-release/master` is pushed by `github-actions[bot]`. GitHub silently drops the downstream `pull_request` event to prevent bot loops (observed on PR #45, #102, #124). | `ci.yml` now also triggers on `push` to `changeset-release/master`, so `Build & Test` reports against the head commit directly. No empty-commit nudge needed. |
+| Release workflow fails with `No commits between master and changeset-release/master` after merging a PR with a new changeset. | A `.changeset/*.md` file whose YAML frontmatter only targets packages listed in `.changeset/config.json#ignore` (e.g. `@mushi-mushi/server`, `@mushi-mushi/admin`). `changeset version` produces no bumps, the version PR is empty, the next push errors (PR #102 / #121, 2026-05-19). | `pnpm check:changeset-orphans` runs in both `ci.yml` and `release.yml`. PR CI fails with an actionable message naming the orphan file *before* it can reach master. If you legitimately need to record an internal-only change, omit the changeset entirely — the diff lives in git history. |
+| Release workflow's `Audit signatures of installed dependencies` step fails with `npm ETARGET / No matching version found for @mushi-mushi/<pkg>@<ver>` seconds after the publish step succeeded. | npm's registry CDN can take up to ~30s to propagate a freshly-published manifest. The audit step shells out to `npm install` against the just-published version and races the CDN (observed 2026-05-20, run 26149167393). | The audit step retries with exponential backoff (1, 2, 4, 8, 16, 32s — 63s total) before failing. Sigstore signatures are written at publish time, so a one-off audit failure never indicates a corrupted package — `pnpm view <pkg> version` is the ground truth. |
+| Push to `master` after merging a PR doesn't fire the `Release` workflow. | Same anti-loop protection: when a squash merge is attributed to `github-actions[bot]`, GitHub may suppress the downstream `push` trigger. Sporadic — observed twice in the last 60 days. | `release.yml` keeps `workflow_dispatch` as the manual fallback. Recovery: **Actions → Release → Run workflow → master**. The `Build & Verify` job re-runs identically to the auto-fired path. |
+
 ### Adding a brand-new publishable package
 
 Trusted Publisher bindings are configured **per package** on `npmjs.com` and require the package to already exist on the registry. New packages therefore need a one-time bootstrap before OIDC can take over.

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": "0.9.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.5.0",
+    "@mushi-mushi/web": "^1.5.0"
   },
   "devDependencies": {
     "eslint": "^10.3.0",