@guidelytech/svelte 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @guidelytech/svelte
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Svelte 4/5 stores, actions and context helpers for Guidely (wraps `@guidelytech/sdk-core`).
+
+```bash
+pnpm add @guidelytech/svelte
+```
+
+```svelte
+<script>
+  import { onMount } from "svelte";
+  import { createGuidely, guidely, activeGuide, guideTrigger } from "@guidelytech/svelte";
+  onMount(() => {
+    const client = createGuidely({ projectId: "pk_dev_…", apiUrl: "http://localhost:3000" });
+    return () => client.destroy();
+  });
+</script>
+
+<button use:guideTrigger={"new-user-onboarding"}>Restart tour</button>
+{#if $activeGuide}<p>Showing {$activeGuide.name}</p>{/if}
+```
+
+| Export | Description |
+|---|---|
+| `createGuidely(options)` | Creates the client (browser only; throws a helpful error on the server) and stores it in `guidely`. Returns the existing client when called twice with the same key. |
+| `destroyGuidely()` | Destroys the client and clears the store. |
+| `syncGuidelyUser(user \| null \| undefined)` | Idempotently mirrors your signed-in user: identifies when id/traits/account change, `reset()`s on `null` (sign-out), ignores `undefined` (still loading). Call from a `$effect` / `$:`; no-op on the server. |
+| `guidely` | `Writable<GuidelyClient \| null>`. |
+| `guidelyReady` | `Readable<boolean>`. |
+| `activeGuide` | `Readable<PublishedGuide \| null>`. |
+| `checklistProgress(idOrKey)` | `Readable<ChecklistProgressState>`. |
+| `guideCompleted(idOrKey)` | `Readable<boolean>`. |
+| `setGuidelyContext(client)` / `getGuidelyContext()` | Component context helpers (fall back to the store). |
+| `use:guideTrigger={"guide-key"}` | Clicking the element starts the guide. |
+| `use:guidelyTarget={"id"}` | Marks the element with `data-tour="id"` (no runtime behaviour). |

package/dist/index.cjs

