@picked/client 0.0.1-dev.1777594341273 → 0.0.1-dev.1777597464369

package/dist/docs/pickedql/examples.md

@@ -87,6 +87,46 @@ FROM events
 WHERE project_id = '{{ your project ID }}'
 ```
 
+## Custom segment with `control_users` / `variant_users`
+
+On `events`, `control_users` / `variant_users` / `control_sessions` / `variant_sessions` accept an optional filter string to count only users/sessions matching the given expression in addition to the implicit `variant_type` filter.
+
+```sql
+-- Control users who fired app_initialize, broken down by step
+SELECT
+  step_id,
+  control_users('event_type=app_initialize')                      AS control_initialized,
+  variant_users('event_type=app_initialize')                      AS variant_initialized
+FROM events
+WHERE project_id = '{{ your project ID }}'
+  AND client_local_date >= '2026-04-01'
+GROUP BY step_id
+ORDER BY control_initialized DESC
+```
+
+The named form (`filter=`) is also supported:
+
+```sql
+SELECT control_users(filter='event_type=form_submit AND step_id=lead-capture') FROM events
+WHERE project_id = '{{ your project ID }}'
+```
+
+## Conversion rate from nested virtual functions
+
+When numerator and denominator come from different segments — e.g., Control users who fired a custom event divided by **all** users (not just Control) — pass virtual function calls directly as conversion-rate args:
+
+```sql
+-- (Control users who fired app_initialize) / (all users, regardless of variant)
+SELECT
+  control_conversion_rate(
+    control_users('event_type=app_initialize'),
+    all_users()
+  ) AS control_initialize_rate
+FROM events
+WHERE project_id = '{{ your project ID }}'
+  AND client_local_date >= '2026-04-01'
+```
+
 ## A/B test by device
 
 ```sql
@@ -138,7 +178,7 @@ ORDER BY project_local_date, device_category
 SELECT
   utm_source,
   all_users()                      AS users,
-  total_purchase_users()           AS purchasers
+  all_purchase_users()             AS purchasers
 FROM metrics
 WHERE project_id = '{{ your project ID }}'
 GROUP BY utm_source

package/dist/docs/pickedql/filtering.md

@@ -29,3 +29,25 @@ WHERE project_id = 'your-project-id'
 :::warning
 Each query can only filter on a single `project_id`. Queries that reference multiple projects will be rejected.
 :::
