@picked/svelte 0.0.1-dev.1780464669265 → 0.0.1-dev.1780615163258

package/dist/experience/{Experience.svelte → ExperienceSlot.svelte}

@@ -28,7 +28,13 @@
   const client = getPicked()
   const selector = $derived(`.picked-slot-${name}`)
 
-  const PLACEMENT_ORDER: ExperienceTarget['placement'][] = ['before', 'prepend', 'append', 'after']
+  const PLACEMENT_ORDER: ExperienceTarget['placement'][] = [
+    'replace',
+    'before',
+    'prepend',
+    'append',
+    'after',
+  ]
 
   interface Candidate {
     experience: ExperienceStore
@@ -54,8 +60,8 @@
   }
 
   /**
-   * Maps an experience to a slot candidate, or null when it does not target this slot, uses the
-   * deferred `replace` placement, or carries an action-referencing condition.
+   * Maps an experience to a slot candidate, or null when it does not target this slot or carries
+   * an action-referencing condition.
    *
    * @param {ExperienceStore} experience - The experience to inspect.
    * @returns {Candidate | null} The candidate, or null when the experience is not an eligible slot match.
@@ -71,12 +77,6 @@
       return null
     }
 
-    // `replace` is deferred (first-wins semantics are not implemented yet), so skip it rather than
-    // letting it fall through and render appended-last.
-    if (target.placement === 'replace') {
-      return null
-    }
-
     // Action-referencing conditions are never cached (their side effect must re-run), so they can
     // never resolve through the synchronous `peek` the slot path relies on. Slots do not support
     // action-gated conditions in v1; excluding them also stops the selection effect from re-firing
@@ -102,13 +102,16 @@
 
   // Referencing `$conditionResults` keeps this recompute reactive to late condition writes
   // (the standalone cache-miss path), so a `peek` that returned `undefined` re-renders once
-  // the async evaluation resolves and writes the store.
-  const active = $derived(
-    candidates.filter((candidate) => {
-      void $conditionResults
-      return client.conditionResults.peek(candidate.hash) === true
-    }),
-  )
+  // the async evaluation resolves and writes the store. An active `replace` experience wins:
+  // the first one (it sorts first) renders alone, replacing any other slot matches.
+  const active = $derived.by(() => {
+    void $conditionResults
+    const activeCandidates = candidates.filter(
+      (candidate) => client.conditionResults.peek(candidate.hash) === true,
+    )
+    const firstReplace = activeCandidates.find((candidate) => candidate.placement === 'replace')
+    return firstReplace ? [firstReplace] : activeCandidates
+  })
 
   /**
    * Builds a plain, JSON-serialisable subset of the current URL for the evaluation context.

package/dist/experience/set-picked-context.d.ts

@@ -2,6 +2,7 @@ import { CreateClientOptions, Picked } from '@picked/client';
 import { PickedSnapshot } from '@picked/client/server';
 type SetPickedContextParams = {
     client: Picked;
+    snapshot?: PickedSnapshot;
 } | {
     options: CreateClientOptions;
     snapshot?: PickedSnapshot;
@@ -12,16 +13,17 @@ type SetPickedContextParams = {
  * Call this once at the top of a component's `<script>` so `setContext` and `onMount` run during
  * component initialisation. Pass `options` to create the client and synchronously hydrate it from an
  * optional SSR snapshot (a `versionId` mismatch is tolerated; the client reconciles via `start()`),
- * or pass an existing `client` (such as the app's already-running global client) to render
- * experiences against it. In the browser the client is started from `onMount`; `start()` is
+ * or pass an existing `client` (such as the app's single global client) to render experiences
+ * against it — supply `snapshot` alongside `client` to SSR-seed that shared client rather than
+ * creating a second one. In the browser the client is started from `onMount`; `start()` is
  * idempotent, so a client that was already started is left untouched.
  *
- * @param {SetPickedContextParams} params - Either `{ client }` or `{ options, snapshot? }`.
+ * @param {SetPickedContextParams} params - `{ client, snapshot? }` or `{ options, snapshot? }`.
  * @returns {Picked} The client placed into context.
  * @example
  * setPickedContext({ options })
  * @example
- * setPickedContext({ client: globalClient })
+ * setPickedContext({ client: globalClient, snapshot })
  */
 export declare function setPickedContext(params: SetPickedContextParams): Picked;
 export {};

package/dist/experience/set-picked-context.js

