@picked/svelte 0.0.63 → 0.0.64-next.2

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/index.d.ts

@@ -1,2 +1,4 @@
+/** @file Public entrypoint for the Svelte devtools plugin — the plugin factory and its consumer-facing types. */
 export { svelteDevtoolsPlugin } from './plugin';
 export type * from './plugin';
+export type { CustomTool } from './customTools';

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.63",
+  "version": "0.0.64-next.2",
   "dependencies": {
     "d3": "^7.9.0"
   },
@@ -106,7 +106,7 @@
   },
   "module": "./dist/index.js",
   "peerDependencies": {
-    "@picked/client": "0.0.63",
+    "@picked/client": "0.0.64-next.2",
     "effector": "^23.3.0",
     "svelte": "^5.46.4"
   },