+
+## Reference tables (per-table tenant filter)
+
+Queries against the reference tables (`steps`, `experiences`, `projects`) require their own tenant filter so you only see rows belonging to a project you have access to:
+
+| Source | Tenant filter |
+|---|---|
+| `steps`, `experiences` | `WHERE project_id = '<project_id>'` |
+| `projects` | `WHERE id = '<project_id>'` (the row's `id` IS the project id) |
+
+```sql
+-- All experiences for one project
+SELECT id, title FROM experiences WHERE project_id = 'your-project-id'
+
+-- All steps for one project
+SELECT id, title FROM steps WHERE project_id = 'your-project-id'
+
+-- Metadata for one project
+SELECT id, name, timezone FROM projects WHERE id = 'your-project-id'
+```
+
+The small lookup tables (`dim_variant`, `dim_device`, `dim_geo`, `dim_utm`, `dim_product`) are still exempt — they contain no tenant data.

package/dist/docs/pickedql/index.md

@@ -22,7 +22,7 @@ PickedQL handles table mapping and dimension joins automatically. You write conc
 1. **Virtual table expansion**: Table names like `metrics` map to underlying data tables
 2. **Virtual function expansion**: Shorthand functions like `control_users()` expand to full aggregate expressions
 3. **Auto dimension joins**: References to dimension columns (like `device_category` or `country_code`) trigger automatic `LEFT JOIN` clauses — you never write joins yourself
-4. **Tenant isolation**: Every query must include a `project_id` filter in the `WHERE` clause. PickedQL extracts it and verifies you have permission to access that project
+4. **Tenant isolation**: Every query must include a tenant filter in the `WHERE` clause — usually `project_id`, but `projects` uses `id` (the row's `id` IS the project id). PickedQL extracts the filter and verifies you have permission to access that project
 5. **SQL passthrough**: Standard SQL (including `CASE WHEN`, window functions, and subqueries) works alongside virtual functions
 
 ## Best practices
@@ -32,4 +32,5 @@ PickedQL handles table mapping and dimension joins automatically. You write conc
 - **Use `experience_journey` for sankey / funnel charts**: One line of SQL returns `source, target, users` — the 8-CTE scaffold (dedup, top-N path ranking, lagInFrame) is handled internally; pass parameters via `WHERE`
 - **Don't write JOINs**: PickedQL injects them automatically when you reference dimension columns
 - **Group by any dimension**: Add dimension columns to `SELECT` and `GROUP BY` freely — required joins are handled for you
+- **Reference table metadata for free**: Use `step_title`, `experience_title`, `project_name` directly in `events` queries — PickedQL auto-joins the `steps`, `experiences`, and `projects` reference tables
 

package/dist/docs/pickedql/schema.md

@@ -83,6 +83,36 @@ These columns are joined automatically when referenced — no `JOIN` syntax need
 | `product_name` | dim_product | Product name |
 | `product_category` | dim_product | Product category |
 | `product_page` | dim_product | Product page |
+| `step_title` | steps | Step title (joined on `project_id` + `experience_id` + `step_id`) |
+| `experience_title` | experiences | Experience title (joined on `project_id` + `experience_id`) |
+| `project_name` | projects | Project name |
+| `project_timezone` | projects | Project timezone |
+
+## `steps`, `experiences`, `projects`
+
+Reference tables describing your Picked configuration. Auto-joined onto `events` when their analyst-facing columns are referenced; require a per-table tenant filter when queried directly.
+
+| Source | Real Columns | Analyst Columns (when referenced from `events`) | Tenant filter (when queried directly) |
+|---|---|---|---|
+| `steps` | `id`, `title`, `experience_id`, `project_id`, `organization_id` | `step_title` | `project_id = '…'` |
+| `experiences` | `id`, `title`, `project_id`, `organization_id` | `experience_title` | `project_id = '…'` |
+| `projects` | `id`, `name`, `timezone`, `organization_id` | `project_name`, `project_timezone` | `id = '<project_id>'` |
+
+When queried directly, use the real column names:
+
+```sql
+-- List all experiences for a project
+SELECT id, title FROM experiences WHERE project_id = 'your-project-id'
+```
+
+When referenced from `events`, use the prefixed analyst names — joins are injected automatically:
+
+```sql
+SELECT experience_title, step_title, count(*)
+FROM events
+WHERE project_id = 'your-project-id'
+GROUP BY experience_title, step_title
+```
 
 ## `features`
 
@@ -117,7 +147,10 @@ Aggregated step-transition edges for sankey / funnel charts. Parameters are supp
 | `num_nodes_after_start` | Integer |  | Forward window from start: keep steps where `seq_pos < start_seq + N` (card 4129 semantics). |
 | `num_nodes_before_target` | Integer |  | Backward window from target: keep steps where `seq_pos >= target_seq - N` (card 2740 semantics). Requires `targeting_step`. |
 | `top_n_path` | Integer |  | Keep only the top-N most-walked paths by user count. Defaults to no limit. |
+| `user_cohort_event` | String |  | Restrict to users who have at least one `fact_events` row with this `event_type`. Implemented as `user_canonical_id IN (SELECT DISTINCT user_canonical_id FROM fact_events WHERE event_type = '…')`. |
+| `client_local_date` | Date |  | Date range filter, pushed into the underlying scan. Supports `=`, `<`, `<=`, `>`, `>=`, `BETWEEN`. |
+| `event_timestamp` | DateTime64 |  | Server-side timestamp filter. Same operators as `client_local_date`. |
 
-When both window params are set, both predicates apply (intersection).
+When both window params are set, both predicates apply (intersection). Date filters combine via `AND` with the other params.
 
 See [data sources → experience_journey](./data-sources#experience_journey--sankey-ready-step-transitions) for usage examples.

package/dist/docs/pickedql/virtual-functions.md

@@ -10,23 +10,53 @@ Virtual functions are shorthand for aggregate expressions. They are **table-awar
 
 | Function | Description |
 |---|---|
-| `control_users()` | Unique users in the Control group |
-| `variant_users()` | Unique users in the Variant group |
+| `control_users([condition])` | Unique users in the Control group, optionally filtered by a custom condition |
+| `variant_users([condition])` | Unique users in the Variant group, optionally filtered by a custom condition |
 | `all_users()` | All unique users |
-| `control_sessions()` | Unique sessions in the Control group |
-| `variant_sessions()` | Unique sessions in the Variant group |
+| `control_sessions([condition])` | Unique sessions in the Control group, optionally filtered by a custom condition |
+| `variant_sessions([condition])` | Unique sessions in the Variant group, optionally filtered by a custom condition |
 | `all_sessions()` | All unique sessions |
 
+### Custom filters on `events`
+
+On the `events` table, `control_*`/`variant_*` functions accept **one optional filter argument** to count only users/sessions matching the given expression, in addition to the implicit `variant_type` filter. The argument can be **positional** or **named** (`filter=`).
+
+The filter uses the same `column=value` syntax as conversion-rate conditions, with `AND`/`OR` operators and parentheses for grouping.
+
+```sql
+-- Default: all Control users
+SELECT control_users() FROM events
+
+-- Custom filter (positional)
+SELECT control_users('event_type=app_initialize') FROM events
+SELECT variant_users('event_type=app_initialize AND step_id=xxx') FROM events
+
+-- AND/OR + parentheses
+SELECT control_users('event_type=app_initialize OR event_type=app_load') FROM events
+SELECT control_users('event_type=form_submit AND (step_id=lead-capture OR step_id=xxx)') FROM events
+
+-- Sessions
+SELECT control_sessions('event_type=step_enter') FROM events
+SELECT variant_sessions('event_type=step_enter AND step_id=checkout') FROM events
+
+-- Named form
+SELECT control_users(filter='event_type=app_initialize AND step_id=xxx') FROM events
+```
+
+:::note
+Custom filters are **not supported on `metrics`** (pre-aggregated data). On `metrics`, these functions ignore any arguments and use the default Control/Variant filter only.
+:::
+
 ## Conversion metrics
 
 | Function | Description |
 |---|---|
-| `total_purchase_users()` | Users who completed a purchase |
+| `all_purchase_users()` | Users who completed a purchase |
 | `control_purchase_users()` | Control users who purchased (`metrics` only) |
 | `variant_purchase_users()` | Variant users who purchased (`metrics` only) |
-| `total_purchase_sessions()` | Sessions with a purchase (`metrics` only) |
-| `total_purchase_orders()` | Unique order count (`metrics` only) |
-| `total_cart_add_users()` | Users who added to cart |
+| `all_purchase_sessions()` | Sessions with a purchase (`metrics` only) |
+| `all_purchase_orders()` | Unique order count (`metrics` only) |
+| `all_cart_add_users()` | Users who added to cart |
 
 ## Conversion rates
 
@@ -38,9 +68,9 @@ Virtual functions are shorthand for aggregate expressions. They are **table-awar
 
 ### Custom conditions on `events`
 
-On the `events` table, conversion rate functions accept up to **2 optional arguments** to customize the numerator and denominator. Arguments can be **positional** or **named** (`numerator=`, `denominator=`).
+On the `events` table, conversion rate functions accept up to **2 optional arguments** to customize the numerator and denominator. Each argument can be either a **condition expression string** or a **nested virtual function call** (see below). Arguments can be **positional** or **named** (`numerator=`, `denominator=`).
 
-Each argument is a condition expression using `column=value` with `AND`/`OR` operators and parentheses for grouping.
+Each condition expression uses `column=value` with `AND`/`OR` operators and parentheses for grouping.
 
 ```sql
 -- Default: purchase users / all users
@@ -69,8 +99,34 @@ SELECT control_conversion_rate(denominator='step_id=lead-capture') FROM events
 SELECT conversion_rate_uplift(numerator='event_type=form_submit', denominator='step_id=lead-capture') FROM events
 ```
 
+#### Nested virtual functions as numerator / denominator
+
+Instead of a condition string, you can pass a **virtual function call** as the numerator or denominator. The inner aggregate is substituted in place — no implicit `variant_type` filter is added on top of it (the nested function controls its own filter).
+
+This is the most flexible form when the numerator and denominator have different segments (e.g., Control users who fired event X over **all** users regardless of variant):
+
+```sql
+-- (Control users who fired app_initialize) / (all users)
+SELECT control_conversion_rate(
+  control_users('event_type=app_initialize'),
+  all_users()
+) FROM events
+
+-- Mix string and nested forms
+SELECT control_conversion_rate(
+  'event_type=form_submit',
+  all_users()
+) FROM events
+
+-- Uplift with nested args
+SELECT conversion_rate_uplift(
+  control_users('event_type=app_initialize'),
+  all_users()
+) FROM events
+```
+
 :::note
-Custom conditions are **not supported on `metrics`** (pre-aggregated data). On `metrics`, these functions always use the default purchase / all users definition.
+Custom conditions and nested virtual function args are **not supported on `metrics`** (pre-aggregated data). On `metrics`, these functions always use the default purchase / all users definition.
 :::
 
 ## Visitor segmentation (`metrics` only)

package/dist/docs/{projects.md → projects.mdx}

@@ -2,10 +2,17 @@
 layout: docs
 ---
 
+import { Screenshot } from '../../components/Screenshot'
+
 # Projects
 
 A project represents one website or app you want to instrument with Picked. Each project has its own set of experiences, entities, and configuration.
 
+<Screenshot
+  route="/{orgSlug}"
+  alt="The organization home page on the Picked dashboard, listing the projects in an organization"
+/>
+
 ## Create a project
 
 You need an organization first. If you don't have one, create it when you sign up.

package/dist/docs/{reports.md → reports.mdx}

@@ -2,10 +2,17 @@
 layout: docs
 ---
 
+import { Screenshot } from '../../components/Screenshot'
+
 # Reports
 
 Reports show analytics data for your project. Track how visitors interact with your experiences and features.
 
+<Screenshot
+  route="/{orgSlug}/{projectId}/reports"
+  alt="The reports list for a project on the Picked dashboard"
+/>
+
 ## View report data
 
 Open a report to see its analytics. Data updates as new visitor interactions are recorded.

package/dist/docs/{steps.md → steps.mdx}

@@ -2,10 +2,17 @@
 layout: docs
 ---
 
+import { Screenshot } from '../../components/Screenshot'
+
 # Steps
 
 A step is a visual screen or card shown to visitors during an experience. Each step holds one or more fields that collect data or display content.
 
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/steps"
+  alt="The steps list for a workspace on the Picked dashboard"
+/>
+
 ## Create a step
 
 1. Open your project.

package/dist/docs/{workspaces.md → workspaces.mdx}

@@ -2,10 +2,18 @@
 layout: docs
 ---
 
+import { Screenshot } from '../../components/Screenshot'
+
 # Workspaces
 
 A workspace is a version of your project's configuration. Use workspaces to stage changes, preview them, and publish when ready.
 
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces"
+  alt="The workspaces list inside a project on the Picked dashboard"
+  hide={['[data-testid="workspace-row-relative-time"]']}
+/>
+
 ## How workspaces work
 
 Each project has a workspace that holds your experiences, features, and entity configurations. When you make changes in the dashboard — editing a flow, updating a feature, or modifying an entity — those changes exist in the workspace until you publish.

package/dist/esm/form/index.js

@@ -1,4 +1,4 @@
-import { t as e } from "../../rules-logic-D7dL30U1.js";
+import { t as e } from "../../rules-logic-BTIxfrJJ.js";
 import { attach as t, combine as n, createEffect as r, createEvent as i, createStore as a, sample as o, split as s } from "effector";
 //#region src/form/build-responses.ts
 function c(e, t, n) {
@@ -70,10 +70,16 @@ function m(e, n, i) {
 			staged: i,
 			committed: e.responses.getAllStore
 		},
-		effect: r(async ({ allFields: t, fieldKeys: n, staged: r, committed: i }) => await p(e, t.filter((e) => n.includes(e.key)), { responses: {
-			...i,
-			...r
-		} }))
+		effect: r(async ({ allFields: t, fieldKeys: n, staged: r, committed: i }) => {
+			let a = new Map(t.map((e) => [e.key, e]));
+			return await p(e, n.flatMap((e) => {
+				let t = a.get(e);
+				return t ? [t] : [];
+			}), { responses: {
+				...i,
+				...r
+			} });
+		})
 	});
 	return o({
 		clock: c.doneData,
@@ -354,7 +360,16 @@ function v({ client: e, experienceInstance: n, formId: c, title: u, stepStore: d
 		clock: g,
 		target: w.executeFx
 	}), o({
-		clock: [y, w.executeFx.done],
+		clock: [
+			y,
+			w.executeFx.done,
+			T.executeFx.fail,
+			E.fail,
+			D.fail,
+			O.fail,
+			C.executeFx.fail,
+			w.executeFx.fail
+		],
 		fn: () => !1,
 		target: b
 	}), {
@@ -374,7 +389,15 @@ function y(e) {
 	if (t instanceof HTMLInputElement) return t.type === "checkbox" ? t.checked : t.value;
 	if (t instanceof HTMLSelectElement || t instanceof HTMLTextAreaElement) return t.value;
 }
-function b(e, t, r, i) {
+function b(e, t) {
+	let n = e.currentTarget;
+	if (t.multiple) {
+		if (n instanceof HTMLInputElement && n.type === "checkbox" && n.form) return Array.from(new FormData(n.form).getAll(n.name), String);
+		if (n instanceof HTMLSelectElement && n.multiple) return Array.from(n.selectedOptions, (e) => e.value);
+	}
+	return y(e);
+}
+function x(e, t, r, i) {
 	let { client: s, experienceInstance: c } = e, { currentStepStore: l, goToNextStep: u } = c, d = n(l, c, (e, t) => ({
 		stepId: e?.id,
 		experienceId: t.id
@@ -389,7 +412,7 @@ function b(e, t, r, i) {
 		},
 		target: f
 	});
-	let { fieldInputEvent: h, fieldChangeEvent: _, fieldBlurEvent: b, touchedStore: x, fieldErrorsStore: S, formErrorsStore: C } = g(s, p, f), w = n({
+	let { fieldInputEvent: h, fieldChangeEvent: _, fieldBlurEvent: y, touchedStore: x, fieldErrorsStore: S, formErrorsStore: C } = g(s, p, f), w = n({
 		fields: p,
 		responses: s.responses.listStore,
 		staged: f,
@@ -398,20 +421,20 @@ function b(e, t, r, i) {
 		experienceAndStepId: d
 	}, ({ fields: e, responses: t, staged: n, fieldErrors: r, touched: i, experienceAndStepId: a }) => e.map((e) => {
 		let o = (t) => {
-			let n = y(t);
+			let n = b(t, e);
 			n !== void 0 && h({
 				fieldKey: e.key,
 				value: n
 			});
 		}, s = (t) => {
-			let n = y(t);
+			let n = b(t, e);
 			n !== void 0 && _({
 				fieldKey: e.key,
 				value: n
 			});
 		}, c = (t) => {
-			let n = y(t);
-			n !== void 0 && b({
+			let n = b(t, e);
+			n !== void 0 && y({
 				fieldKey: e.key,
 				value: n
 			});
@@ -469,4 +492,4 @@ function b(e, t, r, i) {
 	};
 }
 //#endregion
-export { l as buildResponsesFromFormData, m as createFieldEvaluator, g as createFieldValidation, b as createForm, v as createSubmitPipeline, y as getEventValue, p as getStepFields };
+export { l as buildResponsesFromFormData, m as createFieldEvaluator, g as createFieldValidation, x as createForm, v as createSubmitPipeline, y as getEventValue, p as getStepFields };