@@ -1 +1 @@
-import{CLIENT_CONTEXT_KEY as e}from"../context.js";import{onMount as t,setContext as n}from"svelte";import{createClient as r,supportsWindow as i}from"@picked/client";import{registerProjectConfig as a}from"@picked/client/server";function o(e,t){let n=r(e);if(t){let e=n.session.store.getState().id;a(n,t.projectConfig,{isPreview:!1,sessionId:e}),t.content.forEach(e=>n.registerContent(e)),n.conditionResults.seed(t.conditionResults)}return n}function s(r){let a=`client`in r?r.client:o(r.options,r.snapshot);return n(e,a),t(()=>{i()&&a.start()}),a}export{s as setPickedContext};
+import{CLIENT_CONTEXT_KEY as e}from"../context.js";import{onMount as t,setContext as n}from"svelte";import{createClient as r,supportsWindow as i}from"@picked/client";import{registerProjectConfig as a}from"@picked/client/server";function o(e,t){let n=e.session.store.getState().id;a(e,t.projectConfig,{isPreview:!1,sessionId:n}),t.content.forEach(t=>e.registerContent(t)),e.conditionResults.seed(t.conditionResults)}function s(e,t){let n=r(e);return t&&o(n,t),n}function c(r){let a;return`client`in r?(r.snapshot&&o(r.client,r.snapshot),a=r.client):a=s(r.options,r.snapshot),n(e,a),t(()=>{i()&&a.start()}),a}export{c as setPickedContext};

package/dist/index.d.ts

@@ -5,4 +5,4 @@ export { adaptSvelteComponent, isValidAdaptedComponent } from './component';
 export type { ComponentWithProps } from './component';
 export { LazyImage } from './components';
 export { setPickedContext } from './experience/set-picked-context';
-export { default as Experience } from './experience/Experience.svelte';
+export { default as ExperienceSlot } from './experience/ExperienceSlot.svelte';

package/dist/index.js

@@ -1 +1 @@
-import{adaptSvelteComponent as e,isValidAdaptedComponent as t}from"./component.js";import{LazyImage as n}from"./components/index.js";import{setPickedContext as r}from"./experience/set-picked-context.js";import i from"./experience/Experience.svelte";export{i as Experience,n as LazyImage,e as adaptSvelteComponent,t as isValidAdaptedComponent,r as setPickedContext};
+import{adaptSvelteComponent as e,isValidAdaptedComponent as t}from"./component.js";import{LazyImage as n}from"./components/index.js";import{setPickedContext as r}from"./experience/set-picked-context.js";import i from"./experience/ExperienceSlot.svelte";export{i as ExperienceSlot,n as LazyImage,e as adaptSvelteComponent,t as isValidAdaptedComponent,r as setPickedContext};

package/dist/plugins/devtools/DevToolsExperience.svelte

@@ -23,6 +23,7 @@
   import ContentListScreen from './screens/content/ContentListScreen.svelte'
   import FeaturesListScreen from './screens/features/FeaturesListScreen.svelte'
   import EventsListScreen from './screens/events/EventsListScreen.svelte'
+  import CustomToolsScreen from './screens/custom-tools/CustomToolsScreen.svelte'
   import PickedIcon from './PickedIcon.svelte'
 
   const experience = getExperience()
@@ -116,6 +117,12 @@
       component: ResponsesListScreen,
       props: {},
     },
+    {
+      id: 'custom-tools',
+      label: 'Custom Tools',
+      component: CustomToolsScreen,
+      props: {},
+    },
   ]
 
   const isOpen = experience.isOpenStore

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

