@picked/svelte 0.0.51-next.1 → 0.0.51-next.11

package/dist/hooks/action.d.ts

@@ -1,2 +1,25 @@
-export declare function getAction(actionName: string): import('effector').Store<(<T = void>(params?: T) => void) | undefined>;
-export declare function getActionResult(actionName: string): import('effector').StoreWritable<void | undefined>;
+import { Action } from '@picked/client';
+import { Store } from 'effector';
+/**
+ * Returns the reactive evokable action store for the given action name.
+ *
+ * @param {string} actionName - The registered action name.
+ * @returns {Store<() => ReturnType<Action>>} A store containing the callable action function or undefined.
+ * @example
+ * ```ts
+ * const actionStore = getAction('logEvent')
+ * ```
+ */
+export declare function getAction(actionName: string): Store<() => ReturnType<Action>>;
+/**
+ * Returns a reactive store holding the latest result of invoking the named action.
+ * Re-evaluates automatically when the underlying action store updates.
+ *
+ * @param {string} actionName - The registered action name.
+ * @returns {Store<string | string[] | boolean | void | undefined>} A store containing the latest action return value.
+ * @example
+ * ```ts
+ * const result = getActionResult('isLoggedIn')
+ * ```
+ */
+export declare function getActionResult(actionName: string): import('effector').StoreWritable<string | boolean | void | string[] | undefined>;

package/dist/hooks/action.js

@@ -1 +1 @@
-import{getPicked as e}from"./client.js";import{attach as t,createEffect as n,createEvent as r,createStore as i,sample as a}from"effector";function o(t){return e().actions.getEvokableAction(t)}function s(e){let s=o(e),c=i(void 0,{skipVoid:!1}),l=r(),u=t({source:s,mapParams:(e,t)=>t,effect:n(async e=>{if(e)return e()})});return a({clock:l,target:u}),a({clock:u.doneData,target:c}),l(),c}export{o as getAction,s as getActionResult};
+import{getPicked as e}from"./client.js";import{attach as t,createEffect as n,createEvent as r,createStore as i,sample as a}from"effector";import"@picked/client";function o(t){return e().actions.getEvokableAction(t)}function s(e){let s=o(e),c=i(void 0,{skipVoid:!1}),l=r(),u=t({source:s,mapParams:(e,t)=>t,effect:n(async e=>{if(e)return await e()})});return a({clock:l,target:u}),a({clock:u.doneData,target:c}),l(),a({clock:s,target:l}),c}export{o as getAction,s as getActionResult};

package/dist/hooks/field.d.ts

@@ -1,7 +1,8 @@
 import { Field, FieldValue } from '@picked/client';
 import { Store } from 'effector';