@@ -0,0 +1,145 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  activeGuide: () => activeGuide,
+  checklistProgress: () => checklistProgress,
+  createGuidely: () => createGuidely,
+  destroyGuidely: () => destroyGuidely,
+  getGuidelyContext: () => getGuidelyContext,
+  guideCompleted: () => guideCompleted,
+  guideTrigger: () => guideTrigger,
+  guidely: () => guidely,
+  guidelyReady: () => guidelyReady,
+  guidelyTarget: () => guidelyTarget,
+  setGuidelyContext: () => setGuidelyContext,
+  syncGuidelyUser: () => syncGuidelyUser
+});
+module.exports = __toCommonJS(index_exports);
+var import_sdk_core = require("@guidelytech/sdk-core");
+var import_svelte = require("svelte");
+var import_store = require("svelte/store");
+var guidely = (0, import_store.writable)(null);
+function createGuidely(options) {
+  if (typeof window === "undefined") throw new Error("[Guidely] createGuidely() can only run in the browser. Call it inside onMount(), or use initGuidely() from @guidelytech/sveltekit.");
+  const existing = (0, import_store.get)(guidely);
+  if (existing && !existing.getState().destroyed && existing.options.projectId === options.projectId) return existing;
+  existing?.destroy();
+  const client = (0, import_sdk_core.createGuidely)(options);
+  guidely.set(client);
+  if (pendingUser !== void 0) applyUser(client, pendingUser);
+  pendingUser = void 0;
+  return client;
+}
+var appliedUser = /* @__PURE__ */ new WeakMap();
+var pendingUser;
+function syncGuidelyUser(user) {
+  if (typeof window === "undefined") return;
+  const client = (0, import_store.get)(guidely);
+  if (client) applyUser(client, user);
+  else pendingUser = user;
+}
+function applyUser(client, user) {
+  if (user === void 0) return;
+  const key = user ? JSON.stringify([String(user.id), user.traits ?? null, user.account ?? null]) : null;
+  if (appliedUser.has(client) && appliedUser.get(client) === key) return;
+  appliedUser.set(client, key);
+  if (user) void client.identify(user.id, user.traits, user.account);
+  else if (client.getState().user?.id) client.reset();
+}
+function destroyGuidely() {
+  (0, import_store.get)(guidely)?.destroy();
+  guidely.set(null);
+}
+var CONTEXT_KEY = /* @__PURE__ */ Symbol.for("guidely");
+function setGuidelyContext(client) {
+  (0, import_svelte.setContext)(CONTEXT_KEY, client);
+}
+function getGuidelyContext() {
+  return (0, import_svelte.getContext)(CONTEXT_KEY) ?? (0, import_store.get)(guidely);
+}
+function fromClient(initial, compute, events) {
+  return (0, import_store.readable)(initial, (set) => {
+    let offs = [];
+    const unsub = guidely.subscribe((client) => {
+      offs.forEach((off) => off());
+      offs = [];
+      if (!client) return set(initial);
+      const update = () => set(compute(client));
+      update();
+      offs = events.map((e) => client.on(e, update));
+    });
+    return () => {
+      offs.forEach((off) => off());
+      unsub();
+    };
+  });
+}
+var guidelyReady = fromClient(false, (c) => c.getState().ready, ["ready"]);
+var activeGuide = fromClient(null, (c) => c.getActiveGuide(), ["ready", "guide:start", "guide:complete", "guide:dismiss", "guide:skip", "identify"]);
+function checklistProgress(idOrKey) {
+  return fromClient({ completedTaskIds: [], completedAt: null, dismissedAt: null }, (c) => c.getChecklistProgress(idOrKey), ["ready", "identify", "checklist:task", "checklist:complete"]);
+}
+function guideCompleted(idOrKey) {
+  return (0, import_store.derived)(fromClient(false, (c) => c.isGuideCompleted(idOrKey), ["ready", "identify", "guide:complete"]), (v) => v);
+}
+function guideTrigger(node, key) {
+  let current = key;
+  const onClick = (e) => {
+    e.preventDefault();
+    (0, import_store.get)(guidely)?.startGuide(current);
+  };
+  node.addEventListener("click", onClick);
+  node.setAttribute("data-guidely-trigger", current);
+  return {
+    update(next) {
+      current = next;
+      node.setAttribute("data-guidely-trigger", next);
+    },
+    destroy() {
+      node.removeEventListener("click", onClick);
+    }
+  };
+}
+function guidelyTarget(node, id) {
+  const apply = (v) => {
+    if (v) node.setAttribute("data-tour", v);
+  };
+  apply(id);
+  return { update: apply, destroy() {
+  } };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  activeGuide,
+  checklistProgress,
+  createGuidely,
+  destroyGuidely,
+  getGuidelyContext,
+  guideCompleted,
+  guideTrigger,
+  guidely,
+  guidelyReady,
+  guidelyTarget,
+  setGuidelyContext,
+  syncGuidelyUser
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createGuidely as createCore, type ChecklistProgressState, type GuidelyClient, type GuidelyOptions, type GuidelyUser, type PublishedGuide } from \"@guidelytech/sdk-core\";\nimport { getContext, setContext } from \"svelte\";\nimport { derived, get, readable, writable, type Readable } from \"svelte/store\";\n\nexport type { GuidelyClient, GuidelyOptions, GuidelyEvents, GuidelyUser, ChecklistProgressState, PublishedGuide } from \"@guidelytech/sdk-core\";\n\n/** The current client (null on the server and before `createGuidely`). */\nexport const guidely = writable<GuidelyClient | null>(null);\n\n/**\n * Creates the client and stores it in the `guidely` store. Browser-only: throws a helpful error\n * when called during SSR (call it from `onMount` or use `@guidelytech/sveltekit`'s `initGuidely`).\n */\nexport function createGuidely(options: GuidelyOptions): GuidelyClient {\n  if (typeof window === \"undefined\") throw new Error(\"[Guidely] createGuidely() can only run in the browser. Call it inside onMount(), or use initGuidely() from @guidelytech/sveltekit.\");\n  const existing = get(guidely);\n  if (existing && !existing.getState().destroyed && existing.options.projectId === options.projectId) return existing;\n  existing?.destroy();\n  const client = createCore(options);\n  guidely.set(client);\n  if (pendingUser !== undefined) applyUser(client, pendingUser);\n  pendingUser = undefined;\n  return client;\n}\n\nconst appliedUser = new WeakMap<GuidelyClient, string | null>();\nlet pendingUser: GuidelyUser | null | undefined;\n\n/**\n * Keeps the Guidely user in step with your app's signed-in user. Idempotent: call it whenever your\n * user data may have changed (a `$effect` / `$:` on layout data). A user identifies (again only when\n * id, traits or account change); `null` resets a previously identified user, including one restored\n * from storage; `undefined` means \"not known yet\" and changes nothing. No-op on the server; called\n * before `createGuidely`, it is applied when the client is created.\n */\nexport function syncGuidelyUser(user: GuidelyUser | null | undefined): void {\n  if (typeof window === \"undefined\") return;\n  const client = get(guidely);\n  if (client) applyUser(client, user);\n  else pendingUser = user;\n}\n\nfunction applyUser(client: GuidelyClient, user: GuidelyUser | null | undefined): void {\n  if (user === undefined) return;\n  const key = user ? JSON.stringify([String(user.id), user.traits ?? null, user.account ?? null]) : null;\n  if (appliedUser.has(client) && appliedUser.get(client) === key) return;\n  appliedUser.set(client, key);\n  if (user) void client.identify(user.id, user.traits, user.account);\n  else if (client.getState().user?.id) client.reset();\n}\n\n/** Destroys the current client and clears the store. */\nexport function destroyGuidely(): void {\n  get(guidely)?.destroy();\n  guidely.set(null);\n}\n\nconst CONTEXT_KEY = Symbol.for(\"guidely\");\n\nexport function setGuidelyContext(client: GuidelyClient | null): void {\n  setContext(CONTEXT_KEY, client);\n}\n\nexport function getGuidelyContext(): GuidelyClient | null {\n  return (getContext(CONTEXT_KEY) as GuidelyClient | null | undefined) ?? get(guidely);\n}\n\nfunction fromClient<T>(initial: T, compute: (client: GuidelyClient) => T, events: Array<Parameters<GuidelyClient[\"on\"]>[0]>): Readable<T> {\n  return readable<T>(initial, (set) => {\n    let offs: Array<() => void> = [];\n    const unsub = guidely.subscribe((client) => {\n      offs.forEach((off) => off());\n      offs = [];\n      if (!client) return set(initial);\n      const update = () => set(compute(client));\n      update();\n      offs = events.map((e) => client.on(e, update as never));\n    });\n    return () => {\n      offs.forEach((off) => off());\n      unsub();\n    };\n  });\n}\n\n/** True once the configuration has loaded. */\nexport const guidelyReady: Readable<boolean> = fromClient(false, (c) => c.getState().ready, [\"ready\"]);\n\n/** The guide currently showing (flows, modals, surveys), or null. */\nexport const activeGuide: Readable<PublishedGuide | null> = fromClient<PublishedGuide | null>(null, (c) => c.getActiveGuide(), [\"ready\", \"guide:start\", \"guide:complete\", \"guide:dismiss\", \"guide:skip\", \"identify\"]);\n\n/** Live checklist progress for a checklist guide (by id or key). */\nexport function checklistProgress(idOrKey: string): Readable<ChecklistProgressState> {\n  return fromClient<ChecklistProgressState>({ completedTaskIds: [], completedAt: null, dismissedAt: null }, (c) => c.getChecklistProgress(idOrKey), [\"ready\", \"identify\", \"checklist:task\", \"checklist:complete\"]);\n}\n\n/** Is the given guide completed for the current user? */\nexport function guideCompleted(idOrKey: string): Readable<boolean> {\n  return derived(fromClient<boolean>(false, (c) => c.isGuideCompleted(idOrKey), [\"ready\", \"identify\", \"guide:complete\"]), (v) => v);\n}\n\n/** `use:guideTrigger={\"guide-key\"}` — clicking the element starts the guide. */\nexport function guideTrigger(node: HTMLElement, key: string): { update(key: string): void; destroy(): void } {\n  let current = key;\n  const onClick = (e: Event) => {\n    e.preventDefault();\n    get(guidely)?.startGuide(current);\n  };\n  node.addEventListener(\"click\", onClick);\n  node.setAttribute(\"data-guidely-trigger\", current);\n  return {\n    update(next: string) {\n      current = next;\n      node.setAttribute(\"data-guidely-trigger\", next);\n    },\n    destroy() {\n      node.removeEventListener(\"click\", onClick);\n    },\n  };\n}\n\n/** `use:guidelyTarget={\"id\"}` — marks an element as a guide target (`data-tour`). No runtime behaviour. */\nexport function guidelyTarget(node: HTMLElement, id?: string): { update(id?: string): void; destroy(): void } {\n  const apply = (v?: string) => {\n    if (v) node.setAttribute(\"data-tour\", v);\n  };\n  apply(id);\n  return { update: apply, destroy() {} };\n}\n"],"mappings":"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","names":["createCore"]}