@@ -0,0 +1,103 @@
+<script lang="ts">
+  /** @file Renders a custom devtools tool by delegating to its framework's registered renderer. */
+  import { onDestroy } from 'svelte'
+  import type { Framework } from '@picked/client'
+  import { getExperience, getPicked } from '../../../hooks'
+  import type { CustomTool } from '../customTools'
+  import { Banner } from '../ui'
+
+  export let tool: CustomTool
+
+  const client = getPicked()
+  const experience = getExperience()
+  const frameworkStore = client.frameworks.getByName(tool.component.frameworkName)
+
+  let host: HTMLDivElement | undefined
+  let rendered = false
+  let renderFailed = false
+  let destroyed = false
+  let activeFramework: Framework | undefined
+  let activeShadow: ShadowRoot | undefined
+
+  /**
+   * Records a tool render failure: surfaces a banner and logs to the console. A consumer tool's
+   * render failure is deliberately not routed through the client event bus, so a third-party tool
+   * bug never reaches the platform's Sentry exception stream.
+   *
+   * @param {unknown} error - The error thrown or rejected by the framework renderer.
+   * @example
+   * handleRenderError(new Error('tool blew up'))
+   */
+  function handleRenderError(error: unknown) {
+    renderFailed = true
+    // eslint-disable-next-line no-console -- surface tool failures locally; consumer errors must not reach Sentry
+    console.error(`Custom devtools tool "${tool.label}" failed to render`, error)
+  }
+
+  /**
+   * Tears down the tool's mounted instance using the framework that rendered it. Idempotent: the
+   * renderer's unmount is a no-op once the instance is gone, so calling it twice is safe.
+   *
+   * @example
+   * teardown()
+   */
+  function teardown() {
+    if (activeShadow && activeFramework?.unmount) {
+      activeFramework.unmount(activeShadow)
+    }
+  }
+
+  $: framework = $frameworkStore
+
+  $: if (framework && host && !rendered) {
+    rendered = true
+    const shadow = host.shadowRoot ?? host.attachShadow({ mode: 'open' })
+    const fw = framework
+    activeFramework = fw
+    activeShadow = shadow
+    try {
+      void Promise.resolve(fw.render(shadow, tool.component, client, experience))
+        .then(() => {
+          if (destroyed) teardown()
+        })
+        .catch(handleRenderError)
+    } catch (error) {
+      handleRenderError(error)
+    }
+  }
+
+  onDestroy(() => {
+    destroyed = true
+    teardown()
+  })
+</script>
+
+{#if framework}
+  <div class="adapted-tool-host" bind:this={host} hidden={renderFailed}></div>
+  {#if renderFailed}
+    <div class="adapted-tool-fallback">
+      <Banner status="error" title="Tool failed to render">
+        The "{tool.label}" tool threw while rendering. See the browser console for details.
+      </Banner>
+    </div>
+  {/if}
+{:else}
+  <div class="adapted-tool-fallback">
+    <Banner status="warning" title="Framework not registered">
+      This tool renders a "{tool.component.frameworkName}" component, but no matching framework is
+      registered with the Picked client. Add the corresponding framework plugin to use it.
+    </Banner>
+  </div>
+{/if}
+
+<style>
+  .adapted-tool-host {
+    height: 100%;
+    padding: var(--space-4);
+    box-sizing: border-box;
+  }
+
+  .adapted-tool-fallback {
+    padding: var(--space-4);
+  }
+</style>

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

@@ -0,0 +1,26 @@
+import { AdaptedComponent, Picked } from '@picked/client';
+/**
+ * A user-defined developer tool surfaced under the devtools "Custom Tools" tab.
+ *
+ * The component is framework-adapted (via `adaptReactComponent` or `adaptSvelteComponent`), so
+ * tools can be authored in the host app's framework and still receive the live Picked client the
+ * way an experience component does.
+ */
+export interface CustomTool {
+    id: string;
+    label: string;
+    component: AdaptedComponent;
+}
+/**
+ * Reads the custom tools registered with the devtools plugin for a given client.
+ *
+ * Malformed entries are dropped, and entries that repeat an already-seen `id` are dropped
+ * (first registration wins), so a single bad or duplicate registration can't break the tab — the
+ * `id` is used as a keyed-each key when the tools are rendered as tabs.
+ *
+ * @param {Picked} client - The Picked client whose plugin config holds the registered tools.
+ * @returns {CustomTool[]} The valid, id-unique registered custom tools, or an empty array when none exist.
+ * @example
+ * const tools = readCustomTools(getPicked())
+ */
+export declare function readCustomTools(client: Picked): CustomTool[];

package/dist/plugins/devtools/customTools.js

@@ -0,0 +1 @@
+import{DEVTOOLS_PLUGIN_NAME as e}from"./plugin.js";function t(e){return typeof e==`object`&&!!e&&`frameworkName`in e&&typeof e.frameworkName==`string`&&`component`in e}function n(e){return typeof e==`object`&&!!e&&`id`in e&&typeof e.id==`string`&&`label`in e&&typeof e.label==`string`&&`component`in e&&t(e.component)}function r(t){let r=t.getPluginConfig(e).customTools;if(!Array.isArray(r))return[];let i=new Set;return r.filter(n).filter(e=>i.has(e.id)?!1:(i.add(e.id),!0))}export{r as readCustomTools};

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

@@ -1,4 +1,7 @@
 import { Plugin } from '@picked/client';
+import { CustomTool } from './customTools';
+/** Plugin name under which the devtools plugin stores its config (including registered custom tools). */
+export declare const DEVTOOLS_PLUGIN_NAME = "svelte-devtools";
 export interface SvelteDevtoolsPluginOptions {
     /**
      * When `true`, the devtools experience launches automatically on page load.
@@ -9,6 +12,15 @@ export interface SvelteDevtoolsPluginOptions {
      * @default false
      */
     enabled?: boolean;
+    /**
+     * Project-specific custom dev tools surfaced under the "Custom Tools" tab. Each tool's
+     * `component` is framework-adapted (via `adaptReactComponent` or `adaptSvelteComponent`), so it
+     * can be authored in the host app's framework and still receive the live Picked client the way
+     * an experience component does.
+     *
+     * @default []
+     */
+    customTools?: CustomTool[];
 }
 /**
  * Registers the devtools experience for on-demand loading via the Chrome DevTools extension.

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`,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=>{let t=!!e.searchParams[`preview-token`]?.[0];!a?.enabled&&!t||e.eventBus.watch(t=>{t.type===`ready`&&e.experiences.launch({key:o.key,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=`svelte-devtools`,o=o=>{let s=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 s.addStep({name:`Tools`}),[{name:a,setup:e=>{let t=!!e.searchParams[`preview-token`]?.[0];return(o?.enabled||t)&&e.eventBus.watch(t=>{t.type===`ready`&&e.experiences.launch({key:s.key,options:{bypassCondition:!0}})}),{customTools:o?.customTools??[]}}},i({experiences:[s]})]};export{a as DEVTOOLS_PLUGIN_NAME,o as svelteDevtoolsPlugin};

package/dist/plugins/devtools/screens/custom-tools/CustomToolsScreen.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+  /** @file Screen hosting user-registered custom devtools tools as nested tabs. */
+  import { getPicked } from '../../../../hooks'
+  import AdaptedToolHost from '../../components/AdaptedToolHost.svelte'
+  import Tabs from '../../components/Tabs.svelte'
+  import { readCustomTools } from '../../customTools'
+  import { Button, EmptyState, Stack } from '../../ui'
+
+  const client = getPicked()
+  const docsUrl = `${client.documentationSiteUrl}/chrome-extension#custom-tools`
+  const tools = readCustomTools(client)
+  const tabs = tools.map((tool) => ({
+    id: tool.id,
+    label: tool.label,
+    component: AdaptedToolHost,
+    props: { tool },
+  }))
+</script>
+
+{#if tabs.length > 0}
+  <Tabs {tabs} />
+{:else}
+  <Stack direction="vertical" gap="medium" padding="medium" justify="center">
+    <EmptyState message="No custom tools registered." />
+    <Button variant="ghost" size="small" href={docsUrl} target="_blank">
+      Learn how to add custom tools
+    </Button>
+  </Stack>
+{/if}

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

@@ -14,9 +14,8 @@ export interface SvelteFrameworkPluginOptions {
  * This plugin registers the Svelte framework and allows rendering Svelte components
  * with the client's experience data.
  *
- * @param {SvelteFrameworkPluginOptions} options - Configuration options for the Svelte plugin
+ * @param {SvelteFrameworkPluginOptions} options - Configuration options for the Svelte plugin.
  * @returns {Plugin} The plugin.
- *
  * @example
  * ```typescript
  * createClient({

package/dist/plugins/framework/plugin.js

@@ -1 +1 @@
-import{adaptSvelteComponent as e}from"../../component.js";import{renderSvelteComponent as t}from"../../render/browser.js";var n=n=>({name:`svelte-framework`,setup:r=>{r.registerFramework({name:`svelte`,render(...e){return t(...e,{stylesheets:n.stylesheets,css:n.css})}});let i=n.components.experience;i&&r.registerComponent(`experience`,e(i.component,i.style))}});export{n as svelteFrameworkPlugin};
+import{adaptSvelteComponent as e}from"../../component.js";import{renderSvelteComponent as t,unRenderSvelteComponent as n}from"../../render/browser.js";var r=r=>({name:`svelte-framework`,setup:i=>{i.registerFramework({name:`svelte`,render(...e){return t(...e,{stylesheets:r.stylesheets,css:r.css})},unmount:e=>n(e)});let a=r.components.experience;a&&i.registerComponent(`experience`,e(a.component,a.style))}});export{r as svelteFrameworkPlugin};

package/dist/render/browser.d.ts

@@ -1,12 +1,12 @@
 import { AdaptedComponent, ExperienceInstance, Picked } from '@picked/client';
 /**
- * Builds the Svelte context map exposing the client and experience instance to a mounted component.
+ * Builds the Svelte context map that exposes the client and experience to rendered components.
  *
- * @param {Picked} client - The Picked client.
- * @param {ExperienceInstance} experience - The experience instance.
- * @returns {Map<symbol, Picked | ExperienceInstance>} The context map keyed by the client and experience context symbols.
+ * @param {Picked} client - The Picked client to expose via context.
+ * @param {ExperienceInstance} experience - The experience instance to expose via context.
+ * @returns {Map<symbol, Picked | ExperienceInstance>} The context map keyed by the client and experience symbols.
  * @example
- * createContext(client, experience)
+ * mount(Comp, { target, context: createContext(client, experience) })
  */
 export declare function createContext(client: Picked, experience: ExperienceInstance): Map<symbol, Picked | ExperienceInstance>;
 /**
@@ -28,3 +28,12 @@ export declare const renderSvelteComponent: (shadowRoot: ShadowRoot, component:
     stylesheets?: string[];
     css?: string[];
 }) => Promise<void>;
+/**
+ * Unmounts a Svelte component previously rendered into the given shadow root and clears its tracked instance.
+ *
+ * @param {ShadowRoot} target - The shadow root the component was rendered into.
+ * @returns {void} Nothing.
+ * @example
+ * unRenderSvelteComponent(host.shadowRoot)
+ */
+export declare const unRenderSvelteComponent: (target: ShadowRoot) => void;

package/dist/render/browser.js

@@ -1 +1 @@
-import{isValidAdaptedComponent as e}from"../component.js";import{CLIENT_CONTEXT_KEY as t,EXPERIENCE_CONTEXT_KEY as n}from"../context.js";import{mergeArrays as r}from"../utils/array.js";import{mount as i}from"svelte";import{isLazyLoader as a}from"@picked/client";import o from"../utils/ErrorBoundary.svelte";function s(e,r){return new Map([[t,e],[n,r]])}var c=async(t,n,c,l,u)=>{if(!e(n))throw Error(`The component is invalid.`);let d=r(n.style?.sheets,u.stylesheets),f=r(n.style?.css,u.css);d.length&&d.forEach(e=>{let n=document.createElement(`link`);n.setAttribute(`rel`,`stylesheet`),n.setAttribute(`href`,e),n.setAttribute(`type`,`text/css`),n.setAttribute(`picked-injected`,`true`),t.appendChild(n)}),f.length&&f.forEach(e=>{let n=document.createElement(`style`);n.textContent=e,n.setAttribute(`type`,`text/css`),n.setAttribute(`picked-injected`,`true`),t.appendChild(n)});let p=e=>{i(o,{target:t,props:{component:e,componentProps:{client:c,experience:l}},context:s(c,l)})};if(a(n.component)){let{default:e}=await n.component.load();p(e);return}if(n.component instanceof Promise){let{default:e}=await n.component;p(e);return}p(n.component)};export{s as createContext,c as renderSvelteComponent};
+import{isValidAdaptedComponent as e}from"../component.js";import{CLIENT_CONTEXT_KEY as t,EXPERIENCE_CONTEXT_KEY as n}from"../context.js";import{mergeArrays as r}from"../utils/array.js";import{mount as i,unmount as a}from"svelte";import{isLazyLoader as o}from"@picked/client";import s from"../utils/ErrorBoundary.svelte";var c=new WeakMap;function l(e,r){return new Map([[t,e],[n,r]])}var u=async(t,n,a,u,d)=>{if(!e(n))throw Error(`The component is invalid.`);let f=r(n.style?.sheets,d.stylesheets),p=r(n.style?.css,d.css);f.length&&f.forEach(e=>{let n=document.createElement(`link`);n.setAttribute(`rel`,`stylesheet`),n.setAttribute(`href`,e),n.setAttribute(`type`,`text/css`),n.setAttribute(`picked-injected`,`true`),t.appendChild(n)}),p.length&&p.forEach(e=>{let n=document.createElement(`style`);n.textContent=e,n.setAttribute(`type`,`text/css`),n.setAttribute(`picked-injected`,`true`),t.appendChild(n)});let m=e=>{let n=i(s,{target:t,props:{component:e,componentProps:{client:a,experience:u}},context:l(a,u)});c.set(t,n)};if(o(n.component)){let{default:e}=await n.component.load();m(e);return}if(n.component instanceof Promise){let{default:e}=await n.component;m(e);return}m(n.component)},d=e=>{let t=c.get(e);t&&(a(t),c.delete(e))};export{l as createContext,u as renderSvelteComponent,d as unRenderSvelteComponent};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picked/svelte",
-  "version": "0.0.1-dev.1780464669265",
+  "version": "0.0.1-dev.1780615163258",
   "dependencies": {
     "d3": "^7.9.0"
   },
@@ -106,7 +106,7 @@
   },
   "module": "./dist/index.js",
   "peerDependencies": {
-    "@picked/client": "0.0.1-dev.1780464669265",
+    "@picked/client": "0.0.1-dev.1780615163258",
     "effector": "^23.3.0",
     "svelte": "^5.46.4"
   },