-export interface GetFieldResponse {
+interface GetFieldResponse {
     value: Store<FieldValue>;
     field: Store<Field | null>;
 }
-export declare function getField(id: string): GetFieldResponse;
+export declare function getField(key: string): GetFieldResponse;
+export {};

package/dist/hooks/field.js

@@ -1 +1 @@
-import{getPicked as e}from"./client.js";function t(t){let n=e();return{field:n.fields.getById(t),value:n.responses.getByFieldId(t)}}export{t as getField};
+import{getPicked as e}from"./client.js";function t(t){let n=e();return{field:n.fields.getByKey(t),value:n.responses.getByFieldKey(t)}}export{t as getField};

package/dist/hooks/index.d.ts

@@ -1,3 +1,4 @@
+/** @file Public re-exports for Svelte hook utilities. */
 export { getPicked, getExperience } from './client';
 export { getPredicate, getPredicateResult } from './predicate';
 export { getFeature, getFeatureResult } from './feature';

package/dist/hooks/step.d.ts

@@ -3,11 +3,22 @@ import { ExperienceStep } from '@picked/client';
 import { FormInstance, FormField } from '../form/create-form.svelte';
 export interface StepContext extends FormInstance {
     step: Store<ExperienceStep>;
-    /** Directly accessible fields with current response values — usable without a form */
+    /** Directly accessible fields with current response values — usable without a form. */
     fields: Store<FormField[]>;
     isActive: Store<boolean>;
-    /** @deprecated Use `isActive` instead */
+    /** @deprecated Use `isActive` instead. */
     isActiveStep: Store<boolean>;
 }
-export declare function setStepContext(stepId: string): StepContext;
+/**
+ * Creates and sets step context in the Svelte context tree.
+ *
+ * @param stepKey - The step key.
+ * @example setStepContext('step-1')
+ */
+export declare function setStepContext(stepKey: string): StepContext;
+/**
+ * Retrieves the step context from the Svelte context tree.
+ *
+ * @example getStep()
+ */
 export declare function getStep(): StepContext;

package/dist/hooks/step.js

@@ -1 +1 @@
-import{STEP_CONTEXT_KEY as e}from"../context.js";import{getExperience as t}from"./client.js";import{getStepRouter as n}from"../router/context.js";import{getContext as r,setContext as i}from"svelte";import{createForm as a}from"../form/create-form.svelte";function o(e){let n=t().treeStore.map(t=>{let n=t.steps.find(t=>t.id===e);if(!n)throw Error(`Step with id "${e}" not found in the experience tree.`);return n});return{stepStore:n,form:a(e,n.map(e=>e.label),n.map(e=>e.fieldIds))}}function s(t){let{activeStep:r}=n(),a=r.map(e=>e?.id===t),{stepStore:s,form:c}=o(t);return i(e,{step:s,isActive:a,isActiveStep:a,...c})}function c(){return r(e)}export{c as getStep,s as setStepContext};
+import{STEP_CONTEXT_KEY as e}from"../context.js";import{getPicked as t}from"./client.js";import{getStepRouter as n}from"../router/context.js";import{getContext as r,setContext as i}from"svelte";import{createForm as a}from"../form/create-form.svelte";function o(r){let o=t(),{activeStep:s}=n(),c=s.map(e=>e?.key===r),l=o.steps.listStore.map(e=>e.find(e=>e.key===r)??{id:r,key:r,name:``,fieldIds:[]});return i(e,{step:l,isActive:c,isActiveStep:c,...a(r,l.map(e=>e.name),l.map(e=>e.fieldIds))})}function s(){return r(e)}export{s as getStep,o as setStepContext};

package/dist/plugins/devtools/components/ExperienceInstanceListItem.svelte

@@ -1,9 +1,14 @@
 <script lang="ts">
+  /** @file List item row displaying an experience instance's current state in the devtools panel. */
   import type { ExperienceInstance } from '@picked/client'
   import { Button } from '../ui'
+  import { getPicked } from '../../../hooks'
 
   export let experienceInstance: ExperienceInstance
 
+  const client = getPicked()
+  const experienceStore = client.experiences.getById(experienceInstance.experienceId)
+
   const currentNode = experienceInstance.currentNodeStore
   const currentStep = experienceInstance.currentStepStore
   const nextStepNodes = experienceInstance.nextReachableStepNodesStore
@@ -12,15 +17,20 @@
   const isOpen = experienceInstance.isOpenStore
 
   $: totalNextStepNodes = $nextStepNodes.length
+  $: experienceName = $experienceStore?.name ?? experienceInstance.experienceId
+  $: currentNodeDisplay = $currentNode
+    ? (('stepKey' in $currentNode && $currentNode.stepKey) || $currentNode.id)
+    : ''
+  $: currentStepDisplay = $currentStep?.name ?? ''
 </script>
 
 <tr>
-  <td>{experienceInstance.experienceId}</td>
+  <td>{experienceName}</td>
   <td><Button variant="ghost" size="small" onclick={() => experienceInstance.toggleOpen()}>{$isOpen}</Button></td>
-  <td>{$currentNode?.id || ''}</td>
+  <td>{currentNodeDisplay}</td>
   <td>{$currentNode?.type || ''}</td>
-  <td>{$currentStep?.id || ''}</td>
-  <td>{$currentStep?.label || ''}</td>
+  <td>{currentStepDisplay}</td>
+  <td>{$currentStep?.name || ''}</td>
   <td>{totalNextStepNodes}</td>
   <td>{$stepsToOrigin[0]} - {$stepsToOrigin[1]}</td>
   <td>{$stepsToLeaf[0]} - {$stepsToLeaf[1]}</td>

package/dist/plugins/devtools/components/ExperienceInstancesTable.svelte

@@ -6,7 +6,7 @@
   export let experienceInstances: ExperienceInstance[]
 
   const columns = [
-    { key: 'experience', header: 'Experience' },
+    { key: 'experience', header: 'Name' },
     { key: 'isOpen', header: 'Is Open' },
     { key: 'currentNodeId', header: 'Current node ID' },
     { key: 'currentNodeType', header: 'Current node Type' },

package/dist/plugins/devtools/components/Tabs.svelte

@@ -1,10 +1,11 @@
 <script lang="ts">
+  /** @file Accessible tab container that renders dynamic Svelte components per tab. */
   import type { Component } from 'svelte'
 
   interface Tab {
     id: string
     label: string
-    component: Component<any>
+    component: Component<Record<string, unknown>>
     props?: Record<string, unknown>
   }
 
@@ -13,10 +14,28 @@
 
   let activeTab = initialTab
 
+  /**
+   * Sets the active tab to the given index.
+   *
+   * @param {number} index - The zero-based tab index to activate.
+   * @example
+   * ```typescript
+   * activateTab(2) // switches to the third tab
+   * ```
+   */
   function activateTab(index: number) {
     activeTab = index
   }
 
+  /**
+   * Handles arrow-key, Home, and End navigation within the tab list.
+   *
+   * @param {KeyboardEvent} event - The keyboard event from the tab list.
+   * @example
+   * ```typescript
+   * handleKeydown(new KeyboardEvent('keydown', { key: 'ArrowRight' }))
+   * ```
+   */
   function handleKeydown(event: KeyboardEvent) {
     const tabCount = tabs.length
     let newIndex = activeTab
@@ -83,6 +102,7 @@
     display: flex;
     flex-direction: column;
     flex: 1;
+    min-height: 0;
   }
 
   .tab-list {
@@ -124,7 +144,7 @@
   .tab-panel {
     flex: 1 1 auto;
     display: grid;
-    align-content: start;
+    min-height: 0;
     overflow: auto;
   }
 

package/dist/plugins/devtools/plugin.d.ts

@@ -11,5 +11,14 @@ export interface SvelteDevtoolsPluginOptions {
 /**
  * Registers the devtools experience for on-demand loading via the Chrome DevTools extension.
  * The devtools component is lazily loaded — it is never included in the initial bundle.
+ *
+ * @param options - Optional configuration for the devtools plugin.
+ * @returns An array of plugins to register with the Picked client.
+ * @example
+ * ```typescript
+ * const client = new Picked({
+ *   plugins: [...svelteDevtoolsPlugin({ enabled: true })],
+ * })
+ * ```
  */
 export declare const svelteDevtoolsPlugin: (options?: SvelteDevtoolsPluginOptions) => Plugin[];

package/dist/plugins/devtools/plugin.js

@@ -1 +1 @@
-import{adaptSvelteComponent as e}from"../../component.js";import{__vitePreload as t}from"../../_virtual/_vite/preload-helper.js";import{lazyComponent as n}from"@picked/client";import{createExperience as r,createExperiencePlugin as i}from"@picked/client/plugins/create-experience";var a=a=>{let o=r({id:`devtools`,name:`Picked Devtools`,condition:!1,initializeOpen:!1,targets:[{selector:`body`,placement:`append`}],component:e(n(()=>t(()=>import(`./DevToolsExperience.svelte`),[])))});return o.addStep({label:`Tools`}),[{name:`svelte-devtools`,setup:e=>{a?.enabled&&e.eventBus.watch(t=>{t.type===`ready`&&e.experiences.launch({id:o.id,options:{bypassCondition:!0}})})}},i({experiences:[o]})]};export{a as svelteDevtoolsPlugin};
+import{adaptSvelteComponent as e}from"../../component.js";import{__vitePreload as t}from"../../_virtual/_vite/preload-helper.js";import{lazyComponent as n}from"@picked/client";import{createExperience as r,createExperiencePlugin as i}from"@picked/client/plugins/create-experience";var a=a=>{let o=r({id:`devtools`,key:`devtools`,name:`Picked Devtools`,condition:!1,initializeOpen:!1,targets:[{selector:`body`,placement:`append`}],component:e(n(()=>t(()=>import(`./DevToolsExperience.svelte`),[])))});return o.addStep({name:`Tools`}),[{name:`svelte-devtools`,setup:e=>{a?.enabled&&e.eventBus.watch(t=>{t.type===`ready`&&e.experiences.launch({key:o.key,options:{bypassCondition:!0}})})}},i({experiences:[o]})]};export{a as svelteDevtoolsPlugin};

package/dist/plugins/devtools/screens/events/EventListItem.svelte

@@ -1,11 +1,34 @@
 <script lang="ts">
+  /** @file Expandable list item row for displaying an event bus history entry in the devtools events screen. */
   import type { EventBusPayload, EventHistoryEntry } from '@picked/client'
   import { Badge, Card, CodeBlock, Stack, Text } from '../../ui'
+  import { getPicked } from '../../../../hooks'
 
   export let event: EventHistoryEntry
   export let isExpanded: boolean
   export let onToggle: () => void
 
+  const client = getPicked()
+
+  const eventExpId =
+    'experience' in event.payload && event.payload.experience
+      ? event.payload.experience.experienceId
+      : undefined
+  const eventExperienceStore = client.experiences.getById(eventExpId ?? '')
+  $: eventExpName = eventExpId
+    ? ($eventExperienceStore?.name ?? eventExpId)
+    : '-'
+
+  /**
+   * Formats a Date as a 24-hour time string with milliseconds.
+   *
+   * @param {Date} date - The date to format.
+   * @returns {string} The formatted time string.
+   * @example
+   * ```typescript
+   * formatTime(new Date()) // '14:30:05.123'
+   * ```
+   */
   function formatTime(date: Date): string {
     return date.toLocaleTimeString('en-US', {
       hour12: false,
@@ -21,53 +44,111 @@
     value: unknown
   }
 
-  function getPayloadFields(payload: EventBusPayload): PayloadField[] {
+  /**
+   * Extracts experience-related fields from an event payload's experience object.
+   *
+   * @param {unknown} exp - The experience object from the event payload.
+   * @returns {PayloadField[]} Extracted experience fields.
+   * @example
+   * ```typescript
+   * getExperienceFields({ id: 'abc', experienceId: 'quiz' })
+   * // [{ label: 'Experience ID', value: 'abc' }, { label: 'Experience Type', value: 'quiz' }]
+   * ```
+   */
+  function getExperienceFields(exp: unknown): PayloadField[] {
+    if (!exp || typeof exp !== 'object') return []
     const fields: PayloadField[] = []
+    if ('id' in exp && exp.id) fields.push({ label: 'Experience ID', value: exp.id })
+    if ('experienceId' in exp && exp.experienceId)
+      fields.push({ label: 'Experience Type', value: exp.experienceId })
+    return fields
+  }
 
-    fields.push({ label: 'Type', value: payload.type })
+  /**
+   * Extracts step-related fields from an event payload's step object.
+   *
+   * @param {unknown} step - The step object from the event payload.
+   * @returns {PayloadField[]} Extracted step fields.
+   * @example
+   * ```typescript
+   * getStepFields({ id: 's1', name: 'Welcome' })
+   * // [{ label: 'Step ID', value: 's1' }, { label: 'Step Name', value: 'Welcome' }]
+   * ```
+   */
+  function getStepFields(step: unknown): PayloadField[] {
+    if (!step || typeof step !== 'object'){
+      return []
+    } 
 
-    if ('value' in payload && payload.value !== undefined) {
-      fields.push({ label: 'Value', value: payload.value })
+    const fields: PayloadField[] = []
+    if ('key' in step && step.key) { 
+      fields.push({ label: 'Step Key', value: step.key }) 
     }
 
-    if ('experience' in payload && payload.experience) {
-      const exp = payload.experience
-      if (exp && typeof exp === 'object') {
-        if ('id' in exp && exp.id) {
-          fields.push({ label: 'Experience ID', value: exp.id })
-        }
-        if ('experienceId' in exp && exp.experienceId) {
-          fields.push({ label: 'Experience Type', value: exp.experienceId })
-        }
-      }
+    // eslint-disable-next-line sonarjs/deprecation -- backwards-compat fallback for label
+    const stepName = ('name' in step && step.name) || ('label' in step && step.label)
+    if (stepName) { 
+      fields.push({ label: 'Step Name', value: stepName }) 
     }
 
-    if ('step' in payload && payload.step) {
-      const step = payload.step
-      if (step && typeof step === 'object') {
-        if ('id' in step && step.id) {
-          fields.push({ label: 'Step ID', value: step.id })
-        }
-        if ('label' in step && step.label) {
-          fields.push({ label: 'Step Label', value: step.label })
-        }
+    return fields
+  }
+
+  /** Scalar payload keys to extract and their display labels. JSON-serializable values are stringified. */
+  const SCALAR_KEYS: { key: string; label: string; serialize?: boolean }[] = [
+    { key: 'value', label: 'Value' },
+    { key: 'form', label: 'Form', serialize: true },
+    { key: 'feature', label: 'Feature', serialize: true },
+    { key: 'exception', label: 'Exception', serialize: true },
+    { key: 'version', label: 'Version' },
+  ]
+
+  /**
+   * Extracts scalar (non-nested) fields from an event bus payload.
+   *
+   * @param {EventBusPayload} payload - The event bus payload to extract scalar fields from.
+   * @returns {PayloadField[]} Extracted scalar fields.
+   * @example
+   * ```typescript
+   * getScalarFields({ type: 'step', value: 42 })
+   * // [{ label: 'Value', value: 42 }]
+   * ```
+   */
+  function getScalarFields(payload: EventBusPayload): PayloadField[] {
+    const fields: PayloadField[] = []
+    const record = payload as Record<string, unknown>
+
+    for (const { key, label, serialize } of SCALAR_KEYS) {
+      const raw = record[key]
+      if (raw !== undefined) {
+        fields.push({ label, value: serialize ? JSON.stringify(raw) : raw })
       }
     }
 
-    if ('form' in payload && payload.form) {
-      fields.push({ label: 'Form', value: JSON.stringify(payload.form) })
-    }
+    return fields
+  }
 
-    if ('feature' in payload && payload.feature) {
-      fields.push({ label: 'Feature', value: JSON.stringify(payload.feature) })
-    }
+  /**
+   * Builds a flat list of display fields from an event bus payload.
+   *
+   * @param {EventBusPayload} payload - The event bus payload to extract fields from.
+   * @returns {PayloadField[]} All extracted fields.
+   * @example
+   * ```typescript
+   * getPayloadFields({ type: 'session', id: 'sess-1' })
+   * // [{ label: 'Type', value: 'session' }, { label: 'Session ID', value: 'sess-1' }]
+   * ```
+   */
+  function getPayloadFields(payload: EventBusPayload): PayloadField[] {
+    const fields: PayloadField[] = [{ label: 'Type', value: payload.type }]
+    fields.push(...getScalarFields(payload))
 
-    if ('exception' in payload && payload.exception) {
-      fields.push({ label: 'Exception', value: JSON.stringify(payload.exception) })
+    if ('experience' in payload && payload.experience) {
+      fields.push(...getExperienceFields(payload.experience))
     }
 
-    if ('version' in payload && payload.version) {
-      fields.push({ label: 'Version', value: payload.version })
+    if ('step' in payload && payload.step) {
+      fields.push(...getStepFields(payload.step))
     }
 
     if ('id' in payload && payload.id && payload.type === 'session') {
@@ -77,6 +158,17 @@
     return fields
   }
 
+  /**
+   * Formats a field value for display as a string.
+   *
+   * @param {unknown} value - The value to format.
+   * @returns {string} The formatted string representation.
+   * @example
+   * ```typescript
+   * formatValue(42) // '42'
+   * formatValue(null) // 'null'
+   * ```
+   */
   function formatValue(value: unknown): string {
     if (value === null) return 'null'
     if (value === undefined) return 'undefined'
@@ -97,9 +189,7 @@
     <Badge status="info">{event.payload.type}</Badge>
   </td>
   <td>
-    <Text size="small">
-      {'experience' in event.payload && event.payload.experience ? event.payload.experience.experienceId : '-'}
-    </Text>
+    <Text size="small">{eventExpName}</Text>
   </td>
   <td>
     <Text size="caption" color="subdued">
@@ -114,7 +204,7 @@
         <Text size="small" weight="semibold">Event Payload</Text>
         <Card>
           <Stack direction="vertical" gap="small">
-            {#each getPayloadFields(event.payload) as field}
+            {#each getPayloadFields(event.payload) as field (field.label)}
               <Text size="caption" inline>
                 <Text size="caption" weight="semibold" color="subdued" inline>{field.label}:</Text>
                 <CodeBlock code={formatValue(field.value)} inline />

package/dist/plugins/devtools/screens/experiences/ExperienceDetailsScreen.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  /** @file Detail screen for a single experience, showing its config, target selectors, and decision logic. */
   import type { ExperienceStore } from '@picked/client'
   import { getPicked } from '../../../../hooks'
   import { Button, Card, Text, CodeBlock, Stack } from '../../ui'
@@ -11,17 +12,13 @@
 
 <Stack direction="vertical" gap="medium" padding="medium">
   <Stack direction="horizontal" gap="small">
-    <Button variant="primary" size="small" onclick={() => client.launchExperienceById(experience.id)}>
+    <Button variant="primary" size="small" onclick={() => client.experiences.open({ key: experience.key, options: { bypassCondition: true } })}>
       Launch experience
     </Button>
   </Stack>
 
   <Card sectioned>
     <Stack direction="vertical" gap="medium" padding="medium">
-      <div>
-        <Text weight="semibold">Type</Text>
-        <Text>{$config.type}</Text>
-      </div>
 
       <div>
         <Text weight="semibold">Target selectors</Text>

package/dist/plugins/devtools/screens/experiences/ExperienceTreeScreen.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  /** @file D3-based tree visualization of an experience's node graph in the devtools panel. */
   import * as d3 from 'd3'
   import type { ExperienceEdge, ExperienceNode, ExperienceStore } from '@picked/client'
   import { Badge, Button, Spinner, Stack, Text, VisualizationContainer } from '../../ui'
@@ -7,7 +8,9 @@
 
   let svgEl: SVGSVGElement
   let zoom = 1
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- reserved for future node details panel
   let selectedNode = null
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, sonarjs/no-unused-collection -- reserved for future path highlighting
   let highlightedPath: string[][] = []
   let error: string | null = null
   const loading = false
@@ -16,7 +19,6 @@
 
   const tree = experience.treeStore
 
-  $: steps = $tree.steps
   $: nodes = $tree.nodes
   $: edges = $tree.edges
   $: conditions = $tree.conditions
@@ -35,10 +37,30 @@
     _referenceTo?: string
   }
 
+  /**
+   * Type guard that checks if a value is a non-null, non-array object.
+   *
+   * @param val - The value to check.
+   * @example
+   * ```typescript
+   * isRecord({ key: 'value' }) // true
+   * isRecord([1, 2]) // false
+   * ```
+   */
   function isRecord(val: unknown): val is Record<string, unknown> {
     return val !== null && typeof val === 'object' && !Array.isArray(val)
   }
 
+  /**
+   * Recursively formats a JSON Logic rule into a human-readable string.
+   *
+   * @param rule - The JSON Logic rule object to format.
+   * @example
+   * ```typescript
+   * formatLogicRule({ '==': [{ var: 'age' }, 18] }) // 'age = 18'
+   * ```
+   */
+  // eslint-disable-next-line sonarjs/cognitive-complexity -- recursive logic rule formatter handles all operator types
   function formatLogicRule(rule: unknown): string {
     if (rule === null || rule === undefined) return '?'
     if (typeof rule === 'string') return rule
@@ -46,6 +68,7 @@
     if (Array.isArray(rule)) {
       return rule.map(formatLogicRule).join(', ')
     }
+
     if (isRecord(rule)) {
       const keys = Object.keys(rule)
       if (keys.length === 0) return 'Condition'
@@ -69,28 +92,43 @@
       if (op in compOps && Array.isArray(args) && args.length >= 2) {
         return `${formatLogicRule(args[0])} ${compOps[op]} ${formatLogicRule(args[1])}`
       }
+
       if (op === 'and' && Array.isArray(args)) {
         return args.map(formatLogicRule).join(' & ')
       }
+
       if (op === 'or' && Array.isArray(args)) {
         return args.map(formatLogicRule).join(' | ')
       }
+
       if ((op === '!' || op === 'not') && Array.isArray(args)) {
         return `!${formatLogicRule(args[0])}`
       }
+
       if (op === 'in' && Array.isArray(args) && args.length >= 2) {
         return `${formatLogicRule(args[0])} in ${formatLogicRule(args[1])}`
       }
+
       return `${op}(?)`
     }
+
     return '?'
   }
 
+  /**
+   * Renders the experience node graph as an interactive D3 tree visualization.
+   *
+   * @example
+   * ```typescript
+   * renderGraph() // builds and renders the SVG tree
+   * ```
+   */
   function renderGraph() {
     d3.select(svgEl).selectAll('*').remove()
 
-    const stepsMap = new Map(steps.map((s) => [s.id, s]))
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- D3 visualization runs imperatively outside Svelte reactivity
     const conditionsMap = new Map(conditions.map((c) => [c.id, c]))
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- D3 visualization runs imperatively outside Svelte reactivity
     const outgoingEdges = new Map<string, ExperienceEdge[]>()
     edges.forEach((e) => {
       if (!outgoingEdges.has(e.sourceNodeId)) outgoingEdges.set(e.sourceNodeId, [])
@@ -99,17 +137,20 @@
 
     const getNodeLabel = (node: ExperienceNode): string => {
       if (node.type === 'origin') return 'Start'
-      if (node.type === 'step' && node.stepId)
-        return stepsMap.get(node.stepId)?.label ?? 'Unknown Step'
-      if (node.type === 'condition' && node.conditionId) {
-        const condition = conditionsMap.get(node.conditionId)
-        if (condition?.label) return condition.label
-        if (condition?.condition) return formatLogicRule(condition.condition)
+      if (node.type === 'step')
+        return node.name ?? 'Unknown Step'
+      if (node.type === 'condition') {
+        const conditionId = node.conditionId
+        const conditionItem = conditionId ? conditionsMap.get(conditionId) : undefined
+        if (conditionItem?.name) return conditionItem.name
+        if (conditionItem?.logic) return formatLogicRule(conditionItem.logic)
         return 'Condition'
       }
+
       return 'Unknown Node'
     }
 
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- D3 visualization runs imperatively outside Svelte reactivity
     const processedNodes = new Map<string, ProcessedNode>()
     nodes.forEach((n) => {
       processedNodes.set(n.id, {
@@ -141,6 +182,7 @@
       // Use a global visited set so join nodes (multiple incoming branches converging
       // to the same node) only appear once in the tree, with reference nodes on
       // subsequent visits to indicate the convergence point.
+      // eslint-disable-next-line svelte/prefer-svelte-reactivity -- D3 visualization runs imperatively outside Svelte reactivity
       const globalVisited = new Set<string>()
       const convertGraphToTree = (node: ProcessedNode): ProcessedNode => {
         if (globalVisited.has(node.id)) {
@@ -196,6 +238,7 @@
         .append('path')
         .attr('class', 'link')
         .attr('fill', 'none')
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- D3 callback types are untyped
         .attr('stroke', (d: any) => {
           if (d.source.data.type !== 'condition') return '#94a3b8'
           const targetId = d.target.data._isReference
@@ -204,8 +247,8 @@
           const edge = d.source.data._originalEdges.find(
             (e: ExperienceEdge) => e.destinationNodeId === targetId,
           )
-          if (edge?.sourceNodeHandle === 'true') return '#10b981'
-          if (edge?.sourceNodeHandle === 'false') return '#ef4444'
+          if (edge?.sourceHandle === 'true') return '#10b981'
+          if (edge?.sourceHandle === 'false') return '#ef4444'
           return '#94a3b8'
         })
         .attr('stroke-width', 2)
@@ -213,6 +256,7 @@
 
       // Label true/false branches from condition nodes
       g.selectAll('.edge-label')
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- D3 callback types are untyped
         .data(treeRoot.links().filter((d: any) => d.source.data.type === 'condition'))
         .enter()
         .append('text')
@@ -220,8 +264,11 @@
         .attr('text-anchor', 'middle')
         .attr('font-size', '10px')
         .attr('font-weight', 'bold')
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- D3 callback types are untyped
         .attr('x', (d: any) => (d.source.y + d.target.y) / 2)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- D3 callback types are untyped
         .attr('y', (d: any) => (d.source.x + d.target.x) / 2 - 6)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- D3 callback types are untyped
         .attr('fill', (d: any) => {
           const targetId = d.target.data._isReference
             ? d.target.data._referenceTo
@@ -229,10 +276,11 @@
           const edge = d.source.data._originalEdges.find(
             (e: ExperienceEdge) => e.destinationNodeId === targetId,
           )
-          if (edge?.sourceNodeHandle === 'true') return '#10b981'
-          if (edge?.sourceNodeHandle === 'false') return '#ef4444'
+          if (edge?.sourceHandle === 'true') return '#10b981'
+          if (edge?.sourceHandle === 'false') return '#ef4444'
           return '#64748b'
         })
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- D3 callback types are untyped
         .text((d: any) => {
           const targetId = d.target.data._isReference
             ? d.target.data._referenceTo
@@ -240,8 +288,8 @@
           const edge = d.source.data._originalEdges.find(
             (e: ExperienceEdge) => e.destinationNodeId === targetId,
           )
-          if (edge?.sourceNodeHandle === 'true') return 'Yes'
-          if (edge?.sourceNodeHandle === 'false') return 'No'
+          if (edge?.sourceHandle === 'true') return 'Yes'
+          if (edge?.sourceHandle === 'false') return 'No'
           return ''
         })
 
@@ -251,11 +299,14 @@
         .enter()
         .append('g')
         .attr('class', 'node')
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- D3 callback types are untyped
         .attr('transform', (d: any) => `translate(${d.y},${d.x})`)
 
       nodesSelection
         .append('circle')
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- D3 callback types are untyped
         .attr('r', (d: any) => (d.data.type === 'origin' ? 15 : 10))
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- D3 callback types are untyped
         .attr('fill', (d: any) => {
           if (d.data._isReference) return '#38bdf8'
           if (d.data.type === 'origin') return '#00cd90'
@@ -267,10 +318,12 @@
 
       nodesSelection
         .append('text')
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- D3 callback types are untyped
         .attr('dy', (d: any) => (d.children ? -15 : 25))
         .attr('text-anchor', 'middle')
         .attr('font-size', '12px')
         .attr('fill', '#1e293b')
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- D3 callback types are untyped
         .text((d: any) =>
           d.data.name.length > 30 ? `${d.data.name.slice(0, 27)}...` : d.data.name,
         )
@@ -301,11 +354,27 @@
     treeRenderingDone = true
   }
 
+  /**
+   * Zooms the tree visualization in by 20%.
+   *
+   * @example
+   * ```typescript
+   * handleZoomIn() // increases zoom level
+   * ```
+   */
   function handleZoomIn() {
     if (!svgEl || !zoomBehavior) return
     d3.select(svgEl).transition().duration(250).call(zoomBehavior.scaleBy, 1.2)
   }
 
+  /**
+   * Zooms the tree visualization out by 20%.
+   *
+   * @example
+   * ```typescript
+   * handleZoomOut() // decreases zoom level
+   * ```
+   */
   function handleZoomOut() {
     if (!svgEl || !zoomBehavior) return
     d3.select(svgEl)
@@ -314,6 +383,14 @@
       .call(zoomBehavior.scaleBy, 1 / 1.2)
   }
 
+  /**
+   * Resets the tree visualization zoom and position to the default centered view.
+   *
+   * @example
+   * ```typescript
+   * handleReset() // resets zoom to default
+   * ```
+   */
   function handleReset() {
     if (!svgEl || !zoomBehavior) return
     const width = svgEl.clientWidth
@@ -327,6 +404,15 @@
     d3.select(svgEl).transition().duration(750).call(zoomBehavior.transform, initialTransform)
   }
 
+  /**
+   * Closes the node details panel and resets all link/node highlights.
+   *
+   * @example
+   * ```typescript
+   * closeNodeDetails() // resets selection and highlighting
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- reserved for future node details panel
   function closeNodeDetails() {
     selectedNode = null
     if (svgEl) {

package/dist/plugins/devtools/screens/experiences/ExperiencesListScreen.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  /** @file Screen listing all registered experiences as tabs in the devtools panel. */
   import Tabs from '../../components/Tabs.svelte'
   import { getPicked } from '../../../../hooks'
   import ExperienceScreen from './ExperienceScreen.svelte'
@@ -9,7 +10,7 @@
   $: tabs = $experiences.map((experience) => {
     return {
       id: experience.id,
-      label: experience.id,
+      label: experience.name,
       component: ExperienceScreen,
       props: {
         experience,

package/dist/plugins/devtools/screens/history/HistoryEntryListItem.svelte

@@ -1,12 +1,18 @@
 <script lang="ts">
+  /** @file List item row displaying a navigation history entry in the devtools history screen. */
   import type { HistoryEntry } from '@picked/client'
+  import { getPicked } from '../../../../hooks'
 
   export let historyEntry: HistoryEntry
+
+  const client = getPicked()
+  const experienceStore = client.experiences.getById(historyEntry.experienceId)
+  $: experienceName = $experienceStore?.name ?? historyEntry.experienceId
 </script>
 
 <tr>
   <td>{historyEntry.id}</td>
-  <td>{historyEntry.experienceId}</td>
+  <td>{experienceName}</td>
   <td>{historyEntry.node.id}</td>
   <td>{historyEntry.node.type}</td>
   <td>{historyEntry.at}</td>

package/dist/plugins/devtools/screens/responses/ResponseTableRow.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
-  import type { ResponseListItem, PrimitiveFieldValue, Field, FieldValue } from '@picked/client'
+  /** @file Editable table row for a single field response in the devtools responses screen. */
+  import type { ResponseListItem, PrimitiveFieldValue, Field } from '@picked/client'
   import { getPicked } from '../../../../hooks'
   import { Button, Text, CodeBlock, Banner, Stack } from '../../ui'
 
@@ -11,25 +12,47 @@
   let isEditing = false
   let editValue = ''
   let editError = ''
-  let selectedOptions: Set<FieldValue> = new Set()
+  // eslint-disable-next-line svelte/prefer-svelte-reactivity -- Set is reassigned for Svelte reactivity via `selectedOptions = selectedOptions`
+  let selectedOptions: Set<PrimitiveFieldValue> = new Set()
 
   $: hasOptions = Array.isArray(field?.options) && field.options.length > 0
   $: staticOptions = Array.isArray(field?.options) ? field.options : null
   $: currentValue = response?.value ?? null
 
+  /**
+   * Formats a response value for display, handling arrays, objects, and primitives.
+   *
+   * @param value - The response value to format.
+   * @example
+   * ```typescript
+   * formatValue(['a', 'b']) // 'a, b'
+   * formatValue(null) // '-'
+   * ```
+   */
   function formatValue(value: unknown): string {
     if (value === null || value === undefined) {
       return '-'
     }
+
     if (Array.isArray(value) && value.every((item) => typeof item === 'string')) {
       return value.join(', ')
     }
+
     if (typeof value === 'object') {
       return JSON.stringify(value, null, 2)
     }
+
     return String(value)
   }
 
+  /**
+   * Enters edit mode for this field, initializing the edit state from the current value.
+   *
+   * @example
+   * ```typescript
+   * startEdit() // opens the inline editor
+   * ```
+   */
   function startEdit() {
     isEditing = true
     editError = ''
@@ -46,6 +69,14 @@
     }
   }
 
+  /**
+   * Cancels the current edit, discarding changes and resetting edit state.
+   *
+   * @example
+   * ```typescript
+   * cancelEdit() // closes editor without saving
+   * ```
+   */
   function cancelEdit() {
     isEditing = false
     editValue = ''
@@ -53,51 +84,80 @@
     selectedOptions = new Set()
   }
 
-  function toggleOption(optionValue: FieldValue) {
+  /**
+   * Toggles selection of a field option, supporting both single and multi-select modes.
+   *
+   * @param optionValue - The option value to toggle.
+   * @example
+   * ```typescript
+   * toggleOption('red') // selects or deselects the 'red' option
+   * ```
+   */
+  function toggleOption(optionValue: PrimitiveFieldValue) {
     if (field?.multiple) {
       if (selectedOptions.has(optionValue)) {
         selectedOptions.delete(optionValue)
       } else {
         selectedOptions.add(optionValue)
       }
+
       selectedOptions = selectedOptions
     } else {
       selectedOptions = new Set([optionValue])
     }
   }
 
-  function parseValue(input: string): FieldValue {
-    input = input.trim()
+  /**
+   * Parses a string input into a typed value based on the field's type.
+   *
+   * @param input - The raw string input to parse.
+   * @example
+   * ```typescript
+   * parseValue('42') // 42 (when field.type is 'number')
+   * parseValue('true') // true (when field.type is 'boolean')
+   * ```
+   */
+  function parseValue(input: string): unknown {
+    const trimmed = input.trim()
 
-    if (input === '' || input === '-') {
+    if (trimmed === '' || trimmed === '-') {
       return null
     }
 
-    if (input.startsWith('{') || input.startsWith('[')) {
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
       try {
-        return JSON.parse(input)
+        return JSON.parse(trimmed)
       } catch {
         throw new Error('Invalid JSON format')
       }
     }
 
     if (field.type === 'boolean') {
-      if (input === 'true') return true
-      if (input === 'false') return false
+      if (trimmed === 'true') return true
+      if (trimmed === 'false') return false
       throw new Error('Boolean must be "true" or "false"')
     }
 
     if (field.type === 'number') {
-      const num = Number(input)
+      const num = Number(trimmed)
       if (isNaN(num)) {
         throw new Error('Invalid number format')
       }
+
       return num
     }
 
-    return input
+    return trimmed
   }
 
+  /**
+   * Commits the edited value via the client responses API and exits edit mode.
+   *
+   * @example
+   * ```typescript
+   * await saveEdit() // saves the current edit value
+   * ```
+   */
   async function saveEdit() {
     try {
       let newValue: FieldValue
@@ -128,6 +188,14 @@
     }
   }
 
+  /**
+   * Clears the response value for this field via the client responses API.
+   *
+   * @example
+   * ```typescript
+   * handleClear() // removes the response for this field
+   * ```
+   */
   function handleClear() {
     client.responses.clear(field.id)
   }
@@ -135,7 +203,7 @@
 
 <tr>
   <td>
-    <CodeBlock code={field.name} inline />
+    <CodeBlock code={field.key} inline />
   </td>
   <td>
     <Text size="small" weight="semibold">{field.label}</Text>

package/dist/plugins/devtools/screens/responses/ResponsesTable.svelte

@@ -1,8 +1,9 @@
 <script lang="ts">
-  import type { ResponseListItem, Field } from '@picked/client'
+  /** @file Table displaying all field responses with filtering and clear-all functionality in the devtools panel. */
+  import type { ResponseListItem } from '@picked/client'
   import { getPicked } from '../../../../hooks'
-  import ResponseTableRow from './ResponseTableRow.svelte'
   import { Card, DataTable, EmptyState, Button, RadioGroup, Stack } from '../../ui'
+  import ResponseTableRow from './ResponseTableRow.svelte'
 
   export let responses: ResponseListItem[] = []
 
@@ -10,13 +11,13 @@
 
   let filter = 'set'
 
-  $: fieldsStore = client.fields.listStore
+  const fieldsStore = client.fields.listStore
   $: allFields = $fieldsStore ?? []
 
-  $: responseMap = new Map(responses.map((r) => [r.fieldId, r]))
+  $: responseMap = new Map(responses.map((r) => [r.fieldKey, r]))
 
   $: allFieldRows = allFields.map((field) => {
-    const response = responseMap.get(field.id)
+    const response = responseMap.get(field.key)
     return {
       field,
       response: response || null,
@@ -29,12 +30,20 @@
     return true
   })
 
+  /**
+   * Clears all committed field responses via the client responses API.
+   *
+   * @example
+   * ```typescript
+   * handleClearAll() // removes all responses
+   * ```
+   */
   function handleClearAll() {
     client.responses.clearAll()
   }
 
   const columns = [
-    { key: 'id', header: 'ID' },
+    { key: 'key', header: 'Key' },
     { key: 'field', header: 'Field' },
     { key: 'value', header: 'Value' },
     { key: 'type', header: 'Type' },

package/dist/router/Step.svelte

@@ -1,23 +1,25 @@
 <script lang="ts">
+  /** @file Step component that registers a step with the router and renders its content. */
   import { type Component, type Snippet } from 'svelte'
   import { setStepContext } from '../hooks'
   import { getStepRouter } from './context'
 
   interface Props {
-    id: string
+    key: string
     component?: Component | Promise<Component> | Promise<{ default: Component }>
     children?: Snippet
   }
 
-  const { id, component, children }: Props = $props()
+  const { key, component, children }: Props = $props()
+
 
   const step = {
-    id,
+    key,
   }
 
   const { registerStep, unregisterStep } = getStepRouter()
 
-  setStepContext(id)
+  setStepContext(key)
 
   $effect(() => {
     registerStep(step)

package/dist/router/StepRouter.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  /** @file Root router component that manages step registration and active step detection via Effector. */
   import { createEvent, createStore, sample } from 'effector'
   import { supportsWindow } from '@picked/client'
   import { getExperience } from '../hooks'
@@ -34,7 +35,7 @@
       // we just skip them.
       if (hasActiveStep) return
 
-      const isMatchingStep = step.id === currentStepStore.getState()?.id
+      const isMatchingStep = step.key === currentStepStore.getState()?.key
 
       if (isMatchingStep) {
         setActiveStepEvent(step)
@@ -51,7 +52,7 @@
 
   sample({
     source: { steps: stepsStore, currentStep: currentStepStore },
-    fn: ({ steps, currentStep }) => steps.find((s) => s.id === currentStep?.id) || null,
+    fn: ({ steps, currentStep }) => steps.find((s) => s.key === currentStep?.key) || null,
     target: setActiveStepEvent,
   })
 

package/dist/router/context.d.ts

@@ -1,6 +1,6 @@
 import { Store } from 'effector';
 export interface Step {
-    id: string;
+    key: string;
 }
 interface ContextOptions {
     activeStep: Store<Step | null>;

package/dist/utils/ErrorBoundary.svelte

@@ -8,9 +8,9 @@
   }
 
   const { component: InnerComponent, componentProps }: Props = $props()
+  const client = getPicked()
 
   function handleError(error: unknown) {
-    const client = getPicked()
 
     // We still log to console for visibility during development
     // eslint-disable-next-line no-console

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picked/svelte",
-  "version": "0.0.51-next.1",
+  "version": "0.0.51-next.11",
   "dependencies": {
     "d3": "^7.9.0"
   },
@@ -88,7 +88,7 @@
   },
   "module": "./dist/index.js",
   "peerDependencies": {
-    "@picked/client": "0.0.51-next.1",
+    "@picked/client": "0.0.51-next.11",
     "effector": "^23.3.0",
     "svelte": "^5.46.4"
   },