package/dist/index.d.cts

@@ -0,0 +1,44 @@
+import * as svelte_store from 'svelte/store';
+import { Readable } from 'svelte/store';
+import { PublishedGuide, ChecklistProgressState, GuidelyOptions, GuidelyClient, GuidelyUser } from '@guidelytech/sdk-core';
+export { ChecklistProgressState, GuidelyClient, GuidelyEvents, GuidelyOptions, GuidelyUser, PublishedGuide } from '@guidelytech/sdk-core';
+
+/** The current client (null on the server and before `createGuidely`). */
+declare const guidely: svelte_store.Writable<GuidelyClient | null>;
+/**
+ * Creates the client and stores it in the `guidely` store. Browser-only: throws a helpful error
+ * when called during SSR (call it from `onMount` or use `@guidelytech/sveltekit`'s `initGuidely`).
+ */
+declare function createGuidely(options: GuidelyOptions): GuidelyClient;
+/**
+ * Keeps the Guidely user in step with your app's signed-in user. Idempotent: call it whenever your
+ * user data may have changed (a `$effect` / `$:` on layout data). A user identifies (again only when
+ * id, traits or account change); `null` resets a previously identified user, including one restored
+ * from storage; `undefined` means "not known yet" and changes nothing. No-op on the server; called
+ * before `createGuidely`, it is applied when the client is created.
+ */
+declare function syncGuidelyUser(user: GuidelyUser | null | undefined): void;
+/** Destroys the current client and clears the store. */
+declare function destroyGuidely(): void;
+declare function setGuidelyContext(client: GuidelyClient | null): void;
+declare function getGuidelyContext(): GuidelyClient | null;
+/** True once the configuration has loaded. */
+declare const guidelyReady: Readable<boolean>;
+/** The guide currently showing (flows, modals, surveys), or null. */
+declare const activeGuide: Readable<PublishedGuide | null>;
+/** Live checklist progress for a checklist guide (by id or key). */
+declare function checklistProgress(idOrKey: string): Readable<ChecklistProgressState>;
+/** Is the given guide completed for the current user? */
+declare function guideCompleted(idOrKey: string): Readable<boolean>;
+/** `use:guideTrigger={"guide-key"}` — clicking the element starts the guide. */
+declare function guideTrigger(node: HTMLElement, key: string): {
+    update(key: string): void;
+    destroy(): void;
+};
+/** `use:guidelyTarget={"id"}` — marks an element as a guide target (`data-tour`). No runtime behaviour. */
+declare function guidelyTarget(node: HTMLElement, id?: string): {
+    update(id?: string): void;
+    destroy(): void;
+};
+
+export { activeGuide, checklistProgress, createGuidely, destroyGuidely, getGuidelyContext, guideCompleted, guideTrigger, guidely, guidelyReady, guidelyTarget, setGuidelyContext, syncGuidelyUser };

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import * as svelte_store from 'svelte/store';
+import { Readable } from 'svelte/store';
+import { PublishedGuide, ChecklistProgressState, GuidelyOptions, GuidelyClient, GuidelyUser } from '@guidelytech/sdk-core';
+export { ChecklistProgressState, GuidelyClient, GuidelyEvents, GuidelyOptions, GuidelyUser, PublishedGuide } from '@guidelytech/sdk-core';
+
+/** The current client (null on the server and before `createGuidely`). */
+declare const guidely: svelte_store.Writable<GuidelyClient | null>;
+/**
+ * Creates the client and stores it in the `guidely` store. Browser-only: throws a helpful error
+ * when called during SSR (call it from `onMount` or use `@guidelytech/sveltekit`'s `initGuidely`).
+ */
+declare function createGuidely(options: GuidelyOptions): GuidelyClient;
+/**
+ * Keeps the Guidely user in step with your app's signed-in user. Idempotent: call it whenever your
+ * user data may have changed (a `$effect` / `$:` on layout data). A user identifies (again only when
+ * id, traits or account change); `null` resets a previously identified user, including one restored
+ * from storage; `undefined` means "not known yet" and changes nothing. No-op on the server; called
+ * before `createGuidely`, it is applied when the client is created.
+ */
+declare function syncGuidelyUser(user: GuidelyUser | null | undefined): void;
+/** Destroys the current client and clears the store. */
+declare function destroyGuidely(): void;
+declare function setGuidelyContext(client: GuidelyClient | null): void;
+declare function getGuidelyContext(): GuidelyClient | null;
+/** True once the configuration has loaded. */
+declare const guidelyReady: Readable<boolean>;
+/** The guide currently showing (flows, modals, surveys), or null. */
+declare const activeGuide: Readable<PublishedGuide | null>;
+/** Live checklist progress for a checklist guide (by id or key). */
+declare function checklistProgress(idOrKey: string): Readable<ChecklistProgressState>;
+/** Is the given guide completed for the current user? */
+declare function guideCompleted(idOrKey: string): Readable<boolean>;
+/** `use:guideTrigger={"guide-key"}` — clicking the element starts the guide. */
+declare function guideTrigger(node: HTMLElement, key: string): {
+    update(key: string): void;
+    destroy(): void;
+};
+/** `use:guidelyTarget={"id"}` — marks an element as a guide target (`data-tour`). No runtime behaviour. */
+declare function guidelyTarget(node: HTMLElement, id?: string): {
+    update(id?: string): void;
+    destroy(): void;
+};
+
+export { activeGuide, checklistProgress, createGuidely, destroyGuidely, getGuidelyContext, guideCompleted, guideTrigger, guidely, guidelyReady, guidelyTarget, setGuidelyContext, syncGuidelyUser };

package/dist/index.js

@@ -0,0 +1,109 @@
+// src/index.ts
+import { createGuidely as createCore } from "@guidelytech/sdk-core";
+import { getContext, setContext } from "svelte";
+import { derived, get, readable, writable } from "svelte/store";
+var guidely = writable(null);
+function createGuidely(options) {
+  if (typeof window === "undefined") throw new Error("[Guidely] createGuidely() can only run in the browser. Call it inside onMount(), or use initGuidely() from @guidelytech/sveltekit.");
+  const existing = get(guidely);
+  if (existing && !existing.getState().destroyed && existing.options.projectId === options.projectId) return existing;
+  existing?.destroy();
+  const client = createCore(options);
+  guidely.set(client);
+  if (pendingUser !== void 0) applyUser(client, pendingUser);
+  pendingUser = void 0;
+  return client;
+}
+var appliedUser = /* @__PURE__ */ new WeakMap();
+var pendingUser;
+function syncGuidelyUser(user) {
+  if (typeof window === "undefined") return;
+  const client = get(guidely);
+  if (client) applyUser(client, user);
+  else pendingUser = user;
+}
+function applyUser(client, user) {
+  if (user === void 0) return;
+  const key = user ? JSON.stringify([String(user.id), user.traits ?? null, user.account ?? null]) : null;
+  if (appliedUser.has(client) && appliedUser.get(client) === key) return;
+  appliedUser.set(client, key);
+  if (user) void client.identify(user.id, user.traits, user.account);
+  else if (client.getState().user?.id) client.reset();
+}
+function destroyGuidely() {
+  get(guidely)?.destroy();
+  guidely.set(null);
+}
+var CONTEXT_KEY = /* @__PURE__ */ Symbol.for("guidely");
+function setGuidelyContext(client) {
+  setContext(CONTEXT_KEY, client);
+}
+function getGuidelyContext() {
+  return getContext(CONTEXT_KEY) ?? get(guidely);
+}
+function fromClient(initial, compute, events) {
+  return readable(initial, (set) => {
+    let offs = [];
+    const unsub = guidely.subscribe((client) => {
+      offs.forEach((off) => off());
+      offs = [];
+      if (!client) return set(initial);
+      const update = () => set(compute(client));
+      update();
+      offs = events.map((e) => client.on(e, update));
+    });
+    return () => {
+      offs.forEach((off) => off());
+      unsub();
+    };
+  });
+}
+var guidelyReady = fromClient(false, (c) => c.getState().ready, ["ready"]);
+var activeGuide = fromClient(null, (c) => c.getActiveGuide(), ["ready", "guide:start", "guide:complete", "guide:dismiss", "guide:skip", "identify"]);
+function checklistProgress(idOrKey) {
+  return fromClient({ completedTaskIds: [], completedAt: null, dismissedAt: null }, (c) => c.getChecklistProgress(idOrKey), ["ready", "identify", "checklist:task", "checklist:complete"]);
+}
+function guideCompleted(idOrKey) {
+  return derived(fromClient(false, (c) => c.isGuideCompleted(idOrKey), ["ready", "identify", "guide:complete"]), (v) => v);
+}
+function guideTrigger(node, key) {
+  let current = key;
+  const onClick = (e) => {
+    e.preventDefault();
+    get(guidely)?.startGuide(current);
+  };
+  node.addEventListener("click", onClick);
+  node.setAttribute("data-guidely-trigger", current);
+  return {
+    update(next) {
+      current = next;
+      node.setAttribute("data-guidely-trigger", next);
+    },
+    destroy() {
+      node.removeEventListener("click", onClick);
+    }
+  };
+}
+function guidelyTarget(node, id) {
+  const apply = (v) => {
+    if (v) node.setAttribute("data-tour", v);
+  };
+  apply(id);
+  return { update: apply, destroy() {
+  } };
+}
+export {
+  activeGuide,
+  checklistProgress,
+  createGuidely,
+  destroyGuidely,
+  getGuidelyContext,
+  guideCompleted,
+  guideTrigger,
+  guidely,
+  guidelyReady,
+  guidelyTarget,
+  setGuidelyContext,
+  syncGuidelyUser
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createGuidely as createCore, type ChecklistProgressState, type GuidelyClient, type GuidelyOptions, type GuidelyUser, type PublishedGuide } from \"@guidelytech/sdk-core\";\nimport { getContext, setContext } from \"svelte\";\nimport { derived, get, readable, writable, type Readable } from \"svelte/store\";\n\nexport type { GuidelyClient, GuidelyOptions, GuidelyEvents, GuidelyUser, ChecklistProgressState, PublishedGuide } from \"@guidelytech/sdk-core\";\n\n/** The current client (null on the server and before `createGuidely`). */\nexport const guidely = writable<GuidelyClient | null>(null);\n\n/**\n * Creates the client and stores it in the `guidely` store. Browser-only: throws a helpful error\n * when called during SSR (call it from `onMount` or use `@guidelytech/sveltekit`'s `initGuidely`).\n */\nexport function createGuidely(options: GuidelyOptions): GuidelyClient {\n  if (typeof window === \"undefined\") throw new Error(\"[Guidely] createGuidely() can only run in the browser. Call it inside onMount(), or use initGuidely() from @guidelytech/sveltekit.\");\n  const existing = get(guidely);\n  if (existing && !existing.getState().destroyed && existing.options.projectId === options.projectId) return existing;\n  existing?.destroy();\n  const client = createCore(options);\n  guidely.set(client);\n  if (pendingUser !== undefined) applyUser(client, pendingUser);\n  pendingUser = undefined;\n  return client;\n}\n\nconst appliedUser = new WeakMap<GuidelyClient, string | null>();\nlet pendingUser: GuidelyUser | null | undefined;\n\n/**\n * Keeps the Guidely user in step with your app's signed-in user. Idempotent: call it whenever your\n * user data may have changed (a `$effect` / `$:` on layout data). A user identifies (again only when\n * id, traits or account change); `null` resets a previously identified user, including one restored\n * from storage; `undefined` means \"not known yet\" and changes nothing. No-op on the server; called\n * before `createGuidely`, it is applied when the client is created.\n */\nexport function syncGuidelyUser(user: GuidelyUser | null | undefined): void {\n  if (typeof window === \"undefined\") return;\n  const client = get(guidely);\n  if (client) applyUser(client, user);\n  else pendingUser = user;\n}\n\nfunction applyUser(client: GuidelyClient, user: GuidelyUser | null | undefined): void {\n  if (user === undefined) return;\n  const key = user ? JSON.stringify([String(user.id), user.traits ?? null, user.account ?? null]) : null;\n  if (appliedUser.has(client) && appliedUser.get(client) === key) return;\n  appliedUser.set(client, key);\n  if (user) void client.identify(user.id, user.traits, user.account);\n  else if (client.getState().user?.id) client.reset();\n}\n\n/** Destroys the current client and clears the store. */\nexport function destroyGuidely(): void {\n  get(guidely)?.destroy();\n  guidely.set(null);\n}\n\nconst CONTEXT_KEY = Symbol.for(\"guidely\");\n\nexport function setGuidelyContext(client: GuidelyClient | null): void {\n  setContext(CONTEXT_KEY, client);\n}\n\nexport function getGuidelyContext(): GuidelyClient | null {\n  return (getContext(CONTEXT_KEY) as GuidelyClient | null | undefined) ?? get(guidely);\n}\n\nfunction fromClient<T>(initial: T, compute: (client: GuidelyClient) => T, events: Array<Parameters<GuidelyClient[\"on\"]>[0]>): Readable<T> {\n  return readable<T>(initial, (set) => {\n    let offs: Array<() => void> = [];\n    const unsub = guidely.subscribe((client) => {\n      offs.forEach((off) => off());\n      offs = [];\n      if (!client) return set(initial);\n      const update = () => set(compute(client));\n      update();\n      offs = events.map((e) => client.on(e, update as never));\n    });\n    return () => {\n      offs.forEach((off) => off());\n      unsub();\n    };\n  });\n}\n\n/** True once the configuration has loaded. */\nexport const guidelyReady: Readable<boolean> = fromClient(false, (c) => c.getState().ready, [\"ready\"]);\n\n/** The guide currently showing (flows, modals, surveys), or null. */\nexport const activeGuide: Readable<PublishedGuide | null> = fromClient<PublishedGuide | null>(null, (c) => c.getActiveGuide(), [\"ready\", \"guide:start\", \"guide:complete\", \"guide:dismiss\", \"guide:skip\", \"identify\"]);\n\n/** Live checklist progress for a checklist guide (by id or key). */\nexport function checklistProgress(idOrKey: string): Readable<ChecklistProgressState> {\n  return fromClient<ChecklistProgressState>({ completedTaskIds: [], completedAt: null, dismissedAt: null }, (c) => c.getChecklistProgress(idOrKey), [\"ready\", \"identify\", \"checklist:task\", \"checklist:complete\"]);\n}\n\n/** Is the given guide completed for the current user? */\nexport function guideCompleted(idOrKey: string): Readable<boolean> {\n  return derived(fromClient<boolean>(false, (c) => c.isGuideCompleted(idOrKey), [\"ready\", \"identify\", \"guide:complete\"]), (v) => v);\n}\n\n/** `use:guideTrigger={\"guide-key\"}` — clicking the element starts the guide. */\nexport function guideTrigger(node: HTMLElement, key: string): { update(key: string): void; destroy(): void } {\n  let current = key;\n  const onClick = (e: Event) => {\n    e.preventDefault();\n    get(guidely)?.startGuide(current);\n  };\n  node.addEventListener(\"click\", onClick);\n  node.setAttribute(\"data-guidely-trigger\", current);\n  return {\n    update(next: string) {\n      current = next;\n      node.setAttribute(\"data-guidely-trigger\", next);\n    },\n    destroy() {\n      node.removeEventListener(\"click\", onClick);\n    },\n  };\n}\n\n/** `use:guidelyTarget={\"id\"}` — marks an element as a guide target (`data-tour`). No runtime behaviour. */\nexport function guidelyTarget(node: HTMLElement, id?: string): { update(id?: string): void; destroy(): void } {\n  const apply = (v?: string) => {\n    if (v) node.setAttribute(\"data-tour\", v);\n  };\n  apply(id);\n  return { update: apply, destroy() {} };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@guidelytech/svelte",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Svelte stores, actions and client for Guidely",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@guidelytech/sdk-core": "0.2.0",
+    "@guidelytech/shared": "0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7",
+    "happy-dom": "^17.6.3",
+    "eslint": "^9.39.5",
+    "@eslint/js": "^9.39.5",
+    "typescript-eslint": "^8.46.0",
+    "svelte": "^5.57.2"
+  },
+  "peerDependencies": {
+    "svelte": ">=4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/parmarg/Guidely.git",
+    "directory": "packages/svelte"
+  },
+  "homepage": "https://github.com/parmarg/Guidely/tree/main/packages/svelte#readme",
+  "bugs": {
+    "url": "https://github.com/parmarg/Guidely/issues"
+  },
+  "keywords": [
+    "guidely",
+    "product-adoption",
+    "onboarding",
+    "product-tour",
+    "in-app-guidance",
+    "svelte"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "clean": "rm -rf dist"
+  }
 }